@leing2021/super-pi 0.23.0 → 0.23.1

package/skills/04-review/SKILL.md

@@ -5,78 +5,70 @@ description: "Review code with structured findings. Optional browser QA and regr
 
 # Review
 
-Use this skill after implementation to review changes against the diff, the relevant plan, and prior learnings.
+Use this skill after implementation to review changes against the diff, plan, and prior learnings.
 
 See [shared pipeline instructions](../references/pipeline-config.md) for model routing and pipeline behavior.
 
 ## Core rules
 
-- Before reviewing, load project rules:
-  1. `rules/common/code-review.md`
-  2. Detect the project's primary language from the changed files using [language detection](../references/language-detection.md)
-  3. Load all files in the matching language-specific rules directory (e.g. `rules/typescript/`)
-  4. If the review involves frontend/browser changes, also load `rules/web/` files
-- Priority: project-level `{repo-root}/rules/` overrides package-level defaults
-- 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-learn`.
-
-## Review discipline — technical evaluation
+1. Load project rules (4 steps):
+   - Load `rules/common/code-review.md`
+   - Detect language from changed files via [language detection](../references/language-detection.md)
+   - Load matching language-specific rules (e.g., `rules/typescript/`)
+   - If frontend/browser changes, also load `rules/web/` files
+2. **Priority:** project-level `{repo-root}/rules/` overrides package defaults
+3. Determine **diff scope** before selecting reviewers
+4. Use **`review_router`** tool to select reviewer personas based on diff metadata
+5. Read relevant **plan** artifact when exists
+6. Run solution search (see `references/solution-search.md`):
+   - Extract keywords → `grep -rl "tags:.*keyword" docs/solutions/ ~/.pi/agent/docs/solutions/`
+   - Read **frontmatter** only (first 15 lines) of matches → score by severity + tag relevance
+   - Fully read top 3 candidates
+7. Produce structured findings using `references/findings-schema.md`
+8. **Autofixable findings:** apply and re-review (max 3 iterations)
+
+## Review discipline
 
 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.
+- **Verify before implementing** any suggestion
+- **YAGNI check:** question features nothing uses
+- **No performative agreement:** verify before concurring
+- **Push back** with reasoning when findings are incorrect
+- **Evidence before assertions:** cite specific code, not 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.
+1. **Read** — complete all findings without reacting
+2. **Verify** — check each against codebase reality
+3. **Evaluate** — is it sound for THIS codebase?
+4. **Act** — fix confirmed issues, push back on incorrect ones
+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.
+1. Determine diff scope from branch or explicit target
+2. Collect stats (files, insertions, deletions) → call `review_router`
+3. Read matching plan artifact
+4. Run solution search
+5. Apply each reviewer persona from `review_router`
+6. Merge into structured findings
+7. Verify each finding against codebase
+8. Apply autofixes, re-run tests, re-review if needed
 
 ## Optional: QA Test Mode
 
-After step 8 (code review complete), offer browser-based QA testing:
+After code review complete, offer browser QA:
 
-> 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
+> Code review done. Run browser QA?
+> - **A) Done** — stop here
+> - **B) Browser QA** — find visual/functional bugs
+> - **C) QA + regression tests** — find bugs, fix, add 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.
+If B or C: read `references/qa-test-mode.md` and execute workflow.
+After QA: include findings in handoff, note fix commits/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-learn` if learnings are worth capturing.
-4. Recommend `03-work` if fixes need further implementation.
+See `references/handoff.md` for format.
 
 Before finishing this skill, apply the completion checklist in [shared pipeline instructions](../references/pipeline-config.md).

package/skills/04-review/references/solution-search.md

