Getting started

Requires Bun 1.3 or newer and one supported ACP provider already usable on the machine.

Install and run

npmbunpnpmyarn

npm install --global spec-finder

bun add --global spec-finder

pnpm add --global spec-finder

yarn global add spec-finder

cd /path/to/project
spec-finder setup
spec-finder run my-feature

Once the package is current, spec-finder refresh recopies managed skills into this workspace's saved destination and scope without changing provider, model, or scope.

What setup creates

.spec-finder/
├── .gitignore
├── config.json
├── specs/
└── tasks/

.spec-finder/.gitignore ignores tasks/,tasks_done/, and specs/ when those entries are missing. Packet and spec files stay out of git. The workspace root.gitignore is left alone. .spec-finder/config.jsonremains eligible to commit.

Setup options

In an interactive terminal, setup resolves exactly one provider and asks for its installation scope, model, and speed. Supplying a flag skips only that choice's picker. --copy remains accepted for compatibility and is the only installation mode.

spec-finder setup [--agent claude|codex|cursor|grok|pi] [--model auto|CURATED] \
  [--speed auto|normal|fast] [--local|--global] [--copy]

Fresh setup defaults to Codex, gpt-5.6-luna,normal speed, local scope, and every managed skill includingsf-review. A configured refresh preserves an explicit saved skill subset rather than adding new skills silently.

Skill destinations

Scaffolding always stays in the current project. Skill destinations are derived from the selected provider and scope:

Provider	Local skills	Global skills
Claude	`.claude/skills`	`~/.claude/skills`
Codex	`.agents/skills`	`~/.agents/skills`
Cursor	`.agents/skills`	`~/.agents/skills`
Grok Build	`.agents/skills`	`~/.agents/skills`
Pi	`.agents/skills`	`~/.agents/skills`

Cursor's existing .cursor/skills and leftover.pi/skills content are preserved untouched. Setup copies managed skills only to the provider destination above.

Using skills after setup

Thin task, then spec

Ask for sf-create-prd when the task is thin. After the approved PRD, ask for sf-write-spec orsf-tdd-write-spec. Those skills write a separate task_spec.md, reference the approved _prd.md, and print both paths.

Ticket refinement

Ask the agent for sf-refinement with a prompt or a Jira, Linear, GitHub, or similar ticket. That skill writes only.spec-finder/refinements/<task_slug>.md.

Full pipeline

sf-idea-factory → sf-create-prd →sf-create-techspec → sf-create-tasks, thenspec-finder run my-feature.

Review before local ship

Once a packet has completed implementation and reporting, install and usesf-review as the final read-only evidence gate:

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

Review checks the whole active packet. Only the explicit shipsuffix reruns review and invokes target-onlysf-archive-tasks --slug my-feature. It does not write task status or reports, move unrelated packets, push, open or merge a PR, release, or request remote acceptance. Refresh preserves an existing explicit skill subset and does not silently add sf-review.

spec-finder run my-feature --no-ui
spec-finder run my-feature --provider pi --model auto --reasoning auto
spec-finder loop my-feature --dry-run
spec-finder loop my-feature

Grok Build and Pi are packet-only. Authenticate those providers outside Spec Finder. Full operator notes stay in therepository README. Back to home.