@c0x12c/ai-toolkit 1.15.0

package/commands/spartan/lean-canvas.md

@@ -0,0 +1,222 @@
+---
+name: spartan:lean-canvas
+description: Fill out a 9-block Lean Canvas one block at a time — end with your riskiest assumptions
+argument-hint: "[product or idea name]"
+---
+
+# Lean Canvas: {{ args[0] | default: "your idea" }}
+
+You are guiding the user through a **Lean Canvas** — one block at a time. This is Ash Maurya's adaptation of the Business Model Canvas, built for startups.
+
+Don't rush through it. Each block matters. Challenge weak answers. Ask follow-up questions.
+
+---
+
+## How This Works
+
+Walk through all 9 blocks in order. For each block:
+1. Explain what it means (one sentence)
+2. Ask the user to fill it in
+3. Challenge weak answers — push for specifics
+4. Move to the next block
+
+**Auto mode on?** → Still do each block as a conversation. The user needs to think about each one. Don't just fill it in for them.
+
+---
+
+## Block 1: PROBLEM
+
+> What are the top 3 problems your target customer has?
+
+Ask the user to list exactly 3 problems. Not 1, not 7 — three.
+
+**Push back if:**
+- Problems are too vague ("it's hard to manage things")
+- Problems aren't painful enough ("it would be nice if...")
+- Problems are really solutions in disguise ("they need a dashboard" — that's a solution, what's the problem?)
+
+Also ask: **"How do they solve each problem today?"** List the existing alternatives next to each problem.
+
+---
+
+## Block 2: CUSTOMER SEGMENTS
+
+> Who has these problems? Be specific.
+
+Ask for:
+- **Target customer:** Describe them. Job title, company size, situation.
+- **Early adopters:** Who has this problem the WORST? Who would try your product even if it's rough?
+
+**Push back if:**
+- "Everyone" or "all businesses" — that's not a segment
+- Too broad — "developers" has millions of sub-segments
+- No early adopter identified — you need to know who your first 10 users are
+
+---
+
+## Block 3: UNIQUE VALUE PROPOSITION
+
+> Single clear message: why are you different and worth buying?
+
+This is the hardest block. The UVP must:
+- Be one sentence
+- A stranger should understand it in 5 seconds
+- Say what you do AND why it matters
+- Not be generic ("best-in-class solution for your needs" — garbage)
+
+**Formula:** [End result customer wants] + [specific time period] + [address their objection]
+**Example:** "Get a clean inbox in 5 minutes a day — no rules to set up"
+
+Ask the user to write it. Then test it: **"If I read this on a landing page with no other context, would I get it?"**
+
+Rewrite together until it passes the 5-second test.
+
+---
+
+## Block 4: SOLUTION
+
+> Top 3 features that solve the top 3 problems.
+
+Map each solution to a problem from Block 1:
+- Problem 1 → Feature A
+- Problem 2 → Feature B
+- Problem 3 → Feature C
+
+**Push back if:**
+- More than 3 features — you're overbuilding v1
+- Features don't clearly map to problems
+- Features are "infrastructure" nobody sees — users care about outcomes, not architecture
+
+---
+
+## Block 5: CHANNELS
+
+> How do you reach your customers?
+
+Ask about each stage:
+- **Awareness:** How do they find out you exist? (SEO, ads, word of mouth, content, communities)
+- **Evaluation:** How do they decide to try you? (free trial, demo, reviews, referrals)
+- **Purchase:** How do they buy? (self-serve, sales call, app store)
+
+**Push back if:**
+- "We'll go viral" — that's not a channel, that's a wish
+- No specific plan — "social media" means nothing without knowing WHICH platform and WHAT content
+- Only paid channels with no budget — SEO and content take months, ads take money
+
+---
+
+## Block 6: REVENUE STREAMS
+
+> How do you make money?
+
+Ask:
+- **Pricing model:** Subscription? One-time? Usage-based? Freemium?
+- **Price point:** What would you charge? What are alternatives charging?
+- **Who pays:** Is the user the buyer, or do they need to convince a boss?
+
+**Push back if:**
+- "We'll figure out monetization later" — at least have a theory
+- Price is wildly different from alternatives with no justification
+- Revenue model doesn't match user behavior (charging subscription for something they use once a year)
+
+---
+
+## Block 7: COST STRUCTURE
+
+> What does it cost to run this business?
+
+Ask about:
+- **Fixed costs:** Hosting, salaries, tools, subscriptions
+- **Variable costs:** Per-user costs, API calls, support
+- **What's most expensive?** Usually it's time (your time building it)
+
+Keep it simple. Ballpark numbers are fine at this stage.
+
+---
+
+## Block 8: KEY METRICS
+
+> What numbers tell you it's working?
+
+Use the **AARRR framework** (Pirate Metrics):
+
+| Metric | Question | Your Number |
+|---|---|---|
+| **Acquisition** | How many people visit/sign up? | |
+| **Activation** | How many have a good first experience? | |
+| **Retention** | How many come back? | |
+| **Revenue** | How many pay? | |
+| **Referral** | How many invite others? | |
+
+**Push back if:**
+- Only tracking vanity metrics (page views, followers)
+- No retention metric — retention is the most important one
+- Too many metrics — pick 1-2 per stage that matter most
+
+---
+
+## Block 9: UNFAIR ADVANTAGE
+
+> What can't be easily copied or bought?
+
+Real unfair advantages:
+- Personal authority / reputation in the space
+- Network effects (product gets better with more users)
+- Community / audience you already have
+- Proprietary data or technology
+- Domain expertise from years in the industry
+- Existing relationships with target customers
+
+**"Nothing" is an honest answer.** Most startups don't have an unfair advantage yet. That's okay — acknowledge it and figure out how to build one over time.
+
+**Push back if:**
+- "Our technology" — code can be copied
+- "First mover" — rarely lasts
+- "Our team" — teams change
+
+---
+
+## Complete Canvas
+
+After all 9 blocks, show the complete canvas in a formatted table:
+
+```
+## Lean Canvas: [product name]
+
+| PROBLEM              | SOLUTION             | UVP                  |
+| 1.                   | 1.                   |                      |
+| 2.                   | 2.                   |                      |
+| 3.                   | 3.                   |                      |
+|                      |                      |                      |
+| Existing alternatives| KEY METRICS          | UNFAIR ADVANTAGE     |
+| -                    |                      |                      |
+| -                    |                      |                      |
+|                      |                      |                      |
+| CHANNELS             | CUSTOMER SEGMENTS    |                      |
+| -                    | Target:              |                      |
+| -                    | Early adopter:       |                      |
+|                      |                      |                      |
+| COST STRUCTURE       | REVENUE STREAMS      |                      |
+| -                    | Model:               |                      |
+| -                    | Price:               |                      |
+```
+
+---
+
+## Top 3 Riskiest Assumptions
+
+After showing the canvas, identify the 3 riskiest assumptions. These are things the canvas assumes to be true but haven't been proven yet.
+
+For each one:
+1. **The assumption:** What are we assuming?
+2. **Why it's risky:** What happens if it's wrong?
+3. **How to test it:** The cheapest, fastest experiment to validate or kill it
+
+**Example:**
+- **Assumption:** "Freelancers will pay $20/month for this"
+- **Risk:** Maybe they use free tools and won't pay
+- **Test:** Put up a landing page with a "Buy" button. See if anyone clicks. Run for 2 weeks.
+
+---
+
+**Next step:** Validate your riskiest assumption first. Run `/spartan:interview` to talk to real users, or `/spartan:validate` to score the overall idea.

