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
|
@@ -1,119 +1,117 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: delivery-orchestration
|
|
3
|
-
description: Turn
|
|
3
|
+
description: Turn a goal into a sequence of working vertical slices with owners, WIP limits, and evidence. Use when coordinating multiple specialists, planning a milestone, or when a plan is growing faster than the code.
|
|
4
4
|
license: MIT
|
|
5
5
|
metadata:
|
|
6
|
-
version: "
|
|
6
|
+
version: "2.0.0"
|
|
7
7
|
author: development-companion
|
|
8
8
|
---
|
|
9
9
|
|
|
10
10
|
# Delivery Orchestration
|
|
11
11
|
|
|
12
|
-
The team lead routes work; specialists
|
|
13
|
-
|
|
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.
|
|
14
|
+
|
|
15
|
+
**Planning is not progress.** A plan that keeps growing without a commit is a risk, not an asset.
|
|
14
16
|
|
|
15
17
|
## When to use
|
|
16
18
|
|
|
17
19
|
- A project or milestone has more than one workstream.
|
|
18
20
|
- Several agents or people will edit the repository.
|
|
19
21
|
- There are dependencies between frontend, backend, security, QA, and deployment.
|
|
20
|
-
- The
|
|
22
|
+
- The plan is longer than the code.
|
|
21
23
|
|
|
22
24
|
## Inputs
|
|
23
25
|
|
|
24
|
-
-
|
|
25
|
-
-
|
|
26
|
-
- Test plan and threat model.
|
|
26
|
+
- One-page operational brief with the first slice and acceptance criteria.
|
|
27
|
+
- The decisions that actually block the first slice.
|
|
27
28
|
- Branch convention and release process.
|
|
28
29
|
- Team capacity and deadlines.
|
|
29
30
|
|
|
30
31
|
## Procedure
|
|
31
32
|
|
|
32
|
-
### 1.
|
|
33
|
+
### 1. Define the first vertical slice
|
|
33
34
|
|
|
34
|
-
|
|
35
|
+
A slice goes from the user's entry point to an observable result:
|
|
35
36
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
- migration;
|
|
40
|
-
- test suite;
|
|
41
|
-
- security report;
|
|
42
|
-
- deployment recipe.
|
|
37
|
+
```text
|
|
38
|
+
input → process → output
|
|
39
|
+
```
|
|
43
40
|
|
|
44
|
-
|
|
41
|
+
It touches every layer needed for that result. "Finish the domain first" is not a slice.
|
|
45
42
|
|
|
46
|
-
|
|
43
|
+
For the first slice, prefer a fake or fixture over a real dependency. The goal is to prove the
|
|
44
|
+
path, not the integration.
|
|
47
45
|
|
|
48
|
-
|
|
49
|
-
- Read-only work can run in parallel.
|
|
50
|
-
- Write-heavy work is serialized unless the boundaries are explicit.
|
|
51
|
-
- The reviewer or QA does not edit the code they verify.
|
|
46
|
+
### 2. Set the WIP limit
|
|
52
47
|
|
|
53
|
-
|
|
48
|
+
- **One slice per writer.**
|
|
49
|
+
- Parallel work only for read-only tasks or slices that touch disjoint files.
|
|
50
|
+
- Do not start the second slice until the first is green, committed, and demoed.
|
|
54
51
|
|
|
55
|
-
|
|
52
|
+
### 3. Order by risk, not by layer
|
|
56
53
|
|
|
57
|
-
1.
|
|
58
|
-
2.
|
|
59
|
-
3.
|
|
60
|
-
4.
|
|
61
|
-
5. security and QA verification;
|
|
62
|
-
6. deployment and smoke tests.
|
|
54
|
+
1. The assumption most likely to kill the product.
|
|
55
|
+
2. The integration most likely to break.
|
|
56
|
+
3. The user-visible path that unlocks feedback.
|
|
57
|
+
4. Polish and edge cases.
|
|
63
58
|
|
|
64
|
-
|
|
59
|
+
### 4. Write a one-page plan
|
|
65
60
|
|
|
66
|
-
|
|
61
|
+
Only what the next three slices need:
|
|
67
62
|
|
|
68
|
-
|
|
69
|
-
|
|
63
|
+
| Slice | Owner | Observable result | Verification | Depends on |
|
|
64
|
+
|---|---|---|---|---|
|
|
70
65
|
|
|
71
|
-
|
|
66
|
+
No task without an observable result. No owner without a file boundary. No gate without evidence.
|
|
72
67
|
|
|
73
|
-
|
|
68
|
+
### 5. Delegate for code, not documents
|
|
74
69
|
|
|
75
|
-
|
|
76
|
-
- artifact;
|
|
77
|
-
- evidence required;
|
|
78
|
-
- who accepts it.
|
|
70
|
+
Every handoff asks for:
|
|
79
71
|
|
|
80
|
-
|
|
72
|
+
- the smallest shippable outcome;
|
|
73
|
+
- code + tests + a command to reproduce it;
|
|
74
|
+
- files the child owns and files it must not touch;
|
|
75
|
+
- the evidence to return.
|
|
81
76
|
|
|
82
|
-
|
|
77
|
+
Reject a child that returns only a document when code was requested.
|
|
83
78
|
|
|
84
|
-
|
|
79
|
+
### 6. Verify and close the slice
|
|
85
80
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
**Deliverable:** ...
|
|
91
|
-
**Verification:** ...
|
|
92
|
-
**Do not:** ...
|
|
93
|
-
```
|
|
81
|
+
- Run the command yourself or read its output.
|
|
82
|
+
- Confirm the acceptance criteria are covered.
|
|
83
|
+
- Commit.
|
|
84
|
+
- Record one line in the delivery log: slice, commit, tests, next.
|
|
94
85
|
|
|
95
|
-
### 7.
|
|
86
|
+
### 7. Re-plan only when reality changes
|
|
96
87
|
|
|
97
|
-
- Update the plan when
|
|
88
|
+
- Update the plan when a slice reveals a wrong assumption.
|
|
89
|
+
- Do not re-plan to avoid a hard decision.
|
|
98
90
|
- Surface scope growth before implementing it.
|
|
99
|
-
- Keep a short status: done, in progress, blocked, next.
|
|
100
91
|
|
|
101
92
|
## Output
|
|
102
93
|
|
|
103
|
-
`.companion/local/06-delivery-plan.md
|
|
94
|
+
`.companion/local/06-delivery-plan.md`, maximum one page for the first three slices:
|
|
104
95
|
|
|
105
|
-
-
|
|
106
|
-
- owners;
|
|
107
|
-
-
|
|
108
|
-
-
|
|
109
|
-
-
|
|
110
|
-
-
|
|
111
|
-
- status and next checkpoint.
|
|
96
|
+
- first slice and acceptance criteria;
|
|
97
|
+
- owners and file boundaries;
|
|
98
|
+
- WIP limit and parallel tracks;
|
|
99
|
+
- verification per slice;
|
|
100
|
+
- risks and blocked decisions;
|
|
101
|
+
- status: last commit, tests, next slice.
|
|
112
102
|
|
|
113
103
|
## Verification
|
|
114
104
|
|
|
115
|
-
- Every
|
|
105
|
+
- Every slice has an observable result and a verification.
|
|
106
|
+
- The first slice is end-to-end, not a layer.
|
|
107
|
+
- The WIP limit is explicit.
|
|
116
108
|
- No two writers own the same files.
|
|
117
|
-
- The
|
|
118
|
-
|
|
119
|
-
-
|
|
109
|
+
- The plan fits on one page; if it does not, the scope is too broad.
|
|
110
|
+
|
|
111
|
+
## Anti-patterns
|
|
112
|
+
|
|
113
|
+
- **Horizontal plan:** domain, then API, then UI, then integration.
|
|
114
|
+
- **Planning loop:** a second plan before the first commit.
|
|
115
|
+
- **Ownerless work:** "the team" owns it, so nobody does.
|
|
116
|
+
- **Gate theater:** a phase marked done because its document exists.
|
|
117
|
+
- **Silent parallelism:** two writers on the same files.
|
|
@@ -146,6 +146,7 @@ Do not continue past these without clarification:
|
|
|
146
146
|
- Security, accessibility, and performance considered from the start.
|
|
147
147
|
- No secrets, debug output, or unrelated changes.
|
|
148
148
|
- Honest reporting of residual risk.
|
|
149
|
+
- A running increment or a named blocker. Documents alone are not delivery.
|
|
149
150
|
|
|
150
151
|
## Anti-patterns
|
|
151
152
|
|
|
@@ -156,3 +157,4 @@ Do not continue past these without clarification:
|
|
|
156
157
|
- Running tests but not reading the failures.
|
|
157
158
|
- Claiming completion from memory instead of evidence.
|
|
158
159
|
- Expanding scope without telling the user.
|
|
160
|
+
- Producing documents when the user asked for implementation.
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: incremental-delivery
|
|
3
|
+
description: Ship a working vertical slice instead of expanding the plan. Use when planning is growing faster than the code, when a project has documents but no running increment, or when a milestone needs to be cut into end-to-end slices.
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
version: "1.0.0"
|
|
7
|
+
author: development-companion
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Incremental Delivery
|
|
11
|
+
|
|
12
|
+
The failure mode this skill prevents: a project that has produced a stack of design documents
|
|
13
|
+
and still cannot be run. Planning feels like progress because it is easy to produce and hard
|
|
14
|
+
to falsify. Code is the opposite. Prefer the thing that can be falsified.
|
|
15
|
+
|
|
16
|
+
## When to use
|
|
17
|
+
|
|
18
|
+
- The plan is longer than the code.
|
|
19
|
+
- A milestone has many artifacts and no demo.
|
|
20
|
+
- Two consecutive sessions produced documents but no commit.
|
|
21
|
+
- A new feature is described as "the whole module" instead of one visible path.
|
|
22
|
+
- The user says "stop planning, start building".
|
|
23
|
+
|
|
24
|
+
## The rule
|
|
25
|
+
|
|
26
|
+
> **One slice at a time, end-to-end, running, tested, committed.**
|
|
27
|
+
|
|
28
|
+
A slice is vertical: it touches every layer needed to produce one visible result. It is not
|
|
29
|
+
"the domain layer" or "the API".
|
|
30
|
+
|
|
31
|
+
## Procedure
|
|
32
|
+
|
|
33
|
+
### 1. Cut the thinnest end-to-end slice
|
|
34
|
+
|
|
35
|
+
Start from the user's entry point and stop at the first observable result:
|
|
36
|
+
|
|
37
|
+
```text
|
|
38
|
+
input → process → output
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Examples:
|
|
42
|
+
|
|
43
|
+
- "Create a meeting from a fixture WAV and see a fake summary."
|
|
44
|
+
- "Record 10 seconds on the watch and see the file on the phone."
|
|
45
|
+
- "Load the meeting list from the database and open a detail screen."
|
|
46
|
+
|
|
47
|
+
If the slice needs a real model, a real service, or a full schema to be visible, replace it
|
|
48
|
+
with a fake or a fixture. Fakes are allowed in the skeleton; they are not allowed to become
|
|
49
|
+
the product.
|
|
50
|
+
|
|
51
|
+
### 2. Freeze the contract for the slice
|
|
52
|
+
|
|
53
|
+
Write only the interfaces and types the slice needs. Defer the rest. A contract that is not
|
|
54
|
+
used by running code is a guess.
|
|
55
|
+
|
|
56
|
+
### 3. Build in one pass
|
|
57
|
+
|
|
58
|
+
- Implement the smallest path.
|
|
59
|
+
- Add one test that proves it.
|
|
60
|
+
- Run it with one command.
|
|
61
|
+
- Commit.
|
|
62
|
+
|
|
63
|
+
No design system, no exhaustive error matrix, no performance tuning yet.
|
|
64
|
+
|
|
65
|
+
### 4. Demo and decide
|
|
66
|
+
|
|
67
|
+
Record the command and output. Then choose the next slice by risk:
|
|
68
|
+
|
|
69
|
+
1. The assumption most likely to kill the product.
|
|
70
|
+
2. The integration most likely to break.
|
|
71
|
+
3. The user-visible path that unlocks feedback.
|
|
72
|
+
|
|
73
|
+
### 5. Expand just in time
|
|
74
|
+
|
|
75
|
+
Add depth only when the slice demands it:
|
|
76
|
+
|
|
77
|
+
- error states when a failure is observed;
|
|
78
|
+
- architecture when a second adapter appears;
|
|
79
|
+
- abstractions when the third duplication appears;
|
|
80
|
+
- documentation when a decision becomes non-obvious.
|
|
81
|
+
|
|
82
|
+
## Planning budget
|
|
83
|
+
|
|
84
|
+
- Frame: 30–60 minutes, one page.
|
|
85
|
+
- Before the first running slice: ≤ 10–15 % of total effort.
|
|
86
|
+
- Any document that does not unblock the next slice is deferred.
|
|
87
|
+
- If a planning artifact exceeds two pages before the first commit, cut it.
|
|
88
|
+
|
|
89
|
+
## Definition of done for a slice
|
|
90
|
+
|
|
91
|
+
- [ ] It runs end-to-end.
|
|
92
|
+
- [ ] One command reproduces it.
|
|
93
|
+
- [ ] At least one automated test covers the path.
|
|
94
|
+
- [ ] It is committed.
|
|
95
|
+
- [ ] The demo is recorded (command output, screenshot, or request/response).
|
|
96
|
+
- [ ] Deferred work is written down, not silently dropped.
|
|
97
|
+
|
|
98
|
+
## Anti-patterns
|
|
99
|
+
|
|
100
|
+
- **Planning loop:** another discovery/architecture/UX cycle before the first commit.
|
|
101
|
+
- **Horizontal slicing:** "finish the domain first", "finish the schema first".
|
|
102
|
+
- **Fake as product:** the skeleton's fake survives into release without a decision.
|
|
103
|
+
- **Hidden integration:** every layer is "done" but nothing runs together.
|
|
104
|
+
- **Scope creep disguised as quality:** polishing a slice before proving the next one.
|
|
105
|
+
- **Documentation theater:** a 40-page spec for a 2-day slice.
|
|
106
|
+
|
|
107
|
+
## Escalation
|
|
108
|
+
|
|
109
|
+
If the slice cannot be cut small enough, say so with options:
|
|
110
|
+
|
|
111
|
+
- reduce scope;
|
|
112
|
+
- accept a fake for one dependency;
|
|
113
|
+
- split into two slices;
|
|
114
|
+
- stop and ask the user for a decision.
|
|
115
|
+
|
|
116
|
+
Do not respond to a blocked slice by writing more plan.
|
|
@@ -22,6 +22,15 @@ right problem with the right constraints. Ask before building.
|
|
|
22
22
|
For a small change inside a known system, use the short brief in
|
|
23
23
|
`development-workflow` instead.
|
|
24
24
|
|
|
25
|
+
## Timebox and stop rule
|
|
26
|
+
|
|
27
|
+
Discovery has a budget: **30–60 minutes and one page** in the first pass. Stop asking when the
|
|
28
|
+
first end-to-end slice and its acceptance criteria are defined and no blocking constraint is
|
|
29
|
+
open. Defer everything else to the slice that needs it.
|
|
30
|
+
|
|
31
|
+
Do not write a 500-line brief before the first commit. If the brief keeps growing, the slice is
|
|
32
|
+
too broad: cut it.
|
|
33
|
+
|
|
25
34
|
## Inputs
|
|
26
35
|
|
|
27
36
|
- The user's idea, goals, and constraints.
|
|
@@ -93,14 +102,25 @@ Write `.companion/local/01-operational-brief.md` with:
|
|
|
93
102
|
|
|
94
103
|
## Problem and users
|
|
95
104
|
## Goals and success metrics
|
|
96
|
-
##
|
|
97
|
-
|
|
105
|
+
## First end-to-end slice
|
|
106
|
+
- Input:
|
|
107
|
+
- Process:
|
|
108
|
+
- Observable output:
|
|
109
|
+
- Acceptance criteria:
|
|
110
|
+
## Scope
|
|
111
|
+
### In scope
|
|
112
|
+
### Out of scope
|
|
98
113
|
## Constraints
|
|
114
|
+
## Existing artifacts
|
|
99
115
|
## Hosting and third parties
|
|
100
|
-
## Data and
|
|
116
|
+
## Data and privacy
|
|
117
|
+
## Authentication and authorization
|
|
101
118
|
## Platforms
|
|
102
119
|
## Branch convention
|
|
103
120
|
## Definition of done
|
|
121
|
+
## Planning budget
|
|
122
|
+
- Time spent:
|
|
123
|
+
- Deferred decisions and the slice that will unblock them:
|
|
104
124
|
## Open questions
|
|
105
125
|
```
|
|
106
126
|
|
|
@@ -9,8 +9,13 @@ metadata:
|
|
|
9
9
|
|
|
10
10
|
# Test Strategy
|
|
11
11
|
|
|
12
|
-
QA enters
|
|
13
|
-
how it will be proven.
|
|
12
|
+
QA enters with the first slice, not after the whole plan. The test plan is a living contract for
|
|
13
|
+
what "working" means and how it will be proven.
|
|
14
|
+
|
|
15
|
+
## First tests before the full plan
|
|
16
|
+
|
|
17
|
+
Do not write a 300-line test plan before the first commit. Define the **first five tests** that
|
|
18
|
+
prove the walking skeleton and the riskiest failure path. Expand the plan as slices land.
|
|
14
19
|
|
|
15
20
|
## When to use
|
|
16
21
|
|
|
@@ -9,8 +9,13 @@ metadata:
|
|
|
9
9
|
|
|
10
10
|
# UX Design
|
|
11
11
|
|
|
12
|
-
The user approves the experience
|
|
13
|
-
|
|
12
|
+
The user approves the experience per slice. Design is validated with flows, states, and
|
|
13
|
+
screenshots, not with adjectives.
|
|
14
|
+
|
|
15
|
+
## Design the next screen, not the whole app
|
|
16
|
+
|
|
17
|
+
Design only the surfaces needed for the next slice. Reuse patterns; defer the design system until
|
|
18
|
+
the third repetition. Approval is per slice, not a one-time gate for every future screen.
|
|
14
19
|
|
|
15
20
|
## When to use
|
|
16
21
|
|
|
@@ -71,19 +76,44 @@ Target WCAG 2.2 AA unless the project states otherwise.
|
|
|
71
76
|
- Duration and easing; no decorative motion that blocks work.
|
|
72
77
|
- Reduced-motion alternative.
|
|
73
78
|
|
|
74
|
-
### 6.
|
|
79
|
+
### 6. Choose a design tool and produce mockups
|
|
80
|
+
|
|
81
|
+
Ask whether the user wants an existing Figma MCP integration, an installed FigCraft
|
|
82
|
+
CLI/app, or local HTML/SVG. Check availability before proposing an install: query the
|
|
83
|
+
harness for configured MCP tools, try `command -v figcraft-cli`, and on macOS check
|
|
84
|
+
`/Applications/FigCraft.app`. The macOS app binary is not the separate CLI. If FigCraft
|
|
85
|
+
is installed without the CLI, explain the difference and offer the official release:
|
|
86
|
+
<https://github.com/storytold/figcraft/releases/latest> (asset named
|
|
87
|
+
`figcraft-cli-<version>-<platform>`; on macOS `macos-universal.zip`). Check version
|
|
88
|
+
compatibility and verify the download when a checksum is available. Download/install
|
|
89
|
+
only after user consent; never fetch or run third-party binaries silently. Never handle
|
|
90
|
+
Figma tokens in the CLI or project rules. Use the harness's existing MCP connection when
|
|
91
|
+
available; do not assume it is configured.
|
|
75
92
|
|
|
76
93
|
Prefer local, reviewable artifacts:
|
|
77
94
|
|
|
78
95
|
- HTML/SVG wireframes in `.companion/local/mockups/`.
|
|
79
|
-
-
|
|
80
|
-
-
|
|
81
|
-
|
|
96
|
+
- Target-device screenshots (desktop and mobile only when both are relevant).
|
|
97
|
+
- An editable source file, layout/tokens and meaningful variants rather than PNGs alone.
|
|
98
|
+
|
|
99
|
+
### 7. Prototype the slice before approval
|
|
100
|
+
|
|
101
|
+
If the slice spans multiple screens, connect its primary action, back navigation, and
|
|
102
|
+
error/retry/empty branches with real prototype interactions (FigCraft prototype links,
|
|
103
|
+
Figma interactions, or a local interactive HTML equivalent). Open Play/presentation,
|
|
104
|
+
exercise each link and recovery path, and capture evidence. Do not mistake rendered
|
|
105
|
+
frames for a working prototype: if Play cannot navigate, explicitly report a static
|
|
106
|
+
mock and do not claim interactive validation. Record device size, starting screen,
|
|
107
|
+
tested transitions and missing branches. Keep interactions honest: prototypes simulate
|
|
108
|
+
the flow, not network calls, recording, authentication or persistent data.
|
|
82
109
|
|
|
83
|
-
###
|
|
110
|
+
### 8. Get approval
|
|
84
111
|
|
|
85
|
-
Present the flow, states, and
|
|
86
|
-
change. Do not start implementation from an unapproved mockup
|
|
112
|
+
Present the flow, states, screenshots, and prototype entry point. Ask for explicit
|
|
113
|
+
approval or a concrete change. Do not start implementation from an unapproved mockup;
|
|
114
|
+
after approval hand off the validated states and interactions to the implementation role
|
|
115
|
+
(frontend for web; mobile for native phone/watch), along with tokens and accessibility
|
|
116
|
+
requirements. Generated code is a starting point, not a verified implementation.
|
|
87
117
|
|
|
88
118
|
## Output
|
|
89
119
|
|
|
@@ -96,13 +126,15 @@ change. Do not start implementation from an unapproved mockup.
|
|
|
96
126
|
- accessibility checklist;
|
|
97
127
|
- motion specification;
|
|
98
128
|
- design tokens and components;
|
|
99
|
-
- mockup and screenshot references;
|
|
129
|
+
- editable mockup, prototype transitions and screenshot references;
|
|
100
130
|
- approval record.
|
|
101
131
|
|
|
102
132
|
## Verification
|
|
103
133
|
|
|
104
134
|
- All states are designed, not only the happy path.
|
|
105
135
|
- Keyboard and screen reader paths are described.
|
|
106
|
-
- Screenshots exist
|
|
136
|
+
- Screenshots exist for the target devices and required states.
|
|
137
|
+
- Play/presentation was exercised for the primary and recovery paths, or the
|
|
138
|
+
lack of interactive capability was reported explicitly.
|
|
107
139
|
- The user approved the design or requested specific changes.
|
|
108
140
|
- A vision-capable model reviewed the screenshots against the spec.
|