development-companion 1.4.1 → 1.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +29 -0
- package/README.md +40 -24
- package/RELEASE.md +24 -15
- package/adapters/README.md +3 -2
- package/adapters/opencode/README.md +14 -15
- package/core/guidelines/coordination.md +78 -0
- package/core/principles.md +3 -3
- package/core/process.md +9 -6
- package/core/quality-gates.md +2 -2
- package/core/roles/architect.md +6 -5
- package/core/roles/qa-engineer.md +3 -2
- package/core/roles/team-lead.md +17 -15
- package/core/workflow.md +6 -13
- package/package.json +3 -2
- package/skills/development-workflow/SKILL.md +7 -0
- package/skills/project-discovery/SKILL.md +9 -3
- package/skills/ux-design/SKILL.md +4 -0
- package/src/cli.mjs +182 -46
- package/src/content.mjs +1 -1
- package/src/install.mjs +27 -49
- package/src/rules.mjs +136 -6
- package/templates/artifacts/01-operational-brief.md +9 -1
- package/templates/rules/AGENTS.block.md +124 -52
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 1.6.0
|
|
4
|
+
|
|
5
|
+
- `devcomp update` replaces framework-owned skills, roles, bindings, and canonical
|
|
6
|
+
content by default. Use `--keep` to preserve them for a manual merge.
|
|
7
|
+
- `AGENTS.md` is now a complete managed template plus a `# User guiding` section.
|
|
8
|
+
Updates preserve User guiding verbatim and always write `AGENTS.md.bak`.
|
|
9
|
+
- Existing legacy `AGENTS.md` files are migrated automatically (old content under
|
|
10
|
+
User guiding). Ambiguous structures leave a merge-pending notice and `doctor`
|
|
11
|
+
fails until an agent merges the backup.
|
|
12
|
+
- `doctor` verifies canonical, role, and skill content against the package, plus
|
|
13
|
+
the template version and the presence of User guiding.
|
|
14
|
+
|
|
15
|
+
## 1.5.1
|
|
16
|
+
|
|
17
|
+
- `devcomp update --dry-run` now reports the plan and writes nothing instead of
|
|
18
|
+
silently updating the installation.
|
|
19
|
+
|
|
20
|
+
## 1.5.0
|
|
21
|
+
|
|
22
|
+
- The native primary coordinates delivery, directly invokes specialists, and is
|
|
23
|
+
the sole user interlocutor. In OpenCode, the callable Team Lead is an advisor
|
|
24
|
+
and cannot subdelegate.
|
|
25
|
+
- Non-trivial work requires an operational conversation and explicit approval
|
|
26
|
+
of the technical approach. Role handoffs record evidence for golden and dark
|
|
27
|
+
paths, with optional Engram persistence and local records as the fallback.
|
|
28
|
+
- `doctor` detects outdated OpenCode Team Lead permissions. See the
|
|
29
|
+
[migration guide](README.md#working-modes) to preserve customizations.
|
package/README.md
CHANGED
|
@@ -97,6 +97,11 @@ The managed block is delimited by `<!-- development-companion:start -->` and
|
|
|
97
97
|
|
|
98
98
|
## The process
|
|
99
99
|
|
|
100
|
+
**New in 1.5.0:** direct specialist delegation through the primary agent,
|
|
101
|
+
explicit approval of scope and technical approach, and evidence for golden
|
|
102
|
+
and dark paths with optional Engram persistence. Existing installations should
|
|
103
|
+
follow the [migration steps](#working-modes).
|
|
104
|
+
|
|
100
105
|
The process exists to ship working software, not to produce documents. It is a loop:
|
|
101
106
|
|
|
102
107
|
```text
|
|
@@ -140,51 +145,62 @@ The canonical principles, process, workflow, quality gates, and guidelines are i
|
|
|
140
145
|
### Orchestration in OpenCode
|
|
141
146
|
|
|
142
147
|
`devcomp init` preserves OpenCode's native Build default and any existing OpenCode config.
|
|
143
|
-
The native primary
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
148
|
+
The native primary acts as Coordinator and is the only agent that addresses the user.
|
|
149
|
+
It launches applicable roles directly for non-trivial work: read-only input, approved
|
|
150
|
+
implementation, independent verification, and authorized release. The callable
|
|
151
|
+
`team-lead` is an advisor; its binding denies shell and subdelegation and restricts edits
|
|
152
|
+
to companion notes.
|
|
153
|
+
|
|
154
|
+
The Coordinator leads an operational conversation (scope and observable acceptance)
|
|
155
|
+
and a technical conversation (choices, trade-offs, golden paths and dark paths). It
|
|
156
|
+
records explicit approval before implementation. Specialists return findings and evidence
|
|
157
|
+
to the Coordinator. Local notes capture approvals and handoffs; Engram retains relevant,
|
|
158
|
+
verified durable knowledge when enabled and available. See
|
|
159
|
+
[`core/guidelines/coordination.md`](core/guidelines/coordination.md).
|
|
150
160
|
|
|
151
161
|
### Working modes
|
|
152
162
|
|
|
153
163
|
| Mode | Primary agent | Use |
|
|
154
164
|
|---|---|---|
|
|
155
|
-
| **
|
|
156
|
-
| **
|
|
165
|
+
| **Short workflow** | native primary | Routine changes in scope that introduce no new decision. |
|
|
166
|
+
| **Coordinated** | native primary | Direct specialist delegation for non-trivial work; the primary owns gates and communication. |
|
|
167
|
+
| **Single-agent fallback** | native primary | Disclose unavailable delegation; never claim independent review. |
|
|
157
168
|
| **Legacy (do not use)** | `team-lead` as primary | A read-only lead blocks direct implementation and confuses the workflow. |
|
|
158
169
|
|
|
159
|
-
**Migrating
|
|
170
|
+
**Migrating an existing install:**
|
|
171
|
+
|
|
172
|
+
Run the following with Development Companion 1.5.0 (use `node bin/devcomp.mjs`
|
|
173
|
+
from the source checkout to verify before publication).
|
|
160
174
|
|
|
161
175
|
1. Review local customizations and make a private backup outside the repository of
|
|
162
176
|
`AGENTS.md`, `CLAUDE.md`, `.companion/core/`, `.companion/roles/`, `.agents/skills/`,
|
|
163
177
|
`.opencode/agents/` and existing OpenCode configuration. Do not publish the backup
|
|
164
178
|
or read/copy `.env` files.
|
|
165
|
-
2. `
|
|
166
|
-
the
|
|
167
|
-
bindings. Review the
|
|
168
|
-
|
|
169
|
-
|
|
179
|
+
2. `devcomp update <project>` (without `--force`). This installs missing content,
|
|
180
|
+
including the coordination guide, and refreshes the managed block while keeping
|
|
181
|
+
existing skills, core documents, roles and bindings. Review the diff, recover
|
|
182
|
+
any custom text from inside the old managed block, and merge changes manually
|
|
183
|
+
into preserved files that conflict with the new coordination contract.
|
|
170
184
|
3. In the existing `opencode.json`/`opencode.jsonc` at the project root or in `.opencode/`,
|
|
171
185
|
remove `"default_agent": "team-lead"` or set it to `"build"`, preserving other settings.
|
|
172
|
-
4. If `.opencode/agents/team-lead.md`
|
|
173
|
-
|
|
174
|
-
`
|
|
175
|
-
|
|
176
|
-
|
|
186
|
+
4. If `.opencode/agents/team-lead.md` uses `mode: primary` or allows subdelegation,
|
|
187
|
+
merge the updated binding and role manually. Or, after backing up both files,
|
|
188
|
+
regenerate them with `devcomp add role team-lead --target <project> --force`.
|
|
189
|
+
This command overwrites both files without backup. Reapply compatible customizations;
|
|
190
|
+
keep `mode: subagent` and deny `subagent`. Apply step 3 only if the old default exists.
|
|
177
191
|
5. Start a new OpenCode session (the current one keeps the old agent).
|
|
178
|
-
6. `
|
|
179
|
-
|
|
192
|
+
6. `devcomp doctor <project>` checks the installed process, rules and OpenCode binding.
|
|
193
|
+
Then use a new session to verify actual behavior: the primary delegates and asks
|
|
194
|
+
for approval; withhold or reject it and check that implementation does not start.
|
|
180
195
|
|
|
181
196
|
Do not use a blanket `update --force` as a migration shortcut: it deletes installed
|
|
182
197
|
skill directories and replaces roles, core documents and bindings, including local
|
|
183
198
|
customizations. `doctor` checks the managed process block; separately review any
|
|
184
199
|
project-specific instructions outside it for conflicts.
|
|
185
200
|
|
|
186
|
-
|
|
187
|
-
|
|
201
|
+
The CLI installs prompts and permissions; it does not enforce conversational approval
|
|
202
|
+
as a runtime interlock. A harness may display that subagents ran even though only the
|
|
203
|
+
Coordinator addresses the user.
|
|
188
204
|
|
|
189
205
|
## Skills and profiles
|
|
190
206
|
|
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.5.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 .
|
|
@@ -51,6 +51,14 @@ npm install "$packdir"/development-companion-1.4.1.tgz
|
|
|
51
51
|
|
|
52
52
|
All checks must pass before publishing.
|
|
53
53
|
|
|
54
|
+
For coordination changes, also exercise a fresh agent session: give it a
|
|
55
|
+
non-trivial task with a decision to make. On the golden path, the primary
|
|
56
|
+
delegates read-only work, presents options, receives explicit approval, and
|
|
57
|
+
then delegates implementation and verification. On the dark path, withhold
|
|
58
|
+
or deny approval and confirm that no implementation starts. If Engram is
|
|
59
|
+
unavailable, confirm that local evidence remains and the primary does not
|
|
60
|
+
claim a successful save. The CLI smoke test is not a substitute for this check.
|
|
61
|
+
|
|
54
62
|
## 4. Publish
|
|
55
63
|
|
|
56
64
|
```bash
|
|
@@ -71,7 +79,7 @@ republish immediately. Wait a few minutes and verify:
|
|
|
71
79
|
npm view development-companion version dist-tags
|
|
72
80
|
```
|
|
73
81
|
|
|
74
|
-
The `latest` tag must point to `1.
|
|
82
|
+
The `latest` tag must point to `1.5.0`, not `0.0.0-stage`. If it still points to the
|
|
75
83
|
placeholder after several minutes, check the npmjs.com package page and the Staged
|
|
76
84
|
Packages tab before retrying.
|
|
77
85
|
|
|
@@ -79,9 +87,9 @@ Packages tab before retrying.
|
|
|
79
87
|
|
|
80
88
|
```bash
|
|
81
89
|
cd "$(mktemp -d)"
|
|
82
|
-
npx development-companion@1.
|
|
83
|
-
npx development-companion@1.
|
|
84
|
-
npx development-companion@1.
|
|
90
|
+
npx development-companion@1.5.0 --version
|
|
91
|
+
npx development-companion@1.5.0 init . --yes --harness opencode --profile web
|
|
92
|
+
npx development-companion@1.5.0 doctor .
|
|
85
93
|
```
|
|
86
94
|
|
|
87
95
|
Also verify the package page:
|
|
@@ -93,19 +101,19 @@ https://www.npmjs.com/package/development-companion
|
|
|
93
101
|
## 6. Tag and publish the source release
|
|
94
102
|
|
|
95
103
|
```bash
|
|
96
|
-
git tag -a v1.
|
|
104
|
+
git tag -a v1.5.0 -m "v1.5.0"
|
|
97
105
|
git push origin main --tags
|
|
98
106
|
```
|
|
99
107
|
|
|
100
108
|
Create the release on Codeberg:
|
|
101
109
|
|
|
102
110
|
```text
|
|
103
|
-
https://codeberg.org/rockmadehome/development-companion/releases/new?tag=v1.
|
|
111
|
+
https://codeberg.org/rockmadehome/development-companion/releases/new?tag=v1.5.0
|
|
104
112
|
```
|
|
105
113
|
|
|
106
|
-
Include the install command, supported harness tiers and migration from
|
|
107
|
-
OpenCode
|
|
108
|
-
|
|
114
|
+
Include the install command, supported harness tiers and migration from earlier releases:
|
|
115
|
+
OpenCode's primary delegates directly. Existing projects must review bindings with
|
|
116
|
+
nested delegation and any legacy `default_agent`. `--rules handoff` creates a
|
|
109
117
|
local backup and blocks `doctor` until a human-reviewed merge. Do not commit pending
|
|
110
118
|
rules while their backup exists only on the installing machine.
|
|
111
119
|
|
|
@@ -114,17 +122,18 @@ Migration steps:
|
|
|
114
122
|
1. Follow the review and private backup checklist in
|
|
115
123
|
[Migrating a legacy install](README.md#working-modes). Keep backups outside the
|
|
116
124
|
repository; never read/copy `.env` files.
|
|
117
|
-
2. `npx development-companion@1.
|
|
125
|
+
2. `npx development-companion@1.5.0 update <project>` **without `--force`**. Review the
|
|
118
126
|
managed-block diff and merge customized rules from the backup. Compare preserved
|
|
119
127
|
skills, core documents, roles and bindings with the release; merge needed updates.
|
|
120
128
|
3. Remove `"default_agent": "team-lead"` or set it to `"build"` in the existing
|
|
121
129
|
root or `.opencode/` `opencode.json(c)`, preserving other settings.
|
|
122
130
|
4. Only after backing up and reviewing the lead role and binding, regenerate them
|
|
123
|
-
|
|
124
|
-
|
|
131
|
+
if the binding still says `mode: primary` or allows subdelegation:
|
|
132
|
+
`npx development-companion@1.5.0 add role team-lead --target <project> --force`.
|
|
125
133
|
This overwrites both files without backup; merge compatible customizations afterward.
|
|
126
|
-
5. Start a new OpenCode session.
|
|
127
|
-
|
|
134
|
+
5. Start a new OpenCode session. If you need to roll back the rules, restore
|
|
135
|
+
the reviewed backups; installing an older CLI does not revert generated files.
|
|
136
|
+
6. `npx development-companion@1.5.0 doctor <project>` must pass `default agent` and
|
|
128
137
|
`delivery mode`.
|
|
129
138
|
|
|
130
139
|
Do not recommend blanket `update --force`: it deletes skill directories and overwrites
|
package/adapters/README.md
CHANGED
|
@@ -87,8 +87,9 @@ Roles are contracts in `.companion/roles/`. Bindings are thin:
|
|
|
87
87
|
|
|
88
88
|
Pi has no built-in subagents: use the role contract as a prompt template or invoke the
|
|
89
89
|
related skill.
|
|
90
|
-
The harness-native primary
|
|
91
|
-
|
|
90
|
+
The harness-native primary is the sole user interlocutor and delegates directly through
|
|
91
|
+
the process in `AGENTS.md`. The callable team lead is an advisor, not a dispatcher.
|
|
92
|
+
OpenCode does not change its default agent.
|
|
92
93
|
|
|
93
94
|
## Limitations by harness
|
|
94
95
|
|
|
@@ -37,9 +37,8 @@ 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` — callable `mode: subagent` for
|
|
41
|
-
- The 11 specialists — `mode: subagent`, launched by the native primary
|
|
42
|
-
or by the dedicated lead when it coordinates a multi-specialist task.
|
|
40
|
+
- `team-lead.md` — callable `mode: subagent` for advice on scope and sequencing.
|
|
41
|
+
- The 11 specialists — `mode: subagent`, launched directly by the native primary.
|
|
43
42
|
|
|
44
43
|
It does not set `default_agent` or write `.opencode/opencode.json`: native Build
|
|
45
44
|
retains its tools and applies the Team Lead workflow from `AGENTS.md`. Existing
|
|
@@ -49,10 +48,10 @@ the existing configuration; review and refresh the old binding, then open a new
|
|
|
49
48
|
session. Existing project rules should be merged by the harness agent, or placed
|
|
50
49
|
in a backed-up pending handoff with `init --rules handoff`.
|
|
51
50
|
|
|
52
|
-
OpenCode does not route by intent by itself. The
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
51
|
+
OpenCode does not route by intent by itself. The primary follows the routing and
|
|
52
|
+
approval gates in the coordination guide and is the sole user interlocutor. The
|
|
53
|
+
callable advisor denies code edits and shell. All generated roles deny `subagent`
|
|
54
|
+
to avoid nested routing; the native Build agent keeps its delegation tools.
|
|
56
55
|
|
|
57
56
|
Instructions alone cannot guarantee that a model followed the workflow: verify real
|
|
58
57
|
agent behavior in a new session, not only `devcomp doctor`.
|
|
@@ -92,13 +91,13 @@ OpenCode V2 uses **`permissions`** (plural), an ordered list of
|
|
|
92
91
|
`action` / `resource` / `effect` rules. The legacy OpenCode V1 shape (`permission`,
|
|
93
92
|
`permission.task`, boolean maps) is not used in new bindings.
|
|
94
93
|
|
|
95
|
-
## Team lead example
|
|
94
|
+
## Team lead advisor example
|
|
96
95
|
|
|
97
|
-
The generated binding is a callable
|
|
96
|
+
The generated binding is a callable advisor, not the native primary:
|
|
98
97
|
|
|
99
98
|
```yaml
|
|
100
99
|
---
|
|
101
|
-
description:
|
|
100
|
+
description: Advises the primary on scope and delivery sequencing.
|
|
102
101
|
mode: subagent
|
|
103
102
|
permissions:
|
|
104
103
|
- action: edit
|
|
@@ -121,18 +120,18 @@ permissions:
|
|
|
121
120
|
effect: deny
|
|
122
121
|
- action: subagent
|
|
123
122
|
resource: "*"
|
|
124
|
-
effect:
|
|
123
|
+
effect: deny
|
|
125
124
|
---
|
|
126
125
|
```
|
|
127
126
|
|
|
128
|
-
The last matching rule wins. The callable
|
|
129
|
-
|
|
127
|
+
The last matching rule wins. The callable advisor can read and write its own
|
|
128
|
+
companion notes, but it cannot launch a specialist, edit code or run shell commands.
|
|
130
129
|
The native primary keeps its tools. Specialists get
|
|
131
130
|
`{ "action": "subagent", "resource": "*", "effect": "deny" }` so they cannot spawn more
|
|
132
131
|
agents.
|
|
133
132
|
|
|
134
|
-
|
|
135
|
-
|
|
133
|
+
If an existing binding allows `subagent`, follow the migration in the main
|
|
134
|
+
README; do not enable nested delegation for the callable advisor.
|
|
136
135
|
|
|
137
136
|
## Limitations
|
|
138
137
|
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# Coordinated Delivery
|
|
2
|
+
|
|
3
|
+
## One interlocutor
|
|
4
|
+
|
|
5
|
+
The session's primary agent acts as **Coordinator** (Team Lead). Only it asks the
|
|
6
|
+
user questions, presents options, requests approvals, or communicates status and
|
|
7
|
+
closure. It keeps its native tools and owns the result. Specialists report to
|
|
8
|
+
the Coordinator, not to the user, and do not launch other agents. A callable
|
|
9
|
+
`team-lead` advises on scope or sequencing when requested; it is not the primary.
|
|
10
|
+
|
|
11
|
+
For non-trivial work, launch the applicable specialists directly with the
|
|
12
|
+
harness's native delegation tool. A role name in a plan is not a delegation.
|
|
13
|
+
For a routine, in-scope change that introduces no new decision, use the short
|
|
14
|
+
workflow. If a required role or native delegation is unavailable or denied,
|
|
15
|
+
record the limitation and what was done in single-agent mode. Never present it
|
|
16
|
+
as independent review; stop before a gate that requires independence.
|
|
17
|
+
|
|
18
|
+
## Two conversations, then authorization
|
|
19
|
+
|
|
20
|
+
1. **Operational conversation.** Agree on the problem, users, first observable
|
|
21
|
+
slice, scope and exclusions, constraints, acceptance criteria and who approves
|
|
22
|
+
them. Ask only what can change the slice. Follow with bounded, read-only
|
|
23
|
+
specialist work to prepare the technical conversation.
|
|
24
|
+
2. **Technical conversation.** Show the existing conventions and viable choices
|
|
25
|
+
with trade-offs, a recommendation, affected contracts, risks and rollback
|
|
26
|
+
where relevant. Include the verification plan and its golden and dark paths.
|
|
27
|
+
Ask for explicit approval of the scoped approach before authorizing product
|
|
28
|
+
changes, the walking skeleton, a commit, or an external action. Record in the
|
|
29
|
+
operational brief what was approved, by whom and where; link an ADR if needed.
|
|
30
|
+
|
|
31
|
+
Silence, a specialist's recommendation, an Engram entry, or approval for another
|
|
32
|
+
slice is not authorization. Until approval, continue only safe investigation and
|
|
33
|
+
planning. A rejection or material departure from the approved scope, technical
|
|
34
|
+
approach or risk stops affected work until the Coordinator gets a new approval.
|
|
35
|
+
Routine details covered by approved conventions need no separate decision.
|
|
36
|
+
Release is separate and requires the user's authorization.
|
|
37
|
+
|
|
38
|
+
## Delegate by phase
|
|
39
|
+
|
|
40
|
+
| Phase | Direct handoff from the Coordinator | Evidence returned |
|
|
41
|
+
|---|---|---|
|
|
42
|
+
| Frame | QA defines observable checks; architect proposes structural choices; security reviews new trust boundaries; UX or SRE advises when the slice needs it. | Options, risks, questions and proposed checks. |
|
|
43
|
+
| Build | Relevant implementation role from the Team Lead routing table. | Small runnable change, tests, demo, files and limitations. |
|
|
44
|
+
| Verify | QA reviews the delivered behavior independently; security reviews high-risk work and before release. | Expected vs. actual per path, findings and residual risk. |
|
|
45
|
+
| Release | SRE prepares and, once authorized, executes the release; QA and security confirm release gates. | Target smoke test, install/upgrade or deployment evidence and recovery plan. |
|
|
46
|
+
| Close | Coordinator integrates reports and owns the user-facing result. | Approvals, scope, evidence, deferred items and next step. |
|
|
47
|
+
|
|
48
|
+
Give each specialist a slice ID, role, permitted paths/actions, approved
|
|
49
|
+
decisions or read-only status, deliverable, and required checks. Use one slice
|
|
50
|
+
per writer; parallelize only independent reads or disjoint writes. Review the
|
|
51
|
+
returned evidence before accepting it or advancing a gate.
|
|
52
|
+
|
|
53
|
+
## Paths and handoffs
|
|
54
|
+
|
|
55
|
+
- **Golden paths:** the primary user or system journeys that must succeed end
|
|
56
|
+
to end. Record inputs, observable outcome and how to verify it.
|
|
57
|
+
- **Dark paths:** meaningful failures or adverse states (for example denial,
|
|
58
|
+
invalid input, timeout, partial failure or rollback). Record the trigger,
|
|
59
|
+
expected safe state or recovery, and how to verify it.
|
|
60
|
+
|
|
61
|
+
Map both to acceptance criteria. Each critical dark path needs evidence or a
|
|
62
|
+
documented gap; do not turn an untested must-pass case into a pass.
|
|
63
|
+
|
|
64
|
+
Every specialist returns: **slice · role · status** (verified, partial, blocked);
|
|
65
|
+
observations and findings with severity/impact and file or command evidence;
|
|
66
|
+
golden/dark results where applicable; unverified items; blockers or questions
|
|
67
|
+
for the Coordinator; and durable learning worth retaining. Separate observed
|
|
68
|
+
facts from recommendations. Do not publish raw logs or confidential data.
|
|
69
|
+
|
|
70
|
+
Keep the brief, approval references, and summarized handoffs under the configured
|
|
71
|
+
companion docs directory. Use distinct files if several specialists record
|
|
72
|
+
notes concurrently; the Coordinator owns the consolidated status. When Engram
|
|
73
|
+
is enabled and available, recall prior decisions relevant to the slice and
|
|
74
|
+
save or update verified, durable findings and approved decisions by project
|
|
75
|
+
and topic; do not duplicate observations. If the child cannot write, return
|
|
76
|
+
the proposed learning to the Coordinator. If persistence is unavailable,
|
|
77
|
+
disabled or unconfirmed, keep the evidence locally and report the limitation
|
|
78
|
+
without claiming it was saved. Local records remain the source of truth.
|
package/core/principles.md
CHANGED
|
@@ -15,7 +15,7 @@ and the evidence shows it works. Clever code that cannot be verified is not bett
|
|
|
15
15
|
|
|
16
16
|
**Working software is the measure of progress.** Planning is a tool, not a deliverable.
|
|
17
17
|
|
|
18
|
-
- The first commit lands in the first work block
|
|
18
|
+
- The first commit lands in the first implementation work block after approval.
|
|
19
19
|
- Every session ends with a running increment, a failing test that defines the next step, or a
|
|
20
20
|
named blocker that needs the user.
|
|
21
21
|
- A document is progress only when it unblocks a slice that is about to be built.
|
|
@@ -167,8 +167,8 @@ State what you know, what you assume, and what you could not verify. Hidden
|
|
|
167
167
|
uncertainty becomes someone else's incident.
|
|
168
168
|
|
|
169
169
|
**In practice:** report evidence, open questions, and residual risk. Record
|
|
170
|
-
|
|
171
|
-
|
|
170
|
+
technical decisions with context and consequences. Get user approval for new
|
|
171
|
+
technical choices in the scoped approach before implementing them.
|
|
172
172
|
|
|
173
173
|
**Red flags:** confident claims without checks; silent scope changes; decisions
|
|
174
174
|
buried in chat instead of documented.
|
package/core/process.md
CHANGED
|
@@ -17,7 +17,7 @@ waterfall. Planning is a tool that unblocks the next slice; when it stops doing
|
|
|
17
17
|
|
|
18
18
|
> **A phase is complete when code runs, not when a document exists.**
|
|
19
19
|
|
|
20
|
-
- The first commit must land in the first
|
|
20
|
+
- The first commit must land in the first implementation block after approval.
|
|
21
21
|
- Every session ends with one of: a running increment, a failing test that defines the next
|
|
22
22
|
step, or a named blocker that needs the user.
|
|
23
23
|
- A planning artifact is written **just in time**, only as deep as the next slice needs.
|
|
@@ -47,7 +47,9 @@ in roles and skills.
|
|
|
47
47
|
|
|
48
48
|
## Phase 1 — Frame (30–60 minutes, one page)
|
|
49
49
|
|
|
50
|
-
**Owner:**
|
|
50
|
+
**Owner:** the primary agent acting as Coordinator. **Participant:** the user.
|
|
51
|
+
Follow `core/guidelines/coordination.md`: the Coordinator conducts both
|
|
52
|
+
conversations, and specialists return technical observations to the Coordinator.
|
|
51
53
|
|
|
52
54
|
Answer only what can change the first slice:
|
|
53
55
|
|
|
@@ -56,15 +58,16 @@ Answer only what can change the first slice:
|
|
|
56
58
|
3. What constraints could invalidate that slice: platform, data, auth, privacy, performance,
|
|
57
59
|
third parties, deadline?
|
|
58
60
|
4. What is explicitly out of scope for this slice?
|
|
59
|
-
5. Which
|
|
61
|
+
5. Which technical choices need approval now, and what alternatives are viable?
|
|
60
62
|
|
|
61
63
|
Everything else is deferred. Stack details, full schemas, complete UX, and exhaustive test
|
|
62
64
|
matrices are decided when the slice needs them.
|
|
63
65
|
|
|
64
66
|
**Artifact:** `.companion/local/01-operational-brief.md`, maximum one page.
|
|
65
67
|
|
|
66
|
-
**Gate:** the user
|
|
67
|
-
|
|
68
|
+
**Gate:** the user explicitly approves the first slice, its acceptance criteria,
|
|
69
|
+
and the technical approach after seeing the trade-offs and golden/dark paths.
|
|
70
|
+
No implementation starts while approval is missing.
|
|
68
71
|
|
|
69
72
|
**Timebox:** if the brief is not done in one work block, cut it to the five questions above.
|
|
70
73
|
|
|
@@ -169,7 +172,7 @@ first commit, cut it or defer it.
|
|
|
169
172
|
| Change | Process |
|
|
170
173
|
|---|---|
|
|
171
174
|
| Typo, docs, one-line fix | Recon → change → check → report |
|
|
172
|
-
| Feature in one layer |
|
|
175
|
+
| Feature in one layer | Scoped conversations and approval → implement → tests → review |
|
|
173
176
|
| Cross-layer, data, auth, public contract | Frame → skeleton or thin slice → tests → independent security/QA |
|
|
174
177
|
| New project | Frame (1 page) → walking skeleton → slice loop |
|
|
175
178
|
| Incident | Stabilize → diagnose → fix → regression test → short postmortem |
|
package/core/quality-gates.md
CHANGED
|
@@ -90,9 +90,9 @@ For a new project or a major change, progress is gated by running code, not by d
|
|
|
90
90
|
|
|
91
91
|
| Gate | Evidence |
|
|
92
92
|
|---|---|
|
|
93
|
-
| Frame |
|
|
93
|
+
| Frame | Operational and technical conversations; user explicitly approves scope, criteria and approach; golden/dark paths identified. |
|
|
94
94
|
| Walking skeleton | The end-to-end path runs with fakes; one command; one test; a commit. |
|
|
95
|
-
| Slice |
|
|
95
|
+
| Slice | Golden and critical dark paths checked; specialist evidence and gaps recorded; scoped diff, demo and commit. |
|
|
96
96
|
| Release | No open critical/high findings; must-pass checks green; install/upgrade verified in the target. |
|
|
97
97
|
|
|
98
98
|
A planning artifact is not a gate. It is a living note that unblocks a slice. See
|
package/core/roles/architect.md
CHANGED
|
@@ -4,8 +4,8 @@
|
|
|
4
4
|
|
|
5
5
|
## Mission
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
evolvable.
|
|
7
|
+
Propose boundaries and trade-offs that make the system correct, understandable, and
|
|
8
|
+
evolvable. Return recommendations to the Coordinator for user approval.
|
|
9
9
|
|
|
10
10
|
## Use when
|
|
11
11
|
|
|
@@ -43,12 +43,13 @@ Do not use for routine implementation work that already has a clear design.
|
|
|
43
43
|
3. **List options** — include the simplest option and the "do nothing" option.
|
|
44
44
|
4. **Evaluate** — correctness, complexity, coupling, reversibility, security,
|
|
45
45
|
performance, accessibility, cost, operability.
|
|
46
|
-
5. **
|
|
46
|
+
5. **Recommend** — explain why and what the project gives up. Leave the choice pending
|
|
47
|
+
until the Coordinator records the user's approval.
|
|
47
48
|
6. **Define invariants** — what must always hold, and where it is enforced.
|
|
48
49
|
7. **Design failure modes** — timeouts, retries, partial failure, invalid input,
|
|
49
50
|
authorization denial, migration failure.
|
|
50
51
|
8. **Plan verification** — how the design will be tested and observed.
|
|
51
|
-
9. **Record** —
|
|
52
|
+
9. **Record** — note the recommendation in the configured docs directory or ADR log.
|
|
52
53
|
|
|
53
54
|
## Boundaries
|
|
54
55
|
|
|
@@ -63,7 +64,7 @@ Do not use for routine implementation work that already has a clear design.
|
|
|
63
64
|
## Handoff
|
|
64
65
|
|
|
65
66
|
```markdown
|
|
66
|
-
**
|
|
67
|
+
**Recommended decision and approval status:** ...
|
|
67
68
|
**Context:** ...
|
|
68
69
|
**Options considered:** ...
|
|
69
70
|
**Consequences:** ...
|
|
@@ -37,8 +37,8 @@ works and that the important ways it could break are covered.
|
|
|
37
37
|
1. **Map the risk** — rank the flows by impact and likelihood of failure.
|
|
38
38
|
2. **Cover the boundaries** — empty, null, minimum, maximum, malformed, oversized,
|
|
39
39
|
duplicate, concurrent, unauthorized, offline, timeout, partial failure.
|
|
40
|
-
3. **
|
|
41
|
-
4. **Check
|
|
40
|
+
3. **Check golden paths** — prove the primary observable journeys end to end.
|
|
41
|
+
4. **Check dark paths** — invalid input, denied access, failed dependency,
|
|
42
42
|
retry exhaustion, rollback.
|
|
43
43
|
5. **Check state transitions** — double submit, back/forward, refresh, stale cache,
|
|
44
44
|
race conditions, idempotency.
|
|
@@ -64,6 +64,7 @@ works and that the important ways it could break are covered.
|
|
|
64
64
|
**Test plan:** risk → level → cases
|
|
65
65
|
**Automated:** files and commands
|
|
66
66
|
**Manual:** steps and observed result
|
|
67
|
+
**Golden/dark paths:** acceptance criterion, expected vs. actual, evidence
|
|
67
68
|
**Defects:** reproduction, expected vs actual, severity
|
|
68
69
|
**Residual risk:** not covered and why
|
|
69
70
|
```
|
package/core/roles/team-lead.md
CHANGED
|
@@ -6,8 +6,10 @@
|
|
|
6
6
|
|
|
7
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. The native primary agent
|
|
10
|
-
|
|
9
|
+
for **code that lands**, not for the volume of documents produced. The native primary agent
|
|
10
|
+
acts as Coordinator and is the sole user interlocutor. Apply
|
|
11
|
+
`core/guidelines/coordination.md` (installed under `.companion/core/`). A callable
|
|
12
|
+
team-lead specialist only advises the Coordinator and never delegates.
|
|
11
13
|
|
|
12
14
|
## Use when
|
|
13
15
|
|
|
@@ -34,8 +36,8 @@ Do not use for a one-file fix or a routine review; handle those directly.
|
|
|
34
36
|
|
|
35
37
|
## Operating checklist
|
|
36
38
|
|
|
37
|
-
1. **Frame (≤ 1 work block)** —
|
|
38
|
-
|
|
39
|
+
1. **Frame (≤ 1 work block)** — lead the operational conversation, launch relevant specialists
|
|
40
|
+
directly, present the technical options, and record explicit user approval before build.
|
|
39
41
|
2. **Prove the path** — delegate a walking skeleton with fakes where needed. It must run with
|
|
40
42
|
one command and have one test. Commit.
|
|
41
43
|
3. **Slice loop** — pick the highest-risk or highest-value slice; one writer per slice; require
|
|
@@ -70,20 +72,18 @@ is inventory.
|
|
|
70
72
|
| Native Linux | `desktop-linux-engineer` |
|
|
71
73
|
| Cross-platform core | `multiplatform-engineer` |
|
|
72
74
|
| Deploy, observability, secrets | `sre-engineer` |
|
|
73
|
-
| No specialist fits |
|
|
75
|
+
| No specialist fits | Coordinator uses a bounded native generalist or reports the gap |
|
|
74
76
|
|
|
75
77
|
## Boundaries
|
|
76
78
|
|
|
77
|
-
- As a
|
|
78
|
-
run tests, or run shell commands.
|
|
79
|
-
|
|
80
|
-
- Do not edit code. Your only writable paths are `.companion/local/**` and
|
|
81
|
-
`docs/companion/**`.
|
|
79
|
+
- As a callable advisor, do not speak to the user, launch subagents, design the architecture,
|
|
80
|
+
implement features, run tests, or run shell commands. If asked to take notes, write only
|
|
81
|
+
to the configured companion docs directory. Return questions and observations to the Coordinator.
|
|
82
82
|
- Do not claim a delegation you did not perform. A delegation is real only if a native
|
|
83
83
|
delegation tool launched another agent; otherwise describe the work as a single-agent role
|
|
84
84
|
switch or manual handoff.
|
|
85
|
-
- **Do not spend more than one work block producing planning artifacts before
|
|
86
|
-
|
|
85
|
+
- **Do not spend more than one work block producing planning artifacts before asking for
|
|
86
|
+
approval.**
|
|
87
87
|
- **Do not accept a child that returns only a document when code was requested.** Send it back
|
|
88
88
|
with a bounded instruction to implement.
|
|
89
89
|
- **Stop the line:** if two consecutive delegations produce no running code, stop and tell the
|
|
@@ -94,19 +94,21 @@ is inventory.
|
|
|
94
94
|
|
|
95
95
|
## Handoff
|
|
96
96
|
|
|
97
|
-
|
|
97
|
+
As Coordinator, launch applicable native subagents with:
|
|
98
98
|
|
|
99
99
|
```markdown
|
|
100
100
|
**Role:** architect | cybersecurity | qa | frontend | backend | mobile | platform | sre
|
|
101
101
|
**Goal:** the smallest shippable outcome
|
|
102
102
|
**Context:** files, decisions, constraints
|
|
103
|
-
**
|
|
103
|
+
**Authorization:** read-only or approved decisions, permitted paths and actions
|
|
104
|
+
**Deliverable:** recommendation, implementation or verification, depending on phase
|
|
104
105
|
**Slice:** what must work end-to-end when this returns
|
|
105
106
|
**Verification:** command to run and output to return
|
|
107
|
+
**Return to Coordinator:** findings, evidence, golden/dark results, gaps and proposed durable learning
|
|
106
108
|
**Do not:** out-of-scope work, files to avoid, planning expansion
|
|
107
109
|
```
|
|
108
110
|
|
|
109
111
|
After the child returns, verify the evidence and either accept it or send a follow-up. Reject
|
|
110
|
-
"done" without a
|
|
112
|
+
an implementation reported as "done" without a test or a reproducible demo.
|
|
111
113
|
|
|
112
114
|
Close with the completion format in the `development-workflow` skill.
|