spec-forge · diff
v1 to v1
22 added, 1 removed. Audit A to A.
---
name: spec-forge
description: >
Professional specification system for Codex. Use when the user asks to create,
improve, review, audit, analyze, or propagate product/software documentation,
including ideas, PRDs, SRS documents, technical designs, architecture/RFC docs,
feature specs, test cases, documentation audits, document landscape analysis,
and full idea-to-spec chains. Supports complex multi-skill orchestration:
idea -> decompose -> tech-design + feature specs -> review, with optional PRD,
SRS, test-cases, audit, analyze, and propagate workflows.
version: 1.0
subcommands:
- idea
- decompose
- tech-design
- prd
- srs
- test-cases
- review
- audit
- analyze
- propagate
---
# Spec-Forge Orchestrator
Spec-forge is a documentation and specification workflow suite. This root skill is
the Codex-facing orchestrator: decide which child skill to load, keep the document
chain coherent, and avoid loading large generation references until they are needed.
## Trigger Patterns
Use this skill when the user asks for any of the following:
- Start or refine an idea before specs: use `skills/idea/SKILL.md`
- Split a large project into sub-features: use `skills/decompose/SKILL.md`
- Write a PRD or product requirements document: use `skills/prd-generation/SKILL.md`
- Write an SRS, requirements spec, or functional/non-functional requirements: use `skills/srs-generation/SKILL.md`
- Write a technical design, architecture doc, design doc, or RFC: use `skills/tech-design-generation/SKILL.md`
- Generate test cases, QA coverage, or a test case matrix: use `skills/test-cases-generation/SKILL.md`
- Review spec-forge documents for quality and consistency: use `skills/review/SKILL.md`
- Audit project docs against code: use `skills/audit/SKILL.md`
- Analyze a document ecosystem for themes, conflicts, gaps, redundancy, or staleness: use `skills/analyze/SKILL.md`
- Propagate an upstream doc change downstream: use `skills/propagate/SKILL.md`
- Run the full chain for a feature: orchestrate `idea -> decompose -> tech-design -> review`
Also treat slash-like requests as aliases:
| User request | Route |
|---|---|
| `/spec-forge <name>` | Full chain |
| `/spec-forge:idea <name>` or `/idea <name>` | Idea |
| `/spec-forge:decompose <name>` or `/decompose <name>` | Decompose |
| `/spec-forge:tech-design <name>` or `/tech-design <name>` | Tech Design |
| `/spec-forge:prd <name>` or `/prd <name>` | PRD |
| `/spec-forge:srs <name>` or `/srs <name>` | SRS |
| `/spec-forge:test-cases <target>` or `/test-cases <target>` | Test Cases |
| `/spec-forge:review <name>` or `/review <name>` | Review |
| `/spec-forge:audit [path]` or `/audit [path]` | Audit |
| `/spec-forge:analyze [path]` or `/analyze [path]` | Analyze |
| `/spec-forge:propagate ...` or `/propagate ...` | Propagate |
The `commands/*.md` files are compatibility command definitions from the original
Claude-oriented implementation. In Codex, prefer reading the child `skills/*/SKILL.md`
files directly. Use `commands/spec-forge.md` only as an additional orchestration
reference if you need more detail about the full chain.
## Progressive Loading
Keep context small.
1. Read this root file first.
2. Read only the child `SKILL.md` matching the user's request.
3. When a child skill references `skills/shared/project-context.md`, read it if the workflow needs code/project awareness.
4. When a child skill references `skills/shared/doc-first.md`, apply it before generating or editing docs.
- 5. Read generation references, templates, or checklists only when that child skill explicitly needs them.
+ 5. When a child skill invokes the script layer, read `skills/shared/scripts.md` once to resolve `<sf_scripts>`; do not read the scripts' source unless you need to debug them.
+ 6. Read generation references, templates, or checklists only when that child skill explicitly needs them.
Do not bulk-load every child skill. Do not read every reference folder just because
the suite is complex.
## Global Rules
- Preserve the user's requested language. If the user writes in Chinese, respond and write user-facing explanations in Chinese unless the target document convention requires English.
- Treat docs as current truth, not history. Before generating a new spec, scan for existing related docs and decide whether to reuse, edit, or create.
- Do not create parallel versions such as `prd-v2.md`, `new-tech-design.md`, or addendum files. Edit the canonical file in place unless no canonical document exists.
- Keep traceability stable: preserve existing requirement IDs, feature names, component names, and section titles unless the user explicitly asks to rename them.
- When changing upstream docs, identify downstream impact. Either update affected downstream docs or recommend/run the propagate workflow.
- Every finding in review, audit, analyze, or propagate output must cite concrete files/sections. Do not invent issues.
- Prefer project-local conventions and existing docs over generic templates.
- Ask only necessary questions. If existing docs or code provide the answer, use them and state the assumption.
## Shared Project Context
For generation workflows that need grounding in the actual codebase, use:
`skills/shared/project-context.md`
Apply it before PRD, SRS, tech-design, decompose, and test-cases work when the
project exists. It produces a concise summary of:
- Project profile
- Language, framework, database, auth, testing, and CI signals
- Existing documents and upstream specs
- Architecture and module boundaries
- Existing test infrastructure when relevant
For the full chain, scan project context once and reuse the summary across stages
instead of repeatedly rescanning the same repository.
+
+ ## Script Layer
+
+ spec-forge ships a small layer of deterministic Python 3 (standard-library-only)
+ helpers under `skills/shared/scripts/` that absorb the mechanical, token-heavy
+ bookkeeping the skills used to do by hand — project + document scanning
+ (`sf-scan.py`), configuration/directory resolution (`sf-config.py`), document
+ structure/ID validation (`sf-verify-doc.py`), and traceability/coverage math
+ (`sf-trace.py`). The division of labour: **the scripts keep the record-keeping;
+ the model keeps the reasoning** (requirement quality, architecture trade-offs,
+ conflict judgement). Every skill that calls a script keeps a silent manual
+ fallback for when `python3` is unavailable.
+
+ How to locate and invoke the scripts, and which one does what:
+
+ `skills/shared/scripts.md`
+
+ Prefer the fast path (run the script, use its JSON) over re-deriving the same
+ facts by hand. Never restate a script's algorithm in prose — the script is the
+ single source of truth so the two cannot drift.
## Document Discipline
For any document creation or edit, apply:
`skills/shared/doc-first.md`
Minimum pre-write checklist:
1. List relevant existing docs under `docs/`, `specs/`, `design/`, `architecture/`, `ideas/`, and the project root.
2. Grep for the feature name, domain terms, requirement IDs, component names, and aliases.
3. Decide for each topic: reuse existing content, extend existing content, or create new content.
4. Preserve stable IDs and terminology.
5. Note downstream docs that will need updates.
## Full Chain
When the user asks for `/spec-forge <name>` or "run the full spec-forge chain",
execute this sequence:
1. **Idea**: Use `skills/idea/SKILL.md`.
- Goal: validate demand and produce `ideas/{name}/draft.md`.
- If a ready or graduated idea already exists, reuse it.
- If the idea is still exploring/refining, warn the user before continuing.
2. **Decompose**: Use `skills/decompose/SKILL.md`.
- Goal: decide single feature vs multi-split project.
- Multi-split output: `docs/project-{name}.md` with a first-line `FEATURE_MANIFEST` block.
3. **Tech Design + Feature Specs**: Use `skills/tech-design-generation/SKILL.md`.
- Single feature output: `docs/{name}/tech-design.md`.
- Multi-split output: one tech design per sub-feature.
- The tech-design workflow also generates implementation-facing feature specs under `docs/features/`.
- If `ideas/{name}/draft.md` exists, use it for user scenarios, acceptance criteria, success metrics, scope, and goals.
4. **Review**: Use `skills/review/SKILL.md`.
- Review generated tech designs and `docs/features/*.md`.
- Auto-fix only where the review skill permits it.
- Leave review comments where domain knowledge is missing.
PRD, SRS, and test cases are optional on-demand outputs, not required stages in
the default full chain.
## Single-Skill Routes
### Idea
Read `skills/idea/SKILL.md`.
Use for early exploration, demand validation, competitive research, and
anti-pseudo-requirement checks. Output lives in top-level `ideas/{idea-name}/`,
not under `docs/`.
### Decompose
Read `skills/decompose/SKILL.md`.
Use for deciding whether a project is one feature or several independently
specifiable sub-features. If multi-split, generate `docs/project-{name}.md`.
### PRD
Read `skills/prd-generation/SKILL.md`.
Use for product requirements, stakeholder alignment, product strategy, market
context, personas, user stories, priorities, success metrics, and timelines.
### SRS
Read `skills/srs-generation/SKILL.md`.
Use for formal functional/non-functional requirements, requirement IDs,
interfaces, data requirements, acceptance criteria, and traceability matrices.
### Tech Design
Read `skills/tech-design-generation/SKILL.md`.
Use for architecture/design docs, RFCs, API design, data model design,
deployment, observability, security, performance, alternatives, and generated
feature specs.
### Test Cases
Read `skills/test-cases-generation/SKILL.md`.
Use for test case generation, coverage matrices, test strategy, testable unit
extraction, and code/spec-driven QA planning. Honor `--formal` when requested.
### Review
Read `skills/review/SKILL.md`.
Use after spec generation to check completeness, specificity, internal
consistency, traceability, and actionability. Findings first; fixes only where
allowed.
### Audit
Read `skills/audit/SKILL.md`.
Use when auditing one project that has docs and code. It checks documentation
quality, completeness, consistency, staleness, and alignment with the codebase.
### Analyze
Read `skills/analyze/SKILL.md`.
Use for docs-only or cross-repo document landscapes. It maps themes, conflicts,
gaps, redundancies, and stale areas without assuming a single codebase.
### Propagate
Read `skills/propagate/SKILL.md`.
Use after upstream document changes. It finds downstream docs affected by changed
concepts and updates them surgically or reports unresolved stale references.
## Output Locations
Default locations:
- Ideas: `ideas/{name}/`
- PRD: `docs/{name}/prd.md`
- SRS: `docs/{name}/srs.md`
- Tech design: `docs/{name}/tech-design.md`
- Feature specs: `docs/features/*.md`
- Test cases: `docs/{name}/test-cases.md` or the path specified by the child skill
- Project manifest: `docs/project-{name}.md`
- Audit report: `{target-docs-path}/audit-report.md`
- Analysis report: `{target-root}/analysis-report.md`
If existing project conventions differ, follow the existing convention and state
the location you used.
## Completion Criteria
Before finishing a spec-forge task:
- Confirm the requested document or report exists, or explain why it could not be written.
- Mention the exact files changed or generated.
- For generation tasks, note whether project context and existing docs were scanned.
- For review/audit/analyze tasks, summarize findings by severity and cite the report path.
- For chain tasks, summarize which stages completed and which optional stages remain.