@nklisch/pi-agile-workflow 0.15.3

package/skills/research/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: research
+description: >
+  ALWAYS invoke this skill when the user asks to research a library, API, SDK, or technology choice —
+  do not just web-search and summarize inline. Researches external libraries, APIs, SDKs, and patterns
+  to inform design and implementation. Investigates options, evaluates trade-offs against project
+  needs, and produces both a research document and an auto-loading reference skill. Use before
+  designing features that depend on unfamiliar technology, when choosing between options, or when API
+  assumptions need verification. Triggers on "research X", "compare X vs Y", "what library should I
+  use for Y", "investigate an API", and "evaluate an SDK".
+---
+
+# Research
+
+You research external libraries, APIs, SDKs, and patterns, then produce two outputs:
+a research document with your findings and an auto-loading reference skill that future
+agents use when working with the recommended technology.
+
+## Phase 1: Scope the Research
+
+Understand what needs investigating and why.
+
+1. Read **AGENTS.md / CLAUDE.md** and relevant project docs — understand the stack, constraints,
+   and what's already in use
+2. Map how the project currently handles the area being researched with
+   read-first triage: dependency manifests, imports, config files, existing
+   wrappers, and representative call sites via Read/Glob/Grep. Use an exploratory
+   sub-agent only when the integration surface is broad or unclear after that
+   probe.
+   - Use the host's generic/general-purpose subagent prompted with the explorer
+     capsule from `../principles/references/subagents.md`, at medium reasoning
+     by default.
+   - Use high or strongest reviewer reasoning for large or complex codebases.
+   - If no generic subagent adapter is available, keep direct host-local research.
+3. Define research questions:
+   - What specific problem does this technology need to solve for the project?
+   - What constraints must it satisfy? (bundle size, license, runtime, compatibility)
+   - What existing patterns must it work with?
+
+**structured question tool checkpoint:** Present:
+- The research questions you'll investigate
+- Options you plan to evaluate (if known)
+- Any constraints you identified from the codebase
+
+Ask: "Are these the right questions? Any options I should include or exclude?"
+
+## Phase 2: Investigate
+
+For each option, gather current information systematically.
+
+### 2a. Official Sources
+- Read the official documentation — focus on getting-started guides and API reference
+- Check the current version and recent changelog
+- Read migration guides if the project is upgrading from an older version
+
+### 2b. Health Check
+Verify each option is alive and maintained:
+- **Repository**: Recent commits (last 3 months?), open issue count, PR response time
+- **Releases**: Release frequency, latest release date, semantic versioning discipline
+- **Community**: Download trends (npm/crates/pypi), Stack Overflow activity
+- **License**: Compatible with the project's license?
+
+### 2c. API Verification
+- Find the actual API surface — do NOT trust your training data for this
+- Verify function signatures, configuration options, and return types from docs
+- Find real-world usage examples (blog posts, tutorials, open source projects)
+- Note any breaking changes between major versions
+
+### 2d. Integration Fit
+- Does it work with the project's runtime/framework/build system?
+- What does the integration look like? (imports, configuration, initialization)
+- Are there known conflicts with other dependencies in the project?
+
+## Phase 3: Evaluate and Recommend
+
+Score each option against the project's specific criteria — not in the abstract.
+
+For each option:
+- Pros and cons relative to the project's needs
+- Code example showing what integration would look like
+- Learning curve and documentation quality
+- Risk: what happens if this option is abandoned?
+
+**structured question tool checkpoint:** Present:
+- Summary table of options with scores
+- Your recommendation and rationale
+- Any trade-offs the user should weigh in on
+
+Ask: "Does this recommendation align with your priorities? Any concerns?"
+
+## Phase 4: Write Outputs
+
+### 4a. Research Document
+Write to a location based on project conventions (e.g., `docs/research/`, `docs/`).
+
+```markdown
+# Research: {Topic}
+
+## Context
+{Why this research was needed — what project problem it addresses}
+
+## Questions
+1. {Specific question answered}
+
+## Options Evaluated
+
+### {Name} (v{version})
+- **Maturity**: {Active/Stable/Maintenance/Deprecated}
+- **License**: {license}
+- **Pros**: {list}
+- **Cons**: {list}
+- **Fit**: {how well it matches project needs}
+
+## Recommendation
+{Clear choice with rationale tied to project-specific criteria}
+
+## Implementation Notes
+- {Key API patterns to follow}
+- {Common pitfalls to avoid}
+- {Configuration required}
+
+## Code Examples
+
+\`\`\`{lang}
+// Recommended usage pattern
+\`\`\`
+
+## References
+- [{name}]({url}) — {what this covers}
+```
+
+### 4b. Reference Skill
+Write an auto-loading reference skill so future agents have your findings available.
+
+**Location**: `.agents/skills/{topic-slug}/SKILL.md`
+
+If `.claude/skills/` exists, add a symlink or mirror for Claude compatibility.
+
+The skill must:
+- Be named after the technology, not the research (e.g., `hono-v4`, not `research-hono`)
+- Have a description with specific trigger keywords (library names, API method names, imports)
+- Set `user-invocable: false` — it auto-loads by keyword match
+- Contain key API patterns, code examples, and pitfalls from your research
+- Stay under 200 lines — move detailed reference tables to `references/` files if needed
+- Include version-specific information (the version you researched)
+
+## Anti-Patterns
+
+- NEVER recommend without evaluating alternatives — even if the choice seems obvious
+- NEVER trust training data for API shapes — verify from current documentation
+- NEVER skip the health check — a superior but abandoned library is a liability
+- NEVER evaluate against generic criteria — use this project's specific needs
+- NEVER produce a research doc without code examples — agents need concrete patterns
+- NEVER write a reference skill with generic keywords — specific imports and method
+  names are what trigger auto-loading
+- NEVER skip structured question tool checkpoints — wrong research direction wastes effort
+
+## Completion Criteria
+
+- All research questions answered with evidence
+- Multiple options evaluated with project-specific trade-offs
+- Clear recommendation with rationale
+- Research document written with code examples
+- Reference skill written with specific trigger keywords
+- User confirmed the recommendation at Phase 3 checkpoint
+- Changes committed

