Skip to content
Skills Library
Management & product · Writing

spec-forge

/spec-forge

Professional specification system for Codex. Use when the user asks to create, improve, review, audit, analyze, or propagate product/software documentation, including requirements documents to hand to an implementation team or vendor, SRS/functional/non-functional requirements, PRDs and business cases, ideas, technical designs, architecture/RFC docs, feature specs, test cases, documentation audits, document landscape analysis, and full idea-to-spec chains. The chain's spine is a delivery-grade requirements spec followed by a technical design, handed off to code-forge for implementation: [idea]

Repository
spec-forge ↗
Licence
MIT
Last repository change
16.09.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
27
Scripts
6
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 16.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 6 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: skills/shared/scripts/sf-config.py, skills/shared/scripts/sf-scan.py, skills/shared/scripts/sf-trace.py, skills/shared/scripts/sf-verify-doc.py, skills/shared/scripts/sf_common.py, skills/shared/scripts/test_scripts.py

What it does and when to use it

Professional specification system for Codex. Use when the user asks to create, improve, review, audit, analyze, or propagate product/software documentation, including requirements documents to hand to an implementation team or vendor, SRS/functional/non-functional requirements, PRDs and business cases, ideas, technical designs, architecture/RFC docs, feature specs, test cases, documentation audits, document landscape analysis, and full idea-to-spec chains. The chain's spine is a delivery-grade requirements spec followed by a technical design, handed off to code-forge for implementation: [idea]

Original author description

Professional specification system for Codex. Use when the user asks to create, improve, review, audit, analyze, or propagate product/software documentation, including requirements documents to hand to an implementation team or vendor, SRS/functional/non-functional requirements, PRDs and business cases, ideas, technical designs, architecture/RFC docs, feature specs, test cases, documentation audits, document landscape analysis, and full idea-to-spec chains. The chain's spine is a delivery-grade requirements spec followed by a technical design, handed off to code-forge for implementation: [idea]

How it works

  1. Trigger Patterns
  2. Progressive Loading
  3. Global Rules
  4. Shared Project Context
  5. Script Layer
  6. Document Discipline
  7. Full Chain
  8. Single-Skill Routes
  9. Output Locations
  10. Completion Criteria
Original SKILL.md headings · 295 lines, 2,123 words
SKILL.md preview
---
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 requirements documents to hand to an implementation team or vendor,
  SRS/functional/non-functional requirements, PRDs and business cases, ideas,
  technical designs, architecture/RFC docs, feature specs, test cases,
  documentation audits, document landscape analysis, and full idea-to-spec
  chains. The chain's spine is a delivery-grade requirements spec followed by a
  technical design, handed off to code-forge for implementation:
  [idea] -> [decompose] -> [prd] -> srs -> tech-design -> review.
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, 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:

| 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 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.
Files in this package (27)
  • .gitignore 1 KB
  • LICENSE 1 KB
  • README.md 15 KB
  • RELEASE-NOTES.md 14 KB
  • SKILL.md 16 KB
  • commands/analyze.md 2 KB
  • commands/audit.md 2 KB
  • commands/decompose.md 1 KB
  • commands/idea.md 1 KB
  • commands/prd.md 6 KB
  • commands/propagate.md 3 KB
  • commands/review.md 2 KB
  • commands/spec-forge.md 26 KB
  • commands/srs.md 10 KB
  • commands/tech-design.md 9 KB
  • commands/test-cases.md 10 KB
  • commands/test-plan.md.deprecated 7 KB
  • skills/shared/doc-first.md 9 KB
  • skills/shared/project-context.md 5 KB
  • skills/shared/scripts.md 3 KB
  • skills/shared/scripts/README.md 5 KB
  • skills/shared/scripts/sf-config.py 2 KB
  • skills/shared/scripts/sf-scan.py 14 KB
  • skills/shared/scripts/sf-trace.py 8 KB
  • skills/shared/scripts/sf-verify-doc.py 8 KB
  • skills/shared/scripts/sf_common.py 13 KB
  • skills/shared/scripts/test_scripts.py 12 KB

Versions

The database has no other skills named spec-forge.

Database snapshot: 13.11.2026 · package version b9c1e453772b (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100srs-generation
    Generates professional Software Requirements Specification (SRS) documents based on IEEE 830, ISO/IEC/IEEE 29148, and Amazon technical specification standards. This skill activates when the user needs a requirements document, requirements specification, SRS, functional…
  • 100write-spec
    This skill should be used when the user asks to 'write a spec', 'create SRS', 'generate spec', 'author spec', 'spec from vision', 'validate spec', 'review spec', 'check SRS', 'validate SRS against context', 'save context', 'add context file', or 'save this as context'. Creates…
  • 100prd-writer
    Expert PRD (Product Requirements Document) writer for the AI era. Use when users want to create PRDs, spec documents, product specifications, feature specs, or technical requirements documents. Also use when users ask to review/improve existing PRDs, want PRD templates, need…
  • 100spec-writer
    An expert-guided skill for creating layered software specification documents for greenfield projects. Produces five document types: Vision, Business Requirements (BRS), Software Requirements (SRS), Architecture & Design, and Behavioral Spec & Test Verification. Use this skill…
  • 100common-software-requirements
    Standardize SRS and FRS specifications for technical behavior, interfaces, data contracts, quality constraints, and verification mapping. Use when writing SRS, functional specification, system behavior requirements, API/data contracts, or non-functional thresholds.
  • 100frd-writer
    Write a Functional Requirements Document. Use when the user says "write an FRD", "functional requirements", "system requirements", "SRS", "what should the system do", "document the functional specs", "software requirements specification", "detailed requirements for engineering",…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.