{"owner":"backnotprop","repo":"plannotator","hasSkills":true,"totalSkillsCount":76,"totalTokensCount":37275,"categories":["anthropic-skill","root-instruction","marketplace","plugin-manifest","command-prompt"],"hasMcp":false,"mcpConfig":null,"found":[".agents/skills/update-deps/SKILL.md",".agents/skills/review-renovate/SKILL.md","apps/skills/extra/plannotator-visual-explainer/SKILL.md","apps/skills/extra/plannotator-setup-goal/SKILL.md",".agents/skills/release/SKILL.md","apps/skills/extra/plannotator-compound/SKILL.md","apps/skills/core/plannotator-review/SKILL.md","apps/skills/core/plannotator-last/SKILL.md","apps/skills/core/plannotator-annotate/SKILL.md","apps/skills/claude/plannotator-review/SKILL.md","apps/skills/claude/plannotator-last/SKILL.md","apps/skills/claude/plannotator-annotate/SKILL.md","apps/kiro-cli/skills/plannotator-review/SKILL.md","apps/kiro-cli/skills/plannotator-annotate/SKILL.md","AGENTS.md",".claude-plugin/marketplace.json",".factory-plugin/marketplace.json",".github/plugin/marketplace.json","apps/copilot/plugin.json","packages/ui/AGENTS.md","packages/ui/HANDOFF.md","packages/ui/package.json","packages/ui/README.md","packages/ui/tsconfig.json","packages/ui/tsconfig.strict-consumer.json","packages/shared/package.json","packages/shared/tsconfig.json","packages/server/codex-review-schema.json","packages/server/package.json","packages/server/tsconfig.json","packages/review-editor/package.json","packages/review-editor/tsconfig.json","packages/editor/package.json","packages/core/package.json","packages/core/tsconfig.json","packages/ai/package.json","packages/ai/tsconfig.json","apps/opencode-plugin/commands/plannotator-annotate.md","apps/opencode-plugin/commands/plannotator-last.md","apps/opencode-plugin/commands/plannotator-review.md","apps/kiro-cli/agents/plannotator.json","apps/hook/.claude-plugin/plugin.json","apps/droid-plugin/.factory-plugin/plugin.json","apps/copilot/commands/plannotator-annotate.md","apps/copilot/commands/plannotator-last.md","apps/copilot/commands/plannotator-review.md","packages/ui/.migration/badge.md","packages/ui/.migration/button.md","packages/ui/.migration/dialog.md","packages/ui/.migration/dropdown-menu.md","packages/ui/.migration/popout-dialog.md","packages/ui/.migration/popover.md","packages/ui/.migration/project.md","packages/ui/.migration/tabs.md","packages/ui/.migration/tooltip.md","packages/review-editor/.migration/checkbox.md","packages/review-editor/.migration/context-menu.md","packages/review-editor/.migration/dropdown-menu.md","packages/review-editor/.migration/popover.md","packages/review-editor/.migration/project.md",".agents/skills/release/references/release-notes-v0.12.0.md",".agents/skills/release/references/release-notes-v0.13.0.md",".agents/skills/release/references/release-notes-v0.13.1.md","apps/skills/extra/plannotator-visual-explainer/references/design-system.md","apps/skills/extra/plannotator-visual-explainer/references/pr-components.md","apps/skills/extra/plannotator-visual-explainer/references/svg-patterns.md","apps/skills/extra/plannotator-visual-explainer/references/theme-override.md","apps/skills/extra/plannotator-setup-goal/agents/openai.yaml","apps/skills/extra/plannotator-compound/references/claude-code-fallback.md","apps/skills/core/plannotator-review/agents/openai.yaml","apps/skills/core/plannotator-last/agents/openai.yaml","apps/skills/core/plannotator-annotate/agents/openai.yaml","apps/marketing/src/content/docs/commands/annotate.md","apps/marketing/src/content/docs/commands/annotate-last.md","apps/marketing/src/content/docs/commands/code-review.md","apps/marketing/src/content/docs/commands/plan-review.md"],"skills":{".agents/skills/update-deps/SKILL.md":"---\nname: update-deps\ndescription: Audit and update npm/Bun dependencies with supply chain integrity checks — verifies maintainers, publish age, tarball diffs, and provenance before bumping. Defers risky packages to ~/.supply-chain/notes/.\ndisable-model-invocation: true\n---\n\n# Update Dependencies\n\nAudit outdated packages, verify supply chain integrity, bump what's safe, defer what needs review, and log everything.\n\nThis process has three phases: discovery, integrity audit, and execution. The integrity audit is the most important — every package gets checked before it touches the lockfile.\n\n## Phase 1: Discovery\n\nRun `bun outdated` to get the full list of packages with available updates.\n\n```bash\nbun outdated\n```\n\nParse the output into a structured list. For each package, note:\n- Package name\n- Current version\n- Available update version\n- Whether it's age-gated (indicated by `*` in the output — the footnote \"The * indicates that version isn't true latest due to minimum release age\" confirms this)\n- Whether it's a runtime dep, dev dep, or peer dep\n\nAlso check whether any packages are blocked entirely by the age gate (like `@pierre/diffs` was when its minimum semver range couldn't resolve). Flag these separately — they may need `minimumReleaseAgeExcludes` in `bunfig.toml`.\n\n## Phase 2: Integrity Audit\n\nThis is the core of the process. Spawn one **Sonnet sub-agent per package** to run the integrity check in parallel. Sonnet is used here because these are independent, structured verification tasks that don't need heavier reasoning.\n\nEach sub-agent receives the package name, current version, and target version, and performs the following checks:\n\n### Sub-agent prompt template\n\nFor each outdated package, spawn a Sonnet agent with this task:\n\n```\nYou are auditing the npm package \"{package}\" for a version bump from {current} to {target}.\n\nRun these checks and report back with a JSON object:\n\n1. **Maintainer verification**: Check if maintainers changed between versions.\n npm view {package}@{current} maintainers --json\n npm view {package}@{target} maintainers --json\n Compare the two lists. Flag any additions or removals.\n\n2. **Publish date and age**: Get the publish timestamp.\n npm view {package} time --json\n Extract the date for version {target}. Calculate days since publication.\n Flag if younger than 7 days.\n\n3. **Provenance**: Check if the package has registry signatures or attestations.\n npm audit signatures (if not already run this session)\n Note whether the package has provenance attestations.\n\n4. **Tarball diff**: Show what actually changed in the published package.\n npm diff --diff={package}@{current} --diff={package}@{target}\n Summarize the changes:\n - How many files changed\n - Are changes limited to version bumps, deps, and rebuilt dist? Or are there meaningful source changes?\n - Any new runtime dependencies added?\n - Any suspicious patterns (obfuscated code, eval(), network calls in unexpected places)\n\n5. **Release notes**: Try to find what changed.\n Check the package's repository for release notes or changelog:\n npm view {package}@{target} repository.url\n gh release view v{target} --repo (try with and without v prefix)\n Summarize the changelog if found.\n\nReport your findings as JSON:\n\n{{\n \"package\": \"{package}\",\n \"from\": \"{current}\",\n \"to\": \"{target}\",\n \"age_days\": ,\n \"maintainers_changed\": ,\n \"maintainers_added\": [],\n \"maintainers_removed\": [],\n \"provenance\": ,\n \"new_runtime_deps\": [],\n \"files_changed\": ,\n \"has_source_changes\": ,\n \"changelog_summary\": \"\",\n \"suspicious_patterns\": [],\n \"verdict\": \"safe\" | \"review\" | \"defer\",\n \"verdict_reason\": \"\"\n}}\n\nVerdict guidelines:\n- \"safe\": Same maintainers, no new runtime deps, changes match what changelog describes, no suspicious patterns\n- \"review\": Minor concerns (e.g., new maintainer who is clearly from the same org, small new dep from known publisher)\n- \"defer\": Maintainer changes from unknown accounts, new runtime deps with unclear purpose, suspicious code patterns, substantive API changes that need integration testing\n```\n\n### Collecting results\n\nAs sub-agents complete, collect their JSON reports. If a sub-agent fails or times out, mark that package as \"defer\" with reason \"audit failed\".\n\n### Tier classification\n\nAfter collecting all results, classify packages into tiers. This helps the user understand the risk profile at a glance:\n\n| Tier | Description | Typical action |\n|------|-------------|----------------|\n| **Runtime, high surface** | Libraries your code calls directly (parsers, diff engines, UI libs) | Check provenance, review diff, run tests |\n| **SDK/API deps** | Third-party service SDKs (agent SDKs, platform integrations) | Read changelog for API changes, test integration |\n| **Dev-only** | Type definitions, build tools, test frameworks | Update freely — these don't ship |\n| **Build toolchain** | Bun itself, compilers, bundlers | Most caution — breakage affects all outputs |\n\n## Phase 3: Execution\n\n### Bump safe packages\n\nFor all packages with verdict \"safe\":\n\n```bash\nbun update pkg1@version1 pkg2@version2 ...\n```\n\nIf the update fails due to age gate conflicts (a package's minimum semver can't resolve), add it to `minimumReleaseAgeExcludes` in `bunfig.toml` and document why.\n\n### Log to supply chain notes\n\nWrite the full audit results to `~/.supply-chain/notes/.json`:\n\n```json\n{\n \"date\": \"YYYY-MM-DD\",\n \"project\": \"plannotator\",\n \"bumped\": [\n {\n \"package\": \"...\",\n \"from\": \"...\",\n \"to\": \"...\",\n \"age_days\": 0,\n \"maintainers_changed\": false,\n \"provenance\": false,\n \"notes\": \"...\"\n }\n ],\n \"deferred\": [\n {\n \"package\": \"...\",\n \"current\": \"...\",\n \"available\": \"...\",\n \"age_days\": 0,\n \"maintainers_changed\": false,\n \"reason\": \"...\",\n \"review_by\": \"YYYY-MM-DD\"\n }\n ],\n \"excluded_from_age_gate\": [\n {\n \"package\": \"...\",\n \"reason\": \"...\"\n }\n ]\n}\n```\n\nSet `review_by` to 7 days from today for deferred packages.\n\n### Check previously deferred packages\n\nRead all files in `~/.supply-chain/notes/` and collect any deferred packages from previous audits that are still at the same version in the current lockfile. These are packages that were deferred before and still haven't been updated.\n\nTo check: for each previously deferred entry, see if the current installed version matches the `current` field from the deferral note. If it does, the package is still deferred.\n\n## Phase 4: Recap\n\nPresent a clear summary to the user:\n\n### Updated\nList each bumped package with version change and one-line reason it was safe.\n\n### Deferred\nList each deferred package with version change and reason for deferral.\n\n### Still Deferred (from previous audits)\nList any packages that were deferred in previous audit sessions and still haven't been bumped. Include the original deferral date and reason. This is the \"you've been putting this off\" section — it keeps deferred packages from being forgotten.\n\nIf the still-deferred list is empty, say so — that's a good sign.\n\n### Age Gate Exclusions\nIf any packages were added to `minimumReleaseAgeExcludes`, note them and why.\n",".agents/skills/review-renovate/SKILL.md":"---\nname: review-renovate\ndescription: Review Renovate bot PRs that update GitHub Actions dependencies. Verifies supply chain integrity by checking pinned commit SHAs against upstream tagged releases, reviews changelogs for breaking changes, and confirms compatibility with existing workflow configurations. Use when a Renovate PR updates GitHub Actions in .github/workflows/.\n---\n\n# Review Renovate GitHub Actions PRs\n\nYou are reviewing a Renovate bot PR that updates GitHub Actions dependencies. Your job is to verify supply chain integrity and ensure the upgrades won't break CI/CD workflows.\n\n## Inputs\n\nYou will be given a PR number or URL. Use `gh` CLI to fetch PR details and diff.\n\n## Steps\n\n### 1. Fetch PR metadata and diff\n\n```\ngh pr view --json title,body,files,commits,author,headRefName\ngh pr diff \n```\n\nConfirm the PR author is `app/renovate`. If not, flag this immediately — it may not be an automated dependency update.\n\n### 2. Identify all action version changes\n\nFrom the diff, extract each changed action:\n- Full action name (e.g., `oven-sh/setup-bun`)\n- Old version tag and pinned SHA\n- New version tag and pinned SHA\n- Update type (patch, minor, major)\n\n### 3. Verify pinned SHAs against upstream tags\n\nFor every action being updated, verify **both old and new** SHAs match the claimed version tags:\n\n```\ngh api repos/{owner}/{repo}/git/ref/tags/{version} --jq '.object.sha'\n```\n\nCompare each result against the SHA in the workflow file. If any SHA does not match, **stop and report a supply chain integrity failure**. Do not approve the PR.\n\n### 4. Review changelogs for breaking changes\n\nFrom the PR body (Renovate includes release notes), check each updated action for:\n- Removed inputs or outputs that the workflows currently use\n- Changed default behavior for inputs the workflows rely on\n- New required inputs\n- Major version bumps (these almost always have breaking changes)\n\n### 5. Check workflow compatibility\n\nRead the affected workflow files and verify:\n- No removed or renamed inputs are being used\n- No changed defaults affect current behavior\n- The action's runtime requirements are still met (e.g., Node.js version compatibility)\n\n### 6. Report findings\n\nPresent a summary table:\n\n| Action | Old | New | Type | SHA verified |\n|--------|-----|-----|------|-------------|\n| ... | ... | ... | patch/minor/major | yes/NO |\n\nThen state:\n- Whether all SHAs are verified\n- Whether any breaking changes were found\n- Whether the workflows remain compatible\n- A clear **safe to merge** or **do not merge** recommendation\n","apps/skills/extra/plannotator-visual-explainer/SKILL.md":"---\nname: plannotator-visual-explainer\ndisable-model-invocation: true\ndescription: >\n Generate self-contained HTML visualizations with Plannotator theming. Use for implementation\n plans, PR explainers, architecture diagrams, data tables, slide decks, and any visual\n explanation of technical concepts. Plans and PR explainers follow Plannotator's prescriptive\n approach; all other visual content delegates to nicobailon/visual-explainer.\n---\n\n# Plannotator Visual Explainer\n\nThree paths depending on content type. Each has its own references and structure.\n\n## Route by content type\n\n**Implementation plan, design doc, or proposal** → Follow the [Plan path](#plan-path). Read `references/design-system.md` and `references/svg-patterns.md`. Prescriptive structure.\n\n**PR explainer, diff review, or code change walkthrough** → Follow the [PR path](#pr-path). Read `references/design-system.md` and `references/pr-components.md`. Prescriptive structure.\n\n**Everything else** (architecture diagrams, data tables, slide decks, project recaps, general visual explanations) → Follow the [Visual explainer path](#visual-explainer-path). Delegates to nicobailon/visual-explainer with Plannotator theme tokens.\n\n## Delivery\n\nAlways deliver via Plannotator's annotation UI. Do NOT use `open` or `xdg-open`.\n\nFor any deliverable that uses Mermaid, render every diagram with Mermaid 12 in both the light\nand dark palettes before opening the annotation UI. Rendering is a hard gate: an exception,\nempty SVG, or error output such as `aria-roledescription=\"error\"` or `Syntax error in text`\nmeans the explainer is not deliverable. Fix the diagram or theme configuration and rerun both\npalettes until every SVG passes.\n\nFor zoomable diagram shells, additionally zoom to the maximum and pan to all extremes in both palettes before delivering: the figure caption must stay fully legible throughout (see `references/diagram-shell.md`).\n\n**Plans/proposals** (user should approve/deny):\n```bash\nplannotator annotate --gate\n```\n\n**Everything else** (informational):\n```bash\nplannotator annotate \n```\n\n---\n\n## Plan path\n\nFor implementation plans, design docs, feature specs, migration guides, and proposals.\n\n**Before generating, read:**\n1. `references/design-system.md` — Plannotator theme tokens, typography, component patterns\n2. `references/svg-patterns.md` — inline SVG building blocks for architecture diagrams, flowcharts, data flow\n\n**Document structure (in order, pick what fits):**\n\n1. **Header** — eyebrow label (mono, uppercase), title (serif, large), prompt box (the original brief)\n2. **Summary strip** — 3-5 stat cards showing key numbers at a glance (components, endpoints, tables, etc.)\n3. **Milestones / timeline** — vertical timeline showing phases without time estimates. Phases show sequence and dependencies, not duration.\n4. **Architecture / data flow** — inline SVG diagram. Use for 3+ interacting components. Highlighted boxes for new components, dashed arrows for async paths.\n5. **Mockups** — build UI mockups in HTML/CSS directly, not as descriptions\n6. **Key code** — dark-theme code blocks with syntax highlighting. Only architecturally significant interfaces/schemas — not every function.\n7. **Risks & mitigations** — table with severity badges (HIGH/MED/LOW)\n8. **Open questions** — callout cards with decision owner (\"Decide with: backend team\")\n\nNot every plan needs every section. Skip what doesn't serve the content. Never include time estimates, boilerplate sections, or exhaustive file lists.\n\n**Adapt to the task:** Backend → lead with data flow. Frontend → lead with mockups. Refactoring → lead with before/after diagrams. Infrastructure → lead with architecture.\n\n**Quality bar:** The plan answers \"what, why, and how\" within 30 seconds of reading. Whitespace is a feature — one idea per viewport.\n\n---\n\n## PR path\n\nFor PR walkthroughs, diff reviews, code change explainers, and reviewer guides.\n\n**Before generating, read:**\n1. `references/design-system.md` — Plannotator theme tokens, typography, component patterns\n2. `references/pr-components.md` — diff rendering, review comment bubbles, risk chips, file cards, before/after panels\n\n**Document structure (in order, pick what fits):**\n\n1. **Header** — PR title, meta strip (file count, +/- lines, branch, author)\n2. **TL;DR** — bordered card with primary accent left border. 2-3 sentences. Readers who see nothing else should get the gist.\n3. **Why** — motivation and before/after comparison (two-column grid)\n4. **File tour** — collapsible cards per file. Each has: file path + badge (NEW/MOD/DEL) + line stats, a \"why\" paragraph, and important diff hunks. High-risk files expanded, safe files collapsed.\n5. **Risk map** — visual chips showing which files need careful review vs. which are mechanical. Three tiers: attention (destructive), medium (warning), safe (success).\n6. **Where to focus** — numbered callout cards. Each names a file/function and describes the concern.\n7. **Test plan** — checkbox-style verification checklist\n8. **Rollout** (if applicable) — phased deployment with feature flags\n\nUse Pierre diffs via CDN for syntax-highlighted inline diffs — see `references/pr-components.md` for the pattern.\n\n---\n\n## Visual explainer path\n\nFor architecture diagrams, data tables, slide decks, project recaps, comparisons, and any other visual explanation.\n\n**Before generating:**\n\n1. Ensure `visual-explainer` is installed:\n - Check: `~/.claude/skills/visual-explainer/SKILL.md` or `~/.agents/skills/visual-explainer/SKILL.md`\n - If not found: `npx skills add nicobailon/visual-explainer -g --yes`\n2. Read visual-explainer's `SKILL.md` (workflow, diagram types, anti-slop rules)\n3. Read the relevant visual-explainer references and templates for your content type\n4. Read `references/theme-override.md` — Plannotator tokens replacing Nico's palettes\n5. For zoomable Mermaid diagrams with controls and a caption: read `references/diagram-shell.md` and copy its shell — do not hand-roll viewport, canvas, or caption markup\n\nFollow visual-explainer's structure, component classes (`.ve-card`, `.kpi-card`, `.pipeline`), and anti-slop rules. Overrides are the color/typography layer — Plannotator tokens instead of Nico's custom palettes — plus the zoomable diagram shell in `references/diagram-shell.md` when the deliverable has one.\n\n---\n\n## Design philosophy (all paths)\n\n- **Whitespace is a feature.** Generous padding, large section gaps. If cramped, add space — don't shrink text.\n- **One idea per viewport.** Hero section, then diagram, then detail grid — not all crammed together.\n- **Show, don't describe.** A timeline shows sequencing. A diagram shows relationships. A code block shows the interface.\n- **No time estimates.** Timelines show phases and dependencies. Never attach hour/day estimates.\n","apps/skills/extra/plannotator-setup-goal/SKILL.md":"---\nname: plannotator-setup-goal\ndisable-model-invocation: true\ndescription: Turn an idea or objective into a goal package for /goal. Interviews the user, builds a reviewed fact sheet via Plannotator, then explores the codebase to produce an execution plan.\n---\n\n# Setup Goal\n\nTurn an idea into a goal package at `goals//` through structured discovery, user interview, and codebase exploration.\n\n## Phases\n\n### 1. Rearticulate\n\nState back what the user wants in your own words. If the conversation already has rich context, summarize it. If the goal is bare or vague, do minimal shallow exploration of the codebase to ground your understanding. Keep it to 2-3 sentences. Wait for the user to confirm or correct before continuing.\n\nCreate the goal directory once the slug is clear:\n\n```bash\nmkdir -p goals/\n```\n\nUse `goals//` for both working JSON files and final docs. The JSON files are provenance and iteration state; the markdown files are the human-readable authoritative goal package.\n\n**Browser session patience rule:** Plannotator goal setup is a user-driven browser session. After launching an interview or facts command, be absolutely patient and keep waiting on the user until they submit, dismiss, or explicitly ask you to stop. Do not close, kill, restart, refresh, or open a second copy just because the UI is idle or the user is taking time. Never close and reopen the session as a way to update state; if a rerun is needed after the prior session ends, update the working JSON file and launch a new command from that file.\n\n**Optional: grill first (deep, one-at-a-time interview).** Before building the compact interview bundle, *suggest* a grilling pass whenever the goal is vague or carries many interdependent decisions — and run one whenever the user asks for it (\"grill me first\"). This is opt-in: for a clear, well-scoped goal, skip it and go straight to the bundle, so grilling never fights the bundle's \"fewer, higher-leverage questions\" philosophy. When you grill, run the protocol below verbatim, then fold the resolved decisions forward into a higher-quality interview bundle (Phase 2) — or, if grilling fully resolves scope, straight into the fact sheet (Phase 3).\n\n\n\n> Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.\n>\n> Ask the questions one at a time.\n>\n> If a question can be answered by exploring the codebase, explore the codebase instead.\n\n### 2. Interview Bundle\n\nBuild a compact bundle of questions that can derive every \"fact\" this goal should produce. Package the questions together so the user can answer them quickly in the Plannotator goal setup UI. For each question, include your recommended answer and use options when they make answering faster.\n\nDo not ask obvious confirmation questions. If the answer can be inferred from the user's request, from the conversation, or from shallow codebase exploration, infer it and move on. If an obvious area has meaningful nuance, present the inferred answer as a recommendation with options or a custom \"add/correct this\" path rather than asking the user to restate the obvious.\n\nQuestion areas that usually matter:\n\n- What the feature/change is\n- Who it's for\n- What problem it solves\n- What behavior changes\n- What success looks like\n- What's in and out of scope (the most important area to determine facts)\n- What edge cases to consider\n- What constraints or precedent apply\n\n**If a question can be answered by exploring the codebase, explore the codebase instead of asking.** Only include questions where the user's judgment is actually needed. Prefer fewer, higher-leverage questions over exhaustive obvious ones.\n\nWrite the interview bundle before showing it to the user:\n\n`goals//interview.json`\n\n```json\n{\n \"stage\": \"interview\",\n \"title\": \"Short human-readable title\",\n \"goalSlug\": \"\",\n \"questions\": [\n {\n \"id\": \"scope\",\n \"prompt\": \"What should be in scope?\",\n \"description\": \"Optional clarification.\",\n \"answerMode\": \"multi-custom\",\n \"recommendedAnswer\": \"Your recommended answer.\",\n \"recommendedOptionIds\": [\"ui\", \"server\"],\n \"options\": [\n { \"id\": \"ui\", \"label\": \"UI\" },\n { \"id\": \"server\", \"label\": \"Server\" }\n ],\n \"required\": true\n }\n ]\n}\n```\n\nSupported `answerMode` values: `text`, `single`, `multi`, `custom`, `single-custom`, `multi-custom`.\n\nRun this as a monitored foreground process and wait patiently for the browser session to finish. The command may appear idle while the user is reading, editing, or asking questions; leave it running:\n\n```bash\nplannotator setup-goal interview goals//interview.json --json\n```\n\nThe command returns JSON on stdout with the submitted answers. Write that exact result to `goals//interview-result.json` before continuing. A convenient pattern is:\n\n```bash\nplannotator setup-goal interview goals//interview.json --json | tee goals//interview-result.json\n```\n\nIf the user revises after the session finishes, update `interview.json` and rerun the command instead of reconstructing the whole bundle from memory. If the session is dismissed, stop and tell the user the goal setup was closed.\n\nBefore moving to facts, read every answer and note carefully:\n\n- If the user wrote questions, uncertainty, \"not sure\", \"needs context\", or similar concerns in an answer or note, stop and address those questions in chat. Do not proceed to facts until the user has enough context or you have rerun a revised interview bundle.\n- If the user skipped a question with a note, treat the note as intentional feedback, not as an empty answer. Answer the note, refine the question, or make a documented assumption before proceeding.\n- If the user skipped a question without a note, proceed only if the missing answer is non-blocking; otherwise ask the smallest possible follow-up in chat.\n\n### 3. Fact Sheet\n\nA fact is a simple description of each outcome of a goal. It should be easily testable and verifiable. A fact may describe the function of a specific feature or aspect of a system. A fact may determine specific UI and UX. Again, a fact is literally anything that can be tested and verified in automated or manual testing. Keep fact language simple. In a way, a fact sheet is a design spec, but less verbose & using language the human user can easily visualize & rationalize. \n\nPrepare a facts review bundle from `goals//interview-result.json`. Each fact should include whether automated verification is recommended and preselected.\n\nWrite the facts review bundle before showing it to the user. If revising after a prior facts pass, start from `facts-review.json` and `facts-result.json`, include previously accepted facts with `\"accepted\": true`, and preserve their state.\n\n`goals//facts-review.json`\n\n```json\n{\n \"stage\": \"facts\",\n \"title\": \"Short human-readable title\",\n \"goalSlug\": \"\",\n \"facts\": [\n {\n \"id\": \"fact-1\",\n \"text\": \"The accepted fact text.\",\n \"accepted\": false,\n \"removed\": false,\n \"recommendedAutomatedVerification\": true,\n \"automatedVerification\": true\n }\n ]\n}\n```\n\nRun this as a monitored foreground process and wait patiently for the browser session to finish. The command may appear idle while the user is reviewing, editing, or asking questions; leave it running:\n\n```bash\nplannotator setup-goal facts goals//facts-review.json --json\n```\n\nThe command returns JSON on stdout with accepted/edited/removed facts plus automated verification selections. Write that exact result to `goals//facts-result.json`. A convenient pattern is:\n\n```bash\nplannotator setup-goal facts goals//facts-review.json --json | tee goals//facts-result.json\n```\n\nWrite `goals//facts.md` as a flat readable list of accepted facts. Each fact is one line; add a minimal note only when the fact cannot be stated clearly on its own. Also write `goals//facts.meta.json` preserving each accepted fact's `id`, final `text`, `comment`, `recommendedAutomatedVerification`, and `automatedVerification` value.\n\nIf the user edits or removes facts in the UI, apply that result directly. If the session is dismissed, stop and tell the user the facts review was closed.\n\n### 4. Plan\n\nExplore the codebase. Discover and validate implementation paths toward each accepted fact. Treat facts with `automatedVerification: true` as requiring concrete automated checks unless you document a blocker. Trace through code, identify files and systems involved, surface risks and unknowns. Refine until you have a confident order of operations.\n\nWrite `goals//plan.md`:\n\n- Solution approach (brief)\n- Ordered steps with the files/systems each touches\n- Verification for each step (concrete commands or checks)\n- Risks or open questions worth flagging\n\nGate the plan with Plannotator:\n\n```bash\nplannotator annotate goals//plan.md --gate\n```\n\nIf denied, revise from feedback and re-gate until approved.\n\n### 5. Goal Output\n\nWrite `goals//goal.md`:\n\n- The articulated goal (1-3 sentences)\n- Reference to `facts.md` as the shared understanding\n- Reference to `plan.md` as the execution plan\n- Done condition\n\nTell the user:\n\n```\nDone! Launch a goal with `/goal goals//goal.md`\n```\n",".agents/skills/release/SKILL.md":"---\nname: release-plannotator\ndescription: Prepare and execute a Plannotator release — draft release notes with full contributor credit, bump versions across all package files, build in dependency order, and kick off the tag-driven release pipeline. Use this skill whenever the user mentions preparing a release, bumping versions, writing release notes, tagging a release, or publishing. Also trigger when the user says things like \"let's ship\", \"prep a release\", \"what's changed since last release\", or \"time to cut a new version\".\n---\n\n# Plannotator Release\n\nThe process has four phases. Phase 1 (release notes) is where most of the work happens — present the draft for review before proceeding to later phases.\n\n## Phase 1: Draft Release Notes\n\nThis is the most important phase. The release notes are the public face of each version and the primary way the community sees their contributions recognized.\n\n### Step 1: Determine scope\n\n1. Find the latest release tag: `git tag --sort=-v:refname | head -1`\n2. Determine the new version number. Ask the user if unclear (patch, minor, or major).\n3. Gather all changes since the last tag:\n - `git log --oneline ..HEAD` for commit history\n - `git log --merges --oneline ..HEAD` for merged PRs\n4. For each PR, use `gh pr view --json title,author,body,closedIssues,labels` to get details.\n\n### Step 2: Research contributors\n\nThis is critical. Every person who participated in the release gets credit — not just PR authors.\n\nFor each PR and linked issue, collect:\n- **PR authors** — the person who wrote the code\n- **Issue reporters** — who filed the bug or feature request\n- **Issue commenters** — who participated in the discussion with useful context\n- **Discussion creators** — who started relevant GitHub Discussions\n- **Feature requestors** — check the linked \"closes #N\" issues and their authors\n\nUse the GitHub API via `gh`:\n```bash\n# Get issue details including author\ngh issue view --json author,title,body\n\n# Get issue comments to find participants\ngh api repos/backnotprop/plannotator/issues//comments --jq '.[].user.login'\n\n# Get PR review comments\ngh api repos/backnotprop/plannotator/pulls//comments --jq '.[].user.login'\n```\n\n### Step 3: Write the release notes\n\nRead the reference release notes in `references/` for the canonical template structure. These are real release notes from previous versions — match their tone, structure, and level of detail.\n\n- `release-notes-v0.13.0.md` — large release, 14 PRs, 3 first-time contributors, \"New Contributors\" + narrative \"Contributors\" section\n- `release-notes-v0.12.0.md` — large community release, 14 PRs, 10 external, detailed narrative \"Contributors\" section\n- `release-notes-v0.13.1.md` — small patch release, 2 PRs, no external authors, \"Community\" section focused on issue reporters\n\nPay attention to how each reference handles contributor crediting differently. Pick the pattern that fits the release's contributor profile — a release with many external PRs warrants a narrative \"Contributors\" section; a patch driven by issue reports uses a lighter \"Community\" section.\n\nWrite the file to the repo root as `RELEASE_NOTES_v.md`.\n\n#### Structure\n\n1. **X/Twitter follow link** — first line, always the same:\n ```\n Follow [@plannotator](https://x.com/plannotator) on X for updates\n ```\n\n2. **\"Missed recent releases?\"** collapsible table — copy from the previous release's notes, then:\n - Add the previous release (the one you're succeeding) as the newest row\n - Keep roughly 10-12 rows; drop the oldest if needed\n - Each row: version link + comma-separated feature highlights (short phrases)\n\n3. **\"What's New in vX.Y.Z\"** — the heart of the notes\n - Open with 1-3 sentences summarizing the release theme and scope. Mention how many PRs, how many from external contributors, any first-timers.\n - Each major feature/fix gets its own `###` subsection with:\n - A descriptive heading (not the PR title verbatim — rephrase for clarity)\n - 1-4 paragraphs explaining what changed and why it matters. Be specific and concrete. Describe the problem that existed before, what the change does, and how users experience it.\n - Credit line at the bottom: PR link, linked issues with `closing [#N]`, and contributor attribution\n - Minor changes go under `### Additional Changes` as bold-titled bullets\n\n4. **Install / Update** — standard block, read from the previous release notes and reuse verbatim\n\n5. **\"What's Changed\"** — bullet list of every PR in the release:\n ```\n - feat: descriptive PR title by @author in [#N](url)\n ```\n\n6. **\"New Contributors\"** — if any first-time contributors:\n ```\n - @username made their first contribution in [#N](url)\n ```\n\n7. **\"Contributors\" or \"Community\"** — narrative section recognizing everyone who participated:\n - PR authors get a sentence about what they built\n - Issue reporters and commenters get listed with what they reported/discussed\n - Group community issue reporters in a bullet list at the end\n\n8. **Full Changelog link**:\n ```\n **Full Changelog**: https://github.com/backnotprop/plannotator/compare/...\n ```\n\n#### Writing guidelines\n\n- **Narrative over noise.** Write in clear, readable prose. Not marketing-speak, not changelog-dump. Explain what changed and why someone should care, in plain language.\n- **Bullets where they help.** Use bullet lists for enumerating discrete items (additional changes, contributor lists). Use paragraphs for explaining features.\n- **No cliches or buzzwords.** Don't say \"exciting\", \"game-changing\", \"seamless\", \"powerful\". Just describe what happened.\n- **No punchlines.** Don't end sections with a clever quip or a summary zinger. Let the feature speak for itself.\n- **Speak through practical benefit.** Describe what changed and what it means for the user in concrete, reliable terms. Not aspirational, not hype — just what it does.\n- **Don't overuse em dashes.** One or two per release is fine. If you notice them stacking up, restructure the sentence instead.\n- **Grammatical structure matters.** Vary sentence structure. Active voice. Concrete subjects and verbs.\n- **Contributor tags.** Use `@username` — bare at-mentions, not markdown links like `[@user](url)`. GitHub renders bare `@mentions` with avatar icons in release notes. This is important for community recognition.\n- **Every contributor counts.** Everyone who filed an issue, left a comment that shaped a decision, or participated in a discussion gets mentioned. This project's community is its lifeblood.\n\n### Step 4: Present for review\n\nWrite the draft to `RELEASE_NOTES_v.md` in the repo root and tell the user it's ready for review. Do not `git add` or commit this file — release notes are kept untracked by design. Wait for their feedback before proceeding to Phase 2.\n\n---\n\n## Phase 2: Version Bump\n\nBump the version string in these **7 files** (and only these — other package.json files use stub versions):\n\n| File | Field |\n|------|-------|\n| `package.json` (root) | `\"version\"` |\n| `apps/opencode-plugin/package.json` | `\"version\"` |\n| `apps/pi-extension/package.json` | `\"version\"` |\n| `apps/hook/.claude-plugin/plugin.json` | `\"version\"` |\n| `apps/copilot/plugin.json` | `\"version\"` |\n| `openpackage.yml` (root) | `version:` |\n| `packages/server/package.json` | `\"version\"` |\n\nRead each file, confirm the current version matches expectations, then update all 7 atomically.\n\nDo not bump the VS Code extension (`apps/vscode-extension/package.json`) — it has independent versioning.\n\n---\n\n## Phase 3: Build\n\nRun builds in dependency order:\n\n```bash\nbun run build:review # 1. Code review editor (standalone Vite build)\nbun run build:hook # 2. Plan review + hook server (copies review's built HTML into hook dist)\nbun run build:opencode # 3. OpenCode plugin (copies built HTML from hook + review)\nbun run build:pi # 4. Pi extension (chains review → hook → pi internally, safe to run after 1-2)\n```\n\n`build:pi` chains review and hook internally, so after steps 1-2 it only runs the pi-specific build.\n\nVerify all builds succeed before proceeding.\n\n### Pi Parity Gate\n\nAfter builds pass, audit the Pi extension to ensure all server-side imports resolve in the published package. This catches missing files before they reach npm.\n\n1. **Check imports vs `files` array.** Trace all local imports (starting with `./` or `../`) from `index.ts`, `server.ts`, `tool-scope.ts`, and every file in `server/`. Verify each target is covered by a pattern in the `files` array of `apps/pi-extension/package.json`.\n\n2. **Check `vendor.sh` covers all shared/ai imports.** Every `../generated/*.js` import in the server files must have a corresponding entry in `vendor.sh`'s copy loops. If a new shared module or AI module was added to `packages/shared/` or `packages/ai/` and is imported by Pi's server code, it must be added to `vendor.sh`.\n\n3. **Dry-run the pack.** Run `cd apps/pi-extension && bun pm pack --dry-run` and verify the output includes every file the server imports. Look specifically for any newly added files since the last release.\n\n4. **Quick smoke test.** Confirm `generated/` contains all expected files after build, especially any new ones (e.g., a new shared module added in this release cycle).\n\nIf anything is missing, fix it before proceeding to Phase 4. Common fixes:\n- Add the file to `vendor.sh`'s copy loop\n- Add the file or directory to the `files` array in `package.json`\n- Add an import path fix (Pi uses `../generated/` not `@plannotator/shared` or `@plannotator/ai`)\n\n---\n\n## Phase 4: Commit, Tag, and Release\n\n1. **Commit the version bump:**\n ```\n chore: bump version to X.Y.Z\n ```\n Stage only the 7 version-bumped files. Do not stage the release notes file (it's untracked by design).\n\n2. **Create and push the tag:**\n ```bash\n git tag vX.Y.Z\n git push origin main\n git push origin vX.Y.Z\n ```\n The `v*` tag push triggers the release pipeline (`.github/workflows/release.yml`).\n\n3. **The pipeline handles everything else:**\n - Runs tests\n - Cross-compiles binaries for 6 platforms (macOS ARM64/x64, Linux x64/ARM64, Windows x64/ARM64)\n - Compiles paste service binaries (same 6 platforms)\n - Packs the two npm packages in a credential-free job\n - Downloads pinned, checksum-verified Syft and Grype binaries; generates and schema-validates the release-wide CycloneDX SBOM after all shipped subjects exist\n - Forces the repository-owned, suppression-free Grype configuration, retries the official database update up to three times, requires a valid/active schema-v6 database no more than 120 hours old with no pending update, and preserves the machine-readable scan/database/policy evidence as a workflow artifact\n - Rejects every scanner-side ignored match, then blocks before any attestation or publication on CISA KEV or fixable Critical findings classified as shipped/runtime or unknown-applicability. High, development-only, and no-fix Critical findings are report-only but remain in the evidence\n - Generates SLSA build provenance attestations for all 12 binaries via `actions/attest-build-provenance` (signed through Sigstore, recorded in Rekor)\n - Uses the separate official `actions/attest` SBOM path to bind the CycloneDX predicate to all 12 binaries and both npm tarballs through the same GitHub OIDC/Sigstore service. This is an inventory attestation, not a replacement for SLSA or npm provenance\n - Creates the GitHub Release with all binaries, SHA256 sidecars, the versioned CycloneDX SBOM, and its SHA256 sidecar attached\n - Publishes `@plannotator/opencode` and `@plannotator/pi-extension` to npm with provenance\n\n **SBOM scope:** the public document is a release-wide Syft inventory of the monorepo's locked build inputs and dependencies. It is deliberately not described as exact binary runtime contents. Coverage testing found that Bun standalone executables hide bundled JavaScript dependency metadata from Syft. The OpenCode tarball is similarly opaque; the Pi tarball exposes only a partial view through nested package-lock files. The scope and limitations are also embedded in the CycloneDX metadata.\n\n **Exceptions:** there is no active production exception file. If a future release baseline needs one, do not add a loose ignore. Add a repository-reviewed OpenVEX document and explicitly wire it through `PLANNOTATOR_RELEASE_VEX`; each statement must match one exact package URL and vulnerability ID and carry `not_affected` status, an OpenVEX justification, impact statement, HTTPS evidence, owner, created date, and expiration date. The policy tests reject expired, malformed, broad, and nonmatching records.\n\n **Note on immutable releases:** The repo has GitHub Immutable Releases enabled, so once the `v*` tag is pushed and the release is created, the tag→commit and tag→asset bindings are permanent. You cannot delete and re-create a tag to \"fix\" a bad release — you must ship a new version. Release notes remain editable (see step 5), but everything else is locked.\n\n4. **Monitor the pipeline:**\n Watch the release workflow run until it completes:\n ```bash\n gh run list --workflow=release.yml --limit=1\n gh run view --log\n ```\n Verify:\n - All jobs pass, including `release-security`, `attest`, `release`, and `npm-publish`\n - `release-security-evidence` records the Syft/Grype versions, active database schema/build/checksum/update status, all Grype matches, and an `ACCEPT` policy decision\n - The GitHub Release was created with all binary artifacts, SHA256 sidecars, the versioned `plannotator-X.Y.Z-release-sbom.cdx.json`, and its `.sha256` sidecar\n - npm packages published successfully (check with `npm view @plannotator/opencode version` and `npm view @plannotator/pi-extension version`)\n\n A pull request proves generation, schema/sentinel validation, database policy, Grype evaluation, least-privilege job wiring, and all report artifacts. GitHub OIDC issuance, publication to the artifact-attestation service, and final release-asset publication only run for a real eligible `v*` tag. For the first release after this control lands, complete this bounded tag-only verification before calling the rollout complete:\n\n Before tagging that first release, update the canonical Mintlify page at `https://docs.plannotator.ai/open-source/start/installation#pin-or-verify-a-release` with the SBOM scope/limitations, Grype policy, download/checksum commands, and both predicate-verification commands from the README. The legacy Astro files under `apps/marketing/src/content/docs/` are redirect-only/deprecated copies and are not the public documentation source. Confirm the live Mintlify page contains the material; do not let its publication lag the shipped control.\n\n ```bash\n tag=vX.Y.Z\n version=\"${tag#v}\"\n gh release download \"$tag\" --pattern 'plannotator-linux-x64*' --pattern \"plannotator-${version}-release-sbom.cdx.json*\" --dir /tmp/plannotator-release-verify\n (cd /tmp/plannotator-release-verify && sha256sum --check plannotator-linux-x64.sha256)\n (cd /tmp/plannotator-release-verify && sha256sum --check \"plannotator-${version}-release-sbom.cdx.json.sha256\")\n\n gh attestation verify /tmp/plannotator-release-verify/plannotator-linux-x64 \\\n --repo backnotprop/plannotator \\\n --source-ref \"refs/tags/$tag\" \\\n --signer-workflow backnotprop/plannotator/.github/workflows/release.yml \\\n --predicate-type https://slsa.dev/provenance/v1\n\n gh attestation verify /tmp/plannotator-release-verify/plannotator-linux-x64 \\\n --repo backnotprop/plannotator \\\n --source-ref \"refs/tags/$tag\" \\\n --signer-workflow backnotprop/plannotator/.github/workflows/release.yml \\\n --predicate-type https://cyclonedx.org/bom\n ```\n\n Also extract the attested CycloneDX predicate with `gh attestation verify --format json --jq '.[0].verificationResult.statement.predicate'`, canonicalize both it and the downloaded release SBOM with `jq -S`, and `cmp` them. Verify one npm tarball subject the same way if you download the exact published tarball. Record any tag-only discrepancy as a release blocker and ship a new version rather than mutating an immutable release.\n\n If anything fails, investigate the logs and report to the user before retrying.\n\n5. **Replace the release notes:**\n Once the release is live and verified, replace the auto-generated notes body with the drafted release notes:\n ```bash\n gh release edit vX.Y.Z --notes-file RELEASE_NOTES_v.md\n ```\n\n---\n\n## Checklist\n\nBefore tagging, verify:\n- [ ] All 7 version files bumped consistently\n- [ ] Release notes drafted and reviewed\n- [ ] `bun run build:review` succeeded\n- [ ] `bun run build:hook` succeeded\n- [ ] `bun run build:opencode` succeeded\n- [ ] `bun run build:pi` succeeded (or pi-specific build step)\n- [ ] Version bump committed\n- [ ] Pi parity gate passed (imports, vendor.sh, dry-run pack)\n- [ ] No stale build artifacts (clean builds, no cache issues — run `bun install` first if dependencies changed)\n- [ ] The PR-safe `release-security` job generated a schema-valid, sentinel-complete SBOM and accepted the Grype policy with a fresh database\n- [ ] No scanner binary, database, generated SBOM/report, credential, or `DO_NOT_COMMIT` content is staged\n- [ ] For the first SBOM-enabled release, the canonical Mintlify install/verification page contains the README's SBOM scope, policy, checksum, SLSA, and CycloneDX commands (do not edit the deprecated Astro docs instead)\n\nAfter tagging, verify:\n- [ ] Release workflow completed with `release-security`, `attest`, `release`, and `npm-publish` green\n- [ ] GitHub Release created with all binaries, sidecars, SBOM, and SBOM sidecar\n- [ ] One native binary passes both the explicit SLSA and CycloneDX predicate checks pinned to the tag and signer workflow\n- [ ] Downloaded SBOM checksum passes and canonical JSON matches the attested predicate\n- [ ] `release-security-evidence` shows a fresh/active database and an accepted policy decision\n- [ ] npm packages published at correct version\n- [ ] npm trusted-publishing provenance remains visible for both packages\n- [ ] Release notes replaced via `gh release edit`\n","apps/skills/extra/plannotator-compound/SKILL.md":"---\nname: plannotator-compound\ndisable-model-invocation: true\ndescription: >\n Analyze a user's Plannotator plan archive to extract denial patterns, feedback\n taxonomy, evolution over time, and actionable prompt improvements — then produce\n a polished HTML dashboard report. Falls back to Claude Code ExitPlanMode denial\n reasons when Plannotator data is unavailable.\n---\n\n# Compound Planning Analysis\n\nYou are conducting a comprehensive research analysis of a user's Plannotator plan\narchive. The goal: extract patterns from their denied plans, reduce\nthem into actionable insights, and produce an elegant HTML dashboard report.\n\nThis is a multi-phase process. Each phase must complete fully before the next begins.\nResearch integrity is paramount — every file must be read, no skipping.\n\n## Source Selection\n\nBefore starting the analysis, determine which data source is available.\n\n1. **Plannotator mode (first-class)** — Determine the Plannotator data directory:\n use `$PLANNOTATOR_DATA_DIR` if set, otherwise `~/.plannotator`. Check the\n `plans/` subdirectory there. If it exists and contains `*-denied.md` files,\n use this mode. The entire workflow below is written for Plannotator data.\n\n2. **Claude Code fallback mode** — If the Plannotator archive is absent or\n contains no denied plans, check `~/.claude/projects/`. If present, read\n [references/claude-code-fallback.md](references/claude-code-fallback.md)\n before continuing. That reference explains how to use the bundled parser at\n [scripts/extract_exit_plan_mode_outcomes.py](scripts/extract_exit_plan_mode_outcomes.py)\n to extract denial reasons from Claude Code JSONL transcripts. Every phase\n below has a short note explaining what changes in fallback mode — the\n reference file has the details.\n\n3. **Neither available** — Ask the user for their Plannotator plans directory or\n Claude Code projects directory. Do not guess.\n\n## Phase 0: Locate Plans & Check for Previous Reports\n\nUse the mode chosen in Source Selection above.\n\n**Plannotator mode:** Verify the plans directory contains `*-denied.md` files. If\nnone exist, fall back to Claude Code mode before stopping.\n\n**Claude Code fallback mode:** Run the bundled parser per the fallback reference to\nbuild the denial-reason dataset. Create `/tmp/compound-planning/` if needed.\n\nIn either mode, proceed to Previous Report Detection below.\n\n### Previous Report Detection\n\nAfter locating the plans directory, check for existing reports:\n\n```\nls ${PLANNOTATOR_DATA_DIR:-~/.plannotator}/plans/compound-planning-report*.html\n```\n\nReports follow a versioned naming scheme:\n- First report: `compound-planning-report.html`\n- Subsequent reports: `compound-planning-report-v2.html`, `compound-planning-report-v3.html`, etc.\n\nIf one or more reports exist, determine the **latest** one (highest version number).\nGet its filesystem modification date using `stat` (macOS: `stat -f %Sm -t %Y-%m-%d`,\nLinux: `stat -c %y | cut -d' ' -f1`). This is the **cutoff date**.\n\nPresent the user with a choice:\n\n> \"I found a previous report (`compound-planning-report-v{N}.html`) last updated\n> on {CUTOFF_DATE}. I can either:\n>\n> 1. **Incremental** — Only analyze files dated after {CUTOFF_DATE}, saving tokens\n> and building on previous findings\n> 2. **Full** — Re-analyze the entire archive from scratch\n>\n> Which would you prefer?\"\n\nWait for the user's response before proceeding.\n\n**If incremental:** Filter all subsequent phases to only process files with dates\nafter the cutoff date. The new report version will note in its header narrative that\nit covers the period from {CUTOFF_DATE} to present, and reference the previous\nreport for earlier findings. The inventory (Phase 1) should still count ALL files\nfor overall stats, but clearly separate \"new since last report\" counts.\n\n**If full:** Proceed normally with all files, but still use the next version number\nfor the output filename.\n\n**If no previous report exists:** Proceed normally. The output filename will be\n`compound-planning-report.html` (no version suffix for the first report).\n\n## Phase 1: Inventory\n\nCount and report the dataset. **Always count ALL files** for overall stats,\nregardless of whether this is an incremental or full run:\n\n```\n- *-approved.md files (count)\n- *-denied.md files (count)\n- Date range (earliest to latest date found in filenames)\n- Total days spanned\n- Revision rate: denied / (approved + denied) — this is the \"X% of plans\n revised before coding\" stat used in dashboard section 1\n```\n\n**Note:** Ignore `*.annotations.md` files entirely. Denied files already contain\nthe full plan text plus all reviewer feedback appended after a `---` separator.\nAnnotation files are redundant subsets of this content — reading both would\ndouble-count feedback.\n\n**If incremental mode:** After the total counts, separately report the counts for\nfiles dated after the cutoff date only:\n\n```\nNew since {CUTOFF_DATE}:\n- *-denied.md files: X (of Y total)\n- New date range: {CUTOFF_DATE} to {LATEST_DATE}\n- New days spanned: N\n```\n\nIf fewer than 3 new denied files exist since the cutoff, warn the user:\n> \"Only {N} new denied plans since the last report. The incremental analysis may\n> be thin. Would you like to proceed or switch to a full analysis?\"\n\nAlso run `wc -l` across all `*-approved.md` files to get average lines per\napproved plan. This tells the user whether their plans are staying lightweight\nor bloating over time. You do not need to read approved plan contents — just\ntheir line counts. If possible, break this down by time period (e.g., monthly)\nto show whether plan size changed.\n\nDates appear in filenames in YYYY-MM-DD format, sometimes as a prefix\n(2026-01-07-name-approved.md) and sometimes embedded (name-2026-03-15-approved.md).\nExtract dates from all filenames.\n\nTell the user what you found and that you're beginning the extraction.\n\n**Claude Code fallback mode:** The Plannotator inventory fields above do not apply.\nFollow the inventory instructions in\n[references/claude-code-fallback.md](references/claude-code-fallback.md) instead —\nreport the denial-reason dataset assembled by the parser.\n\n## Phase 2: Map — Parallel Extraction\n\nThis is the most time-intensive phase. You must read EVERY `*-denied.md` file\n**in scope**. Do not skip files. Do not summarize early.\n\n**In scope** means: all denied files if running a full analysis, or only denied\nfiles dated after the cutoff date if running incrementally. In incremental mode,\nonly process files whose embedded YYYY-MM-DD date is strictly after the cutoff.\n\n**Claude Code fallback mode:** The parser output is the clean source dataset. Read\nthe fallback reference for the extraction prompt and batching strategy specific to\nJSON part files. Do not go back to raw `.jsonl` logs unless the parser fails or the\nuser asks for audit-level verification.\n\n**Important:** Only read `*-denied.md` files. Do NOT read approved plans,\nannotation files, or diff files. Each denied file contains the full plan text\nfollowed by a `---` separator and the reviewer's feedback — everything needed\nfor analysis is in one file.\n\n### Batching Strategy\n\nAll extraction agents should use `model: \"haiku\"` — they're doing straightforward\nfile reading and structured extraction, not reasoning. Haiku is faster and cheaper\nfor this work.\n\nThe approach depends on dataset size:\n\n**Tiny datasets (≤ 10 total files):** Read all files directly in the main agent —\nno need for sub-agents. Just read them sequentially and proceed to Phase 3.\n\n**Small datasets (11-30 files):** Launch 2-3 parallel Haiku agents, splitting\nfiles roughly evenly.\n\n**Medium datasets (31-80 files):** Launch 4-6 parallel Haiku agents (~10-15 files\neach). Split by file type and/or time period.\n\n**Large datasets (80+ files):** Launch as many parallel Haiku agents as needed to\nkeep each batch around 10-15 files. Split by the natural time boundaries in the\ndata (months, quarters, or whatever groupings produce balanced batches). If one\ntime period dominates (e.g., the most recent month has 3x the files), split that\nperiod into multiple batches.\n\nLaunch all extraction agents in parallel using the Agent tool with\n`run_in_background: true` and `model: \"haiku\"`.\n\n### Output Files\n\nEach extraction agent must write its results to a clean output file rather than\nrelying on the agent task output (which contains interleaved JSONL framework\nlogs that are difficult to parse). Instruct each agent to write to:\n\n```\n/tmp/compound-planning/extraction-{batch-name}.md\n```\n\nCreate the `/tmp/compound-planning/` directory before launching agents. The\nreduce agent in Phase 3 will read these clean files directly.\n\n### Extraction Prompt\n\nEach agent receives this instruction (adapt the time period, file list, and\noutput path):\n\n```\nYou are extracting structured data from denied plan files for a pattern analysis.\n\nDirectory: [PLANS DIRECTORY]\nFiles to read: [LIST OF SPECIFIC *-denied.md FILES]\nOutput: Write your complete results to [OUTPUT FILE PATH]\n\nEach denied file contains two parts separated by a --- line:\n1. The plan text (above the ---)\n2. The reviewer's feedback and annotations (below the ---)\n\nRead EVERY file in your list. For EACH file, extract:\n- The plan name/topic (from the plan text above the ---)\n- The denial reason or feedback given (from below the --- — capture the actual\n words used)\n- What was specifically asked to change\n- The type of feedback (let the content determine the category — don't force-fit\n into predefined types. Common types include things like: scope concerns,\n approach disagreements, missing information, process requirements, quality\n concerns, UX/design issues, naming disputes, clarification requests,\n testing/procedural denials — but the user's actual patterns may differ)\n- Any specific phrases or recurring language from the reviewer\n- Individual annotations if present (numbered feedback items with quoted text\n and reviewer comments)\n- The date (extracted from the filename)\n\nDo NOT skip any files. One entry per file.\n\nFormat each entry as:\n**[filename]**\n- Date: ...\n- Topic: ...\n- Denial reason: ...\n- Feedback type: ...\n- Specific asks: ...\n- Notable phrases: ...\n- Annotations: [count, with brief summary of each]\n---\n\nAfter processing all files, write the complete results to [OUTPUT FILE PATH].\nState the total file count at the end of the file.\n```\n\n### While Agents Run\n\nTrack completion. As each agent finishes, note the count of files it processed.\nVerify the total matches the inventory from Phase 1. If any agent's count is\nshort, flag it and consider re-launching for the missing files.\n\nIf an agent times out (possible with large batches — a batch of 128 files can\ntake 8+ minutes), re-launch it for just the unprocessed files. Check the output\nfile to see how far it got before timing out.\n\n## Phase 3: Reduce — Pattern Analysis\n\nOnce ALL extraction agents have completed (or all files have been read for tiny\ndatasets), proceed with the reduction. Reduction agents should use `model: \"sonnet\"`\n— this phase requires real analytical reasoning, not just file reading.\n\n### Reduction Strategy\n\nThe approach depends on how many extraction files were produced:\n\n**Standard (≤ 20 extraction files):** Launch a single Sonnet agent to read all\nextraction files and produce the full analysis. This covers most datasets.\n\n**Large (21+ extraction files):** Use a two-stage reduce:\n\n1. **Stage 1 — Partial reduces:** Split the extraction files into groups of 4-6.\n Launch parallel Sonnet agents, each reading one group and producing a partial\n analysis with the same sections listed below. Each writes to\n `/tmp/compound-planning/partial-reduce-{N}.md`.\n\n2. **Stage 2 — Final reduce:** A single Sonnet agent reads all partial reduce\n files and synthesizes them into the final comprehensive analysis. This agent\n merges taxonomies, combines counts, deduplicates patterns, and reconciles any\n conflicting categorizations across partials.\n\n**Claude Code fallback mode:** The reduction phase is the same. The only upstream\ndifference is that extraction files were derived from normalized denial-reason JSON\ninstead of Plannotator markdown files.\n\n### Reduction Prompt\n\nGive each reduction agent this prompt (adapt file paths for single vs multi-stage):\n\n```\nYou are a data scientist conducting the reduction phase of a map-reduce analysis\nacross a user's denied plan archive.\n\nRead ALL extraction files at [FILE PATHS]\n\nThese files contain structured extractions from every denied plan file. Each\nextraction includes the plan topic, denial feedback, annotations, and reviewer\nlanguage. Your job: aggregate everything, find patterns, cluster into a taxonomy,\nand produce a comprehensive analysis.\n\nBe exhaustive. Use real counts. Quote real phrases from the data. This is\nresearch — no hand-waving, no fabrication.\n\nWrite your complete results to [OUTPUT FILE PATH].\n\nProduce the following sections:\n[... sections listed below ...]\n```\n\nThe reduction agent's job is to let the data speak. Do not impose a predetermined\nframework — discover what's actually there. The analysis must produce:\n\n### 1. Denial Reason Taxonomy\nCategorize every denial into a finite set of types that emerge from the data. Count\noccurrences. Show percentages. Include real example quotes for each type. Aim for\n8-15 categories — enough to be specific, few enough to be scannable. Let the user's\nactual feedback determine what the categories are.\n\n### 2. Top Feedback Patterns (ranked by frequency)\nThe 5-10 most recurring patterns. For each: what the reviewer consistently asks for,\n3+ example quotes from different files, and whether the pattern changed over time.\n\n### 3. Recurring Phrases\nExact phrases the reviewer uses repeatedly, with counts and what they signal. These\nare the reviewer's vocabulary — their shorthand for what they care about.\n\n### 4. What the Reviewer Values (implicit preferences)\nDerived from patterns — what does this specific person care about most? Quality?\nSpeed? Narrative? Architecture? Process? Simplicity? Rank by evidence strength.\nThis section should feel like a personality profile of the reviewer's standards.\n\n### 5. What Agents Consistently Get Wrong\nThe flip side — what recurring mistakes trigger denials? What should agents stop\ndoing for this reviewer?\n\n### 6. Structural Requests\nWhat plan structure does the reviewer consistently demand? Required sections,\nordering, format preferences, level of detail expected.\n\n### 7. Evolution Over Time\nHow feedback patterns changed across the time span. Group by whatever natural time\nboundaries exist in the data (weeks for short spans, months for longer ones). Did\nexpectations mature? Did new patterns emerge? What shifted? If the dataset spans\nless than a month, note that evolution analysis is limited but still look for any\nprogression from early to late files.\n\n### 8. Actionable Prompt Instructions\nThe most important output. Based on all patterns: specific numbered instructions\nthat could be embedded in a planning prompt to prevent the most common denial\nreasons. Write these as actual directives an agent could follow. Be specific to\nthis user's patterns — generic advice like \"write good plans\" is worthless. Each\ninstruction should trace back to a real, frequent denial pattern.\n\nAfter writing the instructions, calculate what percentage of denials they would\naddress (count how many denials fall into categories covered by the instructions\nvs total denials). Report this percentage — it will be different for every user.\n\n## Phase 4: Generate the HTML Dashboard\n\nBuild a single, self-contained HTML file as the final deliverable. Save it to\nthe user's plans directory with a versioned filename:\n\n- First ever report: `compound-planning-report.html`\n- Second report: `compound-planning-report-v2.html`\n- Third report: `compound-planning-report-v3.html`\n- And so on.\n\nThe version number was determined in Phase 0 based on existing reports found.\n\n**If this is an incremental report**, the header should indicate the analysis\nperiod (e.g., \"March 15 – March 31, 2026\") and include a subtitle noting\n\"Incremental analysis — see v{N-1} for earlier findings.\" The narrative in\nsection 1 should frame findings as what's new or changed since the last report,\nnot as a complete picture. Overall stats in the header (file counts, revision\nrate) should still reflect the full archive for context.\n\nRead the template at `assets/report-template.html` for the **design language\nonly**. The template contains example data from a previous analysis — ignore all\ndata values, quotes, and percentages in the template. Use only its visual design:\ncolors, typography, spacing, component styles, and layout patterns.\n\n### Design Language (from template)\n\n- **Palette:** Light mode, warm off-white (#FDFCFB), text in slate scale, amber\n for highlights/accents, emerald for positive, rose for negative, indigo for\n action elements\n- **Typography:** Playfair Display (serif, for narrative headings), Inter (sans,\n for body/data), JetBrains Mono (mono, for code/phrases) — Google Fonts CDN\n- **Layout:** Single-column, max-width 1024px, generous vertical whitespace (128px\n between major sections), editorial/narrative-first aesthetic\n- **Tone:** Calm, reflective, authoritative. Like a personal retrospective journal,\n not a monitoring dashboard.\n\n### Page Frame (header + footer)\n\nBefore the 7 sections, the page has:\n\n- **Header:** Report title on the left (Playfair Display, ~36px), project name +\n date range below it in light meta text. On the right: file counts in mono\n (e.g., \"223 denials · 71 days\"). Separated from content by\n a bottom border. Generous bottom padding before section 1.\n\n- **Footer:** After section 7. Top border, centered italic Playfair Display tagline\n summarizing the corpus (e.g., \"Analysis of X denied plans from the Plannotator\n archive.\").\n\n### Dashboard Section Order (7 sections)\n\nThe report follows this exact section order. Each section builds on the previous\none — the flow moves from \"what happened\" through \"why\" to \"what to do about it\":\n\n1. **The story in the data** — An editorial narrative paragraph (Playfair Display\n serif, ~26px) that tells the headline finding in prose. Not bullet points — a\n real paragraph that reads like the opening of an article. Alongside it, a KPI\n sidebar with 3 key metrics (the top denial percentage, the overall revision\n rate, and the number of distinct denial categories found). Use an amber inline\n highlight on the most striking number in the narrative.\n\n2. **Why plans get denied** — The taxonomy as a ranked list. Each row: rank number\n (mono), category label, a thin 4px progress bar (top item in amber-500, rest\n in slate-300), percentage (mono), and for the top entries, a real italic quote\n from the data below the label. Show the top 10 categories or however many the\n data supports (minimum 5).\n\n3. **How expectations evolved** — One card per natural time period. Each card has:\n the period name in serif, a theme phrase in colored uppercase (different color\n per period to show progression), a description paragraph, and a stat line at\n the bottom (e.g., \"X denials · Y narrative requests\"). If the data spans less\n than 3 distinct periods, use 2 cards or even a single card with internal\n progression noted.\n\n4. **What works vs what doesn't** — Two side-by-side cards. Left: green-tinted\n (emerald-50/50 bg, emerald-100 border) with traits of plans that succeed for\n this reviewer. Right: red-tinted (rose-50/50 bg, rose-100 border) with what\n agents keep getting wrong. Both derived from the reduction analysis. Bulleted\n with small colored dots. 5-8 items per card.\n\n5. **The actionable output** — The diagnostic payoff. Opens with a Playfair\n Display narrative sentence stating how many prompt instructions were derived\n and what estimated percentage of denials they address (use the real calculated\n percentage from Phase 3, not a generic number). Then the top 3 most impactful\n improvements as numbered items, each with an amber number, bold title, and\n one-line description. This section bridges the analysis and the full prompt\n that follows.\n\n6. **Your most-used phrases** — Grid of chips (2-col mobile, 3-col desktop). Each\n chip: monospace quoted phrase on the left, frequency count on the right. White\n bg, slate-200 border, rounded-12px. Show 9-12 of the most recurring phrases\n found. These should be the reviewer's actual words — their verbal fingerprint.\n\n7. **The corrective prompt** — Dark panel (slate-900 bg, white text, rounded-3xl,\n shadow-xl). Opens with a Playfair intro sentence about the instructions. Then\n a dark code block (slate-800/80 bg, amber-200 monospace text) containing the\n full numbered prompt instructions from Phase 3. Include a copy-to-clipboard\n button that works (JS included). Below the code block: a gradient glow card\n (indigo-to-purple blurred halo behind a white card) with a closing message\n that these instructions are personal — derived from the user's own feedback,\n their own language, their own standards.\n\n### Adaptation Rules\n\n- If the user has < 3 months of data, reduce the evolution section to fewer cards\n- If most denied files lack feedback below the `---` (bare denials with no\n annotations), note this in the narrative — the analysis will be thinner\n- **Claude Code fallback mode:** Explicitly label the report source as Claude Code\n `ExitPlanMode` denial reasons. Do not fabricate Plannotator-only fields such as\n annotation counts or approved-plan line counts. See the fallback reference for\n KPI substitutes and footer/provenance guidance.\n- If fewer than 5 denial categories emerge, combine the taxonomy and patterns\n sections into one\n- If the dataset is very small (< 20 files), the narrative should acknowledge the\n limited sample size and frame findings as preliminary\n- The number of prompt instructions will vary per user — could be 8 or 20. Don't\n force exactly 17. Let the data determine the count.\n- The top 3 actionable items in section 5 must be the 3 that cover the largest\n share of denials, not the 3 that sound most impressive\n\n### Key Rules\n\n1. Every number must come from the real analysis — no fabricated data\n2. Every quote must be a real quote from a real file\n3. The taxonomy percentages must be calculated from real counts\n4. The prompt instructions must trace back to actual denial patterns\n5. The copy button on the prompt block must work (include the JS)\n\nAfter generating, open the file in the user's browser.\n\n## Phase 5: Summary\n\nTell the user:\n- How many denied files were analyzed\n- If incremental: how many were new since the last report\n- The top 3 denial patterns found\n- The estimated percentage of denials the prompt instructions would address\n- The single most impactful prompt improvement\n- Where the report was saved (including version number)\n- If incremental: remind the user that earlier findings are in the previous report\n\n**Claude Code fallback mode:** Adapt the summary per the fallback reference —\nreport human denial reasons analyzed and total `ExitPlanMode` attempts scanned\ninstead of Plannotator file counts.\n\n## Phase 6: Improvement Hook\n\nAfter presenting the summary, ask the user if they want to enable an **improvement\nhook** — this takes the corrective prompt instructions from section 7 of the report\nand writes them to a file that Plannotator's `EnterPlanMode` hook can inject into\nevery future planning session automatically.\n\n> \"Would you like to enable the improvement hook? This will save the corrective\n> prompt instructions to a file that gets automatically injected into all future\n> planning sessions — so Claude sees your feedback patterns before writing any plan.\"\n\n**If yes:**\n\nThe hook file lives at:\n\n```\n${PLANNOTATOR_DATA_DIR:-~/.plannotator}/hooks/compound/enterplanmode-improve-hook.txt\n```\n\nCreate the `hooks/compound/` directory inside the data directory if it doesn't exist.\n\nThe file contents should be the corrective prompt instructions from Phase 3 —\nthe same numbered list that appears in section 7 of the HTML report. Write them\nas plain text, one instruction per line, prefixed with their number. No HTML, no\nmarkdown fences, no preamble — just the instructions themselves. The hook system\nwill inject this file's contents as-is into the planning context.\n\n**If the file already exists:**\n\nRead the existing file and present the user with a choice:\n\n> \"An improvement hook already exists from a previous analysis. I can:\n>\n> 1. **Replace** — Overwrite with the new instructions (the old ones are gone)\n> 2. **Merge** — Combine both, deduplicating overlapping instructions and\n> keeping the best version of each\n> 3. **Keep existing** — Leave the current hook as-is, skip this step\n>\n> Which would you prefer?\"\n\n- **Replace:** Overwrite the file with the new instructions.\n- **Merge:** Read the existing instructions, compare with the new ones, and\n produce a merged set. Remove duplicates (same intent even if worded differently).\n When two instructions cover the same pattern, keep the more specific or\n actionable version. Re-number the final list sequentially. Write the merged\n result to the file. Show the user what changed (added N new, removed N\n redundant, kept N existing).\n- **Keep existing:** Do nothing, move on.\n\n**If no:** Skip this phase entirely.\n\n## Important Notes\n\n- **Data source priority:** Plannotator is the first-class path. Claude Code log\n analysis is the secondary path for users without Plannotator archives.\n- **Research integrity:** Every file must be read. The value of this analysis comes\n from completeness. Sampling or skipping undermines the findings.\n- **Real data only:** Never fabricate quotes, percentages, or patterns. If the data\n doesn't show a clear pattern, say so honestly rather than inventing one.\n- **Let the data lead:** The taxonomy, patterns, and instructions should emerge from\n what's actually in the files. Different users will have completely different\n denial patterns. A user building mobile apps will have different feedback than\n one building APIs. Don't assume what the patterns will be.\n- **Agent parallelization:** For large datasets, maximize parallel agents to reduce\n wall-clock time. The bottleneck is the largest batch — split it.\n- **Structured extraction format:** Ask extraction agents to return structured text\n with consistent delimiters so the reduce agent can parse reliably.\n- **The report is the artifact:** The HTML dashboard is what the user keeps. It\n should be beautiful, honest, and useful. Every section should feel like it was\n written about them specifically, because it was.\n","apps/skills/core/plannotator-review/SKILL.md":"---\nname: plannotator-review\ndescription: Open Plannotator's browser-based code review UI for the current worktree, another directory, or a pull request URL, then act on the feedback that comes back.\ndisable-model-invocation: true\n---\n\n# Plannotator Review\n\nUse this skill when the user wants to review current code changes in Plannotator instead of reading a diff inline.\n\nRun:\n\n```bash\nplannotator review [--base ] [--diff-type ] [directory-or-pr-url]\n```\n\nReviewing one layer of a stacked branch? Pass `--base ` so the review shows only what this layer adds, instead of everything since `main`. Both flags are session-only (the reviewer can change either in the UI; nothing is persisted) and git-only.\n\nTo review another repository or worktree, pass its directory (relative to the current session or absolute), e.g. `plannotator review ../feature-worktree`. Quote paths containing spaces. Feedback names the selected directory; apply changes there.\n\nBehavior:\n\n1. Launch the command with Bash.\n2. Wait for it to finish.\n3. If it returns feedback or annotations, address them in the same conversation.\n4. If it returns an approval/LGTM-style message, acknowledge that review passed and continue.\n\nDo not ask the user to copy shell commands into chat. Run the command yourself.\n","apps/skills/core/plannotator-last/SKILL.md":"---\nname: plannotator-last\ndescription: Open Plannotator on the latest rendered assistant message and use the returned annotations to revise that message or continue.\ndisable-model-invocation: true\n---\n\n# Plannotator Last\n\nUse this skill when the user wants to annotate the latest assistant response in Plannotator.\n\nDo not send a commentary/status message before running the command. The command\ntargets the latest rendered assistant response, so a preamble can mistakenly become the\nthing being annotated.\n\nRun:\n\n```bash\nplannotator last\n```\n\nBehavior:\n\n1. Launch the command with Bash.\n2. Wait for the annotation session to finish.\n3. If feedback is returned, incorporate it into the follow-up response.\n4. If the session closes without feedback, mention that briefly and continue.\n5. An approval may still carry notes — a `\"decision\": \"approved\"` result with a\n `\"feedback\"` field. Read those notes and carry them into subsequent work, but\n do not redo the message over them: they are guidance, not a change request.\n\nRun the command yourself rather than telling the user to invoke shell syntax manually.\n","apps/skills/core/plannotator-annotate/SKILL.md":"---\nname: plannotator-annotate\ndescription: Open Plannotator's annotation UI for a markdown file, plain-text config file (.yaml, .json, .toml, .ini, .csv, .log, …), HTML file, URL, or folder and then respond to the returned annotations.\ndisable-model-invocation: true\n---\n\n# Plannotator Annotate\n\nUse this skill when the user wants to annotate a document in Plannotator instead of reviewing it inline in chat.\n\nRun for ordinary annotation/feedback:\n\n```bash\nplannotator annotate \n```\n\nRun when the user asks to review, approve, accept, or gate a generated plan/spec/document:\n\n```bash\nplannotator annotate --gate --json\n```\n\nPlain `annotate` has no **Approve** button; it only supports feedback or closing the session. Never promise an approval action unless `--gate` is present. `--json` only changes the output format and does not enable approval by itself.\n\nBehavior:\n\n1. Launch the command with Bash.\n2. Wait for the browser review to finish.\n3. If annotations are returned, address them directly.\n4. If the session closes without feedback, say so briefly and continue.\n5. In a `--gate` session, an approval may still carry notes — a `\"decision\": \"approved\"` result with a\n `\"feedback\"` field (without `--json`, an \"Approved with Notes\" message). Read those notes and carry them into subsequent work, but\n do not revise the document over them: they are guidance, not a change request.\n6. If the command reports that the arguments could not be resolved to a file,\n URL, or folder, work out which target the user means and re-run the command\n yourself with that concrete path or URL.\n\nDo not ask the user to paste a shell command into the chat. Run the command yourself.\n","apps/skills/claude/plannotator-review/SKILL.md":"---\nname: plannotator-review\ndescription: Open Plannotator's browser-based code review UI for the current worktree, another directory, or a pull request URL, then act on the feedback that comes back.\nallowed-tools: Bash(plannotator:*)\ndisable-model-invocation: true\n---\n\n# Plannotator Review\n\nArguments pass through to `plannotator review`: one directory or PR/MR URL, `--git` / `--gitbutler`, and the session-only open-state flags `--base ` / `--diff-type ` (git-only; for a stacked branch, `--base ` reviews just that layer).\n\nFor another repository or worktree, pass its path relative to this session or an absolute path, e.g. `/plannotator-review ../feature-worktree`. Quote paths containing spaces. Supply a target, not prose; feedback names the directory where changes belong.\n\n## Code review feedback\n\n!`plannotator review $ARGUMENTS`\n\n## Your task\n\nIf the review above contains feedback or annotations, address them in the same conversation. If no changes were requested (an approval/LGTM-style result), acknowledge that review passed and continue.\n\nIf the review was moved to the background, wait for it to finish. If Claude Code stopped it at its background time limit before the user decided, tell the user, and only when they ask, run `plannotator review $ARGUMENTS` again with `run_in_background` and `timeout: 7200000`: their annotations are restored from the saved draft.\n","apps/skills/claude/plannotator-last/SKILL.md":"---\nname: plannotator-last\ndescription: Open Plannotator on the latest rendered assistant message and use the returned annotations to revise that message or continue.\nallowed-tools: Bash(plannotator:*)\ndisable-model-invocation: true\n---\n\n# Plannotator Last\n\n## Message annotations\n\n!`plannotator annotate-last $ARGUMENTS`\n\n## Your task\n\nThe output above will be one of:\n\n1. The exact text `The user approved.`, an \"Approved with Notes\" message, OR a JSON object with `\"decision\": \"approved\"`. The user approved your last message. If it is the Approved with Notes message, or that object also carries a `\"feedback\"` field, the user approved *with notes*: read them and carry them into subsequent work — they are non-blocking guidance, not a request to revise the message. Otherwise acknowledge with a single sentence (\"Approved.\") and stop. Either way, do not begin any work.\n2. Empty, OR a JSON object with `\"decision\": \"dismissed\"`. The user closed the session without requesting changes. Acknowledge with a single sentence (\"Annotation session closed.\") and stop. Do not begin any work.\n3. Plaintext annotation feedback, OR a JSON object with `\"decision\": \"annotated\"` and a `\"feedback\"` field. Address the feedback. The user has reviewed your last message and provided specific annotations and comments.\n","apps/skills/claude/plannotator-annotate/SKILL.md":"# plannotator-annotate\n\nPath: `apps/skills/claude/plannotator-annotate/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/claude/plannotator-annotate/SKILL.md)","apps/kiro-cli/skills/plannotator-review/SKILL.md":"# plannotator-review\n\nPath: `apps/kiro-cli/skills/plannotator-review/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/kiro-cli/skills/plannotator-review/SKILL.md)","apps/kiro-cli/skills/plannotator-annotate/SKILL.md":"# plannotator-annotate\n\nPath: `apps/kiro-cli/skills/plannotator-annotate/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/kiro-cli/skills/plannotator-annotate/SKILL.md)","AGENTS.md":"# AI Agent Protocol & Instructions\n\nPath: `AGENTS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/AGENTS.md)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.claude-plugin/marketplace.json)",".factory-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.factory-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.factory-plugin/marketplace.json)",".github/plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.github/plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.github/plugin/marketplace.json)","apps/copilot/plugin.json":"# copilot Plugin Manifest\n\nPath: `apps/copilot/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/copilot/plugin.json)","packages/ui/AGENTS.md":"# Ui Skill\n\nPath: `packages/ui/AGENTS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/AGENTS.md)","packages/ui/HANDOFF.md":"# Ui Skill\n\nPath: `packages/ui/HANDOFF.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/HANDOFF.md)","packages/ui/package.json":"# Ui Skill\n\nPath: `packages/ui/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/package.json)","packages/ui/README.md":"# ui Documentation\n\nPath: `packages/ui/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/README.md)","packages/ui/tsconfig.json":"# Ui Skill\n\nPath: `packages/ui/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/tsconfig.json)","packages/ui/tsconfig.strict-consumer.json":"# Ui Skill\n\nPath: `packages/ui/tsconfig.strict-consumer.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/tsconfig.strict-consumer.json)","packages/shared/package.json":"# Shared Skill\n\nPath: `packages/shared/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/shared/package.json)","packages/shared/tsconfig.json":"# Shared Skill\n\nPath: `packages/shared/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/shared/tsconfig.json)","packages/server/codex-review-schema.json":"# Server Skill\n\nPath: `packages/server/codex-review-schema.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/server/codex-review-schema.json)","packages/server/package.json":"# Server Skill\n\nPath: `packages/server/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/server/package.json)","packages/server/tsconfig.json":"# Server Skill\n\nPath: `packages/server/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/server/tsconfig.json)","packages/review-editor/package.json":"# Review-editor Skill\n\nPath: `packages/review-editor/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/package.json)","packages/review-editor/tsconfig.json":"# Review-editor Skill\n\nPath: `packages/review-editor/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/tsconfig.json)","packages/editor/package.json":"# Editor Skill\n\nPath: `packages/editor/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/editor/package.json)","packages/core/package.json":"# Core Skill\n\nPath: `packages/core/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/core/package.json)","packages/core/tsconfig.json":"# Core Skill\n\nPath: `packages/core/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/core/tsconfig.json)","packages/ai/package.json":"# Ai Skill\n\nPath: `packages/ai/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ai/package.json)","packages/ai/tsconfig.json":"# Ai Skill\n\nPath: `packages/ai/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ai/tsconfig.json)","apps/opencode-plugin/commands/plannotator-annotate.md":"# Command: /plannotator-annotate\n\nPath: `apps/opencode-plugin/commands/plannotator-annotate.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/opencode-plugin/commands/plannotator-annotate.md)","apps/opencode-plugin/commands/plannotator-last.md":"# Command: /plannotator-last\n\nPath: `apps/opencode-plugin/commands/plannotator-last.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/opencode-plugin/commands/plannotator-last.md)","apps/opencode-plugin/commands/plannotator-review.md":"# Command: /plannotator-review\n\nPath: `apps/opencode-plugin/commands/plannotator-review.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/opencode-plugin/commands/plannotator-review.md)","apps/kiro-cli/agents/plannotator.json":"# Agents Skill\n\nPath: `apps/kiro-cli/agents/plannotator.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/kiro-cli/agents/plannotator.json)","apps/hook/.claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `apps/hook/.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/hook/.claude-plugin/plugin.json)","apps/droid-plugin/.factory-plugin/plugin.json":"# factory-plugin Plugin Manifest\n\nPath: `apps/droid-plugin/.factory-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/droid-plugin/.factory-plugin/plugin.json)","apps/copilot/commands/plannotator-annotate.md":"# Command: /plannotator-annotate\n\nPath: `apps/copilot/commands/plannotator-annotate.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/copilot/commands/plannotator-annotate.md)","apps/copilot/commands/plannotator-last.md":"# Command: /plannotator-last\n\nPath: `apps/copilot/commands/plannotator-last.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/copilot/commands/plannotator-last.md)","apps/copilot/commands/plannotator-review.md":"# Command: /plannotator-review\n\nPath: `apps/copilot/commands/plannotator-review.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/copilot/commands/plannotator-review.md)","packages/ui/.migration/badge.md":"# .migration Skill\n\nPath: `packages/ui/.migration/badge.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/badge.md)","packages/ui/.migration/button.md":"# .migration Skill\n\nPath: `packages/ui/.migration/button.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/button.md)","packages/ui/.migration/dialog.md":"# .migration Skill\n\nPath: `packages/ui/.migration/dialog.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/dialog.md)","packages/ui/.migration/dropdown-menu.md":"# .migration Skill\n\nPath: `packages/ui/.migration/dropdown-menu.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/dropdown-menu.md)","packages/ui/.migration/popout-dialog.md":"# .migration Skill\n\nPath: `packages/ui/.migration/popout-dialog.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/popout-dialog.md)","packages/ui/.migration/popover.md":"# .migration Skill\n\nPath: `packages/ui/.migration/popover.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/popover.md)","packages/ui/.migration/project.md":"# .migration Skill\n\nPath: `packages/ui/.migration/project.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/project.md)","packages/ui/.migration/tabs.md":"# .migration Skill\n\nPath: `packages/ui/.migration/tabs.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/tabs.md)","packages/ui/.migration/tooltip.md":"# .migration Skill\n\nPath: `packages/ui/.migration/tooltip.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/tooltip.md)","packages/review-editor/.migration/checkbox.md":"# .migration Skill\n\nPath: `packages/review-editor/.migration/checkbox.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/.migration/checkbox.md)","packages/review-editor/.migration/context-menu.md":"# .migration Skill\n\nPath: `packages/review-editor/.migration/context-menu.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/.migration/context-menu.md)","packages/review-editor/.migration/dropdown-menu.md":"# .migration Skill\n\nPath: `packages/review-editor/.migration/dropdown-menu.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/.migration/dropdown-menu.md)","packages/review-editor/.migration/popover.md":"# .migration Skill\n\nPath: `packages/review-editor/.migration/popover.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/.migration/popover.md)","packages/review-editor/.migration/project.md":"# .migration Skill\n\nPath: `packages/review-editor/.migration/project.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/.migration/project.md)",".agents/skills/release/references/release-notes-v0.12.0.md":"# References Skill\n\nPath: `.agents/skills/release/references/release-notes-v0.12.0.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.agents/skills/release/references/release-notes-v0.12.0.md)",".agents/skills/release/references/release-notes-v0.13.0.md":"# References Skill\n\nPath: `.agents/skills/release/references/release-notes-v0.13.0.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.agents/skills/release/references/release-notes-v0.13.0.md)",".agents/skills/release/references/release-notes-v0.13.1.md":"# References Skill\n\nPath: `.agents/skills/release/references/release-notes-v0.13.1.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.agents/skills/release/references/release-notes-v0.13.1.md)","apps/skills/extra/plannotator-visual-explainer/references/design-system.md":"# References Skill\n\nPath: `apps/skills/extra/plannotator-visual-explainer/references/design-system.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-visual-explainer/references/design-system.md)","apps/skills/extra/plannotator-visual-explainer/references/pr-components.md":"# References Skill\n\nPath: `apps/skills/extra/plannotator-visual-explainer/references/pr-components.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-visual-explainer/references/pr-components.md)","apps/skills/extra/plannotator-visual-explainer/references/svg-patterns.md":"# References Skill\n\nPath: `apps/skills/extra/plannotator-visual-explainer/references/svg-patterns.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-visual-explainer/references/svg-patterns.md)","apps/skills/extra/plannotator-visual-explainer/references/theme-override.md":"# References Skill\n\nPath: `apps/skills/extra/plannotator-visual-explainer/references/theme-override.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-visual-explainer/references/theme-override.md)","apps/skills/extra/plannotator-setup-goal/agents/openai.yaml":"# Agents Skill\n\nPath: `apps/skills/extra/plannotator-setup-goal/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-setup-goal/agents/openai.yaml)","apps/skills/extra/plannotator-compound/references/claude-code-fallback.md":"# References Skill\n\nPath: `apps/skills/extra/plannotator-compound/references/claude-code-fallback.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-compound/references/claude-code-fallback.md)","apps/skills/core/plannotator-review/agents/openai.yaml":"# Agents Skill\n\nPath: `apps/skills/core/plannotator-review/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/core/plannotator-review/agents/openai.yaml)","apps/skills/core/plannotator-last/agents/openai.yaml":"# Agents Skill\n\nPath: `apps/skills/core/plannotator-last/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/core/plannotator-last/agents/openai.yaml)","apps/skills/core/plannotator-annotate/agents/openai.yaml":"# Agents Skill\n\nPath: `apps/skills/core/plannotator-annotate/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/core/plannotator-annotate/agents/openai.yaml)","apps/marketing/src/content/docs/commands/annotate.md":"# Command: /annotate\n\nPath: `apps/marketing/src/content/docs/commands/annotate.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/marketing/src/content/docs/commands/annotate.md)","apps/marketing/src/content/docs/commands/annotate-last.md":"# Command: /annotate-last\n\nPath: `apps/marketing/src/content/docs/commands/annotate-last.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/marketing/src/content/docs/commands/annotate-last.md)","apps/marketing/src/content/docs/commands/code-review.md":"# Command: /code-review\n\nPath: `apps/marketing/src/content/docs/commands/code-review.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/marketing/src/content/docs/commands/code-review.md)","apps/marketing/src/content/docs/commands/plan-review.md":"# Command: /plan-review\n\nPath: `apps/marketing/src/content/docs/commands/plan-review.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/marketing/src/content/docs/commands/plan-review.md)"},"files":{".agents/skills/update-deps/SKILL.md":"---\nname: update-deps\ndescription: Audit and update npm/Bun dependencies with supply chain integrity checks — verifies maintainers, publish age, tarball diffs, and provenance before bumping. Defers risky packages to ~/.supply-chain/notes/.\ndisable-model-invocation: true\n---\n\n# Update Dependencies\n\nAudit outdated packages, verify supply chain integrity, bump what's safe, defer what needs review, and log everything.\n\nThis process has three phases: discovery, integrity audit, and execution. The integrity audit is the most important — every package gets checked before it touches the lockfile.\n\n## Phase 1: Discovery\n\nRun `bun outdated` to get the full list of packages with available updates.\n\n```bash\nbun outdated\n```\n\nParse the output into a structured list. For each package, note:\n- Package name\n- Current version\n- Available update version\n- Whether it's age-gated (indicated by `*` in the output — the footnote \"The * indicates that version isn't true latest due to minimum release age\" confirms this)\n- Whether it's a runtime dep, dev dep, or peer dep\n\nAlso check whether any packages are blocked entirely by the age gate (like `@pierre/diffs` was when its minimum semver range couldn't resolve). Flag these separately — they may need `minimumReleaseAgeExcludes` in `bunfig.toml`.\n\n## Phase 2: Integrity Audit\n\nThis is the core of the process. Spawn one **Sonnet sub-agent per package** to run the integrity check in parallel. Sonnet is used here because these are independent, structured verification tasks that don't need heavier reasoning.\n\nEach sub-agent receives the package name, current version, and target version, and performs the following checks:\n\n### Sub-agent prompt template\n\nFor each outdated package, spawn a Sonnet agent with this task:\n\n```\nYou are auditing the npm package \"{package}\" for a version bump from {current} to {target}.\n\nRun these checks and report back with a JSON object:\n\n1. **Maintainer verification**: Check if maintainers changed between versions.\n npm view {package}@{current} maintainers --json\n npm view {package}@{target} maintainers --json\n Compare the two lists. Flag any additions or removals.\n\n2. **Publish date and age**: Get the publish timestamp.\n npm view {package} time --json\n Extract the date for version {target}. Calculate days since publication.\n Flag if younger than 7 days.\n\n3. **Provenance**: Check if the package has registry signatures or attestations.\n npm audit signatures (if not already run this session)\n Note whether the package has provenance attestations.\n\n4. **Tarball diff**: Show what actually changed in the published package.\n npm diff --diff={package}@{current} --diff={package}@{target}\n Summarize the changes:\n - How many files changed\n - Are changes limited to version bumps, deps, and rebuilt dist? Or are there meaningful source changes?\n - Any new runtime dependencies added?\n - Any suspicious patterns (obfuscated code, eval(), network calls in unexpected places)\n\n5. **Release notes**: Try to find what changed.\n Check the package's repository for release notes or changelog:\n npm view {package}@{target} repository.url\n gh release view v{target} --repo (try with and without v prefix)\n Summarize the changelog if found.\n\nReport your findings as JSON:\n\n{{\n \"package\": \"{package}\",\n \"from\": \"{current}\",\n \"to\": \"{target}\",\n \"age_days\": ,\n \"maintainers_changed\": ,\n \"maintainers_added\": [],\n \"maintainers_removed\": [],\n \"provenance\": ,\n \"new_runtime_deps\": [],\n \"files_changed\": ,\n \"has_source_changes\": ,\n \"changelog_summary\": \"\",\n \"suspicious_patterns\": [],\n \"verdict\": \"safe\" | \"review\" | \"defer\",\n \"verdict_reason\": \"\"\n}}\n\nVerdict guidelines:\n- \"safe\": Same maintainers, no new runtime deps, changes match what changelog describes, no suspicious patterns\n- \"review\": Minor concerns (e.g., new maintainer who is clearly from the same org, small new dep from known publisher)\n- \"defer\": Maintainer changes from unknown accounts, new runtime deps with unclear purpose, suspicious code patterns, substantive API changes that need integration testing\n```\n\n### Collecting results\n\nAs sub-agents complete, collect their JSON reports. If a sub-agent fails or times out, mark that package as \"defer\" with reason \"audit failed\".\n\n### Tier classification\n\nAfter collecting all results, classify packages into tiers. This helps the user understand the risk profile at a glance:\n\n| Tier | Description | Typical action |\n|------|-------------|----------------|\n| **Runtime, high surface** | Libraries your code calls directly (parsers, diff engines, UI libs) | Check provenance, review diff, run tests |\n| **SDK/API deps** | Third-party service SDKs (agent SDKs, platform integrations) | Read changelog for API changes, test integration |\n| **Dev-only** | Type definitions, build tools, test frameworks | Update freely — these don't ship |\n| **Build toolchain** | Bun itself, compilers, bundlers | Most caution — breakage affects all outputs |\n\n## Phase 3: Execution\n\n### Bump safe packages\n\nFor all packages with verdict \"safe\":\n\n```bash\nbun update pkg1@version1 pkg2@version2 ...\n```\n\nIf the update fails due to age gate conflicts (a package's minimum semver can't resolve), add it to `minimumReleaseAgeExcludes` in `bunfig.toml` and document why.\n\n### Log to supply chain notes\n\nWrite the full audit results to `~/.supply-chain/notes/.json`:\n\n```json\n{\n \"date\": \"YYYY-MM-DD\",\n \"project\": \"plannotator\",\n \"bumped\": [\n {\n \"package\": \"...\",\n \"from\": \"...\",\n \"to\": \"...\",\n \"age_days\": 0,\n \"maintainers_changed\": false,\n \"provenance\": false,\n \"notes\": \"...\"\n }\n ],\n \"deferred\": [\n {\n \"package\": \"...\",\n \"current\": \"...\",\n \"available\": \"...\",\n \"age_days\": 0,\n \"maintainers_changed\": false,\n \"reason\": \"...\",\n \"review_by\": \"YYYY-MM-DD\"\n }\n ],\n \"excluded_from_age_gate\": [\n {\n \"package\": \"...\",\n \"reason\": \"...\"\n }\n ]\n}\n```\n\nSet `review_by` to 7 days from today for deferred packages.\n\n### Check previously deferred packages\n\nRead all files in `~/.supply-chain/notes/` and collect any deferred packages from previous audits that are still at the same version in the current lockfile. These are packages that were deferred before and still haven't been updated.\n\nTo check: for each previously deferred entry, see if the current installed version matches the `current` field from the deferral note. If it does, the package is still deferred.\n\n## Phase 4: Recap\n\nPresent a clear summary to the user:\n\n### Updated\nList each bumped package with version change and one-line reason it was safe.\n\n### Deferred\nList each deferred package with version change and reason for deferral.\n\n### Still Deferred (from previous audits)\nList any packages that were deferred in previous audit sessions and still haven't been bumped. Include the original deferral date and reason. This is the \"you've been putting this off\" section — it keeps deferred packages from being forgotten.\n\nIf the still-deferred list is empty, say so — that's a good sign.\n\n### Age Gate Exclusions\nIf any packages were added to `minimumReleaseAgeExcludes`, note them and why.\n",".agents/skills/review-renovate/SKILL.md":"---\nname: review-renovate\ndescription: Review Renovate bot PRs that update GitHub Actions dependencies. Verifies supply chain integrity by checking pinned commit SHAs against upstream tagged releases, reviews changelogs for breaking changes, and confirms compatibility with existing workflow configurations. Use when a Renovate PR updates GitHub Actions in .github/workflows/.\n---\n\n# Review Renovate GitHub Actions PRs\n\nYou are reviewing a Renovate bot PR that updates GitHub Actions dependencies. Your job is to verify supply chain integrity and ensure the upgrades won't break CI/CD workflows.\n\n## Inputs\n\nYou will be given a PR number or URL. Use `gh` CLI to fetch PR details and diff.\n\n## Steps\n\n### 1. Fetch PR metadata and diff\n\n```\ngh pr view --json title,body,files,commits,author,headRefName\ngh pr diff \n```\n\nConfirm the PR author is `app/renovate`. If not, flag this immediately — it may not be an automated dependency update.\n\n### 2. Identify all action version changes\n\nFrom the diff, extract each changed action:\n- Full action name (e.g., `oven-sh/setup-bun`)\n- Old version tag and pinned SHA\n- New version tag and pinned SHA\n- Update type (patch, minor, major)\n\n### 3. Verify pinned SHAs against upstream tags\n\nFor every action being updated, verify **both old and new** SHAs match the claimed version tags:\n\n```\ngh api repos/{owner}/{repo}/git/ref/tags/{version} --jq '.object.sha'\n```\n\nCompare each result against the SHA in the workflow file. If any SHA does not match, **stop and report a supply chain integrity failure**. Do not approve the PR.\n\n### 4. Review changelogs for breaking changes\n\nFrom the PR body (Renovate includes release notes), check each updated action for:\n- Removed inputs or outputs that the workflows currently use\n- Changed default behavior for inputs the workflows rely on\n- New required inputs\n- Major version bumps (these almost always have breaking changes)\n\n### 5. Check workflow compatibility\n\nRead the affected workflow files and verify:\n- No removed or renamed inputs are being used\n- No changed defaults affect current behavior\n- The action's runtime requirements are still met (e.g., Node.js version compatibility)\n\n### 6. Report findings\n\nPresent a summary table:\n\n| Action | Old | New | Type | SHA verified |\n|--------|-----|-----|------|-------------|\n| ... | ... | ... | patch/minor/major | yes/NO |\n\nThen state:\n- Whether all SHAs are verified\n- Whether any breaking changes were found\n- Whether the workflows remain compatible\n- A clear **safe to merge** or **do not merge** recommendation\n","apps/skills/extra/plannotator-visual-explainer/SKILL.md":"---\nname: plannotator-visual-explainer\ndisable-model-invocation: true\ndescription: >\n Generate self-contained HTML visualizations with Plannotator theming. Use for implementation\n plans, PR explainers, architecture diagrams, data tables, slide decks, and any visual\n explanation of technical concepts. Plans and PR explainers follow Plannotator's prescriptive\n approach; all other visual content delegates to nicobailon/visual-explainer.\n---\n\n# Plannotator Visual Explainer\n\nThree paths depending on content type. Each has its own references and structure.\n\n## Route by content type\n\n**Implementation plan, design doc, or proposal** → Follow the [Plan path](#plan-path). Read `references/design-system.md` and `references/svg-patterns.md`. Prescriptive structure.\n\n**PR explainer, diff review, or code change walkthrough** → Follow the [PR path](#pr-path). Read `references/design-system.md` and `references/pr-components.md`. Prescriptive structure.\n\n**Everything else** (architecture diagrams, data tables, slide decks, project recaps, general visual explanations) → Follow the [Visual explainer path](#visual-explainer-path). Delegates to nicobailon/visual-explainer with Plannotator theme tokens.\n\n## Delivery\n\nAlways deliver via Plannotator's annotation UI. Do NOT use `open` or `xdg-open`.\n\nFor any deliverable that uses Mermaid, render every diagram with Mermaid 12 in both the light\nand dark palettes before opening the annotation UI. Rendering is a hard gate: an exception,\nempty SVG, or error output such as `aria-roledescription=\"error\"` or `Syntax error in text`\nmeans the explainer is not deliverable. Fix the diagram or theme configuration and rerun both\npalettes until every SVG passes.\n\nFor zoomable diagram shells, additionally zoom to the maximum and pan to all extremes in both palettes before delivering: the figure caption must stay fully legible throughout (see `references/diagram-shell.md`).\n\n**Plans/proposals** (user should approve/deny):\n```bash\nplannotator annotate --gate\n```\n\n**Everything else** (informational):\n```bash\nplannotator annotate \n```\n\n---\n\n## Plan path\n\nFor implementation plans, design docs, feature specs, migration guides, and proposals.\n\n**Before generating, read:**\n1. `references/design-system.md` — Plannotator theme tokens, typography, component patterns\n2. `references/svg-patterns.md` — inline SVG building blocks for architecture diagrams, flowcharts, data flow\n\n**Document structure (in order, pick what fits):**\n\n1. **Header** — eyebrow label (mono, uppercase), title (serif, large), prompt box (the original brief)\n2. **Summary strip** — 3-5 stat cards showing key numbers at a glance (components, endpoints, tables, etc.)\n3. **Milestones / timeline** — vertical timeline showing phases without time estimates. Phases show sequence and dependencies, not duration.\n4. **Architecture / data flow** — inline SVG diagram. Use for 3+ interacting components. Highlighted boxes for new components, dashed arrows for async paths.\n5. **Mockups** — build UI mockups in HTML/CSS directly, not as descriptions\n6. **Key code** — dark-theme code blocks with syntax highlighting. Only architecturally significant interfaces/schemas — not every function.\n7. **Risks & mitigations** — table with severity badges (HIGH/MED/LOW)\n8. **Open questions** — callout cards with decision owner (\"Decide with: backend team\")\n\nNot every plan needs every section. Skip what doesn't serve the content. Never include time estimates, boilerplate sections, or exhaustive file lists.\n\n**Adapt to the task:** Backend → lead with data flow. Frontend → lead with mockups. Refactoring → lead with before/after diagrams. Infrastructure → lead with architecture.\n\n**Quality bar:** The plan answers \"what, why, and how\" within 30 seconds of reading. Whitespace is a feature — one idea per viewport.\n\n---\n\n## PR path\n\nFor PR walkthroughs, diff reviews, code change explainers, and reviewer guides.\n\n**Before generating, read:**\n1. `references/design-system.md` — Plannotator theme tokens, typography, component patterns\n2. `references/pr-components.md` — diff rendering, review comment bubbles, risk chips, file cards, before/after panels\n\n**Document structure (in order, pick what fits):**\n\n1. **Header** — PR title, meta strip (file count, +/- lines, branch, author)\n2. **TL;DR** — bordered card with primary accent left border. 2-3 sentences. Readers who see nothing else should get the gist.\n3. **Why** — motivation and before/after comparison (two-column grid)\n4. **File tour** — collapsible cards per file. Each has: file path + badge (NEW/MOD/DEL) + line stats, a \"why\" paragraph, and important diff hunks. High-risk files expanded, safe files collapsed.\n5. **Risk map** — visual chips showing which files need careful review vs. which are mechanical. Three tiers: attention (destructive), medium (warning), safe (success).\n6. **Where to focus** — numbered callout cards. Each names a file/function and describes the concern.\n7. **Test plan** — checkbox-style verification checklist\n8. **Rollout** (if applicable) — phased deployment with feature flags\n\nUse Pierre diffs via CDN for syntax-highlighted inline diffs — see `references/pr-components.md` for the pattern.\n\n---\n\n## Visual explainer path\n\nFor architecture diagrams, data tables, slide decks, project recaps, comparisons, and any other visual explanation.\n\n**Before generating:**\n\n1. Ensure `visual-explainer` is installed:\n - Check: `~/.claude/skills/visual-explainer/SKILL.md` or `~/.agents/skills/visual-explainer/SKILL.md`\n - If not found: `npx skills add nicobailon/visual-explainer -g --yes`\n2. Read visual-explainer's `SKILL.md` (workflow, diagram types, anti-slop rules)\n3. Read the relevant visual-explainer references and templates for your content type\n4. Read `references/theme-override.md` — Plannotator tokens replacing Nico's palettes\n5. For zoomable Mermaid diagrams with controls and a caption: read `references/diagram-shell.md` and copy its shell — do not hand-roll viewport, canvas, or caption markup\n\nFollow visual-explainer's structure, component classes (`.ve-card`, `.kpi-card`, `.pipeline`), and anti-slop rules. Overrides are the color/typography layer — Plannotator tokens instead of Nico's custom palettes — plus the zoomable diagram shell in `references/diagram-shell.md` when the deliverable has one.\n\n---\n\n## Design philosophy (all paths)\n\n- **Whitespace is a feature.** Generous padding, large section gaps. If cramped, add space — don't shrink text.\n- **One idea per viewport.** Hero section, then diagram, then detail grid — not all crammed together.\n- **Show, don't describe.** A timeline shows sequencing. A diagram shows relationships. A code block shows the interface.\n- **No time estimates.** Timelines show phases and dependencies. Never attach hour/day estimates.\n","apps/skills/extra/plannotator-setup-goal/SKILL.md":"---\nname: plannotator-setup-goal\ndisable-model-invocation: true\ndescription: Turn an idea or objective into a goal package for /goal. Interviews the user, builds a reviewed fact sheet via Plannotator, then explores the codebase to produce an execution plan.\n---\n\n# Setup Goal\n\nTurn an idea into a goal package at `goals//` through structured discovery, user interview, and codebase exploration.\n\n## Phases\n\n### 1. Rearticulate\n\nState back what the user wants in your own words. If the conversation already has rich context, summarize it. If the goal is bare or vague, do minimal shallow exploration of the codebase to ground your understanding. Keep it to 2-3 sentences. Wait for the user to confirm or correct before continuing.\n\nCreate the goal directory once the slug is clear:\n\n```bash\nmkdir -p goals/\n```\n\nUse `goals//` for both working JSON files and final docs. The JSON files are provenance and iteration state; the markdown files are the human-readable authoritative goal package.\n\n**Browser session patience rule:** Plannotator goal setup is a user-driven browser session. After launching an interview or facts command, be absolutely patient and keep waiting on the user until they submit, dismiss, or explicitly ask you to stop. Do not close, kill, restart, refresh, or open a second copy just because the UI is idle or the user is taking time. Never close and reopen the session as a way to update state; if a rerun is needed after the prior session ends, update the working JSON file and launch a new command from that file.\n\n**Optional: grill first (deep, one-at-a-time interview).** Before building the compact interview bundle, *suggest* a grilling pass whenever the goal is vague or carries many interdependent decisions — and run one whenever the user asks for it (\"grill me first\"). This is opt-in: for a clear, well-scoped goal, skip it and go straight to the bundle, so grilling never fights the bundle's \"fewer, higher-leverage questions\" philosophy. When you grill, run the protocol below verbatim, then fold the resolved decisions forward into a higher-quality interview bundle (Phase 2) — or, if grilling fully resolves scope, straight into the fact sheet (Phase 3).\n\n\n\n> Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.\n>\n> Ask the questions one at a time.\n>\n> If a question can be answered by exploring the codebase, explore the codebase instead.\n\n### 2. Interview Bundle\n\nBuild a compact bundle of questions that can derive every \"fact\" this goal should produce. Package the questions together so the user can answer them quickly in the Plannotator goal setup UI. For each question, include your recommended answer and use options when they make answering faster.\n\nDo not ask obvious confirmation questions. If the answer can be inferred from the user's request, from the conversation, or from shallow codebase exploration, infer it and move on. If an obvious area has meaningful nuance, present the inferred answer as a recommendation with options or a custom \"add/correct this\" path rather than asking the user to restate the obvious.\n\nQuestion areas that usually matter:\n\n- What the feature/change is\n- Who it's for\n- What problem it solves\n- What behavior changes\n- What success looks like\n- What's in and out of scope (the most important area to determine facts)\n- What edge cases to consider\n- What constraints or precedent apply\n\n**If a question can be answered by exploring the codebase, explore the codebase instead of asking.** Only include questions where the user's judgment is actually needed. Prefer fewer, higher-leverage questions over exhaustive obvious ones.\n\nWrite the interview bundle before showing it to the user:\n\n`goals//interview.json`\n\n```json\n{\n \"stage\": \"interview\",\n \"title\": \"Short human-readable title\",\n \"goalSlug\": \"\",\n \"questions\": [\n {\n \"id\": \"scope\",\n \"prompt\": \"What should be in scope?\",\n \"description\": \"Optional clarification.\",\n \"answerMode\": \"multi-custom\",\n \"recommendedAnswer\": \"Your recommended answer.\",\n \"recommendedOptionIds\": [\"ui\", \"server\"],\n \"options\": [\n { \"id\": \"ui\", \"label\": \"UI\" },\n { \"id\": \"server\", \"label\": \"Server\" }\n ],\n \"required\": true\n }\n ]\n}\n```\n\nSupported `answerMode` values: `text`, `single`, `multi`, `custom`, `single-custom`, `multi-custom`.\n\nRun this as a monitored foreground process and wait patiently for the browser session to finish. The command may appear idle while the user is reading, editing, or asking questions; leave it running:\n\n```bash\nplannotator setup-goal interview goals//interview.json --json\n```\n\nThe command returns JSON on stdout with the submitted answers. Write that exact result to `goals//interview-result.json` before continuing. A convenient pattern is:\n\n```bash\nplannotator setup-goal interview goals//interview.json --json | tee goals//interview-result.json\n```\n\nIf the user revises after the session finishes, update `interview.json` and rerun the command instead of reconstructing the whole bundle from memory. If the session is dismissed, stop and tell the user the goal setup was closed.\n\nBefore moving to facts, read every answer and note carefully:\n\n- If the user wrote questions, uncertainty, \"not sure\", \"needs context\", or similar concerns in an answer or note, stop and address those questions in chat. Do not proceed to facts until the user has enough context or you have rerun a revised interview bundle.\n- If the user skipped a question with a note, treat the note as intentional feedback, not as an empty answer. Answer the note, refine the question, or make a documented assumption before proceeding.\n- If the user skipped a question without a note, proceed only if the missing answer is non-blocking; otherwise ask the smallest possible follow-up in chat.\n\n### 3. Fact Sheet\n\nA fact is a simple description of each outcome of a goal. It should be easily testable and verifiable. A fact may describe the function of a specific feature or aspect of a system. A fact may determine specific UI and UX. Again, a fact is literally anything that can be tested and verified in automated or manual testing. Keep fact language simple. In a way, a fact sheet is a design spec, but less verbose & using language the human user can easily visualize & rationalize. \n\nPrepare a facts review bundle from `goals//interview-result.json`. Each fact should include whether automated verification is recommended and preselected.\n\nWrite the facts review bundle before showing it to the user. If revising after a prior facts pass, start from `facts-review.json` and `facts-result.json`, include previously accepted facts with `\"accepted\": true`, and preserve their state.\n\n`goals//facts-review.json`\n\n```json\n{\n \"stage\": \"facts\",\n \"title\": \"Short human-readable title\",\n \"goalSlug\": \"\",\n \"facts\": [\n {\n \"id\": \"fact-1\",\n \"text\": \"The accepted fact text.\",\n \"accepted\": false,\n \"removed\": false,\n \"recommendedAutomatedVerification\": true,\n \"automatedVerification\": true\n }\n ]\n}\n```\n\nRun this as a monitored foreground process and wait patiently for the browser session to finish. The command may appear idle while the user is reviewing, editing, or asking questions; leave it running:\n\n```bash\nplannotator setup-goal facts goals//facts-review.json --json\n```\n\nThe command returns JSON on stdout with accepted/edited/removed facts plus automated verification selections. Write that exact result to `goals//facts-result.json`. A convenient pattern is:\n\n```bash\nplannotator setup-goal facts goals//facts-review.json --json | tee goals//facts-result.json\n```\n\nWrite `goals//facts.md` as a flat readable list of accepted facts. Each fact is one line; add a minimal note only when the fact cannot be stated clearly on its own. Also write `goals//facts.meta.json` preserving each accepted fact's `id`, final `text`, `comment`, `recommendedAutomatedVerification`, and `automatedVerification` value.\n\nIf the user edits or removes facts in the UI, apply that result directly. If the session is dismissed, stop and tell the user the facts review was closed.\n\n### 4. Plan\n\nExplore the codebase. Discover and validate implementation paths toward each accepted fact. Treat facts with `automatedVerification: true` as requiring concrete automated checks unless you document a blocker. Trace through code, identify files and systems involved, surface risks and unknowns. Refine until you have a confident order of operations.\n\nWrite `goals//plan.md`:\n\n- Solution approach (brief)\n- Ordered steps with the files/systems each touches\n- Verification for each step (concrete commands or checks)\n- Risks or open questions worth flagging\n\nGate the plan with Plannotator:\n\n```bash\nplannotator annotate goals//plan.md --gate\n```\n\nIf denied, revise from feedback and re-gate until approved.\n\n### 5. Goal Output\n\nWrite `goals//goal.md`:\n\n- The articulated goal (1-3 sentences)\n- Reference to `facts.md` as the shared understanding\n- Reference to `plan.md` as the execution plan\n- Done condition\n\nTell the user:\n\n```\nDone! Launch a goal with `/goal goals//goal.md`\n```\n",".agents/skills/release/SKILL.md":"---\nname: release-plannotator\ndescription: Prepare and execute a Plannotator release — draft release notes with full contributor credit, bump versions across all package files, build in dependency order, and kick off the tag-driven release pipeline. Use this skill whenever the user mentions preparing a release, bumping versions, writing release notes, tagging a release, or publishing. Also trigger when the user says things like \"let's ship\", \"prep a release\", \"what's changed since last release\", or \"time to cut a new version\".\n---\n\n# Plannotator Release\n\nThe process has four phases. Phase 1 (release notes) is where most of the work happens — present the draft for review before proceeding to later phases.\n\n## Phase 1: Draft Release Notes\n\nThis is the most important phase. The release notes are the public face of each version and the primary way the community sees their contributions recognized.\n\n### Step 1: Determine scope\n\n1. Find the latest release tag: `git tag --sort=-v:refname | head -1`\n2. Determine the new version number. Ask the user if unclear (patch, minor, or major).\n3. Gather all changes since the last tag:\n - `git log --oneline ..HEAD` for commit history\n - `git log --merges --oneline ..HEAD` for merged PRs\n4. For each PR, use `gh pr view --json title,author,body,closedIssues,labels` to get details.\n\n### Step 2: Research contributors\n\nThis is critical. Every person who participated in the release gets credit — not just PR authors.\n\nFor each PR and linked issue, collect:\n- **PR authors** — the person who wrote the code\n- **Issue reporters** — who filed the bug or feature request\n- **Issue commenters** — who participated in the discussion with useful context\n- **Discussion creators** — who started relevant GitHub Discussions\n- **Feature requestors** — check the linked \"closes #N\" issues and their authors\n\nUse the GitHub API via `gh`:\n```bash\n# Get issue details including author\ngh issue view --json author,title,body\n\n# Get issue comments to find participants\ngh api repos/backnotprop/plannotator/issues//comments --jq '.[].user.login'\n\n# Get PR review comments\ngh api repos/backnotprop/plannotator/pulls//comments --jq '.[].user.login'\n```\n\n### Step 3: Write the release notes\n\nRead the reference release notes in `references/` for the canonical template structure. These are real release notes from previous versions — match their tone, structure, and level of detail.\n\n- `release-notes-v0.13.0.md` — large release, 14 PRs, 3 first-time contributors, \"New Contributors\" + narrative \"Contributors\" section\n- `release-notes-v0.12.0.md` — large community release, 14 PRs, 10 external, detailed narrative \"Contributors\" section\n- `release-notes-v0.13.1.md` — small patch release, 2 PRs, no external authors, \"Community\" section focused on issue reporters\n\nPay attention to how each reference handles contributor crediting differently. Pick the pattern that fits the release's contributor profile — a release with many external PRs warrants a narrative \"Contributors\" section; a patch driven by issue reports uses a lighter \"Community\" section.\n\nWrite the file to the repo root as `RELEASE_NOTES_v.md`.\n\n#### Structure\n\n1. **X/Twitter follow link** — first line, always the same:\n ```\n Follow [@plannotator](https://x.com/plannotator) on X for updates\n ```\n\n2. **\"Missed recent releases?\"** collapsible table — copy from the previous release's notes, then:\n - Add the previous release (the one you're succeeding) as the newest row\n - Keep roughly 10-12 rows; drop the oldest if needed\n - Each row: version link + comma-separated feature highlights (short phrases)\n\n3. **\"What's New in vX.Y.Z\"** — the heart of the notes\n - Open with 1-3 sentences summarizing the release theme and scope. Mention how many PRs, how many from external contributors, any first-timers.\n - Each major feature/fix gets its own `###` subsection with:\n - A descriptive heading (not the PR title verbatim — rephrase for clarity)\n - 1-4 paragraphs explaining what changed and why it matters. Be specific and concrete. Describe the problem that existed before, what the change does, and how users experience it.\n - Credit line at the bottom: PR link, linked issues with `closing [#N]`, and contributor attribution\n - Minor changes go under `### Additional Changes` as bold-titled bullets\n\n4. **Install / Update** — standard block, read from the previous release notes and reuse verbatim\n\n5. **\"What's Changed\"** — bullet list of every PR in the release:\n ```\n - feat: descriptive PR title by @author in [#N](url)\n ```\n\n6. **\"New Contributors\"** — if any first-time contributors:\n ```\n - @username made their first contribution in [#N](url)\n ```\n\n7. **\"Contributors\" or \"Community\"** — narrative section recognizing everyone who participated:\n - PR authors get a sentence about what they built\n - Issue reporters and commenters get listed with what they reported/discussed\n - Group community issue reporters in a bullet list at the end\n\n8. **Full Changelog link**:\n ```\n **Full Changelog**: https://github.com/backnotprop/plannotator/compare/...\n ```\n\n#### Writing guidelines\n\n- **Narrative over noise.** Write in clear, readable prose. Not marketing-speak, not changelog-dump. Explain what changed and why someone should care, in plain language.\n- **Bullets where they help.** Use bullet lists for enumerating discrete items (additional changes, contributor lists). Use paragraphs for explaining features.\n- **No cliches or buzzwords.** Don't say \"exciting\", \"game-changing\", \"seamless\", \"powerful\". Just describe what happened.\n- **No punchlines.** Don't end sections with a clever quip or a summary zinger. Let the feature speak for itself.\n- **Speak through practical benefit.** Describe what changed and what it means for the user in concrete, reliable terms. Not aspirational, not hype — just what it does.\n- **Don't overuse em dashes.** One or two per release is fine. If you notice them stacking up, restructure the sentence instead.\n- **Grammatical structure matters.** Vary sentence structure. Active voice. Concrete subjects and verbs.\n- **Contributor tags.** Use `@username` — bare at-mentions, not markdown links like `[@user](url)`. GitHub renders bare `@mentions` with avatar icons in release notes. This is important for community recognition.\n- **Every contributor counts.** Everyone who filed an issue, left a comment that shaped a decision, or participated in a discussion gets mentioned. This project's community is its lifeblood.\n\n### Step 4: Present for review\n\nWrite the draft to `RELEASE_NOTES_v.md` in the repo root and tell the user it's ready for review. Do not `git add` or commit this file — release notes are kept untracked by design. Wait for their feedback before proceeding to Phase 2.\n\n---\n\n## Phase 2: Version Bump\n\nBump the version string in these **7 files** (and only these — other package.json files use stub versions):\n\n| File | Field |\n|------|-------|\n| `package.json` (root) | `\"version\"` |\n| `apps/opencode-plugin/package.json` | `\"version\"` |\n| `apps/pi-extension/package.json` | `\"version\"` |\n| `apps/hook/.claude-plugin/plugin.json` | `\"version\"` |\n| `apps/copilot/plugin.json` | `\"version\"` |\n| `openpackage.yml` (root) | `version:` |\n| `packages/server/package.json` | `\"version\"` |\n\nRead each file, confirm the current version matches expectations, then update all 7 atomically.\n\nDo not bump the VS Code extension (`apps/vscode-extension/package.json`) — it has independent versioning.\n\n---\n\n## Phase 3: Build\n\nRun builds in dependency order:\n\n```bash\nbun run build:review # 1. Code review editor (standalone Vite build)\nbun run build:hook # 2. Plan review + hook server (copies review's built HTML into hook dist)\nbun run build:opencode # 3. OpenCode plugin (copies built HTML from hook + review)\nbun run build:pi # 4. Pi extension (chains review → hook → pi internally, safe to run after 1-2)\n```\n\n`build:pi` chains review and hook internally, so after steps 1-2 it only runs the pi-specific build.\n\nVerify all builds succeed before proceeding.\n\n### Pi Parity Gate\n\nAfter builds pass, audit the Pi extension to ensure all server-side imports resolve in the published package. This catches missing files before they reach npm.\n\n1. **Check imports vs `files` array.** Trace all local imports (starting with `./` or `../`) from `index.ts`, `server.ts`, `tool-scope.ts`, and every file in `server/`. Verify each target is covered by a pattern in the `files` array of `apps/pi-extension/package.json`.\n\n2. **Check `vendor.sh` covers all shared/ai imports.** Every `../generated/*.js` import in the server files must have a corresponding entry in `vendor.sh`'s copy loops. If a new shared module or AI module was added to `packages/shared/` or `packages/ai/` and is imported by Pi's server code, it must be added to `vendor.sh`.\n\n3. **Dry-run the pack.** Run `cd apps/pi-extension && bun pm pack --dry-run` and verify the output includes every file the server imports. Look specifically for any newly added files since the last release.\n\n4. **Quick smoke test.** Confirm `generated/` contains all expected files after build, especially any new ones (e.g., a new shared module added in this release cycle).\n\nIf anything is missing, fix it before proceeding to Phase 4. Common fixes:\n- Add the file to `vendor.sh`'s copy loop\n- Add the file or directory to the `files` array in `package.json`\n- Add an import path fix (Pi uses `../generated/` not `@plannotator/shared` or `@plannotator/ai`)\n\n---\n\n## Phase 4: Commit, Tag, and Release\n\n1. **Commit the version bump:**\n ```\n chore: bump version to X.Y.Z\n ```\n Stage only the 7 version-bumped files. Do not stage the release notes file (it's untracked by design).\n\n2. **Create and push the tag:**\n ```bash\n git tag vX.Y.Z\n git push origin main\n git push origin vX.Y.Z\n ```\n The `v*` tag push triggers the release pipeline (`.github/workflows/release.yml`).\n\n3. **The pipeline handles everything else:**\n - Runs tests\n - Cross-compiles binaries for 6 platforms (macOS ARM64/x64, Linux x64/ARM64, Windows x64/ARM64)\n - Compiles paste service binaries (same 6 platforms)\n - Packs the two npm packages in a credential-free job\n - Downloads pinned, checksum-verified Syft and Grype binaries; generates and schema-validates the release-wide CycloneDX SBOM after all shipped subjects exist\n - Forces the repository-owned, suppression-free Grype configuration, retries the official database update up to three times, requires a valid/active schema-v6 database no more than 120 hours old with no pending update, and preserves the machine-readable scan/database/policy evidence as a workflow artifact\n - Rejects every scanner-side ignored match, then blocks before any attestation or publication on CISA KEV or fixable Critical findings classified as shipped/runtime or unknown-applicability. High, development-only, and no-fix Critical findings are report-only but remain in the evidence\n - Generates SLSA build provenance attestations for all 12 binaries via `actions/attest-build-provenance` (signed through Sigstore, recorded in Rekor)\n - Uses the separate official `actions/attest` SBOM path to bind the CycloneDX predicate to all 12 binaries and both npm tarballs through the same GitHub OIDC/Sigstore service. This is an inventory attestation, not a replacement for SLSA or npm provenance\n - Creates the GitHub Release with all binaries, SHA256 sidecars, the versioned CycloneDX SBOM, and its SHA256 sidecar attached\n - Publishes `@plannotator/opencode` and `@plannotator/pi-extension` to npm with provenance\n\n **SBOM scope:** the public document is a release-wide Syft inventory of the monorepo's locked build inputs and dependencies. It is deliberately not described as exact binary runtime contents. Coverage testing found that Bun standalone executables hide bundled JavaScript dependency metadata from Syft. The OpenCode tarball is similarly opaque; the Pi tarball exposes only a partial view through nested package-lock files. The scope and limitations are also embedded in the CycloneDX metadata.\n\n **Exceptions:** there is no active production exception file. If a future release baseline needs one, do not add a loose ignore. Add a repository-reviewed OpenVEX document and explicitly wire it through `PLANNOTATOR_RELEASE_VEX`; each statement must match one exact package URL and vulnerability ID and carry `not_affected` status, an OpenVEX justification, impact statement, HTTPS evidence, owner, created date, and expiration date. The policy tests reject expired, malformed, broad, and nonmatching records.\n\n **Note on immutable releases:** The repo has GitHub Immutable Releases enabled, so once the `v*` tag is pushed and the release is created, the tag→commit and tag→asset bindings are permanent. You cannot delete and re-create a tag to \"fix\" a bad release — you must ship a new version. Release notes remain editable (see step 5), but everything else is locked.\n\n4. **Monitor the pipeline:**\n Watch the release workflow run until it completes:\n ```bash\n gh run list --workflow=release.yml --limit=1\n gh run view --log\n ```\n Verify:\n - All jobs pass, including `release-security`, `attest`, `release`, and `npm-publish`\n - `release-security-evidence` records the Syft/Grype versions, active database schema/build/checksum/update status, all Grype matches, and an `ACCEPT` policy decision\n - The GitHub Release was created with all binary artifacts, SHA256 sidecars, the versioned `plannotator-X.Y.Z-release-sbom.cdx.json`, and its `.sha256` sidecar\n - npm packages published successfully (check with `npm view @plannotator/opencode version` and `npm view @plannotator/pi-extension version`)\n\n A pull request proves generation, schema/sentinel validation, database policy, Grype evaluation, least-privilege job wiring, and all report artifacts. GitHub OIDC issuance, publication to the artifact-attestation service, and final release-asset publication only run for a real eligible `v*` tag. For the first release after this control lands, complete this bounded tag-only verification before calling the rollout complete:\n\n Before tagging that first release, update the canonical Mintlify page at `https://docs.plannotator.ai/open-source/start/installation#pin-or-verify-a-release` with the SBOM scope/limitations, Grype policy, download/checksum commands, and both predicate-verification commands from the README. The legacy Astro files under `apps/marketing/src/content/docs/` are redirect-only/deprecated copies and are not the public documentation source. Confirm the live Mintlify page contains the material; do not let its publication lag the shipped control.\n\n ```bash\n tag=vX.Y.Z\n version=\"${tag#v}\"\n gh release download \"$tag\" --pattern 'plannotator-linux-x64*' --pattern \"plannotator-${version}-release-sbom.cdx.json*\" --dir /tmp/plannotator-release-verify\n (cd /tmp/plannotator-release-verify && sha256sum --check plannotator-linux-x64.sha256)\n (cd /tmp/plannotator-release-verify && sha256sum --check \"plannotator-${version}-release-sbom.cdx.json.sha256\")\n\n gh attestation verify /tmp/plannotator-release-verify/plannotator-linux-x64 \\\n --repo backnotprop/plannotator \\\n --source-ref \"refs/tags/$tag\" \\\n --signer-workflow backnotprop/plannotator/.github/workflows/release.yml \\\n --predicate-type https://slsa.dev/provenance/v1\n\n gh attestation verify /tmp/plannotator-release-verify/plannotator-linux-x64 \\\n --repo backnotprop/plannotator \\\n --source-ref \"refs/tags/$tag\" \\\n --signer-workflow backnotprop/plannotator/.github/workflows/release.yml \\\n --predicate-type https://cyclonedx.org/bom\n ```\n\n Also extract the attested CycloneDX predicate with `gh attestation verify --format json --jq '.[0].verificationResult.statement.predicate'`, canonicalize both it and the downloaded release SBOM with `jq -S`, and `cmp` them. Verify one npm tarball subject the same way if you download the exact published tarball. Record any tag-only discrepancy as a release blocker and ship a new version rather than mutating an immutable release.\n\n If anything fails, investigate the logs and report to the user before retrying.\n\n5. **Replace the release notes:**\n Once the release is live and verified, replace the auto-generated notes body with the drafted release notes:\n ```bash\n gh release edit vX.Y.Z --notes-file RELEASE_NOTES_v.md\n ```\n\n---\n\n## Checklist\n\nBefore tagging, verify:\n- [ ] All 7 version files bumped consistently\n- [ ] Release notes drafted and reviewed\n- [ ] `bun run build:review` succeeded\n- [ ] `bun run build:hook` succeeded\n- [ ] `bun run build:opencode` succeeded\n- [ ] `bun run build:pi` succeeded (or pi-specific build step)\n- [ ] Version bump committed\n- [ ] Pi parity gate passed (imports, vendor.sh, dry-run pack)\n- [ ] No stale build artifacts (clean builds, no cache issues — run `bun install` first if dependencies changed)\n- [ ] The PR-safe `release-security` job generated a schema-valid, sentinel-complete SBOM and accepted the Grype policy with a fresh database\n- [ ] No scanner binary, database, generated SBOM/report, credential, or `DO_NOT_COMMIT` content is staged\n- [ ] For the first SBOM-enabled release, the canonical Mintlify install/verification page contains the README's SBOM scope, policy, checksum, SLSA, and CycloneDX commands (do not edit the deprecated Astro docs instead)\n\nAfter tagging, verify:\n- [ ] Release workflow completed with `release-security`, `attest`, `release`, and `npm-publish` green\n- [ ] GitHub Release created with all binaries, sidecars, SBOM, and SBOM sidecar\n- [ ] One native binary passes both the explicit SLSA and CycloneDX predicate checks pinned to the tag and signer workflow\n- [ ] Downloaded SBOM checksum passes and canonical JSON matches the attested predicate\n- [ ] `release-security-evidence` shows a fresh/active database and an accepted policy decision\n- [ ] npm packages published at correct version\n- [ ] npm trusted-publishing provenance remains visible for both packages\n- [ ] Release notes replaced via `gh release edit`\n","apps/skills/extra/plannotator-compound/SKILL.md":"---\nname: plannotator-compound\ndisable-model-invocation: true\ndescription: >\n Analyze a user's Plannotator plan archive to extract denial patterns, feedback\n taxonomy, evolution over time, and actionable prompt improvements — then produce\n a polished HTML dashboard report. Falls back to Claude Code ExitPlanMode denial\n reasons when Plannotator data is unavailable.\n---\n\n# Compound Planning Analysis\n\nYou are conducting a comprehensive research analysis of a user's Plannotator plan\narchive. The goal: extract patterns from their denied plans, reduce\nthem into actionable insights, and produce an elegant HTML dashboard report.\n\nThis is a multi-phase process. Each phase must complete fully before the next begins.\nResearch integrity is paramount — every file must be read, no skipping.\n\n## Source Selection\n\nBefore starting the analysis, determine which data source is available.\n\n1. **Plannotator mode (first-class)** — Determine the Plannotator data directory:\n use `$PLANNOTATOR_DATA_DIR` if set, otherwise `~/.plannotator`. Check the\n `plans/` subdirectory there. If it exists and contains `*-denied.md` files,\n use this mode. The entire workflow below is written for Plannotator data.\n\n2. **Claude Code fallback mode** — If the Plannotator archive is absent or\n contains no denied plans, check `~/.claude/projects/`. If present, read\n [references/claude-code-fallback.md](references/claude-code-fallback.md)\n before continuing. That reference explains how to use the bundled parser at\n [scripts/extract_exit_plan_mode_outcomes.py](scripts/extract_exit_plan_mode_outcomes.py)\n to extract denial reasons from Claude Code JSONL transcripts. Every phase\n below has a short note explaining what changes in fallback mode — the\n reference file has the details.\n\n3. **Neither available** — Ask the user for their Plannotator plans directory or\n Claude Code projects directory. Do not guess.\n\n## Phase 0: Locate Plans & Check for Previous Reports\n\nUse the mode chosen in Source Selection above.\n\n**Plannotator mode:** Verify the plans directory contains `*-denied.md` files. If\nnone exist, fall back to Claude Code mode before stopping.\n\n**Claude Code fallback mode:** Run the bundled parser per the fallback reference to\nbuild the denial-reason dataset. Create `/tmp/compound-planning/` if needed.\n\nIn either mode, proceed to Previous Report Detection below.\n\n### Previous Report Detection\n\nAfter locating the plans directory, check for existing reports:\n\n```\nls ${PLANNOTATOR_DATA_DIR:-~/.plannotator}/plans/compound-planning-report*.html\n```\n\nReports follow a versioned naming scheme:\n- First report: `compound-planning-report.html`\n- Subsequent reports: `compound-planning-report-v2.html`, `compound-planning-report-v3.html`, etc.\n\nIf one or more reports exist, determine the **latest** one (highest version number).\nGet its filesystem modification date using `stat` (macOS: `stat -f %Sm -t %Y-%m-%d`,\nLinux: `stat -c %y | cut -d' ' -f1`). This is the **cutoff date**.\n\nPresent the user with a choice:\n\n> \"I found a previous report (`compound-planning-report-v{N}.html`) last updated\n> on {CUTOFF_DATE}. I can either:\n>\n> 1. **Incremental** — Only analyze files dated after {CUTOFF_DATE}, saving tokens\n> and building on previous findings\n> 2. **Full** — Re-analyze the entire archive from scratch\n>\n> Which would you prefer?\"\n\nWait for the user's response before proceeding.\n\n**If incremental:** Filter all subsequent phases to only process files with dates\nafter the cutoff date. The new report version will note in its header narrative that\nit covers the period from {CUTOFF_DATE} to present, and reference the previous\nreport for earlier findings. The inventory (Phase 1) should still count ALL files\nfor overall stats, but clearly separate \"new since last report\" counts.\n\n**If full:** Proceed normally with all files, but still use the next version number\nfor the output filename.\n\n**If no previous report exists:** Proceed normally. The output filename will be\n`compound-planning-report.html` (no version suffix for the first report).\n\n## Phase 1: Inventory\n\nCount and report the dataset. **Always count ALL files** for overall stats,\nregardless of whether this is an incremental or full run:\n\n```\n- *-approved.md files (count)\n- *-denied.md files (count)\n- Date range (earliest to latest date found in filenames)\n- Total days spanned\n- Revision rate: denied / (approved + denied) — this is the \"X% of plans\n revised before coding\" stat used in dashboard section 1\n```\n\n**Note:** Ignore `*.annotations.md` files entirely. Denied files already contain\nthe full plan text plus all reviewer feedback appended after a `---` separator.\nAnnotation files are redundant subsets of this content — reading both would\ndouble-count feedback.\n\n**If incremental mode:** After the total counts, separately report the counts for\nfiles dated after the cutoff date only:\n\n```\nNew since {CUTOFF_DATE}:\n- *-denied.md files: X (of Y total)\n- New date range: {CUTOFF_DATE} to {LATEST_DATE}\n- New days spanned: N\n```\n\nIf fewer than 3 new denied files exist since the cutoff, warn the user:\n> \"Only {N} new denied plans since the last report. The incremental analysis may\n> be thin. Would you like to proceed or switch to a full analysis?\"\n\nAlso run `wc -l` across all `*-approved.md` files to get average lines per\napproved plan. This tells the user whether their plans are staying lightweight\nor bloating over time. You do not need to read approved plan contents — just\ntheir line counts. If possible, break this down by time period (e.g., monthly)\nto show whether plan size changed.\n\nDates appear in filenames in YYYY-MM-DD format, sometimes as a prefix\n(2026-01-07-name-approved.md) and sometimes embedded (name-2026-03-15-approved.md).\nExtract dates from all filenames.\n\nTell the user what you found and that you're beginning the extraction.\n\n**Claude Code fallback mode:** The Plannotator inventory fields above do not apply.\nFollow the inventory instructions in\n[references/claude-code-fallback.md](references/claude-code-fallback.md) instead —\nreport the denial-reason dataset assembled by the parser.\n\n## Phase 2: Map — Parallel Extraction\n\nThis is the most time-intensive phase. You must read EVERY `*-denied.md` file\n**in scope**. Do not skip files. Do not summarize early.\n\n**In scope** means: all denied files if running a full analysis, or only denied\nfiles dated after the cutoff date if running incrementally. In incremental mode,\nonly process files whose embedded YYYY-MM-DD date is strictly after the cutoff.\n\n**Claude Code fallback mode:** The parser output is the clean source dataset. Read\nthe fallback reference for the extraction prompt and batching strategy specific to\nJSON part files. Do not go back to raw `.jsonl` logs unless the parser fails or the\nuser asks for audit-level verification.\n\n**Important:** Only read `*-denied.md` files. Do NOT read approved plans,\nannotation files, or diff files. Each denied file contains the full plan text\nfollowed by a `---` separator and the reviewer's feedback — everything needed\nfor analysis is in one file.\n\n### Batching Strategy\n\nAll extraction agents should use `model: \"haiku\"` — they're doing straightforward\nfile reading and structured extraction, not reasoning. Haiku is faster and cheaper\nfor this work.\n\nThe approach depends on dataset size:\n\n**Tiny datasets (≤ 10 total files):** Read all files directly in the main agent —\nno need for sub-agents. Just read them sequentially and proceed to Phase 3.\n\n**Small datasets (11-30 files):** Launch 2-3 parallel Haiku agents, splitting\nfiles roughly evenly.\n\n**Medium datasets (31-80 files):** Launch 4-6 parallel Haiku agents (~10-15 files\neach). Split by file type and/or time period.\n\n**Large datasets (80+ files):** Launch as many parallel Haiku agents as needed to\nkeep each batch around 10-15 files. Split by the natural time boundaries in the\ndata (months, quarters, or whatever groupings produce balanced batches). If one\ntime period dominates (e.g., the most recent month has 3x the files), split that\nperiod into multiple batches.\n\nLaunch all extraction agents in parallel using the Agent tool with\n`run_in_background: true` and `model: \"haiku\"`.\n\n### Output Files\n\nEach extraction agent must write its results to a clean output file rather than\nrelying on the agent task output (which contains interleaved JSONL framework\nlogs that are difficult to parse). Instruct each agent to write to:\n\n```\n/tmp/compound-planning/extraction-{batch-name}.md\n```\n\nCreate the `/tmp/compound-planning/` directory before launching agents. The\nreduce agent in Phase 3 will read these clean files directly.\n\n### Extraction Prompt\n\nEach agent receives this instruction (adapt the time period, file list, and\noutput path):\n\n```\nYou are extracting structured data from denied plan files for a pattern analysis.\n\nDirectory: [PLANS DIRECTORY]\nFiles to read: [LIST OF SPECIFIC *-denied.md FILES]\nOutput: Write your complete results to [OUTPUT FILE PATH]\n\nEach denied file contains two parts separated by a --- line:\n1. The plan text (above the ---)\n2. The reviewer's feedback and annotations (below the ---)\n\nRead EVERY file in your list. For EACH file, extract:\n- The plan name/topic (from the plan text above the ---)\n- The denial reason or feedback given (from below the --- — capture the actual\n words used)\n- What was specifically asked to change\n- The type of feedback (let the content determine the category — don't force-fit\n into predefined types. Common types include things like: scope concerns,\n approach disagreements, missing information, process requirements, quality\n concerns, UX/design issues, naming disputes, clarification requests,\n testing/procedural denials — but the user's actual patterns may differ)\n- Any specific phrases or recurring language from the reviewer\n- Individual annotations if present (numbered feedback items with quoted text\n and reviewer comments)\n- The date (extracted from the filename)\n\nDo NOT skip any files. One entry per file.\n\nFormat each entry as:\n**[filename]**\n- Date: ...\n- Topic: ...\n- Denial reason: ...\n- Feedback type: ...\n- Specific asks: ...\n- Notable phrases: ...\n- Annotations: [count, with brief summary of each]\n---\n\nAfter processing all files, write the complete results to [OUTPUT FILE PATH].\nState the total file count at the end of the file.\n```\n\n### While Agents Run\n\nTrack completion. As each agent finishes, note the count of files it processed.\nVerify the total matches the inventory from Phase 1. If any agent's count is\nshort, flag it and consider re-launching for the missing files.\n\nIf an agent times out (possible with large batches — a batch of 128 files can\ntake 8+ minutes), re-launch it for just the unprocessed files. Check the output\nfile to see how far it got before timing out.\n\n## Phase 3: Reduce — Pattern Analysis\n\nOnce ALL extraction agents have completed (or all files have been read for tiny\ndatasets), proceed with the reduction. Reduction agents should use `model: \"sonnet\"`\n— this phase requires real analytical reasoning, not just file reading.\n\n### Reduction Strategy\n\nThe approach depends on how many extraction files were produced:\n\n**Standard (≤ 20 extraction files):** Launch a single Sonnet agent to read all\nextraction files and produce the full analysis. This covers most datasets.\n\n**Large (21+ extraction files):** Use a two-stage reduce:\n\n1. **Stage 1 — Partial reduces:** Split the extraction files into groups of 4-6.\n Launch parallel Sonnet agents, each reading one group and producing a partial\n analysis with the same sections listed below. Each writes to\n `/tmp/compound-planning/partial-reduce-{N}.md`.\n\n2. **Stage 2 — Final reduce:** A single Sonnet agent reads all partial reduce\n files and synthesizes them into the final comprehensive analysis. This agent\n merges taxonomies, combines counts, deduplicates patterns, and reconciles any\n conflicting categorizations across partials.\n\n**Claude Code fallback mode:** The reduction phase is the same. The only upstream\ndifference is that extraction files were derived from normalized denial-reason JSON\ninstead of Plannotator markdown files.\n\n### Reduction Prompt\n\nGive each reduction agent this prompt (adapt file paths for single vs multi-stage):\n\n```\nYou are a data scientist conducting the reduction phase of a map-reduce analysis\nacross a user's denied plan archive.\n\nRead ALL extraction files at [FILE PATHS]\n\nThese files contain structured extractions from every denied plan file. Each\nextraction includes the plan topic, denial feedback, annotations, and reviewer\nlanguage. Your job: aggregate everything, find patterns, cluster into a taxonomy,\nand produce a comprehensive analysis.\n\nBe exhaustive. Use real counts. Quote real phrases from the data. This is\nresearch — no hand-waving, no fabrication.\n\nWrite your complete results to [OUTPUT FILE PATH].\n\nProduce the following sections:\n[... sections listed below ...]\n```\n\nThe reduction agent's job is to let the data speak. Do not impose a predetermined\nframework — discover what's actually there. The analysis must produce:\n\n### 1. Denial Reason Taxonomy\nCategorize every denial into a finite set of types that emerge from the data. Count\noccurrences. Show percentages. Include real example quotes for each type. Aim for\n8-15 categories — enough to be specific, few enough to be scannable. Let the user's\nactual feedback determine what the categories are.\n\n### 2. Top Feedback Patterns (ranked by frequency)\nThe 5-10 most recurring patterns. For each: what the reviewer consistently asks for,\n3+ example quotes from different files, and whether the pattern changed over time.\n\n### 3. Recurring Phrases\nExact phrases the reviewer uses repeatedly, with counts and what they signal. These\nare the reviewer's vocabulary — their shorthand for what they care about.\n\n### 4. What the Reviewer Values (implicit preferences)\nDerived from patterns — what does this specific person care about most? Quality?\nSpeed? Narrative? Architecture? Process? Simplicity? Rank by evidence strength.\nThis section should feel like a personality profile of the reviewer's standards.\n\n### 5. What Agents Consistently Get Wrong\nThe flip side — what recurring mistakes trigger denials? What should agents stop\ndoing for this reviewer?\n\n### 6. Structural Requests\nWhat plan structure does the reviewer consistently demand? Required sections,\nordering, format preferences, level of detail expected.\n\n### 7. Evolution Over Time\nHow feedback patterns changed across the time span. Group by whatever natural time\nboundaries exist in the data (weeks for short spans, months for longer ones). Did\nexpectations mature? Did new patterns emerge? What shifted? If the dataset spans\nless than a month, note that evolution analysis is limited but still look for any\nprogression from early to late files.\n\n### 8. Actionable Prompt Instructions\nThe most important output. Based on all patterns: specific numbered instructions\nthat could be embedded in a planning prompt to prevent the most common denial\nreasons. Write these as actual directives an agent could follow. Be specific to\nthis user's patterns — generic advice like \"write good plans\" is worthless. Each\ninstruction should trace back to a real, frequent denial pattern.\n\nAfter writing the instructions, calculate what percentage of denials they would\naddress (count how many denials fall into categories covered by the instructions\nvs total denials). Report this percentage — it will be different for every user.\n\n## Phase 4: Generate the HTML Dashboard\n\nBuild a single, self-contained HTML file as the final deliverable. Save it to\nthe user's plans directory with a versioned filename:\n\n- First ever report: `compound-planning-report.html`\n- Second report: `compound-planning-report-v2.html`\n- Third report: `compound-planning-report-v3.html`\n- And so on.\n\nThe version number was determined in Phase 0 based on existing reports found.\n\n**If this is an incremental report**, the header should indicate the analysis\nperiod (e.g., \"March 15 – March 31, 2026\") and include a subtitle noting\n\"Incremental analysis — see v{N-1} for earlier findings.\" The narrative in\nsection 1 should frame findings as what's new or changed since the last report,\nnot as a complete picture. Overall stats in the header (file counts, revision\nrate) should still reflect the full archive for context.\n\nRead the template at `assets/report-template.html` for the **design language\nonly**. The template contains example data from a previous analysis — ignore all\ndata values, quotes, and percentages in the template. Use only its visual design:\ncolors, typography, spacing, component styles, and layout patterns.\n\n### Design Language (from template)\n\n- **Palette:** Light mode, warm off-white (#FDFCFB), text in slate scale, amber\n for highlights/accents, emerald for positive, rose for negative, indigo for\n action elements\n- **Typography:** Playfair Display (serif, for narrative headings), Inter (sans,\n for body/data), JetBrains Mono (mono, for code/phrases) — Google Fonts CDN\n- **Layout:** Single-column, max-width 1024px, generous vertical whitespace (128px\n between major sections), editorial/narrative-first aesthetic\n- **Tone:** Calm, reflective, authoritative. Like a personal retrospective journal,\n not a monitoring dashboard.\n\n### Page Frame (header + footer)\n\nBefore the 7 sections, the page has:\n\n- **Header:** Report title on the left (Playfair Display, ~36px), project name +\n date range below it in light meta text. On the right: file counts in mono\n (e.g., \"223 denials · 71 days\"). Separated from content by\n a bottom border. Generous bottom padding before section 1.\n\n- **Footer:** After section 7. Top border, centered italic Playfair Display tagline\n summarizing the corpus (e.g., \"Analysis of X denied plans from the Plannotator\n archive.\").\n\n### Dashboard Section Order (7 sections)\n\nThe report follows this exact section order. Each section builds on the previous\none — the flow moves from \"what happened\" through \"why\" to \"what to do about it\":\n\n1. **The story in the data** — An editorial narrative paragraph (Playfair Display\n serif, ~26px) that tells the headline finding in prose. Not bullet points — a\n real paragraph that reads like the opening of an article. Alongside it, a KPI\n sidebar with 3 key metrics (the top denial percentage, the overall revision\n rate, and the number of distinct denial categories found). Use an amber inline\n highlight on the most striking number in the narrative.\n\n2. **Why plans get denied** — The taxonomy as a ranked list. Each row: rank number\n (mono), category label, a thin 4px progress bar (top item in amber-500, rest\n in slate-300), percentage (mono), and for the top entries, a real italic quote\n from the data below the label. Show the top 10 categories or however many the\n data supports (minimum 5).\n\n3. **How expectations evolved** — One card per natural time period. Each card has:\n the period name in serif, a theme phrase in colored uppercase (different color\n per period to show progression), a description paragraph, and a stat line at\n the bottom (e.g., \"X denials · Y narrative requests\"). If the data spans less\n than 3 distinct periods, use 2 cards or even a single card with internal\n progression noted.\n\n4. **What works vs what doesn't** — Two side-by-side cards. Left: green-tinted\n (emerald-50/50 bg, emerald-100 border) with traits of plans that succeed for\n this reviewer. Right: red-tinted (rose-50/50 bg, rose-100 border) with what\n agents keep getting wrong. Both derived from the reduction analysis. Bulleted\n with small colored dots. 5-8 items per card.\n\n5. **The actionable output** — The diagnostic payoff. Opens with a Playfair\n Display narrative sentence stating how many prompt instructions were derived\n and what estimated percentage of denials they address (use the real calculated\n percentage from Phase 3, not a generic number). Then the top 3 most impactful\n improvements as numbered items, each with an amber number, bold title, and\n one-line description. This section bridges the analysis and the full prompt\n that follows.\n\n6. **Your most-used phrases** — Grid of chips (2-col mobile, 3-col desktop). Each\n chip: monospace quoted phrase on the left, frequency count on the right. White\n bg, slate-200 border, rounded-12px. Show 9-12 of the most recurring phrases\n found. These should be the reviewer's actual words — their verbal fingerprint.\n\n7. **The corrective prompt** — Dark panel (slate-900 bg, white text, rounded-3xl,\n shadow-xl). Opens with a Playfair intro sentence about the instructions. Then\n a dark code block (slate-800/80 bg, amber-200 monospace text) containing the\n full numbered prompt instructions from Phase 3. Include a copy-to-clipboard\n button that works (JS included). Below the code block: a gradient glow card\n (indigo-to-purple blurred halo behind a white card) with a closing message\n that these instructions are personal — derived from the user's own feedback,\n their own language, their own standards.\n\n### Adaptation Rules\n\n- If the user has < 3 months of data, reduce the evolution section to fewer cards\n- If most denied files lack feedback below the `---` (bare denials with no\n annotations), note this in the narrative — the analysis will be thinner\n- **Claude Code fallback mode:** Explicitly label the report source as Claude Code\n `ExitPlanMode` denial reasons. Do not fabricate Plannotator-only fields such as\n annotation counts or approved-plan line counts. See the fallback reference for\n KPI substitutes and footer/provenance guidance.\n- If fewer than 5 denial categories emerge, combine the taxonomy and patterns\n sections into one\n- If the dataset is very small (< 20 files), the narrative should acknowledge the\n limited sample size and frame findings as preliminary\n- The number of prompt instructions will vary per user — could be 8 or 20. Don't\n force exactly 17. Let the data determine the count.\n- The top 3 actionable items in section 5 must be the 3 that cover the largest\n share of denials, not the 3 that sound most impressive\n\n### Key Rules\n\n1. Every number must come from the real analysis — no fabricated data\n2. Every quote must be a real quote from a real file\n3. The taxonomy percentages must be calculated from real counts\n4. The prompt instructions must trace back to actual denial patterns\n5. The copy button on the prompt block must work (include the JS)\n\nAfter generating, open the file in the user's browser.\n\n## Phase 5: Summary\n\nTell the user:\n- How many denied files were analyzed\n- If incremental: how many were new since the last report\n- The top 3 denial patterns found\n- The estimated percentage of denials the prompt instructions would address\n- The single most impactful prompt improvement\n- Where the report was saved (including version number)\n- If incremental: remind the user that earlier findings are in the previous report\n\n**Claude Code fallback mode:** Adapt the summary per the fallback reference —\nreport human denial reasons analyzed and total `ExitPlanMode` attempts scanned\ninstead of Plannotator file counts.\n\n## Phase 6: Improvement Hook\n\nAfter presenting the summary, ask the user if they want to enable an **improvement\nhook** — this takes the corrective prompt instructions from section 7 of the report\nand writes them to a file that Plannotator's `EnterPlanMode` hook can inject into\nevery future planning session automatically.\n\n> \"Would you like to enable the improvement hook? This will save the corrective\n> prompt instructions to a file that gets automatically injected into all future\n> planning sessions — so Claude sees your feedback patterns before writing any plan.\"\n\n**If yes:**\n\nThe hook file lives at:\n\n```\n${PLANNOTATOR_DATA_DIR:-~/.plannotator}/hooks/compound/enterplanmode-improve-hook.txt\n```\n\nCreate the `hooks/compound/` directory inside the data directory if it doesn't exist.\n\nThe file contents should be the corrective prompt instructions from Phase 3 —\nthe same numbered list that appears in section 7 of the HTML report. Write them\nas plain text, one instruction per line, prefixed with their number. No HTML, no\nmarkdown fences, no preamble — just the instructions themselves. The hook system\nwill inject this file's contents as-is into the planning context.\n\n**If the file already exists:**\n\nRead the existing file and present the user with a choice:\n\n> \"An improvement hook already exists from a previous analysis. I can:\n>\n> 1. **Replace** — Overwrite with the new instructions (the old ones are gone)\n> 2. **Merge** — Combine both, deduplicating overlapping instructions and\n> keeping the best version of each\n> 3. **Keep existing** — Leave the current hook as-is, skip this step\n>\n> Which would you prefer?\"\n\n- **Replace:** Overwrite the file with the new instructions.\n- **Merge:** Read the existing instructions, compare with the new ones, and\n produce a merged set. Remove duplicates (same intent even if worded differently).\n When two instructions cover the same pattern, keep the more specific or\n actionable version. Re-number the final list sequentially. Write the merged\n result to the file. Show the user what changed (added N new, removed N\n redundant, kept N existing).\n- **Keep existing:** Do nothing, move on.\n\n**If no:** Skip this phase entirely.\n\n## Important Notes\n\n- **Data source priority:** Plannotator is the first-class path. Claude Code log\n analysis is the secondary path for users without Plannotator archives.\n- **Research integrity:** Every file must be read. The value of this analysis comes\n from completeness. Sampling or skipping undermines the findings.\n- **Real data only:** Never fabricate quotes, percentages, or patterns. If the data\n doesn't show a clear pattern, say so honestly rather than inventing one.\n- **Let the data lead:** The taxonomy, patterns, and instructions should emerge from\n what's actually in the files. Different users will have completely different\n denial patterns. A user building mobile apps will have different feedback than\n one building APIs. Don't assume what the patterns will be.\n- **Agent parallelization:** For large datasets, maximize parallel agents to reduce\n wall-clock time. The bottleneck is the largest batch — split it.\n- **Structured extraction format:** Ask extraction agents to return structured text\n with consistent delimiters so the reduce agent can parse reliably.\n- **The report is the artifact:** The HTML dashboard is what the user keeps. It\n should be beautiful, honest, and useful. Every section should feel like it was\n written about them specifically, because it was.\n","apps/skills/core/plannotator-review/SKILL.md":"---\nname: plannotator-review\ndescription: Open Plannotator's browser-based code review UI for the current worktree, another directory, or a pull request URL, then act on the feedback that comes back.\ndisable-model-invocation: true\n---\n\n# Plannotator Review\n\nUse this skill when the user wants to review current code changes in Plannotator instead of reading a diff inline.\n\nRun:\n\n```bash\nplannotator review [--base ] [--diff-type ] [directory-or-pr-url]\n```\n\nReviewing one layer of a stacked branch? Pass `--base ` so the review shows only what this layer adds, instead of everything since `main`. Both flags are session-only (the reviewer can change either in the UI; nothing is persisted) and git-only.\n\nTo review another repository or worktree, pass its directory (relative to the current session or absolute), e.g. `plannotator review ../feature-worktree`. Quote paths containing spaces. Feedback names the selected directory; apply changes there.\n\nBehavior:\n\n1. Launch the command with Bash.\n2. Wait for it to finish.\n3. If it returns feedback or annotations, address them in the same conversation.\n4. If it returns an approval/LGTM-style message, acknowledge that review passed and continue.\n\nDo not ask the user to copy shell commands into chat. Run the command yourself.\n","apps/skills/core/plannotator-last/SKILL.md":"---\nname: plannotator-last\ndescription: Open Plannotator on the latest rendered assistant message and use the returned annotations to revise that message or continue.\ndisable-model-invocation: true\n---\n\n# Plannotator Last\n\nUse this skill when the user wants to annotate the latest assistant response in Plannotator.\n\nDo not send a commentary/status message before running the command. The command\ntargets the latest rendered assistant response, so a preamble can mistakenly become the\nthing being annotated.\n\nRun:\n\n```bash\nplannotator last\n```\n\nBehavior:\n\n1. Launch the command with Bash.\n2. Wait for the annotation session to finish.\n3. If feedback is returned, incorporate it into the follow-up response.\n4. If the session closes without feedback, mention that briefly and continue.\n5. An approval may still carry notes — a `\"decision\": \"approved\"` result with a\n `\"feedback\"` field. Read those notes and carry them into subsequent work, but\n do not redo the message over them: they are guidance, not a change request.\n\nRun the command yourself rather than telling the user to invoke shell syntax manually.\n","apps/skills/core/plannotator-annotate/SKILL.md":"---\nname: plannotator-annotate\ndescription: Open Plannotator's annotation UI for a markdown file, plain-text config file (.yaml, .json, .toml, .ini, .csv, .log, …), HTML file, URL, or folder and then respond to the returned annotations.\ndisable-model-invocation: true\n---\n\n# Plannotator Annotate\n\nUse this skill when the user wants to annotate a document in Plannotator instead of reviewing it inline in chat.\n\nRun for ordinary annotation/feedback:\n\n```bash\nplannotator annotate \n```\n\nRun when the user asks to review, approve, accept, or gate a generated plan/spec/document:\n\n```bash\nplannotator annotate --gate --json\n```\n\nPlain `annotate` has no **Approve** button; it only supports feedback or closing the session. Never promise an approval action unless `--gate` is present. `--json` only changes the output format and does not enable approval by itself.\n\nBehavior:\n\n1. Launch the command with Bash.\n2. Wait for the browser review to finish.\n3. If annotations are returned, address them directly.\n4. If the session closes without feedback, say so briefly and continue.\n5. In a `--gate` session, an approval may still carry notes — a `\"decision\": \"approved\"` result with a\n `\"feedback\"` field (without `--json`, an \"Approved with Notes\" message). Read those notes and carry them into subsequent work, but\n do not revise the document over them: they are guidance, not a change request.\n6. If the command reports that the arguments could not be resolved to a file,\n URL, or folder, work out which target the user means and re-run the command\n yourself with that concrete path or URL.\n\nDo not ask the user to paste a shell command into the chat. Run the command yourself.\n","apps/skills/claude/plannotator-review/SKILL.md":"---\nname: plannotator-review\ndescription: Open Plannotator's browser-based code review UI for the current worktree, another directory, or a pull request URL, then act on the feedback that comes back.\nallowed-tools: Bash(plannotator:*)\ndisable-model-invocation: true\n---\n\n# Plannotator Review\n\nArguments pass through to `plannotator review`: one directory or PR/MR URL, `--git` / `--gitbutler`, and the session-only open-state flags `--base ` / `--diff-type ` (git-only; for a stacked branch, `--base ` reviews just that layer).\n\nFor another repository or worktree, pass its path relative to this session or an absolute path, e.g. `/plannotator-review ../feature-worktree`. Quote paths containing spaces. Supply a target, not prose; feedback names the directory where changes belong.\n\n## Code review feedback\n\n!`plannotator review $ARGUMENTS`\n\n## Your task\n\nIf the review above contains feedback or annotations, address them in the same conversation. If no changes were requested (an approval/LGTM-style result), acknowledge that review passed and continue.\n\nIf the review was moved to the background, wait for it to finish. If Claude Code stopped it at its background time limit before the user decided, tell the user, and only when they ask, run `plannotator review $ARGUMENTS` again with `run_in_background` and `timeout: 7200000`: their annotations are restored from the saved draft.\n","apps/skills/claude/plannotator-last/SKILL.md":"---\nname: plannotator-last\ndescription: Open Plannotator on the latest rendered assistant message and use the returned annotations to revise that message or continue.\nallowed-tools: Bash(plannotator:*)\ndisable-model-invocation: true\n---\n\n# Plannotator Last\n\n## Message annotations\n\n!`plannotator annotate-last $ARGUMENTS`\n\n## Your task\n\nThe output above will be one of:\n\n1. The exact text `The user approved.`, an \"Approved with Notes\" message, OR a JSON object with `\"decision\": \"approved\"`. The user approved your last message. If it is the Approved with Notes message, or that object also carries a `\"feedback\"` field, the user approved *with notes*: read them and carry them into subsequent work — they are non-blocking guidance, not a request to revise the message. Otherwise acknowledge with a single sentence (\"Approved.\") and stop. Either way, do not begin any work.\n2. Empty, OR a JSON object with `\"decision\": \"dismissed\"`. The user closed the session without requesting changes. Acknowledge with a single sentence (\"Annotation session closed.\") and stop. Do not begin any work.\n3. Plaintext annotation feedback, OR a JSON object with `\"decision\": \"annotated\"` and a `\"feedback\"` field. Address the feedback. The user has reviewed your last message and provided specific annotations and comments.\n","apps/skills/claude/plannotator-annotate/SKILL.md":"# plannotator-annotate\n\nPath: `apps/skills/claude/plannotator-annotate/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/claude/plannotator-annotate/SKILL.md)","apps/kiro-cli/skills/plannotator-review/SKILL.md":"# plannotator-review\n\nPath: `apps/kiro-cli/skills/plannotator-review/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/kiro-cli/skills/plannotator-review/SKILL.md)","apps/kiro-cli/skills/plannotator-annotate/SKILL.md":"# plannotator-annotate\n\nPath: `apps/kiro-cli/skills/plannotator-annotate/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/kiro-cli/skills/plannotator-annotate/SKILL.md)","AGENTS.md":"# AI Agent Protocol & Instructions\n\nPath: `AGENTS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/AGENTS.md)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.claude-plugin/marketplace.json)",".factory-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.factory-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.factory-plugin/marketplace.json)",".github/plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.github/plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.github/plugin/marketplace.json)","apps/copilot/plugin.json":"# copilot Plugin Manifest\n\nPath: `apps/copilot/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/copilot/plugin.json)","packages/ui/AGENTS.md":"# Ui Skill\n\nPath: `packages/ui/AGENTS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/AGENTS.md)","packages/ui/HANDOFF.md":"# Ui Skill\n\nPath: `packages/ui/HANDOFF.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/HANDOFF.md)","packages/ui/package.json":"# Ui Skill\n\nPath: `packages/ui/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/package.json)","packages/ui/README.md":"# ui Documentation\n\nPath: `packages/ui/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/README.md)","packages/ui/tsconfig.json":"# Ui Skill\n\nPath: `packages/ui/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/tsconfig.json)","packages/ui/tsconfig.strict-consumer.json":"# Ui Skill\n\nPath: `packages/ui/tsconfig.strict-consumer.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/tsconfig.strict-consumer.json)","packages/shared/package.json":"# Shared Skill\n\nPath: `packages/shared/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/shared/package.json)","packages/shared/tsconfig.json":"# Shared Skill\n\nPath: `packages/shared/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/shared/tsconfig.json)","packages/server/codex-review-schema.json":"# Server Skill\n\nPath: `packages/server/codex-review-schema.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/server/codex-review-schema.json)","packages/server/package.json":"# Server Skill\n\nPath: `packages/server/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/server/package.json)","packages/server/tsconfig.json":"# Server Skill\n\nPath: `packages/server/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/server/tsconfig.json)","packages/review-editor/package.json":"# Review-editor Skill\n\nPath: `packages/review-editor/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/package.json)","packages/review-editor/tsconfig.json":"# Review-editor Skill\n\nPath: `packages/review-editor/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/tsconfig.json)","packages/editor/package.json":"# Editor Skill\n\nPath: `packages/editor/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/editor/package.json)","packages/core/package.json":"# Core Skill\n\nPath: `packages/core/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/core/package.json)","packages/core/tsconfig.json":"# Core Skill\n\nPath: `packages/core/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/core/tsconfig.json)","packages/ai/package.json":"# Ai Skill\n\nPath: `packages/ai/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ai/package.json)","packages/ai/tsconfig.json":"# Ai Skill\n\nPath: `packages/ai/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ai/tsconfig.json)","apps/opencode-plugin/commands/plannotator-annotate.md":"# Command: /plannotator-annotate\n\nPath: `apps/opencode-plugin/commands/plannotator-annotate.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/opencode-plugin/commands/plannotator-annotate.md)","apps/opencode-plugin/commands/plannotator-last.md":"# Command: /plannotator-last\n\nPath: `apps/opencode-plugin/commands/plannotator-last.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/opencode-plugin/commands/plannotator-last.md)","apps/opencode-plugin/commands/plannotator-review.md":"# Command: /plannotator-review\n\nPath: `apps/opencode-plugin/commands/plannotator-review.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/opencode-plugin/commands/plannotator-review.md)","apps/kiro-cli/agents/plannotator.json":"# Agents Skill\n\nPath: `apps/kiro-cli/agents/plannotator.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/kiro-cli/agents/plannotator.json)","apps/hook/.claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `apps/hook/.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/hook/.claude-plugin/plugin.json)","apps/droid-plugin/.factory-plugin/plugin.json":"# factory-plugin Plugin Manifest\n\nPath: `apps/droid-plugin/.factory-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/droid-plugin/.factory-plugin/plugin.json)","apps/copilot/commands/plannotator-annotate.md":"# Command: /plannotator-annotate\n\nPath: `apps/copilot/commands/plannotator-annotate.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/copilot/commands/plannotator-annotate.md)","apps/copilot/commands/plannotator-last.md":"# Command: /plannotator-last\n\nPath: `apps/copilot/commands/plannotator-last.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/copilot/commands/plannotator-last.md)","apps/copilot/commands/plannotator-review.md":"# Command: /plannotator-review\n\nPath: `apps/copilot/commands/plannotator-review.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/copilot/commands/plannotator-review.md)","packages/ui/.migration/badge.md":"# .migration Skill\n\nPath: `packages/ui/.migration/badge.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/badge.md)","packages/ui/.migration/button.md":"# .migration Skill\n\nPath: `packages/ui/.migration/button.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/button.md)","packages/ui/.migration/dialog.md":"# .migration Skill\n\nPath: `packages/ui/.migration/dialog.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/dialog.md)","packages/ui/.migration/dropdown-menu.md":"# .migration Skill\n\nPath: `packages/ui/.migration/dropdown-menu.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/dropdown-menu.md)","packages/ui/.migration/popout-dialog.md":"# .migration Skill\n\nPath: `packages/ui/.migration/popout-dialog.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/popout-dialog.md)","packages/ui/.migration/popover.md":"# .migration Skill\n\nPath: `packages/ui/.migration/popover.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/popover.md)","packages/ui/.migration/project.md":"# .migration Skill\n\nPath: `packages/ui/.migration/project.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/project.md)","packages/ui/.migration/tabs.md":"# .migration Skill\n\nPath: `packages/ui/.migration/tabs.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/tabs.md)","packages/ui/.migration/tooltip.md":"# .migration Skill\n\nPath: `packages/ui/.migration/tooltip.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/tooltip.md)","packages/review-editor/.migration/checkbox.md":"# .migration Skill\n\nPath: `packages/review-editor/.migration/checkbox.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/.migration/checkbox.md)","packages/review-editor/.migration/context-menu.md":"# .migration Skill\n\nPath: `packages/review-editor/.migration/context-menu.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/.migration/context-menu.md)","packages/review-editor/.migration/dropdown-menu.md":"# .migration Skill\n\nPath: `packages/review-editor/.migration/dropdown-menu.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/.migration/dropdown-menu.md)","packages/review-editor/.migration/popover.md":"# .migration Skill\n\nPath: `packages/review-editor/.migration/popover.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/.migration/popover.md)","packages/review-editor/.migration/project.md":"# .migration Skill\n\nPath: `packages/review-editor/.migration/project.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/.migration/project.md)",".agents/skills/release/references/release-notes-v0.12.0.md":"# References Skill\n\nPath: `.agents/skills/release/references/release-notes-v0.12.0.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.agents/skills/release/references/release-notes-v0.12.0.md)",".agents/skills/release/references/release-notes-v0.13.0.md":"# References Skill\n\nPath: `.agents/skills/release/references/release-notes-v0.13.0.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.agents/skills/release/references/release-notes-v0.13.0.md)",".agents/skills/release/references/release-notes-v0.13.1.md":"# References Skill\n\nPath: `.agents/skills/release/references/release-notes-v0.13.1.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.agents/skills/release/references/release-notes-v0.13.1.md)","apps/skills/extra/plannotator-visual-explainer/references/design-system.md":"# References Skill\n\nPath: `apps/skills/extra/plannotator-visual-explainer/references/design-system.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-visual-explainer/references/design-system.md)","apps/skills/extra/plannotator-visual-explainer/references/pr-components.md":"# References Skill\n\nPath: `apps/skills/extra/plannotator-visual-explainer/references/pr-components.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-visual-explainer/references/pr-components.md)","apps/skills/extra/plannotator-visual-explainer/references/svg-patterns.md":"# References Skill\n\nPath: `apps/skills/extra/plannotator-visual-explainer/references/svg-patterns.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-visual-explainer/references/svg-patterns.md)","apps/skills/extra/plannotator-visual-explainer/references/theme-override.md":"# References Skill\n\nPath: `apps/skills/extra/plannotator-visual-explainer/references/theme-override.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-visual-explainer/references/theme-override.md)","apps/skills/extra/plannotator-setup-goal/agents/openai.yaml":"# Agents Skill\n\nPath: `apps/skills/extra/plannotator-setup-goal/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-setup-goal/agents/openai.yaml)","apps/skills/extra/plannotator-compound/references/claude-code-fallback.md":"# References Skill\n\nPath: `apps/skills/extra/plannotator-compound/references/claude-code-fallback.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-compound/references/claude-code-fallback.md)","apps/skills/core/plannotator-review/agents/openai.yaml":"# Agents Skill\n\nPath: `apps/skills/core/plannotator-review/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/core/plannotator-review/agents/openai.yaml)","apps/skills/core/plannotator-last/agents/openai.yaml":"# Agents Skill\n\nPath: `apps/skills/core/plannotator-last/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/core/plannotator-last/agents/openai.yaml)","apps/skills/core/plannotator-annotate/agents/openai.yaml":"# Agents Skill\n\nPath: `apps/skills/core/plannotator-annotate/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/core/plannotator-annotate/agents/openai.yaml)","apps/marketing/src/content/docs/commands/annotate.md":"# Command: /annotate\n\nPath: `apps/marketing/src/content/docs/commands/annotate.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/marketing/src/content/docs/commands/annotate.md)","apps/marketing/src/content/docs/commands/annotate-last.md":"# Command: /annotate-last\n\nPath: `apps/marketing/src/content/docs/commands/annotate-last.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/marketing/src/content/docs/commands/annotate-last.md)","apps/marketing/src/content/docs/commands/code-review.md":"# Command: /code-review\n\nPath: `apps/marketing/src/content/docs/commands/code-review.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/marketing/src/content/docs/commands/code-review.md)","apps/marketing/src/content/docs/commands/plan-review.md":"# Command: /plan-review\n\nPath: `apps/marketing/src/content/docs/commands/plan-review.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/marketing/src/content/docs/commands/plan-review.md)"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# AI Agent Protocol & Instructions\n\nPath: `AGENTS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/AGENTS.md)","tokens":300,"sizeBytes":157},{"name":"release-notes-v0.12.0.md","path":".agents/skills/release/references/release-notes-v0.12.0.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.agents/skills/release/references/release-notes-v0.12.0.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# References Skill\n\nPath: `.agents/skills/release/references/release-notes-v0.12.0.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.agents/skills/release/references/release-notes-v0.12.0.md)","tokens":300,"sizeBytes":239},{"name":"release-notes-v0.13.0.md","path":".agents/skills/release/references/release-notes-v0.13.0.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.agents/skills/release/references/release-notes-v0.13.0.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# References Skill\n\nPath: `.agents/skills/release/references/release-notes-v0.13.0.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.agents/skills/release/references/release-notes-v0.13.0.md)","tokens":300,"sizeBytes":239},{"name":"release-notes-v0.13.1.md","path":".agents/skills/release/references/release-notes-v0.13.1.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.agents/skills/release/references/release-notes-v0.13.1.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# References Skill\n\nPath: `.agents/skills/release/references/release-notes-v0.13.1.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.agents/skills/release/references/release-notes-v0.13.1.md)","tokens":300,"sizeBytes":239},{"name":"SKILL.md","path":".agents/skills/release/SKILL.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.agents/skills/release/SKILL.md","title":"release-plannotator","category":"anthropic-skill","format":"markdown","content":"---\nname: release-plannotator\ndescription: Prepare and execute a Plannotator release — draft release notes with full contributor credit, bump versions across all package files, build in dependency order, and kick off the tag-driven release pipeline. Use this skill whenever the user mentions preparing a release, bumping versions, writing release notes, tagging a release, or publishing. Also trigger when the user says things like \"let's ship\", \"prep a release\", \"what's changed since last release\", or \"time to cut a new version\".\n---\n\n# Plannotator Release\n\nThe process has four phases. Phase 1 (release notes) is where most of the work happens — present the draft for review before proceeding to later phases.\n\n## Phase 1: Draft Release Notes\n\nThis is the most important phase. The release notes are the public face of each version and the primary way the community sees their contributions recognized.\n\n### Step 1: Determine scope\n\n1. Find the latest release tag: `git tag --sort=-v:refname | head -1`\n2. Determine the new version number. Ask the user if unclear (patch, minor, or major).\n3. Gather all changes since the last tag:\n - `git log --oneline ..HEAD` for commit history\n - `git log --merges --oneline ..HEAD` for merged PRs\n4. For each PR, use `gh pr view --json title,author,body,closedIssues,labels` to get details.\n\n### Step 2: Research contributors\n\nThis is critical. Every person who participated in the release gets credit — not just PR authors.\n\nFor each PR and linked issue, collect:\n- **PR authors** — the person who wrote the code\n- **Issue reporters** — who filed the bug or feature request\n- **Issue commenters** — who participated in the discussion with useful context\n- **Discussion creators** — who started relevant GitHub Discussions\n- **Feature requestors** — check the linked \"closes #N\" issues and their authors\n\nUse the GitHub API via `gh`:\n```bash\n# Get issue details including author\ngh issue view --json author,title,body\n\n# Get issue comments to find participants\ngh api repos/backnotprop/plannotator/issues//comments --jq '.[].user.login'\n\n# Get PR review comments\ngh api repos/backnotprop/plannotator/pulls//comments --jq '.[].user.login'\n```\n\n### Step 3: Write the release notes\n\nRead the reference release notes in `references/` for the canonical template structure. These are real release notes from previous versions — match their tone, structure, and level of detail.\n\n- `release-notes-v0.13.0.md` — large release, 14 PRs, 3 first-time contributors, \"New Contributors\" + narrative \"Contributors\" section\n- `release-notes-v0.12.0.md` — large community release, 14 PRs, 10 external, detailed narrative \"Contributors\" section\n- `release-notes-v0.13.1.md` — small patch release, 2 PRs, no external authors, \"Community\" section focused on issue reporters\n\nPay attention to how each reference handles contributor crediting differently. Pick the pattern that fits the release's contributor profile — a release with many external PRs warrants a narrative \"Contributors\" section; a patch driven by issue reports uses a lighter \"Community\" section.\n\nWrite the file to the repo root as `RELEASE_NOTES_v.md`.\n\n#### Structure\n\n1. **X/Twitter follow link** — first line, always the same:\n ```\n Follow [@plannotator](https://x.com/plannotator) on X for updates\n ```\n\n2. **\"Missed recent releases?\"** collapsible table — copy from the previous release's notes, then:\n - Add the previous release (the one you're succeeding) as the newest row\n - Keep roughly 10-12 rows; drop the oldest if needed\n - Each row: version link + comma-separated feature highlights (short phrases)\n\n3. **\"What's New in vX.Y.Z\"** — the heart of the notes\n - Open with 1-3 sentences summarizing the release theme and scope. Mention how many PRs, how many from external contributors, any first-timers.\n - Each major feature/fix gets its own `###` subsection with:\n - A descriptive heading (not the PR title verbatim — rephrase for clarity)\n - 1-4 paragraphs explaining what changed and why it matters. Be specific and concrete. Describe the problem that existed before, what the change does, and how users experience it.\n - Credit line at the bottom: PR link, linked issues with `closing [#N]`, and contributor attribution\n - Minor changes go under `### Additional Changes` as bold-titled bullets\n\n4. **Install / Update** — standard block, read from the previous release notes and reuse verbatim\n\n5. **\"What's Changed\"** — bullet list of every PR in the release:\n ```\n - feat: descriptive PR title by @author in [#N](url)\n ```\n\n6. **\"New Contributors\"** — if any first-time contributors:\n ```\n - @username made their first contribution in [#N](url)\n ```\n\n7. **\"Contributors\" or \"Community\"** — narrative section recognizing everyone who participated:\n - PR authors get a sentence about what they built\n - Issue reporters and commenters get listed with what they reported/discussed\n - Group community issue reporters in a bullet list at the end\n\n8. **Full Changelog link**:\n ```\n **Full Changelog**: https://github.com/backnotprop/plannotator/compare/...\n ```\n\n#### Writing guidelines\n\n- **Narrative over noise.** Write in clear, readable prose. Not marketing-speak, not changelog-dump. Explain what changed and why someone should care, in plain language.\n- **Bullets where they help.** Use bullet lists for enumerating discrete items (additional changes, contributor lists). Use paragraphs for explaining features.\n- **No cliches or buzzwords.** Don't say \"exciting\", \"game-changing\", \"seamless\", \"powerful\". Just describe what happened.\n- **No punchlines.** Don't end sections with a clever quip or a summary zinger. Let the feature speak for itself.\n- **Speak through practical benefit.** Describe what changed and what it means for the user in concrete, reliable terms. Not aspirational, not hype — just what it does.\n- **Don't overuse em dashes.** One or two per release is fine. If you notice them stacking up, restructure the sentence instead.\n- **Grammatical structure matters.** Vary sentence structure. Active voice. Concrete subjects and verbs.\n- **Contributor tags.** Use `@username` — bare at-mentions, not markdown links like `[@user](url)`. GitHub renders bare `@mentions` with avatar icons in release notes. This is important for community recognition.\n- **Every contributor counts.** Everyone who filed an issue, left a comment that shaped a decision, or participated in a discussion gets mentioned. This project's community is its lifeblood.\n\n### Step 4: Present for review\n\nWrite the draft to `RELEASE_NOTES_v.md` in the repo root and tell the user it's ready for review. Do not `git add` or commit this file — release notes are kept untracked by design. Wait for their feedback before proceeding to Phase 2.\n\n---\n\n## Phase 2: Version Bump\n\nBump the version string in these **7 files** (and only these — other package.json files use stub versions):\n\n| File | Field |\n|------|-------|\n| `package.json` (root) | `\"version\"` |\n| `apps/opencode-plugin/package.json` | `\"version\"` |\n| `apps/pi-extension/package.json` | `\"version\"` |\n| `apps/hook/.claude-plugin/plugin.json` | `\"version\"` |\n| `apps/copilot/plugin.json` | `\"version\"` |\n| `openpackage.yml` (root) | `version:` |\n| `packages/server/package.json` | `\"version\"` |\n\nRead each file, confirm the current version matches expectations, then update all 7 atomically.\n\nDo not bump the VS Code extension (`apps/vscode-extension/package.json`) — it has independent versioning.\n\n---\n\n## Phase 3: Build\n\nRun builds in dependency order:\n\n```bash\nbun run build:review # 1. Code review editor (standalone Vite build)\nbun run build:hook # 2. Plan review + hook server (copies review's built HTML into hook dist)\nbun run build:opencode # 3. OpenCode plugin (copies built HTML from hook + review)\nbun run build:pi # 4. Pi extension (chains review → hook → pi internally, safe to run after 1-2)\n```\n\n`build:pi` chains review and hook internally, so after steps 1-2 it only runs the pi-specific build.\n\nVerify all builds succeed before proceeding.\n\n### Pi Parity Gate\n\nAfter builds pass, audit the Pi extension to ensure all server-side imports resolve in the published package. This catches missing files before they reach npm.\n\n1. **Check imports vs `files` array.** Trace all local imports (starting with `./` or `../`) from `index.ts`, `server.ts`, `tool-scope.ts`, and every file in `server/`. Verify each target is covered by a pattern in the `files` array of `apps/pi-extension/package.json`.\n\n2. **Check `vendor.sh` covers all shared/ai imports.** Every `../generated/*.js` import in the server files must have a corresponding entry in `vendor.sh`'s copy loops. If a new shared module or AI module was added to `packages/shared/` or `packages/ai/` and is imported by Pi's server code, it must be added to `vendor.sh`.\n\n3. **Dry-run the pack.** Run `cd apps/pi-extension && bun pm pack --dry-run` and verify the output includes every file the server imports. Look specifically for any newly added files since the last release.\n\n4. **Quick smoke test.** Confirm `generated/` contains all expected files after build, especially any new ones (e.g., a new shared module added in this release cycle).\n\nIf anything is missing, fix it before proceeding to Phase 4. Common fixes:\n- Add the file to `vendor.sh`'s copy loop\n- Add the file or directory to the `files` array in `package.json`\n- Add an import path fix (Pi uses `../generated/` not `@plannotator/shared` or `@plannotator/ai`)\n\n---\n\n## Phase 4: Commit, Tag, and Release\n\n1. **Commit the version bump:**\n ```\n chore: bump version to X.Y.Z\n ```\n Stage only the 7 version-bumped files. Do not stage the release notes file (it's untracked by design).\n\n2. **Create and push the tag:**\n ```bash\n git tag vX.Y.Z\n git push origin main\n git push origin vX.Y.Z\n ```\n The `v*` tag push triggers the release pipeline (`.github/workflows/release.yml`).\n\n3. **The pipeline handles everything else:**\n - Runs tests\n - Cross-compiles binaries for 6 platforms (macOS ARM64/x64, Linux x64/ARM64, Windows x64/ARM64)\n - Compiles paste service binaries (same 6 platforms)\n - Packs the two npm packages in a credential-free job\n - Downloads pinned, checksum-verified Syft and Grype binaries; generates and schema-validates the release-wide CycloneDX SBOM after all shipped subjects exist\n - Forces the repository-owned, suppression-free Grype configuration, retries the official database update up to three times, requires a valid/active schema-v6 database no more than 120 hours old with no pending update, and preserves the machine-readable scan/database/policy evidence as a workflow artifact\n - Rejects every scanner-side ignored match, then blocks before any attestation or publication on CISA KEV or fixable Critical findings classified as shipped/runtime or unknown-applicability. High, development-only, and no-fix Critical findings are report-only but remain in the evidence\n - Generates SLSA build provenance attestations for all 12 binaries via `actions/attest-build-provenance` (signed through Sigstore, recorded in Rekor)\n - Uses the separate official `actions/attest` SBOM path to bind the CycloneDX predicate to all 12 binaries and both npm tarballs through the same GitHub OIDC/Sigstore service. This is an inventory attestation, not a replacement for SLSA or npm provenance\n - Creates the GitHub Release with all binaries, SHA256 sidecars, the versioned CycloneDX SBOM, and its SHA256 sidecar attached\n - Publishes `@plannotator/opencode` and `@plannotator/pi-extension` to npm with provenance\n\n **SBOM scope:** the public document is a release-wide Syft inventory of the monorepo's locked build inputs and dependencies. It is deliberately not described as exact binary runtime contents. Coverage testing found that Bun standalone executables hide bundled JavaScript dependency metadata from Syft. The OpenCode tarball is similarly opaque; the Pi tarball exposes only a partial view through nested package-lock files. The scope and limitations are also embedded in the CycloneDX metadata.\n\n **Exceptions:** there is no active production exception file. If a future release baseline needs one, do not add a loose ignore. Add a repository-reviewed OpenVEX document and explicitly wire it through `PLANNOTATOR_RELEASE_VEX`; each statement must match one exact package URL and vulnerability ID and carry `not_affected` status, an OpenVEX justification, impact statement, HTTPS evidence, owner, created date, and expiration date. The policy tests reject expired, malformed, broad, and nonmatching records.\n\n **Note on immutable releases:** The repo has GitHub Immutable Releases enabled, so once the `v*` tag is pushed and the release is created, the tag→commit and tag→asset bindings are permanent. You cannot delete and re-create a tag to \"fix\" a bad release — you must ship a new version. Release notes remain editable (see step 5), but everything else is locked.\n\n4. **Monitor the pipeline:**\n Watch the release workflow run until it completes:\n ```bash\n gh run list --workflow=release.yml --limit=1\n gh run view --log\n ```\n Verify:\n - All jobs pass, including `release-security`, `attest`, `release`, and `npm-publish`\n - `release-security-evidence` records the Syft/Grype versions, active database schema/build/checksum/update status, all Grype matches, and an `ACCEPT` policy decision\n - The GitHub Release was created with all binary artifacts, SHA256 sidecars, the versioned `plannotator-X.Y.Z-release-sbom.cdx.json`, and its `.sha256` sidecar\n - npm packages published successfully (check with `npm view @plannotator/opencode version` and `npm view @plannotator/pi-extension version`)\n\n A pull request proves generation, schema/sentinel validation, database policy, Grype evaluation, least-privilege job wiring, and all report artifacts. GitHub OIDC issuance, publication to the artifact-attestation service, and final release-asset publication only run for a real eligible `v*` tag. For the first release after this control lands, complete this bounded tag-only verification before calling the rollout complete:\n\n Before tagging that first release, update the canonical Mintlify page at `https://docs.plannotator.ai/open-source/start/installation#pin-or-verify-a-release` with the SBOM scope/limitations, Grype policy, download/checksum commands, and both predicate-verification commands from the README. The legacy Astro files under `apps/marketing/src/content/docs/` are redirect-only/deprecated copies and are not the public documentation source. Confirm the live Mintlify page contains the material; do not let its publication lag the shipped control.\n\n ```bash\n tag=vX.Y.Z\n version=\"${tag#v}\"\n gh release download \"$tag\" --pattern 'plannotator-linux-x64*' --pattern \"plannotator-${version}-release-sbom.cdx.json*\" --dir /tmp/plannotator-release-verify\n (cd /tmp/plannotator-release-verify && sha256sum --check plannotator-linux-x64.sha256)\n (cd /tmp/plannotator-release-verify && sha256sum --check \"plannotator-${version}-release-sbom.cdx.json.sha256\")\n\n gh attestation verify /tmp/plannotator-release-verify/plannotator-linux-x64 \\\n --repo backnotprop/plannotator \\\n --source-ref \"refs/tags/$tag\" \\\n --signer-workflow backnotprop/plannotator/.github/workflows/release.yml \\\n --predicate-type https://slsa.dev/provenance/v1\n\n gh attestation verify /tmp/plannotator-release-verify/plannotator-linux-x64 \\\n --repo backnotprop/plannotator \\\n --source-ref \"refs/tags/$tag\" \\\n --signer-workflow backnotprop/plannotator/.github/workflows/release.yml \\\n --predicate-type https://cyclonedx.org/bom\n ```\n\n Also extract the attested CycloneDX predicate with `gh attestation verify --format json --jq '.[0].verificationResult.statement.predicate'`, canonicalize both it and the downloaded release SBOM with `jq -S`, and `cmp` them. Verify one npm tarball subject the same way if you download the exact published tarball. Record any tag-only discrepancy as a release blocker and ship a new version rather than mutating an immutable release.\n\n If anything fails, investigate the logs and report to the user before retrying.\n\n5. **Replace the release notes:**\n Once the release is live and verified, replace the auto-generated notes body with the drafted release notes:\n ```bash\n gh release edit vX.Y.Z --notes-file RELEASE_NOTES_v.md\n ```\n\n---\n\n## Checklist\n\nBefore tagging, verify:\n- [ ] All 7 version files bumped consistently\n- [ ] Release notes drafted and reviewed\n- [ ] `bun run build:review` succeeded\n- [ ] `bun run build:hook` succeeded\n- [ ] `bun run build:opencode` succeeded\n- [ ] `bun run build:pi` succeeded (or pi-specific build step)\n- [ ] Version bump committed\n- [ ] Pi parity gate passed (imports, vendor.sh, dry-run pack)\n- [ ] No stale build artifacts (clean builds, no cache issues — run `bun install` first if dependencies changed)\n- [ ] The PR-safe `release-security` job generated a schema-valid, sentinel-complete SBOM and accepted the Grype policy with a fresh database\n- [ ] No scanner binary, database, generated SBOM/report, credential, or `DO_NOT_COMMIT` content is staged\n- [ ] For the first SBOM-enabled release, the canonical Mintlify install/verification page contains the README's SBOM scope, policy, checksum, SLSA, and CycloneDX commands (do not edit the deprecated Astro docs instead)\n\nAfter tagging, verify:\n- [ ] Release workflow completed with `release-security`, `attest`, `release`, and `npm-publish` green\n- [ ] GitHub Release created with all binaries, sidecars, SBOM, and SBOM sidecar\n- [ ] One native binary passes both the explicit SLSA and CycloneDX predicate checks pinned to the tag and signer workflow\n- [ ] Downloaded SBOM checksum passes and canonical JSON matches the attested predicate\n- [ ] `release-security-evidence` shows a fresh/active database and an accepted policy decision\n- [ ] npm packages published at correct version\n- [ ] npm trusted-publishing provenance remains visible for both packages\n- [ ] Release notes replaced via `gh release edit`\n","frontmatter":{"name":"release-plannotator","description":"Prepare and execute a Plannotator release — draft release notes with full contributor credit, bump versions across all package files, build in dependency order, and kick off the tag-driven release pipeline. Use this skill whenever the user mentions preparing a release, bumping versions, writing release notes, tagging a release, or publishing. Also trigger when the user says things like \"let's ship\", \"prep a release\", \"what's changed since last release\", or \"time to cut a new version\"."},"isInternal":false,"tokens":4311,"sizeBytes":18305},{"name":"SKILL.md","path":".agents/skills/review-renovate/SKILL.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.agents/skills/review-renovate/SKILL.md","title":"review-renovate","category":"anthropic-skill","format":"markdown","content":"---\nname: review-renovate\ndescription: Review Renovate bot PRs that update GitHub Actions dependencies. Verifies supply chain integrity by checking pinned commit SHAs against upstream tagged releases, reviews changelogs for breaking changes, and confirms compatibility with existing workflow configurations. Use when a Renovate PR updates GitHub Actions in .github/workflows/.\n---\n\n# Review Renovate GitHub Actions PRs\n\nYou are reviewing a Renovate bot PR that updates GitHub Actions dependencies. Your job is to verify supply chain integrity and ensure the upgrades won't break CI/CD workflows.\n\n## Inputs\n\nYou will be given a PR number or URL. Use `gh` CLI to fetch PR details and diff.\n\n## Steps\n\n### 1. Fetch PR metadata and diff\n\n```\ngh pr view --json title,body,files,commits,author,headRefName\ngh pr diff \n```\n\nConfirm the PR author is `app/renovate`. If not, flag this immediately — it may not be an automated dependency update.\n\n### 2. Identify all action version changes\n\nFrom the diff, extract each changed action:\n- Full action name (e.g., `oven-sh/setup-bun`)\n- Old version tag and pinned SHA\n- New version tag and pinned SHA\n- Update type (patch, minor, major)\n\n### 3. Verify pinned SHAs against upstream tags\n\nFor every action being updated, verify **both old and new** SHAs match the claimed version tags:\n\n```\ngh api repos/{owner}/{repo}/git/ref/tags/{version} --jq '.object.sha'\n```\n\nCompare each result against the SHA in the workflow file. If any SHA does not match, **stop and report a supply chain integrity failure**. Do not approve the PR.\n\n### 4. Review changelogs for breaking changes\n\nFrom the PR body (Renovate includes release notes), check each updated action for:\n- Removed inputs or outputs that the workflows currently use\n- Changed default behavior for inputs the workflows rely on\n- New required inputs\n- Major version bumps (these almost always have breaking changes)\n\n### 5. Check workflow compatibility\n\nRead the affected workflow files and verify:\n- No removed or renamed inputs are being used\n- No changed defaults affect current behavior\n- The action's runtime requirements are still met (e.g., Node.js version compatibility)\n\n### 6. Report findings\n\nPresent a summary table:\n\n| Action | Old | New | Type | SHA verified |\n|--------|-----|-----|------|-------------|\n| ... | ... | ... | patch/minor/major | yes/NO |\n\nThen state:\n- Whether all SHAs are verified\n- Whether any breaking changes were found\n- Whether the workflows remain compatible\n- A clear **safe to merge** or **do not merge** recommendation\n","frontmatter":{"name":"review-renovate","description":"Review Renovate bot PRs that update GitHub Actions dependencies. Verifies supply chain integrity by checking pinned commit SHAs against upstream tagged releases, reviews changelogs for breaking changes, and confirms compatibility with existing workflow configurations. Use when a Renovate PR updates GitHub Actions in .github/workflows/."},"isInternal":false,"tokens":582,"sizeBytes":2559},{"name":"SKILL.md","path":".agents/skills/update-deps/SKILL.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.agents/skills/update-deps/SKILL.md","title":"update-deps","category":"anthropic-skill","format":"markdown","content":"---\nname: update-deps\ndescription: Audit and update npm/Bun dependencies with supply chain integrity checks — verifies maintainers, publish age, tarball diffs, and provenance before bumping. Defers risky packages to ~/.supply-chain/notes/.\ndisable-model-invocation: true\n---\n\n# Update Dependencies\n\nAudit outdated packages, verify supply chain integrity, bump what's safe, defer what needs review, and log everything.\n\nThis process has three phases: discovery, integrity audit, and execution. The integrity audit is the most important — every package gets checked before it touches the lockfile.\n\n## Phase 1: Discovery\n\nRun `bun outdated` to get the full list of packages with available updates.\n\n```bash\nbun outdated\n```\n\nParse the output into a structured list. For each package, note:\n- Package name\n- Current version\n- Available update version\n- Whether it's age-gated (indicated by `*` in the output — the footnote \"The * indicates that version isn't true latest due to minimum release age\" confirms this)\n- Whether it's a runtime dep, dev dep, or peer dep\n\nAlso check whether any packages are blocked entirely by the age gate (like `@pierre/diffs` was when its minimum semver range couldn't resolve). Flag these separately — they may need `minimumReleaseAgeExcludes` in `bunfig.toml`.\n\n## Phase 2: Integrity Audit\n\nThis is the core of the process. Spawn one **Sonnet sub-agent per package** to run the integrity check in parallel. Sonnet is used here because these are independent, structured verification tasks that don't need heavier reasoning.\n\nEach sub-agent receives the package name, current version, and target version, and performs the following checks:\n\n### Sub-agent prompt template\n\nFor each outdated package, spawn a Sonnet agent with this task:\n\n```\nYou are auditing the npm package \"{package}\" for a version bump from {current} to {target}.\n\nRun these checks and report back with a JSON object:\n\n1. **Maintainer verification**: Check if maintainers changed between versions.\n npm view {package}@{current} maintainers --json\n npm view {package}@{target} maintainers --json\n Compare the two lists. Flag any additions or removals.\n\n2. **Publish date and age**: Get the publish timestamp.\n npm view {package} time --json\n Extract the date for version {target}. Calculate days since publication.\n Flag if younger than 7 days.\n\n3. **Provenance**: Check if the package has registry signatures or attestations.\n npm audit signatures (if not already run this session)\n Note whether the package has provenance attestations.\n\n4. **Tarball diff**: Show what actually changed in the published package.\n npm diff --diff={package}@{current} --diff={package}@{target}\n Summarize the changes:\n - How many files changed\n - Are changes limited to version bumps, deps, and rebuilt dist? Or are there meaningful source changes?\n - Any new runtime dependencies added?\n - Any suspicious patterns (obfuscated code, eval(), network calls in unexpected places)\n\n5. **Release notes**: Try to find what changed.\n Check the package's repository for release notes or changelog:\n npm view {package}@{target} repository.url\n gh release view v{target} --repo (try with and without v prefix)\n Summarize the changelog if found.\n\nReport your findings as JSON:\n\n{{\n \"package\": \"{package}\",\n \"from\": \"{current}\",\n \"to\": \"{target}\",\n \"age_days\": ,\n \"maintainers_changed\": ,\n \"maintainers_added\": [],\n \"maintainers_removed\": [],\n \"provenance\": ,\n \"new_runtime_deps\": [],\n \"files_changed\": ,\n \"has_source_changes\": ,\n \"changelog_summary\": \"\",\n \"suspicious_patterns\": [],\n \"verdict\": \"safe\" | \"review\" | \"defer\",\n \"verdict_reason\": \"\"\n}}\n\nVerdict guidelines:\n- \"safe\": Same maintainers, no new runtime deps, changes match what changelog describes, no suspicious patterns\n- \"review\": Minor concerns (e.g., new maintainer who is clearly from the same org, small new dep from known publisher)\n- \"defer\": Maintainer changes from unknown accounts, new runtime deps with unclear purpose, suspicious code patterns, substantive API changes that need integration testing\n```\n\n### Collecting results\n\nAs sub-agents complete, collect their JSON reports. If a sub-agent fails or times out, mark that package as \"defer\" with reason \"audit failed\".\n\n### Tier classification\n\nAfter collecting all results, classify packages into tiers. This helps the user understand the risk profile at a glance:\n\n| Tier | Description | Typical action |\n|------|-------------|----------------|\n| **Runtime, high surface** | Libraries your code calls directly (parsers, diff engines, UI libs) | Check provenance, review diff, run tests |\n| **SDK/API deps** | Third-party service SDKs (agent SDKs, platform integrations) | Read changelog for API changes, test integration |\n| **Dev-only** | Type definitions, build tools, test frameworks | Update freely — these don't ship |\n| **Build toolchain** | Bun itself, compilers, bundlers | Most caution — breakage affects all outputs |\n\n## Phase 3: Execution\n\n### Bump safe packages\n\nFor all packages with verdict \"safe\":\n\n```bash\nbun update pkg1@version1 pkg2@version2 ...\n```\n\nIf the update fails due to age gate conflicts (a package's minimum semver can't resolve), add it to `minimumReleaseAgeExcludes` in `bunfig.toml` and document why.\n\n### Log to supply chain notes\n\nWrite the full audit results to `~/.supply-chain/notes/.json`:\n\n```json\n{\n \"date\": \"YYYY-MM-DD\",\n \"project\": \"plannotator\",\n \"bumped\": [\n {\n \"package\": \"...\",\n \"from\": \"...\",\n \"to\": \"...\",\n \"age_days\": 0,\n \"maintainers_changed\": false,\n \"provenance\": false,\n \"notes\": \"...\"\n }\n ],\n \"deferred\": [\n {\n \"package\": \"...\",\n \"current\": \"...\",\n \"available\": \"...\",\n \"age_days\": 0,\n \"maintainers_changed\": false,\n \"reason\": \"...\",\n \"review_by\": \"YYYY-MM-DD\"\n }\n ],\n \"excluded_from_age_gate\": [\n {\n \"package\": \"...\",\n \"reason\": \"...\"\n }\n ]\n}\n```\n\nSet `review_by` to 7 days from today for deferred packages.\n\n### Check previously deferred packages\n\nRead all files in `~/.supply-chain/notes/` and collect any deferred packages from previous audits that are still at the same version in the current lockfile. These are packages that were deferred before and still haven't been updated.\n\nTo check: for each previously deferred entry, see if the current installed version matches the `current` field from the deferral note. If it does, the package is still deferred.\n\n## Phase 4: Recap\n\nPresent a clear summary to the user:\n\n### Updated\nList each bumped package with version change and one-line reason it was safe.\n\n### Deferred\nList each deferred package with version change and reason for deferral.\n\n### Still Deferred (from previous audits)\nList any packages that were deferred in previous audit sessions and still haven't been bumped. Include the original deferral date and reason. This is the \"you've been putting this off\" section — it keeps deferred packages from being forgotten.\n\nIf the still-deferred list is empty, say so — that's a good sign.\n\n### Age Gate Exclusions\nIf any packages were added to `minimumReleaseAgeExcludes`, note them and why.\n","frontmatter":{"name":"update-deps","description":"Audit and update npm/Bun dependencies with supply chain integrity checks — verifies maintainers, publish age, tarball diffs, and provenance before bumping. Defers risky packages to ~/.supply-chain/notes/.","disable-model-invocation":true,"disableModelInvocation":true},"isInternal":false,"tokens":1682,"sizeBytes":7288},{"name":"plannotator.json","path":"apps/kiro-cli/agents/plannotator.json","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/kiro-cli/agents/plannotator.json","title":"Agents Skill","category":"anthropic-skill","format":"json","content":"# Agents Skill\n\nPath: `apps/kiro-cli/agents/plannotator.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/kiro-cli/agents/plannotator.json)","tokens":300,"sizeBytes":193},{"name":"SKILL.md","path":"apps/kiro-cli/skills/plannotator-annotate/SKILL.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/kiro-cli/skills/plannotator-annotate/SKILL.md","title":"plannotator-annotate","category":"anthropic-skill","format":"markdown","content":"# plannotator-annotate\n\nPath: `apps/kiro-cli/skills/plannotator-annotate/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/kiro-cli/skills/plannotator-annotate/SKILL.md)","tokens":300,"sizeBytes":227},{"name":"SKILL.md","path":"apps/kiro-cli/skills/plannotator-review/SKILL.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/kiro-cli/skills/plannotator-review/SKILL.md","title":"plannotator-review","category":"anthropic-skill","format":"markdown","content":"# plannotator-review\n\nPath: `apps/kiro-cli/skills/plannotator-review/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/kiro-cli/skills/plannotator-review/SKILL.md)","tokens":300,"sizeBytes":221},{"name":"SKILL.md","path":"apps/skills/claude/plannotator-annotate/SKILL.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/claude/plannotator-annotate/SKILL.md","title":"plannotator-annotate","category":"anthropic-skill","format":"markdown","content":"# plannotator-annotate\n\nPath: `apps/skills/claude/plannotator-annotate/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/claude/plannotator-annotate/SKILL.md)","tokens":300,"sizeBytes":223},{"name":"SKILL.md","path":"apps/skills/claude/plannotator-last/SKILL.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/claude/plannotator-last/SKILL.md","title":"plannotator-last","category":"anthropic-skill","format":"markdown","content":"---\nname: plannotator-last\ndescription: Open Plannotator on the latest rendered assistant message and use the returned annotations to revise that message or continue.\nallowed-tools: Bash(plannotator:*)\ndisable-model-invocation: true\n---\n\n# Plannotator Last\n\n## Message annotations\n\n!`plannotator annotate-last $ARGUMENTS`\n\n## Your task\n\nThe output above will be one of:\n\n1. The exact text `The user approved.`, an \"Approved with Notes\" message, OR a JSON object with `\"decision\": \"approved\"`. The user approved your last message. If it is the Approved with Notes message, or that object also carries a `\"feedback\"` field, the user approved *with notes*: read them and carry them into subsequent work — they are non-blocking guidance, not a request to revise the message. Otherwise acknowledge with a single sentence (\"Approved.\") and stop. Either way, do not begin any work.\n2. Empty, OR a JSON object with `\"decision\": \"dismissed\"`. The user closed the session without requesting changes. Acknowledge with a single sentence (\"Annotation session closed.\") and stop. Do not begin any work.\n3. Plaintext annotation feedback, OR a JSON object with `\"decision\": \"annotated\"` and a `\"feedback\"` field. Address the feedback. The user has reviewed your last message and provided specific annotations and comments.\n","frontmatter":{"name":"plannotator-last","description":"Open Plannotator on the latest rendered assistant message and use the returned annotations to revise that message or continue.","allowed-tools":"Bash(plannotator:*)","disable-model-invocation":true,"allowedTools":["Bash(plannotator:*)"],"disableModelInvocation":true},"allowedTools":["Bash(plannotator:*)"],"isInternal":false,"tokens":282,"sizeBytes":1309},{"name":"SKILL.md","path":"apps/skills/claude/plannotator-review/SKILL.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/claude/plannotator-review/SKILL.md","title":"plannotator-review","category":"anthropic-skill","format":"markdown","content":"---\nname: plannotator-review\ndescription: Open Plannotator's browser-based code review UI for the current worktree, another directory, or a pull request URL, then act on the feedback that comes back.\nallowed-tools: Bash(plannotator:*)\ndisable-model-invocation: true\n---\n\n# Plannotator Review\n\nArguments pass through to `plannotator review`: one directory or PR/MR URL, `--git` / `--gitbutler`, and the session-only open-state flags `--base ` / `--diff-type ` (git-only; for a stacked branch, `--base ` reviews just that layer).\n\nFor another repository or worktree, pass its path relative to this session or an absolute path, e.g. `/plannotator-review ../feature-worktree`. Quote paths containing spaces. Supply a target, not prose; feedback names the directory where changes belong.\n\n## Code review feedback\n\n!`plannotator review $ARGUMENTS`\n\n## Your task\n\nIf the review above contains feedback or annotations, address them in the same conversation. If no changes were requested (an approval/LGTM-style result), acknowledge that review passed and continue.\n\nIf the review was moved to the background, wait for it to finish. If Claude Code stopped it at its background time limit before the user decided, tell the user, and only when they ask, run `plannotator review $ARGUMENTS` again with `run_in_background` and `timeout: 7200000`: their annotations are restored from the saved draft.\n","frontmatter":{"name":"plannotator-review","description":"Open Plannotator's browser-based code review UI for the current worktree, another directory, or a pull request URL, then act on the feedback that comes back.","allowed-tools":"Bash(plannotator:*)","disable-model-invocation":true,"allowedTools":["Bash(plannotator:*)"],"disableModelInvocation":true},"allowedTools":["Bash(plannotator:*)"],"isInternal":false,"tokens":325,"sizeBytes":1422},{"name":"openai.yaml","path":"apps/skills/core/plannotator-annotate/agents/openai.yaml","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/core/plannotator-annotate/agents/openai.yaml","title":"Agents Skill","category":"anthropic-skill","format":"yaml","content":"# Agents Skill\n\nPath: `apps/skills/core/plannotator-annotate/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/core/plannotator-annotate/agents/openai.yaml)","tokens":300,"sizeBytes":231},{"name":"SKILL.md","path":"apps/skills/core/plannotator-annotate/SKILL.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/core/plannotator-annotate/SKILL.md","title":"plannotator-annotate","category":"anthropic-skill","format":"markdown","content":"---\nname: plannotator-annotate\ndescription: Open Plannotator's annotation UI for a markdown file, plain-text config file (.yaml, .json, .toml, .ini, .csv, .log, …), HTML file, URL, or folder and then respond to the returned annotations.\ndisable-model-invocation: true\n---\n\n# Plannotator Annotate\n\nUse this skill when the user wants to annotate a document in Plannotator instead of reviewing it inline in chat.\n\nRun for ordinary annotation/feedback:\n\n```bash\nplannotator annotate \n```\n\nRun when the user asks to review, approve, accept, or gate a generated plan/spec/document:\n\n```bash\nplannotator annotate --gate --json\n```\n\nPlain `annotate` has no **Approve** button; it only supports feedback or closing the session. Never promise an approval action unless `--gate` is present. `--json` only changes the output format and does not enable approval by itself.\n\nBehavior:\n\n1. Launch the command with Bash.\n2. Wait for the browser review to finish.\n3. If annotations are returned, address them directly.\n4. If the session closes without feedback, say so briefly and continue.\n5. In a `--gate` session, an approval may still carry notes — a `\"decision\": \"approved\"` result with a\n `\"feedback\"` field (without `--json`, an \"Approved with Notes\" message). Read those notes and carry them into subsequent work, but\n do not revise the document over them: they are guidance, not a change request.\n6. If the command reports that the arguments could not be resolved to a file,\n URL, or folder, work out which target the user means and re-run the command\n yourself with that concrete path or URL.\n\nDo not ask the user to paste a shell command into the chat. Run the command yourself.\n","frontmatter":{"name":"plannotator-annotate","description":"Open Plannotator's annotation UI for a markdown file, plain-text config file (.yaml, .json, .toml, .ini, .csv, .log, …), HTML file, URL, or folder and then respond to the returned annotations.","disable-model-invocation":true,"disableModelInvocation":true},"isInternal":false,"tokens":400,"sizeBytes":1712},{"name":"openai.yaml","path":"apps/skills/core/plannotator-last/agents/openai.yaml","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/core/plannotator-last/agents/openai.yaml","title":"Agents Skill","category":"anthropic-skill","format":"yaml","content":"# Agents Skill\n\nPath: `apps/skills/core/plannotator-last/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/core/plannotator-last/agents/openai.yaml)","tokens":300,"sizeBytes":223},{"name":"SKILL.md","path":"apps/skills/core/plannotator-last/SKILL.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/core/plannotator-last/SKILL.md","title":"plannotator-last","category":"anthropic-skill","format":"markdown","content":"---\nname: plannotator-last\ndescription: Open Plannotator on the latest rendered assistant message and use the returned annotations to revise that message or continue.\ndisable-model-invocation: true\n---\n\n# Plannotator Last\n\nUse this skill when the user wants to annotate the latest assistant response in Plannotator.\n\nDo not send a commentary/status message before running the command. The command\ntargets the latest rendered assistant response, so a preamble can mistakenly become the\nthing being annotated.\n\nRun:\n\n```bash\nplannotator last\n```\n\nBehavior:\n\n1. Launch the command with Bash.\n2. Wait for the annotation session to finish.\n3. If feedback is returned, incorporate it into the follow-up response.\n4. If the session closes without feedback, mention that briefly and continue.\n5. An approval may still carry notes — a `\"decision\": \"approved\"` result with a\n `\"feedback\"` field. Read those notes and carry them into subsequent work, but\n do not redo the message over them: they are guidance, not a change request.\n\nRun the command yourself rather than telling the user to invoke shell syntax manually.\n","frontmatter":{"name":"plannotator-last","description":"Open Plannotator on the latest rendered assistant message and use the returned annotations to revise that message or continue.","disable-model-invocation":true,"disableModelInvocation":true},"isInternal":false,"tokens":231,"sizeBytes":1115},{"name":"openai.yaml","path":"apps/skills/core/plannotator-review/agents/openai.yaml","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/core/plannotator-review/agents/openai.yaml","title":"Agents Skill","category":"anthropic-skill","format":"yaml","content":"# Agents Skill\n\nPath: `apps/skills/core/plannotator-review/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/core/plannotator-review/agents/openai.yaml)","tokens":300,"sizeBytes":227},{"name":"SKILL.md","path":"apps/skills/core/plannotator-review/SKILL.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/core/plannotator-review/SKILL.md","title":"plannotator-review","category":"anthropic-skill","format":"markdown","content":"---\nname: plannotator-review\ndescription: Open Plannotator's browser-based code review UI for the current worktree, another directory, or a pull request URL, then act on the feedback that comes back.\ndisable-model-invocation: true\n---\n\n# Plannotator Review\n\nUse this skill when the user wants to review current code changes in Plannotator instead of reading a diff inline.\n\nRun:\n\n```bash\nplannotator review [--base ] [--diff-type ] [directory-or-pr-url]\n```\n\nReviewing one layer of a stacked branch? Pass `--base ` so the review shows only what this layer adds, instead of everything since `main`. Both flags are session-only (the reviewer can change either in the UI; nothing is persisted) and git-only.\n\nTo review another repository or worktree, pass its directory (relative to the current session or absolute), e.g. `plannotator review ../feature-worktree`. Quote paths containing spaces. Feedback names the selected directory; apply changes there.\n\nBehavior:\n\n1. Launch the command with Bash.\n2. Wait for it to finish.\n3. If it returns feedback or annotations, address them in the same conversation.\n4. If it returns an approval/LGTM-style message, acknowledge that review passed and continue.\n\nDo not ask the user to copy shell commands into chat. Run the command yourself.\n","frontmatter":{"name":"plannotator-review","description":"Open Plannotator's browser-based code review UI for the current worktree, another directory, or a pull request URL, then act on the feedback that comes back.","disable-model-invocation":true,"disableModelInvocation":true},"isInternal":false,"tokens":288,"sizeBytes":1326},{"name":"claude-code-fallback.md","path":"apps/skills/extra/plannotator-compound/references/claude-code-fallback.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-compound/references/claude-code-fallback.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# References Skill\n\nPath: `apps/skills/extra/plannotator-compound/references/claude-code-fallback.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-compound/references/claude-code-fallback.md)","tokens":300,"sizeBytes":269},{"name":"SKILL.md","path":"apps/skills/extra/plannotator-compound/SKILL.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-compound/SKILL.md","title":"plannotator-compound","category":"anthropic-skill","format":"markdown","content":"---\nname: plannotator-compound\ndisable-model-invocation: true\ndescription: >\n Analyze a user's Plannotator plan archive to extract denial patterns, feedback\n taxonomy, evolution over time, and actionable prompt improvements — then produce\n a polished HTML dashboard report. Falls back to Claude Code ExitPlanMode denial\n reasons when Plannotator data is unavailable.\n---\n\n# Compound Planning Analysis\n\nYou are conducting a comprehensive research analysis of a user's Plannotator plan\narchive. The goal: extract patterns from their denied plans, reduce\nthem into actionable insights, and produce an elegant HTML dashboard report.\n\nThis is a multi-phase process. Each phase must complete fully before the next begins.\nResearch integrity is paramount — every file must be read, no skipping.\n\n## Source Selection\n\nBefore starting the analysis, determine which data source is available.\n\n1. **Plannotator mode (first-class)** — Determine the Plannotator data directory:\n use `$PLANNOTATOR_DATA_DIR` if set, otherwise `~/.plannotator`. Check the\n `plans/` subdirectory there. If it exists and contains `*-denied.md` files,\n use this mode. The entire workflow below is written for Plannotator data.\n\n2. **Claude Code fallback mode** — If the Plannotator archive is absent or\n contains no denied plans, check `~/.claude/projects/`. If present, read\n [references/claude-code-fallback.md](references/claude-code-fallback.md)\n before continuing. That reference explains how to use the bundled parser at\n [scripts/extract_exit_plan_mode_outcomes.py](scripts/extract_exit_plan_mode_outcomes.py)\n to extract denial reasons from Claude Code JSONL transcripts. Every phase\n below has a short note explaining what changes in fallback mode — the\n reference file has the details.\n\n3. **Neither available** — Ask the user for their Plannotator plans directory or\n Claude Code projects directory. Do not guess.\n\n## Phase 0: Locate Plans & Check for Previous Reports\n\nUse the mode chosen in Source Selection above.\n\n**Plannotator mode:** Verify the plans directory contains `*-denied.md` files. If\nnone exist, fall back to Claude Code mode before stopping.\n\n**Claude Code fallback mode:** Run the bundled parser per the fallback reference to\nbuild the denial-reason dataset. Create `/tmp/compound-planning/` if needed.\n\nIn either mode, proceed to Previous Report Detection below.\n\n### Previous Report Detection\n\nAfter locating the plans directory, check for existing reports:\n\n```\nls ${PLANNOTATOR_DATA_DIR:-~/.plannotator}/plans/compound-planning-report*.html\n```\n\nReports follow a versioned naming scheme:\n- First report: `compound-planning-report.html`\n- Subsequent reports: `compound-planning-report-v2.html`, `compound-planning-report-v3.html`, etc.\n\nIf one or more reports exist, determine the **latest** one (highest version number).\nGet its filesystem modification date using `stat` (macOS: `stat -f %Sm -t %Y-%m-%d`,\nLinux: `stat -c %y | cut -d' ' -f1`). This is the **cutoff date**.\n\nPresent the user with a choice:\n\n> \"I found a previous report (`compound-planning-report-v{N}.html`) last updated\n> on {CUTOFF_DATE}. I can either:\n>\n> 1. **Incremental** — Only analyze files dated after {CUTOFF_DATE}, saving tokens\n> and building on previous findings\n> 2. **Full** — Re-analyze the entire archive from scratch\n>\n> Which would you prefer?\"\n\nWait for the user's response before proceeding.\n\n**If incremental:** Filter all subsequent phases to only process files with dates\nafter the cutoff date. The new report version will note in its header narrative that\nit covers the period from {CUTOFF_DATE} to present, and reference the previous\nreport for earlier findings. The inventory (Phase 1) should still count ALL files\nfor overall stats, but clearly separate \"new since last report\" counts.\n\n**If full:** Proceed normally with all files, but still use the next version number\nfor the output filename.\n\n**If no previous report exists:** Proceed normally. The output filename will be\n`compound-planning-report.html` (no version suffix for the first report).\n\n## Phase 1: Inventory\n\nCount and report the dataset. **Always count ALL files** for overall stats,\nregardless of whether this is an incremental or full run:\n\n```\n- *-approved.md files (count)\n- *-denied.md files (count)\n- Date range (earliest to latest date found in filenames)\n- Total days spanned\n- Revision rate: denied / (approved + denied) — this is the \"X% of plans\n revised before coding\" stat used in dashboard section 1\n```\n\n**Note:** Ignore `*.annotations.md` files entirely. Denied files already contain\nthe full plan text plus all reviewer feedback appended after a `---` separator.\nAnnotation files are redundant subsets of this content — reading both would\ndouble-count feedback.\n\n**If incremental mode:** After the total counts, separately report the counts for\nfiles dated after the cutoff date only:\n\n```\nNew since {CUTOFF_DATE}:\n- *-denied.md files: X (of Y total)\n- New date range: {CUTOFF_DATE} to {LATEST_DATE}\n- New days spanned: N\n```\n\nIf fewer than 3 new denied files exist since the cutoff, warn the user:\n> \"Only {N} new denied plans since the last report. The incremental analysis may\n> be thin. Would you like to proceed or switch to a full analysis?\"\n\nAlso run `wc -l` across all `*-approved.md` files to get average lines per\napproved plan. This tells the user whether their plans are staying lightweight\nor bloating over time. You do not need to read approved plan contents — just\ntheir line counts. If possible, break this down by time period (e.g., monthly)\nto show whether plan size changed.\n\nDates appear in filenames in YYYY-MM-DD format, sometimes as a prefix\n(2026-01-07-name-approved.md) and sometimes embedded (name-2026-03-15-approved.md).\nExtract dates from all filenames.\n\nTell the user what you found and that you're beginning the extraction.\n\n**Claude Code fallback mode:** The Plannotator inventory fields above do not apply.\nFollow the inventory instructions in\n[references/claude-code-fallback.md](references/claude-code-fallback.md) instead —\nreport the denial-reason dataset assembled by the parser.\n\n## Phase 2: Map — Parallel Extraction\n\nThis is the most time-intensive phase. You must read EVERY `*-denied.md` file\n**in scope**. Do not skip files. Do not summarize early.\n\n**In scope** means: all denied files if running a full analysis, or only denied\nfiles dated after the cutoff date if running incrementally. In incremental mode,\nonly process files whose embedded YYYY-MM-DD date is strictly after the cutoff.\n\n**Claude Code fallback mode:** The parser output is the clean source dataset. Read\nthe fallback reference for the extraction prompt and batching strategy specific to\nJSON part files. Do not go back to raw `.jsonl` logs unless the parser fails or the\nuser asks for audit-level verification.\n\n**Important:** Only read `*-denied.md` files. Do NOT read approved plans,\nannotation files, or diff files. Each denied file contains the full plan text\nfollowed by a `---` separator and the reviewer's feedback — everything needed\nfor analysis is in one file.\n\n### Batching Strategy\n\nAll extraction agents should use `model: \"haiku\"` — they're doing straightforward\nfile reading and structured extraction, not reasoning. Haiku is faster and cheaper\nfor this work.\n\nThe approach depends on dataset size:\n\n**Tiny datasets (≤ 10 total files):** Read all files directly in the main agent —\nno need for sub-agents. Just read them sequentially and proceed to Phase 3.\n\n**Small datasets (11-30 files):** Launch 2-3 parallel Haiku agents, splitting\nfiles roughly evenly.\n\n**Medium datasets (31-80 files):** Launch 4-6 parallel Haiku agents (~10-15 files\neach). Split by file type and/or time period.\n\n**Large datasets (80+ files):** Launch as many parallel Haiku agents as needed to\nkeep each batch around 10-15 files. Split by the natural time boundaries in the\ndata (months, quarters, or whatever groupings produce balanced batches). If one\ntime period dominates (e.g., the most recent month has 3x the files), split that\nperiod into multiple batches.\n\nLaunch all extraction agents in parallel using the Agent tool with\n`run_in_background: true` and `model: \"haiku\"`.\n\n### Output Files\n\nEach extraction agent must write its results to a clean output file rather than\nrelying on the agent task output (which contains interleaved JSONL framework\nlogs that are difficult to parse). Instruct each agent to write to:\n\n```\n/tmp/compound-planning/extraction-{batch-name}.md\n```\n\nCreate the `/tmp/compound-planning/` directory before launching agents. The\nreduce agent in Phase 3 will read these clean files directly.\n\n### Extraction Prompt\n\nEach agent receives this instruction (adapt the time period, file list, and\noutput path):\n\n```\nYou are extracting structured data from denied plan files for a pattern analysis.\n\nDirectory: [PLANS DIRECTORY]\nFiles to read: [LIST OF SPECIFIC *-denied.md FILES]\nOutput: Write your complete results to [OUTPUT FILE PATH]\n\nEach denied file contains two parts separated by a --- line:\n1. The plan text (above the ---)\n2. The reviewer's feedback and annotations (below the ---)\n\nRead EVERY file in your list. For EACH file, extract:\n- The plan name/topic (from the plan text above the ---)\n- The denial reason or feedback given (from below the --- — capture the actual\n words used)\n- What was specifically asked to change\n- The type of feedback (let the content determine the category — don't force-fit\n into predefined types. Common types include things like: scope concerns,\n approach disagreements, missing information, process requirements, quality\n concerns, UX/design issues, naming disputes, clarification requests,\n testing/procedural denials — but the user's actual patterns may differ)\n- Any specific phrases or recurring language from the reviewer\n- Individual annotations if present (numbered feedback items with quoted text\n and reviewer comments)\n- The date (extracted from the filename)\n\nDo NOT skip any files. One entry per file.\n\nFormat each entry as:\n**[filename]**\n- Date: ...\n- Topic: ...\n- Denial reason: ...\n- Feedback type: ...\n- Specific asks: ...\n- Notable phrases: ...\n- Annotations: [count, with brief summary of each]\n---\n\nAfter processing all files, write the complete results to [OUTPUT FILE PATH].\nState the total file count at the end of the file.\n```\n\n### While Agents Run\n\nTrack completion. As each agent finishes, note the count of files it processed.\nVerify the total matches the inventory from Phase 1. If any agent's count is\nshort, flag it and consider re-launching for the missing files.\n\nIf an agent times out (possible with large batches — a batch of 128 files can\ntake 8+ minutes), re-launch it for just the unprocessed files. Check the output\nfile to see how far it got before timing out.\n\n## Phase 3: Reduce — Pattern Analysis\n\nOnce ALL extraction agents have completed (or all files have been read for tiny\ndatasets), proceed with the reduction. Reduction agents should use `model: \"sonnet\"`\n— this phase requires real analytical reasoning, not just file reading.\n\n### Reduction Strategy\n\nThe approach depends on how many extraction files were produced:\n\n**Standard (≤ 20 extraction files):** Launch a single Sonnet agent to read all\nextraction files and produce the full analysis. This covers most datasets.\n\n**Large (21+ extraction files):** Use a two-stage reduce:\n\n1. **Stage 1 — Partial reduces:** Split the extraction files into groups of 4-6.\n Launch parallel Sonnet agents, each reading one group and producing a partial\n analysis with the same sections listed below. Each writes to\n `/tmp/compound-planning/partial-reduce-{N}.md`.\n\n2. **Stage 2 — Final reduce:** A single Sonnet agent reads all partial reduce\n files and synthesizes them into the final comprehensive analysis. This agent\n merges taxonomies, combines counts, deduplicates patterns, and reconciles any\n conflicting categorizations across partials.\n\n**Claude Code fallback mode:** The reduction phase is the same. The only upstream\ndifference is that extraction files were derived from normalized denial-reason JSON\ninstead of Plannotator markdown files.\n\n### Reduction Prompt\n\nGive each reduction agent this prompt (adapt file paths for single vs multi-stage):\n\n```\nYou are a data scientist conducting the reduction phase of a map-reduce analysis\nacross a user's denied plan archive.\n\nRead ALL extraction files at [FILE PATHS]\n\nThese files contain structured extractions from every denied plan file. Each\nextraction includes the plan topic, denial feedback, annotations, and reviewer\nlanguage. Your job: aggregate everything, find patterns, cluster into a taxonomy,\nand produce a comprehensive analysis.\n\nBe exhaustive. Use real counts. Quote real phrases from the data. This is\nresearch — no hand-waving, no fabrication.\n\nWrite your complete results to [OUTPUT FILE PATH].\n\nProduce the following sections:\n[... sections listed below ...]\n```\n\nThe reduction agent's job is to let the data speak. Do not impose a predetermined\nframework — discover what's actually there. The analysis must produce:\n\n### 1. Denial Reason Taxonomy\nCategorize every denial into a finite set of types that emerge from the data. Count\noccurrences. Show percentages. Include real example quotes for each type. Aim for\n8-15 categories — enough to be specific, few enough to be scannable. Let the user's\nactual feedback determine what the categories are.\n\n### 2. Top Feedback Patterns (ranked by frequency)\nThe 5-10 most recurring patterns. For each: what the reviewer consistently asks for,\n3+ example quotes from different files, and whether the pattern changed over time.\n\n### 3. Recurring Phrases\nExact phrases the reviewer uses repeatedly, with counts and what they signal. These\nare the reviewer's vocabulary — their shorthand for what they care about.\n\n### 4. What the Reviewer Values (implicit preferences)\nDerived from patterns — what does this specific person care about most? Quality?\nSpeed? Narrative? Architecture? Process? Simplicity? Rank by evidence strength.\nThis section should feel like a personality profile of the reviewer's standards.\n\n### 5. What Agents Consistently Get Wrong\nThe flip side — what recurring mistakes trigger denials? What should agents stop\ndoing for this reviewer?\n\n### 6. Structural Requests\nWhat plan structure does the reviewer consistently demand? Required sections,\nordering, format preferences, level of detail expected.\n\n### 7. Evolution Over Time\nHow feedback patterns changed across the time span. Group by whatever natural time\nboundaries exist in the data (weeks for short spans, months for longer ones). Did\nexpectations mature? Did new patterns emerge? What shifted? If the dataset spans\nless than a month, note that evolution analysis is limited but still look for any\nprogression from early to late files.\n\n### 8. Actionable Prompt Instructions\nThe most important output. Based on all patterns: specific numbered instructions\nthat could be embedded in a planning prompt to prevent the most common denial\nreasons. Write these as actual directives an agent could follow. Be specific to\nthis user's patterns — generic advice like \"write good plans\" is worthless. Each\ninstruction should trace back to a real, frequent denial pattern.\n\nAfter writing the instructions, calculate what percentage of denials they would\naddress (count how many denials fall into categories covered by the instructions\nvs total denials). Report this percentage — it will be different for every user.\n\n## Phase 4: Generate the HTML Dashboard\n\nBuild a single, self-contained HTML file as the final deliverable. Save it to\nthe user's plans directory with a versioned filename:\n\n- First ever report: `compound-planning-report.html`\n- Second report: `compound-planning-report-v2.html`\n- Third report: `compound-planning-report-v3.html`\n- And so on.\n\nThe version number was determined in Phase 0 based on existing reports found.\n\n**If this is an incremental report**, the header should indicate the analysis\nperiod (e.g., \"March 15 – March 31, 2026\") and include a subtitle noting\n\"Incremental analysis — see v{N-1} for earlier findings.\" The narrative in\nsection 1 should frame findings as what's new or changed since the last report,\nnot as a complete picture. Overall stats in the header (file counts, revision\nrate) should still reflect the full archive for context.\n\nRead the template at `assets/report-template.html` for the **design language\nonly**. The template contains example data from a previous analysis — ignore all\ndata values, quotes, and percentages in the template. Use only its visual design:\ncolors, typography, spacing, component styles, and layout patterns.\n\n### Design Language (from template)\n\n- **Palette:** Light mode, warm off-white (#FDFCFB), text in slate scale, amber\n for highlights/accents, emerald for positive, rose for negative, indigo for\n action elements\n- **Typography:** Playfair Display (serif, for narrative headings), Inter (sans,\n for body/data), JetBrains Mono (mono, for code/phrases) — Google Fonts CDN\n- **Layout:** Single-column, max-width 1024px, generous vertical whitespace (128px\n between major sections), editorial/narrative-first aesthetic\n- **Tone:** Calm, reflective, authoritative. Like a personal retrospective journal,\n not a monitoring dashboard.\n\n### Page Frame (header + footer)\n\nBefore the 7 sections, the page has:\n\n- **Header:** Report title on the left (Playfair Display, ~36px), project name +\n date range below it in light meta text. On the right: file counts in mono\n (e.g., \"223 denials · 71 days\"). Separated from content by\n a bottom border. Generous bottom padding before section 1.\n\n- **Footer:** After section 7. Top border, centered italic Playfair Display tagline\n summarizing the corpus (e.g., \"Analysis of X denied plans from the Plannotator\n archive.\").\n\n### Dashboard Section Order (7 sections)\n\nThe report follows this exact section order. Each section builds on the previous\none — the flow moves from \"what happened\" through \"why\" to \"what to do about it\":\n\n1. **The story in the data** — An editorial narrative paragraph (Playfair Display\n serif, ~26px) that tells the headline finding in prose. Not bullet points — a\n real paragraph that reads like the opening of an article. Alongside it, a KPI\n sidebar with 3 key metrics (the top denial percentage, the overall revision\n rate, and the number of distinct denial categories found). Use an amber inline\n highlight on the most striking number in the narrative.\n\n2. **Why plans get denied** — The taxonomy as a ranked list. Each row: rank number\n (mono), category label, a thin 4px progress bar (top item in amber-500, rest\n in slate-300), percentage (mono), and for the top entries, a real italic quote\n from the data below the label. Show the top 10 categories or however many the\n data supports (minimum 5).\n\n3. **How expectations evolved** — One card per natural time period. Each card has:\n the period name in serif, a theme phrase in colored uppercase (different color\n per period to show progression), a description paragraph, and a stat line at\n the bottom (e.g., \"X denials · Y narrative requests\"). If the data spans less\n than 3 distinct periods, use 2 cards or even a single card with internal\n progression noted.\n\n4. **What works vs what doesn't** — Two side-by-side cards. Left: green-tinted\n (emerald-50/50 bg, emerald-100 border) with traits of plans that succeed for\n this reviewer. Right: red-tinted (rose-50/50 bg, rose-100 border) with what\n agents keep getting wrong. Both derived from the reduction analysis. Bulleted\n with small colored dots. 5-8 items per card.\n\n5. **The actionable output** — The diagnostic payoff. Opens with a Playfair\n Display narrative sentence stating how many prompt instructions were derived\n and what estimated percentage of denials they address (use the real calculated\n percentage from Phase 3, not a generic number). Then the top 3 most impactful\n improvements as numbered items, each with an amber number, bold title, and\n one-line description. This section bridges the analysis and the full prompt\n that follows.\n\n6. **Your most-used phrases** — Grid of chips (2-col mobile, 3-col desktop). Each\n chip: monospace quoted phrase on the left, frequency count on the right. White\n bg, slate-200 border, rounded-12px. Show 9-12 of the most recurring phrases\n found. These should be the reviewer's actual words — their verbal fingerprint.\n\n7. **The corrective prompt** — Dark panel (slate-900 bg, white text, rounded-3xl,\n shadow-xl). Opens with a Playfair intro sentence about the instructions. Then\n a dark code block (slate-800/80 bg, amber-200 monospace text) containing the\n full numbered prompt instructions from Phase 3. Include a copy-to-clipboard\n button that works (JS included). Below the code block: a gradient glow card\n (indigo-to-purple blurred halo behind a white card) with a closing message\n that these instructions are personal — derived from the user's own feedback,\n their own language, their own standards.\n\n### Adaptation Rules\n\n- If the user has < 3 months of data, reduce the evolution section to fewer cards\n- If most denied files lack feedback below the `---` (bare denials with no\n annotations), note this in the narrative — the analysis will be thinner\n- **Claude Code fallback mode:** Explicitly label the report source as Claude Code\n `ExitPlanMode` denial reasons. Do not fabricate Plannotator-only fields such as\n annotation counts or approved-plan line counts. See the fallback reference for\n KPI substitutes and footer/provenance guidance.\n- If fewer than 5 denial categories emerge, combine the taxonomy and patterns\n sections into one\n- If the dataset is very small (< 20 files), the narrative should acknowledge the\n limited sample size and frame findings as preliminary\n- The number of prompt instructions will vary per user — could be 8 or 20. Don't\n force exactly 17. Let the data determine the count.\n- The top 3 actionable items in section 5 must be the 3 that cover the largest\n share of denials, not the 3 that sound most impressive\n\n### Key Rules\n\n1. Every number must come from the real analysis — no fabricated data\n2. Every quote must be a real quote from a real file\n3. The taxonomy percentages must be calculated from real counts\n4. The prompt instructions must trace back to actual denial patterns\n5. The copy button on the prompt block must work (include the JS)\n\nAfter generating, open the file in the user's browser.\n\n## Phase 5: Summary\n\nTell the user:\n- How many denied files were analyzed\n- If incremental: how many were new since the last report\n- The top 3 denial patterns found\n- The estimated percentage of denials the prompt instructions would address\n- The single most impactful prompt improvement\n- Where the report was saved (including version number)\n- If incremental: remind the user that earlier findings are in the previous report\n\n**Claude Code fallback mode:** Adapt the summary per the fallback reference —\nreport human denial reasons analyzed and total `ExitPlanMode` attempts scanned\ninstead of Plannotator file counts.\n\n## Phase 6: Improvement Hook\n\nAfter presenting the summary, ask the user if they want to enable an **improvement\nhook** — this takes the corrective prompt instructions from section 7 of the report\nand writes them to a file that Plannotator's `EnterPlanMode` hook can inject into\nevery future planning session automatically.\n\n> \"Would you like to enable the improvement hook? This will save the corrective\n> prompt instructions to a file that gets automatically injected into all future\n> planning sessions — so Claude sees your feedback patterns before writing any plan.\"\n\n**If yes:**\n\nThe hook file lives at:\n\n```\n${PLANNOTATOR_DATA_DIR:-~/.plannotator}/hooks/compound/enterplanmode-improve-hook.txt\n```\n\nCreate the `hooks/compound/` directory inside the data directory if it doesn't exist.\n\nThe file contents should be the corrective prompt instructions from Phase 3 —\nthe same numbered list that appears in section 7 of the HTML report. Write them\nas plain text, one instruction per line, prefixed with their number. No HTML, no\nmarkdown fences, no preamble — just the instructions themselves. The hook system\nwill inject this file's contents as-is into the planning context.\n\n**If the file already exists:**\n\nRead the existing file and present the user with a choice:\n\n> \"An improvement hook already exists from a previous analysis. I can:\n>\n> 1. **Replace** — Overwrite with the new instructions (the old ones are gone)\n> 2. **Merge** — Combine both, deduplicating overlapping instructions and\n> keeping the best version of each\n> 3. **Keep existing** — Leave the current hook as-is, skip this step\n>\n> Which would you prefer?\"\n\n- **Replace:** Overwrite the file with the new instructions.\n- **Merge:** Read the existing instructions, compare with the new ones, and\n produce a merged set. Remove duplicates (same intent even if worded differently).\n When two instructions cover the same pattern, keep the more specific or\n actionable version. Re-number the final list sequentially. Write the merged\n result to the file. Show the user what changed (added N new, removed N\n redundant, kept N existing).\n- **Keep existing:** Do nothing, move on.\n\n**If no:** Skip this phase entirely.\n\n## Important Notes\n\n- **Data source priority:** Plannotator is the first-class path. Claude Code log\n analysis is the secondary path for users without Plannotator archives.\n- **Research integrity:** Every file must be read. The value of this analysis comes\n from completeness. Sampling or skipping undermines the findings.\n- **Real data only:** Never fabricate quotes, percentages, or patterns. If the data\n doesn't show a clear pattern, say so honestly rather than inventing one.\n- **Let the data lead:** The taxonomy, patterns, and instructions should emerge from\n what's actually in the files. Different users will have completely different\n denial patterns. A user building mobile apps will have different feedback than\n one building APIs. Don't assume what the patterns will be.\n- **Agent parallelization:** For large datasets, maximize parallel agents to reduce\n wall-clock time. The bottleneck is the largest batch — split it.\n- **Structured extraction format:** Ask extraction agents to return structured text\n with consistent delimiters so the reduce agent can parse reliably.\n- **The report is the artifact:** The HTML dashboard is what the user keeps. It\n should be beautiful, honest, and useful. Every section should feel like it was\n written about them specifically, because it was.\n","frontmatter":{"name":"plannotator-compound","disable-model-invocation":true,"description":"Analyze a user's Plannotator plan archive to extract denial patterns, feedback taxonomy, evolution over time, and actionable prompt improvements — then produce a polished HTML dashboard report. Falls back to Claude Code ExitPlanMode denial reasons when Plannotator data is unavailable.\n","disableModelInvocation":true},"isInternal":false,"tokens":5981,"sizeBytes":26779},{"name":"openai.yaml","path":"apps/skills/extra/plannotator-setup-goal/agents/openai.yaml","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-setup-goal/agents/openai.yaml","title":"Agents Skill","category":"anthropic-skill","format":"yaml","content":"# Agents Skill\n\nPath: `apps/skills/extra/plannotator-setup-goal/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-setup-goal/agents/openai.yaml)","tokens":300,"sizeBytes":237},{"name":"SKILL.md","path":"apps/skills/extra/plannotator-setup-goal/SKILL.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-setup-goal/SKILL.md","title":"plannotator-setup-goal","category":"anthropic-skill","format":"markdown","content":"---\nname: plannotator-setup-goal\ndisable-model-invocation: true\ndescription: Turn an idea or objective into a goal package for /goal. Interviews the user, builds a reviewed fact sheet via Plannotator, then explores the codebase to produce an execution plan.\n---\n\n# Setup Goal\n\nTurn an idea into a goal package at `goals//` through structured discovery, user interview, and codebase exploration.\n\n## Phases\n\n### 1. Rearticulate\n\nState back what the user wants in your own words. If the conversation already has rich context, summarize it. If the goal is bare or vague, do minimal shallow exploration of the codebase to ground your understanding. Keep it to 2-3 sentences. Wait for the user to confirm or correct before continuing.\n\nCreate the goal directory once the slug is clear:\n\n```bash\nmkdir -p goals/\n```\n\nUse `goals//` for both working JSON files and final docs. The JSON files are provenance and iteration state; the markdown files are the human-readable authoritative goal package.\n\n**Browser session patience rule:** Plannotator goal setup is a user-driven browser session. After launching an interview or facts command, be absolutely patient and keep waiting on the user until they submit, dismiss, or explicitly ask you to stop. Do not close, kill, restart, refresh, or open a second copy just because the UI is idle or the user is taking time. Never close and reopen the session as a way to update state; if a rerun is needed after the prior session ends, update the working JSON file and launch a new command from that file.\n\n**Optional: grill first (deep, one-at-a-time interview).** Before building the compact interview bundle, *suggest* a grilling pass whenever the goal is vague or carries many interdependent decisions — and run one whenever the user asks for it (\"grill me first\"). This is opt-in: for a clear, well-scoped goal, skip it and go straight to the bundle, so grilling never fights the bundle's \"fewer, higher-leverage questions\" philosophy. When you grill, run the protocol below verbatim, then fold the resolved decisions forward into a higher-quality interview bundle (Phase 2) — or, if grilling fully resolves scope, straight into the fact sheet (Phase 3).\n\n\n\n> Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.\n>\n> Ask the questions one at a time.\n>\n> If a question can be answered by exploring the codebase, explore the codebase instead.\n\n### 2. Interview Bundle\n\nBuild a compact bundle of questions that can derive every \"fact\" this goal should produce. Package the questions together so the user can answer them quickly in the Plannotator goal setup UI. For each question, include your recommended answer and use options when they make answering faster.\n\nDo not ask obvious confirmation questions. If the answer can be inferred from the user's request, from the conversation, or from shallow codebase exploration, infer it and move on. If an obvious area has meaningful nuance, present the inferred answer as a recommendation with options or a custom \"add/correct this\" path rather than asking the user to restate the obvious.\n\nQuestion areas that usually matter:\n\n- What the feature/change is\n- Who it's for\n- What problem it solves\n- What behavior changes\n- What success looks like\n- What's in and out of scope (the most important area to determine facts)\n- What edge cases to consider\n- What constraints or precedent apply\n\n**If a question can be answered by exploring the codebase, explore the codebase instead of asking.** Only include questions where the user's judgment is actually needed. Prefer fewer, higher-leverage questions over exhaustive obvious ones.\n\nWrite the interview bundle before showing it to the user:\n\n`goals//interview.json`\n\n```json\n{\n \"stage\": \"interview\",\n \"title\": \"Short human-readable title\",\n \"goalSlug\": \"\",\n \"questions\": [\n {\n \"id\": \"scope\",\n \"prompt\": \"What should be in scope?\",\n \"description\": \"Optional clarification.\",\n \"answerMode\": \"multi-custom\",\n \"recommendedAnswer\": \"Your recommended answer.\",\n \"recommendedOptionIds\": [\"ui\", \"server\"],\n \"options\": [\n { \"id\": \"ui\", \"label\": \"UI\" },\n { \"id\": \"server\", \"label\": \"Server\" }\n ],\n \"required\": true\n }\n ]\n}\n```\n\nSupported `answerMode` values: `text`, `single`, `multi`, `custom`, `single-custom`, `multi-custom`.\n\nRun this as a monitored foreground process and wait patiently for the browser session to finish. The command may appear idle while the user is reading, editing, or asking questions; leave it running:\n\n```bash\nplannotator setup-goal interview goals//interview.json --json\n```\n\nThe command returns JSON on stdout with the submitted answers. Write that exact result to `goals//interview-result.json` before continuing. A convenient pattern is:\n\n```bash\nplannotator setup-goal interview goals//interview.json --json | tee goals//interview-result.json\n```\n\nIf the user revises after the session finishes, update `interview.json` and rerun the command instead of reconstructing the whole bundle from memory. If the session is dismissed, stop and tell the user the goal setup was closed.\n\nBefore moving to facts, read every answer and note carefully:\n\n- If the user wrote questions, uncertainty, \"not sure\", \"needs context\", or similar concerns in an answer or note, stop and address those questions in chat. Do not proceed to facts until the user has enough context or you have rerun a revised interview bundle.\n- If the user skipped a question with a note, treat the note as intentional feedback, not as an empty answer. Answer the note, refine the question, or make a documented assumption before proceeding.\n- If the user skipped a question without a note, proceed only if the missing answer is non-blocking; otherwise ask the smallest possible follow-up in chat.\n\n### 3. Fact Sheet\n\nA fact is a simple description of each outcome of a goal. It should be easily testable and verifiable. A fact may describe the function of a specific feature or aspect of a system. A fact may determine specific UI and UX. Again, a fact is literally anything that can be tested and verified in automated or manual testing. Keep fact language simple. In a way, a fact sheet is a design spec, but less verbose & using language the human user can easily visualize & rationalize. \n\nPrepare a facts review bundle from `goals//interview-result.json`. Each fact should include whether automated verification is recommended and preselected.\n\nWrite the facts review bundle before showing it to the user. If revising after a prior facts pass, start from `facts-review.json` and `facts-result.json`, include previously accepted facts with `\"accepted\": true`, and preserve their state.\n\n`goals//facts-review.json`\n\n```json\n{\n \"stage\": \"facts\",\n \"title\": \"Short human-readable title\",\n \"goalSlug\": \"\",\n \"facts\": [\n {\n \"id\": \"fact-1\",\n \"text\": \"The accepted fact text.\",\n \"accepted\": false,\n \"removed\": false,\n \"recommendedAutomatedVerification\": true,\n \"automatedVerification\": true\n }\n ]\n}\n```\n\nRun this as a monitored foreground process and wait patiently for the browser session to finish. The command may appear idle while the user is reviewing, editing, or asking questions; leave it running:\n\n```bash\nplannotator setup-goal facts goals//facts-review.json --json\n```\n\nThe command returns JSON on stdout with accepted/edited/removed facts plus automated verification selections. Write that exact result to `goals//facts-result.json`. A convenient pattern is:\n\n```bash\nplannotator setup-goal facts goals//facts-review.json --json | tee goals//facts-result.json\n```\n\nWrite `goals//facts.md` as a flat readable list of accepted facts. Each fact is one line; add a minimal note only when the fact cannot be stated clearly on its own. Also write `goals//facts.meta.json` preserving each accepted fact's `id`, final `text`, `comment`, `recommendedAutomatedVerification`, and `automatedVerification` value.\n\nIf the user edits or removes facts in the UI, apply that result directly. If the session is dismissed, stop and tell the user the facts review was closed.\n\n### 4. Plan\n\nExplore the codebase. Discover and validate implementation paths toward each accepted fact. Treat facts with `automatedVerification: true` as requiring concrete automated checks unless you document a blocker. Trace through code, identify files and systems involved, surface risks and unknowns. Refine until you have a confident order of operations.\n\nWrite `goals//plan.md`:\n\n- Solution approach (brief)\n- Ordered steps with the files/systems each touches\n- Verification for each step (concrete commands or checks)\n- Risks or open questions worth flagging\n\nGate the plan with Plannotator:\n\n```bash\nplannotator annotate goals//plan.md --gate\n```\n\nIf denied, revise from feedback and re-gate until approved.\n\n### 5. Goal Output\n\nWrite `goals//goal.md`:\n\n- The articulated goal (1-3 sentences)\n- Reference to `facts.md` as the shared understanding\n- Reference to `plan.md` as the execution plan\n- Done condition\n\nTell the user:\n\n```\nDone! Launch a goal with `/goal goals//goal.md`\n```\n","frontmatter":{"name":"plannotator-setup-goal","disable-model-invocation":true,"description":"Turn an idea or objective into a goal package for /goal. Interviews the user, builds a reviewed fact sheet via Plannotator, then explores the codebase to produce an execution plan.","disableModelInvocation":true},"isInternal":false,"tokens":2116,"sizeBytes":9602},{"name":"design-system.md","path":"apps/skills/extra/plannotator-visual-explainer/references/design-system.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-visual-explainer/references/design-system.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# References Skill\n\nPath: `apps/skills/extra/plannotator-visual-explainer/references/design-system.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-visual-explainer/references/design-system.md)","tokens":300,"sizeBytes":271},{"name":"pr-components.md","path":"apps/skills/extra/plannotator-visual-explainer/references/pr-components.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-visual-explainer/references/pr-components.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# References Skill\n\nPath: `apps/skills/extra/plannotator-visual-explainer/references/pr-components.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-visual-explainer/references/pr-components.md)","tokens":300,"sizeBytes":271},{"name":"svg-patterns.md","path":"apps/skills/extra/plannotator-visual-explainer/references/svg-patterns.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-visual-explainer/references/svg-patterns.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# References Skill\n\nPath: `apps/skills/extra/plannotator-visual-explainer/references/svg-patterns.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-visual-explainer/references/svg-patterns.md)","tokens":300,"sizeBytes":269},{"name":"theme-override.md","path":"apps/skills/extra/plannotator-visual-explainer/references/theme-override.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-visual-explainer/references/theme-override.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# References Skill\n\nPath: `apps/skills/extra/plannotator-visual-explainer/references/theme-override.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-visual-explainer/references/theme-override.md)","tokens":300,"sizeBytes":273},{"name":"SKILL.md","path":"apps/skills/extra/plannotator-visual-explainer/SKILL.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-visual-explainer/SKILL.md","title":"plannotator-visual-explainer","category":"anthropic-skill","format":"markdown","content":"---\nname: plannotator-visual-explainer\ndisable-model-invocation: true\ndescription: >\n Generate self-contained HTML visualizations with Plannotator theming. Use for implementation\n plans, PR explainers, architecture diagrams, data tables, slide decks, and any visual\n explanation of technical concepts. Plans and PR explainers follow Plannotator's prescriptive\n approach; all other visual content delegates to nicobailon/visual-explainer.\n---\n\n# Plannotator Visual Explainer\n\nThree paths depending on content type. Each has its own references and structure.\n\n## Route by content type\n\n**Implementation plan, design doc, or proposal** → Follow the [Plan path](#plan-path). Read `references/design-system.md` and `references/svg-patterns.md`. Prescriptive structure.\n\n**PR explainer, diff review, or code change walkthrough** → Follow the [PR path](#pr-path). Read `references/design-system.md` and `references/pr-components.md`. Prescriptive structure.\n\n**Everything else** (architecture diagrams, data tables, slide decks, project recaps, general visual explanations) → Follow the [Visual explainer path](#visual-explainer-path). Delegates to nicobailon/visual-explainer with Plannotator theme tokens.\n\n## Delivery\n\nAlways deliver via Plannotator's annotation UI. Do NOT use `open` or `xdg-open`.\n\nFor any deliverable that uses Mermaid, render every diagram with Mermaid 12 in both the light\nand dark palettes before opening the annotation UI. Rendering is a hard gate: an exception,\nempty SVG, or error output such as `aria-roledescription=\"error\"` or `Syntax error in text`\nmeans the explainer is not deliverable. Fix the diagram or theme configuration and rerun both\npalettes until every SVG passes.\n\nFor zoomable diagram shells, additionally zoom to the maximum and pan to all extremes in both palettes before delivering: the figure caption must stay fully legible throughout (see `references/diagram-shell.md`).\n\n**Plans/proposals** (user should approve/deny):\n```bash\nplannotator annotate --gate\n```\n\n**Everything else** (informational):\n```bash\nplannotator annotate \n```\n\n---\n\n## Plan path\n\nFor implementation plans, design docs, feature specs, migration guides, and proposals.\n\n**Before generating, read:**\n1. `references/design-system.md` — Plannotator theme tokens, typography, component patterns\n2. `references/svg-patterns.md` — inline SVG building blocks for architecture diagrams, flowcharts, data flow\n\n**Document structure (in order, pick what fits):**\n\n1. **Header** — eyebrow label (mono, uppercase), title (serif, large), prompt box (the original brief)\n2. **Summary strip** — 3-5 stat cards showing key numbers at a glance (components, endpoints, tables, etc.)\n3. **Milestones / timeline** — vertical timeline showing phases without time estimates. Phases show sequence and dependencies, not duration.\n4. **Architecture / data flow** — inline SVG diagram. Use for 3+ interacting components. Highlighted boxes for new components, dashed arrows for async paths.\n5. **Mockups** — build UI mockups in HTML/CSS directly, not as descriptions\n6. **Key code** — dark-theme code blocks with syntax highlighting. Only architecturally significant interfaces/schemas — not every function.\n7. **Risks & mitigations** — table with severity badges (HIGH/MED/LOW)\n8. **Open questions** — callout cards with decision owner (\"Decide with: backend team\")\n\nNot every plan needs every section. Skip what doesn't serve the content. Never include time estimates, boilerplate sections, or exhaustive file lists.\n\n**Adapt to the task:** Backend → lead with data flow. Frontend → lead with mockups. Refactoring → lead with before/after diagrams. Infrastructure → lead with architecture.\n\n**Quality bar:** The plan answers \"what, why, and how\" within 30 seconds of reading. Whitespace is a feature — one idea per viewport.\n\n---\n\n## PR path\n\nFor PR walkthroughs, diff reviews, code change explainers, and reviewer guides.\n\n**Before generating, read:**\n1. `references/design-system.md` — Plannotator theme tokens, typography, component patterns\n2. `references/pr-components.md` — diff rendering, review comment bubbles, risk chips, file cards, before/after panels\n\n**Document structure (in order, pick what fits):**\n\n1. **Header** — PR title, meta strip (file count, +/- lines, branch, author)\n2. **TL;DR** — bordered card with primary accent left border. 2-3 sentences. Readers who see nothing else should get the gist.\n3. **Why** — motivation and before/after comparison (two-column grid)\n4. **File tour** — collapsible cards per file. Each has: file path + badge (NEW/MOD/DEL) + line stats, a \"why\" paragraph, and important diff hunks. High-risk files expanded, safe files collapsed.\n5. **Risk map** — visual chips showing which files need careful review vs. which are mechanical. Three tiers: attention (destructive), medium (warning), safe (success).\n6. **Where to focus** — numbered callout cards. Each names a file/function and describes the concern.\n7. **Test plan** — checkbox-style verification checklist\n8. **Rollout** (if applicable) — phased deployment with feature flags\n\nUse Pierre diffs via CDN for syntax-highlighted inline diffs — see `references/pr-components.md` for the pattern.\n\n---\n\n## Visual explainer path\n\nFor architecture diagrams, data tables, slide decks, project recaps, comparisons, and any other visual explanation.\n\n**Before generating:**\n\n1. Ensure `visual-explainer` is installed:\n - Check: `~/.claude/skills/visual-explainer/SKILL.md` or `~/.agents/skills/visual-explainer/SKILL.md`\n - If not found: `npx skills add nicobailon/visual-explainer -g --yes`\n2. Read visual-explainer's `SKILL.md` (workflow, diagram types, anti-slop rules)\n3. Read the relevant visual-explainer references and templates for your content type\n4. Read `references/theme-override.md` — Plannotator tokens replacing Nico's palettes\n5. For zoomable Mermaid diagrams with controls and a caption: read `references/diagram-shell.md` and copy its shell — do not hand-roll viewport, canvas, or caption markup\n\nFollow visual-explainer's structure, component classes (`.ve-card`, `.kpi-card`, `.pipeline`), and anti-slop rules. Overrides are the color/typography layer — Plannotator tokens instead of Nico's custom palettes — plus the zoomable diagram shell in `references/diagram-shell.md` when the deliverable has one.\n\n---\n\n## Design philosophy (all paths)\n\n- **Whitespace is a feature.** Generous padding, large section gaps. If cramped, add space — don't shrink text.\n- **One idea per viewport.** Hero section, then diagram, then detail grid — not all crammed together.\n- **Show, don't describe.** A timeline shows sequencing. A diagram shows relationships. A code block shows the interface.\n- **No time estimates.** Timelines show phases and dependencies. Never attach hour/day estimates.\n","frontmatter":{"name":"plannotator-visual-explainer","disable-model-invocation":true,"description":"Generate self-contained HTML visualizations with Plannotator theming. Use for implementation plans, PR explainers, architecture diagrams, data tables, slide decks, and any visual explanation of technical concepts. Plans and PR explainers follow Plannotator's prescriptive approach; all other visual content delegates to nicobailon/visual-explainer.\n","disableModelInvocation":true},"isInternal":false,"tokens":1577,"sizeBytes":6880},{"name":"package.json","path":"packages/ai/package.json","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ai/package.json","title":"Ai Skill","category":"anthropic-skill","format":"json","content":"# Ai Skill\n\nPath: `packages/ai/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ai/package.json)","tokens":300,"sizeBytes":163},{"name":"tsconfig.json","path":"packages/ai/tsconfig.json","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ai/tsconfig.json","title":"Ai Skill","category":"anthropic-skill","format":"json","content":"# Ai Skill\n\nPath: `packages/ai/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ai/tsconfig.json)","tokens":300,"sizeBytes":165},{"name":"package.json","path":"packages/core/package.json","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/core/package.json","title":"Core Skill","category":"anthropic-skill","format":"json","content":"# Core Skill\n\nPath: `packages/core/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/core/package.json)","tokens":300,"sizeBytes":169},{"name":"tsconfig.json","path":"packages/core/tsconfig.json","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/core/tsconfig.json","title":"Core Skill","category":"anthropic-skill","format":"json","content":"# Core Skill\n\nPath: `packages/core/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/core/tsconfig.json)","tokens":300,"sizeBytes":171},{"name":"package.json","path":"packages/editor/package.json","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/editor/package.json","title":"Editor Skill","category":"anthropic-skill","format":"json","content":"# Editor Skill\n\nPath: `packages/editor/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/editor/package.json)","tokens":300,"sizeBytes":175},{"name":"checkbox.md","path":"packages/review-editor/.migration/checkbox.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/.migration/checkbox.md","title":".migration Skill","category":"anthropic-skill","format":"markdown","content":"# .migration Skill\n\nPath: `packages/review-editor/.migration/checkbox.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/.migration/checkbox.md)","tokens":300,"sizeBytes":213},{"name":"context-menu.md","path":"packages/review-editor/.migration/context-menu.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/.migration/context-menu.md","title":".migration Skill","category":"anthropic-skill","format":"markdown","content":"# .migration Skill\n\nPath: `packages/review-editor/.migration/context-menu.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/.migration/context-menu.md)","tokens":300,"sizeBytes":221},{"name":"dropdown-menu.md","path":"packages/review-editor/.migration/dropdown-menu.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/.migration/dropdown-menu.md","title":".migration Skill","category":"anthropic-skill","format":"markdown","content":"# .migration Skill\n\nPath: `packages/review-editor/.migration/dropdown-menu.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/.migration/dropdown-menu.md)","tokens":300,"sizeBytes":223},{"name":"popover.md","path":"packages/review-editor/.migration/popover.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/.migration/popover.md","title":".migration Skill","category":"anthropic-skill","format":"markdown","content":"# .migration Skill\n\nPath: `packages/review-editor/.migration/popover.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/.migration/popover.md)","tokens":300,"sizeBytes":211},{"name":"project.md","path":"packages/review-editor/.migration/project.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/.migration/project.md","title":".migration Skill","category":"anthropic-skill","format":"markdown","content":"# .migration Skill\n\nPath: `packages/review-editor/.migration/project.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/.migration/project.md)","tokens":300,"sizeBytes":211},{"name":"package.json","path":"packages/review-editor/package.json","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/package.json","title":"Review-editor Skill","category":"anthropic-skill","format":"json","content":"# Review-editor Skill\n\nPath: `packages/review-editor/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/package.json)","tokens":300,"sizeBytes":196},{"name":"tsconfig.json","path":"packages/review-editor/tsconfig.json","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/tsconfig.json","title":"Review-editor Skill","category":"anthropic-skill","format":"json","content":"# Review-editor Skill\n\nPath: `packages/review-editor/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/review-editor/tsconfig.json)","tokens":300,"sizeBytes":198},{"name":"codex-review-schema.json","path":"packages/server/codex-review-schema.json","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/server/codex-review-schema.json","title":"Server Skill","category":"anthropic-skill","format":"json","content":"# Server Skill\n\nPath: `packages/server/codex-review-schema.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/server/codex-review-schema.json)","tokens":300,"sizeBytes":199},{"name":"package.json","path":"packages/server/package.json","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/server/package.json","title":"Server Skill","category":"anthropic-skill","format":"json","content":"# Server Skill\n\nPath: `packages/server/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/server/package.json)","tokens":300,"sizeBytes":175},{"name":"tsconfig.json","path":"packages/server/tsconfig.json","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/server/tsconfig.json","title":"Server Skill","category":"anthropic-skill","format":"json","content":"# Server Skill\n\nPath: `packages/server/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/server/tsconfig.json)","tokens":300,"sizeBytes":177},{"name":"package.json","path":"packages/shared/package.json","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/shared/package.json","title":"Shared Skill","category":"anthropic-skill","format":"json","content":"# Shared Skill\n\nPath: `packages/shared/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/shared/package.json)","tokens":300,"sizeBytes":175},{"name":"tsconfig.json","path":"packages/shared/tsconfig.json","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/shared/tsconfig.json","title":"Shared Skill","category":"anthropic-skill","format":"json","content":"# Shared Skill\n\nPath: `packages/shared/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/shared/tsconfig.json)","tokens":300,"sizeBytes":177},{"name":"badge.md","path":"packages/ui/.migration/badge.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/badge.md","title":".migration Skill","category":"anthropic-skill","format":"markdown","content":"# .migration Skill\n\nPath: `packages/ui/.migration/badge.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/badge.md)","tokens":300,"sizeBytes":185},{"name":"button.md","path":"packages/ui/.migration/button.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/button.md","title":".migration Skill","category":"anthropic-skill","format":"markdown","content":"# .migration Skill\n\nPath: `packages/ui/.migration/button.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/button.md)","tokens":300,"sizeBytes":187},{"name":"dialog.md","path":"packages/ui/.migration/dialog.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/dialog.md","title":".migration Skill","category":"anthropic-skill","format":"markdown","content":"# .migration Skill\n\nPath: `packages/ui/.migration/dialog.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/dialog.md)","tokens":300,"sizeBytes":187},{"name":"dropdown-menu.md","path":"packages/ui/.migration/dropdown-menu.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/dropdown-menu.md","title":".migration Skill","category":"anthropic-skill","format":"markdown","content":"# .migration Skill\n\nPath: `packages/ui/.migration/dropdown-menu.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/dropdown-menu.md)","tokens":300,"sizeBytes":201},{"name":"popout-dialog.md","path":"packages/ui/.migration/popout-dialog.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/popout-dialog.md","title":".migration Skill","category":"anthropic-skill","format":"markdown","content":"# .migration Skill\n\nPath: `packages/ui/.migration/popout-dialog.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/popout-dialog.md)","tokens":300,"sizeBytes":201},{"name":"popover.md","path":"packages/ui/.migration/popover.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/popover.md","title":".migration Skill","category":"anthropic-skill","format":"markdown","content":"# .migration Skill\n\nPath: `packages/ui/.migration/popover.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/popover.md)","tokens":300,"sizeBytes":189},{"name":"project.md","path":"packages/ui/.migration/project.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/project.md","title":".migration Skill","category":"anthropic-skill","format":"markdown","content":"# .migration Skill\n\nPath: `packages/ui/.migration/project.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/project.md)","tokens":300,"sizeBytes":189},{"name":"tabs.md","path":"packages/ui/.migration/tabs.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/tabs.md","title":".migration Skill","category":"anthropic-skill","format":"markdown","content":"# .migration Skill\n\nPath: `packages/ui/.migration/tabs.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/tabs.md)","tokens":300,"sizeBytes":183},{"name":"tooltip.md","path":"packages/ui/.migration/tooltip.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/tooltip.md","title":".migration Skill","category":"anthropic-skill","format":"markdown","content":"# .migration Skill\n\nPath: `packages/ui/.migration/tooltip.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/.migration/tooltip.md)","tokens":300,"sizeBytes":189},{"name":"AGENTS.md","path":"packages/ui/AGENTS.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/AGENTS.md","title":"Ui Skill","category":"anthropic-skill","format":"markdown","content":"# Ui Skill\n\nPath: `packages/ui/AGENTS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/AGENTS.md)","tokens":300,"sizeBytes":157},{"name":"HANDOFF.md","path":"packages/ui/HANDOFF.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/HANDOFF.md","title":"Ui Skill","category":"anthropic-skill","format":"markdown","content":"# Ui Skill\n\nPath: `packages/ui/HANDOFF.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/HANDOFF.md)","tokens":300,"sizeBytes":159},{"name":"package.json","path":"packages/ui/package.json","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/package.json","title":"Ui Skill","category":"anthropic-skill","format":"json","content":"# Ui Skill\n\nPath: `packages/ui/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/package.json)","tokens":300,"sizeBytes":163},{"name":"tsconfig.json","path":"packages/ui/tsconfig.json","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/tsconfig.json","title":"Ui Skill","category":"anthropic-skill","format":"json","content":"# Ui Skill\n\nPath: `packages/ui/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/tsconfig.json)","tokens":300,"sizeBytes":165},{"name":"tsconfig.strict-consumer.json","path":"packages/ui/tsconfig.strict-consumer.json","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/tsconfig.strict-consumer.json","title":"Ui Skill","category":"anthropic-skill","format":"json","content":"# Ui Skill\n\nPath: `packages/ui/tsconfig.strict-consumer.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/tsconfig.strict-consumer.json)","tokens":300,"sizeBytes":197},{"name":"marketplace.json","path":".claude-plugin/marketplace.json","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.claude-plugin/marketplace.json","title":"Claude Plugin Marketplace Catalog","category":"marketplace","format":"json","content":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.claude-plugin/marketplace.json)","tokens":300,"sizeBytes":202},{"name":"marketplace.json","path":".factory-plugin/marketplace.json","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.factory-plugin/marketplace.json","title":"Claude Plugin Marketplace Catalog","category":"marketplace","format":"json","content":"# Claude Plugin Marketplace Catalog\n\nPath: `.factory-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.factory-plugin/marketplace.json)","tokens":300,"sizeBytes":204},{"name":"marketplace.json","path":".github/plugin/marketplace.json","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.github/plugin/marketplace.json","title":"Claude Plugin Marketplace Catalog","category":"marketplace","format":"json","content":"# Claude Plugin Marketplace Catalog\n\nPath: `.github/plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.github/plugin/marketplace.json)","tokens":300,"sizeBytes":202},{"name":"plugin.json","path":"apps/copilot/plugin.json","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/copilot/plugin.json","title":"copilot Plugin Manifest","category":"plugin-manifest","format":"json","content":"# copilot Plugin Manifest\n\nPath: `apps/copilot/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/copilot/plugin.json)","tokens":300,"sizeBytes":178},{"name":"plugin.json","path":"apps/droid-plugin/.factory-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/droid-plugin/.factory-plugin/plugin.json","title":"factory-plugin Plugin Manifest","category":"plugin-manifest","format":"json","content":"# factory-plugin Plugin Manifest\n\nPath: `apps/droid-plugin/.factory-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/droid-plugin/.factory-plugin/plugin.json)","tokens":300,"sizeBytes":227},{"name":"plugin.json","path":"apps/hook/.claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/hook/.claude-plugin/plugin.json","title":"claude-plugin Plugin Manifest","category":"plugin-manifest","format":"json","content":"# claude-plugin Plugin Manifest\n\nPath: `apps/hook/.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/hook/.claude-plugin/plugin.json)","tokens":300,"sizeBytes":208},{"name":"README.md","path":"packages/ui/README.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/README.md","title":"ui Documentation","category":"plugin-manifest","format":"markdown","content":"# ui Documentation\n\nPath: `packages/ui/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ui/README.md)","tokens":300,"sizeBytes":165},{"name":"plannotator-annotate.md","path":"apps/copilot/commands/plannotator-annotate.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/copilot/commands/plannotator-annotate.md","title":"Command: /plannotator-annotate","category":"command-prompt","format":"markdown","content":"# Command: /plannotator-annotate\n\nPath: `apps/copilot/commands/plannotator-annotate.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/copilot/commands/plannotator-annotate.md)","tokens":300,"sizeBytes":227},{"name":"plannotator-last.md","path":"apps/copilot/commands/plannotator-last.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/copilot/commands/plannotator-last.md","title":"Command: /plannotator-last","category":"command-prompt","format":"markdown","content":"# Command: /plannotator-last\n\nPath: `apps/copilot/commands/plannotator-last.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/copilot/commands/plannotator-last.md)","tokens":300,"sizeBytes":215},{"name":"plannotator-review.md","path":"apps/copilot/commands/plannotator-review.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/copilot/commands/plannotator-review.md","title":"Command: /plannotator-review","category":"command-prompt","format":"markdown","content":"# Command: /plannotator-review\n\nPath: `apps/copilot/commands/plannotator-review.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/copilot/commands/plannotator-review.md)","tokens":300,"sizeBytes":221},{"name":"annotate-last.md","path":"apps/marketing/src/content/docs/commands/annotate-last.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/marketing/src/content/docs/commands/annotate-last.md","title":"Command: /annotate-last","category":"command-prompt","format":"markdown","content":"# Command: /annotate-last\n\nPath: `apps/marketing/src/content/docs/commands/annotate-last.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/marketing/src/content/docs/commands/annotate-last.md)","tokens":300,"sizeBytes":244},{"name":"annotate.md","path":"apps/marketing/src/content/docs/commands/annotate.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/marketing/src/content/docs/commands/annotate.md","title":"Command: /annotate","category":"command-prompt","format":"markdown","content":"# Command: /annotate\n\nPath: `apps/marketing/src/content/docs/commands/annotate.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/marketing/src/content/docs/commands/annotate.md)","tokens":300,"sizeBytes":229},{"name":"code-review.md","path":"apps/marketing/src/content/docs/commands/code-review.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/marketing/src/content/docs/commands/code-review.md","title":"Command: /code-review","category":"command-prompt","format":"markdown","content":"# Command: /code-review\n\nPath: `apps/marketing/src/content/docs/commands/code-review.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/marketing/src/content/docs/commands/code-review.md)","tokens":300,"sizeBytes":238},{"name":"plan-review.md","path":"apps/marketing/src/content/docs/commands/plan-review.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/marketing/src/content/docs/commands/plan-review.md","title":"Command: /plan-review","category":"command-prompt","format":"markdown","content":"# Command: /plan-review\n\nPath: `apps/marketing/src/content/docs/commands/plan-review.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/marketing/src/content/docs/commands/plan-review.md)","tokens":300,"sizeBytes":238},{"name":"plannotator-annotate.md","path":"apps/opencode-plugin/commands/plannotator-annotate.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/opencode-plugin/commands/plannotator-annotate.md","title":"Command: /plannotator-annotate","category":"command-prompt","format":"markdown","content":"# Command: /plannotator-annotate\n\nPath: `apps/opencode-plugin/commands/plannotator-annotate.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/opencode-plugin/commands/plannotator-annotate.md)","tokens":300,"sizeBytes":243},{"name":"plannotator-last.md","path":"apps/opencode-plugin/commands/plannotator-last.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/opencode-plugin/commands/plannotator-last.md","title":"Command: /plannotator-last","category":"command-prompt","format":"markdown","content":"# Command: /plannotator-last\n\nPath: `apps/opencode-plugin/commands/plannotator-last.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/opencode-plugin/commands/plannotator-last.md)","tokens":300,"sizeBytes":231},{"name":"plannotator-review.md","path":"apps/opencode-plugin/commands/plannotator-review.md","rawUrl":"https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/opencode-plugin/commands/plannotator-review.md","title":"Command: /plannotator-review","category":"command-prompt","format":"markdown","content":"# Command: /plannotator-review\n\nPath: `apps/opencode-plugin/commands/plannotator-review.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/opencode-plugin/commands/plannotator-review.md)","tokens":300,"sizeBytes":237}],"systemPromptSnippet":"\n\n# AI Agent Protocol & Instructions\n\nPath: `AGENTS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/AGENTS.md)\n\n\n# References Skill\n\nPath: `.agents/skills/release/references/release-notes-v0.12.0.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.agents/skills/release/references/release-notes-v0.12.0.md)\n\n\n# References Skill\n\nPath: `.agents/skills/release/references/release-notes-v0.13.0.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.agents/skills/release/references/release-notes-v0.13.0.md)\n\n\n# References Skill\n\nPath: `.agents/skills/release/references/release-notes-v0.13.1.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/.agents/skills/release/references/release-notes-v0.13.1.md)\n\n\n---\nname: release-plannotator\ndescription: Prepare and execute a Plannotator release — draft release notes with full contributor credit, bump versions across all package files, build in dependency order, and kick off the tag-driven release pipeline. Use this skill whenever the user mentions preparing a release, bumping versions, writing release notes, tagging a release, or publishing. Also trigger when the user says things like \"let's ship\", \"prep a release\", \"what's changed since last release\", or \"time to cut a new version\".\n---\n\n# Plannotator Release\n\nThe process has four phases. Phase 1 (release notes) is where most of the work happens — present the draft for review before proceeding to later phases.\n\n## Phase 1: Draft Release Notes\n\nThis is the most important phase. The release notes are the public face of each version and the primary way the community sees their contributions recognized.\n\n### Step 1: Determine scope\n\n1. Find the latest release tag: `git tag --sort=-v:refname | head -1`\n2. Determine the new version number. Ask the user if unclear (patch, minor, or major).\n3. Gather all changes since the last tag:\n - `git log --oneline ..HEAD` for commit history\n - `git log --merges --oneline ..HEAD` for merged PRs\n4. For each PR, use `gh pr view --json title,author,body,closedIssues,labels` to get details.\n\n### Step 2: Research contributors\n\nThis is critical. Every person who participated in the release gets credit — not just PR authors.\n\nFor each PR and linked issue, collect:\n- **PR authors** — the person who wrote the code\n- **Issue reporters** — who filed the bug or feature request\n- **Issue commenters** — who participated in the discussion with useful context\n- **Discussion creators** — who started relevant GitHub Discussions\n- **Feature requestors** — check the linked \"closes #N\" issues and their authors\n\nUse the GitHub API via `gh`:\n```bash\n# Get issue details including author\ngh issue view --json author,title,body\n\n# Get issue comments to find participants\ngh api repos/backnotprop/plannotator/issues//comments --jq '.[].user.login'\n\n# Get PR review comments\ngh api repos/backnotprop/plannotator/pulls//comments --jq '.[].user.login'\n```\n\n### Step 3: Write the release notes\n\nRead the reference release notes in `references/` for the canonical template structure. These are real release notes from previous versions — match their tone, structure, and level of detail.\n\n- `release-notes-v0.13.0.md` — large release, 14 PRs, 3 first-time contributors, \"New Contributors\" + narrative \"Contributors\" section\n- `release-notes-v0.12.0.md` — large community release, 14 PRs, 10 external, detailed narrative \"Contributors\" section\n- `release-notes-v0.13.1.md` — small patch release, 2 PRs, no external authors, \"Community\" section focused on issue reporters\n\nPay attention to how each reference handles contributor crediting differently. Pick the pattern that fits the release's contributor profile — a release with many external PRs warrants a narrative \"Contributors\" section; a patch driven by issue reports uses a lighter \"Community\" section.\n\nWrite the file to the repo root as `RELEASE_NOTES_v.md`.\n\n#### Structure\n\n1. **X/Twitter follow link** — first line, always the same:\n ```\n Follow [@plannotator](https://x.com/plannotator) on X for updates\n ```\n\n2. **\"Missed recent releases?\"** collapsible table — copy from the previous release's notes, then:\n - Add the previous release (the one you're succeeding) as the newest row\n - Keep roughly 10-12 rows; drop the oldest if needed\n - Each row: version link + comma-separated feature highlights (short phrases)\n\n3. **\"What's New in vX.Y.Z\"** — the heart of the notes\n - Open with 1-3 sentences summarizing the release theme and scope. Mention how many PRs, how many from external contributors, any first-timers.\n - Each major feature/fix gets its own `###` subsection with:\n - A descriptive heading (not the PR title verbatim — rephrase for clarity)\n - 1-4 paragraphs explaining what changed and why it matters. Be specific and concrete. Describe the problem that existed before, what the change does, and how users experience it.\n - Credit line at the bottom: PR link, linked issues with `closing [#N]`, and contributor attribution\n - Minor changes go under `### Additional Changes` as bold-titled bullets\n\n4. **Install / Update** — standard block, read from the previous release notes and reuse verbatim\n\n5. **\"What's Changed\"** — bullet list of every PR in the release:\n ```\n - feat: descriptive PR title by @author in [#N](url)\n ```\n\n6. **\"New Contributors\"** — if any first-time contributors:\n ```\n - @username made their first contribution in [#N](url)\n ```\n\n7. **\"Contributors\" or \"Community\"** — narrative section recognizing everyone who participated:\n - PR authors get a sentence about what they built\n - Issue reporters and commenters get listed with what they reported/discussed\n - Group community issue reporters in a bullet list at the end\n\n8. **Full Changelog link**:\n ```\n **Full Changelog**: https://github.com/backnotprop/plannotator/compare/...\n ```\n\n#### Writing guidelines\n\n- **Narrative over noise.** Write in clear, readable prose. Not marketing-speak, not changelog-dump. Explain what changed and why someone should care, in plain language.\n- **Bullets where they help.** Use bullet lists for enumerating discrete items (additional changes, contributor lists). Use paragraphs for explaining features.\n- **No cliches or buzzwords.** Don't say \"exciting\", \"game-changing\", \"seamless\", \"powerful\". Just describe what happened.\n- **No punchlines.** Don't end sections with a clever quip or a summary zinger. Let the feature speak for itself.\n- **Speak through practical benefit.** Describe what changed and what it means for the user in concrete, reliable terms. Not aspirational, not hype — just what it does.\n- **Don't overuse em dashes.** One or two per release is fine. If you notice them stacking up, restructure the sentence instead.\n- **Grammatical structure matters.** Vary sentence structure. Active voice. Concrete subjects and verbs.\n- **Contributor tags.** Use `@username` — bare at-mentions, not markdown links like `[@user](url)`. GitHub renders bare `@mentions` with avatar icons in release notes. This is important for community recognition.\n- **Every contributor counts.** Everyone who filed an issue, left a comment that shaped a decision, or participated in a discussion gets mentioned. This project's community is its lifeblood.\n\n### Step 4: Present for review\n\nWrite the draft to `RELEASE_NOTES_v.md` in the repo root and tell the user it's ready for review. Do not `git add` or commit this file — release notes are kept untracked by design. Wait for their feedback before proceeding to Phase 2.\n\n---\n\n## Phase 2: Version Bump\n\nBump the version string in these **7 files** (and only these — other package.json files use stub versions):\n\n| File | Field |\n|------|-------|\n| `package.json` (root) | `\"version\"` |\n| `apps/opencode-plugin/package.json` | `\"version\"` |\n| `apps/pi-extension/package.json` | `\"version\"` |\n| `apps/hook/.claude-plugin/plugin.json` | `\"version\"` |\n| `apps/copilot/plugin.json` | `\"version\"` |\n| `openpackage.yml` (root) | `version:` |\n| `packages/server/package.json` | `\"version\"` |\n\nRead each file, confirm the current version matches expectations, then update all 7 atomically.\n\nDo not bump the VS Code extension (`apps/vscode-extension/package.json`) — it has independent versioning.\n\n---\n\n## Phase 3: Build\n\nRun builds in dependency order:\n\n```bash\nbun run build:review # 1. Code review editor (standalone Vite build)\nbun run build:hook # 2. Plan review + hook server (copies review's built HTML into hook dist)\nbun run build:opencode # 3. OpenCode plugin (copies built HTML from hook + review)\nbun run build:pi # 4. Pi extension (chains review → hook → pi internally, safe to run after 1-2)\n```\n\n`build:pi` chains review and hook internally, so after steps 1-2 it only runs the pi-specific build.\n\nVerify all builds succeed before proceeding.\n\n### Pi Parity Gate\n\nAfter builds pass, audit the Pi extension to ensure all server-side imports resolve in the published package. This catches missing files before they reach npm.\n\n1. **Check imports vs `files` array.** Trace all local imports (starting with `./` or `../`) from `index.ts`, `server.ts`, `tool-scope.ts`, and every file in `server/`. Verify each target is covered by a pattern in the `files` array of `apps/pi-extension/package.json`.\n\n2. **Check `vendor.sh` covers all shared/ai imports.** Every `../generated/*.js` import in the server files must have a corresponding entry in `vendor.sh`'s copy loops. If a new shared module or AI module was added to `packages/shared/` or `packages/ai/` and is imported by Pi's server code, it must be added to `vendor.sh`.\n\n3. **Dry-run the pack.** Run `cd apps/pi-extension && bun pm pack --dry-run` and verify the output includes every file the server imports. Look specifically for any newly added files since the last release.\n\n4. **Quick smoke test.** Confirm `generated/` contains all expected files after build, especially any new ones (e.g., a new shared module added in this release cycle).\n\nIf anything is missing, fix it before proceeding to Phase 4. Common fixes:\n- Add the file to `vendor.sh`'s copy loop\n- Add the file or directory to the `files` array in `package.json`\n- Add an import path fix (Pi uses `../generated/` not `@plannotator/shared` or `@plannotator/ai`)\n\n---\n\n## Phase 4: Commit, Tag, and Release\n\n1. **Commit the version bump:**\n ```\n chore: bump version to X.Y.Z\n ```\n Stage only the 7 version-bumped files. Do not stage the release notes file (it's untracked by design).\n\n2. **Create and push the tag:**\n ```bash\n git tag vX.Y.Z\n git push origin main\n git push origin vX.Y.Z\n ```\n The `v*` tag push triggers the release pipeline (`.github/workflows/release.yml`).\n\n3. **The pipeline handles everything else:**\n - Runs tests\n - Cross-compiles binaries for 6 platforms (macOS ARM64/x64, Linux x64/ARM64, Windows x64/ARM64)\n - Compiles paste service binaries (same 6 platforms)\n - Packs the two npm packages in a credential-free job\n - Downloads pinned, checksum-verified Syft and Grype binaries; generates and schema-validates the release-wide CycloneDX SBOM after all shipped subjects exist\n - Forces the repository-owned, suppression-free Grype configuration, retries the official database update up to three times, requires a valid/active schema-v6 database no more than 120 hours old with no pending update, and preserves the machine-readable scan/database/policy evidence as a workflow artifact\n - Rejects every scanner-side ignored match, then blocks before any attestation or publication on CISA KEV or fixable Critical findings classified as shipped/runtime or unknown-applicability. High, development-only, and no-fix Critical findings are report-only but remain in the evidence\n - Generates SLSA build provenance attestations for all 12 binaries via `actions/attest-build-provenance` (signed through Sigstore, recorded in Rekor)\n - Uses the separate official `actions/attest` SBOM path to bind the CycloneDX predicate to all 12 binaries and both npm tarballs through the same GitHub OIDC/Sigstore service. This is an inventory attestation, not a replacement for SLSA or npm provenance\n - Creates the GitHub Release with all binaries, SHA256 sidecars, the versioned CycloneDX SBOM, and its SHA256 sidecar attached\n - Publishes `@plannotator/opencode` and `@plannotator/pi-extension` to npm with provenance\n\n **SBOM scope:** the public document is a release-wide Syft inventory of the monorepo's locked build inputs and dependencies. It is deliberately not described as exact binary runtime contents. Coverage testing found that Bun standalone executables hide bundled JavaScript dependency metadata from Syft. The OpenCode tarball is similarly opaque; the Pi tarball exposes only a partial view through nested package-lock files. The scope and limitations are also embedded in the CycloneDX metadata.\n\n **Exceptions:** there is no active production exception file. If a future release baseline needs one, do not add a loose ignore. Add a repository-reviewed OpenVEX document and explicitly wire it through `PLANNOTATOR_RELEASE_VEX`; each statement must match one exact package URL and vulnerability ID and carry `not_affected` status, an OpenVEX justification, impact statement, HTTPS evidence, owner, created date, and expiration date. The policy tests reject expired, malformed, broad, and nonmatching records.\n\n **Note on immutable releases:** The repo has GitHub Immutable Releases enabled, so once the `v*` tag is pushed and the release is created, the tag→commit and tag→asset bindings are permanent. You cannot delete and re-create a tag to \"fix\" a bad release — you must ship a new version. Release notes remain editable (see step 5), but everything else is locked.\n\n4. **Monitor the pipeline:**\n Watch the release workflow run until it completes:\n ```bash\n gh run list --workflow=release.yml --limit=1\n gh run view --log\n ```\n Verify:\n - All jobs pass, including `release-security`, `attest`, `release`, and `npm-publish`\n - `release-security-evidence` records the Syft/Grype versions, active database schema/build/checksum/update status, all Grype matches, and an `ACCEPT` policy decision\n - The GitHub Release was created with all binary artifacts, SHA256 sidecars, the versioned `plannotator-X.Y.Z-release-sbom.cdx.json`, and its `.sha256` sidecar\n - npm packages published successfully (check with `npm view @plannotator/opencode version` and `npm view @plannotator/pi-extension version`)\n\n A pull request proves generation, schema/sentinel validation, database policy, Grype evaluation, least-privilege job wiring, and all report artifacts. GitHub OIDC issuance, publication to the artifact-attestation service, and final release-asset publication only run for a real eligible `v*` tag. For the first release after this control lands, complete this bounded tag-only verification before calling the rollout complete:\n\n Before tagging that first release, update the canonical Mintlify page at `https://docs.plannotator.ai/open-source/start/installation#pin-or-verify-a-release` with the SBOM scope/limitations, Grype policy, download/checksum commands, and both predicate-verification commands from the README. The legacy Astro files under `apps/marketing/src/content/docs/` are redirect-only/deprecated copies and are not the public documentation source. Confirm the live Mintlify page contains the material; do not let its publication lag the shipped control.\n\n ```bash\n tag=vX.Y.Z\n version=\"${tag#v}\"\n gh release download \"$tag\" --pattern 'plannotator-linux-x64*' --pattern \"plannotator-${version}-release-sbom.cdx.json*\" --dir /tmp/plannotator-release-verify\n (cd /tmp/plannotator-release-verify && sha256sum --check plannotator-linux-x64.sha256)\n (cd /tmp/plannotator-release-verify && sha256sum --check \"plannotator-${version}-release-sbom.cdx.json.sha256\")\n\n gh attestation verify /tmp/plannotator-release-verify/plannotator-linux-x64 \\\n --repo backnotprop/plannotator \\\n --source-ref \"refs/tags/$tag\" \\\n --signer-workflow backnotprop/plannotator/.github/workflows/release.yml \\\n --predicate-type https://slsa.dev/provenance/v1\n\n gh attestation verify /tmp/plannotator-release-verify/plannotator-linux-x64 \\\n --repo backnotprop/plannotator \\\n --source-ref \"refs/tags/$tag\" \\\n --signer-workflow backnotprop/plannotator/.github/workflows/release.yml \\\n --predicate-type https://cyclonedx.org/bom\n ```\n\n Also extract the attested CycloneDX predicate with `gh attestation verify --format json --jq '.[0].verificationResult.statement.predicate'`, canonicalize both it and the downloaded release SBOM with `jq -S`, and `cmp` them. Verify one npm tarball subject the same way if you download the exact published tarball. Record any tag-only discrepancy as a release blocker and ship a new version rather than mutating an immutable release.\n\n If anything fails, investigate the logs and report to the user before retrying.\n\n5. **Replace the release notes:**\n Once the release is live and verified, replace the auto-generated notes body with the drafted release notes:\n ```bash\n gh release edit vX.Y.Z --notes-file RELEASE_NOTES_v.md\n ```\n\n---\n\n## Checklist\n\nBefore tagging, verify:\n- [ ] All 7 version files bumped consistently\n- [ ] Release notes drafted and reviewed\n- [ ] `bun run build:review` succeeded\n- [ ] `bun run build:hook` succeeded\n- [ ] `bun run build:opencode` succeeded\n- [ ] `bun run build:pi` succeeded (or pi-specific build step)\n- [ ] Version bump committed\n- [ ] Pi parity gate passed (imports, vendor.sh, dry-run pack)\n- [ ] No stale build artifacts (clean builds, no cache issues — run `bun install` first if dependencies changed)\n- [ ] The PR-safe `release-security` job generated a schema-valid, sentinel-complete SBOM and accepted the Grype policy with a fresh database\n- [ ] No scanner binary, database, generated SBOM/report, credential, or `DO_NOT_COMMIT` content is staged\n- [ ] For the first SBOM-enabled release, the canonical Mintlify install/verification page contains the README's SBOM scope, policy, checksum, SLSA, and CycloneDX commands (do not edit the deprecated Astro docs instead)\n\nAfter tagging, verify:\n- [ ] Release workflow completed with `release-security`, `attest`, `release`, and `npm-publish` green\n- [ ] GitHub Release created with all binaries, sidecars, SBOM, and SBOM sidecar\n- [ ] One native binary passes both the explicit SLSA and CycloneDX predicate checks pinned to the tag and signer workflow\n- [ ] Downloaded SBOM checksum passes and canonical JSON matches the attested predicate\n- [ ] `release-security-evidence` shows a fresh/active database and an accepted policy decision\n- [ ] npm packages published at correct version\n- [ ] npm trusted-publishing provenance remains visible for both packages\n- [ ] Release notes replaced via `gh release edit`\n\n\n---\nname: review-renovate\ndescription: Review Renovate bot PRs that update GitHub Actions dependencies. Verifies supply chain integrity by checking pinned commit SHAs against upstream tagged releases, reviews changelogs for breaking changes, and confirms compatibility with existing workflow configurations. Use when a Renovate PR updates GitHub Actions in .github/workflows/.\n---\n\n# Review Renovate GitHub Actions PRs\n\nYou are reviewing a Renovate bot PR that updates GitHub Actions dependencies. Your job is to verify supply chain integrity and ensure the upgrades won't break CI/CD workflows.\n\n## Inputs\n\nYou will be given a PR number or URL. Use `gh` CLI to fetch PR details and diff.\n\n## Steps\n\n### 1. Fetch PR metadata and diff\n\n```\ngh pr view --json title,body,files,commits,author,headRefName\ngh pr diff \n```\n\nConfirm the PR author is `app/renovate`. If not, flag this immediately — it may not be an automated dependency update.\n\n### 2. Identify all action version changes\n\nFrom the diff, extract each changed action:\n- Full action name (e.g., `oven-sh/setup-bun`)\n- Old version tag and pinned SHA\n- New version tag and pinned SHA\n- Update type (patch, minor, major)\n\n### 3. Verify pinned SHAs against upstream tags\n\nFor every action being updated, verify **both old and new** SHAs match the claimed version tags:\n\n```\ngh api repos/{owner}/{repo}/git/ref/tags/{version} --jq '.object.sha'\n```\n\nCompare each result against the SHA in the workflow file. If any SHA does not match, **stop and report a supply chain integrity failure**. Do not approve the PR.\n\n### 4. Review changelogs for breaking changes\n\nFrom the PR body (Renovate includes release notes), check each updated action for:\n- Removed inputs or outputs that the workflows currently use\n- Changed default behavior for inputs the workflows rely on\n- New required inputs\n- Major version bumps (these almost always have breaking changes)\n\n### 5. Check workflow compatibility\n\nRead the affected workflow files and verify:\n- No removed or renamed inputs are being used\n- No changed defaults affect current behavior\n- The action's runtime requirements are still met (e.g., Node.js version compatibility)\n\n### 6. Report findings\n\nPresent a summary table:\n\n| Action | Old | New | Type | SHA verified |\n|--------|-----|-----|------|-------------|\n| ... | ... | ... | patch/minor/major | yes/NO |\n\nThen state:\n- Whether all SHAs are verified\n- Whether any breaking changes were found\n- Whether the workflows remain compatible\n- A clear **safe to merge** or **do not merge** recommendation\n\n\n---\nname: update-deps\ndescription: Audit and update npm/Bun dependencies with supply chain integrity checks — verifies maintainers, publish age, tarball diffs, and provenance before bumping. Defers risky packages to ~/.supply-chain/notes/.\ndisable-model-invocation: true\n---\n\n# Update Dependencies\n\nAudit outdated packages, verify supply chain integrity, bump what's safe, defer what needs review, and log everything.\n\nThis process has three phases: discovery, integrity audit, and execution. The integrity audit is the most important — every package gets checked before it touches the lockfile.\n\n## Phase 1: Discovery\n\nRun `bun outdated` to get the full list of packages with available updates.\n\n```bash\nbun outdated\n```\n\nParse the output into a structured list. For each package, note:\n- Package name\n- Current version\n- Available update version\n- Whether it's age-gated (indicated by `*` in the output — the footnote \"The * indicates that version isn't true latest due to minimum release age\" confirms this)\n- Whether it's a runtime dep, dev dep, or peer dep\n\nAlso check whether any packages are blocked entirely by the age gate (like `@pierre/diffs` was when its minimum semver range couldn't resolve). Flag these separately — they may need `minimumReleaseAgeExcludes` in `bunfig.toml`.\n\n## Phase 2: Integrity Audit\n\nThis is the core of the process. Spawn one **Sonnet sub-agent per package** to run the integrity check in parallel. Sonnet is used here because these are independent, structured verification tasks that don't need heavier reasoning.\n\nEach sub-agent receives the package name, current version, and target version, and performs the following checks:\n\n### Sub-agent prompt template\n\nFor each outdated package, spawn a Sonnet agent with this task:\n\n```\nYou are auditing the npm package \"{package}\" for a version bump from {current} to {target}.\n\nRun these checks and report back with a JSON object:\n\n1. **Maintainer verification**: Check if maintainers changed between versions.\n npm view {package}@{current} maintainers --json\n npm view {package}@{target} maintainers --json\n Compare the two lists. Flag any additions or removals.\n\n2. **Publish date and age**: Get the publish timestamp.\n npm view {package} time --json\n Extract the date for version {target}. Calculate days since publication.\n Flag if younger than 7 days.\n\n3. **Provenance**: Check if the package has registry signatures or attestations.\n npm audit signatures (if not already run this session)\n Note whether the package has provenance attestations.\n\n4. **Tarball diff**: Show what actually changed in the published package.\n npm diff --diff={package}@{current} --diff={package}@{target}\n Summarize the changes:\n - How many files changed\n - Are changes limited to version bumps, deps, and rebuilt dist? Or are there meaningful source changes?\n - Any new runtime dependencies added?\n - Any suspicious patterns (obfuscated code, eval(), network calls in unexpected places)\n\n5. **Release notes**: Try to find what changed.\n Check the package's repository for release notes or changelog:\n npm view {package}@{target} repository.url\n gh release view v{target} --repo (try with and without v prefix)\n Summarize the changelog if found.\n\nReport your findings as JSON:\n\n{{\n \"package\": \"{package}\",\n \"from\": \"{current}\",\n \"to\": \"{target}\",\n \"age_days\": ,\n \"maintainers_changed\": ,\n \"maintainers_added\": [],\n \"maintainers_removed\": [],\n \"provenance\": ,\n \"new_runtime_deps\": [],\n \"files_changed\": ,\n \"has_source_changes\": ,\n \"changelog_summary\": \"\",\n \"suspicious_patterns\": [],\n \"verdict\": \"safe\" | \"review\" | \"defer\",\n \"verdict_reason\": \"\"\n}}\n\nVerdict guidelines:\n- \"safe\": Same maintainers, no new runtime deps, changes match what changelog describes, no suspicious patterns\n- \"review\": Minor concerns (e.g., new maintainer who is clearly from the same org, small new dep from known publisher)\n- \"defer\": Maintainer changes from unknown accounts, new runtime deps with unclear purpose, suspicious code patterns, substantive API changes that need integration testing\n```\n\n### Collecting results\n\nAs sub-agents complete, collect their JSON reports. If a sub-agent fails or times out, mark that package as \"defer\" with reason \"audit failed\".\n\n### Tier classification\n\nAfter collecting all results, classify packages into tiers. This helps the user understand the risk profile at a glance:\n\n| Tier | Description | Typical action |\n|------|-------------|----------------|\n| **Runtime, high surface** | Libraries your code calls directly (parsers, diff engines, UI libs) | Check provenance, review diff, run tests |\n| **SDK/API deps** | Third-party service SDKs (agent SDKs, platform integrations) | Read changelog for API changes, test integration |\n| **Dev-only** | Type definitions, build tools, test frameworks | Update freely — these don't ship |\n| **Build toolchain** | Bun itself, compilers, bundlers | Most caution — breakage affects all outputs |\n\n## Phase 3: Execution\n\n### Bump safe packages\n\nFor all packages with verdict \"safe\":\n\n```bash\nbun update pkg1@version1 pkg2@version2 ...\n```\n\nIf the update fails due to age gate conflicts (a package's minimum semver can't resolve), add it to `minimumReleaseAgeExcludes` in `bunfig.toml` and document why.\n\n### Log to supply chain notes\n\nWrite the full audit results to `~/.supply-chain/notes/.json`:\n\n```json\n{\n \"date\": \"YYYY-MM-DD\",\n \"project\": \"plannotator\",\n \"bumped\": [\n {\n \"package\": \"...\",\n \"from\": \"...\",\n \"to\": \"...\",\n \"age_days\": 0,\n \"maintainers_changed\": false,\n \"provenance\": false,\n \"notes\": \"...\"\n }\n ],\n \"deferred\": [\n {\n \"package\": \"...\",\n \"current\": \"...\",\n \"available\": \"...\",\n \"age_days\": 0,\n \"maintainers_changed\": false,\n \"reason\": \"...\",\n \"review_by\": \"YYYY-MM-DD\"\n }\n ],\n \"excluded_from_age_gate\": [\n {\n \"package\": \"...\",\n \"reason\": \"...\"\n }\n ]\n}\n```\n\nSet `review_by` to 7 days from today for deferred packages.\n\n### Check previously deferred packages\n\nRead all files in `~/.supply-chain/notes/` and collect any deferred packages from previous audits that are still at the same version in the current lockfile. These are packages that were deferred before and still haven't been updated.\n\nTo check: for each previously deferred entry, see if the current installed version matches the `current` field from the deferral note. If it does, the package is still deferred.\n\n## Phase 4: Recap\n\nPresent a clear summary to the user:\n\n### Updated\nList each bumped package with version change and one-line reason it was safe.\n\n### Deferred\nList each deferred package with version change and reason for deferral.\n\n### Still Deferred (from previous audits)\nList any packages that were deferred in previous audit sessions and still haven't been bumped. Include the original deferral date and reason. This is the \"you've been putting this off\" section — it keeps deferred packages from being forgotten.\n\nIf the still-deferred list is empty, say so — that's a good sign.\n\n### Age Gate Exclusions\nIf any packages were added to `minimumReleaseAgeExcludes`, note them and why.\n\n\n# Agents Skill\n\nPath: `apps/kiro-cli/agents/plannotator.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/kiro-cli/agents/plannotator.json)\n\n\n# plannotator-annotate\n\nPath: `apps/kiro-cli/skills/plannotator-annotate/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/kiro-cli/skills/plannotator-annotate/SKILL.md)\n\n\n# plannotator-review\n\nPath: `apps/kiro-cli/skills/plannotator-review/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/kiro-cli/skills/plannotator-review/SKILL.md)\n\n\n# plannotator-annotate\n\nPath: `apps/skills/claude/plannotator-annotate/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/claude/plannotator-annotate/SKILL.md)\n\n\n---\nname: plannotator-last\ndescription: Open Plannotator on the latest rendered assistant message and use the returned annotations to revise that message or continue.\nallowed-tools: Bash(plannotator:*)\ndisable-model-invocation: true\n---\n\n# Plannotator Last\n\n## Message annotations\n\n!`plannotator annotate-last $ARGUMENTS`\n\n## Your task\n\nThe output above will be one of:\n\n1. The exact text `The user approved.`, an \"Approved with Notes\" message, OR a JSON object with `\"decision\": \"approved\"`. The user approved your last message. If it is the Approved with Notes message, or that object also carries a `\"feedback\"` field, the user approved *with notes*: read them and carry them into subsequent work — they are non-blocking guidance, not a request to revise the message. Otherwise acknowledge with a single sentence (\"Approved.\") and stop. Either way, do not begin any work.\n2. Empty, OR a JSON object with `\"decision\": \"dismissed\"`. The user closed the session without requesting changes. Acknowledge with a single sentence (\"Annotation session closed.\") and stop. Do not begin any work.\n3. Plaintext annotation feedback, OR a JSON object with `\"decision\": \"annotated\"` and a `\"feedback\"` field. Address the feedback. The user has reviewed your last message and provided specific annotations and comments.\n\n\n---\nname: plannotator-review\ndescription: Open Plannotator's browser-based code review UI for the current worktree, another directory, or a pull request URL, then act on the feedback that comes back.\nallowed-tools: Bash(plannotator:*)\ndisable-model-invocation: true\n---\n\n# Plannotator Review\n\nArguments pass through to `plannotator review`: one directory or PR/MR URL, `--git` / `--gitbutler`, and the session-only open-state flags `--base ` / `--diff-type ` (git-only; for a stacked branch, `--base ` reviews just that layer).\n\nFor another repository or worktree, pass its path relative to this session or an absolute path, e.g. `/plannotator-review ../feature-worktree`. Quote paths containing spaces. Supply a target, not prose; feedback names the directory where changes belong.\n\n## Code review feedback\n\n!`plannotator review $ARGUMENTS`\n\n## Your task\n\nIf the review above contains feedback or annotations, address them in the same conversation. If no changes were requested (an approval/LGTM-style result), acknowledge that review passed and continue.\n\nIf the review was moved to the background, wait for it to finish. If Claude Code stopped it at its background time limit before the user decided, tell the user, and only when they ask, run `plannotator review $ARGUMENTS` again with `run_in_background` and `timeout: 7200000`: their annotations are restored from the saved draft.\n\n\n# Agents Skill\n\nPath: `apps/skills/core/plannotator-annotate/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/core/plannotator-annotate/agents/openai.yaml)\n\n\n---\nname: plannotator-annotate\ndescription: Open Plannotator's annotation UI for a markdown file, plain-text config file (.yaml, .json, .toml, .ini, .csv, .log, …), HTML file, URL, or folder and then respond to the returned annotations.\ndisable-model-invocation: true\n---\n\n# Plannotator Annotate\n\nUse this skill when the user wants to annotate a document in Plannotator instead of reviewing it inline in chat.\n\nRun for ordinary annotation/feedback:\n\n```bash\nplannotator annotate \n```\n\nRun when the user asks to review, approve, accept, or gate a generated plan/spec/document:\n\n```bash\nplannotator annotate --gate --json\n```\n\nPlain `annotate` has no **Approve** button; it only supports feedback or closing the session. Never promise an approval action unless `--gate` is present. `--json` only changes the output format and does not enable approval by itself.\n\nBehavior:\n\n1. Launch the command with Bash.\n2. Wait for the browser review to finish.\n3. If annotations are returned, address them directly.\n4. If the session closes without feedback, say so briefly and continue.\n5. In a `--gate` session, an approval may still carry notes — a `\"decision\": \"approved\"` result with a\n `\"feedback\"` field (without `--json`, an \"Approved with Notes\" message). Read those notes and carry them into subsequent work, but\n do not revise the document over them: they are guidance, not a change request.\n6. If the command reports that the arguments could not be resolved to a file,\n URL, or folder, work out which target the user means and re-run the command\n yourself with that concrete path or URL.\n\nDo not ask the user to paste a shell command into the chat. Run the command yourself.\n\n\n# Agents Skill\n\nPath: `apps/skills/core/plannotator-last/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/core/plannotator-last/agents/openai.yaml)\n\n\n---\nname: plannotator-last\ndescription: Open Plannotator on the latest rendered assistant message and use the returned annotations to revise that message or continue.\ndisable-model-invocation: true\n---\n\n# Plannotator Last\n\nUse this skill when the user wants to annotate the latest assistant response in Plannotator.\n\nDo not send a commentary/status message before running the command. The command\ntargets the latest rendered assistant response, so a preamble can mistakenly become the\nthing being annotated.\n\nRun:\n\n```bash\nplannotator last\n```\n\nBehavior:\n\n1. Launch the command with Bash.\n2. Wait for the annotation session to finish.\n3. If feedback is returned, incorporate it into the follow-up response.\n4. If the session closes without feedback, mention that briefly and continue.\n5. An approval may still carry notes — a `\"decision\": \"approved\"` result with a\n `\"feedback\"` field. Read those notes and carry them into subsequent work, but\n do not redo the message over them: they are guidance, not a change request.\n\nRun the command yourself rather than telling the user to invoke shell syntax manually.\n\n\n# Agents Skill\n\nPath: `apps/skills/core/plannotator-review/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/core/plannotator-review/agents/openai.yaml)\n\n\n---\nname: plannotator-review\ndescription: Open Plannotator's browser-based code review UI for the current worktree, another directory, or a pull request URL, then act on the feedback that comes back.\ndisable-model-invocation: true\n---\n\n# Plannotator Review\n\nUse this skill when the user wants to review current code changes in Plannotator instead of reading a diff inline.\n\nRun:\n\n```bash\nplannotator review [--base ] [--diff-type ] [directory-or-pr-url]\n```\n\nReviewing one layer of a stacked branch? Pass `--base ` so the review shows only what this layer adds, instead of everything since `main`. Both flags are session-only (the reviewer can change either in the UI; nothing is persisted) and git-only.\n\nTo review another repository or worktree, pass its directory (relative to the current session or absolute), e.g. `plannotator review ../feature-worktree`. Quote paths containing spaces. Feedback names the selected directory; apply changes there.\n\nBehavior:\n\n1. Launch the command with Bash.\n2. Wait for it to finish.\n3. If it returns feedback or annotations, address them in the same conversation.\n4. If it returns an approval/LGTM-style message, acknowledge that review passed and continue.\n\nDo not ask the user to copy shell commands into chat. Run the command yourself.\n\n\n# References Skill\n\nPath: `apps/skills/extra/plannotator-compound/references/claude-code-fallback.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-compound/references/claude-code-fallback.md)\n\n\n---\nname: plannotator-compound\ndisable-model-invocation: true\ndescription: >\n Analyze a user's Plannotator plan archive to extract denial patterns, feedback\n taxonomy, evolution over time, and actionable prompt improvements — then produce\n a polished HTML dashboard report. Falls back to Claude Code ExitPlanMode denial\n reasons when Plannotator data is unavailable.\n---\n\n# Compound Planning Analysis\n\nYou are conducting a comprehensive research analysis of a user's Plannotator plan\narchive. The goal: extract patterns from their denied plans, reduce\nthem into actionable insights, and produce an elegant HTML dashboard report.\n\nThis is a multi-phase process. Each phase must complete fully before the next begins.\nResearch integrity is paramount — every file must be read, no skipping.\n\n## Source Selection\n\nBefore starting the analysis, determine which data source is available.\n\n1. **Plannotator mode (first-class)** — Determine the Plannotator data directory:\n use `$PLANNOTATOR_DATA_DIR` if set, otherwise `~/.plannotator`. Check the\n `plans/` subdirectory there. If it exists and contains `*-denied.md` files,\n use this mode. The entire workflow below is written for Plannotator data.\n\n2. **Claude Code fallback mode** — If the Plannotator archive is absent or\n contains no denied plans, check `~/.claude/projects/`. If present, read\n [references/claude-code-fallback.md](references/claude-code-fallback.md)\n before continuing. That reference explains how to use the bundled parser at\n [scripts/extract_exit_plan_mode_outcomes.py](scripts/extract_exit_plan_mode_outcomes.py)\n to extract denial reasons from Claude Code JSONL transcripts. Every phase\n below has a short note explaining what changes in fallback mode — the\n reference file has the details.\n\n3. **Neither available** — Ask the user for their Plannotator plans directory or\n Claude Code projects directory. Do not guess.\n\n## Phase 0: Locate Plans & Check for Previous Reports\n\nUse the mode chosen in Source Selection above.\n\n**Plannotator mode:** Verify the plans directory contains `*-denied.md` files. If\nnone exist, fall back to Claude Code mode before stopping.\n\n**Claude Code fallback mode:** Run the bundled parser per the fallback reference to\nbuild the denial-reason dataset. Create `/tmp/compound-planning/` if needed.\n\nIn either mode, proceed to Previous Report Detection below.\n\n### Previous Report Detection\n\nAfter locating the plans directory, check for existing reports:\n\n```\nls ${PLANNOTATOR_DATA_DIR:-~/.plannotator}/plans/compound-planning-report*.html\n```\n\nReports follow a versioned naming scheme:\n- First report: `compound-planning-report.html`\n- Subsequent reports: `compound-planning-report-v2.html`, `compound-planning-report-v3.html`, etc.\n\nIf one or more reports exist, determine the **latest** one (highest version number).\nGet its filesystem modification date using `stat` (macOS: `stat -f %Sm -t %Y-%m-%d`,\nLinux: `stat -c %y | cut -d' ' -f1`). This is the **cutoff date**.\n\nPresent the user with a choice:\n\n> \"I found a previous report (`compound-planning-report-v{N}.html`) last updated\n> on {CUTOFF_DATE}. I can either:\n>\n> 1. **Incremental** — Only analyze files dated after {CUTOFF_DATE}, saving tokens\n> and building on previous findings\n> 2. **Full** — Re-analyze the entire archive from scratch\n>\n> Which would you prefer?\"\n\nWait for the user's response before proceeding.\n\n**If incremental:** Filter all subsequent phases to only process files with dates\nafter the cutoff date. The new report version will note in its header narrative that\nit covers the period from {CUTOFF_DATE} to present, and reference the previous\nreport for earlier findings. The inventory (Phase 1) should still count ALL files\nfor overall stats, but clearly separate \"new since last report\" counts.\n\n**If full:** Proceed normally with all files, but still use the next version number\nfor the output filename.\n\n**If no previous report exists:** Proceed normally. The output filename will be\n`compound-planning-report.html` (no version suffix for the first report).\n\n## Phase 1: Inventory\n\nCount and report the dataset. **Always count ALL files** for overall stats,\nregardless of whether this is an incremental or full run:\n\n```\n- *-approved.md files (count)\n- *-denied.md files (count)\n- Date range (earliest to latest date found in filenames)\n- Total days spanned\n- Revision rate: denied / (approved + denied) — this is the \"X% of plans\n revised before coding\" stat used in dashboard section 1\n```\n\n**Note:** Ignore `*.annotations.md` files entirely. Denied files already contain\nthe full plan text plus all reviewer feedback appended after a `---` separator.\nAnnotation files are redundant subsets of this content — reading both would\ndouble-count feedback.\n\n**If incremental mode:** After the total counts, separately report the counts for\nfiles dated after the cutoff date only:\n\n```\nNew since {CUTOFF_DATE}:\n- *-denied.md files: X (of Y total)\n- New date range: {CUTOFF_DATE} to {LATEST_DATE}\n- New days spanned: N\n```\n\nIf fewer than 3 new denied files exist since the cutoff, warn the user:\n> \"Only {N} new denied plans since the last report. The incremental analysis may\n> be thin. Would you like to proceed or switch to a full analysis?\"\n\nAlso run `wc -l` across all `*-approved.md` files to get average lines per\napproved plan. This tells the user whether their plans are staying lightweight\nor bloating over time. You do not need to read approved plan contents — just\ntheir line counts. If possible, break this down by time period (e.g., monthly)\nto show whether plan size changed.\n\nDates appear in filenames in YYYY-MM-DD format, sometimes as a prefix\n(2026-01-07-name-approved.md) and sometimes embedded (name-2026-03-15-approved.md).\nExtract dates from all filenames.\n\nTell the user what you found and that you're beginning the extraction.\n\n**Claude Code fallback mode:** The Plannotator inventory fields above do not apply.\nFollow the inventory instructions in\n[references/claude-code-fallback.md](references/claude-code-fallback.md) instead —\nreport the denial-reason dataset assembled by the parser.\n\n## Phase 2: Map — Parallel Extraction\n\nThis is the most time-intensive phase. You must read EVERY `*-denied.md` file\n**in scope**. Do not skip files. Do not summarize early.\n\n**In scope** means: all denied files if running a full analysis, or only denied\nfiles dated after the cutoff date if running incrementally. In incremental mode,\nonly process files whose embedded YYYY-MM-DD date is strictly after the cutoff.\n\n**Claude Code fallback mode:** The parser output is the clean source dataset. Read\nthe fallback reference for the extraction prompt and batching strategy specific to\nJSON part files. Do not go back to raw `.jsonl` logs unless the parser fails or the\nuser asks for audit-level verification.\n\n**Important:** Only read `*-denied.md` files. Do NOT read approved plans,\nannotation files, or diff files. Each denied file contains the full plan text\nfollowed by a `---` separator and the reviewer's feedback — everything needed\nfor analysis is in one file.\n\n### Batching Strategy\n\nAll extraction agents should use `model: \"haiku\"` — they're doing straightforward\nfile reading and structured extraction, not reasoning. Haiku is faster and cheaper\nfor this work.\n\nThe approach depends on dataset size:\n\n**Tiny datasets (≤ 10 total files):** Read all files directly in the main agent —\nno need for sub-agents. Just read them sequentially and proceed to Phase 3.\n\n**Small datasets (11-30 files):** Launch 2-3 parallel Haiku agents, splitting\nfiles roughly evenly.\n\n**Medium datasets (31-80 files):** Launch 4-6 parallel Haiku agents (~10-15 files\neach). Split by file type and/or time period.\n\n**Large datasets (80+ files):** Launch as many parallel Haiku agents as needed to\nkeep each batch around 10-15 files. Split by the natural time boundaries in the\ndata (months, quarters, or whatever groupings produce balanced batches). If one\ntime period dominates (e.g., the most recent month has 3x the files), split that\nperiod into multiple batches.\n\nLaunch all extraction agents in parallel using the Agent tool with\n`run_in_background: true` and `model: \"haiku\"`.\n\n### Output Files\n\nEach extraction agent must write its results to a clean output file rather than\nrelying on the agent task output (which contains interleaved JSONL framework\nlogs that are difficult to parse). Instruct each agent to write to:\n\n```\n/tmp/compound-planning/extraction-{batch-name}.md\n```\n\nCreate the `/tmp/compound-planning/` directory before launching agents. The\nreduce agent in Phase 3 will read these clean files directly.\n\n### Extraction Prompt\n\nEach agent receives this instruction (adapt the time period, file list, and\noutput path):\n\n```\nYou are extracting structured data from denied plan files for a pattern analysis.\n\nDirectory: [PLANS DIRECTORY]\nFiles to read: [LIST OF SPECIFIC *-denied.md FILES]\nOutput: Write your complete results to [OUTPUT FILE PATH]\n\nEach denied file contains two parts separated by a --- line:\n1. The plan text (above the ---)\n2. The reviewer's feedback and annotations (below the ---)\n\nRead EVERY file in your list. For EACH file, extract:\n- The plan name/topic (from the plan text above the ---)\n- The denial reason or feedback given (from below the --- — capture the actual\n words used)\n- What was specifically asked to change\n- The type of feedback (let the content determine the category — don't force-fit\n into predefined types. Common types include things like: scope concerns,\n approach disagreements, missing information, process requirements, quality\n concerns, UX/design issues, naming disputes, clarification requests,\n testing/procedural denials — but the user's actual patterns may differ)\n- Any specific phrases or recurring language from the reviewer\n- Individual annotations if present (numbered feedback items with quoted text\n and reviewer comments)\n- The date (extracted from the filename)\n\nDo NOT skip any files. One entry per file.\n\nFormat each entry as:\n**[filename]**\n- Date: ...\n- Topic: ...\n- Denial reason: ...\n- Feedback type: ...\n- Specific asks: ...\n- Notable phrases: ...\n- Annotations: [count, with brief summary of each]\n---\n\nAfter processing all files, write the complete results to [OUTPUT FILE PATH].\nState the total file count at the end of the file.\n```\n\n### While Agents Run\n\nTrack completion. As each agent finishes, note the count of files it processed.\nVerify the total matches the inventory from Phase 1. If any agent's count is\nshort, flag it and consider re-launching for the missing files.\n\nIf an agent times out (possible with large batches — a batch of 128 files can\ntake 8+ minutes), re-launch it for just the unprocessed files. Check the output\nfile to see how far it got before timing out.\n\n## Phase 3: Reduce — Pattern Analysis\n\nOnce ALL extraction agents have completed (or all files have been read for tiny\ndatasets), proceed with the reduction. Reduction agents should use `model: \"sonnet\"`\n— this phase requires real analytical reasoning, not just file reading.\n\n### Reduction Strategy\n\nThe approach depends on how many extraction files were produced:\n\n**Standard (≤ 20 extraction files):** Launch a single Sonnet agent to read all\nextraction files and produce the full analysis. This covers most datasets.\n\n**Large (21+ extraction files):** Use a two-stage reduce:\n\n1. **Stage 1 — Partial reduces:** Split the extraction files into groups of 4-6.\n Launch parallel Sonnet agents, each reading one group and producing a partial\n analysis with the same sections listed below. Each writes to\n `/tmp/compound-planning/partial-reduce-{N}.md`.\n\n2. **Stage 2 — Final reduce:** A single Sonnet agent reads all partial reduce\n files and synthesizes them into the final comprehensive analysis. This agent\n merges taxonomies, combines counts, deduplicates patterns, and reconciles any\n conflicting categorizations across partials.\n\n**Claude Code fallback mode:** The reduction phase is the same. The only upstream\ndifference is that extraction files were derived from normalized denial-reason JSON\ninstead of Plannotator markdown files.\n\n### Reduction Prompt\n\nGive each reduction agent this prompt (adapt file paths for single vs multi-stage):\n\n```\nYou are a data scientist conducting the reduction phase of a map-reduce analysis\nacross a user's denied plan archive.\n\nRead ALL extraction files at [FILE PATHS]\n\nThese files contain structured extractions from every denied plan file. Each\nextraction includes the plan topic, denial feedback, annotations, and reviewer\nlanguage. Your job: aggregate everything, find patterns, cluster into a taxonomy,\nand produce a comprehensive analysis.\n\nBe exhaustive. Use real counts. Quote real phrases from the data. This is\nresearch — no hand-waving, no fabrication.\n\nWrite your complete results to [OUTPUT FILE PATH].\n\nProduce the following sections:\n[... sections listed below ...]\n```\n\nThe reduction agent's job is to let the data speak. Do not impose a predetermined\nframework — discover what's actually there. The analysis must produce:\n\n### 1. Denial Reason Taxonomy\nCategorize every denial into a finite set of types that emerge from the data. Count\noccurrences. Show percentages. Include real example quotes for each type. Aim for\n8-15 categories — enough to be specific, few enough to be scannable. Let the user's\nactual feedback determine what the categories are.\n\n### 2. Top Feedback Patterns (ranked by frequency)\nThe 5-10 most recurring patterns. For each: what the reviewer consistently asks for,\n3+ example quotes from different files, and whether the pattern changed over time.\n\n### 3. Recurring Phrases\nExact phrases the reviewer uses repeatedly, with counts and what they signal. These\nare the reviewer's vocabulary — their shorthand for what they care about.\n\n### 4. What the Reviewer Values (implicit preferences)\nDerived from patterns — what does this specific person care about most? Quality?\nSpeed? Narrative? Architecture? Process? Simplicity? Rank by evidence strength.\nThis section should feel like a personality profile of the reviewer's standards.\n\n### 5. What Agents Consistently Get Wrong\nThe flip side — what recurring mistakes trigger denials? What should agents stop\ndoing for this reviewer?\n\n### 6. Structural Requests\nWhat plan structure does the reviewer consistently demand? Required sections,\nordering, format preferences, level of detail expected.\n\n### 7. Evolution Over Time\nHow feedback patterns changed across the time span. Group by whatever natural time\nboundaries exist in the data (weeks for short spans, months for longer ones). Did\nexpectations mature? Did new patterns emerge? What shifted? If the dataset spans\nless than a month, note that evolution analysis is limited but still look for any\nprogression from early to late files.\n\n### 8. Actionable Prompt Instructions\nThe most important output. Based on all patterns: specific numbered instructions\nthat could be embedded in a planning prompt to prevent the most common denial\nreasons. Write these as actual directives an agent could follow. Be specific to\nthis user's patterns — generic advice like \"write good plans\" is worthless. Each\ninstruction should trace back to a real, frequent denial pattern.\n\nAfter writing the instructions, calculate what percentage of denials they would\naddress (count how many denials fall into categories covered by the instructions\nvs total denials). Report this percentage — it will be different for every user.\n\n## Phase 4: Generate the HTML Dashboard\n\nBuild a single, self-contained HTML file as the final deliverable. Save it to\nthe user's plans directory with a versioned filename:\n\n- First ever report: `compound-planning-report.html`\n- Second report: `compound-planning-report-v2.html`\n- Third report: `compound-planning-report-v3.html`\n- And so on.\n\nThe version number was determined in Phase 0 based on existing reports found.\n\n**If this is an incremental report**, the header should indicate the analysis\nperiod (e.g., \"March 15 – March 31, 2026\") and include a subtitle noting\n\"Incremental analysis — see v{N-1} for earlier findings.\" The narrative in\nsection 1 should frame findings as what's new or changed since the last report,\nnot as a complete picture. Overall stats in the header (file counts, revision\nrate) should still reflect the full archive for context.\n\nRead the template at `assets/report-template.html` for the **design language\nonly**. The template contains example data from a previous analysis — ignore all\ndata values, quotes, and percentages in the template. Use only its visual design:\ncolors, typography, spacing, component styles, and layout patterns.\n\n### Design Language (from template)\n\n- **Palette:** Light mode, warm off-white (#FDFCFB), text in slate scale, amber\n for highlights/accents, emerald for positive, rose for negative, indigo for\n action elements\n- **Typography:** Playfair Display (serif, for narrative headings), Inter (sans,\n for body/data), JetBrains Mono (mono, for code/phrases) — Google Fonts CDN\n- **Layout:** Single-column, max-width 1024px, generous vertical whitespace (128px\n between major sections), editorial/narrative-first aesthetic\n- **Tone:** Calm, reflective, authoritative. Like a personal retrospective journal,\n not a monitoring dashboard.\n\n### Page Frame (header + footer)\n\nBefore the 7 sections, the page has:\n\n- **Header:** Report title on the left (Playfair Display, ~36px), project name +\n date range below it in light meta text. On the right: file counts in mono\n (e.g., \"223 denials · 71 days\"). Separated from content by\n a bottom border. Generous bottom padding before section 1.\n\n- **Footer:** After section 7. Top border, centered italic Playfair Display tagline\n summarizing the corpus (e.g., \"Analysis of X denied plans from the Plannotator\n archive.\").\n\n### Dashboard Section Order (7 sections)\n\nThe report follows this exact section order. Each section builds on the previous\none — the flow moves from \"what happened\" through \"why\" to \"what to do about it\":\n\n1. **The story in the data** — An editorial narrative paragraph (Playfair Display\n serif, ~26px) that tells the headline finding in prose. Not bullet points — a\n real paragraph that reads like the opening of an article. Alongside it, a KPI\n sidebar with 3 key metrics (the top denial percentage, the overall revision\n rate, and the number of distinct denial categories found). Use an amber inline\n highlight on the most striking number in the narrative.\n\n2. **Why plans get denied** — The taxonomy as a ranked list. Each row: rank number\n (mono), category label, a thin 4px progress bar (top item in amber-500, rest\n in slate-300), percentage (mono), and for the top entries, a real italic quote\n from the data below the label. Show the top 10 categories or however many the\n data supports (minimum 5).\n\n3. **How expectations evolved** — One card per natural time period. Each card has:\n the period name in serif, a theme phrase in colored uppercase (different color\n per period to show progression), a description paragraph, and a stat line at\n the bottom (e.g., \"X denials · Y narrative requests\"). If the data spans less\n than 3 distinct periods, use 2 cards or even a single card with internal\n progression noted.\n\n4. **What works vs what doesn't** — Two side-by-side cards. Left: green-tinted\n (emerald-50/50 bg, emerald-100 border) with traits of plans that succeed for\n this reviewer. Right: red-tinted (rose-50/50 bg, rose-100 border) with what\n agents keep getting wrong. Both derived from the reduction analysis. Bulleted\n with small colored dots. 5-8 items per card.\n\n5. **The actionable output** — The diagnostic payoff. Opens with a Playfair\n Display narrative sentence stating how many prompt instructions were derived\n and what estimated percentage of denials they address (use the real calculated\n percentage from Phase 3, not a generic number). Then the top 3 most impactful\n improvements as numbered items, each with an amber number, bold title, and\n one-line description. This section bridges the analysis and the full prompt\n that follows.\n\n6. **Your most-used phrases** — Grid of chips (2-col mobile, 3-col desktop). Each\n chip: monospace quoted phrase on the left, frequency count on the right. White\n bg, slate-200 border, rounded-12px. Show 9-12 of the most recurring phrases\n found. These should be the reviewer's actual words — their verbal fingerprint.\n\n7. **The corrective prompt** — Dark panel (slate-900 bg, white text, rounded-3xl,\n shadow-xl). Opens with a Playfair intro sentence about the instructions. Then\n a dark code block (slate-800/80 bg, amber-200 monospace text) containing the\n full numbered prompt instructions from Phase 3. Include a copy-to-clipboard\n button that works (JS included). Below the code block: a gradient glow card\n (indigo-to-purple blurred halo behind a white card) with a closing message\n that these instructions are personal — derived from the user's own feedback,\n their own language, their own standards.\n\n### Adaptation Rules\n\n- If the user has < 3 months of data, reduce the evolution section to fewer cards\n- If most denied files lack feedback below the `---` (bare denials with no\n annotations), note this in the narrative — the analysis will be thinner\n- **Claude Code fallback mode:** Explicitly label the report source as Claude Code\n `ExitPlanMode` denial reasons. Do not fabricate Plannotator-only fields such as\n annotation counts or approved-plan line counts. See the fallback reference for\n KPI substitutes and footer/provenance guidance.\n- If fewer than 5 denial categories emerge, combine the taxonomy and patterns\n sections into one\n- If the dataset is very small (< 20 files), the narrative should acknowledge the\n limited sample size and frame findings as preliminary\n- The number of prompt instructions will vary per user — could be 8 or 20. Don't\n force exactly 17. Let the data determine the count.\n- The top 3 actionable items in section 5 must be the 3 that cover the largest\n share of denials, not the 3 that sound most impressive\n\n### Key Rules\n\n1. Every number must come from the real analysis — no fabricated data\n2. Every quote must be a real quote from a real file\n3. The taxonomy percentages must be calculated from real counts\n4. The prompt instructions must trace back to actual denial patterns\n5. The copy button on the prompt block must work (include the JS)\n\nAfter generating, open the file in the user's browser.\n\n## Phase 5: Summary\n\nTell the user:\n- How many denied files were analyzed\n- If incremental: how many were new since the last report\n- The top 3 denial patterns found\n- The estimated percentage of denials the prompt instructions would address\n- The single most impactful prompt improvement\n- Where the report was saved (including version number)\n- If incremental: remind the user that earlier findings are in the previous report\n\n**Claude Code fallback mode:** Adapt the summary per the fallback reference —\nreport human denial reasons analyzed and total `ExitPlanMode` attempts scanned\ninstead of Plannotator file counts.\n\n## Phase 6: Improvement Hook\n\nAfter presenting the summary, ask the user if they want to enable an **improvement\nhook** — this takes the corrective prompt instructions from section 7 of the report\nand writes them to a file that Plannotator's `EnterPlanMode` hook can inject into\nevery future planning session automatically.\n\n> \"Would you like to enable the improvement hook? This will save the corrective\n> prompt instructions to a file that gets automatically injected into all future\n> planning sessions — so Claude sees your feedback patterns before writing any plan.\"\n\n**If yes:**\n\nThe hook file lives at:\n\n```\n${PLANNOTATOR_DATA_DIR:-~/.plannotator}/hooks/compound/enterplanmode-improve-hook.txt\n```\n\nCreate the `hooks/compound/` directory inside the data directory if it doesn't exist.\n\nThe file contents should be the corrective prompt instructions from Phase 3 —\nthe same numbered list that appears in section 7 of the HTML report. Write them\nas plain text, one instruction per line, prefixed with their number. No HTML, no\nmarkdown fences, no preamble — just the instructions themselves. The hook system\nwill inject this file's contents as-is into the planning context.\n\n**If the file already exists:**\n\nRead the existing file and present the user with a choice:\n\n> \"An improvement hook already exists from a previous analysis. I can:\n>\n> 1. **Replace** — Overwrite with the new instructions (the old ones are gone)\n> 2. **Merge** — Combine both, deduplicating overlapping instructions and\n> keeping the best version of each\n> 3. **Keep existing** — Leave the current hook as-is, skip this step\n>\n> Which would you prefer?\"\n\n- **Replace:** Overwrite the file with the new instructions.\n- **Merge:** Read the existing instructions, compare with the new ones, and\n produce a merged set. Remove duplicates (same intent even if worded differently).\n When two instructions cover the same pattern, keep the more specific or\n actionable version. Re-number the final list sequentially. Write the merged\n result to the file. Show the user what changed (added N new, removed N\n redundant, kept N existing).\n- **Keep existing:** Do nothing, move on.\n\n**If no:** Skip this phase entirely.\n\n## Important Notes\n\n- **Data source priority:** Plannotator is the first-class path. Claude Code log\n analysis is the secondary path for users without Plannotator archives.\n- **Research integrity:** Every file must be read. The value of this analysis comes\n from completeness. Sampling or skipping undermines the findings.\n- **Real data only:** Never fabricate quotes, percentages, or patterns. If the data\n doesn't show a clear pattern, say so honestly rather than inventing one.\n- **Let the data lead:** The taxonomy, patterns, and instructions should emerge from\n what's actually in the files. Different users will have completely different\n denial patterns. A user building mobile apps will have different feedback than\n one building APIs. Don't assume what the patterns will be.\n- **Agent parallelization:** For large datasets, maximize parallel agents to reduce\n wall-clock time. The bottleneck is the largest batch — split it.\n- **Structured extraction format:** Ask extraction agents to return structured text\n with consistent delimiters so the reduce agent can parse reliably.\n- **The report is the artifact:** The HTML dashboard is what the user keeps. It\n should be beautiful, honest, and useful. Every section should feel like it was\n written about them specifically, because it was.\n\n\n# Agents Skill\n\nPath: `apps/skills/extra/plannotator-setup-goal/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-setup-goal/agents/openai.yaml)\n\n\n---\nname: plannotator-setup-goal\ndisable-model-invocation: true\ndescription: Turn an idea or objective into a goal package for /goal. Interviews the user, builds a reviewed fact sheet via Plannotator, then explores the codebase to produce an execution plan.\n---\n\n# Setup Goal\n\nTurn an idea into a goal package at `goals//` through structured discovery, user interview, and codebase exploration.\n\n## Phases\n\n### 1. Rearticulate\n\nState back what the user wants in your own words. If the conversation already has rich context, summarize it. If the goal is bare or vague, do minimal shallow exploration of the codebase to ground your understanding. Keep it to 2-3 sentences. Wait for the user to confirm or correct before continuing.\n\nCreate the goal directory once the slug is clear:\n\n```bash\nmkdir -p goals/\n```\n\nUse `goals//` for both working JSON files and final docs. The JSON files are provenance and iteration state; the markdown files are the human-readable authoritative goal package.\n\n**Browser session patience rule:** Plannotator goal setup is a user-driven browser session. After launching an interview or facts command, be absolutely patient and keep waiting on the user until they submit, dismiss, or explicitly ask you to stop. Do not close, kill, restart, refresh, or open a second copy just because the UI is idle or the user is taking time. Never close and reopen the session as a way to update state; if a rerun is needed after the prior session ends, update the working JSON file and launch a new command from that file.\n\n**Optional: grill first (deep, one-at-a-time interview).** Before building the compact interview bundle, *suggest* a grilling pass whenever the goal is vague or carries many interdependent decisions — and run one whenever the user asks for it (\"grill me first\"). This is opt-in: for a clear, well-scoped goal, skip it and go straight to the bundle, so grilling never fights the bundle's \"fewer, higher-leverage questions\" philosophy. When you grill, run the protocol below verbatim, then fold the resolved decisions forward into a higher-quality interview bundle (Phase 2) — or, if grilling fully resolves scope, straight into the fact sheet (Phase 3).\n\n\n\n> Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.\n>\n> Ask the questions one at a time.\n>\n> If a question can be answered by exploring the codebase, explore the codebase instead.\n\n### 2. Interview Bundle\n\nBuild a compact bundle of questions that can derive every \"fact\" this goal should produce. Package the questions together so the user can answer them quickly in the Plannotator goal setup UI. For each question, include your recommended answer and use options when they make answering faster.\n\nDo not ask obvious confirmation questions. If the answer can be inferred from the user's request, from the conversation, or from shallow codebase exploration, infer it and move on. If an obvious area has meaningful nuance, present the inferred answer as a recommendation with options or a custom \"add/correct this\" path rather than asking the user to restate the obvious.\n\nQuestion areas that usually matter:\n\n- What the feature/change is\n- Who it's for\n- What problem it solves\n- What behavior changes\n- What success looks like\n- What's in and out of scope (the most important area to determine facts)\n- What edge cases to consider\n- What constraints or precedent apply\n\n**If a question can be answered by exploring the codebase, explore the codebase instead of asking.** Only include questions where the user's judgment is actually needed. Prefer fewer, higher-leverage questions over exhaustive obvious ones.\n\nWrite the interview bundle before showing it to the user:\n\n`goals//interview.json`\n\n```json\n{\n \"stage\": \"interview\",\n \"title\": \"Short human-readable title\",\n \"goalSlug\": \"\",\n \"questions\": [\n {\n \"id\": \"scope\",\n \"prompt\": \"What should be in scope?\",\n \"description\": \"Optional clarification.\",\n \"answerMode\": \"multi-custom\",\n \"recommendedAnswer\": \"Your recommended answer.\",\n \"recommendedOptionIds\": [\"ui\", \"server\"],\n \"options\": [\n { \"id\": \"ui\", \"label\": \"UI\" },\n { \"id\": \"server\", \"label\": \"Server\" }\n ],\n \"required\": true\n }\n ]\n}\n```\n\nSupported `answerMode` values: `text`, `single`, `multi`, `custom`, `single-custom`, `multi-custom`.\n\nRun this as a monitored foreground process and wait patiently for the browser session to finish. The command may appear idle while the user is reading, editing, or asking questions; leave it running:\n\n```bash\nplannotator setup-goal interview goals//interview.json --json\n```\n\nThe command returns JSON on stdout with the submitted answers. Write that exact result to `goals//interview-result.json` before continuing. A convenient pattern is:\n\n```bash\nplannotator setup-goal interview goals//interview.json --json | tee goals//interview-result.json\n```\n\nIf the user revises after the session finishes, update `interview.json` and rerun the command instead of reconstructing the whole bundle from memory. If the session is dismissed, stop and tell the user the goal setup was closed.\n\nBefore moving to facts, read every answer and note carefully:\n\n- If the user wrote questions, uncertainty, \"not sure\", \"needs context\", or similar concerns in an answer or note, stop and address those questions in chat. Do not proceed to facts until the user has enough context or you have rerun a revised interview bundle.\n- If the user skipped a question with a note, treat the note as intentional feedback, not as an empty answer. Answer the note, refine the question, or make a documented assumption before proceeding.\n- If the user skipped a question without a note, proceed only if the missing answer is non-blocking; otherwise ask the smallest possible follow-up in chat.\n\n### 3. Fact Sheet\n\nA fact is a simple description of each outcome of a goal. It should be easily testable and verifiable. A fact may describe the function of a specific feature or aspect of a system. A fact may determine specific UI and UX. Again, a fact is literally anything that can be tested and verified in automated or manual testing. Keep fact language simple. In a way, a fact sheet is a design spec, but less verbose & using language the human user can easily visualize & rationalize. \n\nPrepare a facts review bundle from `goals//interview-result.json`. Each fact should include whether automated verification is recommended and preselected.\n\nWrite the facts review bundle before showing it to the user. If revising after a prior facts pass, start from `facts-review.json` and `facts-result.json`, include previously accepted facts with `\"accepted\": true`, and preserve their state.\n\n`goals//facts-review.json`\n\n```json\n{\n \"stage\": \"facts\",\n \"title\": \"Short human-readable title\",\n \"goalSlug\": \"\",\n \"facts\": [\n {\n \"id\": \"fact-1\",\n \"text\": \"The accepted fact text.\",\n \"accepted\": false,\n \"removed\": false,\n \"recommendedAutomatedVerification\": true,\n \"automatedVerification\": true\n }\n ]\n}\n```\n\nRun this as a monitored foreground process and wait patiently for the browser session to finish. The command may appear idle while the user is reviewing, editing, or asking questions; leave it running:\n\n```bash\nplannotator setup-goal facts goals//facts-review.json --json\n```\n\nThe command returns JSON on stdout with accepted/edited/removed facts plus automated verification selections. Write that exact result to `goals//facts-result.json`. A convenient pattern is:\n\n```bash\nplannotator setup-goal facts goals//facts-review.json --json | tee goals//facts-result.json\n```\n\nWrite `goals//facts.md` as a flat readable list of accepted facts. Each fact is one line; add a minimal note only when the fact cannot be stated clearly on its own. Also write `goals//facts.meta.json` preserving each accepted fact's `id`, final `text`, `comment`, `recommendedAutomatedVerification`, and `automatedVerification` value.\n\nIf the user edits or removes facts in the UI, apply that result directly. If the session is dismissed, stop and tell the user the facts review was closed.\n\n### 4. Plan\n\nExplore the codebase. Discover and validate implementation paths toward each accepted fact. Treat facts with `automatedVerification: true` as requiring concrete automated checks unless you document a blocker. Trace through code, identify files and systems involved, surface risks and unknowns. Refine until you have a confident order of operations.\n\nWrite `goals//plan.md`:\n\n- Solution approach (brief)\n- Ordered steps with the files/systems each touches\n- Verification for each step (concrete commands or checks)\n- Risks or open questions worth flagging\n\nGate the plan with Plannotator:\n\n```bash\nplannotator annotate goals//plan.md --gate\n```\n\nIf denied, revise from feedback and re-gate until approved.\n\n### 5. Goal Output\n\nWrite `goals//goal.md`:\n\n- The articulated goal (1-3 sentences)\n- Reference to `facts.md` as the shared understanding\n- Reference to `plan.md` as the execution plan\n- Done condition\n\nTell the user:\n\n```\nDone! Launch a goal with `/goal goals//goal.md`\n```\n\n\n# References Skill\n\nPath: `apps/skills/extra/plannotator-visual-explainer/references/design-system.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-visual-explainer/references/design-system.md)\n\n\n# References Skill\n\nPath: `apps/skills/extra/plannotator-visual-explainer/references/pr-components.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-visual-explainer/references/pr-components.md)\n\n\n# References Skill\n\nPath: `apps/skills/extra/plannotator-visual-explainer/references/svg-patterns.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-visual-explainer/references/svg-patterns.md)\n\n\n# References Skill\n\nPath: `apps/skills/extra/plannotator-visual-explainer/references/theme-override.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/apps/skills/extra/plannotator-visual-explainer/references/theme-override.md)\n\n\n---\nname: plannotator-visual-explainer\ndisable-model-invocation: true\ndescription: >\n Generate self-contained HTML visualizations with Plannotator theming. Use for implementation\n plans, PR explainers, architecture diagrams, data tables, slide decks, and any visual\n explanation of technical concepts. Plans and PR explainers follow Plannotator's prescriptive\n approach; all other visual content delegates to nicobailon/visual-explainer.\n---\n\n# Plannotator Visual Explainer\n\nThree paths depending on content type. Each has its own references and structure.\n\n## Route by content type\n\n**Implementation plan, design doc, or proposal** → Follow the [Plan path](#plan-path). Read `references/design-system.md` and `references/svg-patterns.md`. Prescriptive structure.\n\n**PR explainer, diff review, or code change walkthrough** → Follow the [PR path](#pr-path). Read `references/design-system.md` and `references/pr-components.md`. Prescriptive structure.\n\n**Everything else** (architecture diagrams, data tables, slide decks, project recaps, general visual explanations) → Follow the [Visual explainer path](#visual-explainer-path). Delegates to nicobailon/visual-explainer with Plannotator theme tokens.\n\n## Delivery\n\nAlways deliver via Plannotator's annotation UI. Do NOT use `open` or `xdg-open`.\n\nFor any deliverable that uses Mermaid, render every diagram with Mermaid 12 in both the light\nand dark palettes before opening the annotation UI. Rendering is a hard gate: an exception,\nempty SVG, or error output such as `aria-roledescription=\"error\"` or `Syntax error in text`\nmeans the explainer is not deliverable. Fix the diagram or theme configuration and rerun both\npalettes until every SVG passes.\n\nFor zoomable diagram shells, additionally zoom to the maximum and pan to all extremes in both palettes before delivering: the figure caption must stay fully legible throughout (see `references/diagram-shell.md`).\n\n**Plans/proposals** (user should approve/deny):\n```bash\nplannotator annotate --gate\n```\n\n**Everything else** (informational):\n```bash\nplannotator annotate \n```\n\n---\n\n## Plan path\n\nFor implementation plans, design docs, feature specs, migration guides, and proposals.\n\n**Before generating, read:**\n1. `references/design-system.md` — Plannotator theme tokens, typography, component patterns\n2. `references/svg-patterns.md` — inline SVG building blocks for architecture diagrams, flowcharts, data flow\n\n**Document structure (in order, pick what fits):**\n\n1. **Header** — eyebrow label (mono, uppercase), title (serif, large), prompt box (the original brief)\n2. **Summary strip** — 3-5 stat cards showing key numbers at a glance (components, endpoints, tables, etc.)\n3. **Milestones / timeline** — vertical timeline showing phases without time estimates. Phases show sequence and dependencies, not duration.\n4. **Architecture / data flow** — inline SVG diagram. Use for 3+ interacting components. Highlighted boxes for new components, dashed arrows for async paths.\n5. **Mockups** — build UI mockups in HTML/CSS directly, not as descriptions\n6. **Key code** — dark-theme code blocks with syntax highlighting. Only architecturally significant interfaces/schemas — not every function.\n7. **Risks & mitigations** — table with severity badges (HIGH/MED/LOW)\n8. **Open questions** — callout cards with decision owner (\"Decide with: backend team\")\n\nNot every plan needs every section. Skip what doesn't serve the content. Never include time estimates, boilerplate sections, or exhaustive file lists.\n\n**Adapt to the task:** Backend → lead with data flow. Frontend → lead with mockups. Refactoring → lead with before/after diagrams. Infrastructure → lead with architecture.\n\n**Quality bar:** The plan answers \"what, why, and how\" within 30 seconds of reading. Whitespace is a feature — one idea per viewport.\n\n---\n\n## PR path\n\nFor PR walkthroughs, diff reviews, code change explainers, and reviewer guides.\n\n**Before generating, read:**\n1. `references/design-system.md` — Plannotator theme tokens, typography, component patterns\n2. `references/pr-components.md` — diff rendering, review comment bubbles, risk chips, file cards, before/after panels\n\n**Document structure (in order, pick what fits):**\n\n1. **Header** — PR title, meta strip (file count, +/- lines, branch, author)\n2. **TL;DR** — bordered card with primary accent left border. 2-3 sentences. Readers who see nothing else should get the gist.\n3. **Why** — motivation and before/after comparison (two-column grid)\n4. **File tour** — collapsible cards per file. Each has: file path + badge (NEW/MOD/DEL) + line stats, a \"why\" paragraph, and important diff hunks. High-risk files expanded, safe files collapsed.\n5. **Risk map** — visual chips showing which files need careful review vs. which are mechanical. Three tiers: attention (destructive), medium (warning), safe (success).\n6. **Where to focus** — numbered callout cards. Each names a file/function and describes the concern.\n7. **Test plan** — checkbox-style verification checklist\n8. **Rollout** (if applicable) — phased deployment with feature flags\n\nUse Pierre diffs via CDN for syntax-highlighted inline diffs — see `references/pr-components.md` for the pattern.\n\n---\n\n## Visual explainer path\n\nFor architecture diagrams, data tables, slide decks, project recaps, comparisons, and any other visual explanation.\n\n**Before generating:**\n\n1. Ensure `visual-explainer` is installed:\n - Check: `~/.claude/skills/visual-explainer/SKILL.md` or `~/.agents/skills/visual-explainer/SKILL.md`\n - If not found: `npx skills add nicobailon/visual-explainer -g --yes`\n2. Read visual-explainer's `SKILL.md` (workflow, diagram types, anti-slop rules)\n3. Read the relevant visual-explainer references and templates for your content type\n4. Read `references/theme-override.md` — Plannotator tokens replacing Nico's palettes\n5. For zoomable Mermaid diagrams with controls and a caption: read `references/diagram-shell.md` and copy its shell — do not hand-roll viewport, canvas, or caption markup\n\nFollow visual-explainer's structure, component classes (`.ve-card`, `.kpi-card`, `.pipeline`), and anti-slop rules. Overrides are the color/typography layer — Plannotator tokens instead of Nico's custom palettes — plus the zoomable diagram shell in `references/diagram-shell.md` when the deliverable has one.\n\n---\n\n## Design philosophy (all paths)\n\n- **Whitespace is a feature.** Generous padding, large section gaps. If cramped, add space — don't shrink text.\n- **One idea per viewport.** Hero section, then diagram, then detail grid — not all crammed together.\n- **Show, don't describe.** A timeline shows sequencing. A diagram shows relationships. A code block shows the interface.\n- **No time estimates.** Timelines show phases and dependencies. Never attach hour/day estimates.\n\n\n# Ai Skill\n\nPath: `packages/ai/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ai/package.json)\n\n\n# Ai Skill\n\nPath: `packages/ai/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/backnotprop/plannotator/HEAD/packages/ai/tsconfig.json)\n\n\n"}