@leing2021/super-pi 0.14.0

package/skills/02-plan/references/ceo-review-mode.md

@@ -0,0 +1,130 @@
+# CEO Review Mode
+
+After the plan is produced, offer the user an optional CEO-style review. This adds strategic depth without changing the core planning flow.
+
+## When to offer
+
+After the plan artifact is written to `docs/plans/`, ask the user:
+
+> Plan ready. How do you want to review it?
+>
+> - **Just go** — trust the plan, skip review (existing behavior)
+> - **CEO Review** — challenge premises, check for better alternatives, dream-state mapping
+> - **Strict Review** — full CEO Review plus error maps, failure modes, test diagrams
+
+If the user picks "Just go", proceed directly to the `03-work` handoff.
+
+## CEO Review steps
+
+### 1. Premise Challenge
+
+Re-examine the plan's assumptions:
+- Is this the right problem to solve? Could a different framing yield a simpler solution?
+- What is the actual user/business outcome? Is the plan the most direct path?
+- What happens if we do nothing? Real pain or hypothetical?
+
+Present findings as premises the user must agree with. Use `ask_user_question` for each.
+
+### 2. Dream State Mapping
+
+Describe the ideal end state 12 months from now. Does this plan move toward it?
+
+```
+CURRENT STATE          THIS PLAN           12-MONTH IDEAL
+[describe]    --->     [describe delta]    --->    [describe target]
+```
+
+### 3. Implementation Alternatives (MANDATORY)
+
+Produce 2-3 distinct approaches. This is NOT optional.
+
+For each approach:
+```
+APPROACH A: [Name]
+  Summary: [1-2 sentences]
+  Effort:  [S/M/L/XL]
+  Risk:    [Low/Med/High]
+  Pros:    [2-3 bullets]
+  Cons:    [2-3 bullets]
+  Reuses:  [existing code/patterns leveraged]
+```
+
+Rules:
+- At least 2 approaches required.
+- One must be "minimal viable" (fewest files, smallest diff).
+- One must be "ideal architecture" (best long-term trajectory).
+- Recommend one and explain why.
+
+### 4. Temporal Interrogation
+
+Think ahead to implementation. What decisions should be resolved NOW?
+
+```
+HOUR 1 (foundations):     What does the implementer need to know?
+HOUR 2-3 (core logic):   What ambiguities will they hit?
+HOUR 4-5 (integration):  What will surprise them?
+HOUR 6+ (polish/tests):  What will they wish they'd planned for?
+```
+
+Surface these as questions NOW, not "figure it out later."
+
+## Strict Review additions
+
+If the user chose "Strict Review", add these on top of CEO Review:
+
+### 5. Error and Rescue Map
+
+For every new method/codepath that can fail:
+
+```
+METHOD/CODEPATH    | WHAT CAN GO WRONG     | EXCEPTION CLASS
+-------------------|-----------------------|-----------------
+ExampleService#call| API timeout           | TimeoutError
+                   | Malformed response    | JSONParseError
+
+EXCEPTION CLASS    | RESCUED? | RESCUE ACTION      | USER SEES
+-------------------|----------|--------------------|------------------
+TimeoutError       | Y        | Retry 2x, then raise | "Temporarily unavailable"
+JSONParseError     | N (GAP)  | -                    | 500 error (BAD)
+```
+
+### 6. Failure Modes Registry
+
+```
+CODEPATH | FAILURE MODE   | RESCUED? | TEST? | USER SEES?  | LOGGED?
+---------|----------------|----------|-------|-------------|--------
+```
+
+Any row with RESCUED=N, TEST=N, USER SEES=Silent is a **CRITICAL GAP**.
+
+### 7. Test Diagram
+
+Map every new thing the plan introduces:
+- New UX flows
+- New data flows
+- New codepaths
+- New error/rescue paths
+
+For each: what test covers it? Happy path? Failure path? Edge case?
+
+## Cognitive patterns
+
+These shape your perspective throughout the review. Don't enumerate them; internalize them:
+
+1. **Classification instinct** — categorize by reversibility x magnitude (Bezos)
+2. **Inversion reflex** — for every "how do we win?" also ask "what would make us fail?" (Munger)
+3. **Focus as subtraction** — primary value-add is what to NOT do (Jobs)
+4. **Speed calibration** — fast is default. Only slow down for irreversible + high-magnitude (Bezos)
+5. **Proxy skepticism** — are our metrics still serving users? (Bezos Day 1)
+6. **Temporal depth** — think in 5-10 year arcs, regret minimization (Bezos)
+7. **Courage accumulation** — confidence comes FROM making hard decisions, not before (Horowitz)
+8. **Leverage obsession** — find inputs where small effort creates massive output (Altman)
+9. **Edge case paranoia** — what if the name is 47 chars? Zero results? Network fails?
+10. **Subtraction default** — "as little design as possible" (Rams)
+
+## Handoff
+
+After CEO/Strict Review:
+1. Update the plan artifact with any changes the user approved.
+2. Note the review mode and key decisions in the plan.
+3. Proceed to the `03-work` handoff via `references/handoff.md`.

