@deftai/directive-content 0.111.0 → 0.112.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/QUICK-START.md +16 -14
- package/Taskfile.yml +4 -0
- package/UPGRADING.md +64 -24
- package/commands.md +12 -12
- package/contracts/design-critique.md +18 -12
- package/docs/SUPPORT.md +43 -0
- package/docs/capabilities.md +110 -0
- package/docs/capability-overlay.json +197 -0
- package/docs/getting-started.md +131 -49
- package/package.json +1 -1
- package/packs/skills/skills-pack-0.1.json +8 -6
- package/scm/github.md +2 -0
- package/skills/deft-directive-design-critique/SKILL.md +8 -3
- package/skills/deft-directive-review-cycle/SKILL.md +12 -8
- package/skills/deft-directive-swarm/SKILL.md +8 -4
- package/skills/deft-directive-swarm/references/core-ops.md +1 -0
- package/skills/deft-directive-swarm/references/core-phase-0.md +1 -1
- package/skills/deft-directive-swarm/references/core-phase-3.md +7 -4
- package/skills/deft-directive-swarm/references/host-claude-code.md +3 -2
- package/skills/deft-directive-swarm/references/host-grok-build.md +4 -2
- package/skills/deft-directive-swarm/references/host-grokbot.md +151 -0
- package/tasks/docs.yml +19 -0
- package/tasks/migrate.yml +3 -1
- package/tasks/scm.yml +12 -1
- package/tasks/verify.yml +16 -0
- package/templates/PULL_REQUEST_TEMPLATE.md +12 -0
- package/templates/agent-prompt-preamble.md +2 -2
- package/templates/agents-entry.md +1 -1
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
<!-- AUTO-GENERATED by task docs:capability-map -- DO NOT EDIT MANUALLY -->
|
|
2
|
+
<!-- Source of truth: content/docs/capability-overlay.json plus existing registries (#4099) -->
|
|
3
|
+
<!-- Regenerate with: task docs:capability-map -->
|
|
4
|
+
|
|
5
|
+
# Capability index
|
|
6
|
+
|
|
7
|
+
Generated view over existing registries. Overlay: `content/docs/capability-overlay.json`.
|
|
8
|
+
Membership: `in_the_public_index` and status `current` or `compatibility` and canonical kind not `none`.
|
|
9
|
+
Same-PR documentation rule: [`content/coding/docs.md`](../coding/docs.md) (#447).
|
|
10
|
+
|
|
11
|
+
## Consumer
|
|
12
|
+
|
|
13
|
+
### Build skill
|
|
14
|
+
- **Status:** current
|
|
15
|
+
- **Canonical:** skill-trigger `deft-directive-build`
|
|
16
|
+
- **Gotchas:** xbrief:preflight on an active running brief before code. Do not treat completed xBRIEFs as next-build contract.
|
|
17
|
+
|
|
18
|
+
### Doctor
|
|
19
|
+
- **Status:** current
|
|
20
|
+
- **Canonical:** command `doctor`
|
|
21
|
+
- **Gotchas:** Support entry is doctor --full or the README cold-start. Not a second recovery ladder.
|
|
22
|
+
|
|
23
|
+
### Install / init
|
|
24
|
+
- **Status:** current
|
|
25
|
+
- **Canonical:** command `init`
|
|
26
|
+
- **Gotchas:** Consumer path is directive init. Do not send npm consumers through Corepack, Go, or uv.
|
|
27
|
+
|
|
28
|
+
### Public concepts page
|
|
29
|
+
- **Status:** current
|
|
30
|
+
- **Canonical:** document `docs-site/concepts.html`
|
|
31
|
+
- **Gotchas:** Concepts page is a public IA surface. README/UPGRADING rewrites stay on #4100.
|
|
32
|
+
|
|
33
|
+
### Public docs home
|
|
34
|
+
- **Status:** current
|
|
35
|
+
- **Canonical:** document `docs-site/index.html`
|
|
36
|
+
- **Gotchas:** Public IA lives under docs-site/. Do not mix it with maintainer docs/.
|
|
37
|
+
|
|
38
|
+
### Public gates page
|
|
39
|
+
- **Status:** current
|
|
40
|
+
- **Canonical:** document `docs-site/gates.html`
|
|
41
|
+
- **Gotchas:** task check is the merge chokepoint named here; do not invent a parallel public gate.
|
|
42
|
+
|
|
43
|
+
### Public install page
|
|
44
|
+
- **Status:** current
|
|
45
|
+
- **Canonical:** document `docs-site/install.html`
|
|
46
|
+
- **Gotchas:** Install copy stays on the consumer Node floor, not the maintainer toolchain pin.
|
|
47
|
+
|
|
48
|
+
### Public license page
|
|
49
|
+
- **Status:** current
|
|
50
|
+
- **Canonical:** document `docs-site/license.html`
|
|
51
|
+
- **Gotchas:** License page is a docs-site surface, not a substitute for root LICENSE.
|
|
52
|
+
|
|
53
|
+
### Public upgrade page
|
|
54
|
+
- **Status:** current
|
|
55
|
+
- **Canonical:** document `docs-site/upgrade.html`
|
|
56
|
+
- **Gotchas:** Frozen pre-v0.20 migration stays on the v0.59.0 hop. Current npm uses migrate:xbrief.
|
|
57
|
+
|
|
58
|
+
### Session start
|
|
59
|
+
- **Status:** current
|
|
60
|
+
- **Canonical:** command `session:start`
|
|
61
|
+
- **Gotchas:** Run before mutation. USER.md Personal wins. Read-only until implementation intent.
|
|
62
|
+
|
|
63
|
+
### Setup skill
|
|
64
|
+
- **Status:** current
|
|
65
|
+
- **Canonical:** skill-trigger `deft-directive-setup`
|
|
66
|
+
- **Gotchas:** Writes USER.md and PROJECT-DEFINITION. Confirm captured values before write.
|
|
67
|
+
|
|
68
|
+
### task check
|
|
69
|
+
- **Status:** current
|
|
70
|
+
- **Canonical:** command `check`
|
|
71
|
+
- **Gotchas:** Merge chokepoint. Iteration may use cheaper affected gates; do not skip this before PR.
|
|
72
|
+
|
|
73
|
+
## Maintainer
|
|
74
|
+
|
|
75
|
+
### Encoding gate (alias)
|
|
76
|
+
- **Status:** compatibility
|
|
77
|
+
- **Canonical:** command `verify:encoding`
|
|
78
|
+
- **Gotchas:** Alias owner is dispatch.ts VERB_ALIASES. Canonical engine verb is verify-encoding.
|
|
79
|
+
|
|
80
|
+
### Policy inspector
|
|
81
|
+
- **Status:** current
|
|
82
|
+
- **Canonical:** command `policy:show`
|
|
83
|
+
- **Gotchas:** Read namespaced plan["x-directive/policy"]. Bare plan.policy is a shadowing stop.
|
|
84
|
+
|
|
85
|
+
### Pre-PR skill
|
|
86
|
+
- **Status:** current
|
|
87
|
+
- **Canonical:** skill-trigger `deft-directive-pre-pr`
|
|
88
|
+
- **Gotchas:** Run before opening a PR. Always-pin process skill; not this capability index.
|
|
89
|
+
|
|
90
|
+
### Review-cycle skill
|
|
91
|
+
- **Status:** current
|
|
92
|
+
- **Canonical:** skill-trigger `deft-directive-review-cycle`
|
|
93
|
+
- **Gotchas:** Greptile residuals go through this skill. Host babysit/bugbot are advisory-only.
|
|
94
|
+
|
|
95
|
+
### Rule map
|
|
96
|
+
- **Status:** current
|
|
97
|
+
- **Canonical:** command `docs:rule-map`
|
|
98
|
+
- **Gotchas:** Generated maintainer view. Do not mint a second RULE-MAP. Refresh with task docs:rule-map.
|
|
99
|
+
|
|
100
|
+
### Swarm skill
|
|
101
|
+
- **Status:** current
|
|
102
|
+
- **Canonical:** skill-trigger `deft-directive-swarm`
|
|
103
|
+
- **Gotchas:** Drive-to merge-ready is the default story unit. Parent must not implement as the leaf.
|
|
104
|
+
|
|
105
|
+
## Frozen
|
|
106
|
+
|
|
107
|
+
### Frozen vBRIEF migrator
|
|
108
|
+
- **Status:** compatibility
|
|
109
|
+
- **Canonical:** command `migrate:vbrief`
|
|
110
|
+
- **Gotchas:** Current npm does not ship this verb. Pin v0.59.0 for hop 1, then migrate:xbrief.
|
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
{
|
|
2
|
+
"version": 1,
|
|
3
|
+
"issue": 4099,
|
|
4
|
+
"gotcha_max_chars": 280,
|
|
5
|
+
"entries": [
|
|
6
|
+
{
|
|
7
|
+
"id": "session-start",
|
|
8
|
+
"title": "Session start",
|
|
9
|
+
"audience": "consumer",
|
|
10
|
+
"status": "current",
|
|
11
|
+
"in_the_public_index": true,
|
|
12
|
+
"canonical_entry": { "kind": "command", "id": "session:start" },
|
|
13
|
+
"gotchas": "Run before mutation. USER.md Personal wins. Read-only until implementation intent."
|
|
14
|
+
},
|
|
15
|
+
{
|
|
16
|
+
"id": "check",
|
|
17
|
+
"title": "task check",
|
|
18
|
+
"audience": "consumer",
|
|
19
|
+
"status": "current",
|
|
20
|
+
"in_the_public_index": true,
|
|
21
|
+
"canonical_entry": { "kind": "command", "id": "check" },
|
|
22
|
+
"gotchas": "Merge chokepoint. Iteration may use cheaper affected gates; do not skip this before PR."
|
|
23
|
+
},
|
|
24
|
+
{
|
|
25
|
+
"id": "doctor",
|
|
26
|
+
"title": "Doctor",
|
|
27
|
+
"audience": "consumer",
|
|
28
|
+
"status": "current",
|
|
29
|
+
"in_the_public_index": true,
|
|
30
|
+
"canonical_entry": { "kind": "command", "id": "doctor" },
|
|
31
|
+
"gotchas": "Support entry is doctor --full or the README cold-start. Not a second recovery ladder."
|
|
32
|
+
},
|
|
33
|
+
{
|
|
34
|
+
"id": "init",
|
|
35
|
+
"title": "Install / init",
|
|
36
|
+
"audience": "consumer",
|
|
37
|
+
"status": "current",
|
|
38
|
+
"in_the_public_index": true,
|
|
39
|
+
"canonical_entry": { "kind": "command", "id": "init" },
|
|
40
|
+
"gotchas": "Consumer path is directive init. Do not send npm consumers through Corepack, Go, or uv."
|
|
41
|
+
},
|
|
42
|
+
{
|
|
43
|
+
"id": "setup-skill",
|
|
44
|
+
"title": "Setup skill",
|
|
45
|
+
"audience": "consumer",
|
|
46
|
+
"status": "current",
|
|
47
|
+
"in_the_public_index": true,
|
|
48
|
+
"canonical_entry": { "kind": "skill-trigger", "id": "deft-directive-setup" },
|
|
49
|
+
"gotchas": "Writes USER.md and PROJECT-DEFINITION. Confirm captured values before write."
|
|
50
|
+
},
|
|
51
|
+
{
|
|
52
|
+
"id": "build-skill",
|
|
53
|
+
"title": "Build skill",
|
|
54
|
+
"audience": "consumer",
|
|
55
|
+
"status": "current",
|
|
56
|
+
"in_the_public_index": true,
|
|
57
|
+
"canonical_entry": { "kind": "skill-trigger", "id": "deft-directive-build" },
|
|
58
|
+
"gotchas": "xbrief:preflight on an active running brief before code. Do not treat completed xBRIEFs as next-build contract."
|
|
59
|
+
},
|
|
60
|
+
{
|
|
61
|
+
"id": "docs-home",
|
|
62
|
+
"title": "Public docs home",
|
|
63
|
+
"audience": "consumer",
|
|
64
|
+
"status": "current",
|
|
65
|
+
"in_the_public_index": true,
|
|
66
|
+
"canonical_entry": { "kind": "document", "id": "docs-site/index.html" },
|
|
67
|
+
"gotchas": "Public IA lives under docs-site/. Do not mix it with maintainer docs/."
|
|
68
|
+
},
|
|
69
|
+
{
|
|
70
|
+
"id": "docs-install",
|
|
71
|
+
"title": "Public install page",
|
|
72
|
+
"audience": "consumer",
|
|
73
|
+
"status": "current",
|
|
74
|
+
"in_the_public_index": true,
|
|
75
|
+
"canonical_entry": { "kind": "document", "id": "docs-site/install.html" },
|
|
76
|
+
"gotchas": "Install copy stays on the consumer Node floor, not the maintainer toolchain pin."
|
|
77
|
+
},
|
|
78
|
+
{
|
|
79
|
+
"id": "docs-gates",
|
|
80
|
+
"title": "Public gates page",
|
|
81
|
+
"audience": "consumer",
|
|
82
|
+
"status": "current",
|
|
83
|
+
"in_the_public_index": true,
|
|
84
|
+
"canonical_entry": { "kind": "document", "id": "docs-site/gates.html" },
|
|
85
|
+
"gotchas": "task check is the merge chokepoint named here; do not invent a parallel public gate."
|
|
86
|
+
},
|
|
87
|
+
{
|
|
88
|
+
"id": "docs-concepts",
|
|
89
|
+
"title": "Public concepts page",
|
|
90
|
+
"audience": "consumer",
|
|
91
|
+
"status": "current",
|
|
92
|
+
"in_the_public_index": true,
|
|
93
|
+
"canonical_entry": { "kind": "document", "id": "docs-site/concepts.html" },
|
|
94
|
+
"gotchas": "Concepts page is a public IA surface. README/UPGRADING rewrites stay on #4100."
|
|
95
|
+
},
|
|
96
|
+
{
|
|
97
|
+
"id": "docs-upgrade",
|
|
98
|
+
"title": "Public upgrade page",
|
|
99
|
+
"audience": "consumer",
|
|
100
|
+
"status": "current",
|
|
101
|
+
"in_the_public_index": true,
|
|
102
|
+
"canonical_entry": { "kind": "document", "id": "docs-site/upgrade.html" },
|
|
103
|
+
"gotchas": "Frozen pre-v0.20 migration stays on the v0.59.0 hop. Current npm uses migrate:xbrief."
|
|
104
|
+
},
|
|
105
|
+
{
|
|
106
|
+
"id": "docs-license",
|
|
107
|
+
"title": "Public license page",
|
|
108
|
+
"audience": "consumer",
|
|
109
|
+
"status": "current",
|
|
110
|
+
"in_the_public_index": true,
|
|
111
|
+
"canonical_entry": { "kind": "document", "id": "docs-site/license.html" },
|
|
112
|
+
"gotchas": "License page is a docs-site surface, not a substitute for root LICENSE."
|
|
113
|
+
},
|
|
114
|
+
{
|
|
115
|
+
"id": "rule-map",
|
|
116
|
+
"title": "Rule map",
|
|
117
|
+
"audience": "maintainer",
|
|
118
|
+
"status": "current",
|
|
119
|
+
"in_the_public_index": true,
|
|
120
|
+
"canonical_entry": { "kind": "command", "id": "docs:rule-map" },
|
|
121
|
+
"gotchas": "Generated maintainer view. Do not mint a second RULE-MAP. Refresh with task docs:rule-map."
|
|
122
|
+
},
|
|
123
|
+
{
|
|
124
|
+
"id": "policy-show",
|
|
125
|
+
"title": "Policy inspector",
|
|
126
|
+
"audience": "maintainer",
|
|
127
|
+
"status": "current",
|
|
128
|
+
"in_the_public_index": true,
|
|
129
|
+
"canonical_entry": { "kind": "command", "id": "policy:show" },
|
|
130
|
+
"gotchas": "Read namespaced plan[\"x-directive/policy\"]. Bare plan.policy is a shadowing stop."
|
|
131
|
+
},
|
|
132
|
+
{
|
|
133
|
+
"id": "pre-pr-skill",
|
|
134
|
+
"title": "Pre-PR skill",
|
|
135
|
+
"audience": "maintainer",
|
|
136
|
+
"status": "current",
|
|
137
|
+
"in_the_public_index": true,
|
|
138
|
+
"canonical_entry": { "kind": "skill-trigger", "id": "deft-directive-pre-pr" },
|
|
139
|
+
"gotchas": "Run before opening a PR. Always-pin process skill; not this capability index."
|
|
140
|
+
},
|
|
141
|
+
{
|
|
142
|
+
"id": "review-cycle-skill",
|
|
143
|
+
"title": "Review-cycle skill",
|
|
144
|
+
"audience": "maintainer",
|
|
145
|
+
"status": "current",
|
|
146
|
+
"in_the_public_index": true,
|
|
147
|
+
"canonical_entry": { "kind": "skill-trigger", "id": "deft-directive-review-cycle" },
|
|
148
|
+
"gotchas": "Greptile residuals go through this skill. Host babysit/bugbot are advisory-only."
|
|
149
|
+
},
|
|
150
|
+
{
|
|
151
|
+
"id": "swarm-skill",
|
|
152
|
+
"title": "Swarm skill",
|
|
153
|
+
"audience": "maintainer",
|
|
154
|
+
"status": "current",
|
|
155
|
+
"in_the_public_index": true,
|
|
156
|
+
"canonical_entry": { "kind": "skill-trigger", "id": "deft-directive-swarm" },
|
|
157
|
+
"gotchas": "Drive-to merge-ready is the default story unit. Parent must not implement as the leaf."
|
|
158
|
+
},
|
|
159
|
+
{
|
|
160
|
+
"id": "verify-encoding",
|
|
161
|
+
"title": "Encoding gate (alias)",
|
|
162
|
+
"audience": "maintainer",
|
|
163
|
+
"status": "compatibility",
|
|
164
|
+
"in_the_public_index": true,
|
|
165
|
+
"canonical_entry": { "kind": "command", "id": "verify:encoding" },
|
|
166
|
+
"gotchas": "Alias owner is dispatch.ts VERB_ALIASES. Canonical engine verb is verify-encoding."
|
|
167
|
+
},
|
|
168
|
+
{
|
|
169
|
+
"id": "migrate-vbrief-frozen",
|
|
170
|
+
"title": "Frozen vBRIEF migrator",
|
|
171
|
+
"audience": "frozen",
|
|
172
|
+
"status": "compatibility",
|
|
173
|
+
"in_the_public_index": true,
|
|
174
|
+
"canonical_entry": { "kind": "command", "id": "migrate:vbrief" },
|
|
175
|
+
"gotchas": "Current npm does not ship this verb. Pin v0.59.0 for hop 1, then migrate:xbrief."
|
|
176
|
+
},
|
|
177
|
+
{
|
|
178
|
+
"id": "triage-skill-withdrawn",
|
|
179
|
+
"title": "Triage classify (withdrawn)",
|
|
180
|
+
"audience": "maintainer",
|
|
181
|
+
"status": "withdrawn",
|
|
182
|
+
"in_the_public_index": false,
|
|
183
|
+
"canonical_entry": { "kind": "skill-trigger", "id": "deft-directive-triage" },
|
|
184
|
+
"gotchas": "Classify playbook is off. Work selection is plan-sequence:current then triage:queue."
|
|
185
|
+
},
|
|
186
|
+
{
|
|
187
|
+
"id": "product-signal-consent",
|
|
188
|
+
"title": "Product-signal consent",
|
|
189
|
+
"audience": "consumer",
|
|
190
|
+
"status": "experimental",
|
|
191
|
+
"status_owner": "packages/core/src/product-signal",
|
|
192
|
+
"in_the_public_index": false,
|
|
193
|
+
"canonical_entry": { "kind": "command", "id": "product-signal:consent" },
|
|
194
|
+
"gotchas": "Off until the operator grants consent. Absence of consent is not a product verdict."
|
|
195
|
+
}
|
|
196
|
+
]
|
|
197
|
+
}
|
package/docs/getting-started.md
CHANGED
|
@@ -1,25 +1,28 @@
|
|
|
1
1
|
# Getting Started with Deft Directive
|
|
2
2
|
|
|
3
|
-
Deft Directive is a Taskfile-first framework for AI-assisted software work. It combines agent guidance, deterministic gates, xBRIEF lifecycle metadata, installer/doctor handoff, and cache-backed backlog workflows. This guide
|
|
3
|
+
Deft Directive is a Taskfile-first framework for AI-assisted software work. It combines agent guidance, deterministic gates, xBRIEF lifecycle metadata, installer/doctor handoff, and cache-backed backlog workflows. This guide is the **first-project long form**: one path from install through a green Directive check.
|
|
4
4
|
|
|
5
|
-
> **Note**:
|
|
5
|
+
> **Note**: For a single-picture mental model of how Directive turns an idea into shipped work, see [the Directive lifecycle](./directive-lifecycle.md). For command behavior, see [commands.md](../commands.md). Agent detect-state and recovery live in [QUICK-START.md](../QUICK-START.md). This page is that path's long form, not a second install sequence.
|
|
6
6
|
|
|
7
7
|
## The shape of the workflow
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Directive is two connected phases that repeat: an **inception** phase (Concept → Strategy Analysis → Specification + Artifacts) that feeds a recurring **per-session** phase (Session Start → Triage/Refine → Slice → Swarm → Review/Fix → Ship). Shipping surfaces new issues that flow back into the queue. The stage-to-command mapping lives in [the Directive lifecycle overview](./directive-lifecycle.md).
|
|
10
10
|
|
|
11
11
|
## Deft & Directive (naming)
|
|
12
12
|
|
|
13
13
|
**Deft is the company; Directive is the product.** *Deft* names the organization and the on-disk footprint (`.deft/`, `@deftai/*` npm scope, user config under `~/.config/deft/`). *Directive* names the framework you install and run: the npm package is `@deftai/directive`, and the primary CLI is `directive` (`deft` is an alias). Legacy `deft-install` / `deft` paths in this guide refer to the same product during the staged transition ([#423](https://github.com/deftai/directive/issues/423)).
|
|
14
14
|
|
|
15
|
+
Public consumer commands on this page use `directive` / `deft`. After `directive init`, the root Taskfile is include-only, so `task deft:<verb>` is the namespaced Task equivalent. Do not copy bare `task <verb>` from the framework source tree into a new project.
|
|
16
|
+
|
|
15
17
|
---
|
|
16
18
|
|
|
17
19
|
## Prerequisites
|
|
18
20
|
|
|
19
|
-
- **Node 20
|
|
20
|
-
-
|
|
21
|
-
-
|
|
22
|
-
|
|
21
|
+
- **Node 20+**, **Git**, and **GitHub CLI (`gh`)**.
|
|
22
|
+
- The package manager you use to install Directive (`npm` is bundled with Node; pnpm is an alternative).
|
|
23
|
+
- After install, confirm with `directive toolchain:check --consumer`. That probe checks Node, git, gh, and the selected manager. It does not require Python, uv, Go, or Task.
|
|
24
|
+
|
|
25
|
+
**Go 1.22+** is only for the frozen Go installer or a source build. Framework maintainers of this repository use a separate Node 24 pin; see [CONTRIBUTING.md](../../CONTRIBUTING.md).
|
|
23
26
|
|
|
24
27
|
---
|
|
25
28
|
|
|
@@ -27,7 +30,7 @@ Before the mechanics below, it helps to see the whole loop. Directive is two con
|
|
|
27
30
|
|
|
28
31
|
### npm (canonical)
|
|
29
32
|
|
|
30
|
-
|
|
33
|
+
Install Directive globally from npm:
|
|
31
34
|
|
|
32
35
|
```bash
|
|
33
36
|
npm i -g @deftai/directive
|
|
@@ -44,6 +47,8 @@ npx @deftai/directive session:start
|
|
|
44
47
|
|
|
45
48
|
This npm path has been the canonical distribution channel since v0.55.1. A pnpm-managed repository can install the same package with `pnpm add -g @deftai/directive` or project-locally with `pnpm add -D @deftai/directive`.
|
|
46
49
|
|
|
50
|
+
**Success:** `directive --version` prints a version. **Recovery:** run `directive doctor` and follow its one `Next command:`. Agent detect-state cases live in [QUICK-START.md](../QUICK-START.md).
|
|
51
|
+
|
|
47
52
|
### Go installer (legacy bridge)
|
|
48
53
|
|
|
49
54
|
The Go installer is a frozen legacy bridge for older installs and source-oriented recovery. New consumer installs should use npm above; see [UPGRADING.md](../UPGRADING.md#one-time-migration-from-the-go-installer-legacy--npm) when migrating an existing Go-installer layout.
|
|
@@ -60,86 +65,163 @@ For existing consumer projects, the headless upgrade path is:
|
|
|
60
65
|
deft-install --yes --upgrade --repo-root . --json
|
|
61
66
|
```
|
|
62
67
|
|
|
63
|
-
Those consumer flows
|
|
64
|
-
root (`AGENTS.md`, skills pointers, gitignore entries, xbrief scaffolding, and
|
|
65
|
-
related guard configuration). Framework maintainers working inside a
|
|
66
|
-
`deftai/directive` checkout should instead follow
|
|
67
|
-
[`CONTRIBUTING.md`](../../CONTRIBUTING.md) and use `--maintainer`; maintainer setup
|
|
68
|
-
checks tools without rewriting consumer-managed files.
|
|
68
|
+
Those consumer flows project Deft-managed files into your project root (`AGENTS.md`, skills pointers, gitignore entries, xbrief scaffolding, and related guard configuration). Framework maintainers working inside a `deftai/directive` checkout should instead follow [`CONTRIBUTING.md`](../../CONTRIBUTING.md) and use `--maintainer`; maintainer setup checks tools without rewriting consumer-managed files.
|
|
69
69
|
|
|
70
70
|
---
|
|
71
71
|
|
|
72
72
|
## First Project
|
|
73
73
|
|
|
74
|
-
|
|
74
|
+
This is one executable journey. It is a human projection of the setup skill plus the lifecycle bridge. Agents still follow `skills/deft-directive-setup/SKILL.md`. Do not treat this list as a third procedure beside QUICK-START.
|
|
75
75
|
|
|
76
|
-
|
|
76
|
+
The endpoint is **Directive control plane ready**: an active scope passes story-ready and preflight, and `deft check` exits 0. Product implementation comes next. This page does not build a sample app.
|
|
77
77
|
|
|
78
|
-
|
|
78
|
+
### 1. Install the CLI
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
npm i -g @deftai/directive
|
|
82
|
+
directive --version
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
**Success:** a version string. **Recovery:** `directive doctor`.
|
|
86
|
+
|
|
87
|
+
### 2. Create a Git repository, then init
|
|
79
88
|
|
|
80
|
-
|
|
89
|
+
`directive init` deposits files. It does not create a Git repository. `deft verify:story-ready` and `deft check` both require a Git worktree. Start in an empty project directory:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
mkdir my-project && cd my-project
|
|
93
|
+
git init
|
|
94
|
+
directive init
|
|
95
|
+
```
|
|
81
96
|
|
|
82
|
-
|
|
97
|
+
`init` writes the vendored deposit into gitignored `.deft/core/`, renders `AGENTS.md`, scaffolds `xbrief/` lifecycle folders, and adds an include-only root `Taskfile.yml`. Tracked vs ignored: the reconstitutable deposit and session cache are ignored; your `package.json` pin stays tracked.
|
|
83
98
|
|
|
84
|
-
|
|
99
|
+
**Success:** `.deft/core/` and `AGENTS.md` exist. **Recovery:** `directive doctor` (one `Next command:`).
|
|
85
100
|
|
|
86
|
-
|
|
101
|
+
### 3. Doctor
|
|
87
102
|
|
|
88
103
|
```bash
|
|
89
|
-
|
|
104
|
+
directive doctor
|
|
90
105
|
```
|
|
91
106
|
|
|
92
|
-
|
|
107
|
+
Doctor is read-only. When the install is healthy it prints `System check passed!`. When action is required it prints exactly one `Next command:` with a root-cause line.
|
|
93
108
|
|
|
94
|
-
|
|
95
|
-
- `--state {open|closed|all}` selects the issue state (default `open`).
|
|
96
|
-
- `--batch-size <N>` caps the per-page fetch (default `10`).
|
|
97
|
-
- `--delay-ms <N>` inserts a sleep between batches so a populate against a large repo does not trip the rate limiter (default `500`; a `429` retries automatically using the upstream `Retry-After` header).
|
|
98
|
-
- `--repo OWNER/NAME` is optional; when omitted, the bootstrap infers the slug from `git remote get-url origin`.
|
|
109
|
+
**Success:** `System check passed!` **Recovery:** run the printed `Next command:`. Detect-state ladders stay in [QUICK-START.md](../QUICK-START.md).
|
|
99
110
|
|
|
100
|
-
|
|
111
|
+
### 4. USER.md and project definition
|
|
101
112
|
|
|
102
|
-
|
|
113
|
+
User preferences live outside the repo:
|
|
103
114
|
|
|
104
|
-
|
|
115
|
+
- Unix / macOS: `~/.config/deft/USER.md`
|
|
116
|
+
- Windows: `%APPDATA%\deft\USER.md`
|
|
117
|
+
- Override: `DEFT_USER_PATH`
|
|
105
118
|
|
|
119
|
+
Project identity lives in `xbrief/PROJECT-DEFINITION.xbrief.json`. Greenfield setup does not create `specification.xbrief.json`.
|
|
120
|
+
|
|
121
|
+
Tell your agent to follow `AGENTS.md`, or run `directive bootstrap`. That hands off to the setup skill. The skill asks one question at a time and **must not write files until you confirm** the captured values (`yes` / `confirmed` / `approve`). Promotion and activation are later commitments, not automatic setup continuation.
|
|
122
|
+
|
|
123
|
+
**Success:** `USER.md` exists at the platform path and `xbrief/PROJECT-DEFINITION.xbrief.json` exists. **Recovery:** `directive doctor`, then re-enter setup. Do not skip the confirmation gate.
|
|
124
|
+
|
|
125
|
+
### 5. First proposed scope
|
|
126
|
+
|
|
127
|
+
Setup Phase 3 writes the first scope xBRIEF to `xbrief/proposed/` with `plan.status: proposed`. Filename shape: `YYYY-MM-DD-descriptive-slug.xbrief.json`. New writes use `"xBRIEFInfo": { "version": "0.8" }`.
|
|
128
|
+
|
|
129
|
+
**Success:** one file in `xbrief/proposed/`. **Recovery:** `directive doctor`. If setup stopped early, resume the setup skill; do not hand-copy a completed xBRIEF as the next-build contract.
|
|
130
|
+
|
|
131
|
+
### 6. Git: feature branch and a clean tree
|
|
132
|
+
|
|
133
|
+
Story-ready fails when the tree is not Git, when it is dirty, or when you are on the default branch under the default branch policy. Commit the generated setup artifacts, then leave `master` / `main`:
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
git add AGENTS.md Taskfile.yml xbrief .gitignore
|
|
137
|
+
git commit -m "chore: deposit Directive and first proposed scope"
|
|
138
|
+
git switch -c feat/first-project
|
|
139
|
+
deft verify:branch
|
|
106
140
|
```
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
141
|
+
|
|
142
|
+
`--allow-dirty` on story-ready is an intentional exception, not the happy path.
|
|
143
|
+
|
|
144
|
+
**Success:** `deft verify:branch` exits 0 on the feature branch. **Recovery:** create a feature branch; commit or stash leftover files; then `directive doctor`.
|
|
145
|
+
|
|
146
|
+
### 7. Promote, then activate
|
|
147
|
+
|
|
148
|
+
These are two separate user commitments. Setup does not auto-run them.
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
deft scope:promote -- xbrief/proposed/<file>.xbrief.json
|
|
152
|
+
deft scope:activate -- xbrief/pending/<file>.xbrief.json
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Promote moves proposed → pending. Activate moves pending → `xbrief/active/` and sets `plan.status` to `running`. Both commands are idempotent.
|
|
156
|
+
|
|
157
|
+
**Success:** the file is in `xbrief/active/` with `plan.status` `running`. **Recovery:** `directive doctor`. If activate says the file must be in `pending/`, run promote first.
|
|
158
|
+
|
|
159
|
+
Promote and activate move a tracked xBRIEF. Commit that change before story-ready. A dirty tree fails the next gate.
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
git add xbrief
|
|
163
|
+
git commit -m "chore: activate first scope"
|
|
114
164
|
```
|
|
115
165
|
|
|
116
|
-
|
|
166
|
+
### 8. Story-ready and preflight
|
|
117
167
|
|
|
118
|
-
|
|
168
|
+
```bash
|
|
169
|
+
deft verify:story-ready --vbrief-path xbrief/active/<file>.xbrief.json
|
|
170
|
+
deft xbrief:preflight -- xbrief/active/<file>.xbrief.json
|
|
171
|
+
```
|
|
119
172
|
|
|
120
|
-
|
|
173
|
+
`--vbrief-path` is the shipped story-ready flag (the file is still a `.xbrief.json`). Preflight exits 0 only when the candidate lives in `xbrief/active/` and `plan.status` is `running`.
|
|
121
174
|
|
|
122
|
-
|
|
123
|
-
- **Audit log** — `xbrief/.eval/candidates.jsonl` is an append-only JSONL recording every candidate you have ever seen plus the action taken (`accept | reject | defer | needs-ac | mark-duplicate`) and a timestamp. Re-running triage against the same cache short-circuits items that already have a terminal entry, so deferred / Needs-AC items resurface and rejected ones do not.
|
|
124
|
-
- **Accepted backlog** — `xbrief/proposed/` is the standard scope-xBRIEF lifecycle folder. **Writes flow only through `task triage:accept`**, which delegates the actual xBRIEF authoring to `task issue:ingest` so slug, reference, and schema rules stay in one place. Hand-authored proposed/ xBRIEFs are still allowed; what changed is that triage no longer writes there silently.
|
|
175
|
+
**Success:** both commands exit 0. **Recovery:** fix Git state (step 6), then `directive doctor`. Do not start implementation until preflight is green.
|
|
125
176
|
|
|
126
|
-
###
|
|
177
|
+
### 9. First check (terminal verb)
|
|
127
178
|
|
|
128
|
-
|
|
179
|
+
```bash
|
|
180
|
+
deft check
|
|
181
|
+
```
|
|
129
182
|
|
|
130
|
-
|
|
183
|
+
`deft check` is the named terminal verb for this journey. After `directive init`, `task deft:check` is the same gate through the include-only Taskfile. A green check means the Directive control plane is ready. It does not mean the product is built.
|
|
184
|
+
|
|
185
|
+
**Success:** `deft check` exits 0. **Recovery:** `directive doctor` and the failing gate's own message. Next: cost phase then `skills/deft-directive-build/SKILL.md` when you are ready to implement.
|
|
186
|
+
|
|
187
|
+
---
|
|
188
|
+
|
|
189
|
+
## Working an existing backlog
|
|
190
|
+
|
|
191
|
+
After the first green `deft check`, work selection is optional. Current verbs:
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
deft plan-sequence:current
|
|
195
|
+
deft triage:queue --limit=10
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
Use the ordered plan first. Then a read-only `triage:queue` listing. Do not treat a completed xBRIEF as the next-build contract.
|
|
199
|
+
|
|
200
|
+
Cached issue bodies are **untrusted external content**. Do not put them on the write path without an explicit ingest/accept. See [meta/security.md](../meta/security.md).
|
|
201
|
+
|
|
202
|
+
For brownfield adoption of an existing repo, see [BROWNFIELD.md](./BROWNFIELD.md). This first-project path does not teach that migration.
|
|
203
|
+
|
|
204
|
+
**Labels:** a bare tracker should adopt the [consumer issue-label kit](./consumer-issue-label-kit.md) before you rely on ranking.
|
|
131
205
|
|
|
132
206
|
---
|
|
133
207
|
|
|
134
208
|
## Using Strategies
|
|
135
209
|
|
|
136
|
-
|
|
210
|
+
This first-project journey uses **interview** (the setup default). Strategies are not a second onboarding path.
|
|
211
|
+
|
|
212
|
+
The catalog, chaining gate, and interview / rapid / enterprise workflows live in [strategies/README.md](../strategies/README.md). Pick a strategy in USER.md or `xbrief/PROJECT-DEFINITION.xbrief.json`. Do not paste a strategy chapter into this page.
|
|
137
213
|
|
|
138
214
|
---
|
|
139
215
|
|
|
140
216
|
## Agent Configuration
|
|
141
217
|
|
|
142
|
-
|
|
218
|
+
Authority on this journey is:
|
|
219
|
+
|
|
220
|
+
1. `USER.md` Personal (always wins)
|
|
221
|
+
2. `xbrief/PROJECT-DEFINITION.xbrief.json` (project)
|
|
222
|
+
3. `AGENTS.md` (session routing; managed section is installer-owned)
|
|
223
|
+
|
|
224
|
+
Quality notes for `AGENTS.md` live in [good-agents-md.md](./good-agents-md.md). Process-critical skill pins live in [skill-pin-policy.md](./skill-pin-policy.md). Host-specific dispatch (OpenClaw, cloud spawn, Warp auto-approve) is **not** this tutorial. Setup already warns that Warp auto-approve can silently answer interview questions.
|
|
143
225
|
|
|
144
226
|
**OpenClaw:** If your agent host is OpenClaw (persistent-memory agents, Control UI, `sessions_spawn`), read [openclaw-agent-host.md](./openclaw-agent-host.md) for the host mental model, executable babysit path (installed skills), and the epic babysit → `sessions_spawn` Approach 1 expectation. Skill gate text remains in `deft-directive-review-cycle` / `deft-directive-swarm` — the host doc only points.
|
|
145
227
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@deftai/directive-content",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.112.0",
|
|
4
4
|
"deftConsumerDeposit": true,
|
|
5
5
|
"description": "Shippable Directive framework content in the consumer .deft/core/ layout (C1 flatten), plus the engine surfaces (.githooks/, Taskfile.yml, tasks/) the deposit wires. Python-free per #2022 Phase 3. Refs #11, #1669, #1967.",
|
|
6
6
|
"license": "MIT",
|