Spec Finder

A skill-driven specification framework with a local ACP cockpit.

Idea → PRD → TechSpec → executable tasks, without a daemon or a second source of truth. Skills are portable Agent Skills. Claude, Codex, Cursor, Grok Build, and Pi run through their ACP harnesses while Spec Finder owns ordering, lifecycle, permissions, and evidence reports.

npmbunpnpmyarn

npm install --global spec-finder

bun add --global spec-finder

pnpm add --global spec-finder

yarn global add spec-finder

What it does

Closed specification pipeline

Idea, PRD, TechSpec, and numbered tasks live in.spec-finder/tasks/<slug>/.

Simplified spec path

sf-write-spec and sf-tdd-write-spec write## Implementation Spec inside the task_prd.md, then print that path. A thin task goes through sf-create-prd first.

Refinement path

sf-refinement turns a prompt or tracker ticket into.spec-finder/refinements/<task_slug>.md without writing a runner packet or a one-shot spec.

Five ACP providers

Claude, Codex, Cursor, plus packet-only Grok Build and Pi. Spec Finder does not install or authenticate providers.

Read-only cockpit

Watch provider, task graph, ACP activity, and tool calls. One ACP session per task covers implementation and the final report.

Run, loop, batch

spec-finder run is one pass.spec-finder loop keeps recovering one packet.spec-finder run --multiple is serial and fail-fast.

Local packets

Task packets stay in .spec-finder/tasks/. Setup writes.spec-finder/.gitignore so committed specs cannot poison later agent context.

How to use the skills

Every stage keeps approval gates. Research and interactive decisions happen before artifacts are saved. Tasks form an acyclic dependency graph and carry their own tests.

01Idea
sf-idea-factory → _idea.md
02PRD
sf-create-prd → _prd.md
03TechSpec
sf-create-techspec → _techspec.md
04Tasks
sf-create-tasks → task_NN.md

Thin task, then spec

Use sf-create-prd when the task lacks product context. After the approved PRD, choose sf-write-spec orsf-tdd-write-spec. They write the spec into that same _prd.md and print the path.

Prompt or ticket: refinement

Use sf-refinement to turn a prompt or tracker ticket into stories and technical specs at.spec-finder/refinements/<task_slug>.md. It does not write a runner packet or a one-shot spec.

Discovery or regeneration

Keep using idea, PRD, TechSpec, and tasks when you need discovery, a product-only PRD, a design-only TechSpec, or task regeneration.

Skill	Artifact
`sf-write-spec`	`.spec-finder/tasks/<slug>/_spec.md`. References an approved `_prd.md`, leaves it unchanged, and prints both paths.
`sf-tdd-write-spec`	The same separate `_spec.md`, with confirmed public-seam red-green slices. References an approved PRD and prints both paths.
`sf-refinement`	`.spec-finder/refinements/<task_slug>.md` from a prompt or issue ticket. Does not write`.spec-finder/tasks/` or`.spec-finder/specs/`
`sf-idea-factory`	`.spec-finder/tasks/<slug>/_idea.md`
`sf-create-prd`	`_prd.md`
`humanizer`	Plain human-readable prose. `sf-create-prd` runs it on the saved PRD.
`sf-create-techspec`	`_techspec.md`
`sf-create-tasks`	`_tasks.md` and `task_NN.md`
`sf-memory`	`memory/MEMORY.md` and `memory/task_NN.md`
`sf-execute-task`	bounded implementation and verification
`sf-task-report`	`reports/task_NN.md`
`sf-batch-tasks`	dependency-safe manual range execution
`sf-tdd-plan`	additive `## TDD Plan` on an existing task
`sf-tdd-execute`	red → green vertical slices for opted-in behavioral work
`sf-tdd-report`	red+green evidence report, or a one-line not-applicable reason
`sf-tdd-batch`	TDD-only range runner; stop on failure
`sf-archive-tasks`	completed-packet archival and reports
`sf-review`	packet-wide evidence review and explicit target-only local ship

The four sf-tdd-* skills are optional. Use them when a task changes product behavior and you need a failing public-seam test first.spec-finder run stays on core skills until a separate opt-in design; invoking TDD skills is a manual choice.

Review and ship locally

After implementation and reporting, use sf-review for a packet-wide, read-only reconciliation:

/sf-review my-feature
/sf-review my-feature ship

The explicit ship phase reruns review and archives only the exact reviewed slug through the target-filteredsf-archive-tasks --slug my-feature workflow. It never writes task status or reports, moves an unrelated packet, pushes, opens or merges a PR, releases, or requests remote acceptance.

Providers

Provider	Packet run	One-turn exec	Local skills
Claude	yes	uncertified	`.claude/skills`
Codex	yes	uncertified	`.agents/skills`
Cursor	yes	uncertified	`.agents/skills`
Grok Build	packet-only	uncertified	`.agents/skills`
Pi	packet-only	uncertified	`.agents/skills`

Run a packet

spec-finder run my-feature
spec-finder run my-feature --no-ui
spec-finder loop my-feature

Install, setup, and skill destinations are onGetting started. Full flags and provider notes stay in the repository README.