spec-forge

---
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. 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.