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/core/process.md CHANGED
@@ -1,224 +1,191 @@
1
1
  # Development Process
2
2
 
3
- This is the default process for a new project or a major change. It scales down for small
4
- changes; see `core/workflow.md`.
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 Operational discovery
12
- → 2 Architecture + security (in parallel)
13
- → 3 Test strategy
14
- → 4 UX/UI
15
- → 5 Delivery plan
16
- → 6 Implementation
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
- ## Phase 0 — Bootstrap
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
- ## Phase 2 — Architecture and security
18
+ > **A phase is complete when code runs, not when a document exists.**
59
19
 
60
- **Owner:** Architect. **Participant:** Cybersecurity Engineer, in parallel.
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
- Technical questions:
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
- - Assets, actors, entry points, trust boundaries.
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
- **Artifacts:** `.companion/local/02-architecture.md`,
82
- `.companion/local/03-threat-model.md`, and `adr/NNN-*.md`.
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:** stack and versions approved; boundaries and patterns recorded; threats have a
85
- control or an explicit acceptance; no architecture blocker remains.
37
+ **Gate:** `devcomp doctor` passes; existing rules were not lost.
86
38
 
87
- ## Phase 3 — Test strategy
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
- **Owner:** QA Engineer. **Participants:** Team Lead, Architect.
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
- - Golden paths, dark paths, and edge cases.
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
- **Artifact:** `.companion/local/04-test-plan.md`.
50
+ **Owner:** Team Lead. **Participant:** the user.
100
51
 
101
- **Gate:** every acceptance criterion maps to a test; critical failure paths are covered
102
- or explicitly accepted.
52
+ Answer only what can change the first slice:
103
53
 
104
- ## Phase 4 — UX/UI
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
- **Owner:** Frontend Engineer. **Participants:** the user, QA.
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
- - Flows and information architecture.
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
- **Artifact:** `.companion/local/05-ux-spec.md` plus mockups and screenshots.
66
+ **Gate:** the user confirms the first slice and its acceptance criteria; no blocking question
67
+ remains for that slice.
118
68
 
119
- **Gate:** the user approves the design; states and accessibility are covered.
69
+ **Timebox:** if the brief is not done in one work block, cut it to the five questions above.
120
70
 
121
- ## Phase 5 — Delivery plan
71
+ ## Phase 2 — Walking skeleton
122
72
 
123
- **Owner:** Team Lead. **Participants:** all specialists.
73
+ **Owner:** specialists. **Coordinator:** Team Lead.
124
74
 
125
- - Deliverables with owners.
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
- **Artifact:** `.companion/local/06-delivery-plan.md`.
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:** every task has an owner, an output, and a verification; no two writers own the
135
- same files.
82
+ **Gate:** the skeleton runs end-to-end; the command and the test are recorded; the commit
83
+ exists.
136
84
 
137
- ## Phase 6 — Implementation
85
+ ## Phase 3 — Slice loop
138
86
 
139
87
  **Owner:** specialists. **Coordinator:** Team Lead.
140
88
 
141
- - Contracts and schemas first.
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
- **Gate:** local checks pass; the diff is scoped; tests cover the new behavior.
91
+ For each slice:
150
92
 
151
- ## Phase 7 — Security verification
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
- **Owner:** Cybersecurity Engineer. **Participant:** implementers.
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
- - Update the threat model.
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
- **Artifact:** `.companion/local/07-security-report.md`.
105
+ ## Phase 4 — Verify
163
106
 
164
- **Gate:** no open critical or high findings; medium risks have an owner and a date.
107
+ **Owner:** Cybersecurity Engineer and QA Engineer. **Participant:** implementers.
165
108
 
166
- ## Phase 8 — QA verification
109
+ Verification is continuous, not a final phase:
167
110
 
168
- **Owner:** QA Engineer. **Participant:** implementers.
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
- - Functional and regression tests.
171
- - Golden/dark paths and edge cases.
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
- **Artifact:** `.companion/local/08-qa-report.md`.
119
+ ## Phase 5 — Release
178
120
 
179
- **Gate:** must-pass checks are green; known failures are documented; performance is within
180
- budget or explicitly accepted.
121
+ **Owner:** SRE Engineer. **Participants:** Team Lead, Cybersecurity.
181
122
 
