@leing2021/super-pi 0.24.0 → 0.25.1

package/README.md

@@ -8,7 +8,7 @@
 
 **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.
+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.
 
 Install, describe what you want to build, then keep saying "continue." Super Pi drives the full loop:
 
@@ -25,10 +25,9 @@ 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
-- **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
+- **Token-efficient** — ~4,200 tokens new-conversation overhead; progressive loading
 
 ---
 
@@ -45,7 +44,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: inline-first execution, bounded subagents, checkpoint resume
+→ 03-work: inline execution, checkpoint resume
 → 04-review: five-axis findings, autofix loop
 → 05-learn: knowledge compounding
 
@@ -73,22 +72,11 @@ You: /skill:03-work docs/plans/plan.md
 |-------|-------------|-----------|
 | **01-brainstorm** | Structured multi-round discovery, domain vocabulary persistence | `brainstorm_dialog` |
 | **02-plan** | TDD-gated implementation units, optional CEO Review | `plan_diff` |
-| **03-work** | Inline-first execution, checkpoint resume, strict TDD, stop-the-line | `session_checkpoint`, `task_splitter` |
+| **03-work** | Inline execution, checkpoint resume, strict TDD, stop-the-line | `session_checkpoint`, `task_splitter` |
 | **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` |
 | **07-worktree** | Isolated git worktree development | `worktree_manager` |
-| **08-help** | Phase 1 skill explainer | — |
-
-### Optional: External subagent delegation
-
-For generic child agent delegation (background jobs, parallel audits, scout/worker/oracle agents), install the community extension `pi-subagents` separately. Super Pi does not require it.
-
-```bash
-pi install npm:pi-subagents
-```
-
-Super Pi focuses on inline workflow execution. Use subagents only when you need true process isolation or background runs.
 
 ### Model & Thinking Routing
 
@@ -121,7 +109,7 @@ Super Pi is not a fork or wrapper. It extracts useful methods from the projects
 | Project | What Super Pi adopted |
 |---------|------------------------|
 | [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. |
+| [everything-claude-code](https://github.com/affaan-m/everything-claude-code) | 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. |
@@ -157,13 +145,13 @@ All reviewers evaluate changes across: **correctness, readability, architecture,
 
 ## Token Cost
 
-New conversation overhead: **~2,600 tokens** (1.3% of 200K context).
+New conversation overhead: **~4,130 tokens** (2.1% of 200K context).
 
 | Component | Tokens |
 |-----------|--------|
-| 8 skill registrations | ~490 |
-| System prompt | ~1,400 |
-| Skill inlining (per invocation) | ~500-800 |
+| 17 skill registrations | ~1,710 |
+| 22 tool schemas | ~2,420 |
+| Skill inlining (per invocation) | ~300–1,200 |
 
 Progressive loading: only needed skills loaded on-demand.
 
@@ -195,11 +183,11 @@ Commit everything to git — these files are the project's traceable memory.
 
 | Component | Count |
 |-----------|------:|
-| Skills | 8 |
-| Tools | 19 |
-| Rules | 79 |
-| TypeScript lines | ~4,400 |
-| Tests | 209 (786 assertions) |
+| Skills | 7 |
+| Tools | 12 CE + 10 Pi built-in |
+| Rules | 78 |
+| TypeScript lines | ~4,100 |
+| Tests | 180 (727 assertions) |
 
 Rules in `rules/` cover 11 common topics + language-specific sets (TypeScript, Rust, Go, Python, Java, Kotlin, C++, C#, Dart, Swift, Perl, PHP). Project-level overrides take priority.
 

package/extensions/ce-core/index.ts

@@ -3,7 +3,8 @@ import path from "node:path"
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
 import { Type } from "typebox"
 import { createArtifactHelperTool, type ArtifactType } from "./tools/artifact-helper"
-import { createAskUserQuestionTool } from "./tools/ask-user-question"
+import { createAskUserQuestionTool, CUSTOM_SENTINEL } from "./tools/ask-user-question"
+import { createAskUserQuestionCustomFactory } from "./tools/ask-user-question-ui"
 import { createWorkflowStateTool } from "./tools/workflow-state"
 import { createWorktreeManagerTool } from "./tools/worktree-manager"
 import { createReviewRouterTool } from "./tools/review-router"
@@ -26,6 +27,70 @@ const PIPELINE_STAGE_KEYS = new Set([
   "05-learn",
 ])
 
+/**
+ * Module-level promise chain that serializes interactive `ask_user_question`
+ * UI calls within a single Pi process.
+ *
+ * Why: `@earendil-works/pi-coding-agent` renders extension selectors via a
+ * singleton field (`extensionSelector` / `extensionInput` in
+ * `interactive-mode.js`). When two selector calls overlap, the second
+ * overwrites the first, and the first promise never resolves — surfacing to
+ * the agent as a silent `No result provided`. See
+ * `docs/bug/ask-user-question-parallel-call-silent-failure.md`.
+ *
+ * This guard ensures at most one selector/input is on screen at a time.
+ */
+let askUserQuestionExclusiveChain: Promise<unknown> = Promise.resolve()
+
+function runAskUserQuestionExclusive<T>(task: () => Promise<T>): Promise<T> {
+  const run = askUserQuestionExclusiveChain.then(task, task)
+  // Keep the chain robust: a rejected run must not poison subsequent calls.
+  askUserQuestionExclusiveChain = run.then(
+    () => undefined,
+    () => undefined,
+  )
+  return run
+}
+
+/**
+ * Build the UI adapter for `ask_user_question`.
+ *
+ * In interactive TUI mode with `ctx.ui.custom` available, route `select`
+ * through the scrollable custom dialog so long questions/options stay readable
+ * (see `docs/bug/ask-user-question-long-text-not-scrollable.md`). Otherwise
+ * fall back to the built-in `ctx.ui.select()`.
+ */
+function buildAskUserQuestionUi(ctx: any): import("./tools/ask-user-question").AskUserQuestionUi {
+  const useCustom = ctx?.mode === "tui" && typeof ctx?.ui?.custom === "function"
+  const input = async (question: string) => (await ctx.ui.input(question)) ?? null
+  const selectFallback = async (question: string, options: string[]) =>
+    (await ctx.ui.select(question, options)) ?? null
+
+  if (!useCustom) {
+    return { input, select: selectFallback }
+  }
+
+  const select = async (question: string, options: string[]): Promise<string | null> => {
+    // The custom sentinel is appended last (if present) and matches
+    // `CUSTOM_SENTINEL` or a `CUSTOM_SENTINEL (#n)` disambiguation suffix.
+    const last = options.length > 0 ? options[options.length - 1] : null
+    const customLabel = last !== null
+      && (last === CUSTOM_SENTINEL || last.startsWith(`${CUSTOM_SENTINEL} (#`))
+      ? last
+      : null
+    const factory = createAskUserQuestionCustomFactory({
+      question,
+      displayOptions: options,
+      customLabel,
+    })
+    const selection = (await ctx.ui.custom(factory)) as
+      { selectedLabel: string | null } | null | undefined
+    return selection?.selectedLabel ?? null
+  }
+
+  return { input, select }
+}
+
 interface StrategySettings {
   modelStrategy?: Record<string, string>
   thinkingStrategy?: Record<string, string>
@@ -399,6 +464,11 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
     name: askUserQuestion.name,
     label: "Ask User Question",
     description: "Ask the user a structured question with optional choices and custom answers.",
+    promptSnippet: "Ask the user a structured question with optional choices and custom answers",
+    promptGuidelines: [
+      "Call ask_user_question one at a time, never two or more in the same assistant message: Pi renders selectors on a shared singleton, so parallel ask_user_question calls silently fail with 'No result provided'.",
+      "For ask_user_question, keep the question concise and put long analysis in prior text or a file first; ask_user_question normalizes long options to short labels but the full answer is still returned to you.",
+    ],
     parameters: askUserQuestionParams,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       if (!ctx.hasUI) {
@@ -409,17 +479,14 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
         }
       }
 
