@deftai/directive-content 0.105.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/UPGRADING.md +2 -2
- package/commands.md +16 -11
- package/contracts/agent-hook-readiness.md +3 -3
- package/contracts/closed-verb-authz.md +14 -2
- package/contracts/design-critique.md +100 -0
- package/main.md +1 -1
- package/package.json +1 -1
- package/packs/skills/skills-pack-0.1.json +18 -4
- package/packs/strategies/strategies-pack-0.1.json +13 -13
- package/scm/github.md +1 -1
- package/skills/deft-directive-design-critique/SKILL.md +46 -0
- package/skills/deft-directive-probe/SKILL.md +4 -2
- package/skills/deft-directive-release/SKILL.md +5 -3
- package/skills/deft-directive-review-cycle/SKILL.md +1 -1
- package/skills/deft-directive-swarm/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/policy.yml +10 -0
- package/tasks/scope.yml +2 -2
- package/tasks/verify.yml +12 -2
- package/templates/agent-prompt-preamble.md +4 -4
- package/templates/agents-entry.md +1 -1
- package/templates/design-critique-brief.md +41 -0
package/scm/github.md
CHANGED
|
@@ -503,7 +503,7 @@ Three consumer-facing surfaces enforce the branch-policy contract:
|
|
|
503
503
|
- `deft verify:branch` — refuses default-branch commit unless `plan.policy.allowDirectCommitsToMaster = true` (typed) or `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1`.
|
|
504
504
|
- `.githooks/pre-commit` / `pre-push` — installed via `deft setup`; verify via `deft verify:hooks-installed`. After a framework upgrade, run `deft update` to refresh hook templates (#2049).
|
|
505
505
|
- `deft policy:show --field=allowDirectCommitsToMaster` — inspect policy; `deft policy:allow-direct-commits -- --confirm` writes typed override with audit row.
|
|
506
|
-
- `deft verify:forward-coverage` —
|
|
506
|
+
- `deft verify:forward-coverage` — fail-closed new-source-file existence (#1310) plus warn-first diff coverage of added/modified branches (#3514). Intersects `coverage/coverage-final.json` with the diff (90% per-change branch threshold). That 90% is not the 75 global floor. Wired into `deft check` + pre-commit (`--staged`); `--enforce` fail-closes the diff half; `--allow-list <path>` documents exceptions.
|
|
507
507
|
|
|
508
508
|
When `plan.policy.allowDirectCommitsToMaster = true`, the agent MUST surface at session start (after alignment confirmation):
|
|
509
509
|
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: deft-directive-design-critique
|
|
3
|
+
description: >-
|
|
4
|
+
Thin router for the design-critique motion: triggers and five pointer stops
|
|
5
|
+
into the contract. Use when the operator asks for a design critique,
|
|
6
|
+
design-critique, critique panel, or mechanism-shaped triage. Do NOT trigger
|
|
7
|
+
on ordinary implement, build, or swarm work.
|
|
8
|
+
triggers:
|
|
9
|
+
- design critique
|
|
10
|
+
- design-critique
|
|
11
|
+
- critique panel
|
|
12
|
+
- mechanism-shaped triage
|
|
13
|
+
---
|
|
14
|
+
<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
|
|
15
|
+
<!-- Purpose: rendered skill -->
|
|
16
|
+
<!-- Source of truth: packs/skills/skills-pack-0.1.json -->
|
|
17
|
+
<!-- Regenerate with: task packs:render -->
|
|
18
|
+
<!-- Edit the source, not this file. Slice instead of loading every SKILL.md: task packs:slice skills by-trigger --trigger <kw> (or list) -->
|
|
19
|
+
|
|
20
|
+
# Design Critique
|
|
21
|
+
|
|
22
|
+
Thin router into the design-critique contract. Operator dispatches from the brief template.
|
|
23
|
+
|
|
24
|
+
Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
|
|
25
|
+
|
|
26
|
+
## When to Use
|
|
27
|
+
|
|
28
|
+
- Operator asks for a design critique, a design-critique, a critique panel, or mechanism-shaped triage
|
|
29
|
+
- ⊗ Ordinary implement, build, or swarm work
|
|
30
|
+
|
|
31
|
+
## Stops
|
|
32
|
+
|
|
33
|
+
Normative rules live in [`contracts/design-critique.md`](../../contracts/design-critique.md). Fill [`templates/design-critique-brief.md`](../../templates/design-critique-brief.md) and dispatch from there. Phase 1 gate: [`docs/decisions/ADR-005-design-critique-judgment-gate.md`](../../../docs/decisions/ADR-005-design-critique-judgment-gate.md).
|
|
34
|
+
|
|
35
|
+
1. Stop 1 — Gate
|
|
36
|
+
2. Stop 2 — Variant selection
|
|
37
|
+
3. Stop 3 — Critic envelope
|
|
38
|
+
4. Stop 4 — Residual reiteration
|
|
39
|
+
5. Stop 5 — Verified synthesis
|
|
40
|
+
|
|
41
|
+
⊗ Auto-dispatch critics from this skill.
|
|
42
|
+
⊗ Copy the variant table, synthesis rules, or other contract bodies into this skill.
|
|
43
|
+
|
|
44
|
+
## EXIT
|
|
45
|
+
|
|
46
|
+
deft-directive-design-critique complete -- exiting skill. Next: fill the brief template and dispatch.
|
|
@@ -43,6 +43,8 @@ While probe completion criteria (below) are NOT met:
|
|
|
43
43
|
|
|
44
44
|
! Read existing context and interrogate only — artifacts land in the Output phase after completion.
|
|
45
45
|
|
|
46
|
+
**Waiver (#3556):** This skill keeps the no-artifact guard and does not require `deft probe-session`. The probe strategy names `deft probe-session`. Silence is not agreement.
|
|
47
|
+
|
|
46
48
|
## Workflow
|
|
47
49
|
|
|
48
50
|
### Step 1: Establish the plan
|
|
@@ -95,7 +97,7 @@ Walk the decision tree depth-first. For each unresolved branch:
|
|
|
95
97
|
|
|
96
98
|
`{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
99
|
|
|
98
|
-
- ! Produce a `xbrief/proposed/{scope}-probe.xbrief.json` scope xBRIEF with three mandatory narratives:
|
|
100
|
+
- ! Produce a `xbrief/proposed/YYYY-MM-DD-{scope}-probe.xbrief.json` scope xBRIEF with three mandatory narratives:
|
|
99
101
|
- `LockedDecisions` — what was resolved and why
|
|
100
102
|
- `SurfacedRisks` — concerns raised, even if not fully resolved
|
|
101
103
|
- `DeferredDecisions` — explicitly acknowledged items with justification
|
|
@@ -105,7 +107,7 @@ Walk the decision tree depth-first. For each unresolved branch:
|
|
|
105
107
|
|
|
106
108
|
## Chaining Gate
|
|
107
109
|
|
|
108
|
-
After the probe is complete and `xbrief/proposed/{scope}-probe.xbrief.json` is written:
|
|
110
|
+
After the probe is complete and `xbrief/proposed/YYYY-MM-DD-{scope}-probe.xbrief.json` is written:
|
|
109
111
|
|
|
110
112
|
- ! Register artifacts in `./xbrief/plan.xbrief.json` (`completedStrategies`, `artifacts`)
|
|
111
113
|
- ! Return to [interview.md Chaining Gate](../../strategies/interview.md#chaining-gate) when invoked from the interview flow
|
|
@@ -180,7 +180,7 @@ See [`docs/RELEASING.md`](../../../docs/RELEASING.md) § Routine vs hard cut for
|
|
|
180
180
|
6. ! **Run `task reconcile:issues -- --apply-lifecycle-fixes` to clear any closed-issue / non-completed-folder xBRIEFs before invoking `task release`** (#734). The release pipeline carries the deterministic gate at Step 3 (`scripts/release.py::check_vbrief_lifecycle_sync`, refuses with `EXIT_VIOLATION` on any Section (c) mismatch), but Phase 1 is the operator's first-line defence -- running the apply-mode flag here is the canonical clean path; `--allow-vbrief-drift` on the pipeline exists only as the explicit-acknowledgment escape hatch (analogous to `--allow-dirty`). The recurrence record is the v0.21.0 cut, which surfaced 13 stranded xBRIEFs (8 cycle-relevant + 5 historical residue) post-publish; the gate now blocks that drift before any irreversible action
|
|
181
181
|
7. ! **Verify the proposed `v<version>` tag is not already in use locally, on origin, or as a published GitHub release** (#784). The release pipeline carries the deterministic gate at Step 4 (`scripts/release.py::check_tag_available`, refuses with `EXIT_VIOLATION` before any state mutation -- CHANGELOG promotion, ROADMAP refresh, build, commit), but Phase 1 is the operator's first-line defence. Quickly probe with `git tag -l v<version>` (local), `git ls-remote --tags origin refs/tags/v<version>` (remote), and `gh release view v<version> --repo <owner>/<repo>` (release-only, where `gh release view` exits 0 only when the release exists). The recurrence record is the v0.22.0 → v0.23.0 release attempt on 2026-05-01: the operator typed `0.22.0` (the prior release from 12 hours earlier) and the legacy pipeline ran 8 steps before failing at `git tag` -- leaving a wrong-version local commit + `dist/deft-0.22.0.zip` orphan + manual `git reset --hard` recovery. The new pre-flight gate blocks that mode before any irreversible action
|
|
182
182
|
8. ! **Verify the npm credential path is configured before cutting the tag** (#1910, #1909). A `v*` tag now auto-triggers `.github/workflows/npm-publish.yml`, which publishes the four `@deftai/directive*` packages with `npm publish --provenance`. Confirm the publish path can authenticate: either the `NPM_TOKEN` repo secret is present (`gh secret list --repo <owner>/<repo>` shows `NPM_TOKEN`) OR an npm OIDC trusted publisher is configured for the `@deftai/directive*` packages. If neither is in place, WARN loudly that the tag will fire a publish job that fails (red X on the tag, no packages) -- the operator may still proceed for a GitHub-only release, but the npm channel will not land until #1909's credential is provisioned. Cross-reference #1909.
|
|
183
|
-
9. ! **Disclose npm irrevocability before any tag push (#1972, #2002).** A `v<version>` tag push is the **real npm publish gate** -- NOT Phase 5 or `task release:publish`. Tag push fires `.github/workflows/npm-publish.yml` in a separate workflow that is NOT draft-gated; npm packages ship immediately and **cannot be retracted** (`npm unpublish` is forbidden). Recovery is forward-only: deprecate, dist-tag, or ship a patch. The
|
|
183
|
+
9. ! **Disclose npm irrevocability before any tag push (#1972, #2002, #3527).** A `v<version>` tag push is the **real npm publish gate** -- NOT Phase 5 or `task release:publish`. Tag push fires `.github/workflows/npm-publish.yml` in a separate workflow that is NOT draft-gated; npm packages ship immediately and **cannot be retracted** (`npm unpublish` is forbidden). Recovery is forward-only: deprecate, dist-tag, or ship a patch. The last human gates before npm goes live are: (a) Phase 2 dry-run `yes`, (b) a human-origin closed-verb grant (`deft authz:grant -- --template release-publish --target <version>` or `DEFT_ALLOW_RELEASE_PUBLISH=1`). `task release` fails closed at the Step 10–11 tag-push boundary without that grant. Phase 5 only controls GitHub release visibility (draft → public); it does NOT gate npm. The draft-flip `release:publish` closed-verb check remains (#1095).
|
|
184
184
|
10. ~ Ask the operator for an optional one-line release **summary** (recommended 80-160 chars; can be skipped). The summary is the canonical narrative for THIS release across three audiences: (a) injected as a Markdown blockquote at the top of the promoted `CHANGELOG.md [<version>]` section, (b) auto-flowed into the GitHub release body via the existing `_section_for_version` pickup, and (c) populated VERBATIM into the Phase 8 Slack `*Summary*:` slot. Capture the wording once here; do NOT regenerate per-audience downstream
|
|
185
185
|
|
|
186
186
|
⊗ Skip the version-bump magnitude check -- a patch release that ships breaking changes is the kind of regression that Repair Authority [AXIOM] (#709) is designed to prevent.
|
|
@@ -201,7 +201,7 @@ task release -- <version> --dry-run --skip-tag --skip-release --summary "<text>"
|
|
|
201
201
|
|
|
202
202
|
The dry-run prints `[N/13] <step>... DRYRUN (would <action>)` for every pipeline step (Step 13 is the post-create verify-isDraft gate added by #724; Step 4 is the tag-availability pre-flight gate added by #784). Step 6 (CHANGELOG promotion) surfaces whether a summary was supplied (truncated to ~60 chars in the preview) so the operator can validate the wording before any file is written. Capture the output and present it to the user, then wait for explicit confirmation before continuing.
|
|
203
203
|
|
|
204
|
-
! Wait for explicit user confirmation: `yes` / `back` / `quit`. Remind the operator that Phase 4's tag push will irrevocably publish npm (#1972) -- this `yes` is the last safe abort before that channel opens.
|
|
204
|
+
! Wait for explicit user confirmation: `yes` / `back` / `quit`. Remind the operator that Phase 4's tag push will irrevocably publish npm (#1972) and requires a `release-publish` grant (or `DEFT_ALLOW_RELEASE_PUBLISH=1`) -- this `yes` is the last safe abort before that channel opens (#3527).
|
|
205
205
|
- `yes` (or `confirmed` / `approve`) → proceed to Phase 3
|
|
206
206
|
- `back` → return to Phase 1 for re-validation (e.g. user wants to amend the version or `[Unreleased]` content)
|
|
207
207
|
- `quit` → abort the workflow cleanly; no state changes
|
|
@@ -232,7 +232,7 @@ The harness provisions `deftai/deftai-release-test-<ts>-<uuid6>`, runs the smoke
|
|
|
232
232
|
|
|
233
233
|
## Phase 4 — Production draft
|
|
234
234
|
|
|
235
|
-
! **Last human gate before npm (#1972, #2002).** Immediately before invoking `task release`, re-state that the tag push in this step will irrevocably publish all four `@deftai/directive*` packages to npm via `.github/workflows/npm-publish.yml`. There is no undo on npm; only forward recovery (deprecate / dist-tag / patch). Proceed only when the operator explicitly confirms.
|
|
235
|
+
! **Last human gate before npm (#1972, #2002, #3527).** Immediately before invoking `task release`, re-state that the tag push in this step will irrevocably publish all four `@deftai/directive*` packages to npm via `.github/workflows/npm-publish.yml`. There is no undo on npm; only forward recovery (deprecate / dist-tag / patch). Proceed only when the operator explicitly confirms **and** a human-origin grant covers `release-publish` for this version (`deft authz:grant -- --template release-publish --target <version>` or `DEFT_ALLOW_RELEASE_PUBLISH=1`). The pipeline fails closed at Step 10–11 without that grant -- that is the npm-distributing boundary. ⊗ Rely on Phase 5 `release:publish` as the npm gate; it only flips the GitHub draft. ⊗ Delete the draft-flip check as a substitute for the tag-push gate.
|
|
236
236
|
|
|
237
237
|
! Invoke `task release -- <version>` (NO `--dry-run`, NO `--skip-tag`, NO `--skip-release`, NO `--skip-ci`). If Phase 1 collected an operator summary, pass `--summary "<text>"` so the production cut writes the same blockquote the dry-run previewed.
|
|
238
238
|
|
|
@@ -377,6 +377,8 @@ Where `<one-line guidance>` is one of:
|
|
|
377
377
|
- ⊗ Run `task release` without a Phase 2 dry-run preview -- the dry-run is the only safe place to catch a bad version, malformed CHANGELOG, or wrong base branch
|
|
378
378
|
- ⊗ Skip Phase 3 (e2e rehearsal) on the assumption that "the dry-run is enough" -- the e2e harness catches gh-CLI auth issues, repo permission gaps, and pipeline-shape regressions that the dry-run cannot detect
|
|
379
379
|
- ⊗ Pass `--no-draft` to `task release` without explicit operator opt-in -- the default-draft contract is the foundation of the safety hardening surface
|
|
380
|
+
- ⊗ Invoke `task release` without `--skip-tag` when no `release-publish` grant or `DEFT_ALLOW_RELEASE_PUBLISH` is present -- the v0.105.0 cut published npm with no authz because the closed-verb check sat only on the later draft flip (#3527)
|
|
381
|
+
- ⊗ Delete the `release:publish` draft-flip closed-verb check as a substitute for the tag-push gate -- placement, not strength; both stay (#3527 / #1095)
|
|
380
382
|
- ⊗ Treat Phase 5 as the npm authority gate or require a redundant human `publish` prompt when npm already succeeded -- npm ships at tag push (#1972); Phase 5 is GitHub draft QA only
|
|
381
383
|
- ⊗ Expect `task release:rollback` to retract npm packages -- rollback is GitHub-only; npm recovery is forward-only (deprecate / dist-tag / patch)
|
|
382
384
|
- ⊗ Run `task release:rollback` against a release that has > 30 minutes of consumer-driven downloads without first weighing the hot-fix path -- a withdrawal note in the next patch is almost always less disruptive than deleting a public artifact
|
|
@@ -75,7 +75,7 @@ On OpenClaw hosts with Directive installed (`.deft/core/` or equivalent content
|
|
|
75
75
|
! Before entering the review/fix loop, run the skill-level branch-policy guard (#746 / #747). Halt before any state mutation if the project's `plan.policy.allowDirectCommitsToMaster` is unresolvable AND the operator has not set `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1`. Concretely:
|
|
76
76
|
|
|
77
77
|
```
|
|
78
|
-
|
|
78
|
+
deft verify:branch || exit 1
|
|
79
79
|
```
|
|
80
80
|
|
|
81
81
|
The skill MUST NOT modify files, push, or comment on the PR until the guard passes -- this catches the case where a malformed PROJECT-DEFINITION quietly disabled the policy and the agent would have committed directly to master mid-review.
|
|
@@ -29,7 +29,7 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
|
|
|
29
29
|
! Before any state mutation (creating worktrees, dispatching sub-agents, opening PRs), run the skill-level branch-policy guard (#746 / #747). Halt with the actionable disclosure message when the project's `plan.policy.allowDirectCommitsToMaster` is unresolvable AND `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT` is unset:
|
|
30
30
|
|
|
31
31
|
```
|
|
32
|
-
|
|
32
|
+
deft verify:branch || exit 1
|
|
33
33
|
```
|
|
34
34
|
|
|
35
35
|
The swarm skill creates branches per agent so the guard is mostly informational here, but a malformed PROJECT-DEFINITION (missing `plan.policy` block AND no legacy narrative) is a fail-closed signal worth surfacing before the swarm spawns N agents.
|
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
|