@nklisch/pi-agile-workflow 0.15.3 → 0.16.1

package/skills/fix/SKILL.md

@@ -2,20 +2,19 @@
 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".
+  inline. Diagnoses and repairs the bug as a focused substrate story: reproduces it, identifies the
+  root cause, writes a failing test, applies the minimal fix, verifies it, and continues through
+  review to done unless the caller requests stop-at-review. Use when something is verifiably broken,
+  not for unverified hunches, refactors, feature additions, or architectural work. 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
+You diagnose and repair a specific reported bug, capturing the work as a focused
+substrate story that completes through its review lane by default. The discipline
+is reproduce, diagnose to root cause, write a regression test, apply the minimal
+fix, confirm, and honor review's verdict. The artifact is the substrate item, not
 a separate fix doc.
 
 ## When to invoke
@@ -128,46 +127,65 @@ for separate consideration — don't bundle.
 
 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:
+**Test integrity during Phase 6.** Follow the project's test-integrity rules and
+the worker posture in `../principles/references/subagents.md`: fix bad tests
+in-session, park other production bugs rather than bundling them, and never game
+a test to make it pass.
 
-- 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: Commit and complete the lifecycle
 
-### 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:
+1. Update the story stage: `implementing → review`. The PostToolUse hook
+   auto-bumps `updated:`.
+2. Append an "Implementation notes" section capturing:
+   - Execution capability selected from risk and scope, plus the rationale
+   - Effective `review_weight` and its source
    - Files changed
    - Test added
-   - Adjacent issues parked (with their backlog ids)
-3. Commit:
+   - Adjacent issues parked (with backlog ids)
+
+   Choose capability without a routine model-tier question unless the caller or
+   project explicitly overrides it. Resolve review weight from an explicit caller
+   override, then project convention, otherwise `standard`; the principles and
+   review skills own the weight matrix.
+3. Commit the fix:
    ```bash
    git add .work/active/stories/<id>.md <changed-files> <test-file>
    git commit -m "fix: <short description> (<story-id>)"
    ```
