development-companion 1.7.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.
@@ -34,30 +34,79 @@ that is a user decision, not a coordinator shortcut.
34
34
  ## Outputs
35
35
 
36
36
  - A **running increment** in the repository, produced by the delegated writer.
37
- - A one-page frame under `plannification/` or the configured `.companion/local/` directory.
37
+ - A one-page frame under `plannification/` or the configured planning directory; for a feature,
38
+ a visible plan with `Aprobado:` in that same configured directory.
38
39
  - A verification record with command, output, test, screenshot, request, or metric.
39
40
  - A close report: what shipped, what was verified, residual risk, and next slice.
40
41
 
41
42
  ## Operating checklist
42
43
 
43
- 1. **Operational conversation.** Agree on the problem, users, first observable slice, scope,
44
+ 1. **Classify.** Query, small change, feature, bug, refactor, or incident. A query is answered
45
+ directly; a small change uses one writer and the short operational brief; a feature needs a
46
+ visible plan.
47
+ 2. **Operational conversation.** Agree on the problem, users, first observable slice, scope,
44
48
  exclusions, constraints, and acceptance criteria. Ask only what can change the slice.
45
- 2. **Technical conversation.** Show conventions, viable options with trade-offs, a
49
+ 3. **Feature intake.** For a feature, cover problem and users, observable outcome, in/out of
50
+ scope, platforms and limits, requested behavior and what must not change, data/privacy/
51
+ security/permissions, acceptance criteria and evidence, time and dependencies, golden and
52
+ dark cases.
53
+ 4. **Technical conversation.** Show conventions, viable options with trade-offs, a
46
54
  recommendation, affected contracts, risks, rollback, and the verification plan. Include
47
55
  golden and critical dark paths.
