@leing2021/super-pi 0.14.0

package/skills/05-compound/references/solution-search-strategy.md

@@ -0,0 +1,60 @@
+# Solution Search Strategy
+
+Grep-first, tiered retrieval for `docs/solutions/`. Use this in `02-plan` and `04-review` to find relevant learnings without loading all files.
+
+## Search order
+
+1. **Project-level**: `{project-root}/docs/solutions/` — project-specific solutions
+2. **Global-level**: `~/.pi/agent/docs/solutions/` — cross-project solutions
+
+## Steps
+
+### Step 1: Extract keywords
+
+From the task/feature description, identify:
+- **Technical terms**: tool names, framework names, language concepts
+- **Problem indicators**: error symptoms, failure modes, performance issues
+- **Component types**: CLI, extension, skill, test, config
+
+### Step 2: Grep frontmatter fields
+
+Run parallel grep searches across both solution directories. Only return file paths, do not load content:
+
+```bash
+# Search tags (most precise)
+grep -rl "tags:.*keyword1" docs/solutions/ ~/.pi/agent/docs/solutions/
+# Search title
+grep -rl "title:.*keyword" docs/solutions/ ~/.pi/agent/docs/solutions/
+# Search applies_when
+grep -rl "applies_when:" docs/solutions/ ~/.pi/agent/docs/solutions/ | head -5
+```
+
+### Step 3: Narrow if needed
+
+- **>10 candidates**: Re-run with more specific keyword combinations
+- **<3 candidates**: Broaden search to grep full file content, not just frontmatter
+
+### Step 4: Read frontmatter only
+
+For each candidate file, read only the first 15 lines (frontmatter):
+
+```bash
+head -15 <file>
+```
+
+### Step 5: Score and rank
+
+Match quality:
+- **Strong**: `tags` contain direct keyword matches
+- **Moderate**: `title` or `applies_when` are semantically related
+- **Weak**: No overlap — skip
+
+Sort by `severity` (critical > high > medium > low) when multiple strong matches exist.
+
+### Step 6: Full read top-N
+
+Only fully read the **top 3** ranked files. Summarize relevance in 1-2 sentences per file.
+
+## When to stop
+
+If no candidates found after Step 2, do **not** fall back to reading all files. Report "No relevant solutions found" and proceed. An empty result is valuable information — it means the area has no prior learnings.

package/skills/06-next/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: 06-next
+description: Inspect workflow state and recommend the single best next Compound Engineering skill.
+---
+
+# Next
+
+Use this skill when the user wants to know what to run next in the Compound Engineering workflow.
+
+## 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.
+- 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.
+
+## Workflow
+
+1. Call `workflow_state` with the repo root.
+2. Read the structured state: brainstorm count, plan count, solution count, run count, and latest artifact per category.
+3. Apply the recommendation logic from `references/recommendation-logic.md`.
+4. Return the recommended skill and why.
+
+## Output format
+
+- Recommended skill name
+- Why this is the next step
+- Brief summary of current workflow state
+
+## Available skills
+
+- `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-compound` — capture learnings as solution artifacts

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

@@ -0,0 +1,46 @@
+# Recommendation logic
+
+Apply these rules in order. Return the first match.
+
+## Rule 1: No brainstorm artifacts
+
+If `brainstorms.count === 0`:
+- Recommend `01-brainstorm`
+- Reason: No requirements have been captured. Start by clarifying the problem.
+
+## Rule 2: Brainstorm exists, no plan
+
+If `brainstorms.count > 0` and `plans.count === 0`:
+- Recommend `02-plan`
+- Reason: Requirements exist but no implementation plan. Turn them into actionable units.
+
+## Rule 3: Plan exists, no recent review
+
+If `plans.count > 0` and the latest plan has no corresponding review artifact:
+- Recommend `03-work`
+- Reason: A plan is ready for execution. Run `03-work` to implement it.
+
+## Rule 4: After work, review
+
+If code changes have been made (detected by git diff) and no recent review exists:
+- Recommend `04-review`
+- Reason: Implementation is done. Review the changes with structured findings.
+
+## Rule 5: After review, compound
+
+If a review has been completed and `solutions.count` has not increased since the last workflow cycle:
+- Recommend `05-compound`
+- Reason: A review was completed. Capture key learnings as a durable solution artifact.
+
+## Rule 6: All artifacts exist
+
+If brainstorm, plan, and solution all exist:
+- Recommend `05-compound` if no recent solution was added
+- Otherwise recommend `01-brainstorm` for a new cycle
+- Reason: A full loop may be complete. Either compound learnings or start a new cycle.
+
+## Fallback
+
+If no rule matches cleanly:
+- Recommend `08-status`
+- Reason: State is ambiguous. Get a detailed report before deciding.