package/skills/research/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Research"
+  short_description: "Use Research for repo workflows"
+  default_prompt: "Use $research for this repository."
+policy:
+  allow_implicit_invocation: false

package/skills/review/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: review
+description: >
+  ALWAYS invoke this skill when the user asks to review a substrate item, an item is at stage:review,
+  or the user says "review this". Substrate-first: reviews tracked items, files follow-up items, and
+  advances or bounces them. Also supports out-of-band reviews of branches, commits, PRs, working
+  trees, or unpushed commits without substrate side effects. Uses fast, standard, and deep lanes; deep
+  review runs in fresh context when useful. Triggers on "review item X", "review this", "review this item",
+  "deep review", "is this ready", and "verdict on this item".
+---
+
+# Review
+
+You review work that is ready for evaluation. The primary path is a substrate
+item at `stage: review`: a feature, story, or epic whose work is done and ready
+to advance or bounce. The skill can also perform an out-of-band review of a
+branch, commit, PR, working tree, or unpushed commits when the user wants a
+one-off verdict outside the substrate.
+
+Core invariant: resolve the mode before changing files. **Substrate mode** may
+create `.work` findings, advance or bounce items, archive files, and commit
+review metadata. **Standalone mode** prints a review and leaves the substrate and
+git history alone unless the user explicitly asks to track or commit the review.
+
+## References
+
+Load only the reference needed for the selected lane:
+
+| Reference | Load when |
+|---|---|
+| [target-resolution.md](references/target-resolution.md) | Determining the target diff, PR, branch, commit range, or epic aggregate scope. |
+| [review-lenses.md](references/review-lenses.md) | Running a standard or deep review of code changes. |
+| [deep-review.md](references/deep-review.md) | The lane is feature, epic, explicit `--deep`, or the user asks for a more robust review. |
+| [../principles/references/models.md](../principles/references/models.md) | Picking the reviewer/peer, host→peer pairing, and the two-phase advisory→adversarial order for deep reviews. |
+| [../principles/references/subagents.md](../principles/references/subagents.md) | Mapping fresh-context reviewer roles across Claude, Codex, and Pi. |
+| [substrate-side-effects.md](references/substrate-side-effects.md) | Substrate mode needs findings filed, stages advanced or bounced, records appended, or a commit made. |
+
+## Invocation Modes
+
+| Invocation | Behavior |
+|---|---|
+| `review <id>` | Review one substrate item. |
+| `review` | Default to `--all`: drain every item at `stage: review`. |
+| `review --all` | Drain every item at `stage: review`. |
+| `review <NL filter>` | Drain a filtered subset of the review queue. Interpret the filter against item bodies, tags, and parent chains. |
+| `review <branch/commit/range/PR/wip>` | Out-of-band review. Review the target diff and print a verdict. |
+| `deep review <target>` / `review --deep <target>` | Use deep mode for a substrate item or out-of-band target. |
+
+In batch modes (`--all` / NL filter), loop through the matched set and output a
+single consolidated summary at the end: verdicts per item plus total finding
+counts.
+
+## Review Lanes
+
+Review cost should match what the target can actually surface. Resolve mode
+first, then pick the lane:
+
+| Target | Lane | What runs |
+|---|---|---|
+| **story item** | **Fast** | Confirm the green implementation verification already recorded by `implement`, then advance and roll up. No lens walk, no diff re-analysis, no peer. |
+| **out-of-band target** | **Standard** | Review the diff in the current context using the core lenses. Print a structured verdict. No substrate writes, no stage changes, no commit. |
+| **feature / epic item** | **Deep** | Full lens review using fresh-context evaluation when available. |
+| **explicit `--deep` target** | **Deep** | Use the deep lens set even for an out-of-band target. For a story item, keep the fast lane unless the caller explicitly asked for `--deep`. |
+
+### Fast Lane
+
+Stories use the fast lane by default:
+
+1. Read the story body.
+2. Confirm an implementation/verification record exists and reports green build
+   and tests.
+3. If verification is present and green, load
+   [substrate-side-effects.md](references/substrate-side-effects.md) and advance
+   `review -> done` with a one-line record:
+   `Verdict: Approve - story verified by implement; fast-lane advance`.
+4. If verification is absent or failing, either run cheap verification yourself
+   or bounce `review -> implementing` with a `## Review findings` note.
+
+Skip the lens walk for fast-lane stories. Do not deep-review a story unless the
+caller explicitly requested `--deep`.
+
+### Standard Lane
+
+Standalone reviews use the standard lane. Load
+[target-resolution.md](references/target-resolution.md) and
+[review-lenses.md](references/review-lenses.md), read enough surrounding code to
+understand the change, then print the structured review. Do not create `.work`
+items, advance stages, archive files, or commit metadata unless the user
+explicitly converts the findings into substrate work.
+
+### Deep Lane
+
+Feature, epic, and explicit deep reviews use the deep lane. Load
+[deep-review.md](references/deep-review.md) plus any target or lens reference it
+points to. Prefer fresh-context evaluation when available; if no fresh reviewer
+is reachable, do a degraded inline deep review and record that limitation in
+Notes rather than skipping the review. Deep reviews follow the two-phase order
+— **completeness/complementary, then adversarial** — and because a review target
+is a complete artifact, each phase is a **convergence loop to nits**, not a
+single pass (the ideal is the full `peer-review` loop when available). For a
+feature/epic (deep or complex scope) use **two different model classes** when
+available, one per phase (see
+[../principles/references/models.md](../principles/references/models.md) §6 for
+the design-vs-review loop distinction).
+
+## Workflow
+
+### Phase 0: Resolve Mode And Depth
+
+Default to substrate mode when the target looks like a work item id, when any
+item is at `stage: review`, or when autopilot delegated the review. Use
+standalone mode when the user names a branch, commit, commit range, PR number,
+`wip`, working tree, or otherwise asks for an out-of-band code review.
+
+If both interpretations are plausible, prefer substrate mode but ask the user
+before mutating `.work`. If the caller is autopilot or a harness goal, do not
+ask: choose substrate mode and the next review item.
+
+Depth:
+- **Fast**: story item with green implementation verification.
+- **Standard**: out-of-band target or explicitly lightweight review.
+- **Deep**: feature/epic item, explicit `--deep`, or a review where the user asks
+  for robustness across design, contracts, release, and operational dimensions.
+
+### Phase 1: Identify The Target
+
+Substrate mode:
+- If the caller passed an item id, target that item.
+- Otherwise run `.work/bin/work-view --stage review --paths`.
+- If multiple items are at `review` and autopilot delegated the call, pick the
+  most recent by `updated:` and proceed.
+- If multiple items are at `review` for an interactive caller, ask which one.
+
+Standalone mode:
+- Use the branch, commit, range, PR, working tree, or `wip` target from the user.
+- If the target is ambiguous, ask before fetching the diff.
+
+### Phase 2: Gather Context
+
+Substrate mode:
+- Read the item file.
+- Internalize the brief, design, implementation notes, and verification evidence.
+- For a feature, also read each child story body.
+
+Standalone mode:
+- Read the user's stated target.
+- Read PR description or commit messages when available.
+- Read enough surrounding project context to understand the author's intent.
+
+All modes:
+- Read `AGENTS.md` / `CLAUDE.md` for conventions when present.
+- Read `.agents/rules/*.md` (if present) — the project's force-loaded agent
+  rules (tag semantics, test integrity, review policy).
+- Read foundation docs the change touches, such as `docs/SPEC.md` or
+  `docs/ARCHITECTURE.md`.
+
+### Phase 3: Determine The Change Scope
+
+Load [target-resolution.md](references/target-resolution.md). Use it to gather
+the diff, PR metadata, commit messages, or epic aggregate scope.
+
+If the non-epic diff is empty:
+- Autopilot substrate mode: advance only if the item has complete green
+  verification evidence; otherwise bounce for missing review scope.
+- Interactive substrate mode: ask which range to review.
+- Standalone mode: report that there is no diff to review and stop.
+
+### Phase 4: Review
+
+Fast lane:
+- Confirm verification and skip code lenses.
+
+Standard lane:
+- Load [review-lenses.md](references/review-lenses.md).
+- Walk the applicable lenses and note any skipped lens with the reason.
+
+Deep lane:
+- Load [deep-review.md](references/deep-review.md).
+- Use fresh-context evaluation when available.
+- Apply the core lenses plus the deep dimensions.
+
+### Phase 5: Classify Findings
+
+- **Blocker**: must be fixed before advancing or merging. Examples:
+  correctness bug, security vulnerability, undocumented breaking change,
+  foundation-doc drift, or a test that proves the change is wrong.
+- **Important**: should be addressed but is not strictly blocking. Examples:
+  missing tests for meaningful logic, questionable design, unclear naming, minor
+  security gap, or refactor opportunity.
+- **Nit**: optional improvement, style polish, small documentation improvement,
+  or nonessential refactor.
+
+If there are zero blockers and zero important findings, say so plainly. Do not
+pad the review with invented concerns.
+
+### Phase 6: Finish
+
+Standalone mode:
+- Print the structured review.
+- Do not modify `.work`.
+- Do not commit anything.
+- If the user asks to track findings, load
+  [substrate-side-effects.md](references/substrate-side-effects.md) and convert
+  only the requested findings into substrate work.
+
+Substrate mode:
+- Load [substrate-side-effects.md](references/substrate-side-effects.md).
+- File above-nit findings into the substrate.
+- Advance the item if there are no blockers, or bounce it if blockers exist.
+- Append the review record.
+- Commit the substrate changes.
+
+## Output
+
+```markdown
+# Review: <target>
+
+## Summary
+<2-3 sentences>
+
+## Verdict
+Approve | Approve with comments | Request changes | Block
+
+## Findings
+
+### Blockers
+- **<title>** (`file:line`): <what is wrong, why it matters>
+  -> Item: `<finding-item-id>` (substrate mode only)
+
+### Important
+- **<title>** (`file:line`): <explanation and direction>
+  -> Item: `<finding-item-id>` (substrate mode only)
+
+### Nits
+- Nit: <brief note> (`file:line`)
+
+## Notes
+<mode, depth, skipped lenses, limitations, or anything else worth recording>
+```
+
+If no findings above nit level in substrate mode: "This change looks good.
+Nothing blocking or significant to flag. Item advanced to `stage: done`."
+
+If no findings above nit level in standalone mode: "This change looks good.
+Nothing blocking or significant to flag."
+
+## Guardrails
+
+- Resolve mode before making changes. Substrate mode may mutate `.work`;
+  standalone mode prints a review and leaves the workspace alone.
+- Do not pad with nits to look thorough.
+- Do not invent concerns to balance positive feedback. "Looks good, ship it" is
+  valuable.
+- Do not require tests for changes that clearly do not need them: typo fixes,
+  comment-only changes, or config-only changes.
+- Read actual files for context, not just diff lines.
+- If you do not understand the change well enough to judge it, say so
+  explicitly. "I would want the author to explain why X before approving" is a
+  valid finding.
+- In substrate mode, findings above nit-level become items. Do not let real
+  concerns evaporate into review prose.
+- Review's security check is lightweight. For a full security gate, use
+  `/agile-workflow:gate-security`.
+- Foundation-doc drift is a blocker, not a nit. Rolling foundation is a hard
+  rule.
+- Do not advance an item past review unless the verdict is Approve or Approve
+  with comments. Pushing through blockers defeats the point of the stage.

