useblocks V-model RST preset

Switches every spec-kit core command (/speckit.specify, /speckit.plan, /speckit.tasks, /speckit.implement, /speckit.clarify, /speckit.analyze, /speckit.checklist, /speckit.constitution, /speckit.taskstoissues) to emit reStructuredText artefacts with a complete sphinx-needs trace graph:

User Story → Functional Requirement → Architectural Specification → Implementation Task, plus optional Risk and Decision records.

Every artefact is validated by sphinx-build -b needs -W. The build is the oracle, not grep or regex. Open questions live as [NEEDS CLARIFICATION] markers inside directive bodies (the build still passes), and the coverage.rst page lists them for /speckit.clarify to resolve.

Install

Once the preset is published to the spec-kit community catalog:

specify init my-project --integration claude
cd my-project
specify preset add useblocks-vmodel

Install directly from a tagged release archive:

specify preset add --from https://github.com/useblocks/spec-kit-preset-useblocks-vmodel/archive/refs/tags/v0.1.1.zip

Install from a local checkout (preset development):

specify preset add --dev path/to/spec-kit-preset-useblocks-vmodel

First run

The first command you invoke (typically /speckit.specify or /speckit.constitution) detects missing scaffolding and runs the bootstrap script idempotently:

bash .specify/presets/useblocks-vmodel/scripts/bash/bootstrap-vmodel.sh

PowerShell mirror:

pwsh .specify/presets/useblocks-vmodel/scripts/powershell/bootstrap-vmodel.ps1

Bootstrap creates four files at the project root if they are missing:

• ubproject.toml: sphinx-needs schema, link types, ID regex, ubcode config
• conf.py: sphinx config wired to needs_from_toml
• coverage.rst: master document with :glob: toctree over specs/*/
• .specify/config.toml: format = "rst" flag consumed by command prompts

Existing files are left untouched. Bootstrap is safe to re-run.

Workflow

/speckit.constitution     # optional: project principles → .specify/memory/constitution.rst
/speckit.specify <desc>   # → specs/<feature>/spec.rst with US/REQ/RISK/TC
/speckit.clarify          # optional: resolve [NEEDS CLARIFICATION] markers
/speckit.plan <stack>     # → specs/<feature>/plan.rst with SPEC/DEC + ancillary docs
/speckit.tasks            # → specs/<feature>/tasks.rst with TASK directives
/speckit.implement        # execute tasks while preserving trace links
/speckit.analyze          # cross-artefact consistency report

After each command, sphinx-build -b needs -W is the source of truth for structural completeness. The agent re-runs the build until it is green or hits the iteration cap (typically 3 attempts).

ID conventions

• US_<DOMAIN>_<NNN>: User Story
• REQ_<DOMAIN>_<NNN>: Functional Requirement
• SPEC_<DOMAIN>_<NNN>: Architectural Specification
• TASK_<DOMAIN>_<PHASE>_<NNN>: Implementation Task (for example, TASK_AUTH_IMPL_001)
• TC_<DOMAIN>_<KIND>_<NNN>: Test Case (KIND ∈ ACC, SYS, INT, UNIT)
• RISK_<DOMAIN>_<NNN>: Risk
• DEC_<DOMAIN>_<NNN>: Decision

ID regex enforced in ubproject.toml: ^[A-Z]+_[A-Z][A-Z0-9_]*$ (digits cannot follow the first underscore).

Trace link types

Outgoing	Back-link	Direction
:traces_to:	:traces_from:	REQ → US, DEC → US
:satisfies:	:satisfied_by:	SPEC → REQ
:implements:	:implemented_by:	TASK → SPEC
:verifies:	:verified_by:	TC → US, TC → SPEC, TC → TASK
:affects:	:affected_by:	RISK → REQ/SPEC/TASK
:motivates:	:motivated_by:	DEC → SPEC
:mitigates:	:mitigated_by:	SPEC/TASK/DEC → RISK

Layout

.specify/presets/useblocks-vmodel/
├── preset.yml                       # 9 command overrides, replaces: speckit.*
├── commands/                        # AI prompts (one per replaced command)
├── templates/                       # per-feature RST scaffolds
├── scaffold/                        # project-root files copied by bootstrap
└── scripts/
    ├── bash/bootstrap-vmodel.sh
    └── powershell/bootstrap-vmodel.ps1

Compatibility

• spec-kit >=0.8.0 (preset composition strategies)
• sphinx-needs >=2.0
• Python >=3.10 (sphinx-needs requirement)

Companion: pharaoh

pharaoh is a sphinx-needs requirements engineering AI framework that pairs cleanly with this preset. The preset emits artefacts; pharaoh reviews and audits them against ISO 26262-8 §6, ASPICE 4.0, and ISO/SAE 21434, and adds gap, traceability, and impact analysis on top of the resulting needs.json. It ships as a Claude Code / GitHub Copilot plugin (separate distribution from the spec-kit catalog — install both side by side).

# Claude Code
/plugin marketplace add useblocks/pharaoh
/plugin install pharaoh@pharaoh-dev

Recommended pairings:

After this preset command	Run this pharaoh skill	For
/speckit.specify	/pharaoh:pharaoh-req-review	Audit each req directive against the 11 ISO 26262-8 §6 axes
/speckit.plan	/pharaoh:pharaoh-arch-review	Audit each spec directive (architecture element) for traceability and quality
/speckit.tasks	/pharaoh:pharaoh-vplan-review	Audit each test-case directive
/speckit.analyze	/pharaoh:pharaoh-mece	Gap and redundancy analysis (orphans, missing links, MECE violations)
—	/pharaoh:pharaoh-change <ID>	Impact analysis of a requirement change across the trace graph
—	/pharaoh:pharaoh-trace	Traceability navigation across REQ → SPEC → TASK → TC
—	/pharaoh:pharaoh-flow	Full V-model authoring chain (req → arch → vplan → fmea) with a review pass after each step

For the complete catalogue of pharaoh skills (71 atomic, plan-driven), see the pharaoh README.

License

MIT