AGENT SKILL

to-spec

Synthesize a specification from the completed wayfinder map. Never runs its own interview — it only writes down what wayfinder's grilling tickets already established, at a depth proportional to the project's documentation tier.

License 许可
MIT
最近更新
2026-08-05
Stars
★ 0
Forks
0

01 前言 Front Matter

name
to-spec
description
Synthesize a specification from the completed wayfinder map. Never runs its own interview — it only writes down what wayfinder's grilling tickets already established, at a depth proportional to the project's documentation tier.

03 SKILL.md 正文

To-spec

Synthesis only. Takes the accumulated decisions from a completed wayfinder map and writes them into a formal spec. If the map hasn't actually answered something this needs, that's a sign the map wasn't complete — go back to wayfinder and add a ticket rather than inventing an answer.

Process

  1. Read .agent/state.json to get the doc_tier and confirm status is "mapping" with all map tickets resolved. Read the wayfinder map at map_ref.

  2. Explore the repository to understand the current codebase state. Use domain vocabulary from CONTEXT.md and respect existing ADRs.

  3. Identify testing seams — prefer existing public boundaries. If new seams are needed, propose them at the highest architectural level. Use /codebase-design seam discipline: place seams at volatile boundaries, not at every boundary. One adapter = hypothetical seam; two adapters = real seam.

  4. Write the spec at a depth matching the tier (reference/doc-tiers.md):

    • Script tier: no separate spec file. The CONTEXT.md summary from wayfinder grilling is enough; skip straight to skills/to-tickets/SKILL.md.
    • Tool tier: a short spec (~half page) covering problem statement, solution, and 3-6 acceptance criteria.
    • App / system tier: full spec using the template below.

    Spec template (app/system tier)

    • Problem statement — what the user is experiencing.
    • Solution — what the user will experience once done.
    • User stories — numbered, "As a [role], I want [action], so that [outcome]" format.
    • Implementation decisions — modules, interfaces, architectural choices. Use /codebase-design vocabulary (depth, seam, module, adapter, locality) when describing boundaries and interfaces. No file paths (those belong in tickets).
    • Testing decisions — seams, modules needing tests, prior art.
    • Out of scope — explicitly excluded items.
  5. Do not add scope that wasn't discussed. If something seems like an obvious gap, flag it as a question back to the user.

    Evidence gate: every implementation decision in the spec must trace to a resolved decision on the map — quote or reference it. If a decision the spec needs isn't on the map, that's incomplete fog: go back to wayfinder and add a ticket. Do not invent the answer here.

  6. Save to docs/agents/spec.md and update .agent/state.json status to "implementing".

  7. Hand off to skills/to-tickets/SKILL.md directly.

What this skill must never do

  • Never conduct new interview questions — that's wayfinder's job.
  • Never produce a spec for script-tier projects.
  • Never add scope beyond what was discussed on the wayfinder map.

04 同仓库更多 Skills

lynchypin
lynchypin/project-onboard

wayfinder

The orchestration hub for all work. Creates a map of investigation tickets (grilling, research, prototype, task, bug), resolves them one at a time with strict grilling discipline, manages risk posture pauses during implementation, and hands off to to-spec when the map is complete. Use for any work regardless of size — a trivial task has a small map, a large migration has many tickets.

★ 0
lynchypin
lynchypin/project-onboard

to-tickets

Break the spec into small, independently-implementable tracer-bullet vertical slices. No checkpoint gate — hands off directly to wayfinder for implementation orchestration.

★ 0
lynchypin
lynchypin/project-onboard

tdd

Reference material for test-driven development discipline. Red before green, one slice at a time. Use as reference during implementation, not as a step-by-step procedure.

★ 0
lynchypin
lynchypin/project-onboard

start-session

Orient a new session in any project directory. Detects empty directory, existing codebase, or resume state, gathers cheap signals, and routes to wayfinder. The only user-invoked entry point.

★ 0
lynchypin
lynchypin/project-onboard

setup

Configures the issue tracker. Called by start-session during first orient. Model-invoked — runs automatically as part of the flow, not user-triggered.

★ 0
lynchypin
lynchypin/project-onboard

scope-lock

Produces a short context manifest of which files and directories are in-bounds for the current task on a medium or large existing codebase. Keeps subsequent reading inside that boundary unless explicitly widened. Prevents context bloat.

★ 0