@leing2021/super-pi 0.14.1 → 0.15.0

package/README.md

@@ -1,10 +1,8 @@
 # Super Pi
 
-A Pi-native iterative development workflow package, integrating the best ideas from four outstanding open-source projects.
+**Turn your AI coding agent from "a tool that writes code" into "a reliable engineer."**
 
-[中文文档](README_CN.md)
-
-## Install
+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.**
 
 ```bash
 pi install npm:@leing2021/super-pi
@@ -12,333 +10,274 @@ pi install npm:@leing2021/super-pi
 
 ---
 
-## Quick Start
+## Why Super Pi
 
-After installation, tell Pi what you want to build, then keep saying "continue" to walk through the full workflow.
+Using a bare AI agent to write code has three common failure modes:
 
-### Scenario A: Starting a new idea
+1. **Builds before thinking** — you finish and realize it's not what you wanted
+2. **Loses context on interruption** — close the terminal, lose the progress
+3. **Repeats the same mistakes** — every session starts from zero
 
-```
-You: I want to build a tool that helps indie devs find users
+Super Pi's answers:
 
-→ /skill:01-brainstorm
-→ AI asks your goal → you pick "Building a startup"
-→ Enters Startup Diagnostic mode
-→ YC-style forcing questions one at a time: demand evidence? current alternatives? narrowest wedge?
-→ Challenges premises, generates 2-3 approaches
-→ Generates docs/brainstorms/2026-04-18-find-users-requirements.md
-→ Recommends next step: 02-plan
+- **Forces clarity before action** — not a form to fill out, but an AI that interrogates you like a YC partner demanding specific evidence
+- **Auto-resume from checkpoints** — restart after interruption, skip completed work, continue from where you left off
+- **Auto-compounds experience** — every solved problem becomes a searchable knowledge card; next time, the agent finds and reuses it
 
-You: continue
+---
 
-→ /skill:02-plan
-→ Reads requirements artifact
-→ Generates docs/plans/2026-04-18-find-users-plan.md
-→ Asks if you want CEO Review → you pick "CEO Review"
-→ Challenges plan premises, dream-state mapping, forces alternatives, temporal interrogation
-→ Recommends next step: 03-work
+## The Five-Step Loop
 
-You: continue
+```
+01-brainstorm → 02-plan → 03-work → 04-review → 05-compound
+    think          plan      build      review      compound
+```
 
-→ /skill:03-work
-→ Parallel execution, checkpoint resume
-→ Recommends next step: 04-review
+Each step has a dedicated skill + tool pair. Not just prompts — structured toolchains.
 
-You: continue
+---
 
-→ /skill:04-review
-→ Structured code review + autofix
-→ Asks if you want browser QA → you pick "Browser QA"
-→ Opens your app with agent-browser, tests page by page
-→ Fixes bugs found, screenshots as evidence
-→ Recommends next step: 05-compound
+## What Each Step Does
 
-You: continue
+### 01-brainstorm: Think First
 
-→ /skill:05-compound
-→ Extracts reusable patterns
-→ Writes to docs/solutions/ for lasting knowledge
-```
+Not "describe your requirements." Three modes for three scenarios:
 
-### Scenario B: Side Project / Hackathon
+| Mode | For | What it does |
+|------|-----|-------------|
+| **Startup Diagnostic** | Startup ideas, new products | Six YC-style forcing questions, pushed until you produce specific evidence (not "people are interested" — "who would freak out if this disappeared tomorrow?") |
+| **Builder Mode** | Side projects, hackathons | Only focused on building the coolest thing. If you accidentally mention revenue, it auto-upgrades to Startup Diagnostic |
+| **CE Brainstorm** | Adding features to existing projects | Multi-round dialog to clarify scope boundaries, generates a structured requirements doc |
 
-```
-You: I want to make a fun music visualization side project
-
-→ /skill:01-brainstorm
-→ AI asks your goal → you pick "Side project / hackathon"
-→ Enters Builder Mode
-→ Asks: what's the coolest version? fastest path to something you can show?
-→ No business validation, focused on building the coolest thing
-→ If conversation shifts to revenue → auto-upgrades to Startup Diagnostic
-```
+All three modes run a **premise challenge** (are your assumptions valid?) and **alternatives generation** (at least one minimal + one ideal approach) before you're allowed to move on.
 
-### Scenario C: Adding a feature to an existing project
+### 02-plan: Plan Well
 
-```
-You: I want to add user authentication to the project
+Breaks requirements into implementation units, each following strict **RED → GREEN → REFACTOR** (no production code without a failing test first).
 
-→ /skill:01-brainstorm
-→ AI asks your goal → you pick "Adding a feature"
-→ Enters CE Brainstorm (classic requirements discovery)
-→ Multi-round dialog to clarify requirements (OAuth2? JWT? MFA?)
-→ Generates docs/brainstorms/2026-04-18-auth-requirements.md
-→ Recommends next step: 02-plan
-```
+**Incremental updates**: Requirements changed? `plan_diff` detects added/removed/modified units and patches the plan instead of rewriting it.
 
-### Scenario D: Check project status anytime
+**CEO Review (optional)**: After planning, you can request a CEO Review. It challenges your plan using Bezos reversible-decision frameworks, Munger inversion, Jobs subtraction, forces alternative approaches, and draws error maps. Like having a demanding CTO review your proposal for free.
 
-```
-You: /skill:08-status
+### 03-work: Build Right
 
