specforged

Spec-driven development for AI-assisted teams — with the safety net built in. Interviews turn your intent into binding project docs, every feature goes requirements → architecture → tasks → small verified commits, and deterministic CI guards catch what AI-written code gets wrong (or sneaks in) before a human ever hits merge.

Not related to sgl-project/SpecForge (speculative-decoding training for SGLang).

Why

AI writes code fast; the failure mode is everything around the code: scope creep, quietly weakened tests, invented dependencies, giant unreviewable diffs, "fixes" that rewrite the rules that judge them. specforged pairs a document protocol (so the AI always knows the project's binding answers) with ai-code-guardrails (so every PR is checked deterministically, and only a human can waive a check — via a PR label).

What you get

• specforged CLI — init (scaffold a project), upgrade (update the core without touching your content), doctor (diagnose the setup). Python 3.9+, zero runtime dependencies.
• A document core — WORKFLOW.md (the canonical process), AI-GUARDRAILS.md (universal rules for AI-written code), 17 templates with built-in interviews, steering files that bind every AI session.
• A Claude plugin — /specforged:* slash commands (the build half) and specforged-* skills (the plan/design half). One install, no file copying.
• CI guards on every PR — diff budget, scope discipline, test integrity, dependency policy, secrets scan, self-modification protection. Waivers are human-only PR labels.

Install

pip install specforged

Quick start

mkdir my-app && cd my-app
git init
specforged init . --stack python   # python | node | dotnet | flutter | none

Then, in Claude Code:

/plugin marketplace add <this-repo>/integrations/claude
/plugin install specforged@specforged
/specforged:foundation     # interviews fill the 11 steering files
/specforged:roadmap        # milestones + build order

Per feature:

/specforged:feature-requirements login
/specforged:feature-architecture login
/specforged:feature-tasks login
/specforged:feature-implement login
/specforged:feature-review login    # in a fresh session

Push to GitHub, create the waiver labels, make the guard checks required — specforged doctor tells you exactly what is missing.

The upgrade contract

Your project content is untouchable. .specforged/core-manifest.json lists every core file with its factory hash:

• a path not in the manifest (steering, specs, reviews, roadmap, your config) is never touched by specforged upgrade;
• an unmodified core file is updated in place;
• a core file you changed becomes a reported conflict — the new version lands next to it as *.new (or --theirs takes the new file and keeps yours as *.bak).

The contract is machine-enforced: CI regenerates the manifest and fails if it is not exactly the generator's output, and the tests/test_upgrade_fixture.py suite proves an old-layout project upgrades with zero content loss.

Requirements

• Python 3.9+, no runtime dependencies.
• Works with Claude Code / Cowork via the bundled plugin; the document core is agent-agnostic (any tool that reads repo markdown can follow AGENTS.md → .specforged/WORKFLOW.md).

Versioning

The package version, the plugin version and the core manifest version move together; specforged upgrade carries projects forward across releases.

License

Apache-2.0 — see LICENSE and NOTICE.