@boopkit/cap-workflows 0.1.0 → 0.2.0

package/capability.json

@@ -15,6 +15,7 @@
     "boop-issue-sweep-workflow",
     "boop-website-dev-workflow",
     "boop-design-handoff-workflow",
-    "boop-knowledge-backfill"
+    "boop-knowledge-backfill",
+    "boop-stray-disposition"
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cap-workflows",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Reusable end-to-end development and writing workflows for AI agents",
   "files": [
     "skills/",

package/skills/boop-architecture-audit-workflow/SKILL.md

@@ -136,7 +136,10 @@ For the work that is genuinely new:
 - **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`](../../../cap-testing/skills/boop-testing-testing/SKILL.md) 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.
 - **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.
 - **Include a review child** that checks each change against its named change, not merely that the issue closed.
-- **Put the test run scope on every child.** Focused tests for what that child touches, plus the project's whole-program static check; the full suite once, on the review child that completes the branch. Left unstated, a child that has just changed a widely called function runs the whole suite on its own reasoning — minutes to tens of minutes, paid again on every sibling, and it reads as diligence in the log rather than as waste. The rule and the wording to use are in [`boop-project-mgmt-beads-planning`](../../../cap-project-mgmt/skills/boop-project-mgmt-beads-planning/SKILL.md).
+- **Put the test run scope on every child.**
+  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.
+  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.
+  The rule and the wording to use are in [`boop-project-mgmt-beads-planning`](../../../cap-project-mgmt/skills/boop-project-mgmt-beads-planning/SKILL.md).
 - **Do not create the feature branch.** The loop creates the worktree and its `work/<epic-id>` branch when it takes the first child.
 
 - **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`](../../../cap-project-mgmt/skills/boop-project-mgmt-beads-planning/SKILL.md) and the anti-patterns in [`boop-writing-technical-prose`](../../../cap-product-design/skills/boop-writing-technical-prose/SKILL.md), 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.
@@ -197,3 +200,9 @@ If the area is small enough that the audit is one obvious finding with an obviou
 - **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.
 - **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.
 - **Grading against a principle rather than against this codebase.** The criteria that apply here live in [`boop-services-services`](../../../cap-services/skills/boop-services-services/SKILL.md), [`boop-services-controllers`](../../../cap-services/skills/boop-services-controllers/SKILL.md), [`boop-api-rest-api-design`](../../../cap-api/skills/boop-api-rest-api-design/SKILL.md), and [`boop-skills-agent-surface-design`](../../../cap-skills/skills/boop-skills-agent-surface-design/SKILL.md). Cite them, not a textbook.
+
+## Related
+
+- [`boop-refactor-dev-workflow`](../boop-refactor-dev-workflow/SKILL.md) — at execution, once the operator gate has passed and a finding has become a named structural change; that workflow is where the discipline for changing a shape existing code depends on lives.
+- `boop-coding-review-changes` — when the question turns out to be whether a specific change is correct rather than whether an area's structure is sound; a defect in behaviour is not an audit finding.
+- `boop-project-mgmt-beads-planning` — at decomposition, when the graded findings become an issue tree someone else will execute.

package/skills/boop-feature-dev-workflow/SKILL.md

@@ -168,6 +168,11 @@ Create tasks as child issues of the feature issue. The descriptions below are th
    **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:
    - 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.
    - **Breadcrumbs to the design/layer skill** for the code being written (controller, service, data-access, view) **and to all three testing skills** (general principles, Light TDD, the domain testing skill — see the Testing section above). The general-principles skill is the one most often dropped because a task "feels like just unit-testing" — which is exactly when pairwise contract tests get missed. List all three by default; drop one only if it is genuinely irrelevant.
+   - **The test run scope.**
+     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.
+     The full suite runs once per branch, on the Review task in step 4 — give Review that scope when you create it below.
+     Left off, every sub-task runs the whole suite on its own reasoning and the branch pays for it once per slice.
+     The wording to put on each is in the [beads-planning skill](../../../cap-project-mgmt/skills/boop-project-mgmt-beads-planning/SKILL.md).
 
    **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.
 
@@ -401,4 +406,11 @@ Create tasks as child issues of the feature issue. The descriptions below are th
 
       Then **verify**: `bd list --status=open` over the tree must return nothing.
 
