@leing2021/super-pi 0.22.0 → 0.23.0

package/extensions/ce-core/index.ts

@@ -4,23 +4,25 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"
 import { Type } from "typebox"
 import { createArtifactHelperTool, type ArtifactType } from "./tools/artifact-helper"
 import { createAskUserQuestionTool } from "./tools/ask-user-question"
+import { createSubagentTool } from "./tools/subagent"
 import { createWorkflowStateTool } from "./tools/workflow-state"
 import { createWorktreeManagerTool } from "./tools/worktree-manager"
 import { createReviewRouterTool } from "./tools/review-router"
+import { createParallelSubagentTool } from "./tools/parallel-subagent"
 import { createSessionCheckpointTool } from "./tools/session-checkpoint"
 import { createTaskSplitterTool } from "./tools/task-splitter"
 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 { createContextHandoffTool } from "./tools/context-handoff"
 import { filterBashOutput } from "./tools/bash-output-filter"
 import { filterReadOutput } from "./tools/read-output-filter"
 import { COMPACTION_FOCUS_INSTRUCTIONS } from "./tools/compaction-optimizer"
+import { AsyncMutex } from "./tools/async-mutex"
+import type { SubagentExecOptions, SubagentRunner } from "./tools/subagent"
 
-// NOTE: subagent and parallel_subagent tool registration removed.
-// Subagent capabilities are provided by the pi-subagents package.
-// super-pi focuses on CE-specific tools only.
-
+const _subagentEnvMutex = new AsyncMutex()
 const PIPELINE_STAGE_KEYS = new Set([
   "01-brainstorm",
   "02-plan",
@@ -81,6 +83,47 @@ function parseModelRef(
   }
 }
 
+/**
+ * Create a subagent runner that handles env injection with mutex protection
+ * for concurrency safety when multiple parallel subagents share the process.
+ */
+function createSubagentRunner(
+  pi: ExtensionAPI,
+  signal?: AbortSignal,
+): SubagentRunner {
+  return async (prompt: string, options?: SubagentExecOptions) => {
+    const args = ["--no-session", ...(options?.extraFlags ?? []), "-p", prompt]
+    const release = await _subagentEnvMutex.acquire()
+    const savedEnv: Record<string, string | undefined> = {}
+    const extraEnv = options?.extraEnv ?? {}
+    for (const [key, value] of Object.entries(extraEnv)) {
+      savedEnv[key] = process.env[key]
+      process.env[key] = value
+    }
+    try {
+      const execResult = await pi.exec("pi", args, {
+        signal,
+        timeout: 10 * 60 * 1000,
+      })
+
+      if (execResult.code !== 0) {
+        throw new Error(execResult.stderr || execResult.stdout || `Subagent failed for prompt: ${prompt}`)
+      }
+
+      return (execResult.stdout || "").trim()
+    } finally {
+      for (const [key, oldValue] of Object.entries(savedEnv)) {
+        if (oldValue === undefined) {
+          delete process.env[key]
+        } else {
+          process.env[key] = oldValue
+        }
+      }
+      release()
+    }
+  }
+}
+
 const artifactHelperParams = Type.Object({
   repoRoot: Type.String({ description: "Repository root where workflow artifacts should be created" }),
   artifactType: Type.Union([
@@ -103,6 +146,18 @@ const askUserQuestionParams = Type.Object({
   allowCustom: Type.Optional(Type.Boolean({ description: "Allow a custom answer when options are present" })),
 })
 
+const subagentTaskSchema = Type.Object({
+  agent: Type.String({ description: "Skill name to invoke via /skill:<name>" }),
+  task: Type.String({ description: "Task text passed to the subagent" }),
+})
+
+const subagentParams = Type.Object({
+  agent: Type.Optional(Type.String({ description: "Single subagent skill name" })),
+  task: Type.Optional(Type.String({ description: "Single subagent task" })),
+  chain: Type.Optional(Type.Array(subagentTaskSchema, { description: "Serial subagent chain with optional {previous} placeholder" })),
+  inheritSkills: Type.Optional(Type.Boolean({ description: "Whether the subagent should inherit skills. Default: true" })),
+})
+
 const workflowStateParams = Type.Object({
   repoRoot: Type.String({ description: "Repository root to scan for workflow artifacts" }),
 })
@@ -125,6 +180,19 @@ const reviewRouterParams = Type.Object({
   deletions: Type.Number({ description: "Number of lines removed" }),
 })
 
+const parallelSubagentTaskSchema = Type.Object({
+  agent: Type.String({ description: "Skill name to invoke via /skill:<name>" }),
+  task: Type.String({ description: "Task text passed to the subagent" }),
+})
+
+const parallelSubagentParams = Type.Object({
+  tasks: Type.Union([
+    Type.Array(parallelSubagentTaskSchema),
+    Type.String({ description: "JSON stringified array of tasks" }),
+  ], { description: "Array of independent tasks to run concurrently (can be a JSON string)" }),
+  inheritSkills: Type.Optional(Type.Boolean({ description: "Whether subagents should inherit skills. Default: false" })),
+})
+
 const sessionCheckpointParams = Type.Object({
   operation: Type.Union([
     Type.Literal("save"),
@@ -205,6 +273,30 @@ const patternSchema = Type.Object({
   sources: Type.Array(Type.String(), { description: "Artifact sources" }),
 })
 
+const contextHandoffParams = Type.Object({
+  operation: Type.Union([
+    Type.Literal("save"),
+    Type.Literal("load"),
+    Type.Literal("latest"),
+    Type.Literal("status"),
+  ], { description: "Handoff operation" }),
+  repoRoot: Type.String({ description: "Repository root" }),
+  currentStage: Type.Optional(Type.String({ description: "Current pipeline stage (e.g. 02-plan)" })),
+  nextStage: Type.Optional(Type.String({ description: "Next pipeline stage" })),
+  contextHealth: Type.Optional(Type.Union([
+    Type.Literal("good"),
+    Type.Literal("watch"),
+    Type.Literal("heavy"),
+    Type.Literal("critical"),
+  ], { description: "Context health assessment" })),
+  activeFiles: Type.Optional(Type.Array(Type.String(), { description: "1-5 must-know active file paths" })),
+  blocker: Type.Optional(Type.String({ description: "Current blocker description" })),
+  verification: Type.Optional(Type.String({ description: "Latest verification command + result" })),
+  artifacts: Type.Optional(Type.Record(Type.String(), Type.Optional(Type.String()), { description: "Artifact paths (requirements, plan, checkpoint, proof)" })),
+  handoffMarkdown: Type.Optional(Type.String({ description: "Custom handoff markdown content" })),
+  handoffPath: Type.Optional(Type.String({ description: "Specific handoff file path to load" })),
+})
+
 const patternExtractorParams = Type.Object({
   operation: Type.Union([
     Type.Literal("extract"),
@@ -275,15 +367,18 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
 
   const artifactHelper = createArtifactHelperTool()
   const askUserQuestion = createAskUserQuestionTool()
+  const subagent = createSubagentTool()
   const workflowState = createWorkflowStateTool()
   const worktreeManager = createWorktreeManagerTool()
   const reviewRouter = createReviewRouterTool()
+  const parallelSubagent = createParallelSubagentTool()
   const sessionCheckpoint = createSessionCheckpointTool()
   const taskSplitter = createTaskSplitterTool()
   const brainstormDialog = createBrainstormDialogTool()
   const planDiff = createPlanDiffTool()
   const sessionHistory = createSessionHistoryTool()
   const patternExtractor = createPatternExtractorTool()
+  const contextHandoff = createContextHandoffTool()
 
   pi.registerTool({
     name: artifactHelper.name,
@@ -350,6 +445,29 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
     },
   })
 
+  pi.registerTool({
+    name: subagent.name,
+    label: "CE Subagent",
+    description: "Run a single CE skill-based subagent or a serial chain in an isolated Pi process.",
+    parameters: subagentParams,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const result = await subagent.execute(
+        {
+          agent: params.agent,
+          task: params.task,
+          chain: params.chain,
+          inheritSkills: params.inheritSkills,
+        },
+        createSubagentRunner(pi, signal),
+      )
+
+      return {
+        content: [{ type: "text", text: result.outputs[result.outputs.length - 1] ?? "" }],
+        details: result,
+      }
+    },
+  })
+
   pi.registerTool({
     name: workflowState.name,
     label: "Workflow State",
@@ -421,6 +539,39 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
     },
   })
 
+  pi.registerTool({
+    name: parallelSubagent.name,
+    label: "CE Parallel Subagent",
+    description: "Run multiple CE skill-based subagent tasks concurrently. IMPORTANT: Provide 'tasks' as a clean JSON array object. If the environment forces a string, provide a valid JSON array string.",
+    parameters: parallelSubagentParams,
+    async execute(_toolCallId, params, signal) {
+      let tasks: any[]
+      if (typeof params.tasks === "string") {
+        try {
+          const cleaned = params.tasks.replace(/^```json\s*|```$/g, "").trim()
+          tasks = JSON.parse(cleaned)
+        } catch (e) {
+          throw new Error(`Failed to parse tasks string as JSON: ${e instanceof Error ? e.message : String(e)}`)
+        }
+      } else {
+        tasks = params.tasks
+      }
+
+      const result = await parallelSubagent.execute(
+        {
+          tasks,
+          inheritSkills: params.inheritSkills,
+        },
+        createSubagentRunner(pi, signal),
+      )
+
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        details: result,
+      }
+    },
+  })
+
   pi.registerTool({
     name: sessionCheckpoint.name,
     label: "Session Checkpoint",
@@ -544,6 +695,33 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
     },
   })
 
+  pi.registerTool({
+    name: contextHandoff.name,
+    label: "Context Handoff",
+    description: "Manage cross-stage context handoffs with evidence-first templates. Supports save (write handoff + state), load (read handoff + state), latest (read latest dated handoff), and status (read current state).",
+    parameters: contextHandoffParams,
+    async execute(_toolCallId, params) {
+      const result = await contextHandoff.execute({
+        operation: params.operation,
+        repoRoot: params.repoRoot,
+        currentStage: params.currentStage,
+        nextStage: params.nextStage,
+        contextHealth: params.contextHealth,
+        activeFiles: params.activeFiles,
+        blocker: params.blocker,
+        verification: params.verification,
+        artifacts: params.artifacts as Record<string, string | undefined> | undefined,
+        handoffMarkdown: params.handoffMarkdown,
+        handoffPath: params.handoffPath,
+      })
+
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        details: result,
+      }
+    },
+  })
+
   // Bash output smart filter — reduces context waste from verbose command output
   pi.on("tool_result", async (event, _ctx) => {
     if (event.toolName !== "bash") return undefined
@@ -587,8 +765,8 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
     if (event.toolName !== "read") return undefined
 
     // Extract path from input
-    const filePath = (event.input as any)?.path ?? ""
-    if (!filePath) return undefined
+    const path = (event.input as any)?.path ?? ""
+    if (!path) return undefined
 
     // Extract text content from tool result
     const textBlocks = (event.content as Array<any>)?.filter((b: any) => b.type === "text") ?? []
@@ -598,7 +776,7 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
     const isImage = (event.content as Array<any>)?.some((b: any) => b.type === "image") ?? false
 
     const result = filterReadOutput({
-      path: filePath,
+      path,
       output,
       isError: event.isError ?? false,
       isImage,
@@ -631,15 +809,20 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
 
 export { createArtifactHelperTool } from "./tools/artifact-helper"
 export { createAskUserQuestionTool } from "./tools/ask-user-question"
+export { createSubagentTool } from "./tools/subagent"
+export { checkSubagentDepth, getChildDepthEnv, DEFAULT_MAX_SUBAGENT_DEPTH } from "./tools/subagent-depth-guard"
+export { AsyncMutex } from "./tools/async-mutex"
 export { createWorkflowStateTool } from "./tools/workflow-state"
 export { createWorktreeManagerTool } from "./tools/worktree-manager"
 export { createReviewRouterTool } from "./tools/review-router"
+export { createParallelSubagentTool } from "./tools/parallel-subagent"
 export { createSessionCheckpointTool } from "./tools/session-checkpoint"
 export { createTaskSplitterTool } from "./tools/task-splitter"
 export { createBrainstormDialogTool } from "./tools/brainstorm-dialog"
 export { createPlanDiffTool } from "./tools/plan-diff"
 export { createSessionHistoryTool } from "./tools/session-history"
 export { createPatternExtractorTool } from "./tools/pattern-extractor"
+export { createContextHandoffTool } from "./tools/context-handoff"
 export {
   getBrainstormArtifactPath,
   getPlanArtifactPath,

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

@@ -1,5 +1,5 @@
 /**
- * Parallel subagent tool — runs multiple skill-based subagent tasks concurrently.
+ * CE parallel subagent tool — runs multiple CE skill-based subagent tasks concurrently.
  *
  * Features:
  *   - Recursion depth guard (PI_SUBAGENT_DEPTH / PI_SUBAGENT_MAX_DEPTH)
@@ -40,7 +40,7 @@ function buildPrompt(agent: string, task: string): string {
 
 export function createParallelSubagentTool() {
   return {
-    name: "parallel_subagent",
+    name: "ce_parallel_subagent",
     async execute(input: ParallelSubagentInput, runner: SubagentRunner): Promise<ParallelSubagentResult> {
       // Recursion depth guard
       const depthCheck = checkSubagentDepth()
@@ -49,7 +49,7 @@ export function createParallelSubagentTool() {
       }
 
       if (!input.tasks || input.tasks.length === 0) {
-        throw new Error("parallel_subagent requires at least one task")
+        throw new Error("ce_parallel_subagent requires at least one task")
       }
 
       // Default: parallel workers get a slim context (no inherited skills)

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

@@ -1,5 +1,5 @@
 /**
- * Subagent tool — runs a single skill-based subagent or a serial chain.
+ * CE subagent tool — runs a single CE skill-based subagent or a serial chain.
  *
  * Features:
  *   - Recursion depth guard (PI_SUBAGENT_DEPTH / PI_SUBAGENT_MAX_DEPTH)
@@ -43,7 +43,7 @@ export type SubagentRunner = (
 
 export function createSubagentTool() {
   return {
-    name: "subagent",
+    name: "ce_subagent",
     async execute(input: SubagentInput, runner: SubagentRunner): Promise<SubagentResult> {
       // Recursion depth guard
       const depthCheck = checkSubagentDepth()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leing2021/super-pi",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "private": false,
   "type": "module",
   "description": "Pi-native Compound Engineering package for iterative development workflows",
@@ -35,10 +35,8 @@
     "test": "bun test"
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "*"
-  },
-  "dependencies": {
-    "typebox": "^1.1.24"
+    "@mariozechner/pi-coding-agent": ">=0.69.0",
+    "typebox": ">=1.0.0"
   },
   "devDependencies": {
     "@mariozechner/pi-coding-agent": "0.69.0",
@@ -49,19 +47,7 @@
       "./skills"
     ],
     "extensions": [
-      "./extensions",
-      "./extensions/super-pi-extension",
-      "./extensions/subagent"
-    ],
-    "agents": [
-      "./extensions/super-pi-extension/agents",
-      "./extensions/subagent/agents"
-    ],
-    "prompts": [
-      "./extensions/subagent/prompts"
-    ],
-    "chains": [
-      "./extensions/super-pi-extension/chains"
+      "./extensions"
     ]
   }
 }

package/rules/common/naming.md

@@ -0,0 +1,154 @@
+# Naming Convention
+
+> One rule: **use simple, everyday, low-ambiguity words. Avoid jargon, avoid vagueness.**
+
+---
+
+## Word Selection Priority
+
+When naming anything — variables, types, states, API fields, database columns, queues, errors — follow this order:
+
+| Priority | Strategy | Why |
+|----------|----------|-----|
+| 1 | Pick an everyday word first | Short, direct, anyone can understand |
+| 2 | Check it's not vague | `good`, `ready`, `ok`, `normal` are too ambiguous |
+| 3 | Check cross-role clarity | Engineers, reviewers, operators, auditors all understand it |
+| 4 | Use a technical term only when precision demands it | Last resort |
+
+**In short: clarity first, stability second, terminology last.**
+
+---
+
+## Recommended vs. Avoid
+
+### ✅ Prefer — short, direct, unambiguous
+
+```
+Revise     Blocked     Reject     Approve
+Queue      Escalate    Notify     Cancel
+reason     owner       action     next_fix
+recheck_when
+```
+
+### ❌ Avoid — too vague
+
+```
+good    ready    ok    normal    done
+```
+
+Simple but not specific enough for system fields.
+
+### ❌ Avoid — too technical / abstract
+
+```
+orchestration_resolution_state
+deferred_adjudication_mode
+remediation_projection
+resolution_artifact
+operationalized_exception_payload
+```
+
+May be precise, but poor for cross-role collaboration and audit replay.
+
+### ❌ Avoid — too decorative / emotional
+
+System fields must be stable. Don't use literary, emotional, or decorative names.
+
+---
+
+## Style by Context
+
+| Context | Style | Example |
+|---------|-------|---------|
+| File names | kebab-case | `task-orchestrator.ts` |
+| Type names | PascalCase | `TaskEnvelope` |
+| Zod/TypeBox schema variables | PascalCase + `Schema` suffix | `TaskEnvelopeSchema` |
+| Function names | camelCase | `evaluatePolicy` |
+| Exported constants | camelCase | `stateTransitions`, `finalStates` |
+| Database table names | snake_case | `task_records` |
+| Database column names | snake_case | `state_version` |
+| Environment variables | UPPER_SNAKE_CASE | `DATABASE_URL` |
+| Package names | scoped kebab-case | `@org/types` |
+| State / enum values | lowercase everyday words, snake_case for multi-word | `created`, `executing`, `result_ready` |
+| Error classes | `*Error` (never `*Exception`) | `BudgetExhaustedError` |
+| Queue names | semantic, kebab-case | `'task-execution'` (not `'execution_requested'`) |
+| API routes | kebab-case, plural nouns | `/api/tasks`, `/api/audit-events` |
+
+---
+
+## Naming by Role
+
+### Public states — conversational
+
+```
+Revise    Blocked    Reject    Approved
+Pending   Executing  Committed  Cancelled
+```
+
+### Governance actions — direct verbs
+
+```
+Notify    Approve    Queue     Escalate
+Pause     Resume     Discard   Delegate
+```
+
+### Supporting fields — read like speech
+
+```
+next_fix       → what to fix next
+recheck_when   → when to re-check
+reason         → why
+owner          → who's responsible
+action         → what to do
+```
+
+---
+
+## Two-Layer Naming
+
+When a name needs different expressions in schema vs. UI:
+
+| Layer | Strategy | Example |
+|-------|----------|---------|
+| Schema / code / database | More stable, precise | `state: 'revise_requested'` |
+| UI / audit log / replay | More human-readable | "Revision needed" |
+
+Connect the two layers with a mapping table. Don't define semantics twice.
+
+---
+
+## Self-Check Checklist
+
+For every name, confirm:
+
+```
+□ Can you understand it in 5 seconds?
+□ Will different roles (engineer, reviewer, operator, auditor) interpret it the same way?
+□ Is it readable in audit replay / logs?
+□ Is it NOT a vague word (good/ok/ready/normal)?
+□ Is it NOT over-technical jargon?
+□ Does it follow the style rules above (case, separator)?
+□ Is it consistent with existing names in the same domain?
+```
+
+If any answer is "no" → pick a different word and re-check.
+
+---
+
+## Common Anti-Patterns & Fixes
+
+| Anti-pattern | Problem | Fix |
+|--------------|---------|-----|
+| `status: 'good'` | Too vague | `status: 'passed'` |
+| `state: 'orchestration_pending_resolution'` | Too technical | `state: 'waiting_approval'` |
+| `action: 'the_moon_is_rising_retry'` | Too decorative | `action: 'retry'` |
+| `flag: 'ok'` | Too vague | `flag: 'valid'` |
+| `type: 'thing'` | Too generic | Use a concrete domain word |
+| `err: SomethingException(...)` | Wrong convention | `err: SomethingError(...)` |
+| `QUEUE = 'exec_req'` | Unclear abbreviation | `QUEUE = 'task-execution'` |
+
+---
+
+## One-Sentence Rule
+
+> **Default to simple, conversational, low-ambiguity everyday words. If that creates ambiguity, keep the schema term stable and the UI / audit wording more human.**

package/skills/02-plan/SKILL.md

@@ -11,11 +11,12 @@ See [shared pipeline instructions](../references/pipeline-config.md) for model r
 
 ## Core rules
 
-- Before planning, read the `10-rules` skill and load:
+- Before planning, load project rules:
   1. `rules/common/development-workflow.md` and `rules/common/testing.md`
-  2. **Detect the project's primary language** (check for `tsconfig.json` → typescript, `package.json` without tsconfig → javascript, `Cargo.toml` → rust, `go.mod` → golang, `pubspec.yaml` → dart, `pom.xml`/`build.gradle` → java, `*.sln`/`*.csproj` → csharp, `Package.swift` → swift, `requirements.txt`/`pyproject.toml`/`setup.py` → python, `composer.json` → php, `Makefile.PL`/`cpanfile` → perl, `build.gradle.kts` → kotlin)
+  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/`.

package/skills/03-work/SKILL.md

@@ -11,18 +11,21 @@ See [shared pipeline instructions](../references/pipeline-config.md) for model r
 
 ## Core rules
 
-- Before execution, read the `10-rules` skill and load:
+- Before execution, load project rules:
   1. `rules/common/development-workflow.md` and `rules/common/testing.md`
-  2. **Detect the project's primary language** (check for `tsconfig.json` → typescript, `package.json` without tsconfig → javascript, `Cargo.toml` → rust, `go.mod` → golang, `pubspec.yaml` → dart, `pom.xml`/`build.gradle` → java, `*.sln`/`*.csproj` → csharp, `Package.swift` → swift, `requirements.txt`/`pyproject.toml`/`setup.py` → python, `composer.json` → php, `Makefile.PL`/`cpanfile` → perl, `build.gradle.kts` → kotlin)
+  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**.
-- Use **serial subagents** (via `subagent` tool from pi-subagents) for tasks with dependencies.
-- Use **`subagent` tool in parallel mode** (via pi-subagents) for independent tasks that can run concurrently.
+- 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 parallel subagents and dependent units serially.
+- 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`.
 
@@ -48,7 +51,7 @@ Every execution step must follow **RED → GREEN → REFACTOR**:
 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, serial subagents, or parallel subagents depending on task dependencies.
+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.

package/skills/04-review/SKILL.md

@@ -11,11 +11,12 @@ See [shared pipeline instructions](../references/pipeline-config.md) for model r
 
 ## Core rules
 
-- Before reviewing, read the `10-rules` skill and load:
+- Before reviewing, load project rules:
   1. `rules/common/code-review.md`
-  2. **Detect the project's primary language** from the changed files (check for `tsconfig.json` → typescript, `package.json` without tsconfig → javascript, `Cargo.toml` → rust, `go.mod` → golang, `pubspec.yaml` → dart, `pom.xml`/`build.gradle` → java, `*.sln`/`*.csproj` → csharp, `Package.swift` → swift, `requirements.txt`/`pyproject.toml`/`setup.py` → python, `composer.json` → php, `Makefile.PL`/`cpanfile` → perl, `build.gradle.kts` → kotlin)
+  2. Detect the project's primary language from the changed files 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 review involves frontend/browser changes, also load `rules/web/` files
+- Priority: project-level `{repo-root}/rules/` overrides package-level defaults
 - Determine the **diff scope** before selecting reviewers.
 - Use the **`review_router`** tool to automatically select reviewer personas based on diff metadata.
 - Read the relevant **plan** artifact when one exists.