forge

name

forge

description

Spec-driven autonomous development workflow. When the user wants to plan a non-trivial change, build it autonomously, or run a skeptical review of completed work, use the /forge:* commands. /forge:contract writes a rich spec through code exploration, library research, and gray-area discussion. /forge:auto loops build→evaluate→fix until the contract's success criteria are met. /forge:build implements one chunk against an existing contract. /forge:evaluate spawns a fresh-context sub-agent to verify work skeptically. /forge:parallel decomposes large work into independent streams across git worktrees. /forge:pulse generates a development-health report. /forge:status lists active contracts and their progress. The pattern: scout the code → research the libraries → discuss gray areas → write a contract → build with evidence → evaluate skeptically. Activates when the user mentions building a feature non-trivially, asks for spec-driven dev, or invokes any /forge:* command.

Forge

Spec-driven autonomous development workflow for Claude Code. Forge treats the spec as the highest-leverage artifact: a build with a thorough spec gets the right thing on the first try; a build with a thin checklist passes checkboxes and misses intent.

When this skill activates

• The user wants to build a non-trivial change and would benefit from a spec rather than coding directly
• The user invokes any /forge:* command
• The user says things like "spec this out", "let's plan this properly", "I want autonomous build", "skeptical review", "decompose this into parallel streams"

For trivial changes (typo fixes, single-line config edits, obvious bugs), don't invoke forge — just do the work.

The commands

Command	Use when
/forge:contract <task>	You have a feature/change idea and want a thorough spec before any code. Most-used command.
/forge:auto <task>	You want to define the work and come back to a finished result. Discusses → writes contract → builds → evaluates → fixes, autonomously.
/forge:build <contract>	A contract exists; implement against it with gates after each chunk.
/forge:evaluate <contract>	Completed work needs a skeptical fresh-context review against its contract.
/forge:parallel <feature>	Work is too big for one context; decompose into independent streams across git worktrees.
/forge:pulse	Snapshot of repo health — velocity, branches, contracts, recent evaluations.
/forge:status	Quick list of active contracts and their progress.

The pattern

            ┌─────────────────────────────────────┐
            │  /forge:contract                    │
            │  scout code → research libraries    │
            │  → discuss gray areas → spec        │
            └─────────────────────────────────────┘
                          │
                          ▼
            ┌─────────────────────────────────────┐
            │  /forge:build  (or /forge:auto)     │
            │  implement chunk → run gates →      │
            │  evidence → checkbox → commit       │
            └─────────────────────────────────────┘
                          │
                          ▼
            ┌─────────────────────────────────────┐
            │  /forge:evaluate                    │
            │  fresh-context sub-agent verifies   │
            │  ACCEPT / NEEDS WORK                │
            └─────────────────────────────────────┘

Project setup

Forge stores its artifacts in .forge/ at the project root:

.forge/
├── contracts/         ← active and completed specs
│   ├── data-browser-filters.md
│   └── agent-tool-retry.md
├── evaluations/       ← skeptical reviews of completed contracts
│   └── data-browser-filters.md
└── config.{yaml,json} ← optional; per-project gate commands

Add .forge/ to your project once. Subsequent /forge:* invocations populate it.

Gate commands

Forge runs the project's own quality gates — typecheck, test, lint — after each meaningful chunk. The contract specifies which commands to run for which kind of work.

When writing a contract, the spec author identifies the relevant commands from the project. Common patterns:

• Node/TypeScript: npm run typecheck, npm test, bun test
• Python: uv run pytest, ruff check, mypy
• Rust: cargo check, cargo test, cargo clippy
• Go: go vet ./..., go test ./...
• Project-specific runners: make check, ./dev check, just test

If the project has a single "run all checks" command (a Makefile target, a package script, a dev script), prefer that as the headline gate. Add scoped gates for backend-only / frontend-only changes.

If no gate commands exist yet, the contract author can flag this and either propose adding them or run gates manually.

Core principles

• The spec is the artifact. The build is downstream of spec quality. Invest in the spec.
• Scout before asking. Read the code first, then ask grounded questions. Don't ask abstract design questions.
• Research before building. DeepWiki / WebSearch the libraries you'll touch. Training data goes stale fast.
• Evidence before checkbox. Mark a criterion done only with command output, file:line reference, or observed behavior.
• Skeptical evaluation is a sub-agent. Self-evaluation is unreliable; fresh-context evaluation catches what the builder missed.
• Atomic commits, not one giant blob. Commit after each meaningful chunk for rollback points and progress visibility.
• Default to LLMs over heuristics for ambiguous extraction/classification — unless latency-critical or strictly formatted input.
• Discussion is the only interactive part. Once the spec is written, autonomy follows. Don't skip the discussion to "save time" — that's where quality comes from.

Quality bar

A good forge run produces:

• A spec that reads like a thoughtful internal design doc, not a checklist
• Commits that tell a coherent story (one logical chunk per commit)
• Checkboxes backed by specific evidence
• An evaluation that either says "passes" with proof or "fails on criterion N" with specifics

A poor forge run produces:

• A spec that's a wishlist with no investigation
• "Done" claims without evidence
• One giant commit at the end
• An evaluation that rubber-stamps without verifying