package/skills/review/references/deep-review.md

@@ -0,0 +1,98 @@
+# Deep Review
+
+Load this reference for feature reviews, epic reviews, explicit `--deep`
+requests, or any request that asks for a more robust review across design,
+contracts, release, and operational dimensions.
+
+## Reviewer Selection
+
+Prefer a fresh-context reviewer for deep mode. Run the review in a fixed
+**two-phase order** — completeness/complementary/advisory first, adversarial
+second. Because a review target is a **complete** artifact (unlike an open
+design), each phase is a **multi-step convergence loop**, not a single ask:
+iterate until findings stabilize (the ideal is the full `peer-review`
+convergence loop — ≥3 review→refine passes, continue while substantive issues
+keep surfacing, stop on nits, cap ~5). For a feature/epic or deep/complex
+target, use **two different model classes** when available — one class drives
+the Phase 1 convergence loop, a *different* class drives the Phase 2 loop — so
+both augmentation diversity and adversarial independence are maximized.
+
+1. **Phase 1 — Completeness / complementary convergence loop** (different class
+   than host when reachable). Ask each round: are all requirements, acceptance
+   criteria, edge cases, error paths, and dependencies covered? What is missing
+   or should be strengthened? Iterate to convergence; this is augmentation, not
+   judgment — run it *before* attacking.
+2. **Phase 2 — Adversarial convergence loop** (a different class than the host,
+   and ideally a different class than Phase 1). Same convergence shape, now in
+   attack posture: what is broken, contradictory, built on a false assumption,
+   or will fail in operation? Use `peeragent` when a different model class is
+   available and appropriate; do not use peeragent when it would be the same
+   class as the host.
+3. When a different model class is not reachable, use a fresh generic sub-agent
+   prompted with the reviewer capsule from
+   [../../principles/references/subagents.md](../../principles/references/subagents.md)
+   as the same-harness fresh-context fallback. Record that it was not
+   cross-model unless the spawned model class differs from the host.
+4. Otherwise, use a fresh local sub-agent at the highest available model class
+   when the environment provides one. If the mechanism only supports single
+   passes (no convergence loop), run as many rounds as it allows and note that
+   full convergence was not reached.
+5. If no fresh-context mechanism is available, continue inline as a degraded
+   deep review and record that limitation in `Notes`.
+
+For the host→peer pairing table, exact `peeragent` flags, and the design-vs-
+review loop distinction, load
+[../../principles/references/models.md](../../principles/references/models.md).
+
+Peer or sub-agent failures are non-blocking. Fall back to the next option rather
+than halting the review.
+
+A top-tier reasoning peer (Opus-class, xhigh Codex/GLM, or equivalent) commonly
+takes 10 to 30 minutes before it returns, especially for a large feature, epic,
+or out-of-band review. A quiet process that has not returned after a few minutes
+is still normal top-tier review latency, not a hang — budget for it across a
+multi-round convergence loop.
+
+## Reviewer Packet
+
+Give the fresh reviewer enough context to judge without bloating the task:
+
+- Review target and mode: substrate item, PR, branch, range, or epic.
+- Diff or aggregate scope from `target-resolution.md`.
+- Item brief/design/implementation notes, or PR/commit description.
+- Relevant project conventions from `AGENTS.md` / `CLAUDE.md`.
+- Relevant foundation-doc assertions.
+- Core lenses from `review-lenses.md`.
+- Deep dimensions below.
+
+The host classifies returned findings, files substrate items when applicable,
+and performs stage transitions. The fresh reviewer only evaluates.
+
+## Deep Dimensions
+
+Apply these after the core lenses:
+
+- **Contract and API behavior**: public interfaces, generated contracts, schemas,
+  CLI/config surfaces, compatibility, and consumer expectations.
+- **Data and migration behavior**: persistence shape, idempotency, backfills,
+  rollback/forward safety, and data compatibility.
+- **Concurrency and lifecycle**: async races, cancellation, retries, resource
+  cleanup, cache invalidation, and stale reads.
+- **Operational and release risk**: observability, failure modes, deploy
+  ordering, feature flags, dependency changes, and rollback behavior.
+- **Product or UX completeness**: when user-facing, does the end-to-end
+  capability match the brief or PR description from a user's point of view?
+
+## Depth Calibration
+
+Deep does not mean exhaustive. Pull the dimensions that match the change:
+
+- API/schema/CLI changes: emphasize contracts, breaking changes, docs, and tests.
+- Persistence changes: emphasize data migration, idempotency, rollback, and
+  observability.
+- Async/cache/network changes: emphasize concurrency, lifecycle, retries, and
+  failure modes.
+- UI/workflow changes: emphasize capability completeness, accessibility-relevant
+  behavior, state transitions, and regression coverage.
+- Epic reviews: emphasize aggregate alignment and release readiness, not per-line
+  diff analysis.

