development-companion 1.5.0 → 1.7.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 CHANGED
@@ -1,5 +1,48 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.7.0
4
+
5
+ - **Forced flow in OpenCode.** `devcomp init`/`update` now install a `coordinator` primary
6
+ agent and set `default_agent: coordinator`. The coordinator cannot edit product code or run
7
+ shell: it writes the frame under the planning directory and delegates. Implementation
8
+ subagents always resolve to `ask`, so the user confirms the delegation with the native
9
+ permission prompt. There is no magic approval phrase; approval is natural language.
10
+ - **Runtime adapter.** A dependency-free OpenCode plugin injects the five canonical files into
11
+ every session, including sessions opened inside a child repository, and forces the delegation
12
+ prompt even after a saved "always" approval. `devcomp setup opencode --global` installs it
13
+ under `~/.config/opencode/plugins/devcomp.ts` for every project.
14
+ - **Config merge.** `devcomp update` merges `opencode.json` with `default_agent: coordinator`,
15
+ the canonical instructions, a global `git push` denial and a read-only `explore`. Unknown
16
+ keys are preserved; the previous file is backed up under `.companion/local/`.
17
+ - **Read-only recon.** `architect`, `qa-engineer` and `cybersecurity-engineer` bindings deny
18
+ product edits; architect/security deny shell, QA only allows tests, lint, build and git
19
+ inspection.
20
+ - **Doctor.** Verifies `default_agent=coordinator`, the coordinator binding and permissions,
21
+ the runtime plugin and gate, the canonical instructions, the `git push`/explore rules, and
22
+ the managed template. It fails on the old native-Build default and on missing plugins.
23
+ - **New role contract.** `core/roles/coordinator.md`; `team-lead` remains a read-only advisor.
24
+ - **Notifications with the subagent-heavy flow.** The documented OpenCode notify recipe is
25
+ updated to debounce the parent idle turn (`notify_idle_settle_ms`, default 10 s), so a
26
+ subagent report does not produce one toast per subagent; child and archived sessions are
27
+ silent, while questions, permissions and errors remain immediate.
28
+
29
+ ## 1.6.0
30
+
31
+ - `devcomp update` replaces framework-owned skills, roles, bindings, and canonical
32
+ content by default. Use `--keep` to preserve them for a manual merge.
33
+ - `AGENTS.md` is now a complete managed template plus a `# User guiding` section.
34
+ Updates preserve User guiding verbatim and always write `AGENTS.md.bak`.
35
+ - Existing legacy `AGENTS.md` files are migrated automatically (old content under
36
+ User guiding). Ambiguous structures leave a merge-pending notice and `doctor`
37
+ fails until an agent merges the backup.
38
+ - `doctor` verifies canonical, role, and skill content against the package, plus
39
+ the template version and the presence of User guiding.
40
+
41
+ ## 1.5.1
42
+
43
+ - `devcomp update --dry-run` now reports the plan and writes nothing instead of
44
+ silently updating the installation.
45
+
3
46
  ## 1.5.0
4
47
 
5
48
  - The native primary coordinates delivery, directly invokes specialists, and is
package/README.md CHANGED
@@ -89,18 +89,21 @@ The managed block is delimited by `<!-- development-companion:start -->` and
89
89
 
90
90
  | Command | Purpose |
91
91
  |---|---|
92
- | `devcomp init [dir]` | Install the process, skills, roles, rules, and manifest. |
92
+ | `devcomp init [dir]` | Install the process, skills, roles, rules, runtime adapter, and manifest. |
93
93
  | `devcomp add <skill\|role\|profile> <name>` | Add content to an existing install. |
94
+ | `devcomp setup opencode --global` | Install the OpenCode runtime adapter for every project. |
94
95
  | `devcomp scaffold [dir]` | Generate the TypeScript reference monorepo. |
95
- | `devcomp doctor [dir]` | Check skills, roles, rules, branching, and Engram. |
96
- | `devcomp update [dir]` | Refresh installed content without overwriting local edits. |
96
+ | `devcomp doctor [dir]` | Check content, the coordinator binding, the runtime plugin, and the config gate. |
97
+ | `devcomp update [dir]` | Refresh framework content, bindings, plugin, and OpenCode config. |
97
98
 
