development-companion 1.4.1 → 1.5.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,12 @@
1
+ # Changelog
2
+
3
+ ## 1.5.0
4
+
5
+ - The native primary coordinates delivery, directly invokes specialists, and is
6
+ the sole user interlocutor. In OpenCode, the callable Team Lead is an advisor
7
+ and cannot subdelegate.
8
+ - Non-trivial work requires an operational conversation and explicit approval
9
+ of the technical approach. Role handoffs record evidence for golden and dark
10
+ paths, with optional Engram persistence and local records as the fallback.
11
+ - `doctor` detects outdated OpenCode Team Lead permissions. See the
12
+ [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.
package/core/workflow.md CHANGED
@@ -23,18 +23,9 @@ Identify the task type and the minimum rigor it needs.
23
23
  If the task mixes types, split it. Do not ship a refactor and a behavior change in
24
24
  the same unreviewable diff.
25
25
 
26
- **First-commit rule:** for a new feature or project, create the thinnest runnable path before
27
- expanding the design. A plan that does not produce a commit is not progress.
28
-
29
- ## Phase 0.5 — First commit
30
-
31
- Before deep recon or a full plan, ask: *what is the smallest end-to-end path that can run?*
32
-
33
- - Wire the real entry point to a fake or minimal implementation.
34
- - Get one command and one test working.
35
- - Commit.
36
-
37
- Then use the rest of this workflow to deepen that path slice by slice.
26
+ For non-trivial work the Coordinator follows `core/guidelines/coordination.md`
27
+ for delegation, operational and technical conversations, and the approval gate.
28
+ Do not use the first-commit rule to skip approval.
38
29
 
39
30
  ## Phase 1 — Recon
40
31
 
@@ -95,6 +86,8 @@ Keep the plan proportional. A 40-file plan for a 5-line fix is a smell.
95
86
 
96
87
  ## Phase 4 — Implement
97
88
 
89
+ - After approval, get the smallest end-to-end path and one test running before
90
+ expanding the design. Keep the first commit in the first implementation block.
98
91
  - Follow the plan; if reality contradicts it, stop and revise the plan.
99
92
  - Match local patterns before introducing new abstractions.
100
93
  - Keep commits/checkpoints logical and reversible.
@@ -177,6 +170,6 @@ Do not pad the report. Do not claim success you did not verify.
177
170
  | Risk | Workflow |
178
171
  |---|---|
179
172
  | Low (typo, docs, one-line fix) | Recon → change → check → report |
180
- | Medium (feature in one layer) | Brief → plan → implement → tests → self-review |
173
+ | Medium (feature in one layer) | Brief → technical approval → implement → tests → review |
181
174
  | High (cross-layer, data, auth, public API) | Full workflow + independent review + rollback plan |
182
175
  | Incident | Stabilize first, then diagnose, fix, add regression coverage, write a short postmortem |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "development-companion",
3
- "version": "1.4.1",
3
+ "version": "1.5.0",
4
4
  "description": "Harness-neutral development process, roles, and skills for AI coding agents.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -27,6 +27,7 @@
27
27
  "templates/",
28
28
  "adapters/",
29
29
  "README.md",
30
+ "CHANGELOG.md",
30
31
  "LICENSE",
31
32
  "RELEASE.md"
32
33
  ],
@@ -82,6 +82,13 @@ For non-trivial work, state:
82
82
 
83
83
  Keep the plan proportional to the change.
84
84
 
85
+ For non-trivial work, the primary agent coordinates the operational and technical
86
+ conversations, with native specialist input where available. Only the primary
87
+ agent asks the user to explicitly approve the scope, acceptance criteria and
88
+ technical approach. Include golden and critical dark paths in verification.
89
+ Keep implementation blocked while approval is pending or the approved approach
90
+ needs a material change.
91
+
85
92
  ### 5. Implement
86
93
 
87
94
  - Follow the plan; revise it if reality contradicts it.
@@ -40,6 +40,9 @@ too broad: cut it.
40
40
 
41
41
  ## Procedure
42
42
 
43
+ Only the primary agent acting as Coordinator conducts these conversations
44
+ with the user. Specialists return findings and questions to that agent.
45
+
43
46
  ### 1. Operational discovery
44
47
 
45
48
  Ask one topic at a time. Record answers verbatim where they matter.
@@ -76,6 +79,8 @@ Ask one topic at a time. Record answers verbatim where they matter.
76
79
  ### 2. Technical discovery
77
80
 
78
81
  Only after the operational picture is clear.
82
+ Ask applicable specialists for read-only input and synthesize their options,
83
+ trade-offs, risks, and golden/dark verification paths.
79
84
 
80
85
  - Stack and versions: verify the latest stable release; do not invent version numbers.
81
86
  - Repository layout: monorepo or single repo; workspace tool.
