@deftai/directive-content 0.64.0 → 0.66.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.
Files changed (76) hide show
  1. package/.githooks/_deft-run.sh +14 -0
  2. package/.githooks/pre-commit +9 -10
  3. package/.githooks/pre-push +4 -7
  4. package/QUICK-START.md +8 -4
  5. package/Taskfile.yml +32 -14
  6. package/UPGRADING.md +40 -0
  7. package/commands.md +46 -41
  8. package/conventions/rule-ownership.json +1 -1
  9. package/docs/BROWNFIELD.md +37 -33
  10. package/docs/directive-lifecycle.md +2 -2
  11. package/docs/getting-started.md +8 -8
  12. package/package.json +1 -1
  13. package/packs/skills/skills-pack-0.1.json +28 -28
  14. package/skills/deft-directive-article-review/SKILL.md +4 -4
  15. package/skills/deft-directive-build/SKILL.md +37 -37
  16. package/skills/deft-directive-cost/SKILL.md +6 -6
  17. package/skills/deft-directive-debug/SKILL.md +4 -4
  18. package/skills/deft-directive-decompose/SKILL.md +15 -15
  19. package/skills/deft-directive-gh-arch/SKILL.md +3 -3
  20. package/skills/deft-directive-gh-slice/SKILL.md +2 -2
  21. package/skills/deft-directive-interview/SKILL.md +12 -12
  22. package/skills/deft-directive-pre-pr/SKILL.md +3 -3
  23. package/skills/deft-directive-probe/SKILL.md +9 -9
  24. package/skills/deft-directive-refinement/SKILL.md +65 -65
  25. package/skills/deft-directive-release/SKILL.md +3 -3
  26. package/skills/deft-directive-review-cycle/SKILL.md +4 -4
  27. package/skills/deft-directive-setup/SKILL.md +71 -71
  28. package/skills/deft-directive-swarm/SKILL.md +94 -94
  29. package/skills/deft-directive-sync/SKILL.md +55 -55
  30. package/skills/deft-directive-triage/SKILL.md +15 -15
  31. package/tasks/architecture.yml +3 -1
  32. package/tasks/cache.yml +20 -10
  33. package/tasks/capacity.yml +8 -4
  34. package/tasks/change.yml +8 -10
  35. package/tasks/changelog.yml +3 -1
  36. package/tasks/codebase.yml +20 -10
  37. package/tasks/commit.yml +4 -8
  38. package/tasks/engine.yml +16 -4
  39. package/tasks/install.yml +4 -8
  40. package/tasks/issue.yml +8 -10
  41. package/tasks/migrate.yml +24 -8
  42. package/tasks/packs.yml +32 -16
  43. package/tasks/policy.yml +24 -12
  44. package/tasks/pr.yml +16 -8
  45. package/tasks/prd.yml +9 -12
  46. package/tasks/project.yml +14 -14
  47. package/tasks/reconcile.yml +4 -8
  48. package/tasks/roadmap.yml +9 -5
  49. package/tasks/scm.yml +36 -18
  50. package/tasks/scope-undo.yml +3 -1
  51. package/tasks/scope.yml +40 -26
  52. package/tasks/session.yml +4 -2
  53. package/tasks/slice.yml +8 -10
  54. package/tasks/spec.yml +10 -12
  55. package/tasks/swarm.yml +20 -10
  56. package/tasks/triage-actions.yml +32 -16
  57. package/tasks/triage-bootstrap.yml +4 -2
  58. package/tasks/triage-bulk.yml +20 -10
  59. package/tasks/triage-classify.yml +4 -2
  60. package/tasks/triage-queue.yml +12 -6
  61. package/tasks/triage-reconcile.yml +4 -2
  62. package/tasks/triage-scope-drift.yml +4 -2
  63. package/tasks/triage-scope.yml +4 -2
  64. package/tasks/triage-smoketest.yml +4 -2
  65. package/tasks/triage-subscribe.yml +8 -4
  66. package/tasks/triage-summary.yml +4 -2
  67. package/tasks/triage-welcome.yml +4 -2
  68. package/tasks/ts.yml +3 -1
  69. package/tasks/umbrella.yml +1 -7
  70. package/tasks/vbrief.yml +25 -17
  71. package/tasks/verify.yml +107 -48
  72. package/templates/agent-prompt-preamble.md +16 -16
  73. package/templates/agents-entry.md +23 -19
  74. package/vbrief/conformance/extensions/valid/extension-at-root.vbrief.json +31 -0
  75. package/vbrief/conformance/extensions/valid/nested-extension-value.vbrief.json +19 -0
  76. package/vbrief/schemas/xbrief-core-0.8.schema.json +786 -0
@@ -42,13 +42,13 @@ Use this summary to evaluate whether article ideas are genuinely novel or alread
42
42
 
43
43
  **Directive** is a development framework that combines indexed documentation, task automation, and AI-assisted workflows.
44
44
 
45
- **main.md (front door)** — Central entry/index for a Karpathy-wiki-style set of lazy-loaded markdown rules organized into sections: `coding/`, `languages/`, `interfaces/`, `tools/`, `scm/`, `contracts/`, `swarm/`, `strategies/`, `vbrief/`, and `templates/`. Agents load only what's relevant.
45
+ **main.md (front door)** — Central entry/index for a Karpathy-wiki-style set of lazy-loaded markdown rules organized into sections: `coding/`, `languages/`, `interfaces/`, `tools/`, `scm/`, `contracts/`, `swarm/`, `strategies/`, `xbrief/`, and `templates/`. Agents load only what's relevant.
46
46
 
47
47
  **Taskfiles (go-task)** — Single entrypoint for all repeatable operations. Core flows: `task dev`, `task test`, `task build`, `task release`. Composed via `deps`; logic lives in scripts/binaries. Caching via `sources/generates + method: checksum`. Namespaced tasks (`docker:build`, `db:migrate`). Every user-facing task has a `desc`; internal wiring marked `internal: true`.
48
48
 
49
- **vbrief** — Structured JSON artifacts in `./vbrief/` covering current state and forward planning: `plan.vbrief.json` (todos/progress), `specification.vbrief.json` (project specs), `playbook-{name}.vbrief.json` (reusable playbooks), `continue.vbrief.json` (interruption recovery). Drives the full lifecycle: planning → specification → execution → checkpointing → resumption. Refreshed via `deft-sync` at session start.
49
+ **xbrief** — Structured JSON artifacts in `./xbrief/` covering current state and forward planning: `plan.xbrief.json` (todos/progress), `specification.xbrief.json` (project specs), `playbook-{name}.xbrief.json` (reusable playbooks), `continue.xbrief.json` (interruption recovery). Drives the full lifecycle: planning → specification → execution → checkpointing → resumption. Refreshed via `deft-sync` at session start.
50
50
 
51
- **Skills** — Versioned, reusable workflows triggered by keywords: `deft-setup` (bootstrap), `deft-build` (implement from spec), `deft-sync` (refresh framework + vbrief), `deft-pre-pr` (quality loop), `deft-review-cycle` (PR bot feedback), `deft-swarm` (parallel agent orchestration), `deft-roadmap-refresh` (issue triage), `deft-interview` (structured Q&A). Skills chain together and encode lessons from prior runs.
51
+ **Skills** — Versioned, reusable workflows triggered by keywords: `deft-setup` (bootstrap), `deft-build` (implement from spec), `deft-sync` (refresh framework + xbrief), `deft-pre-pr` (quality loop), `deft-review-cycle` (PR bot feedback), `deft-swarm` (parallel agent orchestration), `deft-roadmap-refresh` (issue triage), `deft-interview` (structured Q&A). Skills chain together and encode lessons from prior runs.
52
52
 
53
53
  ## When to Use
54
54
 