98
99
  ## The process
99
100
 
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).
101
+ **New in 1.7.0:** a forced flow in OpenCode. The primary is the `coordinator` agent
102
+ (`default_agent: coordinator`); it cannot edit product code or run shell, so it must frame,
103
+ ask for approval and delegate. A runtime plugin injects the canonical process in every
104
+ session, including child repositories, and forces a user permission prompt before an
105
+ implementation subagent starts. Approval is natural language; there is no magic phrase.
106
+ `devcomp update` migrates existing installations.
104
107
 
105
108
  The process exists to ship working software, not to produce documents. It is a loop:
106
109
 
@@ -124,6 +127,7 @@ For a small change, the process collapses to the workflow in `core/workflow.md`.
124
127
 
125
128
  | Role | Primary question |
126
129
  |---|---|
130
+ | Coordinator | What is the smallest approved slice, which role owns it, and what evidence closes it? |
127
131
  | Team Lead | What is the shortest path to a verified delivery? |
128
132
  | Architect | What boundaries and trade-offs make this correct and evolvable? |
129
133
  | Cybersecurity Engineer | What can be attacked, and what evidence proves the control works? |
@@ -144,63 +148,53 @@ The canonical principles, process, workflow, quality gates, and guidelines are i
144
148
 
145
149
  ### Orchestration in OpenCode
146
150
 
147
- `devcomp init` preserves OpenCode's native Build default and any existing OpenCode config.
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
151
+ `devcomp init`/`update` installs a `coordinator` primary agent and sets
152
+ `default_agent: coordinator` in `opencode.json`. The coordinator can read, search, ask and
153
+ write frames under `plannification/` or `.companion/local/`; it cannot edit product code or
154
+ run shell. Implementation subagents always resolve to `ask`, and the runtime plugin forces the
155
+ user permission prompt even after a saved "always". `build` remains available only as an
156
+ explicit user escape hatch (`--agent build` or an agent switch).
157
+
158
+ The plugin at `.opencode/plugins/devcomp/index.ts` searches upward for the nearest
159
+ `.companion/config.json` and injects the five canonical files at runtime. It fixes the child
160
+ repository case: OpenCode discovers the meta-repo config, bindings and plugins, but relative
161
+ `instructions` do not resolve below the child project root. `devcomp setup opencode --global`
162
+ installs the same adapter under `~/.config/opencode/plugins/devcomp.ts`.
163
+
164
+ The Coordinator leads an operational conversation (scope and observable acceptance) and a
165
+ technical conversation (choices, trade-offs, golden and dark paths). It presents a one-page
166
+ frame and asks for approval in natural language; the user's approval and the native delegation
167
+ prompt are the gate. Specialists return findings and evidence. Local notes capture approvals
168
+ and handoffs; Engram retains verified durable knowledge when enabled and available. See
159
169
  [`core/guidelines/coordination.md`](core/guidelines/coordination.md).
160
170
 
161
171
  ### Working modes
162
172
 
163
173
  | Mode | Primary agent | Use |
164
174
  |---|---|---|
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. |
168
- | **Legacy (do not use)** | `team-lead` as primary | A read-only lead blocks direct implementation and confuses the workflow. |
175
+ | **Coordinated** | `coordinator` | Default for every project; the coordinator frames, asks, delegates and verifies. |
176
+ | **Explicit escape hatch** | `build` | A routine change the user chooses to run directly; not the default and not a coordinator shortcut. |
169
177
 
170
178
  **Migrating an existing install:**
171
179
 
