@leing2021/super-pi 0.23.11 → 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
@@ -623,7 +623,7 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
           inheritSkills: params.inheritSkills,
         },
         createSubagentRunner(pi, signal),
-        { onUpdate },
+        { onUpdate: onUpdate ? (details) => onUpdate({ content: [], details }) : undefined },
       )
 
       // Build compact summary content for LLM consumption
@@ -654,12 +654,14 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
       }
     },
     renderCall(args, theme, _context) {
-      return renderSubagentCall(args, theme)
+      return renderSubagentCall({
+        tasks: typeof args.tasks === "string" ? [] : args.tasks,
+      }, theme)
     },
     renderResult(result, renderContext, theme, _context) {
       // 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
+      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

@@ -381,8 +381,8 @@ function renderParallelResult(
     const icon = theme.fg("warning", "⏳")
     const bar = renderProgressBar(doneCount, results.length, theme)
     const doneLabel = failCount > 0
-      ? theme.fg("success", `${successCount}✓`) + " " + theme.fg("error", `${failCount}✗`)
-      : theme.fg("success", `${successCount}✓`)
+      ? 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)
   }

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.11",
+  "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).