package/commands/spartan/lint-rules.md

@@ -0,0 +1,122 @@
+---
+name: spartan:lint-rules
+description: Validate your .spartan/config.yaml and rule files — check format, paths, and completeness
+argument-hint: ""
+preamble-tier: 2
+---
+
+# Lint Rules
+
+You are a **config validator**. You check that `.spartan/config.yaml` and its rule files are valid and ready for the reviewer.
+
+This is a quick check — should finish in seconds. Don't read full file contents, just check existence and basic format.
+
+---
+
+## Step 1: Find config
+
+```bash
+ls .spartan/config.yaml 2>/dev/null
+```
+
+If the file doesn't exist:
+
+> No config found. Run `/spartan:init-rules` to create one.
+
+Stop here.
+
+---
+
+## Step 2: Validate config format
+
+Read `.spartan/config.yaml` and check:
+
+| Check | What to look for |
+|-------|-----------------|
+| Valid YAML | No syntax errors, file parses correctly |
+| `stack` field | Must exist (e.g., `kotlin-micronaut`, `react-nextjs`, `custom`) |
+| `rules` section | Must have at least one group: `shared`, `backend`, or `frontend` |
+| `file-types` section | Should map extensions to modes |
+| `review-stages` section | Should have at least one stage |
+| `extends` + overrides | If `rules-add`, `rules-remove`, or `rules-override` is set, `extends` must also be set |
+| No duplicate rule paths | Same path shouldn't appear twice in any group |
+
+---
+
+## Step 3: Validate rule files
+
+For each rule path listed in the config:
+
+1. **Does the file exist?** Check in order:
+   - Project root (relative path)
+   - `.claude/` directory
+   - `~/.claude/` (global)
+2. **Is it a `.md` file?**
+3. **Does it have a `#` title on the first non-empty line?**
+4. **Is it non-empty?**
+5. **Does it have code examples?** (Look for triple-backtick blocks. Recommended but not required.)
+
+---
+
+## Step 4: Check review stages
+
+- Are all stage names non-empty strings?
+- Is at least one stage `enabled: true`?
+- Are there duplicate stage names?
+
+---
+
+## Step 5: Check build commands
+
+If `commands.test.backend` or `commands.test.frontend` is set:
+- Does it look like a real command? (not empty string, not just whitespace)
+- Same check for `commands.build.*` and `commands.lint.*`
+
+Don't run the commands — just check they're not blank if defined.
+
+---
+
+## Step 6: Report
+
+Print the report using this format:
+
+```
+Checking .spartan/config.yaml...
+
+Config format:
+  ✅ Valid YAML
+  ✅ Stack: go-standard
+  ✅ Architecture: clean
+  ✅ 5 backend rules, 0 frontend rules, 1 shared rule
+
+Rule files:
+  ✅ rules/go/ERROR_HANDLING.md — found, valid
+  ✅ rules/go/INTERFACES.md — found, valid
+  ❌ rules/go/CONCURRENCY.md — file not found (create it or remove from config)
+  ⚠️ rules/go/TESTING.md — no code examples (recommended)
+
+Review stages:
+  ✅ 7 stages configured, all enabled
+
+Commands:
+  ✅ test: go test ./...
+  ✅ build: go build ./...
+  ✅ lint: golangci-lint run
+
+Result: {N} errors, {M} warnings
+```
+
+**If errors exist:**
+> Fix the errors above. The reviewer can't read missing rule files.
+
+**If clean:**
+> All good. Your rules are ready for `/spartan:build` and `/spartan:review`.
+
+---
+
+## Rules for this command
+
+- **Fast**: This is a lint check. Don't read full rule file contents — just check existence, first line, and look for backtick blocks.
+- **Helpful on errors**: For missing files, say "create it or remove from config." Don't just say "not found."
+- **No changes**: This command only reports. It doesn't fix anything. Tell the user what to fix.
+- **Preamble-tier 2**: Light context. No heavy scanning needed.

