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 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
- For a new project or a major change:
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 Operational discovery (Team Lead)
95
- → 2 Architecture + security (Architect ∥ Cybersecurity)
96
- → 3 Test strategy (QA)
97
- → 4 UX/UI (Frontend)
98
- → 5 Delivery plan (Team Lead)
99
- → 6 Implementation (specialists)
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
- Each phase has an owner, an artifact in `.companion/local/`, and a gate with evidence.
107
- For a small change, the process collapses to the workflow in `core/workflow.md`.
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
- Read `core/process.md` for the full phase guide.
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` warns that
138
- `default_agent` is not set.
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 | Verified per release |
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. Only `.companion/config.json` is tracked.
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.2.0.tgz
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.2.0`, not `0.0.0-stage`. If it still points to the
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.2.0 --version
83
- npx development-companion@1.2.0 init . --yes --harness opencode --profile web
84
- npx development-companion@1.2.0 doctor .
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.2.0 -m "v1.2.0"
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.2.0
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
@@ -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 verified per release |
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 `.opencode/opencode.json` or `.opencode/opencode.jsonc`, the installer
55
- preserves it and `devcomp doctor` warns that `default_agent` is not set.
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`.
@@ -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
- This is the default process for a new project or a major change. It scales down for small
4
- changes; see `core/workflow.md`.
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 Operational discovery
12
- → 2 Architecture + security (in parallel)
13
- → 3 Test strategy
14
- → 4 UX/UI
15
- → 5 Delivery plan
16
- → 6 Implementation
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 the repository, harness, package manager, profile, and branch convention.
28
- - Install `AGENTS.md` and `CLAUDE.md` using keep, append, or replace.
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
- ## Phase 1 — Operational discovery
35
-
36
- **Owner:** Team Lead. **Participant:** the user.
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
- Security, in parallel:
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
- - Assets, actors, entry points, trust boundaries.
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
- **Artifacts:** `.companion/local/02-architecture.md`,
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
- **Gate:** every acceptance criterion maps to a test; critical failure paths are covered
102
- or explicitly accepted.
49
+ Answer only what can change the first slice:
103
50
 
104
- ## Phase 4 — UX/UI
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
- **Owner:** Frontend Engineer. **Participants:** the user, QA.
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
- - Flows and information architecture.
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
- **Artifact:** `.companion/local/05-ux-spec.md` plus mockups and screenshots.
63
+ **Gate:** the user confirms the first slice and its acceptance criteria; no blocking question
64
+ remains for that slice.
118
65
 
119
- **Gate:** the user approves the design; states and accessibility are covered.
66
+ **Timebox:** if the brief is not done in one work block, cut it to the five questions above.
120
67
 
121
- ## Phase 5 — Delivery plan
68
+ ## Phase 2 — Walking skeleton
122
69
 
123
- **Owner:** Team Lead. **Participants:** all specialists.
70
+ **Owner:** specialists. **Coordinator:** Team Lead.
124
71
 
125
- - Deliverables with owners.
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
- **Artifact:** `.companion/local/06-delivery-plan.md`.
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:** every task has an owner, an output, and a verification; no two writers own the
135
- same files.
79
+ **Gate:** the skeleton runs end-to-end; the command and the test are recorded; the commit
80
+ exists.
136
81
 
137
- ## Phase 6 — Implementation
82
+ ## Phase 3 — Slice loop
138
83
 
139
84
  **Owner:** specialists. **Coordinator:** Team Lead.
140
85
 
141
- - Contracts and schemas first.
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
- **Gate:** local checks pass; the diff is scoped; tests cover the new behavior.
88
+ For each slice:
150
89
 
151
- ## Phase 7 — Security verification
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
- **Owner:** Cybersecurity Engineer. **Participant:** implementers.
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
- - Update the threat model.
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
- **Artifact:** `.companion/local/07-security-report.md`.
102
+ ## Phase 4 — Verify
163
103
 
164
- **Gate:** no open critical or high findings; medium risks have an owner and a date.
104
+ **Owner:** Cybersecurity Engineer and QA Engineer. **Participant:** implementers.
165
105
 
166
- ## Phase 8 — QA verification
106
+ Verification is continuous, not a final phase:
167
107
 
168
- **Owner:** QA Engineer. **Participant:** implementers.
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
- - Functional and regression tests.
171
- - Golden/dark paths and edge cases.
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
- **Artifact:** `.companion/local/08-qa-report.md`.
116
+ ## Phase 5 — Release
178
117
 
179
- **Gate:** must-pass checks are green; known failures are documented; performance is within
180
- budget or explicitly accepted.
118
+ **Owner:** SRE Engineer. **Participants:** Team Lead, Cybersecurity.
181
119
 
182
- ## Phase 9 — Deployment
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
- **Owner:** SRE Engineer. **Participants:** Team Lead, Cybersecurity.
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
- - Docker/compose baseline; VPS with Dokploy or Coolify; cloud reference provider.
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
- **Artifact:** `.companion/local/09-runbook.md`.
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:** smoke tests pass; rollback is tested; secrets are outside the repo; monitoring is
196
- active.
137
+ **Gate:** the user accepts; no claim of "done" lacks evidence.
197
138
 
198
- ## Phase 10 — Closure
139
+ ## Artifacts: when to write them
199
140
 
200
- **Owner:** Team Lead. **Participants:** all.
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
- - What was delivered and why.
203
- - Evidence per gate.
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
- **Artifact:** `.companion/local/10-closure.md`.
156
+ ## Planning budget
209
157
 
210
- **Gate:** the user accepts; no claim of "done" lacks evidence; the repository is consistent.
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 → plan → implement → tests → self-review |
218
- | Cross-layer, data, auth, public contract | Full process + independent security and QA |
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.