@@ -0,0 +1,46 @@
+# Solution Search Strategy
+
+Grep-first strategy for finding relevant solutions before planning or reviewing.
+
+## Steps
+
+1. **Extract keywords** from the task description
+2. **Grep frontmatter** fields (tags, title) in both locations:
+   ```bash
+   grep -rl "tags:.*keyword" docs/solutions/ ~/.pi/agent/docs/solutions/
+   ```
+3. **Read frontmatter only** (first 15 lines) of matching files
+4. **Score by:**
+   - Severity match (higher severity = higher priority)
+   - Tag relevance (exact matches rank higher)
+5. **Fully read top 3** candidates
+6. If no matches: report "No relevant solutions found" and proceed
+
+## Search locations
+
+| Level | Path | Use for |
+|---|---|---|
+| Project | `docs/solutions/` | Project-specific learnings |
+| Global | `~/.pi/agent/docs/solutions/` | Cross-project patterns |
+
+## Scoring rubric
+
+| Score | Criteria |
+|---|---|
+| 5 | Exact tag match + high severity + same language |
+| 4 | Tag match + same category |
+| 3 | Partial tag match |
+| 2 | Same category, no tag match |
+| 1 | Worth reading for context |
+| 0 | No relevance |
+
+## Output
+
+- List of relevant solutions with paths and relevance scores
+- Key takeaways from top solutions
+- How they apply to current task
+
+## When to use
+
+- `02-plan`: Before creating implementation units, check for existing patterns
+- `04-review`: Before reviewing, check for known failure modes or solutions

package/skills/06-next/SKILL.md

@@ -9,11 +9,11 @@ Use this skill when the user wants to know what to run next in the Compound Engi
 
 ## Core rules
 
-- Use the `workflow_state` tool to scan repo artifacts before making a recommendation.
-- Use the `session_history` tool to check recent executions and avoid recommending already-completed steps.
+- Use **`workflow_state`** tool to scan repo artifacts before making a recommendation.
+- Use **`session_history`** tool to check recent executions and avoid already-completed steps.
 - Recommend exactly **one** next skill with a clear reason.
 - Do not execute the recommended skill — only suggest it.
-- If the workflow state suggests multiple valid paths, pick the one closest to completing a full loop.
+- If multiple valid paths exist, pick the one closest to completing a full loop.
 
 ## Two modes
 
@@ -21,29 +21,23 @@ Use this skill when the user wants to know what to run next in the Compound Engi
 
 When the user asks "what should I do next?", "continue", or runs `/skill:06-next`:
 
-1. Call `workflow_state` with the repo root.
-2. Apply the recommendation logic from `references/recommendation-logic.md`.
-3. Return:
-   - **Recommended skill name**
-   - **Why** this is the next step
-   - **Brief** summary of current workflow state (1-2 lines)
+1. Call `workflow_state` with the repo root
+2. Apply recommendation logic from `references/recommendation-logic.md`
+3. Return: skill name, reason (1-2 lines), brief workflow state summary
 
 ### Verbose mode: "full status"
 
-When the user asks "show status", "what's the current state", or explicitly requests a detailed report:
+When the user asks "show status", "what's the current state", or uses `--verbose`:
 
-1. Call `workflow_state` with the repo root.
-2. Call `session_history` with `latest` operation to check recent executions.
-3. Return:
-   - Latest relevant brainstorm (path + brief summary)
-   - Latest relevant plan (path + brief summary)
-   - Latest relevant solution (path + brief summary)
-   - Latest runtime artifacts under `.context/compound-engineering/`
-   - Recommended next step with reason
-   - Overall workflow phase summary
+1. Call `workflow_state` with the repo root
+2. Call `session_history` with `latest` operation
+3. Return: latest artifacts (path + summary), status of each phase, recommended next step
 
 ## Artifact locations
 
+See `references/recommendation-logic.md` for full recommendation rules and skill list.
+
+**Quick reference:**
 | Artifact | Path |
 |---|---|
 | Brainstorm | `docs/brainstorms/` |
@@ -51,15 +45,8 @@ When the user asks "show status", "what's the current state", or explicitly requ
 | Solution | `docs/solutions/` |
 | Runtime | `.context/compound-engineering/` |
 
-If `workflow_state` is not available, fall back to `bash` with `ls` and `find` to check which directories and recent files exist, then use `read` on the most relevant recent artifact.
-
-## Available skills
+**Available skills:** `01-brainstorm`, `02-plan`, `03-work`, `04-review`, `05-learn`, `07-worktree`
 
-- `01-brainstorm` — clarify the problem and produce requirements
-- `02-plan` — turn requirements into implementation units
-- `03-work` — execute the plan
-- `04-review` — review changes with structured findings
-- `05-learn` — capture learnings as solution artifacts
-- `07-worktree` — isolated git worktree development
+**Fallback:** If `workflow_state` is unavailable, use `bash ls/find` to check directories, then `read` recent artifacts.
 
 Before finishing this skill, apply the completion checklist in [shared pipeline instructions](../references/pipeline-config.md).

