@boopkit/cap-workflows 0.2.1 → 0.2.2
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/package.json +1 -1
- package/skills/boop-architecture-audit-workflow/SKILL.md +7 -7
- package/skills/boop-design-handoff-workflow/SKILL.md +4 -4
- package/skills/boop-feature-dev-workflow/SKILL.md +28 -28
- package/skills/boop-issue-sweep-workflow/SKILL.md +2 -2
- package/skills/boop-knowledge-backfill/SKILL.md +1 -1
- package/skills/boop-light-dev-workflow/SKILL.md +6 -6
- package/skills/boop-refactor-dev-workflow/SKILL.md +3 -3
- package/skills/boop-test-audit-workflow/SKILL.md +1 -1
- package/skills/boop-website-dev-workflow/SKILL.md +15 -15
package/package.json
CHANGED
|
@@ -128,7 +128,7 @@ A human gate holds its waiter with no periodic check and releases it on `bd gate
|
|
|
128
128
|
|
|
129
129
|
### 7. Decompose the active debt
|
|
130
130
|
|
|
131
|
-
Once the gate releases, write the child issues while the analysis is fresh. Use
|
|
131
|
+
Once the gate releases, write the child issues while the analysis is fresh. Use `boop-project-mgmt-beads-planning` to shape the tree.
|
|
132
132
|
|
|
133
133
|
**First, check whether the findings are already filed.** An audit's most valuable output is often not new work but a new explanation: two or three bugs already in the queue turn out to be one structural cause. When that happens, do not file duplicates. Write one issue for the structural change, link the existing issues to it, and say in its body which symptoms it subsumes. An audit that adds only an explanation and closes nothing new has still earned its keep, and reporting that honestly is better than manufacturing issues to look productive.
|
|
134
134
|
|
|
@@ -137,16 +137,16 @@ For the work that is genuinely new:
|
|
|
137
137
|
- **One child per structural change, not one per call site.** Enumerate-and-patch is the failure that [`boop-refactor-dev-workflow`](../boop-refactor-dev-workflow/SKILL.md) exists to prevent, and it starts at decomposition time.
|
|
138
138
|
- **Carry the method on every child.** Each child must state the go-red discipline explicitly: delete the old shape first, commit the red build, follow the compiler. An agent picking up "split this interface" without that instruction will keep the build green by leaving a fallback, which is the exact failure this is meant to prevent.
|
|
139
139
|
- **Carry the named change too**, so the executor can tell a finished refactor from a rearranged one.
|
|
140
|
-
- **Name the skills on every child, and name only their names.** Step 8 says each child runs under [`boop-refactor-dev-workflow`](../boop-refactor-dev-workflow/SKILL.md) — but the executing session never reads this workflow, only the issue body, so that pointer reaches it exactly when the child says so and never otherwise. Put `boop-refactor-dev-workflow` on every child, plus the skill for the layer the structural change touches (services, controllers, data model, view) and
|
|
140
|
+
- **Name the skills on every child, and name only their names.** Step 8 says each child runs under [`boop-refactor-dev-workflow`](../boop-refactor-dev-workflow/SKILL.md) — but the executing session never reads this workflow, only the issue body, so that pointer reaches it exactly when the child says so and never otherwise. Put `boop-refactor-dev-workflow` on every child, plus the skill for the layer the structural change touches (services, controllers, data model, view) and `boop-testing-testing` for the real-path proof. Names, not extracts: the go-red method in the bullet above is copied deliberately, because a fallback that survives into the branch cannot be corrected afterwards, and that is the one exception. Everything else stays in its skill so there is a single copy to keep current.
|
|
141
141
|
- **Settle open decisions before the work starts, not during.** A choice like which validation library, or where a declaration lives, belongs in the issue body marked as decided, with the reasoning. An executor who has to pick one mid-implementation will pick silently.
|
|
142
142
|
- **Include a review child** that checks each change against its named change, not merely that the issue closed.
|
|
143
143
|
- **Put the test run scope on every child.**
|
|
144
144
|
The review child above is the one that runs the full suite; every other child runs focused tests plus the project's whole-program static check.
|
|
145
145
|
Left unstated, a child that has just changed a widely called function runs the whole suite on its own reasoning, and every sibling pays it again.
|
|
146
|
-
The rule and the wording to use are in
|
|
146
|
+
The rule and the wording to use are in `boop-project-mgmt-beads-planning`.
|
|
147
147
|
- **Do not create the feature branch.** The loop creates the worktree and its `work/<epic-id>` branch when it takes the first child.
|
|
148
148
|
|
|
149
|
-
- **Audit the issue bodies before the session ends, then revise them.** Writing an issue and auditing it are separate passes, and doing both at once produces bodies that read well to their author and cost their reader time. Once every child issue exists, re-read them all as the agent who will claim them cold, using the audit pass in
|
|
149
|
+
- **Audit the issue bodies before the session ends, then revise them.** Writing an issue and auditing it are separate passes, and doing both at once produces bodies that read well to their author and cost their reader time. Once every child issue exists, re-read them all as the agent who will claim them cold, using the audit pass in `boop-project-mgmt-beads-planning` and the anti-patterns in `boop-writing-technical-prose`, then rewrite whatever the audit finds. Read the tree side by side rather than one issue at a time: a child that says "a sibling issue handles this" without naming it, or a term the container defines and a child then uses bare, is only visible that way.
|
|
150
150
|
|
|
151
151
|
### 8. Execute, verify, close out
|
|
152
152
|
|
|
@@ -155,7 +155,7 @@ Hand the tree to a loop. Each child runs under [`boop-refactor-dev-workflow`](..
|
|
|
155
155
|
- **Prove it against the named change.** The closing evidence is that the change from step 1 is now cheap: make it, or make enough of it to show the file list shrank. A green suite proves you did not break anything, which is necessary and is not the point.
|
|
156
156
|
- **Re-grade the properties.** The step 4 verdicts are the baseline, and the ones that moved are the result.
|
|
157
157
|
- Run the full suite before closeout.
|
|
158
|
-
- **Write the audit up, sound findings included**, into `reference/`, using
|
|
158
|
+
- **Write the audit up, sound findings included**, into `reference/`, using `boop-product-design-reference-integration`. Annotate the resolved findings in place rather than deleting them: the record of why a change was made is what stops the next audit from re-deriving it.
|
|
159
159
|
- **Record what the work turned up that the audit did not predict.** A go-red refactor routinely exposes a type or a contract that was wrong all along and hidden by the loose shape. Those are findings the method missed, and writing them down is how the next audit gets better.
|
|
160
160
|
- Leave the branch for review. The human owns the merge.
|
|
161
161
|
|
|
@@ -185,7 +185,7 @@ The last three are the same problem at different scales, and together they are t
|
|
|
185
185
|
| The tests around the area cannot catch a behaviour change | [`boop-test-audit-workflow`](../boop-test-audit-workflow/SKILL.md) first |
|
|
186
186
|
| Clear a noisy backlog of small lingering items in a themed sweep | [`boop-issue-sweep-workflow`](../boop-issue-sweep-workflow/SKILL.md) |
|
|
187
187
|
| Extend an existing system toward a goal, wiring new behaviour from parts that exist | [`boop-light-dev-workflow`](../boop-light-dev-workflow/SKILL.md) |
|
|
188
|
-
| Find bugs in a diff |
|
|
188
|
+
| Find bugs in a diff | `boop-coding-review-changes` |
|
|
189
189
|
|
|
190
190
|
If the area is small enough that the audit is one obvious finding with an obvious fix, skip the epic and file a plain issue. This workflow earns its overhead when the structure is large enough that measuring first genuinely changes what you would have concluded.
|
|
191
191
|
|
|
@@ -203,7 +203,7 @@ If the area is small enough that the audit is one obvious finding with an obviou
|
|
|
203
203
|
- **Decomposing before a human has read the findings.** The gate is the only safeguard this workflow has, and self-critique is not review.
|
|
204
204
|
- **Confusing this with bug hunting.** A bug is a defect in behaviour and belongs in review or debugging. This workflow is about the cost of future change, and mixing the two loses both.
|
|
205
205
|
- **Keeping the build green through a structural change.** That is how the fallback survives. The execution discipline lives in `boop-refactor-dev-workflow`; use it.
|
|
206
|
-
- **Grading against a principle rather than against this codebase.** The criteria that apply here live in
|
|
206
|
+
- **Grading against a principle rather than against this codebase.** The criteria that apply here live in `boop-services-services`, `boop-services-controllers`, `boop-api-rest-api-design`, and `boop-skills-agent-surface-design`. Cite them, not a textbook.
|
|
207
207
|
|
|
208
208
|
## Related
|
|
209
209
|
|
|
@@ -43,11 +43,11 @@ Ask: is the work bounded with a clear path, or is there a judgment call hiding
|
|
|
43
43
|
|
|
44
44
|
### 4. Surface the verdict and any decision to the operator
|
|
45
45
|
|
|
46
|
-
Report: feasible or not, the scope, and the one question that is genuinely theirs — the buried architectural decision, framed at their altitude with a recommendation. Use
|
|
46
|
+
Report: feasible or not, the scope, and the one question that is genuinely theirs — the buried architectural decision, framed at their altitude with a recommendation. Use `boop-product-design-thought-partnership` here. Get the call, then bake the decision into the issue so the sub-agent inherits it rather than re-deriving it. (Example: "derive the value from the shared source, not by duplicating — the README's 're-expose' framing assumed an upstream surface already had it, which it didn't.")
|
|
47
47
|
|
|
48
48
|
### 5. File a bd issue (goal/approach/context shape)
|
|
49
49
|
|
|
50
|
-
Per
|
|
50
|
+
Per `boop-project-mgmt-beads-planning`. Breadcrumb the handoff README as the authoritative spec, and **if the operator settled a decision in step 4, state it in the issue and say it supersedes the README where they differ** — otherwise the sub-agent will follow the README's wrong premise. Note the template's graceful-degradation (template + CSS can drop first; view-model edits light it up). Name the visual-check as the done-gate.
|
|
51
51
|
|
|
52
52
|
### 6. Run it as a sub-agent
|
|
53
53
|
|
|
@@ -92,6 +92,6 @@ Often itself a sub-agent. Per [`boop-knowledge-backfill`](../boop-knowledge-back
|
|
|
92
92
|
## Related
|
|
93
93
|
|
|
94
94
|
- [`boop-knowledge-backfill`](../boop-knowledge-backfill/SKILL.md) — the archive + reference-integration discipline for the closeout.
|
|
95
|
-
-
|
|
95
|
+
- `boop-web-web-ui-design` — the visual-check-before-done rule the run leans on.
|
|
96
96
|
- [`boop-light-dev-workflow`](../boop-light-dev-workflow/SKILL.md) — the per-issue beats that run inside the sub-agent.
|
|
97
|
-
-
|
|
97
|
+
- `boop-product-design-thought-partnership` — surfacing the buried decision at the operator's altitude.
|
|
@@ -23,41 +23,41 @@ When you are tasked with building a feature end-to-end, follow this guidance.
|
|
|
23
23
|
## Relvant skills
|
|
24
24
|
|
|
25
25
|
### Step zero — before claiming any task
|
|
26
|
-
-
|
|
26
|
+
- `boop-skills-discovery` — when you pick up a non-trivial task, before claiming it: the discovery backstop. An issue's breadcrumbs are the primary way the right skills reach you, but an issue can miss one. Before claiming any task in this workflow, run the discovery sweep so a forgotten breadcrumb does not cost you the discipline that skill carries.
|
|
27
27
|
|
|
28
28
|
### Project Management
|
|
29
|
-
-
|
|
30
|
-
-
|
|
29
|
+
- `boop-project-mgmt-beads-planning` — when you need to plan work with beads.
|
|
30
|
+
- `boop-project-mgmt-engineering-planning` — when you need to plan engineering work.
|
|
31
31
|
|
|
32
32
|
### Design
|
|
33
|
-
-
|
|
34
|
-
-
|
|
35
|
-
-
|
|
36
|
-
-
|
|
37
|
-
-
|
|
38
|
-
-
|
|
39
|
-
-
|
|
40
|
-
-
|
|
33
|
+
- `boop-product-design-engineering-design` — when you need to design a feature or system.
|
|
34
|
+
- `boop-api-rest-api-design` — when you need to design REST APIs.
|
|
35
|
+
- `boop-services-services` — when you need to design services.
|
|
36
|
+
- `boop-services-controllers` — when you need to design controllers.
|
|
37
|
+
- `boop-database-data-model` — when you need to design data models.
|
|
38
|
+
- `boop-web-web-ui-design` — when you need to design web UIs.
|
|
39
|
+
- `boop-ux-purpose-judgement` — when the feature includes new or substantially modified UI surface: the structural lens. Does each affordance belong, in the right shape, for the right job? Run during Plan against the spec; run during Review against a screenshot of the built page.
|
|
40
|
+
- `boop-ux-visual-judgement` — when the feature includes new or substantially modified UI surface: the taste lens (eye-path, register, anatomy, scan-line). Run during Review against a screenshot of the built page; optional during Plan against a nearby existing surface for register calibration only.
|
|
41
41
|
|
|
42
42
|
|
|
43
43
|
### Coding
|
|
44
|
-
-
|
|
45
|
-
-
|
|
46
|
-
-
|
|
47
|
-
-
|
|
48
|
-
-
|
|
44
|
+
- `boop-coding-beads-flow` — when you need to start working on a claimed issue.
|
|
45
|
+
- `boop-coding-development` — when you need to develop or modify code.
|
|
46
|
+
- `boop-coding-commit-changes` — when you need to commit code changes.
|
|
47
|
+
- `boop-coding-review-changes` — when you need to review uncommitted code changes.
|
|
48
|
+
- `boop-database-prisma` — when you need to design or migrate the database schema.
|
|
49
49
|
|
|
50
50
|
### Testing
|
|
51
51
|
|
|
52
52
|
Read all three for any code-touching task. They cover different layers, and the easy default of "I'll write a unit test" misses contract bugs at component boundaries.
|
|
53
53
|
|
|
54
|
-
-
|
|
55
|
-
-
|
|
56
|
-
-
|
|
54
|
+
- `boop-testing-testing` — the foundational testing skill: pairwise producer/consumer contracts, integration vs. unit decisions, mock boundaries, data-driven config coverage. Read this **before** picking a test shape; it tells you which shape the change actually needs.
|
|
55
|
+
- `boop-testing-tdd-light` — the Light TDD cycle: the Red / Green / Verify loop applied to features and bug fixes.
|
|
56
|
+
- `boop-testing-testing-express-web` — the domain-specific test skill for services, controllers, middleware, and route tests in the Express stack.
|
|
57
57
|
|
|
58
58
|
### Documentation
|
|
59
|
-
-
|
|
60
|
-
-
|
|
59
|
+
- `boop-product-design-feature-documentation` — when you need to write feature documentation.
|
|
60
|
+
- `boop-product-design-reference-integration` — when you need to integrate knowledge into reference docs.
|
|
61
61
|
|
|
62
62
|
|
|
63
63
|
## Project structure
|
|
@@ -155,7 +155,7 @@ The first issue is the epic root; working it produces the next issue(s), and so
|
|
|
155
155
|
### Task construction:
|
|
156
156
|
Create tasks as child issues of the feature issue. The descriptions below are the content of the created issue - so don't *do* the work described in the issue description, this is just the content of the issue.
|
|
157
157
|
|
|
158
|
-
1. **Understand the feature**: First task issue goal (don't *do* this work, this is the content of the task issue): Read the spec and any related documentation and skills to fully understand the feature requirements, user stories, and acceptance criteria. For each success criterion, identify the outcome it must actually prove and the governing principle behind it, and flag any criterion a partial or intermediate implementation could satisfy without delivering that outcome. If anything is unclear, ask for clarification. eg. for developing capabilities, use the
|
|
158
|
+
1. **Understand the feature**: First task issue goal (don't *do* this work, this is the content of the task issue): Read the spec and any related documentation and skills to fully understand the feature requirements, user stories, and acceptance criteria. For each success criterion, identify the outcome it must actually prove and the governing principle behind it, and flag any criterion a partial or intermediate implementation could satisfy without delivering that outcome. If anything is unclear, ask for clarification. eg. for developing capabilities, use the `boop-capability-development` skill
|
|
159
159
|
|
|
160
160
|
**Findings handoff (critical):** The next task runs in a fresh session with zero context — anything not written to a discoverable file is lost. Write findings to `specs/{feature-name}-plan-findings.md` covering: spec understanding, prior art patterns, identified gaps, open questions, and decisions/recommendations. Reference this file as a breadcrumb in the "plan" task's issue description.
|
|
161
161
|
|
|
@@ -164,11 +164,11 @@ Create tasks as child issues of the feature issue. The descriptions below are th
|
|
|
164
164
|
2. **Plan the work**: Next task (don't *do* this work, this is the content of the task issue): **Start by reading `specs/{feature-name}-plan-findings.md`** from the "understand" task (path is in this task's breadcrumbs; also check `bd show <predecessor-id>` notes). The findings contain gap analysis and open questions that must inform the plan. Then find the feature implementation plan document, or create one in `specs/`. Follow the engineering planning skill. Ensure the plan covers the spec; create follow-up tasks for any gaps.
|
|
165
165
|
|
|
166
166
|
**UX paired-lens pass (when the feature includes new or substantially modified UI surface):** If the spec touches the app's UI surface, run a paired-lens pass during planning so the plan and downstream punch-list carry explicit UI work and acceptance criteria. The two cases are not symmetric:
|
|
167
|
-
- **Brand-new surface (the page does not exist yet):** run
|
|
167
|
+
- **Brand-new surface (the page does not exist yet):** run `boop-ux-purpose-judgement` against the spec, reference docs, and any existing nearby templates that anchor the register. **Do not try to screenshot a not-yet-built surface** — the purpose lens has an explicit fallback for missing inputs; use it and label each finding by which inputs supported it. The output validates the spec's interaction-shapes table: each affordance traced to a job, mechanism matched against frequency × consequence, anything underspecified flagged as a plan or punch-list candidate. Optionally run `boop-ux-visual-judgement` against a nearby existing surface for **register calibration only** (output is "the calm/loud target the new surface should match," not findings about the unbuilt page); skip it if no nearby surface is a useful anchor.
|
|
168
168
|
- **Modified existing surface (the page exists and is being changed):** capture a screenshot of the current surface with the capture script cap-ux ships (`scripts/ux-eval-capture.ts`), then run both lenses in order — purpose first, visual second.
|
|
169
169
|
Write the lens findings into the same `specs/{feature-name}-plan-findings.md`, labelling each with the lens that produced it (`[purpose]` or `[visual]`) and noting which inputs were loaded.
|
|
170
170
|
|
|
171
|
-
3. **Decompose the plan**: Next task (don't *do* this work, this is the content of the task issue): **Start by reading the engineering plan** at `specs/{feature-name}-plan.md` (confirm path from this task's breadcrumbs). Break it down into a "do the work" **container** — a `feature`-typed organiser, never a task — holding smaller, manageable `task` children, following the
|
|
171
|
+
3. **Decompose the plan**: Next task (don't *do* this work, this is the content of the task issue): **Start by reading the engineering plan** at `specs/{feature-name}-plan.md` (confirm path from this task's breadcrumbs). Break it down into a "do the work" **container** — a `feature`-typed organiser, never a task — holding smaller, manageable `task` children, following the `boop-project-mgmt-beads-planning` skill for the issue mechanics (hierarchy, dependencies, breadcrumb links). Create the feature branch `work/<feature-issue-id>` (e.g. `work/boop-arc.14`) — branch names MUST use the `work/` prefix + issue ID, never feature names like `email-capability`. All sub-tasks work within this branch.
|
|
172
172
|
|
|
173
173
|
**Every code-touching sub-task carries a `Tests` section and testing breadcrumbs.** This is how the workflow produces tasks that get tested correctly — author it when you write the sub-task, not later. Each sub-task that creates or changes code must include in its description:
|
|
174
174
|
- A **`Tests`** section naming: (a) the contracts the task creates or modifies — if it writes a function other code calls, or is itself a new caller of an existing function, name that producer/consumer boundary explicitly (e.g. *"this task calls `buildXyz`; exercise the caller's actual argument shape pairwise, not just the function's contract in isolation"*); (b) the test shapes required at this scope — unit for pure helpers, pairwise component where two pieces of code share a boundary, integration where data crosses a real boundary (DB, HTTP, serialization), route/render for surfaces; (c) any test scope deliberately deferred, with why. A `Tests` section that only says "tests pass" gives the implementing agent no signal about which shape the work needs, and the easy default (a unit test on whatever was written) misses contract bugs.
|
|
@@ -177,7 +177,7 @@ Create tasks as child issues of the feature issue. The descriptions below are th
|
|
|
177
177
|
Name what the sub-task runs before it calls itself done: the focused tests for the files it touches, plus the project's whole-program static check, and an explicit instruction not to run the full suite.
|
|
178
178
|
The full suite runs once per branch, on the Review task in step 4 — give Review that scope when you create it below.
|
|
179
179
|
Left off, every sub-task runs the whole suite on its own reasoning and the branch pays for it once per slice.
|
|
180
|
-
The wording to put on each is in the
|
|
180
|
+
The wording to put on each is in the `boop-project-mgmt-beads-planning` skill.
|
|
181
181
|
|
|
182
182
|
**THE TREE RECIPE — verified on bd 1.1.2.** Wire it exactly this way. The whole lifecycle was driven through a simulated loop against this shape, including a slice that decomposed itself mid-flight, and at every step the loop claimed exactly one correct issue: no leak, no deadlock, no stall.
|
|
183
183
|
|
|
@@ -287,7 +287,7 @@ Create tasks as child issues of the feature issue. The descriptions below are th
|
|
|
287
287
|
|
|
288
288
|
1. Pick a port and confirm it is free before you start anything: `lsof -ti tcp:<port>` prints nothing when the port is free. Then start the dev server in the feature worktree: `PORT=<port> npm --prefix <absolute-worktree-path> run dev` — the `--prefix` form is required; `cd <worktree> && npm run dev` silently falls back to the project root and screenshots the wrong build. If the port is already held, do not kill what is there and do not assume it serves your code — several worktrees and loops can run at once. Identify the holder with `lsof -a -d cwd -p <pid> -Fn` and reuse the server only when that directory is this feature's worktree; otherwise move to the next free port.
|
|
289
289
|
2. Capture each changed surface with `scripts/ux-eval-capture.ts`.
|
|
290
|
-
3. Run
|
|
290
|
+
3. Run `boop-ux-purpose-judgement` first against the screenshot plus the rendered HTML, template, controller, and route. Run `boop-ux-visual-judgement` second against the screenshot.
|
|
291
291
|
4. Label findings by lens (`[purpose]`, `[visual]`) in `labs/claude-runs/{feature-issue-id}-review-summary.md`, alongside the code-review findings, and feed them into the punch-list the same way code-review findings do.
|
|
292
292
|
5. **Stop the dev server before this task closes**, unless you reused one you found already running. Stop it by port: `lsof -ti tcp:<port> | xargs kill`. Never pattern-kill (`pkill -f nodemon`, `pkill -f tsx`, and the like) — a pattern matches every other worktree's server and the operator's own, and this project routinely has several alive at once. Never stop a server you did not start, including any port a concurrently running loop owns.
|
|
293
293
|
|
|
@@ -347,7 +347,7 @@ Create tasks as child issues of the feature issue. The descriptions below are th
|
|
|
347
347
|
- The archived spec and planning artifacts should be the full originals — do not edit or trim them.
|
|
348
348
|
|
|
349
349
|
**b. Integrate into reference:**
|
|
350
|
-
- Follow the
|
|
350
|
+
- Follow the `boop-product-design-reference-integration` skill to blend the new feature's knowledge into existing `reference/` pages.
|
|
351
351
|
- This is NOT "create a new page for the feature" — it's merging knowledge into the existing concept pages (and creating new concept pages only when a genuinely new concept has no home).
|
|
352
352
|
- Update cross-links between affected reference pages.
|
|
353
353
|
- Remove or update any reference content that is now outdated.
|
|
@@ -388,7 +388,7 @@ Create tasks as child issues of the feature issue. The descriptions below are th
|
|
|
388
388
|
|
|
389
389
|
**Step 2 — finalize (only when every descendant is closed).** In order:
|
|
390
390
|
|
|
391
|
-
1. **Run any un-run Closeout activity.** Confirm Closeout's two knowledge-integration activities actually landed — the spec (and its `-plan.md` / `-plan-findings.md` siblings) moved to `specs/history/`, and the feature's knowledge folded into `reference/`. If Closeout never ran or left either undone, do that work here now per step 6a/6b and the
|
|
391
|
+
1. **Run any un-run Closeout activity.** Confirm Closeout's two knowledge-integration activities actually landed — the spec (and its `-plan.md` / `-plan-findings.md` siblings) moved to `specs/history/`, and the feature's knowledge folded into `reference/`. If Closeout never ran or left either undone, do that work here now per step 6a/6b and the `boop-product-design-reference-integration` skill, then `bd close <closeout-task-id>` if it is still open.
|
|
392
392
|
|
|
393
393
|
2. **Commit + push + sync** any edits Step 2.1 produced:
|
|
394
394
|
```
|
|
@@ -176,5 +176,5 @@ If the sweep discovers a pattern that warrants a skill update, the skill update
|
|
|
176
176
|
## Related
|
|
177
177
|
|
|
178
178
|
- [`boop-light-dev-workflow`](../boop-light-dev-workflow/SKILL.md) — the per-issue beat structure that issue-sweep uses inside its run stage. Each cluster item is a light-dev-shaped pass, with the eligibility filter and the shared hand-back worktree added on top. Both workflows hand back a worktree; the difference is whether the operator has to bring judgment to it.
|
|
179
|
-
-
|
|
180
|
-
-
|
|
179
|
+
- `boop-web-web-ui-design` — the source of the visual-check rule for UI changes.
|
|
180
|
+
- `boop-writing-technical-prose` — the translation test still applies to anything the agent writes (commit messages, log entries, bail notes).
|
|
@@ -12,7 +12,7 @@ metadata:
|
|
|
12
12
|
# Knowledge Backfill
|
|
13
13
|
|
|
14
14
|
**a. Integrate into reference:**
|
|
15
|
-
- Follow the
|
|
15
|
+
- Follow the `boop-product-design-reference-integration` skill to blend the new feature's knowledge into existing `reference/` pages.
|
|
16
16
|
- This is NOT "create a new page for the feature" — it's merging knowledge into the existing concept pages (and creating new concept pages only when a genuinely new concept has no home).
|
|
17
17
|
- Update cross-links between affected reference pages.
|
|
18
18
|
- Remove or update any reference content that is now outdated.
|
|
@@ -40,7 +40,7 @@ Before designing anything, go look at the real thing first-hand. What "the real
|
|
|
40
40
|
Write down the inventory before moving on: the existing parts, the pattern you will extend, and the exact gap the new wiring fills.
|
|
41
41
|
|
|
42
42
|
### 3. Design
|
|
43
|
-
From the real materials, decide the **smallest wiring that serves the goal by reusing what exists**. Prefer extending an existing seam over standing up a parallel one. For UI surfaces, apply
|
|
43
|
+
From the real materials, decide the **smallest wiring that serves the goal by reusing what exists**. Prefer extending an existing seam over standing up a parallel one. For UI surfaces, apply `boop-ux-purpose-judgement` (does it carry what the job needs, in the right shape?) then `boop-ux-visual-judgement` (does it scan?). For back-end work, the equivalent question is *does this compose with the existing model or fork it* — a design that duplicates an existing mechanism is the back-end version of a database-dump. Favor the option that generalizes over a one-off.
|
|
44
44
|
|
|
45
45
|
### 4. Critique — before you decompose (the compensating control)
|
|
46
46
|
This is the only independent check before the epic is committed, so it carries the weight the missing multi-session redundancy would have. Run the design against the goal as a skeptic:
|
|
@@ -59,18 +59,18 @@ Now swap the "implement" tail of a one-pass flow for a decomposition. In the **s
|
|
|
59
59
|
- **Keep it proportional.** The epic is the real work plus its safety tasks — not a regrown four-session front half or a reflexive 13-issue tree. But it does need to *be* an epic: this workflow's floor is a change that genuinely decomposes into several grounded children. If the work is a one-line edit that needs no decomposition, you are in the wrong workflow — file a plain bd issue or just make the change; do not spin up this flow for it.
|
|
60
60
|
- **Size children to a session, not to a step.** A child issue is the unit a session picks up, and every session boundary is a cold start: the next agent re-reads the surface, re-derives the pattern, and re-runs the gates before it changes a character. So never split work that one session could carry. Group related small changes — a set of copy fixes on one template, several style corrections in one stylesheet — into a single child, and keep grouping until that child would take a session past roughly **50%** context. A one-line text change must never be its own child issue; that is a full session spent on a cold start to earn one line of diff.
|
|
61
61
|
- **Include a review task and a punch-list** as children — the relocated safety net. For engine/back-end extensions especially, the review must verify the new wiring is in the **live path** (not tests-only) and handles **every** existing case it touches.
|
|
62
|
-
- Use
|
|
62
|
+
- Use `boop-project-mgmt-beads-planning` and `boop-project-mgmt-engineering-planning` to shape the epic.
|
|
63
63
|
- **Do not create the feature branch yourself.** This decompose step runs in the *launch directory* (the planning phase runs before any worktree exists), so a `git checkout -b work/<epic-id>` here parks the launch dir on the feature branch — which then collides with the executor's `git worktree add` ("already checked out") and, worse, strands a concurrent session's next commit on your feature branch. The executor owns the branch: `boop loop` creates the worktree and its `work/<epic-id>` branch when it picks up the first child. Just create the bd tree and stop.
|
|
64
64
|
|
|
65
65
|
The loop then picks up each child as its own execution session. That boundary is the context-budget seam, and it is fine *when the child is large enough to need one* — the children are grounded, so a fresh session can execute them. It is pure waste when the child is smaller than the cold start that precedes it, which is what the sizing rule above exists to prevent. It creates the worktree and feature branch itself; the decompose session above must not.
|
|
66
66
|
|
|
67
67
|
### 6. Run the epic — implement, review, punch-list
|
|
68
|
-
The loop implements each child (
|
|
68
|
+
The loop implements each child (`boop-coding-development`, `boop-testing-tdd-light`), then the review and punch-list run against the whole branch (`boop-coding-review-changes`). Do not treat these as leftover process — they are where the independent perspective the single front session lacked actually happens. Verify each child against its goal, not merely that it closed.
|
|
69
69
|
|
|
70
70
|
### 7. Verify and close out
|
|
71
71
|
- **Run the real path, not just the suite.** For UI, capture the render and re-critique against it. For back-end, drive the real end-to-end flow against a throwaway environment — a green suite proves structure compiles, not that the goal is served.
|
|
72
72
|
- Run the targeted tests for what you touched, and the full suite before closeout.
|
|
73
|
-
- Integrate knowledge into `reference/` (
|
|
73
|
+
- Integrate knowledge into `reference/` (`boop-product-design-reference-integration`) and archive anything the change completed.
|
|
74
74
|
- Leave the branch for review. **Do not merge to main** — the human owns the merge.
|
|
75
75
|
|
|
76
76
|
## Front-end, back-end, full-stack: what "investigate" means
|
|
@@ -91,8 +91,8 @@ The trap is symmetric across all three: designing from the summary (the issue, t
|
|
|
91
91
|
|---|---|
|
|
92
92
|
| Extending an existing system toward a goal — FE, BE, or full-stack — wiring something new from existing parts | **this** |
|
|
93
93
|
| Greenfield: a new subsystem, data model, or API driven from a spec | [`boop-feature-dev-workflow`](../boop-feature-dev-workflow/SKILL.md) |
|
|
94
|
-
| An open-ended "make this page better / find what's wrong" eval that should grow the judgement skill |
|
|
95
|
-
| A page UX delivery campaign with a finding budget and per-finding decomposition |
|
|
94
|
+
| An open-ended "make this page better / find what's wrong" eval that should grow the judgement skill | `boop-ux-eval-and-refine-workflow` |
|
|
95
|
+
| A page UX delivery campaign with a finding budget and per-finding decomposition | `boop-ux-app-ui-dev-workflow` |
|
|
96
96
|
| A noisy backlog of small lingering items to clear in a themed sweep | [`boop-issue-sweep-workflow`](../boop-issue-sweep-workflow/SKILL.md) |
|
|
97
97
|
|
|
98
98
|
**Bounded on both ends.** *Above:* if *investigate* or *design* reveals the work is actually greenfield — a genuinely new subsystem, a real data-model design, no existing pattern to extend — it has left this workflow's domain; say so and escalate to `boop-feature-dev-workflow` rather than forcing a redesign through a single grounded session. *Below:* if the change is a one-liner or a lone edit that does not decompose into several grounded issues, it is beneath this workflow — a plain bd issue or a direct fix is the right tool, not an epic.
|
|
@@ -110,6 +110,6 @@ A refactor of this kind usually exists to **make a feature buildable**. It ships
|
|
|
110
110
|
## Related
|
|
111
111
|
|
|
112
112
|
- [boop-feature-dev-workflow](../boop-feature-dev-workflow/SKILL.md) — the peer workflow, for building capability.
|
|
113
|
-
-
|
|
114
|
-
-
|
|
115
|
-
-
|
|
113
|
+
- `boop-product-design-engineering-design` — the concept map in step 1 is a design artifact; the current-state audit guidance applies.
|
|
114
|
+
- `boop-testing-testing` — for the real-path proof in step 7.
|
|
115
|
+
- `boop-coding-review-changes` — the scan in step 5 belongs in review too.
|
|
@@ -108,7 +108,7 @@ Fix the plan here. It is far cheaper than fixing it after an epic of issues has
|
|
|
108
108
|
### 5. Break the work into one epic and a few coarse child issues
|
|
109
109
|
In the same session, while the classification is fresh, create one bd epic (an epic cannot be claimed as work itself, so it is a safe container) with child issues scoped to the trim list.
|
|
110
110
|
|
|
111
|
-
**Keep the child count low, and group coarsely — at the suite level or higher.** Every child issue is a session for whoever runs it, and a fresh session reloads its context from scratch. Many small children multiply that cost and lose context between them. Prefer a few coarse issues, split by area or by suite rather than by file or by kind of change. Keep a removal together with the rewrite that covers its invariant, so one session cannot delete an old test before its replacement exists. Add one issue that confirms coverage and one that reviews the result. Ground each issue in the real test files it touches, and use
|
|
111
|
+
**Keep the child count low, and group coarsely — at the suite level or higher.** Every child issue is a session for whoever runs it, and a fresh session reloads its context from scratch. Many small children multiply that cost and lose context between them. Prefer a few coarse issues, split by area or by suite rather than by file or by kind of change. Keep a removal together with the rewrite that covers its invariant, so one session cannot delete an old test before its replacement exists. Add one issue that confirms coverage and one that reviews the result. Ground each issue in the real test files it touches, and use `boop-project-mgmt-beads-planning` to shape the tree.
|
|
112
112
|
|
|
113
113
|
Then create the bd tree and stop. Do not run the work yourself, and do not create the feature branch: the loop creates the worktree and its `work/<epic-id>` branch when it takes the first child. Creating the branch here collides with that and can strand commits.
|
|
114
114
|
|
|
@@ -18,26 +18,26 @@ This workflow is **project-agnostic**. It names patterns of project artifacts (t
|
|
|
18
18
|
## Relevant skills
|
|
19
19
|
|
|
20
20
|
### Project Management
|
|
21
|
-
-
|
|
22
|
-
-
|
|
21
|
+
- `boop-project-mgmt-beads-planning` — when you need to plan work with beads.
|
|
22
|
+
- `boop-project-mgmt-engineering-planning` — when you need to plan engineering work.
|
|
23
23
|
|
|
24
24
|
### Design
|
|
25
|
-
-
|
|
26
|
-
-
|
|
27
|
-
-
|
|
25
|
+
- `boop-product-design-engineering-design` — when you need to design a feature or system.
|
|
26
|
+
- `boop-web-web-ui-design` — when you need to design web UIs; **the primary design skill for this workflow**.
|
|
27
|
+
- `boop-services-controllers` — when you need to design controllers, the route handlers that render views.
|
|
28
28
|
|
|
29
29
|
### Coding
|
|
30
|
-
-
|
|
31
|
-
-
|
|
32
|
-
-
|
|
33
|
-
-
|
|
30
|
+
- `boop-coding-beads-flow` — when you need to start working on a claimed issue.
|
|
31
|
+
- `boop-coding-development` — when you need to develop or modify code.
|
|
32
|
+
- `boop-coding-commit-changes` — when you need to commit code changes.
|
|
33
|
+
- `boop-coding-review-changes` — when you need to review uncommitted code changes.
|
|
34
34
|
|
|
35
35
|
### Testing
|
|
36
|
-
-
|
|
37
|
-
-
|
|
36
|
+
- `boop-testing-testing` — when you need to write or run tests.
|
|
37
|
+
- `boop-testing-testing-express-web` — when you need to test Express web endpoints.
|
|
38
38
|
|
|
39
39
|
### Documentation
|
|
40
|
-
-
|
|
40
|
+
- `boop-product-design-reference-integration` — when you need to integrate knowledge into reference docs.
|
|
41
41
|
|
|
42
42
|
### Subject-matter marketing skills (discovered per project)
|
|
43
43
|
The project may ship an **audience-type marketing skill** carrying the universal copy patterns for whom it sells to — frameworks, default moves, forbidden patterns (e.g. a `b2b-marketing` skill when the project sells to businesses; consumer / marketplace / etc. variants exist for other audiences). boop does not bundle one; if the project provides it, the Understand step records its exact path. Use whichever matches the project's audience.
|
|
@@ -120,7 +120,7 @@ Create tasks as child issues of the feature issue. The descriptions below are th
|
|
|
120
120
|
|
|
121
121
|
2. **Plan the work**: Next task (don't *do* this work, this is the content of the task issue): **Start by reading the findings** at `specs/{feature-name}-plan-findings.md` from the "understand" task (path is in this task's breadcrumbs; also check `bd show <predecessor-id>` notes). The findings include the guardrail registry (brand ref, realization doc, audience-type marketing skill, web design skill) — these are the breadcrumbs you will propagate into the implementation, review, and punch-list tasks below.
|
|
122
122
|
|
|
123
|
-
Then find or create the website implementation plan at `specs/{feature-name}-plan.md`. Follow the
|
|
123
|
+
Then find or create the website implementation plan at `specs/{feature-name}-plan.md`. Follow the `boop-project-mgmt-engineering-planning` skill. The plan should enumerate, for each in-scope page:
|
|
124
124
|
- Route + controller + view file paths (existing or new; flag scaffold-provided surfaces).
|
|
125
125
|
- **Per-block content sourcing** — for each major content block, whether the copy comes verbatim from the spec, is paraphrased from the spec, or will be written at implementation time per the project's brand-voice ref grounded by the audience-type marketing skill.
|
|
126
126
|
- The **tone mode** that applies (per the project's realization doc).
|
|
@@ -133,7 +133,7 @@ Create tasks as child issues of the feature issue. The descriptions below are th
|
|
|
133
133
|
|
|
134
134
|
When you decompose the plan into implementation sub-tasks (step 3), **include the guardrail registry as breadcrumbs in each sub-task**: the brand ref doc(s), the realization / tone-mode doc, the audience-type marketing skill, the web design skill, and the per-page tone / persona selections from the plan. Review the plan to ensure it fully covers the spec; create follow-up tasks for any gaps it can't resolve.
|
|
135
135
|
|
|
136
|
-
3. **Decompose the plan**: Next task (don't *do* this work, this is the content of the task issue): **Start by reading the website implementation plan** at `specs/{feature-name}-plan.md` (confirm path from this task's breadcrumbs). Break it down into a "do the work" task issue plus smaller sub-tasks following the
|
|
136
|
+
3. **Decompose the plan**: Next task (don't *do* this work, this is the content of the task issue): **Start by reading the website implementation plan** at `specs/{feature-name}-plan.md` (confirm path from this task's breadcrumbs). Break it down into a "do the work" task issue plus smaller sub-tasks following the `boop-project-mgmt-beads-planning` skill.
|
|
137
137
|
|
|
138
138
|
Sub-task granularity for website work is typically **page-level or surface-level**: one sub-task per new page, one per page rewrite, one per retired-route deletion, one for global-nav structure, etc. Shared concerns like semantic CSS extensions or new partials get their own sub-tasks and become blockers for the pages that depend on them.
|
|
139
139
|
|
|
@@ -177,7 +177,7 @@ Create tasks as child issues of the feature issue. The descriptions below are th
|
|
|
177
177
|
- If the work was driven by a *content* spec layered on top of a still-open *IA* spec, archive only the content spec and leave the IA spec in place.
|
|
178
178
|
|
|
179
179
|
**b. Integrate into reference:**
|
|
180
|
-
- Follow the
|
|
180
|
+
- Follow the `boop-product-design-reference-integration` skill to blend the new website knowledge into existing `reference/` pages.
|
|
181
181
|
- This is NOT "create a new page for the feature" — it's merging knowledge into the existing concept pages. The integration targets are the **guardrail registry** captured in the findings file:
|
|
182
182
|
- The project's brand realization / site doc — IA, page roster, retired-surfaces list, tone-mode assignments, any messaging tables (if rows changed).
|
|
183
183
|
- The project's brand ref doc — any voice / language drift discovered during implementation that warrants a new *Do/Don't* row, a new entry in *Language we avoid*, a new persona, etc.
|