package/skills/02-plan/references/handoff.md

@@ -0,0 +1,8 @@
+# Handoff from 02-plan
+
+When the plan is ready:
+
+1. Report the plan path under `docs/plans/`.
+2. Summarize the main implementation units.
+3. Recommend `03-work` as the next step.
+4. Call out any remaining assumptions or open risks.

package/skills/02-plan/references/implementation-unit-template.md

@@ -0,0 +1,25 @@
+# Implementation unit
+
+## Goal
+
+Describe the concrete outcome of this unit.
+
+## Files
+
+List create/modify/test files for this unit.
+
+## Patterns to follow
+
+Point to nearby implementation examples or repo conventions.
+
+## Test scenarios
+
+List happy-path, edge-case, error-path, and integration scenarios when applicable.
+
+## Verification
+
+Name the exact command(s) that prove this unit is complete.
+
+## Dependencies
+
+List prerequisite units or blockers.

package/skills/02-plan/references/plan-template.md

@@ -0,0 +1,21 @@
+# Plan
+
+## Problem summary
+
+Summarize the problem and the relevant requirements.
+
+## Relevant learnings
+
+List the relevant prior artifacts from `docs/solutions/`.
+
+## Scope boundaries
+
+Define what is in and out of scope.
+
+## Implementation units
+
+Break the work into execution-ready units.
+
+## Verification strategy
+
+List the targeted and broader verification steps.

package/skills/03-work/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: 03-work
+description: Execute plan-driven work in a controlled Phase 1 workflow.
+---
+
+# Work
+
+Use this skill when there is a plan path or a tightly scoped bare prompt ready for execution.
+
+## Core rules
+
+- Distinguish between a **plan path** input and a **bare prompt** input before doing work.
+- Prefer deriving execution tasks from plan **implementation units**.
+- Use **serial subagents** for tasks with dependencies.
+- Use **`parallel_subagent`** for independent tasks that can run concurrently.
+- Use **`session_checkpoint`** to track plan execution progress. On start, load the checkpoint and skip completed units. After each unit, save the checkpoint.
+- On execution failure, use `session_checkpoint` `fail` to record the error, then `retry` to get a retry strategy. Follow the suggested strategy to recover.
+- Use **`task_splitter`** to analyze implementation units for file-level dependencies before execution. Run independent units via `parallel_subagent` and dependent units serially.
+- If inside a **worktree** (created via `07-worktree`), execute within it. Otherwise, consider recommending `07-worktree` for isolation.
+- End by recommending `04-review`.
+
+## Hard gates — TDD enforcement
+
+Every execution step must follow **RED → GREEN → REFACTOR**:
+- No production code before a verified failing test.
+- No skipping RED or GREEN verification.
+- No completion claim without command output evidence.
+- Evidence before assertions — always.
+
+**Blocking violations** — stop and ask if:
+- code is written before the RED test
+- a RED step fails for the wrong reason
+- missing evidence that the test failed before implementation
+- missing evidence that the test passed after implementation
+- tests added only after code
+
+## Workflow
+
+1. Detect whether the input is a plan path or a bare prompt.
+2. If it is a plan path, read the implementation units and execute from them.
+3. If it is a bare prompt, do a small scope scan before deciding whether to proceed.
+4. Use `session_checkpoint` to load progress and skip completed units.
+5. Use `task_splitter` to identify parallel-safe vs dependent units.
+6. Execute in inline mode, serial subagents, or parallel subagents depending on task dependencies.
+7. For each unit, follow strict TDD:
+   a. Run the RED test and confirm expected failure.
+   b. Apply minimal implementation.
+   c. Run the GREEN test and confirm pass.
+   d. Refactor only while tests stay green.
+   e. Run unit-level verification.
+8. Record progress using `references/progress-update-format.md`.
+9. After each unit, save `session_checkpoint`.
+10. On failure, use `session_checkpoint` `fail` then `retry`.
+11. Provide a **completion report** when done.
+12. Hand off to `04-review` using `references/handoff.md`.
+
+## Completion report
+
+When all units are done, provide:
+
+- **Completed units**: list of unit names
+- **Files changed**: all files created or modified
+- **Commands run**: all verification commands executed
+- **Verification results**: pass/fail status for each
+- **Follow-up work**: any remaining risks or open questions