-      const result = await askUserQuestion.execute(
+      const result = await runAskUserQuestionExclusive(() => askUserQuestion.execute(
         {
           question: params.question,
           options: params.options,
           allowCustom: params.allowCustom,
         },
-        {
-          input: async (question) => (await ctx.ui.input(question)) ?? null,
-          select: async (question, options) => (await ctx.ui.select(question, options)) ?? null,
-        },
-      )
+        buildAskUserQuestionUi(ctx),
+      ))
 
       const contentText = result.answer === null
         ? "User cancelled."

package/extensions/ce-core/tools/ask-user-question-ui.ts

@@ -0,0 +1,162 @@
+import {
+  Container,
+  Key,
+  matchesKey,
+  truncateToWidth,
+  wrapTextWithAnsi,
+} from "@earendil-works/pi-tui"
+
+/**
+ * Result shape returned by the scrollable ask_user_question custom UI.
+ *
+ * - `selectedLabel`: the normalized display label the user picked (may be the
+ *   custom sentinel), or `null` when cancelled.
+ * - The caller maps `selectedLabel` back to the original full option string.
+ */
+export interface AskUserQuestionSelection {
+  selectedLabel: string | null
+}
+
+interface AskUserQuestionCustomOptions {
+  question: string
+  displayOptions: string[]
+  customLabel: string | null
+}
+
+/**
+ * Maximum number of option/question rows rendered before the viewport scrolls.
+ * Keeps the dialog inside typical terminal heights while still being readable.
+ */
+const MAX_VISIBLE_ROWS = 10
+
+/**
+ * Render the question body as wrapped lines so long questions stay readable
+ * inside the scrollable custom dialog.
+ */
+function renderQuestionLines(question: string, width: number, fg: (color: string, text: string) => string): string[] {
+  const lines = wrapTextWithAnsi(question, width)
+  return lines.map((line) => truncateToWidth(fg("text", line), width))
+}
+
+/**
+ * Scrollable selector component for `ask_user_question`.
+ *
+ * Renders a wrapped (multi-line) question and a list of single-line options.
+ * Handles:
+ * - up/down navigation with scroll offset
+ * - Enter to confirm
+ * - Escape / cancel keybinding to cancel
+ * - optional "Other" custom entry label
+ *
+ * Built to work inside Pi's `ctx.ui.custom()` factory contract:
+ * `(tui, theme, keybindings, done) => Component`.
+ */
+export class AskUserQuestionSelector extends Container {
+  private readonly options: string[]
+  private readonly question: string
+  private readonly customLabel: string | null
+  private readonly theme: { fg: (color: string, text: string) => string }
+  private readonly done: (result: AskUserQuestionSelection) => void
+  private selectedIndex = 0
+  private scrollOffset = 0
+  private resolved = false
+
+  constructor(
+    opts: AskUserQuestionCustomOptions,
+    theme: { fg: (color: string, text: string) => string },
+    done: (result: AskUserQuestionSelection) => void,
+  ) {
+    super()
+    this.options = opts.displayOptions
+    this.question = opts.question
+    this.customLabel = opts.customLabel
+    this.theme = theme
+    this.done = done
+  }
+
+  /** Resolve a selected display label into the result handed to `done()`. */
+  private commit(index: number): void {
+    if (this.resolved) return
+    this.resolved = true
+    const selected = this.options[index] ?? null
+    this.done({ selectedLabel: selected })
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.up) || data === "k") {
+      this.selectedIndex = Math.max(0, this.selectedIndex - 1)
+      this.scrollOffset = Math.min(this.scrollOffset, this.selectedIndex)
+    } else if (matchesKey(data, Key.down) || data === "j") {
+      this.selectedIndex = Math.min(this.options.length - 1, this.selectedIndex + 1)
+      const maxStart = Math.max(0, this.selectedIndex - MAX_VISIBLE_ROWS + 1)
+      this.scrollOffset = Math.max(this.scrollOffset, maxStart)
+    } else if (matchesKey(data, Key.enter) || data === "\n") {
+      this.commit(this.selectedIndex)
+    } else if (matchesKey(data, Key.escape)) {
+      if (this.resolved) return
+      this.resolved = true
+      this.done({ selectedLabel: null })
+    }
+  }
+
+  render(width: number): string[] {
+    const lines: string[] = []
+    const fg = this.theme.fg.bind(this.theme)
+    const innerWidth = Math.max(20, width - 2)
+
+    lines.push(truncateToWidth(fg("accent", "─".repeat(width)), width))
+    for (const line of renderQuestionLines(this.question, innerWidth, fg)) {
+      lines.push(` ${line}`)
+    }
+    lines.push("")
+
+    const visible = this.options.slice(
+      this.scrollOffset,
+      this.scrollOffset + MAX_VISIBLE_ROWS,
+    )
+    for (let i = 0; i < visible.length; i++) {
+      const optionIndex = this.scrollOffset + i
+      const isSelected = optionIndex === this.selectedIndex
+      const isCustom = this.customLabel !== null && visible[i] === this.customLabel
+      const prefix = isSelected ? fg("accent", "→ ") : "  "
+      const marker = isCustom ? fg("muted", " ✎") : ""
+      lines.push(truncateToWidth(`${prefix}${fg(isSelected ? "accent" : "text", visible[i])}${marker}`, width))
+    }
+
+    if (this.options.length > MAX_VISIBLE_ROWS) {
+      lines.push(
+        truncateToWidth(
+          fg("muted", `  (${this.selectedIndex + 1}/${this.options.length})`),
+          width,
+        ),
+      )
+    }
+
+    lines.push("")
+    lines.push(
+      truncateToWidth(
+        fg("dim", " ↑↓ navigate · Enter select · Esc cancel"),
+        width,
+      ),
+    )
+    lines.push(truncateToWidth(fg("accent", "─".repeat(width)), width))
+    return lines
+  }
+}
+
+/**
+ * Build the factory passed to `ctx.ui.custom()`.
+ *
+ * Returns either a normalized display label (the user picked an option / custom
+ * sentinel) or `null` when the user cancelled.
+ */
+export function createAskUserQuestionCustomFactory(opts: AskUserQuestionCustomOptions) {
+  return (
+    _tui: unknown,
+    theme: { fg: (color: string, text: string) => string },
+    _keybindings: unknown,
+    done: (result: AskUserQuestionSelection) => void,
+  ): AskUserQuestionSelector => {
+    return new AskUserQuestionSelector(opts, theme, done)
+  }
+}