-   **STOP HERE — do NOT merge to main.** Reconcile closes the *work-tracking* loop on the `work/<feature-issue-id>` branch. It never merges to main, pushes to main, or deletes the branch — the same hand-off rule as Closeout (step 6c), and for the same reasons (the human owns the merge; concurrent worktrees; the branch is the easy-revert anchor). The loop goes idle on "No ready issues"; the human reviews the branch and merges if approved.
+   **STOP HERE — do NOT merge to main.** Reconcile closes the *work-tracking* loop on the `work/<feature-issue-id>` branch. It never merges to main, pushes to main, or deletes the branch — the same hand-off rule as Closeout (step 6c), and for the same reasons (the human owns the merge; concurrent worktrees; the branch is the easy-revert anchor). The loop goes idle on "No ready issues"; the human reviews the branch and merges if approved.
+
+## Related
+
+- [`boop-light-dev-workflow`](../boop-light-dev-workflow/SKILL.md) — when the Understand step shows the work extends an existing system rather than building a new one; this workflow's separate understand/plan/decompose sessions buy nothing there and lose grounding at every handoff.
+- `boop-project-mgmt-engineering-planning` — at the planning step, to order the slices by which uncertainty each one retires rather than by which is easiest to demo.
+- `boop-project-mgmt-beads-planning` — at decomposition, before writing child issues that a fresh agent has to pick up with none of this session's context.
+- `boop-testing-tdd-light` — inside every implementation slice, and again for each bug UAT turns up; the failing test comes before the fix.

package/skills/boop-knowledge-backfill/SKILL.md

@@ -17,3 +17,7 @@ metadata:
    - If any aspects of the spec were NOT implemented (deferred, descoped, or punted), extract those into a new revised spec in `specs/` that captures just the remaining work. Reference the archived spec for full context.
    - The archived spec should be the full original — do not edit or trim it.
 
+## Related
+
+- `boop-product-design-reference-integration` — for step a of every spec you process; this workflow decides what to backfill and in what order, and that skill decides where each piece lands on the page.
+- `boop-writing-technical-prose` — when extracting the unimplemented remainder into a revised spec; that spec is read cold by someone with none of the backfill's context.

package/skills/boop-light-dev-workflow/SKILL.md