package/skills/06-next/references/recommendation-logic.md

@@ -44,3 +44,48 @@ If brainstorm, plan, and solution all exist:
 If no rule matches cleanly:
 - Summarize the ambiguous state
 - Ask the user what they want to focus on
+
+---
+
+# Skill registry
+
+## Available skills
+
+| Skill | Purpose | When to use |
+|---|---|---|
+| `01-brainstorm` | Clarify problem, produce requirements | Ambiguous request, new idea |
+| `02-plan` | Turn requirements into implementation units | Requirements clear |
+| `03-work` | Execute the plan | Plan ready |
+| `04-review` | Review changes with structured findings | After implementation |
+| `05-learn` | Capture learnings as solution artifacts | After solving a problem |
+| `07-worktree` | Isolated git worktree development | Large/risky/parallel work |
+
+## Artifact locations
+
+| Artifact | Project path | Global path |
+|---|---|---|
+| Brainstorm | `docs/brainstorms/` | — |
+| Plan | `docs/plans/` | — |
+| Solution | `docs/solutions/` | `~/.pi/agent/docs/solutions/` |
+| Handoff | `.context/compound-engineering/handoffs/` | — |
+| Runtime | `.context/compound-engineering/` | — |
+
+## Skill to artifact mapping
+
+When `workflow_state` returns artifacts, map them back to skills:
+
+- Files in `docs/brainstorms/` → produced by `01-brainstorm`
+- Files in `docs/plans/` → produced by `02-plan`
+- Files in `docs/solutions/` → produced by `05-learn`
+- `.context/compound-engineering/` runtime artifacts → produced by `03-work` or `04-review`
+
+## Recommendation priority
+
+When multiple conditions are met, prioritize:
+
+1. `01-brainstorm` — if nothing exists yet
+2. `02-plan` — if brainstorm exists but no plan
+3. `03-work` — if plan exists but no execution
+4. `04-review` — if execution exists but no review
+5. `05-learn` — if review exists but no learning captured
+6. Loop back to `01-brainstorm` or `06-next` for full cycle completion

package/skills/07-worktree/SKILL.md

@@ -5,32 +5,32 @@ description: Create and manage git worktrees for isolated feature development.
 
 # Worktree
 
-Use this skill when you need optional isolated git worktree development for large, risky, or parallel feature work, then merge changes back or clean up after completion.
+Use this skill for optional isolated git worktree development for large, risky, or parallel feature work.
 
 ## Core rules
 
-- Use the `worktree_manager` tool for all git worktree operations.
-- Create a worktree only when the user explicitly asks for isolation, or when the task is large/risky enough and the user confirms.
-- Use a descriptive branch name derived from the plan or task.
-- After creation, report the worktree path so that `03-work` can execute inside it.
-- On completion, offer to merge back and clean up; ask for confirmation before changing the main worktree or deleting branches.
-- Never force operations — if a worktree already exists, report its status instead of creating a duplicate.
+- Use **`worktree_manager`** tool for all operations
+- Only create when user explicitly asks or task is large/risky enough (with confirmation)
+- Derive branch name from plan or task
+- Report worktree path after creation so `03-work` can execute inside it
+- **Never force operations** — if worktree exists, report status instead of duplicating
+- On completion: offer merge → cleanup (with user confirmation)
 
 ## Workflow
 
-1. **Detect**: Use `worktree_manager` with operation `detect` to check if already inside a worktree.
-2. **Create**: When confirmed, use `worktree_manager` with operation `create` to spin up a new worktree with a feature branch.
-3. **Execute**: Run `03-work` inside the worktree directory.
-4. **Merge**: After user confirmation, use `worktree_manager` with operation `merge` to merge the feature branch back to main.
-5. **Cleanup**: After user confirmation, use `worktree_manager` with operation `cleanup` to remove the worktree and delete the branch.
+See `references/worktree-lifecycle.md` for detailed flow, branch naming, and error handling.
 
-## Output
+**Quick reference:**
+1. `detect` — check if already in worktree
+2. `create` — spin up new worktree with feature branch
+3. Execute `03-work` inside worktree directory
+4. `merge` — merge feature branch back (with confirmation)
+5. `cleanup` — remove worktree and delete branch (with confirmation)
 
-After creation, report:
-- Worktree path
-- Branch name
-- Instruction to run `03-work` in the worktree directory
+## Branch naming
 
