A schema-first, AI-assisted workflow that turns spec → implementation into a deterministic pipeline backed by machine-checkable artifacts.
- Clarity for humans, structure for AIs.
- Falsifiability: every statement is testable.
- Traceability: FRs ↔ APIs ↔ Fixtures ↔ NFRs remain linked end to end.
- Early delivery: CI enforces quality from Step 0.
- Start a new project using the init utility:
python devspec_toolkit/scripts/init_project.py --target <path> --strict. - Onboard as a developer with docs/developers/getting_started.md.
- Keep docs/developers/reference.md#core-validation-commands handy for the canonical command list, troubleshooting flow, and naming conventions.
- Use the workflow overviews in docs/developers/workflows/ as you progress through Steps 00–16c.
- Automation agents begin at docs/agents/agents.md.
- Maintain
spec/common/seed_manifest.jsonto define mandatory seed order and docs policy.
<toolkit-root>/
├─ README.md # this file (high-level orientation)
├─ docs/ # audience-specific guidance
├─ prompts/ # deterministic prompt contracts
├─ schema/ # JSON Schemas per step + shared atoms/collections/errors
├─ spec/common/ # shared seed manifest (toolkit baseline)
└─ tools/ # CLI package + schema registry
└─ specdev_tools/ # Python CLI package
├─ cli.py # entry point
├─ core/ # errors, registry, trace_types, changelog_parser
├─ validation/ # validate, validators/, linters (fixtures, seed, docs,
│ # quality, hallucination, dependency, forward-replay,
│ # traceability, invariants, governance, matrix)
├─ generation/ # prompt_generator, prompt_schema_sync, schema_differ
├─ canonical/ # autofix, integrity, lint, registry
└─ migration/ # planner, runner
Most teams vendor the toolkit as a git submodule at <product-repo>/devspec_toolkit/ beside their live spec/ directory.
This toolkit uses Semantic Versioning:
- MAJOR: Breaking changes that require spec migration
- MINOR: New features, backward compatible
- PATCH: Bug fixes and documentation
Current version is defined in tools/pyproject.toml. See CHANGELOG.md for release history and changelog/ for machine-readable version details.
Projects track their toolkit version in spec/specdev_version to enable migration tooling. When versions mismatch, use the specdev align CLI to upgrade.
-
Follow the environment setup in docs/developers/getting_started.md#1-set-up-your-environment (virtualenv + wrapper).
-
Run validations with
./tools/run_specdev.sh … --repo-root <toolkit-root>(wrapper created by init). -
AI runners follow a two-phase flow (Clarify → Emit). See docs/agents/manifest.json and docs/agents/agents.md for the operating protocol. Clarify responses are short, bulleted questions grouped by topic (no JSON, no code fences), prioritizing gating items.
All authoritative CLI examples, guardrails, and troubleshooting checklists live in docs/developers/reference.md.
-
docs/README.md — documentation map.
-
tools/README.md — CLI packaging details.
-
.github/workflows/ci.yml — the toolkit's own CI pipeline.
macOS and Linux are fully supported. Windows users should run the toolkit under WSL2.
This toolkit is released under the MIT License.