@@ -91,7 +96,8 @@ Only after the operational picture is clear.
91
96
 
92
97
  - Summarize the brief in the user's language.
93
98
  - List assumptions, unknowns, and decisions that need the user.
94
- - Do not proceed to architecture while a blocking question is open.
99
+ - Record explicit user approval of the scoped approach before implementation.
100
+ A blocking question, rejection, or silence keeps the affected work pending.
95
101
 
96
102
  ## Output
97
103
 
@@ -124,12 +130,12 @@ Write `.companion/local/01-operational-brief.md` with:
124
130
  ## Open questions
125
131
  ```
126
132
 
127
- Add a short technical addendum if the discovery already covered stack decisions.
133
+ Record the technical options and approval reference in the brief or a linked ADR.
128
134
 
129
135
  ## Verification
130
136
 
131
137
  - Every section has an answer or an explicit "unknown".
132
- - The user confirmed the brief.
138
+ - The user explicitly approved the scope, acceptance criteria, and technical approach.
133
139
  - The branch convention is recorded with its source: detected, user, or default.
134
140
  - No acceptance criterion is untestable.
135
141
  - No secret values were read or printed.
@@ -109,6 +109,10 @@ the flow, not network calls, recording, authentication or persistent data.
109
109
 
110
110
  ### 8. Get approval
111
111
 
112
+ The primary agent presents the prototype and collects user approval. A UX
113
+ specialist returns the prototype, observed interactions and open questions to
114
+ the primary instead of asking the user directly.
115
+
112
116
  Present the flow, states, screenshots, and prototype entry point. Ask for explicit
113
117
  approval or a concrete change. Do not start implementation from an unapproved mockup;
114
118
  after approval hand off the validated states and interactions to the implementation role
package/src/cli.mjs CHANGED
@@ -391,20 +391,45 @@ async function cmdDoctor(args) {
391
391
  add("orchestrator", "fail", "team-lead binding missing");
392
392
  } else {
393
393
  const content = readFileSync(teamLeadPath, "utf8");
394
- const callable = /^mode:\s*subagent\s*$/m.test(content);
394
+ const frontmatter = content.match(/^---[ \t]*\r?\n((?:[^\n]*\n)*?)---[ \t]*(?:\r?\n|$)/)?.[1] ?? "";
395
+ const callable = /^mode:[ \t]*(?:subagent|"subagent"|'subagent')[ \t]*(?:#.*)?$/m.test(frontmatter);
396
+ const review = "review local edits before running devcomp add role team-lead --force (replaces the role and binding)";
395
397
  add(
396
398
  "orchestrator",
397
399
  callable ? "pass" : "fail",
398
400
  callable
399
- ? "team-lead is callable; native primary owns delivery"
400
- : "legacy primary team-lead binding; review local edits and run devcomp add role team-lead --force"
401
+ ? "team-lead is a callable advisor; native primary owns delivery"
402
+ : `legacy primary team-lead binding; ${review}`
401
403
  );
402
- const denies = (action) => new RegExp(`- action: ${action}\\s+resource: "\\*"\\s+effect: deny`).test(content);
403
- const delegates = /- action: subagent\s+resource: "\*"\s+effect: allow/.test(content);
404
- add("lead permissions", denies("edit") && denies("shell") && delegates ? "pass" : "fail",
405
- denies("edit") && denies("shell") && delegates
406
- ? "edits and shell denied; delegation allowed"
407
- : "outdated team-lead binding; review local edits and run devcomp add role team-lead --force to replace it");
404
+
405
+ // Inspect the binding's block-list format, not examples in the Markdown body.
406
+ const block = frontmatter.match(/^permissions:[ \t]*(?:#[^\r\n]*)?\r?\n((?:[^\S\r\n]*\r?\n|[ \t-][^\r\n]*\r?\n)*)/m)?.[1] ?? "";
407
+ const rule = /^[ \t]*-[ \t]+action:[ \t]*(.+?)[ \t]*\r?\n[ \t]+resource:[ \t]*(.+?)[ \t]*\r?\n[ \t]+effect:[ \t]*(.+?)[ \t]*\r?$/gm;
408
+ const scalar = (value) => value.match(/^(?:"([^"\\]*)"|'([^']*)'|([^\s"'#]+))[ \t]*(?:#.*)?$/)
409
+ ?.slice(1).find((part) => part !== undefined);
410
+ const parsed = Array.from(block.matchAll(rule), (match) => match.slice(1).map(scalar));
411
+ const permissions = parsed.filter(([action, resource, effect]) =>
412
+ action && resource && ["allow", "ask", "deny"].includes(effect));
413
+ const unsupported = permissions.length !== parsed.length ||
414
+ block.replace(rule, "").split(/\r?\n/).some((line) => !/^[ \t]*(?:#.*)?$/.test(line));
415
+ const denies = (action) => permissions.some(([a, resource, effect]) =>
416
+ a === action && resource === "*" && effect === "deny");
417
+ const targetsSubagents = (action) => {
418
+ const pattern = action.replace(/[.*+?^${}()|[\]\\]/g, (char) =>
419
+ char === "*" ? ".*" : char === "?" ? "." : `\\${char}`);
420
+ return new RegExp(`^${pattern}$`).test("subagent");
421
+ };
422
+ const denySubagentsAt = permissions.findLastIndex(([action, resource, effect]) =>
423
+ targetsSubagents(action) && resource === "*" && effect === "deny");
424
+ const delegates = permissions.slice(denySubagentsAt + 1).some(([action, , effect]) =>
425
+ targetsSubagents(action) && (effect === "allow" || effect === "ask"));
426
+ const restricted = !unsupported && denies("edit") && denies("shell") && denySubagentsAt >= 0 && !delegates;
427
+ add("lead permissions", restricted ? "pass" : "fail",
428
+ restricted
429
+ ? "edit and shell restrictions present; subdelegation denied"
430
+ : delegates
431
+ ? `legacy team-lead binding permits subdelegation; ${review}`
432
+ : `cannot verify team-lead permission restrictions; ${review}`);
408
433
  }
409
434
 
410
435
  const configPaths = ["opencode.json", "opencode.jsonc", ".opencode/opencode.json", ".opencode/opencode.jsonc"];
package/src/content.mjs CHANGED
@@ -47,7 +47,7 @@ export const ROLES = [
47
47
  ];
48
48
 
49
49
  export const ROLE_DESCRIPTIONS = {
50
- "team-lead": "Leads discovery, planning, delegation, and closure. Use at project start or when coordinating multiple specialists.",
50
+ "team-lead": "Advises the primary on scope, sequencing, and delivery risks. Reports to the primary without subdelegating.",
51
51
  architect: "Defines boundaries, patterns, infrastructure, and ADRs. Use before implementation and for structural changes.",
52
52
  "cybersecurity-engineer": "Builds the threat model and verifies security with evidence. Use during architecture and before release.",
53
53
  "qa-engineer": "Defines the test strategy before development and verifies afterward. Use before implementation and before closure.",
package/src/install.mjs CHANGED
@@ -135,55 +135,15 @@ export function installCanonical({ target, force = false }) {
135
135
  }
136
136
 
137
137
  function bindingBody(role) {
138
- return `Read \`.companion/core/process.md\`, \`.companion/core/principles.md\`, \`.companion/core/quality-gates.md\`, and \`.companion/roles/${role}.md\` and follow them. Load the skills it references from \`.agents/skills/\` or \`.claude/skills/\`. Report evidence, not claims.`;
139
- }
140
-
141
- function openCodeLeadBody() {
142
- return `You are a callable coordination specialist. The native primary agent remains accountable to the user and retains its normal tools.
143
-
144
- ## Mandatory routing
145
-
146
- - You do not implement, edit code, run shell commands, or produce specialist artifacts.
147
- - Your only writable paths are \`.companion/local/**\` and \`docs/companion/**\`.
148
- - When asked to coordinate work needing multiple specialists, delegate with the \`subagent\` tool.
149
- - A delegation is real only if you call \`subagent\`. Never claim a delegation you did not perform.
150
- - Launch independent specialists in parallel; serialize only when one depends on another.
151
- - Report to the primary agent; it speaks to the user and verifies your evidence.
152
- - If a child returns without evidence, send it back with a bounded follow-up.
153
-
154
- ## Routing
138
+ return `Read \`.companion/core/guidelines/coordination.md\`, \`.companion/core/process.md\`, \`.companion/core/principles.md\`, \`.companion/core/quality-gates.md\`, and \`.companion/roles/${role}.md\`. Load the role's referenced skills from \`.agents/skills/\` or \`.claude/skills/\`.
155
139
 
156
- | Work | Subagent |
157
- |---|---|
158
- | Architecture, boundaries, ADRs | architect |
159
- | Threat model, security review, pentest | cybersecurity-engineer |
160
- | Test strategy, QA, load, accessibility verification | qa-engineer |
161
- | UX, UI, web frontend | frontend-engineer |
162
- | API, data, auth, backend | backend-engineer |
163
- | iOS/Android | mobile-engineer |
164
- | Native Windows | desktop-windows-engineer |
165
- | Native macOS | desktop-macos-engineer |
166
- | Native Linux | desktop-linux-engineer |
167
- | Cross-platform core | multiplatform-engineer |
168
- | Deploy, observability, secrets | sre-engineer |
169
- | No specialist fits | general or explore, or ask the user |
170
-
171
- ## Flow
172
-
173
- 1. Read the request, \`.companion/core/process.md\`, \`.companion/core/principles.md\`, \`.companion/core/quality-gates.md\`, and \`.companion/roles/team-lead.md\`.
174
- 2. Decide the route and the bounded deliverable.
175
- 3. Call \`subagent\` with goal, context, deliverable, verification, and do-not.
176
- 4. Review the child's evidence; ask for fixes if needed.
177
- 5. Write only your own plan/closure documents under the configured docs directory in \`AGENTS.md\` (\`.companion/local/\` by default, \`docs/companion/\` when tracked).
178
- 6. Report to the primary agent with evidence.
179
-
180
- A read-only recommendation may be answered directly. Anything that changes the repository or produces an artifact must be delegated.`;
140
+ ${role === "team-lead" ? "Act as a callable coordination advisor. " : ""}Do not subdelegate or contact the user directly. Return evidence and open questions to the primary agent.`;
181
141
  }
182
142
 
183
143
  function openCodeBinding(role) {
184
144
  const isLead = role === "team-lead";
185
145
  const mode = "subagent";
186
- const body = isLead ? openCodeLeadBody() : bindingBody(role);
146
+ const body = bindingBody(role);
187
147
  const permissions = isLead
188
148
  ? [
189
149
  "permissions:",
@@ -207,7 +167,7 @@ function openCodeBinding(role) {
207
167
  " effect: deny",
208
168
  " - action: subagent",
209
169
  ' resource: "*"',
210
- " effect: allow"
170
+ " effect: deny"
211
171
  ]
212
172
  : [
213
173
  "permissions:",
@@ -45,7 +45,15 @@
45
45
 
46
46
  ## Open questions
47
47
 
48
+ ## Technical conversation
49
+
50
+ - Options, recommendation, trade-offs and rollback:
51
+ - Golden paths and observable evidence:
52
+ - Dark paths and expected safe result or recovery:
53
+
48
54
  ## Approval
49
55
 
56
+ - Status: pending | approved | rejected
57
+ - Approved scope, criteria and technical decisions (or linked ADR):
50
58
  - Confirmed by:
51
- - Date:
59
+ - Date and approval reference:
@@ -14,21 +14,24 @@ This project uses the Development Companion process. Read these files before wor
14
14
  - `.companion/roles/qa-engineer.md` — test strategy and verification.
15
15
  - `.companion/roles/` — the rest of the team.
16
16
 
17
- ## Workflow
17
+ ## Run the workflow
18
18
 
19
- Use the `development-workflow` skill for non-trivial work and the `incremental-delivery` skill
20
- when the plan starts growing faster than the code. For a new project or a major change:
21
-
22
- ```text
23
- frame (one page) → walking skeleton → slice loop → verify → release → close
24
- ```
25
-
26
- The native harness agent is the single accountable delivery owner: apply the Team Lead
27
- contract without losing native edit, shell, skills, or delegation tools. Invoke the
28
- `team-lead` specialist for substantial coordination when useful, not for every routine
29
- slice. In OpenCode use native Build by default; the callable `team-lead` is a restricted
30
- subagent. In harnesses without subagents, follow the role yourself; never claim a
31
- delegation you did not perform.
19
+ 1. The native primary agent is the **Coordinator and sole user interlocutor**.
20
+ Read `.companion/core/guidelines/coordination.md` before non-trivial work.
21
+ In OpenCode use native Build by default; the callable `team-lead` only advises.
22
+ 2. For non-trivial work: operational conversation → direct specialist input →
23
+ technical conversation and explicit user approval → build → verify → release
24
+ if authorized → close. Record scope, exclusions, acceptance criteria and
25
+ approved technical choices. Do not implement on silence; ask again if scope
26
+ or approach changes materially. Use `development-workflow` to guide the slice.
27
+ 3. Launch applicable roles directly with the native subagent tool, with clear
28
+ file ownership and evidence. Specialists report findings to the Coordinator,
29
+ not to the user. If delegation is unavailable, record the limitation and
30
+ never label single-agent work as independent verification.
31
+ 4. Verify golden paths (critical success journeys) and dark paths (meaningful
32
+ failures and recovery). Record each role's evidence and unresolved findings
33
+ in the configured docs directory. Use Engram for verified durable decisions
34
+ and findings when enabled and available; keep local records in either case.
32
35
 
33
36
  ## Project rules integration
34
37
 
@@ -48,7 +51,7 @@ Profile: `{{profile}}`. Branching: `{{branching}}`.
48
51
 
49
52
  ## Non-negotiables
50
53
 
51
- 1. **Working software first.** The first commit lands in the first work block. A session that
54
+ 1. **Working software first.** After approval, the first commit lands in the first work block. A session that
52
55
  produces only documents, when the user asked for implementation, is a process failure.
53
56
  2. **One slice at a time, end-to-end.** No horizontal "finish the domain first" plans. WIP limit:
54
57
  one slice per writer.