@leing2021/super-pi 0.23.0 → 0.23.1

package/skills/01-brainstorm/SKILL.md

@@ -5,120 +5,83 @@ description: "Brainstorm requirements with three modes: CE discovery, Startup Di
 
 # Brainstorm
 
-Use this skill when the request is ambiguous, needs requirements discovery before planning, or the user describes a new idea/product.
+Use this skill when the request is ambiguous, needs requirements discovery, or the user describes a new idea/product.
 
 See [shared pipeline instructions](../references/pipeline-config.md) for model routing and pipeline behavior.
 
 ## Core rules
 
-- Use **`brainstorm_dialog`** to manage multi-round conversations.
-- Start with `start` operation: present initial analysis and open questions.
-- Use `refine` operation: incorporate user responses and produce refined analysis with new questions.
-- Repeat refine rounds until all open questions are resolved.
-- End with `summarize` operation: finalize into a requirements-ready artifact.
-- Ask **one question at a time** within each round.
+- Use **`brainstorm_dialog`** to manage multi-round conversations (`start` → `refine` → `summarize`).
+- Ask **one question at a time**.
 - Compare **2-3 approaches** when multiple directions are plausible.
-- Keep the artifact focused on **what** should be built, not implementation details by default.
-- Write the result to `docs/brainstorms/` as a durable requirements document.
-- End by recommending `02-plan` when the requirements are ready.
-- **Do not proceed to planning without explicit user approval** of the design.
+- Keep focused on **what** to build, not implementation details.
+- **Explicit user approval required** before handoff to `02-plan`.
+- Write result to `docs/brainstorms/` as durable requirements document.
 
 ## Mode selection
 
-After initial context gathering, determine which mode to use. Use `ask_user_question`:
+After initial context, determine mode via `ask_user_question`:
 
-> Before we dig in, what's your goal with this?
->
-> - **Building a startup** (or thinking about it)
-> - **Intrapreneurship** — internal project, need to ship fast
-> - **Side project / hackathon / learning** — building for fun or exploration
-> - **Adding a feature** — already have a project, need to design a change
+> What's your goal?
+> - **Building a startup** → Startup Diagnostic
+> - **Intrapreneurship** → Startup Diagnostic
+> - **Side project / hackathon** → Builder Mode
+> - **Adding a feature** → CE Brainstorm
 
-**Mode mapping:**
-- Startup, intrapreneurship → **Startup Diagnostic** (see `references/startup-diagnostic.md`)
-- Side project, hackathon, learning → **Builder Mode** (see `references/builder-mode.md`)
-- Adding a feature → **CE Brainstorm** (the existing requirements discovery flow below)
-
-If the user's request already makes the mode obvious (e.g., "I have a startup idea"), skip the question and go directly to the matching mode.
-
-## Startup Diagnostic mode
-
-Read `references/startup-diagnostic.md` for the full YC-style forcing questions, pushback patterns, and anti-sycophancy rules.
-
-Key differences from CE mode:
-- **Operating principles:** Specificity is the only currency. Interest is not demand. The status quo is your real competitor. Narrow beats wide, early.
-- **Ask the six forcing questions** one at a time, pushing until answers are specific and uncomfortable.
-- **Smart routing:** Pre-product (Q1-Q3), Has users (Q2, Q4, Q5), Paying customers (Q4, Q5, Q6).
-- **End with the assignment:** One concrete action the founder should take next.
+Skip question if mode is obvious from request.
 