-After merge, report:
-- Merge result
-- Whether cleanup is recommended
+- `feat/<slug>` — feature work
+- `fix/<slug>` — bug fixes
+- `chore/<slug>` — maintenance tasks
+
+Before finishing this skill, apply the completion checklist in [shared pipeline instructions](../references/pipeline-config.md).

package/skills/08-help/SKILL.md

@@ -7,31 +7,40 @@ description: Explain when to use each Compound Engineering Phase 1 skill and how
 
 Use this skill when the user asks how to use the package, which workflow step comes next, or which Compound Engineering skill fits the current task.
 
-## Phase 1 skill guide
-
-- `01-brainstorm` — use when the request is ambiguous, needs requirements discovery, or the user has a new idea. Three modes: CE requirements discovery (adding features), Startup Diagnostic (YC-style forcing questions for new products/startups), Builder Mode (side projects, hackathons, learning).
-- `02-plan` — use when requirements are clear enough to turn into implementation units. After planning, user can optionally run a CEO-style strategic review or strict review (error maps, failure modes, test diagrams).
-- `03-work` — use when there is a plan or a tightly scoped task ready for controlled execution.
-- `04-review` — use after code changes to produce structured findings. After code review, user can optionally extend to browser-based QA testing (find visual/functional bugs with agent-browser) and regression test generation.
-- `05-learn` — use after solving a problem so the repo gains a durable learning in `docs/solutions/`.
-- `06-next` — use when the user wants to know what to run next, or wants a full status report of the current project state. Default mode recommends one next step; verbose mode (`--verbose` or ask "show status") shows full artifact details.
-
-## Recommended flow
-
-1. Start with `01-brainstorm` when the problem is still fuzzy or you have a new idea.
-   - **Startup founders** get the YC-style diagnostic: demand reality, status quo, narrowest wedge.
-   - **Side project builders** get generative brainstorming: coolest version, fastest path to ship.
-   - **Feature additions** get the standard CE requirements discovery.
-2. Move to `02-plan` once the desired behavior is clear.
-   - Optionally run **CEO Review** to challenge premises, map alternatives, check dream-state alignment.
-   - Or **Strict Review** for full error maps, failure modes, and test diagrams.
-3. Use `03-work` to execute the plan.
-4. Run `04-review` after implementation.
-   - Optionally extend to **Browser QA** for visual and functional bug finding.
-   - Or **Browser QA + Regression Tests** to also generate automated test coverage.
-5. Capture key learnings with `05-learn`.
-6. Use `06-next` at any point to check what to do next, or ask for a full status report.
-
-## Output
-
-When responding, explain the smallest useful next step instead of forcing the full sequence.
+## Core principle
+
+**Explain the smallest useful next step** — do not force the full sequence.
+
+## Trigger conditions
+
+| User asks | Use this skill |
+|---|---|
+| How to use the package | Help with skill selection |
+| Which step comes next | Recommend via workflow state |
+| Which skill fits | Match task to skill |
+
+## Skill mapping
+
+| Skill | When to use |
+|---|---|
+| `01-brainstorm` | Ambiguous request, new idea, requirements discovery |
+| `02-plan` | Requirements clear, turn into implementation units |
+| `03-work` | Plan ready, controlled execution |
+| `04-review` | After code changes, structured findings |
+| `05-learn` | After solving, capture reusable learning |
+| `06-next` | Check status or get next step recommendation |
+| `07-worktree` | Isolated feature development |
+
+## Workflow sequence
+
+See `references/workflow-sequence.md` for detailed flow, mode variants, and output formats.
+
+**Quick reference:**
+1. `01-brainstorm` → clarify problem
+2. `02-plan` → break into units (optional CEO/Strict review)
+3. `03-work` → execute
+4. `04-review` → inspect (optional Browser QA)
+5. `05-learn` → capture learnings
+6. `06-next` → check status anytime
+
+Before finishing this skill, apply the completion checklist in [shared pipeline instructions](../references/pipeline-config.md).

package/skills/08-help/references/workflow-sequence.md

@@ -1,10 +1,135 @@
 # Workflow Sequence
 
