@c0x12c/ai-toolkit 1.15.0

package/commands/spartan/context-save.md

@@ -0,0 +1,161 @@
+---
+name: spartan:context-save
+description: Manage context window — first tries /compact to free space, then saves full handoff if needed. Auto-triggered when Claude detects context pressure, or run manually anytime.
+---
+
+# Context Save — Smart Context Management
+
+## Step 0: Triage — Compact or Full Save?
+
+Assess the situation before doing a full handoff:
+
+**Option A: Compact (stay in same session)**
+If the session has useful remaining capacity and user wants to keep working:
+1. Summarize the conversation so far into key decisions + current state
+2. Run `/compact` to free context space
+3. Continue working in the same session
+
+Use compact when: mid-task, still productive, just need to free space.
+
+**Option B: Full Save (end session, resume in new one)**
+If the session is too deep to recover, or user is done for now:
+1. Save everything to `.handoff/` file
+2. Update `.memory/` with new knowledge
+3. User starts fresh session and reads the handoff file
+
+Use full save when: session > 60%, quality visibly degrading, end of work day, switching to different task.
+
+**Auto-triggered?** When Claude detects its own context pressure (forgetting earlier context, slow responses, repeating itself), it should:
+1. First try compact (Option A)
+2. If already compacted once this session → go to full save (Option B)
+3. Tell the user what's happening: "Context getting heavy — compacting to stay productive."
+
+---
+
+## Full Save Process (Option B)
+
+## Step 1: Capture Current State
+
+Answer these by reviewing the conversation and codebase:
+
+**1. What was being worked on?**
+(Feature name, ticket, GSD phase, etc.)
+
+**2. What was completed in this session?**
+(List commits made, tasks finished)
+
+**3. What is the current status?**
+(In-progress task, where exactly we stopped)
+
+**4. What are the immediate next steps?**
+(Exactly what to do next — be specific enough that a fresh agent can start without asking)
+
+**5. What context is critical to carry forward?**
+(Key decisions made, tradeoffs chosen, things tried that didn't work)
+
+**6. What are the known risks / things to watch out for?**
+
+---
+
+## Step 2: Check Git State
+
+```bash
+# Uncommitted changes?
+git status
+git diff --stat
+
+# Last commits this session
+git log --oneline -5
+
+# Current branch
+git branch --show-current
+```
+
+If there are uncommitted changes:
+- Stash them: `git stash save "wip: [description]"`
+- Or commit as WIP: `git commit -m "chore: wip - [what's in progress]"`
+
+---
+
+## Step 3: Write Handoff File
+
+Save as `.handoff/[YYYY-MM-DD-HH]-[feature-slug].md`:
+
+```markdown
+# Session Handoff: [feature/task name]
+Created: [timestamp]
+Branch: [current branch]
+Author: [git user.name]
+
+## What We Were Building
+[1-2 sentences on the feature/task]
+
+## Session Progress
+### Completed ✅
+- [task 1 — commit hash if available]
+- [task 2]
+
+### In Progress 🔨
+- [exactly what was being done when session ended]
+- Current file being edited: [path]
+- Stopped at: [line/function/what was next]
+
+## Resume Instructions
+To pick up immediately:
+1. `git checkout [branch]`
+2. [specific command or action to run first]
+3. [next step]
+4. Goal: [what "done" looks like for the next session]
+
+## Key Decisions Made This Session
+- [decision 1 and why]
+- [decision 2 and why]
+
+## Things Tried That Didn't Work
+- [approach X] — didn't work because [reason], don't try again
+- [approach Y] — causes [problem]
+
+## Critical Context
+[Any important information that isn't obvious from the code:
+- Business rules that affected implementation
+- Gotchas discovered
+- Dependencies or constraints to be aware of]
+
+## Blockers / Risks
+- [any outstanding questions or blockers]
+
+## GSD State (if using GSD)
+- Project: [PROJECT.md location]
+- Milestone: [current milestone]
+- Phase: [current phase N of M]
+- Resume with: `/gsd:status` then `/gsd:execute-phase [N]`
+
+## Files Modified This Session
+[list of key files changed]
+
+## Tests Status
+- All tests passing: [yes/no]
+- Tests added: [list]
+- Known failing tests: [list if any, why]
+```
+
+---
+
+## Step 4: Verify Handoff is Complete
+
+Read back the handoff file you just wrote and confirm:
+- [ ] Someone could resume without asking any questions
+- [ ] The "Resume Instructions" are specific enough to act on immediately
+- [ ] Git state is clean (committed or stashed)
+- [ ] No context is locked in this conversation that isn't in the file
+
+---
+
+## How to Resume in Next Session
+
+Start the new session with:
+```
+Read .handoff/[filename].md and resume where we left off.
+```
+
+The fresh Claude session will have full 200k context and all the state from this file.

package/commands/spartan/contribute.md

@@ -0,0 +1,140 @@
+---
+name: spartan:contribute
+description: Toggle contributor mode — Claude rates its own skill experience (0-10) after each command and files improvement reports to ~/.spartan/contributor-logs/. Opt-in only.
+argument-hint: "[on | off | reports]"
+preamble-tier: 2
+---
+
+# Contributor Mode: {{ args[0] | default: "on" }}
+
+You are managing **contributor mode** — a self-improvement loop for Spartan.
+
+When active, after every `/spartan:*` command finishes, Claude writes a short field report rating how well the skill worked.
+
+---
+
+{% if args[0] == "on" or args[0] == nil %}
+## Activate Contributor Mode
+
+```bash
+mkdir -p ~/.spartan/contributor-logs
+echo "enabled" > ~/.spartan/contributor-mode
+```
+
+Say: "Contributor mode ON. I'll file a quick report after each command — you won't notice unless something scored low."
+
+### What Happens Now
+
+After every `/spartan:*` command completes, **silently** evaluate and write a report:
+
+```bash
+mkdir -p ~/.spartan/contributor-logs
+```
+
+Write a file to `~/.spartan/contributor-logs/YYYY-MM-DD-HH-MM-command-name.md`:
+
+```markdown
+## Field Report: /spartan:[command]
+Date: [ISO timestamp]
+Score: [0-10]
+Branch: [current branch]
+Directory: [project directory]
+
+### What worked
+- [1-2 bullets on what the skill did well]
+
+### What didn't work
+- [1-2 bullets on friction, confusion, or missing features]
+- [skip this section if score >= 8]
+
+### Suggestion
+[One concrete improvement — a specific change to the command/skill, not vague feedback]
+```
+
+### Scoring Guide
+
+| Score | Meaning |
+|-------|---------|
+| 9-10 | Nailed it. No friction. Would use again without changes. |
+| 7-8 | Good. Minor friction but got the job done. |
+| 5-6 | OK. Needed manual intervention or workarounds. |
+| 3-4 | Poor. Missed the point or gave bad guidance. |
+| 0-2 | Broken. Actively wasted time or caused errors. |
+
+### Rules for Reporting
+
+1. **Be honest.** Don't inflate scores. A 6 is a 6.
+2. **Be specific.** "The migration template assumed Flyway but we use Liquibase" is useful. "Could be better" is not.
+3. **One suggestion per report.** The best improvement, not a wish list.
+4. **Don't slow down the user.** Write the report silently after the command finishes. Never ask the user to rate anything.
+5. **Score relative to the skill's promise.** If `/spartan:qa` says it'll find bugs but only checked if the page loads, that's a 4.
+
+{% elif args[0] == "off" %}
+## Deactivate Contributor Mode
+
+```bash
+rm -f ~/.spartan/contributor-mode
+```
+
+Say: "Contributor mode OFF. No more field reports. Your existing reports are still in `~/.spartan/contributor-logs/`."
+
+{% elif args[0] == "reports" %}
+## View Reports
+
+```bash
+echo "=== Contributor Reports ==="
+echo ""
+
+if [ ! -d ~/.spartan/contributor-logs ] || [ -z "$(ls ~/.spartan/contributor-logs/ 2>/dev/null)" ]; then
+  echo "No reports yet. Enable contributor mode with /spartan:contribute"
+  exit 0
+fi
+
+# Summary stats
+TOTAL=$(ls ~/.spartan/contributor-logs/*.md 2>/dev/null | wc -l | tr -d ' ')
+echo "Total reports: $TOTAL"
+echo ""
+
+# Show last 10 reports with scores
+echo "Recent reports:"
+for f in $(ls -t ~/.spartan/contributor-logs/*.md 2>/dev/null | head -10); do
+  FNAME=$(basename "$f" .md)
+  SCORE=$(grep "^Score:" "$f" 2>/dev/null | head -1 | awk '{print $2}')
+  echo "  [$SCORE/10] $FNAME"
+done
+```
+
+Show the results in a clean table. Then:
+
+- If any score < 5: "Some skills scored low. Want me to read those reports and suggest fixes?"
+- If average > 7: "Skills are working well overall."
+- Always: "Reports are in `~/.spartan/contributor-logs/`. You can share them as GitHub issues to help improve Spartan."
+
+### Aggregate Analysis
+
+If the user asks for deeper analysis, group reports by command and show:
+
+| Command | Reports | Avg Score | Lowest | Top Issue |
+|---------|---------|-----------|--------|-----------|
+| /spartan:build | N | X.X | X | [most common complaint] |
+| /spartan:debug | N | X.X | X | [most common complaint] |
+
+{% else %}
+## Unknown argument: {{ args[0] }}
+
+Available options:
+- `/spartan:contribute` — Turn on contributor mode (default)
+- `/spartan:contribute off` — Turn it off
+- `/spartan:contribute reports` — View and analyze filed reports
+{% endif %}
+
+---
+
+## How to Check if Active
+
+Any skill can check:
+```bash
+[ -f ~/.spartan/contributor-mode ] && echo "CONTRIBUTOR_MODE=on"
+```
+
+If the file exists and contains "enabled", file a report after the skill finishes.

package/commands/spartan/daily.md

@@ -0,0 +1,42 @@
+---
+name: spartan:daily
+description: Generate a daily standup summary based on recent git history and GSD status
+---
+
+Generate a daily engineering standup summary for the current project.
+
+## Steps
+
+1. **Check recent git history** (last 24-48h):
+   ```bash
+   git log --since="2 days ago" --oneline --author="$(git config user.name)"
+   ```
+
+2. **Check GSD status** (if GSD project exists):
+   Read `.planning/` directory for current milestone and phase status.
+
+3. **Check for any failing tests or CI notes** (if available):
+   Look for recent test output files or CI logs.
+
+## Output Format
+
+```markdown
+## Daily Standup — [DATE]
+
+### Yesterday / Done
+- [completed items from git log / GSD progress]
+
+### Today / In Progress
+- [current phase or active task]
+- [next planned task]
+
+### Blockers
+- [any blockers found, or "None"]
+
+### Progress on Current Milestone
+- Phase X of Y complete
+- Est. completion: [if determinable from roadmap]
+```
+
+Keep it concise — each section max 3-4 bullet points.
+This is for a 15-minute standup, not a status report.

package/commands/spartan/debug.md

@@ -0,0 +1,308 @@
+---
+name: spartan:debug
+description: "Find and fix a bug end-to-end — structured investigation, root cause, test-first fix, and PR"
+argument-hint: "[describe the symptom or error]"
+preamble-tier: 3
+---
+
+# Debug: {{ args[0] | default: "a bug" }}
+
+You are the **Debug workflow leader** — structured debugging from symptom to merged PR.
+
+You decide when to investigate deeper, when to check memory for known issues, and when to ship. Don't guess. Don't try random fixes. Follow the pipeline.
+
+```
+PIPELINE:
+
+  Check Context → Reproduce → Investigate → Fix → Review Agent → Fix Loop → Ship
+       │              │            │          │         │             │        │
+   .memory/        Gate 1       Gate 2     Gate 3   Spawn agent   Loop    Gate 4
+   known issues                                    fix until OK
+```
+
+---
+
+## Step 0: Check Context (silent — no questions)
+
+Before touching anything, check if this is a known issue.
+
+```bash
+# Check memory for known blockers and gotchas
+ls .memory/blockers/ .memory/knowledge/ 2>/dev/null
+
+# Check for handoff from a previous debug session
+ls .handoff/*.md 2>/dev/null
+```
+
+**If `.memory/blockers/` has files**, scan them for anything matching the symptom. If you find a match:
+> "This might be a known issue. Found in `.memory/blockers/[file]`: [summary]. Let me verify if this is the same problem."
+
+**If `.memory/knowledge/` has files**, scan for related gotchas or patterns that might explain the bug.
+
+**If a handoff exists**, check if someone was already debugging this:
+> "Found a previous debug session for this. Resuming from: [last stage]."
+
+---
+
+## Stage 1: Reproduce
+
+**Goal:** Make the bug deterministic. Understand it fully before touching anything.
+
+### Gather info
+1. Get the exact error message, stack trace, or symptom
+2. Ask if not clear:
+   - What inputs trigger it?
+   - What inputs do NOT trigger it?
+   - Consistent or flaky?
+   - Which environment? (local / CI / prod)
+
+### Check recent changes
+```bash
+# What changed recently?
+git log --oneline -15
+git diff HEAD~5 --stat
+
+# Are tests already failing?
+./gradlew test --info 2>&1 | tail -40
+```
+
+### Find minimal reproduction
+- Trace the code path from the symptom
+- Identify the smallest input that triggers the bug
+- Confirm you can make it happen on demand
+
+**If you can't reproduce it:**
+> Stop. Ask for more context — logs, steps, environment details. Don't move forward until you can see the bug happen.
+
+**GATE 1 — STOP and ask:**
+> "I can reproduce the bug. Here's what happens: [symptoms]. Here's how to trigger it: [steps]. Moving to investigation?"
+>
+> **Auto mode on?** → Show findings, continue immediately.
+
+---
+
+## Stage 2: Investigate
+
+**Goal:** Find the exact line, value, or decision that causes the failure.
+
+### Binary isolation
+Start from the failure point. Trace backwards:
+
+1. At the crash/error point — what's the value?
+2. One layer up — is the data correct here?
+3. Keep going back until you find where correct data becomes wrong data
+
+### Common patterns to check
+
+**Kotlin/Micronaut:**
+- `!!` operators (banned — null safety violation)
+- Either handling — is `.left()` / `.right()` correct? Missing error branch?
+- Coroutine scope — is a job cancelled before it finishes?
+- `newSuspendedTransaction {}` — is it wrapping the right calls?
+- Soft delete — is `deleted_at IS NULL` in the query?
+
+**React/Next.js:**
+- Missing dependency in `useEffect` array
+- State update after unmount
+- Server/client hydration mismatch
+- Missing error boundary
+- Wrong key prop in list rendering
+
+**General:**
+- Race condition — does order of execution matter?
+- Stale cache — is old data being served?
+- Config mismatch — different values between environments?
+
+### Form a hypothesis
+Write it down: "The root cause is [X] because [evidence]."
+
+If your first hypothesis is wrong, try the next one. **Max 3 hypotheses** before stopping and asking for help. Don't go in circles.
+
+**GATE 2 — STOP and ask:**
+> "Root cause: [one sentence]. Evidence: [what proves it]. Here's my fix plan: [approach]. Sound right?"
+>
+> **Auto mode on?** → Show root cause, continue to fix.
+
+---
+
+## Stage 3: Fix
+
+**Goal:** Fix correctly. Make sure it can't come back.
+
+### Step 1: Write failing test
+```
+Write a test that captures the exact bug scenario.
+This test MUST FAIL right now — if it passes, you haven't reproduced the bug in the test.
+```
+
+Run it. Confirm red.
+
+### Step 2: Write the minimal fix
+Change as little as possible. This is a fix, not a refactor. Don't clean up nearby code. Don't "improve" things while you're here.
+
+Run the test. Confirm green.
+
+### Step 3: Check for similar patterns
+The same mistake might exist elsewhere:
+```bash
+# Find code with the same pattern as the bug
+grep -rn "[pattern from the bug]" --include="*.kt" --include="*.tsx" src/
+```
+
+If you find similar issues, fix them too. Each gets its own test.
+
+### Step 4: Run full test suite
+```bash
+# Make sure nothing else broke
+./gradlew test
+# or
+npm test
+```
+
+### Commit
+```
+fix([scope]): [root cause description]
+
+- Root cause: [one line]
+- Add regression test: [test name]
+- Checked [N] similar patterns
+```
+
+**GATE 3 — Implementation complete.**
+> "Fixed. [X] tests passing, including the new regression test. Found [N] similar patterns — [fixed/clean]. Starting review."
+>
+> **Auto mode on?** → Go straight to review.
+
+---
+
+## Stage 4: Review (agent-based — mandatory)
+
+**Don't self-review bug fixes.** Spawn a separate review agent to catch things you missed.
+
+### Spawn the review agent
+
+```bash
+echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not_set}"
+```
+
+Use the `Agent` tool to spawn a reviewer:
+
+```
+Agent:
+  name: "reviewer"
+  subagent_type: "phase-reviewer"  (or "general-purpose" if not available)
+  prompt: |
+    You are reviewing a bug fix for: {symptom description}.
+
+    Root cause: {root cause}
+    Fix: {what was changed}
+
+    Run `git diff main...HEAD` to see all changes.
+
+    Review checklist:
+    **Root cause:** Does the fix address the root cause, not just the symptom?
+    **Regression test:** Does the test cover the exact scenario that failed?
+    **Side effects:** Could this fix break anything else?
+    **Similar patterns:** Were similar patterns in the codebase checked?
+    **No extras:** Is the change minimal? No unrelated cleanup?
+
+    Verdict: **PASS** or **NEEDS CHANGES** (with the list of issues).
+```
+
+**If Agent Teams is enabled**, also spawn a test-reviewer in parallel:
+```
+Agent 2: "test-reviewer" — checks test quality, edge cases, coverage gaps
+```
+
+### Fix loop
+
+**If PASS** → continue to Ship.
+
+**If NEEDS CHANGES:**
+1. Fix the issues
+2. Commit: `fix([scope]): address review feedback`
+3. Run tests
+4. Spawn reviewer AGAIN with updated diff
+5. Repeat until PASS
+
+**Max 3 rounds.** If stuck, ask the user.
+
+---
+
+## Stage 5: Ship
+
+### Create PR
+Clear description matters more for bug fixes than features:
+
+```markdown
+## What was broken
+[User-visible symptom]
+
+## Root cause
+[One paragraph — what went wrong and why]
+
+## Fix
+[What was changed and why it fixes the root cause]
+
+## How to verify
+[Steps to confirm the bug is gone]
+
+## Regression test
+[Name of the test that guards against this]
+```
+
+### Save to memory (if this bug reveals a pattern)
+
+After the PR, check if this bug is worth remembering:
+
+- **Recurring pattern?** (same type of bug seen before) → Save to `.memory/knowledge/`
+- **Known blocker for other work?** → Save to `.memory/blockers/`
+- **One-off typo or simple mistake?** → Don't save. Not worth remembering.
+
+```bash
+mkdir -p .memory/knowledge .memory/blockers
+```
+
+Update `.memory/index.md` if you saved anything.
+
+**GATE 4 — Done.**
+> "PR created: [link]. Bug: [symptom]. Root cause: [one line]. Fix: [one line]."
+
+---
+
+## Debug Report
+
+After the PR is created, produce this summary:
+
+```markdown
+## Debug Report: [symptom]
+
+**Root Cause:** [exact cause in one sentence]
+
+**Why it happened:** [2-3 sentences — the chain of events]
+
+**Fix:** [what changed and why]
+
+**Test added:** [test name]
+
+**Similar patterns checked:** [files checked / changes made]
+
+**Prevention:** [what could stop this class of bug — lint rule, convention, type change, etc.]
+
+**Saved to memory:** [yes/no — what was saved and why]
+```
+
+---
+
+## Rules
+
+- **You are the leader.** Check memory, investigate, fix, review, ship — all in one flow. Don't tell the user to run separate commands.
+- **Follow the pipeline in order.** Don't skip to fixing. Understanding comes first.
+- **Never guess.** Every hypothesis needs evidence. "I think it might be..." is not enough.
+- **Write a failing test before writing the fix.** Always.
+- **Minimal fix.** Change as little as possible. Don't refactor while fixing.
+- **Check for siblings.** The same bug pattern might exist nearby. Always look.
+- **Max 3 hypotheses in Stage 2.** If none pan out, stop and ask for help. Don't spiral.
+- **Review is always an agent.** Never self-review. Spawn a reviewer, fix until PASS.
+- **Save patterns to memory.** If this bug type could happen again, save it so future sessions know.
+- **Small bugs don't need this workflow.** If you can see the typo, just fix it. This is for bugs that aren't obvious.

package/commands/spartan/deep-dive.md

@@ -0,0 +1,55 @@
+---
+name: spartan:deep-dive
+description: "Go deep on a validated idea: market research + competitor teardowns (Stage 3)"
+argument-hint: "[project name or idea]"
+---
+
+# Deep Dive: {{ args[0] | default: "your idea" }}
+
+Runs Stage 3: deep market research and competitor teardowns.
+Only do this AFTER validation says GO or TEST MORE.
+
+## Steps
+
+### Check Prior Work
+1. Find the project folder in `projects/`
+2. Read everything in `01-brainstorm/` and `03-validation/`
+3. Pull out: the idea, target user, competitors found, market signals
+
+### Market Research
+4. Use the `market-research` skill
+5. Run market sizing (TAM/SAM/SOM with math shown)
+6. Find industry data, reports, trends
+7. Check demand signals: search volume, forum posts, review complaints
+8. Look for tailwinds (new regulation, tech shift, behavior change)
+9. Save to `02-research/market-research-{date}.md`
+
+### Competitor Teardowns
+10. Use the `competitive-teardown` skill
+11. Identify top 3-5 competitors from validation step
+12. For each competitor:
+    - Product teardown (what they do, pricing, strengths, weaknesses)
+    - Business teardown (funding, team, traction)
+    - User feedback (reviews, Reddit, forums)
+13. Save each to `02-research/teardown-{competitor}-{date}.md`
+
+### Synthesis
+14. Create a summary that connects everything:
+    - Market size and growth
+    - Competitor landscape (table comparison)
+    - The gap: what nobody does well
+    - Our positioning: where we win
+    - Biggest risks
+15. Save to `02-research/synthesis-{date}.md`
+
+### Gate 3 Check
+16. Show findings to user
+17. If strong signals: "This looks worth building. Want me to run /spartan:fundraise?"
+18. If weak signals: "Here's what's concerning: [X]. Still want to go forward?"
+19. If dead: "I'd archive this. Here's why: [X]"
+
+## Rules
+
+- Read ALL prior work before starting. Don't re-research what we already know.
+- If validation was TEST MORE, ask what test the user ran and what happened.
+- Be honest if the data kills the idea. Better now than after building.