A spec-driven methodology for AI-assisted development, packaged as an agent skillset. SpecForge separates reasoning from implementation across three stages:

1. Explore — solution-space exploration with a high-reasoning model.
2. Spec — generate an unambiguous Execution-Spec.
3. Execute — implement strictly from the spec with a coding model.

The methodology is authored once and runs in any SKILL.md-compatible coding agent.

SpecForge installs with one command via the cross-agent skills CLI — no clone, no config. It auto-discovers the skills/ directory in this repo, so there is nothing to set up on our side.

opencode (v1):

npx skills add cadic/specforge -a opencode -g --skill '*'

-a opencode targets opencode, -g installs globally (into ~/.config/opencode/skills/), and --skill '*' installs all four SpecForge skills.

The same command works for any of the 70+ agents the CLI supports — swap the agent name:

npx skills add cadic/specforge -a claude-code -g --skill '*'
npx skills add cadic/specforge -a codex -g --skill '*'

For Cursor (no global skills dir), install into the project instead (drop -g):

npx skills add cadic/specforge -a cursor --skill '*'

Manual fallback (zero dependencies): copy the four skills/specforge* directories into your agent's global skills directory by hand, e.g. cp -r skills/specforge* ~/.config/opencode/skills/.

1. In your agent, invoke the specforge skill and give it a task slug.
2. It scaffolds docs/specforge/<slug>/01-problem-statement.md — fill it in.
3. It detects the phase and routes you through Explore → Spec → Execute, stopping at checkpoints for your input.

SpecForge needs no configuration to run. By default, task artifacts live in docs/specforge/<task-slug>/.

To put them elsewhere, add a .specforge.json at your repo root with a task_root key:

{ "task_root": "coding-assistant/tasks" }

task_root is the only recognized key (v1); it defaults to docs/specforge.

skills/
  specforge/          # orchestrator: scaffolding, phase detection, routing (bash)
  specforge-explore/  # Stage 1 (prose, high-reasoning)
  specforge-spec/     # Stage 2 (prose, high-reasoning) + 04 template
  specforge-execute/  # Stage 3 (prose, coding model)

• Skills live in the agent (its global skills directory).
• Artifacts live in your project under the configured task root (see Configuration).

State lives in the filesystem. skills/specforge/scripts/sf-status.sh derives the current phase from which 0X-*.md files exist, so you can stop after any stage and resume later — even in a different agent.

SpecForge does not ship an AGENTS.md. Stage 3 follows your project's own AGENTS.md/CLAUDE.md. See docs/writing-agents-md-for-specforge.md.

Bash helpers are tested with bats-core:

brew install bats-core
bats tests/

MIT