@leing2021/super-pi 0.19.0 → 0.19.2

package/README.md

@@ -35,6 +35,38 @@ Super Pi's answers:
 
 Each step has a dedicated skill + tool pair. Not just prompts — structured toolchains.
 
+### New: Stage model routing + optional auto-continue
+
+Configure once in `.pi/settings.json`:
+
+```json
+{
+  "modelStrategy": {
+    "01-brainstorm": "claude-sonnet-4-20250514",
+    "02-plan": "claude-opus-4-20250115",
+    "03-work": "claude-sonnet-4-20250514",
+    "04-review": "claude-sonnet-4-20250514",
+    "05-learn": "claude-haiku-4-20250414",
+    "default": "claude-sonnet-4-20250514"
+  },
+  "pipeline": {
+    "autoContinue": false
+  }
+}
+```
+
+How it works:
+- Each stage picks `modelStrategy[stage]`, or `modelStrategy.default` as fallback.
+- Every stage prints a `📊 Pipeline Status` block with `Current / Output / Next`.
+- If `pipeline.autoContinue=true`, super-pi can trigger the next stage automatically.
+- Auto-continue is gate-aware: it will NOT skip required approvals (brainstorm approval, plan/review A/B/C choices).
+
+Quick example:
+1. Run `/skill:01-brainstorm`
+2. Approve the design
+3. If `autoContinue=true`, it moves to `/skill:02-plan` automatically
+4. If `autoContinue=false`, it stops after status output and waits for your command
+
 ---
 
 ## What Each Step Does
@@ -148,7 +180,7 @@ Single `npm install` output filtered once pays for the entire overhead. Full eva
 
 ## Code Scale
 
-~2500 lines of TypeScript implementing 15 tools, 22 Markdown reference files + 78 rule files driving 10 skills, 162 tests covering all tool logic.
+~2800 lines of TypeScript implementing 16 tools, 22 Markdown reference files + 78 rule files driving 10 skills, 170 tests covering all tool logic.
 
 Not a heavy framework. Each tool has a single responsibility, each skill works independently, and together they form a complete workflow.
 
@@ -351,6 +383,18 @@ Not a fork. Not a wrapper. Methodologies extracted and rebuilt with Pi's native
 
 ## Changelog
 
+### 0.19.2 — Evidence-first handoff-lite + docs tracking rule
+- Added `context_handoff` with evidence-first default handoff-lite generation when markdown is omitted.
+- Standardized the shared handoff-lite template across 01-05 workflow handoffs via `skills/references/pipeline-config.md`.
+- Added tests protecting default handoff generation and the shared handoff docs contract.
+- Updated docs tracking so Git only uploads `docs/token-cost-evaluation.md` while other `docs/` artifacts stay local.
+
+### 0.19.1 — Pipeline config + typecheck baseline fix
+- Added shared pipeline config (`skills/references/pipeline-config.md`) for stage model routing via `.pi/settings.json`.
+- Added gated auto-continue rules (`pipeline.autoContinue`) so automation does not skip required approval/review-choice steps.
+- Added explicit README usage examples for `modelStrategy` and `pipeline.autoContinue`.
+- Fixed TypeScript baseline issues so `bunx tsc --noEmit` passes.
+
 ### 0.19.0 — 0.69.0 alignment + learn rename
 - TypeBox migration: `@sinclair/typebox` → `typebox` (zero old-path imports)
 - Peer/dev dependency upgrade: pi-coding-agent `0.67.6` → `0.69.0`

package/extensions/ce-core/index.ts

@@ -282,8 +282,8 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
           allowCustom: params.allowCustom,
         },
         {
-          input: async (question) => ctx.ui.input(question),
-          select: async (question, options) => ctx.ui.select(question, options),
+          input: async (question) => (await ctx.ui.input(question)) ?? null,
+          select: async (question, options) => (await ctx.ui.select(question, options)) ?? null,
         },
       )
 
