@c0x12c/ai-toolkit 1.15.0

package/commands/spartan/onboard.md

@@ -0,0 +1,326 @@
+---
+name: spartan:onboard
+description: "Understand a new codebase — scan, map architecture, set up rules, and get ready to build"
+argument-hint: ""
+preamble-tier: 4
+---
+
+# Onboard to This Codebase
+
+You are the **Onboard workflow leader** — go from "I just joined" to "I'm ready to build."
+
+You handle scanning, mapping, and setup in one flow. Don't tell the user to run separate commands.
+
+```
+PIPELINE:
+
+  Check Context → Scan → Map → Setup → Save to Memory
+       │            │       │      │          │
+   .memory/      Gate 1  Gate 2  Gate 3    auto-save
+   prior sessions
+```
+
+---
+
+## Step 0: Check Context (silent)
+
+Before scanning from scratch, check if someone already did this work.
+
+```bash
+# Check for existing memory/knowledge
+ls .memory/index.md .memory/knowledge/ 2>/dev/null
+
+# Check for existing CLAUDE.md
+ls CLAUDE.md 2>/dev/null
+
+# Check for prior onboarding
+ls .handoff/*.md 2>/dev/null
+```
+
+**If `.memory/` has knowledge files**, read them. Someone already captured context:
+> "Found existing project knowledge in `.memory/`. Reading it before scanning."
+
+**If CLAUDE.md exists**, read it first. Build on top of it, don't start over.
+
+---
+
+## Stage 1: Scan
+
+**Goal:** Understand what this project is at a surface level.
+
+### Check project basics
+```bash
+# What's in the root?
+ls -la
+
+# Package/build files
+ls build.gradle.kts settings.gradle.kts pom.xml 2>/dev/null
+ls package.json tsconfig.json next.config.* 2>/dev/null
+ls Dockerfile docker-compose.yml 2>/dev/null
+ls Makefile 2>/dev/null
+
+# Existing docs
+ls CLAUDE.md README.md CONTRIBUTING.md 2>/dev/null
+ls .planning/ .memory/ .handoff/ 2>/dev/null
+
+# Git info
+git log --oneline -20
+git shortlog -sn --no-merges | head -10
+git branch -a | head -20
+```
+
+### Classify the project
+
+| Signal | Meaning |
+|--------|---------|
+| `build.gradle.kts` + `src/main/kotlin/` | Kotlin/Micronaut backend |
+| `package.json` + `next.config.*` | Next.js/React frontend |
+| Both | Full-stack monorepo |
+| `docker-compose.yml` with multiple services | Microservices |
+| Already has `CLAUDE.md` | Someone set this up before — read it |
+| Has `.planning/` | GSD project — check status |
+
+### Produce a quick summary
+
+```markdown
+## Project Scan
+
+**Name:** [from package.json, settings.gradle, or folder name]
+**Stack:** [what you detected]
+**Size:** [file count, line count estimate]
+**Team:** [from git shortlog — who contributes most]
+**Activity:** [last commit date, commit frequency]
+**Existing docs:** [what exists already]
+**Tests:** [test framework, rough coverage indicator]
+```
+
+**GATE 1 — STOP and ask:**
+> "Here's what I see: [summary]. Does this match your understanding? Anything I should know that's not in the code?"
+
+---
+
+## Stage 2: Map
+
+**Goal:** Understand how the pieces fit together. Build a mental model.
+
+### Agent Teams boost (if enabled)
+
+```bash
+echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not_set}"
+```
+
+**If Agent Teams is enabled AND the codebase is large (50+ files or multi-module):**
+
+Run a parallel mapping team for faster analysis:
+
+```
+TeamCreate(team_name: "onboard-{project-slug}", description: "Mapping codebase for onboarding")
+
+TaskCreate(subject: "Map tech stack", description: "Languages, frameworks, dependencies, build tools, runtime")
+TaskCreate(subject: "Map architecture", description: "Patterns, layers, data flow, entry points, error handling")
+TaskCreate(subject: "Map quality", description: "Conventions, test patterns, code quality concerns")
+
+Agent(
+  team_name: "onboard-{project-slug}",
+  name: "stack-mapper",
+  subagent_type: "Explore",
+  prompt: "Map the tech stack: languages, frameworks, dependencies, build tools, runtime.
+    Write findings as structured markdown. Check TaskList, claim your task."
+)
+
+Agent(
+  team_name: "onboard-{project-slug}",
+  name: "arch-mapper",
+  subagent_type: "Explore",
+  prompt: "Map architecture: patterns, layers, data flow, entry points, error handling.
+    Trace one typical request end-to-end. Check TaskList, claim your task."
+)
+
+Agent(
+  team_name: "onboard-{project-slug}",
+  name: "quality-mapper",
+  subagent_type: "Explore",
+  prompt: "Map conventions, test patterns, code quality concerns. Find TODOs, tech debt.
+    Check TaskList, claim your task."
+)
+```
+
+After all teammates report back, synthesize into the architecture overview below, then `TeamDelete()`.
+
+**If Agent Teams is NOT enabled (or codebase is small)**, map manually:
+
+### Architecture mapping
+
+Use the approach from `/spartan:map-codebase` internally:
+- Identify the main modules/packages
+- Trace a request from entry point to response (for backends) or from page load to render (for frontends)
+- Find the data model (entities, schemas, types)
+- Identify external dependencies (databases, APIs, message queues)
+
+### For backend projects
+```
+Request flow:
+  Client → Controller → Manager/Service → Repository → Database
+                     ↘ External APIs (if any)
+
+Key directories:
+  controllers/   — HTTP endpoints
+  managers/      — Business logic
+  repositories/  — Data access
+  models/        — Entities + DTOs
+  config/        — Application config
+```
+
+### For frontend projects
+```
+Render flow:
+  Route → Page → Layout → Components → Hooks → API client → Backend
+
+Key directories:
+  app/           — Pages and routes
+  components/    — Reusable UI
+  hooks/         — Custom hooks
+  lib/           — Utilities and API client
+  types/         — TypeScript types
+```
+
+### Produce an architecture overview
+
+```markdown
+## Architecture
+
+**Pattern:** [MVC, layered, microservices, etc.]
+**Entry points:** [main files, route handlers]
+**Data model:** [key entities and their relationships]
+**External deps:** [databases, APIs, queues, caches]
+**Config:** [how config works — env vars, files, etc.]
+
+**Request flow:**
+[trace one typical request end-to-end]
+
+**Key decisions:**
+[any non-obvious architecture choices — why things are the way they are]
+```
+
+### Check for gotchas
+- Any code that looks unused but might be important?
+- Unusual patterns that a new dev would trip on?
+- Known tech debt? (look for TODO comments, fixme markers)
+
+```bash
+grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.kt" --include="*.tsx" --include="*.ts" src/ | head -20
+```
+
+**GATE 2 — STOP and ask:**
+> "Here's how this project works: [architecture overview]. Questions before I set things up?"
+>
+> This is the most important gate. Make sure the user's mental model matches reality.
+
+---
+
+## Stage 3: Setup
+
+**Goal:** Configure the AI tools for this specific project.
+
+### Generate or update CLAUDE.md
+Use the approach from `/spartan:init-project` internally:
+- Tech stack section
+- Architecture section (from Stage 2)
+- Conventions (detected from code patterns)
+- Key commands (build, test, run)
+- Domain context
+
+If CLAUDE.md already exists, don't overwrite — merge your findings into it.
+
+### Recommend packs
+Based on the detected stack:
+
+| Stack detected | Recommended packs |
+|----------------|-------------------|
+| Kotlin/Micronaut | `core` + `backend-micronaut` (pulls in `database` + `shared-backend`) |
+| Next.js/React | `core` + `frontend-react` |
+| Full-stack | `core` + `backend-micronaut` + `frontend-react` |
+| Unknown | `core` only, ask about stack |
+
+If packs aren't installed yet:
+> "This is a [stack] project. I'd add the [pack] pack for stack-specific guidance. Want me to set it up?"
+
+### Verify setup
+```bash
+# Check CLAUDE.md exists and has content
+ls -la CLAUDE.md
+wc -l CLAUDE.md
+
+# Check if rules are in place
+ls ~/.claude/rules/ 2>/dev/null
+```
+
+---
+
+## Stage 4: Save to Memory (auto-runs)
+
+After setup, save key findings so future sessions don't have to re-scan.
+
+```bash
+mkdir -p .memory/knowledge .memory/decisions
+```
+
+**What to save:**
+- **Architecture summary** → `.memory/knowledge/architecture.md`
+- **Key gotchas/patterns found** → `.memory/knowledge/gotchas.md`
+- **Tech debt notes** → `.memory/knowledge/tech-debt.md` (if significant)
+- **Non-obvious decisions** → `.memory/decisions/` (only if the user shared context that isn't in the code)
+
+**What NOT to save:**
+- Things already in CLAUDE.md (don't duplicate)
+- Obvious stuff (it's a React app, it uses TypeScript)
+- File paths (they change)
+
+Create or update `.memory/index.md`:
+```markdown
+# Project Memory
+
+## Knowledge
+- [architecture.md](knowledge/architecture.md) — [one-line summary]
+- [gotchas.md](knowledge/gotchas.md) — [one-line summary]
+
+## Decisions
+[add any decisions the user shared]
+```
+
+**GATE 3 — Done.**
+> "You're set up. Here's what's ready:
+> - CLAUDE.md: [created/updated]
+> - Stack: [detected stack]
+> - Packs: [what's installed]
+> - Memory: key findings saved for future sessions
+>
+> Start building with `/spartan:build [feature]` or explore with `/spartan` anytime."
+
+---
+
+## If the codebase is legacy / brownfield
+
+If the scan reveals a messy or unfamiliar codebase (no docs, no tests, tangled dependencies), use the approach from `/spartan:brownfield` internally for a deeper analysis before mapping.
+
+Signs of brownfield:
+- No tests or very few tests
+- No documentation
+- Multiple frameworks or patterns mixed together
+- Large files (1000+ lines)
+- Circular dependencies
+
+In this case, add a warning:
+> "This codebase has some legacy patterns. Here's what to watch out for: [specific issues]. I'd suggest adding tests before making changes in [risky areas]."
+
+---
+
+## Rules
+
+- **You are the leader.** Run scanning, mapping, and setup yourself. Don't tell the user to run `/spartan:init-project` or `/spartan:map-codebase` separately.
+- **Don't change any code during onboarding.** This is read-only. Understand first.
+- **Ask about what's NOT in the code.** Business context, deployment process, team conventions — things you can't see in files.
+- **Don't assume conventions from one file apply everywhere.** Check multiple files for consistency.
+- **If CLAUDE.md exists, read it before scanning.** Someone already did this work — build on it.
+- **Save findings to memory.** Future sessions should benefit from this onboarding work.
+- **The architecture overview should fit on one screen.** If it's longer, you're over-explaining.

package/commands/spartan/outreach.md

@@ -0,0 +1,16 @@
+---
+name: spartan:outreach
+description: Draft personalized investor outreach emails — cold, warm intro, and follow-up
+argument-hint: "[investor name or context]"
+---
+
+# Outreach: {{ args[0] | default: "investor email" }}
+
+Draft investor communication.
+
+## Steps
+
+1. Use the `investor-outreach` skill
+2. If investor name is given, search for their thesis, portfolio, recent activity
+3. Personalize the email based on real data
+4. If no investor info is available, create a template and flag what needs personalizing

package/commands/spartan/phase.md

@@ -0,0 +1,142 @@
+---
+name: spartan:phase
+description: Manage project phases — discuss requirements, plan tasks, execute work, verify results. This is the Spartan wrapper for GSD phase commands. Use after /spartan:project new.
+argument-hint: "[discuss | plan | execute | verify] [phase number]"
+---
+
+# Phase {{ args[1] | default: "?" }}: {{ args[0] | default: "discuss" }}
+
+You are managing a phase in the current GSD project.
+The user does NOT need to know about `/gsd:*` commands — everything runs through `/spartan:*`.
+
+---
+
+{% if args[0] == "discuss" %}
+## Discuss Phase {{ args[1] | default: "N" }}
+
+Gathering requirements for this phase. But first — Office Hours.
+
+**MANDATORY: Ask these 3 forcing questions BEFORE gathering requirements:**
+
+1. **"What pain are we actually solving?"** (not the feature — the underlying pain)
+2. **"What's the narrowest version we can ship to learn?"** (force MVP thinking)
+3. **"What assumption are we making that could be wrong?"** (surface hidden risks)
+
+**Auto mode on?** → Still ask these 3 questions. They prevent building the wrong thing.
+
+Only after the user answers all 3 → proceed:
+
+**Run:** `/gsd:discuss-phase {{ args[1] | default: "N" }}`
+
+After discussion, decompose requirements into work units (WUs) per GSD v5:
+- Each WU: max 3 files, max half-day, one commit
+- Group into waves by dependency
+
+Then tell the user:
+"Requirements gathered and decomposed into [N] work units across [N] waves. Next step: `/spartan:phase plan {{ args[1] | default: "N" }}`"
+
+{% elif args[0] == "plan" %}
+## Plan Phase {{ args[1] | default: "N" }}
+
+Generating the execution plan with wave-parallel tasks.
+
+**Before planning, check `.memory/index.md`** for relevant patterns, decisions, and knowledge from previous phases.
+
+**Run:** `/gsd:plan-phase {{ args[1] | default: "N" }}`
+
+The plan should include:
+- Work units grouped into waves
+- Wave 1 = independent tasks (can run in parallel tabs)
+- Wave 2+ = depends on previous wave
+- Each task has: files to touch, test to write first, commit message
+
+Then tell the user:
+"Plan ready with [N] waves. Next step: `/spartan:phase execute {{ args[1] | default: "N" }}`"
+
+If the user has multiple Claude Code tabs available, suggest:
+"Wave 1 has [N] independent tasks — you can run them in parallel tabs for speed."
+
+{% elif args[0] == "execute" %}
+## Execute Phase {{ args[1] | default: "N" }}
+
+Running the planned tasks wave by wave.
+
+### Auto-parallelize with Agent Teams
+
+```bash
+echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not_set}"
+```
+
+**If Agent Teams is enabled AND the current wave has 2+ parallel work units:** Use Agent Teams automatically. Don't ask — just do it. This replaces manual multi-tab work.
+
+Run `/spartan:team wave` internally. This:
+1. Creates a team from the wave plan
+2. Spawns one agent per WU with worktree isolation
+3. Passes design docs to any UI-related WUs (check `.planning/designs/`)
+4. Verifies tests pass between waves
+5. Auto-advances to the next wave
+
+**If Agent Teams is NOT enabled** (env var not set) → continue with default execution:
+
+**Run:** `/gsd:execute-phase {{ args[1] | default: "N" }}`
+
+During execution:
+- Follow TDD: test first → implement → verify
+- Respect safety guardrails if active (careful/freeze/guard)
+- After each wave, verify all tests pass before starting next wave
+- Capture new knowledge to `.memory/` as you go
+
+After execution, tell the user:
+"Phase {{ args[1] | default: "N" }} executed. [N] commits made."
+
+Suggest next step based on phase complexity:
+- If phase had 3+ tasks: "Run `/spartan:gate-review {{ args[1] | default: "N" }}` for a dual-agent review, then `/spartan:phase verify {{ args[1] | default: "N" }}`"
+- If phase was simple (1-2 tasks): "Next step: `/spartan:phase verify {{ args[1] | default: "N" }}`"
+
+{% elif args[0] == "verify" %}
+## Verify Phase {{ args[1] | default: "N" }}
+
+Running acceptance criteria checks and UAT.
+
+**Run:** `/gsd:verify-work {{ args[1] | default: "N" }}`
+
+After verification:
+1. Check all acceptance criteria from the discuss phase
+2. Run full test suite
+3. Extract decisions made → `.memory/decisions/`
+4. Extract patterns discovered → `.memory/patterns/`
+5. Update `.memory/index.md`
+
+Then tell the user:
+- If passed: "Phase {{ args[1] | default: "N" }} verified ✅. Next: `/spartan:phase discuss [N+1]` for the next phase, or `/spartan:project milestone-complete` if milestone is done."
+- If failed: "Phase {{ args[1] | default: "N" }} has [N] issues. Fix them, then re-run `/spartan:phase verify {{ args[1] | default: "N" }}`."
+
+{% else %}
+## Unknown action: {{ args[0] }}
+
+Available actions:
+- `/spartan:phase discuss N` — Gather requirements (starts with Office Hours)
+- `/spartan:phase plan N` — Generate wave-parallel execution plan
+- `/spartan:phase execute N` — Execute tasks wave by wave
+- `/spartan:phase verify N` — Run acceptance criteria + UAT
+
+Example: `/spartan:phase discuss 1`
+{% endif %}
+
+---
+
+## Phase Lifecycle (for reference)
+
+```
+/spartan:phase discuss N     ← Office Hours → requirements → decompose
+       ↓
+/spartan:phase plan N        ← Wave-parallel plan from .memory/ context
+       ↓
+/spartan:phase execute N     ← TDD, wave by wave, safety guardrails
+       ↓
+/spartan:gate-review N       ← Dual-agent review (Gate 3.5) — optional but recommended
+       ↓
+/spartan:phase verify N      ← UAT + capture knowledge to .memory/
+       ↓
+  [next phase or milestone complete]
+```

package/commands/spartan/pitch.md

@@ -0,0 +1,18 @@
+---
+name: spartan:pitch
+description: Create investor-facing materials — deck outline, one-pager, memo, or financial model
+argument-hint: "[what you need: deck, one-pager, memo, model]"
+---
+
+# Pitch: {{ args[0] | default: "deck outline" }}
+
+Create investor materials.
+
+## Steps
+
+1. Use the `investor-materials` skill
+2. Check for existing research in the project's `02-research/` and `03-validation/` folders
+3. Use that data as the source of truth
+4. Save to the project's `04-build/` folder
+
+If there's no prior research, warn that the materials will be weaker without data.