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.
@@ -1,119 +1,117 @@
1
1
  ---
2
2
  name: delivery-orchestration
3
- description: Turn discovery, architecture, and test strategy into a sequenced delivery plan with owners, gates, parallel work, and handoffs. Use when coordinating multiple specialists, planning a milestone, or deciding what can run in parallel.
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: "1.0.0"
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 do the deep work. A plan is useful only if every
13
- task has an owner, an output, and a way to verify it.
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 work is large enough that "just start coding" would create rework.
22
+ - The plan is longer than the code.
21
23
 
22
24
  ## Inputs
23
25
 
24
- - Operational brief.
25
- - Architecture and ADRs.
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. Decompose by deliverable
33
+ ### 1. Define the first vertical slice
33
34
 
34
- Each task should produce something observable:
35
+ A slice goes from the user's entry point to an observable result:
35
36
 
36
- - contract or schema;
37
- - endpoint or use case;
38
- - screen or flow;
39
- - migration;
40
- - test suite;
41
- - security report;
42
- - deployment recipe.
37
+ ```text
38
+ input → process → output
39
+ ```
43
40
 
44
- Avoid tasks like "work on backend".
41
+ It touches every layer needed for that result. "Finish the domain first" is not a slice.
45
42
 
46
- ### 2. Define ownership
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
- - One owner per file or module at a time.
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
- ### 3. Sequence
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
- Critical path first:
52
+ ### 3. Order by risk, not by layer
56
53
 
57
- 1. contracts and schemas;
58
- 2. domain and use cases;
59
- 3. infrastructure adapters;
60
- 4. delivery (HTTP/UI);
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
- Mark what can run in parallel and what must wait.
59
+ ### 4. Write a one-page plan
65
60
 
66
- ### 4. Use the branch convention
61
+ Only what the next three slices need:
67
62
 
68
- Apply the project's convention: branch names, base branch, PR/MR flow, release branches,
69
- hotfixes. Do not impose a different model.
63
+ | Slice | Owner | Observable result | Verification | Depends on |
64
+ |---|---|---|---|---|
70
65
 
71
- ### 5. Define gates
66
+ No task without an observable result. No owner without a file boundary. No gate without evidence.
72
67
 
73
- For each phase, state:
68
+ ### 5. Delegate for code, not documents
74
69
 
75
- - entry condition;
76
- - artifact;
77
- - evidence required;
78
- - who accepts it.
70
+ Every handoff asks for:
79
71
 
80
- No gate is "the agent said it is done".
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
- ### 6. Plan handoffs
77
+ Reject a child that returns only a document when code was requested.
83
78
 
84
- Every handoff includes:
79
+ ### 6. Verify and close the slice
85
80
 
86
- ```markdown
87
- **Role:** ...
88
- **Goal:** ...
89
- **Context:** files, decisions, constraints
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. Track and re-plan
86
+ ### 7. Re-plan only when reality changes
96
87
 
97
- - Update the plan when reality changes.
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` with:
94
+ `.companion/local/06-delivery-plan.md`, maximum one page for the first three slices:
104
95
 
105
- - milestones and tasks;
106
- - owners;
107
- - dependencies and parallel tracks;
108
- - branch and release flow;
109
- - gates and evidence;
110
- - risks and mitigations;
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 task has an owner, an output, and a verification.
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 critical path is explicit.
118
- - The branch convention is respected.
119
- - Blocked items have a named decision owner.
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
- ## Scope and non-goals
97
- ## Existing artifacts
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 auth
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 before development. The test plan is the contract for what "working" means and
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 before the team builds it. Design is validated with
13
- flows, states, and screenshots, not with adjectives.
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. Produce mockups
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
- - Screenshots at desktop and mobile widths.
80
- - Optional Figma integration via MCP when the user already works there. The CLI never
81
- handles Figma tokens.
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
- ### 7. Get approval
110
+ ### 8. Get approval
84
111
 
85
- Present the flow, states, and screenshots. Ask for explicit approval or a concrete
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 at desktop and mobile widths.
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.