package/skills/03-work/references/handoff.md

@@ -0,0 +1,8 @@
+# Handoff from 03-work
+
+When execution reaches a meaningful checkpoint:
+
+1. Summarize what was completed.
+2. Report the latest verification results.
+3. Recommend `04-review` as the next step.
+4. Mention any remaining implementation risk.

package/skills/03-work/references/progress-update-format.md

@@ -0,0 +1,17 @@
+# Progress update
+
+## Completed
+
+List the task or implementation unit that was completed.
+
+## Files changed
+
+List the files touched during this slice.
+
+## Verification
+
+List the command(s) that were run and whether they passed.
+
+## Remaining
+
+List the next execution slice or blocker.

package/skills/04-review/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: 04-review
+description: "Review code with structured findings. Optional browser QA and regression tests."
+---
+
+# Review
+
+Use this skill after implementation to review changes against the diff, the relevant plan, and prior learnings.
+
+## Core rules
+
+- Determine the **diff scope** before selecting reviewers.
+- Use the **`review_router`** tool to automatically select reviewer personas based on diff metadata.
+- Read the relevant **plan** artifact when one exists.
+- Search solutions with grep-first strategy: extract keywords from the task → `bash grep -rl "tags:.*keyword" docs/solutions/ ~/.pi/agent/docs/solutions/` → read only frontmatter (first 15 lines) of matching files → score by severity + tag relevance → fully read top 3. Search both project-level (`docs/solutions/`) and global-level (`~/.pi/agent/docs/solutions/`). If no matches, report "No relevant solutions found" and proceed.
+- Produce **structured findings** using `references/findings-schema.md`.
+- When findings are **autofixable**, apply fixes and re-review (max 3 iterations).
+- End with a handoff that can point toward fixes, re-review, or `05-compound`.
+
+## Review discipline — technical evaluation
+
+Code review is **technical evaluation**, not social performance:
+- **Verify before implementing** any suggestion — check against codebase reality.
+- **YAGNI check**: if a suggestion adds a feature nothing uses, question whether it's needed.
+- **No performative agreement** — do not agree with findings without technical verification.
+- **Push back with reasoning** when a finding is technically incorrect for this codebase.
+- **Evidence before assertions** — every finding must cite specific code, not general principles.
+
+## Handling findings
+
+When processing review findings:
+1. **Read** — complete all findings without reacting.
+2. **Verify** — check each finding against codebase reality.
+3. **Evaluate** — is it technically sound for THIS codebase?
+4. **Act** — fix confirmed issues, push back on incorrect ones with reasoning.
+5. **Test** — verify each fix individually, no regressions.
+
+## Workflow
+
+1. Determine diff scope from the current branch or explicit review target.
+2. Collect diff stats (files changed, insertions, deletions) and call `review_router`.
+3. Read the matching plan artifact when one exists.
+4. Execute the solution search strategy: extract keywords → grep frontmatter fields (tags, title) in `docs/solutions/` and `~/.pi/agent/docs/solutions/` → read frontmatter of candidates only → score and rank → fully read top 3.
+5. Apply each reviewer persona returned by `review_router`.
+6. Merge the results into structured findings.
+7. Verify each finding against the codebase before acting.
+8. If any findings are autofixable, apply fixes, re-run tests, and re-review.
+
+## Optional: QA Test Mode
+
+After step 8 (code review complete), offer browser-based QA testing:
+
+> Code review complete. Want me to also run the app through browser-based QA?
+>
+> - **A) Just code review** — done here
+> - **B) Run browser QA** — use agent-browser to test the live app, find visual/functional bugs
+> - **C) Browser QA + write regression tests** — find bugs, fix them, add regression tests
+
+If the user picks B or C, read `references/qa-test-mode.md` and execute the QA workflow.
+
+After QA:
+1. Include QA findings in the review handoff alongside code review findings.
+2. If bugs were fixed, note the fix commits.
+3. If regression tests were written, note the test files.
+
+## Handoff
+
+After review (and optional QA) is complete, hand off using `references/handoff.md`:
+1. Summarize all findings (code review + QA if run).
+2. Note fix commits if any were applied.
+3. Recommend `05-compound` if learnings are worth capturing.
+4. Recommend `03-work` if fixes need further implementation.

