@leing2021/super-pi 0.23.10 → 0.23.12

package/README.md

@@ -71,7 +71,7 @@ You: /skill:03-work docs/plans/plan.md
 
 | Skill | What it does | Core tool |
 |-------|-------------|-----------|
-| **01-brainstorm** | Structured multi-round discovery | `brainstorm_dialog` |
+| **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, bounded subagents, checkpoint resume, strict TDD, stop-the-line | `ce_subagent`, `ce_parallel_subagent` |
 | **04-review** | Auto-assigned reviewers, five-axis findings, autofix loop | `review_router` |
@@ -122,6 +122,7 @@ Super Pi is not a fork or wrapper. It extracts useful methods from the projects
 | [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. |
 | [gstack](https://github.com/garrytan/gstack) | YC-style forcing questions, CEO Review cognitive frameworks, browser QA patterns, failure maps, and evidence-first validation. |
+| [mattpocock/skills](https://github.com/mattpocock/skills) | Context glossary (`CONTEXT.md`) for cross-session term persistence, lightweight ADR with three-condition threshold, and feedback-loop-first debug discipline. Adopted as reference templates embedded into existing skills — no new skills or tools. |
 
 ---
 
@@ -133,8 +134,8 @@ When an unexpected failure occurs during `03-work`:
 
 1. **STOP** adding features
 2. **PRESERVE** evidence
-3. **DIAGNOSE** root cause
-4. **FIX** the root cause
+3. **DIAGNOSE** root cause — build a feedback loop first, then reproduce → hypothesise → instrument → fix
+4. **FIX** the root cause, not the symptom
 5. **GUARD** with a regression test
 6. **RESUME** only after verification passes
 
@@ -173,6 +174,7 @@ your-project/
 ├── docs/
 │   ├── brainstorms/      # Requirements
 │   ├── plans/             # Execution plans
+│   ├── adr/               # Architecture decisions (lazy)
 │   └── solutions/         # Knowledge cards
 └── .context/
     └── compound-engineering/

package/extensions/ce-core/index.ts

@@ -130,7 +130,7 @@ function createSubagentRunner(
       prompt,
       agent: "",
       task: "",
-      cwd: pi.cwd ?? process.cwd(),
+      cwd: (pi as any).cwd ?? process.cwd(),
       extraFlags: options?.extraFlags,
       extraEnv: options?.extraEnv,
       signal,
@@ -503,7 +503,7 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
           inheritSkills: params.inheritSkills,
         },
         createSubagentRunner(pi, signal),
-        { onUpdate },
+        { onUpdate: onUpdate ? (details) => onUpdate({ content: [], details }) : undefined },
       )
 
       // Build final content from results
@@ -521,7 +521,10 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
       return renderSubagentCall(args, theme)
     },
     renderResult(result, renderContext, theme, _context) {
-      return renderSubagentResult(result.details as SubagentLiveDetails, renderContext, theme)
+      // Handle partial updates where data is at top level (from onUpdate)
+      // rather than nested in .details (from final result return value)
+      const data = (result.details || result) as SubagentLiveDetails
+      return renderSubagentResult(data, renderContext, theme)
     },
   })
 
@@ -620,31 +623,46 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
           inheritSkills: params.inheritSkills,
         },
         createSubagentRunner(pi, signal),
-        { onUpdate },
+        { onUpdate: onUpdate ? (details) => onUpdate({ content: [], details }) : undefined },
       )
 
-      // Build summary content
+      // Build compact summary content for LLM consumption
       const successCount = result.results.filter(r => r.exitCode === 0).length
       const failCount = result.results.filter(r => isFailedResult(r)).length