package/extensions/ce-core/tools/ask-user-question.ts

@@ -14,7 +14,76 @@ export interface AskUserQuestionResult {
   mode: "input" | "select" | "custom" | "cancelled"
 }
 
-const CUSTOM_OPTION = "Other"
+/** Sentinel label used to offer a free-text custom answer. */
+export const CUSTOM_SENTINEL = "Other"
+
+/**
+ * Maximum display width for a normalized option label. Long labels overflow the
+ * selector row in the built-in `ctx.ui.select()` renderer (see
+ * `docs/bug/ask-user-question-long-options-truncated.md`), so labels are kept
+ * to a single line and truncated to this width.
+ */
+export const MAX_OPTION_LABEL_WIDTH = 60
+
+/**
+ * Build the single-line display label for one option.
+ *
+ * Rules:
+ * - Take only the first line (drop embedded `\n`).
+ * - Trim surrounding whitespace.
+ * - Truncate to {@link MAX_OPTION_LABEL_WIDTH} with an ellipsis when needed.
+ */
+export function toOptionDisplayLabel(option: string): string {
+  const firstLine = option.split("\n", 1)[0] ?? ""
+  const trimmed = firstLine.trim()
+  if (trimmed.length <= MAX_OPTION_LABEL_WIDTH) {
+    return trimmed
+  }
+  return trimmed.slice(0, MAX_OPTION_LABEL_WIDTH - 1) + "…"
+}
+
+/**
+ * Build display labels for all options, disambiguating collisions with a
+ * numeric suffix so the selector never shows two identical rows.
+ *
+ * @returns A map from display label back to the original full option string.
+ *          When collisions exist, labels become `<label> (#<n>)`.
+ */
+export function normalizeQuestionOptions(options: string[]): Map<string, string> {
+  const labelToOriginal = new Map<string, string>()
+  const labelCounts = new Map<string, number>()
+
+  for (const original of options) {
+    const baseLabel = toOptionDisplayLabel(original)
+    const count = (labelCounts.get(baseLabel) ?? 0) + 1
+    labelCounts.set(baseLabel, count)
+
+    // Start from the count-based suffix, then keep appending (#n) until we find
+    // a label that is truly unused. This handles pathological inputs where an
+    // option's own text already ends in `(#k)` and would otherwise collide.
+    let label = count === 1 ? baseLabel : `${baseLabel} (#${count})`
+    let dedup = count
+    while (labelToOriginal.has(label)) {
+      dedup += 1
+      label = `${baseLabel} (#${dedup})`
+    }
+    labelToOriginal.set(label, original)
+  }
+
+  return labelToOriginal
+}
+
+/** Choose a display label for the custom-answer sentinel that never collides. */
+export function resolveCustomSentinelLabel(labelToOriginal: Map<string, string>): string {
+  if (!labelToOriginal.has(CUSTOM_SENTINEL)) {
+    return CUSTOM_SENTINEL
+  }
+  let index = 2
+  while (labelToOriginal.has(`${CUSTOM_SENTINEL} (#${index})`)) {
+    index += 1
+  }
+  return `${CUSTOM_SENTINEL} (#${index})`
+}
 
 export function createAskUserQuestionTool() {
   return {
@@ -33,21 +102,31 @@ export function createAskUserQuestionTool() {
       }
 
       const allowCustom = input.allowCustom ?? true
-      const selectOptions = allowCustom ? [...options, CUSTOM_OPTION] : options
-      const selected = await ui.select(input.question, selectOptions)
+      const labelToOriginal = normalizeQuestionOptions(options)
+      const customLabel = allowCustom
+        ? resolveCustomSentinelLabel(labelToOriginal)
+        : null
+      const displayOptions = customLabel
+        ? [...labelToOriginal.keys(), customLabel]
+        : [...labelToOriginal.keys()]
+
+      const selected = await ui.select(input.question, displayOptions)
 
       if (selected === null) {
         return { answer: null, mode: "cancelled" }
       }
 
-      if (allowCustom && selected === CUSTOM_OPTION) {
+      if (allowCustom && customLabel && selected === customLabel) {
         const customAnswer = await ui.input("Your answer")
         return customAnswer === null
           ? { answer: null, mode: "cancelled" }
           : { answer: customAnswer, mode: "custom" }
       }
 
-      return { answer: selected, mode: "select" }
+      return {
+        answer: labelToOriginal.get(selected) ?? selected,
+        mode: "select",
+      }
     },
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leing2021/super-pi",
-  "version": "0.24.0",
+  "version": "0.25.1",
   "private": false,
   "type": "module",
   "description": "Pi-native Compound Engineering package for iterative development workflows",
@@ -36,10 +36,12 @@
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.74.0",
+    "@earendil-works/pi-tui": ">=0.74.0",
     "typebox": ">=1.0.0"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.76.0",
+    "@earendil-works/pi-tui": "^0.76.0",
     "bun-types": "^1.3.12"
   },
   "pi": {

package/skills/02-plan/references/ceo-review-mode.md

@@ -23,7 +23,7 @@ Re-examine the plan's assumptions:
 - What is the actual user/business outcome? Is the plan the most direct path?
 - What happens if we do nothing? Real pain or hypothetical?
 
-Present findings as premises the user must agree with. Use `ask_user_question` for each.
+Present findings as premises the user must agree with. Use `ask_user_question` for each — **one at a time, sequentially** (never two `ask_user_question` calls in the same assistant message; Pi selectors are serialized and parallel calls silently fail).
 
 ### 2. Dream State Mapping
 

package/skills/08-help/SKILL.md

@@ -1,46 +0,0 @@
----
-name: 08-help
-description: "Explain Phase 1 skills and their connections. Use when learning the workflow or deciding which skill applies."
----
-
-# Help
-
-Use this skill when the user asks how to use the package, which workflow step comes next, or which Compound Engineering skill fits the current task.
-
-## Core principle
-
-**Explain the smallest useful next step** — do not force the full sequence.
-
-## Trigger conditions
-
-| User asks | Use this skill |
-|---|---|
-| How to use the package | Help with skill selection |
-| Which step comes next | Recommend via workflow state |
-| Which skill fits | Match task to skill |
-
-## Skill mapping
-
-| Skill | When to use |
-|---|---|
-| `01-brainstorm` | Ambiguous request, new idea, requirements discovery |
-| `02-plan` | Requirements clear, turn into implementation units |
-| `03-work` | Plan ready, controlled execution |
-| `04-review` | After code changes, structured findings |
-| `05-learn` | After solving, capture reusable learning |
-| `06-next` | Check status or get next step recommendation |
-| `07-worktree` | Isolated feature development |
-
-## Workflow sequence
-
-See `references/workflow-sequence.md` for detailed flow, mode variants, and output formats.
-
-**Quick reference:**
-1. `01-brainstorm` → clarify problem
-2. `02-plan` → break into units (optional CEO/Strict review)
-3. `03-work` → execute
-4. `04-review` → inspect (optional Browser QA)
-5. `05-learn` → capture learnings
-6. `06-next` → check status anytime
-
-Before finishing this skill, apply the completion checklist in [shared pipeline instructions](../references/pipeline-config.md).

package/skills/08-help/references/workflow-sequence.md

@@ -1,135 +0,0 @@
-# Workflow Sequence
-
-## Full CE pipeline
-
-1. `01-brainstorm` → clarify the problem
-2. `02-plan` → break into units (optionally + CEO Review / Strict Review)
-3. `03-work` → execute the plan
-4. `04-review` → inspect changes (optionally + Browser QA / QA + Regression Tests)
-5. `05-learn` → save key learnings
-
-Use `06-next` at any point to see where you are and what to do next.
-Use `07-worktree` for isolated feature development on a separate branch.
-
----
-
-## Phase 1 skill guide
-
-### 01-brainstorm
-**Use when:** request is ambiguous, needs requirements discovery, or user has a new idea.
-
-**Three modes:**
-- **CE Brainstorm** — standard requirements discovery for feature additions
-- **Startup Diagnostic** — YC-style forcing questions for founders/intrapreneurs
-- **Builder Mode** — generative brainstorming for side projects/hackathons/learning
-
-**Key outputs:**
-- Requirements document in `docs/brainstorms/`
-- Explicit user approval before handoff
-
-### 02-plan
-**Use when:** requirements are clear enough to turn into implementation units.
-
-**Optional reviews after planning:**
-- **CEO Review** — challenge premises, check dream-state alignment
-- **Strict Review** — CEO Review + error maps, failure modes, test diagrams
-
-**Key outputs:**
-- Plan artifact in `docs/plans/`
-- Implementation units following TDD RED→GREEN→REFACTOR
-
-### 03-work
-**Use when:** plan is ready or task is tightly scoped.
-
-**Execution mode:**
-- Inline execution for all units in the current session
-
-**Advanced:** For external child agent delegation, install `pi-subagents` separately.
-
-**Key outputs:**
-- Completion report with verification evidence
-- Checkpoint state for resume
-
-### 04-review
-**Use when:** after code changes to produce structured findings.
-
-**Optional extensions:**
-- **Browser QA** — find visual/functional bugs with agent-browser
-- **Browser QA + Regression Tests** — also generate automated coverage
-
-**Key outputs:**
-- Structured findings per `references/findings-schema.md`
-- Optional QA report with fix commits
-
-### 05-learn
-**Use when:** after solving a problem to capture reusable learning.
-
-**Key outputs:**
-- Solution artifact in `docs/solutions/` or global `~/.pi/agent/docs/solutions/`
-- Handoff-lite for workflow closure
-
-### 06-next
-**Use when:** user wants to know what to run next, or wants full status.
-
-**Two modes:**
-- **Default** — recommend one next step with reason
-- **Verbose** (`--verbose` or "show status") — full artifact details + recent history
-
-### 07-worktree
-**Use when:** need isolated git worktree development.
-
-**Use for:** large, risky, or parallel feature work.
-
-**Flow:** create → execute via 03-work → merge → cleanup
-
----
-
-## Skill routing decision tree
-
-```
-Is the request clear and specific?
-├── No → 01-brainstorm (clarify requirements)
-└── Yes → Is there a plan?
-    ├── No → 02-plan (create implementation units)
-    └── Yes → Is work complete?
-        ├── No → 03-work (execute)
-        └── Yes → Has it been reviewed?
-            ├── No → 04-review (structured findings)
-            └── Yes → Is there a learning worth capturing?
-                ├── Yes → 05-learn
-                └── No → Check status with 06-next
-```
-
----
-
-## Output format for help responses
-
-When explaining skills to users, keep it concise:
-
-**Short form** (one skill recommendation):
-```
-Next step: `/skill:02-plan`
-
-Reason: You have a clear idea. Let's turn it into implementation units.
-```
-
-**Medium form** (context + recommendation):
-```
-Status: Requirements captured in docs/brainstorms/2024-01-idea.md
-
-Next step: `/skill:02-plan`
-
-Why: Requirements exist but no implementation plan yet.
-```
-
-**Verbose form** (full sequence):
-```
-Workflow sequence:
-1. ✅ Brainstorm: requirements captured
-2. ⏳ Plan: ready to create
-3. ⏸ Work: waiting for plan
-4. ⏸ Review: waiting for work
-5. ⏸ Learn: waiting for review
-
-Recommended: `/skill:02-plan` to turn requirements into implementation units.
-```