package/skills/04-review/references/findings-schema.md

@@ -0,0 +1,17 @@
+# Findings schema
+
+Each structured finding must include:
+
+- `severity` — one of: `high`, `moderate`, `low`
+- `summary` — one-line description of the issue
+- `evidence` — code reference, diff excerpt, or file path
+- `recommended action` — what should be done to address the finding
+
+Optional fields:
+
+- `related plan unit` — which implementation unit this relates to
+- `related learning` — link to a `docs/solutions/` artifact
+- `reviewer` — which reviewer persona flagged this
+- `autofixable` — whether this finding can be automatically fixed
+- `autofix applied` — whether the autofix was applied
+- `autofix summary` — description of what was changed

package/skills/04-review/references/handoff.md

@@ -0,0 +1,20 @@
+# Handoff from 04-review
+
+When the review is complete:
+
+1. Summarize the highest-priority structured findings.
+2. State whether fixes or re-review are needed.
+3. If findings are **autofixable**, apply the fixes and re-review the changes.
+4. After autofix, report what was changed and whether re-review confirms the fix.
+5. Recommend `05-compound` when the review surfaced a reusable learning or newly solved problem.
+6. Mention any relevant plan or solution artifacts referenced during review.
+
+## Autofix loop
+
+When findings have `autofixable: true`:
+
+1. Apply the fix for each autofixable finding.
+2. Re-run affected tests.
+3. Re-review only the changed lines.
+4. If re-review produces new findings, repeat (max 3 iterations).
+5. Report final state: fixed, partially fixed, or needs manual intervention.

package/skills/04-review/references/qa-test-mode.md

