@deftai/directive-content 0.60.0 → 0.61.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.githooks/pre-commit +10 -128
- package/.githooks/pre-push +8 -109
- package/UPGRADING.md +18 -2
- package/package.json +1 -1
- package/packs/skills/skills-pack-0.1.json +22 -22
- package/packs/strategies/strategies-pack-0.1.json +19 -19
- package/scm/github.md +17 -4
- package/skills/deft-directive-setup/SKILL.md +24 -15
- package/strategies/speckit.md +14 -14
- package/strategies/v0-20-contract.md +12 -1
- package/tasks/project.yml +10 -0
- package/templates/agents-entry.md +1 -1
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
"readme"
|
|
12
12
|
],
|
|
13
13
|
"path": "strategies/README.md",
|
|
14
|
-
"body": "# Strategies\n\nDevelopment strategies define the workflow from idea to implementation.\n\n## Available Strategies\n\n| Strategy | Command | Type | Use Case | Phases |\n|----------|---------|------|----------|--------|\n| [interview.md](./interview.md) | `/deft:run:interview` | spec-generating | Standard projects (default) | Sizing gate: Light (Interview
|
|
14
|
+
"body": "# Strategies\n\nDevelopment strategies define the workflow from idea to implementation.\n\n## Available Strategies\n\n| Strategy | Command | Type | Use Case | Phases |\n|----------|---------|------|----------|--------|\n| [interview.md](./interview.md) | `/deft:run:interview` | spec-generating | Standard projects (default) | Sizing gate: Light (Interview → SPECIFICATION) or Full (Interview → PRD → SPECIFICATION) |\n| [yolo.md](./yolo.md) | `/deft:run:yolo` | spec-generating | Quick prototyping | Auto-pilot sizing gate: Light or Full (Johnbot picks) |\n| [speckit.md](./speckit.md) | `/deft:run:speckit` | spec-generating | Large/complex projects | Principles → Specify → Plan → Phase/Epic Scope → Story Readiness → Implement |\n| [map.md](./map.md) | `/deft:run:map` | preparatory | Existing codebases | Map → Chaining Gate |\n| [discuss.md](./discuss.md) | `/deft:run:discuss` | preparatory | Alignment before planning | Feynman technique → locked decisions → Chaining Gate |\n| [probe.md](./probe.md) | `/deft:run:probe` | preparatory | Adversarial plan stress-testing | Walk decision tree → challenge assumptions → surface risks → Chaining Gate |\n| [research.md](./research.md) | `/deft:run:research` | preparatory | Pre-implementation research | Research → Don't Hand-Roll + Common Pitfalls → Chaining Gate |\n| [roadmap.md](./roadmap.md) | `/deft:run:roadmap` | preparatory | Roadmap maintenance | Discover → Triage → Cleanup |\n| [bdd.md](./bdd.md) | `/deft:run:bdd` | preparatory | Acceptance-test-first development | Scenarios → Failing Tests → Lock Decisions → Spec → Chaining Gate |\n| [rapid.md](./rapid.md) | `/deft:run:rapid` | spec-generating | Quick prototypes | Forced-Light path |\n| [enterprise.md](./enterprise.md) | `/deft:run:enterprise` | spec-generating | Compliance-heavy | Forced-Full path |\n\n## Strategy Types\n\nEvery strategy has a **Type** that determines its behavior in the\n[chaining gate](./interview.md#chaining-gate):\n\n- **`preparatory`** — Produces artifacts that inform spec generation (research docs,\n context files, mapping docs). On completion, returns to the chaining gate so the user\n can run additional strategies or proceed to spec generation. Can be run multiple times.\n Some preparatory strategies (currently `map.md`) also support **standalone** invocation\n via `/deft:run:<name>` — when invoked outside an interview context, they present their\n own next-step options instead of returning to the chaining gate. See each strategy file\n for standalone support.\n- **`spec-generating`** — Produces v0.20-conformant output per [v0-20-contract.md](./v0-20-contract.md) (lifecycle folders + PROJECT-DEFINITION.vbrief.json + date-prefixed proposed/ scope vBRIEFs only; SPECIFICATION.md/PROJECT.md as deprecation stubs or omitted). Selecting one at the chaining gate switches the pipeline to that strategy’s spec flow.\n\nCustom strategies MUST declare their type in this table. If the `Type` column is missing,\nthe chaining gate cannot include the strategy.\n\n## v0.20 Output Contract (for spec-generating strategies)\n\nAll spec-generating strategies (interview, yolo, speckit, rapid, enterprise) MUST produce output conforming to [v0-20-contract.md](./v0-20-contract.md):\n\n- Five vbrief/ lifecycle folders (proposed/ pending/ active/ completed/ cancelled/)\n- vbrief/PROJECT-DEFINITION.vbrief.json (full)\n- Scope vBRIEFs ONLY as date-prefixed in vbrief/proposed/YYYY-MM-DD-*.vbrief.json\n- Never dual-write legacy vbrief/specification.vbrief.json\n- SPECIFICATION.md/PROJECT.md only as deprecation-redirect stubs (banner + sentinel) or omitted\n\nThis contract is the single source of truth for s1-contract and the #1166 migrations (s3-s5). Preparatory strategies follow the same dated proposed/ rule when emitting vBRIEFs.\n\n\n## Selecting a Strategy\n\nUse a slash command:\n\n```\n/deft:run:interview my-project\n```\n\nOr specify in `project.md`:\n\n```markdown\n## Strategy\nUse [strategies/interview.md](../strategies/interview.md) for this project.\n```\n\n**Naming rule:** `/deft:run:<x>` always maps to `strategies/<x>.md`. Custom strategies follow the same pattern.\n\n## Creating Custom Strategies\n\nA strategy file defines:\n\n1. **When to use** — project types, team sizes, constraints\n2. **Workflow phases** — ordered steps with transition criteria\n3. **Artifacts** — what documents are produced\n4. **Agent behavior** — how AI should conduct each phase\n\nName your file `strategies/<name>.md` and invoke it with `/deft:run:<name>`.\n"
|
|
15
15
|
},
|
|
16
16
|
{
|
|
17
17
|
"id": "artifact-guards",
|
|
@@ -21,7 +21,7 @@
|
|
|
21
21
|
"artifact-guards"
|
|
22
22
|
],
|
|
23
23
|
"path": "strategies/artifact-guards.md",
|
|
24
|
-
"body": "# Artifact Idempotency Guards\n\nShared guard rules for strategies that write to vBRIEF artifacts. Referenced by individual strategy files to prevent silent overwrites of approved or completed work.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD,
|
|
24
|
+
"body": "# Artifact Idempotency Guards\n\nShared guard rules for strategies that write to vBRIEF artifacts. Referenced by individual strategy files to prevent silent overwrites of approved or completed work.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**⚠️ See also**: [vbrief/vbrief.md](../vbrief/vbrief.md) | [strategies/v0-20-contract.md](./v0-20-contract.md) | [strategies/interview.md](./interview.md)\n\n---\n\n## When to Use\n\nThis file is not a standalone strategy — it is a shared guard referenced by other strategies. It activates automatically when a strategy writes to vBRIEF artifacts.\n\n- ! Referenced by spec-generating strategies: [speckit](./speckit.md), [enterprise](./enterprise.md), [rapid](./rapid.md)\n- ! Referenced by preparatory strategies: [bdd](./bdd.md), [discuss](./discuss.md), [research](./research.md), [map](./map.md), [probe](./probe.md)\n\n## Workflow\n\n1. Strategy reaches its output step\n2. Strategy follows the appropriate guard (Spec-Generating or Preparatory) from this file\n3. Guard checks file existence and status, prompts user if needed\n4. Strategy proceeds with the write or aborts based on user response\n\n---\n\n## Spec-Generating Guard (Full)\n\nApplies to strategies that write to `PROJECT-DEFINITION.vbrief.json` (⊗ never `specification.vbrief.json` per [v0-20-contract.md](./v0-20-contract.md)): **speckit**, **enterprise**, **rapid**.\n\n! Before writing to `vbrief/PROJECT-DEFINITION.vbrief.json`, the strategy MUST perform the following checks (⊗ Never target the legacy `specification.vbrief.json`):\n\n1. ! **Check existence**: Does the target file already exist?\n - If NO: proceed with the write — no guard needed.\n - If YES: continue to step 2.\n\n2. ! **Read `plan.status`**: Parse the existing file and read `plan.status`.\n\n3. ! **Status: `approved` or `completed`**: Refuse to overwrite without explicit user confirmation.\n - ! Display: \"This artifact has status `{status}`. Overwriting will reset it to `draft` and discard approved/completed state. Continue? (yes/no)\"\n - ! Accept only explicit affirmative (`yes`, `confirmed`) — not vague responses (`proceed`, `ok`, `go ahead`)\n - ⊗ Silently overwrite an approved or completed artifact\n\n4. ! **Status: `draft` or `running`**: Warn and ask before overwriting.\n - ! Display: \"A `{status}` version of this artifact already exists. Replace it? (yes/no)\"\n - ~ If the user declines, offer to enrich (merge narratives) instead of replacing\n\n5. ! **Narrative preservation**: When overwriting `PROJECT-DEFINITION.vbrief.json`, read existing `narratives` keys first. If the strategy only writes a subset of narratives (e.g. speckit Phase 1 writes only `Principles`), merge the new narrative into the existing set — do NOT replace all narratives with only the new key.\n - ⊗ Overwrite all `PROJECT-DEFINITION.vbrief.json` narratives when the strategy only produces a single narrative key\n\n---\n\n## Preparatory Guard (Light)\n\nApplies to strategies that write scoped vBRIEFs to `vbrief/proposed/`: **bdd**, **discuss**, **research**, **map**.\n\n! Before writing a scope vBRIEF to `vbrief/proposed/`, the strategy MUST check for existing files with the same scope or feature name:\n\n1. ! **Check for existing file**: Scan `vbrief/proposed/` for files matching the target scope/feature slug (e.g. `*-{feature}-bdd.vbrief.json`, `*-{scope}-context.vbrief.json`).\n - If NO match: proceed with the write — no guard needed.\n - If a match exists: continue to step 2.\n\n2. ! **Warn and ask**: Display: \"A vBRIEF for this scope already exists at `{path}`. Replace it, or create a new version? (replace/new)\"\n - ! If replace: overwrite the existing file\n - ! If new: append a numeric suffix or use today's date to create a distinct file\n\n3. ~ **Read existing decisions**: If the existing file contains a `LockedDecisions` or similar narrative, surface those decisions to the agent context so they are not lost even if the user chooses to replace.\n\n⊗ Silently overwrite an existing scope vBRIEF with the same feature/scope name without warning the user.\n\n---\n\n## Anti-Patterns\n\n- ⊗ Writing to `PROJECT-DEFINITION.vbrief.json` without checking the file's current status (⊗ never write `specification.vbrief.json` at all per v0-20-contract.md)\n- ⊗ Silently overwriting an `approved` or `completed` artifact — this discards locked decisions and approval state\n- ⊗ Replacing all `PROJECT-DEFINITION.vbrief.json` narratives when the strategy only contributes one narrative key (e.g. `Principles`)\n- ⊗ Overwriting a scope vBRIEF in `vbrief/proposed/` without checking if one already exists for the same scope\n- ⊗ Accepting vague confirmation (`proceed`, `ok`) when the guard requires explicit confirmation for approved/completed artifacts\n"
|
|
25
25
|
},
|
|
26
26
|
{
|
|
27
27
|
"id": "bdd",
|
|
@@ -31,7 +31,7 @@
|
|
|
31
31
|
"bdd"
|
|
32
32
|
],
|
|
33
33
|
"path": "strategies/bdd.md",
|
|
34
|
-
"body": "# BDD Strategy\n\nBehaviour-Driven Development -- failing acceptance tests drive requirements.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD,
|
|
34
|
+
"body": "# BDD Strategy\n\nBehaviour-Driven Development -- failing acceptance tests drive requirements.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**⚠️ See also**: [strategies/interview.md](./interview.md) | [strategies/discuss.md](./discuss.md) | [core/glossary.md](../glossary.md)\n\n> Acceptance tests are the specification. Write them first, let failures surface ambiguity, then lock decisions before generating a formal spec.\n\n---\n\n## When to Use\n\n- ~ Features where expected behaviour is easier to express as examples (Given/When/Then) than as written requirements\n- ~ Teams wanting executable specifications that double as regression tests\n- ~ Projects where acceptance tests will be the source of truth for feature correctness\n- ? Skip when requirements are already unambiguous and a formal spec exists\n\n---\n\n## Workflow\n\n### Step 1: Identify User Scenarios\n\n! Write Given/When/Then scenarios for the feature before any implementation or specification work.\n\n- ! Each scenario covers one behaviour -- avoid multi-assertion scenarios\n- ~ Capture happy path, edge cases, and error cases as separate scenarios\n- ~ Use concrete values, not placeholders (e.g. \"Given a user with 3 items in cart\" not \"Given a user with items\")\n- ! Store scenarios in the project's standard test directory (e.g. `tests/`), not in `specs/`\n\n### Step 2: Write Failing Acceptance Tests\n\n! Translate scenarios into executable test code before writing any implementation.\n\n- ! Tests MUST fail when first written -- a passing test before implementation means the test is wrong or the feature already exists\n- ~ Use the project's test framework (pytest, go test, jest, etc.)\n- ! Place test files in the project's standard test directory (e.g. `tests/`)\n- ⊗ Write implementation code at this step\n\n### Step 3: Run Tests -- Surface Ambiguity\n\n! Run the failing tests. Use the failures to surface missing decisions and ambiguity in requirements.\n\n- ! Each test failure is a question: \"What should happen here?\"\n- ~ Group failures by theme (data model gaps, API contract gaps, business rule gaps)\n- ! Record every ambiguity discovered -- these become decision items in Step 4\n\n### Step 4: Lock Decisions\n\n! Before writing output artifacts, follow the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light).\n\n! Resolve all ambiguities surfaced by Step 3. Record decisions in `vbrief/proposed/{feature}-bdd.vbrief.json`.\n\n- ! Write a scope vBRIEF with two narratives:\n - `Scenarios` -- Given/When/Then scenario descriptions from Step 1\n - `LockedDecisions` -- each decision includes: **what** was decided, **why**, and **alternatives considered**\n- ! Decisions are **locked** -- downstream tasks inherit them, do not re-debate\n- ! Format follows the same vBRIEF narrative structure as [strategies/discuss.md](./discuss.md)\n- ⊗ Leave ambiguities unresolved -- every question surfaced in Step 3 must have a locked answer\n- ⊗ Write decisions to a hand-authored markdown file -- use vBRIEF narratives for token-efficient agent consumption\n\n! After emitting the scope vBRIEF to `vbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).\n\n### Step 5: Generate Spec\n\n! Derive SPECIFICATION.md tasks from the now-stable test scenarios and locked decisions.\n\n- ! Each scenario maps to one or more spec tasks with traceability (`traces: scenario-N`)\n- ! Locked decisions from `vbrief/proposed/{feature}-bdd.vbrief.json` `LockedDecisions` narrative flow into the spec as constraints\n- ~ Use the Light or Full path from [strategies/interview.md](./interview.md) based on project size\n\n### Step 6: Chain into Interview Sizing Gate\n\n! Follow [strategies/interview.md](./interview.md) sizing gate for SPECIFICATION.md finalisation.\n\n- ! On completion, register artifacts in `./vbrief/plan.vbrief.json`:\n - Update `completedStrategies`: increment `runCount` for `\"bdd\"`, append artifact paths\n - Append all new artifact paths to the flat `artifacts` array\n- ! Return to [interview.md Chaining Gate](./interview.md#chaining-gate)\n- ! The locked decisions from `vbrief/proposed/{feature}-bdd.vbrief.json` and the acceptance tests MUST flow into subsequent strategies and spec generation\n\n---\n\n## Output Artifacts\n\n- Executable test files in the project's standard test directory -- derived from Given/When/Then scenarios\n- `vbrief/proposed/{feature}-bdd.vbrief.json` -- scope vBRIEF with `Scenarios` and `LockedDecisions` narratives\n\n---\n\n## Fits into Chaining Gate\n\nBDD is a **preparatory** strategy. It can be combined with other preparatory strategies (research, discuss, map) before spec generation. On completion, the chaining gate reappears so the user can run additional strategies or proceed to specification.\n\n⊗ End the session after BDD without returning to the chaining gate.\n\n---\n\n## Anti-Patterns\n\n- ⊗ Writing implementation before acceptance tests -- tests must come first\n- ⊗ Writing acceptance tests that pass immediately -- a passing test before implementation indicates a wrong test or pre-existing feature\n- ⊗ Leaving ambiguities unresolved after Step 3 -- every surfaced question must be locked in Step 4\n- ⊗ Skipping the vBRIEF file -- decisions that exist only in conversation history will be lost\n- ⊗ Writing scenarios with vague placeholders instead of concrete values\n- ⊗ Combining multiple behaviours into a single scenario -- one scenario, one behaviour\n- ⊗ Ending after BDD without chaining into specification generation\n"
|
|
35
35
|
},
|
|
36
36
|
{
|
|
37
37
|
"id": "brownfield",
|
|
@@ -46,22 +46,22 @@
|
|
|
46
46
|
{
|
|
47
47
|
"id": "discuss",
|
|
48
48
|
"title": "Discuss Strategy",
|
|
49
|
-
"description": "Structured alignment before planning
|
|
49
|
+
"description": "Structured alignment before planning — front-load decisions, prevent drift.",
|
|
50
50
|
"triggers": [
|
|
51
51
|
"discuss"
|
|
52
52
|
],
|
|
53
53
|
"path": "strategies/discuss.md",
|
|
54
|
-
"body": "# Discuss Strategy\n\nStructured alignment before planning
|
|
54
|
+
"body": "# Discuss Strategy\n\nStructured alignment before planning — front-load decisions, prevent drift.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**⚠️ See also**: [strategies/interview.md](./interview.md) (Phase 1: Interview) | [strategies/speckit.md](./speckit.md) (Phase 2: Specify) | [core/glossary.md](../glossary.md)\n\n> Extends Deft's Interview phase with decision locking and Feynman technique. Adapted from [GSD](https://github.com/gsd-build/get-shit-done) discuss phase.\n\n---\n\n## Core Principle\n\nThe most expensive mistake is building the wrong thing. A 10-minute alignment conversation saves hours of re-implementation. Decisions made here flow through the entire pipeline — planning, execution, verification — and are **never re-debated** downstream.\n\n---\n\n## When to Use\n\n- ! Before planning any feature/phase with gray areas\n- ~ Before any feature where multiple reasonable approaches exist\n- ? Skip only when the path forward is unambiguous and the user confirms\n\n## The Feynman Approach\n\nUse the Feynman technique: if the user (or you) can't explain the feature in simple, concrete terms, the understanding isn't there yet.\n\n- ! **Make the abstract concrete** — \"Walk me through using this.\" \"What does that look like on screen?\" \"What happens when this fails?\"\n- ! **Explain it back** — Restate the user's intent in your own words. If the restatement surprises them, the spec is wrong.\n- ! **Find the gaps** — Where the explanation gets hand-wavy is where the bugs will be.\n- ~ Use the \"teach it to a child\" filter: if the expected behavior can't be described without jargon, it's underspecified.\n\n## Questioning Behaviors\n\n### Follow Energy\n\n- ~ Whatever the user emphasizes, dig deeper into that\n- ⊗ Robotically marching through a predetermined question list\n- ~ If the user spends time on error handling, ask deeper questions about error handling\n\n### Challenge Vagueness\n\n- ! Push back on fuzzy answers: \"Make it simple\" → \"Simple how? For the user? To implement? To extend later?\"\n- ! Push back on assumed agreement: \"Standard auth\" → \"JWT with refresh? Server-side sessions? OAuth? Which standard?\"\n- ⊗ Accept fuzzy input — it produces divergent output\n\n### Scope Guardrails\n\n- ! If the user suggests a capability belonging to a different feature, capture it as **deferred**\n- ~ Redirect: \"That sounds like a new capability — I'll note it. For now, let's focus on [current scope].\"\n- ~ Record deferred ideas in `./vbrief/plan.vbrief.json` with `deferred` status and a narrative explaining why\n\n## Domain-Sensitive Questions\n\nAdapt question focus to what's being built:\n\n- **Visual features** → Layout, density, interactions, empty states\n- **APIs/CLIs** → Response format, flags, error handling, verbosity\n- **Data systems** → Schema, validation, migration, edge cases\n- **Organization tasks** → Grouping criteria, naming, duplicates, exceptions\n\n## Output\n\n! Before writing output artifacts, follow the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light).\n\n- ! Produce a `vbrief/proposed/{scope}-context.vbrief.json` scope vBRIEF with a `LockedDecisions` narrative\n- ! Each decision includes: **what** was decided, **why**, and **alternatives considered**\n- ! This vBRIEF is injected into all downstream work: planning, execution, verification\n- ! Persist decisions as vBRIEF narratives on the relevant plan items\n- ⊗ Write decisions to a hand-authored markdown context file -- use vBRIEF narratives for token-efficient agent consumption\n\n! After emitting the scope vBRIEF to `vbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).\n\n## Decision Locking\n\n- ! Decisions in the vBRIEF `LockedDecisions` narrative are **locked** -- downstream tasks inherit them, don't re-debate\n- ! If a locked decision needs revisiting, explicitly flag it as unlocked with justification\n- ⊗ Silently making a different choice because the agent forgot what was decided\n- ⊗ Re-debating a settled decision without explicit user approval\n\n---\n\n## Then: Chaining Gate\n\nAfter alignment is complete and decisions are locked in `vbrief/proposed/{scope}-context.vbrief.json`,\nreturn to the [chaining gate](./interview.md#chaining-gate) so the user can\nrun additional preparatory strategies or proceed to spec generation.\n\n- ! On completion, register artifacts in `./vbrief/plan.vbrief.json`:\n - Update `completedStrategies`: increment `runCount` for `\"discuss\"`,\n append artifact path (`vbrief/proposed/{scope}-context.vbrief.json`)\n - Append the path to the flat `artifacts` array\n- ! Return to [interview.md Chaining Gate](./interview.md#chaining-gate)\n (the discuss phase replaces the interview's question-gathering -- decisions are\n already made, so the interview will be short or skipped entirely)\n- ! The locked decisions from `vbrief/proposed/{scope}-context.vbrief.json` MUST flow into subsequent\n strategies and spec generation\n- ⊗ End the session after discuss without returning to the chaining gate\n or the invoking strategy's next-step menu\n\n! **Standalone context:** If invoked from a standalone strategy (e.g. map's\n standalone next-step menu) rather than from the interview chaining gate,\n return to the invoking strategy's menu instead.\n\n---\n\n## Workflow\n\n1. **Open** -- Start with the user's goal statement; restate it in your own words\n2. **Explore** -- Follow energy, challenge vagueness, ask domain-sensitive questions\n3. **Lock** -- Record each decision in `vbrief/proposed/{scope}-context.vbrief.json` `LockedDecisions` narrative with what/why/alternatives\n4. **Verify** -- Explain the full picture back to the user (Feynman check)\n5. **Chain** -- Return to [interview.md Chaining Gate](./interview.md#chaining-gate), or -- if invoked from a standalone strategy (e.g. map's standalone next-step menu) -- return to the invoking strategy's menu per the [standalone-context rule](#then-chaining-gate) above\n\n## Anti-Patterns\n\n- ⊗ Skipping discuss and immediately writing code\n- ⊗ Asking generic checklist questions instead of following energy\n- ⊗ Accepting \"make it nice\" / \"standard approach\" / \"whatever works\" without pushback\n- ⊗ Scope creep — capturing out-of-scope ideas inline instead of deferring\n- ⊗ Decisions that exist only in conversation history (they must be in the vBRIEF `LockedDecisions` narrative)\n- ⊗ Ending after discuss without chaining into specification generation (chained mode; in standalone context, returning to the invoking strategy's menu satisfies the completion requirement per the [standalone-context rule](#then-chaining-gate))\n"
|
|
55
55
|
},
|
|
56
56
|
{
|
|
57
57
|
"id": "emit-hints",
|
|
58
58
|
"title": "Issue-Emit Hints",
|
|
59
|
-
"description": "Shared hint referenced by strategies at the moment they emit scope vBRIEFs. It names the GitHub-issue tracking choice
|
|
59
|
+
"description": "Shared hint referenced by strategies at the moment they emit scope vBRIEFs. It names the GitHub-issue tracking choice — none / umbrella / per-vBRIEF — so the choice is discoverable instead of the emission step ending silently.",
|
|
60
60
|
"triggers": [
|
|
61
61
|
"emit-hints"
|
|
62
62
|
],
|
|
63
63
|
"path": "strategies/emit-hints.md",
|
|
64
|
-
"body": "# Issue-Emit Hints\n\nShared hint referenced by strategies at the moment they emit scope vBRIEFs. It names the GitHub-issue tracking choice
|
|
64
|
+
"body": "# Issue-Emit Hints\n\nShared hint referenced by strategies at the moment they emit scope vBRIEFs. It names the GitHub-issue tracking choice — none / umbrella / per-vBRIEF — so the choice is discoverable instead of the emission step ending silently.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**⚠️ See also**: [strategies/artifact-guards.md](./artifact-guards.md) | [vbrief/vbrief.md](../vbrief/vbrief.md) | [strategies/v0-20-contract.md](./v0-20-contract.md)\n\n---\n\n## When to Use\n\nThis file is not a standalone strategy — it is a shared hint referenced by other strategies. It activates at the emission step, right after a strategy writes scope vBRIEFs to `vbrief/proposed/` (or `vbrief/pending/`).\n\n- ! Referenced by spec-generating strategies: [speckit](./speckit.md) (Phase 4 and Phase 4.5), [enterprise](./enterprise.md), [rapid](./rapid.md), [interview](./interview.md), [yolo](./yolo.md)\n- ! Referenced by preparatory strategies: [bdd](./bdd.md), [discuss](./discuss.md), [research](./research.md), [map](./map.md), [probe](./probe.md)\n\n## Workflow\n\n1. Strategy reaches its emission step and writes scope vBRIEF(s)\n2. Strategy surfaces the hint below, naming all three patterns\n3. The user picks one — or takes no action (the default)\n4. No issue is filed unless the user explicitly invokes `task deft:issue:emit`\n\n---\n\n## The Hint\n\n! After emitting N scope vBRIEF(s), print the following hint so the user discovers the GitHub-issue tracking choice. The hint is informational text only — it mutates nothing and files no issue.\n\n```\n<strategy> emitted N scope vBRIEF(s).\n\nOptional: track these in GitHub issues.\n - task deft:issue:emit --umbrella -- vbrief/<path>/<glob> (one roadmap issue, all vBRIEFs reference it)\n - task deft:issue:emit --per-vbrief -- vbrief/<path>/<glob> (one issue per vBRIEF)\n - Default behavior (vBRIEF-only) requires no further action.\n```\n\n~ Replace `<path>/<glob>` with the actual emission target (e.g. `vbrief/proposed/2026-06-15-*.vbrief.json`).\n\nNote: `task deft:issue:emit` is the consumer-installed surface (this is what strategies render to). The maintainer-side, in-repo form is `task issue:emit` — the same command without the `deft:` prefix.\n\n---\n\n## The Three Patterns\n\n1. **None (default)** — emit vBRIEF(s) only; file no GitHub issue. Requires no further user action. This is the framework default and is unchanged by this hint.\n2. **Umbrella** — `task deft:issue:emit --umbrella -- vbrief/<path>/<glob>` files ONE roadmap issue, and every matched vBRIEF references it.\n3. **Per-vBRIEF** — `task deft:issue:emit --per-vbrief -- vbrief/<path>/<glob>` files one issue per matched vBRIEF.\n\n- ! Name all three patterns (none / `--umbrella` / `--per-vbrief`) when surfacing the hint — do not hide the umbrella / per-vBRIEF escape hatches.\n- ⊗ File a GitHub issue automatically as part of emission. No strategy files an issue unless the user explicitly invokes `task deft:issue:emit`.\n- ~ The emitted issue body is rendered from the vBRIEF `title` + `Description` + `Acceptance` + `Traces` narratives (see [vbrief/vbrief.md](../vbrief/vbrief.md) Origin Provenance), and the source vBRIEF's `references[]` is updated to link the issue.\n\n---\n\n## Anti-Patterns\n\n- ⊗ Ending a strategy's emission step silently — the user never learns the umbrella / per-vBRIEF choice exists.\n- ⊗ Filing a GitHub issue automatically — the default is vBRIEF-only and requires explicit opt-in via `task deft:issue:emit`.\n- ⊗ Naming only one pattern (e.g. only `--umbrella`) — the hint MUST name none / `--umbrella` / `--per-vbrief` together so the full choice is visible.\n- ⊗ Mutating the source vBRIEF or its `references[]` as a side effect of merely showing the hint — mutation happens only when the user runs `task deft:issue:emit`.\n"
|
|
65
65
|
},
|
|
66
66
|
{
|
|
67
67
|
"id": "enterprise",
|
|
@@ -71,17 +71,17 @@
|
|
|
71
71
|
"enterprise"
|
|
72
72
|
],
|
|
73
73
|
"path": "strategies/enterprise.md",
|
|
74
|
-
"body": "# Enterprise Strategy\n\nCompliance-heavy workflow -- v0.20 date-prefixed story/phase vBRIEF + PROJECT-DEFINITION with explicit approval gates at each stage.\n\n**v0.20 note (s5-migrate-speckit-rapid-enterprise / #1166):** Enterprise now emits only the canonical v0.20 shape (date-prefixed story/phase vBRIEFs in proposed/, full PROJECT-DEFINITION.vbrief.json via task project:render, seeded lifecycle folders, no legacy specification.vbrief.json). PRD.md and SPECIFICATION.md (if any) are deprecation-redirect derivatives only. See the dedicated ## v0.20 Output Shape section and the canonical contract `strategies/v0-20-contract.md` (s1-contract of #1166).\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, \u2249=SHOULD NOT, \u2297=MUST NOT, ?=MAY.\n\n**\u26a0\ufe0f See also**: [strategies/interview.md](./interview.md) | [strategies/speckit.md](./speckit.md) | [strategies/README.md](./README.md) | [strategies/v0-20-contract.md](./v0-20-contract.md) | [artifact-guards.md](./artifact-guards.md)\n\n> When every decision must be auditable and every artifact must survive a compliance\n> review, enterprise strategy adds explicit approval gates between stages. Suited for\n> regulated industries, high-accountability environments, and projects where the cost\n> of rework far exceeds the cost of upfront process.\n\n---\n\n## When to Use\n\n- ~ Regulated or compliance-heavy environments (SOC 2, HIPAA, ISO 27001, FedRAMP)\n- ~ Projects requiring formal Architecture Decision Records (ADRs)\n- ~ Multi-team efforts where approval chains cross organisational boundaries\n- ~ Environments where audit trail and traceability are non-negotiable\n- ? Large internal projects with formal change advisory boards\n- \u2297 Solo prototyping, spikes, or throwaway experiments -- use [rapid.md](./rapid.md) instead\n\n---\n\n## Workflow\n\n### Stage 1: PRD (Forced-Full Path)\n\n! Before writing output artifacts, follow the guards in [artifact-guards.md](./artifact-guards.md) (Preparatory Guard for proposed/ scope items; Spec-Generating Guard for PROJECT-DEFINITION).\n\n! Run the Full interview path from [interview.md](./interview.md) unconditionally -- write PRD narratives as date-prefixed story/phase vBRIEF(s) to `vbrief/proposed/YYYY-MM-DD-<kebab-slug>.vbrief.json`.\n\n- ! Use the Full path regardless of project size -- enterprise always requires a PRD\n- ! Write PRD content as narratives in the proposed/ vBRIEF `plan.narratives`: `ProblemStatement`, `Goals`, `NonGoals`, `UserStories`, `Requirements` (functional + non-functional), `SuccessMetrics`\n- ! Record the PRD approver(s) in the `Approvers` narrative\n- ! Run `task prd:render` (if UX continuity needed) to produce `PRD.md` **only as a deprecation-redirect derivative** (see v0.20 Output Shape); the source of truth is the vbrief/ artifacts.\n\n### Gate 1: PRD Approval\n\n! The rendered `PRD.md` (if present as derivative) or the proposed/ vBRIEF requires explicit written approval before proceeding.\n\n- ! Approval must come from the designated approver(s) -- not the author\n- ! Record approval: approver name, date, and any conditions\n- \u2297 Proceed to Stage 2 without documented PRD approval\n- ~ If approval is conditional, resolve conditions and re-approve before proceeding\n\n### Stage 2: Architecture Decision Records (ADRs)\n\n! For each significant technical decision in the PRD, create an ADR.\n\n- ! ADR format: Title, Status, Context, Decision, Consequences (see [languages/markdown.md](../languages/markdown.md) ADR section)\n- ! Store ADRs in `docs/adr/` or `docs/decisions/`\n- ! Each ADR traces back to the PRD requirement(s) it addresses\n- ~ Minimum ADRs: data storage, authentication, API contracts, deployment model\n- \u2297 Skip ADRs for decisions with compliance, security, or data-residency implications\n\n### Gate 2: ADR Approval\n\n! ADRs require review and approval before specification begins.\n\n- ! Technical lead or architect must approve each ADR\n- ! Record approval alongside the ADR (status field: Proposed \u2192 Accepted)\n- \u2297 Begin specification with Proposed ADRs -- all must be Accepted\n\n### Stage 3: Generate Specification (as v0.20 vBRIEFs)\n\n! Before writing output artifacts, follow the guards in [artifact-guards.md](./artifact-guards.md) (Preparatory Guard for proposed/ scope items; Spec-Generating Guard for PROJECT-DEFINITION).\n\n! Enrich or emit date-prefixed vBRIEF(s) in `vbrief/proposed/` with architecture and plan narratives derived from the approved PRD narratives and accepted ADRs. (No singular `specification.vbrief.json`.)\n\n- ! Add HOW narratives to the proposed/ vBRIEF `plan.narratives`: `Architecture`, `TechDecisions`, `ImplementationPhases`, `TraceabilityMatrix`\n- ! Every spec task must trace to a PRD requirement and, where applicable, an ADR\n- ! Use the Light or Full path from [interview.md](./interview.md) for specification generation\n- ! Include traceability matrix: spec task \u2192 PRD requirement \u2192 ADR (where applicable)\n- ! Run `task spec:render` (if UX continuity needed) to produce `SPECIFICATION.md` **only as a deprecation-redirect derivative** (see v0.20 Output Shape); the source of truth is the vbrief/ lifecycle + PROJECT-DEFINITION.\n- ! After proposed/ vBRIEFs exist, invoke `task project:render` to produce/refresh `vbrief/PROJECT-DEFINITION.vbrief.json`.\n\n! After emitting the proposed/ vBRIEF(s), surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) \u2014 name all three patterns (none / `--umbrella` / `--per-vbrief`).\n\n### Gate 3: Specification Approval\n\n! The proposed/ vBRIEF(s) (and derivative `SPECIFICATION.md` if present) require explicit approval before implementation begins.\n\n- ! Approval scope: completeness (all PRD requirements covered), feasibility, traceability\n- ! Record approval in the vBRIEF header or via a signed-off PR review\n- \u2297 Begin implementation without documented spec approval\n\n### Stage 4: Build\n\n! Implement against the approved vBRIEF(s) in proposed/. All standard quality gates apply.\n\n- ! Full quality gates: `task check`, \u226585% coverage, conventional commits\n- ! Each PR must reference the spec task(s) it implements\n- ! Use `/deft:change` for all changes (mandatory in enterprise -- not optional like in other strategies)\n\n---\n\n## Output Artifacts\n\n- `vbrief/proposed/YYYY-MM-DD-*.vbrief.json` (one or more) -- source of truth for PRD and specification narratives (date-prefixed per v0.20 contract)\n- `vbrief/PROJECT-DEFINITION.vbrief.json` -- complete via `task project:render`\n- `PRD.md` -- rendered export via `task prd:render` **only if deprecation-redirect sentinel** (read-only stakeholder review artifact; otherwise omit)\n- `docs/adr/adr-NNN-*.md` -- accepted Architecture Decision Records (unchanged location)\n- `SPECIFICATION.md` -- rendered export via `task spec:render` **only if deprecation-redirect sentinel** (read-only stakeholder review artifact; otherwise omit)\n- Traceability matrix (inline in the proposed/ vBRIEF narratives or as a separate `docs/traceability.md`)\n- `vbrief/{proposed,pending,active,completed,cancelled}/` -- all five lifecycle folders seeded\n\n---\n\n## Fits into Chaining Gate\n\nEnterprise is a **spec-generating** strategy. It uses the Forced-Full path and adds ADR and approval gates before specification. Preparatory strategies (research, discuss, map, bdd) can run before enterprise begins. Output follows the v0.20 contract exclusively (see ## v0.20 Output Shape).\n\n---\n\n## Anti-Patterns\n\n- \u2297 Skipping any approval gate -- every gate is mandatory in enterprise strategy\n- \u2297 Starting implementation before all three approval gates are passed\n- \u2297 Using enterprise for throwaway prototypes -- the overhead is not justified\n- \u2297 Omitting ADRs for compliance-relevant decisions\n- \u2297 Proceeding with Proposed (unapproved) ADRs\n- \u2297 Losing traceability between PRD \u2192 ADR \u2192 spec \u2192 implementation\n- \u2297 Emitting to `vbrief/specification.vbrief.json` or writing real content to root SPECIFICATION.md/PRD.md without the deprecated-redirect sentinel\n\n---\n\n## v0.20 Output Shape (s5-migrate-speckit-rapid-enterprise / #1166)\n\nThis strategy has been migrated to the full v0.20 output shape so enterprise-generated projects are accepted by the build skill Pre-Cutover Detection Guard with zero errors on first attempt (resolves the enterprise row from the #1166 inconsistency table and the s5 story acceptance criteria).\n\n- ! Seed the five lifecycle folders under `vbrief/` if any are missing: `proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`.\n- ! Emit scope items (PRD, spec phases, etc.) exclusively as date-prefixed scope vBRIEFs: `vbrief/proposed/YYYY-MM-DD-<kebab-slug>.vbrief.json` (use the run's creation date for the prefix; choose descriptive slugs). Decompose into focused, buildable vBRIEFs (v0.6 schema) rather than a monolithic legacy spec.\n- ! After the proposed/ vBRIEFs are written, invoke `task project:render` (run from the repo root) to generate/refresh the complete `vbrief/PROJECT-DEFINITION.vbrief.json` (items registry is derived from the lifecycle folders).\n- \u2297 Never emit `vbrief/specification.vbrief.json` (or any legacy dual-write).\n- ~ `PRD.md` and `SPECIFICATION.md` at the project root, if produced at all, must be only read-only derivatives that include the v0.20 deprecated-redirect sentinel (see conventions/machine-generated-banner.md). The source of truth is the vbrief/ lifecycle vBRIEFs + PROJECT-DEFINITION. ADRs remain in `docs/adr/`.\n- ! Before writing any proposed/ vBRIEFs or PROJECT-DEFINITION, follow the guards in [artifact-guards.md](./artifact-guards.md) (Preparatory Guard for scope items in proposed/; Spec-Generating Guard for PROJECT-DEFINITION).\n- ! Final output tree must pass the deterministic v0.20 strategy output validation gate (s2-deterministic-gate) and the build Pre-Cutover Detection Guard with zero warnings/errors. See full acceptance in the s5 vBRIEF and the 1166 decomposition.\n- ! Cite the canonical contract `strategies/v0-20-contract.md` (s1-contract) for the exact shape and the per-strategy table row.\n\n---\n\n## Artifacts Summary (v0.20)\n\n**Enterprise (Forced-Full path with gates):**\n\n| Artifact | Purpose | Created By |\n|----------|---------|------------|\n| `vbrief/proposed/YYYY-MM-DD-*.vbrief.json` (one or more) | PRD + specification narratives as date-prefixed scope items (per v0.20 contract) | Enterprise |\n| `vbrief/PROJECT-DEFINITION.vbrief.json` | Project identity gestalt + complete scope items registry | `task project:render` (invoked by Enterprise) |\n| `vbrief/{proposed,pending,active,completed,cancelled}/` | All five lifecycle folders seeded | Enterprise |\n| `docs/adr/adr-NNN-*.md` | Accepted Architecture Decision Records (traceable) | Enterprise (unchanged) |\n| (optional derivative) `PRD.md` / `SPECIFICATION.md` | Human-readable (includes deprecated-redirect sentinel only) | `task prd:render` / `task spec:render` (if invoked) |\n\n**Pre-v0.20 / legacy artifacts that MUST NOT be produced by this strategy:**\n\n- `vbrief/specification.vbrief.json`\n- Primary handoff `PRD.md` or `SPECIFICATION.md` at project root (without sentinel)\n- Bare-named vBRIEFs in proposed/\n\nSee the full table and rules in `strategies/v0-20-contract.md` (enterprise row: Must Create Lifecycle Folders: Yes; Must Write PROJECT-DEFINITION: Yes; Scope vBRIEFs Location: proposed/YYYY-MM-DD-*.vbrief.json only; specification.vbrief.json: Never; SPECIFICATION.md / PROJECT.md: Omit or deprecation redirect only).\n\n---\n\n## Invoking This Strategy\n\nSet in PROJECT-DEFINITION.vbrief.json narratives:\n```json\n\"Strategy\": \"strategies/enterprise.md\"\n```\n\nOr explicitly:\n```\nUse the enterprise strategy for this project.\n```\n\nStart with:\n```\nI want to build [project] with features:\n1. [feature]\n2. [feature]\n```\n(Enterprise will force the Full path + gates + ADRs + v0.20 vBRIEF emission.)\n"
|
|
74
|
+
"body": "# Enterprise Strategy\n\nCompliance-heavy workflow -- v0.20 date-prefixed story/phase vBRIEF + PROJECT-DEFINITION with explicit approval gates at each stage.\n\n**v0.20 note (s5-migrate-speckit-rapid-enterprise / #1166):** Enterprise now emits only the canonical v0.20 shape (date-prefixed story/phase vBRIEFs in proposed/, full PROJECT-DEFINITION.vbrief.json via task project:render, seeded lifecycle folders, no legacy specification.vbrief.json). PRD.md and SPECIFICATION.md (if any) are deprecation-redirect derivatives only. See the dedicated ## v0.20 Output Shape section and the canonical contract `strategies/v0-20-contract.md` (s1-contract of #1166).\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**⚠️ See also**: [strategies/interview.md](./interview.md) | [strategies/speckit.md](./speckit.md) | [strategies/README.md](./README.md) | [strategies/v0-20-contract.md](./v0-20-contract.md) | [artifact-guards.md](./artifact-guards.md)\n\n> When every decision must be auditable and every artifact must survive a compliance\n> review, enterprise strategy adds explicit approval gates between stages. Suited for\n> regulated industries, high-accountability environments, and projects where the cost\n> of rework far exceeds the cost of upfront process.\n\n---\n\n## When to Use\n\n- ~ Regulated or compliance-heavy environments (SOC 2, HIPAA, ISO 27001, FedRAMP)\n- ~ Projects requiring formal Architecture Decision Records (ADRs)\n- ~ Multi-team efforts where approval chains cross organisational boundaries\n- ~ Environments where audit trail and traceability are non-negotiable\n- ? Large internal projects with formal change advisory boards\n- ⊗ Solo prototyping, spikes, or throwaway experiments -- use [rapid.md](./rapid.md) instead\n\n---\n\n## Workflow\n\n### Stage 1: PRD (Forced-Full Path)\n\n! Before writing output artifacts, follow the guards in [artifact-guards.md](./artifact-guards.md) (Preparatory Guard for proposed/ scope items; Spec-Generating Guard for PROJECT-DEFINITION).\n\n! Run the Full interview path from [interview.md](./interview.md) unconditionally -- write PRD narratives as date-prefixed story/phase vBRIEF(s) to `vbrief/proposed/YYYY-MM-DD-<kebab-slug>.vbrief.json`.\n\n- ! Use the Full path regardless of project size -- enterprise always requires a PRD\n- ! Write PRD content as narratives in the proposed/ vBRIEF `plan.narratives`: `ProblemStatement`, `Goals`, `NonGoals`, `UserStories`, `Requirements` (functional + non-functional), `SuccessMetrics`\n- ! Record the PRD approver(s) in the `Approvers` narrative\n- ! Run `task prd:render` (if UX continuity needed) to produce `PRD.md` **only as a deprecation-redirect derivative** (see v0.20 Output Shape); the source of truth is the vbrief/ artifacts.\n\n### Gate 1: PRD Approval\n\n! The rendered `PRD.md` (if present as derivative) or the proposed/ vBRIEF requires explicit written approval before proceeding.\n\n- ! Approval must come from the designated approver(s) -- not the author\n- ! Record approval: approver name, date, and any conditions\n- ⊗ Proceed to Stage 2 without documented PRD approval\n- ~ If approval is conditional, resolve conditions and re-approve before proceeding\n\n### Stage 2: Architecture Decision Records (ADRs)\n\n! For each significant technical decision in the PRD, create an ADR.\n\n- ! ADR format: Title, Status, Context, Decision, Consequences (see [languages/markdown.md](../languages/markdown.md) ADR section)\n- ! Store ADRs in `docs/adr/` or `docs/decisions/`\n- ! Each ADR traces back to the PRD requirement(s) it addresses\n- ~ Minimum ADRs: data storage, authentication, API contracts, deployment model\n- ⊗ Skip ADRs for decisions with compliance, security, or data-residency implications\n\n### Gate 2: ADR Approval\n\n! ADRs require review and approval before specification begins.\n\n- ! Technical lead or architect must approve each ADR\n- ! Record approval alongside the ADR (status field: Proposed → Accepted)\n- ⊗ Begin specification with Proposed ADRs -- all must be Accepted\n\n### Stage 3: Generate Specification (as v0.20 vBRIEFs)\n\n! Before writing output artifacts, follow the guards in [artifact-guards.md](./artifact-guards.md) (Preparatory Guard for proposed/ scope items; Spec-Generating Guard for PROJECT-DEFINITION).\n\n! Enrich or emit date-prefixed vBRIEF(s) in `vbrief/proposed/` with architecture and plan narratives derived from the approved PRD narratives and accepted ADRs. (No singular `specification.vbrief.json`.)\n\n- ! Add HOW narratives to the proposed/ vBRIEF `plan.narratives`: `Architecture`, `TechDecisions`, `ImplementationPhases`, `TraceabilityMatrix`\n- ! Every spec task must trace to a PRD requirement and, where applicable, an ADR\n- ! Use the Light or Full path from [interview.md](./interview.md) for specification generation\n- ! Include traceability matrix: spec task → PRD requirement → ADR (where applicable)\n- ! Run `task spec:render` (if UX continuity needed) to produce `SPECIFICATION.md` **only as a deprecation-redirect derivative** (see v0.20 Output Shape); the source of truth is the vbrief/ lifecycle + PROJECT-DEFINITION.\n- ! After proposed/ vBRIEFs exist, invoke `task project:render` to produce/refresh `vbrief/PROJECT-DEFINITION.vbrief.json`.\n\n! After emitting the proposed/ vBRIEF(s), surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).\n\n### Gate 3: Specification Approval\n\n! The proposed/ vBRIEF(s) (and derivative `SPECIFICATION.md` if present) require explicit approval before implementation begins.\n\n- ! Approval scope: completeness (all PRD requirements covered), feasibility, traceability\n- ! Record approval in the vBRIEF header or via a signed-off PR review\n- ⊗ Begin implementation without documented spec approval\n\n### Stage 4: Build\n\n! Implement against the approved vBRIEF(s) in proposed/. All standard quality gates apply.\n\n- ! Full quality gates: `task check`, ≥85% coverage, conventional commits\n- ! Each PR must reference the spec task(s) it implements\n- ! Use `/deft:change` for all changes (mandatory in enterprise -- not optional like in other strategies)\n\n---\n\n## Output Artifacts\n\n- `vbrief/proposed/YYYY-MM-DD-*.vbrief.json` (one or more) -- source of truth for PRD and specification narratives (date-prefixed per v0.20 contract)\n- `vbrief/PROJECT-DEFINITION.vbrief.json` -- complete via `task project:render`\n- `PRD.md` -- rendered export via `task prd:render` **only if deprecation-redirect sentinel** (read-only stakeholder review artifact; otherwise omit)\n- `docs/adr/adr-NNN-*.md` -- accepted Architecture Decision Records (unchanged location)\n- `SPECIFICATION.md` -- rendered export via `task spec:render` **only if deprecation-redirect sentinel** (read-only stakeholder review artifact; otherwise omit)\n- Traceability matrix (inline in the proposed/ vBRIEF narratives or as a separate `docs/traceability.md`)\n- `vbrief/{proposed,pending,active,completed,cancelled}/` -- all five lifecycle folders seeded\n\n---\n\n## Fits into Chaining Gate\n\nEnterprise is a **spec-generating** strategy. It uses the Forced-Full path and adds ADR and approval gates before specification. Preparatory strategies (research, discuss, map, bdd) can run before enterprise begins. Output follows the v0.20 contract exclusively (see ## v0.20 Output Shape).\n\n---\n\n## Anti-Patterns\n\n- ⊗ Skipping any approval gate -- every gate is mandatory in enterprise strategy\n- ⊗ Starting implementation before all three approval gates are passed\n- ⊗ Using enterprise for throwaway prototypes -- the overhead is not justified\n- ⊗ Omitting ADRs for compliance-relevant decisions\n- ⊗ Proceeding with Proposed (unapproved) ADRs\n- ⊗ Losing traceability between PRD → ADR → spec → implementation\n- ⊗ Emitting to `vbrief/specification.vbrief.json` or writing real content to root SPECIFICATION.md/PRD.md without the deprecated-redirect sentinel\n\n---\n\n## v0.20 Output Shape (s5-migrate-speckit-rapid-enterprise / #1166)\n\nThis strategy has been migrated to the full v0.20 output shape so enterprise-generated projects are accepted by the build skill Pre-Cutover Detection Guard with zero errors on first attempt (resolves the enterprise row from the #1166 inconsistency table and the s5 story acceptance criteria).\n\n- ! Seed the five lifecycle folders under `vbrief/` if any are missing: `proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`.\n- ! Emit scope items (PRD, spec phases, etc.) exclusively as date-prefixed scope vBRIEFs: `vbrief/proposed/YYYY-MM-DD-<kebab-slug>.vbrief.json` (use the run's creation date for the prefix; choose descriptive slugs). Decompose into focused, buildable vBRIEFs (v0.6 schema) rather than a monolithic legacy spec.\n- ! After the proposed/ vBRIEFs are written, invoke `task project:render` (run from the repo root) to generate/refresh the complete `vbrief/PROJECT-DEFINITION.vbrief.json` (items registry is derived from the lifecycle folders).\n- ⊗ Never emit `vbrief/specification.vbrief.json` (or any legacy dual-write).\n- ~ `PRD.md` and `SPECIFICATION.md` at the project root, if produced at all, must be only read-only derivatives that include the v0.20 deprecated-redirect sentinel (see conventions/machine-generated-banner.md). The source of truth is the vbrief/ lifecycle vBRIEFs + PROJECT-DEFINITION. ADRs remain in `docs/adr/`.\n- ! Before writing any proposed/ vBRIEFs or PROJECT-DEFINITION, follow the guards in [artifact-guards.md](./artifact-guards.md) (Preparatory Guard for scope items in proposed/; Spec-Generating Guard for PROJECT-DEFINITION).\n- ! Final output tree must pass the deterministic v0.20 strategy output validation gate (s2-deterministic-gate) and the build Pre-Cutover Detection Guard with zero warnings/errors. See full acceptance in the s5 vBRIEF and the 1166 decomposition.\n- ! Cite the canonical contract `strategies/v0-20-contract.md` (s1-contract) for the exact shape and the per-strategy table row.\n\n---\n\n## Artifacts Summary (v0.20)\n\n**Enterprise (Forced-Full path with gates):**\n\n| Artifact | Purpose | Created By |\n|----------|---------|------------|\n| `vbrief/proposed/YYYY-MM-DD-*.vbrief.json` (one or more) | PRD + specification narratives as date-prefixed scope items (per v0.20 contract) | Enterprise |\n| `vbrief/PROJECT-DEFINITION.vbrief.json` | Project identity gestalt + complete scope items registry | `task project:render` (invoked by Enterprise) |\n| `vbrief/{proposed,pending,active,completed,cancelled}/` | All five lifecycle folders seeded | Enterprise |\n| `docs/adr/adr-NNN-*.md` | Accepted Architecture Decision Records (traceable) | Enterprise (unchanged) |\n| (optional derivative) `PRD.md` / `SPECIFICATION.md` | Human-readable (includes deprecated-redirect sentinel only) | `task prd:render` / `task spec:render` (if invoked) |\n\n**Pre-v0.20 / legacy artifacts that MUST NOT be produced by this strategy:**\n\n- `vbrief/specification.vbrief.json`\n- Primary handoff `PRD.md` or `SPECIFICATION.md` at project root (without sentinel)\n- Bare-named vBRIEFs in proposed/\n\nSee the full table and rules in `strategies/v0-20-contract.md` (enterprise row: Must Create Lifecycle Folders: Yes; Must Write PROJECT-DEFINITION: Yes; Scope vBRIEFs Location: proposed/YYYY-MM-DD-*.vbrief.json only; specification.vbrief.json: Never; SPECIFICATION.md / PROJECT.md: Omit or deprecation redirect only).\n\n---\n\n## Invoking This Strategy\n\nSet in PROJECT-DEFINITION.vbrief.json narratives:\n```json\n\"Strategy\": \"strategies/enterprise.md\"\n```\n\nOr explicitly:\n```\nUse the enterprise strategy for this project.\n```\n\nStart with:\n```\nI want to build [project] with features:\n1. [feature]\n2. [feature]\n```\n(Enterprise will force the Full path + gates + ADRs + v0.20 vBRIEF emission.)\n"
|
|
75
75
|
},
|
|
76
76
|
{
|
|
77
77
|
"id": "interview",
|
|
78
78
|
"title": "Interview Strategy",
|
|
79
|
-
"description": "The standard Deft workflow: structured interview
|
|
79
|
+
"description": "The standard Deft workflow: structured interview → SPECIFICATION. This is the canonical source of truth for the interview process. All entry points (CLI via `run spec`, agent via `deft-directive-setup` Phase 3, and `templates/make-spec.md`) MUST follow this strategy.",
|
|
80
80
|
"triggers": [
|
|
81
81
|
"interview"
|
|
82
82
|
],
|
|
83
83
|
"path": "strategies/interview.md",
|
|
84
|
-
"body": "# Interview Strategy\n\nThe standard Deft workflow: structured interview \u2192 SPECIFICATION. This is the\ncanonical source of truth for the interview process. All entry points (CLI via\n`run spec`, agent via `deft-directive-setup` Phase 3, and `templates/make-spec.md`) MUST\nfollow this strategy.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, \u2249=SHOULD NOT, \u2297=MUST NOT, ?=MAY.\n\n**\u26a0\ufe0f See also**: [strategies/discuss.md](./discuss.md) | [strategies/yolo.md](./yolo.md) | [core/glossary.md](../glossary.md)\n\n## When to Use\n\n- ! Default strategy for all new projects\n- ~ Projects with unclear or evolving requirements\n- ~ When stakeholder alignment is needed before implementation\n- ? Skip to SPECIFICATION phase if requirements are already fully documented\n\n---\n\n## Chaining Gate\n\nBefore spec generation, offer the user a chance to run preparatory strategies\nor switch to a different spec-generating strategy. This gate is the single\norchestration point for strategy composition.\n\n! The chaining gate MUST always be shown \u2014 even when the interview strategy is\ninvoked directly with no prior strategy.\n! The chaining gate is a **blocking question**. The AI MUST present the options\nand wait for the user to choose before proceeding.\n\u2297 Skip the chaining gate or proceed to the sizing gate without presenting it.\n\n### When It Appears\n\n- ! Before the [Sizing Gate](#sizing-gate) on every entry to the interview strategy\n- ! After each completed preparatory strategy (recursive \u2014 the gate reappears)\n- ! After the [Acceptance Gate](#acceptance-gate) when the user chooses \"Revise\" or \"Switch\"\n\n### Options\n\nPresent two groups sourced from the `Type` column in\n[strategies/README.md](./README.md#strategy-types):\n\n**Default:**\n1. **Proceed to specification** (default) \u2014 continue to the [Sizing Gate](#sizing-gate)\n\n**Preparatory strategies** (type: `preparatory` \u2014 loops back to this gate on completion):\n- Research \u2014 investigate the domain, find libraries, identify pitfalls\n- Discuss \u2014 lock key decisions using Feynman technique\n- Probe \u2014 adversarially stress-test the plan; surface assumptions, edge cases, and risks\n- Map \u2014 analyze existing codebase conventions\n\n~ Some preparatory strategies (currently map) also support standalone invocation\nvia `/deft:run:<name>` without entering the interview flow. When invoked standalone,\nthey present their own completion options instead of returning to this gate.\nSee `strategies/map.md` for standalone behavior.\n\n**Switch spec-generating strategy** (type: `spec-generating` \u2014 replaces current pipeline):\n- Yolo \u2014 auto-pilot, Johnbot picks all answers\n- SpecKit \u2014 formal spec process with story readiness before implementation\n\n### Run Count Annotations\n\n- ! Previously-run strategies MUST display with a run count (e.g., `Research (ran 1\u00d7)`)\n- ! No strategy is ever removed from the gate \u2014 users can re-run any strategy\n- ! Run counts are read from `completedStrategies` in\n [`./vbrief/plan.vbrief.json`](../vbrief/vbrief.md#strategy-chaining-fields)\n\n### State Tracking\n\n- ! On completion of a preparatory strategy, update `completedStrategies` in\n `./vbrief/plan.vbrief.json`: increment `runCount`, append artifact paths\n- ! Append all new artifact paths to the flat `artifacts` array\n- ! The next strategy and eventual spec generation MUST load all artifacts\n listed in `plan.vbrief.json`\n\n### Example Prompt\n\n```\nReady to generate the specification. Before we proceed, would you like to:\n\n1. Proceed to specification (default)\n\n--- Preparatory (loops back) ---\n2. Run a research phase \u2014 investigate the domain, find libraries, identify pitfalls\n3. Run a discuss phase \u2014 lock key decisions using Feynman technique\n4. Run a probe phase \u2014 adversarially stress-test the plan; surface assumptions, edge cases, and risks\n5. Run a map phase \u2014 analyze existing codebase conventions\n\n--- Switch strategy ---\n6. Switch to yolo \u2014 auto-pilot picks all answers\n7. Switch to speckit \u2014 formal spec process with story readiness before implementation\n\n8. Other (specify)\n```\n\n---\n\n## Sizing Gate\n\nBefore the interview begins, determine project complexity to select the\nappropriate path. The gate runs once, immediately after hearing what the user\nwants to build.\n\n! The sizing gate is a **blocking question**. The AI MUST propose a size and\nwait for the user to confirm or override before asking any interview questions.\n\u2297 Combine the sizing proposal with the first interview question in the same message.\n\u2297 Proceed to interview questions before the user has explicitly confirmed the path.\n\n### Sizing Signals\n\nThe AI SHOULD propose a size based on these signals; the user confirms or overrides:\n\n- Number of features (\u22645 \u2192 Light, >5 \u2192 Full)\n- Number of components/services (1\u20132 \u2192 Light, 3+ \u2192 Full)\n- Expected duration (days \u2192 Light, weeks/months \u2192 Full)\n- Team/agent count (solo \u2192 Light, multi-agent/swarm \u2192 Full)\n- Integration complexity (standalone \u2192 Light, external APIs/auth/DB \u2192 Full)\n\n### PROJECT-DEFINITION.vbrief.json Override\n\n`PROJECT-DEFINITION.vbrief.json` narratives ? declare `\"Process\": \"Light\"` or `\"Process\": \"Full\"` to skip the\ngate entirely. `PROJECT.md` (deprecated) may also carry this field. If the field is absent or empty, the AI MUST ask.\n\n## Workflow Overview\n\n```mermaid\nflowchart LR\n subgraph interview [\"Interview Strategy\"]\n G{\"\u2696\ufe0f Sizing Gate\"}\n I_L[\"\ud83d\udcac Interview<br/><i>Light path</i>\"]\n I_F[\"\ud83d\udcac Interview<br/><i>Full path</i>\"]\n P[\"\ud83d\udcc4 PRD<br/><i>What to build</i>\"]\n S[\"\ud83d\udccb SPECIFICATION<br/><i>How to build it</i>\"]\n end\n\n G -->|\"Light\"| I_L\n G -->|\"Full\"| I_F\n I_L -->|\"Ambiguity resolved\"| S\n I_F -->|\"Ambiguity resolved\"| P\n P -->|\"Approved\"| S\n S -->|\"Ready\"| IMPL[\"\ud83d\udd28 Implementation\"]\n\n style G fill:#f0abfc,stroke:#a21caf,color:#000\n style I_L fill:#c4b5fd,stroke:#7c3aed,color:#000\n style I_F fill:#c4b5fd,stroke:#7c3aed,color:#000\n style P fill:#fef08a,stroke:#ca8a04,color:#000\n style S fill:#6ee7b7,stroke:#059669,color:#000\n style IMPL fill:#7dd3fc,stroke:#0284c7,color:#000\n```\n\n---\n\n## Interview Rules (shared by both paths)\n\n- ~ Use Claude AskInterviewQuestion when available (emulate if not)\n- ! Ask **ONE** focused, non-trivial question per step\n- \u2297 Ask multiple questions at once or sneak in \"also\" questions\n- ~ Provide numbered answer options when appropriate\n- ! Include \"other\" option for custom/unknown responses\n- ! Indicate which option is RECOMMENDED\n- ! When making an opinionated recommendation, state the principle (1 sentence)\n- ! When done, append all questions asked and answers given to the working document\n\n### Question Areas\n\n- ! Missing decisions (language, framework, deployment)\n- ! Edge cases (errors, boundaries, failure modes)\n- ! Implementation details (architecture, patterns, libraries)\n- ! Requirements (performance, security, scalability)\n- ! UX/constraints (users, timeline, compatibility)\n- ! Tradeoffs (simplicity vs features, speed vs safety)\n\n### Transition Criteria (interview complete)\n\n- ! All major decisions have answers\n- ! Edge cases are addressed\n- ! User has approved key tradeoffs (Interview strategy) or Johnbot has chosen recommended options (Yolo strategy)\n- ~ Little ambiguity remains\n\n---\n\n## Light Path (small/medium projects)\n\nInterview \u2192 scope vBRIEFs (date-prefixed in proposed/) + PROJECT-DEFINITION.vbrief.json + rendered SPECIFICATION (v0.20 contract).\n\n### Flow\n\n1. Sizing gate selects Light\n2. Interview (rules above)\n3. Write scope vBRIEF(s) to `./vbrief/proposed/YYYY-MM-DD-<slug>.vbrief.json` (date-prefixed per vbrief filename convention) with `status: proposed`\n4. Run `task project:render` to create/update `./vbrief/PROJECT-DEFINITION.vbrief.json` (full project identity + items registry) and ensure all five lifecycle folders exist\n5. Summarize decisions, ask user to review\n6. On approval, use `task scope:promote` (or equivalent) to move scope vBRIEF(s) to `./vbrief/pending/` with `status: pending` / `approved`\n7. Run `task spec:render` (SPECIFICATION.md is a rendered derivative with deprecation sentinel; `specification.vbrief.json` is legacy and is NOT written by this strategy on the v0.20 path)\n\n! At the emission step (step 3 above), after writing the scope vBRIEF(s) to `./vbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) \u2014 name all three patterns (none / `--umbrella` / `--per-vbrief`).\n\n### SPECIFICATION Structure (Light)\n\n```markdown\n# [Project Name] SPECIFICATION\n\n## Overview\nBrief summary of the project.\n\n## Requirements\n\n### Functional Requirements\n- FR-1: [requirement]\n- FR-2: [requirement]\n\n### Non-Functional Requirements\n- NFR-1: Performance \u2014 [requirement]\n- NFR-2: Security \u2014 [requirement]\n\n## Architecture\nHigh-level system design, components, data flow.\n\n## Implementation Plan\n\n### Phase 1: Foundation\n#### Subphase 1.1: Setup\n- Task 1.1.1: [description] (traces: FR-1)\n - Dependencies: none\n - Acceptance: [criteria]\n\n#### Subphase 1.2: Core (depends on: 1.1)\n- Task 1.2.1: [description] (traces: FR-2, NFR-1)\n\n### Phase 2: Features (depends on: Phase 1)\n...\n\n## Testing Strategy\nHow to verify the implementation meets requirements.\n\n## Deployment\nHow to ship it.\n```\n\n- ! Requirements section MUST appear in SPECIFICATION.md (embedded, no separate PRD)\n- ! Each task SHOULD reference which FR/NFR it implements via `(traces: FR-N)`\n- \u2297 Create a separate PRD.md on the Light path\n\n---\n\n## Full Path (large/complex projects)\n\nInterview \u2192 PRD \u2192 scope vBRIEFs (date-prefixed in proposed/) + PROJECT-DEFINITION.vbrief.json + rendered SPECIFICATION (v0.20 contract).\n\n### Flow\n\n1. Sizing gate selects Full\n2. Interview (rules above)\n3. Generate `PRD.md` \u2014 user approval gate\n4. Write scope vBRIEF(s) to `./vbrief/proposed/YYYY-MM-DD-<slug>.vbrief.json` (date-prefixed per vbrief filename convention) with `status: proposed`\n5. Run `task project:render` to create/update `./vbrief/PROJECT-DEFINITION.vbrief.json` (full project identity + items registry) and ensure all five lifecycle folders exist\n6. Summarize decisions, ask user to review\n7. On approval, use `task scope:promote` (or equivalent) to move scope vBRIEF(s) to `./vbrief/pending/` with `status: pending` / `approved`\n8. Run `task spec:render` (SPECIFICATION.md is a rendered derivative with deprecation sentinel; `specification.vbrief.json` is legacy and is NOT written by this strategy on the v0.20 path)\n\n! At the emission step (step 4 above), after writing the scope vBRIEF(s) to `./vbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) \u2014 name all three patterns (none / `--umbrella` / `--per-vbrief`).\n\n### PRD Structure (Full path only)\n\n```markdown\n# [Project Name] PRD\n\n## Problem Statement\nWhat problem does this solve? Who has this problem?\n\n## Goals\n- Primary goal\n- Secondary goals\n- Non-goals (explicitly out of scope)\n\n## User Stories\nAs a [user type], I want [capability] so that [benefit].\n\n## Requirements\n\n### Functional Requirements\n- FR-1: [requirement]\n- FR-2: [requirement]\n\n### Non-Functional Requirements\n- NFR-1: Performance \u2014 [requirement]\n- NFR-2: Security \u2014 [requirement]\n\n## Success Metrics\nHow do we know this succeeded?\n\n## Open Questions\nAny remaining decisions deferred to implementation.\n```\n\n### PRD Guidelines\n\n- ! Focus on WHAT, not HOW\n- ! Use RFC 2119 language (MUST, SHOULD, MAY)\n- ! Number all requirements for traceability\n- ~ Include acceptance criteria for each requirement\n- \u2297 Include implementation details or architecture\n\n### PRD Transition Criteria\n\n- ! All functional requirements documented\n- ! Non-functional requirements specified\n- ! User has reviewed and approved PRD\n- ~ No blocking open questions remain\n\n### PRD Approval Menu (#740, refs #767)\n\n! After every PRD (Product Requirements Document) review, the agent MUST\npresent the canonical numbered approval menu defined in\n[`../references/plain-english-ux.md`](../references/plain-english-ux.md)\n`## Rule 4`. The menu replaces ambiguous `Accept / Refine / Edit`\nbuttons with action-shaped labels and follows the #767 framework rule\nfor deterministic numbered menus -- the **final two numbered options\nMUST be `Discuss` and `Back`**, in that order.\n\n```\nWhat would you like to do with the PRD (Product Requirements Document)?\n\n 1. Approve and continue (lock the PRD, generate the SPECIFICATION)\n 2. Suggest changes (you describe what to change; the agent rewrites)\n 3. Edit yourself (you edit the PRD directly; the agent waits)\n 4. Discuss\n 5. Back\n\nEnter confirm / b back / 0 discuss\n```\n\n! When `contracts/deterministic-questions.md` lands (Agent 1, #767), this\nstrategy MUST defer to that contract for canonical menu wording.\n\n! When the PRD review surfaces a red/green diff, the agent MUST emit a\nnon-alarming preface above it (per `references/plain-english-ux.md` Rule 5):\n\n```\nHere's what changed since the previous draft. Red lines were removed,\ngreen lines were added. Nothing here is broken -- this is a normal\nreview.\n```\n\n? Alternatively, the agent MAY hide the diff entirely on the first review\npass and present a plain-English summary of changes; show the diff only\non the second pass or when the user explicitly asks for it.\n\n- \u2297 Use plain `Accept / Refine / Edit` buttons without explanatory\n parentheticals.\n- \u2297 Add a numbered approval menu where Discuss and Back are not the\n final two options.\n- \u2297 Show a red/green diff at first review without a non-alarming preface.\n\n### SPECIFICATION Structure (Full)\n\n```markdown\n# [Project Name] SPECIFICATION\n\n## Overview\nBrief summary and link to PRD.\n\n## Architecture\nHigh-level system design, components, data flow.\n\n## Implementation Plan\n\n### Phase 1: Foundation\n#### Subphase 1.1: Setup\n- Task 1.1.1: [description] (traces: FR-1)\n - Dependencies: none\n - Acceptance: [criteria]\n\n#### Subphase 1.2: Core (depends on: 1.1)\n- Task 1.2.1: [description] (traces: FR-2, NFR-1)\n\n### Phase 2: Features (depends on: Phase 1)\n...\n\n## Testing Strategy\nHow to verify the implementation meets requirements.\n\n## Deployment\nHow to ship it.\n```\n\n---\n\n## SPECIFICATION Guidelines (both paths)\n\n- ! Reference requirement IDs (FR-1, NFR-2, etc.) in each task\n- ! Break into phases, subphases, tasks\n- ! Mark ALL dependencies explicitly\n- ! Design for parallel work (multiple agents)\n- ! End each phase/subphase with tests that pass\n- ~ Size tasks for 1-4 hours of work\n- ~ Minimize inter-task dependencies\n- \u2297 Write code (specification only)\n\n### Task Format\n\nEach task SHOULD include:\n- ! Clear description\n- ! Dependencies (or \"none\")\n- ! Acceptance criteria\n- ~ Estimated effort\n- ? Assigned agent (for swarm mode)\n\n### Transition Criteria\n\n- ! All requirements mapped to tasks\n- ! Dependencies form a valid DAG (no cycles)\n- ! Scope vBRIEF(s) exist in `./vbrief/proposed/` (with date-prefixed filenames and `status: \"proposed\"`) or promoted to pending/active (with `status: \"approved\" / \"pending\"`)\n- ! `./vbrief/PROJECT-DEFINITION.vbrief.json` is present (populated via `task project:render`)\n- ! `SPECIFICATION.md` has been rendered via `task spec:render`\n- ! Proceed to [Acceptance Gate](#acceptance-gate)\n\n---\n\n## Acceptance Gate\n\nAfter spec generation, present the user with a final decision before\nimplementation begins.\n\n! The acceptance gate MUST appear after every spec generation (both Light and\nFull paths).\n! The acceptance gate is a **blocking question**. The AI MUST present the\noptions and wait for the user to choose.\n\n### Options\n\n1. **Accept** \u2014 spec is approved, proceed to implementation\n - ! Before handing off to implementation, verify the project toolchain is installed and functional \u2014 see [../coding/toolchain.md](../coding/toolchain.md); stop and report if any required tool is missing\n2. **Revise** \u2014 return to the [Chaining Gate](#chaining-gate) with all prior\n context preserved (completed strategies, artifacts). Run additional\n preparatory strategies or regenerate the spec.\n3. **Switch strategy** \u2014 return to the [Chaining Gate](#chaining-gate) to select\n a different spec-generating strategy (e.g., switch from interview to speckit)\n\n### SPECIFICATION Approval Menu (#740, refs #767)\n\n! In addition to the structured Accept / Revise / Switch options above,\nthe agent MUST present the canonical numbered approval menu defined in\n[`../references/plain-english-ux.md`](../references/plain-english-ux.md)\n`## Rule 4`. The menu states what each choice will actually do, in\nplain-English action-shaped labels, and follows the #767 framework rule\nfor deterministic numbered menus -- the **final two numbered options\nMUST be `Discuss` and `Back`**, in that order.\n\n```\nWhat would you like to do with the SPECIFICATION?\n\n 1. Approve and continue (lock the SPEC, proceed to implementation)\n 2. Suggest changes (you describe what to change; the agent rewrites)\n 3. Edit yourself (you edit the SPEC directly; the agent waits)\n 4. Discuss\n 5. Back\n\nEnter confirm / b back / 0 discuss\n```\n\n! Option 1 (`Approve and continue`) maps to the `Accept` option above\n(which then runs the toolchain verification). Option 2 (`Suggest\nchanges`) and Option 3 (`Edit yourself`) both map to `Revise` (return to\nthe Chaining Gate with prior context preserved). The numbered menu is\nthe user-facing surface; the structured Accept / Revise / Switch above\nis the agent's internal contract.\n\n! When `contracts/deterministic-questions.md` lands (Agent 1, #767), this\nstrategy MUST defer to that contract for canonical menu wording.\n\n! When the SPECIFICATION review surfaces a red/green diff, the agent\nMUST emit a non-alarming preface above it (per\n`references/plain-english-ux.md` Rule 5):\n\n```\nHere's what changed since the previous draft. Red lines were removed,\ngreen lines were added. Nothing here is broken -- this is a normal\nreview.\n```\n\n? Alternatively, the agent MAY hide the diff entirely on the first\nreview pass and present a plain-English summary of changes; show the\ndiff only on the second pass or when the user explicitly asks for it.\n\n- \u2297 Add a numbered approval menu where Discuss and Back are not the\n final two options.\n- \u2297 Show a red/green diff at first review without a non-alarming preface.\n\n### Rejected Spec Archival\n\n- ! When the user chooses \"Revise\" or \"Switch\", the current `SPECIFICATION.md`\n MUST be archived to `history/specs/` before regeneration\n- ! Archived name format: `SPECIFICATION-rejected-{ISO-timestamp}.md`\n (e.g., `SPECIFICATION-rejected-2026-03-15T19-23-00Z.md`)\n- ! If a `PRD.md` exists (Full path), it is NOT archived \u2014 only the spec\n- ~ Include a one-line header in the archived file noting why it was rejected\n\n### State Preservation\n\n- ! All `completedStrategies` and `artifacts` in `plan.vbrief.json` MUST be\n preserved across revisions\n- ! The chaining gate will show updated run counts reflecting the full session history\n\n---\n\n## Artifacts Summary\n\n**Light path:**\n\n| Artifact | Purpose | Created By |\n|----------|---------|------------|\n| `./vbrief/proposed/YYYY-MM-DD-*.vbrief.json` | Scope story vBRIEFs (date-prefixed, v0.20 contract) | Interview |\n| `./vbrief/PROJECT-DEFINITION.vbrief.json` | Project identity gestalt + items registry | `task project:render` (triggered by strategy) |\n| `SPECIFICATION.md` | Generated plan with embedded Requirements (rendered derivative; deprecation sentinel) | `task spec:render` |\n| (no `specification.vbrief.json`) | Legacy artifact \u2014 omitted on v0.20 path | \u2014 |\n\n**Full path:**\n\n| Artifact | Purpose | Created By |\n|----------|---------|------------|\n| `PRD.md` | What to build (approval gate) | Interview |\n| `./vbrief/proposed/YYYY-MM-DD-*.vbrief.json` | Scope story vBRIEFs (date-prefixed, v0.20 contract) | Post-PRD interview |\n| `./vbrief/PROJECT-DEFINITION.vbrief.json` | Project identity gestalt + items registry | `task project:render` (triggered by strategy) |\n| `SPECIFICATION.md` | Generated implementation plan (rendered derivative; deprecation sentinel) | `task spec:render` |\n| (no `specification.vbrief.json`) | Legacy artifact \u2014 omitted on v0.20 path | \u2014 |\n\n## Invoking This Strategy\n\n```\n/deft:run:interview [project name]\n```\n\nOr explicitly:\n\n```\nUse the interview strategy to plan [project].\n```\n\nAfter completion:\n\n```\nimplement the scope vBRIEFs in ./vbrief/active/\n```\n"
|
|
84
|
+
"body": "# Interview Strategy\n\nThe standard Deft workflow: structured interview → SPECIFICATION. This is the\ncanonical source of truth for the interview process. All entry points (CLI via\n`run spec`, agent via `deft-directive-setup` Phase 3, and `templates/make-spec.md`) MUST\nfollow this strategy.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**⚠️ See also**: [strategies/discuss.md](./discuss.md) | [strategies/yolo.md](./yolo.md) | [core/glossary.md](../glossary.md)\n\n## When to Use\n\n- ! Default strategy for all new projects\n- ~ Projects with unclear or evolving requirements\n- ~ When stakeholder alignment is needed before implementation\n- ? Skip to SPECIFICATION phase if requirements are already fully documented\n\n---\n\n## Chaining Gate\n\nBefore spec generation, offer the user a chance to run preparatory strategies\nor switch to a different spec-generating strategy. This gate is the single\norchestration point for strategy composition.\n\n! The chaining gate MUST always be shown — even when the interview strategy is\ninvoked directly with no prior strategy.\n! The chaining gate is a **blocking question**. The AI MUST present the options\nand wait for the user to choose before proceeding.\n⊗ Skip the chaining gate or proceed to the sizing gate without presenting it.\n\n### When It Appears\n\n- ! Before the [Sizing Gate](#sizing-gate) on every entry to the interview strategy\n- ! After each completed preparatory strategy (recursive — the gate reappears)\n- ! After the [Acceptance Gate](#acceptance-gate) when the user chooses \"Revise\" or \"Switch\"\n\n### Options\n\nPresent two groups sourced from the `Type` column in\n[strategies/README.md](./README.md#strategy-types):\n\n**Default:**\n1. **Proceed to specification** (default) — continue to the [Sizing Gate](#sizing-gate)\n\n**Preparatory strategies** (type: `preparatory` — loops back to this gate on completion):\n- Research — investigate the domain, find libraries, identify pitfalls\n- Discuss — lock key decisions using Feynman technique\n- Probe — adversarially stress-test the plan; surface assumptions, edge cases, and risks\n- Map — analyze existing codebase conventions\n\n~ Some preparatory strategies (currently map) also support standalone invocation\nvia `/deft:run:<name>` without entering the interview flow. When invoked standalone,\nthey present their own completion options instead of returning to this gate.\nSee `strategies/map.md` for standalone behavior.\n\n**Switch spec-generating strategy** (type: `spec-generating` — replaces current pipeline):\n- Yolo — auto-pilot, Johnbot picks all answers\n- SpecKit — formal spec process with story readiness before implementation\n\n### Run Count Annotations\n\n- ! Previously-run strategies MUST display with a run count (e.g., `Research (ran 1×)`)\n- ! No strategy is ever removed from the gate — users can re-run any strategy\n- ! Run counts are read from `completedStrategies` in\n [`./vbrief/plan.vbrief.json`](../vbrief/vbrief.md#strategy-chaining-fields)\n\n### State Tracking\n\n- ! On completion of a preparatory strategy, update `completedStrategies` in\n `./vbrief/plan.vbrief.json`: increment `runCount`, append artifact paths\n- ! Append all new artifact paths to the flat `artifacts` array\n- ! The next strategy and eventual spec generation MUST load all artifacts\n listed in `plan.vbrief.json`\n\n### Example Prompt\n\n```\nReady to generate the specification. Before we proceed, would you like to:\n\n1. Proceed to specification (default)\n\n--- Preparatory (loops back) ---\n2. Run a research phase — investigate the domain, find libraries, identify pitfalls\n3. Run a discuss phase — lock key decisions using Feynman technique\n4. Run a probe phase — adversarially stress-test the plan; surface assumptions, edge cases, and risks\n5. Run a map phase — analyze existing codebase conventions\n\n--- Switch strategy ---\n6. Switch to yolo — auto-pilot picks all answers\n7. Switch to speckit — formal spec process with story readiness before implementation\n\n8. Other (specify)\n```\n\n---\n\n## Sizing Gate\n\nBefore the interview begins, determine project complexity to select the\nappropriate path. The gate runs once, immediately after hearing what the user\nwants to build.\n\n! The sizing gate is a **blocking question**. The AI MUST propose a size and\nwait for the user to confirm or override before asking any interview questions.\n⊗ Combine the sizing proposal with the first interview question in the same message.\n⊗ Proceed to interview questions before the user has explicitly confirmed the path.\n\n### Sizing Signals\n\nThe AI SHOULD propose a size based on these signals; the user confirms or overrides:\n\n- Number of features (≤5 → Light, >5 → Full)\n- Number of components/services (1–2 → Light, 3+ → Full)\n- Expected duration (days → Light, weeks/months → Full)\n- Team/agent count (solo → Light, multi-agent/swarm → Full)\n- Integration complexity (standalone → Light, external APIs/auth/DB → Full)\n\n### PROJECT-DEFINITION.vbrief.json Override\n\n`PROJECT-DEFINITION.vbrief.json` narratives ? declare `\"Process\": \"Light\"` or `\"Process\": \"Full\"` to skip the\ngate entirely. `PROJECT.md` (deprecated) may also carry this field. If the field is absent or empty, the AI MUST ask.\n\n## Workflow Overview\n\n```mermaid\nflowchart LR\n subgraph interview [\"Interview Strategy\"]\n G{\"⚖️ Sizing Gate\"}\n I_L[\"💬 Interview<br/><i>Light path</i>\"]\n I_F[\"💬 Interview<br/><i>Full path</i>\"]\n P[\"📄 PRD<br/><i>What to build</i>\"]\n S[\"📋 SPECIFICATION<br/><i>How to build it</i>\"]\n end\n\n G -->|\"Light\"| I_L\n G -->|\"Full\"| I_F\n I_L -->|\"Ambiguity resolved\"| S\n I_F -->|\"Ambiguity resolved\"| P\n P -->|\"Approved\"| S\n S -->|\"Ready\"| IMPL[\"🔨 Implementation\"]\n\n style G fill:#f0abfc,stroke:#a21caf,color:#000\n style I_L fill:#c4b5fd,stroke:#7c3aed,color:#000\n style I_F fill:#c4b5fd,stroke:#7c3aed,color:#000\n style P fill:#fef08a,stroke:#ca8a04,color:#000\n style S fill:#6ee7b7,stroke:#059669,color:#000\n style IMPL fill:#7dd3fc,stroke:#0284c7,color:#000\n```\n\n---\n\n## Interview Rules (shared by both paths)\n\n- ~ Use Claude AskInterviewQuestion when available (emulate if not)\n- ! Ask **ONE** focused, non-trivial question per step\n- ⊗ Ask multiple questions at once or sneak in \"also\" questions\n- ~ Provide numbered answer options when appropriate\n- ! Include \"other\" option for custom/unknown responses\n- ! Indicate which option is RECOMMENDED\n- ! When making an opinionated recommendation, state the principle (1 sentence)\n- ! When done, append all questions asked and answers given to the working document\n\n### Question Areas\n\n- ! Missing decisions (language, framework, deployment)\n- ! Edge cases (errors, boundaries, failure modes)\n- ! Implementation details (architecture, patterns, libraries)\n- ! Requirements (performance, security, scalability)\n- ! UX/constraints (users, timeline, compatibility)\n- ! Tradeoffs (simplicity vs features, speed vs safety)\n\n### Transition Criteria (interview complete)\n\n- ! All major decisions have answers\n- ! Edge cases are addressed\n- ! User has approved key tradeoffs (Interview strategy) or Johnbot has chosen recommended options (Yolo strategy)\n- ~ Little ambiguity remains\n\n---\n\n## Light Path (small/medium projects)\n\nInterview → scope vBRIEFs (date-prefixed in proposed/) + PROJECT-DEFINITION.vbrief.json + rendered SPECIFICATION (v0.20 contract).\n\n### Flow\n\n1. Sizing gate selects Light\n2. Interview (rules above)\n3. Write scope vBRIEF(s) to `./vbrief/proposed/YYYY-MM-DD-<slug>.vbrief.json` (date-prefixed per vbrief filename convention) with `status: proposed`\n4. Run `task project:render` to create/update `./vbrief/PROJECT-DEFINITION.vbrief.json` (full project identity + items registry) and ensure all five lifecycle folders exist\n5. Summarize decisions, ask user to review\n6. On approval, use `task scope:promote` (or equivalent) to move scope vBRIEF(s) to `./vbrief/pending/` with `status: pending` / `approved`\n7. Run `task spec:render` (SPECIFICATION.md is a rendered derivative with deprecation sentinel; `specification.vbrief.json` is legacy and is NOT written by this strategy on the v0.20 path)\n\n! At the emission step (step 3 above), after writing the scope vBRIEF(s) to `./vbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).\n\n### SPECIFICATION Structure (Light)\n\n```markdown\n# [Project Name] SPECIFICATION\n\n## Overview\nBrief summary of the project.\n\n## Requirements\n\n### Functional Requirements\n- FR-1: [requirement]\n- FR-2: [requirement]\n\n### Non-Functional Requirements\n- NFR-1: Performance — [requirement]\n- NFR-2: Security — [requirement]\n\n## Architecture\nHigh-level system design, components, data flow.\n\n## Implementation Plan\n\n### Phase 1: Foundation\n#### Subphase 1.1: Setup\n- Task 1.1.1: [description] (traces: FR-1)\n - Dependencies: none\n - Acceptance: [criteria]\n\n#### Subphase 1.2: Core (depends on: 1.1)\n- Task 1.2.1: [description] (traces: FR-2, NFR-1)\n\n### Phase 2: Features (depends on: Phase 1)\n...\n\n## Testing Strategy\nHow to verify the implementation meets requirements.\n\n## Deployment\nHow to ship it.\n```\n\n- ! Requirements section MUST appear in SPECIFICATION.md (embedded, no separate PRD)\n- ! Each task SHOULD reference which FR/NFR it implements via `(traces: FR-N)`\n- ⊗ Create a separate PRD.md on the Light path\n\n---\n\n## Full Path (large/complex projects)\n\nInterview → PRD → scope vBRIEFs (date-prefixed in proposed/) + PROJECT-DEFINITION.vbrief.json + rendered SPECIFICATION (v0.20 contract).\n\n### Flow\n\n1. Sizing gate selects Full\n2. Interview (rules above)\n3. Generate `PRD.md` — user approval gate\n4. Write scope vBRIEF(s) to `./vbrief/proposed/YYYY-MM-DD-<slug>.vbrief.json` (date-prefixed per vbrief filename convention) with `status: proposed`\n5. Run `task project:render` to create/update `./vbrief/PROJECT-DEFINITION.vbrief.json` (full project identity + items registry) and ensure all five lifecycle folders exist\n6. Summarize decisions, ask user to review\n7. On approval, use `task scope:promote` (or equivalent) to move scope vBRIEF(s) to `./vbrief/pending/` with `status: pending` / `approved`\n8. Run `task spec:render` (SPECIFICATION.md is a rendered derivative with deprecation sentinel; `specification.vbrief.json` is legacy and is NOT written by this strategy on the v0.20 path)\n\n! At the emission step (step 4 above), after writing the scope vBRIEF(s) to `./vbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).\n\n### PRD Structure (Full path only)\n\n```markdown\n# [Project Name] PRD\n\n## Problem Statement\nWhat problem does this solve? Who has this problem?\n\n## Goals\n- Primary goal\n- Secondary goals\n- Non-goals (explicitly out of scope)\n\n## User Stories\nAs a [user type], I want [capability] so that [benefit].\n\n## Requirements\n\n### Functional Requirements\n- FR-1: [requirement]\n- FR-2: [requirement]\n\n### Non-Functional Requirements\n- NFR-1: Performance — [requirement]\n- NFR-2: Security — [requirement]\n\n## Success Metrics\nHow do we know this succeeded?\n\n## Open Questions\nAny remaining decisions deferred to implementation.\n```\n\n### PRD Guidelines\n\n- ! Focus on WHAT, not HOW\n- ! Use RFC 2119 language (MUST, SHOULD, MAY)\n- ! Number all requirements for traceability\n- ~ Include acceptance criteria for each requirement\n- ⊗ Include implementation details or architecture\n\n### PRD Transition Criteria\n\n- ! All functional requirements documented\n- ! Non-functional requirements specified\n- ! User has reviewed and approved PRD\n- ~ No blocking open questions remain\n\n### PRD Approval Menu (#740, refs #767)\n\n! After every PRD (Product Requirements Document) review, the agent MUST\npresent the canonical numbered approval menu defined in\n[`../references/plain-english-ux.md`](../references/plain-english-ux.md)\n`## Rule 4`. The menu replaces ambiguous `Accept / Refine / Edit`\nbuttons with action-shaped labels and follows the #767 framework rule\nfor deterministic numbered menus -- the **final two numbered options\nMUST be `Discuss` and `Back`**, in that order.\n\n```\nWhat would you like to do with the PRD (Product Requirements Document)?\n\n 1. Approve and continue (lock the PRD, generate the SPECIFICATION)\n 2. Suggest changes (you describe what to change; the agent rewrites)\n 3. Edit yourself (you edit the PRD directly; the agent waits)\n 4. Discuss\n 5. Back\n\nEnter confirm / b back / 0 discuss\n```\n\n! When `contracts/deterministic-questions.md` lands (Agent 1, #767), this\nstrategy MUST defer to that contract for canonical menu wording.\n\n! When the PRD review surfaces a red/green diff, the agent MUST emit a\nnon-alarming preface above it (per `references/plain-english-ux.md` Rule 5):\n\n```\nHere's what changed since the previous draft. Red lines were removed,\ngreen lines were added. Nothing here is broken -- this is a normal\nreview.\n```\n\n? Alternatively, the agent MAY hide the diff entirely on the first review\npass and present a plain-English summary of changes; show the diff only\non the second pass or when the user explicitly asks for it.\n\n- ⊗ Use plain `Accept / Refine / Edit` buttons without explanatory\n parentheticals.\n- ⊗ Add a numbered approval menu where Discuss and Back are not the\n final two options.\n- ⊗ Show a red/green diff at first review without a non-alarming preface.\n\n### SPECIFICATION Structure (Full)\n\n```markdown\n# [Project Name] SPECIFICATION\n\n## Overview\nBrief summary and link to PRD.\n\n## Architecture\nHigh-level system design, components, data flow.\n\n## Implementation Plan\n\n### Phase 1: Foundation\n#### Subphase 1.1: Setup\n- Task 1.1.1: [description] (traces: FR-1)\n - Dependencies: none\n - Acceptance: [criteria]\n\n#### Subphase 1.2: Core (depends on: 1.1)\n- Task 1.2.1: [description] (traces: FR-2, NFR-1)\n\n### Phase 2: Features (depends on: Phase 1)\n...\n\n## Testing Strategy\nHow to verify the implementation meets requirements.\n\n## Deployment\nHow to ship it.\n```\n\n---\n\n## SPECIFICATION Guidelines (both paths)\n\n- ! Reference requirement IDs (FR-1, NFR-2, etc.) in each task\n- ! Break into phases, subphases, tasks\n- ! Mark ALL dependencies explicitly\n- ! Design for parallel work (multiple agents)\n- ! End each phase/subphase with tests that pass\n- ~ Size tasks for 1-4 hours of work\n- ~ Minimize inter-task dependencies\n- ⊗ Write code (specification only)\n\n### Task Format\n\nEach task SHOULD include:\n- ! Clear description\n- ! Dependencies (or \"none\")\n- ! Acceptance criteria\n- ~ Estimated effort\n- ? Assigned agent (for swarm mode)\n\n### Transition Criteria\n\n- ! All requirements mapped to tasks\n- ! Dependencies form a valid DAG (no cycles)\n- ! Scope vBRIEF(s) exist in `./vbrief/proposed/` (with date-prefixed filenames and `status: \"proposed\"`) or promoted to pending/active (with `status: \"approved\" / \"pending\"`)\n- ! `./vbrief/PROJECT-DEFINITION.vbrief.json` is present (populated via `task project:render`)\n- ! `SPECIFICATION.md` has been rendered via `task spec:render`\n- ! Proceed to [Acceptance Gate](#acceptance-gate)\n\n---\n\n## Acceptance Gate\n\nAfter spec generation, present the user with a final decision before\nimplementation begins.\n\n! The acceptance gate MUST appear after every spec generation (both Light and\nFull paths).\n! The acceptance gate is a **blocking question**. The AI MUST present the\noptions and wait for the user to choose.\n\n### Options\n\n1. **Accept** — spec is approved, proceed to implementation\n - ! Before handing off to implementation, verify the project toolchain is installed and functional — see [../coding/toolchain.md](../coding/toolchain.md); stop and report if any required tool is missing\n2. **Revise** — return to the [Chaining Gate](#chaining-gate) with all prior\n context preserved (completed strategies, artifacts). Run additional\n preparatory strategies or regenerate the spec.\n3. **Switch strategy** — return to the [Chaining Gate](#chaining-gate) to select\n a different spec-generating strategy (e.g., switch from interview to speckit)\n\n### SPECIFICATION Approval Menu (#740, refs #767)\n\n! In addition to the structured Accept / Revise / Switch options above,\nthe agent MUST present the canonical numbered approval menu defined in\n[`../references/plain-english-ux.md`](../references/plain-english-ux.md)\n`## Rule 4`. The menu states what each choice will actually do, in\nplain-English action-shaped labels, and follows the #767 framework rule\nfor deterministic numbered menus -- the **final two numbered options\nMUST be `Discuss` and `Back`**, in that order.\n\n```\nWhat would you like to do with the SPECIFICATION?\n\n 1. Approve and continue (lock the SPEC, proceed to implementation)\n 2. Suggest changes (you describe what to change; the agent rewrites)\n 3. Edit yourself (you edit the SPEC directly; the agent waits)\n 4. Discuss\n 5. Back\n\nEnter confirm / b back / 0 discuss\n```\n\n! Option 1 (`Approve and continue`) maps to the `Accept` option above\n(which then runs the toolchain verification). Option 2 (`Suggest\nchanges`) and Option 3 (`Edit yourself`) both map to `Revise` (return to\nthe Chaining Gate with prior context preserved). The numbered menu is\nthe user-facing surface; the structured Accept / Revise / Switch above\nis the agent's internal contract.\n\n! When `contracts/deterministic-questions.md` lands (Agent 1, #767), this\nstrategy MUST defer to that contract for canonical menu wording.\n\n! When the SPECIFICATION review surfaces a red/green diff, the agent\nMUST emit a non-alarming preface above it (per\n`references/plain-english-ux.md` Rule 5):\n\n```\nHere's what changed since the previous draft. Red lines were removed,\ngreen lines were added. Nothing here is broken -- this is a normal\nreview.\n```\n\n? Alternatively, the agent MAY hide the diff entirely on the first\nreview pass and present a plain-English summary of changes; show the\ndiff only on the second pass or when the user explicitly asks for it.\n\n- ⊗ Add a numbered approval menu where Discuss and Back are not the\n final two options.\n- ⊗ Show a red/green diff at first review without a non-alarming preface.\n\n### Rejected Spec Archival\n\n- ! When the user chooses \"Revise\" or \"Switch\", the current `SPECIFICATION.md`\n MUST be archived to `history/specs/` before regeneration\n- ! Archived name format: `SPECIFICATION-rejected-{ISO-timestamp}.md`\n (e.g., `SPECIFICATION-rejected-2026-03-15T19-23-00Z.md`)\n- ! If a `PRD.md` exists (Full path), it is NOT archived — only the spec\n- ~ Include a one-line header in the archived file noting why it was rejected\n\n### State Preservation\n\n- ! All `completedStrategies` and `artifacts` in `plan.vbrief.json` MUST be\n preserved across revisions\n- ! The chaining gate will show updated run counts reflecting the full session history\n\n---\n\n## Artifacts Summary\n\n**Light path:**\n\n| Artifact | Purpose | Created By |\n|----------|---------|------------|\n| `./vbrief/proposed/YYYY-MM-DD-*.vbrief.json` | Scope story vBRIEFs (date-prefixed, v0.20 contract) | Interview |\n| `./vbrief/PROJECT-DEFINITION.vbrief.json` | Project identity gestalt + items registry | `task project:render` (triggered by strategy) |\n| `SPECIFICATION.md` | Generated plan with embedded Requirements (rendered derivative; deprecation sentinel) | `task spec:render` |\n| (no `specification.vbrief.json`) | Legacy artifact — omitted on v0.20 path | — |\n\n**Full path:**\n\n| Artifact | Purpose | Created By |\n|----------|---------|------------|\n| `PRD.md` | What to build (approval gate) | Interview |\n| `./vbrief/proposed/YYYY-MM-DD-*.vbrief.json` | Scope story vBRIEFs (date-prefixed, v0.20 contract) | Post-PRD interview |\n| `./vbrief/PROJECT-DEFINITION.vbrief.json` | Project identity gestalt + items registry | `task project:render` (triggered by strategy) |\n| `SPECIFICATION.md` | Generated implementation plan (rendered derivative; deprecation sentinel) | `task spec:render` |\n| (no `specification.vbrief.json`) | Legacy artifact — omitted on v0.20 path | — |\n\n## Invoking This Strategy\n\n```\n/deft:run:interview [project name]\n```\n\nOr explicitly:\n\n```\nUse the interview strategy to plan [project].\n```\n\nAfter completion:\n\n```\nimplement the scope vBRIEFs in ./vbrief/active/\n```\n"
|
|
85
85
|
},
|
|
86
86
|
{
|
|
87
87
|
"id": "map",
|
|
@@ -91,17 +91,17 @@
|
|
|
91
91
|
"map"
|
|
92
92
|
],
|
|
93
93
|
"path": "strategies/map.md",
|
|
94
|
-
"body": "# Map Strategy\n\nStructured analysis of an existing codebase before adding features.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD,
|
|
94
|
+
"body": "# Map Strategy\n\nStructured analysis of an existing codebase before adding features.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**⚠️ See also**: [strategies/interview.md](./interview.md) | [strategies/discuss.md](./discuss.md) | [core/glossary.md](../glossary.md)\n\n> Adapted from [GSD](https://github.com/gsd-build/get-shit-done) map-codebase workflow.\n\n---\n\n## When to Use\n\n- ! When adding features to an existing codebase the agent hasn't seen before\n- ~ When onboarding to a project with unknown conventions\n- ! When exploring an unfamiliar codebase before deciding what to build\n- ? Skip if the codebase is small (<10 files) or the agent already has context\n\n## Invocation Modes\n\nMap supports two modes, determined automatically by context:\n\n- **Standalone** -- invoked directly via `/deft:run:map` with no active interview or\n spec workflow. Runs mapping, presents artifacts, and offers next-step options.\n- **Chained** -- invoked from the [chaining gate](./interview.md#chaining-gate) during\n an active interview/spec workflow. Runs mapping, registers artifacts, and returns to\n the chaining gate.\n\nThe mapping workflow and artifact format are identical in both modes. Only the\ncompletion behavior differs (see [Completion](#completion) below).\n\n## Workflow\n\n```\nMap Codebase → Review Artifacts → Next Steps\n```\n\nMapping produces artifacts that feed into planning so the agent **follows existing conventions** instead of inventing new ones.\n\n---\n\n## Mapping Artifacts\n\n! Before writing output artifacts, follow the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light).\n\nProduce a single `vbrief/proposed/{project}-codebase-map.vbrief.json` with four narratives:\n\n! After emitting this scope vBRIEF, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).\n\n### `Stack` narrative -- Technology inventory\n\n- ! Languages, versions, runtimes\n- ! Frameworks and key dependencies\n- ! Build tools and package managers\n- ~ Environment configuration approach\n\n### `Architecture` narrative -- System design\n\n- ! Layers/components and their responsibilities\n- ! Data flow between components\n- ! Entry points (API routes, CLI, server start)\n- ~ Error handling strategy\n\n### `Conventions` narrative -- How code is written here\n\n- ! Naming conventions (files, functions, variables)\n- ! Import patterns and module organization\n- ! Testing patterns (framework, file naming, assertion style)\n- ! **Be prescriptive**: \"Use camelCase for functions\" not \"some functions use camelCase\"\n\n### `Concerns` narrative -- Technical debt and risks\n\n- ~ TODO/FIXME/HACK inventory with file paths\n- ~ Large files (>500 lines) that may need splitting\n- ~ Stubs and placeholder implementations\n- ~ Missing test coverage areas\n\n---\n\n## Mapping Rules\n\n- ! Include **file paths** with backticks — vague descriptions are not actionable\n- ! Write **current state only** — never what was or what you considered\n- ! Be **prescriptive** — \"Use X pattern\" guides future work; \"X pattern is used\" doesn't\n- ! Answer **\"where do I put new code?\"** — not just what exists\n- ⊗ Read `.env` contents or expose secrets — note existence only\n- ~ Keep each artifact under 200 lines — detail over brevity, but focused\n\n## How Artifacts Feed Downstream\n\n- ! **Planning** loads relevant mapping narratives based on feature type\n- ! **Execution** references `Conventions` narrative to match existing patterns\n- ! **Verification** uses `Concerns` narrative to avoid introducing more debt\n\n---\n\n## Completion\n\n### Artifact Registration (both modes)\n\n- ! On completion, register artifacts in `./vbrief/plan.vbrief.json`:\n - Update `completedStrategies`: increment `runCount` for `\"map\"`,\n append artifact path (`vbrief/proposed/{project}-codebase-map.vbrief.json`)\n - Append the path to the flat `artifacts` array\n- ! The mapping narratives MUST inform subsequent strategies and spec generation:\n - `Conventions` -> implementation constraints\n - `Architecture` -> where new code fits\n - `Concerns` -> things to avoid or fix\n\n### Chained Mode (invoked from chaining gate)\n\n- ! Return to [interview.md Chaining Gate](./interview.md#chaining-gate)\n- ⊗ End the session after mapping without returning to the chaining gate\n\n### Standalone Mode (invoked directly)\n\nAfter presenting the mapping narratives to the user, offer next steps:\n\n```\nMapping complete. Here's what I found:\n - Stack: [brief summary]\n - Architecture: [brief summary]\n - Conventions: [brief summary]\n - Concerns: [brief summary]\n\nArtifact: vbrief/proposed/{project}-codebase-map.vbrief.json\n\nWhat would you like to do next?\n\n1. Start an interview — build a specification informed by this analysis\n2. Run a discuss phase — lock key decisions using Feynman technique\n3. Run a research phase — investigate libraries, alternatives, pitfalls\n4. Done for now — review the artifact and come back later\n```\n\n- ! Present the narrative summary before offering options\n- ! If the user chooses a strategy, invoke it (the artifact persists in `vbrief/proposed/`)\n- ! If the user chooses \"done\", confirm the artifact location and exit cleanly\n- ~ Recommend option 1 (interview) when the user's goal is to build or extend\n- ~ Recommend option 4 (done) when the user's goal is exploration or onboarding\n\n**Handoff rule for chained strategies:** When invoking discuss or research from\nstandalone map, the chaining gate does not exist. On completion of the invoked\nstrategy, the agent MUST return to this standalone next-step menu instead of\nlooking for `interview.md`'s chaining gate.\n\n- ! Tell the invoked strategy that the return target is the standalone map menu\n- ! After the invoked strategy completes and registers its artifacts, re-present\n the standalone next-step options above (with updated run counts)\n\n---\n\n## Invoking This Strategy\n\n```\n/deft:run:map\n```\n\nStandalone — explore a codebase without starting an interview:\n```\nMap this codebase so I can understand it.\n```\n\nBefore an interview — analysis-first, then spec:\n```\nMap this codebase, then use the interview strategy to plan [feature].\n```\n\nOr set in PROJECT-DEFINITION.vbrief.json narratives:\n```json\n\"Strategy\": \"strategies/map.md\"\n```\n"
|
|
95
95
|
},
|
|
96
96
|
{
|
|
97
97
|
"id": "probe",
|
|
98
98
|
"title": "Probe Strategy",
|
|
99
|
-
"description": "Stress-test a plan before committing to it
|
|
99
|
+
"description": "Stress-test a plan before committing to it — relentless interrogation until every branch of the decision tree is resolved.",
|
|
100
100
|
"triggers": [
|
|
101
101
|
"probe"
|
|
102
102
|
],
|
|
103
103
|
"path": "strategies/probe.md",
|
|
104
|
-
"body": "# Probe Strategy\n\nStress-test a plan before committing to it
|
|
104
|
+
"body": "# Probe Strategy\n\nStress-test a plan before committing to it — relentless interrogation until every branch of the decision tree is resolved.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**⚠️ See also**: [strategies/discuss.md](./discuss.md) | [strategies/interview.md](./interview.md) | [core/glossary.md](../glossary.md)\n\n> Inspired by [grill-me](https://github.com/mattpocock/skills/tree/main/grill-me) from [mattpocock/skills](https://github.com/mattpocock/skills). Adapted to directive's preparatory strategy pattern.\n\n---\n\n## When to Use\n\n- ~ Before committing to any significant design decision or architecture choice\n- ~ When a plan has been drafted but not yet stress-tested\n- ! When the user explicitly asks to be probed or challenged on their plan\n- ? Skip when the path forward is unambiguous and small in scope\n\n## Core Principle\n\nThe goal is not alignment — that's `discuss`. Probe is adversarial discovery. It assumes the plan has holes and sets out to find them. Every assumption is challenged, every edge case explored, every dependency branch walked until nothing is unresolved. Where `discuss` builds consensus, `probe` finds what's missing.\n\n---\n\n## Workflow\n\n### Step 1: Establish the plan\n\n- ! Read whatever plan, design, or spec exists in the conversation context\n- ~ If no plan is in context, ask ONE question: \"What's the plan you want me to probe?\"\n- ~ If codebase context is relevant, explore it to answer what you can before asking\n- ⊗ Ask follow-up questions before reading available context\n\n### Step 2: Interrogate relentlessly\n\nWalk the decision tree depth-first. For each unresolved branch:\n\n- ! Ask **ONE** focused question per message\n- ! For each question, provide your recommended answer with brief reasoning\n- ! If the codebase can answer a question, explore it instead of asking the user\n- ~ Follow the thread — if an answer opens new branches, pursue them before moving on\n- ⊗ Ask multiple questions at once\n- ⊗ Accept vague answers — push back: \"What does that mean concretely?\"\n- ⊗ Move to the next branch before the current one is fully resolved\n\n### Question focus areas\n\n- ! **Assumptions** — \"This assumes X is guaranteed — is it?\"\n- ! **Edge cases** — \"What happens when Y is empty / null / at the limit?\"\n- ! **Dependencies** — \"This requires Z to exist — what if it doesn't?\"\n- ! **Failure modes** — \"How does this fail? How is that surfaced to the user?\"\n- ! **Scaling** — \"Does this hold at 10× the expected volume?\"\n- ~ **Security surface** — \"Who can reach this? What's the blast radius if it's wrong?\"\n- ~ **Reversibility** — \"Can this decision be changed later? What's the migration cost?\"\n\n### Transition criteria (probe complete)\n\n- ! All major decision branches have been resolved\n- ! No open assumptions remain\n- ~ User has acknowledged the risks of any deliberately deferred decisions\n- ~ No new branches are surfaced by the last 2–3 questions\n\n---\n\n## Output\n\n! Before writing output artifacts, follow the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light).\n\n### Mechanical guard (`scripts/probe_session.py`)\n\nProbe completion is enforced mechanically — not by prose alone. A per-clone\nsession file at `.deft/probe-session.json` records whether the session is still\n`interrogate` or `complete`, plus the probe `target`, `currentBranch`, and\n`resolvedDecisions`.\n\n- ! At probe start, record the session:\n `uv run python scripts/probe_session.py start --target <scope>`\n- ! While interrogating, record locked/deferred/risk-accepted decisions and\n branch focus with `record` / `set-branch` subcommands as branches resolve\n- ! Before writing probe output or registering `completedStrategies.probe`,\n mark the session complete:\n `uv run python scripts/probe_session.py complete`\n- ! Immediately before artifact or plan registration, run the guard:\n - `uv run python scripts/probe_session.py guard-artifact --path vbrief/proposed/{scope}-probe.vbrief.json`\n - `uv run python scripts/probe_session.py guard-plan-registration`\n- ⊗ Write probe artifacts or update `completedStrategies.probe` while the\n session state is still `interrogate` — the guard exits non-zero with an\n actionable recovery message\n\n**Recovery when the guard blocks handoff:** continue interrogation until the\n[transition criteria](#transition-criteria-probe-complete) are met, record\ndecisions with `probe_session.py record`, run `probe_session.py complete`,\nthen retry the guard before writing artifacts or updating `plan.vbrief.json`.\n\n`{scope}` is the project name from `PROJECT-DEFINITION.vbrief.json`, or the\nfeature/component name if probing a sub-scope. Use the same value consistently\nthroughout the session. Examples: `my-app-probe`, `auth-probe`.\n\n- ! Produce a `vbrief/proposed/{scope}-probe.vbrief.json` scope vBRIEF with three mandatory narratives:\n - `LockedDecisions` — what was resolved and why\n - `SurfacedRisks` — concerns raised, even if not fully resolved\n - `DeferredDecisions` — explicitly acknowledged items with justification\n- ! Each entry in a narrative includes: **question asked**, **answer given**, **status** (locked / deferred / risk-accepted)\n- ! This vBRIEF is injected into all downstream work: planning, execution, verification\n- ! Persist significant decisions as vBRIEF narratives on the relevant plan items\n- ⊗ Write probe output to a hand-authored markdown file — use vBRIEF narratives for token-efficient, machine-consumable agent consumption (mirrors the [discuss](./discuss.md) and [research](./research.md) output contracts so the chaining-gate flow-through guarantee is mechanical, not aspirational)\n\n! After emitting the probe scope vBRIEF to `vbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).\n\n---\n\n## Then: Chaining Gate\n\nAfter the probe is complete and `vbrief/proposed/{scope}-probe.vbrief.json` is\nwritten, return to the [chaining gate](./interview.md#chaining-gate).\n\n- ! On completion, register artifacts in `./vbrief/plan.vbrief.json`:\n - Update `completedStrategies`: increment `runCount` for `\"probe\"`,\n append artifact path (`vbrief/proposed/{scope}-probe.vbrief.json`)\n - Append the path to the flat `artifacts` array\n- ! Return to [interview.md Chaining Gate](./interview.md#chaining-gate)\n- ! The `LockedDecisions`, `SurfacedRisks`, and `DeferredDecisions` narratives from `vbrief/proposed/{scope}-probe.vbrief.json` MUST flow\n into subsequent strategies and spec generation:\n - Locked decisions become constraints in the specification\n - Surfaced risks become NFRs or explicit acceptance criteria\n - Deferred decisions appear as open questions in the spec\n- ⊗ End the session after probe without returning to the chaining gate\n or the invoking strategy's next-step menu\n\n! **Standalone context:** If invoked from a standalone strategy (e.g. map's\n standalone next-step menu) rather than from the interview chaining gate,\n return to the invoking strategy's menu instead.\n\n---\n\n## Anti-Patterns\n\n- ⊗ Accepting \"we'll figure it out later\" without marking it as explicitly deferred\n- ⊗ Asking generic checklist questions instead of following the decision tree\n- ⊗ Letting vague answers pass without pushing for concrete specifics\n- ⊗ Using codebase exploration as a substitute for asking the user about deliberate design choices\n- ⊗ Stopping when the conversation feels comfortable — stop when no new branches emerge\n- ⊗ Ending after probe without chaining back to the gate (chained mode; in standalone context, returning to the invoking strategy's menu satisfies the completion requirement per the [standalone-context rule](#then-chaining-gate))\n- ⊗ Writing probe output to a plain markdown file (`{scope}-probe.md`) instead of the canonical `vbrief/proposed/{scope}-probe.vbrief.json` scope vBRIEF — plain markdown bypasses the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light) and breaks the downstream-consumer flow-through guarantee\n"
|
|
105
105
|
},
|
|
106
106
|
{
|
|
107
107
|
"id": "rapid",
|
|
@@ -111,17 +111,17 @@
|
|
|
111
111
|
"rapid"
|
|
112
112
|
],
|
|
113
113
|
"path": "strategies/rapid.md",
|
|
114
|
-
"body": "# Rapid Strategy\n\nQuick prototyping workflow -- v0.20 date-prefixed story vBRIEF output with minimal gates and fast iteration.\n\n**v0.20 note (s5-migrate-speckit-rapid-enterprise / #1166):** Rapid now emits only the canonical v0.20 shape (date-prefixed story vBRIEFs in proposed/, full PROJECT-DEFINITION.vbrief.json via task project:render, seeded lifecycle folders, no legacy specification.vbrief.json). See the dedicated ## v0.20 Output Shape section and the canonical contract `strategies/v0-20-contract.md` (s1-contract of #1166).\n\nLegend (from RFC2119): !=MUST, ~=SHOULD,
|
|
114
|
+
"body": "# Rapid Strategy\n\nQuick prototyping workflow -- v0.20 date-prefixed story vBRIEF output with minimal gates and fast iteration.\n\n**v0.20 note (s5-migrate-speckit-rapid-enterprise / #1166):** Rapid now emits only the canonical v0.20 shape (date-prefixed story vBRIEFs in proposed/, full PROJECT-DEFINITION.vbrief.json via task project:render, seeded lifecycle folders, no legacy specification.vbrief.json). See the dedicated ## v0.20 Output Shape section and the canonical contract `strategies/v0-20-contract.md` (s1-contract of #1166).\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**⚠️ See also**: [strategies/interview.md](./interview.md) | [strategies/yolo.md](./yolo.md) | [strategies/README.md](./README.md) | [strategies/v0-20-contract.md](./v0-20-contract.md) | [artifact-guards.md](./artifact-guards.md)\n\n> Ship a throwaway prototype fast. Skip the PRD, skip approval gates, produce a\n> date-prefixed vBRIEF in proposed/ + PROJECT-DEFINITION and start building. Suited for spikes, proof-of-concepts, and\n> disposable experiments where learning speed matters more than long-term quality.\n\n---\n\n## When to Use\n\n- ~ Throwaway prototypes, spikes, and proof-of-concept experiments\n- ~ Validating a technical approach before committing to a full spec cycle\n- ~ Solo explorations where the cost of rework is low\n- ? Time-boxed experiments (e.g. \"spend 2 hours proving this works\")\n- ⊗ Production features, shared libraries, or anything with downstream consumers\n\n---\n\n## Workflow\n\n### Step 1: State the Goal\n\n! Describe the prototype goal in one sentence: what are you trying to learn or prove?\n\n- ! Record the goal in a new date-prefixed story vBRIEF written to `vbrief/proposed/YYYY-MM-DD-<kebab-slug>.vbrief.json` (e.g. as the plan title or a brief narrative in the v0.6 schema). Use today's date for the prefix and a descriptive slug.\n- ~ Include a time-box if applicable (e.g. \"4-hour spike\")\n- ⊗ Skip this step -- even throwaway work needs a clear objective\n\n### Step 2: Minimal Interview\n\n! Ask only the questions needed to unblock implementation. Skip sizing gate, skip PRD.\n\n- ! Identify: target platform, primary language, key dependency or API\n- ~ 3-5 questions maximum -- bias toward defaults and moving fast\n- ⊗ Run the full interview questionnaire -- that defeats the purpose of rapid\n\n### Step 3: Generate date-prefixed vBRIEF in proposed/ (Forced-Light Path)\n\n! Before writing output artifacts, follow the guards in [artifact-guards.md](./artifact-guards.md) (Preparatory Guard for proposed/ scope items; Spec-Generating Guard for PROJECT-DEFINITION).\n\n! Write a slim story scope vBRIEF to `vbrief/proposed/YYYY-MM-DD-<kebab-slug>.vbrief.json` -- no PRD, no approval gate. Decompose the rapid plan into one or more focused, buildable story vBRIEFs (v0.6 schema) rather than a monolithic legacy spec.\n\n- ! Use the Light path from [interview.md](./interview.md) unconditionally\n- ! Mark `plan.status` as `draft` (not `approved`) to signal prototype quality\n- ! After the proposed/ vBRIEF(s) are written, invoke `task project:render` (from repo root) to generate/refresh the complete `vbrief/PROJECT-DEFINITION.vbrief.json`\n- ~ Keep tasks coarse-grained -- 3-5 tasks is typical for a spike\n- ⊗ Generate a PRD or require approval -- rapid skips both\n- ⊗ Hand-author `SPECIFICATION.md` directly -- it is a rendered derivative only (see v0.20 Output Shape)\n\n! After emitting the proposed/ story vBRIEF(s), surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).\n\n### Step 4: Build\n\n! Implement against the spec. Quality gates are relaxed but not absent.\n\n- ! Tests are still required, but coverage gate is relaxed to ≥50%\n- ~ Favour working code over clean code -- refactor later if the prototype graduates\n- ! `task check` must still pass (lint + fmt + tests)\n- ⊗ Skip `task check` entirely -- even prototypes must compile and pass basic checks\n\n### Step 5: Evaluate\n\n! At the end of the time-box (or when the prototype is done), decide next steps.\n\n- ! Record findings: what worked, what didn't, what surprised you\n- ~ Options: discard, iterate, or graduate to a full spec cycle via [interview.md](./interview.md)\n- ! If graduating: start a fresh interview -- do not carry forward the rapid spec as-is\n\n---\n\n## Output Artifacts\n\n- `vbrief/proposed/YYYY-MM-DD-*.vbrief.json` (one or more) -- lightweight story scope vBRIEF(s) with `draft` status (primary artifact; date-prefixed per v0.20 contract)\n- `vbrief/PROJECT-DEFINITION.vbrief.json` -- complete project gestalt + items registry (via `task project:render` invoked by Rapid)\n- `vbrief/{proposed,pending,active,completed,cancelled}/` -- all five lifecycle folders seeded\n- (optional derivative) `SPECIFICATION.md` -- read-only human-readable export (includes deprecated-redirect sentinel; via `task spec:render` if invoked)\n- Prototype code (may be discarded)\n- Findings summary (inline in the proposed/ vBRIEF or as a separate note)\n\n---\n\n## Fits into Chaining Gate\n\nRapid is a **spec-generating** strategy. Selecting it at the chaining gate produces date-prefixed story vBRIEF(s) in `vbrief/proposed/` (and refreshes `vbrief/PROJECT-DEFINITION.vbrief.json` via `task project:render`) and moves directly to implementation. There is no chaining back to preparatory strategies. See the v0.20 Output Shape section below for the exact contract.\n\n---\n\n## Anti-Patterns\n\n- ⊗ Using rapid for production features -- rapid output is explicitly throwaway\n- ⊗ Graduating a rapid prototype without a fresh spec cycle -- the shortcuts compound\n- ⊗ Running the full interview or PRD path -- that's interview strategy, not rapid\n- ⊗ Skipping `task check` -- even prototypes must pass basic quality checks\n- ⊗ Omitting the goal statement -- undirected spikes waste time\n- ⊗ Emitting the legacy singular specification artifact or bare-named vBRIEFs -- violates the v0.20 contract (see strategies/v0-20-contract.md)\n\n---\n\n## v0.20 Output Shape (s5-migrate-speckit-rapid-enterprise / #1166)\n\nThis strategy has been migrated to the full v0.20 output shape so rapid-generated projects are accepted by the build skill Pre-Cutover Detection Guard with zero errors on first attempt (resolves the rapid row from the #1166 inconsistency table and the s5 story acceptance criteria).\n\n- ! Seed the five lifecycle folders under `vbrief/` if any are missing: `proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`.\n- ! Emit story scope items exclusively as date-prefixed scope vBRIEFs: `vbrief/proposed/YYYY-MM-DD-<kebab-slug>.vbrief.json` (use the run's creation date for the prefix; choose descriptive slugs). Decompose the rapid plan into one or more focused, buildable story vBRIEFs (v0.6 schema) rather than a monolithic legacy spec.\n- ! After the proposed/ stories are written, invoke `task project:render` (run from the repo root) to generate/refresh the complete `vbrief/PROJECT-DEFINITION.vbrief.json` (items registry is derived from the lifecycle folders).\n- ⊗ Never emit `vbrief/specification.vbrief.json` (or any legacy dual-write).\n- ~ `SPECIFICATION.md` at the project root, if produced at all, must be only a read-only derivative (e.g. via `task spec:render` after the vbriefs exist) that includes the v0.20 deprecated-redirect sentinel. The source of truth is the vbrief/ lifecycle stories + PROJECT-DEFINITION.\n- ! Before writing any proposed/ stories or PROJECT-DEFINITION, follow the guards in [artifact-guards.md](./artifact-guards.md) (Preparatory Guard for scope items in proposed/; Spec-Generating Guard for PROJECT-DEFINITION).\n- ! Final output tree must pass the deterministic v0.20 strategy output validation gate (s2-deterministic-gate) and the build Pre-Cutover Detection Guard with zero warnings/errors. See full acceptance in the s5 vBRIEF and the 1166 decomposition.\n- ! Cite the canonical contract `strategies/v0-20-contract.md` (s1-contract) for the exact shape and the per-strategy table row.\n\n---\n\n## Artifacts Summary (v0.20)\n\n**Rapid (Forced-Light path):**\n\n| Artifact | Purpose | Created By |\n|----------|---------|------------|\n| `vbrief/proposed/YYYY-MM-DD-*.vbrief.json` (one or more) | Focused story scope items (date-prefixed per vbrief convention and v0.20 contract) | Rapid |\n| `vbrief/PROJECT-DEFINITION.vbrief.json` | Project identity gestalt + complete scope items registry | `task project:render` (invoked by Rapid) |\n| `vbrief/{proposed,pending,active,completed,cancelled}/` | All five lifecycle folders seeded | Rapid |\n| (optional derivative) `SPECIFICATION.md` | Human-readable plan (includes deprecated-redirect sentinel) | `task spec:render` (if invoked) |\n\n**Pre-v0.20 / legacy artifacts that MUST NOT be produced by this strategy:**\n\n- `vbrief/specification.vbrief.json`\n- Primary handoff `SPECIFICATION.md` at project root (without sentinel)\n- Bare-named vBRIEFs in proposed/\n\nSee the full table and rules in `strategies/v0-20-contract.md` (rapid row: Must Create Lifecycle Folders: Yes; Must Write PROJECT-DEFINITION: Yes; Scope vBRIEFs Location: proposed/YYYY-MM-DD-*.vbrief.json only; specification.vbrief.json: Never; SPECIFICATION.md / PROJECT.md: Omit or deprecation redirect only).\n\n---\n\n## Invoking This Strategy\n\n```\n /deft:run:rapid [project name]\n```\n\nOr explicitly:\n"
|
|
115
115
|
},
|
|
116
116
|
{
|
|
117
117
|
"id": "research",
|
|
118
118
|
"title": "Research Strategy",
|
|
119
|
-
"description": "Look before you leap
|
|
119
|
+
"description": "Look before you leap — investigate the domain before planning.",
|
|
120
120
|
"triggers": [
|
|
121
121
|
"research"
|
|
122
122
|
],
|
|
123
123
|
"path": "strategies/research.md",
|
|
124
|
-
"body": "# Research Strategy\n\nLook before you leap
|
|
124
|
+
"body": "# Research Strategy\n\nLook before you leap — investigate the domain before planning.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**⚠️ See also**: [strategies/interview.md](./interview.md) | [strategies/discuss.md](./discuss.md) | [strategies/map.md](./map.md)\n\n> Adapted from [GSD](https://github.com/gsd-build/get-shit-done) research phase.\n\n---\n\n## When to Use\n\n- ~ Before planning a feature in an unfamiliar domain (auth, payments, real-time, etc.)\n- ~ When the feature involves libraries or APIs the agent hasn't used in this project\n- ? Skip for well-understood domains where the agent has strong existing context\n\n## Output\n\n! Before writing output artifacts, follow the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light).\n\nProduce `vbrief/proposed/{feature}-research.vbrief.json` with two mandatory narratives:\n\n! After emitting this scope vBRIEF, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).\n\n### `DontHandRoll` narrative\n\nProblems that look simple but have existing, battle-tested solutions.\n\n- ! For each problem area, specify: **problem**, **recommended library/tool**, **why not hand-roll**\n- ! Check the project's existing dependencies first -- don't add a library when one is already available\n- ~ Consult official docs for the recommended library (use Context7 or equivalent)\n\n**Example narrative content:**\n```\nProblem: JWT validation\nUse: jose\nRationale: Edge cases in token expiry, key rotation, algorithm confusion\n\nProblem: Email templates\nUse: react-email\nRationale: HTML email rendering is notoriously broken across clients\n\nProblem: Rate limiting\nUse: express-rate-limit\nRationale: IP spoofing, distributed state, Redis integration\n```\n\n### `CommonPitfalls` narrative\n\nWhat goes wrong in this domain, why, and how to avoid it.\n\n- ! For each pitfall: **what happens**, **why it happens**, **how to avoid it**, **warning signs**\n- ~ Informed by library docs, codebase patterns, and known failure modes\n- ~ Prioritize pitfalls that agents specifically tend to hit (stubs, missing error handling, hardcoded values)\n\n**Example narrative content:**\n```\nPitfall: Storing plain-text passwords\nWhat: User passwords saved without hashing\nWhy: Agent implements the happy path and forgets security\nAvoid: Use bcrypt/argon2, never store raw passwords\nWarning signs: No crypto import in auth module, password field stored as-is\n```\n\n### `IPRisk` narrative (#738)\n\n! When the project description, the `Don't Hand-Roll` survey, or the\nresearch notes reference third-party intellectual property (IP), the\nresearch phase MUST run the IP-risk heuristic from\n[`../references/ip-risk.md`](../references/ip-risk.md) -- canonical\nimplementation `scripts/ip_risk.py:detect_ip_terms` -- and persist a\nplain-English `IPRisk` narrative on the research vBRIEF.\n\nThe heuristic is permissive on purpose: recognizable IP names (Magic:\nThe Gathering, Pokemon, etc.), fictional-universe terms (Hogwarts,\nTatooine), branded characters, sports leagues, and trademarked products\nall trigger a hit.\n\n- ! When `detect_ip_terms` returns at least one hit, the research output\n MUST: (1) ask the explicit monetization-intent question (personal vs\n commercial); (2) emit `plain_risk_summary(hits, intent)` into the\n `IPRisk` narrative; (3) plan to inject the protection scope items\n (`ip_risk_scope_items(intent)`) at SPECIFICATION-generation time.\n- ! On `commercial` intent, surface the **non-optional** lawyer-\n consultation recommendation in the research output -- this carries\n forward into the interview output and the SPECIFICATION via the\n `IPRisk` narrative.\n- ⊗ Treat the absence of detected terms as proof that the project is\n IP-free. The heuristic only knows about the curated lists; when the\n research scope is vague, ask the user directly whether the project is\n based on a game / film / sports league / brand.\n- ⊗ Provide legal advice -- Deft is not a law firm. The only\n recommendation it makes is **consult a lawyer**.\n\n---\n\n## How Research Feeds Downstream\n\n- ! **Planning** reads research before task decomposition — acceptance criteria account for pitfalls\n- ! **Execution** references \"Don't Hand-Roll\" — agent uses recommended libraries, not custom code\n- ~ **Verification** checks for pitfall warning signs during stub detection\n\n## Research Scope Rules\n\n- ! Research the **current feature only** — not the entire project\n- ! Time-box research — if it takes longer than the feature, scope is wrong\n- ⊗ Research as a reason to delay execution indefinitely\n- ~ Research persists as a vBRIEF in `vbrief/proposed/`\n\n---\n\n## Then: Chaining Gate\n\nAfter research is complete, return to the [chaining gate](./interview.md#chaining-gate)\nso the user can run additional preparatory strategies or proceed to spec generation.\n\n- ! On completion, register artifacts in `./vbrief/plan.vbrief.json`:\n - Update `completedStrategies`: increment `runCount` for `\"research\"`,\n append artifact path (`vbrief/proposed/{feature}-research.vbrief.json`)\n - Append the path to the flat `artifacts` array\n- ! Return to [interview.md Chaining Gate](./interview.md#chaining-gate)\n- ! The research findings MUST inform subsequent strategies and spec generation:\n - \"Don't Hand-Roll\" items become constraints in the specification\n - \"Common Pitfalls\" become acceptance criteria or NFRs\n- ⊗ End the session after research without returning to the chaining gate\n or the invoking strategy's next-step menu\n\n! **Standalone context:** If invoked from a standalone strategy (e.g. map's\n standalone next-step menu) rather than from the interview chaining gate,\n return to the invoking strategy's menu instead.\n\n---\n\n## Workflow\n\n1. **Scope** -- Identify the domain and feature boundaries for research\n2. **Survey** -- Check existing project dependencies, official docs, and known pitfalls\n3. **Document** -- Produce `vbrief/proposed/{feature}-research.vbrief.json` with `DontHandRoll` and `CommonPitfalls` narratives\n4. **Chain** -- Return to [interview.md Chaining Gate](./interview.md#chaining-gate), or -- if invoked from a standalone strategy (e.g. map's standalone next-step menu) -- return to the invoking strategy's menu per the [standalone-context rule](#then-chaining-gate) above\n\n## Anti-Patterns\n\n- ⊗ Building custom solutions for solved problems\n- ⊗ Skipping research for unfamiliar domains (\"how hard can auth be?\")\n- ⊗ Research that produces a reading list instead of actionable guidance\n- ⊗ Research that doesn't flow into planning (written and never referenced)\n- ⊗ Ending after research without chaining into specification generation (chained mode; in standalone context, returning to the invoking strategy's menu satisfies the completion requirement per the [standalone-context rule](#then-chaining-gate))\n"
|
|
125
125
|
},
|
|
126
126
|
{
|
|
127
127
|
"id": "roadmap",
|
|
@@ -141,7 +141,7 @@
|
|
|
141
141
|
"speckit"
|
|
142
142
|
],
|
|
143
143
|
"path": "strategies/speckit.md",
|
|
144
|
-
"body": "# SpecKit Strategy\n\nA spec-driven development workflow inspired by [GitHub's spec-kit](https://github.com/github/spec-kit), with a Phase 4.5 readiness layer for decomposing broad implementation scopes into swarm-safe stories. Fully migrated to v0.20 (phases + stories emitted as date-prefixed vBRIEFs in proposed/; no legacy specification.vbrief.json).\n\n**v0.20 note (s5-migrate-speckit-rapid-enterprise / #1166):** Speckit now emits only the canonical v0.20 shape (date-prefixed phase/epic + story vBRIEFs in proposed/, full PROJECT-DEFINITION.vbrief.json via task project:render or spec:render post, seeded lifecycle folders, no legacy specification.vbrief.json). Phase 4/4.5 scopes go to proposed/ (not pending/). See the dedicated ## v0.20 Output Shape section, the Artifacts Summary updated to the contract table, and the canonical contract `strategies/v0-20-contract.md` (s1-contract of #1166).\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, \u2249=SHOULD NOT, \u2297=MUST NOT, ?=MAY.\n\n**\u26a0\ufe0f See also**: [strategies/interview.md](./interview.md) | [strategies/discuss.md](./discuss.md) | [core/glossary.md](../glossary.md) | [strategies/v0-20-contract.md](./v0-20-contract.md) | [artifact-guards.md](./artifact-guards.md) | [vbrief/vbrief.md](../vbrief/vbrief.md)\n\n## When to Use\n\n- ~ Large or complex projects with multiple contributors\n- ~ Projects requiring formal specification review\n- ~ When parallel agent development is planned\n- ~ Enterprise environments with compliance requirements\n- ? Skip Phase 1 if PROJECT-DEFINITION.vbrief.json Principles narrative already defined\n\n## Workflow Overview\n\n```mermaid\nflowchart LR\n subgraph speckit [\"SpecKit Strategy (v0.20)\"]\n P[\"\ud83d\udcdc Principles<br/><i>PROJECT-DEFINITION.vbrief.json</i>\"]\n S[\"\ud83d\udcdd Specify<br/><i>WHAT/WHY \u2192 proposed/YYYY-MM-DD-*.vbrief.json</i>\"]\n PL[\"\ud83c\udfd7\ufe0f Plan<br/><i>HOW \u2192 proposed/YYYY-MM-DD-*.vbrief.json</i>\"]\n T[\"\u2705 Scope<br/><i>Phase/epic vBRIEFs in proposed/</i>\"]\n D[\"\ud83e\udde9 Decompose<br/><i>Story vBRIEFs in proposed/</i>\"]\n I[\"\ud83d\udd28 Implement<br/><i>Execute</i>\"]\n end\n\n P -->|\"Established\"| S\n S -->|\"Approved\"| PL\n PL -->|\"Reviewed\"| T\n T -->|\"Approved\"| D\n D -->|\"Ready stories\"| I\n\n style P fill:#c4b5fd,stroke:#7c3aed,color:#000\n style S fill:#fef08a,stroke:#ca8a04,color:#000\n style PL fill:#6ee7b7,stroke:#059669,color:#000\n style T fill:#7dd3fc,stroke:#0284c7,color:#000\n style D fill:#fde68a,stroke:#d97706,color:#000\n style I fill:#f0abfc,stroke:#a855f7,color:#000\n```\n\n(See ## v0.20 Output Shape for exact artifact rules, the mandatory `task project:render` / `task spec:render` post calls, and citation of strategies/v0-20-contract.md.)\n\n---\n\n## Phase 1: Principles\n\n**Goal:** Establish immutable project principles before any specification.\n\n**Output:** `Principles` narrative in `vbrief/PROJECT-DEFINITION.vbrief.json` (v0.20: plus any early proposed/ context vBRIEFs if needed)\n\n! Before writing output artifacts, follow the guards in [artifact-guards.md](./artifact-guards.md) (Preparatory Guard for proposed/ items; Spec-Generating Guard for PROJECT-DEFINITION).\n\n### Process\n\n- ! Define 3-5 non-negotiable principles\n- ! Include at least one anti-principle (\u2297)\n- ! Write principles as the `Principles` narrative in `vbrief/PROJECT-DEFINITION.vbrief.json`\n- ~ Interview stakeholders about architectural constraints\n- \u2297 Proceed without defined principles\n- \u2297 Create a standalone `project.md` -- principles belong in PROJECT-DEFINITION.vbrief.json\n\n### Transition Criteria\n\n- ! `Principles` narrative in `vbrief/PROJECT-DEFINITION.vbrief.json` is complete\n- ! All stakeholders have reviewed principles\n- ~ No `[NEEDS CLARIFICATION]` markers remain\n\n---\n\n## Phase 2: Specify (WHAT/WHY)\n\n**Goal:** Document WHAT to build and WHY, without implementation details.\n\n**Output:** WHAT/WHY narratives in date-prefixed vBRIEF(s) in `vbrief/proposed/YYYY-MM-DD-*.vbrief.json` (v0.20; no singular specification.vbrief.json)\n\n! Before writing output artifacts, follow the guards in [artifact-guards.md](./artifact-guards.md) (Preparatory Guard for proposed/ scope items; Spec-Generating Guard for PROJECT-DEFINITION).\n\nWrite the following narrative keys into the proposed/ vBRIEF `plan.narratives`\n\n- `ProblemStatement` -- what problem this solves\n- `Goals` -- desired outcomes\n- `UserStories` -- user scenarios with priorities (P1, P2, P3) and acceptance scenarios (Given/When/Then)\n- `Requirements` -- numbered functional (FR-001) and non-functional (NFR-001) requirements\n- `SuccessMetrics` -- measurable success criteria (SC-001)\n- `EdgeCases` -- boundary conditions and error handling\n\n### Guidelines\n\n- ! Focus on WHAT users need and WHY\n- ! Use `[NEEDS CLARIFICATION: question]` for any ambiguity\n- ! Number all requirements (FR-001, NFR-001) for traceability\n- ! Prioritize user stories (P1, P2, P3)\n- \u2297 Include HOW to implement (no tech stack, APIs, code)\n- \u2297 Guess when uncertain -- mark it instead\n- \u2297 Create `specs/` directories or standalone `spec.md` files -- all content goes in the proposed/ date-prefixed vBRIEF(s)\n\n### Transition Criteria\n\n- ! No `[NEEDS CLARIFICATION]` markers remain in narratives\n- ! All user stories have acceptance scenarios\n- ! Requirements are testable and unambiguous\n- ! Stakeholders have approved specification narratives\n\n---\n\n## Phase 3: Plan (HOW)\n\n**Goal:** Document HOW to build it with technical decisions.\n\n**Input:** Approved WHAT/WHY narratives in the proposed/ date-prefixed vBRIEF(s) from Phase 2\n\n**Output:** HOW narratives enriching the proposed/ vBRIEF(s) (v0.20; no singular specification.vbrief.json)\n\nAdd the following narrative keys to the proposed/ vBRIEF `plan.narratives`:\n\n- `Architecture` -- high-level system design (components, data model, API contracts)\n- `TechDecisions` -- technology choices with rationale\n- `ImplementationPhases` -- phased delivery plan with dependencies\n- `PreImplementationGates` -- simplicity gate, test-first gate\n\n### Guidelines\n\n- ! Reference spec requirements (FR-001, etc.) from Phase 2 narratives\n- ! Document rationale for every technology choice\n- ! Pass all pre-implementation gates before proceeding\n- \u2297 Write implementation code\n- \u2297 Create `specs/` directories or standalone `plan.md` files -- all content goes in the proposed/ date-prefixed vBRIEF(s)\n\n### Post-Phase 3 Transition Gate: Render for Review\n\n! Phase 3 -> Phase 4 is gated on an explicit render-and-review step, mirroring the Phase 2 approval gate. Complete the steps below **in order** before advancing. [skills/deft-directive-setup/SKILL.md](../skills/deft-directive-setup/SKILL.md) is required to invoke `task spec:render` at this boundary when running speckit interactively; the gate fails silently otherwise (yolo-mode agents used to skip it -- that is what this gate exists to prevent).\n\n1. ! Run `task spec:render` (or `task project:render`) to (re-)produce derivative views from the proposed/ vBRIEFs + PROJECT-DEFINITION if needed for human review.\n2. ! Confirm any rendered `SPECIFICATION.md` (if emitted as derivative) exists at the project root and contains the `<!-- deft:deprecated-redirect -->` sentinel.\n3. ! The proposed/ vBRIEFs + PROJECT-DEFINITION are the source of truth. Derivatives are read-only exports.\n4. ! Human reviewer approves (or requests changes). On approval, proceed to Phase 4.\n\n### Transition Criteria\n\n- ! All gates pass (or exceptions documented)\n- ! Every spec requirement maps to a plan element\n- ! Architecture reviewed and approved\n- ! **Phase 3 -> Phase 4 transition criterion:** The proposed/ date-prefixed vBRIEF(s) + PROJECT-DEFINITION represent the approved spec (agents MUST NOT advance to Phase 4 without review of the v0.20 artifacts).\n\n---\n\n## Phase 4: Implementation Phase / Epic Scope Emission (v0.20)\n\n**Goal:** Emit one broad scope vBRIEF per implementation phase or epic (plus stories via 4.5) so downstream tooling (`task roadmap:render`, `task project:render`, and Phase 4.5 decomposition) can operate against the lifecycle model described in [vbrief/vbrief.md](../vbrief/vbrief.md). All emitted to `proposed/` per v0.20 contract.\n\n**Input:** Approved HOW narratives in the proposed/ date-prefixed vBRIEF(s) from Phase 3 (`ImplementationPhases` narrative describes IP-1..IP-N).\n\n**Output:** N phase/epic scope vBRIEFs in `./vbrief/proposed/`, one per implementation phase or epic, using the filename convention `YYYY-MM-DD-ip<NNN>-<slug>.vbrief.json` (NNN = 3-digit zero-padded, 001..N). See [vbrief/vbrief.md \u2014 speckit Phase 4 scope vBRIEFs](../vbrief/vbrief.md#speckit-phase-4-scope-vbriefs) for the canonical convention. (v0.20: proposed/ not pending/.)\n\nPhase 4 scopes are planning containers. They MAY keep broad acceptance in `plan.narratives.Acceptance` and MAY have `plan.items: []`. They are not valid concurrent swarm worker inputs unless explicitly marked as a single-story scope. Broad phase/epic scopes MUST pass through Phase 4.5 before swarm allocation.\n\n! After emitting the phase/epic scope vBRIEF(s) to `vbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) \u2014 name all three patterns (none / `--umbrella` / `--per-vbrief`).\n\n### Scope vBRIEF Shape\n\nFor each implementation phase IP-N, write a scope vBRIEF with:\n\n- ! `vBRIEFInfo.version` \u2014 current `scripts/_vbrief_build.py::EMITTED_VBRIEF_VERSION`\n- ! `plan.title` \u2014 phase title (e.g. \"IP-3: Implement data layer\")\n- ! `plan.status` \u2014 `pending` (or proposed per lifecycle)\n- ! `plan.narratives.Description` \u2014 short human summary of the phase\n- ! `plan.narratives.Acceptance` \u2014 acceptance criteria copied from the spec\n- ! `plan.narratives.Traces` \u2014 FR/NFR/IP IDs the phase covers (e.g. `FR-001, FR-003, NFR-002, IP-3`)\n- ! `plan.references` \u2014 link back to the parent proposed/ vBRIEF from Phase 3 (`type: x-vbrief/plan`, `TrustLevel: internal`)\n- ! `plan.metadata.kind` \u2014 `phase` or `epic`\n- ! `plan.metadata.dependencies` \u2014 array of IP IDs this phase depends on / is blocked by (plan-level; mirrors the `edges[].blocks` structure used in earlier drafts)\n\n```json\n{\n \"vBRIEFInfo\": { \"version\": \"<EMITTED_VBRIEF_VERSION>\" },\n \"plan\": {\n \"title\": \"IP-3: Implement data layer\",\n \"status\": \"pending\",\n \"narratives\": {\n \"Description\": \"Stand up the data layer described in the Phase 3 proposed/ vBRIEF Architecture.\",\n \"Acceptance\": \"Repository interfaces defined; CRUD round-trips pass integration tests.\",\n \"Traces\": \"FR-001, FR-003, NFR-002, IP-3\"\n },\n \"metadata\": {\n \"kind\": \"phase\",\n \"dependencies\": [\"ip-1\", \"ip-2\"]\n },\n \"references\": [\n { \"type\": \"x-vbrief/plan\", \"uri\": \"2026-05-26-ip002-plan.vbrief.json\", \"TrustLevel\": \"internal\" }\n ],\n \"items\": []\n }\n}\n```\n\n### plan.vbrief.json \u2014 Session Tracker Only\n\n- ! `plan.vbrief.json` reverts to its canonical session-todo role defined in [vbrief/vbrief.md \u2014 plan.vbrief.json](../vbrief/vbrief.md#planvbriefjson). It is the agent-private tactical plan for the current session, not the project-wide IP list.\n- ! While working on a specific scope vBRIEF, `plan.vbrief.json` MUST carry a `planRef` to that scope vBRIEF in `vbrief/proposed/` or `vbrief/active/`.\n- \u2297 Emit the project-wide Phase 4 task list to `plan.vbrief.json` \u2014 write per-IP scope vBRIEFs to `vbrief/proposed/` instead.\n\n### Migrating Legacy speckit Projects\n\n- ~ Projects that already emitted a speckit-shaped `plan.vbrief.json` (project-wide IP list) can convert to the new model with:\n ```\n python scripts/migrate_vbrief.py --speckit-plan vbrief/plan.vbrief.json\n ```\n The translator emits one scope vBRIEF per IP into `vbrief/proposed/` (3-digit padded filenames, bilingual `edges` reader so both `from/to` and legacy `source/target` translate correctly) and writes the remaining session-level scaffold back to `plan.vbrief.json`.\n\n### Guidelines\n\n- ! Derive one scope vBRIEF per implementation phase from `ImplementationPhases`\n- ! Populate `Description`, `Acceptance`, and `Traces` narratives per [vbrief/vbrief.md \u2014 canonical narrative keys](../vbrief/vbrief.md#scope-vbrief-narrative-keys)\n- ! Use `plan.metadata.dependencies` (plan-level) rather than item-level `blocks` edges for cross-scope dependencies\n- ! Use `plan.metadata.kind = \"phase\"` or `\"epic\"` for broad implementation scopes\n- ~ Size each phase for 1-4 hours of work so the swarm allocator can distribute cleanly\n- \u2297 Create phases not traceable to a spec requirement\n- \u2297 Allocate Phase 4 phase/epic scope vBRIEFs directly to concurrent swarm workers\n\n### Transition Criteria\n\n- ! Every implementation phase from `ImplementationPhases` has a matching scope vBRIEF in `./vbrief/proposed/`\n- ! Each scope vBRIEF has `Description`, `Acceptance`, and `Traces` narratives\n- ! Each scope vBRIEF carries a `references` entry linking back to the parent Phase 3 proposed/ vBRIEF with `TrustLevel: internal`\n- ! Cross-scope dependencies in `plan.metadata.dependencies` form a valid DAG (no cycles)\n\n---\n\n## Phase 4.5: Story Decomposition / Swarm Readiness\n\n**Goal:** Convert approved Phase 4 phase/epic scopes into child story vBRIEFs suitable for parallel agents.\n\n**Input:** Phase 4 phase/epic vBRIEFs in `./vbrief/pending/` or `./vbrief/active/`.\n\n**Output:** Story-level child vBRIEFs whose executable acceptance criteria live in `plan.items` and whose `plan.metadata.swarm` contract proves they are safe to allocate.\n\n! After emitting the story vBRIEF(s) to `vbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) \u2014 name all three patterns (none / `--umbrella` / `--per-vbrief`).\n\n### Process\n\n1. ! Inspect approved specification narratives and Phase 4 scope vBRIEFs.\n2. ! Identify `plan.metadata.kind = \"phase\"` or `\"epic\"` scopes that are too broad for direct implementation.\n3. ! Draft a deterministic decomposition proposal: stories, dependencies, expected file scope, verification commands, traces, and conflict groups.\n4. ! Store the temporary proposal artifact under `vbrief/.eval/decompositions/<parent-slug>.json`; derive `<parent-slug>` from the parent vBRIEF filename by removing `.vbrief.json` and any leading `YYYY-MM-DD-` date prefix.\n5. ! Ask for explicit user approval before writing child story vBRIEFs.\n6. ! Validate the approved draft with `task scope:decompose -- <parent.vbrief.json> --draft vbrief/.eval/decompositions/<parent-slug>.json --check`, then apply it without `--check`.\n7. ! Run `task swarm:readiness -- vbrief/active/*.vbrief.json` before concurrent allocation, or point it at the candidate child story files for a dry readiness review before activation.\n\n### Story vBRIEF Requirements\n\nEach Phase 4.5 child story vBRIEF MUST include:\n\n- ! `plan.metadata.kind = \"story\"`\n- ! non-empty `plan.items`\n- ! `plan.narratives.Description` with at least two concrete sentences\n- ! `plan.narratives.ImplementationPlan` with at least two concrete implementation steps\n- ! executable acceptance in each story's `plan.items`\n- ! `plan.narratives.UserStory` in the form `As a <role>, I want <capability>, so that <outcome>.`\n- ! 2-5 concrete, observable acceptance criteria unless explicitly justified\n- ! explicit dependencies in `plan.metadata.swarm.depends_on`\n- ! traceability back to requirements via `Traces` narratives or explicit trace justification\n- ! expected file scope in `plan.metadata.swarm.file_scope`\n- ! verify commands in `plan.metadata.swarm.verify_commands`\n- ! expected outputs/evidence in `plan.metadata.swarm.expected_outputs`\n- ! swarm readiness metadata in `plan.metadata.swarm`\n- ! `planRef` pointing to the parent phase/epic scope\n- ! parent phase/epic `references` updated to point to every child story\n\n### Decomposition Command\n\nUse the deterministic command surface:\n\n```bash\ntask scope:decompose -- vbrief/pending/2026-05-12-ip001-auth.vbrief.json --draft vbrief/.eval/decompositions/ip001-auth.json --check\ntask scope:decompose -- vbrief/pending/2026-05-12-ip001-auth.vbrief.json --draft vbrief/.eval/decompositions/ip001-auth.json\ntask scope:decompose -- --check\n```\n\nThe draft JSON is a temporary proposal artifact, not a vBRIEF. Agents SHOULD write draft proposals under `vbrief/.eval/decompositions/`, which is gitignored specifically for local decomposition scratch. Derive `<parent-slug>` from the parent vBRIEF filename by removing `.vbrief.json` and any leading `YYYY-MM-DD-` date prefix. Agents MUST NOT leave decomposition draft JSON files at the workspace root. The command validates and applies a proposed decomposition rather than freely inventing one. It creates generated child story vBRIEFs as lifecycle artifacts, defaulting to `vbrief/pending/`, preserves origin/provenance references, sets each child `planRef` to the parent scope, updates parent references to include children, validates the dependency DAG, rejects dependency cycles, and rejects ready stories missing user-story shape, concrete observable acceptance, narrow file scope, focused verify commands, or traces. Parent `plan.items` are input signals, not automatic child stories.\n\nParent phase/epic acceptance MAY remain in `plan.narratives.Acceptance` as context. Executable acceptance for swarm work MUST be redistributed into child story `plan.items`.\n\n### Swarm Readiness Command\n\nUse the readiness gate before swarm allocation:\n\n```bash\ntask swarm:readiness -- vbrief/active/*.vbrief.json\n```\n\nThe readiness report lists ready stories, blocked stories, decomposition-needed epics/phases, dependency waves, conflict groups, a file-overlap matrix, and missing fields. It exits non-zero when candidate work is not swarm-ready for concurrent allocation. `readiness=ready` means ready for concurrent allocation; sequential-safe or low-confidence work MUST use another state such as `sequential` or `needs_refinement` and will fail this gate until refined or scheduled outside concurrent swarm allocation.\n\n### Transition Criteria\n\n- ! Candidate swarm work consists only of `kind=story` vBRIEFs\n- ! Every candidate story has non-empty `plan.items`\n- ! Every candidate story has a product-shaped `UserStory`, 2-5 observable acceptance criteria unless justified, file scope, verify commands, traces or trace justification, and readiness metadata.\n- ! Dependencies resolve and form a DAG\n- ! No unsafe file-scope overlap exists among parallel stories\n- ! No `size=large` story is marked `parallel_safe=true`\n- ! No ready story uses broad file globs, only generic verification such as `task check`, `parallel_safe=false`, or `file_scope_confidence=low`\n\n---\n\n## Phase 5: Implement\n\n**Goal:** Execute scope vBRIEFs following test-first discipline.\n\n**Input:** Story-level scope vBRIEFs in `./vbrief/pending/` (promote to `./vbrief/active/` via `task scope:activate` when work begins). `./vbrief/plan.vbrief.json` holds the current session's tactical todo list and carries a `planRef` to the active scope. Concurrent swarm implementation requires Phase 4.5-ready stories.\n\n### Process\n\n- ! Write tests BEFORE implementation (Red)\n- ! Implement minimal code to pass tests (Green)\n- ! Refactor while keeping tests green (Refactor)\n- ! Update scope vBRIEF `plan.status` and folder via `task scope:*` commands as work progresses (`pending` \u2192 `running` \u2192 `completed`)\n- ! Update `./vbrief/plan.vbrief.json` session todos as tactical steps progress (session-scoped; do NOT put the project-wide IP list here)\n- ~ Work on story vBRIEFs whose `plan.metadata.swarm.depends_on` entries are already completed in parallel when possible\n\n### File Creation Order\n\n1. Create contract/API specifications\n2. Create test files (contract \u2192 integration \u2192 unit)\n3. Create source files to make tests pass\n4. Refactor and document\n\n### Guidelines\n\n- ! Follow the `Principles` narrative in `vbrief/PROJECT-DEFINITION.vbrief.json` throughout\n- ! Move scope vBRIEFs through lifecycle folders using `task scope:activate|complete|cancel|block|unblock`\n- \u2297 Implement without failing tests first\n- \u2297 Skip refactoring phase\n- \u2297 Write the project-wide IP list to `plan.vbrief.json` \u2014 use `vbrief/pending/` scope vBRIEFs as the durable task tracker\n- \u2297 Allocate broad `kind=epic` or `kind=phase` scopes to concurrent swarm workers before decomposition\n\n---\n\n## Artifacts Summary (pre-v0.20, for reference only during migration)\n\n| Phase | Artifact | Purpose |\n|-------|----------|---------|\n| 1. Principles | `vbrief/PROJECT-DEFINITION.vbrief.json` | Governing rules (Principles narrative) |\n| 2. Specify | date-prefixed in `vbrief/proposed/` | WHAT/WHY narratives (v0.20) |\n| 3. Plan | date-prefixed in `vbrief/proposed/` | HOW narratives (enriches Phase 2; v0.20) |\n| 3b. Render (derivative) | `SPECIFICATION.md` (via `task spec:render`, sentinel only) | Read-only human review export (optional) |\n| 3c. Render PRD (derivative) | `PRD.md` (via `task prd:render`, sentinel only) | Optional stakeholder-review export |\n| 4. Tasks | `./vbrief/proposed/YYYY-MM-DD-ip<NNN>-<slug>.vbrief.json` (one per IP/epic) | Phase/epic scope vBRIEFs (v0.20: proposed/) drive roadmap/project render + decomposition |\n| 4.5. Story decomposition | Child story vBRIEFs with `plan.metadata.swarm` in proposed/ | Swarm-ready executable units (v0.20) |\n| 4b. Session todos | `./vbrief/plan.vbrief.json` | Session-level tactical plan (carries `planRef` to active scope) |\n| 5. Implement | Code + tests | Working software, optionally via swarm |\n\n## Directory Structure (v0.20)\n\n```\nproject/\n\u251c\u2500\u2500 vbrief/\n\u2502 \u251c\u2500\u2500 PROJECT-DEFINITION.vbrief.json # Phase 1: Principles narrative\n\u2502 \u251c\u2500\u2500 proposed/ # Phase 2+: date-prefixed WHAT/WHY/HOW + IP scopes + stories\n\u2502 \u2502 \u2514\u2500\u2500 YYYY-MM-DD-*.vbrief.json\n\u2502 \u2502 \u2514\u2500\u2500 YYYY-MM-DD-ip001-....vbrief.json\n\u2502 \u251c\u2500\u2500 plan.vbrief.json # Phase 4b: session todos (planRef to active scope)\n\u2502 \u2514\u2500\u2500 pending/ active/ etc. # Lifecycle (seeded empty or with promoted)\n\u251c\u2500\u2500 SPECIFICATION.md # Optional derivative (task spec:render; sentinel only)\n\u251c\u2500\u2500 PRD.md # Optional derivative (task prd:render; sentinel only)\n\u2514\u2500\u2500 src/ # Phase 5\n```\n\n(See ## v0.20 Output Shape and `strategies/v0-20-contract.md` for the authoritative table row for speckit.)\n\n---\n\n## v0.20 Output Shape (s5-migrate-speckit-rapid-enterprise / #1166)\n\nThis strategy has been migrated to the full v0.20 output shape so speckit-generated projects are accepted by the build skill Pre-Cutover Detection Guard with zero errors on first attempt (resolves the speckit row from the #1166 inconsistency table and the s5 story acceptance criteria, including story-level vBRIEFs in proposed/ instead of only phase/epic in pending/).\n\n- ! Seed the five lifecycle folders under `vbrief/` if any are missing: `proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`.\n- ! Emit all scope items (principles context, spec phases/stories, implementation phases/epics) exclusively as date-prefixed scope vBRIEFs in `vbrief/proposed/YYYY-MM-DD-<kebab-slug>.vbrief.json` (or the ipNNN convention for phases per vbrief.md). For speckit, phases use `YYYY-MM-DD-ip<NNN>-<slug>.vbrief.json` in proposed/; stories from Phase 4.5 also in proposed/. Decompose plans into focused, buildable vBRIEFs (v0.6 schema) rather than a monolithic legacy spec.\n- ! After the proposed/ vBRIEFs are written (or at Phase 3/4 boundaries), invoke `task project:render` (or `task spec:render` post) from the repo root to generate/refresh the complete `vbrief/PROJECT-DEFINITION.vbrief.json` (items registry derived from the lifecycle folders).\n- \u2297 Never emit `vbrief/specification.vbrief.json` (or any legacy dual-write).\n- ~ `SPECIFICATION.md` / `PRD.md` at the project root, if produced at all, must be only read-only derivatives that include the v0.20 deprecated-redirect sentinel. The source of truth is the vbrief/ lifecycle (proposed/ phases + stories) + PROJECT-DEFINITION.\n- ! Before writing any proposed/ vBRIEFs or PROJECT-DEFINITION, follow the guards in [artifact-guards.md](./artifact-guards.md) (Preparatory Guard for scope items in proposed/; Spec-Generating Guard for PROJECT-DEFINITION).\n- ! Final output tree must pass the deterministic v0.20 strategy output validation gate (s2-deterministic-gate) and the build Pre-Cutover Detection Guard with zero warnings/errors. See full acceptance in the s5 vBRIEF (a1: date-prefixed stories in proposed/ + deterministic gate; a2: speckit story-level in proposed/ not only pending phases; a3: no legacy specification.vbrief.json) and the 1166 decomposition.\n- ! Cite the canonical contract `strategies/v0-20-contract.md` (s1-contract) for the exact shape and the per-strategy table row (speckit: Yes lifecycle; Yes PROJECT-DEFINITION Phase 1+; proposed/ (phases + stories date-prefixed); Never specification.vbrief.json; Omit (use task spec:render post) for SPEC/PRD).\n\n---\n\n## Artifacts Summary (v0.20)\n\n**Speckit (full 5-phase with Phase 4/4.5):**\n\n| Artifact | Purpose | Created By |\n|----------|---------|------------|\n| `vbrief/PROJECT-DEFINITION.vbrief.json` | Principles + full items registry | Speckit Phase 1 + `task project:render` |\n| `vbrief/proposed/YYYY-MM-DD-*.vbrief.json` + `YYYY-MM-DD-ipNNN-*.vbrief.json` | All spec (WHAT/WHY/HOW) + phases/epics/stories (date-prefixed; per v0.20 contract and vbrief.md speckit convention) | Speckit Phases 2-4.5 |\n| `vbrief/{proposed,pending,active,completed,cancelled}/` | All five lifecycle folders seeded | Speckit |\n| (optional derivative) `SPECIFICATION.md` / `PRD.md` | Human-readable (includes deprecated-redirect sentinel only) | `task spec:render` / `task prd:render` (post) |\n| `vbrief/plan.vbrief.json` | Session-level tactical plan (planRef to active) | Speckit (internal) |\n\n**Pre-v0.20 / legacy artifacts that MUST NOT be produced by this strategy:**\n\n- `vbrief/specification.vbrief.json`\n- Primary handoff `SPECIFICATION.md` or `PRD.md` at project root (without sentinel)\n- Phase/epic scopes in `pending/` (use `proposed/`)\n\nSee the full table and rules in `strategies/v0-20-contract.md` (speckit row reproduced above).\n\n---\n\n## Invoking This Strategy\n\nSet in PROJECT-DEFINITION.vbrief.json narratives:\n```json\n\"Strategy\": \"strategies/speckit.md\"\n```\n\nOr explicitly:\n```\nUse the speckit strategy for this project.\n```\n\nStart with:\n```\nI want to build [project] with features:\n1. [feature]\n2. [feature]\n```\n"
|
|
144
|
+
"body": "# SpecKit Strategy\n\nA spec-driven development workflow inspired by [GitHub's spec-kit](https://github.com/github/spec-kit), with a Phase 4.5 readiness layer for decomposing broad implementation scopes into swarm-safe stories. Fully migrated to v0.20 (phases + stories emitted as date-prefixed vBRIEFs in proposed/; no legacy specification.vbrief.json).\n\n**v0.20 note (s5-migrate-speckit-rapid-enterprise / #1166):** Speckit now emits only the canonical v0.20 shape (date-prefixed phase/epic + story vBRIEFs in proposed/, full PROJECT-DEFINITION.vbrief.json via task project:render post, seeded lifecycle folders, no legacy specification.vbrief.json). Phase 4/4.5 scopes go to proposed/ (not pending/). Review exports use `task project:export-spec` (gate: export succeeded). See the dedicated ## v0.20 Output Shape section, the Artifacts Summary updated to the contract table, and the canonical contract `strategies/v0-20-contract.md` (s1-contract of #1166).\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**⚠️ See also**: [strategies/interview.md](./interview.md) | [strategies/discuss.md](./discuss.md) | [core/glossary.md](../glossary.md) | [strategies/v0-20-contract.md](./v0-20-contract.md) | [artifact-guards.md](./artifact-guards.md) | [vbrief/vbrief.md](../vbrief/vbrief.md)\n\n## When to Use\n\n- ~ Large or complex projects with multiple contributors\n- ~ Projects requiring formal specification review\n- ~ When parallel agent development is planned\n- ~ Enterprise environments with compliance requirements\n- ? Skip Phase 1 if PROJECT-DEFINITION.vbrief.json Principles narrative already defined\n\n## Workflow Overview\n\n```mermaid\nflowchart LR\n subgraph speckit [\"SpecKit Strategy (v0.20)\"]\n P[\"📜 Principles<br/><i>PROJECT-DEFINITION.vbrief.json</i>\"]\n S[\"📝 Specify<br/><i>WHAT/WHY → proposed/YYYY-MM-DD-*.vbrief.json</i>\"]\n PL[\"🏗️ Plan<br/><i>HOW → proposed/YYYY-MM-DD-*.vbrief.json</i>\"]\n T[\"✅ Scope<br/><i>Phase/epic vBRIEFs in proposed/</i>\"]\n D[\"🧩 Decompose<br/><i>Story vBRIEFs in proposed/</i>\"]\n I[\"🔨 Implement<br/><i>Execute</i>\"]\n end\n\n P -->|\"Established\"| S\n S -->|\"Approved\"| PL\n PL -->|\"Reviewed\"| T\n T -->|\"Approved\"| D\n D -->|\"Ready stories\"| I\n\n style P fill:#c4b5fd,stroke:#7c3aed,color:#000\n style S fill:#fef08a,stroke:#ca8a04,color:#000\n style PL fill:#6ee7b7,stroke:#059669,color:#000\n style T fill:#7dd3fc,stroke:#0284c7,color:#000\n style D fill:#fde68a,stroke:#d97706,color:#000\n style I fill:#f0abfc,stroke:#a855f7,color:#000\n```\n\n(See ## v0.20 Output Shape for exact artifact rules, the mandatory `task project:render` post call and `task project:export-spec` for review exports, and citation of strategies/v0-20-contract.md.)\n\n---\n\n## Phase 1: Principles\n\n**Goal:** Establish immutable project principles before any specification.\n\n**Output:** `Principles` narrative in `vbrief/PROJECT-DEFINITION.vbrief.json` (v0.20: plus any early proposed/ context vBRIEFs if needed)\n\n! Before writing output artifacts, follow the guards in [artifact-guards.md](./artifact-guards.md) (Preparatory Guard for proposed/ items; Spec-Generating Guard for PROJECT-DEFINITION).\n\n### Process\n\n- ! Define 3-5 non-negotiable principles\n- ! Include at least one anti-principle (⊗)\n- ! Write principles as the `Principles` narrative in `vbrief/PROJECT-DEFINITION.vbrief.json`\n- ~ Interview stakeholders about architectural constraints\n- ⊗ Proceed without defined principles\n- ⊗ Create a standalone `project.md` -- principles belong in PROJECT-DEFINITION.vbrief.json\n\n### Transition Criteria\n\n- ! `Principles` narrative in `vbrief/PROJECT-DEFINITION.vbrief.json` is complete\n- ! All stakeholders have reviewed principles\n- ~ No `[NEEDS CLARIFICATION]` markers remain\n\n---\n\n## Phase 2: Specify (WHAT/WHY)\n\n**Goal:** Document WHAT to build and WHY, without implementation details.\n\n**Output:** WHAT/WHY narratives in date-prefixed vBRIEF(s) in `vbrief/proposed/YYYY-MM-DD-*.vbrief.json` (v0.20; no singular specification.vbrief.json)\n\n! Before writing output artifacts, follow the guards in [artifact-guards.md](./artifact-guards.md) (Preparatory Guard for proposed/ scope items; Spec-Generating Guard for PROJECT-DEFINITION).\n\nWrite the following narrative keys into the proposed/ vBRIEF `plan.narratives`\n\n- `ProblemStatement` -- what problem this solves\n- `Goals` -- desired outcomes\n- `UserStories` -- user scenarios with priorities (P1, P2, P3) and acceptance scenarios (Given/When/Then)\n- `Requirements` -- numbered functional (FR-001) and non-functional (NFR-001) requirements\n- `SuccessMetrics` -- measurable success criteria (SC-001)\n- `EdgeCases` -- boundary conditions and error handling\n\n### Guidelines\n\n- ! Focus on WHAT users need and WHY\n- ! Use `[NEEDS CLARIFICATION: question]` for any ambiguity\n- ! Number all requirements (FR-001, NFR-001) for traceability\n- ! Prioritize user stories (P1, P2, P3)\n- ⊗ Include HOW to implement (no tech stack, APIs, code)\n- ⊗ Guess when uncertain -- mark it instead\n- ⊗ Create `specs/` directories or standalone `spec.md` files -- all content goes in the proposed/ date-prefixed vBRIEF(s)\n\n### Transition Criteria\n\n- ! No `[NEEDS CLARIFICATION]` markers remain in narratives\n- ! All user stories have acceptance scenarios\n- ! Requirements are testable and unambiguous\n- ! Stakeholders have approved specification narratives\n\n---\n\n## Phase 3: Plan (HOW)\n\n**Goal:** Document HOW to build it with technical decisions.\n\n**Input:** Approved WHAT/WHY narratives in the proposed/ date-prefixed vBRIEF(s) from Phase 2\n\n**Output:** HOW narratives enriching the proposed/ vBRIEF(s) (v0.20; no singular specification.vbrief.json)\n\nAdd the following narrative keys to the proposed/ vBRIEF `plan.narratives`:\n\n- `Architecture` -- high-level system design (components, data model, API contracts)\n- `TechDecisions` -- technology choices with rationale\n- `ImplementationPhases` -- phased delivery plan with dependencies\n- `PreImplementationGates` -- simplicity gate, test-first gate\n\n### Guidelines\n\n- ! Reference spec requirements (FR-001, etc.) from Phase 2 narratives\n- ! Document rationale for every technology choice\n- ! Pass all pre-implementation gates before proceeding\n- ⊗ Write implementation code\n- ⊗ Create `specs/` directories or standalone `plan.md` files -- all content goes in the proposed/ date-prefixed vBRIEF(s)\n\n### Post-Phase 3 Transition Gate: Export for Review\n\n! Phase 3 -> Phase 4 is gated on a successful spec export for human review, mirroring the Phase 2 approval gate. Complete the steps below **in order** before advancing. [skills/deft-directive-setup/SKILL.md](../skills/deft-directive-setup/SKILL.md) is required to invoke `task project:export-spec` at this boundary when running speckit interactively; the gate fails silently otherwise (yolo-mode agents used to skip it -- that is what this gate exists to prevent).\n\n1. ! Run `task project:export-spec` (use `--audience=internal` when proposed scopes must appear in the `## Scope outlook` section). Legacy migrated trees MAY use `task spec:render` when `vbrief/specification.vbrief.json` exists.\n2. ! Confirm export **succeeded** (command exit 0) and `SPECIFICATION.md` exists at the project root with the greenfield banner (`<!-- Source of truth: vbrief/PROJECT-DEFINITION.vbrief.json -->`) or full-spec banner as appropriate.\n3. ! The proposed/ vBRIEFs + PROJECT-DEFINITION are the source of truth. `SPECIFICATION.md` is a read-only export.\n4. ! Human reviewer approves (or requests changes). On approval, proceed to Phase 4.\n\n### Transition Criteria\n\n- ! All gates pass (or exceptions documented)\n- ! Every spec requirement maps to a plan element\n- ! Architecture reviewed and approved\n- ! **Phase 3 -> Phase 4 transition criterion:** `task project:export-spec` succeeded (exit 0) AND the proposed/ date-prefixed vBRIEF(s) + PROJECT-DEFINITION represent the approved spec (agents MUST NOT advance to Phase 4 without review of the v0.20 artifacts).\n\n---\n\n## Phase 4: Implementation Phase / Epic Scope Emission (v0.20)\n\n**Goal:** Emit one broad scope vBRIEF per implementation phase or epic (plus stories via 4.5) so downstream tooling (`task roadmap:render`, `task project:render`, and Phase 4.5 decomposition) can operate against the lifecycle model described in [vbrief/vbrief.md](../vbrief/vbrief.md). All emitted to `proposed/` per v0.20 contract.\n\n**Input:** Approved HOW narratives in the proposed/ date-prefixed vBRIEF(s) from Phase 3 (`ImplementationPhases` narrative describes IP-1..IP-N).\n\n**Output:** N phase/epic scope vBRIEFs in `./vbrief/proposed/`, one per implementation phase or epic, using the filename convention `YYYY-MM-DD-ip<NNN>-<slug>.vbrief.json` (NNN = 3-digit zero-padded, 001..N). See [vbrief/vbrief.md — speckit Phase 4 scope vBRIEFs](../vbrief/vbrief.md#speckit-phase-4-scope-vbriefs) for the canonical convention. (v0.20: proposed/ not pending/.)\n\nPhase 4 scopes are planning containers. They MAY keep broad acceptance in `plan.narratives.Acceptance` and MAY have `plan.items: []`. They are not valid concurrent swarm worker inputs unless explicitly marked as a single-story scope. Broad phase/epic scopes MUST pass through Phase 4.5 before swarm allocation.\n\n! After emitting the phase/epic scope vBRIEF(s) to `vbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).\n\n### Scope vBRIEF Shape\n\nFor each implementation phase IP-N, write a scope vBRIEF with:\n\n- ! `vBRIEFInfo.version` — current `scripts/_vbrief_build.py::EMITTED_VBRIEF_VERSION`\n- ! `plan.title` — phase title (e.g. \"IP-3: Implement data layer\")\n- ! `plan.status` — `pending` (or proposed per lifecycle)\n- ! `plan.narratives.Description` — short human summary of the phase\n- ! `plan.narratives.Acceptance` — acceptance criteria copied from the spec\n- ! `plan.narratives.Traces` — FR/NFR/IP IDs the phase covers (e.g. `FR-001, FR-003, NFR-002, IP-3`)\n- ! `plan.references` — link back to the parent proposed/ vBRIEF from Phase 3 (`type: x-vbrief/plan`, `TrustLevel: internal`)\n- ! `plan.metadata.kind` — `phase` or `epic`\n- ! `plan.metadata.dependencies` — array of IP IDs this phase depends on / is blocked by (plan-level; mirrors the `edges[].blocks` structure used in earlier drafts)\n\n```json\n{\n \"vBRIEFInfo\": { \"version\": \"<EMITTED_VBRIEF_VERSION>\" },\n \"plan\": {\n \"title\": \"IP-3: Implement data layer\",\n \"status\": \"pending\",\n \"narratives\": {\n \"Description\": \"Stand up the data layer described in the Phase 3 proposed/ vBRIEF Architecture.\",\n \"Acceptance\": \"Repository interfaces defined; CRUD round-trips pass integration tests.\",\n \"Traces\": \"FR-001, FR-003, NFR-002, IP-3\"\n },\n \"metadata\": {\n \"kind\": \"phase\",\n \"dependencies\": [\"ip-1\", \"ip-2\"]\n },\n \"references\": [\n { \"type\": \"x-vbrief/plan\", \"uri\": \"2026-05-26-ip002-plan.vbrief.json\", \"TrustLevel\": \"internal\" }\n ],\n \"items\": []\n }\n}\n```\n\n### plan.vbrief.json — Session Tracker Only\n\n- ! `plan.vbrief.json` reverts to its canonical session-todo role defined in [vbrief/vbrief.md — plan.vbrief.json](../vbrief/vbrief.md#planvbriefjson). It is the agent-private tactical plan for the current session, not the project-wide IP list.\n- ! While working on a specific scope vBRIEF, `plan.vbrief.json` MUST carry a `planRef` to that scope vBRIEF in `vbrief/proposed/` or `vbrief/active/`.\n- ⊗ Emit the project-wide Phase 4 task list to `plan.vbrief.json` — write per-IP scope vBRIEFs to `vbrief/proposed/` instead.\n\n### Migrating Legacy speckit Projects\n\n- ~ Projects that already emitted a speckit-shaped `plan.vbrief.json` (project-wide IP list) can convert to the new model with:\n ```\n python scripts/migrate_vbrief.py --speckit-plan vbrief/plan.vbrief.json\n ```\n The translator emits one scope vBRIEF per IP into `vbrief/proposed/` (3-digit padded filenames, bilingual `edges` reader so both `from/to` and legacy `source/target` translate correctly) and writes the remaining session-level scaffold back to `plan.vbrief.json`.\n\n### Guidelines\n\n- ! Derive one scope vBRIEF per implementation phase from `ImplementationPhases`\n- ! Populate `Description`, `Acceptance`, and `Traces` narratives per [vbrief/vbrief.md — canonical narrative keys](../vbrief/vbrief.md#scope-vbrief-narrative-keys)\n- ! Use `plan.metadata.dependencies` (plan-level) rather than item-level `blocks` edges for cross-scope dependencies\n- ! Use `plan.metadata.kind = \"phase\"` or `\"epic\"` for broad implementation scopes\n- ~ Size each phase for 1-4 hours of work so the swarm allocator can distribute cleanly\n- ⊗ Create phases not traceable to a spec requirement\n- ⊗ Allocate Phase 4 phase/epic scope vBRIEFs directly to concurrent swarm workers\n\n### Transition Criteria\n\n- ! Every implementation phase from `ImplementationPhases` has a matching scope vBRIEF in `./vbrief/proposed/`\n- ! Each scope vBRIEF has `Description`, `Acceptance`, and `Traces` narratives\n- ! Each scope vBRIEF carries a `references` entry linking back to the parent Phase 3 proposed/ vBRIEF with `TrustLevel: internal`\n- ! Cross-scope dependencies in `plan.metadata.dependencies` form a valid DAG (no cycles)\n\n---\n\n## Phase 4.5: Story Decomposition / Swarm Readiness\n\n**Goal:** Convert approved Phase 4 phase/epic scopes into child story vBRIEFs suitable for parallel agents.\n\n**Input:** Phase 4 phase/epic vBRIEFs in `./vbrief/pending/` or `./vbrief/active/`.\n\n**Output:** Story-level child vBRIEFs whose executable acceptance criteria live in `plan.items` and whose `plan.metadata.swarm` contract proves they are safe to allocate.\n\n! After emitting the story vBRIEF(s) to `vbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).\n\n### Process\n\n1. ! Inspect approved specification narratives and Phase 4 scope vBRIEFs.\n2. ! Identify `plan.metadata.kind = \"phase\"` or `\"epic\"` scopes that are too broad for direct implementation.\n3. ! Draft a deterministic decomposition proposal: stories, dependencies, expected file scope, verification commands, traces, and conflict groups.\n4. ! Store the temporary proposal artifact under `vbrief/.eval/decompositions/<parent-slug>.json`; derive `<parent-slug>` from the parent vBRIEF filename by removing `.vbrief.json` and any leading `YYYY-MM-DD-` date prefix.\n5. ! Ask for explicit user approval before writing child story vBRIEFs.\n6. ! Validate the approved draft with `task scope:decompose -- <parent.vbrief.json> --draft vbrief/.eval/decompositions/<parent-slug>.json --check`, then apply it without `--check`.\n7. ! Run `task swarm:readiness -- vbrief/active/*.vbrief.json` before concurrent allocation, or point it at the candidate child story files for a dry readiness review before activation.\n\n### Story vBRIEF Requirements\n\nEach Phase 4.5 child story vBRIEF MUST include:\n\n- ! `plan.metadata.kind = \"story\"`\n- ! non-empty `plan.items`\n- ! `plan.narratives.Description` with at least two concrete sentences\n- ! `plan.narratives.ImplementationPlan` with at least two concrete implementation steps\n- ! executable acceptance in each story's `plan.items`\n- ! `plan.narratives.UserStory` in the form `As a <role>, I want <capability>, so that <outcome>.`\n- ! 2-5 concrete, observable acceptance criteria unless explicitly justified\n- ! explicit dependencies in `plan.metadata.swarm.depends_on`\n- ! traceability back to requirements via `Traces` narratives or explicit trace justification\n- ! expected file scope in `plan.metadata.swarm.file_scope`\n- ! verify commands in `plan.metadata.swarm.verify_commands`\n- ! expected outputs/evidence in `plan.metadata.swarm.expected_outputs`\n- ! swarm readiness metadata in `plan.metadata.swarm`\n- ! `planRef` pointing to the parent phase/epic scope\n- ! parent phase/epic `references` updated to point to every child story\n\n### Decomposition Command\n\nUse the deterministic command surface:\n\n```bash\ntask scope:decompose -- vbrief/pending/2026-05-12-ip001-auth.vbrief.json --draft vbrief/.eval/decompositions/ip001-auth.json --check\ntask scope:decompose -- vbrief/pending/2026-05-12-ip001-auth.vbrief.json --draft vbrief/.eval/decompositions/ip001-auth.json\ntask scope:decompose -- --check\n```\n\nThe draft JSON is a temporary proposal artifact, not a vBRIEF. Agents SHOULD write draft proposals under `vbrief/.eval/decompositions/`, which is gitignored specifically for local decomposition scratch. Derive `<parent-slug>` from the parent vBRIEF filename by removing `.vbrief.json` and any leading `YYYY-MM-DD-` date prefix. Agents MUST NOT leave decomposition draft JSON files at the workspace root. The command validates and applies a proposed decomposition rather than freely inventing one. It creates generated child story vBRIEFs as lifecycle artifacts, defaulting to `vbrief/pending/`, preserves origin/provenance references, sets each child `planRef` to the parent scope, updates parent references to include children, validates the dependency DAG, rejects dependency cycles, and rejects ready stories missing user-story shape, concrete observable acceptance, narrow file scope, focused verify commands, or traces. Parent `plan.items` are input signals, not automatic child stories.\n\nParent phase/epic acceptance MAY remain in `plan.narratives.Acceptance` as context. Executable acceptance for swarm work MUST be redistributed into child story `plan.items`.\n\n### Swarm Readiness Command\n\nUse the readiness gate before swarm allocation:\n\n```bash\ntask swarm:readiness -- vbrief/active/*.vbrief.json\n```\n\nThe readiness report lists ready stories, blocked stories, decomposition-needed epics/phases, dependency waves, conflict groups, a file-overlap matrix, and missing fields. It exits non-zero when candidate work is not swarm-ready for concurrent allocation. `readiness=ready` means ready for concurrent allocation; sequential-safe or low-confidence work MUST use another state such as `sequential` or `needs_refinement` and will fail this gate until refined or scheduled outside concurrent swarm allocation.\n\n### Transition Criteria\n\n- ! Candidate swarm work consists only of `kind=story` vBRIEFs\n- ! Every candidate story has non-empty `plan.items`\n- ! Every candidate story has a product-shaped `UserStory`, 2-5 observable acceptance criteria unless justified, file scope, verify commands, traces or trace justification, and readiness metadata.\n- ! Dependencies resolve and form a DAG\n- ! No unsafe file-scope overlap exists among parallel stories\n- ! No `size=large` story is marked `parallel_safe=true`\n- ! No ready story uses broad file globs, only generic verification such as `task check`, `parallel_safe=false`, or `file_scope_confidence=low`\n\n---\n\n## Phase 5: Implement\n\n**Goal:** Execute scope vBRIEFs following test-first discipline.\n\n**Input:** Story-level scope vBRIEFs in `./vbrief/pending/` (promote to `./vbrief/active/` via `task scope:activate` when work begins). `./vbrief/plan.vbrief.json` holds the current session's tactical todo list and carries a `planRef` to the active scope. Concurrent swarm implementation requires Phase 4.5-ready stories.\n\n### Process\n\n- ! Write tests BEFORE implementation (Red)\n- ! Implement minimal code to pass tests (Green)\n- ! Refactor while keeping tests green (Refactor)\n- ! Update scope vBRIEF `plan.status` and folder via `task scope:*` commands as work progresses (`pending` → `running` → `completed`)\n- ! Update `./vbrief/plan.vbrief.json` session todos as tactical steps progress (session-scoped; do NOT put the project-wide IP list here)\n- ~ Work on story vBRIEFs whose `plan.metadata.swarm.depends_on` entries are already completed in parallel when possible\n\n### File Creation Order\n\n1. Create contract/API specifications\n2. Create test files (contract → integration → unit)\n3. Create source files to make tests pass\n4. Refactor and document\n\n### Guidelines\n\n- ! Follow the `Principles` narrative in `vbrief/PROJECT-DEFINITION.vbrief.json` throughout\n- ! Move scope vBRIEFs through lifecycle folders using `task scope:activate|complete|cancel|block|unblock`\n- ⊗ Implement without failing tests first\n- ⊗ Skip refactoring phase\n- ⊗ Write the project-wide IP list to `plan.vbrief.json` — use `vbrief/pending/` scope vBRIEFs as the durable task tracker\n- ⊗ Allocate broad `kind=epic` or `kind=phase` scopes to concurrent swarm workers before decomposition\n\n---\n\n## Artifacts Summary (pre-v0.20, for reference only during migration)\n\n| Phase | Artifact | Purpose |\n|-------|----------|---------|\n| 1. Principles | `vbrief/PROJECT-DEFINITION.vbrief.json` | Governing rules (Principles narrative) |\n| 2. Specify | date-prefixed in `vbrief/proposed/` | WHAT/WHY narratives (v0.20) |\n| 3. Plan | date-prefixed in `vbrief/proposed/` | HOW narratives (enriches Phase 2; v0.20) |\n| 3b. Export (review) | `SPECIFICATION.md` (via `task project:export-spec`) | Read-only human review export (optional; gate requires export succeeded for Phase 3→4) |\n| 3c. Render PRD (derivative) | `PRD.md` (via `task prd:render`, sentinel only) | Optional stakeholder-review export |\n| 4. Tasks | `./vbrief/proposed/YYYY-MM-DD-ip<NNN>-<slug>.vbrief.json` (one per IP/epic) | Phase/epic scope vBRIEFs (v0.20: proposed/) drive roadmap/project render + decomposition |\n| 4.5. Story decomposition | Child story vBRIEFs with `plan.metadata.swarm` in proposed/ | Swarm-ready executable units (v0.20) |\n| 4b. Session todos | `./vbrief/plan.vbrief.json` | Session-level tactical plan (carries `planRef` to active scope) |\n| 5. Implement | Code + tests | Working software, optionally via swarm |\n\n## Directory Structure (v0.20)\n\n```\nproject/\n├── vbrief/\n│ ├── PROJECT-DEFINITION.vbrief.json # Phase 1: Principles narrative\n│ ├── proposed/ # Phase 2+: date-prefixed WHAT/WHY/HOW + IP scopes + stories\n│ │ └── YYYY-MM-DD-*.vbrief.json\n│ │ └── YYYY-MM-DD-ip001-....vbrief.json\n│ ├── plan.vbrief.json # Phase 4b: session todos (planRef to active scope)\n│ └── pending/ active/ etc. # Lifecycle (seeded empty or with promoted)\n├── SPECIFICATION.md # Optional export (task project:export-spec)\n├── PRD.md # Optional derivative (task prd:render; sentinel only)\n└── src/ # Phase 5\n```\n\n(See ## v0.20 Output Shape and `strategies/v0-20-contract.md` for the authoritative table row for speckit.)\n\n---\n\n## v0.20 Output Shape (s5-migrate-speckit-rapid-enterprise / #1166)\n\nThis strategy has been migrated to the full v0.20 output shape so speckit-generated projects are accepted by the build skill Pre-Cutover Detection Guard with zero errors on first attempt (resolves the speckit row from the #1166 inconsistency table and the s5 story acceptance criteria, including story-level vBRIEFs in proposed/ instead of only phase/epic in pending/).\n\n- ! Seed the five lifecycle folders under `vbrief/` if any are missing: `proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`.\n- ! Emit all scope items (principles context, spec phases/stories, implementation phases/epics) exclusively as date-prefixed scope vBRIEFs in `vbrief/proposed/YYYY-MM-DD-<kebab-slug>.vbrief.json` (or the ipNNN convention for phases per vbrief.md). For speckit, phases use `YYYY-MM-DD-ip<NNN>-<slug>.vbrief.json` in proposed/; stories from Phase 4.5 also in proposed/. Decompose plans into focused, buildable vBRIEFs (v0.6 schema) rather than a monolithic legacy spec.\n- ! After the proposed/ vBRIEFs are written (or at Phase 3/4 boundaries), invoke `task project:render` from the repo root to generate/refresh the complete `vbrief/PROJECT-DEFINITION.vbrief.json` (items registry derived from the lifecycle folders). For human review at Phase 3→4, invoke `task project:export-spec` (or `--audience=internal` when proposed scopes must appear in `## Scope outlook`).\n- ⊗ Never emit `vbrief/specification.vbrief.json` (or any legacy dual-write).\n- ~ `SPECIFICATION.md` / `PRD.md` at the project root, if produced at all, are read-only exports from `task project:export-spec` / `task prd:render`. The source of truth is the vbrief/ lifecycle (proposed/ phases + stories) + PROJECT-DEFINITION. Legacy `task spec:render` applies only to migrated trees with `vbrief/specification.vbrief.json`.\n- ! Before writing any proposed/ vBRIEFs or PROJECT-DEFINITION, follow the guards in [artifact-guards.md](./artifact-guards.md) (Preparatory Guard for scope items in proposed/; Spec-Generating Guard for PROJECT-DEFINITION).\n- ! Final output tree must pass the deterministic v0.20 strategy output validation gate (s2-deterministic-gate) and the build Pre-Cutover Detection Guard with zero warnings/errors. See full acceptance in the s5 vBRIEF (a1: date-prefixed stories in proposed/ + deterministic gate; a2: speckit story-level in proposed/ not only pending phases; a3: no legacy specification.vbrief.json) and the 1166 decomposition.\n- ! Cite the canonical contract `strategies/v0-20-contract.md` (s1-contract) for the exact shape and the per-strategy table row (speckit: Yes lifecycle; Yes PROJECT-DEFINITION Phase 1+; proposed/ (phases + stories date-prefixed); Never specification.vbrief.json; `task project:export-spec` for SPEC export).\n\n---\n\n## Artifacts Summary (v0.20)\n\n**Speckit (full 5-phase with Phase 4/4.5):**\n\n| Artifact | Purpose | Created By |\n|----------|---------|------------|\n| `vbrief/PROJECT-DEFINITION.vbrief.json` | Principles + full items registry | Speckit Phase 1 + `task project:render` |\n| `vbrief/proposed/YYYY-MM-DD-*.vbrief.json` + `YYYY-MM-DD-ipNNN-*.vbrief.json` | All spec (WHAT/WHY/HOW) + phases/epics/stories (date-prefixed; per v0.20 contract and vbrief.md speckit convention) | Speckit Phases 2-4.5 |\n| `vbrief/{proposed,pending,active,completed,cancelled}/` | All five lifecycle folders seeded | Speckit |\n| (optional export) `SPECIFICATION.md` / `PRD.md` | Human-readable spec export | `task project:export-spec` / `task prd:render` |\n| `vbrief/plan.vbrief.json` | Session-level tactical plan (planRef to active) | Speckit (internal) |\n\n**Pre-v0.20 / legacy artifacts that MUST NOT be produced by this strategy:**\n\n- `vbrief/specification.vbrief.json`\n- Primary handoff `SPECIFICATION.md` or `PRD.md` at project root (without sentinel)\n- Phase/epic scopes in `pending/` (use `proposed/`)\n\nSee the full table and rules in `strategies/v0-20-contract.md` (speckit row reproduced above).\n\n---\n\n## Invoking This Strategy\n\nSet in PROJECT-DEFINITION.vbrief.json narratives:\n```json\n\"Strategy\": \"strategies/speckit.md\"\n```\n\nOr explicitly:\n```\nUse the speckit strategy for this project.\n```\n\nStart with:\n```\nI want to build [project] with features:\n1. [feature]\n2. [feature]\n```\n"
|
|
145
145
|
},
|
|
146
146
|
{
|
|
147
147
|
"id": "v0-20-contract",
|
|
@@ -151,7 +151,7 @@
|
|
|
151
151
|
"v0-20-contract"
|
|
152
152
|
],
|
|
153
153
|
"path": "strategies/v0-20-contract.md",
|
|
154
|
-
"body": "# v0.20 Strategy Output Contract\n\nCanonical contract for the artifacts that every spec-generating strategy MUST produce to be v0.20-conformant.\n\n**Legend (from RFC2119):** !=MUST, ~=SHOULD, \u2249=SHOULD NOT, \u2297=MUST NOT, ?=MAY.\n\n**\u26a0\ufe0f See also**: [vbrief/vbrief.md](../vbrief/vbrief.md) | [strategies/README.md](./README.md) | [strategies/artifact-guards.md](./artifact-guards.md) | [skills/deft-directive-build/SKILL.md](../skills/deft-directive-build/SKILL.md) (Pre-Cutover Detection Guard) | [scripts/migrate_vbrief.py](../../scripts/migrate_vbrief.py) | [conventions/machine-generated-banner.md](../conventions/machine-generated-banner.md)\n\n---\n\n## Purpose\n\nSpec-generating strategies (interview, yolo, speckit, rapid, enterprise) historically produced inconsistent artifacts:\n\n- Some wrote only the legacy `vbrief/specification.vbrief.json` + root `SPECIFICATION.md`\n- Some wrote scope vBRIEFs without date prefixes and still dual-wrote the old singular spec file\n- None consistently seeded the full v0.20 lifecycle folders + `PROJECT-DEFINITION.vbrief.json` + date-prefixed proposed/ items\n\nThis caused immediate build failures via the Pre-Cutover Detection Guard for any project generated through those strategies.\n\nThis contract is the single source of truth. All future strategy implementations and migrations target exactly these artifacts. The build skill, vbrief validators, and (post-s2) deterministic shape gate enforce it.\n\n## When to Use\n\nUse this contract when authoring, reviewing, or migrating a spec-generating strategy that creates project definition artifacts, scope vBRIEFs, rendered views, or migration handoff material. It also applies when a guard, validator, or setup path needs to decide whether a project is current v0.20 output or legacy pre-cutover content.\n\n## Workflow\n\n1. Identify whether the strategy is spec-generating or preparatory.\n2. Apply the matching row in the per-strategy summary table.\n3. Create the required lifecycle folders before writing scope artifacts.\n4. Write authoritative vBRIEF content to `vbrief/PROJECT-DEFINITION.vbrief.json` and date-prefixed `vbrief/proposed/*.vbrief.json` files.\n5. Omit root `SPECIFICATION.md` / `PROJECT.md`, or write only deprecation redirect stubs when transitional UX requires them.\n6. Run the validator and content gates before treating the strategy output as v0.20-conformant.\n\n## Canonical v0.20 Output Shape\n\nFor a project that has completed any spec-generating strategy (or the full speckit flow), the following MUST exist and be the only authoritative sources:\n\n### Required Directory Structure\n- `vbrief/proposed/`\n- `vbrief/pending/`\n- `vbrief/active/`\n- `vbrief/completed/`\n- `vbrief/cancelled/`\n\nAll five lifecycle folders MUST be present (even if empty). This is the cutover signal used by pre-cutover guards.\n\n### Required Root-Level vBRIEF Artifact\n- `vbrief/PROJECT-DEFINITION.vbrief.json` (complete: narratives + items registry populated from the strategy session)\n\n`task project:render` MAY be invoked by the strategy or left to the user; the end state after strategy + any render MUST have a non-skeleton PROJECT-DEFINITION.\n\n### Scope vBRIEF Placement & Naming (Strict)\n- All new scope vBRIEFs (user stories, phases, epics from speckit Phase 4/4.5, etc.) MUST be written **only** to `vbrief/proposed/YYYY-MM-DD-<kebab-slug>.vbrief.json`\n- Filenames MUST be date-prefixed using the creation date (immutable per vbrief.md conventions)\n- Bare names (e.g. `scaffold.vbrief.json`) or names without date prefix are FORBIDDEN in v0.20\n- The old singular `vbrief/specification.vbrief.json` MUST NOT be written or updated by v0.20 strategies (it is a legacy container; new work uses the lifecycle folders + PROJECT-DEFINITION)\n\n### SPECIFICATION.md & PROJECT.md (Derivative / Deprecated)\n- Strategies SHOULD OMIT writing `SPECIFICATION.md` and `PROJECT.md` entirely. These are **rendered views** only.\n- If a strategy does emit them (for UX continuity during transition), they MUST be written **exclusively** as deprecation-redirect stubs:\n - Start with the canonical 4-line machine-generated banner (see conventions/machine-generated-banner.md)\n - Fifth line: `<!-- deft:deprecated-redirect -->`\n - Short explanatory body pointing to `vbrief/PROJECT-DEFINITION.vbrief.json` and the lifecycle folders\n - Never contain real spec or project content\n- Real content in these files (without the sentinel) triggers the build/setup/sync pre-cutover guards and forces migration.\n\n### Legacy `specification.vbrief.json`\n- \u2297 No v0.20 strategy may create or dual-write `vbrief/specification.vbrief.json` alongside the new model artifacts.\n- Existing legacy files are handled only by `task migrate:vbrief` (which ingests them into scope vBRIEFs + PROJECT-DEFINITION and leaves a redirect stub at root if needed).\n\n### plan.vbrief.json and continue.vbrief.json\n- Session/tactical state files are permitted at vbrief/ root (they carry `planRef` links). They are not part of the \"spec output\" contract but strategies that maintain chaining state (e.g. interview) update them per their own rules.\n\n## Per-Strategy Summary Table (Target State After Migration)\n\n| Strategy | Type | Must Create Lifecycle Folders | Must Write PROJECT-DEFINITION | Scope vBRIEFs Location | specification.vbrief.json | SPECIFICATION.md / PROJECT.md |\n|--------------|------------------|-------------------------------|-------------------------------|-----------------------------------------|-----------------------------|----------------------------------------|\n| interview | spec-generating | Yes | Yes (narratives + items) | proposed/YYYY-MM-DD-*.vbrief.json only | Never (post-migration) | Omit or deprecation redirect only |\n| yolo | spec-generating | Yes | Yes | proposed/YYYY-MM-DD-*.vbrief.json only | Never | Omit or deprecation redirect only |\n| speckit | spec-generating | Yes | Yes (Phase 1+) | proposed/YYYY-MM-DD-*.vbrief.json only (phases + stories) | Never | Omit (use task spec:render post) |\n| rapid | spec-generating | Yes | Yes | proposed/YYYY-MM-DD-*.vbrief.json only | Never | Omit or deprecation redirect only |\n| enterprise | spec-generating | Yes | Yes | proposed/YYYY-MM-DD-*.vbrief.json only | Never | Omit or deprecation redirect only |\n| preparatory (research, discuss, map, etc.) | preparatory | Yes (if first touch) | No (unless also spec path) | proposed/YYYY-MM-DD-*.vbrief.json (context/decision vBRIEFs) | N/A | N/A (preparatory only) |\n\n## Agent & Strategy Author Rules\n\n- ! Every spec-generating strategy document MUST contain an \"Artifacts\" or \"Output\" section that explicitly cites this contract (`strategies/v0-20-contract.md`) and reproduces the relevant row from the table above.\n- ! Before emitting any vBRIEF artifact, follow the guards in `artifact-guards.md` (updated to reference this contract).\n- ! Date prefixes on scope vBRIEFs are mandatory for swarm readiness, filename sorting, and dedup.\n- \u2297 Write real content to root SPECIFICATION.md or PROJECT.md from a strategy.\n- \u2297 Emit bare-named vBRIEFs in proposed/ or anywhere outside the dated convention.\n- \u2297 Dual-write the old `specification.vbrief.json` in a v0.20 flow.\n\n## Verification & Enforcement\n\n- Build / setup / sync skills: Pre-Cutover Detection Guard (any missing lifecycle folder or real-content legacy md triggers redirect to migrate).\n- `task vbrief:validate` + `task check`: filename convention, folder/status consistency, PROJECT-DEFINITION presence.\n- Post-s2: deterministic validation gate (s2 story) will parse strategy output trees against this contract and fail non-conformant generations.\n- Content tests + migration stories exercise the before/after shapes.\n\n## Migration Path for Existing Strategies\n\nThe s3/s4/s5 stories migrate the individual strategy files (and their emitted examples) to the shape defined here. This contract document is the target spec they implement against; do not change strategies first.\n\n## When to Use\n\nUse this contract when:\n- Authoring a new spec-generating strategy (interview, yolo, speckit, rapid, enterprise, etc.).\n- Migrating an existing strategy to v0.20 (the s3/s4/s5 work).\n- Implementing or updating the deterministic validation gate (s2) or build pre-cutover guards.\n- Writing migration tooling (`migrate_vbrief.py`, reconcile scripts, etc.).\n- Auditing a generated project for v0.20 conformance.\n\n## Workflow\n\n1. Read the Canonical v0.20 Output Shape section.\n2. Ensure your strategy (or migration) writes exactly the required folders + `PROJECT-DEFINITION.vbrief.json` + dated proposed/ vBRIEFs.\n3. Never write the legacy `specification.vbrief.json` or real-content `SPECIFICATION.md`/`PROJECT.md`.\n4. Cite this contract explicitly in your strategy's \"Artifacts\" / \"Output\" section (see the Per-Strategy Summary Table).\n5. Run `task check` (or the deterministic gate once s2 lands) to validate.\n\n---\n\n**Owned by**: `vbrief/active/2026-05-26-define-canonical-v020-strategy-output-contract.vbrief.json` (s1-contract of #1166 strategy consistency decomposition)\n\nThis contract lands first so that s2 (gate) and the migration stories have an unambiguous target.\n"
|
|
154
|
+
"body": "# v0.20 Strategy Output Contract\n\nCanonical contract for the artifacts that every spec-generating strategy MUST produce to be v0.20-conformant.\n\n**Legend (from RFC2119):** !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**⚠️ See also**: [vbrief/vbrief.md](../vbrief/vbrief.md) | [strategies/README.md](./README.md) | [strategies/artifact-guards.md](./artifact-guards.md) | [skills/deft-directive-build/SKILL.md](../skills/deft-directive-build/SKILL.md) (Pre-Cutover Detection Guard) | [scripts/migrate_vbrief.py](../../scripts/migrate_vbrief.py) | [conventions/machine-generated-banner.md](../conventions/machine-generated-banner.md)\n\n---\n\n## Purpose\n\nSpec-generating strategies (interview, yolo, speckit, rapid, enterprise) historically produced inconsistent artifacts:\n\n- Some wrote only the legacy `vbrief/specification.vbrief.json` + root `SPECIFICATION.md`\n- Some wrote scope vBRIEFs without date prefixes and still dual-wrote the old singular spec file\n- None consistently seeded the full v0.20 lifecycle folders + `PROJECT-DEFINITION.vbrief.json` + date-prefixed proposed/ items\n\nThis caused immediate build failures via the Pre-Cutover Detection Guard for any project generated through those strategies.\n\nThis contract is the single source of truth. All future strategy implementations and migrations target exactly these artifacts. The build skill, vbrief validators, and (post-s2) deterministic shape gate enforce it.\n\n## When to Use\n\nUse this contract when authoring, reviewing, or migrating a spec-generating strategy that creates project definition artifacts, scope vBRIEFs, rendered views, or migration handoff material. It also applies when a guard, validator, or setup path needs to decide whether a project is current v0.20 output or legacy pre-cutover content.\n\n## Workflow\n\n1. Identify whether the strategy is spec-generating or preparatory.\n2. Apply the matching row in the per-strategy summary table.\n3. Create the required lifecycle folders before writing scope artifacts.\n4. Write authoritative vBRIEF content to `vbrief/PROJECT-DEFINITION.vbrief.json` and date-prefixed `vbrief/proposed/*.vbrief.json` files.\n5. Omit root `SPECIFICATION.md` / `PROJECT.md`, or write only deprecation redirect stubs when transitional UX requires them.\n6. Run the validator and content gates before treating the strategy output as v0.20-conformant.\n\n## Canonical v0.20 Output Shape\n\nFor a project that has completed any spec-generating strategy (or the full speckit flow), the following MUST exist and be the only authoritative sources:\n\n### Required Directory Structure\n- `vbrief/proposed/`\n- `vbrief/pending/`\n- `vbrief/active/`\n- `vbrief/completed/`\n- `vbrief/cancelled/`\n\nAll five lifecycle folders MUST be present (even if empty). This is the cutover signal used by pre-cutover guards.\n\n### Required Root-Level vBRIEF Artifact\n- `vbrief/PROJECT-DEFINITION.vbrief.json` (complete: narratives + items registry populated from the strategy session)\n\n`task project:render` MAY be invoked by the strategy or left to the user; the end state after strategy + any render MUST have a non-skeleton PROJECT-DEFINITION.\n\n### Scope vBRIEF Placement & Naming (Strict)\n- All new scope vBRIEFs (user stories, phases, epics from speckit Phase 4/4.5, etc.) MUST be written **only** to `vbrief/proposed/YYYY-MM-DD-<kebab-slug>.vbrief.json`\n- Filenames MUST be date-prefixed using the creation date (immutable per vbrief.md conventions)\n- Bare names (e.g. `scaffold.vbrief.json`) or names without date prefix are FORBIDDEN in v0.20\n- The old singular `vbrief/specification.vbrief.json` MUST NOT be written or updated by v0.20 strategies (it is a legacy container; new work uses the lifecycle folders + PROJECT-DEFINITION)\n\n### SPECIFICATION.md & PROJECT.md (Derivative / Deprecated)\n- Strategies SHOULD OMIT writing `SPECIFICATION.md` and `PROJECT.md` entirely. These are **rendered views** only.\n- If a strategy does emit them (for UX continuity during transition), they MUST be written **exclusively** as deprecation-redirect stubs:\n - Start with the canonical 4-line machine-generated banner (see conventions/machine-generated-banner.md)\n - Fifth line: `<!-- deft:deprecated-redirect -->`\n - Short explanatory body pointing to `vbrief/PROJECT-DEFINITION.vbrief.json` and the lifecycle folders\n - Never contain real spec or project content\n- Real content in these files (without the sentinel) triggers the build/setup/sync pre-cutover guards and forces migration.\n\n### Legacy `specification.vbrief.json`\n- ⊗ No v0.20 strategy may create or dual-write `vbrief/specification.vbrief.json` alongside the new model artifacts.\n- Existing legacy files are handled only by `task migrate:vbrief` (which ingests them into scope vBRIEFs + PROJECT-DEFINITION and leaves a redirect stub at root if needed).\n\n### Greenfield spec export (#2013 / #1502)\n\nGreenfield projects (no `vbrief/specification.vbrief.json`) export stakeholder-facing spec text via `task project:export-spec`:\n\n- ! Source of truth: `vbrief/PROJECT-DEFINITION.vbrief.json` product narratives + lifecycle scope bodies (never the legacy singular spec file).\n- ! Default audience is **stakeholder** — proposed scopes are omitted; only pending/active/completed scopes appear under `## Scope outlook`.\n- ! Internal handoff (setup Phase 3, speckit Phase 3→4 when proposed scopes must be visible) uses `task project:export-spec -- --audience=internal`, which adds `### Not yet accepted (proposed)` under `## Scope outlook` with a fixed disclaimer that proposed scopes are ideas, not approved backlog.\n- ! Phase 3→4 transition gate: **export succeeded** (exit 0), not spec-file `approved` status — PROJECT-DEFINITION has no spec-approval lifecycle on greenfield trees.\n- ~ Legacy migrated trees with `vbrief/specification.vbrief.json` MAY continue using `task spec:render` until fully cut over.\n- ⊗ Invoke `task spec:render` on a greenfield tree that lacks `specification.vbrief.json` — use `task project:export-spec` instead.\n\n### plan.vbrief.json and continue.vbrief.json\n- Session/tactical state files are permitted at vbrief/ root (they carry `planRef` links). They are not part of the \"spec output\" contract but strategies that maintain chaining state (e.g. interview) update them per their own rules.\n\n## Per-Strategy Summary Table (Target State After Migration)\n\n| Strategy | Type | Must Create Lifecycle Folders | Must Write PROJECT-DEFINITION | Scope vBRIEFs Location | specification.vbrief.json | SPECIFICATION.md / PROJECT.md |\n|--------------|------------------|-------------------------------|-------------------------------|-----------------------------------------|-----------------------------|----------------------------------------|\n| interview | spec-generating | Yes | Yes (narratives + items) | proposed/YYYY-MM-DD-*.vbrief.json only | Never (post-migration) | Omit or deprecation redirect only |\n| yolo | spec-generating | Yes | Yes | proposed/YYYY-MM-DD-*.vbrief.json only | Never | Omit or deprecation redirect only |\n| speckit | spec-generating | Yes | Yes (Phase 1+) | proposed/YYYY-MM-DD-*.vbrief.json only (phases + stories) | Never | Omit or `task project:export-spec` (legacy: `task spec:render` on migrated trees) |\n| rapid | spec-generating | Yes | Yes | proposed/YYYY-MM-DD-*.vbrief.json only | Never | Omit or deprecation redirect only |\n| enterprise | spec-generating | Yes | Yes | proposed/YYYY-MM-DD-*.vbrief.json only | Never | Omit or deprecation redirect only |\n| preparatory (research, discuss, map, etc.) | preparatory | Yes (if first touch) | No (unless also spec path) | proposed/YYYY-MM-DD-*.vbrief.json (context/decision vBRIEFs) | N/A | N/A (preparatory only) |\n\n## Agent & Strategy Author Rules\n\n- ! Every spec-generating strategy document MUST contain an \"Artifacts\" or \"Output\" section that explicitly cites this contract (`strategies/v0-20-contract.md`) and reproduces the relevant row from the table above.\n- ! Before emitting any vBRIEF artifact, follow the guards in `artifact-guards.md` (updated to reference this contract).\n- ! Date prefixes on scope vBRIEFs are mandatory for swarm readiness, filename sorting, and dedup.\n- ⊗ Write real content to root SPECIFICATION.md or PROJECT.md from a strategy.\n- ⊗ Emit bare-named vBRIEFs in proposed/ or anywhere outside the dated convention.\n- ⊗ Dual-write the old `specification.vbrief.json` in a v0.20 flow.\n\n## Verification & Enforcement\n\n- Build / setup / sync skills: Pre-Cutover Detection Guard (any missing lifecycle folder or real-content legacy md triggers redirect to migrate).\n- `task vbrief:validate` + `task check`: filename convention, folder/status consistency, PROJECT-DEFINITION presence.\n- Post-s2: deterministic validation gate (s2 story) will parse strategy output trees against this contract and fail non-conformant generations.\n- Content tests + migration stories exercise the before/after shapes.\n\n## Migration Path for Existing Strategies\n\nThe s3/s4/s5 stories migrate the individual strategy files (and their emitted examples) to the shape defined here. This contract document is the target spec they implement against; do not change strategies first.\n\n## When to Use\n\nUse this contract when:\n- Authoring a new spec-generating strategy (interview, yolo, speckit, rapid, enterprise, etc.).\n- Migrating an existing strategy to v0.20 (the s3/s4/s5 work).\n- Implementing or updating the deterministic validation gate (s2) or build pre-cutover guards.\n- Writing migration tooling (`migrate_vbrief.py`, reconcile scripts, etc.).\n- Auditing a generated project for v0.20 conformance.\n\n## Workflow\n\n1. Read the Canonical v0.20 Output Shape section.\n2. Ensure your strategy (or migration) writes exactly the required folders + `PROJECT-DEFINITION.vbrief.json` + dated proposed/ vBRIEFs.\n3. Never write the legacy `specification.vbrief.json` or real-content `SPECIFICATION.md`/`PROJECT.md`.\n4. Cite this contract explicitly in your strategy's \"Artifacts\" / \"Output\" section (see the Per-Strategy Summary Table).\n5. Run `task check` (or the deterministic gate once s2 lands) to validate.\n\n---\n\n**Owned by**: `vbrief/active/2026-05-26-define-canonical-v020-strategy-output-contract.vbrief.json` (s1-contract of #1166 strategy consistency decomposition)\n\nThis contract lands first so that s2 (gate) and the migration stories have an unambiguous target.\n"
|
|
155
155
|
},
|
|
156
156
|
{
|
|
157
157
|
"id": "yolo",
|
|
@@ -161,7 +161,7 @@
|
|
|
161
161
|
"yolo"
|
|
162
162
|
],
|
|
163
163
|
"path": "strategies/yolo.md",
|
|
164
|
-
"body": "# Yolo Strategy\n\nAuto-pilot interview: the agent plays both sides, always picking the recommended\noption. Same workflow as [interview.md](./interview.md) (including the sizing\ngate) but the agent answers its own questions via \"Johnbot.\"\n\n**v0.20 note (s3-migrate-yolo / #1166):** Yolo now emits only the canonical v0.20 shape (date-prefixed story vBRIEFs in proposed/, full PROJECT-DEFINITION.vbrief.json via task project:render, seeded lifecycle folders, no legacy specification.vbrief.json). See the dedicated ## v0.20 Output Shape section.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD,
|
|
164
|
+
"body": "# Yolo Strategy\n\nAuto-pilot interview: the agent plays both sides, always picking the recommended\noption. Same workflow as [interview.md](./interview.md) (including the sizing\ngate) but the agent answers its own questions via \"Johnbot.\"\n\n**v0.20 note (s3-migrate-yolo / #1166):** Yolo now emits only the canonical v0.20 shape (date-prefixed story vBRIEFs in proposed/, full PROJECT-DEFINITION.vbrief.json via task project:render, seeded lifecycle folders, no legacy specification.vbrief.json). See the dedicated ## v0.20 Output Shape section.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**⚠️ See also**: [strategies/interview.md](./interview.md) | [strategies/discuss.md](./discuss.md) | [core/glossary.md](../glossary.md) | [vbrief/vbrief.md](../vbrief/vbrief.md) | [artifact-guards.md](./artifact-guards.md)\n\n---\n\n## When to Use\n\n- ~ Quick prototyping where speed matters more than precision\n- ~ When the user trusts the agent's recommended defaults\n- ? When exploring an idea before committing to a full interview\n- ⊗ Production systems or compliance-heavy projects — use [interview.md](./interview.md) instead\n\n## Chaining Gate\n\nJohnbot auto-selects at the [chaining gate](./interview.md#chaining-gate) too.\n\n- ! Johnbot MUST select **\"Proceed to specification\"** (option 1) — no preparatory detours\n- ! Johnbot MUST select **\"Accept\"** at the [acceptance gate](./interview.md#acceptance-gate) — no revisions\n- ⊗ Ask the real user to choose at either gate — Johnbot handles both automatically\n\n## Sizing Gate\n\nJohnbot picks the size too. The same sizing signals from\n[interview.md](./interview.md#sizing-gate) apply, but Johnbot makes the call\nwithout asking the user.\n\n- ! Check `PROJECT.md` for `**Process**: Light` or `**Process**: Full` — if declared, use that path\n- ! If not declared, Johnbot picks based on feature count and complexity signals\n- ~ Default to Light for typical yolo projects (speed over ceremony)\n\n## Workflow Overview\n\n```mermaid\nflowchart LR\n subgraph yolo [\"Yolo Strategy\"]\n G{\"⚖️ Sizing Gate<br/><i>Johnbot picks</i>\"}\n I_L[\"💬 Auto-Interview<br/><i>Light path</i>\"]\n I_F[\"💬 Auto-Interview<br/><i>Full path</i>\"]\n P[\"📄 PRD<br/><i>Auto-approved</i>\"]\n S[\"📁 vbrief/proposed/ (YYYY-MM-DD-*.vbrief.json)<br/>📋 PROJECT-DEFINITION.vbrief.json<br/><i>v0.20 shape</i>\"]\n end\n\n G -->|\"Light\"| I_L\n G -->|\"Full\"| I_F\n I_L -->|\"Johnbot picks defaults\"| S\n I_F -->|\"Johnbot picks defaults\"| P\n P -->|\"Auto-approved\"| S\n S -->|\"Ready\"| IMPL[\"🔨 Implementation\"]\n\n style G fill:#f0abfc,stroke:#a21caf,color:#000\n style I_L fill:#c4b5fd,stroke:#7c3aed,color:#000\n style I_F fill:#c4b5fd,stroke:#7c3aed,color:#000\n style P fill:#fef08a,stroke:#ca8a04,color:#000\n style S fill:#6ee7b7,stroke:#059669,color:#000\n style IMPL fill:#7dd3fc,stroke:#0284c7,color:#000\n```\n\n(See ## v0.20 Output Shape for exact artifact rules and the mandatory `task project:render` call.)\n\n---\n\n## Interview Rules\n\nSame as [interview.md](./interview.md#interview-rules-shared-by-both-paths),\nwith Johnbot additions:\n\n- ~ Use Claude AskInterviewQuestion when available (emulate if not)\n- ! Ask **ONE** focused, non-trivial question per step\n- ⊗ Ask multiple questions at once or sneak in \"also\" questions\n- ~ Provide numbered answer options when appropriate\n- ! Include \"other\" option for custom/unknown responses\n- ! Indicate which option is RECOMMENDED\n- ! Pretend you are the user \"Johnbot\" too\n- ~ Johnbot asks for details/clarifications on the questions when appropriate\n- ! Johnbot ultimately goes with the RECOMMENDED option\n- ⊗ Ask the real user to answer a question — keep working with Johnbot until you can build the specification\n\n---\n\n## Light Path\n\nSame as [interview.md Light path](./interview.md#light-path-smallmedium-projects)\nbut Johnbot answers all questions and auto-approves.\n\n---\n\n## Full Path\n\nSame as [interview.md Full path](./interview.md#full-path-largecomplex-projects)\nbut Johnbot answers all questions and auto-approves the PRD.\n\n---\n\n## v0.20 Output Shape (s3-migrate-yolo / #1166)\n\nThis strategy has been migrated to the full v0.20 output shape so yolo-generated projects are accepted by the build skill Pre-Cutover Detection Guard with zero errors on first attempt (resolves the yolo row from the #1166 inconsistency table).\n\n- ! Seed the five lifecycle folders under `vbrief/` if any are missing: `proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`.\n- ! Emit story scope items exclusively as date-prefixed scope vBRIEFs: `vbrief/proposed/YYYY-MM-DD-<kebab-slug>.vbrief.json` (use the run's creation date for the prefix; choose descriptive slugs). Decompose the yolo plan into one or more focused, buildable story vBRIEFs (v0.6 schema) rather than a monolithic legacy spec.\n- ! After the proposed/ stories are written, invoke `task project:render` (run from the repo root) to generate/refresh the complete `vbrief/PROJECT-DEFINITION.vbrief.json` (items registry is derived from the lifecycle folders).\n- ⊗ Never emit `vbrief/specification.vbrief.json` (or any legacy dual-write).\n- ~ `SPECIFICATION.md` at the project root, if produced at all, must be only a read-only derivative (e.g. via `task spec:render` after the vbriefs exist) that includes the v0.20 deprecated-redirect sentinel. The source of truth is the vbrief/ lifecycle stories + PROJECT-DEFINITION.\n- ! Before writing any proposed/ stories or PROJECT-DEFINITION, follow the guards in [artifact-guards.md](./artifact-guards.md) (Preparatory Guard for scope items in proposed/; Spec-Generating Guard for PROJECT-DEFINITION).\n- ! After emitting the proposed/ story vBRIEF(s), surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).\n- ! Final output tree must pass the deterministic v0.20 strategy output validation gate (s2-deterministic-gate) and the build Pre-Cutover Detection Guard with zero warnings/errors. See full acceptance in the yolo migration vBRIEF and the 1166 decomposition.\n- ~ Once available, cite the canonical contract `strategies/v0-20-contract.md` (s1-contract) for the exact shape.\n\n---\n\n## SPECIFICATION Guidelines\n\nYolo expresses \"specification\" work via the v0.20 date-prefixed story vBRIEFs emitted to `vbrief/proposed/` (see v0.20 Output Shape section above).\n\nThe detailed guidelines from [interview.md](./interview.md#specification-guidelines-both-paths) for content quality, requirements IDs, phasing, parallelism, test-first, task sizing, and format still apply — but the *delivery mechanism* is the discrete vBRIEF stories + PROJECT-DEFINITION (never the legacy specification.vbrief.json).\n\n---\n\n## Artifacts Summary (v0.20)\n\n**Light path and Full path (identical under yolo; PRD auto-approved on Full):**\n\n| Artifact | Purpose | Created By |\n|----------|---------|------------|\n| `vbrief/proposed/YYYY-MM-DD-*.vbrief.json` (one or more) | Focused story scope items (date-prefixed per vbrief convention) | Yolo (Johnbot) |\n| `vbrief/PROJECT-DEFINITION.vbrief.json` | Project identity gestalt + complete scope items registry | `task project:render` (invoked by Yolo) |\n| `vbrief/{proposed,pending,active,completed,cancelled}/` | All five lifecycle folders seeded | Yolo |\n| (optional derivative) `SPECIFICATION.md` | Human-readable plan (includes deprecated-redirect sentinel) | `task spec:render` (if invoked) |\n\n**Pre-v0.20 / legacy artifacts that MUST NOT be produced by this strategy:**\n\n- `vbrief/specification.vbrief.json`\n- Primary handoff `SPECIFICATION.md` at project root\n\n---\n\n## Invoking This Strategy\n\n```\n/deft:run:yolo [project name]\n```\n\nOr explicitly:\n\n```\nUse the yolo strategy to plan [project].\n```\n\nAfter completion (v0.20 shape):\n\n```\ntask project:render\n# Review date-prefixed stories in vbrief/proposed/ + the generated PROJECT-DEFINITION.vbrief.json\n# Implement per the v0.20 artifacts (build skill accepts cleanly on first try)\n```\n"
|
|
165
165
|
}
|
|
166
166
|
]
|
|
167
167
|
}
|