development-companion 1.2.1 → 1.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +53 -32
- package/RELEASE.md +12 -9
- package/adapters/README.md +10 -2
- package/adapters/opencode/README.md +29 -32
- package/core/principles.md +21 -0
- package/core/process.md +126 -159
- package/core/quality-gates.md +21 -13
- package/core/roles/team-lead.md +50 -30
- package/core/workflow.md +16 -3
- package/package.json +1 -1
- package/skills/architecture-design/SKILL.md +7 -0
- package/skills/delivery-orchestration/SKILL.md +65 -67
- package/skills/development-workflow/SKILL.md +2 -0
- package/skills/incremental-delivery/SKILL.md +116 -0
- package/skills/project-discovery/SKILL.md +23 -3
- package/skills/test-strategy/SKILL.md +7 -2
- package/skills/ux-design/SKILL.md +43 -11
- package/src/cli.mjs +78 -26
- package/src/content.mjs +1 -0
- package/src/install.mjs +40 -33
- package/src/rules.mjs +31 -5
- package/templates/artifacts/01-operational-brief.md +17 -3
- package/templates/artifacts/06-delivery-plan.md +26 -5
- package/templates/rules/AGENTS.block.md +49 -18
package/core/process.md
CHANGED
|
@@ -1,224 +1,191 @@
|
|
|
1
1
|
# Development Process
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
The process is owned by the **Team Lead**. Each phase has an artifact in
|
|
7
|
-
`.companion/local/` and a gate that requires evidence.
|
|
3
|
+
The process exists to **ship working software**, not to produce documents. It is a loop, not a
|
|
4
|
+
waterfall. Planning is a tool that unblocks the next slice; when it stops doing that, it stops.
|
|
8
5
|
|
|
9
6
|
```text
|
|
10
7
|
0 Bootstrap
|
|
11
|
-
→ 1
|
|
12
|
-
→ 2
|
|
13
|
-
→ 3
|
|
14
|
-
→ 4
|
|
15
|
-
→ 5
|
|
16
|
-
→ 6
|
|
17
|
-
→ 7 Security verification
|
|
18
|
-
→ 8 QA verification
|
|
19
|
-
→ 9 Deployment
|
|
20
|
-
→ 10 Closure
|
|
8
|
+
→ 1 Frame (30–60 min, one page)
|
|
9
|
+
→ 2 Walking skeleton (end-to-end, fakes allowed)
|
|
10
|
+
→ 3 Slice loop (build → test → demo → next slice)
|
|
11
|
+
→ 4 Verify (security + QA, continuous)
|
|
12
|
+
→ 5 Release
|
|
13
|
+
→ 6 Close
|
|
21
14
|
```
|
|
22
15
|
|
|
23
|
-
##
|
|
24
|
-
|
|
25
|
-
**Owner:** CLI.
|
|
26
|
-
|
|
27
|
-
- Detect the repository, harness, package manager, profile, and branch convention.
|
|
28
|
-
- Install `AGENTS.md` and `CLAUDE.md` using keep, append, or replace.
|
|
29
|
-
- Install process skills, roles, and native bindings.
|
|
30
|
-
- Write `.companion/config.json` and ignore `.companion/local/`.
|
|
31
|
-
|
|
32
|
-
**Gate:** `devcomp doctor` passes; existing rules were not lost.
|
|
33
|
-
|
|
34
|
-
## Phase 1 — Operational discovery
|
|
35
|
-
|
|
36
|
-
**Owner:** Team Lead. **Participant:** the user.
|
|
37
|
-
|
|
38
|
-
Ask, one topic at a time:
|
|
39
|
-
|
|
40
|
-
- What problem, for whom, and why now?
|
|
41
|
-
- What does success look like, and how is it measured?
|
|
42
|
-
- What is in scope and out of scope for the first release?
|
|
43
|
-
- Are there existing repositories, prototypes, designs, or documents?
|
|
44
|
-
- Where will it run: on-prem, VPS, Dokploy, Coolify, cloud?
|
|
45
|
-
- Which third-party services, APIs, MCPs, or on-device capabilities are required?
|
|
46
|
-
- What data is stored, where, and for how long?
|
|
47
|
-
- What authentication is needed: local, OIDC, Firebase, other?
|
|
48
|
-
- Which platforms are targets?
|
|
49
|
-
- What are the deadline, team, budget, and maintenance constraints?
|
|
50
|
-
- Which branch convention is used: gitflow, GitLab flow, trunk-based, GitHub flow, custom?
|
|
51
|
-
Detect it, then ask the user to confirm.
|
|
52
|
-
- What does "done" mean?
|
|
53
|
-
|
|
54
|
-
**Artifact:** `.companion/local/01-operational-brief.md`.
|
|
55
|
-
|
|
56
|
-
**Gate:** the user confirms the brief; no blocking operational question remains.
|
|
16
|
+
## The delivery rule
|
|
57
17
|
|
|
58
|
-
|
|
18
|
+
> **A phase is complete when code runs, not when a document exists.**
|
|
59
19
|
|
|
60
|
-
|
|
20
|
+
- The first commit must land in the first work block, before the second design document.
|
|
21
|
+
- Every session ends with one of: a running increment, a failing test that defines the next
|
|
22
|
+
step, or a named blocker that needs the user.
|
|
23
|
+
- A planning artifact is written **just in time**, only as deep as the next slice needs.
|
|
24
|
+
- A document that does not unblock code is deferred, not expanded.
|
|
61
25
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
- Stack and versions: verify the latest stable release.
|
|
65
|
-
- Monorepo or single repo? Which workspace tool?
|
|
66
|
-
- Monolith, modular monolith, or microservices? Why?
|
|
67
|
-
- Layered, hexagonal, or tactical DDD?
|
|
68
|
-
- Data stores, schema, migrations.
|
|
69
|
-
- AuthN/AuthZ, tenancy, secrets.
|
|
70
|
-
- Integrations, queues, events, webhooks, idempotency.
|
|
71
|
-
- Deployment, observability, backups, rollback.
|
|
72
|
-
- Performance budget and expected load.
|
|
73
|
-
|
|
74
|
-
Security, in parallel:
|
|
26
|
+
## Phase 0 — Bootstrap
|
|
75
27
|
|
|
76
|
-
|
|
77
|
-
- Threat model and top risks.
|
|
78
|
-
- Controls and accepted risks.
|
|
79
|
-
- Relevant CVEs and supply-chain concerns.
|
|
28
|
+
**Owner:** native harness agent, assisted by the CLI.
|
|
80
29
|
|
|
81
|
-
|
|
82
|
-
|
|
30
|
+
- Detect repository, harness, package manager, profile, and branch convention.
|
|
31
|
+
- Install `AGENTS.md`, `CLAUDE.md`, skills, roles, and bindings.
|
|
32
|
+
- Write `.companion/config.json` and ignore `.companion/local/`.
|
|
33
|
+
- When rules already exist, the harness agent reviews them and merges process obligations
|
|
34
|
+
with project-specific facts and tools. A CLI handoff is only a backed-up pending merge;
|
|
35
|
+
`doctor` must fail until the agent finishes it. Do not silently append conflicting rules.
|
|
83
36
|
|
|
84
|
-
**Gate:**
|
|
85
|
-
control or an explicit acceptance; no architecture blocker remains.
|
|
37
|
+
**Gate:** `devcomp doctor` passes; existing rules were not lost.
|
|
86
38
|
|
|
87
|
-
|
|
39
|
+
Install the canonical process, principles, workflow, quality gates, and guidelines in
|
|
40
|
+
`.companion/core/`. Existing project rules or harness configuration are preserved; a
|
|
41
|
+
diagnostic failure must be resolved before treating the process as active. Run `doctor`
|
|
42
|
+
from the repository that the agent actually opens, including a nested app repository.
|
|
88
43
|
|
|
89
|
-
|
|
44
|
+
Artifact paths below use `.companion/local/` by default. When the installation is configured
|
|
45
|
+
with `--docs tracked`, use `docs/companion/` instead; the configured path overrides examples
|
|
46
|
+
in roles and skills.
|
|
90
47
|
|
|
91
|
-
|
|
92
|
-
- Test levels and tools.
|
|
93
|
-
- Data, fixtures, and environments.
|
|
94
|
-
- Load/stress scenario, budgets, and target environment.
|
|
95
|
-
- Accessibility, visual, and cross-platform checks.
|
|
96
|
-
- Security checks.
|
|
97
|
-
- Evidence format and exit criteria.
|
|
48
|
+
## Phase 1 — Frame (30–60 minutes, one page)
|
|
98
49
|
|
|
99
|
-
**
|
|
50
|
+
**Owner:** Team Lead. **Participant:** the user.
|
|
100
51
|
|
|
101
|
-
|
|
102
|
-
or explicitly accepted.
|
|
52
|
+
Answer only what can change the first slice:
|
|
103
53
|
|
|
104
|
-
|
|
54
|
+
1. What problem, for whom, and what observable outcome proves success?
|
|
55
|
+
2. What is the **first end-to-end slice**? (Not the whole product.)
|
|
56
|
+
3. What constraints could invalidate that slice: platform, data, auth, privacy, performance,
|
|
57
|
+
third parties, deadline?
|
|
58
|
+
4. What is explicitly out of scope for this slice?
|
|
59
|
+
5. Which decisions are irreversible and need the user now?
|
|
105
60
|
|
|
106
|
-
|
|
61
|
+
Everything else is deferred. Stack details, full schemas, complete UX, and exhaustive test
|
|
62
|
+
matrices are decided when the slice needs them.
|
|
107
63
|
|
|
108
|
-
-
|
|
109
|
-
- Wireframes or mockups in `.companion/local/mockups/`.
|
|
110
|
-
- States: loading, empty, error, unauthorized, offline, retry, success.
|
|
111
|
-
- Responsive breakpoints and behavior.
|
|
112
|
-
- Accessibility: keyboard, focus, labels, contrast, reduced motion.
|
|
113
|
-
- Motion with purpose.
|
|
114
|
-
- Design tokens and components.
|
|
115
|
-
- Screenshots at desktop and mobile widths.
|
|
64
|
+
**Artifact:** `.companion/local/01-operational-brief.md`, maximum one page.
|
|
116
65
|
|
|
117
|
-
**
|
|
66
|
+
**Gate:** the user confirms the first slice and its acceptance criteria; no blocking question
|
|
67
|
+
remains for that slice.
|
|
118
68
|
|
|
119
|
-
**
|
|
69
|
+
**Timebox:** if the brief is not done in one work block, cut it to the five questions above.
|
|
120
70
|
|
|
121
|
-
## Phase
|
|
71
|
+
## Phase 2 — Walking skeleton
|
|
122
72
|
|
|
123
|
-
**Owner:**
|
|
73
|
+
**Owner:** specialists. **Coordinator:** Team Lead.
|
|
124
74
|
|
|
125
|
-
|
|
126
|
-
- Dependencies and critical path.
|
|
127
|
-
- Parallel vs serial work.
|
|
128
|
-
- Branch and release flow.
|
|
129
|
-
- Gates and evidence.
|
|
130
|
-
- Risks and mitigations.
|
|
75
|
+
Build the thinnest path that goes from the user's entry point to a visible result:
|
|
131
76
|
|
|
132
|
-
|
|
77
|
+
- Real process boundaries, fake or trivial implementations where the real one is expensive.
|
|
78
|
+
- One command to run it; one test that proves the path.
|
|
79
|
+
- Commit as soon as it runs, even if ugly.
|
|
80
|
+
- No design system, no full schema, no exhaustive error handling yet.
|
|
133
81
|
|
|
134
|
-
**Gate:**
|
|
135
|
-
|
|
82
|
+
**Gate:** the skeleton runs end-to-end; the command and the test are recorded; the commit
|
|
83
|
+
exists.
|
|
136
84
|
|
|
137
|
-
## Phase
|
|
85
|
+
## Phase 3 — Slice loop
|
|
138
86
|
|
|
139
87
|
**Owner:** specialists. **Coordinator:** Team Lead.
|
|
140
88
|
|
|
141
|
-
-
|
|
142
|
-
- Tests alongside behavior; TDD if the project chose it.
|
|
143
|
-
- Small, reversible changes.
|
|
144
|
-
- Domain independent from infrastructure.
|
|
145
|
-
- No secrets, debug output, or dead code.
|
|
146
|
-
- Update ADRs when reality contradicts the plan.
|
|
147
|
-
- Self-review before requesting verification.
|
|
89
|
+
Pick the **highest-risk or highest-value slice** and finish it before starting another.
|
|
148
90
|
|
|
149
|
-
|
|
91
|
+
For each slice:
|
|
150
92
|
|
|
151
|
-
|
|
93
|
+
1. State the acceptance criteria (one or two observable sentences).
|
|
94
|
+
2. Implement the smallest coherent change.
|
|
95
|
+
3. Add or update tests with the behavior.
|
|
96
|
+
4. Demo it with a command, a screenshot, or a request/response.
|
|
97
|
+
5. Commit.
|
|
98
|
+
6. Update the living notes only where reality changed a decision.
|
|
152
99
|
|
|
153
|
-
**
|
|
100
|
+
**WIP limit: one slice per writer.** Parallelism is allowed only for read-only work or for
|
|
101
|
+
slices that touch disjoint files.
|
|
154
102
|
|
|
155
|
-
|
|
156
|
-
- OWASP ASVS as a reference, not a checklist ritual.
|
|
157
|
-
- SAST, dependency audit, secret scanning, container/configuration scanning.
|
|
158
|
-
- Test authn, authz, sessions, uploads, payments, webhooks, rate limits.
|
|
159
|
-
- Report every finding with reproducible evidence.
|
|
160
|
-
- Re-test fixes.
|
|
103
|
+
**Gate:** acceptance criteria are covered by evidence; the diff is scoped; the commit exists.
|
|
161
104
|
|
|
162
|
-
|
|
105
|
+
## Phase 4 — Verify
|
|
163
106
|
|
|
164
|
-
**
|
|
107
|
+
**Owner:** Cybersecurity Engineer and QA Engineer. **Participant:** implementers.
|
|
165
108
|
|
|
166
|
-
|
|
109
|
+
Verification is continuous, not a final phase:
|
|
167
110
|
|
|
168
|
-
|
|
111
|
+
- Security review of each new trust boundary, secret, permission, or data flow.
|
|
112
|
+
- Tests at the level the risk requires: unit for rules, integration for boundaries, one
|
|
113
|
+
end-to-end path for the slice.
|
|
114
|
+
- A real-device or real-environment check before release, not only emulators.
|
|
169
115
|
|
|
170
|
-
-
|
|
171
|
-
|
|
172
|
-
- Load/stress evidence in a target-like environment.
|
|
173
|
-
- Accessibility and visual review against the mockup.
|
|
174
|
-
- Cross-platform and responsive checks.
|
|
175
|
-
- Every failure with reproduction and evidence; fixes are re-verified.
|
|
116
|
+
**Gate for release:** no open critical/high findings; must-pass checks green; known failures
|
|
117
|
+
documented; residual risk accepted by the user.
|
|
176
118
|
|
|
177
|
-
|
|
119
|
+
## Phase 5 — Release
|
|
178
120
|
|
|
179
|
-
**
|
|
180
|
-
budget or explicitly accepted.
|
|
121
|
+
**Owner:** SRE Engineer. **Participants:** Team Lead, Cybersecurity.
|
|
181
122
|
|
|
182
|
-
|
|
123
|
+
- Version, changelog, signing, and install/upgrade path.
|
|
124
|
+
- Rollback or roll-forward plan.
|
|
125
|
+
- Smoke test in the target environment.
|
|
126
|
+
- Secrets outside the repository.
|
|
183
127
|
|
|
184
|
-
**
|
|
128
|
+
**Gate:** the release artifact is installed and exercised in the target; rollback is tested or
|
|
129
|
+
explicitly accepted.
|
|
130
|
+
|
|
131
|
+
## Phase 6 — Close
|
|
185
132
|
|
|
186
|
-
|
|
187
|
-
- Secrets in the target manager; never in the repository.
|
|
188
|
-
- Migrations with a tested rollback.
|
|
189
|
-
- Healthchecks, logs, metrics, traces, alerts.
|
|
190
|
-
- Smoke tests against the real target.
|
|
191
|
-
- Performance evidence in the target environment.
|
|
133
|
+
**Owner:** Team Lead.
|
|
192
134
|
|
|
193
|
-
|
|
135
|
+
- What shipped, with evidence.
|
|
136
|
+
- What was deferred and why.
|
|
137
|
+
- Residual risks and next slice.
|
|
138
|
+
- A short completion report, not a novel.
|
|
194
139
|
|
|
195
|
-
**Gate:**
|
|
196
|
-
active.
|
|
140
|
+
**Gate:** the user accepts; no claim of "done" lacks evidence.
|
|
197
141
|
|
|
198
|
-
##
|
|
142
|
+
## Artifacts: when to write them
|
|
199
143
|
|
|
200
|
-
|
|
144
|
+
| Artifact | When | Maximum before the first commit |
|
|
145
|
+
|---|---|---|
|
|
146
|
+
| Operational brief | Frame | 1 page |
|
|
147
|
+
| Architecture notes / ADRs | When a decision blocks a slice | 1 page per ADR |
|
|
148
|
+
| Threat model | When a trust boundary or sensitive data appears | The slice's threats only |
|
|
149
|
+
| Test plan | With the first tests | The first 5 tests |
|
|
150
|
+
| UX spec / mockups | Before the first UI slice | The next screen only |
|
|
151
|
+
| Delivery plan | First slice + next 3 | 1 page |
|
|
152
|
+
| Security report | Before release | Findings only |
|
|
153
|
+
| QA report | Before release | Evidence only |
|
|
154
|
+
| Runbook | Before deployment | The deploy path only |
|
|
201
155
|
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
- Residual risks and accepted debt.
|
|
205
|
-
- Runbook and handoff.
|
|
206
|
-
- Next steps.
|
|
156
|
+
These are **living notes**, not phase gates. If a document grows past its limit before the
|
|
157
|
+
first commit, cut it or defer it.
|
|
207
158
|
|
|
208
|
-
|
|
159
|
+
## Planning budget
|
|
209
160
|
|
|
210
|
-
|
|
161
|
+
- Frame: 30–60 minutes, one page.
|
|
162
|
+
- Total planning before the first end-to-end slice: **≤ 10–15 % of the effort**.
|
|
163
|
+
- Every planning artifact must name the slice it unblocks. If it cannot, defer it.
|
|
164
|
+
- A second planning cycle on the same topic is a smell: decide, build, and let the code
|
|
165
|
+
answer the question.
|
|
211
166
|
|
|
212
167
|
## Scaling down
|
|
213
168
|
|
|
214
169
|
| Change | Process |
|
|
215
170
|
|---|---|
|
|
216
171
|
| Typo, docs, one-line fix | Recon → change → check → report |
|
|
217
|
-
| Feature in one layer | Brief →
|
|
218
|
-
| Cross-layer, data, auth, public contract |
|
|
172
|
+
| Feature in one layer | Brief → implement → tests → self-review |
|
|
173
|
+
| Cross-layer, data, auth, public contract | Frame → skeleton or thin slice → tests → independent security/QA |
|
|
174
|
+
| New project | Frame (1 page) → walking skeleton → slice loop |
|
|
219
175
|
| Incident | Stabilize → diagnose → fix → regression test → short postmortem |
|
|
220
176
|
|
|
221
177
|
## Evidence
|
|
222
178
|
|
|
223
179
|
A gate is not closed by a narrative. It is closed by a command and its output, a test, a
|
|
224
180
|
request, a screenshot, a CVE, or a metric. See `core/quality-gates.md`.
|
|
181
|
+
|
|
182
|
+
## Anti-patterns
|
|
183
|
+
|
|
184
|
+
- **Planning loop:** producing a third document before the first commit.
|
|
185
|
+
- **Big-bang integration:** building every layer before proving one path.
|
|
186
|
+
- **Architecture astronaut:** designing for scale that the product does not have.
|
|
187
|
+
- **Demo debt:** a skeleton that only runs in a notebook, not in the repo.
|
|
188
|
+
- **Phase theater:** marking a phase "done" because its document exists.
|
|
189
|
+
- **Silent scope growth:** adding a second slice before finishing the first.
|
|
190
|
+
|
|
191
|
+
If two consecutive work sessions produce no running code, stop and escalate to the user.
|
package/core/quality-gates.md
CHANGED
|
@@ -84,22 +84,30 @@ Every change, regardless of type:
|
|
|
84
84
|
- [ ] Monitoring and alerts cover the release.
|
|
85
85
|
- [ ] The release was verified in an environment that resembles production.
|
|
86
86
|
|
|
87
|
-
##
|
|
87
|
+
## Delivery gates
|
|
88
88
|
|
|
89
|
-
For a new project or a major change,
|
|
89
|
+
For a new project or a major change, progress is gated by running code, not by documents:
|
|
90
90
|
|
|
91
|
-
|
|
|
91
|
+
| Gate | Evidence |
|
|
92
92
|
|---|---|
|
|
93
|
-
|
|
|
94
|
-
|
|
|
95
|
-
|
|
|
96
|
-
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
93
|
+
| Frame | One-page brief: problem, first slice, acceptance criteria, constraints; user confirms. |
|
|
94
|
+
| Walking skeleton | The end-to-end path runs with fakes; one command; one test; a commit. |
|
|
95
|
+
| Slice | Acceptance criteria covered by tests; scoped diff; a demo; a commit. |
|
|
96
|
+
| Release | No open critical/high findings; must-pass checks green; install/upgrade verified in the target. |
|
|
97
|
+
|
|
98
|
+
A planning artifact is not a gate. It is a living note that unblocks a slice. See
|
|
99
|
+
`core/process.md`.
|
|
100
|
+
|
|
101
|
+
### Session gate
|
|
102
|
+
|
|
103
|
+
Before ending a work session, answer:
|
|
104
|
+
|
|
105
|
+
- [ ] Did I produce a running increment, a failing test, or a named blocker?
|
|
106
|
+
- [ ] Is it committed or handed off with the exact next command?
|
|
107
|
+
- [ ] If I only produced documents, did the user ask for documents?
|
|
108
|
+
|
|
109
|
+
A session that produced only documents, when the user asked for implementation, is a process
|
|
110
|
+
failure. Report it and correct course before adding more planning.
|
|
103
111
|
|
|
104
112
|
## Security and secrets
|
|
105
113
|
|
package/core/roles/team-lead.md
CHANGED
|
@@ -4,9 +4,10 @@
|
|
|
4
4
|
|
|
5
5
|
## Mission
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
7
|
+
Ship working increments. When you own coordination, frame the smallest valuable slice, route
|
|
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 may
|
|
10
|
+
follow this contract with its own tools; a callable team-lead specialist reports to that primary.
|
|
10
11
|
|
|
11
12
|
## Use when
|
|
12
13
|
|
|
@@ -21,30 +22,38 @@ Do not use for a one-file fix or a routine review; handle those directly.
|
|
|
21
22
|
|
|
22
23
|
- The user's request and constraints.
|
|
23
24
|
- The repository and its conventions.
|
|
24
|
-
- Existing
|
|
25
|
+
- Existing notes, ADRs, or delivery documents.
|
|
25
26
|
- The branch convention and release process.
|
|
26
27
|
|
|
27
28
|
## Outputs
|
|
28
29
|
|
|
29
|
-
-
|
|
30
|
-
- `.companion/local/
|
|
31
|
-
- `.companion/local/
|
|
32
|
-
-
|
|
30
|
+
- A **running increment** in the repository (commit + tests + evidence).
|
|
31
|
+
- `.companion/local/01-operational-brief.md` — one page, first slice only.
|
|
32
|
+
- `.companion/local/06-delivery-plan.md` — first slice and next three, one page.
|
|
33
|
+
- `.companion/local/10-closure.md` — what shipped, what was deferred, evidence.
|
|
33
34
|
|
|
34
35
|
## Operating checklist
|
|
35
36
|
|
|
36
|
-
1. **
|
|
37
|
-
|
|
38
|
-
2. **
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
6. **
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
37
|
+
1. **Frame (≤ 1 work block)** — five questions: problem, first end-to-end slice, constraints,
|
|
38
|
+
non-goals, irreversible decisions. Write one page. Stop.
|
|
39
|
+
2. **Prove the path** — delegate a walking skeleton with fakes where needed. It must run with
|
|
40
|
+
one command and have one test. Commit.
|
|
41
|
+
3. **Slice loop** — pick the highest-risk or highest-value slice; one writer per slice; require
|
|
42
|
+
implementation, tests, and a demo.
|
|
43
|
+
4. **Verify** — security and QA review the slice, not a document. Read evidence, not summaries.
|
|
44
|
+
5. **Next slice** — only after the previous one is green and committed.
|
|
45
|
+
6. **Close** — what shipped, what was deferred, residual risk, next slice.
|
|
46
|
+
|
|
47
|
+
## Definition of progress
|
|
48
|
+
|
|
49
|
+
Progress is one of:
|
|
50
|
+
|
|
51
|
+
- a green build with a new end-to-end path;
|
|
52
|
+
- a merged slice with tests and a demo;
|
|
53
|
+
- a release artifact verified in the target.
|
|
54
|
+
|
|
55
|
+
A document is progress only when it unblocks a slice that is about to be built. Otherwise it
|
|
56
|
+
is inventory.
|
|
48
57
|
|
|
49
58
|
## Routing
|
|
50
59
|
|
|
@@ -65,28 +74,39 @@ Do not use for a one-file fix or a routine review; handle those directly.
|
|
|
65
74
|
|
|
66
75
|
## Boundaries
|
|
67
76
|
|
|
68
|
-
-
|
|
77
|
+
- As a dedicated coordination subagent, do not design the architecture, implement features,
|
|
78
|
+
run tests, or run shell commands. The native primary retains its normal capabilities and
|
|
79
|
+
may implement a focused slice directly while following these delivery gates.
|
|
69
80
|
- Do not edit code. Your only writable paths are `.companion/local/**` and
|
|
70
81
|
`docs/companion/**`.
|
|
71
|
-
- Do not claim a delegation you did not perform. A delegation is real only if
|
|
72
|
-
|
|
73
|
-
|
|
82
|
+
- Do not claim a delegation you did not perform. A delegation is real only if a native
|
|
83
|
+
delegation tool launched another agent; otherwise describe the work as a single-agent role
|
|
84
|
+
switch or manual handoff.
|
|
85
|
+
- **Do not spend more than one work block producing planning artifacts before the first
|
|
86
|
+
commit.**
|
|
87
|
+
- **Do not accept a child that returns only a document when code was requested.** Send it back
|
|
88
|
+
with a bounded instruction to implement.
|
|
89
|
+
- **Stop the line:** if two consecutive delegations produce no running code, stop and tell the
|
|
90
|
+
user what is blocking, with options.
|
|
74
91
|
- Do not expand scope silently; surface the trade-off.
|
|
75
92
|
- Do not accept a high-risk change without independent security and QA verification.
|
|
76
93
|
- Do not let two writers own the same files.
|
|
77
94
|
|
|
78
95
|
## Handoff
|
|
79
96
|
|
|
80
|
-
|
|
97
|
+
Where the harness supports native subagents, launch one with:
|
|
81
98
|
|
|
82
99
|
```markdown
|
|
83
100
|
**Role:** architect | cybersecurity | qa | frontend | backend | mobile | platform | sre
|
|
84
|
-
**Goal:**
|
|
101
|
+
**Goal:** the smallest shippable outcome
|
|
85
102
|
**Context:** files, decisions, constraints
|
|
86
|
-
**Deliverable:**
|
|
87
|
-
**
|
|
88
|
-
**
|
|
103
|
+
**Deliverable:** code + tests + evidence (not a document, unless explicitly requested)
|
|
104
|
+
**Slice:** what must work end-to-end when this returns
|
|
105
|
+
**Verification:** command to run and output to return
|
|
106
|
+
**Do not:** out-of-scope work, files to avoid, planning expansion
|
|
89
107
|
```
|
|
90
108
|
|
|
91
|
-
After the child returns, verify the evidence and either accept it or send a follow-up.
|
|
109
|
+
After the child returns, verify the evidence and either accept it or send a follow-up. Reject
|
|
110
|
+
"done" without a commit, a test, or a reproducible demo.
|
|
111
|
+
|
|
92
112
|
Close with the completion format in the `development-workflow` skill.
|
package/core/workflow.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# Development Workflow
|
|
2
2
|
|
|
3
|
-
This is the default path for an individual change
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
This is the default path for an individual change. For a new project, do **not** run the full
|
|
4
|
+
planning sequence first: frame the first slice in one page, build a walking skeleton, then use
|
|
5
|
+
this workflow per slice. See `core/process.md` and the `incremental-delivery` skill.
|
|
6
6
|
|
|
7
7
|
It scales with risk: a typo fix needs a short version; a cross-layer feature needs the full
|
|
8
8
|
version.
|
|
@@ -23,6 +23,19 @@ Identify the task type and the minimum rigor it needs.
|
|
|
23
23
|
If the task mixes types, split it. Do not ship a refactor and a behavior change in
|
|
24
24
|
the same unreviewable diff.
|
|
25
25
|
|
|
26
|
+
**First-commit rule:** for a new feature or project, create the thinnest runnable path before
|
|
27
|
+
expanding the design. A plan that does not produce a commit is not progress.
|
|
28
|
+
|
|
29
|
+
## Phase 0.5 — First commit
|
|
30
|
+
|
|
31
|
+
Before deep recon or a full plan, ask: *what is the smallest end-to-end path that can run?*
|
|
32
|
+
|
|
33
|
+
- Wire the real entry point to a fake or minimal implementation.
|
|
34
|
+
- Get one command and one test working.
|
|
35
|
+
- Commit.
|
|
36
|
+
|
|
37
|
+
Then use the rest of this workflow to deepen that path slice by slice.
|
|
38
|
+
|
|
26
39
|
## Phase 1 — Recon
|
|
27
40
|
|
|
28
41
|
Understand the system before proposing changes.
|
package/package.json
CHANGED
|
@@ -21,6 +21,13 @@ keep the domain independent, and record why.
|
|
|
21
21
|
|
|
22
22
|
Do not use for a local refactor that preserves boundaries.
|
|
23
23
|
|
|
24
|
+
## Minimum viable architecture
|
|
25
|
+
|
|
26
|
+
Architecture is validated by running code, not by review volume. Decide only what blocks the
|
|
27
|
+
next slice; defer reversible choices until a second adapter or a real constraint appears. Write
|
|
28
|
+
one-page ADRs. A second architecture cycle before the first commit is a red flag: build the
|
|
29
|
+
skeleton and let it falsify the design.
|
|
30
|
+
|
|
24
31
|
## Inputs
|
|
25
32
|
|
|
26
33
|
- The operational brief and success criteria.
|