+4. Unless the caller explicitly requested `stop-at-review` (including "stop at
+   review", "leave at review", or "hand off for review") or a project convention
+   sets that boundary, invoke `/agile-workflow:review <id>` in the same invocation
+   and forward the effective `review_weight`. The review lane owns its required
+   context and verdict:
+   - approve: advance and commit `review → done`
+   - bounce: append `## Review findings`, return the story to `implementing`, and
+     report the bounce
+   - blocker: append `## Blocker` and report it without claiming completion
+
+A weight of `none` skips independent review, but the review lane still requires
+the same green verification and acceptance evidence before administrative
+closure. Review remains a real lifecycle act, not silent self-approval. With
+`stop-at-review`, leave the committed story at `review` and report the explicit
+boundary.
 
 ## Output
 
 Brief report in conversation:
-- **Story**: `<id>` at `stage: review`
+- **Story**: `<id>` at `stage: done`, `stage: review` by explicit override, or
+  `stage: implementing` after a documented bounce
+- **Review**: lane verdict, limitation, or blocker
 - **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
+- **Test**: file path and behavior asserted
+- **Execution capability**: choice and rationale
+- **Review weight**: effective value and source
+- **Parked for separate consideration**: adjacent issues not bundled
 
 ## 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.
+- Do not self-approve at `review`; invoke the review lane and honor its verdict.
+- Broad scope (for example, many files, a public-interface change, or multiple
+  subsystems) is a signal that this is a feature rather than a targeted fix, not
+  a review-stop rule. Route it through `/agile-workflow:scope`.

package/skills/implement/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: implement
 description: >
-  ALWAYS invoke this skill when the user explicitly asks to implement a substrate item inline OR the
-  delivery is tiny (about 50 LoC or less, two files or fewer, no coordination) OR the deliverable is no-code prose (a
-  [prose] item — any size, as long as it needs no coordination) — for any larger or default *code*
-  work prefer /agile-workflow:implement-orchestrator. Inline single-stride implementation of a
-  substrate item at stage:implementing. Reads the design embedded in the item body, writes code per
-  the spec, runs build+tests, advances stage implementing to review, and updates the item body with
-  implementation notes. Triggers on "implement this inline", "implement this item inline", "just do it
-  inline", or a very small explicit delivery.
+  ALWAYS invoke this skill when the user explicitly asks to implement a substrate item inline, when
+  the work is cohesive enough for one owner, or when the deliverable is no-code prose (a [prose]
+  item of any size that needs no coordination). Inline implementation of an item at
+  stage:implementing. Reads the design in the item body, implements and verifies it, records the
+  chosen execution capability, and continues through review to done unless the caller requests
+  stop-at-review. Prefer /agile-workflow:implement-orchestrator when ownership, sequencing, or
+  uncertainty makes delegated coordination useful. Triggers on "implement this inline", "implement
+  this item inline", "just do it inline", or a focused explicit delivery.
 ---
 
 # Implement
@@ -20,24 +20,21 @@ notes there as you work.
 
 ## Trigger
 
-`/agile-workflow:implement-orchestrator` is the default routing for implementing
-work, including lone stories. This skill is the **inline alternative** — same
-work, no sub-agent fan-out — and it's the right call when:
-
-- The delivery is small and focused (a tiny tweak, a single-file change, a
-  flag flip, landing code already in the working tree)
-- The deliverable is **no-code prose** (a `[prose]` feature — docs, a
-  convention / rule, research write-up, copy). The ≤50 LoC / ≤2 files cap is a
-  *code-coordination* proxy; it does not apply to prose, which qualifies on
-  **no-coordination** alone regardless of length. A 600-line convention rewrite
-  is one authoring stride, not an orchestrated fan-out.
-- The user explicitly asks to implement inline / "do it yourself"
-- You're already mid-flow on this item and a hand-off would lose context
-
-When the work is multi-unit *code*, spans several files, or has sibling stories
-that could run in parallel, prefer the orchestrator. When in doubt on code work
-and nothing strongly points either way, the orchestrator is the safer default.
-Prose work is never a reason to reach for the orchestrator.
+`/agile-workflow:implement-orchestrator` is the default routing for implementation
+that benefits from coordination. This skill is the **inline alternative** — the
+same lifecycle, owned by the current agent without implementation fan-out.
+Choose between them from cohesion, ownership, sequencing, and uncertainty:
+
+- Prefer inline when one owner can carry a cohesive change end to end, a handoff
+  would lose useful context, or the caller explicitly requests inline execution.
+- Prefer the orchestrator when work has independent ownership surfaces,
+  dependency-driven sequencing, useful parallelism, or enough uncertainty that
+  isolated workers improve delivery.
+- Tiny changes (roughly tens of lines or a couple of files) are a useful hint
+  toward inline execution, never a routing gate.
+- **No-code prose** (`[prose]`) qualifies for inline execution on
+  **no-coordination** grounds regardless of length. Prose is never routed to the
+  orchestrator merely because it is long.
 
 Common phrases:
 - "implement story X", "implement this feature"
@@ -87,7 +84,7 @@ Autopilot pre-filters via `work-view --ready` so this should rarely fire under
 autopilot. Interactive callers will see the note and can choose to fix the
 dep or remove it.
 
-### Phase 2.5: Choose delivery mode
+### Phase 2.5: Choose delivery mode and capability
 
 If the item carries `tags: [prose]`, use **prose mode** for the rest of this skill:
 
@@ -100,6 +97,13 @@ If the item carries `tags: [prose]`, use **prose mode** for the rest of this ski
 
 For non-prose items, continue in code mode.
 
+For either mode, select execution capability from the item's risk and scope
+unless the caller, a stable project convention, or an autopilot caller note
+overrides it. Do not ask a routine model-tier question. Also resolve the
+effective `review_weight`: explicit caller override, then project convention,
+otherwise `standard`. Record both choices in Phase 7; the principles and review
+skills own the weight matrix.
+
 ### Phase 3: Map integration points
 
 For `[prose]` items, map prose integration points instead:
@@ -206,6 +210,8 @@ Append (or update) an "Implementation notes" section in the item's body:
 
 ```markdown
 ## Implementation notes
+- Execution capability: <choice and brief risk/scope rationale>
+- Review weight: <effective value and source: caller, project, or default>
 - Files changed: <list>
 - Tests added: <list>
 - Discrepancies from design: <list with one-line explanation each, or "none">
@@ -234,42 +240,47 @@ Don't claim done if tests don't pass. A known gap reported is better than a hidd
 
 #### Test integrity
 
-When tests fail during verification, classify each failure before reacting:
-
-- **Bad test** (stale fixture, drifted assertion, broken mock, outdated
-  snapshot) → fix in-session. Repairing the suite is part of the stride.
-- **Real production bug** surfaced by the test → park it via
-  `/agile-workflow:park` with a short repro. Do NOT silently fix mid-pass.
-  Once the suite is green, if the parked bug is small enough for a single
-  stride, pick it up immediately with `/agile-workflow:scope` → design →
-  implement. Larger bugs stay in backlog for prioritization.
-- **Pre-existing flake or unrelated regression** → park it. Don't bundle.
-
-NEVER game a test to make it pass. A failing test that documents *why* it
-fails (inline comment, `skip` linked to a backlog id, `xfail` with reason)
-is more honest than a green test that lies. No `expect(true).toBe(true)`,
-no asserting on whatever the code happens to return, no deleting a test
-as "flaky" without root-causing first.
+Follow the project's test-integrity rules and the worker posture in
+`../principles/references/subagents.md`: fix bad tests in-session, park real
+production bugs, and never game a test to make it pass.
 
-### Phase 9: Advance stage and commit
+### Phase 9: Commit and complete the lifecycle
 
 1. Edit the item's frontmatter: `stage: implementing → review`. PostToolUse hook
    bumps `updated:`.
-2. Commit:
+2. Commit the implementation:
    ```bash
    git add <changed-files> <test-files> .work/active/<kind>s/<id>.md
    git commit -m "implement: <id>"
    ```
+3. Unless the caller explicitly requested `stop-at-review` (including "stop at
+   review", "leave at review", or "hand off for review") or a project convention
+   sets that boundary, invoke `/agile-workflow:review <id>` in the same invocation
+   and forward the effective `review_weight`. The review lane owns its required
+   context and verdict:
+   - approve: advance and commit `review → done`
+   - bounce: record `## Review findings`, return the item to `implementing`, and
+     report the bounce
+   - blocker: record `## Blocker` and report it without claiming completion
+
+A weight of `none` skips independent review, but the review lane still requires
+the same green verification and acceptance evidence before administrative
+closure. Reaching `review` remains a real lifecycle transition; continuing
+through it never means silently self-approving. With `stop-at-review`, finish
+Phase 9 after the implementation commit and report that explicit boundary.
 
 ## Output
 
 In conversation:
-- **Implemented**: `<id>` advanced to `stage: review`
+- **Implemented**: `<id>` advanced to `stage: done`, `stage: review` by explicit
+  override, or `stage: implementing` after a documented bounce
+- **Review**: lane verdict, limitation, or blocker
 - **Files changed**: list
 - **Tests added**: list
+- **Execution capability**: choice and rationale
+- **Review weight**: effective value and source
 - **Discrepancies from design**: list (or "none")
 - **Adjacent issues parked**: backlog ids (or "none")
-- **Next**: `/agile-workflow:review <id>` to evaluate the change
 
 ## Guardrails
 
@@ -279,10 +290,10 @@ In conversation:
   When they disagree, adapt the implementation, document the why.
 - Implement fully or report a blocker. NEVER leave TODO comments or `unimplemented!`.
 - Don't add unrequested features. Adapt to repo reality freely; expand scope never.
-- Don't advance past `review` — that's `/agile-workflow:review`'s job.
+- Do not self-approve at `review`; invoke the review lane and honor its verdict.
 - If you discover a genuine design flaw, don't muscle through. Append a
   `## Implementation discovery` section, set stage back to `drafting`, and
   return. The design family will pick it up on the next pass.
 - Adjacent issues you notice get parked via `/agile-workflow:park`, not bundled.
-- Test integrity is non-negotiable. Fix bad tests in-session; park real
-  production bugs; never make a test pass just to make it pass.
+- Test integrity is non-negotiable: follow the project rules and worker posture;
+  fix bad tests, park real production bugs, and never game tests.