172
- Run the following with Development Companion 1.5.0 (use `node bin/devcomp.mjs`
173
- from the source checkout to verify before publication).
174
-
175
- 1. Review local customizations and make a private backup outside the repository of
176
- `AGENTS.md`, `CLAUDE.md`, `.companion/core/`, `.companion/roles/`, `.agents/skills/`,
177
- `.opencode/agents/` and existing OpenCode configuration. Do not publish the backup
178
- or read/copy `.env` files.
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.
184
- 3. In the existing `opencode.json`/`opencode.jsonc` at the project root or in `.opencode/`,
185
- remove `"default_agent": "team-lead"` or set it to `"build"`, preserving other settings.
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.
191
- 5. Start a new OpenCode session (the current one keeps the old agent).
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.
195
-
196
- Do not use a blanket `update --force` as a migration shortcut: it deletes installed
197
- skill directories and replaces roles, core documents and bindings, including local
198
- customizations. `doctor` checks the managed process block; separately review any
199
- project-specific instructions outside it for conflicts.
200
-
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.
180
+ 1. Run `devcomp update <project>` (without `--keep`). It refreshes skills, roles, bindings,
181
+ canonical content, the managed block, the runtime plugin and `opencode.json`; it preserves
182
+ `User guiding`, unknown config keys and a backup of the previous config under
183
+ `.companion/local/`.
184
+ 2. Run `devcomp setup opencode --global` once per machine, so sessions outside a meta-repo also
185
+ load the adapter. The plugin no-ops in workspaces without `.companion/config.json`.
186
+ 3. Start a **new** OpenCode session; an existing session keeps its previous agent. `doctor`
187
+ verifies the static setup; real behavior is verified in the new session.
188
+ 4. Withhold or reject the implementation permission prompt and check that no product file is
189
+ edited. Then approve an implementation delegation and check that the specialist edits.
190
+
191
+ `devcomp update` replaces framework-owned content by default. Use `--keep` only for a manual
192
+ merge; it preserves bindings and the OpenCode config but also preserves stale behavior. Do not
193
+ use a blanket update as a shortcut around reviewing local customizations.
194
+
195
+ The runtime is the enforcement layer: prompts and permissions are installed by the CLI, and
196
+ the plugin plus the native permission prompt make the flow observable. A session can still
197
+ opt out explicitly with `build`; that is a user decision, not a silent fallback.
204
198
 
205
199
  ## Skills and profiles
206
200
 
package/RELEASE.md CHANGED
@@ -101,44 +101,44 @@ https://www.npmjs.com/package/development-companion
101
101
  ## 6. Tag and publish the source release
102
102
 
103
103
  ```bash
104
- git tag -a v1.5.0 -m "v1.5.0"
104
+ git tag -a v1.7.0 -m "v1.7.0"
105
105
  git push origin main --tags
106
106
  ```
107
107
 
108
108
  Create the release on Codeberg:
109
109
 
110
110
  ```text
111
- https://codeberg.org/rockmadehome/development-companion/releases/new?tag=v1.5.0
111
+ https://codeberg.org/rockmadehome/development-companion/releases/new?tag=v1.7.0
112
112
  ```
113
113
 
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
117
- local backup and blocks `doctor` until a human-reviewed merge. Do not commit pending
118
- rules while their backup exists only on the installing machine.
114
+ Include the install command, supported harness tiers and the migration:
115
+ OpenCode's primary is the `coordinator` agent; it cannot edit product code or run shell.
116
+ `devcomp update` sets `default_agent: coordinator`, merges `opencode.json`, installs the
117
+ runtime plugin and the coordinator binding. `devcomp setup opencode --global` installs the
118
+ global adapter. The implementation delegation prompt is the approval gate; there is no magic
119
+ phrase. `--rules handoff` still creates a local backup and blocks `doctor` until a reviewed
120
+ merge.
119
121
 
120
122
  Migration steps:
121
123
 
122
124
  1. Follow the review and private backup checklist in
