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 +22 -21
- package/RELEASE.md +12 -9
- package/adapters/README.md +7 -5
- package/adapters/opencode/README.md +27 -35
- package/core/process.md +4 -1
- package/core/roles/team-lead.md +6 -3
- package/package.json +1 -1
- package/skills/ux-design/SKILL.md +36 -9
- package/src/cli.mjs +28 -17
- package/src/install.mjs +15 -31
- package/src/rules.mjs +28 -4
- package/templates/rules/AGENTS.block.md +22 -7
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**, **
|
|
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.
|
|
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
|
|
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
|
-
- **
|
|
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`
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
`
|
|
143
|
-
|
|
144
|
-
|
|
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.
|
|
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.
|
|
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.
|
|
83
|
-
npx development-companion@1.
|
|
84
|
-
npx development-companion@1.
|
|
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.
|
|
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.
|
|
103
|
+
https://codeberg.org/rockmadehome/development-companion/releases/new?tag=v1.4.0
|
|
104
104
|
```
|
|
105
105
|
|
|
106
|
-
Include the install command,
|
|
107
|
-
|
|
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
|
|
package/adapters/README.md
CHANGED
|
@@ -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
|
|
18
|
-
|
|
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
|
-
- `
|
|
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
|
-
|
|
89
|
-
|
|
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:
|
|
41
|
-
- The 11 specialists — `mode: subagent`, launched by the
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
It
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
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
|
|
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:
|
|
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
|
|
138
|
-
and launch
|
|
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
|
|
152
|
-
`.companion/local/` and the repository; it does not inherit the
|
|
153
|
-
sessions keep their previous agent; start a new session
|
|
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
|
|
package/core/roles/team-lead.md
CHANGED
|
@@ -4,9 +4,10 @@
|
|
|
4
4
|
|
|
5
5
|
## Mission
|
|
6
6
|
|
|
7
|
-
Ship working increments.
|
|
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
|
-
-
|
|
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
|
@@ -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.
|
|
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
|
-
-
|
|
85
|
-
-
|
|
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.
|
|
99
|
+
### 7. Prototype the slice before approval
|
|
89
100
|
|
|
90
|
-
|
|
91
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
394
|
+
const callable = /^mode:\s*subagent\s*$/m.test(content);
|
|
387
395
|
add(
|
|
388
396
|
"orchestrator",
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
? "team-lead is
|
|
392
|
-
: "team-lead
|
|
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" ? "
|
|
427
|
+
defaultAgent === "team-lead" ? "fail" : defaultAgent && defaultAgent !== "build" ? "warn" : "pass",
|
|
420
428
|
defaultAgent
|
|
421
429
|
? `default_agent=${defaultAgent}`
|
|
422
|
-
: "not set;
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
-
-
|
|
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
|
-
-
|
|
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
|
|
178
|
+
6. Report to the primary agent with evidence.
|
|
179
179
|
|
|
180
|
-
A
|
|
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 =
|
|
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
|
-
*
|
|
272
|
-
*
|
|
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
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
48
|
-
|
|
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
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
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
|
|
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
|