package/skills/review/references/review-lenses.md

@@ -0,0 +1,68 @@
+# Review Lenses
+
+Load this reference for standard and deep review lanes. Walk the applicable
+lenses and note any lens skipped with the reason.
+
+## Correctness
+
+- Does the change do what the design, PR description, or commit message says?
+- Are edge cases handled: off-by-one, null/undefined, async race, and boundary
+  conditions?
+- Does the change introduce resource leaks, infinite loops, unbounded growth, or
+  stale state?
+- If this is a fix, does it address the root cause rather than the symptom?
+
+## Tests
+
+- Are tests included for meaningful logic changes?
+- Do tests verify behavior and contract rather than implementation details?
+- Are edge cases covered, not only the happy path?
+- For bug fixes, is there a regression test that would have caught the bug?
+
+## Design Alignment
+
+- Does the implementation match the design, or are deviations documented?
+- Is any new abstraction earned by real repetition or imminent need?
+- Could the change be simpler while preserving behavior?
+- Does complexity move toward boundaries and away from core domain logic?
+
+## Security
+
+- Does the change touch auth, authorization, input validation, secrets, external
+  requests, file paths, or command execution?
+- Check only the applicable items. Do not run a full security audit here.
+- Look for SQL injection, XSS, command injection, path traversal, unsafe secret
+  handling, and SSRF-adjacent outbound request changes.
+
+## Breaking Changes
+
+- Does the change modify a public API, exported signature, schema, CLI, config,
+  or generated contract?
+- If yes, is the break intentional, documented, and paired with a migration path
+  when needed?
+
+## Foundation-Doc Alignment
+
+- Does implementation invalidate any assertion in foundation docs such as
+  `docs/VISION.md`, `docs/SPEC.md`, or `docs/ARCHITECTURE.md`?
+- If yes, did the implementer roll the doc forward in the same change?
+- Foundation-doc drift is a blocker in substrate mode.
+
+## Naming And Comments
+
+- Are new functions, types, and complex logic well named?
+- Do comments explain why the code exists, not just what the code says?
+- Is anything future maintainers need to understand left implicit?
+
+## Epic Review Focus
+
+For epics, skip per-line correctness, tests, and naming by default. Focus on:
+
+- Design alignment: does the realized decomposition match the brief?
+- Foundation-doc alignment: did cumulative work invalidate a foundation
+  assertion that children missed?
+- Breaking changes: are cross-cutting public API shifts visible only in aggregate?
+- Capability completeness: does the promised capability work end to end?
+
+If everything is clean, "Epic delivered as briefed; advancing to done" is a
+complete review.