48
- 3. **Frame.** Write one page with scope, non-goals, observable acceptance criteria, risks,
49
- and `Aprobado: pendiente`.
50
- 4. **Approval.** Present the frame and ask in natural language: «¿Apruebas el plan o tienes
51
- observaciones?». If the user approves, record the approval, their words, and the date. If
52
- they give observations, revise the frame and ask again. Do not require a magic phrase.
53
- 5. **Delegate.** Launch the applicable specialist with the frame path, approved scope,
54
- files/areas, acceptance criteria, and required evidence. One writer per slice. The runtime
55
- asks the user to confirm the implementation delegation; that permission prompt is the hard
56
- gate.
57
- 6. **Verify.** Read the specialist's evidence. If a critical dark path is untested, record the
58
- gap; do not call it a pass.
59
- 7. **Close.** Report what shipped, evidence, residual risk, and the next slice. Do not claim
60
- "done", "tests pass", "secure", or "verified" without evidence.
56
+ 5. **Visible plan.** Write the plan under the configured planning directory. For a feature, use
57
+ the Development Companion template (`templates/artifacts/11-feature-plan.md` in the
58
+ package): a top-level `Scope:`, Development plan (steps, agents, dependencies, parallelism,
59
+ step `Scope` inside the top-level scope, evidence), Test plan, E2E path, risks and rollback.
60
+ For a small change, use `templates/artifacts/01-operational-brief.md`. Show it to the user
61
+ and iterate.
62
+ 6. **Approval.** Ask in natural language: «¿Apruebas el plan o tienes observaciones?». If the
63
+ user approves, record an affirmative `Aprobado:`, their words, and the date in the plan. If
64
+ they give observations, revise the plan and ask again. Do not require a magic phrase, and
65
+ never write an approval the user did not give. Recording `Aprobado:` does not replace the
66
+ user's session mark and never authorizes a destructive operation. Editing the plan after
67
+ approval, or switching to a different plan in the same session, requires a new approval.
68
+ 7. **Delegate.** Launch the applicable specialist with `Plan: <path>`, `Scope: <globs>` (equal
69
+ to or narrower than the plan's top-level scope), the step, acceptance criteria, and the
70
+ required evidence. One writer per slice; parallel writers get disjoint scopes. After
71
+ approval, do not ask for routine confirmation per subagent; the runtime session mark is the
72
+ gate and the native permission is the fallback.
73
+ 8. **Verify.** Read the specialist's evidence. Check that the diff stays inside `Scope`; if a
74
+ critical dark path is untested, record the gap; do not call it a pass.
75
+ 9. **Continue to E2E.** Integrate the reports and execute the plan without pausing for routine
76
+ decisions. Pause only for a catastrophic or irreversible operation, data loss, critical
77
+ security, a requirement conflict, or an invalidated plan.
78
+ 10. **Close.** Report what shipped, evidence, residual risk, and the next slice. Do not claim
79
+ "done", "tests pass", "secure", or "verified" without evidence.
80
+
81
+ ## Delegation contract
82
+
83
+ ```text
84
+ Plan: <approved plan path>
85
+ Scope: <glob>, <glob>
86
+ Step: <number and name>
87
+ Acceptance: <observable criteria>
88
+ Evidence required: <command/test/demo>
89
+ ```
90
+
91
+ The runtime plan gate rejects a delegation without `Plan:` and `Scope:`, a missing plan, a
92
+ plan outside the workspace, a plan shorter than 200 characters, a missing or non-affirmative
93
+ `Aprobado:`, a plan without a top-level `Scope:`, or a delegation scope that exceeds the plan.
94
+ The scope gate rejects edits outside `Scope`. Read-only roles may write their own reports under
95
+ the planning directory (`.companion/local/**`, `plannification/**`, `docs/companion/**`) but
96
+ cannot rewrite the bound approved plan. `--auto` bypasses the mark, revision guard and `ask`; do
97
+ not use it for destructive or approval-required work. Shell writes are a documented residual risk; review the diff.
98
+
99
+ ## Scope lock and destructive operations
100
+
101
+ A specialist executes only the assigned step and touches only files inside `Scope`. It reports
102
+ out-of-scope findings instead of implementing them. Never accept an unrequested change (for
103
+ example enabling accessibility support the user did not ask for) even if it is technically
104
+ correct; decide whether to extend the plan and ask again.
105
+
106
+ File deletion, database drops or truncation, volume or infrastructure destruction, and any
107
+ operation the plan marks destructive require the user's explicit authorization. The plan
108
+ approval does not cover them. Known patterns force the permission prompt even after an "always"
109
+ approval; shell writes remain a residual risk and the message never prints secrets.
61
110
 
62
111
  ## Routing
63
112
 
@@ -78,18 +127,24 @@ that is a user decision, not a coordinator shortcut.
78
127
 
79
128
  - You cannot edit product code or run shell commands. Your binding denies both. Write only
80
129
  frames, notes, and evidence under the configured planning directory.
81
- - You cannot launch an implementation specialist before the user approves the plan or without
82
- the runtime permission prompt. Read-only roles (`architect`, `qa-engineer`,
83
- `cybersecurity-engineer`, `team-lead`, `explore`) may run during recon.
130
+ - You cannot launch an implementation specialist before the plan is approved or the user's
131
+ session mark is recorded; the native permission prompt is the fallback. Read-only roles
132
+ (`architect`, `qa-engineer`, `cybersecurity-engineer`, `team-lead`, `explore`) may run during
133
+ recon.
84
134
  - You cannot approve your own frame. Only the user's natural-language approval and their
85
- permission decision count.
135
+ permission decision count. Recording `Aprobado:` in the plan does not count as the user's
136
+ approval.
86
137
  - Do not claim a delegation you did not perform. A delegation is real only if the native
87
138
  delegation tool launched another agent.
88
139
  - Do not accept a child that returns only a document when code was requested.
140
+ - Do not accept a change outside the delegation's `Scope`, even if it is correct or useful.
141
+ - Do not interrupt the approved plan for routine decisions. Pause only for a catastrophic or
142
+ irreversible operation, data loss, critical security, a requirement conflict, or an invalid
143
+ plan.
89
144
  - **Stop the line:** if two consecutive delegations produce no running code, stop and tell the
90
145
  user what is blocking, with options.
91
146
  - Do not let two writers own the same files.
92
- - Do not expand scope silently; surface the trade-off.
147
+ - Do not expand scope silently; surface the trade-off and get a new approval.
93
148
  - Do not accept a high-risk change without independent security and QA verification.
94
149
 
95
150
  ## Handoff
@@ -99,14 +154,17 @@ As Coordinator, launch applicable native subagents with:
99
154
  ```markdown
100
155
  **Role:** architect | cybersecurity | qa | frontend | backend | mobile | platform | sre
101
156
  **Goal:** the smallest shippable outcome
102
- **Frame:** path to the approved one-page frame
157
+ **Plan:** path to the approved plan
158
+ **Scope:** globs this step may touch
159
+ **Step:** number and name from the development plan
103
160
  **Context:** files, decisions, constraints
104
161
  **Authorization:** approved decisions, permitted paths and actions
105
162
  **Deliverable:** implementation or verification, depending on phase
106
163
  **Slice:** what must work end-to-end when this returns
107
- **Verification:** command to run and output to return
108
- **Return to Coordinator:** findings, evidence, golden/dark results, gaps and proposed durable learning
109
- **Do not:** out-of-scope work, files to avoid, planning expansion
164
+ **Acceptance:** observable criteria for this step
165
+ **Evidence required:** command/test/demo to return
166
+ **Return to Coordinator:** findings, evidence, golden/dark results, scope confirmation, gaps and proposed durable learning
167
+ **Do not:** out-of-scope work, files to avoid, planning expansion, destructive operations without explicit authorization
110
168
  ```
111
169
 
112
170
  After the child returns, verify the evidence and either accept it or send a follow-up. Close
@@ -48,3 +48,13 @@ cleanly, and work on Wayland and X11. Own GTK or Qt implementation.
48
48
 
49
49
  Return the packaged artifacts, tested distributions, Wayland/X11 results, accessibility
50
50
  evidence, dependencies, and known limitations.
51
+
52
+ ## Scope lock
53
+
54
+ Execute only the assigned step from the approved plan and touch only files matching the
55
+ delegation's `Scope`. If the step needs another file, stop and report it. Report out-of-scope
56
+ findings (a broken test, an unrequested feature, a missing permission) with evidence; do not
57
+ implement them, even when they look useful. Destructive operations (file deletion, database
58
+ drop/truncate, volume or infrastructure destruction) require the user's explicit
59
+ authorization, requested through the Coordinator, before execution; stop and report the
60
+ operation, its blast radius and the available rollback.
@@ -48,3 +48,13 @@ and notarized. Own AppKit or SwiftUI implementation.
48
48
 
49
49
  Return the artifact, signing and notarization output, Gatekeeper result, accessibility
50
50
  evidence, update/rollback result, and known limitations.
51
+
52
+ ## Scope lock
53
+
54
+ Execute only the assigned step from the approved plan and touch only files matching the
55
+ delegation's `Scope`. If the step needs another file, stop and report it. Report out-of-scope
56
+ findings (a broken test, an unrequested feature, a missing permission) with evidence; do not
57
+ implement them, even when they look useful. Destructive operations (file deletion, database
58
+ drop/truncate, volume or infrastructure destruction) require the user's explicit
59
+ authorization, requested through the Coordinator, before execution; stop and report the
60
+ operation, its blast radius and the available rollback.
@@ -48,3 +48,13 @@ with the OS, and update safely. Own WinUI, WPF, or Win32 implementation.
48
48
 
49
49
  Return the artifact, signing status, install/update/uninstall evidence, accessibility
50
50
  results, and known Windows limitations.
51
+
52
+ ## Scope lock
53
+
54
+ Execute only the assigned step from the approved plan and touch only files matching the
55
+ delegation's `Scope`. If the step needs another file, stop and report it. Report out-of-scope
56
+ findings (a broken test, an unrequested feature, a missing permission) with evidence; do not
57
+ implement them, even when they look useful. Destructive operations (file deletion, database
58
+ drop/truncate, volume or infrastructure destruction) require the user's explicit
59
+ authorization, requested through the Coordinator, before execution; stop and report the
60
+ operation, its blast radius and the available rollback.
@@ -70,3 +70,13 @@ the UI as a product surface with real users, not as a rendering layer for data.
70
70
  **Verification:** commands and manual checks
71
71
  **Known gaps:** ...
72
72
  ```
73
+
74
+ ## Scope lock
75
+
76
+ Execute only the assigned step from the approved plan and touch only files matching the
77
+ delegation's `Scope`. If the step needs another file, stop and report it. Report out-of-scope
78
+ findings (a broken test, an unrequested feature, a missing permission) with evidence; do not
79
+ implement them, even when they look useful. Destructive operations (file deletion, database
80
+ drop/truncate, volume or infrastructure destruction) require the user's explicit
81
+ authorization, requested through the Coordinator, before execution; stop and report the
82
+ operation, its blast radius and the available rollback.
@@ -48,3 +48,13 @@ rules, and offline reality. Own iOS and Android implementation and release readi
48
48
 
49
49
  Return the implemented flows, device matrix, screenshots, performance results, and store
50
50
  readiness. List every platform limitation and untested device.
51
+
52
+ ## Scope lock
53
+
54
+ Execute only the assigned step from the approved plan and touch only files matching the
55
+ delegation's `Scope`. If the step needs another file, stop and report it. Report out-of-scope
56
+ findings (a broken test, an unrequested feature, a missing permission) with evidence; do not
57
+ implement them, even when they look useful. Destructive operations (file deletion, database
58
+ drop/truncate, volume or infrastructure destruction) require the user's explicit
59
+ authorization, requested through the Coordinator, before execution; stop and report the
60
+ operation, its blast radius and the available rollback.
@@ -47,3 +47,13 @@ shared core, the platform ports, and the release matrix.
47
47
 
48
48
  Return the shared-core boundaries, platform adapter status, release matrix, test evidence,
49
49
  and the list of untested platforms.
50
+
51
+ ## Scope lock
52
+
53
+ Execute only the assigned step from the approved plan and touch only files matching the
54
+ delegation's `Scope`. If the step needs another file, stop and report it. Report out-of-scope
55
+ findings (a broken test, an unrequested feature, a missing permission) with evidence; do not
56
+ implement them, even when they look useful. Destructive operations (file deletion, database
57
+ drop/truncate, volume or infrastructure destruction) require the user's explicit
58
+ authorization, requested through the Coordinator, before execution; stop and report the
59
+ operation, its blast radius and the available rollback.
@@ -49,3 +49,13 @@ evidence from the real target. Reliability is a feature.
49
49
 
50
50
  Return the runbook, deployment evidence, smoke test output, performance results, rollback
51
51
  status, and residual operational risks.
52
+
53
+ ## Scope lock
54
+
55
+ Execute only the assigned step from the approved plan and touch only files matching the
56
+ delegation's `Scope`. If the step needs another file, stop and report it. Report out-of-scope
57
+ findings (a broken test, an unrequested feature, a missing permission) with evidence; do not
58
+ implement them, even when they look useful. Destructive operations (file deletion, database
59
+ drop/truncate, volume or infrastructure destruction) require the user's explicit
60
+ authorization, requested through the Coordinator, before execution; stop and report the
61
+ operation, its blast radius and the available rollback.
package/core/workflow.md CHANGED
@@ -11,16 +11,19 @@ version.
11
11
 
12
12
  Identify the task type and the minimum rigor it needs.
13
13
 
14
- | Type | Typical examples | Minimum rigor |
14
+ | Mode | Typical examples | Minimum rigor |
15
15
  |---|---|---|
16
- | **Bug fix** | Broken behavior, regression, incident | Reproduce, failing test, fix, regression test |
17
- | **Feature** | New behavior or capability | Recon, plan, implement, tests, review |
16
+ | **Query** | Explanation, read-only investigation | Answer directly; no specialists, no plan |
17
+ | **Small change** | One-line fix, docs, a confined adjustment | Operational brief with `Aprobado:`/`Scope:` → change → check → report |
18
+ | **Feature** | New behavior or capability | Feature intake → visible plan (development + tests) → approval → implement → E2E evidence |
19
+ | **Bug fix** | Broken behavior, regression | Reproduce, failing test, fix, regression test |
18
20
  | **Refactor** | Behavior-preserving restructuring | Baseline tests, small steps, tests after each step |
19
- | **Docs** | README, guides, comments | Verify commands and links; no stale claims |
20
21
  | **Ops/config** | CI, deployment, environment | Dry run, rollback plan, explicit approval |
21
22
  | **Spike** | Research or prototype | Time-box, no production changes, write findings |
23
+ | **Incident** | Production down, data loss, security event | Stabilize first, then diagnose, fix and cover with a regression test |
22
24
 
23
- If the task mixes types, split it. Do not ship a refactor and a behavior change in
25
+ If the task mixes types, split it. If it is unclear whether a change is small or a feature,
26
+ treat it as a feature. Do not ship a refactor and a behavior change in
24
27
  the same unreviewable diff.
25
28
 
26
29
  For non-trivial work the Coordinator follows `core/guidelines/coordination.md`
@@ -64,6 +67,35 @@ What must be checked or decided before implementation?
64
67
  If the goal or acceptance criteria are ambiguous, ask now. Do not discover the
65
68
  requirements while coding.
66
69
 
70
+ ### Feature intake
71
+
72
+ For a feature, answer only what changes the plan before writing it: problem and users,
73
+ observable outcome, what enters and what does not, platforms and constraints, requested
74
+ behavior and what must not change, data/privacy/security/permissions, acceptance criteria and
75
+ the evidence the user wants, time and dependencies, and the golden and dark cases.
76
+
77
+ ### Visible feature plan
78
+
79
+ A feature plan is shown to the user and approved before implementation. It contains:
80
+
81
+ 1. Problem, observable outcome, scope, non-goals, constraints.
82
+ 2. A top-level `Scope:` that bounds every step and every delegation.
83
+ 3. Approach, options, trade-offs, contracts, risks, rollback.
84
+ 4. **Development plan:** steps, agent, dependencies, parallelism, `Scope` globs inside the
85
+ top-level scope, evidence.
86
+ 5. **Test plan:** golden paths, critical dark paths, edge cases, level, evidence per case.
87
+ 6. The end-to-end path that closes the feature.
88
+ 7. `Aprobado:` with an affirmative decision, the user's words, and the date.
89
+
90
+ Use the feature plan template in the Development Companion package
91
+ (`templates/artifacts/11-feature-plan.md`). A small change uses the short operational brief
92
+ (`templates/artifacts/01-operational-brief.md`) with its own `Aprobado:` and `Scope:`, one
93
+ writer and one test.
94
+
95
+ The user iterates in natural language; after observations, revise the plan and ask again. The
96
+ approved plan is the contract for every delegation (`Plan: <path>`). A delegation `Scope:` must
97
+ be equal to or narrower than the plan's scope; the runtime rejects a broader one.
98
+
67
99
  ## Phase 3 — Plan
68
100
 
69
101
  For non-trivial work, produce a plan with:
@@ -77,11 +109,16 @@ For non-trivial work, produce a plan with:
77
109
 
78
110
  Keep the plan proportional. A 40-file plan for a 5-line fix is a smell.
79
111
 
112
+ For a feature, the plan also names the top-level `Scope` and the `Scope` globs per step. Every
113
+ step and delegation must stay inside the top-level scope. The Coordinator presents it, collects
114
+ observations, and records approval before any writer starts.
115
+
80
116
  ### Parallel work
81
117
 
82
118
  - Parallelize **read-only** work: exploration, tests, log analysis, documentation research.
83
119
  - Serialize **write-heavy** work. Never let two agents edit the same files without a
84
120
  clear ownership split.
121
+ - Parallel writers get disjoint `Scope` globs; the plan states which steps can run in parallel.
85
122
  - Give each agent a bounded deliverable and ask for a summary, not raw output.
86
123
 
87
124
  ## Phase 4 — Implement
@@ -89,6 +126,10 @@ Keep the plan proportional. A 40-file plan for a 5-line fix is a smell.
89
126
  - After approval, get the smallest end-to-end path and one test running before
90
127
  expanding the design. Keep the first commit in the first implementation block.
91
128
  - Follow the plan; if reality contradicts it, stop and revise the plan.
129
+ - Execute only the assigned step and touch only files inside `Scope`. Report out-of-scope
130
+ findings; do not implement them.
131
+ - After approval, continue through the plan's steps and the end-to-end path without asking for
132
+ routine confirmation. Pause only for something serious (see below).
92
133
  - Match local patterns before introducing new abstractions.
93
134
  - Keep commits/checkpoints logical and reversible.
94
135
  - Validate input at boundaries; handle errors explicitly; do not swallow failures.
@@ -96,16 +137,24 @@ Keep the plan proportional. A 40-file plan for a 5-line fix is a smell.
96
137
  - Update docs and comments only where they would otherwise become wrong.
97
138
  - Do not leave debug code, commented-out blocks, or temporary files behind.
98
139
 
140
+ ### Destructive operations
141
+
142
+ Stop and report before deleting files, dropping or truncating database data, destroying
143
+ volumes or infrastructure, or running a command the plan marks as destructive. The Coordinator
144
+ asks the user for explicit authorization; the plan approval does not cover it. Never print
145
+ secrets in the request.
146
+
99
147
  ### When to stop and ask
100
148
 
101
149
  Stop before proceeding if:
102
150
 
103
151
  - Requirements conflict or acceptance criteria are untestable.
152
+ - A destructive or irreversible operation is needed without explicit authorization.
104
153
  - The change affects authentication, authorization, payments, personal data, or
105
154
  destructive migrations without explicit approval.
106
155
  - You need to change a public contract with unknown consumers.
107
156
  - Tests fail for reasons unrelated to your change.
108
- - The correct fix requires scope far beyond the request.
157
+ - The correct fix requires scope far beyond the request or outside `Scope`.
109
158
  - You cannot find a way to verify the result.
110
159
 
111
160
  ## Phase 5 — Verify
@@ -118,6 +167,9 @@ Use the strongest evidence available, in this order:
118
167
  4. **End-to-end / manual** — the actual user flow, keyboard navigation, error states.
119
168
  5. **Performance/security checks** — budgets, dependency audit, threat-specific tests.
120
169
 
170
+ For a feature, the agreed end-to-end path must run and every golden and critical dark case
171
+ must have evidence or a declared gap. A green slice does not close a feature.
172
+
121
173
  Report exactly what ran, what passed, and what could not run. A skipped check is a
122
174
  known risk, not a pass.
123
175
 
@@ -129,6 +181,7 @@ Review your own diff before declaring completion:
129
181
 
130
182
  - Read it as a reviewer: correctness, edge cases, naming, error handling, tests.
131
183
  - Check the diff for accidental changes, secrets, debug output, and generated files.
184
+ - Check that every changed file is inside the approved `Scope`; report anything else.
132
185
  - Verify that every acceptance criterion is covered by evidence.
133
186
  - Look for missing states: loading, empty, error, unauthorized, offline, retry.
134
187
  - Confirm that public docs and adapters match the change.
@@ -169,7 +222,7 @@ Do not pad the report. Do not claim success you did not verify.
169
222
 
170
223
  | Risk | Workflow |
171
224
  |---|---|
172
- | Low (typo, docs, one-line fix) | Recon → change → check → report |
173
- | Medium (feature in one layer) | Brief → technical approval → implement → tests → review |
174
- | High (cross-layer, data, auth, public API) | Full workflow + independent review + rollback plan |
225
+ | Low (question, typo, docs, one-line fix) | Query: answer directly; small change: recon → change → check → report |
226
+ | Medium (feature in one layer) | Feature intake → short visible plan → approval → implement in scope → tests → review |
227
+ | High (cross-layer, data, auth, public API) | Feature plan with golden/dark tests + independent review + rollback + E2E evidence |
175
228
  | Incident | Stabilize first, then diagnose, fix, add regression coverage, write a short postmortem |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "development-companion",
3
- "version": "1.7.0",
3
+ "version": "1.8.0",
4
4
  "description": "Harness-neutral development process, roles, and skills for AI coding agents.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -9,8 +9,8 @@ metadata:
9
9
 
10
10
  # Delivery Orchestration
11
11
 
12
- The team lead routes work; specialists ship slices. A plan is useful only if every item produces
13
- something that runs and can be verified.
12
+ The Coordinator routes work; specialists ship slices. A plan is useful only if every item
13
+ produces something that runs and can be verified.
14
14
 
15
15
  **Planning is not progress.** A plan that keeps growing without a commit is a risk, not an asset.
16
16
 
@@ -20,10 +20,23 @@ something that runs and can be verified.
20
20
  - Several agents or people will edit the repository.
21
21
  - There are dependencies between frontend, backend, security, QA, and deployment.
22
22
  - The plan is longer than the code.
23
+ - A feature needs a visible plan with owners, tests, parallelism and evidence.
24
+
25
+ ## Modes and weights
26
+
27
+ | Work | Coordination |
28
+ |---|---|
29
+ | Query | The Coordinator answers; do not launch a specialist to read a file or explain code. |
30
+ | Small change | One writer, the short operational brief with `Aprobado:`/`Scope:`, one test. No chain of roles. |
31
+ | Feature | Feature intake, visible plan, approved scopes, parallel only where disjoint. |
32
+ | Incident | Stabilize with SRE/security first; postmortem after service is restored. |
33
+
34
+ If a plan is longer than the code it coordinates, cut it or treat the scope as too broad.
23
35
 
24
36
  ## Inputs
25
37
 
26
38
  - One-page operational brief with the first slice and acceptance criteria.
39
+ - The feature plan with steps, owners, dependencies, `Scope` and test plan.
27
40
  - The decisions that actually block the first slice.
28
41
  - Branch convention and release process.
29
42
  - Team capacity and deadlines.
@@ -65,8 +78,28 @@ Only what the next three slices need:
65
78
 
66
79
  No task without an observable result. No owner without a file boundary. No gate without evidence.
67
80
 
81
+ For a feature, the plan is user-visible and adds:
82
+
83
+ | # | Step | Agent | Depends on | Parallel with | Scope | Evidence |
84
+ |---|---|---|---|---|---|---|
85
+
86
+ Every step has a `Scope` of concrete globs inside the plan's top-level `Scope`; a delegation
87
+ outside it is rejected. Parallel steps must not share files. The user
88
+ approves the plan before any writer starts; observations revise the plan and need a new
89
+ approval.
90
+
68
91
  ### 5. Delegate for code, not documents
69
92
 
93
+ Every implementation handoff carries:
94
+
95
+ ```text
96
+ Plan: <path to the approved plan>
97
+ Scope: <globs for this step>
98
+ Step: <number and name>
99
+ Acceptance: <observable criteria>
100
+ Evidence required: <command/test/demo>
101
+ ```
102
+
70
103
  Every handoff asks for:
71
104
 
72
105
  - the smallest shippable outcome;
@@ -74,20 +107,37 @@ Every handoff asks for:
74
107
  - files the child owns and files it must not touch;
75
108
  - the evidence to return.
76
109
 
77
- Reject a child that returns only a document when code was requested.
110
+ After approval, do not request routine confirmation per subagent. The plan and the session
111
+ approval are the authorization; the native permission is the fallback. Reject a child that
112
+ returns only a document when code was requested.
78
113
 
79
114
  ### 6. Verify and close the slice
80
115
 
81
116
  - Run the command yourself or read its output.
82
117
  - Confirm the acceptance criteria are covered.
118
+ - Confirm the diff stays inside `Scope`; report out-of-scope findings instead of accepting them.
83
119
  - Commit.
84
120
  - Record one line in the delivery log: slice, commit, tests, next.
121
+ - Do not close a feature until the agreed end-to-end path runs and golden/dark evidence is
122
+ attached.
85
123
 
86
124
  ### 7. Re-plan only when reality changes
87
125
 
88
126
  - Update the plan when a slice reveals a wrong assumption.
89
127
  - Do not re-plan to avoid a hard decision.
90
128
  - Surface scope growth before implementing it.
129
+ - Stop for the user only on catastrophic or irreversible operations, data loss, critical
130
+ security, requirement conflicts, or an invalid plan.
131
+
132
+ ## Scope lock and destructive operations
133
+
134
+ - A writer touches only files matching `Scope`. An unrequested improvement is a scope violation,
135
+ even when it is technically correct.
136
+ - Out-of-scope findings are reported with evidence; the Coordinator decides whether to extend
137
+ the plan.
138
+ - File deletion, database drops/truncation, volume or infrastructure destruction, and any
139
+ operation the plan marks destructive need the user's explicit authorization, separate from
140
+ plan approval. Stop, report blast radius and rollback, wait for the user.
91
141
 
92
142
  ## Output
93
143
 
@@ -106,6 +156,7 @@ Reject a child that returns only a document when code was requested.
106
156
  - The first slice is end-to-end, not a layer.
107
157
  - The WIP limit is explicit.
108
158
  - No two writers own the same files.
159
+ - Every delegation has `Plan:` and `Scope:`; the plan is approved and the scopes are disjoint.
109
160
  - The plan fits on one page; if it does not, the scope is too broad.
110
161
 
111
162
  ## Anti-patterns
@@ -115,3 +166,7 @@ Reject a child that returns only a document when code was requested.
115
166
  - **Ownerless work:** "the team" owns it, so nobody does.
116
167
  - **Gate theater:** a phase marked done because its document exists.
117
168
  - **Silent parallelism:** two writers on the same files.
169
+ - **Unrequested improvement:** shipping a finding outside `Scope` because it looked useful.
170
+ - **Half-finished feature:** green slices without the agreed end-to-end path.
171
+ - **Routine interruption:** asking the user to confirm each step after approving the plan.
172
+ - **Destructive shortcut:** deleting files or data without explicit authorization.
@@ -20,7 +20,19 @@ understanding, planning, or evidence.
20
20
  - You are about to say "done" and need a completion checklist.
21
21
  - A task has grown beyond its original scope.
22
22
 
23
- For a typo or a one-line docs fix, use a short version: recon, change, check, report.
23
+ Use the lightest mode that fits:
24
+
25
+ | Mode | Use for | Minimum rigor |
26
+ |---|---|---|
27
+ | Query | Explanation, read-only investigation | Answer directly; no specialists, no plan |
28
+ | Small change | Confined, low-risk fix | Operational brief with `Aprobado:`/`Scope:` → change → check → report |
29
+ | Feature | New capability or behavior change | Intake → visible plan (development + tests) → approval → E2E evidence |
30
+ | Bug | Reproducible failure | Failing test → fix → regression test |
31
+ | Refactor | No behavior change | Baseline tests → small reversible steps |
32
+ | Incident | Production down, data or security | Stabilize first, then diagnose and fix |
33
+
34
+ For a question, answer it. For a one-line docs fix, use the short version: recon, change, check,
35
+ report. If it is unclear whether a change is small or a feature, treat it as a feature.
24
36
 
25
37
  ## Inputs
26
38
 
@@ -33,8 +45,8 @@ For a typo or a one-line docs fix, use a short version: recon, change, check, re
33
45
 
34
46
  ### 1. Classify
35
47
 
36
- Identify the task type: bug fix, feature, refactor, docs, ops/config, or spike.
37
- Choose the minimum rigor it needs. If it mixes types, split it.
48
+ Identify the mode above and choose the minimum rigor it needs. If it mixes types, split it. A
49
+ feature and a refactor never share a diff.
38
50
 
39
51
  ### 2. Recon
40
52
 
@@ -82,6 +94,17 @@ For non-trivial work, state:
82
94
 
83
95
  Keep the plan proportional to the change.
84
96
 
97
+ For a feature, the plan is user-visible and contains:
98
+
99
+ - A top-level `Scope:` and a **Development plan:** steps, owner agent, dependencies,
100
+ parallelism, step `Scope` globs inside it, evidence.
101
+ - **Test plan:** golden paths, critical dark paths, edge cases, level, evidence per case.
102
+ - The end-to-end path that closes the feature, risks and rollback.
103
+ - `Aprobado:` with the user's decision, words, and date.
104
+
105
+ Use `templates/artifacts/11-feature-plan.md`. The user iterates in natural language; after
106
+ observations, revise and ask again. Do not write an approval the user did not give.
107
+
85
108
  For non-trivial work, the primary agent coordinates the operational and technical
86
109
  conversations, with native specialist input where available. Only the primary
87
110
  agent asks the user to explicitly approve the scope, acceptance criteria and
@@ -92,6 +115,11 @@ needs a material change.
92
115
  ### 5. Implement
93
116
 
94
117
  - Follow the plan; revise it if reality contradicts it.
118
+ - Execute only the assigned step and touch only files inside `Scope`. Report out-of-scope
119
+ findings; do not implement them.
120
+ - After approval, continue through the plan without asking for routine confirmation. Pause
121
+ only for a destructive or irreversible operation, data loss, critical security, a
122
+ requirement conflict, or an invalid plan.
95
123
  - Match existing patterns before adding abstractions.
96
124
  - Keep the diff scoped; no drive-by refactors.
97
125
  - Validate at boundaries, handle errors explicitly, no silent failures.
@@ -99,8 +127,8 @@ needs a material change.
99
127
  - Remove debug code, temp files, and commented-out blocks.
100
128
 
101
129
  **Stop and ask** if requirements conflict, the change affects auth/data/money without
102
- approval, a public contract has unknown consumers, unrelated tests fail, or you cannot
103
- verify the result.
130
+ approval, a public contract has unknown consumers, unrelated tests fail, a destructive
131
+ operation is needed without explicit authorization, or you cannot verify the result.
104
132
 
105
133
  ### 6. Verify
106
134
 
@@ -112,12 +140,15 @@ Use the strongest evidence available:
112
140
  4. End-to-end or manual: the actual user/system flow.
113
141
  5. Performance/security checks where relevant.
114
142
 
143
+ For a feature, the agreed end-to-end path must run and every golden and critical dark case must
144
+ have evidence or a declared gap. A green slice is not a finished feature.
145
+
115
146
  Report what ran, what passed, and what could not run. A skipped check is a known risk.
116
147
 
117
148
  ### 7. Review and report
118
149
 
119
- Read your own diff as a reviewer. Check for accidental changes, secrets, missing
120
- states, and stale docs. Then report:
150
+ Read your own diff as a reviewer. Check for accidental changes, secrets, out-of-scope edits,
151
+ missing states, and stale docs. Then report:
121
152
 
122
153
  ```markdown
123
154
  ## Delivered
@@ -141,9 +172,11 @@ Do not continue past these without clarification:
141
172
  - Requirements conflict or acceptance criteria are untestable.
142
173
  - Authentication, authorization, payments, personal data, or destructive migrations
143
174
  are involved without explicit approval.
175
+ - A destructive or irreversible operation is needed without the user's explicit authorization;
176
+ plan approval does not cover it.
144
177
  - A public contract must change and consumers are unknown.
145
178
  - Tests fail for reasons unrelated to the change.
146
- - The correct fix requires scope far beyond the request.
179
+ - The correct fix requires scope far beyond the request or outside `Scope`.
147
180
  - There is no way to verify the result.
148
181
 
149
182
  ## Quality bar
@@ -164,4 +197,7 @@ Do not continue past these without clarification:
164
197
  - Running tests but not reading the failures.
165
198
  - Claiming completion from memory instead of evidence.
166
199
  - Expanding scope without telling the user.
200
+ - Implementing an out-of-scope finding because it looks useful.
201
+ - Closing a feature with green slices but without the agreed end-to-end path.
202
+ - Deleting files or data without explicit user authorization.
167
203
  - Producing documents when the user asked for implementation.