diff --git a/.agents/skills/capturing-knowledge/SKILL.md b/.agents/skills/capturing-knowledge/SKILL.md new file mode 100644 index 00000000000..37ffee10bbf --- /dev/null +++ b/.agents/skills/capturing-knowledge/SKILL.md @@ -0,0 +1,177 @@ +--- +name: capturing-knowledge +description: >- + Use when the user says "capture this", "document this", "we should write that + down"; autonomously at the end of a feature when something non-obvious was + learned; or when invoked by another skill (e.g. shipping-features) as its + knowledge-capture step. Do not use when the fact is obvious from reading the + code, is recent git history, is a one-off debugging recipe, or is already + documented. Captures non-obvious facts into the project's knowledge, + guidelines, or guides docs so future agents understand the code faster. +--- + +# Capturing Knowledge + +## User Input + +```text +$ARGUMENTS +``` + +Treat `$ARGUMENTS` as a short description of what to capture. If empty, scan the +current session for capture-worthy moments (see heuristics below). + +## What this does + +Grow a project's documentation **opportunistically** during real work, so each +session leaves the codebase easier for the next agent to understand. This skill +is project-agnostic: it discovers where a project keeps its docs, proposes the +smallest useful addition, and **never writes without confirmation**. + +## When to use + +- The user says "capture this", "document this", "we should write that down". +- Autonomously at the end of a feature when something non-obvious was learned. +- When invoked by another skill (e.g. `shipping-features`) as its knowledge-capture step. + +Do **not** use this skill to record things that are obvious from the code, recent +git history, one-off debugging recipes, or facts already documented (see +"What NOT to capture"). + +## The three buckets + +Most projects separate docs into three kinds. The names and exact paths vary, but +the distinction is stable: + +| Bucket | What belongs here | +|---|---| +| **Knowledge** | How the system actually works. Architecture, contracts, data flow, non-obvious invariants. Descriptive. | +| **Guidelines** | How code should be written. Conventions, rules, "do this not that". Prescriptive. | +| **Guides** | Step-by-step recipes for a specific task (e.g. "writing a unit test"). Procedural. | + +When in doubt: if removing the doc would make a future agent *misunderstand* the +system, it's **knowledge**. If it would make them *write inconsistent code*, it's +a **guideline**. If it would make them *unable to complete a specific task*, it's +a **guide**. + +## Discover where docs live (read what exists, ask only if nothing is found) + +Before drafting anything, locate the project's documentation home. This skill must +work in any repo, so probe — don't assume a fixed layout. + +1. **Look for conventional bucket directories** (with or without a sub-domain like + `frontend/`, `backend/`, `python/`): + - Knowledge: `dev/knowledge/`, `docs/knowledge/`, `knowledge/` + - Guidelines: `dev/guidelines/`, `docs/guidelines/`, `guidelines/` + - Guides: `dev/guides/`, `docs/guides/`, `guides/` + + ```bash + fd -t d 'knowledge|guidelines|guides' dev docs 2>/dev/null || \ + find dev docs -type d \( -name knowledge -o -name guidelines -o -name guides \) 2>/dev/null + ``` + +2. **Look for pointers in `AGENTS.md` / `CLAUDE.md`.** Many projects list their doc + layout there (under a "See Also" / "Guidelines" / "Knowledge" heading). If a + pointer names a directory, use it. +3. **If buckets exist, use them.** Match the existing sub-domain when there is one + (e.g. a frontend change → `dev/knowledge/frontend/`). +4. **If nothing is found, ask the user once:** state the 1–3 facts worth capturing + and ask where captured learnings should go, or whether to skip. Never invent a + location and never write to one the user has not confirmed. + +Empty captures are a feature, not a failure: if nothing genuinely non-obvious was +learned, say so and skip — do not ask where to put nothing. + +## What to capture + +Capture only things that are: + +- **Non-obvious from reading the code** — a hidden constraint, a subtle invariant, + a "this looks wrong but it's correct because…", a deliberate choice that surprises. +- **Stable** — architecture, contracts between layers, naming conventions, ownership + boundaries. NOT specific implementations that change every sprint. +- **Reusable** — applies to more than one file or future work. + +## What NOT to capture + +- ❌ Anything obvious from reading the file: function signatures, what a component + renders, prop names. +- ❌ Recent changes / git history — `git log` and `git blame` are authoritative. +- ❌ Debugging fix recipes — the fix is in the code; the commit message has the context. +- ❌ Current-task state, in-progress work, who's doing what. +- ❌ Anything already covered in `CLAUDE.md`, `AGENTS.md`, or an existing doc. + +## Workflow + +### 1. Identify the candidate fact + +If the user gave a description as `$ARGUMENTS`, use it. Otherwise, scan the current +session for moments where you (the agent) thought *"I wish this had been documented"* +— surprising patterns, repeated questions, hidden invariants. Surface 1–3 candidates. + +### 2. Classify + +For each candidate, decide bucket (knowledge / guideline / guide) using the table +above. State the classification and the reasoning in one sentence. + +### 3. Discover the docs home + +Run the discovery steps above. If no home exists, ask the user (or skip if there is +nothing worth capturing). + +### 4. Check for duplication FIRST + +Before writing anything new, search the discovered buckets: + +```bash +grep -ri "" +``` + +- If a relevant doc already exists → **prefer updating it** with an Edit. Add the new + fact in the right section. +- If multiple docs touch the topic → consolidate; do not scatter the same fact across files. +- Only create a new file when there is **no existing home** for the fact AND the topic + is broad enough to warrant its own page. + +### 5. Draft the change + +Write the smallest possible addition. One paragraph, or a bullet under an existing +heading. Concrete examples beat abstract description — link to a real file path with +line numbers when relevant (`src/foo/bar.ts:42`). + +If creating a new file, follow the structure of the most similar existing file in the +same bucket. Keep frontmatter (if any) consistent. + +### 6. Confirm with user before writing + +Show the user: + +- The bucket + target file (existing or new) +- The exact diff (or new file contents) +- Why this is non-obvious / why it belongs + +Wait for approval. **Do not silently write docs** — the user owns what enters the +canonical knowledge base. + +### 7. Update the index entries + +If the new doc is a new file and the project has an index (e.g. an `AGENTS.md` +"See Also" section that lists docs), add a one-line pointer there so it shows up in +the skill-discovery surface for future agents. Skip if the project has no such index. + +## Heuristics for sniffing capture candidates during a session + +- An exploration agent had to grep across multiple files to find a contract → capture that contract. +- The user corrected your understanding of how something works → capture the corrected mental model. +- A pattern was reused 3+ times without being named → name it as a guideline. +- A non-trivial decision was made ("we don't do X because Y") → capture as knowledge or guideline depending on framing. +- A workflow took >5 steps to figure out from scratch → consider a guide. + +## Anti-patterns + +- ❌ Writing docs that describe what code currently *does* (read the code instead). +- ❌ Long aspirational docs that don't reflect reality on the default branch. +- ❌ Creating a new file when an existing one has 80% of the same topic. +- ❌ Capturing without user confirmation. +- ❌ Inventing a docs location instead of asking when none is found. +- ❌ Capturing in-flight implementation details that will change next week. diff --git a/.agents/skills/learning-from-review/SKILL.md b/.agents/skills/learning-from-review/SKILL.md new file mode 100644 index 00000000000..3536a2c1c88 --- /dev/null +++ b/.agents/skills/learning-from-review/SKILL.md @@ -0,0 +1,132 @@ +--- +name: learning-from-review +description: >- + Use when the user wants to learn from a reviewed pull request — "what went + wrong in this PR", "why did that get rejected", "capture the lesson from this + review" — or mid-session after the user rejects a proposal and you want to + distill the durable takeaway. Reconstructs proposed -> rejected -> corrected, + diagnoses why an agent would have proposed the rejected version, and delegates + the lesson to capturing-knowledge. Focused on one PR's review->correction + delta with cited evidence, not a broad sweep. Do not use to write docs directly + (that is capturing-knowledge), to introspect the current session for doc gaps + (that is /feedback), to run a whole-session retrospective across config, docs, + and architecture findings (that is a retrospective tool), or to review code + that has not yet been reviewed. +--- + +# Learning From Review + +## User Input + +```text +$ARGUMENTS +``` + +Treat `$ARGUMENTS` as a PR reference (number, URL, or "current branch"). If empty, +fall back to the conversation path (see below). + +## What this does + +An agent proposes a change; a reviewer (or the user) rejects it; a correction +lands. The learning is in that correction — and today it evaporates, so the next +agent proposes the same rejected shape again. This skill reconstructs +**proposed → rejected → corrected** for one PR, diagnoses *why an agent would +have proposed the rejected version*, and distills the smallest durable lesson +that would have produced the accepted version first time. It then hands that +lesson to `capturing-knowledge` to persist. It writes no docs itself. + +## When to use + +- The user points at a reviewed PR and asks what went wrong / what to learn. +- Mid-session, after the user rejects a proposal and you want the durable lesson. + +Do **not** use this to write docs directly (that is `capturing-knowledge`), to +introspect the current session for doc gaps (that is `/feedback`), or on a PR +that has not yet received change-requesting review (there is nothing to learn). + +## Workflow + +### 1. Gather + +Resolve the PR (from `$ARGUMENTS`, else the current branch's PR). Prefer an +in-repo or marketplace GitHub tool; fall back to `gh`. Collect the commit +timeline (SHAs + timestamps), review **submissions** with timestamps and states +(`CHANGES_REQUESTED` / `COMMENTED` / `APPROVED`), inline review **threads** +(body, file, line), and the diff. The **pivot** is the first submission that +requested changes. If no review ever requested changes, tell the user there is +nothing to learn from and stop. + +Useful `gh` calls: +- `gh pr view --json commits,reviews,files,title,url` +- `gh api repos/{owner}/{repo}/pulls//comments` (inline review threads) + +### 2. Segment + +- **Before (rejected proposal):** the diff state the reviewer saw at the pivot. +- **Feedback:** the change-requesting threads and review body at the pivot. +- **After (correction):** commits pushed *after* the pivot. +- **Link** each feedback thread to the correction hunks touching the same + file / lines / symbols. A thread with no later change is unresolved or a + no-op — flag it, do not invent a link. If there are multiple + change-requested rounds, run one pass per round. + +### 3. Diagnose + +For each linked (feedback → correction) pair, build one **lesson unit**: +- **Before** — what the change originally did. +- **Feedback** — the reviewer's objection, quoted verbatim. +- **After** — what was done instead. +- **Root cause** — *why would an agent have proposed the rejected version?* + (missing context, wrong assumption, unstated convention, missing/violated + guideline, misread requirement). +- **Preventive takeaway** — the smallest durable rule or fact that, had the + agent known it, yields the accepted version first time. +- **Bucket** — knowledge / guideline / guide / **drop**. + +### 4. Filter (skeptic pass) + +Before showing anything, drop noise: linter/formatter nits and anything a tool +already enforces; pure taste; rebase/merge-conflict churn; and takeaways already +present in the project's docs. Keep only lessons that would **change future +agent behaviour**. Every survivor MUST cite its evidence — **PR#, the review +comment, and the before/after hunk** — so lessons are verifiable, never invented. + +### 5. Checkpoint + +Present survivors as a table (root cause · takeaway · proposed bucket · evidence +link). The user keeps / edits / drops each. **No writes happen before this gate.** + +### 6. Delegate the write + +For each kept lesson, invoke `capturing-knowledge` with the distilled lesson as +its input — e.g. `capturing-knowledge: : (from PR +#, )`. It discovers where docs live, routes to the right bucket, and +confirms the write. This skill performs no doc writes of its own. + +## The conversation path + +Invoked with no PR, or mid-session after the user rejects a proposal. Skip +*Gather* and *Segment* (no `gh`, no diff archaeology). Reconstruct the lesson +unit from the dialogue: +- what you proposed, +- the user's rejection and its stated reasoning, +- the corrected approach that was accepted. +Then run steps 3 → 6 unchanged (diagnose → filter → checkpoint → delegate). + +## Reuse map + +Reimplement nothing. Each capability resolves through a priority chain: + +| Capability | Resolves to | +|---|---| +| Fetch PR data | in-repo/marketplace GitHub tool → `gh` fallback | +| Persist a lesson | **`capturing-knowledge`** (sibling skill) | +| Locate project docs | delegated to `capturing-knowledge`'s discovery | + +## What NOT to capture + +- Linter/formatter nits or anything a tool already enforces. +- Pure taste or subjective style with no behavioural consequence. +- Rebase / merge-conflict churn mistaken for a correction. +- Lessons already present in the project's docs (dedup before proposing). +- One-off, PR-specific facts with no reuse value. diff --git a/.agents/skills/shipping-features/SKILL.md b/.agents/skills/shipping-features/SKILL.md new file mode 100644 index 00000000000..f0309c65f7d --- /dev/null +++ b/.agents/skills/shipping-features/SKILL.md @@ -0,0 +1,259 @@ +--- +name: shipping-features +description: >- + Use when the user says "ship this feature", "run shipping-features", names a + ticket/feature/bug and asks to drive it end to end, or asks "where am I / what's + next" on in-progress work. Do not use for a single isolated step (just a spec, + just a review, just a PR) — invoke that step's tool directly. Orchestrates a + classified, manifest-driven, resumable pipeline that reuses existing tools. +argument-hint: " (empty resumes in-progress work)" +--- + +# Shipping Features + +## User Input + +```text +$ARGUMENTS +``` + +`$ARGUMENTS` is a ticket ID or short feature description. **If empty, do not ask +what to build yet — first run the resume scan** (see Manifest & resume): an +unfinished `ship.md` means the user is asking "where am I / what's next." + +## What this does + +End-to-end **conductor** for one unit of work — feature, bug, or chore — from idea +to merged-ready PR (and post-open CI watch). It **composes existing tools**: the +repo's own `.agents/skills/` and `.agents/commands/`, marketplace plugins +(superpowers, coderabbit, commit-commands) when present, and built-in agents as the +always-works fallback. It reimplements **nothing**. + +Its only original contributions are four orchestration primitives: + +1. **Classification** — every run opens by classifying the work (type × size + risk), + which selects the lane and the depth. See [phases/classification.md](phases/classification.md). +2. **A durable manifest** (`ship.md`) — the single source of truth for "where am I", + living in the speckit feature dir. See [phases/manifest.md](phases/manifest.md). +3. **A reliability model** — gates everywhere, parallel divergence at design forks, + adversarial verification at correctness claims, stacked only on risk. See + [phases/reliability.md](phases/reliability.md). +4. **Human checkpoints** between phases, so you can pause, redirect, and resume. + +## Core principles + +- **Reuse over reimplementation.** Every phase delegates to an existing tool. Reinvent nothing. +- **Classify first, then adapt.** An `S` bug and an `L` feature must not walk the same path. +- **The manifest is the source of truth.** No phase runs, completes, or resumes without + reading and updating `ship.md`. The user should never have to ask "which step am I on." +- **Gate every phase.** A phase is `done` only when its exit-criteria pass — deterministically. +- **Reliability is layered, not just parallel.** Parallelism improves *quality* at forks; + gates and adversarial verification produce *correctness*. Stack all three only on risk. +- **Stop at checkpoints.** The user approves between phases. Never chain phases unattended. +- **Degrade, never block.** A missing optional tool lowers quality; it never stops the flow. + +## Recommended companion plugins (optional) + +Most capabilities ship **in this repo** under `.agents/skills/` and `.agents/commands/` — they're +always available here. The plugins below only *add* to the built-in fallbacks. Install from the +official marketplace with `claude plugin install ` (or the `/plugin` menu). + +| Plugin | Powers | Tier | +|---|---|---| +| `superpowers` | planning, TDD, worktrees, parallel agents, review wrappers, verification | **Recommended** | +| `coderabbit` | AI correctness/security code review | **Recommended** | +| `commit-commands` | conventional commit, push, PR | Nice-to-have | +| `code-simplifier` | simplification pass on the diff | Nice-to-have | + +## Preflight: check companions once (non-blocking) + +Before phase 1, probe for the plugins above **once**. If any are missing, print a single +consolidated note naming what's absent and the install command, then **proceed immediately** with +the in-repo skills and built-in fallbacks. Do not prompt, wait, re-suggest, or auto-install. + +## Discover available context (probe → reuse → fall back) + +For each capability, use the first available source in priority order. Probe; never invent a +command the repo lacks; surface ambiguity to the user. Column 1 lists the in-repo skill/command +(what actually ships here today); reconcile against `.agents/` if names drift. + +| Capability | 1. In-repo skill/command | 2. Marketplace plugin | 3. Built-in fallback | +|---|---|---|---| +| Ticket/issue | `creating-issues`, `/create-jira-tickets` | — | skip | +| Ticket→branch (Jira/JPD) | `/speckit-git-feature` | — | `git checkout -b` | +| PRD / idea hardening | `grilling-ideas`, `creating-prd` | `superpowers:brainstorming` | ask 2–3 questions inline | +| Bug root-cause | `/bug-analyze` | — | `Explore` agents on the failing surface | +| Spec (divergent) | — | — | `Explore` agents | +| Spec (formalize) | `/speckit-specify`, `/speckit-clarify` | — | keep the synthesized brief | +| Plan (divergent) | — | — | `Plan` agents | +| Plan (formalize) | `/speckit-plan`, `/speckit-tasks` | `superpowers:writing-plans` | inline ordered task list | +| Implement (bug, TDD) | `/bug-tdd` → `/bug-fix` | `superpowers:test-driven-development` | `general-purpose` agent, test-first | +| Implement (feature, TDD) | — | `superpowers:test-driven-development` | `general-purpose` agents, test-first | +| Worktree isolation | — | `superpowers:using-git-worktrees` | `isolation: "worktree"` on Agent calls | +| Parallel execution | — | `superpowers:subagent-driven-development` / `dispatching-parallel-agents` | parallel Agent calls in one message | +| Code review | `speckit-review-run` (or per-lens `speckit-review-{code,tests,types,errors,comments}`), `speckit-review-simplify`, `speckit-critique-run` | `coderabbit:code-review`, `code-simplifier`, `superpowers:requesting-code-review` | `general-purpose` reviewers + `/security-review` | +| Residue cleanup (post-implement) | `pruning-residues` | `code-simplifier` | agent prunes leftover debug logs, dead code, orphaned files/imports, and redundant comments; else skip | +| Knowledge capture | `capturing-knowledge` | — | skip | +| Learn from review | `learning-from-review` | — | skip | +| Docs audit / consistency | `/audit-docs` → `/add-docs` | — | grep doc layers for drift; else skip | +| Session retrospective | `speckit-opsmill-retrospect` (or `/speckit.opsmill.retrospect`) | — | skip | +| Branch update / rebase | `rebase`, `/rebase-current-branch` | — | `git rebase`/`git merge` base | +| CI gate / verify | `/pre-ci` | `superpowers:verification-before-completion` | run detected test + lint commands | +| Commit | `commit`, `/git-commit` | `commit-commands:commit` | `git commit` (conventional message) | +| PR | `pr`, `/git-pr` | `commit-commands:commit-push-pr`, `superpowers:finishing-a-development-branch` | `gh pr create` | +| Post-open CI watch | `monitoring-pull-requests` | — | `gh run watch` / skip | + +## Reliability model (read before phase 1) + +Three layers, applied per phase, scaled by size, stacked only on risk. Full rules and the +risk-triggered stacking table are in [phases/reliability.md](phases/reliability.md). In brief: + +- **Gate (always):** every phase declares exit-criteria checked *before* its checkpoint. No + green criteria → not `done` in `ship.md`. +- **Parallel divergence (design forks):** spec & plan on `M`/`L`. Multiple *framings*, then one + synthesizer. Never on deterministic phases; never as N copies of the same prompt. +- **Adversarial verify (correctness claims):** after implement & review, a skeptic agent tries + to *refute* the claim ("this doesn't fix it", "this finding is a false positive"). +- **Stack all three** on a phase only when a **risk flag** (`irreversible | security | cross-team + | crux-algorithm`) is set at classification — the user confirms it, the model does not guess it. + +## Classification (phase 0 — opens every run) + +Follow [phases/classification.md](phases/classification.md): propose `type` (bug / feature / +chore), `size` (S / M / L), and any `risk` flags from the ticket text and diff surface; the user +confirms or overrides at a checkpoint. Write the confirmed values to `ship.md`. **Never re-ask on +resume** — the manifest already holds them. + +The lane and depth follow from the classification: + +| Phase | `bug` | `feature` | `chore` | +|---|---|---|---| +| Ticket/branch | `creating-issues` → `/speckit-git-feature` | same | same | +| Understand | `/bug-analyze` → `analysis.md` | `grilling-ideas` → `/speckit-specify` → `spec.md` | short inline brief | +| Plan | skip on `S`, else light | `/speckit-plan` + `/speckit-tasks` → `plan.md`, `tasks.md` (`M`/`L`) | skip | +| Implement | `/bug-tdd` → `/bug-fix` | TDD agents (worktrees on `L`) | direct edit | +| Review | `speckit-review-run` → `review.md` + verify | same | same (lighter) | +| Knowledge & learning | `capturing-knowledge` + `learning-from-review` + `speckit-opsmill-retrospect` + `/audit-docs` (conditional) | same | same | +| CI gate | `/pre-ci` | same | same | +| Commit | `commit` | same | same | +| PR | `pr` → split assessment | same | same (usually single PR) | +| CI watch | `monitoring-pull-requests` | same | same | + +`S` runs its lane straight through (gate + one verify, no parallelism). `M`/`L` light up the +parallel front-end and, on a risk flag, the stacked verify. + +## Manifest & resume + +`ship.md` lives in the speckit feature dir (`specs/NNN-slug/`, located via `.specify/feature.json`). +It records classification, the selected phase list, per-phase status, and links to every artifact. +Follow [phases/manifest.md](phases/manifest.md) for its schema, the update contract, and the +**resume + reconcile** logic (re-invoking the skill scans for an unfinished `ship.md`, prints a +status board, reconciles claimed-`done` phases against reality, and continues at the first +unfinished phase). + +## Phases + +Each phase below: **delegates to** a discovered tool, **reads** the upstream artifacts named in +`ship.md`, **writes** its own artifact back, runs its **gate**, then **checkpoints**. Update +`ship.md` at every transition. + +### Phase 0 — Classify +Per [phases/classification.md](phases/classification.md). Create `ship.md` (or resume an existing +one). **Checkpoint:** user confirms type / size / risk before any work. + +### Phase 1 — Ticket & branch +If no ticket and the project tracks issues, offer `creating-issues` (or `/create-jira-tickets`). +Create the feature branch via `/speckit-git-feature` (validates Jira/JPD ref, names the branch) or +`git checkout -b` fallback. Record ticket + branch in `ship.md`. **Gate:** on a named branch, not the base branch. + +### Phase 2 — Understand +- **bug:** `/bug-analyze` → `analysis.md` (root cause + repro). **Gate:** a concrete repro exists. +- **feature:** harden with `grilling-ideas` (or `creating-prd`) if fuzzy; **diverge** (3 `Explore` framings: existing + patterns / related entities & APIs / test-coverage gaps) → **synthesize** 1 brief; formalize + with `/speckit-specify` (+`/speckit-clarify`) → `spec.md`. **Gate:** no unresolved + `[NEEDS CLARIFICATION]`. +- **chore:** short inline brief. **Gate:** scope stated in one paragraph. +**Checkpoint:** show the artifact + open questions. + +### Phase 3 — Plan (feature `M`/`L`; skipped otherwise) +**Diverge** (3 `Plan` framings: minimal / refactor-friendly / test-first) → **synthesize** one +ordered task list; formalize with `/speckit-plan` + `/speckit-tasks` → `plan.md`, `tasks.md`. +On a risk flag, add a skeptic pass on the synthesis (see reliability). **Gate:** every task +references files that exist; plan cites the spec. **Checkpoint:** merged plan + tradeoffs. + +### Phase 4 — Implement +- **bug:** `/bug-tdd` (failing test) → `/bug-fix`. +- **feature/chore:** group `tasks.md` into independent units; run TDD agents (worktree isolation + on `L`); independent units in parallel (one message), dependent units sequentially. +- **Prune residues** before the gate: run `pruning-residues` (fallback `code-simplifier`, or an + agent instructed to strip leftover debug logs, dead code, commented-out blocks, orphaned + files/imports, and redundant/obvious comments the implementation introduced). This tightens the + diff *before* review sees it — re-run the gate test after pruning so cleanup can't silently break anything. +Verify the real diff, never the self-report. **Gate + adversarial verify:** a test that was red is +now green (on the pruned diff) *and* a skeptic agent fails to refute "this actually implements the +spec/fixes the bug." **Checkpoint** only if a blocker surfaces or on `L`. + +### Phase 5 — Review (pre-PR) +The in-repo `speckit-review-*` suite already **is** the divergence — its lenses (`speckit-review-code`, +`-tests`, `-types`, `-errors`, `-comments`) map onto the parallel framings. Prefer `speckit-review-run` +(runs the suite) or the individual lenses in parallel, plus `speckit-review-simplify` and +`speckit-critique-run`; add `coderabbit:code-review` / `code-simplifier` / `/security-review` when +present. Fallback: 2–3 framed `general-purpose` reviewers. → **synthesize** a severity-ranked fix +list (blocker / nit / suggestion) → **adversarial verify** each finding is real before acting. Wrap +with `superpowers:requesting-code-review` / `receiving-code-review` when present. Write `review.md`. +**Gate:** zero unaddressed blockers. **Checkpoint:** ranked list, then fix pass (small parallel +agents per file group). + +### Phase 6 — Knowledge, learning & retrospective (opportunistic) +1. **Capture domain facts** — delegate to `capturing-knowledge` (no args). Skip silently if nothing + genuinely new was learned — empty captures are a feature. +2. **Learn from the review** — delegate to `learning-from-review` (PR ref, or the current branch's PR; + else the phase-5 review threads). It reconstructs proposed → rejected → corrected, distills the + durable lesson that would have produced the accepted version first time, and hands it to + `capturing-knowledge` to persist. Skip if phase 5 requested no changes — there is nothing to learn. +3. **Audit docs** — run `/audit-docs` against this branch's changes (it cross-references the doc layers + and reports gaps/drift, so the docs stay consistent with what was actually built). For each real + gap, update or create the doc with `/add-docs` (fallback: edit the doc directly). +4. **Retrospective** — delegate to `speckit-opsmill-retrospect` (or the `/speckit.opsmill.retrospect` + command) while the session is fresh: it surfaces context-management/tooling gaps (AGENTS.md, skills, + commands, guides, templates) that caused avoidable friction and routes each to a disposition — + `fix-now`, `open-pr`, `github-issue`, or `local-only`. It writes `retrospective.md` in the feature + dir and stays read-only until you approve per bucket. Distinct from the steps above: + `capturing-knowledge` records *domain/code* facts, `learning-from-review` distills *review* lessons, + and the retrospective improves the *process & tooling* surface. Skip cleanly if the skill is absent. +Any doc changes join **this** PR (no separate docs PR unless the user asks). Record the retrospective +report path + chosen dispositions in `ship.md`. **Checkpoint** only if any step proposes changes — +otherwise skip silently. + +### Phase 7 — CI gate (must-pass before PR) +Run `/pre-ci` (or `superpowers:verification-before-completion`, or detected test+lint commands — +never invented). Red → loop back to the phase 5 fix pass. **Do not proceed with a red gate.** +**Checkpoint:** results. + +### Phase 8 — Commit & PR +1. **Commit** any final drift with `commit` → `/git-commit` → `commit-commands:commit` → + `git commit`. By now work was committed iteratively in phase 4; do not auto-commit to satisfy a + command — surface a dirty-tree refusal instead. +2. **Split assessment** (bias toward single PR) per [phases/pr-split.md](phases/pr-split.md). + **Checkpoint:** user picks single / accepts split / proposes another. Never force a split. +3. **Open** each approved PR with `pr` → `/git-pr` → `commit-commands:commit-push-pr` → + `superpowers:finishing-a-development-branch` → `gh pr create`. For split PRs prepend + `Depends on #` and open in dependency order. Record PR URL(s) in `ship.md`. + +### Phase 9 — Post-open CI watch +Delegate to `monitoring-pull-requests` (or `gh run watch`) to watch the opened PR's CI. On red, surface the +failure and loop back to phase 5's fix pass. Record final CI status in `ship.md`. Skip cleanly if +no watch tool resolves. **Terminal checkpoint:** green CI + PR URL(s) → shipped & done. + +## Anti-patterns + +- ❌ Asking "what should I build?" when `$ARGUMENTS` is empty — run the resume scan first. +- ❌ Running or completing a phase without reading/updating `ship.md`. +- ❌ Marking a phase `done` without its exit-criteria gate passing. +- ❌ Trusting a claimed-`done` phase on resume without reconciling it against the branch. +- ❌ Running the same lane for a bug and an L feature. +- ❌ Skipping the synthesizer between parallel agents; or feeding N framings into N implementers. +- ❌ Stacking all three reliability layers on a phase with no risk flag. +- ❌ Reimplementing anything in the discovery table, or inventing a command the project lacks. +- ❌ Blocking on a missing optional plugin, re-suggesting it every phase, or auto-installing it. +- ❌ Opening a PR with a red CI gate; forcing a PR split when the changes are coupled. diff --git a/.agents/skills/shipping-features/docs/overview-and-design.md b/.agents/skills/shipping-features/docs/overview-and-design.md new file mode 100644 index 00000000000..a23d95e332a --- /dev/null +++ b/.agents/skills/shipping-features/docs/overview-and-design.md @@ -0,0 +1,111 @@ +# Shipping Features — overview & design + +> A short brief for discussing the `shipping-features` skill with the team. +> Companion to the skill itself (`../SKILL.md`) and its phase references (`../phases/`). + +## The problem it solves + +Shipping a change end to end means touching many tools — Jira, spec, plan, code, tests, +review, CI, PR — and today that means the developer (and the agent) constantly asks: + +> *"Where am I? Which step is done? Which skill do I run next?"* + +`shipping-features` exists to make that question disappear. It is a **conductor**: it doesn't +re-implement spec/plan/review/PR logic, it **orchestrates the tools we already have** and keeps a +durable record of where the work stands so anyone — or any session — can pick it up. + +## Three ideas, in one paragraph each + +**1. Classify first.** Every run opens by classifying the work along three axes — **type** +(bug / feature / chore), **size** (S / M / L), and optional **risk flags** (irreversible, +security, cross-team, crux-algorithm). The agent proposes a classification; the user confirms it +at a checkpoint. This picks the *lane* (a bug goes `bug-analyze → bug-tdd → bug-fix`; a feature +goes `grilling-ideas → spec → plan → implement`) and the *depth* (an S fix skips specs entirely; an L +feature gets the full treatment). One workflow, shaped to the work. + +**2. A durable manifest (`ship.md`).** Each unit of work gets a `ship.md` inside its speckit +feature dir (`specs/NNN-slug/`) — the single source of truth. It records the classification, the +selected phase list with per-phase status (`todo / in-progress / done / skipped`), and links to +every artifact (`spec.md`, `plan.md`, `review.md`, the PR URL). Re-running the skill scans for an +unfinished `ship.md`, prints a **status board**, and resumes at the first unfinished phase — so +pause/resume/redirect is free, and survives across sessions and machines. Before trusting a +`done` phase on resume it **reconciles** the manifest against the repo (branch state, artifacts, +tests) so it never ships stale state. + +**3. A layered reliability model.** Parallelism alone doesn't make results *reliable* — it makes +them *better at design forks*. Reliability comes from three independent layers: +- **Gate** — every phase has deterministic exit-criteria; it can't be marked `done` until they pass. +- **Parallel divergence** — multiple framings + a synthesizer, but only at genuine design forks + (spec, plan) and only on M/L. +- **Adversarial verify** — a skeptic agent tries to *refute* a correctness claim (implement, review). + +These sit at opposite ends of the pipeline (divergence before work exists; verification after a +claim exists), so they rarely stack on one phase. All three stack **only** when a risk flag makes +the extra cost worth it — because parallel agents share priors and can share a blind spot, and a +skeptic breaks that correlated error. The user confirms the risk flag; the model doesn't guess it. + +## Artifacts as the interface between steps + +Every phase **reads** the upstream artifacts named in `ship.md` and **writes** its own artifact +back. Nothing is re-derived from scratch. This makes the flow inspectable (open the feature dir and +read the story), shareable (hand someone the dir), and resumable (the artifacts + `ship.md` are the +whole state). + +``` +specs/001-user-auth/ + ship.md ← manifest: classification, phase status, artifact links + spec.md ← phase 2 (feature) | analysis.md ← phase 2 (bug) + plan.md + tasks.md + review.md ← phase 5 + retrospective.md ← phase 6 + → PR URL recorded in ship.md (phase 8), CI status (phase 9) +``` + +## Reuse over reimplementation + +The skill's core rule. Each capability resolves through a priority chain +(**in-repo skill/command → marketplace plugin → built-in fallback**), so it works in any repo and +gets better as more tools are installed. These all ship in-repo under `.agents/`: +`creating-issues`, `creating-prd`, `grilling-ideas`, `/bug-analyze`·`/bug-tdd`·`/bug-fix`, the +`speckit-*` suite (including `speckit-review-{code,tests,types,errors,comments,simplify}` and +`speckit-critique-run`), `pruning-residues` (post-implement cleanup of dead code, debug logs, and +redundant comments), `capturing-knowledge`, `learning-from-review` (distills review lessons), +`/audit-docs`·`/add-docs` (docs-consistency audit), `rebase`, `commit`, `pr`, +`monitoring-pull-requests` (post-open CI watch), and `speckit-opsmill-retrospect` (retrospective, +run at the knowledge step). + +## The pipeline at a glance + +| # | Phase | Delegates to | Reliability layers | +|---|---|---|---| +| 0 | Classify | (this skill) | checkpoint | +| 1 | Ticket & branch | `creating-issues`, `/speckit-git-feature` | gate | +| 2 | Understand | `/bug-analyze` / `grilling-ideas`+`/speckit-specify` | gate (+ parallel on feature M/L) | +| 3 | Plan | `/speckit-plan`+`/speckit-tasks` | gate + parallel (+ skeptic on risk) | +| 4 | Implement | `/bug-tdd`+`/bug-fix` / TDD agents · prune residues | gate + adversarial verify | +| 5 | Review | `speckit-review-run`, `coderabbit`, `/security-review` | gate + parallel + verify | +| 6 | Knowledge, learning & retrospective | `capturing-knowledge` + `learning-from-review` + `speckit-opsmill-retrospect` + `/audit-docs`→`/add-docs` | conditional | +| 7 | CI gate | `/pre-ci` | gate | +| 8 | Commit & PR | `commit`, `pr`, split assessment | parallel (split) | +| 9 | CI watch | `monitoring-pull-requests` | gate | + +Checkpoints sit between phases; the user can pause, redirect, reclassify, or jump at any of them. +**Two cleanups keep it consistent:** code residues + stale comments at phase 4 (`pruning-residues`), +docs & knowledge at phase 6 (`capturing-knowledge` + `/audit-docs`). + +## Open questions for the team + +- Is `specs/NNN-slug/` the right home for `ship.md`, or should bug/chore work (which may skip + speckit) use a lighter location? +- Which risk flags actually earn stacked verification in our codebase? Are four too many/few? +- Should phase 9 (CI watch) block the "done" state, or just report? +- What's the right default size→depth mapping — is `L` too eager to spin up worktrees + 3–4 agents? + +## Status + +Draft skill on branch `ple-test-shipping-features-skill`, rebased onto latest `develop` so every +in-repo tool it delegates to resolves today. A first **pressure-test pass** held: fresh agents kept +the rules — resume-scan on empty input, classify-don't-over-engineer under time pressure, refuse a +red CI gate, and never mark a phase done without its gate — under "we're late, skip it" pressure. +A fuller RED→GREEN→REFACTOR pass is still worthwhile before heavy use. diff --git a/.agents/skills/shipping-features/phases/classification.md b/.agents/skills/shipping-features/phases/classification.md new file mode 100644 index 00000000000..5284823b014 --- /dev/null +++ b/.agents/skills/shipping-features/phases/classification.md @@ -0,0 +1,59 @@ +# Phase 0 — Classification + +The first thing every `shipping-features` run does. Classification selects the **lane** (which +sibling skills run) and the **depth** (how much divergence/verification), so an `S` bug and an +`L` feature never walk the same path. The model **proposes**; the user **confirms** at a checkpoint. + +## What to classify + +Three axes. Write all three to `ship.md`. + +### 1. Type — routes the lane + +| Type | Signals | Lane head | +|---|---|---| +| `bug` | "broken", "regression", stack trace, failing test, "used to work" | `/bug-analyze` → `/bug-tdd` → `/bug-fix` | +| `feature` | new capability, user story, "add", "support", "allow users to…" | `grilling-ideas` → `/speckit-specify` → plan → implement | +| `chore` | refactor, dependency bump, rename, config, docs-only, cleanup | inline brief → direct edit | + +When ambiguous (a "bug" that's really a missing feature), state the ambiguity and let the user pick. + +### 2. Size — sets the depth + +| Size | Heuristic (any one qualifies) | Depth | +|---|---|---| +| `S` | one file / a few lines; obvious fix; no design choice | skip specs & plan; 1 agent; gate + one verify; no parallelism | +| `M` | a few files; one clear approach; minor design choice | light spec; 2 agents; parallel spec only if a real fork exists | +| `L` | many files / cross-cutting; genuine design forks; new surface area | full spec → plan → split; 3–4 parallel framings; worktrees | + +Size is about **decision complexity**, not raw line count. A 500-line mechanical rename is `S`; +a 40-line change to auth logic is `L`. + +### 3. Risk flags — trigger stacked verification + +Zero or more. Each one turns on the third reliability layer for the phases it touches +(see [reliability.md](reliability.md)). + +| Flag | Set when | Effect | +|---|---|---| +| `irreversible` | data migration, schema change, deletion, public API change | skeptic pass on the plan synthesis | +| `security` | auth, permissions, secrets, input handling, crypto | `/security-review` mandatory; skeptic on review findings | +| `cross-team` | touches contracts other teams depend on; needs >1 reviewer | plan skeptic + note reviewers in PR | +| `crux-algorithm` | one genuinely hard algorithmic unit | twin independent implementations of that unit, gated + refuted | + +## How to propose + +1. Read `$ARGUMENTS` (ticket text / description) and, if a branch already has changes, the diff surface. +2. Emit a one-line guess: *"Looks like a **medium bug fix**, no risk flags — lane: analyze → tdd → fix → review → PR."* +3. **Checkpoint (AskUserQuestion or inline):** user confirms or overrides type / size / risk. +4. Write the confirmed values to `ship.md` and derive the phase list from them. + +## Rules + +- **Confirm before working.** Classification is a hard checkpoint — never skip it, even when "obvious". +- **Never re-ask on resume.** If `ship.md` already holds a classification, use it; only re-classify + if the user explicitly asks to reclassify (record the change in `ship.md`). +- **Reclassification is allowed mid-flight.** If the work turns out bigger than thought, bump the + size, note it in `ship.md`, and add the phases the new size requires. Don't silently keep the old lane. +- **Don't guess risk flags to look thorough.** A flag you can't justify from the ticket/diff is noise + that just burns tokens on stacked verification. When unsure, leave it off and say so. diff --git a/.agents/skills/shipping-features/phases/manifest.md b/.agents/skills/shipping-features/phases/manifest.md new file mode 100644 index 00000000000..f784b141f70 --- /dev/null +++ b/.agents/skills/shipping-features/phases/manifest.md @@ -0,0 +1,101 @@ +# The `ship.md` manifest & resume logic + +`ship.md` is the **single source of truth** for a unit of work in flight. It answers the three +questions this skill exists to eliminate: *where am I, what's done, what's next.* Every phase reads +it and updates it; resume relies on it entirely. + +## Location + +Inside the speckit feature dir, alongside the artifacts it indexes: + +``` +specs/NNN-slug/ + ship.md ← this manifest + spec.md (feature) + analysis.md (bug) + plan.md tasks.md (feature M/L) + review.md +``` + +Locate the dir via `.specify/feature.json` (`{"feature_directory": "specs/NNN-slug"}`). If speckit +isn't initialized yet (bug/chore that skips speckit), create `specs/NNN-slug/ship.md` directly using +the branch slug, and still write `feature.json` so downstream speckit calls agree on the dir. + +## Schema + +Human-readable and glanceable on purpose — the user opens it to orient, and the model parses it to resume. + +```markdown +# Ship: + +type: feature # bug | feature | chore +size: L # S | M | L +risk: [security] # subset of: irreversible security cross-team crux-algorithm (or none) +ticket: INFP-460 # or none +branch: user-auth-infp-460 +base: develop +updated: 2026-07-06 + +## Phases +- [x] classify → (this file) +- [x] ticket-branch → branch user-auth-infp-460 +- [x] understand → spec.md +- [x] plan → plan.md, tasks.md +- [>] implement → 3/5 tasks; worktrees wt-a, wt-b +- [ ] review → +- [ ] knowledge → +- [ ] ci → +- [ ] commit-pr → +- [ ] ci-watch → + +## Artifacts +- spec.md, plan.md, tasks.md +- pr: + +## Notes +- 2026-07-06 reclassified M→L after auth surface turned out cross-cutting. +``` + +Status markers: `[ ]` todo · `[>]` in-progress · `[x]` done · `[-]` skipped (with a reason in Notes). +The phase list is **derived from the classification** — only list phases the lane actually runs. + +## Update contract + +- **On entering a phase:** flip it to `[>]`, bump `updated`. +- **On finishing a phase:** flip to `[x]` **only after its exit-criteria gate passes**; record the + artifact it produced on the same line. +- **On skipping a phase:** `[-]` with a one-line reason in Notes (e.g. knowledge capture found nothing). +- **On reclassification:** update the axes, add/remove phases, append a dated Note. +- Never mark a phase `[x]` speculatively. The manifest must reflect reality, not intent. + +## Resume + reconcile + +When the skill is invoked with empty `$ARGUMENTS`, or on any re-entry: + +1. **Scan** for an unfinished `ship.md` (search `specs/*/ship.md` with an incomplete phase list; + prefer one whose `branch` matches the current git branch). +2. **None found** → this is new work; ask what to ship and start at phase 0. +3. **Found** → print a **status board**: the phase list with markers, the classification line, and + the next action. This is the "where am I" answer. +4. **Reconcile before trusting** — the manifest can drift from reality (a branch was reset, a + worktree removed, tests now fail). For each `[x]` phase, cheaply verify its claim still holds: + + | Phase | Reconcile check | + |---|---| + | ticket-branch | branch exists and is checked out | + | understand/plan | the named artifact file exists and is non-empty | + | implement | branch is ahead of base; the phase-4 gate test is still green | + | ci | re-run is fast? if not, trust the recorded result but flag its age | + | commit-pr | the PR URL still resolves and is open | + + A failed check **re-opens** that phase (`[x]`→`[>]`) and everything downstream of it. Say so + explicitly: *"implement was marked done but the gate test is red — re-opening implement + review."* +5. **Continue** at the first non-`[x]`/`[-]` phase, honoring the between-phase checkpoints. + +## Rules + +- The manifest is authoritative for *bookkeeping*, the repo is authoritative for *truth* — reconcile + reconciles the two, and the repo always wins. +- One `ship.md` per unit of work (per feature dir / branch). Don't share one across branches. +- User overrides are first-class: "redo review", "skip knowledge", "jump to PR" just edit the markers + (with reconciliation for anything they jump past) — no separate command needed. diff --git a/.agents/skills/shipping-features/phases/pr-split.md b/.agents/skills/shipping-features/phases/pr-split.md new file mode 100644 index 00000000000..cc85093e844 --- /dev/null +++ b/.agents/skills/shipping-features/phases/pr-split.md @@ -0,0 +1,39 @@ +# Phase 8 — PR split assessment (bias toward single PR) + +Reference for the split-assessment step of `shipping-features` (phase 8, before opening the PR). +Apply the **parallel divergence + synthesize** layer to the split decision. + +## Diverge + +Run **3 `general-purpose` agents in parallel** against `git diff ...HEAD` and +`git log ..HEAD` (auto-detect the base branch), each with a deliberately +different framing: + +- **Reviewer ergonomics** — "what split would make this fastest to review?" (favors small, focused PRs) +- **Risk isolation** — "what split would let us revert one part without affecting others?" (favors separating high-risk from low-risk) +- **Coherence preservation** — "what's the simplest narrative? when would splitting break tests or tell a worse story?" (favors a single PR; the counterweight) + +Each agent returns *"ship as one"* or *"split into N groups: ..."* with reasoning. + +## Synthesize + +**1 `general-purpose` agent**, applying a strong bias toward a single PR: + +- **Only recommend a split when ≥2 of the 3 framings independently suggest it**, AND at least one of: + - Independent concerns (unrelated drive-by refactor, or backend + frontend independently reviewable). + - Different reviewers needed (infra/CI vs. product). + - Different risk profiles (low-risk config + high-risk feature). + - Revertable in isolation. +- **Do NOT recommend a split when:** + - ❌ Changes are coupled (feature + its own tests + its own docs). + - ❌ Splitting would leave one PR with broken tests or builds. + - ❌ The change has a single coherent narrative. + - ❌ The split would create a chain of dependent PRs that must merge in order for little value. + +## Output + +The synthesizer outputs one of: + +- **"Ship as one PR"** with a one-line justification. +- **"Suggest split into N PRs"** with the proposed groupings (which commits / files go where, in + dependency order), plus an explicit *"but a single PR is also reasonable"* note when borderline. diff --git a/.agents/skills/shipping-features/phases/reliability.md b/.agents/skills/shipping-features/phases/reliability.md new file mode 100644 index 00000000000..51cd0f10caf --- /dev/null +++ b/.agents/skills/shipping-features/phases/reliability.md @@ -0,0 +1,60 @@ +# Reliability model + +Three independent layers, each catching a different failure mode. The gate is universal; +parallel and adversarial-verify sit at opposite ends of the pipeline; all three stack on a +single phase **only** when a risk flag makes it worth the cost. + +## The three layers + +| Layer | Catches | Fires | +|---|---|---| +| **Gate** (exit-criteria) | artifact is objectively incomplete / malformed | end of *every* phase, deterministic | +| **Parallel** (divergent framings + synthesize) | a locally-optimal but narrow approach | *before* work exists — genuine design forks only | +| **Adversarial verify** (skeptic tries to refute a claim) | looks right but is actually wrong | *after* a phase emits a checkable correctness claim | + +**Why they don't all belong everywhere:** parallel and adversarial-verify apply at opposite ends. +A spec/plan phase has a design fork but no ground truth yet → parallel helps, a skeptic has nothing +concrete to refute. An implement/review phase produces a concrete claim → a skeptic is exactly right, +but divergence is wrong (each implement agent owns *different work*, not a *different framing*). + +## Default placement (no risk flags) + +| Phase | Gate | Parallel | Verify | +|---|---|---|---| +| understand (spec/plan) | ✅ | ✅ on `M`/`L` (framings → synthesize) | — (speckit-analyze/clarify already play the check role) | +| implement | ✅ (red→green test) | — | ✅ skeptic: "does this actually implement the spec / fix the bug?" | +| review | ✅ (no open blockers) | ✅ (review lenses → synthesize) | ✅ (verify each finding is real before acting) | +| ci / commit / pr | ✅ | — | — (deterministic) | + +**Review is the one phase that naturally runs all three** — multiple lenses diverge, a synthesizer +ranks, then each finding is verified real. It's read-only, so it's cheap. That's by design, not a risk escalation. + +## Risk-triggered stacking + +Add the *third* layer to a phase only when a risk flag set at classification justifies it. The +trigger is: **high blast radius AND the first two layers share a failure mode** (parallel agents read +the same codebase, so their framings — and the synthesizer inheriting them — can share a blind spot; a +skeptic breaks that correlated error). + +| Risk flag | Escalation | +|---|---| +| `irreversible` | skeptic pass on the **plan synthesis** — red-team "what breaks in prod that all framings missed" | +| `security` | `/security-review` mandatory in review; skeptic on each security finding | +| `cross-team` | plan-synthesis skeptic + name required reviewers in the PR body | +| `crux-algorithm` | on the one hard unit only: **two independent implementations** (real divergence on implement), gate on tests, skeptic picks the survivor apart | + +## Scaling by size + +- **`S`** — gate + one verify on implement. No parallelism. A skeptic on a one-line fix is enough. +- **`M`** — parallel only where a real fork exists; verify on implement + review. +- **`L`** — full parallel front-end (spec, plan), verify on implement + review, plus any risk stacking. + +## Rules + +- **Gate first, always.** If you add only one layer to a phase, it's the gate. Parallel and verify + are refinements on top of a gate, never replacements for it. +- **One synthesizer per divergence.** Never feed N parallel framings into N downstream agents. +- **A skeptic must try to fail the claim.** Prompt it to refute, defaulting to "not proven" when + uncertain — a verifier that rubber-stamps is worse than none (false confidence). +- **Don't stack to look thorough.** Three layers on a no-risk phase is wasted tokens and slower + checkpoints. Match the layers to the flags in `ship.md`.