@leing2021/super-pi 0.30.5 → 0.31.0

package/README.md

@@ -98,6 +98,8 @@ Configure in `.pi/settings.json`:
 
 Model and thinking level switch automatically — no manual `/model` needed.
 
+Routing triggers on explicit `/skill:` commands **and** when the agent reads a stage's `SKILL.md` on its own. If no strategy is configured, routing is a no-op — the session model is never touched. Project-level settings take precedence; missing keys fall back to global `~/.pi/agent/settings.json`.
+
 ## Design Philosophy & Acknowledgements
 
 **80% planning and review, 20% execution.**
@@ -109,12 +111,13 @@ 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) | Checkpoint resume, continuous learning loops, and token-conscious agent workflow design. |
+| [everything-claude-code (ECC)](https://github.com/affaan-m/ECC) | Checkpoint resume, continuous learning loops, and token-conscious agent workflow design. (Repo renamed; original link dead.) |
 | [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. |
+| [superpowers](https://github.com/obra/superpowers) | Strict TDD gates, design checklists, review discipline, the rationalization table (excuse → reality), 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, the knowledge-compounding backbone, and solution retirement (knowledge must be able to leave, not only accumulate). |
 | [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`), lightweight ADR (three-condition threshold + "What qualifies" catalog), feedback-loop-first debug discipline, deep-module vocabulary (module/interface/depth/seam/adapter/leverage/locality + internal seams + rejected framings), interview discipline (facts-vs-decisions, one-question-at-a-time), the review Spec axis, and the out-of-scope knowledge base. Absorbed as self-contained `skills/references/` content — no external path deps, no issue-tracker deps, no standalone skills grafted (super-pi's existing 01-brainstorm/domain-language/module-design already cover the active disciplines). |
+| [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) | The Ladder (7-rung minimalism decision chain: need-to-exist → codebase reuse → stdlib → platform-native → installed dep → one line → minimum), the `debt:` marker convention (name the ceiling and upgrade trigger), and dependency-axis review tags (`stdlib:` / `native:` / `dependency:`) flowing into the 04-review Standards axis. Embedded into `rules/common/` — no intensity tiers, no hooks/MCP, no standalone skills. |
 
 ---
 

package/extensions/ce-core/index.ts

@@ -1,7 +1,4 @@
-import { readFile } from "node:fs/promises"
-import path from "node:path"
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
-import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent"
 import { Type } from "typebox"
 import { createArtifactHelperTool, type ArtifactType } from "./tools/artifact-helper"
 import { createAskUserQuestionTool, CUSTOM_SENTINEL } from "./tools/ask-user-question"
@@ -19,14 +16,7 @@ import { createContextHandoffTool } from "./tools/context-handoff"
 import { filterBashOutput } from "./tools/bash-output-filter"
 import { filterReadOutput } from "./tools/read-output-filter"
 import { COMPACTION_FOCUS_INSTRUCTIONS } from "./tools/compaction-optimizer"
-
-const PIPELINE_STAGE_KEYS = new Set([
-  "01-brainstorm",
-  "02-plan",
-  "03-work",
-  "04-review",
-  "05-learn",
-])
+import { applyStageStrategies, parseStageSkillName, parseStageSkillPath } from "./utils/stage-routing"
 
 /**
  * Module-level promise chain that serializes interactive `ask_user_question`
@@ -92,91 +82,6 @@ function buildAskUserQuestionUi(ctx: any): import("./tools/ask-user-question").A
   return { input, select }
 }
 
-interface StrategySettings {
-  modelStrategy?: Record<string, string>
-  thinkingStrategy?: Record<string, string>
-}
-
-/**
- * Read settings from two locations (config dir honors pi's `CONFIG_DIR_NAME`,
- * which defaults to `.pi` but is user-configurable since pi 0.79.7):
- * 1. Project-level: {cwd}/{CONFIG_DIR_NAME}/settings.json (highest priority)
- * 2. Global-level: ~/{CONFIG_DIR_NAME}/agent/settings.json (fallback)
- *
- * Project-level takes precedence; global-level is used as fallback.
- */
-async function readSettings(cwd: string): Promise<StrategySettings | null> {
-  const agentHome = process.env.HOME || "~"
-  // Try project-level first
-  const projectPath = path.join(cwd, CONFIG_DIR_NAME, "settings.json")
-  try {
-    const content = await readFile(projectPath, "utf8")
-    const projectSettings = JSON.parse(content) as StrategySettings
-    // If project has modelStrategy or thinkingStrategy, use it
-    if (projectSettings.modelStrategy || projectSettings.thinkingStrategy) {
-      return projectSettings
-    }
-  } catch {
-    // Project settings not found, continue to global
-  }
-
-  // Fallback to global-level
-  const globalPath = path.join(agentHome, CONFIG_DIR_NAME, "agent", "settings.json")
-  try {
-    const content = await readFile(globalPath, "utf8")
-    return JSON.parse(content) as StrategySettings
-  } catch {
-    // Global settings not found either
-  }
-
-  // Try ~/{CONFIG_DIR_NAME}/settings.json as another fallback
-  const altGlobalPath = path.join(agentHome, CONFIG_DIR_NAME, "settings.json")
-  try {
-    const content = await readFile(altGlobalPath, "utf8")
-    return JSON.parse(content) as StrategySettings
-  } catch {
-    return null
-  }
-}
-
-function parseStageSkillName(text: string): string | null {
-  const trimmed = text.trim()
-  const match = trimmed.match(/^\/skill:([^\s]+)/)
-  if (!match) {
-    return null
-  }
-
-  const skillName = match[1]
-  return PIPELINE_STAGE_KEYS.has(skillName) ? skillName : null
-}
-
-function parseModelRef(
-  modelRef: string,
-  currentProvider?: string,
-): { provider: string, id: string } | null {
-  const trimmed = modelRef.trim()
-  if (!trimmed) {
-    return null
-  }
-
-  const slashIndex = trimmed.indexOf("/")
-  if (slashIndex > 0 && slashIndex < trimmed.length - 1) {
-    return {
-      provider: trimmed.slice(0, slashIndex),
-      id: trimmed.slice(slashIndex + 1),
-    }
-  }
-
-  if (!currentProvider) {
-    return null
-  }
-
-  return {
-    provider: currentProvider,
-    id: trimmed,
-  }
-}
-
 const artifactHelperParams = Type.Object({
   repoRoot: Type.String({ description: "Repository root where workflow artifacts should be created" }),
   artifactType: Type.Union([
@@ -360,78 +265,31 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
       return { action: "continue" as const }
     }
 
-    const settings = await readSettings(ctx.cwd)
-    const modelStrategy = settings?.modelStrategy
-    const thinkingStrategy = settings?.thinkingStrategy
-    // Notification guard: only notify in interactive (TUI) or RPC modes.
-    // For interactive input capability checks (askUserQuestion), use ctx.hasUI directly.
-    const shouldNotify = ctx.mode === "tui" || ctx.mode === "rpc"
-
-    // Model switching
-    if (modelStrategy) {
-      const targetModelRef = modelStrategy[stageKey] ?? modelStrategy.default
-      if (targetModelRef) {
-        const parsed = parseModelRef(targetModelRef, ctx.model?.provider)
-        if (parsed) {
-          // Skip if already using the same model
-          if (ctx.model?.provider !== parsed.provider || ctx.model?.id !== parsed.id) {
-            const model = ctx.modelRegistry.find(parsed.provider, parsed.id)
-            if (model) {
-              const switched = await pi.setModel(model)
-              if (switched) {
-                if (shouldNotify) {
-                  ctx.ui.notify(`Switched model for ${stageKey}: ${model.provider}/${model.id}`, "info")
-                }
-              } else {
-                if (shouldNotify) {
-                  ctx.ui.notify(`No API key for ${stageKey}: ${model.provider}/${model.id}`, "warning")
-                }
-              }
-            } else if (shouldNotify) {
-              ctx.ui.notify(`Model not found for ${stageKey}: ${targetModelRef}`, "warning")
-            }
-          }
-        } else if (shouldNotify) {
-          ctx.ui.notify(`Invalid modelStrategy for ${stageKey}: ${targetModelRef}`, "warning")
-        }
-      }
-    }
-
-    // Thinking level switching
-    if (thinkingStrategy) {
-      const targetThinking = thinkingStrategy[stageKey] ?? thinkingStrategy.default
-      if (targetThinking) {
-        const levelMap: Record<string, ReturnType<ExtensionAPI["getThinkingLevel"]>> = {
-          off: "off",
-          minimal: "minimal",
-          low: "low",
-          medium: "medium",
-          high: "high",
-          xhigh: "xhigh",
-          max: "max",
-          "0": "low",
-          "1": "medium",
-          "2": "high",
-        }
-        const rawThinking = targetThinking.toLowerCase()
-        const knownLevel = levelMap[rawThinking]
-        const normalized = knownLevel ?? "medium"
-        if (!knownLevel && shouldNotify) {
-          ctx.ui.notify(`Unknown thinking level for ${stageKey}: ${targetThinking}, falling back to medium`, "warning")
-        }
-        const currentLevel = pi.getThinkingLevel()
-        if (currentLevel !== normalized) {
-          pi.setThinkingLevel(normalized)
-          if (shouldNotify) {
-            ctx.ui.notify(`Switched thinking level for ${stageKey}: ${normalized}`, "info")
-          }
-        }
-      }
-    }
+    await applyStageStrategies(pi, ctx, stageKey)
 
     return { action: "continue" as const }
   })
 
+  // Model-initiated skill invocation: when the agent reads a pipeline
+  // stage's SKILL.md (instead of the user typing /skill:), route the
+  // stage's model/thinking strategies the same way. Reads of other paths
+  // are untouched.
+  pi.on("tool_call", async (event, ctx) => {
+    if (event.toolName !== "read") {
+      return undefined
+    }
+    const filePath = (event.input as { path?: unknown } | undefined)?.path
+    if (typeof filePath !== "string") {
+      return undefined
+    }
+    const stageKey = parseStageSkillPath(filePath)
+    if (!stageKey) {
+      return undefined
+    }
+    await applyStageStrategies(pi, ctx, stageKey)
+    return undefined
+  })
+
   const artifactHelper = createArtifactHelperTool()
   const askUserQuestion = createAskUserQuestionTool()
   const workflowState = createWorkflowStateTool()

package/extensions/ce-core/utils/stage-routing.ts

@@ -0,0 +1,230 @@
+import { readFile } from "node:fs/promises"
+import path from "node:path"
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
+import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent"
+
+export const PIPELINE_STAGE_KEYS = new Set([
+  "01-brainstorm",
+  "02-plan",
+  "03-work",
+  "04-review",
+  "05-learn",
+  "06-next",
+  "07-worktree",
+])
+
+interface StrategySettings {
+  modelStrategy?: Record<string, string>
+  thinkingStrategy?: Record<string, string>
+}
+
+/**
+ * Structural subset of the extension context used by stage routing.
+ * Keeps the routing helpers testable without full ExtensionContext mocks.
+ */
+interface StageRoutingContext {
+  cwd: string
+  mode?: string
+  hasUI?: boolean
+  model?: { provider?: string, id?: string }
+  modelRegistry?: { find(provider: string, id: string): unknown }
+  ui?: { notify(message: string, level?: string): void }
+}
+
+/**
+ * Model/thinking strategies only matter where the user can see the switch
+ * notification; silent hosts would swallow failures.
+ */
+function shouldNotifyRouting(ctx: StageRoutingContext): boolean {
+  return ctx.mode === "tui" || ctx.mode === "rpc"
+}
+
+async function applyModelStrategy(
+  pi: ExtensionAPI,
+  ctx: StageRoutingContext,
+  stageKey: string,
+  strategy: Record<string, string> | undefined,
+): Promise<void> {
+  if (!strategy) {
+    return
+  }
+  const notify = (message: string, level: "info" | "warning") => {
+    if (shouldNotifyRouting(ctx)) {
+      ctx.ui?.notify(message, level)
+    }
+  }
+
+  const targetModelRef = strategy[stageKey] ?? strategy.default
+  if (!targetModelRef) {
+    return
+  }
+  const parsed = parseModelRef(targetModelRef, ctx.model?.provider)
+  if (!parsed) {
+    notify(`Invalid modelStrategy for ${stageKey}: ${targetModelRef}`, "warning")
+    return
+  }
+  // Skip if already using the same model (idempotent re-reads).
+  if (ctx.model?.provider === parsed.provider && ctx.model?.id === parsed.id) {
+    return
+  }
+  const model = ctx.modelRegistry?.find(parsed.provider, parsed.id)
+  if (!model) {
+    notify(`Model not found for ${stageKey}: ${targetModelRef}`, "warning")
+    return
+  }
+  const switched = await pi.setModel(model as Parameters<ExtensionAPI["setModel"]>[0])
+  if (switched) {
+    notify(`Switched model for ${stageKey}: ${parsed.provider}/${parsed.id}`, "info")
+  } else {
+    notify(`No API key for ${stageKey}: ${parsed.provider}/${parsed.id}`, "warning")
+  }
+}
+
+function applyThinkingStrategy(
+  pi: ExtensionAPI,
+  ctx: StageRoutingContext,
+  stageKey: string,
+  strategy: Record<string, string> | undefined,
+): void {
+  if (!strategy) {
+    return
+  }
+  const targetThinking = strategy[stageKey] ?? strategy.default
+  if (!targetThinking) {
+    return
+  }
+  const levelMap: Record<string, ReturnType<ExtensionAPI["getThinkingLevel"]>> = {
+    off: "off",
+    minimal: "minimal",
+    low: "low",
+    medium: "medium",
+    high: "high",
+    xhigh: "xhigh",
+    max: "max",
+    "0": "low",
+    "1": "medium",
+    "2": "high",
+  }
+  const rawThinking = targetThinking.toLowerCase()
+  const knownLevel = levelMap[rawThinking]
+  const normalized = knownLevel ?? "medium"
+  if (!knownLevel && shouldNotifyRouting(ctx)) {
+    ctx.ui?.notify(`Unknown thinking level for ${stageKey}: ${targetThinking}, falling back to medium`, "warning")
+  }
+  if (pi.getThinkingLevel() !== normalized) {
+    pi.setThinkingLevel(normalized)
+    if (shouldNotifyRouting(ctx)) {
+      ctx.ui?.notify(`Switched thinking level for ${stageKey}: ${normalized}`, "info")
+    }
+  }
+}
+
+/**
+ * Apply model + thinking strategies for a pipeline stage. Shared by the
+ * `input` hook (explicit `/skill:` commands) and the `tool_call` hook
+ * (model-initiated SKILL.md reads).
+ */
+export async function applyStageStrategies(
+  pi: ExtensionAPI,
+  ctx: StageRoutingContext,
+  stageKey: string,
+): Promise<void> {
+  const settings = await readSettings(ctx.cwd)
+  await applyModelStrategy(pi, ctx, stageKey, settings?.modelStrategy)
+  applyThinkingStrategy(pi, ctx, stageKey, settings?.thinkingStrategy)
+}
+
+/**
+ * Read settings from two locations (config dir honors pi's `CONFIG_DIR_NAME`,
+ * which defaults to `.pi` but is user-configurable since pi 0.79.7):
+ * 1. Project-level: {cwd}/{CONFIG_DIR_NAME}/settings.json (highest priority)
+ * 2. Global-level: ~/{CONFIG_DIR_NAME}/agent/settings.json (fallback)
+ *
+ * Project-level takes precedence; global-level is used as fallback.
+ */
+async function readSettings(cwd: string): Promise<StrategySettings | null> {
+  const agentHome = process.env.HOME || "~"
+  // Try project-level first
+  const projectPath = path.join(cwd, CONFIG_DIR_NAME, "settings.json")
+  try {
+    const content = await readFile(projectPath, "utf8")
+    const projectSettings = JSON.parse(content) as StrategySettings
+    // If project has modelStrategy or thinkingStrategy, use it
+    if (projectSettings.modelStrategy || projectSettings.thinkingStrategy) {
+      return projectSettings
+    }
+  } catch {
+    // Project settings not found, continue to global
+  }
+
+  // Fallback to global-level
+  const globalPath = path.join(agentHome, CONFIG_DIR_NAME, "agent", "settings.json")
+  try {
+    const content = await readFile(globalPath, "utf8")
+    return JSON.parse(content) as StrategySettings
+  } catch {
+    // Global settings not found either
+  }
+
+  // Try ~/{CONFIG_DIR_NAME}/settings.json as another fallback
+  const altGlobalPath = path.join(agentHome, CONFIG_DIR_NAME, "settings.json")
+  try {
+    const content = await readFile(altGlobalPath, "utf8")
+    return JSON.parse(content) as StrategySettings
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Detect a pipeline stage SKILL.md path, e.g.
+ * `.../skills/03-work/SKILL.md`. Returns the stage key or null.
+ */
+export function parseStageSkillPath(filePath: string): string | null {
+  // Accept absolute paths, `./`-prefixed, and bare relative paths like
+  // `skills/03-work/SKILL.md` (the read tool allows relative paths).
+  const match = filePath.match(/(?:^|[\\/])skills[\\/]([^\\/]+)[\\/]SKILL\.md$/)
+  if (!match) {
+    return null
+  }
+  const stageKey = match[1]
+  return PIPELINE_STAGE_KEYS.has(stageKey) ? stageKey : null
+}
+
+export function parseStageSkillName(text: string): string | null {
+  const trimmed = text.trim()
+  const match = trimmed.match(/^\/skill:([^\s]+)/)
+  if (!match) {
+    return null
+  }
+
+  const skillName = match[1]
+  return PIPELINE_STAGE_KEYS.has(skillName) ? skillName : null
+}
+
+function parseModelRef(
+  modelRef: string,
+  currentProvider?: string,
+): { provider: string, id: string } | null {
+  const trimmed = modelRef.trim()
+  if (!trimmed) {
+    return null
+  }
+
+  const slashIndex = trimmed.indexOf("/")
+  if (slashIndex > 0 && slashIndex < trimmed.length - 1) {
+    return {
+      provider: trimmed.slice(0, slashIndex),
+      id: trimmed.slice(slashIndex + 1),
+    }
+  }
+
+  if (!currentProvider) {
+    return null
+  }
+
+  return {
+    provider: currentProvider,
+    id: trimmed,
+  }
+}

package/package.json

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

package/skills/03-work/SKILL.md

@@ -55,6 +55,15 @@ Anti-rationalization — when a gate fails or evidence is missing:
 - Stop, report the blocker with evidence, and either fix the root cause or ask for direction.
 - Do not continue unrelated implementation after failed verification.
 
+Common rationalizations and their reality:
+
+| Excuse | Reality |
+|--------|---------|
+| "Close enough — the gate almost passed" | A failed gate means not done. Fix it or stop and report; those are the only exits. |
+| "One more retry will converge" | Past the 3-failure cap, retries do not converge — the failure is structural. Ask for direction. |
+| "The fix is tiny, skip re-verification" | Unverified fixes are how regressions land. Every fix ends with verification. |
+| "This failure is a special case" | No evidence, no exception. Treat it like every other failure. |
+
 This is a hard gate — do not push past a failing test or broken build to continue implementation. Errors compound.
 
 ## Error compaction after recovery

package/skills/05-learn/SKILL.md

@@ -37,7 +37,7 @@ See [shared pipeline instructions](../references/pipeline-config.md) for model r
 - Every solution MUST include YAML frontmatter per `references/solution-schema.yaml` (title, category, severity, tags, applies_when).
 - Use `references/category-map.md` to map the problem to the correct solution category.
 - Check for overlap with nearby solution docs before creating a new artifact.
-- Use `references/overlap-rules.md` to decide whether to create, update, or consolidate.
+- Use `references/overlap-rules.md` to decide whether to create, update, consolidate, or retire.
 - Use **`pattern_extractor`** to identify recurring patterns across existing artifacts before writing a new solution.
 - Structure the document with `assets/solution-template.md`.
 - Determine storage level:

package/skills/05-learn/references/overlap-rules.md

@@ -5,3 +5,13 @@ Use these overlap levels when deciding whether to create a new solution doc or u
 - **High** — same problem, same root cause, and same solution approach. Update the existing doc.
 - **Moderate** — related problem area but a different angle or solution. Create a new doc and cross-link it.
 - **Low** — only loosely related. Create a distinct doc.
+
+## Retirement
+
+When an existing solution is discovered stale — the described code/API no longer exists, or the fix has been superseded:
+
+- **Superseded** — fold into the replacing solution (keep the old tags searchable there) and delete the old one.
+- **Dead reference** — delete. Git is the archive; no tombstones.
+- **Scope narrowed** — update `applies_when` instead of deleting.
+
+Never leave an artifact describing code that no longer exists — stale solutions pollute every future search.

package/skills/references/pipeline-config.md

@@ -4,8 +4,12 @@ Use these rules in all Phase 1 skills: `01-brainstorm` → `02-plan` → `03-wor
 
 ## Start of skill: model routing
 
-Model routing is handled automatically by the ce-core extension's `input` hook.
-When a user types `/skill:01-brainstorm` through `/skill:05-learn`, the extension:
+Model routing is handled automatically by the ce-core extension, with two triggers:
+
+1. **Explicit command**: the user types `/skill:01-brainstorm` through `/skill:07-worktree` (the `input` hook).
+2. **Model-initiated skill load**: the agent reads a stage's `SKILL.md` (e.g. `.../skills/03-work/SKILL.md`) without an explicit command (the `tool_call` hook).
+
+On either trigger the extension:
 
 1. Reads `.pi/settings.json` from the project root.
 2. Parses `modelStrategy[stageKey]` or falls back to `modelStrategy.default`.