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 +12 -0
- package/README.md +40 -24
- package/RELEASE.md +24 -15
- package/adapters/README.md +3 -2
- package/adapters/opencode/README.md +14 -15
- package/core/guidelines/coordination.md +78 -0
- package/core/principles.md +3 -3
- package/core/process.md +9 -6
- package/core/quality-gates.md +2 -2
- package/core/roles/architect.md +6 -5
- package/core/roles/qa-engineer.md +3 -2
- package/core/roles/team-lead.md +17 -15
- package/core/workflow.md +6 -13
- package/package.json +2 -1
- package/skills/development-workflow/SKILL.md +7 -0
- package/skills/project-discovery/SKILL.md +9 -3
- package/skills/ux-design/SKILL.md +4 -0
- package/src/cli.mjs +34 -9
- package/src/content.mjs +1 -1
- package/src/install.mjs +4 -44
- package/templates/artifacts/01-operational-brief.md +9 -1
- package/templates/rules/AGENTS.block.md +18 -15
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
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
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
|
-
| **
|
|
156
|
-
| **
|
|
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
|
|
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. `
|
|
166
|
-
the
|
|
167
|
-
bindings. Review the
|
|
168
|
-
|
|
169
|
-
|
|
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`
|
|
173
|
-
|
|
174
|
-
`
|
|
175
|
-
|
|
176
|
-
|
|
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. `
|
|
179
|
-
|
|
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
|
-
|
|
187
|
-
|
|
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.
|
|
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.
|
|
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.
|
|
83
|
-
npx development-companion@1.
|
|
84
|
-
npx development-companion@1.
|
|
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.
|
|
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.
|
|
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
|
|
107
|
-
OpenCode
|
|
108
|
-
|
|
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.
|
|
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
|
-
|
|
124
|
-
|
|
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
|
-
|
|
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
|
package/adapters/README.md
CHANGED
|
@@ -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
|
|
91
|
-
|
|
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
|
|
41
|
-
- The 11 specialists — `mode: subagent`, launched by the native primary
|
|
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
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
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
|
|
96
|
+
The generated binding is a callable advisor, not the native primary:
|
|
98
97
|
|
|
99
98
|
```yaml
|
|
100
99
|
---
|
|
101
|
-
description:
|
|
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:
|
|
123
|
+
effect: deny
|
|
125
124
|
---
|
|
126
125
|
```
|
|
127
126
|
|
|
128
|
-
The last matching rule wins. The callable
|
|
129
|
-
|
|
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
|
-
|
|
135
|
-
|
|
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.
|
package/core/principles.md
CHANGED
|
@@ -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
|
|
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
|
-
|
|
171
|
-
|
|
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
|
|
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:**
|
|
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
|
|
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
|
|
67
|
-
|
|
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 |
|
|
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 |
|
package/core/quality-gates.md
CHANGED
|
@@ -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 |
|
|
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 |
|
|
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
|
package/core/roles/architect.md
CHANGED
|
@@ -4,8 +4,8 @@
|
|
|
4
4
|
|
|
5
5
|
## Mission
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
evolvable.
|
|
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. **
|
|
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** —
|
|
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
|
-
**
|
|
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. **
|
|
41
|
-
4. **Check
|
|
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
|
```
|
package/core/roles/team-lead.md
CHANGED
|
@@ -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
|
|
10
|
-
|
|
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)** —
|
|
38
|
-
|
|
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 |
|
|
75
|
+
| No specialist fits | Coordinator uses a bounded native generalist or reports the gap |
|
|
74
76
|
|
|
75
77
|
## Boundaries
|
|
76
78
|
|
|
77
|
-
- As a
|
|
78
|
-
run tests, or run shell commands.
|
|
79
|
-
|
|
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
|
|
86
|
-
|
|
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
|
-
|
|
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
|
-
**
|
|
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
|
|
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
|
-
|
|
27
|
-
|
|
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 →
|
|
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.
|
|
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
|
-
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
:
|
|
401
|
+
? "team-lead is a callable advisor; native primary owns delivery"
|
|
402
|
+
: `legacy primary team-lead binding; ${review}`
|
|
401
403
|
);
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
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": "
|
|
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
|
|
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
|
-
|
|
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 =
|
|
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:
|
|
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
|
-
##
|
|
17
|
+
## Run the workflow
|
|
18
18
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
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.**
|
|
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.
|