development-companion 1.6.0 → 1.8.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 +82 -0
- package/README.md +133 -57
- package/RELEASE.md +49 -32
- package/adapters/README.md +15 -4
- package/adapters/opencode/README.md +116 -24
- package/adapters/opencode/plugin/devcomp/gates.mjs +688 -0
- package/adapters/opencode/plugin/devcomp/index.ts +603 -0
- package/core/guidelines/coordination.md +138 -4
- package/core/process.md +141 -7
- package/core/quality-gates.md +41 -1
- package/core/roles/README.md +4 -1
- package/core/roles/backend-engineer.md +10 -0
- package/core/roles/coordinator.md +171 -0
- package/core/roles/desktop-linux-engineer.md +10 -0
- package/core/roles/desktop-macos-engineer.md +10 -0
- package/core/roles/desktop-windows-engineer.md +10 -0
- package/core/roles/frontend-engineer.md +10 -0
- package/core/roles/mobile-engineer.md +10 -0
- package/core/roles/multiplatform-engineer.md +10 -0
- package/core/roles/sre-engineer.md +10 -0
- package/core/workflow.md +62 -9
- package/package.json +1 -1
- package/skills/delivery-orchestration/SKILL.md +58 -3
- package/skills/development-workflow/SKILL.md +44 -8
- package/skills/test-strategy/SKILL.md +12 -0
- package/src/cli.mjs +211 -19
- package/src/content.mjs +16 -0
- package/src/install.mjs +397 -44
- package/templates/artifacts/01-operational-brief.md +14 -1
- package/templates/artifacts/11-feature-plan.md +83 -0
- package/templates/artifacts/README.md +8 -5
- package/templates/rules/AGENTS.block.md +117 -8
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
## One interlocutor
|
|
4
4
|
|
|
5
|
-
The session's primary agent acts as **Coordinator
|
|
5
|
+
The session's primary agent acts as **Coordinator**. Only it asks the
|
|
6
6
|
user questions, presents options, requests approvals, or communicates status and
|
|
7
7
|
closure. It keeps its native tools and owns the result. Specialists report to
|
|
8
8
|
the Coordinator, not to the user, and do not launch other agents. A callable
|
|
@@ -15,6 +15,24 @@ workflow. If a required role or native delegation is unavailable or denied,
|
|
|
15
15
|
record the limitation and what was done in single-agent mode. Never present it
|
|
16
16
|
as independent review; stop before a gate that requires independence.
|
|
17
17
|
|
|
18
|
+
## Working modes
|
|
19
|
+
|
|
20
|
+
Pick the lightest mode that still protects the user's data and the approved outcome.
|
|
21
|
+
|
|
22
|
+
| Mode | Agents | Minimum artifact | Authorization |
|
|
23
|
+
|---|---|---|---|
|
|
24
|
+
| **Query** | Coordinator only | None | None |
|
|
25
|
+
| **Small change** | One writer for the area | Short operational brief with `Aprobado:` and `Scope:` | Natural language + delegation permission |
|
|
26
|
+
| **Feature** | Read-only planning + writers | Feature plan: scope, development plan, test plan, evidence, risks, rollback | User-approved plan |
|
|
27
|
+
| **Bug** | One writer (+ QA if critical) | Reproduction + failing test + fix + regression | Short brief with Aprobado/Scope |
|
|
28
|
+
| **Refactor** | One writer | Baseline tests + reversible steps | Short brief with Aprobado/Scope |
|
|
29
|
+
| **Incident** | Coordinator + SRE/security | Stabilize first; postmortem after | Coordinator talks to the user |
|
|
30
|
+
|
|
31
|
+
A query is answered directly, without launching a specialist. A small change uses one writer,
|
|
32
|
+
the short operational brief from `templates/artifacts/01-operational-brief.md` (problem, scope,
|
|
33
|
+
test, evidence, `Aprobado:`, `Scope:`), and no chain of roles. A feature always gets a visible
|
|
34
|
+
plan. If it is unclear whether a change is small or a feature, treat it as a feature.
|
|
35
|
+
|
|
18
36
|
## Two conversations, then authorization
|
|
19
37
|
|
|
20
38
|
1. **Operational conversation.** Agree on the problem, users, first observable
|
|
@@ -35,12 +53,42 @@ approach or risk stops affected work until the Coordinator gets a new approval.
|
|
|
35
53
|
Routine details covered by approved conventions need no separate decision.
|
|
36
54
|
Release is separate and requires the user's authorization.
|
|
37
55
|
|
|
56
|
+
### Feature intake
|
|
57
|
+
|
|
58
|
+
For a feature, ask only what changes the plan: problem and users, observable
|
|
59
|
+
outcome, what enters and what does not, platforms and constraints, requested
|
|
60
|
+
behavior and what must not change, data/privacy/security/permissions and
|
|
61
|
+
accessibility, acceptance criteria and the evidence the user wants to see, time
|
|
62
|
+
and dependencies, and the golden and dark cases. Defer anything that cannot
|
|
63
|
+
change the plan.
|
|
64
|
+
|
|
65
|
+
### Visible feature plan
|
|
66
|
+
|
|
67
|
+
Present the plan to the user before implementation. It contains the scope and
|
|
68
|
+
non-goals, a top-level `Scope:` that bounds every step, approach and trade-offs,
|
|
69
|
+
the **development plan** (steps, owner agent, dependencies, parallelism,
|
|
70
|
+
`Scope` globs inside the top-level scope, expected evidence), the **test plan**
|
|
71
|
+
(golden paths, critical dark paths, edge cases, evidence per case), the
|
|
72
|
+
end-to-end path that closes the feature, risks and rollback. Use the feature
|
|
73
|
+
plan template in the Development Companion package (`templates/artifacts/11-feature-plan.md`).
|
|
74
|
+
|
|
75
|
+
The user iterates in natural language. Observations revise the plan and require
|
|
76
|
+
a new approval. When the user approves, record an affirmative `Aprobado:` with
|
|
77
|
+
their words and the date in the plan. Do not write an approval the user did not
|
|
78
|
+
give, and do not treat a file as approval: recording `Aprobado:` does not replace
|
|
79
|
+
the user's session mark and never authorizes a destructive operation. The runtime
|
|
80
|
+
binds the session mark to the approved plan path and content; editing the plan or
|
|
81
|
+
using a different plan in the same session revokes it until the user approves again.
|
|
82
|
+
|
|
83
|
+
After approval, the plan is the execution contract (see **Goal continuity**).
|
|
84
|
+
A feature plan path is passed to every writer as `Plan: <path>`.
|
|
85
|
+
|
|
38
86
|
## Delegate by phase
|
|
39
87
|
|
|
40
88
|
| Phase | Direct handoff from the Coordinator | Evidence returned |
|
|
41
89
|
|---|---|---|
|
|
42
90
|
| 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
|
|
91
|
+
| Build | Relevant implementation role from the Coordinator routing table; the prompt carries `Plan:` and `Scope:`. | Small runnable change, tests, demo, files and limitations. |
|
|
44
92
|
| 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
93
|
| 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
94
|
| Close | Coordinator integrates reports and owns the user-facing result. | Approvals, scope, evidence, deferred items and next step. |
|
|
@@ -50,6 +98,90 @@ decisions or read-only status, deliverable, and required checks. Use one slice
|
|
|
50
98
|
per writer; parallelize only independent reads or disjoint writes. Review the
|
|
51
99
|
returned evidence before accepting it or advancing a gate.
|
|
52
100
|
|
|
101
|
+
### Delegation contract
|
|
102
|
+
|
|
103
|
+
Every implementation delegation states, in the prompt, each field on its own line:
|
|
104
|
+
|
|
105
|
+
```text
|
|
106
|
+
Plan: <path to the approved plan>
|
|
107
|
+
Scope: <glob>, <glob>, <path>
|
|
108
|
+
Step: <number and name from the development plan>
|
|
109
|
+
Acceptance: <observable criteria for this step>
|
|
110
|
+
Evidence required: <command/test/demo the specialist must return>
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
The runtime plan gate rejects an implementation delegation without `Plan:` and
|
|
114
|
+
`Scope:`, a missing plan, a plan outside the workspace, a plan shorter than 200
|
|
115
|
+
characters, a plan without a top-level `Scope:`, a plan without
|
|
116
|
+
Test/Verification/Evidence content, a missing or non-affirmative `Aprobado:`, or a
|
|
117
|
+
delegation `Scope:` that exceeds the plan. A plan with a development table also
|
|
118
|
+
requires `Step:` and a row whose Step and declared agent match. The scope gate rejects
|
|
119
|
+
`edit`, `write`, or `patch` outside the `Scope` globs. Read-only roles may write their
|
|
120
|
+
own reports under the planning directory (`.companion/local/**`, `plannification/**`,
|
|
121
|
+
`docs/companion/**`); they cannot rewrite the bound approved plan. Paths
|
|
122
|
+
are resolved against the session's project root and matched against the Development
|
|
123
|
+
Companion workspace root; in a meta-repo include the child prefix (for example
|
|
124
|
+
`repos/api/src/**`). Shell writes are a documented residual risk; the diff review
|
|
125
|
+
and the destructive guard are the other layers.
|
|
126
|
+
|
|
127
|
+
After the plan is approved, do not ask the user to confirm each subagent. The
|
|
128
|
+
user's approval and the runtime session mark are the authorization; the native
|
|
129
|
+
delegation prompt remains the fallback when the runtime cannot confirm approval.
|
|
130
|
+
An observation or rejection message revokes the session mark until the user
|
|
131
|
+
approves again. The mark is bound to the first approved plan and its content; an
|
|
132
|
+
unrelated approval can re-bind it. `--auto` or a non-interactive run bypasses the
|
|
133
|
+
session mark, the revision guard and the `ask`; do not use it for destructive or
|
|
134
|
+
approval-required work.
|
|
135
|
+
|
|
136
|
+
## Goal continuity
|
|
137
|
+
|
|
138
|
+
The approved plan is the contract. After approval:
|
|
139
|
+
|
|
140
|
+
- Do not ask "shall I continue?" between steps or request confirmation for each subagent.
|
|
141
|
+
- Receive each specialist's status, evidence, gaps and blockers; verify, integrate and decide
|
|
142
|
+
inside the approved scope.
|
|
143
|
+
- If a step fails, retry or adjust inside the plan. If the adjustment changes scope,
|
|
144
|
+
acceptance criteria or the technical approach, revise the plan with the user.
|
|
145
|
+
- Do not close the feature until the agreed end-to-end path runs and every golden and critical
|
|
146
|
+
dark case has evidence or a declared gap.
|
|
147
|
+
- Pause only for a catastrophic or irreversible operation, data loss, critical security, a
|
|
148
|
+
requirement conflict, or an invalid plan.
|
|
149
|
+
|
|
150
|
+
## Scope lock
|
|
151
|
+
|
|
152
|
+
A specialist executes only the assigned step and touches only files matching `Scope`. It
|
|
153
|
+
reports out-of-scope findings (for example an unrequested accessibility change, a broken test,
|
|
154
|
+
or a missing permission) without implementing them. The Coordinator decides whether to extend
|
|
155
|
+
the plan and obtains a new approval when the scope changes.
|
|
156
|
+
|
|
157
|
+
The TalkBack case is the rule, not an exception: enabling an unrequested capability because it
|
|
158
|
+
looks beneficial is a scope violation, even when the change is technically correct.
|
|
159
|
+
|
|
160
|
+
## Destructive operations
|
|
161
|
+
|
|
162
|
+
File deletion, database `DROP`/`TRUNCATE`/`DELETE` without `WHERE`, volume or infrastructure
|
|
163
|
+
destruction (`docker volume rm`, `docker compose down -v`, `kubectl delete`,
|
|
164
|
+
`terraform destroy`, cloud storage removal, `rsync --delete`), and any operation the plan marks
|
|
165
|
+
as destructive require explicit user authorization, separate from the plan approval.
|
|
166
|
+
|
|
167
|
+
1. The specialist stops and reports the operation, why it is needed, its blast radius, and the
|
|
168
|
+
available backup or rollback.
|
|
169
|
+
2. The Coordinator asks the user for explicit authorization.
|
|
170
|
+
3. The runtime forces the permission prompt for known destructive patterns, even when the
|
|
171
|
+
session is approved and even when an "always" approval exists; shell writes remain a residual
|
|
172
|
+
risk and the message never prints secrets.
|
|
173
|
+
4. Without authorization, do not execute; find a safe alternative.
|
|
174
|
+
|
|
175
|
+
The runtime pattern list is best effort. The specialist's report and the Coordinator's review
|
|
176
|
+
are the other layer; neither replaces the user's decision.
|
|
177
|
+
|
|
178
|
+
## Escalation
|
|
179
|
+
|
|
180
|
+
Escalate only a catastrophic or irreversible operation, data loss, critical security, a
|
|
181
|
+
requirement conflict, or an invalidated plan. Routine implementation decisions, choices inside
|
|
182
|
+
the approved scope, retries and test details already covered by the plan are the Coordinator's
|
|
183
|
+
job: decide, record the decision, and continue.
|
|
184
|
+
|
|
53
185
|
## Paths and handoffs
|
|
54
186
|
|
|
55
187
|
- **Golden paths:** the primary user or system journeys that must succeed end
|
|
@@ -64,8 +196,10 @@ documented gap; do not turn an untested must-pass case into a pass.
|
|
|
64
196
|
Every specialist returns: **slice · role · status** (verified, partial, blocked);
|
|
65
197
|
observations and findings with severity/impact and file or command evidence;
|
|
66
198
|
golden/dark results where applicable; unverified items; blockers or questions
|
|
67
|
-
for the Coordinator;
|
|
68
|
-
|
|
199
|
+
for the Coordinator; a scope confirmation (files changed inside `Scope`, and
|
|
200
|
+
out-of-scope findings reported, not implemented); and durable learning worth
|
|
201
|
+
retaining. Separate observed facts from recommendations. Do not publish raw
|
|
202
|
+
logs or confidential data.
|
|
69
203
|
|
|
70
204
|
Keep the brief, approval references, and summarized handoffs under the configured
|
|
71
205
|
companion docs directory. Use distinct files if several specialists record
|
package/core/process.md
CHANGED
|
@@ -23,6 +23,24 @@ waterfall. Planning is a tool that unblocks the next slice; when it stops doing
|
|
|
23
23
|
- A planning artifact is written **just in time**, only as deep as the next slice needs.
|
|
24
24
|
- A document that does not unblock code is deferred, not expanded.
|
|
25
25
|
|
|
26
|
+
## Working modes
|
|
27
|
+
|
|
28
|
+
Pick the lightest mode that still protects the user's data and the approved outcome.
|
|
29
|
+
|
|
30
|
+
| Mode | Use for | Minimum artifact | Agents | Authorization |
|
|
31
|
+
|---|---|---|---|---|
|
|
32
|
+
| **Query** | A question, explanation, or read-only investigation | None | Coordinator only | None |
|
|
33
|
+
| **Small change** | A confined fix or adjustment with low risk | Short operational brief with `Aprobado:` and `Scope:` | One writer for the area | Natural language + delegation permission |
|
|
34
|
+
| **Feature** | A new capability or a behavior change | Feature plan: scope, options, development plan, test plan, evidence, risks, rollback | Read-only planning + writers | User-approved plan |
|
|
35
|
+
| **Bug** | A reproducible failure | Reproduction, a failing test, the fix, a regression test | One writer (+ QA if critical) | Short brief with Aprobado/Scope |
|
|
36
|
+
| **Refactor** | Behavior must not change | Baseline tests and reversible steps | One writer | Short brief with Aprobado/Scope |
|
|
37
|
+
| **Incident** | Production down, data loss, or a security event | Stabilize first; short postmortem after | Coordinator + SRE/security | Coordinator talks to the user |
|
|
38
|
+
|
|
39
|
+
A **query** is answered directly: do not launch specialists to read a file or explain code.
|
|
40
|
+
A **small change** does not need a feature plan or a chain of roles: one writer, one short
|
|
41
|
+
plan, tests, evidence. A **feature** always needs a visible plan before implementation. If it
|
|
42
|
+
is unclear whether a change is small or a feature, treat it as a feature.
|
|
43
|
+
|
|
26
44
|
## Phase 0 — Bootstrap
|
|
27
45
|
|
|
28
46
|
**Owner:** native harness agent, assisted by the CLI.
|
|
@@ -71,9 +89,56 @@ No implementation starts while approval is missing.
|
|
|
71
89
|
|
|
72
90
|
**Timebox:** if the brief is not done in one work block, cut it to the five questions above.
|
|
73
91
|
|
|
92
|
+
## Feature intake
|
|
93
|
+
|
|
94
|
+
Before writing a feature plan, the Coordinator asks only what can change the scope:
|
|
95
|
+
|
|
96
|
+
1. Problem, users, and the observable result.
|
|
97
|
+
2. What enters and what explicitly does not.
|
|
98
|
+
3. Platforms, devices, environments, and limits.
|
|
99
|
+
4. Expected behavior/UX and what must not change.
|
|
100
|
+
5. Data, privacy, security, permissions, and accessibility requested explicitly.
|
|
101
|
+
6. Acceptance criteria and the evidence the user wants to see.
|
|
102
|
+
7. Time constraints, dependencies, and risks.
|
|
103
|
+
8. Golden and dark cases that must be covered.
|
|
104
|
+
|
|
105
|
+
Do not turn intake into a second discovery phase. If an answer cannot change the plan, defer
|
|
106
|
+
it. If the user cannot answer, state the assumption and ask them to confirm it with the plan.
|
|
107
|
+
|
|
108
|
+
## Feature plan
|
|
109
|
+
|
|
110
|
+
A feature plan is the execution contract and the user sees it before code. It contains:
|
|
111
|
+
|
|
112
|
+
- Problem, observable outcome, scope, non-goals, and constraints.
|
|
113
|
+
- A top-level `Scope:` that bounds every step and every delegation.
|
|
114
|
+
- Viable options with trade-offs and a recommendation; affected contracts.
|
|
115
|
+
- **Development plan:** steps, owner agent, dependencies, what can run in parallel, the
|
|
116
|
+
`Scope` globs of each step (inside the top-level `Scope`), and the expected evidence.
|
|
117
|
+
- **Test plan:** golden paths, critical dark paths, edge cases, levels, and evidence per case.
|
|
118
|
+
- A Test, Verification, or Evidence section; the runtime rejects a plan without one.
|
|
119
|
+
- Risks, rollback, and the end-to-end path that closes the feature.
|
|
120
|
+
- `Aprobado:` with an affirmative decision, the user's words, and the date.
|
|
121
|
+
|
|
122
|
+
Template (Development Companion package): `templates/artifacts/11-feature-plan.md`. Store it in
|
|
123
|
+
the configured planning directory (`.companion/local/`, `plannification/`, or `docs/companion/`
|
|
124
|
+
when tracked) and link it in the frame when both exist.
|
|
125
|
+
|
|
126
|
+
The runtime rejects a plan shorter than 200 characters, without a top-level `Scope:`, or
|
|
127
|
+
without Test/Verification/Evidence content; a plan with only `Aprobado:` and `Scope:` is not a
|
|
128
|
+
plan. A plan with a development table requires `Step:` and a matching Step/agent row.
|
|
129
|
+
|
|
130
|
+
A small change uses the short operational brief
|
|
131
|
+
(`templates/artifacts/01-operational-brief.md`) with its own `Aprobado:` and `Scope:`, one
|
|
132
|
+
writer, and one test; it does not need a feature plan or a chain of roles.
|
|
133
|
+
|
|
134
|
+
The user iterates the plan in natural language. Observations change the plan and require a new
|
|
135
|
+
approval; silence is not approval. The approved plan is also the path the Coordinator passes to
|
|
136
|
+
every implementation delegation as `Plan: <path>`. A delegation `Scope:` must be equal to or
|
|
137
|
+
narrower than the plan's `Scope:`; the runtime rejects a broader scope.
|
|
138
|
+
|
|
74
139
|
## Phase 2 — Walking skeleton
|
|
75
140
|
|
|
76
|
-
**Owner:** specialists. **Coordinator:**
|
|
141
|
+
**Owner:** specialists. **Coordinator:** the Coordinator agent.
|
|
77
142
|
|
|
78
143
|
Build the thinnest path that goes from the user's entry point to a visible result:
|
|
79
144
|
|
|
@@ -87,7 +152,7 @@ exists.
|
|
|
87
152
|
|
|
88
153
|
## Phase 3 — Slice loop
|
|
89
154
|
|
|
90
|
-
**Owner:** specialists. **Coordinator:**
|
|
155
|
+
**Owner:** specialists. **Coordinator:** the Coordinator agent.
|
|
91
156
|
|
|
92
157
|
Pick the **highest-risk or highest-value slice** and finish it before starting another.
|
|
93
158
|
|
|
@@ -105,6 +170,66 @@ slices that touch disjoint files.
|
|
|
105
170
|
|
|
106
171
|
**Gate:** acceptance criteria are covered by evidence; the diff is scoped; the commit exists.
|
|
107
172
|
|
|
173
|
+
## Goal continuity
|
|
174
|
+
|
|
175
|
+
After the plan is approved, the plan is the execution contract:
|
|
176
|
+
|
|
177
|
+
- Do not ask "shall I continue?" between steps or request confirmation for every subagent.
|
|
178
|
+
Present the plan once, get approval, then execute.
|
|
179
|
+
- Each specialist returns status, evidence, gaps, and blockers. The Coordinator verifies,
|
|
180
|
+
integrates, and decides inside the approved scope.
|
|
181
|
+
- If a step fails, retry or adjust inside the plan. If the adjustment changes scope,
|
|
182
|
+
acceptance criteria, or the technical approach, revise the plan with the user.
|
|
183
|
+
- The feature is not closed until the agreed end-to-end path works and the evidence for every
|
|
184
|
+
golden and critical dark path is attached. A set of green slices is not a finished feature.
|
|
185
|
+
- The only legitimate pause after approval is serious: a destructive or irreversible
|
|
186
|
+
operation, data loss, a critical security issue, a requirement conflict, or an invalid plan.
|
|
187
|
+
|
|
188
|
+
## Scope lock
|
|
189
|
+
|
|
190
|
+
Every delegation carries the approved `Plan:` path and `Scope:` globs. The specialist:
|
|
191
|
+
|
|
192
|
+
1. Reads the plan and executes only the assigned step.
|
|
193
|
+
2. Touches only files that match `Scope`. If the step needs another file, stop and report.
|
|
194
|
+
3. Reports out-of-scope findings (a missing permission, a broken test, an unrequested feature)
|
|
195
|
+
without implementing them. The Coordinator decides whether to extend the plan.
|
|
196
|
+
4. Never expands the scope silently, even when the change looks small or obviously useful.
|
|
197
|
+
|
|
198
|
+
Scope globs must name concrete paths; the Coordinator resolves ambiguity before approval. One
|
|
199
|
+
writer per slice, and parallel writers get disjoint scopes.
|
|
200
|
+
|
|
201
|
+
## Destructive operations
|
|
202
|
+
|
|
203
|
+
These require the user's explicit authorization, separate from the plan approval. They include
|
|
204
|
+
file deletion (`rm`, `rmdir`, `unlink`, `shred`, `truncate`, `git clean`, `git reset --hard`,
|
|
205
|
+
`git checkout -- .`, destructive `git restore`), database destruction (`DROP`, `TRUNCATE`,
|
|
206
|
+
`DELETE` without `WHERE`, `dropdb`, `dropDatabase`, `FLUSHALL`/`FLUSHDB`, `flyway clean`,
|
|
207
|
+
`prisma migrate reset`, `alembic downgrade base`), and infrastructure/data tools
|
|
208
|
+
(`docker volume rm`, `docker compose down -v`, `kubectl delete`, `terraform destroy`,
|
|
209
|
+
`aws s3 rm`, `gsutil rm`, `mc rm`, `rclone delete`, `rsync --delete`). Any operation the plan
|
|
210
|
+
marks as destructive also qualifies.
|
|
211
|
+
|
|
212
|
+
Mandatory flow:
|
|
213
|
+
|
|
214
|
+
1. The specialist detects the need and **stops**.
|
|
215
|
+
2. It reports the operation, why it is needed, its blast radius, and the available backup or
|
|
216
|
+
rollback.
|
|
217
|
+
3. The Coordinator asks the user for explicit authorization.
|
|
218
|
+
4. Only then is the operation executed. The runtime still forces the permission prompt for
|
|
219
|
+
known destructive patterns, even when the session is approved and even when an "always"
|
|
220
|
+
approval exists. Shell writes remain a residual risk and the message never prints secrets.
|
|
221
|
+
5. Without authorization, do not execute; find a safe alternative.
|
|
222
|
+
|
|
223
|
+
Plan approval never authorizes a destructive operation. The runtime pattern list is best effort;
|
|
224
|
+
the specialist's report and the Coordinator's review are the other layer.
|
|
225
|
+
|
|
226
|
+
## Escalation
|
|
227
|
+
|
|
228
|
+
The Coordinator escalates to the user only for a catastrophic or irreversible operation, data
|
|
229
|
+
loss, critical security, a conflict between requirements, or an invalidated plan. Routine
|
|
230
|
+
implementation decisions, file choices inside the approved scope, test strategy already covered
|
|
231
|
+
by the plan, and retries are the Coordinator's job: decide, record the decision, and continue.
|
|
232
|
+
|
|
108
233
|
## Phase 4 — Verify
|
|
109
234
|
|
|
110
235
|
**Owner:** Cybersecurity Engineer and QA Engineer. **Participant:** implementers.
|
|
@@ -114,6 +239,8 @@ Verification is continuous, not a final phase:
|
|
|
114
239
|
- Security review of each new trust boundary, secret, permission, or data flow.
|
|
115
240
|
- Tests at the level the risk requires: unit for rules, integration for boundaries, one
|
|
116
241
|
end-to-end path for the slice.
|
|
242
|
+
- For a feature, the agreed end-to-end path is exercised and every golden and critical dark
|
|
243
|
+
case has evidence or a declared gap.
|
|
117
244
|
- A real-device or real-environment check before release, not only emulators.
|
|
118
245
|
|
|
119
246
|
**Gate for release:** no open critical/high findings; must-pass checks green; known failures
|
|
@@ -121,7 +248,7 @@ documented; residual risk accepted by the user.
|
|
|
121
248
|
|
|
122
249
|
## Phase 5 — Release
|
|
123
250
|
|
|
124
|
-
**Owner:** SRE Engineer. **Participants:**
|
|
251
|
+
**Owner:** SRE Engineer. **Participants:** Coordinator, Cybersecurity.
|
|
125
252
|
|
|
126
253
|
- Version, changelog, signing, and install/upgrade path.
|
|
127
254
|
- Rollback or roll-forward plan.
|
|
@@ -133,7 +260,7 @@ explicitly accepted.
|
|
|
133
260
|
|
|
134
261
|
## Phase 6 — Close
|
|
135
262
|
|
|
136
|
-
**Owner:**
|
|
263
|
+
**Owner:** the Coordinator.
|
|
137
264
|
|
|
138
265
|
- What shipped, with evidence.
|
|
139
266
|
- What was deferred and why.
|
|
@@ -147,6 +274,7 @@ explicitly accepted.
|
|
|
147
274
|
| Artifact | When | Maximum before the first commit |
|
|
148
275
|
|---|---|---|
|
|
149
276
|
| Operational brief | Frame | 1 page |
|
|
277
|
+
| Feature plan | Feature intake | One visible plan with development and test plan |
|
|
150
278
|
| Architecture notes / ADRs | When a decision blocks a slice | 1 page per ADR |
|
|
151
279
|
| Threat model | When a trust boundary or sensitive data appears | The slice's threats only |
|
|
152
280
|
| Test plan | With the first tests | The first 5 tests |
|
|
@@ -171,9 +299,11 @@ first commit, cut it or defer it.
|
|
|
171
299
|
|
|
172
300
|
| Change | Process |
|
|
173
301
|
|---|---|
|
|
174
|
-
|
|
|
175
|
-
|
|
|
176
|
-
|
|
|
302
|
+
| Question or read-only investigation | Query: answer directly, no specialists |
|
|
303
|
+
| Typo, docs, one-line fix | Small change: recon → change → check → report |
|
|
304
|
+
| Feature in one layer | Operational brief + approval → implement in scope → tests → review |
|
|
305
|
+
| New capability across layers | Feature intake → visible feature plan → approval → delegated steps → E2E |
|
|
306
|
+
| Cross-layer, data, auth, public contract | Feature plan + independent security/QA, scope lock on every writer |
|
|
177
307
|
| New project | Frame (1 page) → walking skeleton → slice loop |
|
|
178
308
|
| Incident | Stabilize → diagnose → fix → regression test → short postmortem |
|
|
179
309
|
|
|
@@ -190,5 +320,9 @@ request, a screenshot, a CVE, or a metric. See `core/quality-gates.md`.
|
|
|
190
320
|
- **Demo debt:** a skeleton that only runs in a notebook, not in the repo.
|
|
191
321
|
- **Phase theater:** marking a phase "done" because its document exists.
|
|
192
322
|
- **Silent scope growth:** adding a second slice before finishing the first.
|
|
323
|
+
- **Unrequested improvements:** implementing a finding outside `Scope` because it looked useful.
|
|
324
|
+
- **Half-finished feature:** closing with green slices but without the agreed end-to-end path.
|
|
325
|
+
- **Routine interruption:** pausing the approved plan to ask about a decision the plan covers.
|
|
326
|
+
- **Destructive shortcut:** deleting files or data without the user's explicit authorization.
|
|
193
327
|
|
|
194
328
|
If two consecutive work sessions produce no running code, stop and escalate to the user.
|
package/core/quality-gates.md
CHANGED
|
@@ -9,6 +9,7 @@ Every change, regardless of type:
|
|
|
9
9
|
|
|
10
10
|
- [ ] The requested behavior or documentation is complete.
|
|
11
11
|
- [ ] The diff is scoped; unrelated changes are excluded.
|
|
12
|
+
- [ ] The diff stays inside the approved `Scope`; out-of-scope findings are reported, not implemented.
|
|
12
13
|
- [ ] The diff has been read end-to-end by the author.
|
|
13
14
|
- [ ] No secrets, tokens, credentials, or private data are added.
|
|
14
15
|
- [ ] No debug output, commented-out code, or temporary files remain.
|
|
@@ -20,8 +21,21 @@ Every change, regardless of type:
|
|
|
20
21
|
|
|
21
22
|
## Gates by change type
|
|
22
23
|
|
|
24
|
+
### Query
|
|
25
|
+
|
|
26
|
+
- [ ] The answer cites the file, command, or behavior it is based on.
|
|
27
|
+
- [ ] No specialist was launched to read or explain code.
|
|
28
|
+
- [ ] No file was modified.
|
|
29
|
+
|
|
30
|
+
### Small change
|
|
31
|
+
|
|
32
|
+
- [ ] The short operational brief states problem, scope, test, expected evidence, `Aprobado:` and `Scope:`.
|
|
33
|
+
- [ ] One writer owns the change.
|
|
34
|
+
- [ ] The change stays inside the stated scope.
|
|
35
|
+
|
|
23
36
|
### Bug fix
|
|
24
37
|
|
|
38
|
+
- [ ] The short brief records `Aprobado:` and `Scope:`.
|
|
25
39
|
- [ ] The failure was reproduced before the fix.
|
|
26
40
|
- [ ] A test fails without the fix and passes with it (regression test).
|
|
27
41
|
- [ ] The root cause is addressed, not only the symptom.
|
|
@@ -30,16 +44,22 @@ Every change, regardless of type:
|
|
|
30
44
|
|
|
31
45
|
### Feature
|
|
32
46
|
|
|
47
|
+
- [ ] Feature intake answered before the plan.
|
|
48
|
+
- [ ] The user saw the plan: development steps, agents, parallelism, test plan, evidence, risks, rollback.
|
|
49
|
+
- [ ] The plan has a top-level `Scope:`, Test/Verification/Evidence content, and an affirmative `Aprobado:` with the user's decision, words, and date; observations were iterated.
|
|
50
|
+
- [ ] Every writer received `Plan:` and a disjoint `Scope` equal to or narrower than the plan's scope; a development-table plan had a matching `Step:` and declared agent row; no unrequested change was implemented.
|
|
33
51
|
- [ ] Acceptance criteria are observable and covered.
|
|
34
52
|
- [ ] Loading, empty, error, unauthorized, and retry states are handled where relevant.
|
|
35
53
|
- [ ] Input is validated at the boundary.
|
|
36
54
|
- [ ] Authorization is enforced server-side, not only in the UI.
|
|
37
|
-
- [ ] Tests cover the happy path
|
|
55
|
+
- [ ] Tests cover the happy path, the important failure paths, and every critical dark case.
|
|
56
|
+
- [ ] The agreed end-to-end path runs and its evidence is attached.
|
|
38
57
|
- [ ] Observability exists for new failure modes.
|
|
39
58
|
- [ ] Documentation is updated.
|
|
40
59
|
|
|
41
60
|
### Refactor
|
|
42
61
|
|
|
62
|
+
- [ ] The short brief records `Aprobado:` and `Scope:`.
|
|
43
63
|
- [ ] Behavior is unchanged by definition and by tests.
|
|
44
64
|
- [ ] Baseline tests passed before the refactor.
|
|
45
65
|
- [ ] Changes are small and reversible; no feature work is mixed in.
|
|
@@ -84,6 +104,24 @@ Every change, regardless of type:
|
|
|
84
104
|
- [ ] Monitoring and alerts cover the release.
|
|
85
105
|
- [ ] The release was verified in an environment that resembles production.
|
|
86
106
|
|
|
107
|
+
## Scope and destructive operations
|
|
108
|
+
|
|
109
|
+
A change is not accepted because it is green; it is accepted when it does what was approved
|
|
110
|
+
and nothing else.
|
|
111
|
+
|
|
112
|
+
- **Scope lock:** the writer touched only files matching the delegation's `Scope`, and the
|
|
113
|
+
delegation scope was equal to or narrower than the plan's top-level `Scope`. Any other change
|
|
114
|
+
is reverted or explicitly approved as a plan revision.
|
|
115
|
+
- **Out-of-scope findings:** report them with evidence. Do not implement them, even when they
|
|
116
|
+
look like obvious improvements. The Coordinator decides whether to extend the plan. Read-only
|
|
117
|
+
roles may write their own reports under the planning directory.
|
|
118
|
+
- **Destructive operations:** file deletion, database `DROP`/`TRUNCATE`/`DELETE` without
|
|
119
|
+
`WHERE`, volume or infrastructure destruction, and any operation the plan marks as
|
|
120
|
+
destructive require the user's explicit authorization. Plan approval is not authorization.
|
|
121
|
+
Known patterns force the permission prompt; shell writes remain a residual risk.
|
|
122
|
+
- **Evidence of authorization:** the user's words and the permission decision, recorded in the
|
|
123
|
+
plan or session notes. Never print secrets while requesting it.
|
|
124
|
+
|
|
87
125
|
## Delivery gates
|
|
88
126
|
|
|
89
127
|
For a new project or a major change, progress is gated by running code, not by documents:
|
|
@@ -91,8 +129,10 @@ For a new project or a major change, progress is gated by running code, not by d
|
|
|
91
129
|
| Gate | Evidence |
|
|
92
130
|
|---|---|
|
|
93
131
|
| Frame | Operational and technical conversations; user explicitly approves scope, criteria and approach; golden/dark paths identified. |
|
|
132
|
+
| Feature plan | User-visible development plan + test plan + agents/parallelism; top-level `Scope:`; affirmative `Aprobado:`; scopes are disjoint and inside the plan. |
|
|
94
133
|
| Walking skeleton | The end-to-end path runs with fakes; one command; one test; a commit. |
|
|
95
134
|
| Slice | Golden and critical dark paths checked; specialist evidence and gaps recorded; scoped diff, demo and commit. |
|
|
135
|
+
| Feature closure | The agreed E2E path runs; every golden and critical dark case has evidence or a declared gap; residual risk reported. |
|
|
96
136
|
| Release | No open critical/high findings; must-pass checks green; install/upgrade verified in the target. |
|
|
97
137
|
|
|
98
138
|
A planning artifact is not a gate. It is a living note that unblocks a slice. See
|
package/core/roles/README.md
CHANGED
|
@@ -18,6 +18,7 @@ harnesses that support subagents.
|
|
|
18
18
|
|
|
19
19
|
| Role | Primary question |
|
|
20
20
|
|---|---|
|
|
21
|
+
| [Coordinator](coordinator.md) | What is the smallest approved slice, who owns it, and what evidence closes it? |
|
|
21
22
|
| [Team Lead](team-lead.md) | What is the shortest path to a verified delivery? |
|
|
22
23
|
| [Architect](architect.md) | What boundaries and trade-offs make this correct and evolvable? |
|
|
23
24
|
| [Cybersecurity Engineer](cybersecurity-engineer.md) | What can be attacked, and what proves the control works? |
|
|
@@ -41,7 +42,9 @@ The files remain for v0.1 compatibility but are not installed by `devcomp init`.
|
|
|
41
42
|
## Rules
|
|
42
43
|
|
|
43
44
|
- A role is not a personality. It is a bounded responsibility with explicit outputs.
|
|
44
|
-
- The
|
|
45
|
+
- The Coordinator routes; specialists do the deep work; QA and Cybersecurity verify.
|
|
46
|
+
- Every implementation role executes only the delegated step and stays inside the approved
|
|
47
|
+
`Scope`; out-of-scope findings are reported, not implemented.
|
|
45
48
|
- Every role follows the installed skills and the process. In this repository, the
|
|
46
49
|
canonical source docs are `core/principles.md`, `core/process.md`, and
|
|
47
50
|
`core/quality-gates.md`.
|
|
@@ -72,3 +72,13 @@ operable under failure.
|
|
|
72
72
|
**Verification:** commands and results
|
|
73
73
|
**Known gaps:** ...
|
|
74
74
|
```
|
|
75
|
+
|
|
76
|
+
## Scope lock
|
|
77
|
+
|
|
78
|
+
Execute only the assigned step from the approved plan and touch only files matching the
|
|
79
|
+
delegation's `Scope`. If the step needs another file, stop and report it. Report out-of-scope
|
|
80
|
+
findings (a broken test, an unrequested feature, a missing permission) with evidence; do not
|
|
81
|
+
implement them, even when they look useful. Destructive operations (file deletion, database
|
|
82
|
+
drop/truncate, volume or infrastructure destruction) require the user's explicit
|
|
83
|
+
authorization, requested through the Coordinator, before execution; stop and report the
|
|
84
|
+
operation, its blast radius and the available rollback.
|