development-companion 1.2.1 → 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
 
@@ -11,6 +11,12 @@ npx development-companion@latest init
11
11
  `devcomp init` detects the repository and harness, installs the process, and leaves your
12
12
  existing `AGENTS.md` and `CLAUDE.md` intact unless you choose otherwise.
13
13
 
14
+ Run `devcomp doctor` **from the repository opened by the agent**. If you work in a nested
15
+ repository, install there too: its own `AGENTS.md` and agent configuration may take precedence.
16
+ `init --yes` preserves existing rules; `doctor` fails when those rules do not activate the
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.
19
+
14
20
  ## Why
15
21
 
16
22
  Coding agents are powerful but inconsistent. Each harness has its own rules file, skill
@@ -56,7 +62,7 @@ npx development-companion init . \
56
62
  | `--harness <name>` | Force the adapter; `auto` detects it. |
57
63
  | `--profile <name>` | `web`, `backend`, `mobile`, `desktop`, `cross-platform`, `full`. |
58
64
  | `--skills <a,b>` | Add specific skills. |
59
- | `--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. |
60
66
  | `--branching <name>` | `gitflow`, `gitlab-flow`, `trunk-based`, `github-flow`, `custom`. |
61
67
  | `--docs local\|tracked` | Keep design docs local or version them in `docs/companion/`. |
62
68
  | `--memory engram\|none` | Recommend Engram for cross-session memory. |
@@ -70,7 +76,11 @@ If `AGENTS.md` or `CLAUDE.md` already exists, the CLI asks:
70
76
 
71
77
  - **keep** — leave the file untouched;
72
78
  - **append** — add a managed block, preserving your rules;
73
- - **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.
74
84
 
75
85
  The managed block is delimited by `<!-- development-companion:start -->` and
76
86
  `<!-- development-companion:end -->`, so updates are idempotent.
@@ -87,26 +97,23 @@ The managed block is delimited by `<!-- development-companion:start -->` and
87
97
 
88
98
  ## The process
89
99
 
90
- For a new project or a major change:
100
+ The process exists to ship working software, not to produce documents. It is a loop:
91
101
 
92
102
  ```text
93
103
  0 Bootstrap
