Add useblocks-vmodel preset (RST V-model as a preset, no core changes)#2
Merged
Add useblocks-vmodel preset (RST V-model as a preset, no core changes)#2
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a self-contained useblocks-vmodel preset that overrides core Spec Kit commands to generate reStructuredText (RST) artefacts compatible with sphinx-needs, including project-root scaffolding and bootstrap scripts—without modifying Spec Kit core.
Changes:
- Introduces a new preset (
preset.yml) thatreplaces:9 corespeckit.*commands with RST-oriented prompts. - Adds RST templates for spec/plan/tasks/coverage/checklist/constitution and project-root Sphinx/ubcode scaffolding.
- Adds idempotent bootstrap scripts (bash + PowerShell) to scaffold required root files and
.specify/config.toml.
Reviewed changes
Copilot reviewed 22 out of 22 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| presets/useblocks-vmodel/preset.yml | Declares the preset and command overrides via replaces:. |
| presets/useblocks-vmodel/README.md | Documents installation, workflow, and ID/link conventions for the preset. |
| presets/useblocks-vmodel/commands/speckit.specify.md | RST-based /speckit.specify prompt including sphinx-needs trace rules + bootstrap guidance. |
| presets/useblocks-vmodel/commands/speckit.plan.md | RST-based /speckit.plan prompt producing plan.rst with SPEC/DEC/RISK/TC. |
| presets/useblocks-vmodel/commands/speckit.tasks.md | RST-based /speckit.tasks prompt producing tasks.rst with TASK/TC links. |
| presets/useblocks-vmodel/commands/speckit.implement.md | RST-based /speckit.implement prompt for executing tasks and updating statuses. |
| presets/useblocks-vmodel/commands/speckit.clarify.md | RST-based /speckit.clarify prompt for resolving [NEEDS CLARIFICATION] markers. |
| presets/useblocks-vmodel/commands/speckit.analyze.md | RST-based /speckit.analyze prompt for read-only analysis using needs.json. |
| presets/useblocks-vmodel/commands/speckit.checklist.md | RST checklist-generation prompt (non-sphinx-needs artefact). |
| presets/useblocks-vmodel/commands/speckit.constitution.md | RST constitution authoring prompt (plain RST, no sphinx-needs directives). |
| presets/useblocks-vmodel/commands/speckit.taskstoissues.md | Converts .. task:: directives into GitHub issues with write-back guidance. |
| presets/useblocks-vmodel/templates/spec-template.rst | RST template for feature specs (US/REQ/RISK/DEC/TC). |
| presets/useblocks-vmodel/templates/plan-template.rst | RST template for implementation plans (SPEC/DEC/RISK/TC). |
| presets/useblocks-vmodel/templates/tasks-template.rst | RST template for task breakdown + test cases. |
| presets/useblocks-vmodel/templates/coverage-template.rst | RST template for coverage tables/needflow rendering. |
| presets/useblocks-vmodel/templates/checklist-template.rst | RST template for checklists using checkbox-style list items. |
| presets/useblocks-vmodel/templates/constitution-template.rst | RST template for project constitution (principles + governance). |
| presets/useblocks-vmodel/scaffold/ubproject.toml | ubcode/sphinx-needs types, links, and ID regex configuration. |
| presets/useblocks-vmodel/scaffold/conf.py | Sphinx config wiring needs_from_toml, exclude patterns, and warning suppression. |
| presets/useblocks-vmodel/scaffold/coverage.rst | Project-root master doc aggregating specs and rendering coverage tables/needflow. |
| presets/useblocks-vmodel/scripts/bash/bootstrap-vmodel.sh | Idempotent bootstrapper to copy root scaffolding + set .specify/config.toml. |
| presets/useblocks-vmodel/scripts/powershell/bootstrap-vmodel.ps1 | PowerShell bootstrapper equivalent to the bash script. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 22 out of 22 changed files in this pull request and generated 7 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…odel output Replaces every core /speckit.* command with an RST variant that emits sphinx-needs directives carrying the full V-model trace graph (User Story, Functional Requirement, Architectural Specification, Implementation Task, plus Risk and Decision). Build correctness is validated by `sphinx-build -b needs -W` after every command. Implementation is a pure preset, zero core changes. The preset ships 9 command overrides via `replaces:`, 6 per-feature RST templates, 3 project-root scaffolding files (ubproject.toml, conf.py, coverage.rst), and an idempotent bootstrap script (bash + PowerShell mirrors) that copies scaffolding to the project root on first command run. Validated end-to-end with claude -p sonnet: - /speckit-specify produces 21 needs, 0 schema warnings, complete US/REQ/RISK/TC graph with [NEEDS CLARIFICATION] markers preserved. - /speckit-plan chained on top reaches 38 total needs, 0 trace violations. Every REQ satisfied by SPEC, every SPEC verified by TC, decisions resolve open clarifications from the spec phase. Tested against spec-kit 0.8.2.dev0. The preset depends on the composition strategies introduced in PR github#2133.
bburda
force-pushed
the
useblocks/vmodel-preset
branch
from
532f186 to
5c47fc6
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Re-implements the RST + sphinx-needs V-model workflow from #1 as a pure spec-kit preset. Zero changes to core. Drops a new directory under
presets/useblocks-vmodel/containing 9 command overrides, 6 RST templates, project-root scaffolding, and an idempotent bootstrap script.How this relates to #1
#1 (
useblocks/integration) proves the concept by modifying spec-kit core: a top-level--format rstflag, a paralleltemplates/commands-rst/tree,_bootstrap_rst_project()in__init__.py, format-aware toggles inagents.py,extensions.py,presets.py, and the integration setups, plus mirrored bash and PowerShell scripts. ~4300 added lines, 46 files touched, currentlyCONFLICTINGagainstmainafter upstream's 27-commit--ai → --integrationrename,SkillsIntegrationmigration, andcompose: replace|prepend|append|wrappreset composition strategies (PR github#2133) landed.This PR uses those new composition strategies. Each of the nine V-model commands is declared in
preset.ymlwithreplaces: speckit.<name>, so when an agent runs/speckit-specifythe preset resolver returns our RST prompt instead of the core Markdown one. No core code changes.The two PRs are intentionally independent. #1 is not the base of this PR. They target the same use case via two different mechanisms:
--format rst) + parallelcommands-rst/treereplaces:overrides via composition strategiessrc/specify_cli/mainCONFLICTING(27 commits behind)main)#1 stays open as the reference implementation that documents what the workflow actually does. The prompts originated there. This PR is the upstream-friendly path. After agreement that this preset path is preferred, #1 can be closed without losing the prompt content. It has been carried forward verbatim in this PR's
commands/.What is in
preset.yml: 9 command overrides (speckit.specify,plan,tasks,implement,clarify,analyze,checklist,constitution,taskstoissues), eachreplaces:the core command via the defaultreplacestrategy.commands/: 9 RST-flavoured agent prompts. Each teaches V-model authoring (User Story, Requirement, Specification, Task plus Risk and Decision), self-validation viasphinx-build -b needs -Wwith up to 3 fix iterations, and the honest-unknowns rule ([NEEDS CLARIFICATION]markers inside directive bodies instead of fabricated SHOULD/MUST clauses).templates/: 6 per-feature RST scaffolds (spec, plan, tasks, coverage, checklist, constitution).scaffold/: 3 project-root files copied by bootstrap (ubproject.toml,conf.py,coverage.rst).scripts/bash/bootstrap-vmodel.shandscripts/powershell/bootstrap-vmodel.ps1: idempotent scaffolding helpers. The first command run (typically/speckit-specifyor/speckit-constitution) instructs the agent to invoke this script. Existing project-root files are never overwritten.What is out
src/specify_cli/,templates/,scripts/,tests/.specify preset add useblocks-vmodelswitches behaviour,specify preset remove useblocks-vmodelreverts.SkillsIntegration(PR feat(vibe): migrate to SkillsIntegration from the old prompts-based MarkdownIntegration github/spec-kit#2336) are sufficient.Testing
End-to-end with
claude -p --model sonnet --permission-mode bypassPermissionsagainst a fresh project (specify init test --integration claude --no-gitthenspecify preset add --dev presets/useblocks-vmodel):/speckit-specifyon a CSV bucket aggregator description created 21 needs with 0 schema warnings. 3[NEEDS CLARIFICATION]markers were preserved (not invented). Bootstrap script ran (4 project-root files created)./speckit-planchained on the same project added another 17 needs for a total of 38 with 0 trace violations. Every REQ has at least one SPEC:satisfies:it. Every SPEC has at least one TC:verifies:it. Two open clarifications from spec phase resolved by DEC records.sphinx-build -b needs -Wpasses (build succeeded).Test plan
specify initproject, thenspecify preset add --dev presets/useblocks-vmodel./speckit-specifywith any feature description. Confirm bootstrap createsubproject.toml,conf.py,coverage.rst,.specify/config.toml.specs/<feature>/spec.rstcontains sphinx-needs directives and passessphinx-build -b needs -W./speckit-planand verify trace graph completeness vianeeds.json.specify preset remove useblocks-vmodelreverts to core Markdown commands.Known limitations
SkillsIntegrationrewrites the rendered SKILL.md description from a hardcodedSKILL_DESCRIPTIONSdict inpresets.py. The user-visible command description shows the core Markdown wording rather than the preset's V-model framing. The command body (the actual instructions the agent follows) is preserved verbatim, so behaviour is correct. A small upstream change to honour preset frontmatter would close this gap.coverage.rsttoctree fire on a fresh project with no specs yet.suppress_warnings = ["toc.empty_glob"]is set inconf.pybut Sphinx 9.1's toctree warning does not passtype=, so the suppression is currently a no-op (documented intent). Agents handle these warnings as expected during the spec phase. Once any feature exists, the build is green.