@c0x12c/ai-toolkit 1.15.0

package/commands/spartan/brainstorm.md

@@ -0,0 +1,134 @@
+---
+name: spartan:brainstorm
+description: Structured brainstorming — generate ideas, filter fast, rank the top 3
+argument-hint: "[theme or problem space]"
+---
+
+# Brainstorm: {{ args[0] | default: "new ideas" }}
+
+You are running a structured brainstorming session in 3 steps: Generate, Filter, Rank.
+
+The goal: go from a theme to 3 strong ideas in about 15 minutes.
+
+---
+
+## Step 1: GENERATE (~5 min)
+
+Brain dump time. Quantity over quality. No filtering yet.
+
+Generate **8-15 ideas** around the theme: {{ args[0] }}
+
+Use different lenses to get variety:
+- **Technology lens:** What can new tech (AI, APIs, automation) make possible now that wasn't before?
+- **Market gap lens:** What's missing in this space? What do people complain about?
+- **Pain point lens:** What painful manual process could be fixed?
+- **Trend lens:** What's changing in this space? Where is it heading?
+- **Remix lens:** Take an existing product in another market — what if it existed for THIS market?
+
+For each idea, write exactly 3 things:
+
+| # | Name | One-Sentence Pitch | Who It's For |
+|---|---|---|---|
+| 1 | [catchy name] | [what it does in one sentence] | [specific person/role] |
+| 2 | | | |
+| ... | | | |
+
+**Rules during generation:**
+- No judging yet. Bad ideas are fine. They can spark good ones.
+- Each idea must be different enough from the others — no slight variations
+- "Who it's for" must be a specific person, not "everyone"
+
+Show the full list, then ask: **"Want to add any ideas before we filter? Last chance — once we filter, we kill fast."**
+
+---
+
+## Step 2: FILTER (~5 min)
+
+Quick kill round. For each idea, answer 3 questions:
+
+| # | Name | Build MVP in 2-4 weeks? | Know someone with this problem? | Would someone pay TODAY? | Grade |
+|---|---|---|---|---|---|
+| 1 | [name] | Yes/No | Yes/No | Yes/No | HOT/WARM/COLD |
+| 2 | | | | | |
+| ... | | | | | |
+
+**Grading:**
+- **HOT** = All 3 yes — strong candidate
+- **WARM** = 2 yes — worth a closer look
+- **COLD** = 0-1 yes — kill it (for now)
+
+**Kill question details:**
+
+**"Can I build an MVP in 2-4 weeks?"**
+If no → park it. Good ideas you can't build fast become idea graveyards. Come back when you can.
+
+**"Do I know someone who has this problem?"**
+If no → risky. You can't do user interviews if you don't know the users. You'd be guessing.
+
+**"Would someone pay for this TODAY?"**
+If no → might still work as a free/community play, but the path to money is harder. Note it.
+
+Show the filtered list. Cross out COLD ideas. Ask: **"Agree with the filtering? Any saves before we rank?"**
+
+---
+
+## Step 3: RANK (pick top 3, ~5 min)
+
+Take all HOT and WARM ideas. If there are more than 5, narrow down.
+
+Rank by these 3 factors:
+
+| # | Name | Founder-Market Fit | Market Size (gut) | Excitement | Total |
+|---|---|---|---|---|---|
+| | | 1-5 | 1-5 | 1-5 | /15 |
+
+**Founder-Market Fit:** Do you understand these users? Have you been one of them? Do you have connections in this space?
+
+**Market Size (gut feel):** How many people have this problem? Don't need exact numbers — just S/M/L/XL gut check, mapped to 1-5.
+
+**Excitement:** How pumped are you about this idea? Be honest. You'll be working on it for months. Low excitement = you'll quit.
+
+---
+
+## Output: Top 3 Ideas
+
+For each of the top 3, write one paragraph:
+
+```
+## Top 3 Ideas
+
+### #1: [Name] (Score: X/15)
+[One paragraph: what it is, who it's for, why it scored high,
+what makes it worth pursuing. Include the biggest risk.]
+
+### #2: [Name] (Score: X/15)
+[Same format]
+
+### #3: [Name] (Score: X/15)
+[Same format]
+```
+
+---
+
+## Also Considered (WARM ideas for later)
+
+List the WARM ideas that didn't make top 3 but could be worth revisiting:
+- [Name] — [one line on why it's parked]
+
+---
+
+## Next Step
+
+> Run `/spartan:validate` on your #1 pick.
+
+Validation will score the idea on 7 areas and give you a GO / TEST MORE / KILL decision.
+
+If your #1 doesn't pass validation, come back and try #2.
+
+---
+
+**Other useful follow-ups:**
+- `/spartan:teardown [competitor]` — Analyze competitors in the space
+- `/spartan:interview [idea]` — Generate user interview questions
+- `/spartan:lean-canvas [idea]` — Map out the full business model
+- `/spartan:think [idea]` — Deep structured thinking before building

package/commands/spartan/brownfield.md

@@ -0,0 +1,157 @@
+---
+name: spartan:brownfield
+description: Analyze an existing codebase and generate a structured context map + onboarding spec before making any changes. Use when joining a legacy project or unfamiliar service.
+argument-hint: "[service name or directory] [optional: area of focus]"
+---
+
+# Brownfield Onboarding: {{ args[0] }}
+Focus area: {{ args[1] | default: "full codebase" }}
+
+You are performing a **brownfield analysis** — mapping an existing codebase before touching it.
+This prevents the most common AI coding mistake: making changes without understanding the terrain.
+
+Inspired by OpenSpec's change-isolation philosophy: understand first, change second.
+
+---
+
+## Phase 1: Structure Mapping (automated)
+
+Run these commands to get a high-level picture:
+
+```bash
+# Project structure
+find . -type f -name "*.kt" | head -60
+find . -type f -name "*.gradle.kts" | head -10
+
+# Dependencies
+cat build.gradle.kts 2>/dev/null || cat pom.xml 2>/dev/null
+
+# Database migrations (Flyway)
+ls src/main/resources/db/migration/ 2>/dev/null | sort
+
+# Test coverage picture
+find . -path "*/test/*" -name "*.kt" | wc -l
+find . -path "*/main/*" -name "*.kt" | wc -l
+
+# Recent git activity
+git log --oneline -20
+git log --oneline --since="30 days ago" | wc -l
+```
+
+---
+
+## Phase 2: Architecture Analysis
+
+Read and analyze these files (if they exist):
+- `README.md` / `docs/`
+- `CLAUDE.md` / `AGENTS.md`
+- `src/main/resources/application.yml`
+- Main `@MicronautApplication or Application.kt` class
+- Domain model files in `domain/model/`
+
+Then answer:
+1. **What does this service do?** (1-2 sentences)
+2. **What are the main domain entities?**
+3. **What external systems does it talk to?** (DB, Kafka, Redis, HTTP)
+4. **What are the main entry points?** (controllers, consumers)
+5. **What tech debt is visible?** (TODO comments, deprecated APIs, inconsistent patterns)
+
+---
+
+## Phase 3: Hotspot Detection
+
+```bash
+# Most-changed files (potential complexity hotspots)
+git log --format=format: --name-only | grep "\.kt$" | sort | uniq -c | sort -rn | head -15
+
+# Largest files (potential god classes)
+find . -name "*.kt" -exec wc -l {} \; | sort -rn | head -10
+
+# TODO/FIXME density
+grep -r "TODO\|FIXME\|HACK\|XXX" --include="*.kt" | wc -l
+grep -r "TODO\|FIXME\|HACK\|XXX" --include="*.kt" | head -10
+```
+
+---
+
+## Phase 4: Test Health Check
+
+```bash
+# Test types present
+find . -name "*Test*.kt" -o -name "*Spec*.kt" | head -20
+
+# Integration tests (Testcontainers)
+grep -r "Testcontainers\|@Container" --include="*.kt" -l
+
+# Test coverage (if JaCoCo configured)
+cat build.gradle.kts | grep -A5 "jacoco"
+```
+
+Assess:
+- Unit test coverage (estimate from file count ratio)
+- Integration test presence
+- Any tests using mocks where Testcontainers would be better
+
+---
+
+## Phase 5: Generate Context Map
+
+Save output as `docs/CONTEXT-MAP.md`:
+
+```markdown
+# Context Map: [service name]
+Generated: [date]
+
+## Service Purpose
+[1-2 sentences]
+
+## Architecture
+- Pattern: [layered / hexagonal / other]
+- Main layers: [list]
+- External dependencies: [list with protocols]
+
+## Domain Model
+[key entities and their relationships]
+
+## Entry Points
+[controllers + endpoints, consumers + topics]
+
+## Known Tech Debt
+[ordered by severity]
+
+## Test Health
+- Unit tests: [count / assessment]
+- Integration tests: [count / assessment]
+- Coverage gaps: [where tests are missing]
+
+## Safe Change Zones
+[areas that are well-tested and safe to modify]
+
+## Danger Zones  
+[areas that are fragile, under-tested, or have unclear behavior]
+
+## Recommended First Steps
+1. [what to do before making any changes]
+2. [what tests to add first]
+3. [what to refactor before building new features]
+```
+
+---
+
+## Phase 6: Change Isolation Setup
+
+For each planned change to this codebase, create a folder:
+```
+.changes/
+  [YYYY-MM-DD]-[change-name]/
+    PROPOSAL.md    ← what you want to change and why
+    DESIGN.md      ← how you'll change it
+    TASKS.md       ← atomic steps (max 4)
+    RISKS.md       ← what could break
+```
+
+This prevents scope creep and keeps each change independently reviewable.
+
+After analysis, present the Context Map summary and ask:
+"Analysis complete. What change would you like to make first?
+I'll create a change folder and use `/spartan:spec` → `/spartan:build` for it."