package/commands/spartan/map-codebase.md

@@ -0,0 +1,124 @@
+---
+name: spartan:map-codebase
+description: Deep codebase analysis with parallel agents. Produces 7 structured documents covering stack, architecture, conventions, testing, integrations, and concerns. Use before major refactoring, milestone planning, or team onboarding.
+argument-hint: "[optional: focus area e.g. 'auth' or 'api']"
+---
+
+# Map Codebase: {{ args[0] | default: "full analysis" }}
+
+You are performing a **deep codebase analysis** using parallel mapper agents. This produces structured documentation that feeds into GSD planning and execution.
+
+---
+
+## When to Use This vs /spartan:brownfield
+
+| Command | Purpose | Output | Depth |
+|---------|---------|--------|-------|
+| `/spartan:brownfield` | Quick onboarding overview | 1 file: CONTEXT-MAP.md | Surface-level, 10 min |
+| `/spartan:map-codebase` | Deep technical analysis | 7 files in .planning/codebase/ | Thorough, 4 parallel agents |
+
+**Use brownfield** when joining a project for the first time and need a quick overview.
+**Use map-codebase** when preparing for major work: refactoring, new milestone, architecture review, or team onboarding docs.
+
+---
+
+## What Gets Produced
+
+7 documents in `.planning/codebase/`:
+
+| Document | Focus | What It Captures |
+|----------|-------|-----------------|
+| `STACK.md` | Tech | Languages, frameworks, dependencies, build tools, runtime |
+| `INTEGRATIONS.md` | Tech | External APIs, databases, auth providers, webhooks, env vars |
+| `ARCHITECTURE.md` | Architecture | Patterns, layers, data flow, entry points, error handling |
+| `STRUCTURE.md` | Architecture | Directory layout, key file locations, where to add new code |
+| `CONVENTIONS.md` | Quality | Code style, naming patterns, import organization, formatting |
+| `TESTING.md` | Quality | Test framework, patterns, coverage, mocking, fixtures |
+| `CONCERNS.md` | Concerns | Tech debt, known bugs, security risks, fragile areas, scaling limits |
+
+All documents include **file paths in backticks** so Claude can navigate directly to relevant code during planning and execution.
+
+---
+
+## Execution
+
+### Agent Teams boost (if enabled)
+
+```bash
+echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not_set}"
+```
+
+**If Agent Teams is enabled**, use a coordinated mapping team (NOT sub-agents):
+
+```
+TeamCreate(team_name: "map-{project-slug}", description: "Deep codebase analysis")
+
+TaskCreate(subject: "Map tech stack + integrations", description: "Write STACK.md + INTEGRATIONS.md to .planning/codebase/")
+TaskCreate(subject: "Map architecture + structure", description: "Write ARCHITECTURE.md + STRUCTURE.md to .planning/codebase/")
+TaskCreate(subject: "Map conventions + testing", description: "Write CONVENTIONS.md + TESTING.md to .planning/codebase/")
+TaskCreate(subject: "Map concerns", description: "Write CONCERNS.md to .planning/codebase/")
+
+Agent(
+  team_name: "map-{project-slug}",
+  name: "tech-mapper",
+  subagent_type: "Explore",
+  prompt: "Write STACK.md and INTEGRATIONS.md to .planning/codebase/.
+    Include file paths in backticks. Check TaskList, claim your task.
+    If you find security concerns, message concerns-mapper via SendMessage."
+)
+
+Agent(
+  team_name: "map-{project-slug}",
+  name: "arch-mapper",
+  subagent_type: "Explore",
+  prompt: "Write ARCHITECTURE.md and STRUCTURE.md to .planning/codebase/.
+    Trace data flow end-to-end. Check TaskList, claim your task."
+)
+
+Agent(
+  team_name: "map-{project-slug}",
+  name: "quality-mapper",
+  subagent_type: "Explore",
+  prompt: "Write CONVENTIONS.md and TESTING.md to .planning/codebase/.
+    Find patterns, code style, test coverage. Check TaskList, claim your task."
+)
+
+Agent(
+  team_name: "map-{project-slug}",
+  name: "concerns-mapper",
+  subagent_type: "Explore",
+  prompt: "Write CONCERNS.md to .planning/codebase/.
+    Find tech debt, bugs, security risks, fragile areas. Check TaskList, claim your task."
+)
+```
+
+After all teammates complete, verify 7 documents exist and are non-empty, then `TeamDelete()`.
+
+**If Agent Teams is NOT enabled**, delegate to GSD:
+
+**Run this command now:**
+
+```
+/gsd:map-codebase {{ args[0] }}
+```
+
+GSD will:
+1. Check for existing maps in `.planning/codebase/` (offer refresh/skip if found)
+2. Spawn 4 parallel mapper agents (tech, arch, quality, concerns)
+3. Each agent writes documents directly to `.planning/codebase/`
+4. Verify all 7 documents exist and are non-empty
+5. Scan for accidentally leaked secrets
+6. Commit results
+
+---
+
+## After Mapping
+
+Once mapping is complete, suggest next steps based on context:
+
+- **Starting a new project?** → `/spartan:project new` (map feeds into roadmap creation)
+- **Planning a phase?** → `/spartan:phase plan N` (agents read codebase docs automatically)
+- **Major refactoring?** → `/spartan:spec "refactor description"` → `/spartan:build` (informed by CONCERNS.md)
+- **Team onboarding?** → Share `.planning/codebase/` docs with new team members
+
+The codebase map is consumed automatically by GSD planning and execution agents — no manual wiring needed.

