development-companion 1.2.0 → 1.3.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 -19
- package/RELEASE.md +7 -7
- package/adapters/README.md +7 -1
- package/adapters/opencode/README.md +7 -2
- package/core/principles.md +21 -0
- package/core/process.md +122 -158
- package/core/quality-gates.md +21 -13
- package/core/roles/team-lead.md +46 -29
- package/core/workflow.md +16 -3
- package/package.json +2 -2
- 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 +7 -2
- package/src/cli.mjs +57 -16
- package/src/content.mjs +1 -0
- package/src/install.mjs +30 -7
- package/src/rules.mjs +3 -1
- package/src/scaffold.mjs +4 -1
- package/templates/artifacts/01-operational-brief.md +17 -3
- package/templates/artifacts/06-delivery-plan.md +26 -5
- package/templates/rules/AGENTS.block.md +34 -18
package/README.md
CHANGED
|
@@ -11,6 +11,11 @@ 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. Use `init --rules append` to add the managed block without removing existing rules.
|
|
18
|
+
|
|
14
19
|
## Why
|
|
15
20
|
|
|
16
21
|
Coding agents are powerful but inconsistent. Each harness has its own rules file, skill
|
|
@@ -87,26 +92,23 @@ The managed block is delimited by `<!-- development-companion:start -->` and
|
|
|
87
92
|
|
|
88
93
|
## The process
|
|
89
94
|
|
|
90
|
-
|
|
95
|
+
The process exists to ship working software, not to produce documents. It is a loop:
|
|
91
96
|
|
|
92
97
|
```text
|
|
93
98
|
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)
|
|
99
|
+
→ 1 Frame (one page, 30–60 min)
|
|
100
|
+
→ 2 Walking skeleton (end-to-end, fakes allowed)
|
|
101
|
+
→ 3 Slice loop (build → test → demo → next)
|
|
102
|
+
→ 4 Verify (security + QA, continuous)
|
|
103
|
+
→ 5 Release
|
|
104
|
+
→ 6 Close
|
|
104
105
|
```
|
|
105
106
|
|
|
106
|
-
|
|
107
|
-
|
|
107
|
+
Planning artifacts are living notes written just in time, not phase gates. The first commit
|
|
108
|
+
lands before the second design document. See `core/process.md` and the `incremental-delivery`
|
|
109
|
+
skill.
|
|
108
110
|
|
|
109
|
-
|
|
111
|
+
For a small change, the process collapses to the workflow in `core/workflow.md`.
|
|
110
112
|
|
|
111
113
|
## Roles
|
|
112
114
|
|
|
@@ -127,6 +129,8 @@ Read `core/process.md` for the full phase guide.
|
|
|
127
129
|
|
|
128
130
|
Role contracts live in `core/roles/`. The CLI installs them to `.companion/roles/` and
|
|
129
131
|
generates native bindings where the harness supports subagents.
|
|
132
|
+
The canonical principles, process, workflow, quality gates, and guidelines are installed in
|
|
133
|
+
`.companion/core/`. The generated rules and agent bindings reference these files.
|
|
130
134
|
|
|
131
135
|
### Orchestration in OpenCode
|
|
132
136
|
|
|
@@ -134,8 +138,13 @@ generates native bindings where the harness supports subagents.
|
|
|
134
138
|
`.opencode/opencode.json` with `default_agent: "team-lead"`. The 11 specialists are
|
|
135
139
|
subagents. New sessions start as the team lead, which delegates with the `subagent` tool;
|
|
136
140
|
Build and Plan remain available in the agent selector. If the project already has an
|
|
137
|
-
OpenCode config, the installer preserves it and `devcomp doctor`
|
|
138
|
-
`default_agent`
|
|
141
|
+
OpenCode config, the installer preserves it and `devcomp doctor` fails if
|
|
142
|
+
`default_agent` does not select the team lead.
|
|
143
|
+
|
|
144
|
+
For an existing OpenCode configuration, add `"default_agent": "team-lead"` yourself and
|
|
145
|
+
start a **new** session. The CLI will not overwrite that configuration; `doctor` reports a
|
|
146
|
+
failure until an effective default is configured. Existing `AGENTS.md` files also require
|
|
147
|
+
`--rules append` (or an explicit replacement) before the process is active.
|
|
139
148
|
|
|
140
149
|
The team lead is a router, not an implementer. Its generated binding denies `edit` outside
|
|
141
150
|
`.companion/local/**` and `docs/companion/**`, and denies `shell`; it must launch a
|
|
@@ -149,7 +158,7 @@ Process skills are installed always:
|
|
|
149
158
|
|
|
150
159
|
`project-discovery`, `architecture-design`, `test-strategy`, `ux-design`,
|
|
151
160
|
`delivery-orchestration`, `security-review`, `deployment-sre`, `development-workflow`,
|
|
152
|
-
`code-review`.
|
|
161
|
+
`incremental-delivery`, `code-review`.
|
|
153
162
|
|
|
154
163
|
Domain skills are installed by profile:
|
|
155
164
|
|
|
@@ -169,16 +178,22 @@ specification.
|
|
|
169
178
|
|
|
170
179
|
| Tier | Harnesses | Commitment |
|
|
171
180
|
|---|---|---|
|
|
172
|
-
| 1 | OpenCode, Claude Code, Codex, Pi |
|
|
181
|
+
| 1 | OpenCode, Claude Code, Codex, Pi | Installation targets; behavioral validation required per release |
|
|
173
182
|
| 2 | Cursor, Gemini CLI, Copilot CLI, Windsurf, Cline | Best-effort, generated |
|
|
174
183
|
| 3 | Any harness that reads `AGENTS.md` or accepts a prompt pack | Generic fallback |
|
|
175
184
|
|
|
176
185
|
Adapters are data: rules file, skills directory, agent directory, and limitations.
|
|
186
|
+
Installation checks do not prove that a model followed the workflow. Claude Code and Codex
|
|
187
|
+
provide specialist bindings but do not automatically start in a team-lead role; invoke it
|
|
188
|
+
explicitly when orchestration is needed. Pi has no native subagents and must run the role
|
|
189
|
+
workflow in one session or through a user-supplied extension. Validate real agent behavior
|
|
190
|
+
in each harness before claiming process compliance.
|
|
177
191
|
|
|
178
192
|
## Local design documents
|
|
179
193
|
|
|
180
194
|
By default, discovery, architecture, test plans, evidence, and reports live in
|
|
181
|
-
`.companion/local/`, which is ignored by git.
|
|
195
|
+
`.companion/local/`, which is ignored by git. The manifest, installed core documents,
|
|
196
|
+
roles, and skills can be tracked; the design notes remain local unless opted in.
|
|
182
197
|
|
|
183
198
|
If you want the design to travel with the repository:
|
|
184
199
|
|
|
@@ -188,6 +203,8 @@ npx development-companion init . --docs tracked
|
|
|
188
203
|
|
|
189
204
|
That moves the artifacts to `docs/companion/`.
|
|
190
205
|
|
|
206
|
+
This configured path overrides default `.companion/local/` examples in role and skill files.
|
|
207
|
+
|
|
191
208
|
## Memory: Engram (optional)
|
|
192
209
|
|
|
193
210
|
The process works without memory. If Engram is available, it stores decisions, findings,
|
|
@@ -228,6 +245,23 @@ node bin/devcomp.mjs --help
|
|
|
228
245
|
|
|
229
246
|
Requirements: Node >= 22. No runtime dependencies, no `postinstall`, no telemetry.
|
|
230
247
|
|
|
248
|
+
### End-to-end framework test
|
|
249
|
+
|
|
250
|
+
The expense tracker is a repeatable E2E fixture for the framework itself:
|
|
251
|
+
|
|
252
|
+
```bash
|
|
253
|
+
DC_E2E_ITERATION=01 node scripts/e2e-expense.mjs
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
It deletes `~/repos/dc-e2e-expense`, installs the published package with `npx`, runs
|
|
257
|
+
`init`, `doctor`, and `scaffold`, copies the expense app, and runs unit, API, component,
|
|
258
|
+
and Playwright tests. Screenshots, command logs, process artifacts, and `report.md` are
|
|
259
|
+
written to `plannification/validation/e2e-expense/<iteration>/` (gitignored). The workdir
|
|
260
|
+
stays for inspection; the next run deletes it.
|
|
261
|
+
|
|
262
|
+
This exercises installation and a prebuilt app fixture; it does **not** launch a coding agent
|
|
263
|
+
or prove it followed instructions. Behavioral validation requires separate agent sessions.
|
|
264
|
+
|
|
231
265
|
## Repository layout
|
|
232
266
|
|
|
233
267
|
```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.3.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.3.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.3.0 --version
|
|
83
|
+
npx development-companion@1.3.0 init . --yes --harness opencode --profile web
|
|
84
|
+
npx development-companion@1.3.0 doctor .
|
|
85
85
|
```
|
|
86
86
|
|
|
87
87
|
Also verify the package page:
|
|
@@ -93,14 +93,14 @@ 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.3.0 -m "v1.3.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.3.0
|
|
104
104
|
```
|
|
105
105
|
|
|
106
106
|
Include the install command, the supported harness tiers, and the breaking changes from
|
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 an OpenCode configuration without the team lead default is a failure,
|
|
18
|
+
not proof of an active installation.
|
|
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
|
|
|
@@ -81,6 +85,8 @@ Roles are contracts in `.companion/roles/`. Bindings are thin:
|
|
|
81
85
|
|
|
82
86
|
Pi has no built-in subagents: use the role contract as a prompt template or invoke the
|
|
83
87
|
related skill.
|
|
88
|
+
Claude Code and Codex do not select the team lead automatically; invoke it explicitly when
|
|
89
|
+
orchestration is needed. Only the OpenCode adapter configures a primary default agent.
|
|
84
90
|
|
|
85
91
|
## Limitations by harness
|
|
86
92
|
|
|
@@ -51,8 +51,11 @@ It also creates `.opencode/opencode.json` with:
|
|
|
51
51
|
```
|
|
52
52
|
|
|
53
53
|
New sessions start as `team-lead`; Build and Plan remain available in the selector. If the
|
|
54
|
-
project already has
|
|
55
|
-
preserves it
|
|
54
|
+
project already has `opencode.json(c)` at the root or in `.opencode/`, the installer
|
|
55
|
+
preserves it. `devcomp doctor` fails unless the effective project config selects
|
|
56
|
+
`default_agent: "team-lead"`; add it manually to the existing config, then start a new
|
|
57
|
+
session. Likewise, an existing `AGENTS.md` needs `init --rules append` to activate the
|
|
58
|
+
canonical process without discarding project rules.
|
|
56
59
|
|
|
57
60
|
OpenCode does not route by intent by itself. The generated team-lead prompt **mandates**
|
|
58
61
|
delegation with the `subagent` tool, and its permissions **deny `edit` and `shell`** outside
|
|
@@ -143,6 +146,8 @@ To restrict which specialists the team lead may launch, replace `"*"` with expli
|
|
|
143
146
|
|
|
144
147
|
- OpenCode subagents use Markdown frontmatter, not the canonical role format. Keep the
|
|
145
148
|
binding thin and put durable policy in `core/`.
|
|
149
|
+
- Install separately from the working repository root when an app is a nested repository;
|
|
150
|
+
the parent repo's rules, skills and agent definitions may not be discovered.
|
|
146
151
|
- The team lead starts with fresh context in a new session. It reads
|
|
147
152
|
`.companion/local/` and the repository; it does not inherit the previous chat. Existing
|
|
148
153
|
sessions keep their previous agent; start a new session to pick up `team-lead`.
|
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
|
package/core/process.md
CHANGED
|
@@ -1,224 +1,188 @@
|
|
|
1
1
|
# Development Process
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
The process is owned by the **Team Lead**. Each phase has an artifact in
|
|
7
|
-
`.companion/local/` and a gate that requires evidence.
|
|
3
|
+
The process exists to **ship working software**, not to produce documents. It is a loop, not a
|
|
4
|
+
waterfall. Planning is a tool that unblocks the next slice; when it stops doing that, it stops.
|
|
8
5
|
|
|
9
6
|
```text
|
|
10
7
|
0 Bootstrap
|
|
11
|
-
→ 1
|
|
12
|
-
→ 2
|
|
13
|
-
→ 3
|
|
14
|
-
→ 4
|
|
15
|
-
→ 5
|
|
16
|
-
→ 6
|
|
17
|
-
→ 7 Security verification
|
|
18
|
-
→ 8 QA verification
|
|
19
|
-
→ 9 Deployment
|
|
20
|
-
→ 10 Closure
|
|
8
|
+
→ 1 Frame (30–60 min, one page)
|
|
9
|
+
→ 2 Walking skeleton (end-to-end, fakes allowed)
|
|
10
|
+
→ 3 Slice loop (build → test → demo → next slice)
|
|
11
|
+
→ 4 Verify (security + QA, continuous)
|
|
12
|
+
→ 5 Release
|
|
13
|
+
→ 6 Close
|
|
21
14
|
```
|
|
22
15
|
|
|
16
|
+
## The delivery rule
|
|
17
|
+
|
|
18
|
+
> **A phase is complete when code runs, not when a document exists.**
|
|
19
|
+
|
|
20
|
+
- The first commit must land in the first work block, before the second design document.
|
|
21
|
+
- Every session ends with one of: a running increment, a failing test that defines the next
|
|
22
|
+
step, or a named blocker that needs the user.
|
|
23
|
+
- A planning artifact is written **just in time**, only as deep as the next slice needs.
|
|
24
|
+
- A document that does not unblock code is deferred, not expanded.
|
|
25
|
+
|
|
23
26
|
## Phase 0 — Bootstrap
|
|
24
27
|
|
|
25
28
|
**Owner:** CLI.
|
|
26
29
|
|
|
27
|
-
- Detect
|
|
28
|
-
- Install `AGENTS.md
|
|
29
|
-
- Install process skills, roles, and native bindings.
|
|
30
|
+
- Detect repository, harness, package manager, profile, and branch convention.
|
|
31
|
+
- Install `AGENTS.md`, `CLAUDE.md`, skills, roles, and bindings.
|
|
30
32
|
- Write `.companion/config.json` and ignore `.companion/local/`.
|
|
31
33
|
|
|
32
34
|
**Gate:** `devcomp doctor` passes; existing rules were not lost.
|
|
33
35
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
Ask, one topic at a time:
|
|
39
|
-
|
|
40
|
-
- What problem, for whom, and why now?
|
|
41
|
-
- What does success look like, and how is it measured?
|
|
42
|
-
- What is in scope and out of scope for the first release?
|
|
43
|
-
- Are there existing repositories, prototypes, designs, or documents?
|
|
44
|
-
- Where will it run: on-prem, VPS, Dokploy, Coolify, cloud?
|
|
45
|
-
- Which third-party services, APIs, MCPs, or on-device capabilities are required?
|
|
46
|
-
- What data is stored, where, and for how long?
|
|
47
|
-
- What authentication is needed: local, OIDC, Firebase, other?
|
|
48
|
-
- Which platforms are targets?
|
|
49
|
-
- What are the deadline, team, budget, and maintenance constraints?
|
|
50
|
-
- Which branch convention is used: gitflow, GitLab flow, trunk-based, GitHub flow, custom?
|
|
51
|
-
Detect it, then ask the user to confirm.
|
|
52
|
-
- What does "done" mean?
|
|
53
|
-
|
|
54
|
-
**Artifact:** `.companion/local/01-operational-brief.md`.
|
|
55
|
-
|
|
56
|
-
**Gate:** the user confirms the brief; no blocking operational question remains.
|
|
57
|
-
|
|
58
|
-
## Phase 2 — Architecture and security
|
|
59
|
-
|
|
60
|
-
**Owner:** Architect. **Participant:** Cybersecurity Engineer, in parallel.
|
|
61
|
-
|
|
62
|
-
Technical questions:
|
|
63
|
-
|
|
64
|
-
- Stack and versions: verify the latest stable release.
|
|
65
|
-
- Monorepo or single repo? Which workspace tool?
|
|
66
|
-
- Monolith, modular monolith, or microservices? Why?
|
|
67
|
-
- Layered, hexagonal, or tactical DDD?
|
|
68
|
-
- Data stores, schema, migrations.
|
|
69
|
-
- AuthN/AuthZ, tenancy, secrets.
|
|
70
|
-
- Integrations, queues, events, webhooks, idempotency.
|
|
71
|
-
- Deployment, observability, backups, rollback.
|
|
72
|
-
- Performance budget and expected load.
|
|
36
|
+
Install the canonical process, principles, workflow, quality gates, and guidelines in
|
|
37
|
+
`.companion/core/`. Existing project rules or harness configuration are preserved; a
|
|
38
|
+
diagnostic failure must be resolved before treating the process as active. Run `doctor`
|
|
39
|
+
from the repository that the agent actually opens, including a nested app repository.
|
|
73
40
|
|
|
74
|
-
|
|
41
|
+
Artifact paths below use `.companion/local/` by default. When the installation is configured
|
|
42
|
+
with `--docs tracked`, use `docs/companion/` instead; the configured path overrides examples
|
|
43
|
+
in roles and skills.
|
|
75
44
|
|
|
76
|
-
|
|
77
|
-
- Threat model and top risks.
|
|
78
|
-
- Controls and accepted risks.
|
|
79
|
-
- Relevant CVEs and supply-chain concerns.
|
|
45
|
+
## Phase 1 — Frame (30–60 minutes, one page)
|
|
80
46
|
|
|
81
|
-
**
|
|
82
|
-
`.companion/local/03-threat-model.md`, and `adr/NNN-*.md`.
|
|
83
|
-
|
|
84
|
-
**Gate:** stack and versions approved; boundaries and patterns recorded; threats have a
|
|
85
|
-
control or an explicit acceptance; no architecture blocker remains.
|
|
86
|
-
|
|
87
|
-
## Phase 3 — Test strategy
|
|
88
|
-
|
|
89
|
-
**Owner:** QA Engineer. **Participants:** Team Lead, Architect.
|
|
90
|
-
|
|
91
|
-
- Golden paths, dark paths, and edge cases.
|
|
92
|
-
- Test levels and tools.
|
|
93
|
-
- Data, fixtures, and environments.
|
|
94
|
-
- Load/stress scenario, budgets, and target environment.
|
|
95
|
-
- Accessibility, visual, and cross-platform checks.
|
|
96
|
-
- Security checks.
|
|
97
|
-
- Evidence format and exit criteria.
|
|
98
|
-
|
|
99
|
-
**Artifact:** `.companion/local/04-test-plan.md`.
|
|
47
|
+
**Owner:** Team Lead. **Participant:** the user.
|
|
100
48
|
|
|
101
|
-
|
|
102
|
-
or explicitly accepted.
|
|
49
|
+
Answer only what can change the first slice:
|
|
103
50
|
|
|
104
|
-
|
|
51
|
+
1. What problem, for whom, and what observable outcome proves success?
|
|
52
|
+
2. What is the **first end-to-end slice**? (Not the whole product.)
|
|
53
|
+
3. What constraints could invalidate that slice: platform, data, auth, privacy, performance,
|
|
54
|
+
third parties, deadline?
|
|
55
|
+
4. What is explicitly out of scope for this slice?
|
|
56
|
+
5. Which decisions are irreversible and need the user now?
|
|
105
57
|
|
|
106
|
-
|
|
58
|
+
Everything else is deferred. Stack details, full schemas, complete UX, and exhaustive test
|
|
59
|
+
matrices are decided when the slice needs them.
|
|
107
60
|
|
|
108
|
-
-
|
|
109
|
-
- Wireframes or mockups in `.companion/local/mockups/`.
|
|
110
|
-
- States: loading, empty, error, unauthorized, offline, retry, success.
|
|
111
|
-
- Responsive breakpoints and behavior.
|
|
112
|
-
- Accessibility: keyboard, focus, labels, contrast, reduced motion.
|
|
113
|
-
- Motion with purpose.
|
|
114
|
-
- Design tokens and components.
|
|
115
|
-
- Screenshots at desktop and mobile widths.
|
|
61
|
+
**Artifact:** `.companion/local/01-operational-brief.md`, maximum one page.
|
|
116
62
|
|
|
117
|
-
**
|
|
63
|
+
**Gate:** the user confirms the first slice and its acceptance criteria; no blocking question
|
|
64
|
+
remains for that slice.
|
|
118
65
|
|
|
119
|
-
**
|
|
66
|
+
**Timebox:** if the brief is not done in one work block, cut it to the five questions above.
|
|
120
67
|
|
|
121
|
-
## Phase
|
|
68
|
+
## Phase 2 — Walking skeleton
|
|
122
69
|
|
|
123
|
-
**Owner:**
|
|
70
|
+
**Owner:** specialists. **Coordinator:** Team Lead.
|
|
124
71
|
|
|
125
|
-
|
|
126
|
-
- Dependencies and critical path.
|
|
127
|
-
- Parallel vs serial work.
|
|
128
|
-
- Branch and release flow.
|
|
129
|
-
- Gates and evidence.
|
|
130
|
-
- Risks and mitigations.
|
|
72
|
+
Build the thinnest path that goes from the user's entry point to a visible result:
|
|
131
73
|
|
|
132
|
-
|
|
74
|
+
- Real process boundaries, fake or trivial implementations where the real one is expensive.
|
|
75
|
+
- One command to run it; one test that proves the path.
|
|
76
|
+
- Commit as soon as it runs, even if ugly.
|
|
77
|
+
- No design system, no full schema, no exhaustive error handling yet.
|
|
133
78
|
|
|
134
|
-
**Gate:**
|
|
135
|
-
|
|
79
|
+
**Gate:** the skeleton runs end-to-end; the command and the test are recorded; the commit
|
|
80
|
+
exists.
|
|
136
81
|
|
|
137
|
-
## Phase
|
|
82
|
+
## Phase 3 — Slice loop
|
|
138
83
|
|
|
139
84
|
**Owner:** specialists. **Coordinator:** Team Lead.
|
|
140
85
|
|
|
141
|
-
-
|
|
142
|
-
- Tests alongside behavior; TDD if the project chose it.
|
|
143
|
-
- Small, reversible changes.
|
|
144
|
-
- Domain independent from infrastructure.
|
|
145
|
-
- No secrets, debug output, or dead code.
|
|
146
|
-
- Update ADRs when reality contradicts the plan.
|
|
147
|
-
- Self-review before requesting verification.
|
|
86
|
+
Pick the **highest-risk or highest-value slice** and finish it before starting another.
|
|
148
87
|
|
|
149
|
-
|
|
88
|
+
For each slice:
|
|
150
89
|
|
|
151
|
-
|
|
90
|
+
1. State the acceptance criteria (one or two observable sentences).
|
|
91
|
+
2. Implement the smallest coherent change.
|
|
92
|
+
3. Add or update tests with the behavior.
|
|
93
|
+
4. Demo it with a command, a screenshot, or a request/response.
|
|
94
|
+
5. Commit.
|
|
95
|
+
6. Update the living notes only where reality changed a decision.
|
|
152
96
|
|
|
153
|
-
**
|
|
97
|
+
**WIP limit: one slice per writer.** Parallelism is allowed only for read-only work or for
|
|
98
|
+
slices that touch disjoint files.
|
|
154
99
|
|
|
155
|
-
|
|
156
|
-
- OWASP ASVS as a reference, not a checklist ritual.
|
|
157
|
-
- SAST, dependency audit, secret scanning, container/configuration scanning.
|
|
158
|
-
- Test authn, authz, sessions, uploads, payments, webhooks, rate limits.
|
|
159
|
-
- Report every finding with reproducible evidence.
|
|
160
|
-
- Re-test fixes.
|
|
100
|
+
**Gate:** acceptance criteria are covered by evidence; the diff is scoped; the commit exists.
|
|
161
101
|
|
|
162
|
-
|
|
102
|
+
## Phase 4 — Verify
|
|
163
103
|
|
|
164
|
-
**
|
|
104
|
+
**Owner:** Cybersecurity Engineer and QA Engineer. **Participant:** implementers.
|
|
165
105
|
|
|
166
|
-
|
|
106
|
+
Verification is continuous, not a final phase:
|
|
167
107
|
|
|
168
|
-
|
|
108
|
+
- Security review of each new trust boundary, secret, permission, or data flow.
|
|
109
|
+
- Tests at the level the risk requires: unit for rules, integration for boundaries, one
|
|
110
|
+
end-to-end path for the slice.
|
|
111
|
+
- A real-device or real-environment check before release, not only emulators.
|
|
169
112
|
|
|
170
|
-
-
|
|
171
|
-
|
|
172
|
-
- Load/stress evidence in a target-like environment.
|
|
173
|
-
- Accessibility and visual review against the mockup.
|
|
174
|
-
- Cross-platform and responsive checks.
|
|
175
|
-
- Every failure with reproduction and evidence; fixes are re-verified.
|
|
113
|
+
**Gate for release:** no open critical/high findings; must-pass checks green; known failures
|
|
114
|
+
documented; residual risk accepted by the user.
|
|
176
115
|
|
|
177
|
-
|
|
116
|
+
## Phase 5 — Release
|
|
178
117
|
|
|
179
|
-
**
|
|
180
|
-
budget or explicitly accepted.
|
|
118
|
+
**Owner:** SRE Engineer. **Participants:** Team Lead, Cybersecurity.
|
|
181
119
|
|
|
182
|
-
|
|
120
|
+
- Version, changelog, signing, and install/upgrade path.
|
|
121
|
+
- Rollback or roll-forward plan.
|
|
122
|
+
- Smoke test in the target environment.
|
|
123
|
+
- Secrets outside the repository.
|
|
183
124
|
|
|
184
|
-
**
|
|
125
|
+
**Gate:** the release artifact is installed and exercised in the target; rollback is tested or
|
|
126
|
+
explicitly accepted.
|
|
127
|
+
|
|
128
|
+
## Phase 6 — Close
|
|
185
129
|
|
|
186
|
-
|
|
187
|
-
- Secrets in the target manager; never in the repository.
|
|
188
|
-
- Migrations with a tested rollback.
|
|
189
|
-
- Healthchecks, logs, metrics, traces, alerts.
|
|
190
|
-
- Smoke tests against the real target.
|
|
191
|
-
- Performance evidence in the target environment.
|
|
130
|
+
**Owner:** Team Lead.
|
|
192
131
|
|
|
193
|
-
|
|
132
|
+
- What shipped, with evidence.
|
|
133
|
+
- What was deferred and why.
|
|
134
|
+
- Residual risks and next slice.
|
|
135
|
+
- A short completion report, not a novel.
|
|
194
136
|
|
|
195
|
-
**Gate:**
|
|
196
|
-
active.
|
|
137
|
+
**Gate:** the user accepts; no claim of "done" lacks evidence.
|
|
197
138
|
|
|
198
|
-
##
|
|
139
|
+
## Artifacts: when to write them
|
|
199
140
|
|
|
200
|
-
|
|
141
|
+
| Artifact | When | Maximum before the first commit |
|
|
142
|
+
|---|---|---|
|
|
143
|
+
| Operational brief | Frame | 1 page |
|
|
144
|
+
| Architecture notes / ADRs | When a decision blocks a slice | 1 page per ADR |
|
|
145
|
+
| Threat model | When a trust boundary or sensitive data appears | The slice's threats only |
|
|
146
|
+
| Test plan | With the first tests | The first 5 tests |
|
|
147
|
+
| UX spec / mockups | Before the first UI slice | The next screen only |
|
|
148
|
+
| Delivery plan | First slice + next 3 | 1 page |
|
|
149
|
+
| Security report | Before release | Findings only |
|
|
150
|
+
| QA report | Before release | Evidence only |
|
|
151
|
+
| Runbook | Before deployment | The deploy path only |
|
|
201
152
|
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
- Residual risks and accepted debt.
|
|
205
|
-
- Runbook and handoff.
|
|
206
|
-
- Next steps.
|
|
153
|
+
These are **living notes**, not phase gates. If a document grows past its limit before the
|
|
154
|
+
first commit, cut it or defer it.
|
|
207
155
|
|
|
208
|
-
|
|
156
|
+
## Planning budget
|
|
209
157
|
|
|
210
|
-
|
|
158
|
+
- Frame: 30–60 minutes, one page.
|
|
159
|
+
- Total planning before the first end-to-end slice: **≤ 10–15 % of the effort**.
|
|
160
|
+
- Every planning artifact must name the slice it unblocks. If it cannot, defer it.
|
|
161
|
+
- A second planning cycle on the same topic is a smell: decide, build, and let the code
|
|
162
|
+
answer the question.
|
|
211
163
|
|
|
212
164
|
## Scaling down
|
|
213
165
|
|
|
214
166
|
| Change | Process |
|
|
215
167
|
|---|---|
|
|
216
168
|
| Typo, docs, one-line fix | Recon → change → check → report |
|
|
217
|
-
| Feature in one layer | Brief →
|
|
218
|
-
| Cross-layer, data, auth, public contract |
|
|
169
|
+
| Feature in one layer | Brief → implement → tests → self-review |
|
|
170
|
+
| Cross-layer, data, auth, public contract | Frame → skeleton or thin slice → tests → independent security/QA |
|
|
171
|
+
| New project | Frame (1 page) → walking skeleton → slice loop |
|
|
219
172
|
| Incident | Stabilize → diagnose → fix → regression test → short postmortem |
|
|
220
173
|
|
|
221
174
|
## Evidence
|
|
222
175
|
|
|
223
176
|
A gate is not closed by a narrative. It is closed by a command and its output, a test, a
|
|
224
177
|
request, a screenshot, a CVE, or a metric. See `core/quality-gates.md`.
|
|
178
|
+
|
|
179
|
+
## Anti-patterns
|
|
180
|
+
|
|
181
|
+
- **Planning loop:** producing a third document before the first commit.
|
|
182
|
+
- **Big-bang integration:** building every layer before proving one path.
|
|
183
|
+
- **Architecture astronaut:** designing for scale that the product does not have.
|
|
184
|
+
- **Demo debt:** a skeleton that only runs in a notebook, not in the repo.
|
|
185
|
+
- **Phase theater:** marking a phase "done" because its document exists.
|
|
186
|
+
- **Silent scope growth:** adding a second slice before finishing the first.
|
|
187
|
+
|
|
188
|
+
If two consecutive work sessions produce no running code, stop and escalate to the user.
|