@@ -102,3 +102,9 @@ The trap is symmetric across all three: designing from the summary (the issue, t
 - **Ceremony inflation.** Regrowing feature-dev's separate understand/plan/decompose sessions, or a reflexive large issue tree, throws away the entire reason to use this. The epic is scoped to the wiring.
 - **Verifying against the diff or the suite instead of the real path/render.** Tests prove structure; only the real path proves the goal is served.
 - **Wiring the new behavior in tests only, never in the live code path.**
+
+## Related
+
+- [`boop-feature-dev-workflow`](../boop-feature-dev-workflow/SKILL.md) — when investigate or design reveals the work is genuinely greenfield; a single grounded session has nowhere to put a real data-model design, so escalate rather than force it.
+- `boop-testing-tdd-light` — when running each child issue; the test that proves the wiring is missing is written before the wiring.
+- `boop-coding-development` — for the implementation conventions the child issues are executed under, so the extension matches the seam it extends.

package/skills/boop-stray-disposition/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: boop-stray-disposition
+description: "When an autonomous run (a loop, a sweep, a sub-agent session) has finished and filed follow-up issues along the way, settle each one before you write the closing summary. Every stray gets a recorded disposition — re-parented and reachable from the roadmap, folded into a spec and closed, or triaged away. Use this whenever a run ends with issues in the queue that nobody has decided to do."
+metadata:
+  category: workflow
+---
+
+# Stray disposition — settle what a run filed before you call it done
+
+Agents working through an autonomous run routinely file follow-up issues during review and
+punch-list work without parenting them to the epic they arose from. Those issues land in the
+ready queue disconnected from the context that produced them. After every run, before the
+closing summary, audit for these strays and give each one a **disposition** — the deliberate
+settling of what becomes of it — so nothing is left in limbo.
+
+Find them by running `bd ready` and `bd list --status=open` and identifying the issues this run
+filed: they cite the run's findings or the files it touched.
+
+## The three dispositions
+
+1. **Re-parent** — the stray belongs to the work that just ran. Move it under the run's epic, or
+   group several strays under a new discovered-from epic (`Group: <work> hardening`) for a
+   follow-on run scoped to that prefix on the same branch, so the operator still reviews and
+   merges once.
+
+2. **Fold** — the stray is requirements or evidence for a spec that is already planned. Move the
+   substance into that spec's text and close the issue with a reason pointing at the spec. A
+   future run plans from the spec, never from the closed queue, so content left behind in the
+   issue would never reach it.
+
+3. **Triage** — a true orphan. Close it with a reason if it does not survive scrutiny, or surface
+   it to the operator in the closing summary for a decision. Never leave it silently in the queue.
+
+## Re-parenting alone is not a disposition
+
+Nothing polls or sweeps the issue queue. Work reaches an agent only through the plan spec and the
+runs it launches. A stray moved under an epic that no planned run will execute is still stranded —
+just tidier.
+
+A disposition is complete only when the stray is **reachable from the roadmap**: the plan spec
+names the issue and the trigger for picking it up, or the substance is folded into a spec, or the
+issue is closed.
+
+If the stray must wait on an event, encode the sequencing as a dependency (`bd dep`) on the issue
+that produces that event. A dependency is visible and self-releasing. Deferring an issue only
+hides it from the ready queue until a date, which helps nobody who is not already polling.
+
+## Fold versus reference is a judgement call
+
+**Fold** — extract the substance into the spec so it reads complete cold, close the issue, and
+leave pointers at both ends — when the next reader is a planner working from the spec.
+
+**Keep the issue open and give the spec a one-line reference instead** when the finding is
+operational rather than design-shaped (a bug with reproduction steps that will be worked *as* an
+issue), when the issue is a living artifact with discussion or an owner, or when the content is
+too bulky to fold without bloating the spec.
+
+The test under both: put the substance where its next reader will actually look, and leave a
+pointer at the other end.
+
+## Archiving a spec orphans the issues it rooted
+
+When closeout moves a spec to a history location, any open issue whose only roadmap reference
+lived in that spec is stranded again. Migrate those references to the successor document — the
+remainder spec, or the plan — as part of the same sweep.
+
+## The test at the end
+
+Every stray filed during the run has a recorded disposition, each disposition ends at the roadmap
+or at a closed issue, and the ready queue contains only work someone has actually decided to do.
+
+A queue that accumulates undispositioned findings makes every future `bd ready` call more
+expensive to read. That noise is what this practice exists to prevent.
+
+## Related
+
+- `boop-project-mgmt-beads-planning` — how to write and parent the issues a disposition re-parents
+  or folds, so the next agent can pick one up cold.
+- `boop-issue-sweep-workflow` — when the strays have already accumulated into a backlog and want
+  clearing as a batch rather than settling one run's output.

package/skills/boop-test-audit-workflow/SKILL.md

@@ -150,3 +150,9 @@ If the set of tests is small enough that the audit is a handful of edits with no
 - **Changing production code while rewriting a test.** A real bug the audit uncovers is a separate issue.
 - **Re-running the whole suite on every pass.** Work per file or per small group, and save the full suite for closeout.
 - **Splitting into many small child issues.** Each is a session with real setup cost; group coarsely, at the suite level or higher.
+
+## Related
+
+- `boop-testing-testing` — when a test on the rewrite list has to be re-levelled; the project's conventions decide which level is the right one to promote it to.
+- `boop-testing-tdd-light` — when the audit uncovers a real bug hiding behind a weak test; that is a separate issue, and it starts with the failing test.
+- `boop-coding-debugging` — when a rewritten test goes red for a reason you did not expect; diagnose from the data before assuming the rewrite is at fault.

package/skills/boop-website-dev-workflow/SKILL.md

@@ -193,3 +193,9 @@ Create tasks as child issues of the feature issue. The descriptions below are th
    4. `bd close <closeout-task-id>`.
    5. `bd close <feature-issue-id>` (all child work is now done).
    6. Stop. The loop will go idle on "No ready issues for prefix"; the next action belongs to the human reviewer.
+
+## Related
+
+- `boop-web-web-ui-design` — the primary design skill for this workflow; read it at the design step, before deciding what a page is made of.
+- `boop-ux-purpose-judgement` — when reviewing the rendered page, to ask whether each thing on it belongs there at all, which the visual pass does not ask.
+- `boop-writing-technical-prose` — when writing the driving spec and the child issues; each is picked up cold by an agent who was not in this session.