package/commands/spartan/migration.md

@@ -0,0 +1,82 @@
+---
+name: spartan:migration
+description: Create a database migration script following company DATABASE_RULES (TEXT not VARCHAR, no FK, soft deletes, UUID PKs)
+argument-hint: "[description of the migration]"
+---
+
+Create a migration for: {{ args[0] }}
+
+**Before creating, read:** `rules/database/SCHEMA.md`
+
+## Hard Rules (from DATABASE_RULES)
+- **TEXT not VARCHAR** — always
+- **No REFERENCES / foreign keys** — handle at application level
+- **No CASCADE** — handle deletions in application
+- **UUID primary keys** — `gen_random_uuid()`
+- **Soft delete** — `deleted_at TIMESTAMP`, never hard delete
+- **Standard columns** on every table: `id`, `created_at`, `updated_at`, `deleted_at`
+
+## Steps
+
+1. **Find the next migration version**:
+   ```bash
+   ls src/main/resources/db/migration/ | sort | tail -5
+   ```
+   Use the next version number (e.g., if last is V7, create V8).
+
+2. **Create the migration file**:
+   Path: `src/main/resources/db/migration/V{N}__{snake_case_description}.sql`
+
+3. **Template for new table**:
+```sql
+-- Migration: {{ args[0] }}
+-- Reason: [explain business need]
+
+CREATE TABLE IF NOT EXISTS table_name (
+    id          UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
+    -- business columns here (always TEXT, never VARCHAR)
+    name        TEXT        NOT NULL,
+    status      TEXT        NOT NULL DEFAULT 'active',
+    description TEXT,
+    -- NO REFERENCES / FOREIGN KEYS — handle at application level
+    -- standard columns (required on ALL tables)
+    created_at  TIMESTAMP   NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at  TIMESTAMP   NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    deleted_at  TIMESTAMP
+);
+
+CREATE INDEX idx_table_name_column ON table_name(column);
+CREATE INDEX idx_table_name_deleted_at ON table_name(deleted_at);
+
+-- Auto-update updated_at trigger
+CREATE OR REPLACE FUNCTION update_updated_at_column()
+RETURNS TRIGGER AS $$
+BEGIN NEW.updated_at = CURRENT_TIMESTAMP; RETURN NEW; END;
+$$ language 'plpgsql';
+
+CREATE TRIGGER update_table_name_updated_at
+    BEFORE UPDATE ON table_name
+    FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
+
+-- To rollback:
+-- DROP TABLE IF EXISTS table_name;
+```
+
+4. **Template for ALTER TABLE**:
+```sql
+-- Migration: {{ args[0] }}
+
+ALTER TABLE existing_table
+    ADD COLUMN IF NOT EXISTS new_column TEXT,
+    ADD COLUMN IF NOT EXISTS another_col BOOLEAN NOT NULL DEFAULT false;
+
+-- To rollback:
+-- ALTER TABLE existing_table DROP COLUMN IF EXISTS new_column;
+```
+
+5. **After creating, also generate Exposed Table object** using `/database-table-creator` skill if this is a new table.
+
+After creating, verify:
+```bash
+./gradlew flywayValidate
+```