@nklisch/pi-agile-workflow 0.15.3

package/skills/fix/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: fix
+description: >
+  ALWAYS invoke this skill when the user asks to fix a specific verified bug — do not just edit code
+  inline. Diagnoses and repairs a specific bug as a single-stride substrate story. Reproduces the
+  issue, identifies the root cause, writes a failing test, applies the minimal fix, confirms, and
+  creates a story item under .work/active/stories/ at stage:review capturing the work. Use when
+  something is verifiably broken — not for unverified hunches, refactors, or feature additions.
+  Triggers on "fix bug X", "fix the typo in", "fix this issue", "this is broken — fix it", and "patch
+  this item".
+---
+
+# Fix
+
+You diagnose and repair a specific reported bug, capturing the work as a single
+substrate story that lands at `stage: review`. The discipline is the same as a
+careful bug-fix workflow — reproduce, diagnose to root cause, write a regression
+test, apply the minimal fix, confirm — but the artifact is a substrate item, not
+a separate fix doc.
+
+## When to invoke
+
+Trigger phrases:
+- "fix bug X", "fix the issue with Y", "fix this"
+- "the typo in foo.md should be Z"
+- "I'm seeing error X when Y happens"
+
+Skip if:
+- User wants a refactor (no broken behavior) → use `/agile-workflow:scope` with
+  `tags: [refactor]`
+- User wants a new feature → use `/agile-workflow:scope`
+- The bug requires architectural changes spanning multiple subsystems → scope a
+  feature instead, fix is for targeted patches
+
+## Workflow
+
+### Phase 1: Reproduce
+
+A bug you can't reproduce can't be reliably fixed.
+
+1. Get the symptom from the user's input — error message, stack trace, failing test,
+   exact steps. If anything critical is missing (steps, environment, inputs), ask
+   the user.
+2. Read `AGENTS.md` / `CLAUDE.md` for build and test commands, plus
+   `.agents/rules/*.md` (if present) — the project's force-loaded agent rules
+   (tag semantics, test integrity, review policy).
+3. Reproduce locally. Capture the error verbatim.
+
+If you can't reproduce, halt and ask the user for more specific reproduction steps.
+
+### Phase 2: Diagnose to root cause
+
+1. Form a hypothesis. Read the relevant code; trace the data flow from symptom to source.
+2. Test the hypothesis (logging, debugger, code reading).
+3. Use `git bisect` if the bug is a recent regression.
+4. Name the root cause explicitly — not "the function fails" but the specific
+   assumption that's wrong, and where.
+
+A NullPointerException is a symptom. "The user object is built without an email
+field when login is via OAuth" is a root cause. Fix the root cause.
+
+### Phase 3: Capture in a test
+
+Before writing the fix, write a test that fails because of this bug. Use the project's
+test framework. Run it; confirm it fails. The test becomes the regression guard.
+
+If the bug is genuinely untestable (timing-dependent, external infra), document that
+in the story body and write the closest approximation.
+
+### Phase 4: Create the story item
+
+Create `.work/active/stories/<id>.md`:
+
+```yaml
+---
+id: story-fix-<short-slug>
+kind: story
+stage: implementing
+tags: [bug]
+parent: null
+depends_on: []
+release_binding: null
+gate_origin: null
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+
+# <one-line description>
+
+## Symptom
+<what the user reported, verbatim if useful>
+
+## Root cause
+<one paragraph: specific code path and assumption that was wrong>
+
+## Fix approach
+<what's changing, why it addresses the root cause>
+
+## Regression test
+<file path and what it asserts>
+```
+
+### Phase 5: Apply the minimal fix
+
+The smallest change that:
+- Makes the failing test pass
+- Doesn't break any existing tests
+- Addresses the root cause, not the symptom
+
+**Resist the urge to:**
+- Refactor adjacent code that isn't causing the bug
+- "Improve" surrounding logic while you're in there
+- Add defensive code beyond what addresses the root cause
+- Expand the fix's scope to "clean things up"
+
+These are valid improvements — but they belong in a separate concern. If you
+notice something genuinely worth addressing, park it via `/agile-workflow:park`
+for separate consideration — don't bundle.
+
+### Phase 6: Confirm (four-step checklist)
+
+1. **Run the new test** — it passes now
+2. **Run the full test suite** — nothing else regressed
+3. **Re-run the original reproduction** — the symptom is gone
+4. **Verify against the user's report** — does this resolve what they actually
+   described? (A test passing is necessary but not sufficient — confirm the
+   *symptom* the user reported is gone.)
+
+If any step fails, return to diagnosis. Do not ship a fix you can't confirm works.
+
+**Test integrity during Phase 6.** If running the full suite surfaces
+*other* failing tests:
+
+- Bad tests (stale fixtures, drifted assertions, broken mocks) → fix
+  in-session if the fix is small and scoped to this bug's surface area;
+  otherwise park.
+- Pre-existing real production bugs → park via `/agile-workflow:park`.
+  Do NOT bundle them into this fix's commit; this skill is for *one*
+  bug.
+- NEVER make a test pass by weakening its assertion or silencing it
+  without a documented reason. The regression test you wrote in Phase 3
+  must verify behavior, not "whatever the code returns now".
+
+### Phase 7: Advance to review and commit
+
+1. Update story stage: `implementing → review`. The PostToolUse hook auto-bumps `updated:`.
+2. Append an "Implementation notes" section to the story body capturing:
+   - Files changed
+   - Test added
+   - Adjacent issues parked (with their backlog ids)
+3. Commit:
+   ```bash
+   git add .work/active/stories/<id>.md <changed-files> <test-file>
+   git commit -m "fix: <short description> (<story-id>)"
+   ```
+
+## Output
+
+Brief report in conversation:
+- **Story**: `<id>` at `stage: review`
+- **Root cause**: one sentence
+- **Fix**: file(s) changed
+- **Test**: file path, what it asserts
+- **Parked for separate consideration**: any adjacent issues you noticed but didn't bundle
+
+## Guardrails
+
+- Do NOT skip the test (Phase 3). Fixes without tests recur.
+- Do NOT bundle refactoring or unrelated improvements into the fix's commit.
+- Do NOT advance the story past `review` — the user reviews and runs
+  `/agile-workflow:review` to advance to `done`.
+- If the fix would touch > 5 files or change a public interface, stop. This isn't a
+  fix; it's a feature with refactor implications. Use `/agile-workflow:scope` instead.

