@leing2021/super-pi 0.23.7 → 0.23.9

package/README.md

@@ -8,6 +8,8 @@
 
 **Turn your AI coding agent into a reliable engineer.**
 
+Super Pi is a Pi-native engineering workflow layer: it adds stage discipline, durable artifacts, TDD gates, checkpoints, review, and learning loops on top of your coding agent. It is not a general-purpose multi-agent executor; subagents are optional helpers for bounded leaf tasks.
+
 Install, describe what you want to build, then keep saying "continue." Super Pi drives the full loop:
 
  **think → plan → build → review → compound learnings.**
@@ -23,7 +25,7 @@ pi install npm:@leing2021/super-pi
 - **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`
+- **Controlled subagents** — inline execution by default; subagents are limited to bounded, non-interactive leaf tasks
 - **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
@@ -43,7 +45,7 @@ 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
+→ 03-work: inline-first execution, bounded subagents, checkpoint resume
 → 04-review: five-axis findings, autofix loop
 → 05-learn: knowledge compounding
 
@@ -71,7 +73,7 @@ You: /skill:03-work docs/plans/plan.md
 |-------|-------------|-----------|
 | **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` |
+| **03-work** | Inline-first execution, bounded subagents, 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` |
@@ -82,6 +84,8 @@ You: /skill:03-work docs/plans/plan.md
 
 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.
 
+These tools are helpers, not the core workflow. Use inline execution by default. Use CE subagents only for bounded, non-interactive, easily verifiable leaf tasks. Do not use them to invoke pipeline-stage skills (`01-brainstorm` through `05-learn`); run those stages directly with `/skill:<stage>`.
+
 ### Model & Thinking Routing
 
 Configure in `.pi/settings.json`:
@@ -114,6 +118,7 @@ Super Pi is not a fork or wrapper. It extracts useful methods from the projects
 |---------|------------------------|
 | [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. |
+| [humanlayer/12-factor-agents](https://github.com/humanlayer/12-factor-agents) | Context window ownership, compacting resolved errors, retry caps, and pre-fetching obvious prerequisites. Adopted as lightweight context hygiene rules inside the existing Phase 1 pipeline. |
 | [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. |

package/extensions/ce-core/tools/parallel-subagent.ts

@@ -10,7 +10,7 @@ import {
   checkSubagentDepth,
   getChildDepthEnv,
 } from "./subagent-depth-guard"
-import type { SubagentExecOptions, SubagentRunner } from "./subagent"
+import { assertNonPipelineStageSkill, type SubagentExecOptions, type SubagentRunner } from "./subagent"
 
 export interface ParallelSubagentTask {
   agent: string
@@ -52,6 +52,10 @@ export function createParallelSubagentTool() {
         throw new Error("ce_parallel_subagent requires at least one task")
       }
 
+      for (const task of input.tasks) {
+        assertNonPipelineStageSkill(task.agent, "ce_parallel_subagent")
+      }
+
       // Default: parallel workers get a slim context (no inherited skills)
       const inheritSkills = input.inheritSkills ?? false
       const execOptions = buildParallelExecOptions(inheritSkills)

package/extensions/ce-core/tools/subagent.ts

@@ -41,6 +41,23 @@ export type SubagentRunner = (
   options?: SubagentExecOptions,
 ) => Promise<string>
 
+const PIPELINE_STAGE_SKILLS = new Set([
+  "01-brainstorm",
+  "02-plan",
+  "03-work",
+  "04-review",
+  "05-learn",
+])
+
+export function assertNonPipelineStageSkill(agent: string, toolName: string): void {
+  if (PIPELINE_STAGE_SKILLS.has(agent)) {
+    throw new Error(
+      `Pipeline-stage skill "${agent}" cannot run through ${toolName}. ` +
+      `Run it directly with /skill:${agent} instead.`,
+    )
+  }
+}
+
 export function createSubagentTool() {
   return {
     name: "ce_subagent",
@@ -61,6 +78,7 @@ export function createSubagentTool() {
       const execOptions = buildExecOptions(input.inheritSkills)
 
       if (hasSingle) {
+        assertNonPipelineStageSkill(input.agent!, "ce_subagent")
         const prompt = buildPrompt(input.agent!, input.task!)
         const output = await runner(prompt, execOptions)
         return {
@@ -73,6 +91,7 @@ export function createSubagentTool() {
       let previous = ""
 
       for (const task of input.chain ?? []) {
+        assertNonPipelineStageSkill(task.agent, "ce_subagent")
         const prompt = buildPrompt(task.agent, task.task.replace(/\{previous\}/g, previous))
         const output = await runner(prompt, execOptions)
         outputs.push(output)

package/package.json

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

package/skills/03-work/SKILL.md

@@ -20,9 +20,10 @@ See [shared pipeline instructions](../references/pipeline-config.md) for model r
 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
+   - **Inline mode** is the default execution path
+   - **`ce_parallel_subagent`** only for bounded, non-interactive, easily verifiable leaf tasks
+   - **`ce_subagent`** only for rare dependent serial chains of leaf tasks
+   - Never use either tool to invoke pipeline-stage skills (`01-brainstorm through 05-learn`). Run those stages directly with `/skill:<stage>`.
 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
@@ -57,6 +58,17 @@ Anti-rationalization — when a gate fails or evidence is missing:
 
 This is a hard gate — do not push past a failing test or broken build to continue implementation. Errors compound.
 
+## Error compaction after recovery
+
+After a stop-the-line failure is diagnosed, fixed, and verified:
+
+1. Replace full traces in handoff/context with `ERROR(resolved): <root cause>`
+2. Keep only the final repro, root cause, fix summary, and verification result
+3. Remove intermediate debug output and failed exploratory runs that are no longer relevant
+4. Update `session_checkpoint` with the compacted state only
+
+If the same tool, command, or implementation unit fails 3 consecutive times, stop retrying and ask the user for direction with a concise evidence summary.
+
 ## 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.
@@ -64,7 +76,7 @@ This is a hard gate — do not push past a failing test or broken build to conti
 3. Read implementation units if plan path
 4. Load `session_checkpoint` to skip completed units
 5. Use `task_splitter` for dependency analysis
-6. Execute: **inline mode** by default, `ce_parallel_subagent` for independent units
+6. Execute: **inline mode** by default; use subagents only for bounded, non-interactive, easily verifiable leaf tasks
 7. Follow TDD per unit: RED → minimal code → GREEN → refactor → unit-level **verification**
 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`

package/skills/references/pipeline-config.md

@@ -29,6 +29,15 @@ Before reading any project files or running repository-wide scans, load the most
 
 Core principle: **consume handoff before broad project file reads** — a single handoff read (~500 tokens) avoids 5-10 project file scans (~5K-10K tokens).
 
+## Context hygiene rules
+
+Applies to all Phase 1 skills when preparing context or saving handoff.
+
+1. **Compact resolved errors** — Once an error is diagnosed, fixed, and verified, do not carry the full trace forward. Replace it with `ERROR(resolved): <root cause>` and keep repro/verification only if still relevant.
+2. **Fetch obvious prerequisites** — If the next step has an obvious deterministic prerequisite, fetch it before reasoning further instead of spending an LLM round trip asking for it.
+3. **Cap repeated failures** — After 3 consecutive failures on the same tool, command, or implementation unit, stop retrying. Summarize evidence and ask the user for direction.
+4. **Prune before handoff** — Before saving handoff, keep only what the next stage needs. Move broad history to artifact paths; remove intermediate debug output that is no longer relevant.
+
 ## End of skill: save handoff + status + context
 
 Every Phase 1 skill (02-plan through 05-learn) must save context handoff at completion: