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, business case, or product definition — "is this worth building": use skills/prd-generation/SKILL.md
• Write the requirements a team will be held to — a requirements spec, an SRS, functional/non-functional requirements, a requirements document to hand to an implementation team or vendor: 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] -> [prd] -> srs -> tech-design -> review -> handoff to code-forge

Routing the ambiguous "write me a requirements document". When the user says "需求文档", "requirements doc", or "spec" without qualifying it, the deciding question is whether the decision to build has already been made. If it has — the user knows what they want and needs it specified precisely enough to implement against — route to SRS. If it has not — the user is making a case, seeking approval, or sizing an opportunity — route to PRD. When genuinely unclear, ask that one question rather than guessing; producing the wrong document wastes the entire generation.

Also treat slash-like requests as aliases:

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 SRS, PRD, 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

The chain has one mandatory spine — a delivery-grade requirements specification, then a technical design — with everything else conditional on what the project actually needs. When the user asks for /spec-forge <name> or "run the full spec-forge chain", execute this sequence:

1. Idea (conditional): Use skills/idea/SKILL.md.
   • Run when the demand itself is unvalidated: the user is exploring, the problem is fuzzy, or there is no evidence anyone needs this.
   • Skip when the user already knows what they want built.
   • 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 (conditional): Use skills/decompose/SKILL.md.
   • Run when the scope plausibly covers several independently specifiable sub-features.
   • Skip for a single coherent feature.
   • Multi-split output: docs/project-{name}.md with a first-line FEATURE_MANIFEST block.
3. PRD (conditional): Use skills/prd-generation/SKILL.md.
   • Run for a new product, a new product line, or anything needing a go/no-go decision, budget approval, or stakeholder alignment before commitment.
   • Skip when the decision to build is already made and the work is a well-understood feature — go straight to the SRS. A PRD written after the decision is ceremony.
   • Output: docs/{name}/prd.md — business case and product definition.
4. SRS (mandatory): Use skills/srs-generation/SKILL.md.
   • This is the spine of the chain. It is the delivery contract: the document an implementation team — an external vendor, another team, or code-forge — is held to.
   • Output: docs/{name}/srs.md with FR-*/NFR-* requirements, input field rules, state machines, permission matrix, error catalogue, acceptance criteria, and change control.
   • If docs/{name}/prd.md exists, trace every capability into requirements. If only ideas/{name}/draft.md exists, derive scope and requirements from it. If neither exists, work from the user's request and state the assumptions explicitly.
   • Never skip this stage to reach the tech design faster. A design built on unstated requirements produces code whose correctness nobody can settle.
5. Tech Design (mandatory): Use skills/tech-design-generation/SKILL.md.
   • Single feature output: docs/{name}/tech-design.md.
   • Multi-split output: one tech design per sub-feature.
   • Also generates one implementation-facing feature spec under docs/features/ per component in §8.1, plus docs/features/overview.md with the dependency graph and execution order.
   • Every component must trace to the FR-*/NFR-* requirements it satisfies, and every requirement must be satisfied by at least one component.
6. Review (mandatory): Use skills/review/SKILL.md.
   • Review the SRS, the tech design, and any docs/features/*.md.
   • Auto-fix only where the review skill permits it. Leave review comments where domain knowledge is missing.
7. Handoff: Report the handoff command rather than running it.
   • /code-forge:plan @docs/features/ when feature specs were generated.
   • /code-forge:plan @docs/{name}/tech-design.md for a single-component design.
   • Implementation and test generation belong to code-forge. spec-forge owns requirements and design; code-forge owns implementation and verification. Tests are derived from the SRS acceptance criteria by code-forge:tdd — spec-forge does not produce a separate test document in the chain.

Test cases, audit, analyze, and propagate are on-demand outputs, not stages in the default 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 — the business case

Read skills/prd-generation/SKILL.md.

Answers "is this worth building, for whom, and at what priority". Market context, competitive landscape, demand validation, feasibility go/no-go, personas, user stories, capability scope, success metrics, milestones, risks. Read by stakeholders before commitment and largely frozen once the decision is made. Optional: skip it when the decision to build is already settled.

Deliberately not in the PRD: field-level rules, state machines, error codes, Given/When/Then acceptance criteria, solution architecture. Those are the SRS's and tech design's job. A PRD row that needs more than two sentences is a system behavior in the wrong document.

SRS — the delivery contract

Read skills/srs-generation/SKILL.md.

Answers "exactly what must be built, and how do we settle whether it was". This is the document an implementation team — an external vendor, another team, or code-forge — is held to, and the mandatory spine of the chain. Formal FR-*/NFR-* requirements with main/alternative flows, input field rules, state machines including illegal-transition handling, permission matrix, error catalogue with degradation behavior, machine-verifiable acceptance criteria, interface and data requirements, traceability, and acceptance and change control.

Unlike the PRD, it keeps evolving through delivery — which is exactly why the two are separate files. A requirement change must not require touching market sizing, and internal go/no-go reasoning must not ship to an implementation vendor.

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 (business case, optional): docs/{name}/prd.md
• SRS (delivery contract, mandatory): 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, which conditional stages were skipped and why, and state the /code-forge:plan handoff command.
• For a full chain, confirm the SRS exists and passed its structural gate. The SRS is the chain's spine; a chain that reached a tech design without one is incomplete, not merely abbreviated.