@leing2021/super-pi 0.14.0

package/extensions/ce-core/tools/worktree-manager.ts

@@ -0,0 +1,131 @@
+import path from "node:path"
+
+export type GitRunner = (args: string[]) => Promise<string>
+
+export interface WorktreeManagerInput {
+  operation: "create" | "detect" | "merge" | "cleanup"
+  repoRoot: string
+  branchName?: string
+  worktreePath?: string
+}
+
+export interface WorktreeManagerResult {
+  operation: string
+  worktreePath?: string
+  isWorktree?: boolean
+  merged?: boolean
+  cleanedUp?: boolean
+}
+
+export function createWorktreeManagerTool() {
+  return {
+    name: "worktree_manager",
+    async execute(
+      input: WorktreeManagerInput,
+      runner: GitRunner,
+    ): Promise<WorktreeManagerResult> {
+      switch (input.operation) {
+        case "create":
+          return createWorktree(input, runner)
+        case "detect":
+          return detectWorktree(input, runner)
+        case "merge":
+          return mergeWorktree(input, runner)
+        case "cleanup":
+          return cleanupWorktree(input, runner)
+        default:
+          throw new Error(`Unknown operation: ${input.operation}`)
+      }
+    },
+  }
+}
+
+async function createWorktree(
+  input: WorktreeManagerInput,
+  runner: GitRunner,
+): Promise<WorktreeManagerResult> {
+  const branchName = required(input.branchName, "branchName")
+  const worktreeDir = `${path.basename(input.repoRoot)}-${normalizeBranchSlug(branchName)}`
+  const worktreePath = path.join(path.dirname(input.repoRoot), worktreeDir)
+
+  await runner(["git", "branch", branchName])
+  await runner(["git", "worktree", "add", worktreePath, branchName])
+
+  return {
+    operation: "create",
+    worktreePath,
+  }
+}
+
+async function detectWorktree(
+  input: WorktreeManagerInput,
+  runner: GitRunner,
+): Promise<WorktreeManagerResult> {
+  const output = await runner(["git", "worktree", "list"])
+  const lines = output.trim().split("\n")
+
+  if (lines.length <= 1) {
+    return { operation: "detect", isWorktree: false }
+  }
+
+  // Find a worktree that is not the main one
+  const mainLine = lines[0]
+  const worktreeLine = lines.find(
+    (line) => line !== mainLine && line.includes(input.repoRoot),
+  )
+
+  if (worktreeLine) {
+    const worktreePath = worktreeLine.split(/\s+/)[0]
+    return { operation: "detect", isWorktree: true, worktreePath }
+  }
+
+  // Check if any secondary worktree exists
+  const secondaryLine = lines.find((line) => line !== mainLine)
+  if (secondaryLine) {
+    const worktreePath = secondaryLine.split(/\s+/)[0]
+    return { operation: "detect", isWorktree: true, worktreePath }
+  }
+
+  return { operation: "detect", isWorktree: false }
+}
+
+async function mergeWorktree(
+  input: WorktreeManagerInput,
+  runner: GitRunner,
+): Promise<WorktreeManagerResult> {
+  const branchName = required(input.branchName, "branchName")
+
+  await runner(["git", "checkout", "main"])
+  await runner(["git", "merge", branchName])
+
+  return { operation: "merge", merged: true }
+}
+
+async function cleanupWorktree(
+  input: WorktreeManagerInput,
+  runner: GitRunner,
+): Promise<WorktreeManagerResult> {
+  const branchName = required(input.branchName, "branchName")
+  const worktreePath = required(input.worktreePath, "worktreePath")
+
+  await runner(["git", "worktree", "remove", worktreePath])
+  await runner(["git", "branch", "-d", branchName])
+
+  return { operation: "cleanup", cleanedUp: true }
+}
+
+function required(value: string | undefined, field: string): string {
+  if (!value) {
+    throw new Error(`worktree_manager requires ${field}`)
+  }
+  return value
+}
+
+function normalizeBranchSlug(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "")
+}

package/extensions/ce-core/utils/artifact-paths.ts