@@ -0,0 +1,134 @@
+# QA Test Mode
+
+After code review is complete, offer the user browser-based QA testing using `agent-browser`. This catches visual, functional, and UX bugs that code review alone cannot find.
+
+## When to offer
+
+After the review findings are produced and any autofixes applied, ask the user:
+
+> Code review complete. Want me to also run the app through browser-based QA?
+>
+> - **A) Just code review** — done, no browser testing (existing behavior)
+> - **B) Run browser QA** — use agent-browser to test the live app, find visual/functional bugs
+> - **C) Browser QA + write regression tests** — find bugs, fix them, and add regression tests
+
+If the user picks A, proceed directly to the handoff.
+
+## Prerequisites
+
+Before starting QA, ensure:
+1. The app is running locally (check common ports: 3000, 4000, 8080, 5173)
+2. `agent-browser` is available: `which agent-browser`
+3. If the app isn't running, ask the user to start it and tell you the URL
+
+## QA tiers
+
+| Tier | What gets fixed | Time |
+|------|----------------|------|
+| Quick | Critical + high severity | ~2 min |
+| Standard | + medium severity | ~5-10 min |
+| Exhaustive | + low/cosmetic severity | ~15-20 min |
+
+Default is Standard unless the user specifies otherwise.
+
+## Workflow
+
+### Phase 1: Orient
+
+```bash
+agent-browser open <target-url>
+agent-browser snapshot -i
+agent-browser console --errors
+```
+
+Map the application structure. Note framework (Next.js, Rails, SPA, etc.).
+
+### Phase 2: Explore
+
+Visit pages systematically. At each page:
+
+```bash
+agent-browser open <page-url>
+agent-browser snapshot -i
+agent-browser screenshot /tmp/qa-screenshots/<page-name>.png
+agent-browser console --errors
+```
+
+For each page, check the per-page exploration checklist:
+
+1. **Visual scan** — layout issues, broken images, alignment
+2. **Interactive elements** — click buttons, links, controls. Do they work?
+3. **Forms** — fill and submit. Test empty, invalid, edge cases
+4. **Navigation** — check all paths in and out
+5. **States** — empty state, loading, error, overflow
+6. **Console** — any JS errors after interactions?
+
+### Phase 3: Document
+
+Document each issue immediately with:
+- Screenshot evidence
+- Severity (critical/high/medium/low)
+- Category (visual/functional/UX/content/performance/accessibility)
+- Reproduction steps
+
+### Phase 4: Fix loop (modes B and C)
+
+For each fixable issue, in severity order:
+
+1. **Locate source** — grep for the component, find the responsible file
+2. **Fix** — minimal change that resolves the issue
+3. **Commit** — `git commit -m "fix(qa): ISSUE-NNN — description"`
+4. **Re-test** — navigate back and verify the fix with a screenshot
+5. **Classify** — verified / best-effort / reverted
+
+Self-regulation: Stop every 5 fixes and check with the user. Hard cap at 50 fixes.
+
+### Phase 5: Regression tests (mode C only)
+
+For each verified fix, write a regression test:
+- Trace the bug's codepath through the code you just fixed
+- Set up the exact precondition that triggered the bug
+- Assert the correct behavior (NOT "it renders" — test what it DOES)
+- Include attribution comment: `// Regression: ISSUE-NNN — {what broke}`
+- Run the test, commit if passing
+
+## Issue severity rubric
+
+| Severity | Definition | Examples |
+|----------|-----------|---------|
+| Critical | Blocks a core workflow, data loss, crash | Form submit causes error page, checkout broken |
+| High | Major feature broken, no workaround | Search returns wrong results, file upload fails |
+| Medium | Feature works but with problems, workaround exists | Slow page load, form validation missing |
+| Low | Minor cosmetic or polish issue | Typo, 1px alignment issue, hover state |
+
+## Health score
+
+Compute a weighted score:
+
+| Category | Weight |
+|----------|--------|
+| Console errors | 15% |
+| Broken links | 10% |
+| Visual | 10% |
+| Functional | 20% |
+| UX | 15% |
+| Performance | 10% |
+| Content | 5% |
+| Accessibility | 15% |
+
+Each category starts at 100. Deduct per finding: critical (-25), high (-15), medium (-8), low (-3).
+
+## Diff-aware mode
+
+If the user is on a feature branch with no explicit URL, automatically:
+1. Analyze the branch diff: `git diff main...HEAD --name-only`
+2. Identify affected pages/routes from the changed files
+3. Detect the running app on common local ports
+4. Test only the affected pages
+5. Report findings scoped to the branch changes
+
+## Framework-specific guidance
+
+- **Next.js**: Check for hydration errors, test client-side navigation, monitor `_next/data` requests
+- **Rails**: Check CSRF tokens, test Turbo/Stimulus integration, verify flash messages
+- **SPA (React/Vue/Angular)**: Use `snapshot -i` for navigation, check stale state, test browser back/forward

package/skills/04-review/references/reviewer-selection.md

@@ -0,0 +1,24 @@
+# Reviewer selection
+
+Use the `review_router` tool to determine which reviewers to apply based on diff metadata.
+
+## How to use
+
+1. Collect diff stats: files changed, insertions, deletions.
+2. Call `review_router` with these inputs.
+3. Apply the returned reviewer personas to the review.
+
+## Reviewer personas
+
+### Base reviewers (always active)
+
+- **correctness-reviewer**: Logical correctness, intended behavior, edge cases.
+- **testing-reviewer**: Test coverage, test quality, missing test scenarios.
+- **maintainability-reviewer**: Code clarity, naming, structure, duplication.
+
+### Conditional reviewers (routed by `review_router`)
+
+- **security-reviewer**: Triggered when auth, permissions, tokens, sessions, or crypto files change. Reviews for injection, auth bypass, credential leakage.
+- **performan04-reviewer**: Triggered when query, cache, database, or streaming files change. Reviews for N+1, unnecessary allocation, missing indexes.
+- **integration-reviewer**: Triggered when CI/CD, Docker, package.json, or config files change. Reviews for dependency conflicts, build breakage, deployment issues.
+- **thoroughness-reviewer**: Triggered for large diffs (5+ files or 300+ lines). Reviews for incomplete refactors, missed callers, inconsistent changes.