182
- ## Phase 9 — Deployment
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
- **Owner:** SRE Engineer. **Participants:** Team Lead, Cybersecurity.
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
- - Docker/compose baseline; VPS with Dokploy or Coolify; cloud reference provider.
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
- **Artifact:** `.companion/local/09-runbook.md`.
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:** smoke tests pass; rollback is tested; secrets are outside the repo; monitoring is
196
- active.
140
+ **Gate:** the user accepts; no claim of "done" lacks evidence.
197
141
 
198
- ## Phase 10 — Closure
142
+ ## Artifacts: when to write them
199
143
 
200
- **Owner:** Team Lead. **Participants:** all.
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
- - What was delivered and why.
203
- - Evidence per gate.
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
- **Artifact:** `.companion/local/10-closure.md`.
159
+ ## Planning budget
209
160
 
210
- **Gate:** the user accepts; no claim of "done" lacks evidence; the repository is consistent.
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 → plan → implement → tests → self-review |
218
- | Cross-layer, data, auth, public contract | Full process + independent security and QA |
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.
@@ -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
- ## Process gates
87
+ ## Delivery gates
88
88
 
89
- For a new project or a major change, each phase in `core/process.md` has a gate:
89
+ For a new project or a major change, progress is gated by running code, not by documents:
90
90
 
91
- | Phase | Gate evidence |
91
+ | Gate | Evidence |
92
92
  |---|---|
93
- | Discovery | The user confirmed the operational brief; no blocking question. |
94
- | Architecture | Approved stack and versions, boundaries, ADRs, threat model. |
95
- | Test strategy | Every acceptance criterion maps to a test; failure paths covered. |
96
- | UX | Approved flows, states, screenshots, and accessibility checklist. |
97
- | Delivery plan | Owners, dependencies, gates, and branch convention recorded. |
98
- | Implementation | Local checks pass; diff scoped; new behavior tested. |
99
- | Security | No open critical/high findings; evidence per finding. |
100
- | QA | Must-pass checks green; load/a11y/visual evidence; known failures documented. |
101
- | Deployment | Smoke test in target; rollback tested; secrets outside repo. |
102
- | Closure | Evidence per gate; residual risks and handoff written. |
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
 
@@ -4,9 +4,10 @@
4
4
 
5
5
  ## Mission
6
6
 
7
- Own the process from request to verified closure. The user talks only to you. You frame
8
- the work, route it to specialists, enforce the gates, and report with evidence. You are a
9
- router and reviewer, not an implementer.
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 discovery, architecture, or delivery documents.
25
+ - Existing notes, ADRs, or delivery documents.
25
26
  - The branch convention and release process.
26
27
 
27
28
  ## Outputs
28
29
 
29
- - `.companion/local/01-operational-brief.md`
30
- - `.companion/local/06-delivery-plan.md`
31
- - `.companion/local/10-closure.md`
32
- - A verified completion report with evidence from the specialists.
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. **Discover** — ask the operational questions first; confirm scope, success, hosting,
37
- third parties, data, auth, platforms, branch convention, and definition of done.
38
- 2. **Frame** — state goal, non-goals, acceptance criteria, and constraints.
39
- 3. **Route** — choose the specialist for each deliverable and launch it with `subagent`.
40
- Launch independent specialists in parallel; serialize dependencies.
41
- 4. **Plan** — decompose into deliverables with owners, dependencies, and gates.
42
- 5. **Delegate** — give each specialist a bounded deliverable, context, and evidence
43
- requirement.
44
- 6. **Verify** — read the evidence, not the summary. If a child returns without proof, send
45
- it back with a bounded follow-up.
46
- 7. **Integrate** — resolve conflicts, prevent duplicate edits, keep the diff coherent.
47
- 8. **Close** — summarize delivered, verified, residual risks, and next steps.
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
- - Do not design the architecture, implement features, run tests, or run shell commands.
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 the
72
- `subagent` tool was called.
73
- - Do not start implementation before discovery and architecture are accepted.
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
- Use the `subagent` tool with:
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
- **Verification:** what evidence to return
88
- **Do not:** out-of-scope work, files to avoid
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 inside an existing system. For a new
4
- project or a major change, use `core/process.md` first: discovery, architecture, security,
5
- test strategy, UX, and a delivery plan come before implementation.
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "development-companion",
3
- "version": "1.2.1",
3
+ "version": "1.4.0",
4
4
  "description": "Harness-neutral development process, roles, and skills for AI coding agents.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -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.