-After the diagnostic, run Premise Challenge (see `references/premise-challenge.md`), then proceed to Alternatives Generation and design checklist.
-
-## Builder Mode
-
-Read `references/builder-mode.md` for the full generative question set and response posture.
-
-Key differences from CE mode:
-- **Operating principles:** Delight is the currency. Ship something you can show. Solve your own problem. Explore before you optimize.
-- **Ask generative questions** one at a time (coolest version, who would you show, fastest path, what's different, 10x version).
-- **End with concrete build steps**, not business validation tasks.
-- **Vibe shift detection:** If the user starts talking about customers/revenue, upgrade to Startup Diagnostic.
-
-After the questions, run Premise Challenge (see `references/premise-challenge.md`), then proceed to Alternatives Generation and design checklist.
+**Mode mapping:**
+- Startup / intrapreneurship → **Startup Diagnostic** (see `references/startup-diagnostic.md`)
+- Side project / hackathon → **Builder Mode** (see `references/builder-mode.md`)
+- Feature addition → **CE Brainstorm** (see `references/ce-brainstorm-mode.md`)
 
-## CE Brainstorm mode (existing flow)
+## Mode summaries
 
-This is the original Compound Engineering brainstorm. Use when adding a feature to an existing project.
+| Mode | Key principle | End goal |
+|---|---|---|
+| Startup Diagnostic | Specificity is currency, narrow beats wide | One concrete next action |
+| Builder Mode | Delight is currency, ship something showable | Concrete build steps |
+| CE Brainstorm | Requirements clarity | Implementation-ready spec |
 
-1. Scan the repository for nearby context.
-2. Use `brainstorm_dialog` `start` to begin multi-round refinement.
-3. Present initial analysis and open questions to the user.
-4. Use `brainstorm_dialog` `refine` to incorporate user responses and refine analysis.
-5. Repeat step 4 until all questions are resolved.
+See reference files for full question sets and patterns.
 
-## Premise Challenge (all modes)
+## Premise Challenge
 
-After the mode-specific questions are complete, run the Premise Challenge. See `references/premise-challenge.md`.
+After mode-specific questions, run Premise Challenge. See `references/premise-challenge.md`.
 
 ## Design checklist
 
 Before summarizing, ensure the design answers:
 - What are we building?
 - Why does it exist?
-- What files/modules are likely to change?
-- What are the boundaries between responsibilities?
-- What can fail, and how should failure be handled?
+- What files/modules will change?
+- What are the responsibility boundaries?
+- What can fail, and how?
 - How will we verify success?
 
 ## Stop conditions
 
-Stop and ask the user instead of guessing when:
-- requirements conflict
-- success criteria are unclear
-- the task spans multiple independent systems
-- the user has not approved the design yet
+Stop and ask instead of guessing when: requirements conflict, success criteria unclear, task spans multiple systems, or user hasn't approved design.
 
 ## Approval gate
 
-Before handing off to `02-plan`:
-1. Present the final design to the user.
-2. Ask for explicit approval.
-3. Only proceed after the user confirms.
+**Required:** Explicit user approval before handoff to `02-plan`.
 
 ## Workflow
 
-1. Scan the repository for nearby context.
-2. Determine mode (Startup / Builder / CE) via the mode selection step.
-3. Run mode-specific questions using the appropriate reference file.
-4. Run Premise Challenge.
-5. Generate 2-3 alternatives (at least one "minimal viable" and one "ideal architecture").
-6. Validate against the design checklist.
-7. Use `brainstorm_dialog` `summarize` to finalize the conversation.
-8. Capture the agreed direction in a requirements artifact under `docs/brainstorms/`.
-9. Get explicit user approval before handing off.
-10. Hand off to `02-plan` using `references/handoff.md`.
+1. Scan repository for nearby context
+2. Determine mode (Startup / Builder / CE)
+3. Run mode-specific questions (use reference files)
+4. Run Premise Challenge
+5. Generate 2-3 alternatives (minimal viable + ideal architecture)
+6. Validate against design checklist
+7. Use `brainstorm_dialog` `summarize` to finalize
+8. Capture requirements in `docs/brainstorms/`
+9. Get explicit user approval
+10. Handoff to `02-plan` using `references/handoff.md`
 
 ## Artifact contract
 
-Use `references/requirements-template.md` to structure the requirements document. Keep implementation details out unless the brainstorm is specifically about architecture or technical direction.
+Use `references/requirements-template.md` to structure the document. Keep implementation details out unless specifically about architecture.
 
 Before finishing this skill, apply the completion checklist in [shared pipeline instructions](../references/pipeline-config.md).

package/skills/01-brainstorm/references/ce-brainstorm-mode.md

@@ -0,0 +1,47 @@
+# CE Brainstorm Mode
+
+Standard requirements discovery flow for feature additions to existing projects.
+
+## When to use
+
+- Adding a feature to an existing project
+- User has a project but unclear about what to build
+- Request is somewhat specific but needs elaboration
+
+## Operating principle
+
+**Requirements clarity** — the goal is to produce implementation-ready specifications.
+
+## Workflow
+
+1. Scan the repository for nearby context
+2. Use `brainstorm_dialog` `start` to begin multi-round refinement
+3. Present initial analysis and open questions to the user
+4. Use `brainstorm_dialog` `refine` to incorporate user responses and refine analysis
+5. Repeat step 4 until all questions are resolved
+
+## Key questions
+
+Ask one at a time:
+- What problem does this feature solve?
+- Who is the user/consumer?
+- What does success look like?
+- What are the boundaries?
+- What could go wrong?
+
+## End state
+
+Requirements document covering:
+- Feature purpose and scope
+- User-facing behavior
+- Edge cases and failure modes
+- Success criteria
+- Likely file changes
+
+## Difference from other modes
+
+| Aspect | CE Brainstorm | Startup Diagnostic | Builder Mode |
+|---|---|---|---|
+| Goal | Implementation clarity | Business validation | Buildable prototype |
+| Questions | Requirements-focused | Problem-first | Solution-first |
+| Output | Spec document | One action | Build steps |

package/skills/02-plan/SKILL.md

@@ -11,77 +11,58 @@ See [shared pipeline instructions](../references/pipeline-config.md) for model r
 
 ## Core rules
 
-- Before planning, load project rules:
-  1. `rules/common/development-workflow.md` and `rules/common/testing.md`
-  2. Detect the project's primary language 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 task involves frontend/browser concerns, also load `rules/web/` files
-- Priority: project-level `{repo-root}/rules/` overrides package-level defaults
-- Search `docs/brainstorms/` for a relevant requirements artifact first.
-- 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.
-- Write the final plan to `docs/plans/`.
-- Break the work into implementation units instead of writing an execution script.
-- If a plan already exists, use **`plan_diff`** to compare existing units with new requirements and apply incremental changes instead of rewriting.
-- End by recommending `03-work` once the plan is ready.
+1. Load project rules (4 steps):
+   - Load `rules/common/development-workflow.md` and `rules/common/testing.md`
+   - Detect project language via [language detection](../references/language-detection.md)
+   - Load matching language-specific rules (e.g., `rules/typescript/`)
+   - If frontend/browser concerns, also load `rules/web/` files
+2. **Priority:** project-level `{repo-root}/rules/` overrides package defaults
+3. Search `docs/brainstorms/` for relevant requirements first
+4. 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
+5. Write plan to `docs/plans/`
+6. If plan exists, use **`plan_diff`** to compare and patch incrementally
+7. End by recommending `03-work`
 
 ## Hard gates — TDD enforcement
 
-Every implementation unit must follow **RED, GREEN, REFACTOR**:
-- No production code step may appear before a failing test step.
-- Every unit must include exact verification commands.
-- No placeholders allowed — replace "handle edge cases" with concrete steps.
+Every unit follows **RED → GREEN → REFACTOR**:
 
-**TDD violation rejection criteria** — stop and revise the plan if any unit:
-- implements code before a failing test
-- lacks a command proving the RED step
-- lacks a command proving the GREEN step
-- skips verification
-- relies on unstated tools or assumptions
+**TDD violation rejection criteria** — reject and revise if any unit:
+- Implements code before failing test
+- Lacks RED step verification
+- Lacks GREEN step verification
+- Skips verification
+- Uses placeholders or unstated assumptions
 
 ## Planning flow
 
-1. Read the most relevant brainstorm artifact from `docs/brainstorms/` when one exists.
-2. 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.
-3. Gather repository context from the affected areas.
-4. If a plan already exists:
-   a. Use `plan_diff` `compare` to identify added, removed, modified, and unchanged units.
-   b. Review the diff with the user.
-   c. Use `plan_diff` `patch` to apply approved changes.
-5. If no plan exists, write a new plan artifact under `docs/plans/` using `references/plan-template.md`.
-6. Structure the work using `references/implementation-unit-template.md`.
-7. Verify every unit follows strict TDD — reject units that violate the gates above.
+1. Read relevant brainstorm from `docs/brainstorms/`
+2. Run solution search (keywords → grep frontmatter → read top 3)
+3. Gather repository context
+4. If plan exists: use `plan_diff` `compare` → review with user → `patch`
+5. If no plan: write new plan under `docs/plans/` using `references/plan-template.md`
+6. Structure work using `references/implementation-unit-template.md`
+7. Verify every unit follows TDD gates
 
 ## Optional: CEO Review
 
-After the plan artifact is written (step 5 or 6 above), offer the user a strategic review:
-
-> Plan ready. How do you want to review it?
->
-> - **A) Just go** — trust the plan, skip review
-> - **B) CEO Review** — challenge premises, check for better alternatives, dream-state mapping
-> - **C) Strict Review** — full CEO Review plus error maps, failure modes, test diagrams
-
-If the user picks A, proceed directly to the `03-work` handoff.
-If the user picks B or C, read `references/ceo-review-mode.md` and execute the review flow.
-
-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.
-
-## Implementation unit format
-
-Every unit must include:
-- **Purpose**: what this unit accomplishes
-- **Files**: exact paths to create, modify, or test
-- **Steps** as checkboxes:
-  1. Write or update a failing test
-  2. Run the targeted test and confirm it fails for the expected reason (RED)
-  3. Write the minimal implementation needed to pass
-  4. Run the targeted test and confirm it passes (GREEN)
-  5. Refactor if needed while keeping tests green
-  6. Run unit-level verification
-- **Verification commands**: exact commands to run
-- **Expected results**: what success looks like
+After plan is written, offer strategic review:
+
+> Plan ready. How to review?
+> - **A) Just go** — trust the plan
+> - **B) CEO Review** — challenge premises, dream-state mapping
+> - **C) Strict Review** — CEO + error maps, failure modes, test diagrams
+
+If B or C: read `references/ceo-review-mode.md` and execute review flow.
+After review: update plan artifact, then handoff to `03-work`.
+
+## Artifact output
+
+- Plan: `docs/plans/<slug>.md`
+- Use `references/plan-template.md` structure
+- Implementation units follow `references/implementation-unit-template.md`
 
 Before finishing this skill, apply the completion checklist in [shared pipeline instructions](../references/pipeline-config.md).

