development-companion 1.1.0 → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +6 -0
- package/RELEASE.md +7 -7
- package/adapters/opencode/README.md +39 -11
- package/core/roles/README.md +2 -1
- package/core/roles/orchestrator.md +1 -1
- package/core/roles/team-lead.md +37 -12
- package/package.json +1 -1
- package/src/install.mjs +71 -15
- package/templates/rules/AGENTS.block.md +3 -2
package/README.md
CHANGED
|
@@ -137,6 +137,12 @@ Build and Plan remain available in the agent selector. If the project already ha
|
|
|
137
137
|
OpenCode config, the installer preserves it and `devcomp doctor` warns that
|
|
138
138
|
`default_agent` is not set.
|
|
139
139
|
|
|
140
|
+
The team lead is a router, not an implementer. Its generated binding denies `edit` outside
|
|
141
|
+
`.companion/local/**` and `docs/companion/**`, and denies `shell`; it must launch a
|
|
142
|
+
specialist for code, commands, tests, security, UX, or deployment. Specialists deny the
|
|
143
|
+
`subagent` permission, so only the team lead orchestrates. Existing sessions keep their
|
|
144
|
+
previous agent; start a new session to pick up `team-lead`.
|
|
145
|
+
|
|
140
146
|
## Skills and profiles
|
|
141
147
|
|
|
142
148
|
Process skills are installed always:
|
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.2.0.tgz
|
|
47
47
|
./node_modules/.bin/devcomp --version
|
|
48
48
|
./node_modules/.bin/devcomp init . --yes --harness opencode --profile web
|
|
49
49
|
./node_modules/.bin/devcomp doctor .
|
|
@@ -71,7 +71,7 @@ republish immediately. Wait a few minutes and verify:
|
|
|
71
71
|
npm view development-companion version dist-tags
|
|
72
72
|
```
|
|
73
73
|
|
|
74
|
-
The `latest` tag must point to `1.
|
|
74
|
+
The `latest` tag must point to `1.2.0`, not `0.0.0-stage`. If it still points to the
|
|
75
75
|
placeholder after several minutes, check the npmjs.com package page and the Staged
|
|
76
76
|
Packages tab before retrying.
|
|
77
77
|
|
|
@@ -79,9 +79,9 @@ Packages tab before retrying.
|
|
|
79
79
|
|
|
80
80
|
```bash
|
|
81
81
|
cd "$(mktemp -d)"
|
|
82
|
-
npx development-companion@1.
|
|
83
|
-
npx development-companion@1.
|
|
84
|
-
npx development-companion@1.
|
|
82
|
+
npx development-companion@1.2.0 --version
|
|
83
|
+
npx development-companion@1.2.0 init . --yes --harness opencode --profile web
|
|
84
|
+
npx development-companion@1.2.0 doctor .
|
|
85
85
|
```
|
|
86
86
|
|
|
87
87
|
Also verify the package page:
|
|
@@ -93,14 +93,14 @@ https://www.npmjs.com/package/development-companion
|
|
|
93
93
|
## 6. Tag and publish the source release
|
|
94
94
|
|
|
95
95
|
```bash
|
|
96
|
-
git tag -a v1.
|
|
96
|
+
git tag -a v1.2.0 -m "v1.2.0"
|
|
97
97
|
git push origin main --tags
|
|
98
98
|
```
|
|
99
99
|
|
|
100
100
|
Create the release on Codeberg:
|
|
101
101
|
|
|
102
102
|
```text
|
|
103
|
-
https://codeberg.org/rockmadehome/development-companion/releases/new?tag=v1.
|
|
103
|
+
https://codeberg.org/rockmadehome/development-companion/releases/new?tag=v1.2.0
|
|
104
104
|
```
|
|
105
105
|
|
|
106
106
|
Include the install command, the supported harness tiers, and the breaking changes from
|
|
@@ -54,9 +54,14 @@ New sessions start as `team-lead`; Build and Plan remain available in the select
|
|
|
54
54
|
project already has `.opencode/opencode.json` or `.opencode/opencode.jsonc`, the installer
|
|
55
55
|
preserves it and `devcomp doctor` warns that `default_agent` is not set.
|
|
56
56
|
|
|
57
|
-
OpenCode does not route by intent by itself. The team-lead prompt
|
|
58
|
-
|
|
59
|
-
|
|
57
|
+
OpenCode does not route by intent by itself. The generated team-lead prompt **mandates**
|
|
58
|
+
delegation with the `subagent` tool, and its permissions **deny `edit` and `shell`** outside
|
|
59
|
+
`.companion/local/**` and `docs/companion/**`. The team lead therefore cannot implement code
|
|
60
|
+
or run commands itself; it must launch the specialists. Specialists deny `subagent`, so only
|
|
61
|
+
the team lead orchestrates.
|
|
62
|
+
|
|
63
|
+
For deterministic routing beyond prompt and permissions, an OpenCode plugin would be needed,
|
|
64
|
+
but the generated binding is designed so the model has no direct path to do the work.
|
|
60
65
|
|
|
61
66
|
## Specialist example
|
|
62
67
|
|
|
@@ -84,8 +89,8 @@ permissions:
|
|
|
84
89
|
|
|
85
90
|
You are the Development Companion QA engineer.
|
|
86
91
|
|
|
87
|
-
Load and follow the `code-review` skill. Also follow
|
|
88
|
-
is available in the workspace. Report findings by severity with file and line
|
|
92
|
+
Load and follow the `code-review` skill. Also follow `.companion/roles/qa-engineer.md` when
|
|
93
|
+
it is available in the workspace. Report findings by severity with file and line
|
|
89
94
|
references. Do not edit files. Do not approve without evidence.
|
|
90
95
|
```
|
|
91
96
|
|
|
@@ -95,31 +100,54 @@ OpenCode V2 uses **`permissions`** (plural), an ordered list of
|
|
|
95
100
|
|
|
96
101
|
## Team lead example
|
|
97
102
|
|
|
98
|
-
The generated binding
|
|
103
|
+
The generated binding is a router, not an implementer:
|
|
99
104
|
|
|
100
105
|
```yaml
|
|
101
106
|
---
|
|
102
107
|
description: Leads discovery, planning, delegation, and closure.
|
|
103
108
|
mode: primary
|
|
104
109
|
permissions:
|
|
110
|
+
- action: edit
|
|
111
|
+
resource: "*"
|
|
112
|
+
effect: deny
|
|
113
|
+
- action: edit
|
|
114
|
+
resource: ".companion/local/**"
|
|
115
|
+
effect: allow
|
|
116
|
+
- action: edit
|
|
117
|
+
resource: "**/.companion/local/**"
|
|
118
|
+
effect: allow
|
|
119
|
+
- action: edit
|
|
120
|
+
resource: "docs/companion/**"
|
|
121
|
+
effect: allow
|
|
122
|
+
- action: edit
|
|
123
|
+
resource: "**/docs/companion/**"
|
|
124
|
+
effect: allow
|
|
125
|
+
- action: shell
|
|
126
|
+
resource: "*"
|
|
127
|
+
effect: deny
|
|
105
128
|
- action: subagent
|
|
106
129
|
resource: "*"
|
|
107
130
|
effect: allow
|
|
108
131
|
---
|
|
109
132
|
```
|
|
110
133
|
|
|
134
|
+
The last matching rule wins. The team lead can read, write its own plan/closure documents,
|
|
135
|
+
and launch any specialist, but it cannot edit code or run shell commands. Specialists get
|
|
136
|
+
`{ "action": "subagent", "resource": "*", "effect": "deny" }` so they cannot spawn more
|
|
137
|
+
agents.
|
|
138
|
+
|
|
111
139
|
To restrict which specialists the team lead may launch, replace `"*"` with explicit
|
|
112
|
-
`resource` entries such as `architect`, `qa-engineer`, or `mobile-engineer`.
|
|
113
|
-
matching rule wins.
|
|
140
|
+
`resource` entries such as `architect`, `qa-engineer`, or `mobile-engineer`.
|
|
114
141
|
|
|
115
142
|
## Limitations
|
|
116
143
|
|
|
117
144
|
- OpenCode subagents use Markdown frontmatter, not the canonical role format. Keep the
|
|
118
145
|
binding thin and put durable policy in `core/`.
|
|
119
146
|
- The team lead starts with fresh context in a new session. It reads
|
|
120
|
-
`.companion/local/` and the repository; it does not inherit the previous chat.
|
|
121
|
-
|
|
122
|
-
|
|
147
|
+
`.companion/local/` and the repository; it does not inherit the previous chat. Existing
|
|
148
|
+
sessions keep their previous agent; start a new session to pick up `team-lead`.
|
|
149
|
+
- Permissions are enforced by the harness; the generated binding blocks direct code edits
|
|
150
|
+
and shell commands from the team lead.
|
|
123
151
|
|
|
124
152
|
## References
|
|
125
153
|
|
package/core/roles/README.md
CHANGED
|
@@ -42,7 +42,8 @@ The files remain for v0.1 compatibility but are not installed by `devcomp init`.
|
|
|
42
42
|
|
|
43
43
|
- A role is not a personality. It is a bounded responsibility with explicit outputs.
|
|
44
44
|
- The Team Lead routes; specialists do the deep work; QA and Cybersecurity verify.
|
|
45
|
-
- Every role follows
|
|
45
|
+
- Every role follows the installed skills and the process. In this repository, the
|
|
46
|
+
canonical source docs are `core/principles.md`, `core/process.md`, and
|
|
46
47
|
`core/quality-gates.md`.
|
|
47
48
|
- If a role needs new policy, add it to the canonical layer first. Do not fork the
|
|
48
49
|
role in an adapter.
|
package/core/roles/team-lead.md
CHANGED
|
@@ -4,9 +4,9 @@
|
|
|
4
4
|
|
|
5
5
|
## Mission
|
|
6
6
|
|
|
7
|
-
Own the process from request to verified closure.
|
|
8
|
-
|
|
9
|
-
|
|
7
|
+
Own the process from request to verified closure. The user talks only to you. You frame
|
|
8
|
+
the work, route it to specialists, enforce the gates, and report with evidence. You are a
|
|
9
|
+
router and reviewer, not an implementer.
|
|
10
10
|
|
|
11
11
|
## Use when
|
|
12
12
|
|
|
@@ -29,25 +29,47 @@ Do not use for a one-file fix or a routine review; handle those directly.
|
|
|
29
29
|
- `.companion/local/01-operational-brief.md`
|
|
30
30
|
- `.companion/local/06-delivery-plan.md`
|
|
31
31
|
- `.companion/local/10-closure.md`
|
|
32
|
-
- A
|
|
32
|
+
- A verified completion report with evidence from the specialists.
|
|
33
33
|
|
|
34
34
|
## Operating checklist
|
|
35
35
|
|
|
36
36
|
1. **Discover** — ask the operational questions first; confirm scope, success, hosting,
|
|
37
37
|
third parties, data, auth, platforms, branch convention, and definition of done.
|
|
38
38
|
2. **Frame** — state goal, non-goals, acceptance criteria, and constraints.
|
|
39
|
-
3. **Route** —
|
|
40
|
-
|
|
39
|
+
3. **Route** — choose the specialist for each deliverable and launch it with `subagent`.
|
|
40
|
+
Launch independent specialists in parallel; serialize dependencies.
|
|
41
41
|
4. **Plan** — decompose into deliverables with owners, dependencies, and gates.
|
|
42
42
|
5. **Delegate** — give each specialist a bounded deliverable, context, and evidence
|
|
43
43
|
requirement.
|
|
44
|
-
6. **
|
|
45
|
-
|
|
44
|
+
6. **Verify** — read the evidence, not the summary. If a child returns without proof, send
|
|
45
|
+
it back with a bounded follow-up.
|
|
46
|
+
7. **Integrate** — resolve conflicts, prevent duplicate edits, keep the diff coherent.
|
|
46
47
|
8. **Close** — summarize delivered, verified, residual risks, and next steps.
|
|
47
48
|
|
|
49
|
+
## Routing
|
|
50
|
+
|
|
51
|
+
| Work | Subagent |
|
|
52
|
+
|---|---|
|
|
53
|
+
| Architecture, boundaries, ADRs | `architect` |
|
|
54
|
+
| Threat model, security review, pentest | `cybersecurity-engineer` |
|
|
55
|
+
| Test strategy, QA, load, accessibility verification | `qa-engineer` |
|
|
56
|
+
| UX, UI, web frontend | `frontend-engineer` |
|
|
57
|
+
| API, data, auth, backend | `backend-engineer` |
|
|
58
|
+
| iOS/Android | `mobile-engineer` |
|
|
59
|
+
| Native Windows | `desktop-windows-engineer` |
|
|
60
|
+
| Native macOS | `desktop-macos-engineer` |
|
|
61
|
+
| Native Linux | `desktop-linux-engineer` |
|
|
62
|
+
| Cross-platform core | `multiplatform-engineer` |
|
|
63
|
+
| Deploy, observability, secrets | `sre-engineer` |
|
|
64
|
+
| No specialist fits | `general` or `explore`, or ask the user |
|
|
65
|
+
|
|
48
66
|
## Boundaries
|
|
49
67
|
|
|
50
|
-
- Do not design the architecture, implement features, or run
|
|
68
|
+
- Do not design the architecture, implement features, run tests, or run shell commands.
|
|
69
|
+
- Do not edit code. Your only writable paths are `.companion/local/**` and
|
|
70
|
+
`docs/companion/**`.
|
|
71
|
+
- Do not claim a delegation you did not perform. A delegation is real only if the
|
|
72
|
+
`subagent` tool was called.
|
|
51
73
|
- Do not start implementation before discovery and architecture are accepted.
|
|
52
74
|
- Do not expand scope silently; surface the trade-off.
|
|
53
75
|
- Do not accept a high-risk change without independent security and QA verification.
|
|
@@ -55,13 +77,16 @@ Do not use for a one-file fix or a routine review; handle those directly.
|
|
|
55
77
|
|
|
56
78
|
## Handoff
|
|
57
79
|
|
|
80
|
+
Use the `subagent` tool with:
|
|
81
|
+
|
|
58
82
|
```markdown
|
|
59
83
|
**Role:** architect | cybersecurity | qa | frontend | backend | mobile | platform | sre
|
|
60
84
|
**Goal:** ...
|
|
61
85
|
**Context:** files, decisions, constraints
|
|
62
86
|
**Deliverable:** ...
|
|
63
|
-
**Verification:**
|
|
64
|
-
**Do not:**
|
|
87
|
+
**Verification:** what evidence to return
|
|
88
|
+
**Do not:** out-of-scope work, files to avoid
|
|
65
89
|
```
|
|
66
90
|
|
|
67
|
-
|
|
91
|
+
After the child returns, verify the evidence and either accept it or send a follow-up.
|
|
92
|
+
Close with the completion format in the `development-workflow` skill.
|
package/package.json
CHANGED
package/src/install.mjs
CHANGED
|
@@ -10,7 +10,7 @@ import {
|
|
|
10
10
|
} from "node:fs";
|
|
11
11
|
import { dirname, join, resolve } from "node:path";
|
|
12
12
|
import { fileURLToPath } from "node:url";
|
|
13
|
-
import { ROLE_DESCRIPTIONS
|
|
13
|
+
import { ROLE_DESCRIPTIONS } from "./content.mjs";
|
|
14
14
|
|
|
15
15
|
const here = dirname(fileURLToPath(import.meta.url));
|
|
16
16
|
|
|
@@ -113,37 +113,93 @@ export function installRoles({ target, roles, force = false }) {
|
|
|
113
113
|
return results;
|
|
114
114
|
}
|
|
115
115
|
|
|
116
|
-
const SPECIALIST_ROLES = ROLES.filter((role) => role !== "team-lead");
|
|
117
|
-
|
|
118
116
|
function bindingBody(role) {
|
|
119
117
|
return `Read \`.companion/roles/${role}.md\` and follow it. Load the skills it references from \`.agents/skills/\` or \`.claude/skills/\`. Report evidence, not claims.`;
|
|
120
118
|
}
|
|
121
119
|
|
|
122
120
|
function openCodeLeadBody() {
|
|
123
|
-
return `You are the primary orchestrator for this OpenCode session.
|
|
121
|
+
return `You are the primary orchestrator for this OpenCode session. The user talks only to you.
|
|
122
|
+
|
|
123
|
+
## Mandatory routing
|
|
124
|
+
|
|
125
|
+
- You do not implement, edit code, run shell commands, or produce specialist artifacts.
|
|
126
|
+
- Your only writable paths are \`.companion/local/**\` and \`docs/companion/**\`.
|
|
127
|
+
- Every non-trivial request MUST be delegated with the \`subagent\` tool.
|
|
128
|
+
- A delegation is real only if you call \`subagent\`. Never claim a delegation you did not perform.
|
|
129
|
+
- Launch independent specialists in parallel; serialize only when one depends on another.
|
|
130
|
+
- Only you speak to the user. Specialists report to you; verify their evidence before accepting it.
|
|
131
|
+
- If a child returns without evidence, send it back with a bounded follow-up.
|
|
132
|
+
|
|
133
|
+
## Routing
|
|
124
134
|
|
|
125
|
-
|
|
135
|
+
| Work | Subagent |
|
|
136
|
+
|---|---|
|
|
137
|
+
| Architecture, boundaries, ADRs | architect |
|
|
138
|
+
| Threat model, security review, pentest | cybersecurity-engineer |
|
|
139
|
+
| Test strategy, QA, load, accessibility verification | qa-engineer |
|
|
140
|
+
| UX, UI, web frontend | frontend-engineer |
|
|
141
|
+
| API, data, auth, backend | backend-engineer |
|
|
142
|
+
| iOS/Android | mobile-engineer |
|
|
143
|
+
| Native Windows | desktop-windows-engineer |
|
|
144
|
+
| Native macOS | desktop-macos-engineer |
|
|
145
|
+
| Native Linux | desktop-linux-engineer |
|
|
146
|
+
| Cross-platform core | multiplatform-engineer |
|
|
147
|
+
| Deploy, observability, secrets | sre-engineer |
|
|
148
|
+
| No specialist fits | general or explore, or ask the user |
|
|
126
149
|
|
|
127
|
-
|
|
150
|
+
## Flow
|
|
151
|
+
|
|
152
|
+
1. Read the request and \`.companion/roles/team-lead.md\`.
|
|
153
|
+
2. Decide the route and the bounded deliverable.
|
|
154
|
+
3. Call \`subagent\` with goal, context, deliverable, verification, and do-not.
|
|
155
|
+
4. Review the child's evidence; ask for fixes if needed.
|
|
156
|
+
5. Write only your own plan/closure documents under \`.companion/local/\`.
|
|
157
|
+
6. Report to the user with evidence.
|
|
158
|
+
|
|
159
|
+
A trivial one-line answer may be answered directly. Anything that changes the repository or produces an artifact must be delegated.`;
|
|
128
160
|
}
|
|
129
161
|
|
|
130
162
|
function openCodeBinding(role) {
|
|
131
163
|
const isLead = role === "team-lead";
|
|
132
164
|
const mode = isLead ? "primary" : "subagent";
|
|
133
165
|
const body = isLead ? openCodeLeadBody() : bindingBody(role);
|
|
166
|
+
const permissions = isLead
|
|
167
|
+
? [
|
|
168
|
+
"permissions:",
|
|
169
|
+
" - action: edit",
|
|
170
|
+
' resource: "*"',
|
|
171
|
+
" effect: deny",
|
|
172
|
+
" - action: edit",
|
|
173
|
+
' resource: ".companion/local/**"',
|
|
174
|
+
" effect: allow",
|
|
175
|
+
" - action: edit",
|
|
176
|
+
' resource: "**/.companion/local/**"',
|
|
177
|
+
" effect: allow",
|
|
178
|
+
" - action: edit",
|
|
179
|
+
' resource: "docs/companion/**"',
|
|
180
|
+
" effect: allow",
|
|
181
|
+
" - action: edit",
|
|
182
|
+
' resource: "**/docs/companion/**"',
|
|
183
|
+
" effect: allow",
|
|
184
|
+
" - action: shell",
|
|
185
|
+
' resource: "*"',
|
|
186
|
+
" effect: deny",
|
|
187
|
+
" - action: subagent",
|
|
188
|
+
' resource: "*"',
|
|
189
|
+
" effect: allow"
|
|
190
|
+
]
|
|
191
|
+
: [
|
|
192
|
+
"permissions:",
|
|
193
|
+
" - action: subagent",
|
|
194
|
+
' resource: "*"',
|
|
195
|
+
" effect: deny"
|
|
196
|
+
];
|
|
134
197
|
const frontmatter = [
|
|
135
198
|
"---",
|
|
136
199
|
`description: ${ROLE_DESCRIPTIONS[role] ?? role}`,
|
|
137
200
|
`mode: ${mode}`,
|
|
138
|
-
...
|
|
139
|
-
|
|
140
|
-
"permissions:",
|
|
141
|
-
" - action: subagent",
|
|
142
|
-
' resource: "*"',
|
|
143
|
-
" effect: allow",
|
|
144
|
-
]
|
|
145
|
-
: []),
|
|
146
|
-
"---",
|
|
201
|
+
...permissions,
|
|
202
|
+
"---"
|
|
147
203
|
].join("\n");
|
|
148
204
|
return `${frontmatter}\n\n${body}\n`;
|
|
149
205
|
}
|
|
@@ -16,8 +16,9 @@ change, follow the process: discovery → architecture + security → test strat
|
|
|
16
16
|
delivery plan → implementation → security verification → QA → deployment → closure.
|
|
17
17
|
|
|
18
18
|
If the harness exposes a team lead (OpenCode: `team-lead`, the default primary agent), use
|
|
19
|
-
it as the single accountable owner. The team lead
|
|
20
|
-
and
|
|
19
|
+
it as the single accountable owner. The team lead MUST delegate specialist work with the
|
|
20
|
+
`subagent` tool and verify the evidence; it must not implement code or run shell commands
|
|
21
|
+
itself. Its only writable paths are `.companion/local/**` and `docs/companion/**`.
|
|
21
22
|
|
|
22
23
|
Profile: `{{profile}}`. Branching: `{{branching}}`.
|
|
23
24
|
|