package/skills/05-compound/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: 05-compound
+description: Capture solved problems as reusable solution artifacts.
+---
+
+# Compound
+
+Use this skill after solving a problem so the repository gains a reusable learning in `docs/solutions/`.
+
+## Core rules
+
+- Every solution MUST include YAML frontmatter per `references/solution-schema.yaml` (title, category, severity, tags, applies_when).
+- Use `references/category-map.md` to map the problem to the correct solution category.
+- Check for overlap with nearby solution docs before creating a new artifact.
+- Use `references/overlap-rules.md` to decide whether to create, update, or consolidate.
+- Use **`pattern_extractor`** to identify recurring patterns across existing artifacts before writing a new solution.
+- Structure the document with `assets/solution-template.md`.
+- Determine storage level:
+  - **Project-specific** → `{project-root}/docs/solutions/` (only relevant to current project)
+  - **Cross-project (global)** → `~/.pi/agent/docs/solutions/` (applicable to any project)
+  - Default to **global** when uncertain.
+- Make the result useful to future `02-plan` and `04-review` runs via the search strategy in `references/solution-search-strategy.md`.
+
+## Workflow
+
+1. Identify the recently solved problem or learning.
+2. Use `pattern_extractor` `extract` to scan existing artifacts for recurring patterns.
+3. Use `pattern_extractor` `categorize` to group patterns by type.
+4. Search `docs/solutions/` for related artifacts and perform an overlap check.
+5. Choose the correct category using `references/category-map.md`.
+6. Write or update the solution artifact under `docs/solutions/<category>/`.
+7. Mention how future `02-plan` and `04-review` runs should benefit from the new learning.

package/skills/05-compound/assets/solution-template.md

@@ -0,0 +1,27 @@
+---
+title:
+category:
+severity: medium
+tags: []
+applies_when: []
+---
+
+# Problem
+
+Describe the solved problem or reusable learning.
+
+# Context
+
+Explain where it showed up and why it mattered.
+
+# Solution
+
+Describe the fix or recommended practice.
+
+# Why this works
+
+Explain the root cause or reasoning.
+
+# Prevention
+
+Describe how future work should avoid rediscovering the same issue.

package/skills/05-compound/references/category-map.md

@@ -0,0 +1,9 @@
+# Category map
+
+Use these categories when writing `docs/solutions/` artifacts:
+
+- `workflow` — planning, execution, or review workflow learnings
+- `testing` — test failures, harness issues, or coverage learnings
+- `architecture` — cross-cutting design or system structure learnings
+- `integration` — external service or tool integration learnings
+- `tooling` — package, CLI, or environment learnings

package/skills/05-compound/references/overlap-rules.md

@@ -0,0 +1,7 @@
+# Overlap rules
+
+Use these overlap levels when deciding whether to create a new solution doc or update an existing one.
+
+- **High** — same problem, same root cause, and same solution approach. Update the existing doc.
+- **Moderate** — related problem area but a different angle or solution. Create a new doc and cross-link it.
+- **Low** — only loosely related. Create a distinct doc.

package/skills/05-compound/references/solution-schema.yaml

@@ -0,0 +1,27 @@
+required:
+  - title
+  - category
+  - severity
+  - tags
+  - applies_when
+properties:
+  title:
+    type: string
+    description: Human-readable title for the solution
+  category:
+    type: string
+    description: Subdirectory name (tooling, integration, workflow, testing, architecture)
+  severity:
+    type: string
+    enum: [critical, high, medium, low]
+    description: Priority for retrieval ranking
+  tags:
+    type: array
+    items:
+      type: string
+    description: Keywords for grep-based search matching
+  applies_when:
+    type: array
+    items:
+      type: string
+    description: Conditions where this solution is relevant