SpecSpec Skills
Use these skills in order when you need a complete top-down design:
create-specspecruns the complete workflow.create-specspec-l4creates product intent and capabilities.create-specspec-l3creates the system design.create-specspec-l2creates component boundaries.create-specspec-l1creates module boundaries.
Use review-specspec-design to inspect a complete L4-L1 design. It reports architecture findings
without changing documents. Use correct-specspec-design to resolve a reviewer report and repeat
the review.
For an existing codebase, use code2specspec to derive a source-backed L0-L4 bundle. Its
layer skills can also run one layer at a time:
code2specspec-l0records source files, symbols, and line-anchored evidence.code2specspec-l1derives Modules from the source and L0 inventory.code2specspec-l2derives Components from the observed Modules.code2specspec-l3describes observed system behavior and interfaces.code2specspec-l4describes source-backed product outcomes and limits.
code2specspec-review checks source accuracy and gap coverage without editing the bundle.
The master code2specspec skill runs the five layers in order, audits entry-to-output behavior,
and then calls the reviewer. This reverse workflow is separate from the proposed-design workflow
above.
The repository examples contain separate code-spec/ bundles and a comparison report at
examples/code2specspec-comparison.md.
When a comparison spec is supplied, code2specspec derives the source bundle first. It then
checks each expected outcome and writes a gap report. Unimplemented intent stays in that report.
You can also start at a lower layer when the required higher-layer documents already exist.
The design workflow stops at L1. Use implement-spec with an approved L4-L1 bundle to build a
new reference application. It asks for stack approval, delivers a runnable first version, and
continues until every Capability Behavior bullet and Acceptance criterion passes with a marked test.
It then derives L0 from tested code in a separate implementation bundle and requires an independent L0-L4 review. It pauses for specification decisions. Working-tree L0 evidence records pending Git pinning when no matching committed revision exists. Existing application changes are not supported.
The plugin includes an L3-L1 ontology validator at
scripts/validate_specspec_design.py and a criterion coverage checker at
scripts/check_criterion_coverage.py.
Three reference examples use the same approved design:
examples/equipment-reservation/is a complete Python, Flask, and SQLite reference with 90 passing tests, code-derived L0, and an independent L0-L4 review.examples/equipment-reservation-cobol/is a mainframe reference with Enterprise COBOL, CICS, DB2, a browser shell, JCL, and 50 marked criterion tests. Runtime verification is blocked because this workstation has no z/OS, CICS, DB2, or Enterprise COBOL runtime.examples/equipment-reservation-foxpro/is a Visual FoxPro 9 reference with DBF tables, a browser shell, and 50 marked criterion tests. Runtime verification is blocked because this workstation has no VFP9 runtime.