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 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.1.0.tgz
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.1.0`, not `0.0.0-stage`. If it still points to the
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.1.0 --version
83
- npx development-companion@1.1.0 init . --yes --harness opencode --profile web
84
- npx development-companion@1.1.0 doctor .
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.1.0 -m "v1.1.0"
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.1.0
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 explicitly instructs the
58
- model to delegate with the `subagent` tool; the model chooses the specialist. For
59
- deterministic routing you would need an OpenCode plugin.
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 `core/roles/qa-engineer.md` when it
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 restricts nothing by default, but it can be narrowed:
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`. The last
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
- - Permissions are enforced by the harness; do not rely on prompt instructions alone for
122
- read-only review.
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
 
@@ -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 `core/principles.md`, `core/process.md`, and
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.
@@ -66,4 +66,4 @@ When delegating, provide:
66
66
  **Do not:** out-of-scope work, files to avoid
67
67
  ```
68
68
 
69
- When reporting to the user, use the completion format in `core/quality-gates.md`.
69
+ When reporting to the user, use the completion format in the `development-workflow` skill.
@@ -4,9 +4,9 @@
4
4
 
5
5
  ## Mission
6
6
 
7
- Own the process from request to verified closure. Ask the operational and technical
8
- questions, choose the route, delegate to specialists, enforce the gates, and report with
9
- evidence. The team lead does not do the deep specialist work.
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 clear delegation record and a verified completion report.
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** — invoke the architect and cybersecurity engineer in parallel after
40
- discovery; then QA for the test strategy; then frontend for UX.
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. **Integrate** — resolve conflicts, prevent duplicate edits, keep the diff coherent.
45
- 7. **Verify** — read the evidence, not the summary. Reject "done" without proof.
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 the penetration test yourself.
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
- Close with the completion format in `core/quality-gates.md`.
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "development-companion",
3
- "version": "1.1.0",
3
+ "version": "1.2.0",
4
4
  "description": "Harness-neutral development process, roles, and skills for AI coding agents.",
5
5
  "license": "MIT",
6
6
  "type": "module",
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, ROLES } from "./content.mjs";
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. Read \`.companion/roles/team-lead.md\` and follow it. Delegate specialist work with the \`subagent\` tool; do not do the specialists' deep work yourself.
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
- Available specialists: ${SPECIALIST_ROLES.join(", ")}.
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
- Load the skills referenced by the role from \`.agents/skills/\` or \`.claude/skills/\`. Report evidence, not claims.`;
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
- ...(isLead
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 delegates to the specialist subagents
20
- and closes with evidence; it does not do their deep work itself.
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