-→ Scans docs/brainstorms/, docs/plans/, docs/solutions/
-→ Queries session_history for recent execution records
-→ Shows current progress + recommends next step
-```
+**Parallel execution**: `task_splitter` uses a Union-Find algorithm to analyze file dependencies, feeds conflict-free units to `parallel_subagent` for concurrent execution.
 
-### Scenario E: Requirements changed, update the plan
+**Checkpoint resume**: After each unit, a checkpoint is saved. Interrupted? Next startup auto-loads, skips completed work, continues from the breakpoint. Failed? `fail` records the error → `retry` suggests a recovery strategy (timeout? extend timeout. Permission issue? check permissions first. Code error? fix then retry).
 
-```
-You: Requirements changed, need to add SSO support
+**Strict TDD**: Run failing test → write minimal implementation → test passes → refactor. Every step requires command output as evidence. No skipping.
 
-→ /skill:02-plan
-→ plan_diff compare detects added/removed/modified units
-→ plan_diff patch applies incremental changes
-→ No need to rewrite the entire plan
-```
+### 04-review: Review Thoroughly
 
-### Scenario F: Resume after interruption
+**Structured code review**: `review_router` auto-assigns reviewer personas based on diff metadata (changed payment code? bring in the security reviewer). Review discipline is technical evaluation, not theater — every finding must cite specific code, YAGNI checks, no performative agreement.
 
-```
-You: /skill:03-work docs/plans/auth-plan.md
+**Browser QA (optional)**: Uses `agent-browser` to open your app, click through pages, screenshot bugs, fix by severity, up to 3 auto-fix iterations. Can auto-generate regression tests. Like having a QA engineer run acceptance tests.
 
-→ session_checkpoint.load finds completed units
-→ Automatically skips completed parts, resumes from checkpoint
-```
+### 05-compound: Compound Learnings
 
-### Scenario G: Isolated development
+`pattern_extractor` scans existing artifacts, extracts and categorizes patterns. Turns "the pitfall we hit this time" into a YAML-tagged solution card in `docs/solutions/`.
 
-```
-You: /skill:07-worktree
+Two-level storage: project-specific → inside the project; cross-project → `~/.pi/agent/docs/solutions/` globally searchable.
 