-1. `01-brainstorm` → clarify the problem (CE mode / Startup Diagnostic / Builder Mode)
-2. `02-plan` → break it into concrete units (optionally + CEO Review / Strict Review)
+## Full CE pipeline
+
+1. `01-brainstorm` → clarify the problem
+2. `02-plan` → break into units (optionally + CEO Review / Strict Review)
 3. `03-work` → execute the plan
-4. `04-review` → inspect the changes (optionally + Browser QA / QA + Regression Tests)
+4. `04-review` → inspect changes (optionally + Browser QA / QA + Regression Tests)
 5. `05-learn` → save key learnings
 
 Use `06-next` at any point to see where you are and what to do next.
 Use `07-worktree` for isolated feature development on a separate branch.
+
+---
+
+## Phase 1 skill guide
+
+### 01-brainstorm
+**Use when:** request is ambiguous, needs requirements discovery, or user has a new idea.
+
+**Three modes:**
+- **CE Brainstorm** — standard requirements discovery for feature additions
+- **Startup Diagnostic** — YC-style forcing questions for founders/intrapreneurs
+- **Builder Mode** — generative brainstorming for side projects/hackathons/learning
+
+**Key outputs:**
+- Requirements document in `docs/brainstorms/`
+- Explicit user approval before handoff
+
+### 02-plan
+**Use when:** requirements are clear enough to turn into implementation units.
+
+**Optional reviews after planning:**
+- **CEO Review** — challenge premises, check dream-state alignment
+- **Strict Review** — CEO Review + error maps, failure modes, test diagrams
+
+**Key outputs:**
+- Plan artifact in `docs/plans/`
+- Implementation units following TDD RED→GREEN→REFACTOR
+
+### 03-work
+**Use when:** plan is ready or task is tightly scoped.
+
+**Execution modes:**
+- Inline execution for small units
+- `ce_parallel_subagent` for independent CE skill units
+- `ce_subagent` only for dependent serial chains
+
+**Key outputs:**
+- Completion report with verification evidence
+- Checkpoint state for resume
+
+### 04-review
+**Use when:** after code changes to produce structured findings.
+
+**Optional extensions:**
+- **Browser QA** — find visual/functional bugs with agent-browser
+- **Browser QA + Regression Tests** — also generate automated coverage
+
+**Key outputs:**
+- Structured findings per `references/findings-schema.md`
+- Optional QA report with fix commits
+
+### 05-learn
+**Use when:** after solving a problem to capture reusable learning.
+
+**Key outputs:**
+- Solution artifact in `docs/solutions/` or global `~/.pi/agent/docs/solutions/`
+- Handoff-lite for workflow closure
+
+### 06-next
+**Use when:** user wants to know what to run next, or wants full status.
+
+**Two modes:**
+- **Default** — recommend one next step with reason
+- **Verbose** (`--verbose` or "show status") — full artifact details + recent history
+
+### 07-worktree
+**Use when:** need isolated git worktree development.
+
+**Use for:** large, risky, or parallel feature work.
+
+**Flow:** create → execute via 03-work → merge → cleanup
+
+---
+
+## Skill routing decision tree
+
+```
+Is the request clear and specific?
+├── No → 01-brainstorm (clarify requirements)
+└── Yes → Is there a plan?
+    ├── No → 02-plan (create implementation units)
+    └── Yes → Is work complete?
+        ├── No → 03-work (execute)
+        └── Yes → Has it been reviewed?
+            ├── No → 04-review (structured findings)
+            └── Yes → Is there a learning worth capturing?
+                ├── Yes → 05-learn
+                └── No → Check status with 06-next
+```
+
+---
+
+## Output format for help responses
+
+When explaining skills to users, keep it concise:
+
+**Short form** (one skill recommendation):
+```
+Next step: `/skill:02-plan`
+
+Reason: You have a clear idea. Let's turn it into implementation units.
+```
+
+**Medium form** (context + recommendation):
+```
+Status: Requirements captured in docs/brainstorms/2024-01-idea.md
+
+Next step: `/skill:02-plan`
+
+Why: Requirements exist but no implementation plan yet.
+```
+
+**Verbose form** (full sequence):
+```
+Workflow sequence:
+1. ✅ Brainstorm: requirements captured
+2. ⏳ Plan: ready to create
+3. ⏸ Work: waiting for plan
+4. ⏸ Review: waiting for work
+5. ⏸ Learn: waiting for review
+
+Recommended: `/skill:02-plan` to turn requirements into implementation units.
+```