Metadata-Version: 2.4
Name: specforged
Version: 0.7.0
Summary: SpecForged - spec-driven development workflow with an installable, upgradable core (specforged init / upgrade / doctor).
Author: Pawel Szulc
License: Apache-2.0
Keywords: spec-driven-development,workflow,ai-guardrails,scaffolding
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Dynamic: license-file

# 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](https://github.com/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](https://github.com/Pandaeb/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

```bash
pip install specforged
```

## Quick start

```bash
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](LICENSE) and [NOTICE](NOTICE).