@@ -586,7 +586,7 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
     return {
       content: [{ type: "text", text: result.output }],
       details: {
-        ...event.details,
+        ...(event.details && typeof event.details === "object" ? event.details : {}),
         bashFilter: {
           strategy: result.strategy,
           originalBytes: result.originalBytes,
@@ -623,7 +623,7 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
     return {
       content: [{ type: "text", text: result.output }],
       details: {
-        ...event.details,
+        ...(event.details && typeof event.details === "object" ? event.details : {}),
         readFilter: {
           strategy: result.strategy,
           originalBytes: result.originalBytes,
@@ -633,10 +633,11 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
     }
   })
 
-  // Compaction prompt optimizer — makes summaries more focused and useful
-  pi.on("session_before_compact", async (_event, _ctx) => {
+  // Tree summary prompt optimizer — keeps branch summaries focused
+  pi.on("session_before_tree", async (_event, _ctx) => {
     return {
       customInstructions: COMPACTION_FOCUS_INSTRUCTIONS,
+      replaceInstructions: false,
     }
   })
 }

package/extensions/ce-core/tools/context-handoff.ts

@@ -0,0 +1,357 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises"
+import { existsSync } from "node:fs"
+import path from "node:path"
+import { normalizeSlug } from "../utils/name-utils"
+
+export type ContextHealth = "good" | "watch" | "heavy" | "critical"
+
+export interface ContextHandoffInput {
+  operation: "save" | "load" | "latest" | "status"
+  repoRoot: string
+  currentStage?: string
+  nextStage?: string
+  contextHealth?: ContextHealth
+  activeFiles?: string[]
+  blocker?: string
+  verification?: string
+  artifacts?: Record<string, string | undefined>
+  handoffMarkdown?: string
+  handoffPath?: string
+}
+
+export interface ContextStateEntry {
+  currentStage: string
+  nextStage?: string
+  contextHealth: ContextHealth
+  latestHandoffPath?: string
+  latestDatedHandoffPath?: string
+  activeFiles: string[]
+  blocker?: string
+  verification?: string
+  artifacts: Record<string, string | undefined>
+  recommendNewSession: boolean
+  updatedAt: string
+}
+
+export interface ContextHandoffResult {
+  operation: string
+  found?: boolean
+  path?: string
+  latestPath?: string
+  currentStage?: string
+  nextStage?: string
+  contextHealth?: ContextHealth
+  activeFiles?: string[]
+  blocker?: string
+  verification?: string
+  artifacts?: Record<string, string | undefined>
+  recommendNewSession?: boolean
+  handoffMarkdown?: string
+  updatedAt?: string
+}
+
+function ceDir(repoRoot: string): string {
+  return path.join(repoRoot, ".context", "compound-engineering")
+}
+
+function handoffDir(repoRoot: string): string {
+  return path.join(ceDir(repoRoot), "handoffs")
+}
+
+function stateFilePath(repoRoot: string): string {
+  return path.join(ceDir(repoRoot), "context-state.json")
+}
+
+function latestHandoffPath(repoRoot: string): string {
+  return path.join(handoffDir(repoRoot), "latest.md")
+}
+
+function toRepoRelative(repoRoot: string, filePath: string): string {
+  return path.relative(repoRoot, filePath)
+}
+
+function resolveRepoPath(repoRoot: string, filePath: string): string {
+  return path.isAbsolute(filePath) ? filePath : path.join(repoRoot, filePath)
+}
+
+function stageSlug(value?: string): string {
+  if (!value || value.trim().length === 0) return "unknown"
+  return normalizeSlug(value)
+}
+
+function buildDatedHandoffPath(repoRoot: string, currentStage?: string, nextStage?: string): string {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-")
+  const fileName = `${timestamp}-${stageSlug(currentStage)}-to-${stageSlug(nextStage)}.md`
+  return path.join(handoffDir(repoRoot), fileName)
+}
+
+function computeRecommendNewSession(currentStage?: string, nextStage?: string, contextHealth: ContextHealth = "watch"): boolean {
+  const isCrossPhase = Boolean(currentStage && nextStage && currentStage !== nextStage)
+  const isHeavy = contextHealth === "heavy" || contextHealth === "critical"
+  return isCrossPhase && isHeavy
+}
+
+function formatBullets(items: string[]): string {
+  if (items.length === 0) return "- N/A"
+  return items.map(item => `- ${item}`).join("\n")
+}
+
+function formatArtifacts(artifacts: Record<string, string | undefined>): string {
+  const lines = Object.entries(artifacts)
+    .filter(([, value]) => Boolean(value && value.trim().length > 0))
+    .map(([key, value]) => `- ${key}: ${value}`)
+
+  if (lines.length === 0) return "- N/A"
+  return lines.join("\n")
+}
+
+function buildDefaultHandoffMarkdown(input: {
+  currentStage: string
+  nextStage?: string
+  activeFiles: string[]
+  artifacts: Record<string, string | undefined>
+  blocker?: string
+  verification?: string
+}): string {
+  const currentTask = input.nextStage
+    ? `Continue from ${input.currentStage} to ${input.nextStage}.`
+    : `Continue ${input.currentStage}.`
+
+  const hotContext = formatBullets(input.activeFiles.slice(0, 5))
+
+  const verifiedFacts = formatBullets([
+    `Current stage: ${input.currentStage}`,
+    `Next stage: ${input.nextStage ?? "N/A"}`,
+  ])
+
+  const activeFiles = formatBullets(input.activeFiles.slice(0, 5))
+  const artifacts = formatArtifacts(input.artifacts)
+  const blocker = input.blocker ?? "N/A"
+  const verification = input.verification ?? "Not run"
+  const nextMinimalStep = input.nextStage ? `/skill:${input.nextStage}` : "N/A"
+
+  return [
+    "## Current Task",
+    currentTask,
+    "",
+    "## Hot Context",
+    hotContext,
+    "",
+    "## Verified Facts",
+    verifiedFacts,
+    "",
+    "## Active Files",
+    activeFiles,
+    "",
+    "## Artifacts",
+    artifacts,
+    "",
+    "## Current Blocker",
+    `- ${blocker}`,
+    "",
+    "## Verification",
+    `- ${verification}`,
+    "",
+    "## Do Not Repeat",
+    "- Do not reload full history unless the handoff lacks required evidence.",
+    "",
+    "## Next Minimal Step",
+    `- ${nextMinimalStep}`,
+    "",
+  ].join("\n")
+}
+
+async function readState(repoRoot: string): Promise<ContextStateEntry | null> {
+  const filePath = stateFilePath(repoRoot)
+  if (!existsSync(filePath)) return null
+
+  try {
+    const content = await readFile(filePath, "utf8")
+    return JSON.parse(content) as ContextStateEntry
+  } catch {
+    return null
+  }
+}
+
+async function writeState(repoRoot: string, state: ContextStateEntry): Promise<void> {
+  const filePath = stateFilePath(repoRoot)
+  await mkdir(path.dirname(filePath), { recursive: true })
+  await writeFile(filePath, JSON.stringify(state, null, 2), "utf8")
+}
+
+export function createContextHandoffTool() {
+  return {
+    name: "context_handoff",
+    async execute(input: ContextHandoffInput): Promise<ContextHandoffResult> {
+      switch (input.operation) {
+        case "save":
+          return save(input)
+        case "load":
+          return load(input)
+        case "latest":
+          return latest(input)
+        case "status":
+          return status(input)
+        default:
+          throw new Error(`Unknown operation: ${input.operation}`)
+      }
+    },
+  }
+}
+
+async function save(input: ContextHandoffInput): Promise<ContextHandoffResult> {
+  const currentStage = input.currentStage ?? "unknown"
+  const nextStage = input.nextStage
+  const contextHealth = input.contextHealth ?? "watch"
+  const activeFiles = input.activeFiles ?? []
+  const blocker = input.blocker
+  const verification = input.verification
+  const artifacts = input.artifacts ?? {}
+  const handoffMarkdown = input.handoffMarkdown?.trim().length
+    ? input.handoffMarkdown
+    : buildDefaultHandoffMarkdown({
+      currentStage,
+      nextStage,
+      activeFiles,
+      artifacts,
+      blocker,
+      verification,
+    })
+
+  const recommendNewSession = computeRecommendNewSession(currentStage, nextStage, contextHealth)
+  const latestPath = latestHandoffPath(input.repoRoot)
+  const datedPath = buildDatedHandoffPath(input.repoRoot, currentStage, nextStage)
+  const relativeLatestPath = toRepoRelative(input.repoRoot, latestPath)
+  const relativeDatedPath = toRepoRelative(input.repoRoot, datedPath)
+
+  await mkdir(path.dirname(latestPath), { recursive: true })
+  await writeFile(latestPath, handoffMarkdown, "utf8")
+  await writeFile(datedPath, handoffMarkdown, "utf8")
+
+  const state: ContextStateEntry = {
+    currentStage,
+    nextStage,
+    contextHealth,
+    latestHandoffPath: relativeLatestPath,
+    latestDatedHandoffPath: relativeDatedPath,
+    activeFiles,
+    blocker,
+    verification,
+    artifacts,
+    recommendNewSession,
+    updatedAt: new Date().toISOString(),
+  }
+
+  await writeState(input.repoRoot, state)
+
+  return {
+    operation: "save",
+    found: true,
+    path: relativeDatedPath,
+    latestPath: relativeLatestPath,
+    currentStage,
+    nextStage,
+    contextHealth,
+    activeFiles,
+    blocker,
+    verification,
+    artifacts,
+    recommendNewSession,
+    updatedAt: state.updatedAt,
+  }
+}
+
+async function load(input: ContextHandoffInput): Promise<ContextHandoffResult> {
+  const state = await readState(input.repoRoot)
+  if (!state) {
+    return {
+      operation: "load",
+      found: false,
+      contextHealth: "watch",
+      recommendNewSession: false,
+    }
+  }
+
+  const targetPath = input.handoffPath ?? state.latestHandoffPath ?? latestHandoffPath(input.repoRoot)
+  const absoluteTargetPath = resolveRepoPath(input.repoRoot, targetPath)
+  let markdown = ""
+  if (existsSync(absoluteTargetPath)) {
+    markdown = await readFile(absoluteTargetPath, "utf8")
+  }
+
+  return {
+    operation: "load",
+    found: true,
+    path: targetPath,
+    latestPath: state.latestHandoffPath,
+    currentStage: state.currentStage,
+    nextStage: state.nextStage,
+    contextHealth: state.contextHealth,
+    activeFiles: state.activeFiles,
+    blocker: state.blocker,
+    verification: state.verification,
+    artifacts: state.artifacts,
+    recommendNewSession: state.recommendNewSession,
+    handoffMarkdown: markdown,
+    updatedAt: state.updatedAt,
+  }
+}
+
+async function latest(input: ContextHandoffInput): Promise<ContextHandoffResult> {
+  const state = await readState(input.repoRoot)
+  if (!state || !state.latestHandoffPath) {
+    return {
+      operation: "latest",
+      found: false,
+      contextHealth: "watch",
+      recommendNewSession: false,
+    }
+  }
+
+  return {
+    operation: "latest",
+    found: true,
+    path: state.latestDatedHandoffPath,
+    latestPath: state.latestHandoffPath,
+    currentStage: state.currentStage,
+    nextStage: state.nextStage,
+    contextHealth: state.contextHealth,
+    activeFiles: state.activeFiles,
+    blocker: state.blocker,
+    verification: state.verification,
+    artifacts: state.artifacts,
+    recommendNewSession: state.recommendNewSession,
+    updatedAt: state.updatedAt,
+  }
+}
+
+async function status(input: ContextHandoffInput): Promise<ContextHandoffResult> {
+  const state = await readState(input.repoRoot)
+
+  if (!state) {
+    return {
+      operation: "status",
+      found: false,
+      contextHealth: "watch",
+      recommendNewSession: false,
+      activeFiles: [],
+      artifacts: {},
+    }
+  }
+
+  return {
+    operation: "status",
+    found: true,
+    path: state.latestDatedHandoffPath,
+    latestPath: state.latestHandoffPath,
+    currentStage: state.currentStage,
+    nextStage: state.nextStage,
+    contextHealth: state.contextHealth,
+    activeFiles: state.activeFiles,
+    blocker: state.blocker,
+    verification: state.verification,
+    artifacts: state.artifacts,
+    recommendNewSession: state.recommendNewSession,
+    updatedAt: state.updatedAt,
+  }
+}

package/package.json

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

package/skills/01-brainstorm/SKILL.md

@@ -7,6 +7,8 @@ description: "Brainstorm requirements with three modes: CE discovery, Startup Di
 
 Use this skill when the request is ambiguous, needs requirements discovery before planning, or the user describes a new idea/product.
 
+See [shared pipeline instructions](../references/pipeline-config.md) for model routing and pipeline behavior.
+
 ## Core rules
 
 - Use **`brainstorm_dialog`** to manage multi-round conversations.
@@ -118,3 +120,5 @@ Before handing off to `02-plan`:
 ## Artifact contract
 
 Use `references/requirements-template.md` to structure the requirements document. Keep implementation details out unless the brainstorm is specifically about architecture or technical direction.
+
+Before finishing this skill, apply the completion checklist in [shared pipeline instructions](../references/pipeline-config.md).

package/skills/01-brainstorm/references/handoff.md

@@ -6,3 +6,6 @@ When the requirements artifact is ready:
 2. Summarize the recommended direction in 2-3 bullets.
 3. Recommend `02-plan` as the next step.
 4. If key ambiguity remains, say so before handing off.
+5. Provide `🧠 Context Status` (health, handoff path, active files, new-session recommendation).
+6. Save/mention handoff-lite path under `.context/compound-engineering/handoffs/` using the shared `Handoff-lite template` in `skills/references/pipeline-config.md`.
+7. Recommend new session only when cross-phase + health is heavy/critical, and include a copyable prompt.

package/skills/02-plan/SKILL.md

@@ -7,6 +7,8 @@ description: "Turn requirements into a plan. Optional CEO-style strategic review
 
 Use this skill when requirements are ready to become an execution-ready plan.
 
+See [shared pipeline instructions](../references/pipeline-config.md) for model routing and pipeline behavior.
+
 ## Core rules
 
 - Before planning, read the `10-rules` skill and load `rules/common/development-workflow.md` and `rules/common/testing.md` for coding standards context.
@@ -76,3 +78,5 @@ Every unit must include:
   6. Run unit-level verification
 - **Verification commands**: exact commands to run
 - **Expected results**: what success looks like
+
+Before finishing this skill, apply the completion checklist in [shared pipeline instructions](../references/pipeline-config.md).

package/skills/02-plan/references/handoff.md

@@ -6,3 +6,6 @@ When the plan is ready:
 2. Summarize the main implementation units.
 3. Recommend `03-work` as the next step.
 4. Call out any remaining assumptions or open risks.
+5. Provide `🧠 Context Status` (health, handoff path, active files, new-session recommendation).
+6. Save/mention handoff-lite path under `.context/compound-engineering/handoffs/` using the shared `Handoff-lite template` in `skills/references/pipeline-config.md`.
+7. Recommend new session only when cross-phase + health is heavy/critical, and include a copyable prompt.

package/skills/03-work/SKILL.md

@@ -7,6 +7,8 @@ description: Execute plan-driven work in a controlled Phase 1 workflow.
 
 Use this skill when there is a plan path or a tightly scoped bare prompt ready for execution.
 
+See [shared pipeline instructions](../references/pipeline-config.md) for model routing and pipeline behavior.
+
 ## Core rules
 
 - Before execution, read the `10-rules` skill and load language-specific rules matching the active codebase (e.g. `rules/typescript/` for TS work).
@@ -64,3 +66,5 @@ When all units are done, provide:
 - **Commands run**: all verification commands executed
 - **Verification results**: pass/fail status for each
 - **Follow-up work**: any remaining risks or open questions
+
+Before finishing this skill, apply the completion checklist in [shared pipeline instructions](../references/pipeline-config.md).

package/skills/03-work/references/handoff.md

@@ -6,3 +6,7 @@ When execution reaches a meaningful checkpoint:
 2. Report the latest verification results.
 3. Recommend `04-review` as the next step.
 4. Mention any remaining implementation risk.
+5. Include checkpoint fields: `activeFiles`, `currentUnit`, `blocker`, `verification`, `contextTiers`, `handoffPath`.
+6. Provide `🧠 Context Status` (health, handoff path, active files, new-session recommendation).
+7. Save/mention handoff-lite path under `.context/compound-engineering/handoffs/` using the shared `Handoff-lite template` in `skills/references/pipeline-config.md`.
+8. Recommend new session only when cross-phase + health is heavy/critical, and include a copyable prompt.

package/skills/04-review/SKILL.md

@@ -7,6 +7,8 @@ description: "Review code with structured findings. Optional browser QA and regr
 
 Use this skill after implementation to review changes against the diff, the relevant plan, and prior learnings.
 
+See [shared pipeline instructions](../references/pipeline-config.md) for model routing and pipeline behavior.
+
 ## Core rules
 
 - Before reviewing, read the `10-rules` skill and load `rules/common/code-review.md` plus language-specific rules matching the changed files.
@@ -71,3 +73,5 @@ After review (and optional QA) is complete, hand off using `references/handoff.m
 2. Note fix commits if any were applied.
 3. Recommend `05-learn` if learnings are worth capturing.
 4. Recommend `03-work` if fixes need further implementation.
+
+Before finishing this skill, apply the completion checklist in [shared pipeline instructions](../references/pipeline-config.md).

package/skills/04-review/references/handoff.md

@@ -8,6 +8,8 @@ When the review is complete:
 4. After autofix, report what was changed and whether re-review confirms the fix.
 5. Recommend `05-learn` when the review surfaced a reusable learning or newly solved problem.
 6. Mention any relevant plan or solution artifacts referenced during review.
+7. Provide `🧠 Context Status` (health, handoff path, active files, new-session recommendation).
+8. Save/mention handoff-lite path under `.context/compound-engineering/handoffs/` using the shared `Handoff-lite template` in `skills/references/pipeline-config.md`.
 
 ## Autofix loop
 

package/skills/05-learn/SKILL.md

@@ -7,6 +7,8 @@ description: Capture solved problems as reusable solution artifacts.
 
 Use this skill after solving a problem so the repository gains a reusable learning in `docs/solutions/`.
 
+See [shared pipeline instructions](../references/pipeline-config.md) for model routing and pipeline behavior.
+
 ## Core rules
 
 - Every solution MUST include YAML frontmatter per `references/solution-schema.yaml` (title, category, severity, tags, applies_when).
@@ -30,3 +32,7 @@ Use this skill after solving a problem so the repository gains a reusable learni
 5. Choose the correct category using `references/category-map.md`.
 6. Write or update the solution artifact under `docs/solutions/<category>/`.
 7. Mention how future `02-plan` and `04-review` runs should benefit from the new learning.
+8. Include `🧠 Context Status` (health, handoff path, active files, new-session recommendation) for workflow closure.
+9. Save/mention handoff-lite path under `.context/compound-engineering/handoffs/` using the shared `Handoff-lite template` in `skills/references/pipeline-config.md`.
+
+Before finishing this skill, apply the completion checklist in [shared pipeline instructions](../references/pipeline-config.md).

package/skills/references/pipeline-config.md

@@ -0,0 +1,137 @@
+# Shared pipeline instructions
+
+Use these rules in all Phase 1 skills: `01-brainstorm` → `02-plan` → `03-work` → `04-review` → `05-learn`.
+
+## Start of skill: model routing
+
+Run this checklist before normal skill workflow:
+
+1. Read `.pi/settings.json` from the project root.
+2. Parse `modelStrategy` (if missing, skip switching).
+3. Resolve current stage key:
+   - `01-brainstorm`
+   - `02-plan`
+   - `03-work`
+   - `04-review`
+   - `05-learn`
+4. Pick `targetModel = modelStrategy[stageKey] ?? modelStrategy.default`.
+5. If `targetModel` exists and differs from the current model, run `/model <targetModel>`.
+6. If switching fails, continue with current model and mention the failure once.
+
+## End of skill: status + context + optional auto-continue
+
+Before final completion, always output these blocks (replace placeholders with real values, never output angle-bracket placeholders literally):
+
+```
+---
+📊 Pipeline Status
+- Current: <stageKey>
+- Output: <main artifact path or N/A>
+- Next: <next skill command or Completed>
+---
+
+🧠 Context Status
+- Health: good | watch | heavy | critical
+- Handoff: <path or N/A>
+- Active: <1-5 active files or N/A>
+- New session: recommended | not needed
+---
+```
+
+Next step mapping:
+- `01-brainstorm` → `/skill:02-plan`
+- `02-plan` → `/skill:03-work`
+- `03-work` → `/skill:04-review`
+- `04-review` → `/skill:05-learn`
+- `05-learn` → `Completed`
+
+Then read `.pi/settings.json` → `pipeline.autoContinue`:
+- If `false` or missing, stop after the status block and wait for user input.
+- If current stage is `05-learn`, stop after status block.
+- If `true` and current stage is not `05-learn`, auto-continue is allowed only after stage-specific gates are satisfied:
+  - `01-brainstorm`: user has explicitly approved the design handoff.
+  - `02-plan`: review choice is resolved (A/B/C flow completed) and user confirmed to proceed.
+  - `04-review`: optional QA choice is resolved (A/B/C flow completed) and user confirmed to proceed.
+  - Any unclear/ambiguous state: do not auto-continue; stop and ask.
+- When gates are satisfied, automatically trigger the mapped next skill command.
+
+### Handoff-lite template
+
+When a stage produces or updates handoff-lite, use this evidence-first structure and keep it concise (target <= 1500 tokens):
+
+```md
+## Current Task
+
+## Hot Context
+- 1-5 must-know facts for the next step
+
+## Verified Facts
+- already validated facts (do not re-prove)
+
+## Active Files
+- 1-5 file paths only
+
+## Artifacts
+- requirements: <path or N/A>
+- plan: <path or N/A>
+- checkpoint: <path or N/A>
+- proof: <path or N/A>
+
+## Current Blocker
+- <blocker or N/A>
+
+## Verification
+- <latest command + result or Not run>
+
+## Do Not Repeat
+- what should not be re-read/re-run unless needed
+
+## Next Minimal Step
+- exact next command/action
+```
+
+Rules:
+- Use `N/A` instead of inventing facts.
+- Keep broad history in artifact paths, not expanded narrative.
+- If `context_handoff` is unavailable, manually write this shape to `.context/compound-engineering/handoffs/latest.md` and mention the path.
+
+### New-session recommendation rule
+
+Recommend a new session only when both are true:
+
+1. Phase is changing (`Current` != next stage)
+2. Context health is `heavy` or `critical`
+
+When recommending a new session, include a directly copyable prompt:
+
+```md
+## 建议新开 Session
+
+原因：当前 `<current stage>` 已完成，下一步将进入 `<next stage>`。当前窗口已经包含较多已完成阶段上下文，继续执行会降低 Token ROI，并增加旧上下文干扰后续判断的风险。
+
+建议：新开一个窗口，把下面这段 Prompt 复制进去即可继续。
+
+```text
+继续这个 Super Pi workflow，不要重新开始。
+
+Repo: <repo path>
+
+请先读取：
+- <latest plan/requirements artifact>
+- <latest handoff-lite path>
+- <latest checkpoint path or summary>
+
+然后继续：
+- 执行 <next skill command>
+
+上下文策略：
+- hot: 仅保留当前执行必须文件（1-5）
+- warm: 通过 artifact path 按需回读
+- cold: 不进入当前窗口，除非明确需要
+
+核心原则：
+- 不重复已完成阶段
+- 优先验证当前阶段输出
+- 控制 token，保持高 ROI
+```
+```