-→ worktree_manager creates git worktree isolation
-→ Execute 03-work within the worktree
-→ Merge back to main branch when done
-```
+Next time `02-plan` or `04-review` runs, a grep-first search strategy automatically retrieves relevant past experience.
 
 ---
 
-## Skills (9)
+## Technical Architecture
 
-| Skill | Command | Description | Associated Tools |
-|-------|---------|-------------|-----------------|
-| `01-brainstorm` | `/skill:01-brainstorm` | Requirements discovery, three modes: CE / Startup Diagnostic / Builder | `brainstorm_dialog` |
-| `02-plan` | `/skill:02-plan` | Create/update plans, optional CEO Review | `plan_diff` |
-| `03-work` | `/skill:03-work` | Execute plans (parallel + checkpoint + recovery) | `session_checkpoint`, `task_splitter`, `parallel_subagent` |
-| `04-review` | `/skill:04-review` | Code review + optional browser QA | `review_router` |
-| `05-compound` | `/skill:05-compound` | Knowledge compounding | `pattern_extractor` |
-| `06-next` | `/skill:06-next` | Recommend next step | `workflow_state`, `session_history` |
-| `07-worktree` | `/skill:07-worktree` | Worktree isolated development | `worktree_manager` |
-| `08-status` | `/skill:08-status` | Check project status | `workflow_state`, `session_history` |
-| `09-help` | `/skill:09-help` | Usage guide | — |
+### 9 Skills (workflow nodes)
 
----
+| Skill | One-liner | Core Tool |
+|-------|-----------|-----------|
+| `01-brainstorm` | Deep requirements mining in three modes | `brainstorm_dialog` |
+| `02-plan` | Break into units, TDD gates, incremental updates | `plan_diff` |
+| `03-work` | Parallel execution, checkpoint resume, error recovery | `session_checkpoint`, `task_splitter`, `parallel_subagent` |
+| `04-review` | Persona-routed review + live browser testing | `review_router` |
+| `05-compound` | Pattern extraction → knowledge card compounding | `pattern_extractor` |
+| `06-next` | Not sure what to do next? Ask this | `workflow_state`, `session_history` |
+| `07-worktree` | Git worktree isolated development | `worktree_manager` |
+| `08-status` | Scan artifacts, report progress | `workflow_state`, `session_history` |
+| `09-help` | Usage guide | — |
 
-## Tools (13)
+### 13 Tools (underlying capabilities)
 
-| Tool | Description |
+| Tool | What it does |
 |------|-------------|
-| `artifact_helper` | Artifact path resolution + directory creation |
-| `ask_user_question` | Structured user questions (free input / fixed options) |
+| `task_splitter` | Union-Find algorithm analyzes file dependencies, auto-groups parallel-safe units |
+| `session_checkpoint` | JSON-persisted checkpoints with save/load/fail/retry operations |
+| `plan_diff` | Incremental plans: compare detects diffs, patch applies changes |
+| `parallel_subagent` | `Promise.allSettled`-style parallel subagent execution |
+| `review_router` | Auto-assign reviewer personas from diff metadata |
+| `pattern_extractor` | Extract and categorize patterns from artifacts |
+| `brainstorm_dialog` | Multi-round dialog state machine (start → refine × N → summarize) |
+| `session_history` | Cross-session execution history recording and querying |
+| `workflow_state` | Scan docs/ and .context/ to summarize workflow state |
+| `worktree_manager` | Full git worktree lifecycle management |
+| `artifact_helper` | Artifact path resolution and directory creation |
+| `ask_user_question` | Structured user prompts (choices / free input) |
 | `subagent` | Serial subagent chain |
-| `parallel_subagent` | Parallel subagent execution (`Promise.allSettled`) |
-| `workflow_state` | Workflow artifact state scanning |
-| `worktree_manager` | Git worktree lifecycle (create/detect/merge/cleanup) |
-| `review_router` | Diff analysis + reviewer persona routing (base + conditional) |
-| `session_checkpoint` | Plan execution checkpoint + error recovery (save/load/fail/retry) |
-| `task_splitter` | File-level dependency analysis + parallel grouping (union-find) |
-| `brainstorm_dialog` | Multi-round brainstorm dialog management (start/refine/summarize) |
-| `plan_diff` | Plan incremental comparison + patching (compare/patch) |
-| `session_history` | Cross-session execution history (record/query/latest) |
-| `pattern_extractor` | Artifact pattern extraction + categorization (extract/categorize) |
 
 ---
 
-## Core Workflow
+## Code Scale
 
-```
-01-brainstorm → 02-plan → 03-work → 04-review → 05-compound
-   Three modes      CEO Review    Parallel      Browser QA     Knowledge
-   (CE/Startup/     (optional)    Checkpoint    (optional)    compounding
-    Builder)                       Resume
-```
+~2000 lines of TypeScript implementing 13 tools, 22 Markdown reference files driving 9 skills' behavioral strategies, 95 tests covering all tool logic.
 
-`06-next`, `07-worktree`, `08-status`, `09-help` can be used at any stage.
-
----
-
-## Generated File Structure
-
-```
-your-project/
-├── docs/
-│   ├── brainstorms/                        # Generated by 01-brainstorm
-│   │   └── 2026-04-18-auth-requirements.md
-│   ├── plans/                              # Generated by 02-plan
-│   │   └── 2026-04-18-auth-plan.md
-│   └── solutions/                          # Generated by 05-compound
-│       └── auth/
-│           └── oauth2-solution.md
-└── .context/
-    └── compound-engineering/
-        ├── checkpoints/                    # Generated by session_checkpoint
-        │   └── docs-plans-auth-plan.json
-        ├── dialogs/                        # Generated by brainstorm_dialog
-        │   └── docs-brainstorms-auth.json
-        └── history/                        # Generated by session_history
-            └── 1745000000-01-brainstorm.json
-```
+Not a heavy framework. Each tool has a single responsibility, each skill works independently, and together they form a complete workflow.
 
 ---
 
-## Best Practices
-
-| Tip | Description |
-|-----|-------------|
-| **Start with 01-brainstorm** | New ideas → Startup/Builder Mode, features → CE Mode |
-| **Use 08-status to check progress** | Not sure where you are? Use 08-status |
-| **Use 06-next for direction** | Don't know the next step? Use 06-next |
-| **Commit artifacts to git** | Both `docs/` and `.context/` should be committed |
-| **Use 07-worktree for big features** | Isolated development without affecting main branch |
-| **Don't panic on interruption** | Next 03-work will auto-resume from checkpoint |
-| **Use CEO Review to stress-test plans** | After planning, pick CEO Review to challenge premises and find blind spots |
-| **Use Browser QA for acceptance** | After code review, pick Browser QA for real-app testing |
-
----
+## Quick Start
 
-## Acknowledgments & Sources
+### New idea
 
-Super Pi integrates ideas and practices from four outstanding open-source projects. This is not a fork — it's a Pi-native reimplementation of their core insights.
+```
+You: I want to build a tool that helps indie devs find users
 
-### [Compound Engineering](https://github.com/EveryInc/compound-engineering-plugin) — Every Inc.
+→ Auto-enters 01-brainstorm, YC-style interrogation
+→ Generates docs/brainstorms/2026-04-18-find-users-requirements.md
+→ Recommends next: 02-plan
 
-> "Each unit of engineering work should make subsequent units easier — not harder."
+You: continue
 
-The foundational workflow of Super Pi comes directly from Compound Engineering's core philosophy: the **brainstorm → plan → work → review → compound** cycle. The "80% planning and review, 20% execution" philosophy is the backbone of the entire package.
+→ 02-plan breaks into units, optional CEO Review
+→ Generates docs/plans/2026-04-18-find-users-plan.md
 
-**What we adopted:**
-- Five-step workflow architecture (brainstorm → plan → work → review → compound)
-- Knowledge compounding: every engineering cycle produces a reusable solution artifact
-- Artifact-driven state management (tracking progress through persistent docs under `docs/`)
-- Structured review methodology (reviewer persona routing, findings schema)
+You: continue
 
