@leing2021/super-pi 0.23.7 → 0.23.8

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`:

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.8",
   "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
@@ -64,7 +65,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`