@leing2021/super-pi 0.23.0 → 0.23.2

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

@@ -17,6 +17,11 @@ export interface ContextHandoffInput {
   artifacts?: Record<string, string | undefined>
   handoffMarkdown?: string
   handoffPath?: string
+  currentTruth?: string[]
+  invalidatedAssumptions?: string[]
+  openDecisions?: string[]
+  recentlyAccessedFiles?: string[]
+  compressionRisk?: string[]
 }
 
 export interface ContextStateEntry {
@@ -29,6 +34,11 @@ export interface ContextStateEntry {
   blocker?: string
   verification?: string
   artifacts: Record<string, string | undefined>
+  currentTruth: string[]
+  invalidatedAssumptions: string[]
+  openDecisions: string[]
+  recentlyAccessedFiles: string[]
+  compressionRisk: string[]
   recommendNewSession: boolean
   updatedAt: string
 }
@@ -47,6 +57,11 @@ export interface ContextHandoffResult {
   artifacts?: Record<string, string | undefined>
   recommendNewSession?: boolean
   handoffMarkdown?: string
+  currentTruth?: string[]
+  invalidatedAssumptions?: string[]
+  openDecisions?: string[]
+  recentlyAccessedFiles?: string[]
+  compressionRisk?: string[]
   updatedAt?: string
 }
 
@@ -112,6 +127,11 @@ function buildDefaultHandoffMarkdown(input: {
   artifacts: Record<string, string | undefined>
   blocker?: string
   verification?: string
+  currentTruth: string[]
+  invalidatedAssumptions: string[]
+  openDecisions: string[]
+  recentlyAccessedFiles: string[]
+  compressionRisk: string[]
 }): string {
   const currentTask = input.nextStage
     ? `Continue from ${input.currentStage} to ${input.nextStage}.`
@@ -137,12 +157,24 @@ function buildDefaultHandoffMarkdown(input: {
     "## Hot Context",
     hotContext,
     "",
+    "## Current Truth",
+    formatBullets(input.currentTruth),
+    "",
     "## Verified Facts",
     verifiedFacts,
     "",
+    "## Invalidated Assumptions",
+    formatBullets(input.invalidatedAssumptions),
+    "",
+    "## Open Decisions",
+    formatBullets(input.openDecisions),
+    "",
     "## Active Files",
     activeFiles,
     "",
+    "## Recently Accessed Files",
+    formatBullets(input.recentlyAccessedFiles),
+    "",
     "## Artifacts",
     artifacts,
     "",
@@ -152,6 +184,9 @@ function buildDefaultHandoffMarkdown(input: {
     "## Verification",
     `- ${verification}`,
     "",
+    "## Compression Risk",
+    formatBullets(input.compressionRisk),
+    "",
     "## Do Not Repeat",
     "- Do not reload full history unless the handoff lacks required evidence.",
     "",
@@ -161,13 +196,54 @@ function buildDefaultHandoffMarkdown(input: {
   ].join("\n")
 }
 
+function toStringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : []
+}
+
+function normalizeStateEntry(raw: unknown): ContextStateEntry | null {
+  if (!raw || typeof raw !== "object") return null
+
+  const state = raw as Record<string, unknown>
+  const activeFiles = toStringArray(state.activeFiles)
+
+  return {
+    currentStage: typeof state.currentStage === "string" ? state.currentStage : "unknown",
+    nextStage: typeof state.nextStage === "string" ? state.nextStage : undefined,
+    contextHealth: isContextHealth(state.contextHealth) ? state.contextHealth : "watch",
+    latestHandoffPath: typeof state.latestHandoffPath === "string" ? state.latestHandoffPath : undefined,
+    latestDatedHandoffPath: typeof state.latestDatedHandoffPath === "string" ? state.latestDatedHandoffPath : undefined,
+    activeFiles,
+    blocker: typeof state.blocker === "string" ? state.blocker : undefined,
+    verification: typeof state.verification === "string" ? state.verification : undefined,
+    artifacts: isStringRecord(state.artifacts) ? state.artifacts : {},
+    currentTruth: toStringArray(state.currentTruth),
+    invalidatedAssumptions: toStringArray(state.invalidatedAssumptions),
+    openDecisions: toStringArray(state.openDecisions),
+    recentlyAccessedFiles: toStringArray(state.recentlyAccessedFiles).length > 0
+      ? toStringArray(state.recentlyAccessedFiles)
+      : activeFiles.slice(0, 5),
+    compressionRisk: toStringArray(state.compressionRisk),
+    recommendNewSession: typeof state.recommendNewSession === "boolean" ? state.recommendNewSession : false,
+    updatedAt: typeof state.updatedAt === "string" ? state.updatedAt : new Date(0).toISOString(),
+  }
+}
+
+function isContextHealth(value: unknown): value is ContextHealth {
+  return value === "good" || value === "watch" || value === "heavy" || value === "critical"
+}
+
+function isStringRecord(value: unknown): value is Record<string, string | undefined> {
+  if (!value || typeof value !== "object") return false
+  return Object.values(value).every(item => item === undefined || typeof item === "string")
+}
+
 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
+    return normalizeStateEntry(JSON.parse(content))
   } catch {
     return null
   }
@@ -207,6 +283,14 @@ async function save(input: ContextHandoffInput): Promise<ContextHandoffResult> {
   const blocker = input.blocker
   const verification = input.verification
   const artifacts = input.artifacts ?? {}
+  const currentTruth = input.currentTruth ?? []
+  const invalidatedAssumptions = input.invalidatedAssumptions ?? []
+  const openDecisions = input.openDecisions ?? []
+  const recentlyAccessedFiles = input.recentlyAccessedFiles?.length
+    ? input.recentlyAccessedFiles
+    : activeFiles.slice(0, 5)
+  const compressionRisk = input.compressionRisk ?? []
+
   const handoffMarkdown = input.handoffMarkdown?.trim().length
     ? input.handoffMarkdown
     : buildDefaultHandoffMarkdown({
@@ -216,6 +300,11 @@ async function save(input: ContextHandoffInput): Promise<ContextHandoffResult> {
       artifacts,
       blocker,
       verification,
+      currentTruth,
+      invalidatedAssumptions,
+      openDecisions,
+      recentlyAccessedFiles,
+      compressionRisk,
     })
 
   const recommendNewSession = computeRecommendNewSession(currentStage, nextStage, contextHealth)
@@ -238,6 +327,11 @@ async function save(input: ContextHandoffInput): Promise<ContextHandoffResult> {
     blocker,
     verification,
     artifacts,
+    currentTruth,
+    invalidatedAssumptions,
+    openDecisions,
+    recentlyAccessedFiles,
+    compressionRisk,
     recommendNewSession,
     updatedAt: new Date().toISOString(),
   }
@@ -256,6 +350,11 @@ async function save(input: ContextHandoffInput): Promise<ContextHandoffResult> {
     blocker,
     verification,
     artifacts,
+    currentTruth,
+    invalidatedAssumptions,
+    openDecisions,
+    recentlyAccessedFiles,
+    compressionRisk,
     recommendNewSession,
     updatedAt: state.updatedAt,
   }
@@ -291,6 +390,11 @@ async function load(input: ContextHandoffInput): Promise<ContextHandoffResult> {
     blocker: state.blocker,
     verification: state.verification,
     artifacts: state.artifacts,
+    currentTruth: state.currentTruth,
+    invalidatedAssumptions: state.invalidatedAssumptions,
+    openDecisions: state.openDecisions,
+    recentlyAccessedFiles: state.recentlyAccessedFiles,
+    compressionRisk: state.compressionRisk,
     recommendNewSession: state.recommendNewSession,
     handoffMarkdown: markdown,
     updatedAt: state.updatedAt,
@@ -320,6 +424,11 @@ async function latest(input: ContextHandoffInput): Promise<ContextHandoffResult>
     blocker: state.blocker,
     verification: state.verification,
     artifacts: state.artifacts,
+    currentTruth: state.currentTruth,
+    invalidatedAssumptions: state.invalidatedAssumptions,
+    openDecisions: state.openDecisions,
+    recentlyAccessedFiles: state.recentlyAccessedFiles,
+    compressionRisk: state.compressionRisk,
     recommendNewSession: state.recommendNewSession,
     updatedAt: state.updatedAt,
   }
@@ -351,6 +460,11 @@ async function status(input: ContextHandoffInput): Promise<ContextHandoffResult>
     blocker: state.blocker,
     verification: state.verification,
     artifacts: state.artifacts,
+    currentTruth: state.currentTruth,
+    invalidatedAssumptions: state.invalidatedAssumptions,
+    openDecisions: state.openDecisions,
+    recentlyAccessedFiles: state.recentlyAccessedFiles,
+    compressionRisk: state.compressionRisk,
     recommendNewSession: state.recommendNewSession,
     updatedAt: state.updatedAt,
   }

package/extensions/ce-core/tools/workflow-state.ts

@@ -1,4 +1,4 @@
-import { readdirSync, statSync, existsSync } from "node:fs"
+import { readdirSync, existsSync, readFileSync } from "node:fs"
 import path from "node:path"
 
 export interface WorkflowCategoryState {
@@ -6,6 +6,25 @@ export interface WorkflowCategoryState {
   latest: string | null
 }
 
+export interface WorkflowContextState {
+  found: boolean
+  currentStage?: string
+  nextStage?: string
+  contextHealth?: string
+  latestHandoffPath?: string
+  latestDatedHandoffPath?: string
+  activeFiles: string[]
+  recentlyAccessedFiles: string[]
+  blocker?: string
+  verification?: string
+  currentTruth: string[]
+  invalidatedAssumptions: string[]
+  openDecisions: string[]
+  compressionRisk: string[]
+  recommendNewSession?: boolean
+  updatedAt?: string
+}
+
 export interface WorkflowStateInput {
   repoRoot: string
 }
@@ -15,6 +34,7 @@ export interface WorkflowStateResult {
   plans: WorkflowCategoryState
   solutions: WorkflowCategoryState
   runs: WorkflowCategoryState
+  context: WorkflowContextState
 }
 
 function emptyCategory(): WorkflowCategoryState {
@@ -63,6 +83,52 @@ function collectFiles(dirPath: string): string[] {
   return results
 }
 
+function emptyContext(): WorkflowContextState {
+  return {
+    found: false,
+    activeFiles: [],
+    recentlyAccessedFiles: [],
+    currentTruth: [],
+    invalidatedAssumptions: [],
+    openDecisions: [],
+    compressionRisk: [],
+  }
+}
+
+function toStringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : []
+}
+
+function readContextState(repoRoot: string): WorkflowContextState {
+  const statePath = path.join(repoRoot, ".context", "compound-engineering", "context-state.json")
+  if (!existsSync(statePath)) return emptyContext()
+
+  try {
+    const raw = readFileSync(statePath, "utf8")
+    const state = JSON.parse(raw) as Record<string, unknown>
+    return {
+      found: true,
+      currentStage: typeof state.currentStage === "string" ? state.currentStage : undefined,
+      nextStage: typeof state.nextStage === "string" ? state.nextStage : undefined,
+      contextHealth: typeof state.contextHealth === "string" ? state.contextHealth : undefined,
+      latestHandoffPath: typeof state.latestHandoffPath === "string" ? state.latestHandoffPath : undefined,
+      latestDatedHandoffPath: typeof state.latestDatedHandoffPath === "string" ? state.latestDatedHandoffPath : undefined,
+      activeFiles: toStringArray(state.activeFiles),
+      recentlyAccessedFiles: toStringArray(state.recentlyAccessedFiles),
+      blocker: typeof state.blocker === "string" ? state.blocker : undefined,
+      verification: typeof state.verification === "string" ? state.verification : undefined,
+      currentTruth: toStringArray(state.currentTruth),
+      invalidatedAssumptions: toStringArray(state.invalidatedAssumptions),
+      openDecisions: toStringArray(state.openDecisions),
+      compressionRisk: toStringArray(state.compressionRisk),
+      recommendNewSession: typeof state.recommendNewSession === "boolean" ? state.recommendNewSession : undefined,
+      updatedAt: typeof state.updatedAt === "string" ? state.updatedAt : undefined,
+    }
+  } catch {
+    return emptyContext()
+  }
+}
+
 export function createWorkflowStateTool() {
   return {
     name: "workflow_state",
@@ -74,6 +140,7 @@ export function createWorkflowStateTool() {
         plans: scanDir(path.join(repoRoot, "docs", "plans")),
         solutions: scanDir(path.join(repoRoot, "docs", "solutions")),
         runs: scanDir(path.join(repoRoot, ".context", "compound-engineering")),
+        context: readContextState(repoRoot),
       }
     },
   }

package/package.json

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

package/skills/01-brainstorm/SKILL.md

@@ -5,120 +5,83 @@ description: "Brainstorm requirements with three modes: CE discovery, Startup Di
 
 # Brainstorm
 
-Use this skill when the request is ambiguous, needs requirements discovery before planning, or the user describes a new idea/product.
+Use this skill when the request is ambiguous, needs requirements discovery, 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.
-- Start with `start` operation: present initial analysis and open questions.
-- Use `refine` operation: incorporate user responses and produce refined analysis with new questions.
-- Repeat refine rounds until all open questions are resolved.
-- End with `summarize` operation: finalize into a requirements-ready artifact.
-- Ask **one question at a time** within each round.
+- Use **`brainstorm_dialog`** to manage multi-round conversations (`start` → `refine` → `summarize`).
+- Ask **one question at a time**.
 - Compare **2-3 approaches** when multiple directions are plausible.
-- Keep the artifact focused on **what** should be built, not implementation details by default.
-- Write the result to `docs/brainstorms/` as a durable requirements document.
-- End by recommending `02-plan` when the requirements are ready.
-- **Do not proceed to planning without explicit user approval** of the design.
+- Keep focused on **what** to build, not implementation details.
+- **Explicit user approval required** before handoff to `02-plan`.
+- Write result to `docs/brainstorms/` as durable requirements document.
 
 ## Mode selection
 
-After initial context gathering, determine which mode to use. Use `ask_user_question`:
+After initial context, determine mode via `ask_user_question`:
 
-> Before we dig in, what's your goal with this?
->
-> - **Building a startup** (or thinking about it)
-> - **Intrapreneurship** — internal project, need to ship fast
-> - **Side project / hackathon / learning** — building for fun or exploration
-> - **Adding a feature** — already have a project, need to design a change
+> What's your goal?
+> - **Building a startup** → Startup Diagnostic
+> - **Intrapreneurship** → Startup Diagnostic
+> - **Side project / hackathon** → Builder Mode
+> - **Adding a feature** → CE Brainstorm
 
-**Mode mapping:**
-- Startup, intrapreneurship → **Startup Diagnostic** (see `references/startup-diagnostic.md`)
-- Side project, hackathon, learning → **Builder Mode** (see `references/builder-mode.md`)
-- Adding a feature → **CE Brainstorm** (the existing requirements discovery flow below)
-
-If the user's request already makes the mode obvious (e.g., "I have a startup idea"), skip the question and go directly to the matching mode.
-
-## Startup Diagnostic mode
-
-Read `references/startup-diagnostic.md` for the full YC-style forcing questions, pushback patterns, and anti-sycophancy rules.
-
-Key differences from CE mode:
-- **Operating principles:** Specificity is the only currency. Interest is not demand. The status quo is your real competitor. Narrow beats wide, early.
-- **Ask the six forcing questions** one at a time, pushing until answers are specific and uncomfortable.
-- **Smart routing:** Pre-product (Q1-Q3), Has users (Q2, Q4, Q5), Paying customers (Q4, Q5, Q6).
-- **End with the assignment:** One concrete action the founder should take next.
+Skip question if mode is obvious from request.
 
-After the diagnostic, run Premise Challenge (see `references/premise-challenge.md`), then proceed to Alternatives Generation and design checklist.
-
-## Builder Mode
-
-Read `references/builder-mode.md` for the full generative question set and response posture.
-
-Key differences from CE mode:
-- **Operating principles:** Delight is the currency. Ship something you can show. Solve your own problem. Explore before you optimize.
-- **Ask generative questions** one at a time (coolest version, who would you show, fastest path, what's different, 10x version).
-- **End with concrete build steps**, not business validation tasks.
-- **Vibe shift detection:** If the user starts talking about customers/revenue, upgrade to Startup Diagnostic.
-
-After the questions, run Premise Challenge (see `references/premise-challenge.md`), then proceed to Alternatives Generation and design checklist.
+**Mode mapping:**
+- Startup / intrapreneurship → **Startup Diagnostic** (see `references/startup-diagnostic.md`)
+- Side project / hackathon → **Builder Mode** (see `references/builder-mode.md`)
+- Feature addition → **CE Brainstorm** (see `references/ce-brainstorm-mode.md`)
 
-## CE Brainstorm mode (existing flow)
+## Mode summaries
 
-This is the original Compound Engineering brainstorm. Use when adding a feature to an existing project.
+| Mode | Key principle | End goal |
+|---|---|---|
+| Startup Diagnostic | Specificity is currency, narrow beats wide | One concrete next action |
+| Builder Mode | Delight is currency, ship something showable | Concrete build steps |
+| CE Brainstorm | Requirements clarity | Implementation-ready spec |
 
-1. Scan the repository for nearby context.
-2. Use `brainstorm_dialog` `start` to begin multi-round refinement.
-3. Present initial analysis and open questions to the user.
-4. Use `brainstorm_dialog` `refine` to incorporate user responses and refine analysis.
-5. Repeat step 4 until all questions are resolved.
+See reference files for full question sets and patterns.
 
-## Premise Challenge (all modes)
+## Premise Challenge
 
-After the mode-specific questions are complete, run the Premise Challenge. See `references/premise-challenge.md`.
+After mode-specific questions, run Premise Challenge. See `references/premise-challenge.md`.
 
 ## Design checklist
 
 Before summarizing, ensure the design answers:
 - What are we building?
 - Why does it exist?
-- What files/modules are likely to change?
-- What are the boundaries between responsibilities?
-- What can fail, and how should failure be handled?
+- What files/modules will change?
+- What are the responsibility boundaries?
+- What can fail, and how?
 - How will we verify success?
 
 ## Stop conditions
 
-Stop and ask the user instead of guessing when:
-- requirements conflict
-- success criteria are unclear
-- the task spans multiple independent systems
-- the user has not approved the design yet
+Stop and ask instead of guessing when: requirements conflict, success criteria unclear, task spans multiple systems, or user hasn't approved design.
 
 ## Approval gate
 
-Before handing off to `02-plan`:
-1. Present the final design to the user.
-2. Ask for explicit approval.
-3. Only proceed after the user confirms.
+**Required:** Explicit user approval before handoff to `02-plan`.
 
 ## Workflow
 
-1. Scan the repository for nearby context.
-2. Determine mode (Startup / Builder / CE) via the mode selection step.
-3. Run mode-specific questions using the appropriate reference file.
-4. Run Premise Challenge.
-5. Generate 2-3 alternatives (at least one "minimal viable" and one "ideal architecture").
-6. Validate against the design checklist.
-7. Use `brainstorm_dialog` `summarize` to finalize the conversation.
-8. Capture the agreed direction in a requirements artifact under `docs/brainstorms/`.
-9. Get explicit user approval before handing off.
-10. Hand off to `02-plan` using `references/handoff.md`.
+1. Scan repository for nearby context
+2. Determine mode (Startup / Builder / CE)
+3. Run mode-specific questions (use reference files)
+4. Run Premise Challenge
+5. Generate 2-3 alternatives (minimal viable + ideal architecture)
+6. Validate against design checklist
+7. Use `brainstorm_dialog` `summarize` to finalize
+8. Capture requirements in `docs/brainstorms/`
+9. Get explicit user approval
+10. Handoff to `02-plan` using `references/handoff.md`
 
 ## 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.
+Use `references/requirements-template.md` to structure the document. Keep implementation details out unless specifically about architecture.
 
 Before finishing this skill, apply the completion checklist in [shared pipeline instructions](../references/pipeline-config.md).

package/skills/01-brainstorm/references/ce-brainstorm-mode.md

@@ -0,0 +1,47 @@
+# CE Brainstorm Mode
+
+Standard requirements discovery flow for feature additions to existing projects.
+
+## When to use
+
+- Adding a feature to an existing project
+- User has a project but unclear about what to build
+- Request is somewhat specific but needs elaboration
+
+## Operating principle
+
+**Requirements clarity** — the goal is to produce implementation-ready specifications.
+
+## Workflow
+
+1. Scan the repository for nearby context
+2. Use `brainstorm_dialog` `start` to begin multi-round refinement
+3. Present initial analysis and open questions to the user
+4. Use `brainstorm_dialog` `refine` to incorporate user responses and refine analysis
+5. Repeat step 4 until all questions are resolved
+
+## Key questions
+
+Ask one at a time:
+- What problem does this feature solve?
+- Who is the user/consumer?
+- What does success look like?
+- What are the boundaries?
+- What could go wrong?
+
+## End state
+
+Requirements document covering:
+- Feature purpose and scope
+- User-facing behavior
+- Edge cases and failure modes
+- Success criteria
+- Likely file changes
+
+## Difference from other modes
+
+| Aspect | CE Brainstorm | Startup Diagnostic | Builder Mode |
+|---|---|---|---|
+| Goal | Implementation clarity | Business validation | Buildable prototype |
+| Questions | Requirements-focused | Problem-first | Solution-first |
+| Output | Spec document | One action | Build steps |

package/skills/02-plan/SKILL.md

@@ -11,77 +11,58 @@ See [shared pipeline instructions](../references/pipeline-config.md) for model r
 
 ## Core rules
 
-- Before planning, load project rules:
-  1. `rules/common/development-workflow.md` and `rules/common/testing.md`
-  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/`.
-- Break the work into implementation units instead of writing an execution script.
-- If a plan already exists, use **`plan_diff`** to compare existing units with new requirements and apply incremental changes instead of rewriting.
-- End by recommending `03-work` once the plan is ready.
+1. Load project rules (4 steps):
+   - Load `rules/common/development-workflow.md` and `rules/common/testing.md`
+   - Detect project language via [language detection](../references/language-detection.md)
+   - Load matching language-specific rules (e.g., `rules/typescript/`)
+   - If frontend/browser concerns, also load `rules/web/` files
+2. **Priority:** project-level `{repo-root}/rules/` overrides package defaults
+3. Search `docs/brainstorms/` for relevant requirements first
+4. Run solution search (see `references/solution-search.md`):
+   - Extract keywords → `grep -rl "tags:.*keyword" docs/solutions/ ~/.pi/agent/docs/solutions/`
+   - Read **frontmatter** only (first 15 lines) of matches → score by severity + tag relevance
+   - Fully read top 3 candidates
+5. Write plan to `docs/plans/`
+6. If plan exists, use **`plan_diff`** to compare and patch incrementally
+7. End by recommending `03-work`
 
 ## Hard gates — TDD enforcement
 
-Every implementation unit must follow **RED, GREEN, REFACTOR**:
-- No production code step may appear before a failing test step.
-- Every unit must include exact verification commands.
-- No placeholders allowed — replace "handle edge cases" with concrete steps.
+Every unit follows **RED → GREEN → REFACTOR**:
 
-**TDD violation rejection criteria** — stop and revise the plan if any unit:
-- implements code before a failing test
-- lacks a command proving the RED step
-- lacks a command proving the GREEN step
-- skips verification
-- relies on unstated tools or assumptions
+**TDD violation rejection criteria** — reject and revise if any unit:
+- Implements code before failing test
+- Lacks RED step verification
+- Lacks GREEN step verification
+- Skips verification
+- Uses placeholders or unstated assumptions
 
 ## Planning flow
 
-1. Read the most relevant brainstorm artifact from `docs/brainstorms/` when one exists.
-2. Execute the solution search strategy: extract keywords → grep frontmatter fields (tags, title) in `docs/solutions/` and `~/.pi/agent/docs/solutions/` → read frontmatter of candidates only → score and rank → fully read top 3.
-3. Gather repository context from the affected areas.
-4. If a plan already exists:
-   a. Use `plan_diff` `compare` to identify added, removed, modified, and unchanged units.
-   b. Review the diff with the user.
-   c. Use `plan_diff` `patch` to apply approved changes.
-5. If no plan exists, write a new plan artifact under `docs/plans/` using `references/plan-template.md`.
-6. Structure the work using `references/implementation-unit-template.md`.
-7. Verify every unit follows strict TDD — reject units that violate the gates above.
+1. Read relevant brainstorm from `docs/brainstorms/`
+2. Run solution search (keywords → grep frontmatter → read top 3)
+3. Gather repository context
+4. If plan exists: use `plan_diff` `compare` → review with user → `patch`
+5. If no plan: write new plan under `docs/plans/` using `references/plan-template.md`
+6. Structure work using `references/implementation-unit-template.md`
+7. Verify every unit follows TDD gates
 
 ## Optional: CEO Review
 
-After the plan artifact is written (step 5 or 6 above), offer the user a strategic review:
-
-> Plan ready. How do you want to review it?
->
-> - **A) Just go** — trust the plan, skip review
-> - **B) CEO Review** — challenge premises, check for better alternatives, dream-state mapping
-> - **C) Strict Review** — full CEO Review plus error maps, failure modes, test diagrams
-
-If the user picks A, proceed directly to the `03-work` handoff.
-If the user picks B or C, read `references/ceo-review-mode.md` and execute the review flow.
-
-After CEO/Strict Review:
-1. Update the plan artifact with any changes the user approved.
-2. Note the review mode and key decisions in the plan.
-3. Proceed to the `03-work` handoff.
-
-## Implementation unit format
-
-Every unit must include:
-- **Purpose**: what this unit accomplishes
-- **Files**: exact paths to create, modify, or test
-- **Steps** as checkboxes:
-  1. Write or update a failing test
-  2. Run the targeted test and confirm it fails for the expected reason (RED)
-  3. Write the minimal implementation needed to pass
-  4. Run the targeted test and confirm it passes (GREEN)
-  5. Refactor if needed while keeping tests green
-  6. Run unit-level verification
-- **Verification commands**: exact commands to run
-- **Expected results**: what success looks like
+After plan is written, offer strategic review:
+
+> Plan ready. How to review?
+> - **A) Just go** — trust the plan
+> - **B) CEO Review** — challenge premises, dream-state mapping
+> - **C) Strict Review** — CEO + error maps, failure modes, test diagrams
+
+If B or C: read `references/ceo-review-mode.md` and execute review flow.
+After review: update plan artifact, then handoff to `03-work`.
+
+## Artifact output
+
+- Plan: `docs/plans/<slug>.md`
+- Use `references/plan-template.md` structure
+- Implementation units follow `references/implementation-unit-template.md`
 
 Before finishing this skill, apply the completion checklist in [shared pipeline instructions](../references/pipeline-config.md).