@@ -0,0 +1,23 @@
+import path from "node:path"
+import { normalizeSlug } from "./name-utils"
+
+export function getBrainstormArtifactPath(repoRoot: string, date: string, topic: string): string {
+  return path.join(repoRoot, "docs", "brainstorms", `${date}-${normalizeSlug(topic)}-requirements.md`)
+}
+
+export function getPlanArtifactPath(repoRoot: string, date: string, topic: string): string {
+  return path.join(repoRoot, "docs", "plans", `${date}-${normalizeSlug(topic)}-plan.md`)
+}
+
+export function getSolutionArtifactPath(
+  repoRoot: string,
+  category: string,
+  topic: string,
+  date: string,
+): string {
+  return path.join(repoRoot, "docs", "solutions", normalizeSlug(category), `${date}-${normalizeSlug(topic)}.md`)
+}
+
+export function getRunArtifactPath(repoRoot: string, skillName: string, runId: string): string {
+  return path.join(repoRoot, ".context", "compound-engineering", normalizeSlug(skillName), runId)
+}

package/extensions/ce-core/utils/name-utils.ts

@@ -0,0 +1,8 @@
+export function normalizeSlug(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "")
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@leing2021/super-pi",
+  "version": "0.14.0",
+  "private": false,
+  "type": "module",
+  "description": "Pi-native Compound Engineering package for iterative development workflows",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leing2021/super-pi.git"
+  },
+  "homepage": "https://github.com/leing2021/super-pi",
+  "bugs": {
+    "url": "https://github.com/leing2021/super-pi/issues"
+  },
+  "keywords": [
+    "@leing2021/super-pi",
+    "pi-package",
+    "pi",
+    "super-pi",
+    "coding-agent",
+    "compound-engineering"
+  ],
+  "files": [
+    "skills",
+    "extensions",
+    "README.md",
+    "package.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@sinclair/typebox": "*"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "0.67.6",
+    "@sinclair/typebox": "0.34.41",
+    "bun-types": "^1.3.12"
+  },
+  "pi": {
+    "skills": [
+      "./skills"
+    ],
+    "extensions": [
+      "./extensions"
+    ]
+  }
+}

package/skills/01-brainstorm/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: 01-brainstorm
+description: "Brainstorm requirements with three modes: CE discovery, Startup Diagnostic, Builder Mode."
+---
+
+# Brainstorm
+
+Use this skill when the request is ambiguous, needs requirements discovery before planning, or the user describes a new idea/product.
+
+## 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.
+- 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.
+
+## Mode selection
+
+After initial context gathering, determine which mode to use. Use `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
+
+**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.
+
+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.
+
+## CE Brainstorm mode (existing flow)
+
+This is the original Compound Engineering brainstorm. Use when adding a feature to an existing project.
+
+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.
+
+## Premise Challenge (all modes)
+
+After the mode-specific questions are complete, run the 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?
+- 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
+
+## 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.
+
+## 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`.
+
+## 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.

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

@@ -0,0 +1,39 @@
+# Builder Mode
+
+Design thinking brainstorming for side projects, hackathons, learning, open source, and creative outlets. Use when the user is building for fun, learning, hacking, or exploring.
+
+## Operating principles
+
+1. **Delight is the currency.** What makes someone say "whoa"?
+2. **Ship something you can show people.** The best version of anything is the one that exists.
+3. **The best side projects solve your own problem.** If you're building it for yourself, trust that instinct.
+4. **Explore before you optimize.** Try the weird idea first. Polish later.
+
+## Response posture
+
+- **Enthusiastic, opinionated collaborator.** You're here to help them build the coolest thing possible. Riff on their ideas. Get excited about what's exciting.
+- **Help them find the most exciting version of their idea.** Don't settle for the obvious version.
+- **Suggest cool things they might not have thought of.** Bring adjacent ideas, unexpected combinations, "what if you also..." suggestions.
+- **End with concrete build steps, not business validation tasks.** The deliverable is "what to build next," not "who to interview."
+
+## Generative questions
+
+Ask these **ONE AT A TIME** via `ask_user_question`. The goal is to brainstorm and sharpen the idea, not interrogate.
+
+- **What's the coolest version of this?** What would make it genuinely delightful?
+- **Who would you show this to?** What would make them say "whoa"?
+- **What's the fastest path to something you can actually use or share?**
+- **What existing thing is closest to this, and how is yours different?**
+- **What would you add if you had unlimited time?** What's the 10x version?
+
+**Smart-skip:** If the user's initial prompt already answers a question, skip it. Only ask questions whose answers aren't yet clear.
+
+**STOP** after each question. Wait for the response before asking the next.
+
+## Escape hatch
+
+If the user says "just do it" or provides a fully formed plan: fast-track to Premise Challenge and Alternatives Generation.
+
+## Vibe shift detection
+
+If the user starts saying things like "actually I think this could be a real company" or mentions customers, revenue, or fundraising: upgrade to Startup Diagnostic mode naturally. Say: "Okay, now we're talking. Let me ask you some harder questions." Then switch to the Startup Diagnostic questions.