-### [Superpowers](https://github.com/obra/superpowers) — Jesse Vincent
+→ 03-work parallel execution, checkpoint resume
+→ 04-review code review + optional browser QA
+→ 05-compound knowledge compounding
+```
 
-> "A complete software development methodology for your coding agents."
+### Adding a feature
 
-Superpowers' main contribution to Super Pi is **engineering discipline**: strict TDD gates, design checklists, and the anti-performative-agreement principle in reviews.
+```
+You: I want to add user authentication to the project
 
-**What we adopted:**
-- Strict TDD gates (RED → GREEN → REFACTOR) with violation rejection criteria
-- Design checklist (what/why/boundaries/failure/verification)
-- Review discipline: technical evaluation over performative agreement, YAGNI checks
-- User approval gates: no advancing to the next step without explicit confirmation
-- Subagent-driven development patterns
+→ 01-brainstorm CE mode, multi-round dialog: OAuth2? JWT? MFA?
+→ Requirements doc → 02-plan → 03-work → 04-review → 05-compound
+```
 
-### [Everything Claude Code](https://github.com/affaan-m/everything-claude-code) — Affaan Mustafa
+### Resume after interruption
 
-> "The performance optimization system for AI agent harnesses. Not just configs — a complete system."
+```
+You: /skill:03-work docs/plans/auth-plan.md
 
-With 140K+ stars, ECC demonstrated best practices for AI agent toolchains. Super Pi adopted its systematic approach to token optimization, continuous learning, parallelization, and subagent orchestration.
+→ Auto-loads checkpoint, skips completed units, resumes from breakpoint
+```
 
-**What we adopted:**
-- Session history management and continuous learning mechanisms
-- Parallel subagent orchestration patterns (`Promise.allSettled` style)
-- Checkpoint-based resume and error recovery strategies
-- Systematic tool design: each skill paired with a dedicated tool
+### Requirements changed
 
-### [gstack](https://github.com/garrytan/gstack) — Garry Tan / Y Combinator
+```
+You: Requirements changed, need to add SSO support
 
-> "One person's software factory. 23 specialist roles and 8 power tools."
+→ 02-plan uses plan_diff to detect changes, patches incrementally
+```
 
-gstack is Y Combinator CEO Garry Tan's personal AI toolchain, representing the "AI-native founder" way of working. Super Pi integrated the methodology from three core gstack modules in v1.2.0.
+### Check progress anytime
 
-**What we adopted:**
-- **office-hours → 01-brainstorm Startup Diagnostic**: YC-style six forcing questions (demand evidence, status quo alternatives, narrowest wedge), anti-sycophancy rules, per-question pushback patterns
-- **plan-ceo-review → 02-plan CEO Review**: CEO cognitive frameworks (Bezos irreversible decisions, Munger inversion, Jobs subtraction), dream-state mapping, mandatory alternative generation, error maps and failure mode registries
-- **qa → 04-review Browser QA**: Browser-driven QA testing workflow (using Pi-native `agent-browser` instead of gstack's `$B`), health scoring system, diff-aware test scoping, fix loops and regression test generation
+```
+You: /skill:08-status
 
