development-companion 1.4.1 → 1.6.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/CHANGELOG.md ADDED
@@ -0,0 +1,29 @@
1
+ # Changelog
2
+
3
+ ## 1.6.0
4
+
5
+ - `devcomp update` replaces framework-owned skills, roles, bindings, and canonical
6
+ content by default. Use `--keep` to preserve them for a manual merge.
7
+ - `AGENTS.md` is now a complete managed template plus a `# User guiding` section.
8
+ Updates preserve User guiding verbatim and always write `AGENTS.md.bak`.
9
+ - Existing legacy `AGENTS.md` files are migrated automatically (old content under
10
+ User guiding). Ambiguous structures leave a merge-pending notice and `doctor`
11
+ fails until an agent merges the backup.
12
+ - `doctor` verifies canonical, role, and skill content against the package, plus
13
+ the template version and the presence of User guiding.
14
+
15
+ ## 1.5.1
16
+
17
+ - `devcomp update --dry-run` now reports the plan and writes nothing instead of
18
+ silently updating the installation.
19
+
20
+ ## 1.5.0
21
+
22
+ - The native primary coordinates delivery, directly invokes specialists, and is
23
+ the sole user interlocutor. In OpenCode, the callable Team Lead is an advisor
24
+ and cannot subdelegate.
25
+ - Non-trivial work requires an operational conversation and explicit approval
26
+ of the technical approach. Role handoffs record evidence for golden and dark
27
+ paths, with optional Engram persistence and local records as the fallback.
28
+ - `doctor` detects outdated OpenCode Team Lead permissions. See the
29
+ [migration guide](README.md#working-modes) to preserve customizations.
package/README.md CHANGED
@@ -97,6 +97,11 @@ The managed block is delimited by `<!-- development-companion:start -->` and
97
97
 
98
98
  ## The process
99
99
 
100
+ **New in 1.5.0:** direct specialist delegation through the primary agent,
101
+ explicit approval of scope and technical approach, and evidence for golden
102
+ and dark paths with optional Engram persistence. Existing installations should
103
+ follow the [migration steps](#working-modes).
104
+
100
105
  The process exists to ship working software, not to produce documents. It is a loop:
101
106
 
102
107
  ```text
@@ -140,51 +145,62 @@ The canonical principles, process, workflow, quality gates, and guidelines are i
140
145
  ### Orchestration in OpenCode
141
146
 
142
147
  `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.
148
+ The native primary acts as Coordinator and is the only agent that addresses the user.
149
+ It launches applicable roles directly for non-trivial work: read-only input, approved
150
+ implementation, independent verification, and authorized release. The callable
151
+ `team-lead` is an advisor; its binding denies shell and subdelegation and restricts edits
152
+ to companion notes.
153
+
154
+ The Coordinator leads an operational conversation (scope and observable acceptance)
155
+ and a technical conversation (choices, trade-offs, golden paths and dark paths). It
156
+ records explicit approval before implementation. Specialists return findings and evidence
157
+ to the Coordinator. Local notes capture approvals and handoffs; Engram retains relevant,
158
+ verified durable knowledge when enabled and available. See
159
+ [`core/guidelines/coordination.md`](core/guidelines/coordination.md).
150
160
 
151
161
  ### Working modes
152
162
 
153
163
  | Mode | Primary agent | Use |
154
164
  |---|---|---|
155
- | **Solo (default)** | native Build | One agent implements, tests, and commits. Specialists are optional reviews. |
156
- | **Orchestrated** | native Build + callable `team-lead` | The lead coordinates several specialists and verifies their evidence. |
165
+ | **Short workflow** | native primary | Routine changes in scope that introduce no new decision. |
166
+ | **Coordinated** | native primary | Direct specialist delegation for non-trivial work; the primary owns gates and communication. |
167
+ | **Single-agent fallback** | native primary | Disclose unavailable delegation; never claim independent review. |
157
168
  | **Legacy (do not use)** | `team-lead` as primary | A read-only lead blocks direct implementation and confuses the workflow. |
158
169
 
159
- **Migrating a legacy install (1.3.0 or earlier):**
170
+ **Migrating an existing install:**
171
+
172
+ Run the following with Development Companion 1.5.0 (use `node bin/devcomp.mjs`
173
+ from the source checkout to verify before publication).
160
174
 
161
175
  1. Review local customizations and make a private backup outside the repository of
162
176
  `AGENTS.md`, `CLAUDE.md`, `.companion/core/`, `.companion/roles/`, `.agents/skills/`,
163
177
  `.opencode/agents/` and existing OpenCode configuration. Do not publish the backup
164
178
  or read/copy `.env` files.
165
- 2. `npx development-companion@1.4.1 update <project>` (without `--force`). This refreshes
166
- the managed rules block while keeping existing skills, core documents, roles and
167
- bindings. Review the rules diff; merge any customized managed-block instructions
168
- from the backup. Compare preserved content with 1.4.1 and merge needed updates
169
- manually rather than replacing all customizations.
179
+ 2. `devcomp update <project>` (without `--force`). This installs missing content,
180
+ including the coordination guide, and refreshes the managed block while keeping
181
+ existing skills, core documents, roles and bindings. Review the diff, recover
182
+ any custom text from inside the old managed block, and merge changes manually
183
+ into preserved files that conflict with the new coordination contract.
170
184
  3. In the existing `opencode.json`/`opencode.jsonc` at the project root or in `.opencode/`,
171
185
  remove `"default_agent": "team-lead"` or set it to `"build"`, preserving other settings.
172
- 4. If `.opencode/agents/team-lead.md` still says `mode: primary`, review its backup and
173
- regenerate **only** that binding and role:
174
- `npx development-companion@1.4.1 add role team-lead --target <project> --force`.
175
- Reapply compatible customizations from the backup; keep `mode: subagent` and the
176
- coordination permissions. This targeted command overwrites both files without backup.
186
+ 4. If `.opencode/agents/team-lead.md` uses `mode: primary` or allows subdelegation,
187
+ merge the updated binding and role manually. Or, after backing up both files,
188
+ regenerate them with `devcomp add role team-lead --target <project> --force`.
189
+ This command overwrites both files without backup. Reapply compatible customizations;
190
+ keep `mode: subagent` and deny `subagent`. Apply step 3 only if the old default exists.
177
191
  5. Start a new OpenCode session (the current one keeps the old agent).
178
- 6. `npx development-companion@1.4.1 doctor <project>` must show
179
- `PASS default agent` and `PASS delivery mode`.
192
+ 6. `devcomp doctor <project>` checks the installed process, rules and OpenCode binding.
193
+ Then use a new session to verify actual behavior: the primary delegates and asks
194
+ for approval; withhold or reject it and check that implementation does not start.
180
195
 
181
196
  Do not use a blanket `update --force` as a migration shortcut: it deletes installed
182
197
  skill directories and replaces roles, core documents and bindings, including local
183
198
  customizations. `doctor` checks the managed process block; separately review any
184
199
  project-specific instructions outside it for conflicts.
185
200
 
186
- Why: a primary `team-lead` cannot edit code or run shell, so every change must be delegated.
187
- That is correct for orchestration and wrong for solo implementation.
201
+ The CLI installs prompts and permissions; it does not enforce conversational approval
202
+ as a runtime interlock. A harness may display that subagents ran even though only the
203
+ Coordinator addresses the user.
188
204
 
189
205
  ## Skills and profiles
190
206
 
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.4.1.tgz
46
+ npm install "$packdir"/development-companion-1.5.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 .
@@ -51,6 +51,14 @@ npm install "$packdir"/development-companion-1.4.1.tgz
51
51
 
52
52
  All checks must pass before publishing.
53
53
 
54
+ For coordination changes, also exercise a fresh agent session: give it a
55
+ non-trivial task with a decision to make. On the golden path, the primary
56
+ delegates read-only work, presents options, receives explicit approval, and
57
+ then delegates implementation and verification. On the dark path, withhold
58
+ or deny approval and confirm that no implementation starts. If Engram is
59
+ unavailable, confirm that local evidence remains and the primary does not
60
+ claim a successful save. The CLI smoke test is not a substitute for this check.
61
+
54
62
  ## 4. Publish
55
63
 
56
64
  ```bash
@@ -71,7 +79,7 @@ republish immediately. Wait a few minutes and verify:
71
79
  npm view development-companion version dist-tags
72
80
  ```
73
81
 
74
- The `latest` tag must point to `1.4.1`, not `0.0.0-stage`. If it still points to the
82
+ The `latest` tag must point to `1.5.0`, not `0.0.0-stage`. If it still points to the
75
83
  placeholder after several minutes, check the npmjs.com package page and the Staged
76
84
  Packages tab before retrying.
77
85
 
@@ -79,9 +87,9 @@ Packages tab before retrying.
79
87
 
80
88
  ```bash
81
89
  cd "$(mktemp -d)"
82
- npx development-companion@1.4.1 --version
83
- npx development-companion@1.4.1 init . --yes --harness opencode --profile web
84
- npx development-companion@1.4.1 doctor .
90
+ npx development-companion@1.5.0 --version
91
+ npx development-companion@1.5.0 init . --yes --harness opencode --profile web
92
+ npx development-companion@1.5.0 doctor .
85
93
  ```
86
94
 
87
95
  Also verify the package page:
@@ -93,19 +101,19 @@ https://www.npmjs.com/package/development-companion
93
101
  ## 6. Tag and publish the source release
94
102
 
95
103
  ```bash
96
- git tag -a v1.4.1 -m "v1.4.1"
104
+ git tag -a v1.5.0 -m "v1.5.0"
97
105
  git push origin main --tags
98
106
  ```
99
107
 
100
108
  Create the release on Codeberg:
101
109
 
102
110
  ```text
103
- https://codeberg.org/rockmadehome/development-companion/releases/new?tag=v1.4.1
111
+ https://codeberg.org/rockmadehome/development-companion/releases/new?tag=v1.5.0
104
112
  ```
105
113
 
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
114
+ Include the install command, supported harness tiers and migration from earlier releases:
115
+ OpenCode's primary delegates directly. Existing projects must review bindings with
116
+ nested delegation and any legacy `default_agent`. `--rules handoff` creates a
109
117
  local backup and blocks `doctor` until a human-reviewed merge. Do not commit pending
110
118
  rules while their backup exists only on the installing machine.
111
119
 
@@ -114,17 +122,18 @@ Migration steps:
114
122
  1. Follow the review and private backup checklist in
115
123
  [Migrating a legacy install](README.md#working-modes). Keep backups outside the
116
124
  repository; never read/copy `.env` files.
117
- 2. `npx development-companion@1.4.1 update <project>` **without `--force`**. Review the
125
+ 2. `npx development-companion@1.5.0 update <project>` **without `--force`**. Review the
118
126
  managed-block diff and merge customized rules from the backup. Compare preserved
119
127
  skills, core documents, roles and bindings with the release; merge needed updates.
120
128
  3. Remove `"default_agent": "team-lead"` or set it to `"build"` in the existing
121
129
  root or `.opencode/` `opencode.json(c)`, preserving other settings.
122
130
  4. Only after backing up and reviewing the lead role and binding, regenerate them
123
- if the binding still says `mode: primary`:
124
- `npx development-companion@1.4.1 add role team-lead --target <project> --force`.
131
+ if the binding still says `mode: primary` or allows subdelegation:
132
+ `npx development-companion@1.5.0 add role team-lead --target <project> --force`.
125
133
  This overwrites both files without backup; merge compatible customizations afterward.
126
- 5. Start a new OpenCode session.
127
- 6. `npx development-companion@1.4.1 doctor <project>` must pass `default agent` and
134
+ 5. Start a new OpenCode session. If you need to roll back the rules, restore
135
+ the reviewed backups; installing an older CLI does not revert generated files.
136
+ 6. `npx development-companion@1.5.0 doctor <project>` must pass `default agent` and
128
137
  `delivery mode`.
129
138
 
130
139
  Do not recommend blanket `update --force`: it deletes skill directories and overwrites
@@ -87,8 +87,9 @@ Roles are contracts in `.companion/roles/`. Bindings are thin:
87
87
 
88
88
  Pi has no built-in subagents: use the role contract as a prompt template or invoke the
89
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.
90
+ The harness-native primary is the sole user interlocutor and delegates directly through
91
+ the process in `AGENTS.md`. The callable team lead is an advisor, not a dispatcher.
92
+ OpenCode does not change its default agent.
92
93
 
93
94
  ## Limitations by harness
94
95
 
@@ -37,9 +37,8 @@ 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` — 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.
40
+ - `team-lead.md` — callable `mode: subagent` for advice on scope and sequencing.
41
+ - The 11 specialists — `mode: subagent`, launched directly by the native primary.
43
42
 
44
43
  It does not set `default_agent` or write `.opencode/opencode.json`: native Build
45
44
  retains its tools and applies the Team Lead workflow from `AGENTS.md`. Existing
@@ -49,10 +48,10 @@ the existing configuration; review and refresh the old binding, then open a new
49
48
  session. Existing project rules should be merged by the harness agent, or placed
50
49
  in a backed-up pending handoff with `init --rules handoff`.
51
50
 
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.
51
+ OpenCode does not route by intent by itself. The primary follows the routing and
52
+ approval gates in the coordination guide and is the sole user interlocutor. The
53
+ callable advisor denies code edits and shell. All generated roles deny `subagent`
54
+ to avoid nested routing; the native Build agent keeps its delegation tools.
56
55
 
57
56
  Instructions alone cannot guarantee that a model followed the workflow: verify real
58
57
  agent behavior in a new session, not only `devcomp doctor`.
@@ -92,13 +91,13 @@ OpenCode V2 uses **`permissions`** (plural), an ordered list of
92
91
  `action` / `resource` / `effect` rules. The legacy OpenCode V1 shape (`permission`,
93
92
  `permission.task`, boolean maps) is not used in new bindings.
94
93
 
95
- ## Team lead example
94
+ ## Team lead advisor example
96
95
 
97
- The generated binding is a callable router, not the native primary:
96
+ The generated binding is a callable advisor, not the native primary:
98
97
 
99
98
  ```yaml
100
99
  ---
101
- description: Leads discovery, planning, delegation, and closure.
100
+ description: Advises the primary on scope and delivery sequencing.
102
101
  mode: subagent
103
102
  permissions:
104
103
  - action: edit
@@ -121,18 +120,18 @@ permissions:
121
120
  effect: deny
122
121
  - action: subagent
123
122
  resource: "*"
124
- effect: allow
123
+ effect: deny
125
124
  ---
126
125
  ```
127
126
 
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.
127
+ The last matching rule wins. The callable advisor can read and write its own
128
+ companion notes, but it cannot launch a specialist, edit code or run shell commands.
130
129
  The native primary keeps its tools. Specialists get
131
130
  `{ "action": "subagent", "resource": "*", "effect": "deny" }` so they cannot spawn more
132
131
  agents.
133
132
 
134
- To restrict which specialists the team lead may launch, replace `"*"` with explicit
135
- `resource` entries such as `architect`, `qa-engineer`, or `mobile-engineer`.
133
+ If an existing binding allows `subagent`, follow the migration in the main
134
+ README; do not enable nested delegation for the callable advisor.
136
135
 
137
136
  ## Limitations
138
137
 
@@ -0,0 +1,78 @@
1
+ # Coordinated Delivery
2
+
3
+ ## One interlocutor
4
+
5
+ The session's primary agent acts as **Coordinator** (Team Lead). Only it asks the
6
+ user questions, presents options, requests approvals, or communicates status and
7
+ closure. It keeps its native tools and owns the result. Specialists report to
8
+ the Coordinator, not to the user, and do not launch other agents. A callable
9
+ `team-lead` advises on scope or sequencing when requested; it is not the primary.
10
+
11
+ For non-trivial work, launch the applicable specialists directly with the
12
+ harness's native delegation tool. A role name in a plan is not a delegation.
13
+ For a routine, in-scope change that introduces no new decision, use the short
14
+ workflow. If a required role or native delegation is unavailable or denied,
15
+ record the limitation and what was done in single-agent mode. Never present it
16
+ as independent review; stop before a gate that requires independence.
17
+
18
+ ## Two conversations, then authorization
19
+
20
+ 1. **Operational conversation.** Agree on the problem, users, first observable
21
+ slice, scope and exclusions, constraints, acceptance criteria and who approves
22
+ them. Ask only what can change the slice. Follow with bounded, read-only
23
+ specialist work to prepare the technical conversation.
24
+ 2. **Technical conversation.** Show the existing conventions and viable choices
25
+ with trade-offs, a recommendation, affected contracts, risks and rollback
26
+ where relevant. Include the verification plan and its golden and dark paths.
27
+ Ask for explicit approval of the scoped approach before authorizing product
28
+ changes, the walking skeleton, a commit, or an external action. Record in the
29
+ operational brief what was approved, by whom and where; link an ADR if needed.
30
+
31
+ Silence, a specialist's recommendation, an Engram entry, or approval for another
32
+ slice is not authorization. Until approval, continue only safe investigation and
33
+ planning. A rejection or material departure from the approved scope, technical
34
+ approach or risk stops affected work until the Coordinator gets a new approval.
35
+ Routine details covered by approved conventions need no separate decision.
36
+ Release is separate and requires the user's authorization.
37
+
38
+ ## Delegate by phase
39
+
40
+ | Phase | Direct handoff from the Coordinator | Evidence returned |
41
+ |---|---|---|
42
+ | Frame | QA defines observable checks; architect proposes structural choices; security reviews new trust boundaries; UX or SRE advises when the slice needs it. | Options, risks, questions and proposed checks. |
43
+ | Build | Relevant implementation role from the Team Lead routing table. | Small runnable change, tests, demo, files and limitations. |
44
+ | Verify | QA reviews the delivered behavior independently; security reviews high-risk work and before release. | Expected vs. actual per path, findings and residual risk. |
45
+ | Release | SRE prepares and, once authorized, executes the release; QA and security confirm release gates. | Target smoke test, install/upgrade or deployment evidence and recovery plan. |
46
+ | Close | Coordinator integrates reports and owns the user-facing result. | Approvals, scope, evidence, deferred items and next step. |
47
+
48
+ Give each specialist a slice ID, role, permitted paths/actions, approved
49
+ decisions or read-only status, deliverable, and required checks. Use one slice
50
+ per writer; parallelize only independent reads or disjoint writes. Review the
51
+ returned evidence before accepting it or advancing a gate.
52
+
53
+ ## Paths and handoffs
54
+
55
+ - **Golden paths:** the primary user or system journeys that must succeed end
56
+ to end. Record inputs, observable outcome and how to verify it.
57
+ - **Dark paths:** meaningful failures or adverse states (for example denial,
58
+ invalid input, timeout, partial failure or rollback). Record the trigger,
59
+ expected safe state or recovery, and how to verify it.
60
+
61
+ Map both to acceptance criteria. Each critical dark path needs evidence or a
62
+ documented gap; do not turn an untested must-pass case into a pass.
63
+
64
+ Every specialist returns: **slice · role · status** (verified, partial, blocked);
65
+ observations and findings with severity/impact and file or command evidence;
66
+ golden/dark results where applicable; unverified items; blockers or questions
67
+ for the Coordinator; and durable learning worth retaining. Separate observed
68
+ facts from recommendations. Do not publish raw logs or confidential data.
69
+
70
+ Keep the brief, approval references, and summarized handoffs under the configured
71
+ companion docs directory. Use distinct files if several specialists record
72
+ notes concurrently; the Coordinator owns the consolidated status. When Engram
73
+ is enabled and available, recall prior decisions relevant to the slice and
74
+ save or update verified, durable findings and approved decisions by project
75
+ and topic; do not duplicate observations. If the child cannot write, return
76
+ the proposed learning to the Coordinator. If persistence is unavailable,
77
+ disabled or unconfirmed, keep the evidence locally and report the limitation
78
+ without claiming it was saved. Local records remain the source of truth.
@@ -15,7 +15,7 @@ and the evidence shows it works. Clever code that cannot be verified is not bett
15
15
 
16
16
  **Working software is the measure of progress.** Planning is a tool, not a deliverable.
17
17
 
18
- - The first commit lands in the first work block, before the second design document.
18
+ - The first commit lands in the first implementation work block after approval.
19
19
  - Every session ends with a running increment, a failing test that defines the next step, or a
20
20
  named blocker that needs the user.
21
21
  - A document is progress only when it unblocks a slice that is about to be built.
@@ -167,8 +167,8 @@ State what you know, what you assume, and what you could not verify. Hidden
167
167
  uncertainty becomes someone else's incident.
168
168
 
169
169
  **In practice:** report evidence, open questions, and residual risk. Record
170
- architectural decisions with context and consequences. Ask before making a
171
- high-impact choice on the user's behalf.
170
+ technical decisions with context and consequences. Get user approval for new
171
+ technical choices in the scoped approach before implementing them.
172
172
 
173
173
  **Red flags:** confident claims without checks; silent scope changes; decisions
174
174
  buried in chat instead of documented.
package/core/process.md CHANGED
@@ -17,7 +17,7 @@ waterfall. Planning is a tool that unblocks the next slice; when it stops doing
17
17
 
18
18
  > **A phase is complete when code runs, not when a document exists.**
19
19
 
20
- - The first commit must land in the first work block, before the second design document.
20
+ - The first commit must land in the first implementation block after approval.
21
21
  - Every session ends with one of: a running increment, a failing test that defines the next
22
22
  step, or a named blocker that needs the user.
23
23
  - A planning artifact is written **just in time**, only as deep as the next slice needs.
@@ -47,7 +47,9 @@ in roles and skills.
47
47
 
48
48
  ## Phase 1 — Frame (30–60 minutes, one page)
49
49
 
50
- **Owner:** Team Lead. **Participant:** the user.
50
+ **Owner:** the primary agent acting as Coordinator. **Participant:** the user.
51
+ Follow `core/guidelines/coordination.md`: the Coordinator conducts both
52
+ conversations, and specialists return technical observations to the Coordinator.
51
53
 
52
54
  Answer only what can change the first slice:
53
55
 
@@ -56,15 +58,16 @@ Answer only what can change the first slice:
56
58
  3. What constraints could invalidate that slice: platform, data, auth, privacy, performance,
57
59
  third parties, deadline?
58
60
  4. What is explicitly out of scope for this slice?
59
- 5. Which decisions are irreversible and need the user now?
61
+ 5. Which technical choices need approval now, and what alternatives are viable?
60
62
 
61
63
  Everything else is deferred. Stack details, full schemas, complete UX, and exhaustive test
62
64
  matrices are decided when the slice needs them.
63
65
 
64
66
  **Artifact:** `.companion/local/01-operational-brief.md`, maximum one page.
65
67
 
66
- **Gate:** the user confirms the first slice and its acceptance criteria; no blocking question
67
- remains for that slice.
68
+ **Gate:** the user explicitly approves the first slice, its acceptance criteria,
69
+ and the technical approach after seeing the trade-offs and golden/dark paths.
70
+ No implementation starts while approval is missing.
68
71
 
69
72
  **Timebox:** if the brief is not done in one work block, cut it to the five questions above.
70
73
 
@@ -169,7 +172,7 @@ first commit, cut it or defer it.
169
172
  | Change | Process |
170
173
  |---|---|
171
174
  | Typo, docs, one-line fix | Recon → change → check → report |
172
- | Feature in one layer | Brief → implement → tests → self-review |
175
+ | Feature in one layer | Scoped conversations and approval → implement → tests → review |
173
176
  | Cross-layer, data, auth, public contract | Frame → skeleton or thin slice → tests → independent security/QA |
174
177
  | New project | Frame (1 page) → walking skeleton → slice loop |
175
178
  | Incident | Stabilize → diagnose → fix → regression test → short postmortem |
@@ -90,9 +90,9 @@ For a new project or a major change, progress is gated by running code, not by d
90
90
 
91
91
  | Gate | Evidence |
92
92
  |---|---|
93
- | Frame | One-page brief: problem, first slice, acceptance criteria, constraints; user confirms. |
93
+ | Frame | Operational and technical conversations; user explicitly approves scope, criteria and approach; golden/dark paths identified. |
94
94
  | Walking skeleton | The end-to-end path runs with fakes; one command; one test; a commit. |
95
- | Slice | Acceptance criteria covered by tests; scoped diff; a demo; a commit. |
95
+ | Slice | Golden and critical dark paths checked; specialist evidence and gaps recorded; scoped diff, demo and commit. |
96
96
  | Release | No open critical/high findings; must-pass checks green; install/upgrade verified in the target. |
97
97
 
98
98
  A planning artifact is not a gate. It is a living note that unblocks a slice. See
@@ -4,8 +4,8 @@
4
4
 
5
5
  ## Mission
6
6
 
7
- Choose boundaries and trade-offs that make the system correct, understandable, and
8
- evolvable. Produce decisions that another engineer can implement without guessing.
7
+ Propose boundaries and trade-offs that make the system correct, understandable, and
8
+ evolvable. Return recommendations to the Coordinator for user approval.
9
9
 
10
10
  ## Use when
11
11
 
@@ -43,12 +43,13 @@ Do not use for routine implementation work that already has a clear design.
43
43
  3. **List options** — include the simplest option and the "do nothing" option.
44
44
  4. **Evaluate** — correctness, complexity, coupling, reversibility, security,
45
45
  performance, accessibility, cost, operability.
46
- 5. **Decide** — choose one, explain why, and record what you are giving up.
46
+ 5. **Recommend** — explain why and what the project gives up. Leave the choice pending
47
+ until the Coordinator records the user's approval.
47
48
  6. **Define invariants** — what must always hold, and where it is enforced.
48
49
  7. **Design failure modes** — timeouts, retries, partial failure, invalid input,
49
50
  authorization denial, migration failure.
50
51
  8. **Plan verification** — how the design will be tested and observed.
51
- 9. **Record** — add the decision to `plannification/` (local) or the project's ADR log.
52
+ 9. **Record** — note the recommendation in the configured docs directory or ADR log.
52
53
 
53
54
  ## Boundaries
54
55
 
@@ -63,7 +64,7 @@ Do not use for routine implementation work that already has a clear design.
63
64
  ## Handoff
64
65
 
65
66
  ```markdown
66
- **Decision:** ...
67
+ **Recommended decision and approval status:** ...
67
68
  **Context:** ...
68
69
  **Options considered:** ...
69
70
  **Consequences:** ...
@@ -37,8 +37,8 @@ works and that the important ways it could break are covered.
37
37
  1. **Map the risk** — rank the flows by impact and likelihood of failure.
38
38
  2. **Cover the boundaries** — empty, null, minimum, maximum, malformed, oversized,
39
39
  duplicate, concurrent, unauthorized, offline, timeout, partial failure.
40
- 3. **Test behavior** — assert observable outcomes, not private implementation.
41
- 4. **Check the negative paths** — invalid input, denied access, failed dependency,
40
+ 3. **Check golden paths** — prove the primary observable journeys end to end.
41
+ 4. **Check dark paths** — invalid input, denied access, failed dependency,
42
42
  retry exhaustion, rollback.
43
43
  5. **Check state transitions** — double submit, back/forward, refresh, stale cache,
44
44
  race conditions, idempotency.
@@ -64,6 +64,7 @@ works and that the important ways it could break are covered.
64
64
  **Test plan:** risk → level → cases
65
65
  **Automated:** files and commands
66
66
  **Manual:** steps and observed result
67
+ **Golden/dark paths:** acceptance criterion, expected vs. actual, evidence
67
68
  **Defects:** reproduction, expected vs actual, severity
68
69
  **Residual risk:** not covered and why
69
70
  ```
@@ -6,8 +6,10 @@
6
6
 
7
7
  Ship working increments. When you own coordination, frame the smallest valuable slice, route
8
8
  it to specialists, enforce the delivery gates, and report with evidence. You are accountable
9
- for **code that lands**, not for the volume of documents produced. The native primary agent may
10
- follow this contract with its own tools; a callable team-lead specialist reports to that primary.
9
+ for **code that lands**, not for the volume of documents produced. The native primary agent
10
+ acts as Coordinator and is the sole user interlocutor. Apply
11
+ `core/guidelines/coordination.md` (installed under `.companion/core/`). A callable
12
+ team-lead specialist only advises the Coordinator and never delegates.
11
13
 
12
14
  ## Use when
13
15
 
@@ -34,8 +36,8 @@ Do not use for a one-file fix or a routine review; handle those directly.
34
36
 
35
37
  ## Operating checklist
36
38
 
37
- 1. **Frame (≤ 1 work block)** — five questions: problem, first end-to-end slice, constraints,
38
- non-goals, irreversible decisions. Write one page. Stop.
39
+ 1. **Frame (≤ 1 work block)** — lead the operational conversation, launch relevant specialists
40
+ directly, present the technical options, and record explicit user approval before build.
39
41
  2. **Prove the path** — delegate a walking skeleton with fakes where needed. It must run with
40
42
  one command and have one test. Commit.
41
43
  3. **Slice loop** — pick the highest-risk or highest-value slice; one writer per slice; require
@@ -70,20 +72,18 @@ is inventory.
70
72
  | Native Linux | `desktop-linux-engineer` |
71
73
  | Cross-platform core | `multiplatform-engineer` |
72
74
  | Deploy, observability, secrets | `sre-engineer` |
73
- | No specialist fits | `general` or `explore`, or ask the user |
75
+ | No specialist fits | Coordinator uses a bounded native generalist or reports the gap |
74
76
 
75
77
  ## Boundaries
76
78
 
77
- - As a dedicated coordination subagent, do not design the architecture, implement features,
78
- run tests, or run shell commands. The native primary retains its normal capabilities and
79
- may implement a focused slice directly while following these delivery gates.
80
- - Do not edit code. Your only writable paths are `.companion/local/**` and
81
- `docs/companion/**`.
79
+ - As a callable advisor, do not speak to the user, launch subagents, design the architecture,
80
+ implement features, run tests, or run shell commands. If asked to take notes, write only
81
+ to the configured companion docs directory. Return questions and observations to the Coordinator.
82
82
  - Do not claim a delegation you did not perform. A delegation is real only if a native
83
83
  delegation tool launched another agent; otherwise describe the work as a single-agent role
84
84
  switch or manual handoff.
85
- - **Do not spend more than one work block producing planning artifacts before the first
86
- commit.**
85
+ - **Do not spend more than one work block producing planning artifacts before asking for
86
+ approval.**
87
87
  - **Do not accept a child that returns only a document when code was requested.** Send it back
88
88
  with a bounded instruction to implement.
89
89
  - **Stop the line:** if two consecutive delegations produce no running code, stop and tell the
@@ -94,19 +94,21 @@ is inventory.
94
94
 
95
95
  ## Handoff
96
96
 
97
- Where the harness supports native subagents, launch one with:
97
+ As Coordinator, launch applicable native subagents with:
98
98
 
99
99
  ```markdown
100
100
  **Role:** architect | cybersecurity | qa | frontend | backend | mobile | platform | sre
101
101
  **Goal:** the smallest shippable outcome
102
102
  **Context:** files, decisions, constraints
103
- **Deliverable:** code + tests + evidence (not a document, unless explicitly requested)
103
+ **Authorization:** read-only or approved decisions, permitted paths and actions
104
+ **Deliverable:** recommendation, implementation or verification, depending on phase
104
105
  **Slice:** what must work end-to-end when this returns
105
106
  **Verification:** command to run and output to return
107
+ **Return to Coordinator:** findings, evidence, golden/dark results, gaps and proposed durable learning
106
108
  **Do not:** out-of-scope work, files to avoid, planning expansion
107
109
  ```
108
110
 
109
111
  After the child returns, verify the evidence and either accept it or send a follow-up. Reject
110
- "done" without a commit, a test, or a reproducible demo.
112
+ an implementation reported as "done" without a test or a reproducible demo.
111
113
 
112
114
  Close with the completion format in the `development-workflow` skill.