package/skills/07-worktree/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: 07-worktree
+description: Create and manage git worktrees for isolated feature development.
+---
+
+# 03-worktree
+
+Use this skill when you need to create an isolated git worktree for feature work, merge changes back, or clean up after completion.
+
+## Core rules
+
+- Use the `worktree_manager` tool for all git worktree operations.
+- Default behavior is to **automatically create** a worktree with 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, merge back and clean up.
+- Never force operations — if a worktree already exists, report its status instead of creating a duplicate.
+
+## Workflow
+
+1. **Create**: Use `worktree_manager` with operation `create` to spin up a new worktree with a feature branch.
+2. **Detect**: Use `worktree_manager` with operation `detect` to check if already inside a worktree.
+3. **Execute**: Run `03-work` inside the worktree directory.
+4. **Merge**: Use `worktree_manager` with operation `merge` to merge the feature branch back to main.
+5. **Cleanup**: Use `worktree_manager` with operation `cleanup` to remove the worktree and delete the branch.
+
+## Output
+
+After creation, report:
+- Worktree path
+- Branch name
+- Instruction to run `03-work` in the worktree directory
+
+After merge, report:
+- Merge result
+- Whether cleanup is recommended

package/skills/07-worktree/references/worktree-lifecycle.md

@@ -0,0 +1,22 @@
+# Worktree lifecycle
+
+## Default flow
+
+1. `create` — derive branch name from plan topic or task description
+2. `detect` — check if already in a worktree (avoid nested worktrees)
+3. Execute work via `03-work` in the worktree directory
+4. `merge` — merge feature branch back to main
+5. `cleanup` — remove worktree and delete branch
+
+## Branch naming
+
+- Use `feat/<slug>` for feature work
+- Use `fix/<slug>` for bug fixes
+- Use `chore/<slug>` for maintenance tasks
+- Slug is derived from the plan or task topic using `normalizeSlug`
+
+## Error handling
+
+- If worktree creation fails, check for existing worktrees with `detect`
+- If merge has conflicts, report them and let the user resolve
+- If cleanup fails, suggest manual `git worktree remove`

package/skills/08-status/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: 08-status
+description: Inspect repo-local workflow artifacts and recommend the next Compound Engineering step.
+---
+
+# Status
+
+Use this skill when the user wants to know the current state of the Compound Engineering workflow in this repository.
+
+## What to scan
+
+Use the `workflow_state` tool to get structured artifact state. It scans these repo-local locations:
+
+- `docs/brainstorms/`
+- `docs/plans/`
+- `docs/solutions/`
+- `.context/compound-engineering/`
+
+Use the `session_history` tool to check recent CE skill executions and their outcomes.
+
+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.
+
+## Recommendation logic
+
+- If there is no recent `docs/brainstorms/` artifact and the request is still ambiguous, recommend `01-brainstorm` next.
+- If a recent brainstorm exists but there is no matching plan in `docs/plans/`, recommend `02-plan` next.
+- If a recent plan exists and implementation appears incomplete, recommend `03-work` next.
+- If code has changed after planning, recommend `04-review` next.
+- If a problem was just solved and there is no matching learning in `docs/solutions/`, recommend `05-compound` next.
+- If multiple artifacts exist, summarize them briefly and name the single best next step.
+
+## Output format
+
+Return:
+
+- latest relevant brainstorm
+- latest relevant plan
+- latest relevant solution
+- latest relevant runtime artifact under `.context/compound-engineering/`
+- recommended next step
+- why this is the next step

package/skills/08-status/references/artifact-locations.md

@@ -0,0 +1,10 @@
+# Artifact Locations
+
+| Artifact | Path |
+|---|---|
+| Brainstorm | `docs/brainstorms/` |
+| Plan | `docs/plans/` |
+| Solution | `docs/solutions/` |
+| Runtime | `.context/compound-engineering/` |
+
+Use `bash` with `ls` and `find` to scan these paths.

package/skills/09-help/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: 09-help
+description: Explain when to use each Compound Engineering Phase 1 skill and how they connect.
+---
+
+# Help
+
+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-compound` — use after solving a problem so the repo gains a durable learning in `docs/solutions/`.
+- `08-status` — use when the user wants to know which artifact already exists and what the next workflow step should be.
+
+## 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-compound`.
+6. Use `08-status` at any point to inspect repo-local workflow state.
+
+## Output
+
+When responding, explain the smallest useful next step instead of forcing the full sequence.

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

@@ -0,0 +1,9 @@
+# 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)
+3. `03-work` → execute the plan
+4. `04-review` → inspect the changes (optionally + Browser QA / QA + Regression Tests)
+5. `05-compound` → save key learnings
+
+Use `08-status` at any point to see where you are.