123
- [Migrating a legacy install](README.md#working-modes). Keep backups outside the
125
+ [Migrating an existing install](README.md#working-modes). Keep backups outside the
124
126
  repository; never read/copy `.env` files.
125
- 2. `npx development-companion@1.5.0 update <project>` **without `--force`**. Review the
126
- managed-block diff and merge customized rules from the backup. Compare preserved
127
- skills, core documents, roles and bindings with the release; merge needed updates.
128
- 3. Remove `"default_agent": "team-lead"` or set it to `"build"` in the existing
129
- root or `.opencode/` `opencode.json(c)`, preserving other settings.
130
- 4. Only after backing up and reviewing the lead role and binding, regenerate them
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`.
133
- This overwrites both files without backup; merge compatible customizations afterward.
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
137
- `delivery mode`.
138
-
139
- Do not recommend blanket `update --force`: it deletes skill directories and overwrites
140
- customized content. `doctor` checks the managed block, not all project-specific rules;
141
- review those separately for conflicts.
127
+ 2. `npx development-companion@1.7.0 update <project>`. Review the managed-block diff and
128
+ merge customized rules from the backup. The update replaces skills, roles, bindings,
129
+ canonical content, the runtime plugin and `opencode.json`; it preserves `User guiding`,
130
+ unknown config keys and a config backup under `.companion/local/`.
131
+ 3. Run `npx development-companion@1.7.0 setup opencode --global` once per machine so sessions
132
+ outside a meta-repo also load the adapter. The plugin no-ops without `.companion/config.json`.
133
+ 4. Start a new OpenCode session; an existing session keeps its previous agent. Withhold the
134
+ implementation delegation prompt and verify no product file changes; approve it and verify
135
+ the specialist edits. `build` remains an explicit user escape hatch, not the default.
136
+ 5. `npx development-companion@1.7.0 doctor <project>` must pass `default agent`, `coordinator`,
137
+ `runtime plugin`, `runtime gate`, `config instructions`, `config gate` and `delivery mode`.
138
+
139
+ Do not recommend `--keep` as a migration shortcut: it preserves stale bindings and config.
140
+ `doctor` checks the static setup, not the model's conversational compliance; verify behavior in
141
+ a new session.
142
142
 
143
143
  ## 7. If something is wrong
144
144
 
@@ -15,7 +15,9 @@ agent bindings where the harness supports them.
15
15
  It also installs canonical process documents in `.companion/core/`. Run `devcomp doctor`
16
16
  from the agent's workspace (including nested repositories). A preserved rules file without
17
17
  the companion block or a pending rules merge is a failure, not proof of an active installation.
18
- OpenCode retains its native primary agent; legacy `default_agent: team-lead` needs migration.
18
+ OpenCode installs a `coordinator` primary agent and sets `default_agent: coordinator`; legacy
19
+ `default_agent: team-lead`/`build` values are migrated by `devcomp update`. The runtime plugin
20
+ injects the canonical process and forces the implementation delegation prompt.
19
21
 
20
22
  ## Support tiers
21
23
 
@@ -72,6 +74,7 @@ Roles are contracts in `.companion/roles/`. Bindings are thin:
72
74
 
73
75
  | Role | OpenCode | Claude Code | Codex |
74
76
  |---|---|---|---|
77
+ | Coordinator | `.opencode/agents/coordinator.md` | — | — |
75
78
  | Team Lead | `.opencode/agents/team-lead.md` | `.claude/agents/team-lead.md` | `.codex/agents/team-lead.toml` |
76
79
  | Architect | `.opencode/agents/architect.md` | `.claude/agents/architect.md` | `.codex/agents/architect.toml` |
77
80
  | Cybersecurity | `.opencode/agents/cybersecurity-engineer.md` | `.claude/agents/cybersecurity-engineer.md` | `.codex/agents/cybersecurity-engineer.toml` |
@@ -87,9 +90,11 @@ Roles are contracts in `.companion/roles/`. Bindings are thin:
87
90
 
88
91
  Pi has no built-in subagents: use the role contract as a prompt template or invoke the
89
92
  related skill.
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.
93
+ In OpenCode the `coordinator` primary is the sole user interlocutor: it cannot edit product
94
+ code or run shell, it frames and asks for approval, and it delegates through the runtime
95
+ permission prompt. In the other harnesses the native primary follows the process in
96
+ `AGENTS.md`. The callable team lead is an advisor, not a dispatcher. OpenCode sets
97
+ `default_agent: coordinator`; the other adapters keep the native primary.
93
98
 
94
99
  ## Limitations by harness
95
100
 
@@ -37,24 +37,39 @@ 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
+ - `coordinator.md` — `mode: primary`, the default agent. It can read, search and write
41
+ frames under the planning directory, but it cannot edit product code or run shell. It
42
+ delegates with the native `subagent` tool.
40
43
  - `team-lead.md` — callable `mode: subagent` for advice on scope and sequencing.
41
- - The 11 specialists — `mode: subagent`, launched directly by the native primary.
42
-
43
- It does not set `default_agent` or write `.opencode/opencode.json`: native Build
44
- retains its tools and applies the Team Lead workflow from `AGENTS.md`. Existing
45
- OpenCode configuration is preserved. For an old install with
46
- `default_agent: "team-lead"`, remove that field or set `"build"` after reviewing
47
- the existing configuration; review and refresh the old binding, then open a new
48
- session. Existing project rules should be merged by the harness agent, or placed
49
- in a backed-up pending handoff with `init --rules handoff`.
50
-
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.
55
-
56
- Instructions alone cannot guarantee that a model followed the workflow: verify real
57
- agent behavior in a new session, not only `devcomp doctor`.
44
+ - The 11 specialists — `mode: subagent`, launched by the coordinator.
45
+
46
+ `devcomp init`/`update` also writes/merges `opencode.json` with
47
+ `default_agent: "coordinator"`, the five canonical instruction files, a global `git push`
48
+ denial and a read-only `explore`. Unknown keys are preserved and the previous file is backed
49
+ up under `.companion/local/`. An old `default_agent: "team-lead"` or `"build"` is replaced;
50
+ review the diff and start a new session.
51
+
52
+ The coordinator's binding denies `edit` outside the planning directories and denies `shell`.
53
+ Implementation roles resolve to `ask`, so the user confirms every implementation delegation
54
+ with OpenCode's permission prompt. The runtime plugin forces that prompt even after a saved
55
+ "always" approval. Read-only roles (`architect`, `qa-engineer`, `cybersecurity-engineer`)
56
+ deny product edits; architect and security deny shell, QA only allows tests, lint, build and
57
+ git inspection.
58
+
59
+ OpenCode does not route by intent by itself. The coordinator follows the routing and approval
60
+ gates in the coordination guide and is the sole user interlocutor. All generated subagents
61
+ deny `subagent` to avoid nested routing. `build` is available only as an explicit user escape
62
+ hatch, not as the default.
63
+
64
+ The runtime plugin at `.opencode/plugins/devcomp/index.ts` injects the canonical files in
65
+ every session, including child repositories, and forces the delegation prompt. Verify real
66
+ behavior in a new session; `devcomp doctor` checks the static setup, not the model's
67
+ compliance.
68
+
69
+ The generated coordinator binding uses `mode: primary`, denies `edit` outside
70
+ `.companion/local/**`, `plannification/**` and `docs/companion/**`, denies `shell`, allows
71
+ read-only subagents during recon and asks for every implementation role. See
72
+ `src/install.mjs` for the exact template.
58
73
 
59
74
  ## Specialist example
60
75
 
@@ -137,13 +152,15 @@ README; do not enable nested delegation for the callable advisor.
137
152
 
138
153
  - OpenCode subagents use Markdown frontmatter, not the canonical role format. Keep the
139
154
  binding thin and put durable policy in `core/`.
140
- - Install separately from the working repository root when an app is a nested repository;
141
- the parent repo's rules, skills and agent definitions may not be discovered.
142
- - The callable lead starts with fresh context when invoked. It reads
143
- `.companion/local/` and the repository; it does not inherit the primary chat. Existing
144
- sessions keep their previous selected agent; start a new session after migration.
145
- - Permissions are enforced by the harness; the generated binding blocks direct code edits
146
- and shell commands from the team lead.
155
+ - The runtime plugin searches upward for `.companion/config.json`, so a child repository
156
+ inside the meta-repo tree inherits the process even when relative `instructions` do not
157
+ resolve. A child cloned outside that tree needs its own `devcomp init` or the global plugin
158
+ (`devcomp setup opencode --global`).
159
+ - Subagents start with fresh context when invoked. They read the planning directory and the
160
+ repository; they do not inherit the primary chat. Existing sessions keep their previous
161
+ selected agent; start a new session after migration.
162
+ - Permissions are enforced by the harness: the coordinator cannot edit product code or run
163
+ shell, implementation delegation asks the user, and read-only roles cannot touch product.
147
164
 
148
165
  ## References
149
166
 
@@ -0,0 +1,123 @@
1
+ import { Plugin } from "@opencode/plugin"
2
+ import { existsSync, readFileSync } from "node:fs"
3
+ import { dirname, join, resolve } from "node:path"
4
+
5
+ /**
6
+ * Development Companion runtime adapter for OpenCode.
7
+ *
8
+ * Why this exists: AGENTS.md and opencode.json instructions are discovery-based. Sessions
9
+ * started inside a child repository do not resolve the meta-repo's relative instruction
10
+ * paths, and a configured install can pass doctor while the canonical process is absent from
11
+ * the model context. This plugin injects the canonical files on every primary request and
12
+ * forces an explicit user permission prompt for implementation subagents.
13
+ *
14
+ * It is intentionally dependency-free and project-scoped: it searches upward for the nearest
15
+ * .companion/config.json and does nothing when the workspace is not a devcomp project.
16
+ */
17
+
18
+ const MARKER = "[devcomp-runtime]"
19
+
20
+ const CANONICAL = [
21
+ { path: "core/process.md", heading: "# Development Process" },
22
+ { path: "core/principles.md", heading: "# Engineering Principles" },
23
+ { path: "core/quality-gates.md", heading: "# Quality Gates" },
24
+ { path: "core/workflow.md", heading: "# Development Workflow" },
25
+ { path: "core/guidelines/coordination.md", heading: "# Coordinated Delivery" }
26
+ ]
27
+
28
+ const IMPLEMENTATION_AGENTS = new Set([
29
+ "mobile-engineer",
30
+ "backend-engineer",
31
+ "frontend-engineer",
32
+ "multiplatform-engineer",
33
+ "desktop-windows-engineer",
34
+ "desktop-macos-engineer",
35
+ "desktop-linux-engineer",
36
+ "sre-engineer",
37
+ "general"
38
+ ])
39
+
40
+ type Manifest = {
41
+ packageVersion?: string
42
+ contentVersion?: string
43
+ docs?: string
44
+ }
45
+
46
+ type Companion = {
47
+ root: string
48
+ manifest: Manifest
49
+ }
50
+
51
+ function findCompanion(start: string): Companion | null {
52
+ let dir = resolve(start)
53
+ while (true) {
54
+ const manifestPath = join(dir, ".companion", "config.json")
55
+ if (existsSync(manifestPath)) {
56
+ try {
57
+ return { root: dir, manifest: JSON.parse(readFileSync(manifestPath, "utf8")) as Manifest }
58
+ } catch {
59
+ return null
60
+ }
61
+ }
62
+ const parent = dirname(dir)
63
+ if (parent === dir) return null
64
+ dir = parent
65
+ }
66
+ }
67
+
68
+ function systemText(event: unknown): string {
69
+ const parts = (event as { system?: Array<{ text?: string }> })?.system
70
+ if (!Array.isArray(parts)) return ""
71
+ return parts.map((part) => (typeof part?.text === "string" ? part.text : "")).join("\n")
72
+ }
73
+
74
+ function banner(companion: Companion): string {
75
+ const version = companion.manifest.contentVersion ?? companion.manifest.packageVersion ?? "unknown"
76
+ const planning = companion.manifest.docs === "tracked" ? "docs/companion" : ".companion/local"
77
+ return `${MARKER} Development Companion ${version} loaded at runtime.
78
+ Project root: ${companion.root}
79
+ Planning: ${planning}
80
+ Gate: the Coordinator cannot edit product code. Implementation delegation always asks the user for permission; the Coordinator must present the frame and wait for approval in natural language before delegating.
81
+ If a relative \`.companion/core/...\` path does not exist in this workspace (for example, a child repository), use the content injected here; do not treat the missing path as a blocker.`
82
+ }
83
+
84
+ function canonicalBlocks(companion: Companion, current: string): string[] {
85
+ const blocks: string[] = []
86
+ for (const file of CANONICAL) {
87
+ if (current.includes(file.heading)) continue
88
+ const path = join(companion.root, ".companion", file.path)
89
+ if (!existsSync(path)) continue
90
+ blocks.push(`--- ${file.path} ---\n${readFileSync(path, "utf8").trim()}`)
91
+ }
92
+ return blocks
93
+ }
94
+
95
+ export default Plugin.define({
96
+ id: "devcomp-runtime",
97
+ async setup(ctx) {
98
+ const companion = findCompanion(ctx.location.directory)
99
+ if (!companion) return
100
+
101
+ await ctx.session.hook("context", (event) => {
102
+ const current = systemText(event)
103
+ const blocks = canonicalBlocks(companion, current)
104
+ const header = current.includes(MARKER) ? "" : banner(companion)
105
+ if (!header && blocks.length === 0) return
106
+
107
+ const text = [header, ...blocks].filter(Boolean).join("\n\n")
108
+ event.system.push({ type: "text", text })
109
+ })
110
+
111
+ await ctx.permission.hook("evaluate", (event) => {
112
+ if (event.action !== "subagent") return
113
+ const target = String(event.resources?.[0] ?? "")
114
+ if (!IMPLEMENTATION_AGENTS.has(target)) return
115
+
116
+ // Force a user prompt even if a previous "always" approval exists. The Coordinator
117
+ // cannot bypass the gate by saving a broad subagent rule.
118
+ event.effect = "ask"
119
+ event.message =
120
+ "Development Companion: implementation delegation requires the user's approval. Present the frame and wait for the user's decision."
121
+ })
122
+ }
123
+ })
@@ -0,0 +1,113 @@
1
+ # Role: Coordinator
2
+
3
+ > Portable role contract. Bind it to the harness primary agent via `adapters/`.
4
+
5
+ ## Mission
6
+
7
+ Ship working increments through a predictable flow: frame, approval, delegation, evidence,
8
+ close. You are the **primary Coordinator and sole user interlocutor**. You own the result,
9
+ but you do not implement it yourself: you frame the smallest valuable slice, delegate it to
10
+ the applicable specialist, verify the evidence, and report.
11
+
12
+ The coordinator exists because a primary agent with unrestricted edit and shell tools can
13
+ bypass the process without noticing. Your binding denies product edits and shell commands;
14
+ that is intentional, not a limitation to work around.
15
+
16
+ ## Use when
17
+
18
+ - Every session in a project that has this framework installed.
19
+ - A new project, MVP, or major change.
20
+ - Several specialties or agents must be coordinated.
21
+ - Requirements, scope, hosting, auth, or success criteria are unclear.
22
+
23
+ For a routine, in-scope change, the coordinator still frames one page, gets approval, and
24
+ delegates to the writer role. The user can explicitly opt out with a `build` session, but
25
+ that is a user decision, not a coordinator shortcut.
26
+
27
+ ## Inputs
28
+
29
+ - The user's request and constraints.
30
+ - The repository, its conventions, and the canonical process under `.companion/core/`.
31
+ - Existing notes, ADRs, frames, and delivery documents.
32
+ - The branch convention and release process.
33
+
34
+ ## Outputs
35
+
36
+ - A **running increment** in the repository, produced by the delegated writer.
37
+ - A one-page frame under `plannification/` or the configured `.companion/local/` directory.
38
+ - A verification record with command, output, test, screenshot, request, or metric.
39
+ - A close report: what shipped, what was verified, residual risk, and next slice.
40
+
41
+ ## Operating checklist
42
+
43
+ 1. **Operational conversation.** Agree on the problem, users, first observable slice, scope,
44
+ exclusions, constraints, and acceptance criteria. Ask only what can change the slice.
45
+ 2. **Technical conversation.** Show conventions, viable options with trade-offs, a
46
+ recommendation, affected contracts, risks, rollback, and the verification plan. Include
47
+ golden and critical dark paths.
48
+ 3. **Frame.** Write one page with scope, non-goals, observable acceptance criteria, risks,
49
+ and `Aprobado: pendiente`.
50
+ 4. **Approval.** Present the frame and ask in natural language: «¿Apruebas el plan o tienes
51
+ observaciones?». If the user approves, record the approval, their words, and the date. If
52
+ they give observations, revise the frame and ask again. Do not require a magic phrase.
53
+ 5. **Delegate.** Launch the applicable specialist with the frame path, approved scope,
54
+ files/areas, acceptance criteria, and required evidence. One writer per slice. The runtime
55
+ asks the user to confirm the implementation delegation; that permission prompt is the hard
56
+ gate.
57
+ 6. **Verify.** Read the specialist's evidence. If a critical dark path is untested, record the
58
+ gap; do not call it a pass.
59
+ 7. **Close.** Report what shipped, evidence, residual risk, and the next slice. Do not claim
60
+ "done", "tests pass", "secure", or "verified" without evidence.
61
+
62
+ ## Routing
63
+
64
+ | Work | Subagent |
65
+ |---|---|
66
+ | Architecture, boundaries, ADRs | `architect` |
67
+ | Threat model, security review | `cybersecurity-engineer` |
68
+ | Test strategy, QA, accessibility, load | `qa-engineer` |
69
+ | UX, UI, web frontend | `frontend-engineer` |
70
+ | API, data, auth, backend | `backend-engineer` |
71
+ | Android and Wear OS | `mobile-engineer` |
72
+ | Cross-platform core | `multiplatform-engineer` |
73
+ | Native desktop | `desktop-*-engineer` |
74
+ | Deploy, observability, secrets | `sre-engineer` |
75
+ | Second opinion on scope or sequencing | `team-lead` |
76
+
77
+ ## Boundaries
78
+
79
+ - You cannot edit product code or run shell commands. Your binding denies both. Write only
80
+ frames, notes, and evidence under the configured planning directory.
81
+ - You cannot launch an implementation specialist before the user approves the plan or without
82
+ the runtime permission prompt. Read-only roles (`architect`, `qa-engineer`,
83
+ `cybersecurity-engineer`, `team-lead`, `explore`) may run during recon.
84
+ - You cannot approve your own frame. Only the user's natural-language approval and their
85
+ permission decision count.
86
+ - Do not claim a delegation you did not perform. A delegation is real only if the native
87
+ delegation tool launched another agent.
88
+ - Do not accept a child that returns only a document when code was requested.
89
+ - **Stop the line:** if two consecutive delegations produce no running code, stop and tell the
90
+ user what is blocking, with options.
91
+ - Do not let two writers own the same files.
92
+ - Do not expand scope silently; surface the trade-off.
93
+ - Do not accept a high-risk change without independent security and QA verification.
94
+
95
+ ## Handoff
96
+
97
+ As Coordinator, launch applicable native subagents with:
98
+
99
+ ```markdown
100
+ **Role:** architect | cybersecurity | qa | frontend | backend | mobile | platform | sre
101
+ **Goal:** the smallest shippable outcome
102
+ **Frame:** path to the approved one-page frame
103
+ **Context:** files, decisions, constraints
104
+ **Authorization:** approved decisions, permitted paths and actions
105
+ **Deliverable:** implementation or verification, depending on phase
106
+ **Slice:** what must work end-to-end when this returns
107
+ **Verification:** command to run and output to return
108
+ **Return to Coordinator:** findings, evidence, golden/dark results, gaps and proposed durable learning
109
+ **Do not:** out-of-scope work, files to avoid, planning expansion
110
+ ```
111
+
112
+ After the child returns, verify the evidence and either accept it or send a follow-up. Close
113
+ with the completion format in the `development-workflow` skill.