package/skills/gate-cruft/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: gate-cruft
+description: >
+  Cruft gate that scans the items bound to a release for AI-accumulated debris (dead code, stale
+  comments, compatibility shims, defensive bloat, over-abstraction) introduced or revealed by the
+  bundle. Delegates the full scan to a deep cleanup scanner agent which runs language-aware
+  detection plus heuristic pattern-matching, then returns findings. The orchestrator converts findings
+  into items in .work/active/ with gate_origin:cruft and tags:[cleanup]. Auto-triggers during
+  /agile-workflow:release-deploy.
+---
+
+# Gate-Cruft
+
+You orchestrate a cruft gate over the items bound to a release. The actual
+scan runs inside a **deep cleanup scanner agent** (a generic sub-agent prompted with the scanner posture from `../principles/references/subagents.md`); your role is to prepare the bundle context,
+dispatch the scanner, and convert the findings it returns into items in the
+substrate. Findings get `gate_origin: cruft`,
+`tags: [cleanup]`, with severity tier shaping the stage.
+
+Scanner strength is explicit: spawn exactly one source-read-only deep cleanup
+scanner with the strongest inspection/reviewer setting the host exposes. Use a generic sub-agent prompted with the scanner posture from `../principles/references/subagents.md`. Use extra-high reasoning
+for large or polyglot release bundles. If the host has no scanner path,
+run the audit inline and record the reduced isolation in the release body.
+
+## Trigger
+
+- `/agile-workflow:release-deploy` invokes during `quality-gate` stage
+- User can invoke manually: `/agile-workflow:gate-cruft <release-version>`
+
+## Workflow
+
+### Phase 1: Identify bundle changes
+
+```bash
+# Bound non-release items. `--release` auto-widens to ALL tiers (active + archive + releases).
+# Include late-bound archived stubs; their bodies may be pruned, but their item id is still
+# present and can recover the bundle commits/files. Ignore only the release orchestration item.
+.work/bin/work-view --release <version> --paths | while IFS= read -r item; do
+  kind=$(grep -m1 '^kind:' "$item" | awk '{print $2}')
+  [ "$kind" = "release" ] && continue
+  echo "$item"
+done > /tmp/bundle-items-<version>.txt
+
+# Files changed by the bundle. For archived stubs, the body is pruned on disk by design; use the
+# item id to find implementation commits instead of treating the missing body as a skip reason.
+while IFS= read -r item; do
+  id=$(grep -m1 '^id:' "$item" | awk '{print $2}')
+  git log --grep "$id" --format='%H' | xargs -I{} git diff-tree --no-commit-id --name-only -r {}
+done < /tmp/bundle-items-<version>.txt | sort -u > /tmp/bundle-files-<version>.txt
+```
+
+### Phase 2: Read existing gate items (idempotency prep)
+
+```bash
+.work/bin/work-view --release <version> --gate cruft --paths
+```
+
+Capture the set of `(file:line, category)` already-tracked findings to feed
+into the scanner brief.
+
+### Phase 3: Dispatch the cruft scanner
+
+Spawn ONE source-read-only deep scanner agent with the full scan brief. Use a generic sub-agent prompted with the scanner posture from `../principles/references/subagents.md` and the strongest
+inspection/reviewer setting the host exposes, escalating for large or polyglot
+bundles. If scanner agents are unavailable, run the audit inline and record
+the reduced isolation in the release body. The scanner does ecosystem detection,
+runs language-aware tools, applies heuristic pattern-matching, triages
+confidence, and returns structured findings.
+
+**Brief template**:
+
+> You are conducting a cruft scan for release `<version>` as an agile-workflow
+> scanner. Use read/search/shell tools as needed. Audit ONLY the bundle's
+> changed files — not the whole repo. Do not spawn nested sub-agents or implement
+> fixes.
+>
+> **Bundle scope**:
+> ```
+> <bundle-files>
+> ```
+>
+> **Already-tracked findings to skip**:
+> ```
+> <already-tracked file:line / category pairs>
+> ```
+>
+> **Methodology**:
+>
+> 1. **Ecosystem discovery** — examine `package.json`, `tsconfig.json`,
+>    `Cargo.toml`, `go.mod`, `pyproject.toml`, `Makefile`. This determines
+>    which language-aware detection tools are available.
+>
+> 2. **Language-aware detection (high confidence)** — run against the
+>    bundle's changed files only:
+>    - **TypeScript/JavaScript** — `tsc --noUnusedLocals --noUnusedParameters
+>      --noEmit`, eslint unused rules
+>    - **Python** — `ruff check --select F811,F841,F401`, `vulture`
+>    - **Go** — `go vet`, `deadcode`
+>    - **Rust** — compiler warnings for `#[warn(dead_code)]`
+>    Capture output and parse into findings.
+>
+> 3. **Heuristic pattern-matching** via Grep on bundle files:
+>
+>    **Medium confidence:**
+>    - Comments containing "removed", "backwards compat", "for backwards
+>      compatibility", "deprecated", "TODO" where the work is clearly done,
+>      "FIXME" for fixed code
+>    - Re-exports that nothing imports (cross-check with Grep)
+>    - Variables prefixed with `_` that were renamed to suppress warnings
+>    - Empty catch/except blocks with "// ignore" style comments
+>    - Wrapper functions that just call through to one other function with no
+>      added logic
+>
+>    **Low confidence:**
+>    - Try/catch around code that cannot throw
+>    - Validation of internal-only inputs at non-boundary functions
+>    - Single-use helper functions that could be inlined
+>    - Config/options parameters that only ever receive one value
+>    - Abstractions with a single implementation
+>
+> 4. **Cross-check existing patterns** — read `.agents/skills/patterns/` and
+>    legacy `.claude/skills/patterns/` if
+>    present. Intentional repetition documented as a pattern is NOT cruft.
+>
+> 5. **Triage by confidence**:
+>    | Confidence | Stage of produced item |
+>    |---|---|
+>    | High (tool-detected) | `stage: implementing` |
+>    | Medium (pattern-matched) | `stage: drafting` |
+>    | Low (judgment calls) | backlog file |
+>
+> **Output format** — return a single markdown document with:
+>
+> ```
+> ## Findings
+>
+> ### Finding 1
+> - **Title**: <one-line description>
+> - **Confidence**: High | Medium | Low
+> - **Category**: unused import | dead function | stale comment |
+>   compatibility shim | passthrough wrapper | defensive try/catch |
+>   single-use helper | over-abstraction
+> - **Location**: `<file>:<line>`
+> - **Evidence**:
+>   ```<lang>
+>   <the offending code, 1-10 lines>
+>   ```
+> - **Removal**: <what to remove and what to fix in surroundings>
+>
+> ### Finding 2
+> ...
+> ```
+>
+> Followed by:
+>
+> ```
+> ## Scan summary
+> - Ecosystem: <one-line>
+> - Tools run: <list>
+> - Files scanned: <count>
+> - Findings by confidence: High=<n>, Medium=<n>, Low=<n>
+> ```
+>
+> **Rules**:
+> - Scan only Bundle scope. Don't expand.
+> - Cite file:line for every finding.
+> - Don't fabricate. If a tool produces no output, don't invent findings.
+> - Skip already-tracked. Patterns documented in
+>   `.agents/skills/patterns/` or legacy `.claude/skills/patterns/` are
+>   intentional, not cruft.
+> - Don't propose findings you can't verify (e.g. "is this exported function
+>   used externally?" — if you can't confirm zero callers, downgrade to
+>   medium confidence rather than high).
+
+### Phase 4: Convert findings to items
+
+For each finding the scanner returned:
+
+Read `gate_finding_routing` from `.work/CONVENTIONS.md` before writing items.
+If absent, use the default routing below. Normalize cruft confidence to routing
+keys as: `High -> high`, `Medium -> medium`, and `Low -> low`. If a normalized
+key maps to `skip`, do not emit an item for that finding; include the skipped
+count in the gate output. If it maps to `backlog`, write a `.work/backlog/`
+item instead of an active story.
+
+```yaml
+---
+id: gate-cruft-<short-slug>
+kind: story
+stage: implementing | drafting    # by confidence
+tags: [cleanup]
+parent: null
+depends_on: []
+release_binding: <version>
+gate_origin: cruft
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+
+# <one-line description>
+
+## Confidence
+High | Medium | Low
+
+## Category
+<category>
+
+## Location
+`<file>:<line>`
+
+## Evidence
+\`\`\`<lang>
+<the offending code, 1-10 lines>
+\`\`\`
+
+## Removal
+<what to remove and what to fix in the surroundings — imports, whitespace, etc.>
+```
+
+Default confidence -> placement mapping:
+- **High** → `stage: implementing` in `.work/active/stories/`
+- **Medium** → `stage: drafting` in `.work/active/stories/`
+- **Low** → backlog file in `.work/backlog/`
+
+### Phase 5: Commit
+
+```bash
+git add .work/active/stories/ .work/backlog/
+git commit -m "gate-cruft: <N> findings for <version>"
+```
+
+## Output
+
+In conversation:
+- **Bundle**: `<version>` — `<N>` items audited, `<M>` files changed
+- **Findings**: count by confidence (High / Medium / Low)
+- **Items created**: count, with new ids
+- **Already-tracked**: count skipped
+
+If the count of cleanup items is large (> 20), suggest the user implement them
+in a single orchestrated pass: "These items can be drained efficiently via
+`/agile-workflow:implement-orchestrator` against a parent feature, OR by
+starting an autopilot goal scoped to gate-cruft items. Cleanup is mechanical
+and parallelizes well."
+
+## Guardrails
+
+- **The scan happens in the scanner agent, not here.** Your job is bundle
+  prep, dispatch, and item-writing. Don't replicate the scanner's analysis.
+- Audit only the bundle's changed files, not the whole repo.
+- Never remove code in this skill — produce items only.
+- Cleanup items must be surgical when implemented. They remove cruft and fix
+  the immediate surroundings only. They do NOT improve, refactor, or enhance.
+- Patterns documented in `.agents/skills/patterns/` or legacy
+  `.claude/skills/patterns/` are intentional, not
+  cruft. The scanner cross-checks; don't override.
+- Pass already-tracked findings into the scanner brief so it skips
+  duplicates.