package/skills/01-brainstorm/references/handoff.md

@@ -0,0 +1,8 @@
+# Handoff from 01-brainstorm
+
+When the requirements artifact is ready:
+
+1. Report the artifact path under `docs/brainstorms/`.
+2. Summarize the recommended direction in 2-3 bullets.
+3. Recommend `02-plan` as the next step.
+4. If key ambiguity remains, say so before handing off.

package/skills/01-brainstorm/references/premise-challenge.md

@@ -0,0 +1,23 @@
+# Premise Challenge
+
+Before proposing solutions, challenge the premises. Run this after the diagnostic questions (Startup or Builder) and before Alternatives Generation.
+
+## Steps
+
+1. **Is this the right problem?** Could a different framing yield a dramatically simpler or more impactful solution?
+2. **What happens if we do nothing?** Real pain point or hypothetical one?
+3. **What existing code already partially solves this?** Map existing patterns, utilities, and flows that could be reused.
+4. **If the deliverable is a new artifact** (CLI binary, library, package, container image, mobile app): **how will users get it?** Code without distribution is code nobody can use.
+
+## Output format
+
+Present premises as clear statements the user must agree with before proceeding:
+
+```
+PREMISES:
+1. [statement] — agree/disagree?
+2. [statement] — agree/disagree?
+3. [statement] — agree/disagree?
+```
+
+Use `ask_user_question` to confirm each premise. If the user disagrees, revise understanding and loop back.

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

@@ -0,0 +1,25 @@
+# Requirements
+
+## Problem
+
+Describe the user or product problem being solved.
+
+## Goals
+
+List the primary outcomes this work should achieve.
+
+## Non-goals
+
+List what this brainstorm intentionally does not cover.
+
+## Approach options
+
+Compare 2-3 approaches with tradeoffs.
+
+## Recommended direction
+
+Describe the chosen direction and why it is the best fit.
+
+## Success criteria
+
+List the concrete outcomes that would mean this work succeeded.

package/skills/01-brainstorm/references/startup-diagnostic.md