94
- → 1 Operational discovery (Team Lead)
95
- → 2 Architecture + security (Architect ∥ Cybersecurity)
96
- → 3 Test strategy (QA)
97
- → 4 UX/UI (Frontend)
98
- → 5 Delivery plan (Team Lead)
99
- → 6 Implementation (specialists)
100
- → 7 Security verification (Cybersecurity)
101
- → 8 QA verification (QA)
102
- → 9 Deployment (SRE)
103
- → 10 Closure (Team Lead)
104
+ → 1 Frame (one page, 30–60 min)
105
+ → 2 Walking skeleton (end-to-end, fakes allowed)
106
+ → 3 Slice loop (build → test → demo → next)
107
+ → 4 Verify (security + QA, continuous)
108
+ → 5 Release
109
+ → 6 Close
104
110
  ```
105
111
 
106
- Each phase has an owner, an artifact in `.companion/local/`, and a gate with evidence.
107
- For a small change, the process collapses to the workflow in `core/workflow.md`.
112
+ Planning artifacts are living notes written just in time, not phase gates. The first commit
113
+ lands before the second design document. See `core/process.md` and the `incremental-delivery`
114
+ skill.
108
115
 
109
- Read `core/process.md` for the full phase guide.
116
+ For a small change, the process collapses to the workflow in `core/workflow.md`.
110
117
 
111
118
  ## Roles
112
119
 
@@ -127,21 +134,19 @@ Read `core/process.md` for the full phase guide.
127
134
 
128
135
  Role contracts live in `core/roles/`. The CLI installs them to `.companion/roles/` and
129
136
  generates native bindings where the harness supports subagents.
137
+ The canonical principles, process, workflow, quality gates, and guidelines are installed in
138
+ `.companion/core/`. The generated rules and agent bindings reference these files.
130
139
 
131
140
  ### Orchestration in OpenCode
132
141
 
133
- `devcomp init` installs `team-lead` with `mode: primary` and writes
134
- `.opencode/opencode.json` with `default_agent: "team-lead"`. The 11 specialists are
135
- subagents. New sessions start as the team lead, which delegates with the `subagent` tool;
136
- Build and Plan remain available in the agent selector. If the project already has an
137
- OpenCode config, the installer preserves it and `devcomp doctor` warns that
138
- `default_agent` is not set.
139
-
140
- The team lead is a router, not an implementer. Its generated binding denies `edit` outside
141
- `.companion/local/**` and `docs/companion/**`, and denies `shell`; it must launch a
142
- specialist for code, commands, tests, security, UX, or deployment. Specialists deny the
143
- `subagent` permission, so only the team lead orchestrates. Existing sessions keep their
144
- previous agent; start a new session to pick up `team-lead`.
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.
145
150
 
146
151
  ## Skills and profiles
147
152
 
@@ -149,7 +154,7 @@ Process skills are installed always:
149
154
 
150
155
  `project-discovery`, `architecture-design`, `test-strategy`, `ux-design`,
151
156
  `delivery-orchestration`, `security-review`, `deployment-sre`, `development-workflow`,
152
- `code-review`.
157
+ `incremental-delivery`, `code-review`.
153
158
 
154
159
  Domain skills are installed by profile:
155
160
 
@@ -165,20 +170,31 @@ Domain skills are installed by profile:
165
170
  Every skill is self-contained and follows the [Agent Skills](https://agentskills.io)
166
171
  specification.
167
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
+
168
178
  ## Harness support
169
179
 
170
180
  | Tier | Harnesses | Commitment |
171
181
  |---|---|---|
172
- | 1 | OpenCode, Claude Code, Codex, Pi | Verified per release |
182
+ | 1 | OpenCode, Claude Code, Codex, Pi | Installation targets; behavioral validation required per release |
173
183
  | 2 | Cursor, Gemini CLI, Copilot CLI, Windsurf, Cline | Best-effort, generated |
174
184
  | 3 | Any harness that reads `AGENTS.md` or accepts a prompt pack | Generic fallback |
175
185
 
176
186
  Adapters are data: rules file, skills directory, agent directory, and limitations.
187
+ Installation checks do not prove that a model followed the workflow. Claude Code and Codex
188
+ provide specialist bindings but do not automatically start in a team-lead role; invoke it
189
+ explicitly when orchestration is needed. Pi has no native subagents and must run the role
190
+ workflow in one session or through a user-supplied extension. Validate real agent behavior
191
+ in each harness before claiming process compliance.
177
192
 
178
193
  ## Local design documents
179
194
 
180
195
  By default, discovery, architecture, test plans, evidence, and reports live in
181
- `.companion/local/`, which is ignored by git. Only `.companion/config.json` is tracked.
196
+ `.companion/local/`, which is ignored by git. The manifest, installed core documents,
197
+ roles, and skills can be tracked; the design notes remain local unless opted in.
182
198
 
183
199
  If you want the design to travel with the repository:
184
200
 
@@ -188,6 +204,8 @@ npx development-companion init . --docs tracked
188
204
 
189
205
  That moves the artifacts to `docs/companion/`.
190
206
 
207
+ This configured path overrides default `.companion/local/` examples in role and skill files.
208
+
191
209
  ## Memory: Engram (optional)
192
210
 
193
211
  The process works without memory. If Engram is available, it stores decisions, findings,
@@ -242,6 +260,9 @@ and Playwright tests. Screenshots, command logs, process artifacts, and `report.
242
260
  written to `plannification/validation/e2e-expense/<iteration>/` (gitignored). The workdir
243
261
  stays for inspection; the next run deletes it.
244
262
 
263
+ This exercises installation and a prebuilt app fixture; it does **not** launch a coding agent
264
+ or prove it followed instructions. Behavioral validation requires separate agent sessions.
265
+
245
266
  ## Repository layout
246
267
 
247
268
  ```text
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.2.1.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.2.1`, 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.2.1 --version
83
- npx development-companion@1.2.1 init . --yes --harness opencode --profile web
84
- npx development-companion@1.2.1 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.2.1 -m "v1.2.1"
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.2.1
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
 
@@ -12,12 +12,16 @@ npx development-companion@latest init --harness <name>
12
12
  The CLI reads `adapters/<name>/adapter.json`, installs skills into the adapter's skills
13
13
  directory, writes `AGENTS.md`/`CLAUDE.md` with keep/append/replace, and generates native
14
14
  agent bindings where the harness supports them.
15
+ It also installs canonical process documents in `.companion/core/`. Run `devcomp doctor`
16
+ from the agent's workspace (including nested repositories). A preserved rules file without
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.
15
19
 
16
20
  ## Support tiers
17
21
 
18
22
  | Tier | Harness | Commitment |
19
23
  |---|---|---|
20
- | 1 | OpenCode, Claude Code, Codex, Pi | Installation and discovery verified per release |
24
+ | 1 | OpenCode, Claude Code, Codex, Pi | Installation and discovery targets; verify behavior in a real agent session |
21
25
  | 2 | Cursor, Gemini CLI, Copilot CLI, Windsurf, Cline | Best-effort adapter; verify against the installed version |
22
26
  | 3 | Any other harness | `AGENTS.md` + skills copy or prompt pack |
23
27
 
@@ -57,7 +61,9 @@ Each adapter declares its paths and limitations:
57
61
  - If they exist, the CLI asks **keep**, **append**, or **replace**.
58
62
  - `append` uses a managed block with
59
63
  `<!-- development-companion:start -->` / `<!-- development-companion:end -->`.
60
- - `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.
61
67
  - `--yes` defaults to `keep` for existing files.
62
68
 
63
69
  ## Binding roles
@@ -81,6 +87,8 @@ Roles are contracts in `.companion/roles/`. Bindings are thin:
81
87
 
82
88
  Pi has no built-in subagents: use the role contract as a prompt template or invoke the
83
89
  related skill.
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.
84
92
 
85
93
  ## Limitations by harness
86
94
 
@@ -37,31 +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/opencode.json` or `.opencode/opencode.jsonc`, the installer
55
- preserves it and `devcomp doctor` warns that `default_agent` is not set.
56
-
57
- OpenCode does not route by intent by itself. The generated team-lead prompt **mandates**
58
- delegation with the `subagent` tool, and its permissions **deny `edit` and `shell`** outside
59
- `.companion/local/**` and `docs/companion/**`. The team lead therefore cannot implement code
60
- or run commands itself; it must launch the specialists. Specialists deny `subagent`, so only
61
- the team lead orchestrates.
62
-
63
- For deterministic routing beyond prompt and permissions, an OpenCode plugin would be needed,
64
- but the generated binding is designed so the model has no direct path to do the work.
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`.
65
59
 
66
60
  ## Specialist example
67
61
 
@@ -100,12 +94,12 @@ OpenCode V2 uses **`permissions`** (plural), an ordered list of
100
94
 
101
95
  ## Team lead example
102
96
 
103
- The generated binding is a router, not an implementer:
97
+ The generated binding is a callable router, not the native primary:
104
98
 
105
99
  ```yaml
106
100
  ---
107
101
  description: Leads discovery, planning, delegation, and closure.
108
- mode: primary
102
+ mode: subagent
109
103
  permissions:
110
104
  - action: edit
111
105
  resource: "*"
@@ -131,8 +125,9 @@ permissions:
131
125
  ---
132
126
  ```
133
127
 
134
- The last matching rule wins. The team lead can read, write its own plan/closure documents,
135
- and launch any specialist, but it cannot edit code or run shell commands. Specialists get
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
136
131
  `{ "action": "subagent", "resource": "*", "effect": "deny" }` so they cannot spawn more
137
132
  agents.
138
133
 
@@ -143,9 +138,11 @@ To restrict which specialists the team lead may launch, replace `"*"` with expli
143
138
 
144
139
  - OpenCode subagents use Markdown frontmatter, not the canonical role format. Keep the
145
140
  binding thin and put durable policy in `core/`.
146
- - The team lead starts with fresh context in a new session. It reads
147
- `.companion/local/` and the repository; it does not inherit the previous chat. Existing
148
- sessions keep their previous agent; start a new session to pick up `team-lead`.
141
+ - Install separately from the working repository root when an app is a nested repository;
142
+ the parent repo's rules, skills and agent definitions may not be discovered.
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.
149
146
  - Permissions are enforced by the harness; the generated binding blocks direct code edits
150
147
  and shell commands from the team lead.
151
148
 
@@ -11,6 +11,27 @@ OpenCode, Claude Code, Codex, Pi, or a human.
11
11
  "Better" means the requested problem is solved, the change is understandable,
12
12
  and the evidence shows it works. Clever code that cannot be verified is not better.
13
13
 
14
+ ## The delivery rule
15
+
16
+ **Working software is the measure of progress.** Planning is a tool, not a deliverable.
17
+
18
+ - The first commit lands in the first work block, before the second design document.
19
+ - Every session ends with a running increment, a failing test that defines the next step, or a
20
+ named blocker that needs the user.
21
+ - A document is progress only when it unblocks a slice that is about to be built.
22
+ - A project with ten documents and no runnable path has not progressed; it has accumulated risk.
23
+
24
+ **Red flags:** a brief longer than the first slice; "phase complete" with no commit; a third
25
+ architecture review before any code; planning used to avoid deciding.
26
+
27
+ ## Planning budget
28
+
29
+ - Frame: 30–60 minutes, one page.
30
+ - Before the first end-to-end slice: **≤ 10–15 % of total effort**.
31
+ - Every artifact names the slice it unblocks. If it cannot, defer it.
32
+ - If a planning document exceeds two pages before the first commit, cut it.
33
+ - A second planning cycle on the same topic is a smell: decide, build, and let the code answer.
34
+
14
35
  ---
15
36
 
16
37
  ## 1. Understand before changing