@deftai/directive-content 0.104.0 → 0.106.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/Taskfile.yml +12 -6
- package/UPGRADING.md +6 -2
- package/coding/coding.md +2 -2
- package/commands.md +42 -17
- package/contracts/agent-hook-readiness.md +3 -3
- package/contracts/closed-verb-authz.md +14 -2
- package/contracts/design-critique.md +100 -0
- package/docs/directive-lifecycle.md +12 -4
- package/docs/project-invariants.md +79 -0
- package/docs/scope-provenance.md +53 -8
- package/main.md +3 -1
- package/meta/ralph.md +1 -1
- package/package.json +1 -1
- package/packs/rules/rules-pack-0.1.json +3 -3
- package/packs/skills/skills-pack-0.1.json +31 -11
- package/packs/strategies/strategies-pack-0.1.json +13 -13
- package/scm/github.md +35 -2
- package/skills/deft-directive-build/SKILL.md +26 -1
- package/skills/deft-directive-design-critique/SKILL.md +46 -0
- package/skills/deft-directive-gh-slice/SKILL.md +2 -2
- package/skills/deft-directive-probe/SKILL.md +4 -2
- package/skills/deft-directive-refinement/SKILL.md +1 -1
- package/skills/deft-directive-release/SKILL.md +5 -3
- package/skills/deft-directive-review-cycle/SKILL.md +38 -12
- package/skills/deft-directive-setup/SKILL.md +2 -0
- package/skills/deft-directive-swarm/SKILL.md +22 -6
- package/skills/deft-directive-swarm/references/core-ops.md +3 -1
- package/skills/deft-directive-swarm/references/core-phase-0.md +1 -0
- package/skills/deft-directive-swarm/references/core-phase-3.md +1 -1
- package/skills/deft-directive-swarm/references/core-phase-4.md +27 -11
- package/skills/deft-directive-swarm/references/core-phase-5-6.md +4 -1
- package/skills/deft-directive-sync/SKILL.md +1 -1
- package/strategies/README.md +4 -4
- package/strategies/bdd.md +6 -6
- package/strategies/discuss.md +8 -8
- package/strategies/emit-hints.md +6 -6
- package/strategies/enterprise.md +18 -18
- package/strategies/interview.md +4 -4
- package/strategies/map.md +6 -6
- package/strategies/probe.md +22 -18
- package/strategies/rapid.md +16 -16
- package/strategies/research.md +6 -6
- package/strategies/roadmap.md +1 -1
- package/strategies/speckit.md +52 -52
- package/strategies/v0-20-contract.md +21 -21
- package/strategies/yolo.md +12 -12
- package/tasks/engine.yml +2 -0
- package/tasks/occupancy.yml +17 -0
- package/tasks/policy.yml +10 -0
- package/tasks/scm.yml +13 -7
- package/tasks/scope.yml +2 -2
- package/tasks/vbrief.yml +3 -2
- package/tasks/verify.yml +34 -4
- package/tasks/xbrief.yml +43 -0
- package/templates/agent-prompt-preamble.md +16 -7
- package/templates/agents-entry.md +8 -3
- package/templates/design-critique-brief.md +41 -0
- package/vbrief/schemas/vbrief-core.schema.json +72 -0
|
@@ -69,29 +69,42 @@ tools: explore=0 commit=3 verify=0 coordinate=0 unknown=1 | anomalies: commit-wi
|
|
|
69
69
|
| Stop | Default |
|
|
70
70
|
|------|---------|
|
|
71
71
|
| max iterations | **3** repair actions for the same leaf/PR failure class (resume prompt, takeover complete-remaining-steps, re-dispatch replacement, review re-trigger) |
|
|
72
|
-
| no-progress | same error / same
|
|
72
|
+
| no-progress | same error / same idle stage **3+** times with no material worktree or review change. Same-fingerprint Greptile residual: [`deft-directive-review-cycle/SKILL.md`](../../deft-directive-review-cycle/SKILL.md) Dual stop — **Same-fingerprint stop** |
|
|
73
73
|
| budget | honor `pr:watch` / poll max-wait and Greptile service-error single-retry+escalate caps; do not nest an unbounded poll outside them |
|
|
74
74
|
|
|
75
75
|
! When the failure stop fires: **halt** automatic repair/re-dispatch; emit an **operator-visible halt report** (what was tried, current stage, missing evidence, human decision needed). Prefer `BLOCKED:` over thin `DONE` when the unit cannot reach merge-ready inside the envelope.
|
|
76
76
|
|
|
77
|
-
! **Halt-report resume line (MUST, #3273 /
|
|
77
|
+
! **Halt-report resume line (MUST, #3273 / #3448):** Terminal dual-stop / hard-stop / conf-residual halt reports MUST end with a copy-pasteable operator resume affordance so agents discover the follow-up path without prior chat memory:
|
|
78
78
|
|
|
79
79
|
```
|
|
80
|
-
RESUME: residual=<class> conf=<n/5|n/a> PR=<url>
|
|
81
|
-
Operator may re-authorize **one residual pass** with: pursue residual | follow-up hard-stop | same as conf-hold | continue dual-stopped PR
|
|
80
|
+
RESUME: residual=<class> leftover=<A|B|C> conf=<n/5|n/a> floor=<resolved min|n/a> standing=<yes|one-shot> PR=<url>
|
|
81
|
+
Operator may re-authorize **one residual pass** (one-shot) with: pursue residual | follow-up hard-stop | same as conf-hold | continue dual-stopped PR
|
|
82
|
+
Standing order (open cohort/plan units, class A until resolved floor or same-fingerprint loop): until floor or loop | until greptile meets policy | pursue residuals until told otherwise
|
|
82
83
|
Skill: deft-directive-swarm § Operator follow-up after dual-stop / hard stop (#3273) · deft-directive-review-cycle same section
|
|
83
84
|
```
|
|
84
85
|
|
|
85
|
-
Residual class examples: `review_cycle_cap` / `greptile_p0_p1` / `conf_floor` / `no_progress` / `ci_weather` / `thin_done`.
|
|
86
|
+
Residual class examples: `review_cycle_cap` / `greptile_p0_p1` / `conf_floor` / `no_progress` / `ci_weather` / `thin_done`. Leftover class: **class A** already-touched in-AC residual · **class B** new subsystem / AC fight · **class C** score-only.
|
|
86
87
|
|
|
87
88
|
### Operator follow-up after dual-stop / hard stop (#3273)
|
|
88
89
|
|
|
89
|
-
Operator-initiated resume after dual-stop, hard-stop, or conf-floor residual — **not** automatic re-thrash. Primary discovery is the halt-report resume line above; this section holds the steps. Portable for consumer deposit and maintainer tree (`task` / `deft` dual-invoke; no framework-monorepo-only path).
|
|
90
|
+
Operator-initiated resume after dual-stop, hard-stop, or conf-floor residual — **not** automatic re-thrash. Primary discovery is the halt-report resume line above; this section holds the steps. Portable for consumer deposit and maintainer tree (`task` / `deft` dual-invoke; no framework-monorepo-only path). Continue-until target is the **resolved `#3095` floor** (`plan.policy.review.minGreptileConfidence`: typed project policy > framework dogfood **5** > consumer default **4**; inspect `task policy:show --field=minGreptileConfidence` / `deft policy:show --field=minGreptileConfidence`). ⊗ Hard-code 5/5. ⊗ Lower project policy to clear one PR.
|
|
90
91
|
|
|
91
|
-
**
|
|
92
|
+
**Leftover classes (A/B/C, #3448):**
|
|
92
93
|
|
|
93
|
-
|
|
94
|
-
|
|
94
|
+
| Class | What it is | Auto-continue? |
|
|
95
|
+
|-------|------------|----------------|
|
|
96
|
+
| **class A** — named leftover on already-touched files | Wrong remediation, dropped field, fixture, same-module hole on files this PR already owns | **in-AC residual.** Continue until the resolved floor or same-fingerprint loop |
|
|
97
|
+
| **class B** — new subsystem / AC fight | New ledger, protocol, cross-cutting contract, or work that expands story meaning | Park or file follow-up. Do not expand mid-babysit |
|
|
98
|
+
| **class C** — score-only, no concrete finding | Confidence below the resolved floor, 0 P0/P1, no named leftover | Document / same-as-conf-hold / operator floor this-PR-only. Not unbounded redesign |
|
|
99
|
+
|
|
100
|
+
! **Already-touched leftover is class A (#2881 / #3448):** a leftover on files **already in the PR** is class A unless it needs a new ledger, protocol, or story.
|
|
101
|
+
|
|
102
|
+
**One-shot vs standing (#3448):**
|
|
103
|
+
- **One-shot** triggers: pursue residual · follow-up hard-stop · same as conf-hold · continue dual-stopped PR · re-babysit residual — **one** pass on the unit that just halted, then re-stop. Do not silently widen.
|
|
104
|
+
- **Standing** triggers: **until floor or loop** · **until greptile meets policy** · **pursue residuals until told otherwise** — class A leftovers on **every open unit in the active cohort / ordered plan** keep moving until the resolved floor or the **Same-fingerprint stop** in [`deft-directive-review-cycle/SKILL.md`](../../deft-directive-review-cycle/SKILL.md) Dual stop. Class B/C stay parked unless the operator names them.
|
|
105
|
+
|
|
106
|
+
**One residual pass (then re-stop, or one standing batch):**
|
|
107
|
+
1. Ground-truth: dual-invoke `pr:merge-ready` / `pr:watch --one-shot` on the PR (CLI `deft` first, then `task deft:` — see review-cycle #2893). Classify leftover A/B/C.
|
|
95
108
|
2. If a delivery attempt is still active, cancel then begin with the **same unit ids** (exit 0 required before residual spawn) (#3228 / #3143):
|
|
96
109
|
```
|
|
97
110
|
task swarm:pre-dispatch -- --scope-id <story-or-issue-or-xbrief-id> --target-id <worktree-path-or-branch> --action cancel
|
|
@@ -99,14 +112,17 @@ Operator-initiated resume after dual-stop, hard-stop, or conf-floor residual —
|
|
|
99
112
|
```
|
|
100
113
|
3. Spawn **one** active residual worker or review-cycle owner (not sleep-only re-poll as the only work). Monitor MUST NOT self-implement product fixes after merge-ready leaf handback (#2843).
|
|
101
114
|
4. If the operator authorized a conf floor for **this PR only** (e.g. ≥4/5): post a PR audit comment naming the floor, HEAD SHA, and who authorized it. That comment is the **human-merge / documented-override trail** — it does **not** rewrite `plan.policy.review.minGreptileConfidence` or make `pr:merge-ready` / `pr:watch` exit CLEAN below policy. Merge still requires policy CLEAN, bot-merge authority + override path, or human merge after the documented floor is met in the bot body. ⊗ Silent policy edit of `minGreptileConfidence` for one residual.
|
|
102
|
-
5. Wait re-review; merge when policy floor + gates met (or human-merge after documented PR-local floor). Run `scope:complete` + lifecycle land when in scope (#3264 / finalize).
|
|
115
|
+
5. Wait re-review; merge when policy floor + gates met (or human-merge after documented PR-local floor). Run `scope:complete` + lifecycle land when in scope (#3264 / finalize). Halt reports MUST include leftover class + resolved floor + standing vs one-shot.
|
|
116
|
+
|
|
117
|
+
! **Same-fingerprint stop:** [`deft-directive-review-cycle/SKILL.md`](../../deft-directive-review-cycle/SKILL.md) Dual stop — review fix loops (#2442) (normative). ⊗ Spawn another continuation leaf after a same-fingerprint `BLOCKED` handoff. `#2442` batch cap (max 3 repair actions) still applies.
|
|
103
118
|
|
|
104
|
-
! Dual-stop re-entry: after the residual pass (+ re-review wait), if still blocked, halt again with a fresh resume line. Another pass requires **new** operator consent.
|
|
119
|
+
! Dual-stop re-entry: after the residual pass (+ re-review wait), if still blocked, halt again with a fresh resume line. Another **one-shot** pass requires **new** operator consent. A **standing** order MAY continue class A with a **new** fingerprint under the `#2442` cap.
|
|
105
120
|
|
|
106
121
|
⊗ Unlimited auto-retry after dual-stop without new operator consent (#3273 / #2442).
|
|
107
122
|
⊗ Sleep-only multi-hour re-poll as the sole residual work.
|
|
108
123
|
⊗ Parent/monitor self-implement after merge-ready leaf handback (#2843).
|
|
109
124
|
⊗ Lower project-wide `minGreptileConfidence` for one residual.
|
|
125
|
+
⊗ Treat one-shot `pursue residual` as a standing order, or park a class A leftover on already-touched files because the score is below 5.
|
|
110
126
|
|
|
111
127
|
! Composes with minimal-subgraph repair (#2439): repairs stay minimal **and** dual-stop bounded. Mechanical delivery/acceptance circuit breaker: **#3143** `packages/core/src/delivery-attempt/` (`evaluatePreDispatch`). Docs: `docs/delivery-attempt.md`.
|
|
112
128
|
|
|
@@ -232,7 +232,7 @@ This is defense in depth -- run it even when the pre-merge inspection above pass
|
|
|
232
232
|
|
|
233
233
|
### Step 1.5: Cohort Completion Sweep (#1487)
|
|
234
234
|
|
|
235
|
-
! **REQUIRED.** Once the cohort's PRs are merged (Step 1 complete), the monitor MUST run the deterministic cohort completion sweep so the finished swarm leaves NO stranded xBRIEFs. This step closes the gap where a completed cohort left its story xBRIEFs in `xbrief/active/` and their decompose-created epic parents in `xbrief/pending/` -- nothing in the swarm flow swept them to `completed/` (observed in the 2026-06-03 swarm: after the cohort's PRs merged, the child story xBRIEFs stayed in `active/` and their epic parents stayed in `pending/`).
|
|
235
|
+
! **REQUIRED.** Once the cohort's PRs are merged (Step 1 complete), the monitor MUST run the deterministic cohort completion sweep so the finished swarm leaves NO stranded xBRIEFs. `task swarm:complete-cohort` / `task swarm:finalize-cohort` release the swarm occupancy lease on a successful non-dry-run sweep (#3433). This step closes the gap where a completed cohort left its story xBRIEFs in `xbrief/active/` and their decompose-created epic parents in `xbrief/pending/` -- nothing in the swarm flow swept them to `completed/` (observed in the 2026-06-03 swarm: after the cohort's PRs merged, the child story xBRIEFs stayed in `active/` and their epic parents stayed in `pending/`).
|
|
236
236
|
|
|
237
237
|
! **Pre-sweep merge re-poll for human-merge / `stop-at: pr-open` (#3153):** Before invoking `task swarm:complete-cohort` or `task swarm:finalize-cohort`, re-read each cohort PR's merge state via REST. If any PR marked `awaiting-human-merge` is still open, **halt** the sweep, keep durable ownership, and continue the observe path (Phase 5 human-merge section) until merge or operator cancel. ⊗ Sweep on Greptile CLEAN alone while a human-merge PR is still open.
|
|
238
238
|
|
|
@@ -265,9 +265,12 @@ task swarm:finalize-cohort -- --stories <issue-or-path>... --repo <owner/repo>
|
|
|
265
265
|
|
|
266
266
|
The finalize surface runs the same `completeCohort(...)` engine as `task swarm:complete-cohort`, fast-forwards the local base branch, creates a `swarm/finalize/<label>` feature branch (branch policy #747 safe), commits the `xbrief/` lifecycle moves, and auto-opens the sweep PR. Pass `--no-commit` to sweep only (manual Step 2b), or `--no-open-pr` to commit locally without opening the PR. Gate on exit 0 plus green `task xbrief:validate` before declaring the swarm closed.
|
|
267
267
|
|
|
268
|
+
! **Drive-to last-leaf close (#3476):** After the last `drive-to: merge-ready` leaf of a cohort announces, parent `done` without same-turn `task swarm:finalize-cohort` (or a land PR already proving `task verify:completed-tracked` green on `origin/<deliveryBranch>`) is a **failed close**. Narrative-only `done` under #2934 is not enough when completed xBRIEFs exist only as untracked worktree residue. `scope:complete` stays filesystem-only -- do not teach every leaf to commit on master. Keep `verify:completed-tracked` off `task check`.
|
|
269
|
+
|
|
268
270
|
! **Manual fallback (#1487):** `task swarm:complete-cohort` remains the idempotent manual primitive when finalize automation is unavailable or you need a dry-run preview of transitions only. The headless path above replaces the historical requirement to hand-author a separate `chore(xbrief)` sweep PR every cycle.
|
|
269
271
|
|
|
270
272
|
⊗ Declare a swarm closed while any cohort story xBRIEF remains in `xbrief/active/` or any fully-childless decompose-created epic parent remains in `xbrief/pending/` -- run `task swarm:complete-cohort` and confirm `task xbrief:validate` is green first (#1487).
|
|
273
|
+
⊗ After the last `drive-to` leaf, emit parent `done` without finalize-cohort / completed-tracked green on the delivery tip -- that is a failed close (#3476).
|
|
271
274
|
|
|
272
275
|
### Step 2: Close Issues and Update Origins
|
|
273
276
|
|
|
@@ -238,7 +238,7 @@ directive doctor
|
|
|
238
238
|
- Top-level `xBRIEFInfo` envelope with `version` field present
|
|
239
239
|
- `plan` object with `title`, `status`, and `items` fields present
|
|
240
240
|
- `plan.status` values from valid enum: draft, proposed, approved, pending, running, completed, blocked, cancelled
|
|
241
|
-
3. ~ Use `task xbrief:validate`
|
|
241
|
+
3. ~ Use `task xbrief:validate` for deeper validation
|
|
242
242
|
4. ! Report any validation failures with file name and specific violation
|
|
243
243
|
|
|
244
244
|
⊗ Overwrite or modify project-level `./xbrief/*.xbrief.json` files -- those are project data, not framework files. Report issues and let the user decide how to fix them.
|
package/strategies/README.md
CHANGED
|
@@ -36,7 +36,7 @@ Every strategy has a **Type** that determines its behavior in the
|
|
|
36
36
|
via `/deft:run:<name>` — when invoked outside an interview context, they present their
|
|
37
37
|
own next-step options instead of returning to the chaining gate. See each strategy file
|
|
38
38
|
for standalone support.
|
|
39
|
-
- **`spec-generating`** — Produces v0.20-conformant output per [v0-20-contract.md](./v0-20-contract.md) (lifecycle folders + PROJECT-DEFINITION.
|
|
39
|
+
- **`spec-generating`** — Produces v0.20-conformant output per [v0-20-contract.md](./v0-20-contract.md) (lifecycle folders + PROJECT-DEFINITION.xbrief.json + date-prefixed proposed/ scope vBRIEFs only; SPECIFICATION.md/PROJECT.md as deprecation stubs or omitted). Selecting one at the chaining gate switches the pipeline to that strategy’s spec flow.
|
|
40
40
|
|
|
41
41
|
Custom strategies MUST declare their type in this table. If the `Type` column is missing,
|
|
42
42
|
the chaining gate cannot include the strategy.
|
|
@@ -45,9 +45,9 @@ the chaining gate cannot include the strategy.
|
|
|
45
45
|
|
|
46
46
|
All spec-generating strategies (interview, yolo, speckit, rapid, enterprise) MUST produce output conforming to [v0-20-contract.md](./v0-20-contract.md):
|
|
47
47
|
|
|
48
|
-
- Five
|
|
49
|
-
-
|
|
50
|
-
- Scope vBRIEFs ONLY as date-prefixed in
|
|
48
|
+
- Five xbrief/ lifecycle folders (proposed/ pending/ active/ completed/ cancelled/)
|
|
49
|
+
- xbrief/PROJECT-DEFINITION.xbrief.json (full)
|
|
50
|
+
- Scope vBRIEFs ONLY as date-prefixed in xbrief/proposed/YYYY-MM-DD-*.xbrief.json
|
|
51
51
|
- Never dual-write legacy vbrief/specification.vbrief.json
|
|
52
52
|
- SPECIFICATION.md/PROJECT.md only as deprecation-redirect stubs (banner + sentinel) or omitted
|
|
53
53
|
|
package/strategies/bdd.md
CHANGED
|
@@ -57,7 +57,7 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
|
|
|
57
57
|
|
|
58
58
|
! Before writing output artifacts, follow the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light).
|
|
59
59
|
|
|
60
|
-
! Resolve all ambiguities surfaced by Step 3. Record decisions in `
|
|
60
|
+
! Resolve all ambiguities surfaced by Step 3. Record decisions in `xbrief/proposed/{feature}-bdd.xbrief.json`.
|
|
61
61
|
|
|
62
62
|
- ! Write a scope vBRIEF with two narratives:
|
|
63
63
|
- `Scenarios` -- Given/When/Then scenario descriptions from Step 1
|
|
@@ -67,32 +67,32 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
|
|
|
67
67
|
- ⊗ Leave ambiguities unresolved -- every question surfaced in Step 3 must have a locked answer
|
|
68
68
|
- ⊗ Write decisions to a hand-authored markdown file -- use vBRIEF narratives for token-efficient agent consumption
|
|
69
69
|
|
|
70
|
-
! After emitting the scope vBRIEF to `
|
|
70
|
+
! After emitting the scope vBRIEF to `xbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).
|
|
71
71
|
|
|
72
72
|
### Step 5: Generate Spec
|
|
73
73
|
|
|
74
74
|
! Derive SPECIFICATION.md tasks from the now-stable test scenarios and locked decisions.
|
|
75
75
|
|
|
76
76
|
- ! Each scenario maps to one or more spec tasks with traceability (`traces: scenario-N`)
|
|
77
|
-
- ! Locked decisions from `
|
|
77
|
+
- ! Locked decisions from `xbrief/proposed/{feature}-bdd.xbrief.json` `LockedDecisions` narrative flow into the spec as constraints
|
|
78
78
|
- ~ Use the Light or Full path from [strategies/interview.md](./interview.md) based on project size
|
|
79
79
|
|
|
80
80
|
### Step 6: Chain into Interview Sizing Gate
|
|
81
81
|
|
|
82
82
|
! Follow [strategies/interview.md](./interview.md) sizing gate for SPECIFICATION.md finalisation.
|
|
83
83
|
|
|
84
|
-
- ! On completion, register artifacts in `./
|
|
84
|
+
- ! On completion, register artifacts in `./xbrief/plan.xbrief.json`:
|
|
85
85
|
- Update `completedStrategies`: increment `runCount` for `"bdd"`, append artifact paths
|
|
86
86
|
- Append all new artifact paths to the flat `artifacts` array
|
|
87
87
|
- ! Return to [interview.md Chaining Gate](./interview.md#chaining-gate)
|
|
88
|
-
- ! The locked decisions from `
|
|
88
|
+
- ! The locked decisions from `xbrief/proposed/{feature}-bdd.xbrief.json` and the acceptance tests MUST flow into subsequent strategies and spec generation
|
|
89
89
|
|
|
90
90
|
---
|
|
91
91
|
|
|
92
92
|
## Output Artifacts
|
|
93
93
|
|
|
94
94
|
- Executable test files in the project's standard test directory -- derived from Given/When/Then scenarios
|
|
95
|
-
- `
|
|
95
|
+
- `xbrief/proposed/{feature}-bdd.xbrief.json` -- scope vBRIEF with `Scenarios` and `LockedDecisions` narratives
|
|
96
96
|
|
|
97
97
|
---
|
|
98
98
|
|
package/strategies/discuss.md
CHANGED
|
@@ -55,7 +55,7 @@ Use the Feynman technique: if the user (or you) can't explain the feature in sim
|
|
|
55
55
|
|
|
56
56
|
- ! If the user suggests a capability belonging to a different feature, capture it as **deferred**
|
|
57
57
|
- ~ Redirect: "That sounds like a new capability — I'll note it. For now, let's focus on [current scope]."
|
|
58
|
-
- ~ Record deferred ideas in `./
|
|
58
|
+
- ~ Record deferred ideas in `./xbrief/plan.xbrief.json` with `deferred` status and a narrative explaining why
|
|
59
59
|
|
|
60
60
|
## Domain-Sensitive Questions
|
|
61
61
|
|
|
@@ -70,14 +70,14 @@ Adapt question focus to what's being built:
|
|
|
70
70
|
|
|
71
71
|
! Before writing output artifacts, follow the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light).
|
|
72
72
|
|
|
73
|
-
- ! Produce a `
|
|
73
|
+
- ! Produce a `xbrief/proposed/{scope}-context.xbrief.json` scope vBRIEF with a `LockedDecisions` narrative
|
|
74
74
|
- ! Each decision includes: **what** was decided, **why**, and **alternatives considered**
|
|
75
75
|
- ! When the lock is an intentional under-build (weaker Now + decided end-product Later), the decision MUST also include dual-path graduation fields: `now`, `later`, `graduationRef`, `trigger`, and `status` (`open` | `shipped` | `cancelled`) — see [Graduation (Now+Later)](#graduation-nowlater-dual-path-locks-2899)
|
|
76
76
|
- ! This vBRIEF is injected into all downstream work: planning, execution, verification
|
|
77
77
|
- ! Persist decisions as vBRIEF narratives on the relevant plan items
|
|
78
78
|
- ⊗ Write decisions to a hand-authored markdown context file -- use vBRIEF narratives for token-efficient agent consumption
|
|
79
79
|
|
|
80
|
-
! After emitting the scope vBRIEF to `
|
|
80
|
+
! After emitting the scope vBRIEF to `xbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).
|
|
81
81
|
|
|
82
82
|
## Decision Locking
|
|
83
83
|
|
|
@@ -128,18 +128,18 @@ Glossary naming for this term is owned by sibling work (#2907). Strategy prose h
|
|
|
128
128
|
|
|
129
129
|
## Then: Chaining Gate
|
|
130
130
|
|
|
131
|
-
After alignment is complete and decisions are locked in `
|
|
131
|
+
After alignment is complete and decisions are locked in `xbrief/proposed/{scope}-context.xbrief.json`,
|
|
132
132
|
return to the [chaining gate](./interview.md#chaining-gate) so the user can
|
|
133
133
|
run additional preparatory strategies or proceed to spec generation.
|
|
134
134
|
|
|
135
|
-
- ! On completion, register artifacts in `./
|
|
135
|
+
- ! On completion, register artifacts in `./xbrief/plan.xbrief.json`:
|
|
136
136
|
- Update `completedStrategies`: increment `runCount` for `"discuss"`,
|
|
137
|
-
append artifact path (`
|
|
137
|
+
append artifact path (`xbrief/proposed/{scope}-context.xbrief.json`)
|
|
138
138
|
- Append the path to the flat `artifacts` array
|
|
139
139
|
- ! Return to [interview.md Chaining Gate](./interview.md#chaining-gate)
|
|
140
140
|
(the discuss phase replaces the interview's question-gathering -- decisions are
|
|
141
141
|
already made, so the interview will be short or skipped entirely)
|
|
142
|
-
- ! The locked decisions from `
|
|
142
|
+
- ! The locked decisions from `xbrief/proposed/{scope}-context.xbrief.json` MUST flow into subsequent
|
|
143
143
|
strategies and spec generation
|
|
144
144
|
- ⊗ End the session after discuss without returning to the chaining gate
|
|
145
145
|
or the invoking strategy's next-step menu
|
|
@@ -154,7 +154,7 @@ run additional preparatory strategies or proceed to spec generation.
|
|
|
154
154
|
|
|
155
155
|
1. **Open** -- Start with the user's goal statement; restate it in your own words
|
|
156
156
|
2. **Explore** -- Follow energy, challenge vagueness, ask domain-sensitive questions
|
|
157
|
-
3. **Lock** -- Record each decision in `
|
|
157
|
+
3. **Lock** -- Record each decision in `xbrief/proposed/{scope}-context.xbrief.json` `LockedDecisions` narrative with what/why/alternatives (and dual-path graduation fields when the lock is an under-build; #2899)
|
|
158
158
|
4. **Verify** -- Explain the full picture back to the user (Feynman check)
|
|
159
159
|
5. **Chain** -- Return to [interview.md Chaining Gate](./interview.md#chaining-gate), or -- if invoked from a standalone strategy (e.g. map's standalone next-step menu) -- return to the invoking strategy's menu per the [standalone-context rule](#then-chaining-gate) above
|
|
160
160
|
|
package/strategies/emit-hints.md
CHANGED
|
@@ -16,7 +16,7 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
|
|
|
16
16
|
|
|
17
17
|
## When to Use
|
|
18
18
|
|
|
19
|
-
This file is not a standalone strategy — it is a shared hint referenced by other strategies. It activates at the emission step, right after a strategy writes scope vBRIEFs to `
|
|
19
|
+
This file is not a standalone strategy — it is a shared hint referenced by other strategies. It activates at the emission step, right after a strategy writes scope vBRIEFs to `xbrief/proposed/` (or `xbrief/pending/`).
|
|
20
20
|
|
|
21
21
|
- ! Referenced by spec-generating strategies: [speckit](./speckit.md) (Phase 4 and Phase 4.5), [enterprise](./enterprise.md), [rapid](./rapid.md), [interview](./interview.md), [yolo](./yolo.md)
|
|
22
22
|
- ! Referenced by preparatory strategies: [bdd](./bdd.md), [discuss](./discuss.md), [research](./research.md), [map](./map.md), [probe](./probe.md)
|
|
@@ -38,12 +38,12 @@ This file is not a standalone strategy — it is a shared hint referenced by oth
|
|
|
38
38
|
<strategy> emitted N scope vBRIEF(s).
|
|
39
39
|
|
|
40
40
|
Optional: track these in GitHub issues.
|
|
41
|
-
- task deft:issue:emit --umbrella --
|
|
42
|
-
- task deft:issue:emit --per-vbrief --
|
|
41
|
+
- task deft:issue:emit --umbrella -- xbrief/<path>/<glob> (one roadmap issue, all vBRIEFs reference it)
|
|
42
|
+
- task deft:issue:emit --per-vbrief -- xbrief/<path>/<glob> (one issue per vBRIEF)
|
|
43
43
|
- Default behavior (vBRIEF-only) requires no further action.
|
|
44
44
|
```
|
|
45
45
|
|
|
46
|
-
~ Replace `<path>/<glob>` with the actual emission target (e.g. `
|
|
46
|
+
~ Replace `<path>/<glob>` with the actual emission target (e.g. `xbrief/proposed/2026-06-15-*.xbrief.json`).
|
|
47
47
|
|
|
48
48
|
Note: `task deft:issue:emit` is the consumer-installed surface (this is what strategies render to). The maintainer-side, in-repo form is `task issue:emit` — the same command without the `deft:` prefix.
|
|
49
49
|
|
|
@@ -52,8 +52,8 @@ Note: `task deft:issue:emit` is the consumer-installed surface (this is what str
|
|
|
52
52
|
## The Three Patterns
|
|
53
53
|
|
|
54
54
|
1. **None (default)** — emit vBRIEF(s) only; file no GitHub issue. Requires no further user action. This is the framework default and is unchanged by this hint.
|
|
55
|
-
2. **Umbrella** — `task deft:issue:emit --umbrella --
|
|
56
|
-
3. **Per-vBRIEF** — `task deft:issue:emit --per-vbrief --
|
|
55
|
+
2. **Umbrella** — `task deft:issue:emit --umbrella -- xbrief/<path>/<glob>` files ONE roadmap issue, and every matched vBRIEF references it.
|
|
56
|
+
3. **Per-vBRIEF** — `task deft:issue:emit --per-vbrief -- xbrief/<path>/<glob>` files one issue per matched vBRIEF.
|
|
57
57
|
|
|
58
58
|
- ! Name all three patterns (none / `--umbrella` / `--per-vbrief`) when surfacing the hint — do not hide the umbrella / per-vBRIEF escape hatches.
|
|
59
59
|
- ⊗ File a GitHub issue automatically as part of emission. No strategy files an issue unless the user explicitly invokes `task deft:issue:emit`.
|
package/strategies/enterprise.md
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
|
|
9
9
|
Compliance-heavy workflow -- v0.20 date-prefixed story/phase vBRIEF + PROJECT-DEFINITION with explicit approval gates at each stage.
|
|
10
10
|
|
|
11
|
-
**v0.20 note (s5-migrate-speckit-rapid-enterprise / #1166):** Enterprise now emits only the canonical v0.20 shape (date-prefixed story/phase vBRIEFs in proposed/, full PROJECT-DEFINITION.
|
|
11
|
+
**v0.20 note (s5-migrate-speckit-rapid-enterprise / #1166):** Enterprise now emits only the canonical v0.20 shape (date-prefixed story/phase vBRIEFs in proposed/, full PROJECT-DEFINITION.xbrief.json via task project:render, seeded lifecycle folders, no legacy specification.vbrief.json). PRD.md and SPECIFICATION.md (if any) are deprecation-redirect derivatives only. See the dedicated ## v0.20 Output Shape section and the canonical contract `strategies/v0-20-contract.md` (s1-contract of #1166).
|
|
12
12
|
|
|
13
13
|
Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
|
|
14
14
|
|
|
@@ -38,12 +38,12 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
|
|
|
38
38
|
|
|
39
39
|
! Before writing output artifacts, follow the guards in [artifact-guards.md](./artifact-guards.md) (Preparatory Guard for proposed/ scope items; Spec-Generating Guard for PROJECT-DEFINITION).
|
|
40
40
|
|
|
41
|
-
! Run the Full interview path from [interview.md](./interview.md) unconditionally -- write PRD narratives as date-prefixed story/phase vBRIEF(s) to `
|
|
41
|
+
! Run the Full interview path from [interview.md](./interview.md) unconditionally -- write PRD narratives as date-prefixed story/phase vBRIEF(s) to `xbrief/proposed/YYYY-MM-DD-<kebab-slug>.xbrief.json`.
|
|
42
42
|
|
|
43
43
|
- ! Use the Full path regardless of project size -- enterprise always requires a PRD
|
|
44
44
|
- ! Write PRD content as narratives in the proposed/ vBRIEF `plan.narratives`: `ProblemStatement`, `Goals`, `NonGoals`, `UserStories`, `Requirements` (functional + non-functional), `SuccessMetrics`
|
|
45
45
|
- ! Record the PRD approver(s) in the `Approvers` narrative
|
|
46
|
-
- ! Run `task prd:render` (if UX continuity needed) to produce `PRD.md` **only as a deprecation-redirect derivative** (see v0.20 Output Shape); the source of truth is the
|
|
46
|
+
- ! Run `task prd:render` (if UX continuity needed) to produce `PRD.md` **only as a deprecation-redirect derivative** (see v0.20 Output Shape); the source of truth is the xbrief/ artifacts.
|
|
47
47
|
|
|
48
48
|
### Gate 1: PRD Approval
|
|
49
49
|
|
|
@@ -76,14 +76,14 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
|
|
|
76
76
|
|
|
77
77
|
! Before writing output artifacts, follow the guards in [artifact-guards.md](./artifact-guards.md) (Preparatory Guard for proposed/ scope items; Spec-Generating Guard for PROJECT-DEFINITION).
|
|
78
78
|
|
|
79
|
-
! Enrich or emit date-prefixed vBRIEF(s) in `
|
|
79
|
+
! Enrich or emit date-prefixed vBRIEF(s) in `xbrief/proposed/` with architecture and plan narratives derived from the approved PRD narratives and accepted ADRs. (No singular `specification.vbrief.json`.)
|
|
80
80
|
|
|
81
81
|
- ! Add HOW narratives to the proposed/ vBRIEF `plan.narratives`: `Architecture`, `TechDecisions`, `ImplementationPhases`, `TraceabilityMatrix`
|
|
82
82
|
- ! Every spec task must trace to a PRD requirement and, where applicable, an ADR
|
|
83
83
|
- ! Use the Light or Full path from [interview.md](./interview.md) for specification generation
|
|
84
84
|
- ! Include traceability matrix: spec task → PRD requirement → ADR (where applicable)
|
|
85
|
-
- ! Run `task spec:render` (if UX continuity needed) to produce `SPECIFICATION.md` **only as a deprecation-redirect derivative** (see v0.20 Output Shape); the source of truth is the
|
|
86
|
-
- ! After proposed/ vBRIEFs exist, invoke `task project:render` to produce/refresh `
|
|
85
|
+
- ! Run `task spec:render` (if UX continuity needed) to produce `SPECIFICATION.md` **only as a deprecation-redirect derivative** (see v0.20 Output Shape); the source of truth is the xbrief/ lifecycle + PROJECT-DEFINITION.
|
|
86
|
+
- ! After proposed/ vBRIEFs exist, invoke `task project:render` to produce/refresh `xbrief/PROJECT-DEFINITION.xbrief.json`.
|
|
87
87
|
|
|
88
88
|
! After emitting the proposed/ vBRIEF(s), surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).
|
|
89
89
|
|
|
@@ -107,13 +107,13 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
|
|
|
107
107
|
|
|
108
108
|
## Output Artifacts
|
|
109
109
|
|
|
110
|
-
- `
|
|
111
|
-
- `
|
|
110
|
+
- `xbrief/proposed/YYYY-MM-DD-*.xbrief.json` (one or more) -- source of truth for PRD and specification narratives (date-prefixed per v0.20 contract)
|
|
111
|
+
- `xbrief/PROJECT-DEFINITION.xbrief.json` -- complete via `task project:render`
|
|
112
112
|
- `PRD.md` -- rendered export via `task prd:render` **only if deprecation-redirect sentinel** (read-only stakeholder review artifact; otherwise omit)
|
|
113
113
|
- `docs/adr/adr-NNN-*.md` -- accepted Architecture Decision Records (unchanged location)
|
|
114
114
|
- `SPECIFICATION.md` -- rendered export via `task spec:render` **only if deprecation-redirect sentinel** (read-only stakeholder review artifact; otherwise omit)
|
|
115
115
|
- Traceability matrix (inline in the proposed/ vBRIEF narratives or as a separate `docs/traceability.md`)
|
|
116
|
-
- `
|
|
116
|
+
- `xbrief/{proposed,pending,active,completed,cancelled}/` -- all five lifecycle folders seeded
|
|
117
117
|
|
|
118
118
|
---
|
|
119
119
|
|
|
@@ -139,11 +139,11 @@ Enterprise is a **spec-generating** strategy. It uses the Forced-Full path and a
|
|
|
139
139
|
|
|
140
140
|
This strategy has been migrated to the full v0.20 output shape so enterprise-generated projects are accepted by the build skill Pre-Cutover Detection Guard with zero errors on first attempt (resolves the enterprise row from the #1166 inconsistency table and the s5 story acceptance criteria).
|
|
141
141
|
|
|
142
|
-
- ! Seed the five lifecycle folders under `
|
|
143
|
-
- ! Emit scope items (PRD, spec phases, etc.) exclusively as date-prefixed scope vBRIEFs: `
|
|
144
|
-
- ! After the proposed/ vBRIEFs are written, invoke `task project:render` (run from the repo root) to generate/refresh the complete `
|
|
142
|
+
- ! Seed the five lifecycle folders under `xbrief/` if any are missing: `proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`.
|
|
143
|
+
- ! Emit scope items (PRD, spec phases, etc.) exclusively as date-prefixed scope vBRIEFs: `xbrief/proposed/YYYY-MM-DD-<kebab-slug>.xbrief.json` (use the run's creation date for the prefix; choose descriptive slugs). Decompose into focused, buildable vBRIEFs (v0.6 schema) rather than a monolithic legacy spec.
|
|
144
|
+
- ! After the proposed/ vBRIEFs are written, invoke `task project:render` (run from the repo root) to generate/refresh the complete `xbrief/PROJECT-DEFINITION.xbrief.json` (items registry is derived from the lifecycle folders).
|
|
145
145
|
- ⊗ Never emit `vbrief/specification.vbrief.json` (or any legacy dual-write).
|
|
146
|
-
- ~ `PRD.md` and `SPECIFICATION.md` at the project root, if produced at all, must be only read-only derivatives that include the v0.20 deprecated-redirect sentinel (see conventions/machine-generated-banner.md). The source of truth is the
|
|
146
|
+
- ~ `PRD.md` and `SPECIFICATION.md` at the project root, if produced at all, must be only read-only derivatives that include the v0.20 deprecated-redirect sentinel (see conventions/machine-generated-banner.md). The source of truth is the xbrief/ lifecycle vBRIEFs + PROJECT-DEFINITION. ADRs remain in `docs/adr/`.
|
|
147
147
|
- ! Before writing any proposed/ vBRIEFs or PROJECT-DEFINITION, follow the guards in [artifact-guards.md](./artifact-guards.md) (Preparatory Guard for scope items in proposed/; Spec-Generating Guard for PROJECT-DEFINITION).
|
|
148
148
|
- ! Final output tree must pass the deterministic v0.20 strategy output validation gate (s2-deterministic-gate) and the build Pre-Cutover Detection Guard with zero warnings/errors. See full acceptance in the s5 vBRIEF and the 1166 decomposition.
|
|
149
149
|
- ! Cite the canonical contract `strategies/v0-20-contract.md` (s1-contract) for the exact shape and the per-strategy table row.
|
|
@@ -156,9 +156,9 @@ This strategy has been migrated to the full v0.20 output shape so enterprise-gen
|
|
|
156
156
|
|
|
157
157
|
| Artifact | Purpose | Created By |
|
|
158
158
|
|----------|---------|------------|
|
|
159
|
-
| `
|
|
160
|
-
| `
|
|
161
|
-
| `
|
|
159
|
+
| `xbrief/proposed/YYYY-MM-DD-*.xbrief.json` (one or more) | PRD + specification narratives as date-prefixed scope items (per v0.20 contract) | Enterprise |
|
|
160
|
+
| `xbrief/PROJECT-DEFINITION.xbrief.json` | Project identity gestalt + complete scope items registry | `task project:render` (invoked by Enterprise) |
|
|
161
|
+
| `xbrief/{proposed,pending,active,completed,cancelled}/` | All five lifecycle folders seeded | Enterprise |
|
|
162
162
|
| `docs/adr/adr-NNN-*.md` | Accepted Architecture Decision Records (traceable) | Enterprise (unchanged) |
|
|
163
163
|
| (optional derivative) `PRD.md` / `SPECIFICATION.md` | Human-readable (includes deprecated-redirect sentinel only) | `task prd:render` / `task spec:render` (if invoked) |
|
|
164
164
|
|
|
@@ -168,13 +168,13 @@ This strategy has been migrated to the full v0.20 output shape so enterprise-gen
|
|
|
168
168
|
- Primary handoff `PRD.md` or `SPECIFICATION.md` at project root (without sentinel)
|
|
169
169
|
- Bare-named vBRIEFs in proposed/
|
|
170
170
|
|
|
171
|
-
See the full table and rules in `strategies/v0-20-contract.md` (enterprise row: Must Create Lifecycle Folders: Yes; Must Write PROJECT-DEFINITION: Yes; Scope vBRIEFs Location: proposed/YYYY-MM-DD-*.
|
|
171
|
+
See the full table and rules in `strategies/v0-20-contract.md` (enterprise row: Must Create Lifecycle Folders: Yes; Must Write PROJECT-DEFINITION: Yes; Scope vBRIEFs Location: proposed/YYYY-MM-DD-*.xbrief.json only; specification.vbrief.json: Never; SPECIFICATION.md / PROJECT.md: Omit or deprecation redirect only).
|
|
172
172
|
|
|
173
173
|
---
|
|
174
174
|
|
|
175
175
|
## Invoking This Strategy
|
|
176
176
|
|
|
177
|
-
Set in PROJECT-DEFINITION.
|
|
177
|
+
Set in PROJECT-DEFINITION.xbrief.json narratives:
|
|
178
178
|
```json
|
|
179
179
|
"Strategy": "strategies/enterprise.md"
|
|
180
180
|
```
|
package/strategies/interview.md
CHANGED
|
@@ -94,15 +94,15 @@ See `strategies/map.md` for standalone behavior.
|
|
|
94
94
|
- ! Previously-run strategies MUST display with a run count (e.g., `Research (ran 1×)`)
|
|
95
95
|
- ! No strategy is ever removed from the gate — users can re-run any strategy
|
|
96
96
|
- ! Run counts are read from `completedStrategies` in
|
|
97
|
-
[`./
|
|
97
|
+
[`./xbrief/plan.xbrief.json`](../vbrief/vbrief.md#strategy-chaining-fields)
|
|
98
98
|
|
|
99
99
|
### State Tracking
|
|
100
100
|
|
|
101
101
|
- ! On completion of a preparatory strategy, update `completedStrategies` in
|
|
102
|
-
`./
|
|
102
|
+
`./xbrief/plan.xbrief.json`: increment `runCount`, append artifact paths
|
|
103
103
|
- ! Append all new artifact paths to the flat `artifacts` array
|
|
104
104
|
- ! The next strategy and eventual spec generation MUST load all artifacts
|
|
105
|
-
listed in `plan.
|
|
105
|
+
listed in `plan.xbrief.json`
|
|
106
106
|
- ! On brownfield **Add scope** or **Update project definition**, load existing
|
|
107
107
|
PROJECT-DEFINITION identity and preparatory artifacts before asking questions
|
|
108
108
|
|
|
@@ -578,7 +578,7 @@ diff only on the second pass or when the user explicitly asks for it.
|
|
|
578
578
|
|
|
579
579
|
### State Preservation
|
|
580
580
|
|
|
581
|
-
- ! All `completedStrategies` and `artifacts` in `plan.
|
|
581
|
+
- ! All `completedStrategies` and `artifacts` in `plan.xbrief.json` MUST be
|
|
582
582
|
preserved across revisions
|
|
583
583
|
- ! The chaining gate will show updated run counts reflecting the full session history
|
|
584
584
|
|
package/strategies/map.md
CHANGED
|
@@ -50,7 +50,7 @@ Mapping produces artifacts that feed into planning so the agent **follows existi
|
|
|
50
50
|
|
|
51
51
|
! Before writing output artifacts, follow the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light).
|
|
52
52
|
|
|
53
|
-
Produce a single `
|
|
53
|
+
Produce a single `xbrief/proposed/{project}-codebase-map.xbrief.json` with four narratives:
|
|
54
54
|
|
|
55
55
|
! After emitting this scope vBRIEF, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).
|
|
56
56
|
|
|
@@ -105,9 +105,9 @@ Produce a single `vbrief/proposed/{project}-codebase-map.vbrief.json` with four
|
|
|
105
105
|
|
|
106
106
|
### Artifact Registration (both modes)
|
|
107
107
|
|
|
108
|
-
- ! On completion, register artifacts in `./
|
|
108
|
+
- ! On completion, register artifacts in `./xbrief/plan.xbrief.json`:
|
|
109
109
|
- Update `completedStrategies`: increment `runCount` for `"map"`,
|
|
110
|
-
append artifact path (`
|
|
110
|
+
append artifact path (`xbrief/proposed/{project}-codebase-map.xbrief.json`)
|
|
111
111
|
- Append the path to the flat `artifacts` array
|
|
112
112
|
- ! The mapping narratives MUST inform subsequent strategies and spec generation:
|
|
113
113
|
- `Conventions` -> implementation constraints
|
|
@@ -130,7 +130,7 @@ Mapping complete. Here's what I found:
|
|
|
130
130
|
- Conventions: [brief summary]
|
|
131
131
|
- Concerns: [brief summary]
|
|
132
132
|
|
|
133
|
-
Artifact:
|
|
133
|
+
Artifact: xbrief/proposed/{project}-codebase-map.xbrief.json
|
|
134
134
|
|
|
135
135
|
What would you like to do next?
|
|
136
136
|
|
|
@@ -141,7 +141,7 @@ What would you like to do next?
|
|
|
141
141
|
```
|
|
142
142
|
|
|
143
143
|
- ! Present the narrative summary before offering options
|
|
144
|
-
- ! If the user chooses a strategy, invoke it (the artifact persists in `
|
|
144
|
+
- ! If the user chooses a strategy, invoke it (the artifact persists in `xbrief/proposed/`)
|
|
145
145
|
- ! If the user chooses "done", confirm the artifact location and exit cleanly
|
|
146
146
|
- ~ Recommend option 1 (interview) when the user's goal is to build or extend
|
|
147
147
|
- ~ Recommend option 4 (done) when the user's goal is exploration or onboarding
|
|
@@ -173,7 +173,7 @@ Before an interview — analysis-first, then spec:
|
|
|
173
173
|
Map this codebase, then use the interview strategy to plan [feature].
|
|
174
174
|
```
|
|
175
175
|
|
|
176
|
-
Or set in PROJECT-DEFINITION.
|
|
176
|
+
Or set in PROJECT-DEFINITION.xbrief.json narratives:
|
|
177
177
|
```json
|
|
178
178
|
"Strategy": "strategies/map.md"
|
|
179
179
|
```
|
package/strategies/probe.md
CHANGED
|
@@ -73,46 +73,50 @@ Walk the decision tree depth-first. For each unresolved branch:
|
|
|
73
73
|
|
|
74
74
|
! Before writing output artifacts, follow the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light).
|
|
75
75
|
|
|
76
|
-
### Mechanical guard (`
|
|
76
|
+
### Mechanical guard (`deft probe-session`)
|
|
77
77
|
|
|
78
78
|
Probe completion is enforced mechanically — not by prose alone. A per-clone
|
|
79
79
|
session file at `.deft/probe-session.json` records whether the session is still
|
|
80
80
|
`interrogate` or `complete`, plus the probe `target`, `currentBranch`, and
|
|
81
81
|
`resolvedDecisions`.
|
|
82
82
|
|
|
83
|
+
**Waiver (#3556):** The probe skill keeps the no-artifact guard and does not
|
|
84
|
+
require `deft probe-session`. This strategy names `deft probe-session`.
|
|
85
|
+
Silence is not agreement.
|
|
86
|
+
|
|
83
87
|
- ! At probe start, record the session:
|
|
84
|
-
`
|
|
88
|
+
`deft probe-session start --target <scope>`
|
|
85
89
|
- ! While interrogating, record locked/deferred/risk-accepted decisions and
|
|
86
90
|
branch focus with `record` / `set-branch` subcommands as branches resolve
|
|
87
91
|
- ! Before writing probe output or registering `completedStrategies.probe`,
|
|
88
92
|
mark the session complete:
|
|
89
|
-
`
|
|
93
|
+
`deft probe-session complete`
|
|
90
94
|
- ! Immediately before artifact or plan registration, run the guard:
|
|
91
|
-
- `
|
|
92
|
-
- `
|
|
95
|
+
- `deft probe-session guard-artifact --path xbrief/proposed/YYYY-MM-DD-{scope}-probe.xbrief.json`
|
|
96
|
+
- `deft probe-session guard-plan-registration`
|
|
93
97
|
- ⊗ Write probe artifacts or update `completedStrategies.probe` while the
|
|
94
98
|
session state is still `interrogate` — the guard exits non-zero with an
|
|
95
99
|
actionable recovery message
|
|
96
100
|
|
|
97
101
|
**Recovery when the guard blocks handoff:** continue interrogation until the
|
|
98
102
|
[transition criteria](#transition-criteria-probe-complete) are met, record
|
|
99
|
-
decisions with `
|
|
100
|
-
then retry the guard before writing artifacts or updating `plan.
|
|
103
|
+
decisions with `deft probe-session record`, run `deft probe-session complete`,
|
|
104
|
+
then retry the guard before writing artifacts or updating `plan.xbrief.json`.
|
|
101
105
|
|
|
102
|
-
`{scope}` is the project name from `PROJECT-DEFINITION.
|
|
106
|
+
`{scope}` is the project name from `PROJECT-DEFINITION.xbrief.json`, or the
|
|
103
107
|
feature/component name if probing a sub-scope. Use the same value consistently
|
|
104
108
|
throughout the session. Examples: `my-app-probe`, `auth-probe`.
|
|
105
109
|
|
|
106
|
-
- ! Produce a `
|
|
110
|
+
- ! Produce a `xbrief/proposed/YYYY-MM-DD-{scope}-probe.xbrief.json` scope xBRIEF with three mandatory narratives:
|
|
107
111
|
- `LockedDecisions` — what was resolved and why (when the lock is an intentional under-build, include dual-path graduation fields: `now`, `later`, `graduationRef`, `trigger`, `status` — see [Graduation (Now+Later)](#graduation-nowlater-when-locking-an-under-build-2899))
|
|
108
112
|
- `SurfacedRisks` — concerns raised, even if not fully resolved
|
|
109
113
|
- `DeferredDecisions` — explicitly acknowledged items with justification
|
|
110
114
|
- ! Each entry in a narrative includes: **question asked**, **answer given**, **status** (locked / deferred / risk-accepted)
|
|
111
|
-
- ! This
|
|
112
|
-
- ! Persist significant decisions as
|
|
113
|
-
- ⊗ Write probe output to a hand-authored markdown file — use
|
|
115
|
+
- ! This xBRIEF is injected into all downstream work: planning, execution, verification
|
|
116
|
+
- ! Persist significant decisions as xBRIEF narratives on the relevant plan items
|
|
117
|
+
- ⊗ Write probe output to a hand-authored markdown file — use xBRIEF narratives for token-efficient, machine-consumable agent consumption (mirrors the [discuss](./discuss.md) and [research](./research.md) output contracts so the chaining-gate flow-through guarantee is mechanical, not aspirational)
|
|
114
118
|
|
|
115
|
-
! After emitting the probe scope
|
|
119
|
+
! After emitting the probe scope xBRIEF to `xbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).
|
|
116
120
|
|
|
117
121
|
## Graduation (Now+Later) when locking an under-build (#2899)
|
|
118
122
|
|
|
@@ -142,15 +146,15 @@ Glossary naming for Graduation is owned by sibling work (#2907); this section is
|
|
|
142
146
|
|
|
143
147
|
## Then: Chaining Gate
|
|
144
148
|
|
|
145
|
-
After the probe is complete and `
|
|
149
|
+
After the probe is complete and `xbrief/proposed/YYYY-MM-DD-{scope}-probe.xbrief.json` is
|
|
146
150
|
written, return to the [chaining gate](./interview.md#chaining-gate).
|
|
147
151
|
|
|
148
|
-
- ! On completion, register artifacts in `./
|
|
152
|
+
- ! On completion, register artifacts in `./xbrief/plan.xbrief.json`:
|
|
149
153
|
- Update `completedStrategies`: increment `runCount` for `"probe"`,
|
|
150
|
-
append artifact path (`
|
|
154
|
+
append artifact path (`xbrief/proposed/YYYY-MM-DD-{scope}-probe.xbrief.json`)
|
|
151
155
|
- Append the path to the flat `artifacts` array
|
|
152
156
|
- ! Return to [interview.md Chaining Gate](./interview.md#chaining-gate)
|
|
153
|
-
- ! The `LockedDecisions`, `SurfacedRisks`, and `DeferredDecisions` narratives from `
|
|
157
|
+
- ! The `LockedDecisions`, `SurfacedRisks`, and `DeferredDecisions` narratives from `xbrief/proposed/YYYY-MM-DD-{scope}-probe.xbrief.json` MUST flow
|
|
154
158
|
into subsequent strategies and spec generation:
|
|
155
159
|
- Locked decisions become constraints in the specification
|
|
156
160
|
- Surfaced risks become NFRs or explicit acceptance criteria
|
|
@@ -174,4 +178,4 @@ written, return to the [chaining gate](./interview.md#chaining-gate).
|
|
|
174
178
|
- ⊗ Using codebase exploration as a substitute for asking the user about deliberate design choices
|
|
175
179
|
- ⊗ Stopping when the conversation feels comfortable — stop when no new branches emerge
|
|
176
180
|
- ⊗ Ending after probe without chaining back to the gate (chained mode; in standalone context, returning to the invoking strategy's menu satisfies the completion requirement per the [standalone-context rule](#then-chaining-gate))
|
|
177
|
-
- ⊗ Writing probe output to a plain markdown file (`{scope}-probe.md`) instead of the canonical `
|
|
181
|
+
- ⊗ Writing probe output to a plain markdown file (`{scope}-probe.md`) instead of the canonical `xbrief/proposed/YYYY-MM-DD-{scope}-probe.xbrief.json` scope xBRIEF — plain markdown bypasses the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light) and breaks the downstream-consumer flow-through guarantee
|