@@ -0,0 +1,108 @@
+# Startup Diagnostic
+
+The YC-style forcing questions. Use these when the user is building a startup or doing intrapreneurship.
+
+## Smart routing by product stage
+
+| Stage | Questions to ask |
+|-------|-----------------|
+| Pre-product (idea stage) | Q1, Q2, Q3 |
+| Has users (not yet paying) | Q2, Q4, Q5 |
+| Has paying customers | Q4, Q5, Q6 |
+| Pure engineering/infra | Q2, Q4 only |
+
+## The six forcing questions
+
+Ask these **ONE AT A TIME** via `ask_user_question`. Push on each one until the answer is specific and uncomfortable. Comfort means the founder hasn't gone deep enough.
+
+### Q1: Demand Reality
+
+**Ask:** "What's the strongest evidence you have that someone actually wants this? Not 'is interested,' not 'signed up for a waitlist,' but would be genuinely upset if it disappeared tomorrow?"
+
+**Push until you hear:** Specific behavior. Someone paying. Someone expanding usage. Someone building their workflow around it. Someone who would have to scramble if you vanished.
+
+**Red flags:** "People say it's interesting." "We got 500 waitlist signups." "VCs are excited about the space." None of these are demand.
+
+### Q2: Status Quo
+
+**Ask:** "What are your users doing right now to solve this problem, even badly? What does that workaround cost them?"
+
+**Push until you hear:** A specific workflow. Hours spent. Dollars wasted. Tools duct-taped together. People hired to do it manually.
+
+**Red flags:** "Nothing. There's no solution, that's why the opportunity is so big." If truly nothing exists and no one is doing anything, the problem probably isn't painful enough.
+
+### Q3: Desperate Specificity
+
+**Ask:** "Name the actual human who needs this most. What's their title? What gets them promoted? What gets them fired? What keeps them up at night?"
+
+**Push until you hear:** A name. A role. A specific consequence they face if the problem isn't solved.
+
+**Red flags:** Category-level answers. "Healthcare enterprises." "SMBs." "Marketing teams." You can't email a category.
+
+### Q4: Narrowest Wedge
+
+**Ask:** "What's the smallest possible version of this that someone would pay real money for, this week, not after you build the platform?"
+
+**Push until you hear:** One feature. One workflow. Maybe something as simple as a weekly email or a single automation. Something they could ship in days, not months, that someone would pay for.
+
+**Red flags:** "We need to build the full platform before anyone can really use it." "We could strip it down but then it wouldn't be differentiated."
+
+**Bonus push:** "What if the user didn't have to do anything at all to get value? No login, no integration, no setup. What would that look like?"
+
+### Q5: Observation and Surprise
+
+**Ask:** "Have you actually sat down and watched someone use this without helping them? What did they do that surprised you?"
+
+**Push until you hear:** A specific surprise. Something the user did that contradicted assumptions.
+
+**Red flags:** "We sent out a survey." "We did some demo calls." "Nothing surprising, it's going as expected." Surveys lie. Demos are theater.
+
+**The gold:** Users doing something the product wasn't designed for. That's often the real product trying to emerge.
+
+### Q6: Future-Fit
+
+**Ask:** "If the world looks meaningfully different in 3 years, and it will, does your product become more essential or less?"
+
+**Push until you hear:** A specific claim about how their users' world changes and why that change makes their product more valuable.
+
+**Red flags:** "The market is growing 20% per year." Growth rate is not a vision. "AI will make everything better." That's not a product thesis.
+
+## Response posture
+
+- **Be direct to the point of discomfort.** Comfort means you haven't pushed hard enough. Your job is diagnosis, not encouragement.
+- **Push once, then push again.** The first answer is usually the polished version. The real answer comes after the second or third push.
+- **Name common failure patterns:** "solution in search of a problem," "hypothetical users," "waiting to launch until it's perfect," "assuming interest equals demand." Name them directly.
+- **End with the assignment.** Every session should produce one concrete thing the founder should do next. Not a strategy, an action.
+
+## Anti-sycophancy rules
+
+**Never say these during the diagnostic:**
+- "That's an interesting approach" (take a position instead)
+- "There are many ways to think about this" (pick one)
+- "You might want to consider..." (say "This is wrong because..." or "This works because...")
+- "That could work" (say whether it WILL work based on evidence)
+
+**Always:**
+- Take a position on every answer. State your position AND what evidence would change it.
+- Challenge the strongest version of the claim, not a strawman.
+
+## Pushback patterns
+
+**Vague market, force specificity:**
+- BAD: "That's a big market! Let's explore what kind of tool."
+- GOOD: "There are 10,000 AI developer tools right now. What specific task does a specific developer currently waste 2+ hours/week on that your tool eliminates? Name the person."
+
+**Social proof, demand test:**
+- BAD: "That's encouraging! Who specifically have you talked to?"
+- GOOD: "Loving an idea is free. Has anyone offered to pay? Has anyone asked when it ships? Love is not demand."
+
+**Platform vision, wedge challenge:**
+- BAD: "What would a stripped-down version look like?"
+- GOOD: "That's a red flag. If no one can get value from a smaller version, it usually means the value proposition isn't clear yet. What's the one thing a user would pay for this week?"
+
+## Escape hatch
+
+If the user says "just do it" or expresses impatience:
+- Say: "The hard questions are the value. Skipping them is like skipping the exam and going straight to the prescription. Let me ask two more, then we'll move."
+- Ask the 2 most critical remaining questions, then proceed to Premise Challenge.
+- If the user pushes back a second time, respect it. Proceed immediately.

package/skills/02-plan/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: 02-plan
+description: "Turn requirements into a plan. Optional CEO-style strategic review after."
+---
+
+# Plan
+
+Use this skill when requirements are ready to become an execution-ready plan.
+
+## Core rules
+
+- 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.
+
+## 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.
+
+**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
+
+## 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.
+
+## 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