@boopkit/cap-workflows 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cap-workflows",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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-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.