@deftai/directive-content 0.65.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.
- package/.githooks/pre-commit +3 -1
- package/QUICK-START.md +8 -4
- package/Taskfile.yml +31 -14
- package/UPGRADING.md +19 -5
- package/commands.md +46 -41
- package/conventions/rule-ownership.json +1 -1
- package/docs/BROWNFIELD.md +37 -33
- package/docs/directive-lifecycle.md +2 -2
- package/docs/getting-started.md +8 -8
- package/package.json +1 -1
- package/packs/skills/skills-pack-0.1.json +28 -28
- package/skills/deft-directive-article-review/SKILL.md +4 -4
- package/skills/deft-directive-build/SKILL.md +37 -37
- package/skills/deft-directive-cost/SKILL.md +6 -6
- package/skills/deft-directive-debug/SKILL.md +4 -4
- package/skills/deft-directive-decompose/SKILL.md +15 -15
- package/skills/deft-directive-gh-arch/SKILL.md +3 -3
- package/skills/deft-directive-gh-slice/SKILL.md +2 -2
- package/skills/deft-directive-interview/SKILL.md +12 -12
- package/skills/deft-directive-pre-pr/SKILL.md +3 -3
- package/skills/deft-directive-probe/SKILL.md +9 -9
- package/skills/deft-directive-refinement/SKILL.md +65 -65
- package/skills/deft-directive-release/SKILL.md +3 -3
- package/skills/deft-directive-review-cycle/SKILL.md +4 -4
- package/skills/deft-directive-setup/SKILL.md +71 -71
- package/skills/deft-directive-swarm/SKILL.md +94 -94
- package/skills/deft-directive-sync/SKILL.md +55 -55
- package/skills/deft-directive-triage/SKILL.md +15 -15
- package/tasks/architecture.yml +3 -1
- package/tasks/cache.yml +20 -10
- package/tasks/capacity.yml +8 -4
- package/tasks/change.yml +8 -10
- package/tasks/changelog.yml +3 -1
- package/tasks/codebase.yml +20 -10
- package/tasks/commit.yml +4 -8
- package/tasks/engine.yml +16 -4
- package/tasks/install.yml +4 -8
- package/tasks/issue.yml +8 -10
- package/tasks/migrate.yml +24 -8
- package/tasks/packs.yml +32 -16
- package/tasks/policy.yml +24 -12
- package/tasks/pr.yml +16 -8
- package/tasks/prd.yml +9 -12
- package/tasks/project.yml +14 -14
- package/tasks/reconcile.yml +4 -8
- package/tasks/roadmap.yml +9 -5
- package/tasks/scm.yml +36 -18
- package/tasks/scope-undo.yml +3 -1
- package/tasks/scope.yml +40 -26
- package/tasks/session.yml +4 -2
- package/tasks/slice.yml +8 -10
- package/tasks/spec.yml +10 -12
- package/tasks/swarm.yml +20 -10
- package/tasks/triage-actions.yml +32 -16
- package/tasks/triage-bootstrap.yml +4 -2
- package/tasks/triage-bulk.yml +20 -10
- package/tasks/triage-classify.yml +4 -2
- package/tasks/triage-queue.yml +12 -6
- package/tasks/triage-reconcile.yml +4 -2
- package/tasks/triage-scope-drift.yml +4 -2
- package/tasks/triage-scope.yml +4 -2
- package/tasks/triage-smoketest.yml +4 -2
- package/tasks/triage-subscribe.yml +8 -4
- package/tasks/triage-summary.yml +4 -2
- package/tasks/triage-welcome.yml +4 -2
- package/tasks/ts.yml +3 -1
- package/tasks/umbrella.yml +1 -7
- package/tasks/vbrief.yml +25 -17
- package/tasks/verify.yml +102 -50
- package/templates/agent-prompt-preamble.md +16 -16
- package/templates/agents-entry.md +23 -19
- package/vbrief/conformance/extensions/valid/extension-at-root.vbrief.json +31 -0
- package/vbrief/conformance/extensions/valid/nested-extension-value.vbrief.json +19 -0
- 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/`, `
|
|
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
|
-
**
|
|
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 +
|
|
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,
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
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
|
|
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
|
|
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 `
|
|
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
|
|
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
|
|
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
|
|
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:
|
|
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. `
|
|
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
|
|
72
|
-
- `
|
|
73
|
-
- `
|
|
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.
|
|
84
|
-
- Non-date-prefixed
|
|
85
|
-
- Missing `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
|
|
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. `./
|
|
148
|
-
2. `./
|
|
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.
|
|
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
|
|
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.
|
|
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.
|
|
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
|
|
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
|
|
193
|
-
- ! Identify phases, dependencies, starting point from scope
|
|
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
|
|
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.
|
|
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
|
|
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
|
|
279
|
-
- ! Scope needs changes -> propose, get approval, update the scope
|
|
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
|
|
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
|
|
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.
|
|
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 `
|
|
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
|
-
- ! `
|
|
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
|
-
- ~ `
|
|
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
|
|
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 `
|
|
160
|
-
via a `references` entry of type `x-
|
|
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.
|
|
62
|
-
`docs/reference/forensic-research/templates/investigation.
|
|
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
|
|
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
|
|
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
|
|
5
|
-
story
|
|
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
|
|
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
|
|
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 `
|
|
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
|
|
38
|
-
- ! Treat the draft JSON as a temporary proposal artifact, not a
|
|
39
|
-
- ! Write draft proposals under `
|
|
40
|
-
- ! Derive `<parent-slug>` from the parent
|
|
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/**`, `
|
|
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 --
|
|
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 --
|
|
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
|
|
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 --
|
|
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
|
|
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
|
|
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 `
|
|
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
|
|
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 `
|
|
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 `
|
|
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
|
|
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.
|
|
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-
|
|
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.
|
|
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
|
|
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.
|
|
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
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
-
|
|
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.
|
|
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
|
|
55
|
-
- ~ If changed files include `
|
|
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 `
|
|
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
|
|
40
|
-
- ⊗ Update `
|
|
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
|
|
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.
|
|
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 `
|
|
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
|
|
104
|
-
- ⊗ Write probe output to a hand-authored markdown file — use
|
|
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 `
|
|
108
|
+
After the probe is complete and `xbrief/proposed/{scope}-probe.xbrief.json` is written:
|
|
109
109
|
|
|
110
|
-
- ! Register artifacts in `./
|
|
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
|