package/skills/02-plan/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/03-work/SKILL.md

@@ -5,73 +5,52 @@ 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.
+Use this skill when there is a plan path or tightly scoped bare prompt ready for execution.
 
 See [shared pipeline instructions](../references/pipeline-config.md) for model routing and pipeline behavior.
 
 ## Core rules
 
-- Before execution, load project rules:
-  1. `rules/common/development-workflow.md` and `rules/common/testing.md`
-  2. Detect the project's primary language 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 task involves frontend/browser concerns, also load `rules/web/` files
-- Priority: project-level `{repo-root}/rules/` overrides package-level defaults
-- Distinguish between a **plan path** input and a **bare prompt** input before doing work.
-- Prefer deriving execution tasks from plan **implementation units**.
-- Prefer inline execution for small or tightly scoped units.
-- Use **`ce_parallel_subagent`** for independent CE skill-based units that can run concurrently.
-- Use **`ce_subagent`** only for dependent serial chains that benefit from isolated context or specialized CE skill execution.
-- Note: the generic `subagent` / `parallel_subagent` tool names are reserved for third-party agent extensions (e.g. `pi-subagents`); CE skill-router uses the `ce_`-prefixed names to avoid tool-name conflicts.
-- 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 `ce_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`.
+1. Load project rules (4 steps):
+   - Load `rules/common/development-workflow.md` and `rules/common/testing.md`
+   - Detect project language via [language detection](../references/language-detection.md)
+   - Load matching language-specific rules
+   - If frontend/browser concerns, also load `rules/web/` files
+2. **Priority:** project-level `{repo-root}/rules/` overrides package defaults
+3. **Distinguish input:** plan path vs bare prompt
+4. Derive tasks from plan **implementation units**
+5. **Execution mode:**
+   - **Inline mode** for small/scoped units
+   - **`ce_parallel_subagent`** for independent CE skill units
+   - **`ce_subagent`** only for dependent serial chains
+6. Use **`session_checkpoint`** to track progress and enable resume
+7. Use **`task_splitter`** to analyze dependencies before execution
+8. If in **worktree** (via `07-worktree`), execute inside it
+9. 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.
+Every step follows **RED → GREEN → REFACTOR**:
 
 **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