-**Design decisions:** gstack depends on its own infrastructure (`$B` browser binary, `gstack-*` scripts, `~/.gstack/` directory, telemetry). Super Pi replaces all of these with Pi-native tools — zero external infrastructure. All gstack capabilities are integrated as optional branch points within the existing flow; not selecting a new path = identical to the original behavior.
+→ Scans all artifacts, shows progress + recommends next step
+```
 
 ---
 
-## Changelog
-
-### 0.14.0
+## Generated File Structure
 
-**Structured solution retrieval**
+```
+your-project/
+├── docs/
+│   ├── brainstorms/                  # Requirements (01-brainstorm)
+│   ├── plans/                        # Execution plans (02-plan)
+│   └── solutions/                    # Knowledge cards (05-compound)
+└── .context/
+    └── compound-engineering/
+        ├── checkpoints/              # Breakpoint files (session_checkpoint)
+        ├── dialogs/                  # Dialog state (brainstorm_dialog)
+        └── history/                  # Execution history (session_history)
+```
 
-- New 5-field YAML frontmatter for solution artifacts: title, category, severity, tags, applies_when
-- `02-plan` and `04-review`: grep-first search strategy (project-level + global-level `~/.pi/agent/docs/solutions/`)
-- `05-compound`: mandatory frontmatter, two-level storage (project-specific vs cross-project global)
-- Added `solution-search-strategy.md` reference
-- 95 tests passing
+**Recommendation: commit everything to git** — these files are the project's traceable memory.
 
-### 0.13.0
+---
 
-- Merged Superpowers insights into CE skills
-- `01-brainstorm`: design checklist, stop conditions, user approval gate
-- `02-plan`: strict TDD gates (RED→GREEN→REFACTOR), TDD violation rejection
-- `03-work`: TDD execution discipline, structured completion report
-- `04-review`: review discipline (technical evaluation), YAGNI check
+## Design Philosophy
 
-### 0.12.0
+**80% planning and review, 20% execution.**
 
-- Extended `session_checkpoint` with `fail` and `retry` operations
+The goal isn't making AI write code faster — it's making AI think before writing, review after writing, and compound learnings after reviewing. Speed comes from fewer rewrites, not from skipping steps.
 
-### 0.11.0
+**The best ideas from four projects, reimplemented natively for Pi:**
 
-- Added `pattern_extractor` tool
+- **Compound Engineering** (Every Inc.) → The five-step loop + knowledge compounding backbone
+- **Superpowers** (Jesse Vincent) → Strict TDD gates + design checklists + review discipline
+- **Everything Claude Code** (140K+ stars) → Parallel subagent orchestration + checkpoint resume + continuous learning
+- **gstack** (Garry Tan / YC) → YC-style forcing questions + CEO Review cognitive frameworks + browser QA
 
-### 0.10.0
+Not a fork. Not a wrapper. The methodologies are extracted and rebuilt with Pi's native tool + skill system.
 
-- Added `session_history` tool
+---
 
-### 0.9.0
+## Best Practices
 
-- Added `plan_diff` tool: incremental plan updates
+| Tip | Why |
+|-----|-----|
+| Start with 01-brainstorm | Whatever the scenario, thinking first never hurts |
+| Use 07-worktree for big features | Isolated dev, no impact on main branch |
+| Use CEO Review on plans | Like having a demanding CTO review for free |
+| Use browser QA for acceptance | Code review can't catch layout breaks and blank screens |
+| Don't panic on interruption | Next 03-work auto-resumes from checkpoint |
+| Use 08-status when lost | One glance shows where you are |
 
-### 0.8.0
+---
 
-- Added `brainstorm_dialog` tool
+## Changelog
 
-### 0.7.0
+### 0.14.0 — Structured solution retrieval
+- YAML frontmatter tagging + grep-first two-level search
+- 95 tests passing
 
-- Added `task_splitter` tool: union-find parallel grouping
+### 0.13.0 — Superpowers engineering discipline
+- Strict TDD gates, design checklists, YAGNI checks
 
-### 0.6.0
+### 0.12.0 — Error recovery
+- session_checkpoint fail/retry operations
 
-- Added `session_checkpoint` tool: resume-from-checkpoint
+### 0.11.0 — Pattern extraction
+- New pattern_extractor tool
 
-### 0.5.0
+### 0.10.0 — Continuous learning
+- New session_history tool
 
-- Added `parallel_subagent` tool
+### 0.9.0 — Incremental planning
+- New plan_diff tool
 
-### 0.4.0
+### 0.8.0 — Multi-round dialog
+- New brainstorm_dialog tool
 
-- Added `review_router` tool
+### 0.7.0 — Parallel grouping
+- Union-Find based task_splitter
 
-### 0.3.0
+### 0.6.0 — Checkpoint resume
+- New session_checkpoint tool
 
-- Added `worktree_manager` tool and `07-worktree` skill
+### 0.5.0 — Parallel execution
+- New parallel_subagent tool
 
-### 0.2.0
+### 0.4.0 — Smart review
+- New review_router tool
 
-- Added `workflow_state` tool and `06-next` skill
+### 0.3.0 — Isolated development
+- New worktree_manager + 07-worktree
 
-### 0.1.0–0.1.2
+### 0.2.0 — State awareness
+- New workflow_state + 06-next
 
-- Initial release: 7 skills, 3 tools, CI/CD
+### 0.1.0 — Initial release
+- 7 skills, 3 tools
 
 ---
 
@@ -353,20 +292,3 @@ gstack is Y Combinator CEO Garry Tan's personal AI toolchain, representing the "
 bun test
 npm publish --dry-run
 ```
-
-## CI/CD
-
-- **Test**: runs `bun test` on every push/PR to main
-- **Publish**: runs `bun test` + `npm publish` on version tags (`v*`)
-
-### Release process
-
-1. Bump version in `package.json`
-2. Update README Changelog
-3. `git commit -m "chore: bump to x.y.z"`
-4. `git tag vx.y.z`
-5. `git push origin main --tags`
-
-### Required secrets
-
-Set `NPM_TOKEN` in GitHub → Settings → Secrets → Actions.

package/extensions/ce-core/index.ts

@@ -13,6 +13,7 @@ import { createBrainstormDialogTool } from "./tools/brainstorm-dialog"
 import { createPlanDiffTool } from "./tools/plan-diff"
 import { createSessionHistoryTool } from "./tools/session-history"
 import { createPatternExtractorTool } from "./tools/pattern-extractor"
+import { filterBashOutput } from "./tools/bash-output-filter"
 
 const artifactHelperParams = Type.Object({
   repoRoot: Type.String({ description: "Repository root where workflow artifacts should be created" }),
@@ -504,8 +505,47 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
       }
     },
   })
+
+  // Bash output smart filter — reduces context waste from verbose command output
+  pi.on("tool_result", async (event, _ctx) => {
+    if (event.toolName !== "bash") return undefined
+
+    // Extract command from input
+    const command = (event.input as any)?.command ?? ""
+    if (!command) return undefined
+
+    // Extract text content from tool result
+    const textBlocks = (event.content as Array<any>)?.filter((b: any) => b.type === "text") ?? []
+    if (textBlocks.length === 0) return undefined
+
+    const output = textBlocks.map((b: any) => b.text).join("")
+    const fullOutputPath = (event.details as any)?.fullOutputPath
+
+    const result = filterBashOutput({
+      command,
+      output,
+      isError: event.isError ?? false,
+      fullOutputPath,
+    })
+
+    if (!result.filtered) return undefined
+
+    // Replace content with filtered version
+    return {
+      content: [{ type: "text", text: result.output }],
+      details: {
+        ...event.details,
+        bashFilter: {
+          strategy: result.strategy,
+          originalBytes: result.originalBytes,
+          filteredBytes: result.filteredBytes,
+        },
+      },
+    }
+  })
 }
 
