@leing2021/super-pi 0.23.4 → 0.23.6

package/README.md

@@ -1,32 +1,86 @@
 # Super Pi
 
-**Turn your AI coding agent from "a tool that writes code" into "a reliable engineer."**
+![Super Pi Workflow](docs/assets/super-pi.png)
 
-Install it, tell Pi what you want to build, then keep saying "continue" — it walks through the full loop: **think → plan → build → review → compound learnings.**
+[中文](README-CN.md)  | [English](README.md) 
+
+
+
+**Turn your AI coding agent into a reliable engineer.**
+
+Install, describe what you want to build, then keep saying "continue." Super Pi drives the full loop:
+
+ **think → plan → build → review → compound learnings.**
+
+```bash
+pi install npm:@leing2021/super-pi
+```
+
+---
+
+## Highlights
+
+- **Five-step loop** — brainstorm → plan → work → review → learn, with automatic skill routing
+- **Checkpoint resume** — interrupted? Resume from the exact unit you left off
+- **TDD enforcement** — every unit follows RED → GREEN → REFACTOR with hard gates
+- **Parallel execution** — independent units run concurrently via `ce_parallel_subagent`
+- **Evidence-first review** — auto-assigned reviewers across five axes, autofix loop
+- **Knowledge compounding** — solved problems become searchable solution artifacts
+- **Token-efficient** — ~2,600 tokens new-conversation overhead; progressive loading
+
+---
+
+## Quickstart
 
 ```bash
 pi install npm:@leing2021/super-pi
 ```
 
+Then in Pi:
+
+```
+You: I want to build a CLI tool that helps indie devs find early users
+
+→ 01-brainstorm: structured discovery → requirements artifact
+→ 02-plan: TDD-gated implementation units → plan artifact
+→ 03-work: parallel execution, checkpoint resume
+→ 04-review: five-axis findings, autofix loop
+→ 05-learn: knowledge compounding
+
+You: continue
+→ Next skill recommended via /skill:06-next
+```
+
+**Resume after interruption:**
+
+```
+You: /skill:03-work docs/plans/plan.md
+→ Loads checkpoint, skips completed units, resumes from breakpoint
+```
+
 ---
 
 ## The Five-Step Loop
 
 ```
 01-brainstorm → 02-plan → 03-work → 04-review → 05-learn
-    think          plan      build      review      learn
+    think         plan      build      review      learn
 ```
 
-| Skill | Does | Core Tool |
-|-------|------|-----------|
-| **01-brainstorm** | YC-style interrogation, three modes (Startup/Builder/CE) | `brainstorm_dialog` |
-| **02-plan** | RED→GREEN→REFACTOR, incremental updates, optional CEO Review | `plan_diff` |
-| **03-work** | Parallel execution, checkpoint resume, strict TDD | `ce_subagent`, `ce_parallel_subagent` |
-| **04-review** | Auto-assigned reviewers, structured findings, browser QA | `review_router` |
-| **05-learn** | Pattern extraction → searchable knowledge cards | `pattern_extractor` |
-| **06-next** | Next-step recommendation + full status report | `workflow_state` |
+| Skill | What it does | Core tool |
+|-------|-------------|-----------|
+| **01-brainstorm** | Structured multi-round discovery | `brainstorm_dialog` |
+| **02-plan** | TDD-gated implementation units, optional CEO Review | `plan_diff` |
+| **03-work** | Parallel execution, checkpoint resume, strict TDD, stop-the-line | `ce_subagent`, `ce_parallel_subagent` |
+| **04-review** | Auto-assigned reviewers, five-axis findings, autofix loop | `review_router` |
+| **05-learn** | Pattern extraction → searchable solution artifacts | `pattern_extractor` |
+| **06-next** | Next-step recommendation + workflow status | `workflow_state` |
 | **07-worktree** | Isolated git worktree development | `worktree_manager` |
-| **08-help** | Phase 1 skill explainer and usage guide | — |
+| **08-help** | Phase 1 skill explainer | — |
+
+### Subagent tool namespace
+
+Super Pi ships CE-specific tools named `ce_subagent` and `ce_parallel_subagent`. They are intentionally namespaced so they can coexist with the compatible third-party `pi-subagents` extension without tool-name collisions.
 
 ### Model & Thinking Routing
 
