development-companion 1.3.0 → 1.4.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
@@ -1,6 +1,6 @@
1
1
  # Development Companion
2
2
 
3
- One installable development process for AI coding agents: **12 roles**, **17 skills**, and
3
+ One installable development process for AI coding agents: **12 roles**, **18 skills**, and
4
4
  a CLI that adapts the same canonical base to OpenCode, Claude Code, Codex, Pi, and other
5
5
  harnesses.
6
6
 
@@ -14,7 +14,8 @@ existing `AGENTS.md` and `CLAUDE.md` intact unless you choose otherwise.
14
14
  Run `devcomp doctor` **from the repository opened by the agent**. If you work in a nested
15
15
  repository, install there too: its own `AGENTS.md` and agent configuration may take precedence.
16
16
  `init --yes` preserves existing rules; `doctor` fails when those rules do not activate the
17
- process. Use `init --rules append` to add the managed block without removing existing rules.
17
+ process. Ask the harness agent to merge existing rules, or use `init --rules handoff` for a
18
+ backed-up, explicitly pending merge. `--rules append` remains available for compatible rules.
18
19
 
19
20
  ## Why
20
21
 
@@ -61,7 +62,7 @@ npx development-companion init . \
61
62
  | `--harness <name>` | Force the adapter; `auto` detects it. |
62
63
  | `--profile <name>` | `web`, `backend`, `mobile`, `desktop`, `cross-platform`, `full`. |
63
64
  | `--skills <a,b>` | Add specific skills. |
64
- | `--rules keep\|append\|replace` | Policy for existing `AGENTS.md`/`CLAUDE.md`. |
65
+ | `--rules keep\|append\|handoff\|replace` | Policy for existing rules; `handoff` backs up `AGENTS.md` for agent-led merge. |
65
66
  | `--branching <name>` | `gitflow`, `gitlab-flow`, `trunk-based`, `github-flow`, `custom`. |
66
67
  | `--docs local\|tracked` | Keep design docs local or version them in `docs/companion/`. |
67
68
  | `--memory engram\|none` | Recommend Engram for cross-session memory. |
@@ -75,7 +76,11 @@ If `AGENTS.md` or `CLAUDE.md` already exists, the CLI asks:
75
76
 
76
77
  - **keep** — leave the file untouched;
77
78
  - **append** — add a managed block, preserving your rules;
78
- - **replace** — replace the file, with explicit confirmation.
79
+ - **handoff** — back up `AGENTS.md` under `.companion/local/rules-backup/`, write a
80
+ pending-merge notice and the process block; `doctor` fails until an agent merges
81
+ project-specific rules and removes the notice. Existing `CLAUDE.md` is kept.
82
+ - **replace** — replace the file, with explicit confirmation and a local backup;
83
+ `AGENTS.md` still requires a reviewed merge of the original before work begins.
79
84
 
80
85
  The managed block is delimited by `<!-- development-companion:start -->` and
81
86
  `<!-- development-companion:end -->`, so updates are idempotent.
@@ -134,23 +139,14 @@ The canonical principles, process, workflow, quality gates, and guidelines are i
134
139
 
135
140
  ### Orchestration in OpenCode
136
141
 
137
- `devcomp init` installs `team-lead` with `mode: primary` and writes
138
- `.opencode/opencode.json` with `default_agent: "team-lead"`. The 11 specialists are
139
- subagents. New sessions start as the team lead, which delegates with the `subagent` tool;
140
- Build and Plan remain available in the agent selector. If the project already has an
141
- OpenCode config, the installer preserves it and `devcomp doctor` fails if
142
- `default_agent` does not select the team lead.
143
-
144
- For an existing OpenCode configuration, add `"default_agent": "team-lead"` yourself and
145
- start a **new** session. The CLI will not overwrite that configuration; `doctor` reports a
146
- failure until an effective default is configured. Existing `AGENTS.md` files also require
147
- `--rules append` (or an explicit replacement) before the process is active.
148
-
149
- The team lead is a router, not an implementer. Its generated binding denies `edit` outside
150
- `.companion/local/**` and `docs/companion/**`, and denies `shell`; it must launch a
151
- specialist for code, commands, tests, security, UX, or deployment. Specialists deny the
152
- `subagent` permission, so only the team lead orchestrates. Existing sessions keep their
153
- previous agent; start a new session to pick up `team-lead`.
142
+ `devcomp init` preserves OpenCode's native Build default and any existing OpenCode config.
143
+ The native primary follows the Team Lead delivery contract from `AGENTS.md` and retains
144
+ its harness skills, shell, edit and delegation tools. `team-lead` and the 11 specialists
145
+ are callable subagents; invoke the dedicated lead for substantial coordination, not every
146
+ routine slice. Its own binding denies edits outside local design notes and denies shell.
147
+ `devcomp doctor` fails on the old `default_agent: "team-lead"` and primary-only binding:
148
+ review local customizations, update the binding explicitly, remove that default (or select
149
+ `build`), and start a new session. The CLI will not overwrite existing config or bindings.
154
150
 