-      const summaries = result.results.map(r => {
+      const summaries = result.results.map((r, i) => {
+        const icon = isFailedResult(r) ? "✗" : "✓"
         const output = getFinalOutput(r.messages) || r.errorMessage || r.stderr || "(no output)"
-        const status = isFailedResult(r) ? "failed" : "completed"
-        return `### [${r.agent}] ${status}\n\n${output}`
+        // Compact: first non-empty line, stripped of markdown formatting
+        const summaryLine = output.split("\n").find((l: string) => l.trim().length > 0) || ""
+        const cleaned = summaryLine.replace(/^#+\s*/, "").replace(/\*\*/g, "").trim()
+        const oneLine = cleaned.length > 200 ? cleaned.slice(0, 199) + "…" : cleaned
+        return `${i + 1}. ${icon} ${r.agent} — ${oneLine}`
+      })
+
+      // Full outputs available in details for expanded view
+      const fullOutputs = result.results.map(r => {
+        const output = getFinalOutput(r.messages) || ""
+        return output
       })
 
       return {
         content: [{
           type: "text",
-          text: `Parallel: ${successCount}/${result.results.length} succeeded${failCount > 0 ? `, ${failCount} failed` : ""}\n\n${summaries.join("\n\n---\n\n")}`,
+          text: `Parallel: ${successCount}/${result.results.length} succeeded${failCount > 0 ? `, ${failCount} failed` : ""}\n${summaries.join("\n")}`,
         }],
         details: result,
       }
     },
     renderCall(args, theme, _context) {
-      return renderSubagentCall(args, theme)
+      return renderSubagentCall({
+        tasks: typeof args.tasks === "string" ? [] : args.tasks,
+      }, theme)
     },
     renderResult(result, renderContext, theme, _context) {
-      return renderSubagentResult(result.details as SubagentLiveDetails, renderContext, theme)
+      // Handle partial updates where data is at top level (from onUpdate)
+      // rather than nested in .details (from final result return value)
+      const data = (result.details || result) as ParallelSubagentLiveDetails
+      return renderSubagentResult(data, renderContext, theme)
     },
   })
 

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

@@ -20,11 +20,13 @@ import {
   getFinalOutput,
   makeFailedResult,
   invokeRunner,
+  type AnyRunner,
 } from "./subagent-events"
 import {
   assertNonPipelineStageSkill,
   type SubagentLiveRunner,
   type SubagentLiveExecOptions,
+  type SubagentRunner,
 } from "./subagent"
 
 // ---------------------------------------------------------------------------