@@ -48,32 +102,46 @@ Configure in `.pi/settings.json`:
 
 Model and thinking level switch automatically — no manual `/model` needed.
 
-### pi-subagents Compatibility
+## Design Philosophy & Acknowledgements
+
+**80% planning and review, 20% execution.**
+
+The goal is not to make AI write code faster. The goal is to make AI think before writing, review after writing, and compound what it learns.
+
+Super Pi is not a fork or wrapper. It extracts useful methods from the projects below and rebuilds them with Pi-native skills, tools, artifacts, checkpoints, and handoffs.
 
-CE skill tools use a dedicated namespace (`ce_subagent`, `ce_parallel_subagent`) to avoid conflicts with third-party extensions like [pi-subagents](https://www.npmjs.com/package/pi-subagents). Both can coexist without configuration.
+| Project | What Super Pi adopted |
+|---------|------------------------|
+| [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) | "Use when" skill trigger conditions, source-driven verification, stop-the-line hard gate, anti-rationalization, and the five-axis review baseline. Adopted as embedded micro-patterns only — no new skills, tools, commands, or agents. |
+| [everything-claude-code](https://github.com/affaan-m/everything-claude-code) | Parallel subagent orchestration, checkpoint resume, continuous learning loops, and token-conscious agent workflow design. |
+| [superpowers](https://github.com/obra/superpowers) | Strict TDD gates, design checklists, review discipline, and the idea that agents need hard gates instead of gentle suggestions. |
+| [compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin) | The five-step think → plan → build → review → learn loop and the knowledge-compounding backbone. |
+| [gstack](https://github.com/garrytan/gstack) | YC-style forcing questions, CEO Review cognitive frameworks, browser QA patterns, failure maps, and evidence-first validation. |
 
 ---
 
-## Quick Start
+## Behavioral Gates
 
-```
-You: I want to build a tool that helps indie devs find users
+### Stop-the-line (Hard gate)
 
-→ 01-brainstorm: YC-style interrogation → docs/brainstorms/requirements.md
-→ 02-plan: RED→GREEN→REFACTOR units → docs/plans/plan.md
-→ 03-work: parallel execution, checkpoint resume
-→ 04-review: structured findings, optional browser QA
-→ 05-learn: knowledge compounding
+When an unexpected failure occurs during `03-work`:
 
-You: continue
-→ Next skill recommended automatically via /skill:06-next
-```
+1. **STOP** adding features
+2. **PRESERVE** evidence
+3. **DIAGNOSE** root cause
+4. **FIX** the root cause
+5. **GUARD** with a regression test
+6. **RESUME** only after verification passes
 
-**After interruption:**
-```
-You: /skill:03-work docs/plans/plan.md
-→ Auto-loads checkpoint, skips completed units, resumes from breakpoint
-```
+Anti-rationalization: do not rationalize, downgrade, or explain away failures. Stop and report with evidence.
+
+### Source-driven verification
+
+When implementation depends on a framework/library API, version-specific behavior, or a recommended pattern: verify against official documentation before implementing. Pure logic, renaming, or in-project pattern reuse does not require external citation.
+
+### Review five axes
+
+All reviewers evaluate changes across: **correctness, readability, architecture, security, performance.**
 
 ---
 
@@ -84,12 +152,12 @@ New conversation overhead: **~2,600 tokens** (1.3% of 200K context).
 | Component | Tokens |
 |-----------|--------|
 | 8 skill registrations | ~490 |
-| System prompt (skills) | ~1,400 |
+| System prompt | ~1,400 |
 | Skill inlining (per invocation) | ~500-800 |
 
 Progressive loading: only needed skills loaded on-demand.
 
-Full evaluation → [`docs/token-cost-evaluation.md`](docs/token-cost-evaluation.md)
+See [docs/token-cost-evaluation.md](docs/token-cost-evaluation.md) for detailed per-skill breakdown and measurement methodology.
 
 ---
 
@@ -100,26 +168,38 @@ your-project/
 ├── docs/
 │   ├── brainstorms/      # Requirements
 │   ├── plans/             # Execution plans
-│   └── solutions/          # Knowledge cards
+│   └── solutions/         # Knowledge cards
 └── .context/
     └── compound-engineering/
         ├── checkpoints/   # Breakpoint files
-        ├── dialogs/       # Dialog state
+        ├── handoffs/      # Cross-stage context
         └── history/       # Execution history
 ```
 
-**Commit everything to git** — these files are the project's traceable memory.
+Commit everything to git — these files are the project's traceable memory.
 
 ---
 
 ## Architecture
 
-- **8 skills** with dedicated tools
-- **14 tools** + 2 helpers
-- **~2800 lines** TypeScript, **175 tests**
-- **Progressive rule loading** — only what each task needs
+| Component | Count |
+|-----------|------:|
+| Skills | 8 |
+| Tools | 19 |
+| Rules | 79 |
+| TypeScript lines | ~4,400 |
+| Tests | 209 (786 assertions) |
+
+Rules in `rules/` cover 11 common topics + language-specific sets (TypeScript, Rust, Go, Python, Java, Kotlin, C++, C#, Dart, Swift, Perl, PHP). Project-level overrides take priority.
+
+---
+
+## Commands
 
-Rules in `rules/` (11 common + language-specific). Project-level overrides take priority.
+| Command | Description |
+|---------|-------------|
+| `bun test` | Run all tests |
+| `npm publish --dry-run` | Preview package contents |
 
 ---
 
@@ -127,14 +207,8 @@ Rules in `rules/` (11 common + language-specific). Project-level overrides take
 
 See [CHANGELOG.md](./CHANGELOG.md) for full version history.
 
-## Repository
+## Links
 
-- **GitHub**: https://github.com/leing2021/super-pi
 - **npm**: https://www.npmjs.com/package/@leing2021/super-pi
-
-## Development
-
-```bash
-bun test
-npm publish --dry-run
-```
+- **GitHub**: https://github.com/leing2021/super-pi
+- **License**: MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leing2021/super-pi",
-  "version": "0.23.4",
+  "version": "0.23.6",
   "private": false,
   "type": "module",
   "description": "Pi-native Compound Engineering package for iterative development workflows",

package/rules/common/development-workflow.md

@@ -13,6 +13,7 @@ The Feature Implementation Workflow describes the development pipeline: research
    - **Check package registries:** Search npm, PyPI, crates.io, and other registries before writing utility code. Prefer battle-tested libraries over hand-rolled solutions.
    - **Search for adaptable implementations:** Look for open-source projects that solve 80%+ of the problem and can be forked, ported, or wrapped.
    - Prefer adopting or porting a proven approach over writing net-new code when it meets the requirement.
+   - **Source-driven trigger:** When implementation depends on a framework/library API, version-specific behavior, or a recommended pattern, verify against official documentation and cite key sources in the output. Pure logic, renaming, or in-project pattern reuse does not require external citation.
 
 1. **Plan First**
    - Use **planner** agent to create implementation plan

package/skills/01-brainstorm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: 01-brainstorm
-description: "Brainstorm requirements with three modes: CE discovery, Startup Diagnostic, Builder Mode."
+description: "Discover requirements through structured multi-round dialog. Use when the request is ambiguous, needs discovery, or describes a new idea/product."
 ---
 
 # Brainstorm

package/skills/02-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: 02-plan
-description: "Turn requirements into a plan. Optional CEO-style strategic review after."
+description: "Turn requirements into an execution-ready plan with TDD-gated implementation units. Use when a brainstorm artifact exists and is ready for planning."
 ---
 
 # Plan
@@ -43,7 +43,8 @@ Every unit follows **RED → GREEN → REFACTOR**:
 2. Read relevant brainstorm from `docs/brainstorms/`
 3. Run solution search (keywords → grep frontmatter → read top 3)
 4. Gather repository context
-5. If plan exists: use `plan_diff` `compare` → review with user → `patch`
+5. **Source-driven check:** For each unit that involves framework/library APIs, add a note: "Verify against official docs before implementing."
+6. If plan exists: use `plan_diff` `compare` → review with user → `patch`
 6. If no plan: write new plan under `docs/plans/` using `references/plan-template.md`
 7. Structure work using `references/implementation-unit-template.md`
 8. Verify every unit follows TDD gates

package/skills/03-work/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: 03-work
-description: Execute plan-driven work in a controlled Phase 1 workflow.
+description: "Execute plan units with parallel subagents, TDD enforcement, and checkpoint resume. Use when a plan path is ready for implementation."
 ---
 
 # Work
@@ -39,6 +39,24 @@ Every step follows **RED → GREEN → REFACTOR**:
 - Missing evidence test passed after implementation
 - Tests added only after code
 
+## Stop-the-line rule (Hard gate)
+
+When any unexpected failure occurs during execution:
+
+1. **STOP** adding features or making changes
+2. **PRESERVE** evidence (error output, repro steps)
+3. **DIAGNOSE** root cause — reproduce, localize, reduce
+4. **FIX** the root cause, not the symptom
+5. **GUARD** with a regression test
+6. **RESUME** only after verification passes
+
+Anti-rationalization — when a gate fails or evidence is missing:
+- Do not rationalize, downgrade, or explain away the failure.
+- Stop, report the blocker with evidence, and either fix the root cause or ask for direction.
+- Do not continue unrelated implementation after failed verification.
+
+This is a hard gate — do not push past a failing test or broken build to continue implementation. Errors compound.
+
 ## Workflow
 
 1. **Load context**: consume latest handoff before any broad file reads — `context_handoff load` or read `.context/compound-engineering/handoffs/latest.md`. If found, use `activeFiles`, `blocker`, `verification`, `activeRules` as starting point. If not found, proceed normally.
@@ -48,7 +66,8 @@ Every step follows **RED → GREEN → REFACTOR**:
 5. Use `task_splitter` for dependency analysis
 6. Execute: **inline mode** by default, `ce_parallel_subagent` for independent units
 7. Follow TDD per unit: RED → minimal code → GREEN → refactor → unit-level **verification**
-8. Record progress via `references/progress-update-format.md`
+8. **Source-driven gate:** Before implementing framework/library-specific code, verify the API or pattern against official documentation. Flag unverified patterns as UNVERIFIED in output.
+9. Record progress via `references/progress-update-format.md`
 9. Save `session_checkpoint` after each unit
 10. On failure: `session_checkpoint` `fail` → `retry` → follow strategy
 11. Provide completion report (see `references/completion-report.md`)

package/skills/04-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: 04-review
-description: "Review code with structured findings. Optional browser QA and regression tests."
+description: "Review code changes across five axes with evidence-first findings. Use after implementation is complete and before committing."
 ---
 
 # Review

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

@@ -10,6 +10,8 @@ Use the `review_router` tool to determine which reviewers to apply based on diff
 
 ## Reviewer personas
 
+All reviewers evaluate changes across five axes: correctness, readability, architecture, security, performance. Base reviewers cover axes 1–3 by default; conditional reviewers add depth on specific axes.
+
 ### Base reviewers (always active)
 
 - **correctness-reviewer**: Logical correctness, intended behavior, edge cases.
@@ -19,6 +21,6 @@ Use the `review_router` tool to determine which reviewers to apply based on diff
 ### 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.
+- **performance-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-learn/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: 05-learn
-description: Capture solved problems as reusable solution artifacts.
+description: "Capture solved problems as searchable solution artifacts. Use after a workflow loop completes or a non-trivial problem is solved."
 ---
 
 # Learn

package/skills/06-next/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: 06-next
-description: "Inspect workflow state and recommend the single best next Compound Engineering skill. Use --verbose for a full status report."
+description: "Inspect workflow artifacts and recommend the single best next skill. Use when unsure what to run next."
 ---
 
 # Next

package/skills/07-worktree/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: 07-worktree
-description: Create and manage git worktrees for isolated feature development.
+description: "Create and manage git worktrees for isolated feature development. Use when starting a feature that needs branch isolation."
 ---
 
 # Worktree

package/skills/08-help/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: 08-help
-description: Explain when to use each Compound Engineering Phase 1 skill and how they connect.
+description: "Explain Phase 1 skills and their connections. Use when learning the workflow or deciding which skill applies."
 ---
 
 # Help