155
151
  ## Skills and profiles
156
152
 
@@ -174,6 +170,11 @@ Domain skills are installed by profile:
174
170
  Every skill is self-contained and follows the [Agent Skills](https://agentskills.io)
175
171
  specification.
176
172
 
173
+ For UI design the agent offers local HTML/SVG, an existing Figma MCP, or FigCraft
174
+ CLI if available. The CLI does not install third-party tools or handle Figma tokens.
175
+ The `ux-design` skill explains how to find the official FigCraft CLI download, create
176
+ editable files and exercise a clickable prototype in Play before approving the design.
177
+
177
178
  ## Harness support
178
179
 
179
180
  | Tier | Harnesses | Commitment |
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.3.0.tgz
46
+ npm install "$packdir"/development-companion-1.4.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.3.0`, not `0.0.0-stage`. If it still points to the
74
+ The `latest` tag must point to `1.4.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.3.0 --version
83
- npx development-companion@1.3.0 init . --yes --harness opencode --profile web
84
- npx development-companion@1.3.0 doctor .
82
+ npx development-companion@1.4.0 --version
83
+ npx development-companion@1.4.0 init . --yes --harness opencode --profile web
84
+ npx development-companion@1.4.0 doctor .
85
85
  ```
86
86
 
87
87
  Also verify the package page:
@@ -93,18 +93,21 @@ 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.3.0 -m "v1.3.0"
96
+ git tag -a v1.4.0 -m "v1.4.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.3.0
103
+ https://codeberg.org/rockmadehome/development-companion/releases/new?tag=v1.4.0
104
104
  ```
105
105
 
106
- Include the install command, the supported harness tiers, and the breaking changes from
107
- v0.1.
106
+ Include the install command, supported harness tiers and migration from 1.3.0:
107
+ OpenCode no longer selects `team-lead` as primary; existing projects must review and
108
+ update their old binding and `default_agent` explicitly. `--rules handoff` creates a
109
+ local backup and blocks `doctor` until a human-reviewed merge. Do not commit pending
110
+ rules while their backup exists only on the installing machine.
108
111
 
109
112
  ## 7. If something is wrong
110
113
 
@@ -14,8 +14,8 @@ directory, writes `AGENTS.md`/`CLAUDE.md` with keep/append/replace, and generate
14
14
  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
- the companion block or an OpenCode configuration without the team lead default is a failure,
18
- not proof of an active installation.
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.
19
19
 
20
20
  ## Support tiers
21
21
 
@@ -61,7 +61,9 @@ Each adapter declares its paths and limitations:
61
61
  - If they exist, the CLI asks **keep**, **append**, or **replace**.
62
62
  - `append` uses a managed block with
63
63
  `<!-- development-companion:start -->` / `<!-- development-companion:end -->`.
64
- - `replace` requires explicit confirmation or `--force`.
64
+ - `handoff` backs up original `AGENTS.md` locally and writes a pending-merge notice;
65
+ the harness agent must merge business and framework rules before `doctor` passes.
66
+ - `replace` requires explicit confirmation or `--force` and also preserves a local backup.
65
67
  - `--yes` defaults to `keep` for existing files.
66
68
 
67
69
  ## Binding roles
@@ -85,8 +87,8 @@ Roles are contracts in `.companion/roles/`. Bindings are thin:
85
87
 
86
88
  Pi has no built-in subagents: use the role contract as a prompt template or invoke the
87
89
  related skill.
88
- Claude Code and Codex do not select the team lead automatically; invoke it explicitly when
89
- orchestration is needed. Only the OpenCode adapter configures a primary default agent.
90
+ The harness-native primary coordinates through `AGENTS.md`; invoke a dedicated team lead
91
+ only when coordination adds value. OpenCode does not change its default agent.
90
92
 
91
93
  ## Limitations by harness
92
94
 
@@ -37,34 +37,25 @@ 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` — `mode: primary`, so it appears in the OpenCode agent selector.
41
- - The 11 specialists — `mode: subagent`, launched by the team lead through the
42
- `subagent` tool.
43
-
44
- It also creates `.opencode/opencode.json` with:
45
-
46
- ```json
47
- {
48
- "$schema": "https://opencode.ai/config.json",
49
- "default_agent": "team-lead"
50
- }
51
- ```
52
-
53
- New sessions start as `team-lead`; Build and Plan remain available in the selector. If the
54
- project already has `opencode.json(c)` at the root or in `.opencode/`, the installer
55
- preserves it. `devcomp doctor` fails unless the effective project config selects
56
- `default_agent: "team-lead"`; add it manually to the existing config, then start a new
57
- session. Likewise, an existing `AGENTS.md` needs `init --rules append` to activate the
58
- canonical process without discarding project rules.
59
-
60
- OpenCode does not route by intent by itself. The generated team-lead prompt **mandates**
61
- delegation with the `subagent` tool, and its permissions **deny `edit` and `shell`** outside
62
- `.companion/local/**` and `docs/companion/**`. The team lead therefore cannot implement code
63
- or run commands itself; it must launch the specialists. Specialists deny `subagent`, so only
64
- the team lead orchestrates.
65
-
66
- For deterministic routing beyond prompt and permissions, an OpenCode plugin would be needed,
67
- but the generated binding is designed so the model has no direct path to do the work.
40
+ - `team-lead.md` — callable `mode: subagent` for substantial coordination.
41
+ - The 11 specialists — `mode: subagent`, launched by the native primary agent
42
+ or by the dedicated lead when it coordinates a multi-specialist task.
43
+
44
+ It does not set `default_agent` or write `.opencode/opencode.json`: native Build
45
+ retains its tools and applies the Team Lead workflow from `AGENTS.md`. Existing
46
+ OpenCode configuration is preserved. For an old install with
47
+ `default_agent: "team-lead"`, remove that field or set `"build"` after reviewing
48
+ the existing configuration; review and refresh the old binding, then open a new
49
+ session. Existing project rules should be merged by the harness agent, or placed
50
+ in a backed-up pending handoff with `init --rules handoff`.
51
+
52
+ OpenCode does not route by intent by itself. The callable lead's own permissions
53
+ deny `edit` on code and deny `shell`; the native Build agent is **not** restricted.
54
+ The primary may delegate specialists or implement a focused slice directly while
55
+ following the same process. Specialists deny `subagent` to avoid unintended chains.
56
+
57
+ Instructions alone cannot guarantee that a model followed the workflow: verify real
58
+ agent behavior in a new session, not only `devcomp doctor`.
68
59
 
69
60
  ## Specialist example
70
61
 
@@ -103,12 +94,12 @@ OpenCode V2 uses **`permissions`** (plural), an ordered list of
103
94
 
104
95
  ## Team lead example
105
96
 
106
- The generated binding is a router, not an implementer:
97
+ The generated binding is a callable router, not the native primary:
107
98
 
108
99
  ```yaml
109
100
  ---
110
101
  description: Leads discovery, planning, delegation, and closure.
111
- mode: primary
102
+ mode: subagent
112
103
  permissions:
113
104
  - action: edit
114
105
  resource: "*"
@@ -134,8 +125,9 @@ permissions:
134
125
  ---
135
126
  ```
136
127
 
137
- The last matching rule wins. The team lead can read, write its own plan/closure documents,
138
- and launch any specialist, but it cannot edit code or run shell commands. Specialists get
128
+ The last matching rule wins. The callable lead can read, write its own plan/closure
129
+ documents, and launch a specialist, but it cannot edit code or run shell commands.
130
+ The native primary keeps its tools. Specialists get
139
131
  `{ "action": "subagent", "resource": "*", "effect": "deny" }` so they cannot spawn more
140
132
  agents.
141
133
 
@@ -148,9 +140,9 @@ To restrict which specialists the team lead may launch, replace `"*"` with expli
148
140
  binding thin and put durable policy in `core/`.
149
141
  - Install separately from the working repository root when an app is a nested repository;
150
142
  the parent repo's rules, skills and agent definitions may not be discovered.
151
- - The team lead starts with fresh context in a new session. It reads
152
- `.companion/local/` and the repository; it does not inherit the previous chat. Existing
153
- sessions keep their previous agent; start a new session to pick up `team-lead`.
143
+ - The callable lead starts with fresh context when invoked. It reads
144
+ `.companion/local/` and the repository; it does not inherit the primary chat. Existing
145
+ sessions keep their previous selected agent; start a new session after migration.
154
146
  - Permissions are enforced by the harness; the generated binding blocks direct code edits
155
147
  and shell commands from the team lead.
156
148
 
package/core/process.md CHANGED
@@ -25,11 +25,14 @@ waterfall. Planning is a tool that unblocks the next slice; when it stops doing
25
25
 
26
26
  ## Phase 0 — Bootstrap
27
27
 
28
- **Owner:** CLI.
28
+ **Owner:** native harness agent, assisted by the CLI.
29
29
 
30
30
  - Detect repository, harness, package manager, profile, and branch convention.
31
31
  - Install `AGENTS.md`, `CLAUDE.md`, skills, roles, and bindings.
32
32
  - Write `.companion/config.json` and ignore `.companion/local/`.
33
+ - When rules already exist, the harness agent reviews them and merges process obligations
34
+ with project-specific facts and tools. A CLI handoff is only a backed-up pending merge;
35
+ `doctor` must fail until the agent finishes it. Do not silently append conflicting rules.
33
36
 
34
37
  **Gate:** `devcomp doctor` passes; existing rules were not lost.
35
38
 
@@ -4,9 +4,10 @@
4
4
 
5
5
  ## Mission
6
6
 
7
- Ship working increments. The user talks to you; you frame the smallest valuable slice, route
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.
9
+ for **code that lands**, not for the volume of documents produced. The native primary agent may
10
+ follow this contract with its own tools; a callable team-lead specialist reports to that primary.
10
11
 
11
12
  ## Use when
12
13
 
@@ -73,7 +74,9 @@ is inventory.
73
74
 
74
75
  ## Boundaries
75
76
 
76
- - Do not design the architecture, implement features, run tests, or run shell commands.
77
+ - As a dedicated coordination subagent, do not design the architecture, implement features,
78
+ run tests, or run shell commands. The native primary retains its normal capabilities and
79
+ may implement a focused slice directly while following these delivery gates.
77
80
  - Do not edit code. Your only writable paths are `.companion/local/**` and
78
81
  `docs/companion/**`.
79
82
  - Do not claim a delegation you did not perform. A delegation is real only if a native
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "development-companion",
3
- "version": "1.3.0",
3
+ "version": "1.4.0",
4
4
  "description": "Harness-neutral development process, roles, and skills for AI coding agents.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -76,19 +76,44 @@ Target WCAG 2.2 AA unless the project states otherwise.
76
76
  - Duration and easing; no decorative motion that blocks work.
77
77
  - Reduced-motion alternative.
78
78
 
79
- ### 6. Produce mockups
79
+ ### 6. Choose a design tool and produce mockups
80
+
81
+ Ask whether the user wants an existing Figma MCP integration, an installed FigCraft
82
+ CLI/app, or local HTML/SVG. Check availability before proposing an install: query the
83
+ harness for configured MCP tools, try `command -v figcraft-cli`, and on macOS check
84
+ `/Applications/FigCraft.app`. The macOS app binary is not the separate CLI. If FigCraft
85
+ is installed without the CLI, explain the difference and offer the official release:
86
+ <https://github.com/storytold/figcraft/releases/latest> (asset named
87
+ `figcraft-cli-<version>-<platform>`; on macOS `macos-universal.zip`). Check version
88
+ compatibility and verify the download when a checksum is available. Download/install
89
+ only after user consent; never fetch or run third-party binaries silently. Never handle
90
+ Figma tokens in the CLI or project rules. Use the harness's existing MCP connection when
91
+ available; do not assume it is configured.
80
92
 
81
93
  Prefer local, reviewable artifacts:
82
94
 
83
95
  - HTML/SVG wireframes in `.companion/local/mockups/`.
84
- - Screenshots at desktop and mobile widths.
85
- - Optional Figma integration via MCP when the user already works there. The CLI never
86
- handles Figma tokens.
96
+ - Target-device screenshots (desktop and mobile only when both are relevant).
97
+ - An editable source file, layout/tokens and meaningful variants rather than PNGs alone.
87
98
 
88
- ### 7. Get approval
99
+ ### 7. Prototype the slice before approval
89
100
 
90
- Present the flow, states, and screenshots. Ask for explicit approval or a concrete
91
- change. Do not start implementation from an unapproved mockup.
101
+ If the slice spans multiple screens, connect its primary action, back navigation, and
102
+ error/retry/empty branches with real prototype interactions (FigCraft prototype links,
103
+ Figma interactions, or a local interactive HTML equivalent). Open Play/presentation,
104
+ exercise each link and recovery path, and capture evidence. Do not mistake rendered
105
+ frames for a working prototype: if Play cannot navigate, explicitly report a static
106
+ mock and do not claim interactive validation. Record device size, starting screen,
107
+ tested transitions and missing branches. Keep interactions honest: prototypes simulate
108
+ the flow, not network calls, recording, authentication or persistent data.
109
+
110
+ ### 8. Get approval
111
+
112
+ Present the flow, states, screenshots, and prototype entry point. Ask for explicit
113
+ approval or a concrete change. Do not start implementation from an unapproved mockup;
114
+ after approval hand off the validated states and interactions to the implementation role
115
+ (frontend for web; mobile for native phone/watch), along with tokens and accessibility
116
+ requirements. Generated code is a starting point, not a verified implementation.
92
117
 
93
118
  ## Output
94
119
 
@@ -101,13 +126,15 @@ change. Do not start implementation from an unapproved mockup.
101
126
  - accessibility checklist;
102
127
  - motion specification;
103
128
  - design tokens and components;
104
- - mockup and screenshot references;
129
+ - editable mockup, prototype transitions and screenshot references;
105
130
  - approval record.
106
131
 
107
132
  ## Verification
108
133
 
109
134
  - All states are designed, not only the happy path.
110
135
  - Keyboard and screen reader paths are described.
111
- - Screenshots exist at desktop and mobile widths.
136
+ - Screenshots exist for the target devices and required states.
137
+ - Play/presentation was exercised for the primary and recovery paths, or the
138
+ lack of interactive capability was reported explicitly.
112
139
  - The user approved the design or requested specific changes.
113
140
  - A vision-capable model reviewed the screenshots against the spec.
package/src/cli.mjs CHANGED
@@ -45,7 +45,7 @@ Init options:
45
45
  --harness <name> Force the harness adapter (auto by default)
46
46
  --profile <name> ${Object.keys(PROFILES).join(" | ")}
47
47
  --skills <a,b> Extra skills to install
48
- --rules <mode> keep | append | replace (existing AGENTS.md/CLAUDE.md)
48
+ --rules <mode> keep | append | handoff | replace (existing rules)
49
49
  --branching <name> gitflow | gitlab-flow | trunk-based | github-flow | custom
50
50
  --docs <mode> local | tracked
51
51
  --memory <mode> engram | none
@@ -88,8 +88,8 @@ function printPlan(plan) {
88
88
 
89
89
  function normalizeMode(value, fallback) {
90
90
  if (!value || value === true) return fallback;
91
- if (!["keep", "append", "replace"].includes(value)) {
92
- throw new Error(`invalid rules mode "${value}". Use keep, append, or replace.`);
91
+ if (!["keep", "append", "handoff", "replace"].includes(value)) {
92
+ throw new Error(`invalid rules mode "${value}". Use keep, append, handoff, or replace.`);
93
93
  }
94
94
  return value;
95
95
  }
@@ -159,7 +159,7 @@ async function cmdInit(args) {
159
159
  const rulesFlag = flag(args, "rules");
160
160
  const rules = {
161
161
  "AGENTS.md": normalizeMode(rulesFlag, "keep"),
162
- "CLAUDE.md": normalizeMode(rulesFlag, "keep")
162
+ "CLAUDE.md": rulesFlag === "handoff" ? "keep" : normalizeMode(rulesFlag, "keep")
163
163
  };
164
164
  if (!yes && !rulesFlag) {
165
165
  for (const file of ["AGENTS.md", "CLAUDE.md"]) {
@@ -167,7 +167,7 @@ async function cmdInit(args) {
167
167
  if (!exists) continue;
168
168
  rules[file] = await choose(
169
169
  `${file} already exists. What should I do?`,
170
- ["keep", "append", "replace"],
170
+ file === "AGENTS.md" ? ["keep", "handoff", "append", "replace"] : ["keep", "append", "replace"],
171
171
  "keep"
172
172
  );
173
173
  }
@@ -228,14 +228,22 @@ async function cmdInit(args) {
228
228
  filePath: join(requested, "AGENTS.md"),
229
229
  mode: rules["AGENTS.md"],
230
230
  block: agentsBlock,
231
- force
231
+ force,
232
+ backupPath: join(requested, ".companion", "local", "rules-backup", "AGENTS.md")
232
233
  });
234
+ if (["error", "blocked"].includes(rulesResult["AGENTS.md"].mode)) {
235
+ throw new Error(`AGENTS.md: ${rulesResult["AGENTS.md"].reason}`);
236
+ }
233
237
  rulesResult["CLAUDE.md"] = applyRules({
234
238
  filePath: join(requested, "CLAUDE.md"),
235
239
  mode: rules["CLAUDE.md"],
236
240
  block: claudeBlock,
237
- force
241
+ force,
242
+ backupPath: join(requested, ".companion", "local", "rules-backup", "CLAUDE.md")
238
243
  });
244
+ if (["error", "blocked"].includes(rulesResult["CLAUDE.md"].mode)) {
245
+ throw new Error(`CLAUDE.md: ${rulesResult["CLAUDE.md"].reason}`);
246
+ }
239
247
 
240
248
  const canonicalResults = installCanonical({ target: requested, force });
241
249
  const skillResults = installSkills({ target: requested, adapter, skills, mode, force });
@@ -283,7 +291,7 @@ async function cmdInit(args) {
283
291
  }
284
292
  if (ignore.changed) console.log(` .gitignore: added ${ignore.added.join(", ")}`);
285
293
  console.log("");
286
- console.log("Next: run `devcomp doctor`; resolve any FAIL before starting with `project-discovery`.");
294
+ console.log("Next: run `devcomp doctor`; resolve rules merge or legacy agent FAIL before starting work.");
287
295
  }
288
296
 
289
297
  async function cmdAdd(args) {
@@ -383,13 +391,13 @@ async function cmdDoctor(args) {
383
391
  add("orchestrator", "fail", "team-lead binding missing");
384
392
  } else {
385
393
  const content = readFileSync(teamLeadPath, "utf8");
386
- const primary = /^mode:\s*primary\s*$/m.test(content);
394
+ const callable = /^mode:\s*subagent\s*$/m.test(content);
387
395
  add(
388
396
  "orchestrator",
389
- primary ? "pass" : "fail",
390
- primary
391
- ? "team-lead is a primary agent"
392
- : "team-lead is not primary; review local edits and run devcomp add role team-lead --force"
397
+ callable ? "pass" : "fail",
398
+ callable
399
+ ? "team-lead is callable; native primary owns delivery"
400
+ : "legacy primary team-lead binding; review local edits and run devcomp add role team-lead --force"
393
401
  );
394
402
  const denies = (action) => new RegExp(`- action: ${action}\\s+resource: "\\*"\\s+effect: deny`).test(content);
395
403
  const delegates = /- action: subagent\s+resource: "\*"\s+effect: allow/.test(content);
@@ -416,10 +424,10 @@ async function cmdDoctor(args) {
416
424
  }
417
425
  add(
418
426
  "default agent",
419
- defaultAgent === "team-lead" ? "pass" : "fail",
427
+ defaultAgent === "team-lead" ? "fail" : defaultAgent && defaultAgent !== "build" ? "warn" : "pass",
420
428
  defaultAgent
421
429
  ? `default_agent=${defaultAgent}`
422
- : "not set; set default_agent to team-lead in your existing OpenCode config, then start a new session"
430
+ : "not set; native Build remains the default"
423
431
  );
424
432
  }
425
433
 
@@ -429,9 +437,12 @@ async function cmdDoctor(args) {
429
437
  } else {
430
438
  const content = readFileSync(agentsPath, "utf8");
431
439
  const managed = hasManagedBlock(content);
432
- const current = managed && content.includes(".companion/core/process.md");
440
+ const pending = content.split("<!-- development-companion:start -->")[0].includes("# Project rules merge pending");
441
+ const current = managed && content.includes(".companion/core/process.md") && !pending;
433
442
  add("AGENTS.md", current ? "pass" : "fail", current ? "canonical process linked" :
434
- "framework rules missing or outdated; run devcomp init --rules append (preserves existing rules)");
443
+ pending
444
+ ? "merge the original from .companion/local/rules-backup/ into AGENTS.md and remove pending notice after review"
445
+ : "framework rules missing or outdated; ask the harness agent to merge the rules, or use devcomp init --rules handoff");
435
446
  }
436
447
 
437
448
  const claudePath = join(target, "CLAUDE.md");
package/src/install.mjs CHANGED
@@ -139,16 +139,16 @@ function bindingBody(role) {
139
139
  }
140
140
 
141
141
  function openCodeLeadBody() {
142
- return `You are the primary orchestrator for this OpenCode session. The user talks only to you.
142
+ return `You are a callable coordination specialist. The native primary agent remains accountable to the user and retains its normal tools.
143
143
 
144
144
  ## Mandatory routing
145
145
 
146
146
  - You do not implement, edit code, run shell commands, or produce specialist artifacts.
147
147
  - Your only writable paths are \`.companion/local/**\` and \`docs/companion/**\`.
148
- - Every non-trivial request MUST be delegated with the \`subagent\` tool.
148
+ - When asked to coordinate work needing multiple specialists, delegate with the \`subagent\` tool.
149
149
  - A delegation is real only if you call \`subagent\`. Never claim a delegation you did not perform.
150
150
  - Launch independent specialists in parallel; serialize only when one depends on another.
151
- - Only you speak to the user. Specialists report to you; verify their evidence before accepting it.
151
+ - Report to the primary agent; it speaks to the user and verifies your evidence.
152
152
  - If a child returns without evidence, send it back with a bounded follow-up.
153
153
 
154
154
  ## Routing
@@ -175,14 +175,14 @@ function openCodeLeadBody() {
175
175
  3. Call \`subagent\` with goal, context, deliverable, verification, and do-not.
176
176
  4. Review the child's evidence; ask for fixes if needed.
177
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 user with evidence.
178
+ 6. Report to the primary agent with evidence.
179
179
 
180
- A trivial one-line answer may be answered directly. Anything that changes the repository or produces an artifact must be delegated.`;
180
+ A read-only recommendation may be answered directly. Anything that changes the repository or produces an artifact must be delegated.`;
181
181
  }
182
182
 
183
183
  function openCodeBinding(role) {
184
184
  const isLead = role === "team-lead";
185
- const mode = isLead ? "primary" : "subagent";
185
+ const mode = "subagent";
186
186
  const body = isLead ? openCodeLeadBody() : bindingBody(role);
187
187
  const permissions = isLead
188
188
  ? [
@@ -268,34 +268,18 @@ export function installBindings({ target, adapter, roles, force = false }) {
268
268
  }
269
269
 
270
270
  /**
271
- * Create `.opencode/opencode.json` with `default_agent: team-lead` only when the
272
- * project has no existing OpenCode config at its root or inside `.opencode/`.
271
+ * Leave the harness default and existing configuration alone. The process is
272
+ * installed as instructions, not as a replacement for the native Build agent.
273
273
  */
274
274
  export function writeOpenCodeConfig(target) {
275
- const dir = join(target, ".opencode");
276
- const jsonPath = join(dir, "opencode.json");
277
- const jsoncPath = join(dir, "opencode.jsonc");
278
- const existing = [jsonPath, jsoncPath, join(target, "opencode.json"), join(target, "opencode.jsonc")]
275
+ const existing = [
276
+ join(target, ".opencode", "opencode.json"),
277
+ join(target, ".opencode", "opencode.jsonc"),
278
+ join(target, "opencode.json"),
279
+ join(target, "opencode.jsonc")
280
+ ]
279
281
  .find((path) => existsSync(path));
280
- if (existing) {
281
- return {
282
- status: "kept",
283
- path: existing,
284
- };
285
- }
286
- ensureDir(dir);
287
- writeText(
288
- jsonPath,
289
- `${JSON.stringify(
290
- {
291
- $schema: "https://opencode.ai/config.json",
292
- default_agent: "team-lead",
293
- },
294
- null,
295
- 2,
296
- )}\n`,
297
- );
298
- return { status: "created", path: jsonPath };
282
+ return { status: existing ? "kept" : "native default (no config written)", path: existing ?? "OpenCode default" };
299
283
  }
300
284
 
301
285
  export function writeManifest(target, manifest) {
package/src/rules.mjs CHANGED
@@ -1,4 +1,5 @@
1
- import { existsSync, readFileSync, writeFileSync } from "node:fs";
1
+ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
2
+ import { basename, dirname, relative } from "node:path";
2
3
 
3
4
  export const START = "<!-- development-companion:start -->";
4
5
  export const END = "<!-- development-companion:end -->";
@@ -27,7 +28,11 @@ export function appendBlock(content, block) {
27
28
  return `${trimmed}\n\n${block}\n`;
28
29
  }
29
30
 
30
- export function applyRules({ filePath, mode, block, force = false }) {
31
+ function mergeNotice(filePath, backupPath) {
32
+ return `# Project rules merge pending\n\nThe original AGENTS.md is backed up at \`${relative(dirname(filePath), backupPath)}\`. Before coding, compare it with this file and merge business rules, commands, tools and constraints into one coherent AGENTS.md. Preserve both sets of requirements; resolve conflicts with the user. Remove this notice only after reviewing the backup. Do not commit this pending file or its local backup: the original rules would be absent on other machines.\n\n`;
33
+ }
34
+
35
+ export function applyRules({ filePath, mode, block, force = false, backupPath }) {
31
36
  block = block.trimEnd();
32
37
  const exists = existsSync(filePath);
33
38
  if (!exists) {
@@ -40,12 +45,31 @@ export function applyRules({ filePath, mode, block, force = false }) {
40
45
  return { mode: "kept", changed: false, reason: "keep requested" };
41
46
  }
42
47
 
48
+ if (mode === "handoff") {
49
+ if (!backupPath || hasManagedBlock(current)) {
50
+ return { mode: "error", changed: false, reason: "handoff requires a backup path and unmerged original rules" };
51
+ }
52
+ if (existsSync(backupPath) && readFileSync(backupPath, "utf8") !== current) {
53
+ return { mode: "error", changed: false, reason: "backup differs; merge existing backup before retrying" };
54
+ }
55
+ mkdirSync(dirname(backupPath), { recursive: true });
56
+ if (!existsSync(backupPath)) writeFileSync(backupPath, current, { encoding: "utf8", flag: "wx" });
57
+ writeFileSync(filePath, `${mergeNotice(filePath, backupPath)}${block}\n`, "utf8");
58
+ return { mode: "handoff", changed: true, reason: "original backed up; agent merge pending" };
59
+ }
60
+
43
61
  if (mode === "replace") {
44
62
  if (!force) {
45
63
  return { mode: "blocked", changed: false, reason: "replace requires --force" };
46
64
  }
47
- writeFileSync(filePath, `${block}\n`, "utf8");
48
- return { mode: "replaced", changed: true, reason: "replace requested" };
65
+ if (!backupPath) return { mode: "error", changed: false, reason: "replace requires a backup path" };
66
+ if (existsSync(backupPath) && readFileSync(backupPath, "utf8") !== current) {
67
+ return { mode: "error", changed: false, reason: "backup differs; merge existing backup before retrying" };
68
+ }
69
+ mkdirSync(dirname(backupPath), { recursive: true });
70
+ if (!existsSync(backupPath)) writeFileSync(backupPath, current, { encoding: "utf8", flag: "wx" });
71
+ writeFileSync(filePath, `${basename(filePath) === "AGENTS.md" ? mergeNotice(filePath, backupPath) : ""}${block}\n`, "utf8");
72
+ return { mode: "replaced", changed: true, reason: `original backed up at ${relative(dirname(filePath), backupPath)}` };
49
73
  }
50
74
 
51
75
  if (mode === "append") {
@@ -23,12 +23,26 @@ when the plan starts growing faster than the code. For a new project or a major
23
23
  frame (one page) → walking skeleton → slice loop → verify → release → close
24
24
  ```
25
25
 
26
- If the harness exposes a team lead, use it as the single accountable owner. In OpenCode,
27
- `team-lead` is the default primary agent and MUST use the `subagent` tool to delegate; it
28
- must not implement code or run shell commands itself. Its only writable paths are
29
- `.companion/local/**` and `docs/companion/**`. In other harnesses, invoke the team lead
30
- explicitly where supported; Pi has no native subagents, so follow the role workflow without
31
- claiming delegation that did not occur.
26
+ The native harness agent is the single accountable delivery owner: apply the Team Lead
27
+ contract without losing native edit, shell, skills, or delegation tools. Invoke the
28
+ `team-lead` specialist for substantial coordination when useful, not for every routine
29
+ slice. In OpenCode use native Build by default; the callable `team-lead` is a restricted
30
+ subagent. In harnesses without subagents, follow the role yourself; never claim a
31
+ delegation you did not perform.
32
+
33
+ ## Project rules integration
34
+
35
+ Before implementation, reconcile these process instructions with existing project/business
36
+ rules into one coherent `AGENTS.md`: project identity and domain → commands and toolchain →
37
+ architecture and conventions → delivery workflow and roles → verification and safety.
38
+ Keep unique facts from both sources; identify stale or conflicting instructions and ask the
39
+ user before discarding them. Do not blindly append or treat a backup as active instructions.
40
+ If `# Project rules merge pending` appears above, read the named local backup, perform the
41
+ merge and remove the notice only after review; run `devcomp doctor` again.
42
+
43
+ For each new project or material change, detect its language, stack and available harness
44
+ capabilities. Review `AGENTS.md` with the user where needed and update it through the harness,
45
+ not by guessing from the CLI.
32
46
 
33
47
  Profile: `{{profile}}`. Branching: `{{branching}}`.
34
48
 
@@ -46,7 +60,8 @@ Profile: `{{profile}}`. Branching: `{{branching}}`.
46
60
  without printing values.
47
61
  6. Do not commit secrets, local design documents, or `.companion/local/`.
48
62
  7. Keep the domain independent from frameworks and infrastructure. Ports and adapters.
49
- 8. UI work requires screenshots at desktop and mobile widths and a vision-capable review.
63
+ 8. UI work needs target-device screenshots, a vision-capable review, and (for multi-screen
64
+ flows) an interactive prototype exercised in Play/presentation before approval and code.
50
65
  9. If a decision is missing, ask; do not invent requirements.
51
66
 
52
67
  ## Local documents