+- Code written before RED test
+- RED fails for wrong reason
+- Missing evidence test failed before implementation
+- Missing evidence 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 by default; use `ce_parallel_subagent` for independent CE skill units and `ce_subagent` only for valuable dependent serial chains.
-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
+1. Detect input type (plan path vs bare prompt)
+2. Read implementation units if plan path
+3. Load `session_checkpoint` to skip completed units
+4. Use `task_splitter` for dependency analysis
+5. Execute: **inline mode** by default, `ce_parallel_subagent` for independent units
+6. Follow TDD per unit: RED → minimal code → GREEN → refactor → unit-level **verification**
+7. Record progress via `references/progress-update-format.md`
+8. Save `session_checkpoint` after each unit
+9. On failure: `session_checkpoint` `fail` → `retry` → follow strategy
+10. Provide completion report (see `references/completion-report.md`)
+11. Handoff to `04-review` using `references/handoff.md`
 
 Before finishing this skill, apply the completion checklist in [shared pipeline instructions](../references/pipeline-config.md).

package/skills/03-work/references/completion-report.md

@@ -0,0 +1,51 @@
+# Completion Report Template
+
+When all implementation units are complete, provide this report:
+
+## Summary
+
+Brief description of what was completed.
+
+## Completed units
+
+| Unit | Status | Verification |
+|---|---|---|
+| unit-name-1 | ✅ Done | command output |
+| unit-name-2 | ✅ Done | command output |
+
+## Files changed
+
+- Created: `path/to/file`
+- Modified: `path/to/file`
+
+## Commands run
+
+| Command | Result |
+|---|---|
+| `npm test` | ✅ Pass |
+| `npm run build` | ✅ Pass |
+
+## Verification results
+
+All tests pass. Build succeeds. No regressions.
+
+## Follow-up work
+
+- Any remaining risks
+- Open questions
+- Suggested next steps
+
+---
+
+## Report format for skill output
+
+```
+## Completion Report
+
+**Completed:** list of unit names
+**Files changed:** all created/modified files
+**Commands run:** all verification commands
+**Verification:** pass/fail status for each
+
+**Next:** `/skill:04-review`
+```