@@ -88,7 +90,7 @@ export function createParallelSubagentTool() {
 
     async execute(
       input: ParallelSubagentInput,
-      runner: SubagentLiveRunner,
+      runner: SubagentLiveRunner | SubagentRunner,
       toolCtx?: { onUpdate?: (details: ParallelSubagentLiveDetails) => void },
     ): Promise<ParallelSubagentLiveDetails> {
       // Recursion depth guard

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

@@ -142,13 +142,14 @@ export function renderSubagentCall(
 
   if (args.tasks && args.tasks.length > 0) {
     let text =
-      theme.fg("toolTitle", theme.bold("ce_parallel_subagent ")) +
-      theme.fg("accent", `parallel (${args.tasks.length} tasks)`)
-    for (const t of args.tasks.slice(0, 3)) {
-      const preview = t.task.length > 40 ? `${t.task.slice(0, 40)}...` : t.task
-      text += `\n  ${theme.fg("accent", t.agent)}${theme.fg("dim", ` ${preview}`)}`
+      theme.fg("toolTitle", theme.bold("⬇ parallel ")) +
+      theme.fg("accent", `${args.tasks.length} agents launching...`)
+    for (let i = 0; i < args.tasks.length; i++) {
+      const t = args.tasks[i]
+      const num = theme.fg("muted", `${i + 1}.`)
+      const preview = t.task.length > 50 ? `${t.task.slice(0, 50)}...` : t.task
+      text += `\n  ${num} ${theme.fg("accent", t.agent)} ${theme.fg("dim", preview)}`
     }
-    if (args.tasks.length > 3) text += `\n  ${theme.fg("muted", `... +${args.tasks.length - 3} more`)}`
     return new Text(text, 0, 0)
   }
 
@@ -373,70 +374,94 @@ function renderParallelResult(
   const successCount = results.filter(r => r.exitCode !== -1 && !isFailedResult(r)).length
   const failCount = results.filter(r => r.exitCode !== -1 && isFailedResult(r)).length
   const isRunning = running > 0
-  const icon = isRunning
-    ? theme.fg("warning", "⏳")
-    : failCount > 0
-      ? theme.fg("warning", "◐")
-      : theme.fg("success", "✓")
-  const status = isRunning
-    ? `${successCount + failCount}/${results.length} done, ${running} running`
-    : `${successCount}/${results.length} tasks`
-
-  if (context.expanded && !isRunning) {
+
+  if (isRunning) {
+    // --- Live progress: compact status line ---
+    const doneCount = successCount + failCount
+    const icon = theme.fg("warning", "⏳")
+    const bar = renderProgressBar(doneCount, results.length, theme)
+    const doneLabel = failCount > 0
+      ? theme.fg("success", `${doneCount}/${results.length}✓`) + " " + theme.fg("error", `${failCount}✗`)
+      : theme.fg("success", `${doneCount}/${results.length}✓`)
+    const runningLabel = theme.fg("dim", `, ${running} running...`)
+    return new Text(`${icon} ${bar} ${doneLabel}${runningLabel}`, 0, 0)
+  }
+
+  // --- Completed: summary card layout ---
+  const allSuccess = failCount === 0
+  const headerIcon = allSuccess ? theme.fg("success", "✓") : theme.fg("warning", "◐")
+  const headerText = failCount > 0
+    ? `${successCount}/${results.length} succeeded, ${failCount} failed`
+    : `${successCount}/${results.length} succeeded`
+
+  if (context.expanded) {
+    // Expanded: header + per-task details with tool calls and output
     const container = new Container()
-    container.addChild(new Text(`${icon} ${theme.fg("toolTitle", theme.bold("parallel "))}${theme.fg("accent", status)}`, 0, 0))
+    container.addChild(new Text(`${headerIcon} ${theme.fg("toolTitle", theme.bold("parallel "))}${theme.fg("accent", headerText)}`, 0, 0))
+    container.addChild(new Spacer(1))
 
     for (const r of results) {
       const rIcon = isFailedResult(r) ? theme.fg("error", "✗") : theme.fg("success", "✓")
-      const displayItems = getDisplayItems(r.messages)
       const finalOutput = getFinalOutput(r.messages)
+      const summaryText = isFailedResult(r)
+        ? (r.errorMessage || r.stderr || "unknown error")
+        : (finalOutput ? summarizeText(finalOutput, 200) : "(no output)")
 
-      container.addChild(new Spacer(1))
-      container.addChild(new Text(`${theme.fg("muted", "─── ")}${theme.fg("accent", r.agent)} ${rIcon}`, 0, 0))
-      container.addChild(new Text(theme.fg("muted", "Task: ") + theme.fg("dim", r.task), 0, 0))
-      for (const item of displayItems) {
-        if (item.type === "toolCall")
-          container.addChild(new Text(theme.fg("muted", "→ ") + formatToolCall(item.name, item.args, theme.fg.bind(theme)), 0, 0))
-      }
-      if (finalOutput) {
-        container.addChild(new Spacer(1))
+      container.addChild(new Text(`${rIcon} ${theme.fg("accent", r.agent)} — ${summaryText}`, 0, 0))
+
+      if (!isFailedResult(r) && finalOutput) {
         container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme))
       }
+
       const taskUsage = formatUsageStats(r.usage, r.model)
       if (taskUsage) container.addChild(new Text(theme.fg("dim", taskUsage), 0, 0))
+      container.addChild(new Spacer(1))
     }
 
     const usageStr = formatUsageStats(aggregateUsage(results))
     if (usageStr) {
-      container.addChild(new Spacer(1))
       container.addChild(new Text(theme.fg("dim", `Total: ${usageStr}`), 0, 0))
     }
     return container
   }
 
-  // Collapsed (or still running)
-  let text = `${icon} ${theme.fg("toolTitle", theme.bold("parallel "))}${theme.fg("accent", status)}`
+  // Collapsed: one-line summary per task
+  let text = `${headerIcon} ${theme.fg("toolTitle", theme.bold("parallel "))}${theme.fg("accent", headerText)}`
   for (const r of results) {
-    const rIcon =
-      r.exitCode === -1
-        ? theme.fg("warning", "⏳")
-        : isFailedResult(r)
-          ? theme.fg("error", "✗")
-          : theme.fg("success", "✓")
-    const displayItems = getDisplayItems(r.messages)
-    text += `\n\n${theme.fg("muted", "─── ")}${theme.fg("accent", r.agent)} ${rIcon}`
-    if (displayItems.length === 0)
-      text += `\n${theme.fg("muted", r.exitCode === -1 ? "(running...)" : "(no output)")}`
-    else text += `\n${renderDisplayItems(displayItems, 5)}`
+    const rIcon = isFailedResult(r) ? theme.fg("error", "✗") : theme.fg("success", "✓")
+    const finalOutput = getFinalOutput(r.messages)
+    const summaryText = isFailedResult(r)
+      ? (r.errorMessage || r.stderr || "unknown error")
+      : (finalOutput ? summarizeText(finalOutput, 120) : "(no output)")
+    text += `\n  ${rIcon} ${theme.fg("accent", r.agent)} — ${summaryText}`
   }
-  if (!isRunning) {
-    const usageStr = formatUsageStats(aggregateUsage(results))
-    if (usageStr) text += `\n\n${theme.fg("dim", `Total: ${usageStr}`)}`
-  }
-  if (!context.expanded) text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`
+  const usageStr = formatUsageStats(aggregateUsage(results))
+  if (usageStr) text += `\n${theme.fg("dim", usageStr)}`
+  text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`
   return new Text(text, 0, 0)
 }
 
+// ---------------------------------------------------------------------------
+// Progress bar & text helpers
+// ---------------------------------------------------------------------------
+
+function renderProgressBar(done: number, total: number, theme: Theme): string {
+  const width = Math.min(total, 20)
+  const filled = Math.round((done / total) * width)
+  const empty = width - filled
+  const bar = theme.fg("success", "█".repeat(filled)) + theme.fg("dim", "░".repeat(empty))
+  return bar
+}
+
+function summarizeText(text: string, maxLen: number): string {
+  // Take first meaningful paragraph or line
+  const firstLine = text.split("\n").find(l => l.trim().length > 0) || ""
+  // Strip markdown headers and bold for summary
+  const cleaned = firstLine.replace(/^#+\s*/, "").replace(/\*\*/g, "").replace(/\[.*?\]\(.*?\)/g, "").trim()
+  if (cleaned.length <= maxLen) return cleaned
+  return cleaned.slice(0, maxLen - 1) + "…"
+}
+
 // ---------------------------------------------------------------------------
 // Markdown theme helper
 // ---------------------------------------------------------------------------

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

@@ -35,7 +35,7 @@ export interface SubagentInput {
 }
 
 export interface SubagentLiveDetails {
-  mode: "single" | "chain"
+  mode: "single" | "chain" | "parallel"
   results: SingleResult[]
 }
 

package/package.json

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

package/skills/01-brainstorm/SKILL.md

@@ -59,6 +59,15 @@ Before summarizing, ensure the design answers:
 - What can fail, and how?
 - How will we verify success?
 
+## Domain vocabulary (optional)
+
+After mode-specific questions, check if the project has a `CONTEXT.md` at root.
+If not, and the brainstorm reveals 3+ domain-specific terms with ambiguous meanings,
+offer to create one using `references/context-glossary.md`. Update it inline during
+the session — don't batch. If it exists, cross-reference and flag conflicts:
+
+> "Your CONTEXT.md defines 'cancellation' as X, but you seem to mean Y — which is it?"
+
 ## Stop conditions
 
 Stop and ask instead of guessing when: requirements conflict, success criteria unclear, task spans multiple systems, or user hasn't approved design.
@@ -70,15 +79,17 @@ Stop and ask instead of guessing when: requirements conflict, success criteria u
 ## Workflow
 
 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`
+2. Check for existing `CONTEXT.md` at repo root
+3. Determine mode (Startup / Builder / CE)
+4. Run mode-specific questions (use reference files)
+5. Run Premise Challenge
+6. Generate 2-3 alternatives (minimal viable + ideal architecture)
+7. Validate against design checklist
+8. Offer to create/update `CONTEXT.md` if domain terms emerged
+9. Use `brainstorm_dialog` `summarize` to finalize
+10. Capture requirements in `docs/brainstorms/`
+11. Get explicit user approval
+12. Handoff to `02-plan` using `references/handoff.md`
 
 ## Artifact contract
 

package/skills/01-brainstorm/references/context-glossary.md

@@ -0,0 +1,46 @@
+# Context Glossary
+
+An optional project vocabulary file that persists domain terms across sessions.
+
+## When to create
+
+Create `CONTEXT.md` at repo root **only when** the brainstorm reveals 3+ domain-specific terms
+that have ambiguous or overloaded meanings. Skip for trivial features.
+
+## Format
+
+```md
+# {Project Name}
+
+## Language
+
+**Term**: One-sentence definition.
+_Avoid_: aliases to discourage
+
+**Term2**: One-sentence definition.
+_Avoid_: aliases to discourage
+
+## Relationships
+
+- **Term** contains many **Term2**
+
+## Example
+
+> Dev: "The materialization cascade is failing."
+> Domain expert: "You mean when a lesson gets a filesystem path?"
+> Dev: "Yes — 'materialization cascade' is our term for that flow."
+```
+
+## Rules
+
+- One definition per term, 1-2 sentences max. Define what it IS, not what it does.
+- Pick one canonical term, list alternatives as _Avoid_.
+- Only project-specific concepts — general programming terms don't belong.
+- Flag ambiguities explicitly.
+- No implementation details. This is a glossary, not a spec.
+
+## Multiple bounded contexts
+
+If the project has clearly separated domains (e.g. ordering vs billing), create a
+`CONTEXT-MAP.md` at root that lists each context and its `CONTEXT.md` location.
+Most projects need only a single root `CONTEXT.md`.

package/skills/01-brainstorm/references/requirements-template.md

@@ -23,3 +23,8 @@ Describe the chosen direction and why it is the best fit.
 ## Success criteria
 
 List the concrete outcomes that would mean this work succeeded.
+
+## Domain vocabulary
+
+List any canonical terms established during this session.
+If a `CONTEXT.md` was created or updated, link it here.

package/skills/02-plan/references/adr-template.md

@@ -0,0 +1,43 @@
+# ADR Template
+
+Lightweight Architecture Decision Records. Only create when ALL THREE are true:
+
+1. **Hard to reverse** — changing your mind later costs meaningfully
+2. **Surprising without context** — a future reader will wonder "why this way?"
+3. **Real trade-off** — genuine alternatives existed and you picked one for a reason
+
+If any is missing, skip the ADR.
+
+## File location
+
+`docs/adr/0001-slug.md`, sequential numbering. Create `docs/adr/` lazily.
+
+## Template
+
+```md
+# {Short title}
+
+{1-3 sentences: context, decision, and why.}
+```
+
+That's it. A single paragraph is fine. The value is recording THAT a decision was made and WHY.
+
+## Optional sections
+
+Only when they add genuine value:
+- **Considered Options** — when rejected alternatives are worth remembering
+- **Consequences** — when downstream effects are non-obvious
+
+## What qualifies
+
+- Architectural shape (monorepo, event-sourced, etc.)
+- Technology choices with lock-in (database, message bus, auth provider)
+- Boundary/scope decisions
+- Deliberate deviations from the obvious path
+- Constraints not visible in code (compliance, latency SLA)
+
+## What doesn't qualify
+
+- Easy-to-reverse decisions — just reverse them
+- Obvious choices — nobody will wonder why
+- No real alternative — nothing to record

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

@@ -12,6 +12,11 @@ List the relevant prior artifacts from `docs/solutions/`.
 
 Define what is in and out of scope.
 
+## Architecture decisions
+
+List any decisions that meet the ADR threshold (see `references/adr-template.md`).
+Link to `docs/adr/XXXX-slug.md` if created. If none qualify, state "No ADR-worthy decisions."
+
 ## Implementation units
 
 Break the work into execution-ready units.

package/skills/03-work/SKILL.md

@@ -46,7 +46,7 @@ When any unexpected failure occurs during execution:
 
 1. **STOP** adding features or making changes
 2. **PRESERVE** evidence (error output, repro steps)
-3. **DIAGNOSE** root cause — reproduce, localize, reduce
+3. **DIAGNOSE** root cause — follow debug discipline (`references/debug-discipline.md`): build feedback loop first, then reproduce → hypothesise → instrument → fix
 4. **FIX** the root cause, not the symptom
 5. **GUARD** with a regression test
 6. **RESUME** only after verification passes

package/skills/03-work/references/debug-discipline.md

@@ -0,0 +1,53 @@
+# Debug Discipline
+
+When stop-the-line triggers, follow this order. Skip phases only when explicitly justified.
+
+## Phase 1 — Build a feedback loop
+
+**This is the skill. Everything else is mechanical.**
+
+If you have a fast, deterministic, agent-runnable pass/fail signal, you will find the cause.
+If you don't, no amount of staring at code will save you. Spend disproportionate effort here.
+
+### Strategies (try in order)
+
+1. **Failing test** at the seam closest to the bug
+2. **CLI invocation** with fixture input, diff against known-good output
+3. **Curl/HTTP script** against running dev server
+4. **Throwaway harness** — minimal subset exercising the bug path
+5. **Bisection** — `git bisect run` between known-good and known-bad states
+
+### Iterate on the loop itself
+
+- Faster? (Skip unrelated setup, narrow scope)
+- Sharper signal? (Assert the specific symptom, not "didn't crash")
+- More deterministic? (Pin time, seed RNG, isolate filesystem)
+
+A 2-second deterministic loop is a debugging superpower.
+A 30-second flaky loop is barely better than no loop.
+
+## Phase 2 — Reproduce
+
+Confirm the loop produces the **user-described** failure, not a different nearby failure.
+
+## Phase 3 — Hypothesise
+
+Generate 3-5 ranked hypotheses. Each must be falsifiable:
+
+> "If <X> is the cause, then <Y> will make the bug disappear."
+
+Show the ranked list to the user before testing. They often have domain knowledge
+that re-ranks instantly.
+
+## Phase 4 — Instrument
+
+One probe per hypothesis. Change one variable at a time.
+
+Tag debug logs with unique prefixes (e.g. `[DEBUG-a4f2]`) so cleanup is a single grep.
+
+## Phase 5 — Fix + regression test
+
+Write regression test BEFORE the fix — but only if a correct seam exists.
+If no correct seam exists, that itself is the finding. Note it.
+
+After fix: remove all debug instrumentation (grep for tags).