@@ -77,7 +77,7 @@ Use this summary to evaluate whether article ideas are genuinely novel or alread
77
77
  Look for lessons applicable to how directive itself is built, structured, and maintained:
78
78
 
79
79
  - ! Skills and strategies: are there new skills, strategies, or workflow patterns directive should adopt?
80
- - ! Framework architecture: does this suggest changes to lazy loading, vBRIEF, AGENTS.md structure, or the patterns/ directory?
80
+ - ! Framework architecture: does this suggest changes to lazy loading, xBRIEF, AGENTS.md structure, or the patterns/ directory?
81
81
  - ! Agent safety and reliability: does this reveal new failure modes or defenses directive should encode?
82
82
  - ! Tooling: does this suggest new tasks, task patterns, or SCM conventions directive should add?
83
83
  - ~ Naming, directory structure, or documentation conventions worth adopting
@@ -1,9 +1,9 @@
1
1
  ---
2
2
  name: deft-directive-build
3
3
  description: >-
4
- Build a project from scope vBRIEFs following Deft Directive framework
4
+ Build a project from scope xBRIEFs following Deft Directive framework
5
5
  standards. Use after deft-directive-setup has generated the project
6
- definition, or when the user has story vBRIEFs in vbrief/active/ ready to
6
+ definition, or when the user has story xBRIEFs in xbrief/active/ ready to
7
7
  implement. Handles scaffolding, implementation, testing, and quality checks
8
8
  phase by phase.
9
9
  ---
@@ -15,33 +15,33 @@ description: >-
15
15
 
16
16
  # Deft Directive Build
17
17
 
18
- Implements a project from its scope vBRIEFs following Deft Directive standards.
18
+ Implements a project from its scope xBRIEFs following Deft Directive standards.
19
19
 
20
20
  Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
21
21
 
22
22
  ## When to Use
23
23
 
24
- - After `deft-directive-setup` completes and generates `PROJECT-DEFINITION.vbrief.json`
24
+ - After `deft-directive-setup` completes and generates `PROJECT-DEFINITION.xbrief.json`
25
25
  - User says "build this", "implement the spec", or "start building"
26
- - Resuming a partially-built project that has story vBRIEFs in `vbrief/active/`
26
+ - Resuming a partially-built project that has story xBRIEFs in `xbrief/active/`
27
27
 
28
28
  ## Step 0 -- Implementation Preflight (#810)
29
29
 
30
30
  - ! Before starting any new implementation story or switching from one story to another, MUST run `git status --short --branch`.
31
31
  - ! If the working tree is dirty, MUST stop and summarize the current branch, modified/untracked files, and whether the changes appear related to the target story. Ask the operator to choose one path: commit existing work, stash existing work, include existing work in the current story, or stop.
32
32
  - ⊗ Begin a new story while unrelated dirty work is present without explicit operator approval.
33
- - ! Resolve exactly one target story vBRIEF path by default. One story is the default implementation unit for this skill; if the user asks for a phase/epic, decompose or ask which story to start.
33
+ - ! Resolve exactly one target story xBRIEF path by default. One story is the default implementation unit for this skill; if the user asks for a phase/epic, decompose or ask which story to start.
34
34
  - ! Batching multiple stories in one branch/PR requires explicit operator approval and a short rationale recorded in the handoff.