+
 export { createArtifactHelperTool } from "./tools/artifact-helper"
 export { createAskUserQuestionTool } from "./tools/ask-user-question"
 export { createSubagentTool } from "./tools/subagent"
@@ -526,3 +566,4 @@ export {
   getRunArtifactPath,
 } from "./utils/artifact-paths"
 export { normalizeSlug } from "./utils/name-utils"
+export { filterBashOutput } from "./tools/bash-output-filter"

package/extensions/ce-core/tools/bash-output-filter.ts

@@ -0,0 +1,402 @@
+import { Type } from "@sinclair/typebox"
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface BashOutputFilterInput {
+  /** The bash command that was run */
+  command: string
+  /** The raw output text */
+  output: string
+  /** Whether the command exited with an error */
+  isError: boolean
+  /** Original full output path (if truncated by pi) */
+  fullOutputPath?: string
+}
+
+export interface BashOutputFilterResult {
+  /** Filtered output text */
+  output: string
+  /** Whether filtering was applied */
+  filtered: boolean
+  /** Original size in bytes */
+  originalBytes: number
+  /** Filtered size in bytes */
+  filteredBytes: number
+  /** The filter strategy that was applied */
+  strategy: string
+}
+
+// ============================================================================
+// Command Classification
+// ============================================================================
+
+type CommandCategory = "install" | "test" | "build" | "search" | "git-diff" | "list" | "http" | "unknown"
+
+interface CommandPattern {
+  pattern: RegExp
+  category: CommandCategory
+  /** Whether this is a "means" command (output is a side-effect) */
+  isMeans: boolean
+}
+
+const COMMAND_PATTERNS: CommandPattern[] = [
+  // Install commands — output is a side-effect
+  { pattern: /\b(npm|yarn|pnpm|bun)\s+(install|i|add|ci|update|upgrade)\b/, category: "install", isMeans: true },
+  { pattern: /\b(pip|pip3|poetry|conda)\s+(install|add)\b/, category: "install", isMeans: true },
+  { pattern: /\b(cargo)\s+(install|add|update)\b/, category: "install", isMeans: true },
+  { pattern: /\b(bundle|gem)\s+(install)\b/, category: "install", isMeans: true },
+  { pattern: /\b(go)\s+(get|install|mod\s+(tidy|download))\b/, category: "install", isMeans: true },
+  // Test commands — output is mostly noise (pass lines), failures are signal
+  { pattern: /\b(npm|yarn|pnpm|bun)\s+(test|t|run\s+test)/, category: "test", isMeans: true },
+  { pattern: /\b(vitest|jest|mocha|pytest|cargo\s+test|go\s+test|ruby|-Ilib)\b.*\b(test|spec)\b/, category: "test", isMeans: true },
+  { pattern: /\b(jest|vitest|mocha|pytest|npx\s+(jest|vitest|mocha))\b/, category: "test", isMeans: true },
+  { pattern: /\b(cargo)\s+test\b/, category: "test", isMeans: true },
+  { pattern: /\b(go)\s+test\b/, category: "test", isMeans: true },
+  // Build/compile commands — warnings/errors are signal
+  { pattern: /\b(tsc|typescript|tscl)\b/, category: "build", isMeans: true },
+  { pattern: /\b(npm|yarn|pnpm|bun)\s+(run\s+)?(build|compile)\b/, category: "build", isMeans: true },
+  { pattern: /\b(cargo)\s+(build|check|clippy)\b/, category: "build", isMeans: true },
+  { pattern: /\b(make|cmake|gcc|g\+\+|clang)\b/, category: "build", isMeans: true },
+  { pattern: /\b(dotnet)\s+(build|publish)\b/, category: "build", isMeans: true },
+  { pattern: /\b(gradle|mvn|mvnw)\b/, category: "build", isMeans: true },
+  // Search commands — output IS the purpose, don't filter
+  { pattern: /\b(grep|rg|ag|ack|git\s+grep)\b/, category: "search", isMeans: false },
+  { pattern: /\b(rg|ripgrep)\b/, category: "search", isMeans: false },
+  // Git diff/log — output IS the purpose
+  { pattern: /\bgit\s+(diff|log|show|range-diff)\b/, category: "git-diff", isMeans: false },
+  // File listing — moderate filtering ok
+  { pattern: /\b(find|fd|ls\s+-R|tree|du|ncdu)\b/, category: "list", isMeans: false },
+  // HTTP requests — can be verbose
+  { pattern: /\b(curl|wget|httpie|http\s+)\b/, category: "http", isMeans: false },
+]
+
+function classifyCommand(command: string): CommandPattern | null {
+  // Normalize command: remove leading whitespace, handle pipes
+  const cmd = command.trim()
+
+  // Check primary command (before any pipe)
+  const primaryCmd = cmd.split("|")[0].trim()
+
+  for (const pattern of COMMAND_PATTERNS) {
+    if (pattern.pattern.test(primaryCmd)) {
+      return pattern
+    }
+  }
+
+  return null
+}
+
+// ============================================================================
+// Output Filters
+// ============================================================================
+
+/**
+ * Filter for install command output.
+ * Keep: error lines, warning lines, summary lines (added/removed/changed counts).
+ * Remove: progress bars, download lines, individual package install lines.
+ */
+function filterInstallOutput(output: string): string {
+  const lines = output.split("\n")
+  const kept: string[] = []
+  let removedCount = 0
+
+  for (const line of lines) {
+    // Always keep: empty lines (structure), errors, warnings, summary
+    if (
+      line.trim() === "" ||
+      /(error|ERR!|fatal|FAILED|failed|abort|timeout)/i.test(line) ||
+      /\b(warn|WARN|warning|deprecat)\b/i.test(line) ||
+      /\b(added|removed|changed|updated|audited)\s+\d+/i.test(line) ||
+      /\bpackages?\b.*\b(look|found|installed|removed)\b/i.test(line) ||
+      /\bvulnerabilities\b/i.test(line) ||
+      /^\s*$/.test(line) ||
+      line.startsWith("[") ||
+      /^\s*(\d+ packages?|up to date|already|nothing)/i.test(line)
+    ) {
+      kept.push(line)
+    } else {
+      removedCount++
+    }
+  }
+
+  // Deduplicate consecutive empty lines
+  return deduplicateEmptyLines(kept.join("\n"))
+}
+
+/**
+ * Filter for test command output.
+ * Keep: FAIL, ERROR, summary, test suite headers.
+ * Remove: PASS lines (✓, ✔, PASS, ✓), progress dots.
+ */
+function filterTestOutput(output: string): string {
+  const lines = output.split("\n")
+  const kept: string[] = []
+  let removedCount = 0
+
+  for (const line of lines) {
+    // Always keep: errors, failures, summary, suite names
+    if (
+      line.trim() === "" ||
+      /\b(FAIL|FAILING|FAILED|ERROR|✕|✗|×|✘|broken)\b/i.test(line) ||
+      /\b(fail|failure|error|timeout|crash)\b.*\d/i.test(line) ||
+      /\b(tests?|suites?|files?|passed|failed|skipped|pending)\s*[:=]?\s*\d/i.test(line) ||
+      /\b(RUN|RUNS)\s/i.test(line) || // vitest running indicator
+      /^\s*(FAIL|PASS|ERROR|SKIP|TODO)\s+(?:\s|\[)/i.test(line) ||
+      /^[\s│┌┐└┘├┤┬┴┼─]+/.test(line) || // Box drawing (test summaries)
+      /\b(synopsis|assert|expect|received|expected)\b/i.test(line) ||
+      /\s+(→|at)\s+.*\.\w+\s*$/i.test(line) || // Stack traces
+      /\d+\.\d+\s*(s|ms)\s*$/.test(line.trim()) || // Timing lines
+      line.includes("Test Suites:") ||
+      line.includes("Tests:") ||
+      line.includes("Snapshots:") ||
+      line.includes("Time:")
+    ) {
+      kept.push(line)
+    } else if (
+      // Specifically skip PASS lines
+      /^\s*✓|✔|PASS|✅|·/.test(line) ||
+      /^\s*√/.test(line) ||
+      /^\s*ok\s+\d+/.test(line) ||
+      /^\s*\.\s*$/.test(line.trim()) // Progress dots
+    ) {
+      removedCount++
+    } else {
+      // Keep lines that don't match pass patterns (context lines)
+      kept.push(line)
+    }
+  }
+
+  return deduplicateEmptyLines(kept.join("\n"))
+}
+
+/**
+ * Filter for build/compile output.
+ * Keep: error lines, warning lines (deduplicated), summary.
+ * Remove: successful compilation lines, progress indicators.
+ */
+function filterBuildOutput(output: string): string {
+  const lines = output.split("\n")
+  const kept: string[] = []
+  const seenWarnings = new Set<string>()
+  let removedCount = 0
+
+  for (const line of lines) {
+    if (line.trim() === "") {
+      kept.push(line)
+      continue
+    }
+
+    // Always keep errors
+    if (/\b(error|Error:|fatal|FAILED|failed)\b/i.test(line)) {
+      kept.push(line)
+      continue
+    }
+
+    // Deduplicate warnings (keep first occurrence)
+    if (/\b(warning|warn)\b/i.test(line)) {
+      const normalized = line.replace(/:\d+:\d+/g, ":N:N").trim()
+      if (!seenWarnings.has(normalized)) {
+        seenWarnings.add(normalized)
+        kept.push(line)
+      } else {
+        kept.push(`  ... (${countByPattern(lines, normalized)} similar warnings omitted)`)
+      }
+      continue
+    }
+
+    // Keep summary lines
+    if (
+      /\b(compiled|built|generated|error|warning)\s*\d/i.test(line) ||
+      /\b(Finished|Compiling|Building)\b/i.test(line) ||
+      /error\(s\)|warning\(s\)/i.test(line)
+    ) {
+      kept.push(line)
+      continue
+    }
+
+    // Skip progress/success lines
+    if (
+      /^\s*(Compiling|Building|Generating)\s/i.test(line) ||
+      /^\s*\[.*\]\s/.test(line) // [1/10] style progress
+    ) {
+      removedCount++
+      continue
+    }
+
+    // Keep everything else (might be important context)
+    kept.push(line)
+  }
+
+  return deduplicateEmptyLines(kept.join("\n"))
+}
+
+/**
+ * General filter for any large output.
+ * Applies safe, universal compression:
+ * - Collapse consecutive empty lines
+ * - Remove ANSI escape sequences
+ * - Trim trailing whitespace
+ */
+function filterGenericOutput(output: string): string {
+  // Remove ANSI escape sequences
+  const cleaned = output.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, "")
+  // Deduplicate empty lines
+  return deduplicateEmptyLines(cleaned)
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function deduplicateEmptyLines(text: string): string {
+  return text.replace(/\n{3,}/g, "\n\n")
+}
+
+function countByPattern(lines: string[], normalizedPattern: string): number {
+  let count = 0
+  for (const line of lines) {
+    if (line.replace(/:\d+:\d+/g, ":N:N").trim() === normalizedPattern) {
+      count++
+    }
+  }
+  return count
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`
+}
+
+// ============================================================================
+// Main Filter Function
+// ============================================================================
+
+/** Minimum output size (bytes) to trigger any filtering */
+const MIN_FILTER_THRESHOLD = 2048 // 2KB
+
+/** Maximum filtered output size (bytes) — aggressive cutoff for very large outputs */
+const MAX_FILTERED_SIZE = 30720 // 30KB
+
+export function filterBashOutput(input: BashOutputFilterInput): BashOutputFilterResult {
+  const { command, output, isError, fullOutputPath } = input
+  const originalBytes = Buffer.byteLength(output, "utf-8")
+
+  // Don't filter small outputs
+  if (originalBytes < MIN_FILTER_THRESHOLD) {
+    return {
+      output,
+      filtered: false,
+      originalBytes,
+      filteredBytes: originalBytes,
+      strategy: "none (below threshold)",
+    }
+  }
+
+  // Don't filter error outputs — they need to be complete
+  if (isError) {
+    return {
+      output,
+      filtered: false,
+      originalBytes,
+      filteredBytes: originalBytes,
+      strategy: "none (error output)",
+    }
+  }
+
+  const matched = classifyCommand(command)
+
+  // If no pattern matched, apply generic filtering for large outputs
+  if (!matched) {
+    if (originalBytes > MAX_FILTERED_SIZE) {
+      const filtered = filterGenericOutput(output)
+      const filteredBytes = Buffer.byteLength(filtered, "utf-8")
+      if (filteredBytes < originalBytes * 0.9) {
+        return {
+          output: appendFilterNotice(filtered, originalBytes, filteredBytes, "generic", fullOutputPath),
+          filtered: true,
+          originalBytes,
+          filteredBytes,
+          strategy: "generic (large unknown command)",
+        }
+      }
+    }
+    return {
+      output,
+      filtered: false,
+      originalBytes,
+      filteredBytes: originalBytes,
+      strategy: "none (unknown command, below aggressive threshold)",
+    }
+  }
+
+  // Don't filter "purpose" commands (search, git diff) unless extremely large
+  if (!matched.isMeans && originalBytes < MAX_FILTERED_SIZE) {
+    return {
+      output,
+      filtered: false,
+      originalBytes,
+      filteredBytes: originalBytes,
+      strategy: `none (${matched.category}: purpose command, within limit)`,
+    }
+  }
+
+  // Apply category-specific filter
+  let filtered: string
+  let strategyName: string
+
+  switch (matched.category) {
+    case "install":
+      filtered = filterInstallOutput(output)
+      strategyName = "install (errors + summary only)"
+      break
+    case "test":
+      filtered = filterTestOutput(output)
+      strategyName = "test (failures + summary only)"
+      break
+    case "build":
+      filtered = filterBuildOutput(output)
+      strategyName = "build (errors + deduplicated warnings)"
+      break
+    default:
+      // Purpose commands that are very large get generic filtering
+      filtered = filterGenericOutput(output)
+      strategyName = `generic (${matched.category}: large output)`
+      break
+  }
+
+  const filteredBytes = Buffer.byteLength(filtered, "utf-8")
+
+  // If filtering didn't help much (< 20% reduction), keep original
+  if (filteredBytes > originalBytes * 0.8) {
+    return {
+      output,
+      filtered: false,
+      originalBytes,
+      filteredBytes,
+      strategy: `none (${matched.category}: filtering insufficient, <20% reduction)`,
+    }
+  }
+
+  return {
+    output: appendFilterNotice(filtered, originalBytes, filteredBytes, strategyName, fullOutputPath),
+    filtered: true,
+    originalBytes,
+    filteredBytes,
+    strategy: strategyName,
+  }
+}
+
+function appendFilterNotice(
+  output: string,
+  originalBytes: number,
+  filteredBytes: number,
+  strategy: string,
+  fullOutputPath?: string,
+): string {
+  const saved = formatBytes(originalBytes - filteredBytes)
+  const notice = `\n\n[Output filtered: ${formatBytes(originalBytes)} → ${formatBytes(filteredBytes)} (${saved} saved, strategy: ${strategy})${fullOutputPath ? `. Full output: ${fullOutputPath}` : ""}]`
+  return output + notice
+}

package/package.json

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