@boopkit/cap-workflows 0.1.1 → 0.2.1

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.1",
+  "version": "0.2.1",
   "description": "Reusable end-to-end development and writing workflows for AI agents",
   "files": [
     "skills/",

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

@@ -4,6 +4,10 @@ description: "When you need to judge whether an area of shipped code is structur
 metadata:
   category: workflow
 ---
+> **Read `PROJECT.md`, beside this file, first.**
+> It records how this project applies the guidance below, and where it deliberately differs.
+> Where the two conflict, `PROJECT.md` wins.
+> Record project-specific rules there, never in this file.
 
 # Architecture audit workflow — judge an area's structural health, and find the debt a named change would actually hit.
 

package/skills/boop-design-handoff-workflow/SKILL.md

@@ -4,6 +4,10 @@ description: "When the operator hands off a design package (a README plus a drop
 metadata:
   category: workflow
 ---
+> **Read `PROJECT.md`, beside this file, first.**
+> It records how this project applies the guidance below, and where it deliberately differs.
+> Where the two conflict, `PROJECT.md` wins.
+> Record project-specific rules there, never in this file.
 
 # Design-handoff workflow — turn a design package into shipped, reviewed code.
 

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

@@ -4,6 +4,11 @@ description: "When you are tasked with building a feature end-to-end, follow thi
 metadata:
   category: workflow
 ---
+> **Read `PROJECT.md`, beside this file, first.**
+> It records how this project applies the guidance below, and where it deliberately differs.
+> Where the two conflict, `PROJECT.md` wins.
+> Record project-specific rules there, never in this file.
+
 # Workflow for building features.
 When you are tasked with building a feature end-to-end, follow this guidance.
 

package/skills/boop-issue-sweep-workflow/SKILL.md

@@ -4,6 +4,10 @@ description: "When the bd queue has accumulated a noisy backlog of lingering P1/
 metadata:
   category: workflow
 ---
+> **Read `PROJECT.md`, beside this file, first.**
+> It records how this project applies the guidance below, and where it deliberately differs.
+> Where the two conflict, `PROJECT.md` wins.
+> Record project-specific rules there, never in this file.
 
 # Issue sweep workflow — clear lingering backlog noise without spending the operator's judgment.
 

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

@@ -4,6 +4,11 @@ description: "When you need to integrate new knowledge from a set of specs or co
 metadata:
   category: docs
 ---
+> **Read `PROJECT.md`, beside this file, first.**
+> It records how this project applies the guidance below, and where it deliberately differs.
+> Where the two conflict, `PROJECT.md` wins.
+> Record project-specific rules there, never in this file.
+
 # Knowledge Backfill
 
    **a. Integrate into reference:**

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

@@ -4,6 +4,10 @@ description: "When you are extending an existing system (front-end, back-end, or
 metadata:
   category: workflow
 ---
+> **Read `PROJECT.md`, beside this file, first.**
+> It records how this project applies the guidance below, and where it deliberately differs.
+> Where the two conflict, `PROJECT.md` wins.
+> Record project-specific rules there, never in this file.
 
 # Light dev workflow — goal-grounded extension of an existing system.
 

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

@@ -4,6 +4,10 @@ description: "When you need to change a contract, cardinality, or shape that exi
 metadata:
   category: workflow
 ---
+> **Read `PROJECT.md`, beside this file, first.**
+> It records how this project applies the guidance below, and where it deliberately differs.
+> Where the two conflict, `PROJECT.md` wins.
+> Record project-specific rules there, never in this file.
 
 # Workflow for refactoring to enable a feature
 

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

@@ -0,0 +1,84 @@
+---
+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
+---
+> **Read `PROJECT.md`, beside this file, first.**
+> It records how this project applies the guidance below, and where it deliberately differs.
+> Where the two conflict, `PROJECT.md` wins.
+> Record project-specific rules there, never in this file.
+
+# 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

@@ -4,6 +4,10 @@ description: "Use when a set of tests is not testing the purpose of the code: mo
 metadata:
   category: workflow
 ---
+> **Read `PROJECT.md`, beside this file, first.**
+> It records how this project applies the guidance below, and where it deliberately differs.
+> Where the two conflict, `PROJECT.md` wins.
+> Record project-specific rules there, never in this file.
 
 # Test audit workflow — cut the tests that cannot go red, and re-level the rest.
 

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

@@ -4,6 +4,11 @@ description: "When you are tasked with implementing website changes end-to-end (
 metadata:
   category: workflow
 ---
+> **Read `PROJECT.md`, beside this file, first.**
+> It records how this project applies the guidance below, and where it deliberately differs.
+> Where the two conflict, `PROJECT.md` wins.
+> Record project-specific rules there, never in this file.
+
 # Workflow for building website changes.
 
 This is the **website sibling** of [`boop-feature-dev-workflow`](../boop-feature-dev-workflow/SKILL.md) — same step-by-step flow, same beads-issue structure, customized for marketing-site work (new pages, page rewrites, IA changes, content/CTA updates).