35
- - ! **Swarm-cohort dispatch carve-out**: when this skill is invoked as part of a swarm cohort allocated by `skills/deft-directive-swarm/SKILL.md`, the approved Phase 5 allocation plan satisfies the "explicit operator approval and short rationale recorded in the handoff" requirement above -- the dispatched vBRIEF paths and allocation rationale ARE the consent token. Process each assigned story sequentially under the checkpoint-commit + `task scope:complete` discipline below. Do NOT re-prompt the parent for batching approval mid-cohort -- the all-or-nothing dispatch envelope rule (`AGENTS.md` `## Multi-agent orchestration discipline (#954)`) forbids mid-scope user-approval gates.
35
+ - ! **Swarm-cohort dispatch carve-out**: when this skill is invoked as part of a swarm cohort allocated by `skills/deft-directive-swarm/SKILL.md`, the approved Phase 5 allocation plan satisfies the "explicit operator approval and short rationale recorded in the handoff" requirement above -- the dispatched xBRIEF paths and allocation rationale ARE the consent token. Process each assigned story sequentially under the checkpoint-commit + `task scope:complete` discipline below. Do NOT re-prompt the parent for batching approval mid-cohort -- the all-or-nothing dispatch envelope rule (`AGENTS.md` `## Multi-agent orchestration discipline (#954)`) forbids mid-scope user-approval gates.
36
36
  - ! **Structured consent-token recognition (#1378)**: the canonical recognition path for the carve-out above is the structured `## Allocation context` section of the dispatch envelope (the frozen schema in `templates/agent-prompt-preamble.md`, Story A of #1378). When that section reports `dispatch_kind: swarm-cohort` with a non-null `allocation_plan_id` AND a non-null `batching_rationale`, the consent token is satisfied mechanically -- read `cohort_vbriefs` as the authoritative file boundary and process each entry sequentially under the checkpoint-commit + `task scope:complete` discipline below, without re-prompting the parent for batching approval mid-cohort. When the `## Allocation context` section is ABSENT (pre-#1378 dispatches, solo-interactive sessions), fall back to the #1371 prose carve-out immediately above -- the prose carve-out remains the recognition path of record for un-elevated envelopes.
37
37
  - ! **Within a cohort, between stories**: the working tree MUST be clean after each story's checkpoint commit + `task scope:complete`. If `git status --short` shows uncommitted state between stories (e.g. a missed `task scope:complete` move, an unstaged file from the prior story), checkpoint-commit it and proceed -- do NOT pause to ask the operator. The dirty-tree "ask the operator" branch above applies only at the FIRST story-start of a fresh branch, where uncommitted operator work might legitimately exist.
38
- - ! If the target story is in `vbrief/proposed/`, run `task scope:promote -- <path>` first; if it is in `vbrief/pending/`, run `task scope:activate -- <path>`. After activation, update the path to the active-file location before preflight.
39
- - ! Before any code-writing tool call -- the first scaffold edit, the first `task` invocation that mutates files, or any `start_agent` dispatch that will implement scope -- MUST run `task vbrief:preflight -- <active-story-path>` (the structural intent gate; wraps `scripts/preflight_implementation.py` so the same invocation works whether deft is the project root or installed as a `deft/` subdirectory).
38
+ - ! If the target story is in `xbrief/proposed/`, run `task scope:promote -- <path>` first; if it is in `xbrief/pending/`, run `task scope:activate -- <path>`. After activation, update the path to the active-file location before preflight.
39
+ - ! Before any code-writing tool call -- the first scaffold edit, the first `task` invocation that mutates files, or any `start_agent` dispatch that will implement scope -- MUST run `task xbrief:preflight -- <active-story-path>` (the structural intent gate; wraps `scripts/preflight_implementation.py` so the same invocation works whether deft is the project root or installed as a `deft/` subdirectory).
40
40
 
41
- The gate exits 0 only when the candidate vBRIEF lives in `vbrief/active/` AND `plan.status == "running"`. Any other state (pending/, proposed/, completed/, active/-with-non-running-status, malformed JSON, missing keys) exits 1 with an actionable redirect to `task vbrief:activate <path>`.
41
+ The gate exits 0 only when the candidate xBRIEF lives in `xbrief/active/` AND `plan.status == "running"`. Any other state (pending/, proposed/, completed/, active/-with-non-running-status, malformed JSON, missing keys) exits 1 with an actionable redirect to `task xbrief:activate <path>`.
42
42
 
43
43
  - ! A non-zero exit MUST halt the skill. Surface the helper's stderr message verbatim to the user; do NOT proceed to USER.md Gate, File Reading, or any later phase.
44
- - ! Use canonical lifecycle tasks to satisfy this gate: `task scope:promote -- <path>` for proposed stories, `task scope:activate -- <path>` for pending stories, and the helper's idempotent companion `task vbrief:activate <path>` only when following the preflight redirect directly. Manual lifecycle moves bypass the activation contract -- use the task.
44
+ - ! Use canonical lifecycle tasks to satisfy this gate: `task scope:promote -- <path>` for proposed stories, `task scope:activate -- <path>` for pending stories, and the helper's idempotent companion `task xbrief:activate <path>` only when following the preflight redirect directly. Manual lifecycle moves bypass the activation contract -- use the task.
45
45
  - ⊗ Infer implementation intent from lifecycle vocabulary ("do the full PR process", "start the work", "poller agents"), branching language, or workflow shape. Workflow-shape vocabulary is NOT authorization to spawn an implementation agent (#810 surfacing event).
46
46
  - ⊗ Skip this preflight because the user said "yes", "go", or "proceed" -- affirmative continuation phrases are NOT implementation authorization unless the prior turn explicitly proposed implementation. When intent is ambiguous, ask one targeted question before invoking the gate.
47
47
 
@@ -64,13 +64,13 @@ The gate exits 0 only when the candidate vBRIEF lives in `vbrief/active/` AND `p
64
64
 
65
65
  A project is **pre-cutover** if ANY of the following are true. This prose mirrors the executable helper in `scripts/_precutover.py`; when in doubt, the helper is canonical.
66
66
 
67
- 1. `SPECIFICATION.md` exists and is neither a deprecation redirect nor a current generated spec export. A current generated spec export contains `<!-- Purpose: rendered specification -->` and `<!-- Source of truth: vbrief/specification.vbrief.json -->`, and `vbrief/specification.vbrief.json` plus all five lifecycle folders exist.
67
+ 1. `SPECIFICATION.md` exists and is neither a deprecation redirect nor a current generated spec export. A current generated spec export contains `<!-- Purpose: rendered specification -->` and `<!-- Source of truth: xbrief/specification.xbrief.json -->`, and `xbrief/specification.xbrief.json` plus all five lifecycle folders exist.
68
68
  2. `PROJECT.md` exists and contains neither the legacy `<!-- deft:deprecated-redirect -->` sentinel NOR the current `Purpose: deprecation redirect` canonical-banner marker (real content, not a deprecation redirect)
69
- 3. `vbrief/specification.vbrief.json` exists but the lifecycle folders (`vbrief/proposed/`, `vbrief/pending/`, `vbrief/active/`, `vbrief/completed/`, `vbrief/cancelled/`) do NOT exist
69
+ 3. `xbrief/specification.xbrief.json` exists but the lifecycle folders (`xbrief/proposed/`, `xbrief/pending/`, `xbrief/active/`, `xbrief/completed/`, `xbrief/cancelled/`) do NOT exist
70
70
  4. Strategy output shape violations (run `task verify-strategy-output` -- the canonical gate -- or the direct form `python .deft/core/scripts/validate_strategy_output.py --project-root <path>` after `deft` install):
71
- - Any scope vBRIEF under `vbrief/proposed/` (or other lifecycle dirs) lacks the required `YYYY-MM-DD-` date prefix in its filename (e.g. bare `scaffold.vbrief.json`).
72
- - `vbrief/PROJECT-DEFINITION.vbrief.json` is missing.
73
- - `vbrief/specification.vbrief.json` exists as a legacy dual-write in a user-generated project. This is tolerated only for the framework source tree or a complete post-cutover full-spec consumer where all lifecycle folders exist and `SPECIFICATION.md` is rendered from `vbrief/specification.vbrief.json`.
71
+ - Any scope xBRIEF under `xbrief/proposed/` (or other lifecycle dirs) lacks the required `YYYY-MM-DD-` date prefix in its filename (e.g. bare `scaffold.xbrief.json`).
72
+ - `xbrief/PROJECT-DEFINITION.xbrief.json` is missing.
73
+ - `xbrief/specification.xbrief.json` exists as a legacy dual-write in a user-generated project. This is tolerated only for the framework source tree or a complete post-cutover full-spec consumer where all lifecycle folders exist and `SPECIFICATION.md` is rendered from `xbrief/specification.xbrief.json`.
74
74
 
75
75
  ### Action on Detection
76
76
 
@@ -80,11 +80,11 @@ A project is **pre-cutover** if ANY of the following are true. This prose mirror
80
80
 
81
81
  ! Include specific details about what was detected (the validator output is authoritative):
82
82
 
83
- - Legacy specification.vbrief.json or missing lifecycle folders: "Follow the frozen v0.59.0 migrator path (#2068) or run `task migrate:preflight` for current-release guidance"
84
- - Non-date-prefixed vBRIEFs: "Re-run the emitting strategy after the v0.20 migrations (#1166 s1+s2+...) or manually rename files to `YYYY-MM-DD-<slug>.vbrief.json` and `task scope:promote`"
85
- - Missing `PROJECT-DEFINITION.vbrief.json`: "Run `task project:render` to generate the project definition"
83
+ - Legacy specification.xbrief.json or missing lifecycle folders: "Follow the frozen v0.59.0 migrator path (#2068) or run `task migrate:preflight` for current-release guidance"
84
+ - Non-date-prefixed xBRIEFs: "Re-run the emitting strategy after the v0.20 migrations (#1166 s1+s2+...) or manually rename files to `YYYY-MM-DD-<slug>.xbrief.json` and `task scope:promote`"
85
+ - Missing `PROJECT-DEFINITION.xbrief.json`: "Run `task project:render` to generate the project definition"
86
86
  - `SPECIFICATION.md` / `PROJECT.md` without sentinel: the classic pre-cutover messages
87
- - Scope vBRIEF in wrong folder: "Status is '{status}' but file is in {folder}/ -- run `task scope:activate <file>` to fix"
87
+ - Scope xBRIEF in wrong folder: "Status is '{status}' but file is in {folder}/ -- run `task scope:activate <file>` to fix"
88
88
 
89
89
  ! After the validator reports clean, re-run this guard before continuing.
90
90
 
@@ -144,8 +144,8 @@ signal.
144
144
  ## File Reading
145
145
 
146
146
  - ! Read in order, lazy load:
147
- 1. `./vbrief/active/` -- scope vBRIEFs for work items to build (required)
148
- 2. `./vbrief/PROJECT-DEFINITION.vbrief.json` -- project identity, tech stack, architecture
147
+ 1. `./xbrief/active/` -- scope xBRIEFs for work items to build (required)
148
+ 2. `./xbrief/PROJECT-DEFINITION.xbrief.json` -- project identity, tech stack, architecture
149
149
  3. `./.planning/codebase/MAP.md` -- generated codebase orientation projection, if present (advisory)
150
150
  4. USER.md at the platform-appropriate path (see Platform Detection) -- Personal section is highest precedence; Defaults are fallback
151
151
  5. `deft/main.md` -- framework guidelines
@@ -162,22 +162,22 @@ signal.
162
162
 
163
163
  ```
164
164
  USER.md Personal <- HIGHEST (name, custom rules -- always wins)
165
- PROJECT-DEFINITION.vbrief.json <- Project-specific (tech stack, architecture, config)
165
+ PROJECT-DEFINITION.xbrief.json <- Project-specific (tech stack, architecture, config)
166
166
  USER.md Defaults <- Fallback defaults (used when PROJECT-DEFINITION doesn't specify)
167
167
  {language}.md <- Language standards
168
168
  coding.md <- General coding
169
169
  main.md <- Framework defaults
170
- Scope vBRIEFs <- LOWEST
170
+ Scope xBRIEFs <- LOWEST
171
171
  ```
172
172
 
173
173
  - ! USER.md Personal section always wins over any other file
174
- - ! For project-scoped settings, PROJECT-DEFINITION.vbrief.json overrides USER.md Defaults
174
+ - ! For project-scoped settings, PROJECT-DEFINITION.xbrief.json overrides USER.md Defaults
175
175
 
176
176
  ## Change Lifecycle Gate
177
177
 
178
178
  ! Before any implementation that touches 3+ files, verify that a `/deft:change <name>` proposal exists and has been confirmed by the user:
179
179
 
180
- - ! Check `history/changes/` for an active `proposal.vbrief.json` matching this work
180
+ - ! Check `history/changes/` for an active `proposal.xbrief.json` matching this work
181
181
  - ! If no proposal exists: propose `/deft:change <name>` and present the change name for explicit confirmation (e.g. "Confirm? yes/no")
182
182
  - ! The user must reply with an affirmative (`yes`, `confirmed`, `approve`) — a general 'proceed', 'do it', or 'go ahead' does NOT satisfy this gate
183
183
  - ? For solo projects: this gate is RECOMMENDED but not mandatory for changes fully covered by `task check`; it remains mandatory for cross-cutting, architectural, or high-risk changes
@@ -185,18 +185,18 @@ Scope vBRIEFs <- LOWEST
185
185
 
186
186
  ## Build Process
187
187
 
188
- All vBRIEFs (including those read from `vbrief/active/` and any new vBRIEFs this skill emits) MUST use `"vBRIEFInfo": { "version": "0.6" }`. The validator rejects any other version (see [`../../conventions/references.md`](../../conventions/references.md)).
188
+ All xBRIEFs (including those read from `xbrief/active/` and any new xBRIEFs this skill emits) MUST use `"xBRIEFInfo": { "version": "0.6" }`. The validator rejects any other version (see [`../../conventions/references.md`](../../conventions/references.md)).
189
189
 
190
190
  ### Step 1: Understand the Scope
191
191
 
192
- - ! Read story vBRIEFs from `vbrief/active/` and `PROJECT-DEFINITION.vbrief.json`
193
- - ! Identify phases, dependencies, starting point from scope vBRIEF acceptance criteria
192
+ - ! Read story xBRIEFs from `xbrief/active/` and `PROJECT-DEFINITION.xbrief.json`
193
+ - ! Identify phases, dependencies, starting point from scope xBRIEF acceptance criteria
194
194
  - ~ Use `.planning/codebase/MAP.md`, when present, to orient broad codebase scanning. If the MAP conflicts with current code or canonical metadata, surface the drift and trust `plan.architecture.codeStructure` / provider artifacts plus the working tree over generated prose.
195
195
  - ! When scanning the existing codebase during scope understanding, MUST surface any contradicting patterns (two error-handling shapes, two state-management approaches, two naming conventions, etc.) before implementation begins -- apply `coding/hygiene.md` `## Surface Conflicts: Pick One, Explain, Flag the Other (#1005)` and choose ONE pattern (more recent OR more tested), explain the choice in the scope summary, and flag the other for cleanup
196
196
  - ⊗ Begin implementation against an averaged blend of two contradicting patterns -- "average code that satisfies both rules is the worst code" (#1005)
197
197
  - ! Present brief summary to user:
198
198
 
199
- > "Here's what I see: {N} story vBRIEFs in active/. I'll start with {name}. Ready?"
199
+ > "Here's what I see: {N} story xBRIEFs in active/. I'll start with {name}. Ready?"
200
200
 
201
201
  ### Step 2: Verify Toolchain
202
202
 
@@ -223,7 +223,7 @@ After EVERY phase:
223
223
 
224
224
  ```bash
225
225
  task check # Format, lint, type check, test, coverage
226
- task test:coverage # >=85% or PROJECT-DEFINITION.vbrief.json override
226
+ task test:coverage # >=85% or PROJECT-DEFINITION.xbrief.json override
227
227
  ```
228
228
 
229
229
  - ! Phase is NOT done until `task check` passes
@@ -248,7 +248,7 @@ See `deft/coding/coding.md` and `deft/coding/testing.md` for full rules.
248
248
  ! Before every commit, re-read ALL modified files and explicitly check for:
249
249
 
250
250
  1. ! **Encoding errors** -- em-dashes corrupted to replacement characters, BOM artifacts, mojibake from round-trip read/write
251
- 2. ! **Unintended duplication** -- accidental double entries in CHANGELOG.md, scope vBRIEF files, or structured data files
251
+ 2. ! **Unintended duplication** -- accidental double entries in CHANGELOG.md, scope xBRIEF files, or structured data files
252
252
  3. ! **Structural issues** -- malformed CHANGELOG entries, broken table rows, mismatched index entries, invalid JSON/YAML
253
253
  4. ! **Semantic accuracy** -- verify that counts, claims, and summaries in CHANGELOG entries and ROADMAP changelog lines match the actual data in the commit (e.g. "triaged 4 issues" must match the number actually triaged, issue numbers cited must match the issues actually added)
254
254
  5. ! **Semantic contradictions** -- when adding a `!` or `⊗` rule that prohibits a specific command, pattern, or behavior, search the same file for any `~`, `≉`, or prose that recommends or permits the same command/pattern -- resolve all contradictions in the same commit before pushing
@@ -275,8 +275,8 @@ feat(phase-2): add REST API endpoints with integration tests
275
275
  - ! Tests fail → fix them; ⊗ skip or weaken assertions
276
276
  - ! Coverage drops → write more tests; ⊗ exclude files
277
277
  - ! Lint/type errors → fix them; ≉ add ignore comments without documented reason
278
- - ! Scope vBRIEF ambiguous -> ask user; ⊗ guess
279
- - ! Scope needs changes -> propose, get approval, update the scope vBRIEF first
278
+ - ! Scope xBRIEF ambiguous -> ask user; ⊗ guess
279
+ - ! Scope needs changes -> propose, get approval, update the scope xBRIEF first
280
280
 
281
281
  ## Completion
282
282
 
@@ -288,15 +288,15 @@ feat(phase-2): add REST API endpoints with integration tests
288
288
 
289
289
  - ⊗ Skip tests or write them after implementation
290
290
  - ⊗ Ignore `task check` failures
291
- - ⊗ Implement things not in scope vBRIEF without asking
291
+ - ⊗ Implement things not in scope xBRIEF without asking
292
292
  - ⊗ Read every deft file upfront
293
293
  - ⊗ Move to next phase before current passes checks
294
294
  - ⊗ Make commits without running `task check`
295
295
  - ⊗ Proceed without USER.md -- always run the USER.md Gate first
296
- - ⊗ Spawn an implementation agent or invoke a code-writing tool against a vBRIEF that has not passed `task vbrief:preflight` (which wraps `scripts/preflight_implementation.py`) -- always run the Step 0 Implementation Preflight (#810) first; satisfy via `task vbrief:activate <path>`
296
+ - ⊗ Spawn an implementation agent or invoke a code-writing tool against a xBRIEF that has not passed `task xbrief:preflight` (which wraps `scripts/preflight_implementation.py`) -- always run the Step 0 Implementation Preflight (#810) first; satisfy via `task xbrief:activate <path>`
297
297
  - ⊗ Proceed without `COST-ESTIMATE.md` and a recorded build / rescope / no-build / skip(+reason) decision -- always run the Cost Phase Gate (#739) first
298
298
  - ⊗ Proceed with implementation when the build or test toolchain is unavailable -- always run the Toolchain Gate (Step 2) first
299
299
  - ⊗ Proceed to next task or phase without tests passing -- testing is a hard gate, not a cleanup step
300
300
  - ⊗ Skip the Change Lifecycle Gate because the user said "proceed" -- broad approval does not satisfy the confirmation gate
301
- - ⊗ Commit or push directly to the default branch -- always create a feature branch first. Exception: user explicitly instructs a direct commit, or `PROJECT-DEFINITION.vbrief.json` narratives contain `Allow direct commits to master: true`
301
+ - ⊗ Commit or push directly to the default branch -- always create a feature branch first. Exception: user explicitly instructs a direct commit, or `PROJECT-DEFINITION.xbrief.json` narratives contain `Allow direct commits to master: true`
302
302
  - ⊗ Add a prohibition (`!` or `⊗`) without scanning the same file for conflicting softer-strength rules (`~`, `≉`) that reference the same term
@@ -25,7 +25,7 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
25
25
  ## When to Use
26
26
 
27
27
  - After `skills/deft-directive-setup/SKILL.md` Phase 3 has produced an
28
- approved `vbrief/specification.vbrief.json` (status `approved`)
28
+ approved `xbrief/specification.xbrief.json` (status `approved`)
29
29
  - Before `skills/deft-directive-build/SKILL.md` kicks off
30
30
  - When the user says "cost", "budget", "pre-build cost", "how much will
31
31
  this cost", or asks to estimate cost before building
@@ -60,11 +60,11 @@ two skills agree on the user's preferences file.
60
60
 
61
61
  ## Inputs
62
62
 
63
- - ! `vbrief/specification.vbrief.json` MUST exist with `plan.status =
63
+ - ! `xbrief/specification.xbrief.json` MUST exist with `plan.status =
64
64
  "approved"`. If the spec is not yet approved, stop and redirect to
65
65
  `skills/deft-directive-setup/SKILL.md` Phase 3 / the spec approval
66
66
  gate.
67
- - ~ `vbrief/PROJECT-DEFINITION.vbrief.json` (for tech-stack and
67
+ - ~ `xbrief/PROJECT-DEFINITION.xbrief.json` (for tech-stack and
68
68
  architecture narratives). Optional but improves the estimate.
69
69
  - ~ `templates/COST-ESTIMATE.md` (canonical artifact body).
70
70
  - ~ `references/cost-models.md` (methodology).
@@ -139,7 +139,7 @@ This is your project's cost estimate. Pick one.
139
139
  `skills/deft-directive-refinement/SKILL.md` to pull spec scope back,
140
140
  or the interview), then re-run this skill from Phase 1.
141
141
  - ! On `No-build`, write the decision to `COST-ESTIMATE.md`, mark the
142
- spec scope vBRIEF accordingly, exit, and do NOT chain into the build
142
+ spec scope xBRIEF accordingly, exit, and do NOT chain into the build
143
143
  skill.
144
144
  - ! On `Skip`, write the decision and skip reason to `COST-ESTIMATE.md`
145
145
  and proceed to the build kickoff.
@@ -156,8 +156,8 @@ This is your project's cost estimate. Pick one.
156
156
 
157
157
  - ! `COST-ESTIMATE.md` (in the project root). Created by Phase 2 and
158
158
  finalised in Phase 4 with the recorded decision.
159
- - ~ Reference the artifact from `vbrief/PROJECT-DEFINITION.vbrief.json`
160
- via a `references` entry of type `x-vbrief/spec-section` so future
159
+ - ~ Reference the artifact from `xbrief/PROJECT-DEFINITION.xbrief.json`
160
+ via a `references` entry of type `x-xbrief/spec-section` so future
161
161
  agents discover the cost decision when re-reading the project
162
162
  definition.
163
163
 
@@ -58,8 +58,8 @@ NO CONCLUSIONS WITHOUT EVIDENCE THAT CLOSES
58
58
  The investigation is a sustained posture across turns, not a one-shot answer.
59
59
 
60
60
  - ! On entry, create an investigation directory `.tmp/investigations/<id>/`
61
- (gitignored, ephemeral) and write the ledger `investigation.vbrief.json` from
62
- `docs/reference/forensic-research/templates/investigation.vbrief.json`. Stamp
61
+ (gitignored, ephemeral) and write the ledger `investigation.xbrief.json` from
62
+ `docs/reference/forensic-research/templates/investigation.xbrief.json`. Stamp
63
63
  `plan.status = "running"`.
64
64
  - ! While MODE is active, every turn appends evidence to the ledger before any
65
65
  narrative. The ledger is the source of truth; chat is a view of it.
@@ -71,7 +71,7 @@ The investigation is a sustained posture across turns, not a one-shot answer.
71
71
 
72
72
  ## The Claim Ledger
73
73
 
74
- The ledger is a thin vBRIEF 0.6 profile (`forensic-research-v1`):
74
+ The ledger is a thin xBRIEF 0.6 profile (`forensic-research-v1`):
75
75
 
76
76
  - ! Top-level `plan.items[]` are **branches** (competing theories). Each branch's
77
77
  child `items[]` are **claims** (testable assertions).
@@ -124,7 +124,7 @@ When the close gate passes, write the Outcome from
124
124
 
125
125
  ! When the Outcome is delivered and the ledger has passed the close gate, confirm
126
126
  exit unambiguously: "deft-directive-debug complete -- exiting skill." Then state
127
- the next step (e.g. open a fix vBRIEF for the proven cause, or chain into
127
+ the next step (e.g. open a fix xBRIEF for the proven cause, or chain into
128
128
  `skills/deft-directive-build/SKILL.md` to implement the fix).
129
129
 
130
130
  ⊗ Exit silently without confirming completion.
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  name: deft-directive-decompose
3
3
  description: >-
4
- Convert approved specification/phase/epic scope vBRIEFs into swarm-ready
5
- story vBRIEFs before concurrent agent allocation.
4
+ Convert approved specification/phase/epic scope xBRIEFs into swarm-ready
5
+ story xBRIEFs before concurrent agent allocation.
6
6
  ---
7
7
  <!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
8
8
  <!-- Purpose: rendered skill -->
@@ -12,7 +12,7 @@ description: >-
12
12
 
13
13
  # Deft Directive Decompose
14
14
 
15
- Use this skill when a specification, Phase 4 implementation scope, or epic vBRIEF is too broad for direct concurrent swarm work and must be decomposed into story-level vBRIEFs.
15
+ Use this skill when a specification, Phase 4 implementation scope, or epic xBRIEF is too broad for direct concurrent swarm work and must be decomposed into story-level xBRIEFs.
16
16
 
17
17
  Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
18
18
 
@@ -20,11 +20,11 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
20
20
 
21
21
  ## Purpose
22
22
 
23
- Convert approved specification/phase/epic scope vBRIEFs into swarm-ready child story vBRIEFs. Story vBRIEFs are the only valid input for concurrent swarm worker allocation.
23
+ Convert approved specification/phase/epic scope xBRIEFs into swarm-ready child story xBRIEFs. Story xBRIEFs are the only valid input for concurrent swarm worker allocation.
24
24
 
25
25
  ## Phase 0: Inspect
26
26
 
27
- - ! Read `vbrief/specification.vbrief.json` and relevant scope vBRIEFs from `vbrief/proposed/`, `vbrief/pending/`, and `vbrief/active/`.
27
+ - ! Read `xbrief/specification.xbrief.json` and relevant scope xBRIEFs from `xbrief/proposed/`, `xbrief/pending/`, and `xbrief/active/`.
28
28
  - ! Identify broad scopes with `plan.metadata.kind = "phase"` or `"epic"` or scopes with broad `plan.narratives.Acceptance` and empty `plan.items`.
29
29
  - ! Preserve parent acceptance as context; do not treat it as executable story acceptance.
30
30
  - ! Treat parent `plan.items` as input signals only; they are not automatically child stories.
@@ -34,10 +34,10 @@ Convert approved specification/phase/epic scope vBRIEFs into swarm-ready child s
34
34
 
35
35
  ## Phase 1: Draft
36
36
 
37
- - ! Draft a decomposition JSON proposal with child stories only; do not write child vBRIEFs yet.
38
- - ! Treat the draft JSON as a temporary proposal artifact, not a vBRIEF.
39
- - ! Write draft proposals under `vbrief/.eval/decompositions/`, using a parent-derived slug such as `vbrief/.eval/decompositions/ip001-auth.json`.
40
- - ! Derive `<parent-slug>` from the parent vBRIEF filename by removing `.vbrief.json` and any leading `YYYY-MM-DD-` date prefix; for example, `vbrief/pending/2026-05-12-ip001-auth.vbrief.json` uses `ip001-auth`, while `vbrief/pending/feature-xyz.vbrief.json` uses `feature-xyz`.
37
+ - ! Draft a decomposition JSON proposal with child stories only; do not write child xBRIEFs yet.
38
+ - ! Treat the draft JSON as a temporary proposal artifact, not a xBRIEF.
39
+ - ! Write draft proposals under `xbrief/.eval/decompositions/`, using a parent-derived slug such as `xbrief/.eval/decompositions/ip001-auth.json`.
40
+ - ! Derive `<parent-slug>` from the parent xBRIEF filename by removing `.xbrief.json` and any leading `YYYY-MM-DD-` date prefix; for example, `xbrief/pending/2026-05-12-ip001-auth.xbrief.json` uses `ip001-auth`, while `xbrief/pending/feature-xyz.xbrief.json` uses `feature-xyz`.
41
41
  - ⊗ Agents MUST NOT leave decomposition draft JSON files at the workspace root.
42
42
  - ! Each story MUST include `id`, `title`, `Description`, `ImplementationPlan`, `UserStory`, executable `items` or `acceptance`, `traces` or explicit trace justification, `swarm.file_scope`, `swarm.verify_commands`, `swarm.expected_outputs`, `swarm.depends_on`, `swarm.conflict_group`, `swarm.size`, `swarm.file_scope_confidence`, and `swarm.model_tier`.
43
43
  - ! `Description` MUST provide at least two concrete sentences explaining the user/product behavior, boundaries, and why this story is independently buildable.
@@ -46,7 +46,7 @@ Convert approved specification/phase/epic scope vBRIEFs into swarm-ready child s
46
46
  - ! Each ready story MUST have 2-5 concrete acceptance criteria unless `swarm.acceptance_criteria_justification` explains the exception.
47
47
  - ! Acceptance criteria MUST be observable behavior, preferably Given/When/Then or equivalent testable product behavior.
48
48
  - ⊗ Mark a story ready when acceptance says only "to refine from parent scope", duplicates the title/description, is placeholder text, or is vague docs-only acceptance.
49
- - ⊗ Mark a story ready with broad write scope such as `backend/**`, `frontend/**`, `docs/**`, `vbrief/**`, or any other directory glob.
49
+ - ⊗ Mark a story ready with broad write scope such as `backend/**`, `frontend/**`, `docs/**`, `xbrief/**`, or any other directory glob.
50
50
  - ⊗ Mark a story ready when verification is only generic validation such as `task check`.
51
51
  - ⊗ Mark a story ready with `parallel_safe: false` or `file_scope_confidence: low`; use `readiness: sequential` or `readiness: needs_refinement` instead.
52
52
  - ! Model dependencies as story IDs and ensure they form a DAG.
@@ -67,23 +67,23 @@ Convert approved specification/phase/epic scope vBRIEFs into swarm-ready child s
67
67
  - ! Validate the approved draft first:
68
68
 
69
69
  ```bash
70
- task scope:decompose -- vbrief/pending/2026-05-12-ip001-auth.vbrief.json --draft vbrief/.eval/decompositions/ip001-auth.json --check
70
+ task scope:decompose -- xbrief/pending/2026-05-12-ip001-auth.xbrief.json --draft xbrief/.eval/decompositions/ip001-auth.json --check
71
71
  ```
72
72
 
73
73
  - ! Apply the approved draft:
74
74
 
75
75
  ```bash
76
- task scope:decompose -- vbrief/pending/2026-05-12-ip001-auth.vbrief.json --draft vbrief/.eval/decompositions/ip001-auth.json
76
+ task scope:decompose -- xbrief/pending/2026-05-12-ip001-auth.xbrief.json --draft xbrief/.eval/decompositions/ip001-auth.json
77
77
  ```
78
78
 
79
- The command creates generated child story vBRIEFs as lifecycle artifacts, defaulting to `vbrief/pending/`. It preserves origin/provenance references, sets each child `planRef` to the parent, updates parent references to include the children, rejects dependency cycles, and rejects ready stories missing executable acceptance, user-story shape, concrete acceptance, narrow file scope, focused verify commands, or traces.
79
+ The command creates generated child story xBRIEFs as lifecycle artifacts, defaulting to `xbrief/pending/`. It preserves origin/provenance references, sets each child `planRef` to the parent, updates parent references to include the children, rejects dependency cycles, and rejects ready stories missing executable acceptance, user-story shape, concrete acceptance, narrow file scope, focused verify commands, or traces.
80
80
 
81
81
  ## Phase 4: Pending Readiness
82
82
 
83
83
  - ! Run readiness against the generated pending child story paths after decomposition:
84
84
 
85
85
  ```bash
86
- task swarm:readiness -- vbrief/pending/<child-story-1>.vbrief.json vbrief/pending/<child-story-2>.vbrief.json
86
+ task swarm:readiness -- xbrief/pending/<child-story-1>.xbrief.json xbrief/pending/<child-story-2>.xbrief.json
87
87
  ```
88
88
 
89
89
  - ! Treat this as a dry readiness review before activation; do not allocate workers from pending paths.
@@ -93,4 +93,4 @@ task swarm:readiness -- vbrief/pending/<child-story-1>.vbrief.json vbrief/pendin
93
93
 
94
94
  ## Exit
95
95
 
96
- deft-directive-decompose complete -- exiting skill. Next, activate the approved child story vBRIEFs through the existing lifecycle flow, then run `skills/deft-directive-swarm/SKILL.md` for concurrent allocation.
96
+ deft-directive-decompose complete -- exiting skill. Next, activate the approved child story xBRIEFs through the existing lifecycle flow, then run `skills/deft-directive-swarm/SKILL.md` for concurrent allocation.
@@ -94,7 +94,7 @@ Spawn 3+ sub-agents with **radically different** design constraints. Each produc
94
94
  - Agent 3: "Optimize for the most common caller — make the default case trivial"
95
95
  - Agent 4 (if applicable): "Design around ports & adapters for cross-boundary dependencies"
96
96
 
97
- - ! The sub-agent dispatch envelope MUST include `templates/agent-prompt-preamble.md` verbatim (or by reference) per AGENTS.md `## Multi-agent orchestration discipline (#954)`. The preamble carries the AGENTS.md read mandate, the #810 vBRIEF gate walkthrough, the PowerShell 5.1 non-ASCII rule, REST-over-GraphQL rules, and the mandatory DONE message protocol -- without it, the recurrence patterns documented in #954 re-fire on every fresh dispatch.
97
+ - ! The sub-agent dispatch envelope MUST include `templates/agent-prompt-preamble.md` verbatim (or by reference) per AGENTS.md `## Multi-agent orchestration discipline (#954)`. The preamble carries the AGENTS.md read mandate, the #810 xBRIEF gate walkthrough, the PowerShell 5.1 non-ASCII rule, REST-over-GraphQL rules, and the mandatory DONE message protocol -- without it, the recurrence patterns documented in #954 re-fire on every fresh dispatch.
98
98
 
99
99
  Present designs sequentially, then compare in prose. Give your own recommendation — which is strongest and why. If elements combine well, propose a hybrid. Be opinionated.
100
100
 
@@ -107,9 +107,9 @@ Present designs sequentially, then compare in prose. Give your own recommendatio
107
107
  - ! Create a refactor RFC immediately using `gh issue create` with the template below
108
108
  - ~ Issue-label hygiene: before filing, inspect the target repo's existing labels with `gh label list` or the labels API; choose one or more suitable existing labels when practical, or explicitly note that no label was applied. This is a recommendation, not a gate -- do not block issue creation solely because no label fits, and do not invent ad hoc labels outside the repo's existing label set.
109
109
  - ! After creating, print the issue URL
110
- - ! When the RFC is filed as an umbrella with companion child issues (e.g. an interface-extraction RFC plus one child per migrating caller), record the cohort in `vbrief/.eval/slices.jsonl` via `scripts/slice_record.py::write_slice(...)` with `actor="skill:gh-arch"` -- this is the durable production-side record consumed by `task triage:audit --orphans` (#1132 / D13). Same usage pattern as `skills/deft-directive-gh-slice/SKILL.md` Step 6; idempotent on retry. Skip when the RFC is a single-issue "file and forget" with no child cohort.
110
+ - ! When the RFC is filed as an umbrella with companion child issues (e.g. an interface-extraction RFC plus one child per migrating caller), record the cohort in `xbrief/.eval/slices.jsonl` via `scripts/slice_record.py::write_slice(...)` with `actor="skill:gh-arch"` -- this is the durable production-side record consumed by `task triage:audit --orphans` (#1132 / D13). Same usage pattern as `skills/deft-directive-gh-slice/SKILL.md` Step 6; idempotent on retry. Skip when the RFC is a single-issue "file and forget" with no child cohort.
111
111
  - ! Confirm skill exit: "deft-directive-gh-arch complete — RFC filed at <url>."
112
- - ~ Suggest next steps: run `deft-directive-refinement` to slot the RFC into the vBRIEF lifecycle, or assign the issue for swarm pickup.
112
+ - ~ Suggest next steps: run `deft-directive-refinement` to slot the RFC into the xBRIEF lifecycle, or assign the issue for swarm pickup.
113
113
 
114
114
  **Issue template:**
115
115
 
@@ -138,9 +138,9 @@ After all issues are created, print a summary table: issue number, title, type,
138
138
 
139
139
  - ! When the source plan was sliced into an umbrella + child issues, file the umbrella first, then file its `## Current shape (as of pass-N)` comment per `## Umbrella current-shape convention` in `AGENTS.md` (#1152) so subsequent design passes have a stable edit-in-place surface to update.
140
140
 
141
- ### Step 6: Record the cohort in `vbrief/.eval/slices.jsonl` (#1132 / D13)
141
+ ### Step 6: Record the cohort in `xbrief/.eval/slices.jsonl` (#1132 / D13)
142
142
 
143
- At slice-completion (after the umbrella + every child issue is filed) call the framework helper to persist a durable cohort record. The record is sibling to the gitignored `candidates.jsonl` but is **tracked in git** (per `vbrief/.eval/README.md`) so a fresh contributor on pass-N can see prior cohort outputs without rebuilding state from closed issues.
143
+ At slice-completion (after the umbrella + every child issue is filed) call the framework helper to persist a durable cohort record. The record is sibling to the gitignored `candidates.jsonl` but is **tracked in git** (per `xbrief/.eval/README.md`) so a fresh contributor on pass-N can see prior cohort outputs without rebuilding state from closed issues.
144
144
 
145
145
  ```python path=null start=null
146
146
  from pathlib import Path
@@ -4,7 +4,7 @@ description: >-
4
4
  Deterministic structured Q&A interview loop. Use when any skill needs to
5
5
  gather structured input from the user through a series of focused questions
6
6
  with numbered options, stated defaults, and a confirmation gate before
7
- artifact generation. Interview output targets vBRIEF narratives — not
7
+ artifact generation. Interview output targets xBRIEF narratives — not
8
8
  PRD.md.
9
9
  ---
10
10
  <!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
@@ -196,7 +196,7 @@ The answers map format:
196
196
 
197
197
  ## Output Targets
198
198
 
199
- Interview output writes to `specification.vbrief.json` `plan.narratives` — the vBRIEF draft is the sole authoritative output. PRD.md is never generated. All vBRIEFs target the canonical v0.6 schema (`vbrief/schemas/vbrief-core.schema.json`, strict `const: "0.6"`); see [`../../conventions/references.md`](../../conventions/references.md).
199
+ Interview output writes to `specification.xbrief.json` `plan.narratives` — the xBRIEF draft is the sole authoritative output. PRD.md is never generated. All xBRIEFs target the canonical v0.6 schema (`xbrief/schemas/xbrief-core.schema.json`, strict `const: "0.6"`); see [`../../conventions/references.md`](../../conventions/references.md).
200
200
 
201
201
  When the interview captures origin provenance (e.g. the user links to a GitHub issue or Jira ticket), include a `references` entry in the canonical form documented in [`../../conventions/references.md`](../../conventions/references.md):
202
202
 
@@ -204,7 +204,7 @@ When the interview captures origin provenance (e.g. the user links to a GitHub i
204
204
  "references": [
205
205
  {
206
206
  "uri": "https://github.com/{owner}/{repo}/issues/{N}",
207
- "type": "x-vbrief/github-issue",
207
+ "type": "x-xbrief/github-issue",
208
208
  "title": "Issue #{N}: {issue title}"
209
209
  }
210
210
  ]
@@ -212,7 +212,7 @@ When the interview captures origin provenance (e.g. the user links to a GitHub i
212
212
 
213
213
  ### Full Path Output
214
214
 
215
- ! On the Full path, the interview populates `specification.vbrief.json` `plan.narratives` with `vBRIEFInfo.version: "0.6"`, `status: draft`, and rich keys:
215
+ ! On the Full path, the interview populates `specification.xbrief.json` `plan.narratives` with `xBRIEFInfo.version: "0.6"`, `status: draft`, and rich keys:
216
216
 
217
217
  - `ProblemStatement`: What problem this project solves
218
218
  - `Goals`: High-level project goals
@@ -224,23 +224,23 @@ When the interview captures origin provenance (e.g. the user links to a GitHub i
224
224
 
225
225
  ! All narrative values MUST be plain strings — never objects or arrays.
226
226
 
227
- ! The human approval gate reviews the vBRIEF draft narratives directly — reviewing the narratives IS the approval step. On approval, update `status` to `approved` and generate downstream scope vBRIEFs.
227
+ ! The human approval gate reviews the xBRIEF draft narratives directly — reviewing the narratives IS the approval step. On approval, update `status` to `approved` and generate downstream scope xBRIEFs.
228
228
 
229
229
  ### Light Path Output
230
230
 
231
- ! On the Light path, the interview populates `specification.vbrief.json` with `status: draft` and slim narratives:
231
+ ! On the Light path, the interview populates `specification.xbrief.json` with `status: draft` and slim narratives:
232
232
 
233
233
  - `Overview`: Brief project summary
234
234
  - `Architecture`: System design description
235
235
 
236
- ! On approval, update `status` to `approved`. Scope vBRIEFs are then created in `vbrief/proposed/` for each identified work item.
236
+ ! On approval, update `status` to `approved`. Scope xBRIEFs are then created in `xbrief/proposed/` for each identified work item.
237
237
 
238
238
  ### PRD.md (deprecated — never authoritative)
239
239
 
240
- PRD.md is not generated as part of the interview workflow on either path. The `specification.vbrief.json` vBRIEF draft is the sole source of truth.
240
+ PRD.md is not generated as part of the interview workflow on either path. The `specification.xbrief.json` xBRIEF draft is the sole source of truth.
241
241
 
242
242
  - ? If stakeholders require a traditional PRD document, run `task prd:render` to export a read-only `PRD.md` from `plan.narratives`
243
- - ! PRD.md is never authoritative — `specification.vbrief.json` is the source of truth
243
+ - ! PRD.md is never authoritative — `specification.xbrief.json` is the source of truth
244
244
  - ⊗ Generate an authoritative PRD.md during the interview process
245
245
  - ⊗ Treat PRD.md as a source of truth — it is a generated export artifact
246
246
 
@@ -375,13 +375,13 @@ Tatooine), branded characters (Mickey Mouse, Spider-Man), sports leagues
375
375
  2. ! Emit the plain-English risk summary from
376
376
  `scripts/ip_risk.py:plain_risk_summary(hits, intent)` into the
377
377
  interview output AND into an `IPRisk` narrative on the
378
- `specification.vbrief.json` draft. The summary opens with `not legal
378
+ `specification.xbrief.json` draft. The summary opens with `not legal
379
379
  advice`, names the detected categories, and (for commercial intent)
380
380
  states explicitly that lawyer consultation is **not optional output**
381
381
  from this interview.
382
382
  3. ! Inject the three protection scope items from
383
383
  `scripts/ip_risk.py:ip_risk_scope_items(intent)` into the spec
384
- vBRIEF's `plan.items` array (disclaimer stub `IP-1`, API-only-asset
384
+ xBRIEF's `plan.items` array (disclaimer stub `IP-1`, API-only-asset
385
385
  policy `IP-2`, hosting policy `IP-3`). The items flow naturally into
386
386
  the rendered SPECIFICATION.md via the existing
387
387
  `scripts/spec_render.py` pipeline -- no spec_render.py modification
@@ -513,7 +513,7 @@ for it.
513
513
  - ⊗ Skip the depth gate and generate artifacts with known ambiguity remaining
514
514
  - ⊗ Exit the interview without producing a structured answers map for the calling skill
515
515
  - ⊗ Combine interview questions with artifact generation in the same message
516
- - ⊗ Generate an authoritative PRD.md — interview output targets `specification.vbrief.json` narratives only
516
+ - ⊗ Generate an authoritative PRD.md — interview output targets `specification.xbrief.json` narratives only
517
517
  - ⊗ Treat PRD.md as a source of truth — it is a read-only export via `task prd:render`
518
518
  - ⊗ Auto-advance to the next question on number press without echoing the selection and waiting for confirmation
519
519
  - ⊗ Refuse backward navigation during the interview -- the user must be able to revisit previous answers
@@ -51,8 +51,8 @@ Each iteration proceeds through all phases in order. Do NOT skip phases or reord
51
51
  ! Re-read each changed file end-to-end (`git diff master --name-only` to get the list).
52
52
 
53
53
  - ! Read every changed file in full -- do not skim or skip sections
54
- - ! Compare each file against its scope vBRIEF acceptance criteria in `vbrief/active/`
55
- - ~ If changed files include `vbrief/PROJECT-DEFINITION.vbrief.json`, a configured `codebase-map` provider artifact, or `.planning/codebase/MAP.md`, read the MAP and canonical metadata together. The MAP is orientation; `plan.architecture.codeStructure` and provider artifacts remain authoritative.
54
+ - ! Compare each file against its scope xBRIEF acceptance criteria in `xbrief/active/`
55
+ - ~ If changed files include `xbrief/PROJECT-DEFINITION.xbrief.json`, a configured `codebase-map` provider artifact, or `.planning/codebase/MAP.md`, read the MAP and canonical metadata together. The MAP is orientation; `plan.architecture.codeStructure` and provider artifacts remain authoritative.
56
56
  - ! When adding a `!` or `⊗` rule that prohibits a specific command, pattern, or behavior, search the same file for any `~`, `≉`, or prose that recommends or permits the same command/pattern -- resolve all contradictions in the same commit before pushing
57
57
  - ! When strengthening a rule (e.g. upgrading `~` to `!`), grep for the term in the full file and verify no weaker-strength duplicate remains
58
58
  - ~ Note any inconsistencies, missing RFC2119 markers, stale cross-references, or incomplete sections
@@ -80,7 +80,7 @@ Each iteration proceeds through all phases in order. Do NOT skip phases or reord
80
80
 
81
81
  ### Phase 3b -- Auto-Render Exports
82
82
 
83
- ! If `vbrief/specification.vbrief.json` exists, refresh rendered exports before the diff check:
83
+ ! If `xbrief/specification.xbrief.json` exists, refresh rendered exports before the diff check:
84
84
 
85
85
  - ! Run `task prd:render` if `PRD.md` already exists in the project root
86
86
  - ! Run `task spec:render` if `SPECIFICATION.md` already exists and does not contain `<!-- deft:deprecated-redirect -->`
@@ -36,10 +36,10 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
36
36
 
37
37
  While probe completion criteria (below) are NOT met:
38
38
 
39
- - ⊗ Write or update any vBRIEF file (`vbrief/proposed/`, `vbrief/active/`, plan items, narratives)
40
- - ⊗ Update `vbrief/plan.vbrief.json` or register probe artifacts
39
+ - ⊗ Write or update any xBRIEF file (`xbrief/proposed/`, `xbrief/active/`, plan items, narratives)
40
+ - ⊗ Update `xbrief/plan.xbrief.json` or register probe artifacts
41
41
  - ⊗ Post GitHub completion comments, close issues, or open PRs on behalf of the probe session
42
- - ⊗ Produce probe output markdown files instead of the canonical vBRIEF contract
42
+ - ⊗ Produce probe output markdown files instead of the canonical xBRIEF contract
43
43
 
44
44
  ! Read existing context and interrogate only — artifacts land in the Output phase after completion.
45
45
 
@@ -93,21 +93,21 @@ Walk the decision tree depth-first. For each unresolved branch:
93
93
 
94
94
  ! Before writing output artifacts, follow the [Preparatory Guard](../../strategies/artifact-guards.md#preparatory-guard-light).
95
95
 
96
- `{scope}` is the project name from `PROJECT-DEFINITION.vbrief.json`, or the feature/component name if probing a sub-scope. Use the same value consistently throughout the session.
96
+ `{scope}` is the project name from `PROJECT-DEFINITION.xbrief.json`, or the feature/component name if probing a sub-scope. Use the same value consistently throughout the session.
97
97
 
98
- - ! Produce a `vbrief/proposed/{scope}-probe.vbrief.json` scope vBRIEF with three mandatory narratives:
98
+ - ! Produce a `xbrief/proposed/{scope}-probe.xbrief.json` scope xBRIEF with three mandatory narratives:
99
99
  - `LockedDecisions` — what was resolved and why
100
100
  - `SurfacedRisks` — concerns raised, even if not fully resolved
101
101
  - `DeferredDecisions` — explicitly acknowledged items with justification
102
102
  - ! Each entry includes: **question asked**, **answer given**, **status** (locked / deferred / risk-accepted)
103
- - ! Persist significant decisions as vBRIEF narratives on the relevant plan items
104
- - ⊗ Write probe output to a hand-authored markdown file — use vBRIEF narratives for machine-consumable downstream work
103
+ - ! Persist significant decisions as xBRIEF narratives on the relevant plan items
104
+ - ⊗ Write probe output to a hand-authored markdown file — use xBRIEF narratives for machine-consumable downstream work
105
105
 
106
106
  ## Chaining Gate
107
107
 
108
- After the probe is complete and `vbrief/proposed/{scope}-probe.vbrief.json` is written:
108
+ After the probe is complete and `xbrief/proposed/{scope}-probe.xbrief.json` is written:
109
109
 
110
- - ! Register artifacts in `./vbrief/plan.vbrief.json` (`completedStrategies`, `artifacts`)
110
+ - ! Register artifacts in `./xbrief/plan.xbrief.json` (`completedStrategies`, `artifacts`)
111
111
  - ! Return to [interview.md Chaining Gate](../../strategies/interview.md#chaining-gate) when invoked from the interview flow
112
112
  - ! Locked decisions, surfaced risks, and deferred decisions MUST flow into subsequent strategies and spec generation
113
113
  - ⊗ End the session after probe without returning to the chaining gate or the invoking strategy's next-step menu