development-companion 1.2.1 → 1.4.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/README.md +53 -32
- package/RELEASE.md +12 -9
- package/adapters/README.md +10 -2
- package/adapters/opencode/README.md +29 -32
- package/core/principles.md +21 -0
- package/core/process.md +126 -159
- package/core/quality-gates.md +21 -13
- package/core/roles/team-lead.md +50 -30
- package/core/workflow.md +16 -3
- package/package.json +1 -1
- package/skills/architecture-design/SKILL.md +7 -0
- package/skills/delivery-orchestration/SKILL.md +65 -67
- package/skills/development-workflow/SKILL.md +2 -0
- package/skills/incremental-delivery/SKILL.md +116 -0
- package/skills/project-discovery/SKILL.md +23 -3
- package/skills/test-strategy/SKILL.md +7 -2
- package/skills/ux-design/SKILL.md +43 -11
- package/src/cli.mjs +78 -26
- package/src/content.mjs +1 -0
- package/src/install.mjs +40 -33
- package/src/rules.mjs +31 -5
- package/templates/artifacts/01-operational-brief.md +17 -3
- package/templates/artifacts/06-delivery-plan.md +26 -5
- package/templates/rules/AGENTS.block.md +49 -18
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Development Companion
|
|
2
2
|
|
|
3
|
-
One installable development process for AI coding agents: **12 roles**, **
|
|
3
|
+
One installable development process for AI coding agents: **12 roles**, **18 skills**, and
|
|
4
4
|
a CLI that adapts the same canonical base to OpenCode, Claude Code, Codex, Pi, and other
|
|
5
5
|
harnesses.
|
|
6
6
|
|
|
@@ -11,6 +11,12 @@ npx development-companion@latest init
|
|
|
11
11
|
`devcomp init` detects the repository and harness, installs the process, and leaves your
|
|
12
12
|
existing `AGENTS.md` and `CLAUDE.md` intact unless you choose otherwise.
|
|
13
13
|
|
|
14
|
+
Run `devcomp doctor` **from the repository opened by the agent**. If you work in a nested
|
|
15
|
+
repository, install there too: its own `AGENTS.md` and agent configuration may take precedence.
|
|
16
|
+
`init --yes` preserves existing rules; `doctor` fails when those rules do not activate the
|
|
17
|
+
process. Ask the harness agent to merge existing rules, or use `init --rules handoff` for a
|
|
18
|
+
backed-up, explicitly pending merge. `--rules append` remains available for compatible rules.
|
|
19
|
+
|
|
14
20
|
## Why
|
|
15
21
|
|
|
16
22
|
Coding agents are powerful but inconsistent. Each harness has its own rules file, skill
|
|
@@ -56,7 +62,7 @@ npx development-companion init . \
|
|
|
56
62
|
| `--harness <name>` | Force the adapter; `auto` detects it. |
|
|
57
63
|
| `--profile <name>` | `web`, `backend`, `mobile`, `desktop`, `cross-platform`, `full`. |
|
|
58
64
|
| `--skills <a,b>` | Add specific skills. |
|
|
59
|
-
| `--rules keep\|append\|replace` | Policy for existing `AGENTS.md
|
|
65
|
+
| `--rules keep\|append\|handoff\|replace` | Policy for existing rules; `handoff` backs up `AGENTS.md` for agent-led merge. |
|
|
60
66
|
| `--branching <name>` | `gitflow`, `gitlab-flow`, `trunk-based`, `github-flow`, `custom`. |
|
|
61
67
|
| `--docs local\|tracked` | Keep design docs local or version them in `docs/companion/`. |
|
|
62
68
|
| `--memory engram\|none` | Recommend Engram for cross-session memory. |
|
|
@@ -70,7 +76,11 @@ If `AGENTS.md` or `CLAUDE.md` already exists, the CLI asks:
|
|
|
70
76
|
|
|
71
77
|
- **keep** — leave the file untouched;
|
|
72
78
|
- **append** — add a managed block, preserving your rules;
|
|
73
|
-
- **
|
|
79
|
+
- **handoff** — back up `AGENTS.md` under `.companion/local/rules-backup/`, write a
|
|
80
|
+
pending-merge notice and the process block; `doctor` fails until an agent merges
|
|
81
|
+
project-specific rules and removes the notice. Existing `CLAUDE.md` is kept.
|
|
82
|
+
- **replace** — replace the file, with explicit confirmation and a local backup;
|
|
83
|
+
`AGENTS.md` still requires a reviewed merge of the original before work begins.
|
|
74
84
|
|
|
75
85
|
The managed block is delimited by `<!-- development-companion:start -->` and
|
|
76
86
|
`<!-- development-companion:end -->`, so updates are idempotent.
|
|
@@ -87,26 +97,23 @@ The managed block is delimited by `<!-- development-companion:start -->` and
|
|
|
87
97
|
|
|
88
98
|
## The process
|
|
89
99
|
|
|
90
|
-
|
|
100
|
+
The process exists to ship working software, not to produce documents. It is a loop:
|
|
91
101
|
|
|
92
102
|
```text
|
|
93
103
|
0 Bootstrap
|
|
94
|
-
→ 1
|
|
95
|
-
→ 2
|
|
96
|
-
→ 3
|
|
97
|
-
→ 4
|
|
98
|
-
→ 5
|
|
99
|
-
→ 6
|
|
100
|
-
→ 7 Security verification (Cybersecurity)
|
|
101
|
-
→ 8 QA verification (QA)
|
|
102
|
-
→ 9 Deployment (SRE)
|
|
103
|
-
→ 10 Closure (Team Lead)
|
|
104
|
+
→ 1 Frame (one page, 30–60 min)
|
|
105
|
+
→ 2 Walking skeleton (end-to-end, fakes allowed)
|
|
106
|
+
→ 3 Slice loop (build → test → demo → next)
|
|
107
|
+
→ 4 Verify (security + QA, continuous)
|
|
108
|
+
→ 5 Release
|
|
109
|
+
→ 6 Close
|
|
104
110
|
```
|
|
105
111
|
|
|
106
|
-
|
|
107
|
-
|
|
112
|
+
Planning artifacts are living notes written just in time, not phase gates. The first commit
|
|
113
|
+
lands before the second design document. See `core/process.md` and the `incremental-delivery`
|
|
114
|
+
skill.
|
|
108
115
|
|
|
109
|
-
|
|
116
|
+
For a small change, the process collapses to the workflow in `core/workflow.md`.
|
|
110
117
|
|
|
111
118
|
## Roles
|
|
112
119
|
|
|
@@ -127,21 +134,19 @@ Read `core/process.md` for the full phase guide.
|
|
|
127
134
|
|
|
128
135
|
Role contracts live in `core/roles/`. The CLI installs them to `.companion/roles/` and
|
|
129
136
|
generates native bindings where the harness supports subagents.
|
|
137
|
+
The canonical principles, process, workflow, quality gates, and guidelines are installed in
|
|
138
|
+
`.companion/core/`. The generated rules and agent bindings reference these files.
|
|
130
139
|
|
|
131
140
|
### Orchestration in OpenCode
|
|
132
141
|
|
|
133
|
-
`devcomp init`
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
`default_agent`
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
`.companion/local/**` and `docs/companion/**`, and denies `shell`; it must launch a
|
|
142
|
-
specialist for code, commands, tests, security, UX, or deployment. Specialists deny the
|
|
143
|
-
`subagent` permission, so only the team lead orchestrates. Existing sessions keep their
|
|
144
|
-
previous agent; start a new session to pick up `team-lead`.
|
|
142
|
+
`devcomp init` preserves OpenCode's native Build default and any existing OpenCode config.
|
|
143
|
+
The native primary follows the Team Lead delivery contract from `AGENTS.md` and retains
|
|
144
|
+
its harness skills, shell, edit and delegation tools. `team-lead` and the 11 specialists
|
|
145
|
+
are callable subagents; invoke the dedicated lead for substantial coordination, not every
|
|
146
|
+
routine slice. Its own binding denies edits outside local design notes and denies shell.
|
|
147
|
+
`devcomp doctor` fails on the old `default_agent: "team-lead"` and primary-only binding:
|
|
148
|
+
review local customizations, update the binding explicitly, remove that default (or select
|
|
149
|
+
`build`), and start a new session. The CLI will not overwrite existing config or bindings.
|
|
145
150
|
|
|
146
151
|
## Skills and profiles
|
|
147
152
|
|
|
@@ -149,7 +154,7 @@ Process skills are installed always:
|
|
|
149
154
|
|
|
150
155
|
`project-discovery`, `architecture-design`, `test-strategy`, `ux-design`,
|
|
151
156
|
`delivery-orchestration`, `security-review`, `deployment-sre`, `development-workflow`,
|
|
152
|
-
`code-review`.
|
|
157
|
+
`incremental-delivery`, `code-review`.
|
|
153
158
|
|
|
154
159
|
Domain skills are installed by profile:
|
|
155
160
|
|
|
@@ -165,20 +170,31 @@ Domain skills are installed by profile:
|
|
|
165
170
|
Every skill is self-contained and follows the [Agent Skills](https://agentskills.io)
|
|
166
171
|
specification.
|
|
167
172
|
|
|
173
|
+
For UI design the agent offers local HTML/SVG, an existing Figma MCP, or FigCraft
|
|
174
|
+
CLI if available. The CLI does not install third-party tools or handle Figma tokens.
|
|
175
|
+
The `ux-design` skill explains how to find the official FigCraft CLI download, create
|
|
176
|
+
editable files and exercise a clickable prototype in Play before approving the design.
|
|
177
|
+
|
|
168
178
|
## Harness support
|
|
169
179
|
|
|
170
180
|
| Tier | Harnesses | Commitment |
|
|
171
181
|
|---|---|---|
|
|
172
|
-
| 1 | OpenCode, Claude Code, Codex, Pi |
|
|
182
|
+
| 1 | OpenCode, Claude Code, Codex, Pi | Installation targets; behavioral validation required per release |
|
|
173
183
|
| 2 | Cursor, Gemini CLI, Copilot CLI, Windsurf, Cline | Best-effort, generated |
|
|
174
184
|
| 3 | Any harness that reads `AGENTS.md` or accepts a prompt pack | Generic fallback |
|
|
175
185
|
|
|
176
186
|
Adapters are data: rules file, skills directory, agent directory, and limitations.
|
|
187
|
+
Installation checks do not prove that a model followed the workflow. Claude Code and Codex
|
|
188
|
+
provide specialist bindings but do not automatically start in a team-lead role; invoke it
|
|
189
|
+
explicitly when orchestration is needed. Pi has no native subagents and must run the role
|
|
190
|
+
workflow in one session or through a user-supplied extension. Validate real agent behavior
|
|
191
|
+
in each harness before claiming process compliance.
|
|
177
192
|
|
|
178
193
|
## Local design documents
|
|
179
194
|
|
|
180
195
|
By default, discovery, architecture, test plans, evidence, and reports live in
|
|
181
|
-
`.companion/local/`, which is ignored by git.
|
|
196
|
+
`.companion/local/`, which is ignored by git. The manifest, installed core documents,
|
|
197
|
+
roles, and skills can be tracked; the design notes remain local unless opted in.
|
|
182
198
|
|
|
183
199
|
If you want the design to travel with the repository:
|
|
184
200
|
|
|
@@ -188,6 +204,8 @@ npx development-companion init . --docs tracked
|
|
|
188
204
|
|
|
189
205
|
That moves the artifacts to `docs/companion/`.
|
|
190
206
|
|
|
207
|
+
This configured path overrides default `.companion/local/` examples in role and skill files.
|
|
208
|
+
|
|
191
209
|
## Memory: Engram (optional)
|
|
192
210
|
|
|
193
211
|
The process works without memory. If Engram is available, it stores decisions, findings,
|
|
@@ -242,6 +260,9 @@ and Playwright tests. Screenshots, command logs, process artifacts, and `report.
|
|
|
242
260
|
written to `plannification/validation/e2e-expense/<iteration>/` (gitignored). The workdir
|
|
243
261
|
stays for inspection; the next run deletes it.
|
|
244
262
|
|
|
263
|
+
This exercises installation and a prebuilt app fixture; it does **not** launch a coding agent
|
|
264
|
+
or prove it followed instructions. Behavioral validation requires separate agent sessions.
|
|
265
|
+
|
|
245
266
|
## Repository layout
|
|
246
267
|
|
|
247
268
|
```text
|
package/RELEASE.md
CHANGED
|
@@ -43,7 +43,7 @@ npm pack --pack-destination "$packdir"
|
|
|
43
43
|
app=$(mktemp -d)
|
|
44
44
|
cd "$app"
|
|
45
45
|
npm init -y
|
|
46
|
-
npm install "$packdir"/development-companion-1.
|
|
46
|
+
npm install "$packdir"/development-companion-1.4.0.tgz
|
|
47
47
|
./node_modules/.bin/devcomp --version
|
|
48
48
|
./node_modules/.bin/devcomp init . --yes --harness opencode --profile web
|
|
49
49
|
./node_modules/.bin/devcomp doctor .
|
|
@@ -71,7 +71,7 @@ republish immediately. Wait a few minutes and verify:
|
|
|
71
71
|
npm view development-companion version dist-tags
|
|
72
72
|
```
|
|
73
73
|
|
|
74
|
-
The `latest` tag must point to `1.
|
|
74
|
+
The `latest` tag must point to `1.4.0`, not `0.0.0-stage`. If it still points to the
|
|
75
75
|
placeholder after several minutes, check the npmjs.com package page and the Staged
|
|
76
76
|
Packages tab before retrying.
|
|
77
77
|
|
|
@@ -79,9 +79,9 @@ Packages tab before retrying.
|
|
|
79
79
|
|
|
80
80
|
```bash
|
|
81
81
|
cd "$(mktemp -d)"
|
|
82
|
-
npx development-companion@1.
|
|
83
|
-
npx development-companion@1.
|
|
84
|
-
npx development-companion@1.
|
|
82
|
+
npx development-companion@1.4.0 --version
|
|
83
|
+
npx development-companion@1.4.0 init . --yes --harness opencode --profile web
|
|
84
|
+
npx development-companion@1.4.0 doctor .
|
|
85
85
|
```
|
|
86
86
|
|
|
87
87
|
Also verify the package page:
|
|
@@ -93,18 +93,21 @@ https://www.npmjs.com/package/development-companion
|
|
|
93
93
|
## 6. Tag and publish the source release
|
|
94
94
|
|
|
95
95
|
```bash
|
|
96
|
-
git tag -a v1.
|
|
96
|
+
git tag -a v1.4.0 -m "v1.4.0"
|
|
97
97
|
git push origin main --tags
|
|
98
98
|
```
|
|
99
99
|
|
|
100
100
|
Create the release on Codeberg:
|
|
101
101
|
|
|
102
102
|
```text
|
|
103
|
-
https://codeberg.org/rockmadehome/development-companion/releases/new?tag=v1.
|
|
103
|
+
https://codeberg.org/rockmadehome/development-companion/releases/new?tag=v1.4.0
|
|
104
104
|
```
|
|
105
105
|
|
|
106
|
-
Include the install command,
|
|
107
|
-
|
|
106
|
+
Include the install command, supported harness tiers and migration from 1.3.0:
|
|
107
|
+
OpenCode no longer selects `team-lead` as primary; existing projects must review and
|
|
108
|
+
update their old binding and `default_agent` explicitly. `--rules handoff` creates a
|
|
109
|
+
local backup and blocks `doctor` until a human-reviewed merge. Do not commit pending
|
|
110
|
+
rules while their backup exists only on the installing machine.
|
|
108
111
|
|
|
109
112
|
## 7. If something is wrong
|
|
110
113
|
|
package/adapters/README.md
CHANGED
|
@@ -12,12 +12,16 @@ npx development-companion@latest init --harness <name>
|
|
|
12
12
|
The CLI reads `adapters/<name>/adapter.json`, installs skills into the adapter's skills
|
|
13
13
|
directory, writes `AGENTS.md`/`CLAUDE.md` with keep/append/replace, and generates native
|
|
14
14
|
agent bindings where the harness supports them.
|
|
15
|
+
It also installs canonical process documents in `.companion/core/`. Run `devcomp doctor`
|
|
16
|
+
from the agent's workspace (including nested repositories). A preserved rules file without
|
|
17
|
+
the companion block or a pending rules merge is a failure, not proof of an active installation.
|
|
18
|
+
OpenCode retains its native primary agent; legacy `default_agent: team-lead` needs migration.
|
|
15
19
|
|
|
16
20
|
## Support tiers
|
|
17
21
|
|
|
18
22
|
| Tier | Harness | Commitment |
|
|
19
23
|
|---|---|---|
|
|
20
|
-
| 1 | OpenCode, Claude Code, Codex, Pi | Installation and discovery
|
|
24
|
+
| 1 | OpenCode, Claude Code, Codex, Pi | Installation and discovery targets; verify behavior in a real agent session |
|
|
21
25
|
| 2 | Cursor, Gemini CLI, Copilot CLI, Windsurf, Cline | Best-effort adapter; verify against the installed version |
|
|
22
26
|
| 3 | Any other harness | `AGENTS.md` + skills copy or prompt pack |
|
|
23
27
|
|
|
@@ -57,7 +61,9 @@ Each adapter declares its paths and limitations:
|
|
|
57
61
|
- If they exist, the CLI asks **keep**, **append**, or **replace**.
|
|
58
62
|
- `append` uses a managed block with
|
|
59
63
|
`<!-- development-companion:start -->` / `<!-- development-companion:end -->`.
|
|
60
|
-
- `
|
|
64
|
+
- `handoff` backs up original `AGENTS.md` locally and writes a pending-merge notice;
|
|
65
|
+
the harness agent must merge business and framework rules before `doctor` passes.
|
|
66
|
+
- `replace` requires explicit confirmation or `--force` and also preserves a local backup.
|
|
61
67
|
- `--yes` defaults to `keep` for existing files.
|
|
62
68
|
|
|
63
69
|
## Binding roles
|
|
@@ -81,6 +87,8 @@ Roles are contracts in `.companion/roles/`. Bindings are thin:
|
|
|
81
87
|
|
|
82
88
|
Pi has no built-in subagents: use the role contract as a prompt template or invoke the
|
|
83
89
|
related skill.
|
|
90
|
+
The harness-native primary coordinates through `AGENTS.md`; invoke a dedicated team lead
|
|
91
|
+
only when coordination adds value. OpenCode does not change its default agent.
|
|
84
92
|
|
|
85
93
|
## Limitations by harness
|
|
86
94
|
|
|
@@ -37,31 +37,25 @@ Verify with the `skill` tool or ask OpenCode to list available skills.
|
|
|
37
37
|
|
|
38
38
|
`devcomp init` writes one Markdown agent per role in `.opencode/agents/`:
|
|
39
39
|
|
|
40
|
-
- `team-lead.md` — `mode:
|
|
41
|
-
- The 11 specialists — `mode: subagent`, launched by the
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
It
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
`.companion/local/**` and `docs/companion/**`. The team lead therefore cannot implement code
|
|
60
|
-
or run commands itself; it must launch the specialists. Specialists deny `subagent`, so only
|
|
61
|
-
the team lead orchestrates.
|
|
62
|
-
|
|
63
|
-
For deterministic routing beyond prompt and permissions, an OpenCode plugin would be needed,
|
|
64
|
-
but the generated binding is designed so the model has no direct path to do the work.
|
|
40
|
+
- `team-lead.md` — callable `mode: subagent` for substantial coordination.
|
|
41
|
+
- The 11 specialists — `mode: subagent`, launched by the native primary agent
|
|
42
|
+
or by the dedicated lead when it coordinates a multi-specialist task.
|
|
43
|
+
|
|
44
|
+
It does not set `default_agent` or write `.opencode/opencode.json`: native Build
|
|
45
|
+
retains its tools and applies the Team Lead workflow from `AGENTS.md`. Existing
|
|
46
|
+
OpenCode configuration is preserved. For an old install with
|
|
47
|
+
`default_agent: "team-lead"`, remove that field or set `"build"` after reviewing
|
|
48
|
+
the existing configuration; review and refresh the old binding, then open a new
|
|
49
|
+
session. Existing project rules should be merged by the harness agent, or placed
|
|
50
|
+
in a backed-up pending handoff with `init --rules handoff`.
|
|
51
|
+
|
|
52
|
+
OpenCode does not route by intent by itself. The callable lead's own permissions
|
|
53
|
+
deny `edit` on code and deny `shell`; the native Build agent is **not** restricted.
|
|
54
|
+
The primary may delegate specialists or implement a focused slice directly while
|
|
55
|
+
following the same process. Specialists deny `subagent` to avoid unintended chains.
|
|
56
|
+
|
|
57
|
+
Instructions alone cannot guarantee that a model followed the workflow: verify real
|
|
58
|
+
agent behavior in a new session, not only `devcomp doctor`.
|
|
65
59
|
|
|
66
60
|
## Specialist example
|
|
67
61
|
|
|
@@ -100,12 +94,12 @@ OpenCode V2 uses **`permissions`** (plural), an ordered list of
|
|
|
100
94
|
|
|
101
95
|
## Team lead example
|
|
102
96
|
|
|
103
|
-
The generated binding is a router, not
|
|
97
|
+
The generated binding is a callable router, not the native primary:
|
|
104
98
|
|
|
105
99
|
```yaml
|
|
106
100
|
---
|
|
107
101
|
description: Leads discovery, planning, delegation, and closure.
|
|
108
|
-
mode:
|
|
102
|
+
mode: subagent
|
|
109
103
|
permissions:
|
|
110
104
|
- action: edit
|
|
111
105
|
resource: "*"
|
|
@@ -131,8 +125,9 @@ permissions:
|
|
|
131
125
|
---
|
|
132
126
|
```
|
|
133
127
|
|
|
134
|
-
The last matching rule wins. The
|
|
135
|
-
and launch
|
|
128
|
+
The last matching rule wins. The callable lead can read, write its own plan/closure
|
|
129
|
+
documents, and launch a specialist, but it cannot edit code or run shell commands.
|
|
130
|
+
The native primary keeps its tools. Specialists get
|
|
136
131
|
`{ "action": "subagent", "resource": "*", "effect": "deny" }` so they cannot spawn more
|
|
137
132
|
agents.
|
|
138
133
|
|
|
@@ -143,9 +138,11 @@ To restrict which specialists the team lead may launch, replace `"*"` with expli
|
|
|
143
138
|
|
|
144
139
|
- OpenCode subagents use Markdown frontmatter, not the canonical role format. Keep the
|
|
145
140
|
binding thin and put durable policy in `core/`.
|
|
146
|
-
-
|
|
147
|
-
|
|
148
|
-
|
|
141
|
+
- Install separately from the working repository root when an app is a nested repository;
|
|
142
|
+
the parent repo's rules, skills and agent definitions may not be discovered.
|
|
143
|
+
- The callable lead starts with fresh context when invoked. It reads
|
|
144
|
+
`.companion/local/` and the repository; it does not inherit the primary chat. Existing
|
|
145
|
+
sessions keep their previous selected agent; start a new session after migration.
|
|
149
146
|
- Permissions are enforced by the harness; the generated binding blocks direct code edits
|
|
150
147
|
and shell commands from the team lead.
|
|
151
148
|
|
package/core/principles.md
CHANGED
|
@@ -11,6 +11,27 @@ OpenCode, Claude Code, Codex, Pi, or a human.
|
|
|
11
11
|
"Better" means the requested problem is solved, the change is understandable,
|
|
12
12
|
and the evidence shows it works. Clever code that cannot be verified is not better.
|
|
13
13
|
|
|
14
|
+
## The delivery rule
|
|
15
|
+
|
|
16
|
+
**Working software is the measure of progress.** Planning is a tool, not a deliverable.
|
|
17
|
+
|
|
18
|
+
- The first commit lands in the first work block, before the second design document.
|
|
19
|
+
- Every session ends with a running increment, a failing test that defines the next step, or a
|
|
20
|
+
named blocker that needs the user.
|
|
21
|
+
- A document is progress only when it unblocks a slice that is about to be built.
|
|
22
|
+
- A project with ten documents and no runnable path has not progressed; it has accumulated risk.
|
|
23
|
+
|
|
24
|
+
**Red flags:** a brief longer than the first slice; "phase complete" with no commit; a third
|
|
25
|
+
architecture review before any code; planning used to avoid deciding.
|
|
26
|
+
|
|
27
|
+
## Planning budget
|
|
28
|
+
|
|
29
|
+
- Frame: 30–60 minutes, one page.
|
|
30
|
+
- Before the first end-to-end slice: **≤ 10–15 % of total effort**.
|
|
31
|
+
- Every artifact names the slice it unblocks. If it cannot, defer it.
|
|
32
|
+
- If a planning document exceeds two pages before the first commit, cut it.
|
|
33
|
+
- A second planning cycle on the same topic is a smell: decide, build, and let the code answer.
|
|
34
|
+
|
|
14
35
|
---
|
|
15
36
|
|
|
16
37
|
## 1. Understand before changing
|