From 2c95f423e2556832acd9ab84d15c61edfe322f57 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sun, 26 Jul 2026 15:18:15 +0000 Subject: [PATCH 1/2] Update workflow-preset to v3.0.0 Assisted-by: GitHub Actions (autonomous) --- presets/catalog.community.json | 13 +- presets/catalog.json | 11 +- presets/workflow-preset.release.json | 181 ++++++ presets/workflow-preset/.gitignore | 24 - presets/workflow-preset/AGENTS.md | 11 +- presets/workflow-preset/CHANGELOG.md | 13 + presets/workflow-preset/README.md | 584 +++++------------- .../commands/speckit.implement.md | 219 ------- .../docs/extension-governance.md | 254 ++++---- presets/workflow-preset/preset.yml | 11 +- .../contracts/speckit-cross-agent-protocol.md | 85 +-- .../tests/test_preset_contract.py | 115 +++- tests/test_presets.py | 2 +- 13 files changed, 629 insertions(+), 894 deletions(-) create mode 100644 presets/workflow-preset.release.json delete mode 100644 presets/workflow-preset/.gitignore delete mode 100644 presets/workflow-preset/commands/speckit.implement.md diff --git a/presets/catalog.community.json b/presets/catalog.community.json index 86d9af59e9..b2121713cb 100644 --- a/presets/catalog.community.json +++ b/presets/catalog.community.json @@ -670,11 +670,11 @@ "workflow-preset": { "name": "Workflow Preset", "id": "workflow-preset", - "version": "2.0.0", + "version": "3.0.0", "description": "Constitution-managed architecture, behavior-first specification, design artifacts, and scoped change governance", "author": "bigsmartben", "repository": "https://github.com/bigsmartben/spec-kit-workflow-preset", - "download_url": "https://github.com/bigsmartben/spec-kit-workflow-preset/releases/download/v2.0.0/spec-kit-workflow-preset-v2.0.0.zip", + "download_url": "https://github.com/bigsmartben/spec-kit-workflow-preset/releases/download/v3.0.0/spec-kit-workflow-preset-v3.0.0.zip", "homepage": "https://github.com/bigsmartben/spec-kit-workflow-preset", "documentation": "https://github.com/bigsmartben/spec-kit-workflow-preset/blob/main/README.md", "license": "MIT", @@ -683,7 +683,7 @@ }, "provides": { "templates": 24, - "commands": 8 + "commands": 7 }, "tags": [ "architecture", @@ -691,11 +691,12 @@ "behavior", "bdd", "planning", - "implementation", - "handoff" + "implementation" ], "created_at": "2026-05-27T00:00:00Z", - "updated_at": "2026-06-23T00:00:00Z" + "updated_at": "2026-06-23T00:00:00Z", + "source_commit": "c35c96cec18c280445ea4f9f73c929e5b61f8393", + "sha256": "3924817ded5c59649ea3ef685cd1a4572363f95e9379becd0eafe1d3757ee852" } } } diff --git a/presets/catalog.json b/presets/catalog.json index edcef0416d..b5e5fbc216 100644 --- a/presets/catalog.json +++ b/presets/catalog.json @@ -29,7 +29,7 @@ "workflow-preset": { "name": "Workflow Preset", "id": "workflow-preset", - "version": "2.0.0", + "version": "3.0.0", "description": "Constitution-managed architecture, behavior-first specification, design artifacts, and scoped change governance", "author": "bigsmartben", "repository": "https://github.com/bigsmartben/spec-kit-workflow-preset", @@ -39,7 +39,7 @@ "speckit_version": ">=0.12.7.dev0" }, "provides": { - "commands": 8, + "commands": 7, "templates": 24 }, "tags": [ @@ -48,9 +48,10 @@ "behavior", "bdd", "planning", - "implementation", - "handoff" - ] + "implementation" + ], + "source_commit": "c35c96cec18c280445ea4f9f73c929e5b61f8393", + "sha256": "3924817ded5c59649ea3ef685cd1a4572363f95e9379becd0eafe1d3757ee852" } } } diff --git a/presets/workflow-preset.release.json b/presets/workflow-preset.release.json new file mode 100644 index 0000000000..4b1a6990b8 --- /dev/null +++ b/presets/workflow-preset.release.json @@ -0,0 +1,181 @@ +{ + "artifact": { + "name": "spec-kit-workflow-preset-v3.0.0.zip", + "sha256": "3924817ded5c59649ea3ef685cd1a4572363f95e9379becd0eafe1d3757ee852" + }, + "files": [ + { + "path": "AGENTS.md", + "sha256": "a3e48054a1cdedfa8ef91c642fe7b166bf951df1916ed92bc3b370d7b1f64d48" + }, + { + "path": "CHANGELOG.md", + "sha256": "b5500b5bdbe6febc33778e9bbf3dab0bb0426030788235bcf1c3d3bd154cf2e3" + }, + { + "path": "LICENSE", + "sha256": "8c9a47687655839e45d596c67fb9a13a1c9cd39eca4aaa0846e7afd9a01f1ab1" + }, + { + "path": "README.md", + "sha256": "b392ddb13c8cd4bf627da2d41e1ffb5ad13cf2a8c7ee6e69d1f460ecebf328eb" + }, + { + "path": "commands/speckit.analyze.md", + "sha256": "4ee1593b26cf7bc96246a78c3d44409775c7715cdb250b98ba6924f8b667de0e" + }, + { + "path": "commands/speckit.checklist.md", + "sha256": "931dc432b490f76dc4df80e8d087bbeb1468205fa986369870ed0fd85152c9e3" + }, + { + "path": "commands/speckit.clarify.md", + "sha256": "cc893a93b96b2f1196540ad315cae25d0f4316651a3a1260396ed8cac3c95260" + }, + { + "path": "commands/speckit.constitution.md", + "sha256": "a32ac47fb666bb2475d93d0d2ebb93426a2a5c70723ede8f5dd38005f87b0448" + }, + { + "path": "commands/speckit.plan.md", + "sha256": "26bbc0ff6ba91b72b86c317c501cfd65cf22d0e9bfc67e55d722ce6cb95b2e9e" + }, + { + "path": "commands/speckit.specify.md", + "sha256": "0e9a1c1521a2932d708ad34af5c67215b15d094691b12f9c6be501b20413e7c2" + }, + { + "path": "commands/speckit.tasks.md", + "sha256": "7434d434f9092ab99ba02857e933f8426cbd731ffa61b24473c96382aeded219" + }, + { + "path": "docs/extension-governance.md", + "sha256": "6f9d183ff3defb1abcfc6a25970feda8855e04f70e66cb98df96d33a030a3961" + }, + { + "path": "preset.yml", + "sha256": "d6812ee256ac3719e5d5ea95704e7a97c46aae63cbe5a19eb7dbcf91068cd8d6" + }, + { + "path": "requirements-dev.txt", + "sha256": "75bfdb680a26a97ba91e8089c6970962de9aefbaa102eb6a3445bd08e4b55322" + }, + { + "path": "schemas/speckit.behavior.assertions.v1.schema.json", + "sha256": "8f39b5b1615172ee1d0ac15a72545b60b98355474695694cca60cf0615772fed" + }, + { + "path": "schemas/speckit.behavior.data-fixtures.intent.v1.schema.json", + "sha256": "e43a3f4341b80507a8cee8e07949dd6cc0380c88655894c60c51ba0ac92873ed" + }, + { + "path": "schemas/speckit.behavior.data-fixtures.v1.schema.json", + "sha256": "7b763ede880aff476746b5f9eb24c540d42bcbc4d24a33b002376bdecbbca5dd" + }, + { + "path": "schemas/speckit.behavior.scenario-instances.v1.schema.json", + "sha256": "5f847f913b32829fd4c205cbef9e994e0e065a8596f8f8be525bb34f653f2191" + }, + { + "path": "schemas/speckit.behavior.scenarios.draft.v1.schema.json", + "sha256": "b992e4e85d5854b777f37be7f7a309105526b6c8cd53ff7f58cc2e0fcd002fec" + }, + { + "path": "schemas/speckit.behavior.uif.expected.v1.schema.json", + "sha256": "024653cfaef2255a1dec521feae52847e24c5e88782d2babbbdb3120e5bc81bc" + }, + { + "path": "schemas/speckit.behavior.uif.intent.v1.schema.json", + "sha256": "f8600df13a610634330b736116f560b9b5ea72ba6f092dea096a7522e6a362ed" + }, + { + "path": "templates/architecture-template.md", + "sha256": "9f8460ec74e6aeaef0cef686eec1ff3843aced4cd6e68ff2eb3e7291b87bcd40" + }, + { + "path": "templates/behavior/assertions.json", + "sha256": "b47c06f6fc77bfbf76dd4fbfd1207d292196bfe5be16391e17fcbfb6e2df2bd6" + }, + { + "path": "templates/behavior/bdd-contract.feature", + "sha256": "7b846ea7e4cdd0ff63245fb3da201df3da9742d6364c685a5a3583137607a810" + }, + { + "path": "templates/behavior/bdd-draft.feature", + "sha256": "070262ee305e6fe5e053df4d47d6edf9d3cf215a8f6457f7ee2b309fee68310f" + }, + { + "path": "templates/behavior/behavior-scenarios-draft.json", + "sha256": "6def3acc8d3a44b2023d60c3e7717d1183ef4e4b7ff7be8bfb9d1d8f4fbd451c" + }, + { + "path": "templates/behavior/behavior-testability.md", + "sha256": "bbedd7a31c1ebb0b03ba1585401551f2910f3f297f62bcc3ded8d1e2b8057ad0" + }, + { + "path": "templates/behavior/data-fixtures-intent.json", + "sha256": "52860246ad830f8a3d620fbb78773127777839d50cb72da25383677adf4aba17" + }, + { + "path": "templates/behavior/data-fixtures.json", + "sha256": "aba3c98fd9d4a0332a2d5a57bc007885bf46279aa356e619e19b2a4ff9e47387" + }, + { + "path": "templates/behavior/scenario-instances.json", + "sha256": "1bf2999050106565bbb5a0c0b93fdaabe3d64602643822b17c041db1afc2a120" + }, + { + "path": "templates/behavior/uif-expected.json", + "sha256": "20c45e08817cfd926c9586f8ccdc7bf55eb7f2e08a57b783e41a4fb5efd97959" + }, + { + "path": "templates/behavior/uif-intent.json", + "sha256": "66572ff70127e5fcb23c0815f902a0fc525081a3c1c0d1e0e87c4be4c19bbbad" + }, + { + "path": "templates/constitution-template.md", + "sha256": "6763fba121628fa5b81b1c52ba8c6bc5485ce4c15ebb4653d88f3ebbd507391c" + }, + { + "path": "templates/plan-template.md", + "sha256": "3ac5ca372aad14e8b2110aa7c48d36fbe5409646c8267444cf6fc59317b18da0" + }, + { + "path": "templates/requirements/behavior-gate.md", + "sha256": "432c805d3f0f1e7feea6bc0171573a410bf20a64ccc16411de2c2cc9eb7628d6" + }, + { + "path": "templates/requirements/domain-gate.md", + "sha256": "d79afadb37e0f95a2faf4f429c88d0577e536000f97f4126ae92194bef0c26e8" + }, + { + "path": "templates/requirements/nfr-gate.md", + "sha256": "3aa029528263aae1f082822214301a39bb2008dd14a56f3c730959f63a50c79c" + }, + { + "path": "templates/requirements/visual-gate.md", + "sha256": "0884437eba2d8e2f9ea49bc6027c721763987cee6ab63dc3806b50843cbc6974" + }, + { + "path": "tests/contracts/speckit-cross-agent-protocol.md", + "sha256": "17c7b2dd55f4f4c775f3bd2ed8649afea2bd9620d182ced9feaeab1bca8b2aa8" + }, + { + "path": "tests/test_preset_contract.py", + "sha256": "b513ee724b850f7e1d489bb1df2a3c50c24239c4a45697852cb2b50048268dea" + }, + { + "path": "validators/__init__.py", + "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" + }, + { + "path": "validators/speckit_behavior_contract.py", + "sha256": "988131eb3138cc6a4a21a5ef3c936534aeceea17fe866be822ef0a3f09476ac9" + } + ], + "preset_id": "workflow-preset", + "schema_version": "1.0", + "source_commit": "c35c96cec18c280445ea4f9f73c929e5b61f8393", + "source_repository": "https://github.com/bigsmartben/spec-kit-workflow-preset", + "version": "3.0.0" +} diff --git a/presets/workflow-preset/.gitignore b/presets/workflow-preset/.gitignore deleted file mode 100644 index 756e140ac4..0000000000 --- a/presets/workflow-preset/.gitignore +++ /dev/null @@ -1,24 +0,0 @@ -__pycache__/ -*.py[cod] -.pytest_cache/ -.mypy_cache/ -.ruff_cache/ -.coverage -htmlcov/ -.venv/ -venv/ -dist/ -build/ -*.egg-info/ -*.zip -*.log -.env -.env.* -!.env.example -.tmp/ -tmp/ -temp/ -.DS_Store -Thumbs.db -.worktrees/ -docs/superpowers/ diff --git a/presets/workflow-preset/AGENTS.md b/presets/workflow-preset/AGENTS.md index 6d70b447cf..670f8eae45 100644 --- a/presets/workflow-preset/AGENTS.md +++ b/presets/workflow-preset/AGENTS.md @@ -14,10 +14,15 @@ This repository is a Spec Kit community preset named `workflow-preset`. ## Development Rules - Preserve the preset contract tested by `tests/test_preset_contract.py`. -- Follow the Extension Governance in `docs/extension-governance.md` before adding or changing preset commands, templates, schemas, validators, handoff contracts, or behavior-first artifacts. +- Follow the Extension Governance in `docs/extension-governance.md` before adding or changing preset commands, templates, schemas, validators, or behavior-first artifacts. - Keep `/speckit.plan` and `/speckit.tasks` as core-template wrappers. -- Keep `/speckit.implement` as a replacement command synchronized with the upstream standard implementation workflow. -- Do not reintroduce Python orchestration, workflow shell dispatch, integration adapter scripts, or worker dispatch from scripts. +- Do not declare, copy, or replace `/speckit.implement`; implementation execution + belongs to the currently installed Spec Kit core command. +- Keep Final Code Review as the last mandatory phase generated in `tasks.md`. +- Do not introduce an implementation reviewer runtime, persistent transfer + protocol, execution manifest, worker result protocol, Python orchestration, + workflow shell dispatch, integration adapter scripts, or script-based worker + dispatch. - Planning design artifacts are optional and contextual: - `class-diagram.md` - `contracts/sequences.md` diff --git a/presets/workflow-preset/CHANGELOG.md b/presets/workflow-preset/CHANGELOG.md index bae0146c9e..5051ef40f6 100644 --- a/presets/workflow-preset/CHANGELOG.md +++ b/presets/workflow-preset/CHANGELOG.md @@ -2,6 +2,19 @@ ## Unreleased +## 3.0.0 - 2026-07-26 + +- Removed the preset-owned `speckit.implement` replacement and its manifest, + transfer, worker-result schemas, validator, and persistent execution + protocol. The active Spec Kit core command now owns implementation. +- Kept Final Code Review as the last mandatory `tasks.md` phase so standard + core implementation executes and validates it in checklist order. +- Split behavior-only cross-field validation into + `validators/speckit_behavior_contract.py`. +- Defined release snapshots as immutable, source-backed artifacts; downstream + bundling must preserve release file hashes and must not modify a published + version in place. + ## 2.0.0 - 2026-07-26 - Moved project Architecture generation into `/speckit.constitution`, which now diff --git a/presets/workflow-preset/README.md b/presets/workflow-preset/README.md index 46119ab46f..e71163653a 100644 --- a/presets/workflow-preset/README.md +++ b/presets/workflow-preset/README.md @@ -1,500 +1,224 @@ # Workflow Preset -This Spec Kit community preset combines Constitution-managed project Architecture, behavior-first specification, design-aware planning, scoped change governance, and agent-native handoff orchestration. - -It wraps `/speckit.specify`, `/speckit.checklist`, `/speckit.clarify`, -`/speckit.constitution`, `/speckit.plan`, `/speckit.tasks`, and -`/speckit.analyze` with multi-domain requirement gates, Change Scope -Granularity, a single-file project Architecture lifecycle, Architecture-guided -planning, Phase 0 behavior projection, formal behavior contracts, plan-stage -Behavior Testability, optional design artifacts, and task-time validation -derivation. It replaces -`/speckit.implement` with a Core Agent, Vertical Planner Agent, and Worker Agent -orchestration contract that writes handoffs to disk. - -## Goal - -`workflow-preset` turns a Spec Kit feature from a single broad implementation prompt into a staged workflow with stable design context and explicit worker boundaries. - -The preset has six goals: - -- Make requirements, behavior, UX, security, NFR, and visual readiness explicit - before planning without creating a Planning Readiness summary file. -- Project accepted requirements into BDD, UIF intent, and fixture intent drafts during `/speckit.plan` Phase 0. -- Close planning with `behavior/behavior-testability.md`, which maps Required - Cases and formal planning decisions into Task Readiness. -- Preserve richer planning intent so downstream tasks and implementation do not lose object design, service-flow, or validation decisions. -- Keep implementation scope explicit by applying Change Scope Granularity from planning onward: M + U boundaries are locked before execution maps them to concrete paths and O-level edits. -- Execute implementation through agent-native handoff orchestration so each worker receives explicit task IDs, lifecycle stage, vertical capability, context, read/write paths, validation commands, and receipt requirements. - -## Problem Addressed - -Large Spec Kit features can overload the implementation phase. A single `/speckit.implement` run may need to keep product requirements, technical decisions, domain details, interface contracts, object design, service flows, test strategy, task ordering, and current code changes in one prompt. As the context grows, the agent is more likely to drift from earlier design decisions, blur task boundaries, read unrelated documents, update the wrong files, or mark tasks complete without enough validation evidence. - -`workflow-preset` reduces that failure mode in three complementary ways: - -- Requirement enhancement keeps product requirements in `spec.md` and gates - planning with metadata-bearing domain checklists. -- Scope governance keeps broad repository context from becoming implementation scope by applying the R/M/U/O model once planning begins. -- Plan enhancement projects accepted behavior drafts, then gives object design, service sequencing, and validation intent stable homes before tasks are generated. -- Implement handoff orchestration slices work by lifecycle and vertical capability, then gives each Worker Agent a compact digest, scoped paths, validation commands, and a receipt contract instead of the full planning corpus. - -The intent is not to add ceremony to simple features. The intent is to preserve reasoning quality when the feature is large enough that a single implementation context becomes a source of drift. - -## Capabilities - -Requirement capabilities: - -- Wraps `/speckit.specify` so it produces or updates `spec.md` only. -- Wraps `/speckit.clarify` so it resolves product-decision blockers in - `spec.md`, recomputes affected gates, and leaves provider evidence with - intake. -- Consumes confirmed product facts, external intake facts, visual SSOT refs, HTML SSOT refs, structured IR refs, and evidence refs when projecting requirements into `spec.md`. -- When external intake evidence or visual SSOT refs have already been projected into `spec.md`, `/speckit.clarify` clarifies evidence-derived gaps already written in `spec.md` and does not call provider tools. -- Wraps `/speckit.checklist` to generate `requirements.md`, `behavior.md`, - `ux.md`, `security.md`, `nfr.md`, and `visual.md` requirement gates. -- Checks user stories, acceptance criteria, Given/When/Then readiness, roles, permissions, states, data, validation, boundary, exception, state_conflict behavior, and non-functional requirements directly from `spec.md`. -- Adds a Case Coverage Matrix with one row per story or capability case type so positive, negative, boundary, permission, validation, and state_conflict cases are marked Required, Not Applicable, or Unknown before planning. -- Checks visual requirements for source traceability, external intake readiness status when cited, HTML SSOT refs, structured IR refs, evidence refs, provider blocker status, and visual fidelity scope before planning. -- Preserves stable visual SSOT refs, HTML SSOT refs, structured IR refs, and evidence refs through `spec.md` and the Visual Fidelity Evidence Matrix. -- Records Client Asset Contract facts in `spec.md` for asset source strategy, required variants, fallback policy, and blocker status. -- Requires NFR dimensions to be marked Required, Not Applicable, or Unknown in product language before planning. -- Blocks planning when readiness gaps or missing or unverifiable NFR assumptions must return to `/speckit.clarify` or `/speckit.specify`. - -Governance capabilities: - -- Wraps `/speckit.constitution` so one Constitution-stage lifecycle maintains separate `.specify/memory/constitution.md` and `.specify/memory/architecture.md` files. -- Establishes a user-confirmed input agreement for greenfield, brownfield, and amendment runs; no UC, README, or repository path is an automatic prerequisite or authority. -- Produces one five-section project Architecture through System Boundary -> Conceptual Model -> Technical Decisions & Evidence -> Planning Guardrails & Gaps reasoning, with no 4+1 views or secondary models. -- Defines the fixed R/M/U/O model: R is Repository / Workspace, M is Module / Capability, U is Unit / Design Object, and O is Operation / Detail. These letters must not be renamed or expanded with alternate nouns. -- Blocks constitution writes when a generated draft changes the fixed R/M/U/O mapping. -- Keeps durable governance in `constitution.md` and project-level boundaries, concepts, technical direction, evidence, constraints, and gaps in `architecture.md`. -- Requires planning to lock M + U before execution maps units to concrete paths. -- Treats unresolved U -> path mapping as a context gap instead of widening execution to repository-wide or broad module scope. - -Planning capabilities: - -- Wraps `/speckit.plan` to run Phase 0 preflight, Phase 0 behavior projection, and optional/contextual design artifacts when useful. -- Requires `/speckit.plan` to read project Architecture before writing and to preserve its decisions in `research.md`, concepts in `data-model.md`, boundaries in `contracts/`, and constraints or gaps in `plan.md` and `quickstart.md`. -- Stops planning and returns to `/speckit.constitution` when a feature conflicts with or requires changing project Architecture. -- Requires the runtime Planning Readiness aggregate to pass before planning; - no `planning-readiness.md` is generated. -- Treats Phase 0 preflight failures as report-only/no-write failures. -- Writes `behavior/bdd.draft.feature`, `behavior/behavior-scenarios.draft.json`, `behavior/uif.intent.json`, and `behavior/data-fixtures.intent.json` during Phase 0 behavior projection. -- Projects Required case coverage into `behavior/behavior-scenarios.draft.json` instead of allowing Required cases to disappear behind positive-only drafts. -- Consumes Phase 0 behavior drafts and must formalize them into - `contracts/bdd/`, `contracts/uif/`, and `contracts/behavior/` after the - multi-domain Planning Readiness aggregate passes. -- Requires failure scenarios in `contracts/behavior/` to carry an explicit trigger, case kind, error code, failure feedback, and state invariant, rollback, or compensation assertion reference. -- Records `N/A or blocker` and `case_coverage_blockers` when behavior drafts cannot be formalized. -- Keeps `plan.md` focused on technical decisions and navigation. -- Adds plan-template navigation to the core plan output. -- Stores internal object design in `class-diagram.md`. -- Stores service, command, event, async, retry, rollback, and failure-path flows in `contracts/sequences.md`. -- Records validation decisions in `research.md` and validation paths in `quickstart.md`. -- Generates `behavior/behavior-testability.md` at BDD Plan closeout with a Task - Derivation Matrix and READY/BLOCKED status. -- When visual requirements are in scope, research.md carries forward visual/IR source refs, readiness inputs, accepted exceptions, related contract paths, and unresolved blockers; contracts formalize visual interaction and state constraints; contracts/sequences.md records visual state flow only when it affects cross-boundary sequencing. -- For visual restoration work, visual SSOT refs carry requirement traceability while Client Asset Contract entries carry local asset binding expectations. -- Keeps product requirements in `spec.md`, domain facts in `data-model.md`, interface schemas in `contracts/`, and executable validation guidance in `quickstart.md`. - -Task generation capabilities: - -- Wraps `/speckit.tasks` so task generation requires READY - `behavior/behavior-testability.md` and consumes its Case mappings. -- Uses formal BDD, UIF, and behavior contracts to derive test-first fixture, acceptance test, implementation, and verification tasks. -- Treats missing Required failure behavior scenarios as blockers instead of generating complete-looking happy-path-only tasks. -- Performs test strategy derivation from BDD contracts, Expected UIF contracts, behavior contracts, interface contracts, `research.md`, and `quickstart.md` without writing a separate strategy artifact. -- Derives paired UI implementation and acceptance tasks when UIF contracts, Visual Fidelity Readiness rows, visual acceptance requirements, or Client Asset Contract entries apply. -- Preserves visual/IR traceability refs on UI implementation, asset binding, and non-visual acceptance tasks without generating visual validation, screenshot comparison, visual diff, baseline capture, or final visual review work. -- Uses design artifacts to derive implementation, integration, orchestration, failure-handling, and validation tasks. -- Adds Final Code Review tasks for boundary, interface contract, visual, data side-effect, behavior contract, sequence consistency, and asset binding scopes when applicable. -- Preserves the existing checklist format and user-story organization. - -Analysis capabilities: - -- Wraps `/speckit.analyze` to check vertical consistency from `spec.md` through BDD/UIF intent, formal contracts, and `tasks.md`. -- Checks that user stories, Given/When/Then steps, UIF API calls, behavior contracts, tasks, and quickstart validation paths remain traceable. -- Adds case coverage checks so Required case types remain traceable through behavior drafts, formal contracts, tasks, and quickstart validation paths. -- Treats UIF as a requirement behavior projection, formalized during planning as Expected UIF contracts. - -Implementation capabilities: - -- Replaces `/speckit.implement` with an agent-native handoff orchestration command. -- Uses Core Agent mode to own lifecycle state, create the context index, assemble the final manifest, dispatch Worker Agent runs, review receipts, update `tasks.md`, and run integration verification. -- Uses Vertical Planner Agent mode to plan one `vertical_capability`, produce shard plans, create handoff drafts, create context digest drafts, and derive allowed paths. -- Uses Worker Agent mode to execute exactly one `speckit.implement.handoff.v2` handoff. -- Writes `handoff-manifest.json`, one handoff JSON, one context digest, a context index, and one worker receipt per shard. -- Defines deterministic shard, context digest, and allowed path derivation rules. -- Uses the cross-agent protocol profile `speckit.implement.persistent_handoff_orchestration`; `/speckit.plan`, `/speckit.tasks`, and `/speckit.analyze` use their own stage-local profiles without inheriting implement execution permissions. -- Keeps manifest, handoff, and receipt JSON contracts in standalone schema files. -- Splits implement gates into manifest structure, handoff structure, dispatch readiness, receipt structure, and commit readiness validation. -- Requires behavior-linked `validation_evidence` in worker receipts when behavior contracts are in handoff context. -- Requires Final Code Review receipts to include post-implementation data side-effect review, visual consistency review, and asset binding review of actual implementation diffs before task status commit when those scopes apply. -- Requires Final Code Review receipts to reconcile implemented UI states, viewport behavior, visual/IR traceability refs, and Client Asset Contract bindings when UI or asset scopes apply. -- Assigns every handoff a lifecycle stage and vertical capability such as `domain-model`, `api-contract`, `persistence`, `service-flow`, `ui`, `test-validation`, `documentation`, `integration`, or `cleanup`. -- Supports direct single-shard execution with `Use handoff JSON `. -- Blocks worker execution when generated context has unresolved `context_gaps`. -- Commits completed task statuses from `speckit.implement.receipt.v1` receipts so the Core Agent is the only `tasks.md` writer. - -Context-load controls: - -- `context-index.json` records the available planning and implementation context without requiring every worker to read every source document. -- Context digests include only assigned task text, relevant headings, referenced sections, applicable `class-diagram.md` or `contracts/sequences.md` constraints, relevant `research.md` validation decisions, and relevant `quickstart.md` validation paths. -- `context_gaps` are explicit blockers. A Worker Agent stops instead of guessing or expanding into full `spec.md`, `plan.md`, `research.md`, `contracts/`, `class-diagram.md`, or `quickstart.md`. -- `allowed_read_paths` and `allowed_write_paths` make each handoff auditable and prevent broad implementation runs from silently crossing capability boundaries. -- Worker receipts separate execution evidence from task status commits, so the Core Agent can review validation evidence before updating `tasks.md`. -- Final Code Review analyzes implementation data side effects after Worker Agents finish and before task status commit. -- When isolated subagents are unavailable, Core Agent writes the manifest and handoffs, then reports a `Manual Worker Queue` of `/speckit.implement Use handoff JSON ` entries in dispatch order. - -## Workflow - -1. `/speckit.constitution` confirms greenfield, brownfield, or amendment inputs, then maintains separate Constitution and project Architecture files. -2. `/speckit.specify` keeps the core requirements output in `spec.md`. -3. `/speckit.clarify` resolves requirement ambiguity in `spec.md`. -4. `/speckit.checklist` evaluates requirements, behavior, UX, security, NFR, - and visual readiness directly from `spec.md`; `/speckit.clarify` repairs - product-decision blockers and re-evaluates affected gates. -5. `/speckit.plan` reads project Architecture, applies Change Scope Granularity, runs Phase 0 preflight, performs Phase 0 behavior projection, formalizes behavior drafts into contracts, and adds design artifacts when they help implementation. -6. `/speckit.tasks` reads the core plan outputs, optional design artifacts, behavior contracts, interface contracts, `research.md`, and `quickstart.md`, then produces executable tasks with inline test level, data strategy, visual/IR traceability refs, asset binding, non-visual acceptance, and evidence requirements. -7. `/speckit.analyze` checks vertical consistency across requirements, behavior drafts, contracts, and tasks. -8. `/speckit.implement` enters Core Agent mode when no handoff path is provided. -9. The Core Agent writes `context-index.json` and dispatches one Vertical Planner Agent per active vertical capability. -10. Vertical Planner Agents produce shard plans, handoff drafts, context digest drafts, and allowed path derivations. -11. The Core Agent assembles final handoffs and writes `handoff-manifest.json`. -12. Worker Agents run only from persisted handoff JSON files and write receipts. -13. Final Code Review checks boundary, contract, visual, asset binding, sequence, implementation data side effects, and real e2e readiness. -14. The Core Agent reviews receipts, updates `tasks.md`, runs integration verification, and reports closeout status. - -## Non-Goals - -- It does not make every feature produce large diagrams or test matrices. -- It does not move product requirements out of `spec.md`. -- It does not move API or message schemas out of `contracts/`. -- It does not replace `data-model.md`, `research.md`, or `quickstart.md`. -- It does not generate 4+1, UML, C4, PoC code, or Architecture-consumption audit artifacts. -- It does not treat `uc.md` or any discovered conventional path as an automatic Constitution-stage input. -- It does not infer UIF from built code; UIF remains a requirement and planning contract. -- It does not provide a Python orchestration script, workflow shell runner, or integration adapter layer. -- It does not allow Worker Agents to freely expand context by reading full planning documents when the digest is insufficient. +`workflow-preset` extends Spec Kit with Constitution-managed project +Architecture, behavior-first requirements and planning, UI/UX delivery +contracts, and an execution-ready task mapping. -## Install - -Release install: - -```bash -specify preset add workflow-preset --from https://github.com/bigsmartben/spec-kit-workflow-preset/releases/download/v2.0.0/spec-kit-workflow-preset-v2.0.0.zip -``` +It deliberately does **not** provide `speckit.implement`. After installation, +`/speckit.implement` always resolves to the implementation command supplied by +the currently installed Spec Kit core. -Local development install: +## Ownership Model -```bash -specify preset add --dev /path/to/workflow-preset -``` - -## Usage +| Stage | What this preset adds | Primary output | +|---|---|---| +| Specify | behavior, visual, and UI/UX requirement ownership | `spec.md` | +| Checklist | requirement-domain readiness gates | `checklists/*.md` | +| Plan | Architecture consumption, BDD/UIF contracts, validation design | `plan.md`, `research.md`, `quickstart.md`, `contracts/`, behavior artifacts | +| Tasks | mapping of upstream artifacts to ordered implementation, validation, e2e, and review work | `tasks.md` | +| Implement | no preset override; standard core behavior | execution of `tasks.md` | -Run the behavior-first workflow: +The lifecycle is: ```text -/speckit.constitution -/speckit.specify -/speckit.clarify -/speckit.checklist -/speckit.plan -/speckit.tasks -/speckit.analyze +spec requirements and UI/UX intent + -> requirement readiness gates + -> plan, behavior/UI contracts, and validation design + -> tasks.md execution checklist + -> standard core implement ``` -At `/speckit.constitution`, identify the mode and selected inputs. For example: - -```text -/speckit.constitution Brownfield amendment. Use the existing constitution, -docs/platform-boundaries.md, and repository configuration under services/api/ -as authorized evidence. Exclude Git history. Update both Constitution and Architecture. -``` - -### External Intake And Visual SSOT - -Source capture and provider-specific intake are owned by the separate `spec-kit-intake` -extension. Install or run that extension when PRD, design, provider design, rendered HTML, -or test-case evidence must be captured or validated before this preset projects -requirements. - -```text -external intake evidence + visual SSOT refs + HTML SSOT refs + structured IR refs -> /speckit.specify -> baseline spec.md -``` - -`/speckit.specify` does not perform intake, call provider tools, parse HTML SSOT bundles, re-parse structured IR artifacts, or decide provider source readiness. It consumes confirmed source-backed facts and preserves visual SSOT refs, HTML SSOT refs, structured IR refs, evidence refs, state/viewport refs, -screenshots, visual proof refs, and Client Asset Contract facts in `spec.md`. -Missing product decisions become `[NEEDS CLARIFICATION]`; missing provider or intake evidence for a feature that depends on that evidence becomes `[BLOCKED: PROVIDER_EVIDENCE]`; features that do not depend on HTML SSOT, structured IR, or provider evidence are `Not Applicable`. - -### Provider Evidence Refs - -Screenshots, visual proof refs, HTML SSOT refs, structured IR refs, and provider artifacts are evidence refs, not intake execution. This preset only references them through `spec.md` visual requirements and the Visual Fidelity Evidence Matrix. +## Commands -Evidence refs can support layout, density, state, viewport, asset, and visual facts when source-backed. They cannot upgrade product semantics such as permissions, business effects, validation rules, or data ownership into confirmed requirements. +The preset packages seven command wrappers: -The Visual Fidelity Evidence Matrix is the single visual readiness record. It records requirement status, source refs, HTML SSOT refs, structured IR refs, other evidence refs, provider blocker status, accepted exception refs, Gate Status, and Blocking Items. It does not define visual validation work, screenshot comparison, visual diff, baseline capture, or final visual review. +1. `/speckit.specify` +2. `/speckit.clarify` +3. `/speckit.checklist` +4. `/speckit.constitution` +5. `/speckit.plan` +6. `/speckit.tasks` +7. `/speckit.analyze` -### Provider Design And HTML SSOT Input +`speckit.implement` is intentionally absent from `preset.yml` and `commands/`. +This prevents the preset from freezing or shadowing a core implementation +command. -Use the `spec-kit-intake` extension for provider design, HTML SSOT, or structured IR capture: +## UI/UX From Specify -```text -/speckit.intake.visual-design -/speckit.intake.figma2htmlssot -``` - -The intake extension owns source capture, provider evidence, raw provider metadata, -node inventory parity, rendered HTML visual SSOT bundles, structured IR artifacts, -source-side readiness, and blocker codes. This preset consumes only the confirmed -artifact refs, readiness inputs, blocker status, and traceability refs written or cited in `spec.md`. +UI/UX is a requirement concern before it is an implementation concern. +`/speckit.specify` records applicable visual and interaction needs in +`spec.md`, including states, viewport behavior, source/evidence refs, and Client +Asset Contract expectations. `/speckit.checklist` decides whether those +requirements are ready for planning. -Then run agent-native orchestrated implementation: - -```text -/speckit.implement -``` +External provider capture stays outside the preset. Confirmed visual SSOT refs, +HTML SSOT refs, structured IR refs, screenshots, and visual proof refs may be +consumed after an intake extension has projected them into the specification. +Missing provider evidence remains an intake blocker; it is not converted into a +product clarification. -Run a single worker handoff directly: +Example: ```text -/speckit.implement Use handoff JSON specs/001-demo/handoffs/implement//S01-service-flow-01.json +Requirement: Checkout shows loading, success, validation-error, and +payment-declined states at desktop and mobile viewports. ``` -## Files Written - -The core governance and planning workflow still owns its normal artifacts: - -- `.specify/memory/constitution.md` -- `.specify/memory/architecture.md` -- `specs//plan.md` -- `specs//research.md` -- `specs//data-model.md` -- `specs//contracts/` -- `specs//quickstart.md` -- `specs//tasks.md` - -This preset adds requirement-stage checklist artifacts: - -- `specs//checklists/behavior.md` -- `specs//checklists/ux.md` -- `specs//checklists/security.md` -- `specs//checklists/nfr.md` -- `specs//checklists/visual.md` - -Source intake artifacts and provider artifact instances are written by -`spec-kit-intake` or another external intake extension. This preset consumes the -qualified evidence refs from `spec.md` after `/speckit.specify` writes confirmed -requirements or records `[BLOCKED: PROVIDER_EVIDENCE]`; it does not define or -generate the artifact instances. Provider evidence blockers do not become -`[NEEDS CLARIFICATION]`. - -This preset adds Phase 0 behavior artifacts: - -- `specs//behavior/bdd.draft.feature` -- `specs//behavior/behavior-scenarios.draft.json` -- `specs//behavior/uif.intent.json` -- `specs//behavior/data-fixtures.intent.json` - -This preset adds planning-phase formal behavior contracts: - -- `specs//contracts/bdd/` -- `specs//contracts/uif/` -- `specs//contracts/behavior/` - -This preset adds the plan-stage task-readiness artifact: - -- `specs//behavior/behavior-testability.md` +The Visual Fidelity Evidence Matrix in `checklists/visual.md` records the +planning-readiness status of that requirement. It does not define screenshot +comparison, visual diff, baseline capture, or final visual review work. -This preset adds optional/contextual planning artifacts: +## Validation Design From Plan -- `specs//class-diagram.md` -- `specs//contracts/sequences.md` +`/speckit.plan` consumes checklist-approved requirements and creates the +technical and validation contracts required for task derivation: -Agent-native handoff orchestration writes implementation artifacts: +- `research.md` records validation decisions, test levels, fixture strategy, + and external-system strategy. +- `quickstart.md` records executable validation paths and real-system + integration/e2e scenarios. +- `behavior/bdd.draft.feature`, `behavior/uif.intent.json`, and + `behavior/data-fixtures.intent.json` provide Phase 0 projections. +- `contracts/bdd/`, `contracts/uif/`, and `contracts/behavior/` contain formal + behavior contracts. +- `behavior/behavior-testability.md` closes the BDD Plan with a READY or + BLOCKED decision. +- `class-diagram.md` and `contracts/sequences.md` are optional contextual design + artifacts. -- `specs//handoffs/implement//handoff-manifest.json` -- `specs//handoffs/implement//planner-outputs/` -- `specs//handoffs/implement//*.json` -- `specs//handoffs/implement//*.context.md` -- `specs//handoffs/implement//context-index.json` -- `specs//handoffs/implement//results/*.json` +This is broader than unit testing. Applicable plans cover unit, contract, +integration, UI acceptance, and real-system e2e validation. -Contract files packaged by the preset: +Example: -- `schemas/speckit.behavior.scenarios.draft.v1.schema.json` -- `schemas/speckit.behavior.uif.intent.v1.schema.json` -- `schemas/speckit.behavior.data-fixtures.intent.v1.schema.json` -- `schemas/speckit.behavior.uif.expected.v1.schema.json` -- `schemas/speckit.behavior.scenario-instances.v1.schema.json` -- `schemas/speckit.behavior.data-fixtures.v1.schema.json` -- `schemas/speckit.behavior.assertions.v1.schema.json` -- `schemas/speckit.implement.manifest.v1.schema.json` -- `schemas/speckit.implement.handoff.v2.schema.json` -- `schemas/speckit.implement.receipt.v1.schema.json` - -Governance templates packaged by the preset: - -- `templates/constitution-template.md` -- `templates/architecture-template.md` - -Packaged contract validators: - -- `validators/speckit_implement_contract.py` - -Source intake templates, provider design contracts, visual requirements schemas, HTML SSOT bundle contracts, structured IR contracts, and source-side validators live in the `spec-kit-intake` extension. - -## Artifact Roles - -`.specify/memory/architecture.md` is the project-level Architecture source for planning. It contains exactly Architecture Overview, System Boundary, Conceptual Model, Technical Decisions & Evidence, and Planning Guardrails & Gaps. Optional tables may be empty; an explicit Architecture goal, authorized source list, and owned boundary are required. For example, a payment boundary may own payment authorization but explicitly not own order fulfillment; feature `contracts/` must preserve that responsibility and dependency direction. - -`checklists/behavior.md` owns observable behavior and the Case Coverage Matrix; -`checklists/nfr.md` owns product-level non-functional readiness; and -`checklists/visual.md` owns the single Visual Fidelity Evidence Matrix. -Together with requirements, UX, and security gates they produce the runtime -Planning Readiness aggregate. Missing product decisions return to clarify; -provider evidence remains an intake blocker. - -`behavior/bdd.draft.feature` captures Phase 0 behavior projection in readable Given/When/Then form. `behavior/behavior-scenarios.draft.json`, `behavior/uif.intent.json`, and `behavior/data-fixtures.intent.json` make the same draft behavior machine-readable enough for planning formalization. - -`contracts/bdd/`, `contracts/uif/`, and `contracts/behavior/` contain planning-phase formal behavior contracts. They are generated from Phase 0 drafts after planning has resolved fixture strategy, data model, interface contracts, and validation paths, unless planning records `N/A or blocker` for missing planning input. `contracts/behavior/scenario-instances.json` carries `case_coverage_blockers` for Required cases that cannot be formalized. Failure scenarios must be structured enough to constrain implementation, including error code, failure feedback, and state invariant, rollback, or compensation assertion references. - -`behavior/behavior-testability.md` is generated at plan closeout. It maps every -Required Case to its Scenario, BDD/UIF contract, fixture, assertion, validation -level, research decision, quickstart path, and visual/NFR refs. `/speckit.tasks` -stops unless this artifact is current and READY. - -`class-diagram.md` captures internal implementation object structure: classes, interfaces, abstract types, composition, dependencies, references, and design pattern participants. It is the object design map that helps implementation preserve boundaries between services, adapters, repositories, strategies, factories, controllers, coordinators, and extension points. - -`contracts/sequences.md` captures service-call, command, event, external-system, retry, rollback, compensation, async, and failure-path sequencing. It is the flow design map that helps implementation preserve call order, service boundaries, async behavior, idempotency, compensation, and error propagation. Sequences always live at this path, even when there are no other contract files. - -For visual planning, research.md carries forward visual/IR source refs, readiness inputs, accepted exception refs, unresolved blocker refs, related contracts, and quickstart paths. contracts formalize visual interaction and state constraints by linking accepted visual items to Expected UIF, behavior scenarios, assertions, and supporting API/data schemas. contracts/sequences.md records visual state flow only when it affects cross-boundary sequencing, async results, retries, rollback, compensation, or error propagation; it does not redefine layout, tokens, screenshot matrices, visual readiness, or visual validation strategy. - -Test strategy derivation happens during `/speckit.tasks`. The command derives unit, contract, integration, and end-to-end validation work from BDD contracts, Expected UIF contracts, behavior contracts, interface contracts, `research.md`, and `quickstart.md`, then writes the strategy inline on the relevant `tasks.md` checklist items. It also defines UI implementation, non-visual acceptance, contract validation, data-side-effect validation, integration/e2e validation, and scope-aware code review tasks in `tasks.md`; `/speckit.implement` executes those tasks and records receipt evidence without inventing validation strategy, changing requirements, updating contracts, or widening scope. - -The handoff context digest includes relevant design constraints, visual fidelity requirements, visual SSOT refs, HTML SSOT refs, structured IR refs, external evidence refs, readiness inputs, quickstart paths, and behavior contracts when present, so Worker Agents can preserve object boundaries, service flows, visual intent, and validation intent without reading full planning documents by default. - -See `commands/speckit.implement.md` for runtime handoff orchestration rules, and `schemas/` plus `validators/speckit_implement_contract.py` for the machine-checked manifest, handoff, receipt, dispatch, and commit contracts. - -## Agent Topology - -The Core Agent is the lifecycle orchestrator. It owns context indexing, manifest assembly, worker dispatch, receipt review, task status commit, integration verification, and closeout. It does not directly produce shard plans or context digest drafts. +```text +quickstart.md: a buyer submits a refund against a sandbox payment service and +observes the persisted refund plus the user-visible confirmation state. +``` -Vertical Planner Agent runs are planners. A Vertical Planner Agent handles one `vertical_capability`, produces shard plans, handoff drafts, context digest drafts, and allowed path derivations, and does not execute implementation, write the final manifest, dispatch workers, or edit `tasks.md`. +That path is a source for integration/e2e tasks, not an implementation detail +invented later by Tasks or Implement. -Worker Agent runs are executors. A Worker Agent handles one persisted handoff, writes only `allowed_write_paths`, does not edit `tasks.md`, does not dispatch additional workers, and writes a `speckit.implement.receipt.v1` receipt. +## Tasks Is A Mapping Stage -Worker mode rejects handoff paths that do not exist or are not listed in `handoff-manifest.json`. +`/speckit.tasks` produces only `tasks.md`. It maps upstream deliverables into +the core checklist format and user-story organization. -Only Vertical Planner Agents may produce shard plans and digest drafts. +For each applicable story, it derives: -Only Core Agent may write final `handoff-manifest.json` and commit `tasks.md`. +- fixtures and environment setup; +- unit and contract validation; +- UI implementation and UI acceptance; +- implementation work; +- data-side-effect validation; +- integration and real-system e2e validation; +- evidence collection and blocker reporting. -Only Worker Agents may execute implementation handoffs. +Task text binds the work to concrete source, test, fixture, configuration, and +asset paths plus upstream scenario, contract, visual/IR, or quickstart refs. +Tasks does not create a second plan, execution manifest, transfer file, worker +result file, write-path protocol, or execution queue. -## Lifecycle +Example mapping: -Core Agent mode proceeds through these stages: +| Upstream product | `tasks.md` result | +|---|---| +| `SCN-ERR-001` permission failure | fixture + BDD/contract test + implementation + evidence tasks | +| Expected UIF submit event and error feedback | UI implementation + UI acceptance tasks | +| `quickstart.md` sandbox refund path | integration/e2e environment + execution + evidence tasks | +| persistence update rules | implementation + data-side-effect validation tasks | -- `intake` -- `context_indexing` -- `vertical_planning` -- `manifest_assembly` -- `worker_dispatch` -- `worker_execution` -- `receipt_review` -- `code_review` -- `task_commit` -- `integration_verification` -- `closeout` +## Mandatory Final Code Review -Every worker handoff records its `lifecycle_stage`, `vertical_capability`, `agent_topology`, `capability_boundary`, `planner_outputs`, and `draft_source`. +Tasks appends **Final Code Review** after all user-story, integration, and +validation work. It is a mandatory final phase in `tasks.md`, so the standard +core implementation command executes it in normal checklist order. -## Vertical Capability +The phase includes applicable checks for: -Worker handoffs should stay inside one vertical capability: +- the planned `M + U` boundary; +- interface and behavior contracts; +- implemented UI states and viewport behavior; +- visual/IR traceability refs and Client Asset Contract bindings; +- field-level and runtime data side effects; +- cross-boundary sequence consistency; +- integration/e2e evidence and unresolved blockers. -- `domain-model` -- `api-contract` -- `persistence` -- `service-flow` -- `ui` -- `cli` -- `test-validation` -- `documentation` -- `integration` -- `cleanup` +Code Review is not a separate command, reviewer runtime, or orchestration +protocol. Completion means the review checklist items pass; failures remain +open tasks or explicit blockers. -When a task spans capabilities, the Core Agent should split it into dependent handoffs instead of assigning broad cross-cutting work to one Worker Agent. +## Architecture And Scope -## Safety Boundaries +`/speckit.constitution` manages separate project-level artifacts: -Planning artifacts are optional/contextual. Simple features may produce concise files or `N/A` sections with concrete reasons. The command should avoid large placeholder artifacts and should not move product requirements out of `spec.md`, interface schemas out of `contracts/`, validation decisions out of `research.md`, or quick validation instructions out of `quickstart.md`. +- `.specify/memory/constitution.md` +- `.specify/memory/architecture.md` -Vertical Planner Agents may read only the planning artifacts required to produce their capability-local shard plan and digest drafts. Worker Agents should treat the final handoff JSON and its digest as the primary context. They should not read full `spec.md`, `plan.md`, `research.md`, `contracts/`, `class-diagram.md`, or `quickstart.md` by default. If the digest contains `context_gaps`, the Worker Agent must stop instead of expanding context on its own. +The Architecture follows the System Boundary -> Conceptual Model -> Technical +Decisions & Evidence -> Planning Guardrails & Gaps chain. -Completed `[x]` tasks are not scheduled into new implementation handoffs. +Change Scope Granularity uses the fixed R/M/U/O model: R is Repository / Workspace, M is Module / Capability, U is Unit / Design Object, and O is Operation / Detail. Planning locks `M + U`; Tasks maps those design objects to concrete executable paths without widening the planned boundary. -## Development +## Behavior Contracts -Runtime requirements: +The preset packages separate templates and JSON schemas for behavior drafts, +Expected UIF, scenario instances, fixtures, and assertions. +`validators/speckit_behavior_contract.py` checks cross-field relationships such +as scenario-to-fixture references, exception-case structure, Expected UIF +steps, and required-case coverage. -- Spec Kit CLI `>=0.12.7.dev0` -- An agent environment capable of running `/speckit.implement` in Core Agent, Vertical Planner Agent, and Worker Agent modes +The behavior validator is independent of implementation execution. There are no +implementation manifest, transfer, or worker-result schemas in this package. -Development and release tooling: - -- Python 3.10 or newer -- PyYAML and jsonschema for contract tests -- Git -- GitHub CLI `gh` for repository and release publishing +## Install -Install development test dependencies: +Development checkout: ```bash -python3 -m pip install -r requirements-dev.txt +specify preset add --dev /path/to/spec-kit-workflow-preset ``` -Run the contract tests: +Published release: ```bash -python3 -m unittest tests/test_preset_contract.py +specify preset add --from https://github.com/bigsmartben/spec-kit-workflow-preset/releases/download/v3.0.0/spec-kit-workflow-preset-v3.0.0.zip ``` -## Preset CI Boundary +After installation, resolve a preset-owned wrapper: -This repository owns preset artifact health: - -- run `tests/test_preset_contract.py`; -- build `spec-kit-workflow-preset-v.zip`; -- smoke-install this checkout on an Ubuntu GitHub runner with a `specify` CLI built from `bigsmartben/spec-kit`; -- publish or confirm the release artifact for a tag or manual release run; -- create or update a `workflow-preset-release-v` integration PR in `bigsmartben/spec-kit` on tag releases or manual runs with `create_integration_pr=true`. +```bash +specify preset resolve speckit.tasks +``` -Manual release runs default to the next patch version when `version` is omitted. For example, a `preset.yml` version of `2.0.0` defaults to release version `2.0.1`. +Resolve implementation through the normal command surface. Because the preset +does not declare it, `speckit.implement` comes from the active Spec Kit core. -The integration PR step requires a repository secret named `SPEC_KIT_FORK_PR_TOKEN` with permission to push branches and open pull requests in `bigsmartben/spec-kit`. If a tag release or manual `create_integration_pr=true` run reaches that step without the secret, the workflow fails fast instead of skipping integration PR creation. +## Release Integrity -This repository owns the release artifact and the fork integration PR. It does not open pull requests to `github/spec-kit`. The `bigsmartben/spec-kit` fork owns downstream integration validation, core workflow fixes, catalog resolver checks, and any later community catalog PR flow. +A source release is immutable. The integration fork must record: -Optional local CLI sanity check: +- source repository URL; +- release version; +- source commit SHA; +- release download URL; +- release artifact SHA-256; +- per-file hashes from the release manifest. -```bash -specify preset add --dev /path/to/workflow-preset -specify preset info workflow-preset -specify preset remove workflow-preset -``` +The fork extracts the release snapshot without edits. Bundled installation and +installation from the same release must produce identical preset files and +manifest content. Any functional change requires a new source version; a +published version is never modified in place. -Release install smoke validation is intentionally owned by GitHub Actions, not by a local WSL environment. +## Development -After tagging a release, validate archive installation: +Install test requirements and run the contract suite: ```bash -specify preset add workflow-preset --from https://github.com/bigsmartben/spec-kit-workflow-preset/releases/download/v2.0.0/spec-kit-workflow-preset-v2.0.0.zip +python3 -m pip install -r requirements-dev.txt +python3 -m unittest tests/test_preset_contract.py ``` -## Source Rationale - -See `2026-05-15-plan-design-artifacts-proposal.md` for the design artifact proposal that this preset incorporates. +Repository extension rules are in +[`docs/extension-governance.md`](docs/extension-governance.md). diff --git a/presets/workflow-preset/commands/speckit.implement.md b/presets/workflow-preset/commands/speckit.implement.md deleted file mode 100644 index 1d312a1c37..0000000000 --- a/presets/workflow-preset/commands/speckit.implement.md +++ /dev/null @@ -1,219 +0,0 @@ ---- -description: Execute the implementation plan by processing and executing all tasks defined in tasks.md -scripts: - sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks - ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks - py: scripts/python/check_prerequisites.py --json --require-tasks --include-tasks ---- - -## User Input - -```text -$ARGUMENTS -``` - -You **MUST** consider the user input before proceeding (if not empty). - -## Pre-Execution Checks - -**Check for extension hooks (before implementation)**: -- Check if `.specify/extensions.yml` exists in the project root. -- If it exists, read it and look for entries under the `hooks.before_implement` key -- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally -- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. -- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: - - If the hook has no `condition` field, or it is null/empty, treat the hook as executable - - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation -- For each executable hook, output the following based on its `optional` flag: - - **Optional hook** (`optional: true`): - ``` - ## Extension Hooks - - **Optional Pre-Hook**: {extension} - Command: `/{command}` - Description: {description} - - Prompt: {prompt} - To execute: `/{command}` - ``` - - **Mandatory hook** (`optional: false`): - ``` - ## Extension Hooks - - **Automatic Pre-Hook**: {extension} - Executing: `/{command}` - EXECUTE_COMMAND: {command} - - Wait for the result of the hook command before proceeding to the Outline. - ``` - After emitting the block above you MUST actually invoke the hook and wait for it to finish before continuing. Run it the same way you would run the command yourself in this agent/session (the invocation may differ from the literal `{command}` id shown above, e.g. a skills-mode agent runs it as `/skill:speckit-...` or `$speckit-...`). Emitting the block alone does not run the hook. -- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently - -## Outline - -1. Run `{SCRIPT}` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). - -2. **Check checklists status** (if FEATURE_DIR/checklists/ exists): - - Scan all checklist files in the checklists/ directory - - For each checklist, count: - - Total items: All lines matching `- [ ]` or `- [X]` or `- [x]` - - Completed items: Lines matching `- [X]` or `- [x]` - - Incomplete items: Lines matching `- [ ]` - - Create a status table: - - ```text - | Checklist | Total | Completed | Incomplete | Status | - |-----------|-------|-----------|------------|--------| - | ux.md | 12 | 12 | 0 | ✓ PASS | - | test.md | 8 | 5 | 3 | ✗ FAIL | - | security.md | 6 | 6 | 0 | ✓ PASS | - ``` - - - Calculate overall status: - - **PASS**: All checklists have 0 incomplete items - - **FAIL**: One or more checklists have incomplete items - - - **If any checklist is incomplete**: - - Display the table with incomplete item counts - - **STOP** and ask: "Some checklists are incomplete. Do you want to proceed with implementation anyway? (yes/no)" - - Wait for user response before continuing - - If user says "no" or "wait" or "stop", halt execution - - If user says "yes" or "proceed" or "continue", proceed to step 3 - - - **If all checklists are complete**: - - Display the table showing all checklists passed - - Automatically proceed to step 3 - -3. Load and analyze the implementation context: - - **REQUIRED**: Read tasks.md for the complete task list and execution plan - - **REQUIRED**: Read plan.md for tech stack, architecture, and file structure - - **IF EXISTS**: Read data-model.md for entities and relationships - - **IF EXISTS**: Read contracts/ for API specifications and test requirements - - **IF EXISTS**: Read research.md for technical decisions and constraints - - **IF EXISTS**: Read /memory/constitution.md for governance constraints - - **IF EXISTS**: Read quickstart.md for integration scenarios - -4. **Project Setup Verification**: - - **REQUIRED**: Create/verify ignore files based on actual project setup: - - **Detection & Creation Logic**: - - Check if the following command succeeds to determine if the repository is a git repo (create/verify .gitignore if so): - - ```sh - git rev-parse --git-dir 2>/dev/null - ``` - - - Check if Dockerfile* exists or Docker in plan.md → create/verify .dockerignore - - Check if .eslintrc* exists → create/verify .eslintignore - - Check if eslint.config.* exists → ensure the config's `ignores` entries cover required patterns - - Check if .prettierrc* exists → create/verify .prettierignore - - Check if .npmrc or package.json exists → create/verify .npmignore (if publishing) - - Check if terraform files (*.tf) exist → create/verify .terraformignore - - Check if .helmignore needed (helm charts present) → create/verify .helmignore - - **If ignore file already exists**: Verify it contains essential patterns, append missing critical patterns only - **If ignore file missing**: Create with full pattern set for detected technology - - **Common Patterns by Technology** (from plan.md tech stack): - - **Node.js/JavaScript/TypeScript**: `node_modules/`, `dist/`, `build/`, `*.log`, `.env*` - - **Python**: `__pycache__/`, `*.pyc`, `.venv/`, `venv/`, `dist/`, `*.egg-info/` - - **Java**: `target/`, `*.class`, `*.jar`, `.gradle/`, `build/` - - **C#/.NET**: `bin/`, `obj/`, `*.user`, `*.suo`, `packages/` - - **Go**: `*.exe`, `*.test`, `vendor/`, `*.out` - - **Ruby**: `.bundle/`, `log/`, `tmp/`, `*.gem`, `vendor/bundle/` - - **PHP**: `vendor/`, `*.log`, `*.cache`, `*.env` - - **Rust**: `target/`, `debug/`, `release/`, `*.rs.bk`, `*.rlib`, `*.prof*`, `.idea/`, `*.log`, `.env*` - - **Kotlin**: `build/`, `out/`, `.gradle/`, `.idea/`, `*.class`, `*.jar`, `*.iml`, `*.log`, `.env*` - - **C++**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.so`, `*.a`, `*.exe`, `*.dll`, `.idea/`, `*.log`, `.env*` - - **C**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.a`, `*.so`, `*.exe`, `*.dll`, `autom4te.cache/`, `config.status`, `config.log`, `.idea/`, `*.log`, `.env*` - - **Swift**: `.build/`, `DerivedData/`, `*.swiftpm/`, `Packages/` - - **R**: `.Rproj.user/`, `.Rhistory`, `.RData`, `.Ruserdata`, `*.Rproj`, `packrat/`, `renv/` - - **Universal**: `.DS_Store`, `Thumbs.db`, `*.tmp`, `*.swp`, `.vscode/`, `.idea/` - - **Tool-Specific Patterns**: - - **Docker**: `node_modules/`, `.git/`, `Dockerfile*`, `.dockerignore`, `*.log*`, `.env*`, `coverage/` - - **ESLint**: `node_modules/`, `dist/`, `build/`, `coverage/`, `*.min.js` - - **Prettier**: `node_modules/`, `dist/`, `build/`, `coverage/`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` - - **Terraform**: `.terraform/`, `*.tfstate*`, `*.tfvars`, `.terraform.lock.hcl` - - **Kubernetes/k8s**: `*.secret.yaml`, `secrets/`, `.kube/`, `kubeconfig*`, `*.key`, `*.crt` - -5. Parse tasks.md structure and extract: - - **Task phases**: Setup, Tests, Core, Integration, Polish - - **Task dependencies**: Sequential vs parallel execution rules - - **Task details**: ID, description, file paths, parallel markers [P] - - **Execution flow**: Order and dependency requirements - -6. Execute implementation following the task plan: - - **Phase-by-phase execution**: Complete each phase before moving to the next - - **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together - - **Follow TDD approach**: Execute test tasks before their corresponding implementation tasks - - **File-based coordination**: Tasks affecting the same files must run sequentially - - **Validation checkpoints**: Verify each phase completion before proceeding - -7. Implementation execution rules: - - **Setup first**: Initialize project structure, dependencies, configuration - - **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios - - **Core development**: Implement models, services, CLI commands, endpoints - - **Integration work**: Database connections, middleware, logging, external services - - **Polish and validation**: Unit tests, performance optimization, documentation - -8. Progress tracking and error handling: - - Report progress after each completed task - - Halt execution if any non-parallel task fails - - For parallel tasks [P], continue with successful tasks, report failed ones - - Provide clear error messages with context for debugging - - Suggest next steps if implementation cannot proceed - - **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file. - -9. Completion validation: - - Verify all required tasks are completed - - Check that implemented features match the original specification - - Validate that tests pass and coverage meets requirements - - Confirm the implementation follows the technical plan - -Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `__SPECKIT_COMMAND_TASKS__` first to regenerate the task list. - -## Mandatory Post-Execution Hooks - -**You MUST complete this section before reporting completion to the user.** - -Check if `.specify/extensions.yml` exists in the project root. -- If it does not exist, or no hooks are registered under `hooks.after_implement`, skip to the Completion Report. -- If it exists, read it and look for entries under the `hooks.after_implement` key. -- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue to the Completion Report. -- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. -- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: - - If the hook has no `condition` field, or it is null/empty, treat the hook as executable - - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation -- For each executable hook, output the following based on its `optional` flag: - - **Mandatory hook** (`optional: false`) — **You MUST emit `EXECUTE_COMMAND:` for each mandatory hook**: - ``` - ## Extension Hooks - - **Automatic Hook**: {extension} - Executing: `/{command}` - EXECUTE_COMMAND: {command} - ``` - After emitting the block above you MUST actually invoke the hook and wait for it to finish before continuing. Run it the same way you would run the command yourself in this agent/session (the invocation may differ from the literal `{command}` id shown above, e.g. a skills-mode agent runs it as `/skill:speckit-...` or `$speckit-...`). Emitting the block alone does not run the hook. - - **Optional hook** (`optional: true`): - ``` - ## Extension Hooks - - **Optional Hook**: {extension} - Command: `/{command}` - Description: {description} - - Prompt: {prompt} - To execute: `/{command}` - ``` - -## Completion Report - -Report final status with summary of completed work. - -## Done When - -- [ ] All tasks in tasks.md completed and marked `[X]` -- [ ] Implementation validated against specification, plan, and test coverage -- [ ] Extension hooks dispatched or skipped according to the rules in Mandatory Post-Execution Hooks above -- [ ] Completion reported to user with summary of completed work diff --git a/presets/workflow-preset/docs/extension-governance.md b/presets/workflow-preset/docs/extension-governance.md index 37c349569b..ac1281e13c 100644 --- a/presets/workflow-preset/docs/extension-governance.md +++ b/presets/workflow-preset/docs/extension-governance.md @@ -1,172 +1,158 @@ # Preset Extension Governance -This document is the repository-level rule set for extending `workflow-preset`. -It exists to keep preset changes aligned with Spec Kit's preset model and this -repository's contract tests. + +This document defines the ownership boundaries for `workflow-preset`. ## Source Of Truth -- `preset.yml` declares every packaged command, template, schema, and script. -- `commands/` contains stage-local LLM instructions. + +- `preset.yml` declares every packaged command, template, and schema. +- `commands/` contains stage-local instructions. - `templates/` contains stable artifact shapes. -- `schemas/` contains machine-readable JSON contracts. -- `validators/` contains pure in-memory cross-field contract checks. -- `tests/test_preset_contract.py` is the executable contract for this preset. - -## Preset Boundaries - -Presets customize existing Spec Kit workflows by overriding or composing -commands, templates, and scripts. Use extensions, not presets, for new tooling, -external integrations, static analyzers, workflow runners, or commands that add -a new capability outside the existing Spec Kit workflow. - -Do not reintroduce Python orchestration, workflow shell dispatch, integration -adapter scripts, or worker dispatch from scripts. - -Source intake artifacts belong in an extension, not this preset. External intake owns source capture, provider evidence, provider metadata, rendered HTML SSOT bundles, structured IR artifacts, -source-side readiness, and blocker codes. This preset may consume confirmed -external intake artifact refs, visual SSOT refs, HTML SSOT refs, structured IR refs, -source refs, coverage gaps, readiness inputs, accepted exception refs, and provider blockers already cited in `spec.md`. -External evidence refs are consumed as source, readiness, blocker, and traceability inputs only. Provider tools, provider execution, hooks, adapter scripts, -and authentication are external integration concerns and remain outside this -preset. - -## Template And Command Ownership - -- templates own stable artifact shapes. -- commands own stage-local generation instructions. -- Commands may name the inputs they consume, the outputs they write, and the - local update rules for their own phase. -- An upstream stage may define the explicit consumption contract for its direct - standard SDD downstream stage when both stages are wrapped by this preset. -- Do not encode full output structures only inside command text when the output - is intended to be durable or reused by later phases. - -Stage ownership: - -- `/speckit.constitution`: durable Constitution governance plus the separate - project-level `.specify/memory/architecture.md` lifecycle. -- `/speckit.specify`: requirement artifacts only. -- `/speckit.clarify`: product-decision clarification and affected requirement-gate recomputation only. -- `/speckit.checklist`: requirements, behavior, UX, security, NFR, and visual requirement gates only. -- `/speckit.plan`: Architecture-guided planning, Phase 0 behavior projection, - planning artifacts, formal contracts, and BDD Plan closeout. -- `/speckit.tasks`: `tasks.md` only. -- `/speckit.analyze`: vertical consistency checks across requirements, behavior drafts, contracts, and tasks only. -- `/speckit.implement`: implementation handoff execution only. - -`/speckit.tasks` owns implementation, non-visual acceptance, contract validation, data-side-effect validation, integration/e2e validation, and code review task definition in `tasks.md`. `/speckit.implement` may execute those tasks and record receipt evidence, but it must not invent validation strategy, visual validation work, lifecycle roles, requirements, contract updates, or wider scope during execution. - -When external intake evidence or visual SSOT refs have already been projected into `spec.md`, `/speckit.clarify` may clarify those requirement gaps from `spec.md`, but extraction remains outside clarification. -External design extraction is not a clarification responsibility. - -Visual Fidelity readiness applies to external-intake-derived and product-side -visual requirements. `checklists/visual.md` and its Visual Fidelity Evidence -Matrix are the single visual requirement-readiness record. Provider evidence -gaps remain intake blockers. The matrix must not define visual validation work, -screenshot comparison, visual diff, baseline capture, or final visual review. +- `schemas/` contains machine-readable behavior contracts. +- `validators/speckit_behavior_contract.py` contains pure in-memory behavior + cross-field checks. +- `tests/test_preset_contract.py` is the executable preset contract. + +## Preset Boundary + +The preset enriches existing Spec Kit stages. It does not own execution +orchestration or add a second implementation engine. + +| Stage | Owner | Durable output | +|---|---|---| +| `/speckit.constitution` | preset wrapper | Constitution and project Architecture | +| `/speckit.specify` | preset wrapper | requirement and UI/UX intent in `spec.md` | +| `/speckit.clarify` | preset wrapper | clarified requirement decisions | +| `/speckit.checklist` | preset wrapper | requirement-readiness gates | +| `/speckit.plan` | preset wrapper | design, behavior contracts, and validation design | +| `/speckit.tasks` | preset wrapper | executable checklist in `tasks.md` | +| `/speckit.analyze` | preset wrapper | read-only consistency findings | +| `/speckit.implement` | Spec Kit core | execution of `tasks.md` | + +`workflow-preset` MUST NOT declare, package, copy, or replace +`speckit.implement`. The active Spec Kit core version is the single source of +truth for the implementation command. A core implementation change therefore +requires no preset release. + +The preset MUST NOT introduce an implementation-specific reviewer command, +runtime role, persistent transfer protocol, execution manifest, worker result +protocol, manual execution queue, or implementation validator. + +## Artifact Pipeline + +The workflow is a producer-to-consumer pipeline: + +```text +spec.md + requirement gates + -> plan artifacts + BDD/UIF/validation design + -> tasks.md implementation and validation checklist + -> core /speckit.implement execution +``` -## Structured Artifact Rules +Tasks maps upstream artifacts into checklist items. It must not create another +planning system or execution protocol. -Machine-readable JSON artifacts are contracts, not prose examples. Stable -structured JSON artifacts require schemas in `schemas/` and focused validator -coverage in `validators/` when cross-field rules matter. +Examples: -Every schema or validator added for a preset artifact must be covered by -`tests/test_preset_contract.py`. +- A UI state in `spec.md` and `contracts/uif/` becomes a concrete UI + implementation task plus a UI acceptance task. +- A real-system path in `quickstart.md` becomes an integration/e2e task with + environment and evidence expectations. +- A persistence change becomes implementation and data-side-effect validation + tasks, followed by the final review scope. -## Cross-Agent Protocol Rules +## Final Code Review Gate -Shared multi-agent runtime behavior belongs in command source, schemas, and validators. -Test coverage for shared multi-agent behavior belongs in `tests/contracts/speckit-cross-agent-protocol.md`. -Commands may reference only their own profile. A profile inherits scheduling -protocol fields, not execution permissions from another command. -Commands must not reference `tests/` or `docs/` paths as runtime contract sources. +`/speckit.tasks` MUST append Final Code Review as the last mandatory phase of +`tasks.md`. It is an ordinary ordered task phase executed by the standard core +implementation command, not an independent runtime. -Persistent handoff orchestration belongs only to `/speckit.implement`. -Manifest files, handoff files, receipts, `allowed_write_paths`, dispatch -readiness, commit readiness, and manual worker queues must not be introduced -into `/speckit.specify`, `/speckit.plan`, `/speckit.tasks`, or -`/speckit.analyze`. +The phase must cover each applicable scope: -The implement handoff runtime profile lives in `commands/speckit.implement.md`; -test coverage lives in `tests/contracts/speckit-cross-agent-subagents.md`. -Both must stay aligned with the implement schemas and validator gates. +- planned `M + U` boundary; +- interface contracts; +- behavior contracts; +- UI state, viewport, and visual/IR consistency; +- data side effects; +- sequence consistency; +- asset bindings; +- integration/e2e evidence and unresolved blockers. -## Behavior-first extension rule +Completion requires the review tasks themselves to pass. No separate worker +result file or orchestration layer is required. -BDD and UIF artifacts need independent templates. A behavior-first extension -must not rely only on command prose to define: +## Structured Artifact Rules -- BDD draft files. -- UIF intent files. -- data fixture intent files. -- behavior scenario draft files. -- formal BDD contracts. -- Expected UIF contracts. -- behavior scenario, fixture, and assertion contracts. +Machine-readable JSON artifacts are contracts, not prose examples. Stable +behavior JSON artifacts require schemas in `schemas/` and focused coverage in +`validators/speckit_behavior_contract.py` when cross-field rules matter. + +Every packaged schema and validator must be covered by +`tests/test_preset_contract.py`. -Phase 0 behavior drafts and planning-phase formal contracts must be separate -artifacts with separate owners. If they are JSON, they also need schemas and -validator coverage. +## Cross-Agent Rules + +Planning and task derivation may use bounded, stage-local subagents when the +runtime supports them. The owning command remains the sole final writer for its +stage. Delegation metadata is transient derivation context and must not become +an implementation transfer format. + +Shared stage-local behavior is documented in +`tests/contracts/speckit-cross-agent-protocol.md`. Commands may reference only +their own stage profile. Commands must not use `tests/` or `docs/` paths as +runtime sources. ## Planning Artifact Boundaries -Keep `/speckit.plan` and `/speckit.tasks` as core-template wrappers unless the -contract tests are intentionally updated to change that rule. +Keep `/speckit.plan` and `/speckit.tasks` as core-template wrappers unless an +intentional contract change says otherwise. -Planning design artifacts remain optional and contextual: +Optional contextual design artifacts include: - `class-diagram.md` - `contracts/sequences.md` -Validation decisions are recorded in `research.md`, executable paths in -`quickstart.md`, and the BDD Plan closeout maps them to Required Cases in -`behavior/behavior-testability.md`. `/speckit.tasks` derives concrete tasks from -that READY mapping. Do not add a standalone `test-plan.md`. - -Planning Readiness is aggregated at runtime from metadata-bearing requirement -gates. It is not a durable artifact and must never be written as -`planning-readiness.md`. +Validation decisions stay in `research.md`, executable paths stay in +`quickstart.md`, and BDD Plan closeout maps them into +`behavior/behavior-testability.md`. `/speckit.tasks` derives unit, contract, +integration, UI acceptance, real-system e2e, and review tasks from that mapping. +Do not add a standalone `test-plan.md`. -`behavior/behavior-testability.md` is a permitted planning artifact, not a test -strategy document. It contains the task-derivation matrix and READY/BLOCKED -decision; it must not duplicate requirement prose, provider intake, or -clarification. +## External Intake Boundary -Keep product requirements in `spec.md`, including explicit NFR assumptions; -NFR readiness belongs in `spec.md` product requirements rather than downstream -planning guesses. Keep domain model details in `data-model.md`, interface -schemas in `contracts/`, and validation run guidance in `quickstart.md`. +External source capture, provider access, rendered HTML, structured IR, +screenshots, authentication, and provider evidence generation belong to +extensions. This preset only consumes confirmed refs already projected into +requirements and readiness artifacts. -For visual planning, research.md records visual/IR source refs, readiness inputs, accepted exception refs, related contract paths, and unresolved blocker refs only; it must not duplicate the Visual Fidelity Evidence Matrix or define visual validation strategy, screenshot comparison, visual diff, baseline capture, or final visual review. contracts formalize visual interaction and state constraints by referencing accepted visual items, source refs, structured IR refs, and accepted exception refs; contracts/sequences.md records visual state flow only when it affects cross-boundary sequencing, async callbacks, retry, rollback, compensation, or error propagation, and must not define visual style, tokens, layout breakpoints, screenshot matrices, or validation commands. +Provider evidence gaps remain intake blockers. Product decision gaps return to +clarification. Neither planning nor implementation may silently manufacture +missing evidence. -## Handoff Extension Rules +## Release And Integration Boundary -Handoff extensions must update schema, validator, command, and cross-agent documentation together. -Any new implementation-stage artifact that Worker -Agents may read or write must be reflected in: +The source repository owns development, tests, tags, releases, and release +artifacts. The Spec Kit fork owns only a reproducible bundled snapshot and +catalog metadata. -- `schemas/speckit.implement.*.schema.json` when the JSON contract changes. -- `validators/speckit_implement_contract.py` when cross-field validation changes. -- `commands/speckit.implement.md` when Core, Vertical Planner, or Worker - behavior changes. -- `tests/contracts/speckit-cross-agent-protocol.md` when shared profile behavior changes. -- `tests/contracts/speckit-cross-agent-subagents.md` when implement worker prompts, - context digest rules, shard rules, or path rules change. -- `tests/test_preset_contract.py` for all of the above. +Integration must use an immutable release: -## Release Discipline +1. publish a new source version; +2. record the source repository, version, commit SHA, artifact URL, and artifact + SHA-256; +3. extract the bundled snapshot without edits; +4. verify every bundled file hash against the release manifest; +5. ensure bundled and `--from ` installations are identical. -Do not bump preset version or release archive URLs until release preparation. -Unreleased behavior belongs under `## Unreleased` in `CHANGELOG.md`. +Never change a published version in place or modify the bundled snapshot after +integration. -## Verification +## Validation -After changing preset commands, templates, schemas, validators, governance docs, -or public documentation, run: +Run: ```bash python3 -m unittest tests/test_preset_contract.py ``` -If the system Python lacks development dependencies, use a local virtual -environment and the same unittest command from that environment. +Release preparation must also run the install smoke checks in +`.github/workflows/preset-artifact.yml`. diff --git a/presets/workflow-preset/preset.yml b/presets/workflow-preset/preset.yml index f40d460d33..df777a9069 100644 --- a/presets/workflow-preset/preset.yml +++ b/presets/workflow-preset/preset.yml @@ -2,9 +2,9 @@ schema_version: '1.0' preset: id: workflow-preset name: Workflow Preset - version: 2.0.0 + version: 3.0.0 description: Constitution-managed architecture, behavior-first specification, design - artifacts, and scoped change governance + artifacts, and execution-ready task mapping author: bigsmartben repository: https://github.com/bigsmartben/spec-kit-workflow-preset license: MIT @@ -76,12 +76,6 @@ provides: description: Require READY behavior testability and derive complete task chains replaces: speckit.tasks strategy: wrap - - type: command - name: speckit.implement - file: commands/speckit.implement.md - description: Execute the implementation plan defined in tasks.md - replaces: speckit.implement - strategy: replace - type: template name: behavior-bdd-draft-template file: templates/behavior/bdd-draft.feature @@ -215,4 +209,3 @@ tags: - bdd - planning - implementation -- handoff diff --git a/presets/workflow-preset/tests/contracts/speckit-cross-agent-protocol.md b/presets/workflow-preset/tests/contracts/speckit-cross-agent-protocol.md index 28391cff11..a92aa3958a 100644 --- a/presets/workflow-preset/tests/contracts/speckit-cross-agent-protocol.md +++ b/presets/workflow-preset/tests/contracts/speckit-cross-agent-protocol.md @@ -1,66 +1,77 @@ # Spec Kit Cross-Agent Protocol ## Purpose -Constrain observable workflow behavior with small stage protocols instead of long global agent memory rules. The protocol constrains inputs, outputs, file access, readiness gates, stop conditions, and fallback behavior. It does not constrain internal reasoning. + +Constrain stage-local delegation without defining a second implementation +runtime. The protocol covers bounded inputs, outputs, readiness gates, stop +conditions, and sequential fallback. ## BaseSubagentProtocol -Every command profile defines these fields: - -- `stage`: command-local lifecycle stage. -- `owner_agent`: agent role that owns final writes and readiness decisions. -- `input_scope`: exact artifacts, sections, IDs, or path families assigned to the stage. -- `allowed_reads`: files, directories, or scoped excerpts the role may inspect. -- `allowed_writes`: files, directories, or artifact families the role may create or update. -- `output_contract`: draft, finding, blocker, or final artifact shape. -- `validation_gate`: schema, validator, checklist, or blocker-code gate before the next stage. -- `stop_conditions`: deterministic blockers that stop the current role. -- `fallback`: sequential simulation or manual queue behavior when delegated agents are unavailable. + +Every preset-owned command profile defines: + +- `stage` +- `owner_agent` +- `input_scope` +- `allowed_reads` +- `allowed_writes` +- `output_contract` +- `validation_gate` +- `stop_conditions` +- `fallback` ## Command Profiles ### `speckit.specify.single_core` + - `stage`: requirement projection. - `owner_agent`: Specify Core Agent. -- `input_scope`: user prompt, product notes, confirmed external intake refs, visual SSOT refs, HTML SSOT refs, structured IR refs, screenshots, and visual proof refs. -- `allowed_reads`: command inputs and existing requirement context selected by core Spec Kit behavior. - `allowed_writes`: `spec.md` only. -- `output_contract`: stakeholder-readable requirements with explicit source-backed facts, assumptions, visual/UI status, and provider blockers. -- `validation_gate`: specification quality validation in `/speckit.specify`. -- `stop_conditions`: missing feature description, unsupported inference, or provider evidence treated as product semantics. -- `fallback`: single-core execution; no persistent handoff, receipt, or worker queue. +- `output_contract`: source-aware product, behavior, visual, and UI/UX + requirements. +- `fallback`: single-core execution. ### `speckit.plan.stage_local_planning` + - `stage`: Phase 0 behavior projection and Phase 1 planning. - `owner_agent`: Plan Core Agent. -- `input_scope`: checklist-approved requirement sections, behavior readiness rows, planning inputs, and assigned artifact families. -- `allowed_reads`: scoped planning inputs declared per delegated payload. +- `input_scope`: checklist-approved requirements and assigned planning artifact + families. - `allowed_writes`: final planning artifacts owned by `/speckit.plan`. -- `output_contract`: draft behavior artifacts, formal contract drafts, design artifact drafts, blockers, and `context_gaps`. -- `validation_gate`: checklist PASS preflight, matching behavior schemas, and planning blocker report. -- `stop_conditions`: failed checklist gate, required case projection gaps, or unresolved planning `context_gaps`. -- `fallback`: Plan Core Agent sequentially simulates each assigned scope and preserves final-write ownership. +- `output_contract`: behavior drafts, formal contracts, design drafts, + validation design, blockers, and `context_gaps`. +- `validation_gate`: checklist PASS, matching behavior schemas, and planning + blocker aggregation. +- `fallback`: the Plan Core Agent processes one assigned scope at a time and + preserves final-write ownership. ### `speckit.tasks.stage_local_derivation` -- `stage`: task derivation. + +- `stage`: upstream-artifact-to-checklist mapping. - `owner_agent`: Tasks Core Agent. -- `input_scope`: user stories, behavior contracts, interface contracts, research decisions, quickstart validation paths, visual readiness rows, visual/IR traceability refs, and review scopes. -- `allowed_reads`: scoped derivation payloads; no full artifact tree unless the payload explicitly lists it. +- `input_scope`: user stories, behavior and interface contracts, research + decisions, quickstart paths, UI/visual readiness, and review scopes. +- `allowed_reads`: only the scoped inputs declared for each derivation unit. - `allowed_writes`: `tasks.md` only. -- `output_contract`: task candidates, evidence refs, source refs, blockers, and `context_gaps`. -- `validation_gate`: task-derivation blocker aggregation and existing checklist format. -- `stop_conditions`: missing Required case coverage, missing required provider evidence, or unresolved task-derivation `context_gaps`. -- `fallback`: Tasks Core Agent processes one assigned scope at a time; no handoff, receipt, write-path metadata, or worker dispatch. +- `output_contract`: ordered implementation, validation, integration/e2e, and + Final Code Review checklist items, plus blockers and `context_gaps`. +- `validation_gate`: source/evidence binding, dependency ordering, final review + placement, and blocker aggregation. +- `stop_conditions`: missing required case coverage, missing provider evidence, + or unresolved derivation context. +- `fallback`: the Tasks Core Agent processes one scope at a time. ### `speckit.analyze.read_only_parallel_review` + - `stage`: vertical consistency analysis. - `owner_agent`: Analyze Core Agent. -- `input_scope`: existing planning artifacts and stable IDs such as `CASE-`, `SCN-`, `UIF-`, `FIX-`, `AST-`, and `BLK-`. -- `allowed_reads`: bounded artifact inventory, ID maps, and surrounding prose only when an ID link is missing or ambiguous. - `allowed_writes`: none. - `output_contract`: findings, blockers, warnings, and closed-chain summary. -- `validation_gate`: read-only consistency checks by source artifact and target artifact. -- `stop_conditions`: missing source artifact, broken traceability, or first blocker that proves a downstream link cannot close. -- `fallback`: sequential read-only review; no durable artifact writes. +- `fallback`: sequential read-only review. ## Permission Boundary -Profiles inherit the scheduling protocol, not execution permissions. A command must reference only its own profile. + +Profiles share only the stage-local delegation shape. They do not grant +implementation permissions and do not define persistent execution artifacts. +The implementation command and its execution behavior are owned exclusively by +the current Spec Kit core. diff --git a/presets/workflow-preset/tests/test_preset_contract.py b/presets/workflow-preset/tests/test_preset_contract.py index 4b81e9d5fd..5ed90a29fa 100644 --- a/presets/workflow-preset/tests/test_preset_contract.py +++ b/presets/workflow-preset/tests/test_preset_contract.py @@ -30,7 +30,6 @@ ANALYZE_COMMAND_PATH = REPO_ROOT / "commands" / "speckit.analyze.md" PLAN_COMMAND_PATH = REPO_ROOT / "commands" / "speckit.plan.md" TASKS_COMMAND_PATH = REPO_ROOT / "commands" / "speckit.tasks.md" -IMPLEMENT_COMMAND_PATH = REPO_ROOT / "commands" / "speckit.implement.md" CONSTITUTION_TEMPLATE_PATH = REPO_ROOT / "templates" / "constitution-template.md" ARCHITECTURE_TEMPLATE_PATH = REPO_ROOT / "templates" / "architecture-template.md" PLAN_TEMPLATE_PATH = REPO_ROOT / "templates" / "plan-template.md" @@ -118,6 +117,14 @@ / "requirements" / "visual-gate.md", } +REMOVED_IMPLEMENT_RUNTIME_PATHS = ( + REPO_ROOT / "commands" / "speckit.implement.md", + REPO_ROOT / "schemas" / "speckit.implement.manifest.v1.schema.json", + REPO_ROOT / "schemas" / "speckit.implement.handoff.v2.schema.json", + REPO_ROOT / "schemas" / "speckit.implement.receipt.v1.schema.json", + REPO_ROOT / "validators" / "speckit_implement_contract.py", + REPO_ROOT / "tests" / "contracts" / "speckit-cross-agent-subagents.md", +) FEATURE_PATH = "specs/001-demo" @@ -316,6 +323,61 @@ def minimal_exception_behavior_assertions_with_intent(intent: str) -> dict: class PresetContractTests(unittest.TestCase): + def test_manifest_excludes_implement_override_and_runtime(self) -> None: + manifest = yaml.safe_load(PRESET_PATH.read_text(encoding="utf-8")) + entries = manifest["provides"]["templates"] + command_entries = [entry for entry in entries if entry["type"] == "command"] + template_entries = [entry for entry in entries if entry["type"] == "template"] + + self.assertEqual(7, len(command_entries)) + self.assertEqual(24, len(template_entries)) + self.assertEqual(31, len(entries)) + self.assertNotIn( + "speckit.implement", + {entry["name"] for entry in command_entries}, + ) + self.assertFalse( + any("speckit.implement" in entry["file"] for entry in entries) + ) + for path in REMOVED_IMPLEMENT_RUNTIME_PATHS: + self.assertFalse(path.exists(), path) + + def test_tasks_end_with_mandatory_code_review_without_runtime_protocol(self) -> None: + tasks = TASKS_COMMAND_PATH.read_text(encoding="utf-8") + self.assertIn("Final Code Review", tasks) + self.assertIn("append the final phase after user-story tasks", tasks) + self.assertIn( + "`boundary`, `interface_contract`, `visual`, `data_side_effect`, " + "`behavior_contract`, `sequence_consistency`, and `asset_binding`", + tasks, + ) + for forbidden in ( + "speckit.implement.handoff", + "speckit.implement.receipt", + "handoff-manifest.json", + "Manual Worker Queue", + "Reviewer runtime", + ): + self.assertNotIn(forbidden, tasks) + + def test_current_docs_define_core_implement_ownership(self) -> None: + current_docs = ( + README_PATH.read_text(encoding="utf-8"), + EXTENSION_GOVERNANCE_PATH.read_text(encoding="utf-8"), + AGENTS_PATH.read_text(encoding="utf-8"), + CROSS_AGENT_PROTOCOL_PATH.read_text(encoding="utf-8"), + ) + for document in current_docs: + self.assertIn("Spec Kit core", document) + for forbidden in ( + "speckit.implement.persistent_handoff_orchestration", + "Manual Worker Queue", + "Vertical Planner Agent", + "Worker Agent mode", + "speckit.implement.receipt.v1", + ): + self.assertNotIn(forbidden, document) + def test_requirement_gate_and_clarify_repair_contract(self) -> None: checklist = CHECKLIST_COMMAND_PATH.read_text(encoding="utf-8") clarify = CLARIFY_COMMAND_PATH.read_text(encoding="utf-8") @@ -409,16 +471,13 @@ def test_public_docs_define_two_stage_ownership(self) -> None: readme = README_PATH.read_text(encoding="utf-8") governance = EXTENSION_GOVERNANCE_PATH.read_text(encoding="utf-8") - self.assertIn("multi-domain requirement gates", readme) - self.assertIn("no `planning-readiness.md` is generated", readme) - self.assertIn("`behavior/behavior-testability.md` is generated at plan closeout", readme) - self.assertIn("provider evidence remains an intake blocker", readme) + self.assertIn("requirement-domain readiness gates", readme) + self.assertIn("behavior/behavior-testability.md", readme) + self.assertIn("Missing provider evidence remains an intake blocker", readme) - self.assertIn("requirement-gate recomputation only", governance) - self.assertIn("requirements, behavior, UX, security, NFR, and visual requirement gates", governance) + self.assertIn("requirement-readiness gates", governance) self.assertIn("BDD Plan closeout", governance) - self.assertIn("must never be written as\n`planning-readiness.md`", governance) - self.assertIn("`behavior/behavior-testability.md` is a permitted planning artifact", governance) + self.assertIn("behavior/behavior-testability.md", governance) def test_plan_command_wrapper_contract(self) -> None: @@ -512,20 +571,13 @@ def test_plan_visual_substage_enhancement_contract(self) -> None: for document in (readme, governance): self.assertIn("research.md", document) - self.assertIn("visual/IR source refs", document) - self.assertIn("contracts formalize visual interaction and state constraints", document) - self.assertIn("contracts/sequences.md records visual state flow only when it affects cross-boundary sequencing", document) - self.assertNotIn("research.md records visual validation decisions", document) + self.assertIn("visual/IR", document) + self.assertIn("contracts/sequences.md", document) self.assertIn( "fixed R/M/U/O model: R is Repository / Workspace, M is Module / Capability, U is Unit / Design Object, and O is Operation / Detail", readme, ) - self.assertIn( - "Blocks constitution writes when a generated draft changes the fixed R/M/U/O mapping", - readme, - ) - self.assertIn("single-file project Architecture lifecycle", readme) self.assertIn("System Boundary -> Conceptual Model", readme) def test_constitution_change_scope_granularity_contract(self) -> None: @@ -620,7 +672,6 @@ def test_change_scope_granularity_stage_references(self) -> None: plan = PLAN_COMMAND_PATH.read_text(encoding="utf-8") tasks = TASKS_COMMAND_PATH.read_text(encoding="utf-8") analyze = ANALYZE_COMMAND_PATH.read_text(encoding="utf-8") - implement = IMPLEMENT_COMMAND_PATH.read_text(encoding="utf-8") self.assertIn("Apply the constitution's Change Scope Granularity principle.", plan) self.assertIn("During planning, lock the change scope to `M + U`", plan) @@ -634,8 +685,7 @@ def test_change_scope_granularity_stage_references(self) -> None: self.assertIn("Check that tasks preserve the planned `M + U` scope.", analyze) self.assertIn("Report missing, widened, or ambiguous scope boundaries as blockers.", analyze) - self.assertIn("Read plan.md for tech stack, architecture, and file structure", implement) - self.assertIn("Respect dependencies", implement) + self.assertFalse((REPO_ROOT / "commands" / "speckit.implement.md").exists()) def test_preplanning_commands_do_not_infer_scope_granularity(self) -> None: for path in (SPECIFY_COMMAND_PATH, CLARIFY_COMMAND_PATH, CHECKLIST_COMMAND_PATH): @@ -1026,7 +1076,6 @@ def test_behavior_first_plan_and_tasks_awareness_contract(self) -> None: plan = PLAN_COMMAND_PATH.read_text(encoding="utf-8") tasks = TASKS_COMMAND_PATH.read_text(encoding="utf-8") template = PLAN_TEMPLATE_PATH.read_text(encoding="utf-8") - implement = IMPLEMENT_COMMAND_PATH.read_text(encoding="utf-8") for term in ( "behavior/bdd.draft.feature", @@ -1302,7 +1351,6 @@ def test_actual_uif_artifacts_are_not_part_of_preset_contract(self) -> None: ANALYZE_COMMAND_PATH, PLAN_COMMAND_PATH, TASKS_COMMAND_PATH, - IMPLEMENT_COMMAND_PATH, PRESET_PATH, ] forbidden_terms = [ @@ -2182,9 +2230,24 @@ def test_github_actions_artifact_release_and_integration_pr_workflow(self) -> No "tests/test_presets.py", "__pycache__", ".pyc", - "*.pyc", "ZipInfo", "1980, 1, 1", + 'MANIFEST_NAME="spec-kit-workflow-preset-v${VERSION}.manifest.json"', + '"source_commit": source_commit', + '"sha256": zip_sha256', + "Verify release manifest", + "validators/speckit_behavior_contract.py", + '"requirements-dev.txt"', + '"tests"', + "test ! -e .specify/presets/workflow-preset/commands/speckit.implement.md", + "core_implement_sha", + "WORKFLOW_PRESET_MANIFEST_URL", + "presets/workflow-preset.release.json", + 'entry["source_commit"] = release_manifest["source_commit"]', + 'entry["sha256"] = release_manifest["artifact"]["sha256"]', + "curl --fail --location", + "archive.extractall", + 'cmp "${ZIP_PATH}" "${existing_dir}/${ZIP_NAME}"', "github.ref_type == 'tag' || (github.event_name == 'workflow_dispatch' && env.CREATE_INTEGRATION_PR == 'true')", "env.CREATE_INTEGRATION_PR == 'true'", "refs/tags/v${VERSION}", @@ -2204,10 +2267,10 @@ def test_github_actions_artifact_release_and_integration_pr_workflow(self) -> No "client_payload[download_url]", "repository_dispatch", "repos/bigsmartben/spec-kit/dispatches", - "tests/contracts/speckit-cross-agent-protocol.md", - "tests/contracts/speckit-cross-agent-subagents.md", "::warning::SPEC_KIT_FORK_DISPATCH_TOKEN", "skipping integration PR", + "gh release upload \"${TAG_NAME}\" \"${ZIP_PATH}\" --clobber", + "\"${GITHUB_WORKSPACE}/\" \"${fork_dir}/spec-kit/presets/workflow-preset/\"", ] for term in forbidden_terms: self.assertNotIn(term, workflow_text) diff --git a/tests/test_presets.py b/tests/test_presets.py index e5231230fc..35b4d7fd4d 100644 --- a/tests/test_presets.py +++ b/tests/test_presets.py @@ -4650,7 +4650,7 @@ def test_workflow_preset_catalog_matches_manifest(self): assert catalog_updated_at >= datetime(2026, 6, 18, tzinfo=timezone.utc) assert entry["bundled"] is True - assert entry["version"] == "2.0.0" + assert entry["version"] == "3.0.0" assert entry["version"] == manifest["preset"]["version"] assert entry["repository"] == manifest["preset"]["repository"] assert entry["requires"]["speckit_version"] == manifest["requires"]["speckit_version"] From 427f49f55966e085d146b489a09b0eda53290d66 Mon Sep 17 00:00:00 2001 From: bigben <245982990@qq.com> Date: Sun, 26 Jul 2026 23:22:31 +0800 Subject: [PATCH 2/2] feat: integrate workflow-preset v3.0.0 Sync the immutable v3.0.0 Release snapshot, remove the preset-owned Implement override, preserve Tasks final Code Review, and validate Core Implement ownership across bundled and external installs. Assisted-by: OpenAI Codex (model: GPT-5, autonomous) --- .github/workflows/community-smoke.yml | 2 + .../workflows/workflow-preset-integration.yml | 75 ++- README.md | 9 +- docs/community/presets.md | 2 +- docs/preset-extension-coding-standard.md | 2 +- presets/catalog.community.json | 15 +- presets/catalog.json | 13 +- presets/workflow-preset.release.json | 181 ++++++ presets/workflow-preset/.gitignore | 24 - presets/workflow-preset/AGENTS.md | 11 +- presets/workflow-preset/CHANGELOG.md | 13 + presets/workflow-preset/README.md | 584 +++++------------- .../commands/speckit.implement.md | 219 ------- .../docs/extension-governance.md | 254 ++++---- presets/workflow-preset/preset.yml | 11 +- .../contracts/speckit-cross-agent-protocol.md | 85 +-- .../tests/test_preset_contract.py | 115 +++- tests/integrations/test_cli.py | 3 +- tests/test_presets.py | 94 ++- 19 files changed, 789 insertions(+), 923 deletions(-) create mode 100644 presets/workflow-preset.release.json delete mode 100644 presets/workflow-preset/.gitignore delete mode 100644 presets/workflow-preset/commands/speckit.implement.md diff --git a/.github/workflows/community-smoke.yml b/.github/workflows/community-smoke.yml index da9ad32811..4fc9f6541f 100644 --- a/.github/workflows/community-smoke.yml +++ b/.github/workflows/community-smoke.yml @@ -93,6 +93,8 @@ jobs: test -f .specify/presets/workflow-preset/.composed/speckit.analyze.md test -f .specify/presets/workflow-preset/.composed/speckit.plan.md test -f .specify/presets/workflow-preset/.composed/speckit.tasks.md + test ! -e .specify/presets/workflow-preset/commands/speckit.implement.md + test ! -e .specify/presets/workflow-preset/.composed/speckit.implement.md test -f .claude/skills/speckit-preview-wireflow/SKILL.md test -f .claude/skills/speckit-discovery-contract/SKILL.md diff --git a/.github/workflows/workflow-preset-integration.yml b/.github/workflows/workflow-preset-integration.yml index 093766c974..767fa67bda 100644 --- a/.github/workflows/workflow-preset-integration.yml +++ b/.github/workflows/workflow-preset-integration.yml @@ -4,8 +4,6 @@ permissions: contents: read on: - repository_dispatch: - types: ["workflow-preset-release"] workflow_dispatch: inputs: preset_version: @@ -14,6 +12,9 @@ on: preset_download_url: description: "Optional workflow preset release ZIP URL" required: false + preset_manifest_url: + description: "Optional workflow preset release manifest URL" + required: false require_bundled_version_match: description: "Require bundled preset version to match preset_version" required: false @@ -21,7 +22,7 @@ on: default: false concurrency: - group: ${{ github.workflow }}-${{ github.event.client_payload.preset_version || github.event.client_payload.version || inputs.preset_version || 'unknown-version' }}-${{ github.run_id }} + group: ${{ github.workflow }}-${{ inputs.preset_version || 'unknown-version' }}-${{ github.run_id }} cancel-in-progress: false jobs: @@ -50,8 +51,9 @@ jobs: - name: Resolve workflow preset release id: release env: - EVENT_PRESET_VERSION: ${{ github.event.client_payload.preset_version || github.event.client_payload.version || inputs.preset_version }} - EVENT_PRESET_DOWNLOAD_URL: ${{ github.event.client_payload.preset_download_url || github.event.client_payload.download_url || inputs.preset_download_url }} + EVENT_PRESET_VERSION: ${{ inputs.preset_version }} + EVENT_PRESET_DOWNLOAD_URL: ${{ inputs.preset_download_url }} + EVENT_PRESET_MANIFEST_URL: ${{ inputs.preset_manifest_url }} run: | set -euo pipefail write_github_output() { @@ -72,7 +74,7 @@ jobs: preset_version="${EVENT_PRESET_VERSION}" if [ -z "$preset_version" ]; then - echo "preset_version is required from repository_dispatch payload or workflow_dispatch input" >&2 + echo "preset_version is required from workflow_dispatch input" >&2 exit 1 fi if ! printf '%s\n' "$preset_version" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'; then @@ -84,20 +86,65 @@ jobs: if [ -z "$preset_download_url" ]; then preset_download_url="https://github.com/bigsmartben/spec-kit-workflow-preset/releases/download/v${preset_version}/spec-kit-workflow-preset-v${preset_version}.zip" fi + preset_manifest_url="${EVENT_PRESET_MANIFEST_URL}" + if [ -z "$preset_manifest_url" ]; then + preset_manifest_url="https://github.com/bigsmartben/spec-kit-workflow-preset/releases/download/v${preset_version}/spec-kit-workflow-preset-v${preset_version}.manifest.json" + fi write_github_output "version" "$preset_version" write_github_output "download_url" "$preset_download_url" + write_github_output "manifest_url" "$preset_manifest_url" - name: Install and verify external workflow preset env: PRESET_VERSION: ${{ steps.release.outputs.version }} PRESET_DOWNLOAD_URL: ${{ steps.release.outputs.download_url }} + PRESET_MANIFEST_URL: ${{ steps.release.outputs.manifest_url }} run: | set -euo pipefail - project_dir="$(mktemp -d)" - cd "$project_dir" + release_dir="$(mktemp -d)" + curl --fail --location --silent --show-error "$PRESET_DOWNLOAD_URL" \ + --output "$release_dir/workflow-preset.zip" + curl --fail --location --silent --show-error "$PRESET_MANIFEST_URL" \ + --output "$release_dir/workflow-preset.manifest.json" + /tmp/specify-workflow-preset-venv/bin/python - "$release_dir" <<'PY' + import hashlib + import json + import sys + import zipfile + from pathlib import Path + + release_dir = Path(sys.argv[1]) + zip_path = release_dir / "workflow-preset.zip" + release_manifest = json.loads( + (release_dir / "workflow-preset.manifest.json").read_text( + encoding="utf-8" + ) + ) + assert ( + hashlib.sha256(zip_path.read_bytes()).hexdigest() + == release_manifest["artifact"]["sha256"] + ) + with zipfile.ZipFile(zip_path) as archive: + actual = { + name: hashlib.sha256(archive.read(name)).hexdigest() + for name in archive.namelist() + } + expected = { + entry["path"]: entry["sha256"] + for entry in release_manifest["files"] + } + assert actual == expected + PY + + bundled_project="$(mktemp -d)" + cd "$bundled_project" + /tmp/specify-workflow-preset-venv/bin/specify init --here --ai claude --script sh --ignore-agent-tools + external_project="$(mktemp -d)" + cd "$external_project" /tmp/specify-workflow-preset-venv/bin/specify init --here --ai claude --script sh --ignore-agent-tools + core_implement_sha="$(sha256sum .claude/skills/speckit-implement/SKILL.md | awk '{print $1}')" /tmp/specify-workflow-preset-venv/bin/specify preset remove workflow-preset /tmp/specify-workflow-preset-venv/bin/specify preset add --from "$PRESET_DOWNLOAD_URL" @@ -121,15 +168,17 @@ jobs: test -f .specify/presets/workflow-preset/commands/speckit.constitution.md test -f .specify/presets/workflow-preset/commands/speckit.plan.md test -f .specify/presets/workflow-preset/commands/speckit.tasks.md - test -f .specify/presets/workflow-preset/commands/speckit.implement.md + test ! -e .specify/presets/workflow-preset/commands/speckit.implement.md test -f .claude/skills/speckit-constitution/SKILL.md test -f .claude/skills/speckit-plan/SKILL.md test -f .claude/skills/speckit-tasks/SKILL.md test -f .claude/skills/speckit-implement/SKILL.md grep -F "Change Scope Granularity" .claude/skills/speckit-constitution/SKILL.md - grep -F "## Pre-Execution Checks" .claude/skills/speckit-implement/SKILL.md - grep -F "mark the task off as [X] in the tasks file" .claude/skills/speckit-implement/SKILL.md + test "${core_implement_sha}" = "$(sha256sum .claude/skills/speckit-implement/SKILL.md | awk '{print $1}')" + diff -ru \ + "$bundled_project/.specify/presets/workflow-preset" \ + "$external_project/.specify/presets/workflow-preset" bundled-regression: runs-on: ubuntu-latest @@ -159,8 +208,8 @@ jobs: - name: Check bundled workflow preset version env: - EVENT_PRESET_VERSION: ${{ github.event.client_payload.preset_version || github.event.client_payload.version || inputs.preset_version }} - REQUIRE_BUNDLED_VERSION_MATCH: ${{ github.event.client_payload.require_bundled_version_match || inputs.require_bundled_version_match || 'false' }} + EVENT_PRESET_VERSION: ${{ inputs.preset_version }} + REQUIRE_BUNDLED_VERSION_MATCH: ${{ inputs.require_bundled_version_match || 'false' }} run: | set -euo pipefail if [ "$REQUIRE_BUNDLED_VERSION_MATCH" != "true" ]; then diff --git a/README.md b/README.md index 88ba49ee3c..4b6d5f40f7 100644 --- a/README.md +++ b/README.md @@ -69,7 +69,7 @@ specify init my-project --integration codex --ignore-agent-tools | 默认扩展 | `intake` | `extensions/intake` | 把 PRD、设计稿、Figma、最终静态 HTML 交付、测试用例等来源归一化为 SDD 可消费的证据包。 | | 默认扩展 | `preview` | `extensions/preview` | 从规格和计划生成低、中、高保真 Markdown 或自包含 HTML 预览。 | | 默认扩展 | `repository-governance` | `extensions/repository-governance` | 生成仓库治理 SSOT，帮助 agent 明确目录责任、读取顺序和事实证据。 | -| 默认预设 | `workflow-preset` | `presets/workflow-preset` | 由 Constitution 阶段托管单文件项目架构，并强化 BDD、NFR、UIF、设计产物、任务验证策略和 implement handoff 编排。 | +| 默认预设 | `workflow-preset` | `presets/workflow-preset` | 从 Specify 引入 UI/UX 需求，从 Plan 引入 BDD、集成与 E2E 测试设计，由 Tasks 映射为执行清单，最终交给标准 Core Implement。 | 默认扩展列表在 `src/specify_cli/commands/init.py` 的 `DEFAULT_BUNDLED_EXTENSIONS` 中维护。默认预设列表在同文件的 `DEFAULT_BUNDLED_PRESETS` 中维护。 @@ -238,7 +238,7 @@ specs//preview/wireflow.html ### `workflow-preset` -`workflow-preset` 是这个本地分发版的核心增强预设。它包装或替换核心命令，让规格驱动流程更适合复杂功能和多 agent 实现。 +`workflow-preset` 是这个本地分发版的核心增强预设。它包装规格、检查、规划和任务阶段；实现阶段始终使用当前 Spec Kit core 命令。 它会增强这些命令： @@ -250,7 +250,6 @@ specs//preview/wireflow.html /speckit.analyze /speckit.plan /speckit.tasks -/speckit.implement ``` 主要增强： @@ -258,8 +257,8 @@ specs//preview/wireflow.html - `/speckit.checklist` 增加 BDD、NFR、视觉保真 readiness gate。 - `/speckit.constitution` 增加 Change Scope Granularity 治理。 - `/speckit.plan` 增加 Phase 0 行为投影、BDD/UIF/data fixture intent 和可选设计产物。 -- `/speckit.tasks` 从行为契约、接口契约、`research.md`、`quickstart.md` 派生验证策略。 -- `/speckit.implement` 使用上游标准单会话流程执行 `tasks.md`，在每个阶段验证并标记完成任务。 +- `/speckit.tasks` 从行为契约、接口契约、`research.md`、`quickstart.md` 映射实现、验证、集成/E2E 和最终 Code Review 清单。 +- `/speckit.implement` 不由 preset 复制或覆盖；当前 core 命令按顺序执行 `tasks.md`，其中 Final Code Review 是最后的强制阶段。 典型产物： diff --git a/docs/community/presets.md b/docs/community/presets.md index 109e3c875d..f1b2b8c756 100644 --- a/docs/community/presets.md +++ b/docs/community/presets.md @@ -29,6 +29,6 @@ The following community-contributed presets customize how Spec Kit behaves — o | Spec2Cloud | Spec-driven workflow tuned for shipping to Azure: spec → plan → tasks → implement → deploy | 5 templates, 8 commands | — | [spec2cloud](https://github.com/Azure-Samples/Spec2Cloud) | | Table of Contents Navigation | Adds a navigable Table of Contents to generated spec.md, plan.md, and tasks.md documents | 3 templates, 3 commands | — | [spec-kit-preset-toc-navigation](https://github.com/Quratulain-bilal/spec-kit-preset-toc-navigation) | | VS Code Ask Questions | Enhances the clarify command to use `vscode/askQuestions` for batched interactive questioning. | 1 command | — | [spec-kit-presets](https://github.com/fdcastel/spec-kit-presets) | -| Workflow Preset | Behavior-first specification, design-aware planning, and scoped change governance — adds requirement-phase behavior drafts, formal BDD/UIF/behavior contracts, and optional design artifacts while keeping the standard implementation workflow | 20 templates, 8 commands | — | [spec-kit-workflow-preset](https://github.com/bigsmartben/spec-kit-workflow-preset) | +| Workflow Preset | UI/UX-aware specification, behavior-first planning, integration/E2E test design, and task-to-execution mapping with mandatory final Code Review while keeping the standard core implementation workflow | 24 templates, 7 commands | — | [spec-kit-workflow-preset](https://github.com/bigsmartben/spec-kit-workflow-preset) | To build and publish your own preset, see the [Presets Publishing Guide](https://github.com/bigsmartben/spec-kit/blob/main/presets/PUBLISHING.md). diff --git a/docs/preset-extension-coding-standard.md b/docs/preset-extension-coding-standard.md index fd8456a1da..d4b803e034 100644 --- a/docs/preset-extension-coding-standard.md +++ b/docs/preset-extension-coding-standard.md @@ -578,7 +578,7 @@ Preset/Extension issue 只有满足以下条件才可视为完成： - `extensions/arch/`：Command、Template、Schema 和 Validator 分离。 - `extensions/intake/`：Schema、语义 Contract、Readiness Validator 权威清晰。 -- `presets/workflow-preset/`：阶段所有权、结构化契约和多 agent handoff 边界。 +- `presets/workflow-preset/`：阶段所有权、结构化行为契约，以及 Tasks 与标准 Core Implement 的边界。 - `src/specify_cli/integrations/`：平台投影与功能提示词分离。 - `src/specify_cli/agents.py`：Extension/Preset 共用的 command registrar。 diff --git a/presets/catalog.community.json b/presets/catalog.community.json index 86d9af59e9..0c1f1b956e 100644 --- a/presets/catalog.community.json +++ b/presets/catalog.community.json @@ -670,11 +670,11 @@ "workflow-preset": { "name": "Workflow Preset", "id": "workflow-preset", - "version": "2.0.0", - "description": "Constitution-managed architecture, behavior-first specification, design artifacts, and scoped change governance", + "version": "3.0.0", + "description": "Constitution-managed architecture, behavior-first specification, design artifacts, and execution-ready task mapping", "author": "bigsmartben", "repository": "https://github.com/bigsmartben/spec-kit-workflow-preset", - "download_url": "https://github.com/bigsmartben/spec-kit-workflow-preset/releases/download/v2.0.0/spec-kit-workflow-preset-v2.0.0.zip", + "download_url": "https://github.com/bigsmartben/spec-kit-workflow-preset/releases/download/v3.0.0/spec-kit-workflow-preset-v3.0.0.zip", "homepage": "https://github.com/bigsmartben/spec-kit-workflow-preset", "documentation": "https://github.com/bigsmartben/spec-kit-workflow-preset/blob/main/README.md", "license": "MIT", @@ -683,7 +683,7 @@ }, "provides": { "templates": 24, - "commands": 8 + "commands": 7 }, "tags": [ "architecture", @@ -691,11 +691,12 @@ "behavior", "bdd", "planning", - "implementation", - "handoff" + "implementation" ], "created_at": "2026-05-27T00:00:00Z", - "updated_at": "2026-06-23T00:00:00Z" + "updated_at": "2026-07-26T00:00:00Z", + "source_commit": "c35c96cec18c280445ea4f9f73c929e5b61f8393", + "sha256": "3924817ded5c59649ea3ef685cd1a4572363f95e9379becd0eafe1d3757ee852" } } } diff --git a/presets/catalog.json b/presets/catalog.json index edcef0416d..8f90050fbd 100644 --- a/presets/catalog.json +++ b/presets/catalog.json @@ -29,8 +29,8 @@ "workflow-preset": { "name": "Workflow Preset", "id": "workflow-preset", - "version": "2.0.0", - "description": "Constitution-managed architecture, behavior-first specification, design artifacts, and scoped change governance", + "version": "3.0.0", + "description": "Constitution-managed architecture, behavior-first specification, design artifacts, and execution-ready task mapping", "author": "bigsmartben", "repository": "https://github.com/bigsmartben/spec-kit-workflow-preset", "license": "MIT", @@ -39,7 +39,7 @@ "speckit_version": ">=0.12.7.dev0" }, "provides": { - "commands": 8, + "commands": 7, "templates": 24 }, "tags": [ @@ -48,9 +48,10 @@ "behavior", "bdd", "planning", - "implementation", - "handoff" - ] + "implementation" + ], + "source_commit": "c35c96cec18c280445ea4f9f73c929e5b61f8393", + "sha256": "3924817ded5c59649ea3ef685cd1a4572363f95e9379becd0eafe1d3757ee852" } } } diff --git a/presets/workflow-preset.release.json b/presets/workflow-preset.release.json new file mode 100644 index 0000000000..4b1a6990b8 --- /dev/null +++ b/presets/workflow-preset.release.json @@ -0,0 +1,181 @@ +{ + "artifact": { + "name": "spec-kit-workflow-preset-v3.0.0.zip", + "sha256": "3924817ded5c59649ea3ef685cd1a4572363f95e9379becd0eafe1d3757ee852" + }, + "files": [ + { + "path": "AGENTS.md", + "sha256": "a3e48054a1cdedfa8ef91c642fe7b166bf951df1916ed92bc3b370d7b1f64d48" + }, + { + "path": "CHANGELOG.md", + "sha256": "b5500b5bdbe6febc33778e9bbf3dab0bb0426030788235bcf1c3d3bd154cf2e3" + }, + { + "path": "LICENSE", + "sha256": "8c9a47687655839e45d596c67fb9a13a1c9cd39eca4aaa0846e7afd9a01f1ab1" + }, + { + "path": "README.md", + "sha256": "b392ddb13c8cd4bf627da2d41e1ffb5ad13cf2a8c7ee6e69d1f460ecebf328eb" + }, + { + "path": "commands/speckit.analyze.md", + "sha256": "4ee1593b26cf7bc96246a78c3d44409775c7715cdb250b98ba6924f8b667de0e" + }, + { + "path": "commands/speckit.checklist.md", + "sha256": "931dc432b490f76dc4df80e8d087bbeb1468205fa986369870ed0fd85152c9e3" + }, + { + "path": "commands/speckit.clarify.md", + "sha256": "cc893a93b96b2f1196540ad315cae25d0f4316651a3a1260396ed8cac3c95260" + }, + { + "path": "commands/speckit.constitution.md", + "sha256": "a32ac47fb666bb2475d93d0d2ebb93426a2a5c70723ede8f5dd38005f87b0448" + }, + { + "path": "commands/speckit.plan.md", + "sha256": "26bbc0ff6ba91b72b86c317c501cfd65cf22d0e9bfc67e55d722ce6cb95b2e9e" + }, + { + "path": "commands/speckit.specify.md", + "sha256": "0e9a1c1521a2932d708ad34af5c67215b15d094691b12f9c6be501b20413e7c2" + }, + { + "path": "commands/speckit.tasks.md", + "sha256": "7434d434f9092ab99ba02857e933f8426cbd731ffa61b24473c96382aeded219" + }, + { + "path": "docs/extension-governance.md", + "sha256": "6f9d183ff3defb1abcfc6a25970feda8855e04f70e66cb98df96d33a030a3961" + }, + { + "path": "preset.yml", + "sha256": "d6812ee256ac3719e5d5ea95704e7a97c46aae63cbe5a19eb7dbcf91068cd8d6" + }, + { + "path": "requirements-dev.txt", + "sha256": "75bfdb680a26a97ba91e8089c6970962de9aefbaa102eb6a3445bd08e4b55322" + }, + { + "path": "schemas/speckit.behavior.assertions.v1.schema.json", + "sha256": "8f39b5b1615172ee1d0ac15a72545b60b98355474695694cca60cf0615772fed" + }, + { + "path": "schemas/speckit.behavior.data-fixtures.intent.v1.schema.json", + "sha256": "e43a3f4341b80507a8cee8e07949dd6cc0380c88655894c60c51ba0ac92873ed" + }, + { + "path": "schemas/speckit.behavior.data-fixtures.v1.schema.json", + "sha256": "7b763ede880aff476746b5f9eb24c540d42bcbc4d24a33b002376bdecbbca5dd" + }, + { + "path": "schemas/speckit.behavior.scenario-instances.v1.schema.json", + "sha256": "5f847f913b32829fd4c205cbef9e994e0e065a8596f8f8be525bb34f653f2191" + }, + { + "path": "schemas/speckit.behavior.scenarios.draft.v1.schema.json", + "sha256": "b992e4e85d5854b777f37be7f7a309105526b6c8cd53ff7f58cc2e0fcd002fec" + }, + { + "path": "schemas/speckit.behavior.uif.expected.v1.schema.json", + "sha256": "024653cfaef2255a1dec521feae52847e24c5e88782d2babbbdb3120e5bc81bc" + }, + { + "path": "schemas/speckit.behavior.uif.intent.v1.schema.json", + "sha256": "f8600df13a610634330b736116f560b9b5ea72ba6f092dea096a7522e6a362ed" + }, + { + "path": "templates/architecture-template.md", + "sha256": "9f8460ec74e6aeaef0cef686eec1ff3843aced4cd6e68ff2eb3e7291b87bcd40" + }, + { + "path": "templates/behavior/assertions.json", + "sha256": "b47c06f6fc77bfbf76dd4fbfd1207d292196bfe5be16391e17fcbfb6e2df2bd6" + }, + { + "path": "templates/behavior/bdd-contract.feature", + "sha256": "7b846ea7e4cdd0ff63245fb3da201df3da9742d6364c685a5a3583137607a810" + }, + { + "path": "templates/behavior/bdd-draft.feature", + "sha256": "070262ee305e6fe5e053df4d47d6edf9d3cf215a8f6457f7ee2b309fee68310f" + }, + { + "path": "templates/behavior/behavior-scenarios-draft.json", + "sha256": "6def3acc8d3a44b2023d60c3e7717d1183ef4e4b7ff7be8bfb9d1d8f4fbd451c" + }, + { + "path": "templates/behavior/behavior-testability.md", + "sha256": "bbedd7a31c1ebb0b03ba1585401551f2910f3f297f62bcc3ded8d1e2b8057ad0" + }, + { + "path": "templates/behavior/data-fixtures-intent.json", + "sha256": "52860246ad830f8a3d620fbb78773127777839d50cb72da25383677adf4aba17" + }, + { + "path": "templates/behavior/data-fixtures.json", + "sha256": "aba3c98fd9d4a0332a2d5a57bc007885bf46279aa356e619e19b2a4ff9e47387" + }, + { + "path": "templates/behavior/scenario-instances.json", + "sha256": "1bf2999050106565bbb5a0c0b93fdaabe3d64602643822b17c041db1afc2a120" + }, + { + "path": "templates/behavior/uif-expected.json", + "sha256": "20c45e08817cfd926c9586f8ccdc7bf55eb7f2e08a57b783e41a4fb5efd97959" + }, + { + "path": "templates/behavior/uif-intent.json", + "sha256": "66572ff70127e5fcb23c0815f902a0fc525081a3c1c0d1e0e87c4be4c19bbbad" + }, + { + "path": "templates/constitution-template.md", + "sha256": "6763fba121628fa5b81b1c52ba8c6bc5485ce4c15ebb4653d88f3ebbd507391c" + }, + { + "path": "templates/plan-template.md", + "sha256": "3ac5ca372aad14e8b2110aa7c48d36fbe5409646c8267444cf6fc59317b18da0" + }, + { + "path": "templates/requirements/behavior-gate.md", + "sha256": "432c805d3f0f1e7feea6bc0171573a410bf20a64ccc16411de2c2cc9eb7628d6" + }, + { + "path": "templates/requirements/domain-gate.md", + "sha256": "d79afadb37e0f95a2faf4f429c88d0577e536000f97f4126ae92194bef0c26e8" + }, + { + "path": "templates/requirements/nfr-gate.md", + "sha256": "3aa029528263aae1f082822214301a39bb2008dd14a56f3c730959f63a50c79c" + }, + { + "path": "templates/requirements/visual-gate.md", + "sha256": "0884437eba2d8e2f9ea49bc6027c721763987cee6ab63dc3806b50843cbc6974" + }, + { + "path": "tests/contracts/speckit-cross-agent-protocol.md", + "sha256": "17c7b2dd55f4f4c775f3bd2ed8649afea2bd9620d182ced9feaeab1bca8b2aa8" + }, + { + "path": "tests/test_preset_contract.py", + "sha256": "b513ee724b850f7e1d489bb1df2a3c50c24239c4a45697852cb2b50048268dea" + }, + { + "path": "validators/__init__.py", + "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" + }, + { + "path": "validators/speckit_behavior_contract.py", + "sha256": "988131eb3138cc6a4a21a5ef3c936534aeceea17fe866be822ef0a3f09476ac9" + } + ], + "preset_id": "workflow-preset", + "schema_version": "1.0", + "source_commit": "c35c96cec18c280445ea4f9f73c929e5b61f8393", + "source_repository": "https://github.com/bigsmartben/spec-kit-workflow-preset", + "version": "3.0.0" +} diff --git a/presets/workflow-preset/.gitignore b/presets/workflow-preset/.gitignore deleted file mode 100644 index 756e140ac4..0000000000 --- a/presets/workflow-preset/.gitignore +++ /dev/null @@ -1,24 +0,0 @@ -__pycache__/ -*.py[cod] -.pytest_cache/ -.mypy_cache/ -.ruff_cache/ -.coverage -htmlcov/ -.venv/ -venv/ -dist/ -build/ -*.egg-info/ -*.zip -*.log -.env -.env.* -!.env.example -.tmp/ -tmp/ -temp/ -.DS_Store -Thumbs.db -.worktrees/ -docs/superpowers/ diff --git a/presets/workflow-preset/AGENTS.md b/presets/workflow-preset/AGENTS.md index 6d70b447cf..670f8eae45 100644 --- a/presets/workflow-preset/AGENTS.md +++ b/presets/workflow-preset/AGENTS.md @@ -14,10 +14,15 @@ This repository is a Spec Kit community preset named `workflow-preset`. ## Development Rules - Preserve the preset contract tested by `tests/test_preset_contract.py`. -- Follow the Extension Governance in `docs/extension-governance.md` before adding or changing preset commands, templates, schemas, validators, handoff contracts, or behavior-first artifacts. +- Follow the Extension Governance in `docs/extension-governance.md` before adding or changing preset commands, templates, schemas, validators, or behavior-first artifacts. - Keep `/speckit.plan` and `/speckit.tasks` as core-template wrappers. -- Keep `/speckit.implement` as a replacement command synchronized with the upstream standard implementation workflow. -- Do not reintroduce Python orchestration, workflow shell dispatch, integration adapter scripts, or worker dispatch from scripts. +- Do not declare, copy, or replace `/speckit.implement`; implementation execution + belongs to the currently installed Spec Kit core command. +- Keep Final Code Review as the last mandatory phase generated in `tasks.md`. +- Do not introduce an implementation reviewer runtime, persistent transfer + protocol, execution manifest, worker result protocol, Python orchestration, + workflow shell dispatch, integration adapter scripts, or script-based worker + dispatch. - Planning design artifacts are optional and contextual: - `class-diagram.md` - `contracts/sequences.md` diff --git a/presets/workflow-preset/CHANGELOG.md b/presets/workflow-preset/CHANGELOG.md index bae0146c9e..5051ef40f6 100644 --- a/presets/workflow-preset/CHANGELOG.md +++ b/presets/workflow-preset/CHANGELOG.md @@ -2,6 +2,19 @@ ## Unreleased +## 3.0.0 - 2026-07-26 + +- Removed the preset-owned `speckit.implement` replacement and its manifest, + transfer, worker-result schemas, validator, and persistent execution + protocol. The active Spec Kit core command now owns implementation. +- Kept Final Code Review as the last mandatory `tasks.md` phase so standard + core implementation executes and validates it in checklist order. +- Split behavior-only cross-field validation into + `validators/speckit_behavior_contract.py`. +- Defined release snapshots as immutable, source-backed artifacts; downstream + bundling must preserve release file hashes and must not modify a published + version in place. + ## 2.0.0 - 2026-07-26 - Moved project Architecture generation into `/speckit.constitution`, which now diff --git a/presets/workflow-preset/README.md b/presets/workflow-preset/README.md index 46119ab46f..e71163653a 100644 --- a/presets/workflow-preset/README.md +++ b/presets/workflow-preset/README.md @@ -1,500 +1,224 @@ # Workflow Preset -This Spec Kit community preset combines Constitution-managed project Architecture, behavior-first specification, design-aware planning, scoped change governance, and agent-native handoff orchestration. - -It wraps `/speckit.specify`, `/speckit.checklist`, `/speckit.clarify`, -`/speckit.constitution`, `/speckit.plan`, `/speckit.tasks`, and -`/speckit.analyze` with multi-domain requirement gates, Change Scope -Granularity, a single-file project Architecture lifecycle, Architecture-guided -planning, Phase 0 behavior projection, formal behavior contracts, plan-stage -Behavior Testability, optional design artifacts, and task-time validation -derivation. It replaces -`/speckit.implement` with a Core Agent, Vertical Planner Agent, and Worker Agent -orchestration contract that writes handoffs to disk. - -## Goal - -`workflow-preset` turns a Spec Kit feature from a single broad implementation prompt into a staged workflow with stable design context and explicit worker boundaries. - -The preset has six goals: - -- Make requirements, behavior, UX, security, NFR, and visual readiness explicit - before planning without creating a Planning Readiness summary file. -- Project accepted requirements into BDD, UIF intent, and fixture intent drafts during `/speckit.plan` Phase 0. -- Close planning with `behavior/behavior-testability.md`, which maps Required - Cases and formal planning decisions into Task Readiness. -- Preserve richer planning intent so downstream tasks and implementation do not lose object design, service-flow, or validation decisions. -- Keep implementation scope explicit by applying Change Scope Granularity from planning onward: M + U boundaries are locked before execution maps them to concrete paths and O-level edits. -- Execute implementation through agent-native handoff orchestration so each worker receives explicit task IDs, lifecycle stage, vertical capability, context, read/write paths, validation commands, and receipt requirements. - -## Problem Addressed - -Large Spec Kit features can overload the implementation phase. A single `/speckit.implement` run may need to keep product requirements, technical decisions, domain details, interface contracts, object design, service flows, test strategy, task ordering, and current code changes in one prompt. As the context grows, the agent is more likely to drift from earlier design decisions, blur task boundaries, read unrelated documents, update the wrong files, or mark tasks complete without enough validation evidence. - -`workflow-preset` reduces that failure mode in three complementary ways: - -- Requirement enhancement keeps product requirements in `spec.md` and gates - planning with metadata-bearing domain checklists. -- Scope governance keeps broad repository context from becoming implementation scope by applying the R/M/U/O model once planning begins. -- Plan enhancement projects accepted behavior drafts, then gives object design, service sequencing, and validation intent stable homes before tasks are generated. -- Implement handoff orchestration slices work by lifecycle and vertical capability, then gives each Worker Agent a compact digest, scoped paths, validation commands, and a receipt contract instead of the full planning corpus. - -The intent is not to add ceremony to simple features. The intent is to preserve reasoning quality when the feature is large enough that a single implementation context becomes a source of drift. - -## Capabilities - -Requirement capabilities: - -- Wraps `/speckit.specify` so it produces or updates `spec.md` only. -- Wraps `/speckit.clarify` so it resolves product-decision blockers in - `spec.md`, recomputes affected gates, and leaves provider evidence with - intake. -- Consumes confirmed product facts, external intake facts, visual SSOT refs, HTML SSOT refs, structured IR refs, and evidence refs when projecting requirements into `spec.md`. -- When external intake evidence or visual SSOT refs have already been projected into `spec.md`, `/speckit.clarify` clarifies evidence-derived gaps already written in `spec.md` and does not call provider tools. -- Wraps `/speckit.checklist` to generate `requirements.md`, `behavior.md`, - `ux.md`, `security.md`, `nfr.md`, and `visual.md` requirement gates. -- Checks user stories, acceptance criteria, Given/When/Then readiness, roles, permissions, states, data, validation, boundary, exception, state_conflict behavior, and non-functional requirements directly from `spec.md`. -- Adds a Case Coverage Matrix with one row per story or capability case type so positive, negative, boundary, permission, validation, and state_conflict cases are marked Required, Not Applicable, or Unknown before planning. -- Checks visual requirements for source traceability, external intake readiness status when cited, HTML SSOT refs, structured IR refs, evidence refs, provider blocker status, and visual fidelity scope before planning. -- Preserves stable visual SSOT refs, HTML SSOT refs, structured IR refs, and evidence refs through `spec.md` and the Visual Fidelity Evidence Matrix. -- Records Client Asset Contract facts in `spec.md` for asset source strategy, required variants, fallback policy, and blocker status. -- Requires NFR dimensions to be marked Required, Not Applicable, or Unknown in product language before planning. -- Blocks planning when readiness gaps or missing or unverifiable NFR assumptions must return to `/speckit.clarify` or `/speckit.specify`. - -Governance capabilities: - -- Wraps `/speckit.constitution` so one Constitution-stage lifecycle maintains separate `.specify/memory/constitution.md` and `.specify/memory/architecture.md` files. -- Establishes a user-confirmed input agreement for greenfield, brownfield, and amendment runs; no UC, README, or repository path is an automatic prerequisite or authority. -- Produces one five-section project Architecture through System Boundary -> Conceptual Model -> Technical Decisions & Evidence -> Planning Guardrails & Gaps reasoning, with no 4+1 views or secondary models. -- Defines the fixed R/M/U/O model: R is Repository / Workspace, M is Module / Capability, U is Unit / Design Object, and O is Operation / Detail. These letters must not be renamed or expanded with alternate nouns. -- Blocks constitution writes when a generated draft changes the fixed R/M/U/O mapping. -- Keeps durable governance in `constitution.md` and project-level boundaries, concepts, technical direction, evidence, constraints, and gaps in `architecture.md`. -- Requires planning to lock M + U before execution maps units to concrete paths. -- Treats unresolved U -> path mapping as a context gap instead of widening execution to repository-wide or broad module scope. - -Planning capabilities: - -- Wraps `/speckit.plan` to run Phase 0 preflight, Phase 0 behavior projection, and optional/contextual design artifacts when useful. -- Requires `/speckit.plan` to read project Architecture before writing and to preserve its decisions in `research.md`, concepts in `data-model.md`, boundaries in `contracts/`, and constraints or gaps in `plan.md` and `quickstart.md`. -- Stops planning and returns to `/speckit.constitution` when a feature conflicts with or requires changing project Architecture. -- Requires the runtime Planning Readiness aggregate to pass before planning; - no `planning-readiness.md` is generated. -- Treats Phase 0 preflight failures as report-only/no-write failures. -- Writes `behavior/bdd.draft.feature`, `behavior/behavior-scenarios.draft.json`, `behavior/uif.intent.json`, and `behavior/data-fixtures.intent.json` during Phase 0 behavior projection. -- Projects Required case coverage into `behavior/behavior-scenarios.draft.json` instead of allowing Required cases to disappear behind positive-only drafts. -- Consumes Phase 0 behavior drafts and must formalize them into - `contracts/bdd/`, `contracts/uif/`, and `contracts/behavior/` after the - multi-domain Planning Readiness aggregate passes. -- Requires failure scenarios in `contracts/behavior/` to carry an explicit trigger, case kind, error code, failure feedback, and state invariant, rollback, or compensation assertion reference. -- Records `N/A or blocker` and `case_coverage_blockers` when behavior drafts cannot be formalized. -- Keeps `plan.md` focused on technical decisions and navigation. -- Adds plan-template navigation to the core plan output. -- Stores internal object design in `class-diagram.md`. -- Stores service, command, event, async, retry, rollback, and failure-path flows in `contracts/sequences.md`. -- Records validation decisions in `research.md` and validation paths in `quickstart.md`. -- Generates `behavior/behavior-testability.md` at BDD Plan closeout with a Task - Derivation Matrix and READY/BLOCKED status. -- When visual requirements are in scope, research.md carries forward visual/IR source refs, readiness inputs, accepted exceptions, related contract paths, and unresolved blockers; contracts formalize visual interaction and state constraints; contracts/sequences.md records visual state flow only when it affects cross-boundary sequencing. -- For visual restoration work, visual SSOT refs carry requirement traceability while Client Asset Contract entries carry local asset binding expectations. -- Keeps product requirements in `spec.md`, domain facts in `data-model.md`, interface schemas in `contracts/`, and executable validation guidance in `quickstart.md`. - -Task generation capabilities: - -- Wraps `/speckit.tasks` so task generation requires READY - `behavior/behavior-testability.md` and consumes its Case mappings. -- Uses formal BDD, UIF, and behavior contracts to derive test-first fixture, acceptance test, implementation, and verification tasks. -- Treats missing Required failure behavior scenarios as blockers instead of generating complete-looking happy-path-only tasks. -- Performs test strategy derivation from BDD contracts, Expected UIF contracts, behavior contracts, interface contracts, `research.md`, and `quickstart.md` without writing a separate strategy artifact. -- Derives paired UI implementation and acceptance tasks when UIF contracts, Visual Fidelity Readiness rows, visual acceptance requirements, or Client Asset Contract entries apply. -- Preserves visual/IR traceability refs on UI implementation, asset binding, and non-visual acceptance tasks without generating visual validation, screenshot comparison, visual diff, baseline capture, or final visual review work. -- Uses design artifacts to derive implementation, integration, orchestration, failure-handling, and validation tasks. -- Adds Final Code Review tasks for boundary, interface contract, visual, data side-effect, behavior contract, sequence consistency, and asset binding scopes when applicable. -- Preserves the existing checklist format and user-story organization. - -Analysis capabilities: - -- Wraps `/speckit.analyze` to check vertical consistency from `spec.md` through BDD/UIF intent, formal contracts, and `tasks.md`. -- Checks that user stories, Given/When/Then steps, UIF API calls, behavior contracts, tasks, and quickstart validation paths remain traceable. -- Adds case coverage checks so Required case types remain traceable through behavior drafts, formal contracts, tasks, and quickstart validation paths. -- Treats UIF as a requirement behavior projection, formalized during planning as Expected UIF contracts. - -Implementation capabilities: - -- Replaces `/speckit.implement` with an agent-native handoff orchestration command. -- Uses Core Agent mode to own lifecycle state, create the context index, assemble the final manifest, dispatch Worker Agent runs, review receipts, update `tasks.md`, and run integration verification. -- Uses Vertical Planner Agent mode to plan one `vertical_capability`, produce shard plans, create handoff drafts, create context digest drafts, and derive allowed paths. -- Uses Worker Agent mode to execute exactly one `speckit.implement.handoff.v2` handoff. -- Writes `handoff-manifest.json`, one handoff JSON, one context digest, a context index, and one worker receipt per shard. -- Defines deterministic shard, context digest, and allowed path derivation rules. -- Uses the cross-agent protocol profile `speckit.implement.persistent_handoff_orchestration`; `/speckit.plan`, `/speckit.tasks`, and `/speckit.analyze` use their own stage-local profiles without inheriting implement execution permissions. -- Keeps manifest, handoff, and receipt JSON contracts in standalone schema files. -- Splits implement gates into manifest structure, handoff structure, dispatch readiness, receipt structure, and commit readiness validation. -- Requires behavior-linked `validation_evidence` in worker receipts when behavior contracts are in handoff context. -- Requires Final Code Review receipts to include post-implementation data side-effect review, visual consistency review, and asset binding review of actual implementation diffs before task status commit when those scopes apply. -- Requires Final Code Review receipts to reconcile implemented UI states, viewport behavior, visual/IR traceability refs, and Client Asset Contract bindings when UI or asset scopes apply. -- Assigns every handoff a lifecycle stage and vertical capability such as `domain-model`, `api-contract`, `persistence`, `service-flow`, `ui`, `test-validation`, `documentation`, `integration`, or `cleanup`. -- Supports direct single-shard execution with `Use handoff JSON `. -- Blocks worker execution when generated context has unresolved `context_gaps`. -- Commits completed task statuses from `speckit.implement.receipt.v1` receipts so the Core Agent is the only `tasks.md` writer. - -Context-load controls: - -- `context-index.json` records the available planning and implementation context without requiring every worker to read every source document. -- Context digests include only assigned task text, relevant headings, referenced sections, applicable `class-diagram.md` or `contracts/sequences.md` constraints, relevant `research.md` validation decisions, and relevant `quickstart.md` validation paths. -- `context_gaps` are explicit blockers. A Worker Agent stops instead of guessing or expanding into full `spec.md`, `plan.md`, `research.md`, `contracts/`, `class-diagram.md`, or `quickstart.md`. -- `allowed_read_paths` and `allowed_write_paths` make each handoff auditable and prevent broad implementation runs from silently crossing capability boundaries. -- Worker receipts separate execution evidence from task status commits, so the Core Agent can review validation evidence before updating `tasks.md`. -- Final Code Review analyzes implementation data side effects after Worker Agents finish and before task status commit. -- When isolated subagents are unavailable, Core Agent writes the manifest and handoffs, then reports a `Manual Worker Queue` of `/speckit.implement Use handoff JSON ` entries in dispatch order. - -## Workflow - -1. `/speckit.constitution` confirms greenfield, brownfield, or amendment inputs, then maintains separate Constitution and project Architecture files. -2. `/speckit.specify` keeps the core requirements output in `spec.md`. -3. `/speckit.clarify` resolves requirement ambiguity in `spec.md`. -4. `/speckit.checklist` evaluates requirements, behavior, UX, security, NFR, - and visual readiness directly from `spec.md`; `/speckit.clarify` repairs - product-decision blockers and re-evaluates affected gates. -5. `/speckit.plan` reads project Architecture, applies Change Scope Granularity, runs Phase 0 preflight, performs Phase 0 behavior projection, formalizes behavior drafts into contracts, and adds design artifacts when they help implementation. -6. `/speckit.tasks` reads the core plan outputs, optional design artifacts, behavior contracts, interface contracts, `research.md`, and `quickstart.md`, then produces executable tasks with inline test level, data strategy, visual/IR traceability refs, asset binding, non-visual acceptance, and evidence requirements. -7. `/speckit.analyze` checks vertical consistency across requirements, behavior drafts, contracts, and tasks. -8. `/speckit.implement` enters Core Agent mode when no handoff path is provided. -9. The Core Agent writes `context-index.json` and dispatches one Vertical Planner Agent per active vertical capability. -10. Vertical Planner Agents produce shard plans, handoff drafts, context digest drafts, and allowed path derivations. -11. The Core Agent assembles final handoffs and writes `handoff-manifest.json`. -12. Worker Agents run only from persisted handoff JSON files and write receipts. -13. Final Code Review checks boundary, contract, visual, asset binding, sequence, implementation data side effects, and real e2e readiness. -14. The Core Agent reviews receipts, updates `tasks.md`, runs integration verification, and reports closeout status. - -## Non-Goals - -- It does not make every feature produce large diagrams or test matrices. -- It does not move product requirements out of `spec.md`. -- It does not move API or message schemas out of `contracts/`. -- It does not replace `data-model.md`, `research.md`, or `quickstart.md`. -- It does not generate 4+1, UML, C4, PoC code, or Architecture-consumption audit artifacts. -- It does not treat `uc.md` or any discovered conventional path as an automatic Constitution-stage input. -- It does not infer UIF from built code; UIF remains a requirement and planning contract. -- It does not provide a Python orchestration script, workflow shell runner, or integration adapter layer. -- It does not allow Worker Agents to freely expand context by reading full planning documents when the digest is insufficient. +`workflow-preset` extends Spec Kit with Constitution-managed project +Architecture, behavior-first requirements and planning, UI/UX delivery +contracts, and an execution-ready task mapping. -## Install - -Release install: - -```bash -specify preset add workflow-preset --from https://github.com/bigsmartben/spec-kit-workflow-preset/releases/download/v2.0.0/spec-kit-workflow-preset-v2.0.0.zip -``` +It deliberately does **not** provide `speckit.implement`. After installation, +`/speckit.implement` always resolves to the implementation command supplied by +the currently installed Spec Kit core. -Local development install: +## Ownership Model -```bash -specify preset add --dev /path/to/workflow-preset -``` - -## Usage +| Stage | What this preset adds | Primary output | +|---|---|---| +| Specify | behavior, visual, and UI/UX requirement ownership | `spec.md` | +| Checklist | requirement-domain readiness gates | `checklists/*.md` | +| Plan | Architecture consumption, BDD/UIF contracts, validation design | `plan.md`, `research.md`, `quickstart.md`, `contracts/`, behavior artifacts | +| Tasks | mapping of upstream artifacts to ordered implementation, validation, e2e, and review work | `tasks.md` | +| Implement | no preset override; standard core behavior | execution of `tasks.md` | -Run the behavior-first workflow: +The lifecycle is: ```text -/speckit.constitution -/speckit.specify -/speckit.clarify -/speckit.checklist -/speckit.plan -/speckit.tasks -/speckit.analyze +spec requirements and UI/UX intent + -> requirement readiness gates + -> plan, behavior/UI contracts, and validation design + -> tasks.md execution checklist + -> standard core implement ``` -At `/speckit.constitution`, identify the mode and selected inputs. For example: - -```text -/speckit.constitution Brownfield amendment. Use the existing constitution, -docs/platform-boundaries.md, and repository configuration under services/api/ -as authorized evidence. Exclude Git history. Update both Constitution and Architecture. -``` - -### External Intake And Visual SSOT - -Source capture and provider-specific intake are owned by the separate `spec-kit-intake` -extension. Install or run that extension when PRD, design, provider design, rendered HTML, -or test-case evidence must be captured or validated before this preset projects -requirements. - -```text -external intake evidence + visual SSOT refs + HTML SSOT refs + structured IR refs -> /speckit.specify -> baseline spec.md -``` - -`/speckit.specify` does not perform intake, call provider tools, parse HTML SSOT bundles, re-parse structured IR artifacts, or decide provider source readiness. It consumes confirmed source-backed facts and preserves visual SSOT refs, HTML SSOT refs, structured IR refs, evidence refs, state/viewport refs, -screenshots, visual proof refs, and Client Asset Contract facts in `spec.md`. -Missing product decisions become `[NEEDS CLARIFICATION]`; missing provider or intake evidence for a feature that depends on that evidence becomes `[BLOCKED: PROVIDER_EVIDENCE]`; features that do not depend on HTML SSOT, structured IR, or provider evidence are `Not Applicable`. - -### Provider Evidence Refs - -Screenshots, visual proof refs, HTML SSOT refs, structured IR refs, and provider artifacts are evidence refs, not intake execution. This preset only references them through `spec.md` visual requirements and the Visual Fidelity Evidence Matrix. +## Commands -Evidence refs can support layout, density, state, viewport, asset, and visual facts when source-backed. They cannot upgrade product semantics such as permissions, business effects, validation rules, or data ownership into confirmed requirements. +The preset packages seven command wrappers: -The Visual Fidelity Evidence Matrix is the single visual readiness record. It records requirement status, source refs, HTML SSOT refs, structured IR refs, other evidence refs, provider blocker status, accepted exception refs, Gate Status, and Blocking Items. It does not define visual validation work, screenshot comparison, visual diff, baseline capture, or final visual review. +1. `/speckit.specify` +2. `/speckit.clarify` +3. `/speckit.checklist` +4. `/speckit.constitution` +5. `/speckit.plan` +6. `/speckit.tasks` +7. `/speckit.analyze` -### Provider Design And HTML SSOT Input +`speckit.implement` is intentionally absent from `preset.yml` and `commands/`. +This prevents the preset from freezing or shadowing a core implementation +command. -Use the `spec-kit-intake` extension for provider design, HTML SSOT, or structured IR capture: +## UI/UX From Specify -```text -/speckit.intake.visual-design -/speckit.intake.figma2htmlssot -``` - -The intake extension owns source capture, provider evidence, raw provider metadata, -node inventory parity, rendered HTML visual SSOT bundles, structured IR artifacts, -source-side readiness, and blocker codes. This preset consumes only the confirmed -artifact refs, readiness inputs, blocker status, and traceability refs written or cited in `spec.md`. +UI/UX is a requirement concern before it is an implementation concern. +`/speckit.specify` records applicable visual and interaction needs in +`spec.md`, including states, viewport behavior, source/evidence refs, and Client +Asset Contract expectations. `/speckit.checklist` decides whether those +requirements are ready for planning. -Then run agent-native orchestrated implementation: - -```text -/speckit.implement -``` +External provider capture stays outside the preset. Confirmed visual SSOT refs, +HTML SSOT refs, structured IR refs, screenshots, and visual proof refs may be +consumed after an intake extension has projected them into the specification. +Missing provider evidence remains an intake blocker; it is not converted into a +product clarification. -Run a single worker handoff directly: +Example: ```text -/speckit.implement Use handoff JSON specs/001-demo/handoffs/implement//S01-service-flow-01.json +Requirement: Checkout shows loading, success, validation-error, and +payment-declined states at desktop and mobile viewports. ``` -## Files Written - -The core governance and planning workflow still owns its normal artifacts: - -- `.specify/memory/constitution.md` -- `.specify/memory/architecture.md` -- `specs//plan.md` -- `specs//research.md` -- `specs//data-model.md` -- `specs//contracts/` -- `specs//quickstart.md` -- `specs//tasks.md` - -This preset adds requirement-stage checklist artifacts: - -- `specs//checklists/behavior.md` -- `specs//checklists/ux.md` -- `specs//checklists/security.md` -- `specs//checklists/nfr.md` -- `specs//checklists/visual.md` - -Source intake artifacts and provider artifact instances are written by -`spec-kit-intake` or another external intake extension. This preset consumes the -qualified evidence refs from `spec.md` after `/speckit.specify` writes confirmed -requirements or records `[BLOCKED: PROVIDER_EVIDENCE]`; it does not define or -generate the artifact instances. Provider evidence blockers do not become -`[NEEDS CLARIFICATION]`. - -This preset adds Phase 0 behavior artifacts: - -- `specs//behavior/bdd.draft.feature` -- `specs//behavior/behavior-scenarios.draft.json` -- `specs//behavior/uif.intent.json` -- `specs//behavior/data-fixtures.intent.json` - -This preset adds planning-phase formal behavior contracts: - -- `specs//contracts/bdd/` -- `specs//contracts/uif/` -- `specs//contracts/behavior/` - -This preset adds the plan-stage task-readiness artifact: - -- `specs//behavior/behavior-testability.md` +The Visual Fidelity Evidence Matrix in `checklists/visual.md` records the +planning-readiness status of that requirement. It does not define screenshot +comparison, visual diff, baseline capture, or final visual review work. -This preset adds optional/contextual planning artifacts: +## Validation Design From Plan -- `specs//class-diagram.md` -- `specs//contracts/sequences.md` +`/speckit.plan` consumes checklist-approved requirements and creates the +technical and validation contracts required for task derivation: -Agent-native handoff orchestration writes implementation artifacts: +- `research.md` records validation decisions, test levels, fixture strategy, + and external-system strategy. +- `quickstart.md` records executable validation paths and real-system + integration/e2e scenarios. +- `behavior/bdd.draft.feature`, `behavior/uif.intent.json`, and + `behavior/data-fixtures.intent.json` provide Phase 0 projections. +- `contracts/bdd/`, `contracts/uif/`, and `contracts/behavior/` contain formal + behavior contracts. +- `behavior/behavior-testability.md` closes the BDD Plan with a READY or + BLOCKED decision. +- `class-diagram.md` and `contracts/sequences.md` are optional contextual design + artifacts. -- `specs//handoffs/implement//handoff-manifest.json` -- `specs//handoffs/implement//planner-outputs/` -- `specs//handoffs/implement//*.json` -- `specs//handoffs/implement//*.context.md` -- `specs//handoffs/implement//context-index.json` -- `specs//handoffs/implement//results/*.json` +This is broader than unit testing. Applicable plans cover unit, contract, +integration, UI acceptance, and real-system e2e validation. -Contract files packaged by the preset: +Example: -- `schemas/speckit.behavior.scenarios.draft.v1.schema.json` -- `schemas/speckit.behavior.uif.intent.v1.schema.json` -- `schemas/speckit.behavior.data-fixtures.intent.v1.schema.json` -- `schemas/speckit.behavior.uif.expected.v1.schema.json` -- `schemas/speckit.behavior.scenario-instances.v1.schema.json` -- `schemas/speckit.behavior.data-fixtures.v1.schema.json` -- `schemas/speckit.behavior.assertions.v1.schema.json` -- `schemas/speckit.implement.manifest.v1.schema.json` -- `schemas/speckit.implement.handoff.v2.schema.json` -- `schemas/speckit.implement.receipt.v1.schema.json` - -Governance templates packaged by the preset: - -- `templates/constitution-template.md` -- `templates/architecture-template.md` - -Packaged contract validators: - -- `validators/speckit_implement_contract.py` - -Source intake templates, provider design contracts, visual requirements schemas, HTML SSOT bundle contracts, structured IR contracts, and source-side validators live in the `spec-kit-intake` extension. - -## Artifact Roles - -`.specify/memory/architecture.md` is the project-level Architecture source for planning. It contains exactly Architecture Overview, System Boundary, Conceptual Model, Technical Decisions & Evidence, and Planning Guardrails & Gaps. Optional tables may be empty; an explicit Architecture goal, authorized source list, and owned boundary are required. For example, a payment boundary may own payment authorization but explicitly not own order fulfillment; feature `contracts/` must preserve that responsibility and dependency direction. - -`checklists/behavior.md` owns observable behavior and the Case Coverage Matrix; -`checklists/nfr.md` owns product-level non-functional readiness; and -`checklists/visual.md` owns the single Visual Fidelity Evidence Matrix. -Together with requirements, UX, and security gates they produce the runtime -Planning Readiness aggregate. Missing product decisions return to clarify; -provider evidence remains an intake blocker. - -`behavior/bdd.draft.feature` captures Phase 0 behavior projection in readable Given/When/Then form. `behavior/behavior-scenarios.draft.json`, `behavior/uif.intent.json`, and `behavior/data-fixtures.intent.json` make the same draft behavior machine-readable enough for planning formalization. - -`contracts/bdd/`, `contracts/uif/`, and `contracts/behavior/` contain planning-phase formal behavior contracts. They are generated from Phase 0 drafts after planning has resolved fixture strategy, data model, interface contracts, and validation paths, unless planning records `N/A or blocker` for missing planning input. `contracts/behavior/scenario-instances.json` carries `case_coverage_blockers` for Required cases that cannot be formalized. Failure scenarios must be structured enough to constrain implementation, including error code, failure feedback, and state invariant, rollback, or compensation assertion references. - -`behavior/behavior-testability.md` is generated at plan closeout. It maps every -Required Case to its Scenario, BDD/UIF contract, fixture, assertion, validation -level, research decision, quickstart path, and visual/NFR refs. `/speckit.tasks` -stops unless this artifact is current and READY. - -`class-diagram.md` captures internal implementation object structure: classes, interfaces, abstract types, composition, dependencies, references, and design pattern participants. It is the object design map that helps implementation preserve boundaries between services, adapters, repositories, strategies, factories, controllers, coordinators, and extension points. - -`contracts/sequences.md` captures service-call, command, event, external-system, retry, rollback, compensation, async, and failure-path sequencing. It is the flow design map that helps implementation preserve call order, service boundaries, async behavior, idempotency, compensation, and error propagation. Sequences always live at this path, even when there are no other contract files. - -For visual planning, research.md carries forward visual/IR source refs, readiness inputs, accepted exception refs, unresolved blocker refs, related contracts, and quickstart paths. contracts formalize visual interaction and state constraints by linking accepted visual items to Expected UIF, behavior scenarios, assertions, and supporting API/data schemas. contracts/sequences.md records visual state flow only when it affects cross-boundary sequencing, async results, retries, rollback, compensation, or error propagation; it does not redefine layout, tokens, screenshot matrices, visual readiness, or visual validation strategy. - -Test strategy derivation happens during `/speckit.tasks`. The command derives unit, contract, integration, and end-to-end validation work from BDD contracts, Expected UIF contracts, behavior contracts, interface contracts, `research.md`, and `quickstart.md`, then writes the strategy inline on the relevant `tasks.md` checklist items. It also defines UI implementation, non-visual acceptance, contract validation, data-side-effect validation, integration/e2e validation, and scope-aware code review tasks in `tasks.md`; `/speckit.implement` executes those tasks and records receipt evidence without inventing validation strategy, changing requirements, updating contracts, or widening scope. - -The handoff context digest includes relevant design constraints, visual fidelity requirements, visual SSOT refs, HTML SSOT refs, structured IR refs, external evidence refs, readiness inputs, quickstart paths, and behavior contracts when present, so Worker Agents can preserve object boundaries, service flows, visual intent, and validation intent without reading full planning documents by default. - -See `commands/speckit.implement.md` for runtime handoff orchestration rules, and `schemas/` plus `validators/speckit_implement_contract.py` for the machine-checked manifest, handoff, receipt, dispatch, and commit contracts. - -## Agent Topology - -The Core Agent is the lifecycle orchestrator. It owns context indexing, manifest assembly, worker dispatch, receipt review, task status commit, integration verification, and closeout. It does not directly produce shard plans or context digest drafts. +```text +quickstart.md: a buyer submits a refund against a sandbox payment service and +observes the persisted refund plus the user-visible confirmation state. +``` -Vertical Planner Agent runs are planners. A Vertical Planner Agent handles one `vertical_capability`, produces shard plans, handoff drafts, context digest drafts, and allowed path derivations, and does not execute implementation, write the final manifest, dispatch workers, or edit `tasks.md`. +That path is a source for integration/e2e tasks, not an implementation detail +invented later by Tasks or Implement. -Worker Agent runs are executors. A Worker Agent handles one persisted handoff, writes only `allowed_write_paths`, does not edit `tasks.md`, does not dispatch additional workers, and writes a `speckit.implement.receipt.v1` receipt. +## Tasks Is A Mapping Stage -Worker mode rejects handoff paths that do not exist or are not listed in `handoff-manifest.json`. +`/speckit.tasks` produces only `tasks.md`. It maps upstream deliverables into +the core checklist format and user-story organization. -Only Vertical Planner Agents may produce shard plans and digest drafts. +For each applicable story, it derives: -Only Core Agent may write final `handoff-manifest.json` and commit `tasks.md`. +- fixtures and environment setup; +- unit and contract validation; +- UI implementation and UI acceptance; +- implementation work; +- data-side-effect validation; +- integration and real-system e2e validation; +- evidence collection and blocker reporting. -Only Worker Agents may execute implementation handoffs. +Task text binds the work to concrete source, test, fixture, configuration, and +asset paths plus upstream scenario, contract, visual/IR, or quickstart refs. +Tasks does not create a second plan, execution manifest, transfer file, worker +result file, write-path protocol, or execution queue. -## Lifecycle +Example mapping: -Core Agent mode proceeds through these stages: +| Upstream product | `tasks.md` result | +|---|---| +| `SCN-ERR-001` permission failure | fixture + BDD/contract test + implementation + evidence tasks | +| Expected UIF submit event and error feedback | UI implementation + UI acceptance tasks | +| `quickstart.md` sandbox refund path | integration/e2e environment + execution + evidence tasks | +| persistence update rules | implementation + data-side-effect validation tasks | -- `intake` -- `context_indexing` -- `vertical_planning` -- `manifest_assembly` -- `worker_dispatch` -- `worker_execution` -- `receipt_review` -- `code_review` -- `task_commit` -- `integration_verification` -- `closeout` +## Mandatory Final Code Review -Every worker handoff records its `lifecycle_stage`, `vertical_capability`, `agent_topology`, `capability_boundary`, `planner_outputs`, and `draft_source`. +Tasks appends **Final Code Review** after all user-story, integration, and +validation work. It is a mandatory final phase in `tasks.md`, so the standard +core implementation command executes it in normal checklist order. -## Vertical Capability +The phase includes applicable checks for: -Worker handoffs should stay inside one vertical capability: +- the planned `M + U` boundary; +- interface and behavior contracts; +- implemented UI states and viewport behavior; +- visual/IR traceability refs and Client Asset Contract bindings; +- field-level and runtime data side effects; +- cross-boundary sequence consistency; +- integration/e2e evidence and unresolved blockers. -- `domain-model` -- `api-contract` -- `persistence` -- `service-flow` -- `ui` -- `cli` -- `test-validation` -- `documentation` -- `integration` -- `cleanup` +Code Review is not a separate command, reviewer runtime, or orchestration +protocol. Completion means the review checklist items pass; failures remain +open tasks or explicit blockers. -When a task spans capabilities, the Core Agent should split it into dependent handoffs instead of assigning broad cross-cutting work to one Worker Agent. +## Architecture And Scope -## Safety Boundaries +`/speckit.constitution` manages separate project-level artifacts: -Planning artifacts are optional/contextual. Simple features may produce concise files or `N/A` sections with concrete reasons. The command should avoid large placeholder artifacts and should not move product requirements out of `spec.md`, interface schemas out of `contracts/`, validation decisions out of `research.md`, or quick validation instructions out of `quickstart.md`. +- `.specify/memory/constitution.md` +- `.specify/memory/architecture.md` -Vertical Planner Agents may read only the planning artifacts required to produce their capability-local shard plan and digest drafts. Worker Agents should treat the final handoff JSON and its digest as the primary context. They should not read full `spec.md`, `plan.md`, `research.md`, `contracts/`, `class-diagram.md`, or `quickstart.md` by default. If the digest contains `context_gaps`, the Worker Agent must stop instead of expanding context on its own. +The Architecture follows the System Boundary -> Conceptual Model -> Technical +Decisions & Evidence -> Planning Guardrails & Gaps chain. -Completed `[x]` tasks are not scheduled into new implementation handoffs. +Change Scope Granularity uses the fixed R/M/U/O model: R is Repository / Workspace, M is Module / Capability, U is Unit / Design Object, and O is Operation / Detail. Planning locks `M + U`; Tasks maps those design objects to concrete executable paths without widening the planned boundary. -## Development +## Behavior Contracts -Runtime requirements: +The preset packages separate templates and JSON schemas for behavior drafts, +Expected UIF, scenario instances, fixtures, and assertions. +`validators/speckit_behavior_contract.py` checks cross-field relationships such +as scenario-to-fixture references, exception-case structure, Expected UIF +steps, and required-case coverage. -- Spec Kit CLI `>=0.12.7.dev0` -- An agent environment capable of running `/speckit.implement` in Core Agent, Vertical Planner Agent, and Worker Agent modes +The behavior validator is independent of implementation execution. There are no +implementation manifest, transfer, or worker-result schemas in this package. -Development and release tooling: - -- Python 3.10 or newer -- PyYAML and jsonschema for contract tests -- Git -- GitHub CLI `gh` for repository and release publishing +## Install -Install development test dependencies: +Development checkout: ```bash -python3 -m pip install -r requirements-dev.txt +specify preset add --dev /path/to/spec-kit-workflow-preset ``` -Run the contract tests: +Published release: ```bash -python3 -m unittest tests/test_preset_contract.py +specify preset add --from https://github.com/bigsmartben/spec-kit-workflow-preset/releases/download/v3.0.0/spec-kit-workflow-preset-v3.0.0.zip ``` -## Preset CI Boundary +After installation, resolve a preset-owned wrapper: -This repository owns preset artifact health: - -- run `tests/test_preset_contract.py`; -- build `spec-kit-workflow-preset-v.zip`; -- smoke-install this checkout on an Ubuntu GitHub runner with a `specify` CLI built from `bigsmartben/spec-kit`; -- publish or confirm the release artifact for a tag or manual release run; -- create or update a `workflow-preset-release-v` integration PR in `bigsmartben/spec-kit` on tag releases or manual runs with `create_integration_pr=true`. +```bash +specify preset resolve speckit.tasks +``` -Manual release runs default to the next patch version when `version` is omitted. For example, a `preset.yml` version of `2.0.0` defaults to release version `2.0.1`. +Resolve implementation through the normal command surface. Because the preset +does not declare it, `speckit.implement` comes from the active Spec Kit core. -The integration PR step requires a repository secret named `SPEC_KIT_FORK_PR_TOKEN` with permission to push branches and open pull requests in `bigsmartben/spec-kit`. If a tag release or manual `create_integration_pr=true` run reaches that step without the secret, the workflow fails fast instead of skipping integration PR creation. +## Release Integrity -This repository owns the release artifact and the fork integration PR. It does not open pull requests to `github/spec-kit`. The `bigsmartben/spec-kit` fork owns downstream integration validation, core workflow fixes, catalog resolver checks, and any later community catalog PR flow. +A source release is immutable. The integration fork must record: -Optional local CLI sanity check: +- source repository URL; +- release version; +- source commit SHA; +- release download URL; +- release artifact SHA-256; +- per-file hashes from the release manifest. -```bash -specify preset add --dev /path/to/workflow-preset -specify preset info workflow-preset -specify preset remove workflow-preset -``` +The fork extracts the release snapshot without edits. Bundled installation and +installation from the same release must produce identical preset files and +manifest content. Any functional change requires a new source version; a +published version is never modified in place. -Release install smoke validation is intentionally owned by GitHub Actions, not by a local WSL environment. +## Development -After tagging a release, validate archive installation: +Install test requirements and run the contract suite: ```bash -specify preset add workflow-preset --from https://github.com/bigsmartben/spec-kit-workflow-preset/releases/download/v2.0.0/spec-kit-workflow-preset-v2.0.0.zip +python3 -m pip install -r requirements-dev.txt +python3 -m unittest tests/test_preset_contract.py ``` -## Source Rationale - -See `2026-05-15-plan-design-artifacts-proposal.md` for the design artifact proposal that this preset incorporates. +Repository extension rules are in +[`docs/extension-governance.md`](docs/extension-governance.md). diff --git a/presets/workflow-preset/commands/speckit.implement.md b/presets/workflow-preset/commands/speckit.implement.md deleted file mode 100644 index 1d312a1c37..0000000000 --- a/presets/workflow-preset/commands/speckit.implement.md +++ /dev/null @@ -1,219 +0,0 @@ ---- -description: Execute the implementation plan by processing and executing all tasks defined in tasks.md -scripts: - sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks - ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks - py: scripts/python/check_prerequisites.py --json --require-tasks --include-tasks ---- - -## User Input - -```text -$ARGUMENTS -``` - -You **MUST** consider the user input before proceeding (if not empty). - -## Pre-Execution Checks - -**Check for extension hooks (before implementation)**: -- Check if `.specify/extensions.yml` exists in the project root. -- If it exists, read it and look for entries under the `hooks.before_implement` key -- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally -- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. -- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: - - If the hook has no `condition` field, or it is null/empty, treat the hook as executable - - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation -- For each executable hook, output the following based on its `optional` flag: - - **Optional hook** (`optional: true`): - ``` - ## Extension Hooks - - **Optional Pre-Hook**: {extension} - Command: `/{command}` - Description: {description} - - Prompt: {prompt} - To execute: `/{command}` - ``` - - **Mandatory hook** (`optional: false`): - ``` - ## Extension Hooks - - **Automatic Pre-Hook**: {extension} - Executing: `/{command}` - EXECUTE_COMMAND: {command} - - Wait for the result of the hook command before proceeding to the Outline. - ``` - After emitting the block above you MUST actually invoke the hook and wait for it to finish before continuing. Run it the same way you would run the command yourself in this agent/session (the invocation may differ from the literal `{command}` id shown above, e.g. a skills-mode agent runs it as `/skill:speckit-...` or `$speckit-...`). Emitting the block alone does not run the hook. -- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently - -## Outline - -1. Run `{SCRIPT}` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). - -2. **Check checklists status** (if FEATURE_DIR/checklists/ exists): - - Scan all checklist files in the checklists/ directory - - For each checklist, count: - - Total items: All lines matching `- [ ]` or `- [X]` or `- [x]` - - Completed items: Lines matching `- [X]` or `- [x]` - - Incomplete items: Lines matching `- [ ]` - - Create a status table: - - ```text - | Checklist | Total | Completed | Incomplete | Status | - |-----------|-------|-----------|------------|--------| - | ux.md | 12 | 12 | 0 | ✓ PASS | - | test.md | 8 | 5 | 3 | ✗ FAIL | - | security.md | 6 | 6 | 0 | ✓ PASS | - ``` - - - Calculate overall status: - - **PASS**: All checklists have 0 incomplete items - - **FAIL**: One or more checklists have incomplete items - - - **If any checklist is incomplete**: - - Display the table with incomplete item counts - - **STOP** and ask: "Some checklists are incomplete. Do you want to proceed with implementation anyway? (yes/no)" - - Wait for user response before continuing - - If user says "no" or "wait" or "stop", halt execution - - If user says "yes" or "proceed" or "continue", proceed to step 3 - - - **If all checklists are complete**: - - Display the table showing all checklists passed - - Automatically proceed to step 3 - -3. Load and analyze the implementation context: - - **REQUIRED**: Read tasks.md for the complete task list and execution plan - - **REQUIRED**: Read plan.md for tech stack, architecture, and file structure - - **IF EXISTS**: Read data-model.md for entities and relationships - - **IF EXISTS**: Read contracts/ for API specifications and test requirements - - **IF EXISTS**: Read research.md for technical decisions and constraints - - **IF EXISTS**: Read /memory/constitution.md for governance constraints - - **IF EXISTS**: Read quickstart.md for integration scenarios - -4. **Project Setup Verification**: - - **REQUIRED**: Create/verify ignore files based on actual project setup: - - **Detection & Creation Logic**: - - Check if the following command succeeds to determine if the repository is a git repo (create/verify .gitignore if so): - - ```sh - git rev-parse --git-dir 2>/dev/null - ``` - - - Check if Dockerfile* exists or Docker in plan.md → create/verify .dockerignore - - Check if .eslintrc* exists → create/verify .eslintignore - - Check if eslint.config.* exists → ensure the config's `ignores` entries cover required patterns - - Check if .prettierrc* exists → create/verify .prettierignore - - Check if .npmrc or package.json exists → create/verify .npmignore (if publishing) - - Check if terraform files (*.tf) exist → create/verify .terraformignore - - Check if .helmignore needed (helm charts present) → create/verify .helmignore - - **If ignore file already exists**: Verify it contains essential patterns, append missing critical patterns only - **If ignore file missing**: Create with full pattern set for detected technology - - **Common Patterns by Technology** (from plan.md tech stack): - - **Node.js/JavaScript/TypeScript**: `node_modules/`, `dist/`, `build/`, `*.log`, `.env*` - - **Python**: `__pycache__/`, `*.pyc`, `.venv/`, `venv/`, `dist/`, `*.egg-info/` - - **Java**: `target/`, `*.class`, `*.jar`, `.gradle/`, `build/` - - **C#/.NET**: `bin/`, `obj/`, `*.user`, `*.suo`, `packages/` - - **Go**: `*.exe`, `*.test`, `vendor/`, `*.out` - - **Ruby**: `.bundle/`, `log/`, `tmp/`, `*.gem`, `vendor/bundle/` - - **PHP**: `vendor/`, `*.log`, `*.cache`, `*.env` - - **Rust**: `target/`, `debug/`, `release/`, `*.rs.bk`, `*.rlib`, `*.prof*`, `.idea/`, `*.log`, `.env*` - - **Kotlin**: `build/`, `out/`, `.gradle/`, `.idea/`, `*.class`, `*.jar`, `*.iml`, `*.log`, `.env*` - - **C++**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.so`, `*.a`, `*.exe`, `*.dll`, `.idea/`, `*.log`, `.env*` - - **C**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.a`, `*.so`, `*.exe`, `*.dll`, `autom4te.cache/`, `config.status`, `config.log`, `.idea/`, `*.log`, `.env*` - - **Swift**: `.build/`, `DerivedData/`, `*.swiftpm/`, `Packages/` - - **R**: `.Rproj.user/`, `.Rhistory`, `.RData`, `.Ruserdata`, `*.Rproj`, `packrat/`, `renv/` - - **Universal**: `.DS_Store`, `Thumbs.db`, `*.tmp`, `*.swp`, `.vscode/`, `.idea/` - - **Tool-Specific Patterns**: - - **Docker**: `node_modules/`, `.git/`, `Dockerfile*`, `.dockerignore`, `*.log*`, `.env*`, `coverage/` - - **ESLint**: `node_modules/`, `dist/`, `build/`, `coverage/`, `*.min.js` - - **Prettier**: `node_modules/`, `dist/`, `build/`, `coverage/`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` - - **Terraform**: `.terraform/`, `*.tfstate*`, `*.tfvars`, `.terraform.lock.hcl` - - **Kubernetes/k8s**: `*.secret.yaml`, `secrets/`, `.kube/`, `kubeconfig*`, `*.key`, `*.crt` - -5. Parse tasks.md structure and extract: - - **Task phases**: Setup, Tests, Core, Integration, Polish - - **Task dependencies**: Sequential vs parallel execution rules - - **Task details**: ID, description, file paths, parallel markers [P] - - **Execution flow**: Order and dependency requirements - -6. Execute implementation following the task plan: - - **Phase-by-phase execution**: Complete each phase before moving to the next - - **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together - - **Follow TDD approach**: Execute test tasks before their corresponding implementation tasks - - **File-based coordination**: Tasks affecting the same files must run sequentially - - **Validation checkpoints**: Verify each phase completion before proceeding - -7. Implementation execution rules: - - **Setup first**: Initialize project structure, dependencies, configuration - - **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios - - **Core development**: Implement models, services, CLI commands, endpoints - - **Integration work**: Database connections, middleware, logging, external services - - **Polish and validation**: Unit tests, performance optimization, documentation - -8. Progress tracking and error handling: - - Report progress after each completed task - - Halt execution if any non-parallel task fails - - For parallel tasks [P], continue with successful tasks, report failed ones - - Provide clear error messages with context for debugging - - Suggest next steps if implementation cannot proceed - - **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file. - -9. Completion validation: - - Verify all required tasks are completed - - Check that implemented features match the original specification - - Validate that tests pass and coverage meets requirements - - Confirm the implementation follows the technical plan - -Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `__SPECKIT_COMMAND_TASKS__` first to regenerate the task list. - -## Mandatory Post-Execution Hooks - -**You MUST complete this section before reporting completion to the user.** - -Check if `.specify/extensions.yml` exists in the project root. -- If it does not exist, or no hooks are registered under `hooks.after_implement`, skip to the Completion Report. -- If it exists, read it and look for entries under the `hooks.after_implement` key. -- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue to the Completion Report. -- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. -- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: - - If the hook has no `condition` field, or it is null/empty, treat the hook as executable - - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation -- For each executable hook, output the following based on its `optional` flag: - - **Mandatory hook** (`optional: false`) — **You MUST emit `EXECUTE_COMMAND:` for each mandatory hook**: - ``` - ## Extension Hooks - - **Automatic Hook**: {extension} - Executing: `/{command}` - EXECUTE_COMMAND: {command} - ``` - After emitting the block above you MUST actually invoke the hook and wait for it to finish before continuing. Run it the same way you would run the command yourself in this agent/session (the invocation may differ from the literal `{command}` id shown above, e.g. a skills-mode agent runs it as `/skill:speckit-...` or `$speckit-...`). Emitting the block alone does not run the hook. - - **Optional hook** (`optional: true`): - ``` - ## Extension Hooks - - **Optional Hook**: {extension} - Command: `/{command}` - Description: {description} - - Prompt: {prompt} - To execute: `/{command}` - ``` - -## Completion Report - -Report final status with summary of completed work. - -## Done When - -- [ ] All tasks in tasks.md completed and marked `[X]` -- [ ] Implementation validated against specification, plan, and test coverage -- [ ] Extension hooks dispatched or skipped according to the rules in Mandatory Post-Execution Hooks above -- [ ] Completion reported to user with summary of completed work diff --git a/presets/workflow-preset/docs/extension-governance.md b/presets/workflow-preset/docs/extension-governance.md index 37c349569b..ac1281e13c 100644 --- a/presets/workflow-preset/docs/extension-governance.md +++ b/presets/workflow-preset/docs/extension-governance.md @@ -1,172 +1,158 @@ # Preset Extension Governance -This document is the repository-level rule set for extending `workflow-preset`. -It exists to keep preset changes aligned with Spec Kit's preset model and this -repository's contract tests. + +This document defines the ownership boundaries for `workflow-preset`. ## Source Of Truth -- `preset.yml` declares every packaged command, template, schema, and script. -- `commands/` contains stage-local LLM instructions. + +- `preset.yml` declares every packaged command, template, and schema. +- `commands/` contains stage-local instructions. - `templates/` contains stable artifact shapes. -- `schemas/` contains machine-readable JSON contracts. -- `validators/` contains pure in-memory cross-field contract checks. -- `tests/test_preset_contract.py` is the executable contract for this preset. - -## Preset Boundaries - -Presets customize existing Spec Kit workflows by overriding or composing -commands, templates, and scripts. Use extensions, not presets, for new tooling, -external integrations, static analyzers, workflow runners, or commands that add -a new capability outside the existing Spec Kit workflow. - -Do not reintroduce Python orchestration, workflow shell dispatch, integration -adapter scripts, or worker dispatch from scripts. - -Source intake artifacts belong in an extension, not this preset. External intake owns source capture, provider evidence, provider metadata, rendered HTML SSOT bundles, structured IR artifacts, -source-side readiness, and blocker codes. This preset may consume confirmed -external intake artifact refs, visual SSOT refs, HTML SSOT refs, structured IR refs, -source refs, coverage gaps, readiness inputs, accepted exception refs, and provider blockers already cited in `spec.md`. -External evidence refs are consumed as source, readiness, blocker, and traceability inputs only. Provider tools, provider execution, hooks, adapter scripts, -and authentication are external integration concerns and remain outside this -preset. - -## Template And Command Ownership - -- templates own stable artifact shapes. -- commands own stage-local generation instructions. -- Commands may name the inputs they consume, the outputs they write, and the - local update rules for their own phase. -- An upstream stage may define the explicit consumption contract for its direct - standard SDD downstream stage when both stages are wrapped by this preset. -- Do not encode full output structures only inside command text when the output - is intended to be durable or reused by later phases. - -Stage ownership: - -- `/speckit.constitution`: durable Constitution governance plus the separate - project-level `.specify/memory/architecture.md` lifecycle. -- `/speckit.specify`: requirement artifacts only. -- `/speckit.clarify`: product-decision clarification and affected requirement-gate recomputation only. -- `/speckit.checklist`: requirements, behavior, UX, security, NFR, and visual requirement gates only. -- `/speckit.plan`: Architecture-guided planning, Phase 0 behavior projection, - planning artifacts, formal contracts, and BDD Plan closeout. -- `/speckit.tasks`: `tasks.md` only. -- `/speckit.analyze`: vertical consistency checks across requirements, behavior drafts, contracts, and tasks only. -- `/speckit.implement`: implementation handoff execution only. - -`/speckit.tasks` owns implementation, non-visual acceptance, contract validation, data-side-effect validation, integration/e2e validation, and code review task definition in `tasks.md`. `/speckit.implement` may execute those tasks and record receipt evidence, but it must not invent validation strategy, visual validation work, lifecycle roles, requirements, contract updates, or wider scope during execution. - -When external intake evidence or visual SSOT refs have already been projected into `spec.md`, `/speckit.clarify` may clarify those requirement gaps from `spec.md`, but extraction remains outside clarification. -External design extraction is not a clarification responsibility. - -Visual Fidelity readiness applies to external-intake-derived and product-side -visual requirements. `checklists/visual.md` and its Visual Fidelity Evidence -Matrix are the single visual requirement-readiness record. Provider evidence -gaps remain intake blockers. The matrix must not define visual validation work, -screenshot comparison, visual diff, baseline capture, or final visual review. +- `schemas/` contains machine-readable behavior contracts. +- `validators/speckit_behavior_contract.py` contains pure in-memory behavior + cross-field checks. +- `tests/test_preset_contract.py` is the executable preset contract. + +## Preset Boundary + +The preset enriches existing Spec Kit stages. It does not own execution +orchestration or add a second implementation engine. + +| Stage | Owner | Durable output | +|---|---|---| +| `/speckit.constitution` | preset wrapper | Constitution and project Architecture | +| `/speckit.specify` | preset wrapper | requirement and UI/UX intent in `spec.md` | +| `/speckit.clarify` | preset wrapper | clarified requirement decisions | +| `/speckit.checklist` | preset wrapper | requirement-readiness gates | +| `/speckit.plan` | preset wrapper | design, behavior contracts, and validation design | +| `/speckit.tasks` | preset wrapper | executable checklist in `tasks.md` | +| `/speckit.analyze` | preset wrapper | read-only consistency findings | +| `/speckit.implement` | Spec Kit core | execution of `tasks.md` | + +`workflow-preset` MUST NOT declare, package, copy, or replace +`speckit.implement`. The active Spec Kit core version is the single source of +truth for the implementation command. A core implementation change therefore +requires no preset release. + +The preset MUST NOT introduce an implementation-specific reviewer command, +runtime role, persistent transfer protocol, execution manifest, worker result +protocol, manual execution queue, or implementation validator. + +## Artifact Pipeline + +The workflow is a producer-to-consumer pipeline: + +```text +spec.md + requirement gates + -> plan artifacts + BDD/UIF/validation design + -> tasks.md implementation and validation checklist + -> core /speckit.implement execution +``` -## Structured Artifact Rules +Tasks maps upstream artifacts into checklist items. It must not create another +planning system or execution protocol. -Machine-readable JSON artifacts are contracts, not prose examples. Stable -structured JSON artifacts require schemas in `schemas/` and focused validator -coverage in `validators/` when cross-field rules matter. +Examples: -Every schema or validator added for a preset artifact must be covered by -`tests/test_preset_contract.py`. +- A UI state in `spec.md` and `contracts/uif/` becomes a concrete UI + implementation task plus a UI acceptance task. +- A real-system path in `quickstart.md` becomes an integration/e2e task with + environment and evidence expectations. +- A persistence change becomes implementation and data-side-effect validation + tasks, followed by the final review scope. -## Cross-Agent Protocol Rules +## Final Code Review Gate -Shared multi-agent runtime behavior belongs in command source, schemas, and validators. -Test coverage for shared multi-agent behavior belongs in `tests/contracts/speckit-cross-agent-protocol.md`. -Commands may reference only their own profile. A profile inherits scheduling -protocol fields, not execution permissions from another command. -Commands must not reference `tests/` or `docs/` paths as runtime contract sources. +`/speckit.tasks` MUST append Final Code Review as the last mandatory phase of +`tasks.md`. It is an ordinary ordered task phase executed by the standard core +implementation command, not an independent runtime. -Persistent handoff orchestration belongs only to `/speckit.implement`. -Manifest files, handoff files, receipts, `allowed_write_paths`, dispatch -readiness, commit readiness, and manual worker queues must not be introduced -into `/speckit.specify`, `/speckit.plan`, `/speckit.tasks`, or -`/speckit.analyze`. +The phase must cover each applicable scope: -The implement handoff runtime profile lives in `commands/speckit.implement.md`; -test coverage lives in `tests/contracts/speckit-cross-agent-subagents.md`. -Both must stay aligned with the implement schemas and validator gates. +- planned `M + U` boundary; +- interface contracts; +- behavior contracts; +- UI state, viewport, and visual/IR consistency; +- data side effects; +- sequence consistency; +- asset bindings; +- integration/e2e evidence and unresolved blockers. -## Behavior-first extension rule +Completion requires the review tasks themselves to pass. No separate worker +result file or orchestration layer is required. -BDD and UIF artifacts need independent templates. A behavior-first extension -must not rely only on command prose to define: +## Structured Artifact Rules -- BDD draft files. -- UIF intent files. -- data fixture intent files. -- behavior scenario draft files. -- formal BDD contracts. -- Expected UIF contracts. -- behavior scenario, fixture, and assertion contracts. +Machine-readable JSON artifacts are contracts, not prose examples. Stable +behavior JSON artifacts require schemas in `schemas/` and focused coverage in +`validators/speckit_behavior_contract.py` when cross-field rules matter. + +Every packaged schema and validator must be covered by +`tests/test_preset_contract.py`. -Phase 0 behavior drafts and planning-phase formal contracts must be separate -artifacts with separate owners. If they are JSON, they also need schemas and -validator coverage. +## Cross-Agent Rules + +Planning and task derivation may use bounded, stage-local subagents when the +runtime supports them. The owning command remains the sole final writer for its +stage. Delegation metadata is transient derivation context and must not become +an implementation transfer format. + +Shared stage-local behavior is documented in +`tests/contracts/speckit-cross-agent-protocol.md`. Commands may reference only +their own stage profile. Commands must not use `tests/` or `docs/` paths as +runtime sources. ## Planning Artifact Boundaries -Keep `/speckit.plan` and `/speckit.tasks` as core-template wrappers unless the -contract tests are intentionally updated to change that rule. +Keep `/speckit.plan` and `/speckit.tasks` as core-template wrappers unless an +intentional contract change says otherwise. -Planning design artifacts remain optional and contextual: +Optional contextual design artifacts include: - `class-diagram.md` - `contracts/sequences.md` -Validation decisions are recorded in `research.md`, executable paths in -`quickstart.md`, and the BDD Plan closeout maps them to Required Cases in -`behavior/behavior-testability.md`. `/speckit.tasks` derives concrete tasks from -that READY mapping. Do not add a standalone `test-plan.md`. - -Planning Readiness is aggregated at runtime from metadata-bearing requirement -gates. It is not a durable artifact and must never be written as -`planning-readiness.md`. +Validation decisions stay in `research.md`, executable paths stay in +`quickstart.md`, and BDD Plan closeout maps them into +`behavior/behavior-testability.md`. `/speckit.tasks` derives unit, contract, +integration, UI acceptance, real-system e2e, and review tasks from that mapping. +Do not add a standalone `test-plan.md`. -`behavior/behavior-testability.md` is a permitted planning artifact, not a test -strategy document. It contains the task-derivation matrix and READY/BLOCKED -decision; it must not duplicate requirement prose, provider intake, or -clarification. +## External Intake Boundary -Keep product requirements in `spec.md`, including explicit NFR assumptions; -NFR readiness belongs in `spec.md` product requirements rather than downstream -planning guesses. Keep domain model details in `data-model.md`, interface -schemas in `contracts/`, and validation run guidance in `quickstart.md`. +External source capture, provider access, rendered HTML, structured IR, +screenshots, authentication, and provider evidence generation belong to +extensions. This preset only consumes confirmed refs already projected into +requirements and readiness artifacts. -For visual planning, research.md records visual/IR source refs, readiness inputs, accepted exception refs, related contract paths, and unresolved blocker refs only; it must not duplicate the Visual Fidelity Evidence Matrix or define visual validation strategy, screenshot comparison, visual diff, baseline capture, or final visual review. contracts formalize visual interaction and state constraints by referencing accepted visual items, source refs, structured IR refs, and accepted exception refs; contracts/sequences.md records visual state flow only when it affects cross-boundary sequencing, async callbacks, retry, rollback, compensation, or error propagation, and must not define visual style, tokens, layout breakpoints, screenshot matrices, or validation commands. +Provider evidence gaps remain intake blockers. Product decision gaps return to +clarification. Neither planning nor implementation may silently manufacture +missing evidence. -## Handoff Extension Rules +## Release And Integration Boundary -Handoff extensions must update schema, validator, command, and cross-agent documentation together. -Any new implementation-stage artifact that Worker -Agents may read or write must be reflected in: +The source repository owns development, tests, tags, releases, and release +artifacts. The Spec Kit fork owns only a reproducible bundled snapshot and +catalog metadata. -- `schemas/speckit.implement.*.schema.json` when the JSON contract changes. -- `validators/speckit_implement_contract.py` when cross-field validation changes. -- `commands/speckit.implement.md` when Core, Vertical Planner, or Worker - behavior changes. -- `tests/contracts/speckit-cross-agent-protocol.md` when shared profile behavior changes. -- `tests/contracts/speckit-cross-agent-subagents.md` when implement worker prompts, - context digest rules, shard rules, or path rules change. -- `tests/test_preset_contract.py` for all of the above. +Integration must use an immutable release: -## Release Discipline +1. publish a new source version; +2. record the source repository, version, commit SHA, artifact URL, and artifact + SHA-256; +3. extract the bundled snapshot without edits; +4. verify every bundled file hash against the release manifest; +5. ensure bundled and `--from ` installations are identical. -Do not bump preset version or release archive URLs until release preparation. -Unreleased behavior belongs under `## Unreleased` in `CHANGELOG.md`. +Never change a published version in place or modify the bundled snapshot after +integration. -## Verification +## Validation -After changing preset commands, templates, schemas, validators, governance docs, -or public documentation, run: +Run: ```bash python3 -m unittest tests/test_preset_contract.py ``` -If the system Python lacks development dependencies, use a local virtual -environment and the same unittest command from that environment. +Release preparation must also run the install smoke checks in +`.github/workflows/preset-artifact.yml`. diff --git a/presets/workflow-preset/preset.yml b/presets/workflow-preset/preset.yml index f40d460d33..df777a9069 100644 --- a/presets/workflow-preset/preset.yml +++ b/presets/workflow-preset/preset.yml @@ -2,9 +2,9 @@ schema_version: '1.0' preset: id: workflow-preset name: Workflow Preset - version: 2.0.0 + version: 3.0.0 description: Constitution-managed architecture, behavior-first specification, design - artifacts, and scoped change governance + artifacts, and execution-ready task mapping author: bigsmartben repository: https://github.com/bigsmartben/spec-kit-workflow-preset license: MIT @@ -76,12 +76,6 @@ provides: description: Require READY behavior testability and derive complete task chains replaces: speckit.tasks strategy: wrap - - type: command - name: speckit.implement - file: commands/speckit.implement.md - description: Execute the implementation plan defined in tasks.md - replaces: speckit.implement - strategy: replace - type: template name: behavior-bdd-draft-template file: templates/behavior/bdd-draft.feature @@ -215,4 +209,3 @@ tags: - bdd - planning - implementation -- handoff diff --git a/presets/workflow-preset/tests/contracts/speckit-cross-agent-protocol.md b/presets/workflow-preset/tests/contracts/speckit-cross-agent-protocol.md index 28391cff11..a92aa3958a 100644 --- a/presets/workflow-preset/tests/contracts/speckit-cross-agent-protocol.md +++ b/presets/workflow-preset/tests/contracts/speckit-cross-agent-protocol.md @@ -1,66 +1,77 @@ # Spec Kit Cross-Agent Protocol ## Purpose -Constrain observable workflow behavior with small stage protocols instead of long global agent memory rules. The protocol constrains inputs, outputs, file access, readiness gates, stop conditions, and fallback behavior. It does not constrain internal reasoning. + +Constrain stage-local delegation without defining a second implementation +runtime. The protocol covers bounded inputs, outputs, readiness gates, stop +conditions, and sequential fallback. ## BaseSubagentProtocol -Every command profile defines these fields: - -- `stage`: command-local lifecycle stage. -- `owner_agent`: agent role that owns final writes and readiness decisions. -- `input_scope`: exact artifacts, sections, IDs, or path families assigned to the stage. -- `allowed_reads`: files, directories, or scoped excerpts the role may inspect. -- `allowed_writes`: files, directories, or artifact families the role may create or update. -- `output_contract`: draft, finding, blocker, or final artifact shape. -- `validation_gate`: schema, validator, checklist, or blocker-code gate before the next stage. -- `stop_conditions`: deterministic blockers that stop the current role. -- `fallback`: sequential simulation or manual queue behavior when delegated agents are unavailable. + +Every preset-owned command profile defines: + +- `stage` +- `owner_agent` +- `input_scope` +- `allowed_reads` +- `allowed_writes` +- `output_contract` +- `validation_gate` +- `stop_conditions` +- `fallback` ## Command Profiles ### `speckit.specify.single_core` + - `stage`: requirement projection. - `owner_agent`: Specify Core Agent. -- `input_scope`: user prompt, product notes, confirmed external intake refs, visual SSOT refs, HTML SSOT refs, structured IR refs, screenshots, and visual proof refs. -- `allowed_reads`: command inputs and existing requirement context selected by core Spec Kit behavior. - `allowed_writes`: `spec.md` only. -- `output_contract`: stakeholder-readable requirements with explicit source-backed facts, assumptions, visual/UI status, and provider blockers. -- `validation_gate`: specification quality validation in `/speckit.specify`. -- `stop_conditions`: missing feature description, unsupported inference, or provider evidence treated as product semantics. -- `fallback`: single-core execution; no persistent handoff, receipt, or worker queue. +- `output_contract`: source-aware product, behavior, visual, and UI/UX + requirements. +- `fallback`: single-core execution. ### `speckit.plan.stage_local_planning` + - `stage`: Phase 0 behavior projection and Phase 1 planning. - `owner_agent`: Plan Core Agent. -- `input_scope`: checklist-approved requirement sections, behavior readiness rows, planning inputs, and assigned artifact families. -- `allowed_reads`: scoped planning inputs declared per delegated payload. +- `input_scope`: checklist-approved requirements and assigned planning artifact + families. - `allowed_writes`: final planning artifacts owned by `/speckit.plan`. -- `output_contract`: draft behavior artifacts, formal contract drafts, design artifact drafts, blockers, and `context_gaps`. -- `validation_gate`: checklist PASS preflight, matching behavior schemas, and planning blocker report. -- `stop_conditions`: failed checklist gate, required case projection gaps, or unresolved planning `context_gaps`. -- `fallback`: Plan Core Agent sequentially simulates each assigned scope and preserves final-write ownership. +- `output_contract`: behavior drafts, formal contracts, design drafts, + validation design, blockers, and `context_gaps`. +- `validation_gate`: checklist PASS, matching behavior schemas, and planning + blocker aggregation. +- `fallback`: the Plan Core Agent processes one assigned scope at a time and + preserves final-write ownership. ### `speckit.tasks.stage_local_derivation` -- `stage`: task derivation. + +- `stage`: upstream-artifact-to-checklist mapping. - `owner_agent`: Tasks Core Agent. -- `input_scope`: user stories, behavior contracts, interface contracts, research decisions, quickstart validation paths, visual readiness rows, visual/IR traceability refs, and review scopes. -- `allowed_reads`: scoped derivation payloads; no full artifact tree unless the payload explicitly lists it. +- `input_scope`: user stories, behavior and interface contracts, research + decisions, quickstart paths, UI/visual readiness, and review scopes. +- `allowed_reads`: only the scoped inputs declared for each derivation unit. - `allowed_writes`: `tasks.md` only. -- `output_contract`: task candidates, evidence refs, source refs, blockers, and `context_gaps`. -- `validation_gate`: task-derivation blocker aggregation and existing checklist format. -- `stop_conditions`: missing Required case coverage, missing required provider evidence, or unresolved task-derivation `context_gaps`. -- `fallback`: Tasks Core Agent processes one assigned scope at a time; no handoff, receipt, write-path metadata, or worker dispatch. +- `output_contract`: ordered implementation, validation, integration/e2e, and + Final Code Review checklist items, plus blockers and `context_gaps`. +- `validation_gate`: source/evidence binding, dependency ordering, final review + placement, and blocker aggregation. +- `stop_conditions`: missing required case coverage, missing provider evidence, + or unresolved derivation context. +- `fallback`: the Tasks Core Agent processes one scope at a time. ### `speckit.analyze.read_only_parallel_review` + - `stage`: vertical consistency analysis. - `owner_agent`: Analyze Core Agent. -- `input_scope`: existing planning artifacts and stable IDs such as `CASE-`, `SCN-`, `UIF-`, `FIX-`, `AST-`, and `BLK-`. -- `allowed_reads`: bounded artifact inventory, ID maps, and surrounding prose only when an ID link is missing or ambiguous. - `allowed_writes`: none. - `output_contract`: findings, blockers, warnings, and closed-chain summary. -- `validation_gate`: read-only consistency checks by source artifact and target artifact. -- `stop_conditions`: missing source artifact, broken traceability, or first blocker that proves a downstream link cannot close. -- `fallback`: sequential read-only review; no durable artifact writes. +- `fallback`: sequential read-only review. ## Permission Boundary -Profiles inherit the scheduling protocol, not execution permissions. A command must reference only its own profile. + +Profiles share only the stage-local delegation shape. They do not grant +implementation permissions and do not define persistent execution artifacts. +The implementation command and its execution behavior are owned exclusively by +the current Spec Kit core. diff --git a/presets/workflow-preset/tests/test_preset_contract.py b/presets/workflow-preset/tests/test_preset_contract.py index 4b81e9d5fd..5ed90a29fa 100644 --- a/presets/workflow-preset/tests/test_preset_contract.py +++ b/presets/workflow-preset/tests/test_preset_contract.py @@ -30,7 +30,6 @@ ANALYZE_COMMAND_PATH = REPO_ROOT / "commands" / "speckit.analyze.md" PLAN_COMMAND_PATH = REPO_ROOT / "commands" / "speckit.plan.md" TASKS_COMMAND_PATH = REPO_ROOT / "commands" / "speckit.tasks.md" -IMPLEMENT_COMMAND_PATH = REPO_ROOT / "commands" / "speckit.implement.md" CONSTITUTION_TEMPLATE_PATH = REPO_ROOT / "templates" / "constitution-template.md" ARCHITECTURE_TEMPLATE_PATH = REPO_ROOT / "templates" / "architecture-template.md" PLAN_TEMPLATE_PATH = REPO_ROOT / "templates" / "plan-template.md" @@ -118,6 +117,14 @@ / "requirements" / "visual-gate.md", } +REMOVED_IMPLEMENT_RUNTIME_PATHS = ( + REPO_ROOT / "commands" / "speckit.implement.md", + REPO_ROOT / "schemas" / "speckit.implement.manifest.v1.schema.json", + REPO_ROOT / "schemas" / "speckit.implement.handoff.v2.schema.json", + REPO_ROOT / "schemas" / "speckit.implement.receipt.v1.schema.json", + REPO_ROOT / "validators" / "speckit_implement_contract.py", + REPO_ROOT / "tests" / "contracts" / "speckit-cross-agent-subagents.md", +) FEATURE_PATH = "specs/001-demo" @@ -316,6 +323,61 @@ def minimal_exception_behavior_assertions_with_intent(intent: str) -> dict: class PresetContractTests(unittest.TestCase): + def test_manifest_excludes_implement_override_and_runtime(self) -> None: + manifest = yaml.safe_load(PRESET_PATH.read_text(encoding="utf-8")) + entries = manifest["provides"]["templates"] + command_entries = [entry for entry in entries if entry["type"] == "command"] + template_entries = [entry for entry in entries if entry["type"] == "template"] + + self.assertEqual(7, len(command_entries)) + self.assertEqual(24, len(template_entries)) + self.assertEqual(31, len(entries)) + self.assertNotIn( + "speckit.implement", + {entry["name"] for entry in command_entries}, + ) + self.assertFalse( + any("speckit.implement" in entry["file"] for entry in entries) + ) + for path in REMOVED_IMPLEMENT_RUNTIME_PATHS: + self.assertFalse(path.exists(), path) + + def test_tasks_end_with_mandatory_code_review_without_runtime_protocol(self) -> None: + tasks = TASKS_COMMAND_PATH.read_text(encoding="utf-8") + self.assertIn("Final Code Review", tasks) + self.assertIn("append the final phase after user-story tasks", tasks) + self.assertIn( + "`boundary`, `interface_contract`, `visual`, `data_side_effect`, " + "`behavior_contract`, `sequence_consistency`, and `asset_binding`", + tasks, + ) + for forbidden in ( + "speckit.implement.handoff", + "speckit.implement.receipt", + "handoff-manifest.json", + "Manual Worker Queue", + "Reviewer runtime", + ): + self.assertNotIn(forbidden, tasks) + + def test_current_docs_define_core_implement_ownership(self) -> None: + current_docs = ( + README_PATH.read_text(encoding="utf-8"), + EXTENSION_GOVERNANCE_PATH.read_text(encoding="utf-8"), + AGENTS_PATH.read_text(encoding="utf-8"), + CROSS_AGENT_PROTOCOL_PATH.read_text(encoding="utf-8"), + ) + for document in current_docs: + self.assertIn("Spec Kit core", document) + for forbidden in ( + "speckit.implement.persistent_handoff_orchestration", + "Manual Worker Queue", + "Vertical Planner Agent", + "Worker Agent mode", + "speckit.implement.receipt.v1", + ): + self.assertNotIn(forbidden, document) + def test_requirement_gate_and_clarify_repair_contract(self) -> None: checklist = CHECKLIST_COMMAND_PATH.read_text(encoding="utf-8") clarify = CLARIFY_COMMAND_PATH.read_text(encoding="utf-8") @@ -409,16 +471,13 @@ def test_public_docs_define_two_stage_ownership(self) -> None: readme = README_PATH.read_text(encoding="utf-8") governance = EXTENSION_GOVERNANCE_PATH.read_text(encoding="utf-8") - self.assertIn("multi-domain requirement gates", readme) - self.assertIn("no `planning-readiness.md` is generated", readme) - self.assertIn("`behavior/behavior-testability.md` is generated at plan closeout", readme) - self.assertIn("provider evidence remains an intake blocker", readme) + self.assertIn("requirement-domain readiness gates", readme) + self.assertIn("behavior/behavior-testability.md", readme) + self.assertIn("Missing provider evidence remains an intake blocker", readme) - self.assertIn("requirement-gate recomputation only", governance) - self.assertIn("requirements, behavior, UX, security, NFR, and visual requirement gates", governance) + self.assertIn("requirement-readiness gates", governance) self.assertIn("BDD Plan closeout", governance) - self.assertIn("must never be written as\n`planning-readiness.md`", governance) - self.assertIn("`behavior/behavior-testability.md` is a permitted planning artifact", governance) + self.assertIn("behavior/behavior-testability.md", governance) def test_plan_command_wrapper_contract(self) -> None: @@ -512,20 +571,13 @@ def test_plan_visual_substage_enhancement_contract(self) -> None: for document in (readme, governance): self.assertIn("research.md", document) - self.assertIn("visual/IR source refs", document) - self.assertIn("contracts formalize visual interaction and state constraints", document) - self.assertIn("contracts/sequences.md records visual state flow only when it affects cross-boundary sequencing", document) - self.assertNotIn("research.md records visual validation decisions", document) + self.assertIn("visual/IR", document) + self.assertIn("contracts/sequences.md", document) self.assertIn( "fixed R/M/U/O model: R is Repository / Workspace, M is Module / Capability, U is Unit / Design Object, and O is Operation / Detail", readme, ) - self.assertIn( - "Blocks constitution writes when a generated draft changes the fixed R/M/U/O mapping", - readme, - ) - self.assertIn("single-file project Architecture lifecycle", readme) self.assertIn("System Boundary -> Conceptual Model", readme) def test_constitution_change_scope_granularity_contract(self) -> None: @@ -620,7 +672,6 @@ def test_change_scope_granularity_stage_references(self) -> None: plan = PLAN_COMMAND_PATH.read_text(encoding="utf-8") tasks = TASKS_COMMAND_PATH.read_text(encoding="utf-8") analyze = ANALYZE_COMMAND_PATH.read_text(encoding="utf-8") - implement = IMPLEMENT_COMMAND_PATH.read_text(encoding="utf-8") self.assertIn("Apply the constitution's Change Scope Granularity principle.", plan) self.assertIn("During planning, lock the change scope to `M + U`", plan) @@ -634,8 +685,7 @@ def test_change_scope_granularity_stage_references(self) -> None: self.assertIn("Check that tasks preserve the planned `M + U` scope.", analyze) self.assertIn("Report missing, widened, or ambiguous scope boundaries as blockers.", analyze) - self.assertIn("Read plan.md for tech stack, architecture, and file structure", implement) - self.assertIn("Respect dependencies", implement) + self.assertFalse((REPO_ROOT / "commands" / "speckit.implement.md").exists()) def test_preplanning_commands_do_not_infer_scope_granularity(self) -> None: for path in (SPECIFY_COMMAND_PATH, CLARIFY_COMMAND_PATH, CHECKLIST_COMMAND_PATH): @@ -1026,7 +1076,6 @@ def test_behavior_first_plan_and_tasks_awareness_contract(self) -> None: plan = PLAN_COMMAND_PATH.read_text(encoding="utf-8") tasks = TASKS_COMMAND_PATH.read_text(encoding="utf-8") template = PLAN_TEMPLATE_PATH.read_text(encoding="utf-8") - implement = IMPLEMENT_COMMAND_PATH.read_text(encoding="utf-8") for term in ( "behavior/bdd.draft.feature", @@ -1302,7 +1351,6 @@ def test_actual_uif_artifacts_are_not_part_of_preset_contract(self) -> None: ANALYZE_COMMAND_PATH, PLAN_COMMAND_PATH, TASKS_COMMAND_PATH, - IMPLEMENT_COMMAND_PATH, PRESET_PATH, ] forbidden_terms = [ @@ -2182,9 +2230,24 @@ def test_github_actions_artifact_release_and_integration_pr_workflow(self) -> No "tests/test_presets.py", "__pycache__", ".pyc", - "*.pyc", "ZipInfo", "1980, 1, 1", + 'MANIFEST_NAME="spec-kit-workflow-preset-v${VERSION}.manifest.json"', + '"source_commit": source_commit', + '"sha256": zip_sha256', + "Verify release manifest", + "validators/speckit_behavior_contract.py", + '"requirements-dev.txt"', + '"tests"', + "test ! -e .specify/presets/workflow-preset/commands/speckit.implement.md", + "core_implement_sha", + "WORKFLOW_PRESET_MANIFEST_URL", + "presets/workflow-preset.release.json", + 'entry["source_commit"] = release_manifest["source_commit"]', + 'entry["sha256"] = release_manifest["artifact"]["sha256"]', + "curl --fail --location", + "archive.extractall", + 'cmp "${ZIP_PATH}" "${existing_dir}/${ZIP_NAME}"', "github.ref_type == 'tag' || (github.event_name == 'workflow_dispatch' && env.CREATE_INTEGRATION_PR == 'true')", "env.CREATE_INTEGRATION_PR == 'true'", "refs/tags/v${VERSION}", @@ -2204,10 +2267,10 @@ def test_github_actions_artifact_release_and_integration_pr_workflow(self) -> No "client_payload[download_url]", "repository_dispatch", "repos/bigsmartben/spec-kit/dispatches", - "tests/contracts/speckit-cross-agent-protocol.md", - "tests/contracts/speckit-cross-agent-subagents.md", "::warning::SPEC_KIT_FORK_DISPATCH_TOKEN", "skipping integration PR", + "gh release upload \"${TAG_NAME}\" \"${ZIP_PATH}\" --clobber", + "\"${GITHUB_WORKSPACE}/\" \"${fork_dir}/spec-kit/presets/workflow-preset/\"", ] for term in forbidden_terms: self.assertNotIn(term, workflow_text) diff --git a/tests/integrations/test_cli.py b/tests/integrations/test_cli.py index f9eb8e78f3..733c498656 100644 --- a/tests/integrations/test_cli.py +++ b/tests/integrations/test_cli.py @@ -1070,6 +1070,8 @@ def test_workflow_preset_registers_commands_and_composes_wrappers(self, tmp_path assert (preset_dir / ".composed" / "speckit.plan.md").exists() assert (preset_dir / ".composed" / "speckit.tasks.md").exists() assert (preset_dir / ".composed" / "speckit.analyze.md").exists() + assert not (preset_dir / "commands" / "speckit.implement.md").exists() + assert not (preset_dir / ".composed" / "speckit.implement.md").exists() preset_registry = json.loads((project / ".specify" / "presets" / ".registry").read_text()) workflow_entry = preset_registry["presets"]["workflow-preset"] @@ -1086,7 +1088,6 @@ def test_workflow_preset_registers_commands_and_composes_wrappers(self, tmp_path "speckit.analyze", "speckit.plan", "speckit.tasks", - "speckit.implement", } assert set(workflow_entry["registered_commands"]["claude"]) == expected_preset_commands diff --git a/tests/test_presets.py b/tests/test_presets.py index e5231230fc..ec93dfd7f4 100644 --- a/tests/test_presets.py +++ b/tests/test_presets.py @@ -11,6 +11,7 @@ """ import pytest +import hashlib import io import json import tempfile @@ -4650,13 +4651,17 @@ def test_workflow_preset_catalog_matches_manifest(self): assert catalog_updated_at >= datetime(2026, 6, 18, tzinfo=timezone.utc) assert entry["bundled"] is True - assert entry["version"] == "2.0.0" + assert entry["version"] == "3.0.0" assert entry["version"] == manifest["preset"]["version"] assert entry["repository"] == manifest["preset"]["repository"] assert entry["requires"]["speckit_version"] == manifest["requires"]["speckit_version"] assert entry["provides"]["commands"] == command_count assert entry["provides"]["templates"] == template_count + assert command_count == 7 + assert template_count == 24 assert entry["tags"] == manifest["tags"] + assert len(entry["source_commit"]) == 40 + assert entry["sha256"] def test_workflow_preset_community_catalog_matches_manifest(self): """workflow-preset community catalog entry matches the released preset.""" @@ -4680,10 +4685,70 @@ def test_workflow_preset_community_catalog_matches_manifest(self): assert entry["requires"]["speckit_version"] == manifest["requires"]["speckit_version"] assert entry["provides"]["commands"] == command_count assert entry["provides"]["templates"] == template_count + assert command_count == 7 + assert template_count == 24 assert entry["tags"] == manifest["tags"] + assert len(entry["source_commit"]) == 40 + assert entry["sha256"] + + def test_workflow_preset_snapshot_matches_release_manifest(self): + """Bundled files are an unmodified snapshot of the declared release.""" + root = Path(__file__).parent.parent + snapshot_root = root / "presets" / "workflow-preset" + release_manifest = json.loads( + (root / "presets" / "workflow-preset.release.json").read_text( + encoding="utf-8" + ) + ) + bundled_catalog = json.loads( + (root / "presets" / "catalog.json").read_text(encoding="utf-8") + )["presets"]["workflow-preset"] + community_catalog = json.loads( + (root / "presets" / "catalog.community.json").read_text( + encoding="utf-8" + ) + )["presets"]["workflow-preset"] + + expected_hashes = { + entry["path"]: entry["sha256"] + for entry in release_manifest["files"] + } + actual_paths = { + path.relative_to(snapshot_root).as_posix() + for path in snapshot_root.rglob("*") + if path.is_file() + and "__pycache__" not in path.parts + and path.suffix not in {".pyc", ".pyo"} + } + + assert actual_paths == set(expected_hashes) + for relative_path, expected_hash in expected_hashes.items(): + assert ( + hashlib.sha256((snapshot_root / relative_path).read_bytes()).hexdigest() + == expected_hash + ) + + manifest = yaml.safe_load( + (snapshot_root / "preset.yml").read_text(encoding="utf-8") + ) + assert release_manifest["version"] == manifest["preset"]["version"] + assert release_manifest["source_repository"] == manifest["preset"]["repository"] + assert bundled_catalog["source_commit"] == release_manifest["source_commit"] + assert community_catalog["source_commit"] == release_manifest["source_commit"] + assert bundled_catalog["sha256"] == release_manifest["artifact"]["sha256"] + assert community_catalog["sha256"] == release_manifest["artifact"]["sha256"] + + command_names = { + entry["name"] + for entry in manifest["provides"]["templates"] + if entry["type"] == "command" + } + assert len(command_names) == 7 + assert "speckit.implement" not in command_names + assert not (snapshot_root / "commands" / "speckit.implement.md").exists() def test_workflow_preset_integration_release_payload_contract(self): - """Workflow preset release dispatch contract stays aligned with preset repo.""" + """Workflow validates immutable release and bundled-install parity.""" workflow_path = ( Path(__file__).parent.parent / ".github" @@ -4694,20 +4759,35 @@ def test_workflow_preset_integration_release_payload_contract(self): workflow = yaml.safe_load(workflow_text) on_config = workflow.get("on", workflow.get(True)) - assert on_config["repository_dispatch"]["types"] == ["workflow-preset-release"] - assert "github.event.client_payload.preset_version" in workflow_text - assert "github.event.client_payload.preset_download_url" in workflow_text + assert "repository_dispatch" not in on_config + assert "workflow_dispatch" in on_config + assert "preset_manifest_url" in on_config["workflow_dispatch"]["inputs"] assert ( "releases/download/v${preset_version}/" "spec-kit-workflow-preset-v${preset_version}.zip" ) in workflow_text + assert ( + "releases/download/v${preset_version}/" + "spec-kit-workflow-preset-v${preset_version}.manifest.json" + ) in workflow_text assert "^[0-9]+\\.[0-9]+\\.[0-9]+$" in workflow_text - assert "/workflow-preset.zip" not in workflow_text + assert 'release_manifest["artifact"]["sha256"]' in workflow_text + assert 'entry["path"]: entry["sha256"]' in workflow_text + assert "diff -ru" in workflow_text assert "test -f .specify/presets/workflow-preset/templates/tasks-template.md" not in workflow_text assert "specify preset resolve tasks-template" in workflow_text assert 'grep -F "(top layer from: core)" preset-resolve-tasks-template.txt' in workflow_text assert "test -f .specify/templates/tasks-template.md" in workflow_text - assert "## Pre-Execution Checks" in workflow_text + assert "core_implement_sha" in workflow_text + assert ( + 'test "${core_implement_sha}" = "$(sha256sum ' + ".claude/skills/speckit-implement/SKILL.md" + in workflow_text + ) + assert ( + "test ! -e .specify/presets/workflow-preset/commands/speckit.implement.md" + in workflow_text + ) assert "speckit.implement.receipt.v1.schema.json" not in workflow_text def test_community_smoke_checks_wheel_assets_and_extension_dev_reinstall(self):