@c0x12c/ai-toolkit 1.15.0

package/commands/spartan/init-rules.md

@@ -0,0 +1,298 @@
+---
+name: spartan:init-rules
+description: Set up configurable rules — interactive wizard that generates .spartan/config.yaml
+argument-hint: "[optional: profile name like go-standard or python-fastapi]"
+preamble-tier: 3
+---
+
+# Init Rules: {{ args[0] | default: "interactive setup" }}
+
+You are an **interactive config wizard**. Walk the user through setting up `.spartan/config.yaml` for their project. This file tells the toolkit which rules, review stages, and build commands to use.
+
+Keep questions short. Always recommend a default. One decision per turn.
+
+---
+
+## Step 0: Check Existing Config
+
+```bash
+ls .spartan/config.yaml 2>/dev/null && echo "CONFIG_EXISTS" || echo "NO_CONFIG"
+```
+
+**If config exists:**
+
+> You already have a config at `.spartan/config.yaml`.
+>
+> What do you want to do?
+>   A) Start fresh — wipe and reconfigure from scratch (recommended if it's outdated)
+>   B) Edit existing — I'll walk through each section, keep what's good
+>   C) Cancel — keep current config
+>
+> I'd go with A if you're not sure what's in there.
+
+- If **A**: continue to Step 1 (will overwrite at the end)
+- If **B**: read the existing config, then walk through Step 3 with current values as defaults
+- If **C**: stop here
+
+**If no config exists:** continue to Step 1.
+
+---
+
+## Step 1: Detect Stack (silent — don't ask questions yet)
+
+Scan the project to figure out what stack is being used:
+
+```bash
+# Build tools & frameworks
+ls build.gradle.kts settings.gradle.kts 2>/dev/null && echo "DETECTED:kotlin"
+ls pom.xml 2>/dev/null && echo "DETECTED:java"
+ls go.mod 2>/dev/null && echo "DETECTED:go"
+ls requirements.txt pyproject.toml setup.py 2>/dev/null && echo "DETECTED:python"
+ls package.json 2>/dev/null && echo "DETECTED:node"
+
+# Framework specifics
+cat build.gradle.kts 2>/dev/null | grep -qi "micronaut" && echo "FRAMEWORK:micronaut"
+cat build.gradle.kts 2>/dev/null | grep -qi "spring" && echo "FRAMEWORK:spring"
+cat pom.xml 2>/dev/null | grep -qi "spring-boot" && echo "FRAMEWORK:spring"
+cat package.json 2>/dev/null | grep -q '"next"' && echo "FRAMEWORK:nextjs"
+cat package.json 2>/dev/null | grep -q '"express"' && echo "FRAMEWORK:express"
+cat package.json 2>/dev/null | grep -q '"fastify"' && echo "FRAMEWORK:fastify"
+cat requirements.txt pyproject.toml 2>/dev/null | grep -qi "django" && echo "FRAMEWORK:django"
+cat requirements.txt pyproject.toml 2>/dev/null | grep -qi "fastapi" && echo "FRAMEWORK:fastapi"
+
+# Database
+ls src/main/resources/db/migration/ 2>/dev/null && echo "DB:flyway"
+cat docker-compose.yml 2>/dev/null | grep -E "postgres|mysql|mongo|redis" 2>/dev/null
+cat package.json 2>/dev/null | grep -E "prisma|typeorm|drizzle" 2>/dev/null
+
+# Test frameworks
+cat build.gradle.kts 2>/dev/null | grep -qi "kotest\|junit" && echo "TEST:kotlin"
+cat package.json 2>/dev/null | grep -E "vitest|jest|mocha" 2>/dev/null
+ls pytest.ini pyproject.toml 2>/dev/null | xargs grep -l "pytest" 2>/dev/null && echo "TEST:pytest"
+```
+
+Show the user what you found:
+
+> **Detected:** [language] + [framework], [test framework], [database if found]
+
+---
+
+## Step 2: Pick a Profile
+
+If the user passed a profile argument (e.g., `/spartan:init-rules go-standard`), use `{{ args[0] }}` directly. Skip the menu — jump to Step 3.
+
+Otherwise, show the menu:
+
+> Pick a profile to start from:
+>
+>   A) **kotlin-micronaut** -- Kotlin + Micronaut (thin controllers, Either errors, Exposed ORM)
+>   B) **react-nextjs** -- React + Next.js (App Router, Server Components, Vitest)
+>   C) **go-standard** -- Go (clean arch, table-driven tests, golangci-lint)
+>   D) **python-django** -- Python + Django (models, views, pytest-django)
+>   E) **python-fastapi** -- Python + FastAPI (async, Pydantic, dependency injection)
+>   F) **java-spring** -- Java + Spring Boot (@RestController, JPA, @SpringBootTest)
+>   G) **typescript-node** -- TypeScript + Node.js (Express/Fastify, Zod, strict mode)
+>   H) **custom** -- Start from blank, I'll configure everything myself
+>
+> I'd go with **[detected option]** based on your project files.
+
+Wait for the user to pick before continuing.
+
+---
+
+## Step 3: Customize
+
+Walk through these questions **one at a time**. Pre-fill answers from the chosen profile.
+
+### 3a: Architecture Style
+
+Based on the stack, show 2-3 options with a default:
+
+**For Kotlin / Java:**
+> Architecture style?
+>   A) Layered (Controller -> Manager -> Repository) -- recommended for most projects
+>   B) Hexagonal (ports & adapters)
+>   C) Custom -- I'll describe my own
+
+**For Go:**
+> Architecture style?
+>   A) Clean Architecture (handler -> usecase -> repository) -- recommended
+>   B) Flat (single package per service)
+>   C) Custom
+
+**For Python (Django):**
+> Architecture style?
+>   A) MVC (views -> models -> managers) -- recommended
+>   B) Clean Architecture
+>   C) Custom
+
+**For Python (FastAPI):**
+> Architecture style?
+>   A) Layered (router -> service -> repository) -- recommended
+>   B) Clean Architecture
+>   C) Custom
+
+**For React / Next.js:**
+> Architecture style?
+>   A) Feature-based (feature folders with components, hooks, types) -- recommended
+>   B) Layered (pages -> components -> hooks -> services)
+>   C) Custom
+
+**For TypeScript + Node.js:**
+> Architecture style?
+>   A) Layered (controller -> service -> repository) -- recommended
+>   B) Clean Architecture
+>   C) Custom
+
+### 3b: Review Stages
+
+Show the 7 default stages:
+
+> These stages run during build review. Remove any you don't need.
+>
+> 1. **correctness** -- Does the code match the spec? Edge cases?
+> 2. **stack-conventions** -- Follows stack patterns and idioms
+> 3. **test-coverage** -- Tests exist, are independent, cover edge cases
+> 4. **architecture** -- Proper layer separation
+> 5. **database-api** -- Schema rules, API design, input validation
+> 6. **security** -- Auth, injection, data exposure
+> 7. **documentation-gaps** -- New patterns that should be documented
+>
+> These are all on by default. Type the numbers to remove (e.g., "5, 7") or say "keep all".
+
+### 3c: Custom Rules
+
+> Have any extra rules you want to add? These are markdown files with your team's coding standards.
+>
+> Give me the file paths (relative to project root), or say "no".
+>
+> Example: `rules/OUR_API_RULES.md`, `docs/coding-standards.md`
+
+### 3d: Build Commands
+
+Pre-fill from the chosen profile. Let the user edit.
+
+**For Kotlin / Micronaut:**
+> Build commands -- edit if these aren't right:
+> - Test: `./gradlew test`
+> - Build: `./gradlew build`
+> - Lint: `./gradlew ktlintCheck`
+
+**For React / Next.js:**
+> Build commands -- edit if these aren't right:
+> - Test: `npm test` (or `yarn vitest`)
+> - Build: `npm run build`
+> - Lint: `npm run lint`
+
+**For Go:**
+> Build commands -- edit if these aren't right:
+> - Test: `go test ./...`
+> - Build: `go build ./...`
+> - Lint: `golangci-lint run`
+
+**For Python (Django):**
+> Build commands -- edit if these aren't right:
+> - Test: `pytest`
+> - Build: `python manage.py check`
+> - Lint: `ruff check .`
+
+**For Python (FastAPI):**
+> Build commands -- edit if these aren't right:
+> - Test: `pytest`
+> - Build: `python -m py_compile main.py`
+> - Lint: `ruff check .`
+
+**For Java / Spring:**
+> Build commands -- edit if these aren't right:
+> - Test: `./mvnw test` (or `./gradlew test`)
+> - Build: `./mvnw package` (or `./gradlew build`)
+> - Lint: `./mvnw checkstyle:check`
+
+**For TypeScript / Node.js:**
+> Build commands -- edit if these aren't right:
+> - Test: `npm test`
+> - Build: `npm run build`
+> - Lint: `npm run lint`
+
+**For custom:** ask the user to fill in all three from scratch.
+
+---
+
+## Step 4: Generate Config
+
+Build the `.spartan/config.yaml` file from the user's answers.
+
+```bash
+mkdir -p .spartan
+```
+
+Write `.spartan/config.yaml` using this structure (based on the template at `toolkit/templates/spartan-config.yaml`):
+
+```yaml
+# .spartan/config.yaml — Generated by /spartan:init-rules
+# Validate: /spartan:lint-rules
+# Auto-detect rules from code: /spartan:scan-rules
+
+# ─── Stack & Architecture ───────────────────────────────────────────
+
+stack: [chosen-profile]
+architecture: [chosen-architecture]
+
+# ─── Rules ──────────────────────────────────────────────────────────
+
+rules:
+  shared: []
+    # Add rules that apply to both backend and frontend
+
+  backend: []
+    # Add backend-specific rules
+
+  frontend: []
+    # Add frontend-specific rules
+
+# ─── File Type Mapping ──────────────────────────────────────────────
+
+file-types:
+  backend: [extensions based on stack]
+  frontend: [".tsx", ".ts", ".jsx", ".js", ".vue", ".svelte"]
+  migration: [".sql"]
+  config: [".yaml", ".yml", ".json", ".toml"]
+
+# ─── Review Stages ──────────────────────────────────────────────────
+
+review-stages:
+  [only include stages the user kept enabled]
+
+# ─── Build Commands ─────────────────────────────────────────────────
+
+commands:
+  test:
+    backend: "[from 3d]"
+    frontend: "[from 3d]"
+  build:
+    backend: "[from 3d]"
+    frontend: "[from 3d]"
+  lint:
+    backend: "[from 3d]"
+    frontend: "[from 3d]"
+```
+
+If the user gave custom rule paths in Step 3c, add them to the right section (`shared`, `backend`, or `frontend` — ask which if unclear).
+
+Show the full generated config to the user for a final check:
+
+> Here's your config. Look good?
+
+If they want changes, edit and show again. If they're happy, write the file.
+
+> Config saved to `.spartan/config.yaml`.
+
+---
+
+## Step 5: Next Steps
+
+> What's next:
+> - **Write your own rules** -- create markdown files and add paths to the `rules:` section
+> - **Scan your code for patterns** -- `/spartan:scan-rules` (auto-detects conventions from code)
+> - **Validate your config** -- `/spartan:lint-rules` (checks for broken paths and format issues)
+> - **Build a feature** -- `/spartan:build` (will pick up your new config automatically)

package/commands/spartan/interview.md

@@ -0,0 +1,154 @@
+---
+name: spartan:interview
+description: Generate Mom Test interview questions — talk about their life, not your idea
+argument-hint: "[product or feature name]"
+---
+
+# Interview Script: {{ args[0] | default: "your product" }}
+
+You are generating a user interview script based on **The Mom Test** by Rob Fitzpatrick.
+
+The core idea: even your mom will lie to you about your startup idea. So don't ask about your idea — ask about their life.
+
+---
+
+## The Mom Test Rules (ALWAYS enforce these)
+
+1. **Talk about their life, not your idea.** Don't pitch. Don't describe what you're building. Ask about what they do today.
+2. **Ask about specifics in the past, not generics or the future.** "Tell me about the last time you..." beats "Would you ever..."
+3. **Talk less, listen more.** If you're talking more than 30% of the time, you're doing it wrong.
+
+---
+
+## Red Flags (print these as warnings in the script)
+
+| Red Flag | What It Really Means | What to Do Instead |
+|---|---|---|
+| "That sounds great!" | They're being polite | Ask: "When was the last time you had this problem?" |
+| "I would definitely use that" | Future promises are worthless | Ask: "What did you do LAST TIME this happened?" |
+| "Yeah, that's a problem" | Generic agreement, no signal | Ask: "Can you walk me through the last time?" |
+| "I'd pay for that" | Talk is cheap | Ask: "How much do you spend on [current solution] now?" |
+| They change the subject | They don't actually care | Note it. This problem isn't top of mind for them. |
+
+---
+
+## Generate the Interview Script
+
+Based on {{ args[0] }}, generate a ready-to-use script. Ask the user first:
+
+> **"In 1-2 sentences, what problem does {{ args[0] }} solve and who has this problem?"**
+
+Then generate the full script:
+
+---
+
+### Opening (~2 min)
+
+**Goal:** Build rapport. Set the frame. Don't bias them.
+
+Script:
+```
+"Thanks for taking the time. I'm trying to understand how people
+deal with [problem area — NOT your solution]. I'm not selling anything.
+I just want to learn about your experience.
+
+There are no right or wrong answers. I'm most interested in stories
+about what you actually do day to day."
+```
+
+**DO NOT** say: "I'm building X and want your feedback." That biases everything.
+
+---
+
+### Group 1: Understanding Their World (5 questions)
+
+**Goal:** Understand their current workflow. What do they do today?
+
+1. "Can you walk me through how you handle [problem area] right now?"
+2. "What does a typical [day/week] look like when you're dealing with this?"
+3. "What tools or processes do you use for this today?"
+4. "What's the most annoying part of how you do this now?"
+5. "If you could wave a magic wand and fix one thing about this, what would it be?"
+
+**For each answer:** Follow up with "Can you give me a specific example?" and "When was the last time that happened?"
+
+---
+
+### Group 2: Finding the Pain (4 questions)
+
+**Goal:** How bad is the problem? Are they actively trying to fix it?
+
+6. "How often does [the problem] come up? Daily? Weekly? Monthly?"
+7. "The last time this happened, what did you do? Walk me through it step by step."
+8. "Have you tried to find a better way to handle this? What did you try?"
+9. "Have you spent any money trying to solve this? How much?"
+
+**Key signal:** If they haven't tried to solve it or spent money on it, the pain might not be bad enough.
+
+---
+
+### Group 3: Checking Importance (5 questions)
+
+**Goal:** Is this a top-3 problem or just a minor annoyance?
+
+10. "Where does this problem rank in your list of headaches? Top 3? Top 10?"
+11. "If this problem disappeared tomorrow, how much would your life change?"
+12. "What other problems compete for your attention and budget right now?"
+13. "Have you ever started fixing this and then stopped? Why?"
+14. "If someone solved this for you, what would that free you up to do?"
+
+**Key signal:** If it's not in their top 3, they won't pay for a solution or change their behavior.
+
+---
+
+### Closing (~2 min)
+
+**Goal:** Get referrals and next steps.
+
+Script:
+```
+"This has been really helpful. A couple more quick things:
+
+- Is there anything about [problem area] that I should have asked
+  but didn't?
+- Do you know 2-3 other people who deal with this same problem?
+  I'd love to talk to them too.
+- Would it be okay if I followed up in a few weeks with a quick update?"
+```
+
+---
+
+## Scoring Rubric
+
+After the interview, score the signal strength:
+
+| Signal | Score | What It Means |
+|---|---|---|
+| They described the problem with emotion and detail | STRONG | Real pain, they care |
+| They've spent money or significant time trying to solve it | STRONG | Willing to pay |
+| They asked YOU when it would be ready | STRONG | Pull signal — they want this |
+| They offered to introduce you to others with the problem | STRONG | They think this matters |
+| They gave generic answers, no specific stories | WEAK | Problem might not be real for them |
+| They were polite but didn't share any struggles | WEAK | No pain here |
+| They said "cool idea" but had no personal experience | NONE | Wrong person or wrong problem |
+
+### After the Interview
+
+Count your signals:
+
+- **3+ STRONG signals** = This problem is real. Keep digging with more interviews.
+- **1-2 STRONG signals** = Promising but need more data. Interview 3-5 more people.
+- **0 STRONG signals** = Wrong person or wrong problem. Try a different audience or rethink.
+
+---
+
+## Output
+
+Show the user:
+1. The complete interview script (ready to print/copy)
+2. The red flags cheat sheet (keep it visible during the interview)
+3. The scoring rubric (fill in after each interview)
+
+**Remind the user:** Talk to at least 5 people before making any decisions. One interview is not enough data.
+
+**Next step:** After 5+ interviews, run `/spartan:validate` to score the idea based on what you learned.

package/commands/spartan/kickoff.md

@@ -0,0 +1,73 @@
+---
+name: spartan:kickoff
+description: "Start a new idea: create project folder, brainstorm, then validate top picks (Stages 1-2)"
+argument-hint: "[theme or problem space]"
+preamble-tier: 3
+---
+
+# Kickoff: {{ args[0] | default: "new idea" }}
+
+Runs Brainstorm + Validate back to back. Gets you to a GO / PASS decision fast.
+
+If the user already has a specific idea (not a theme), skip brainstorm and go straight to validate.
+
+---
+
+## Step 1: Setup
+
+Create project folder with stage subfolders:
+
+```bash
+mkdir -p "projects/{{ args[0] | default: "new-idea" }}"/{01-brainstorm,02-interviews,03-validation,04-research,05-pitch}
+```
+
+---
+
+## Step 2: Brainstorm
+
+Run `/spartan:brainstorm {{ args[0] | default: "" }}` internally — don't tell the user to run it separately.
+
+This will:
+1. Set the frame: space, target user, limits, goal
+2. Generate 8-15 ideas
+3. Rate each: demand signal, buildability, moat (0-5)
+4. Pick top 3
+5. Save to `projects/{{ args[0] }}/01-brainstorm/brainstorm-session.md`
+
+### Gate 1
+
+Show top 3 to user. Ask:
+> "Which ones should I validate? Or brainstorm more?"
+
+Wait for answer before continuing.
+
+---
+
+## Step 3: Validate
+
+Run `/spartan:validate` internally for each picked idea.
+
+This will:
+1. Problem check (real pain or nice-to-have?)
+2. Quick market check
+3. Quick competitor check
+4. Distribution check
+5. Build check
+6. Give verdict: GO / TEST MORE / PASS
+7. Save to `projects/{{ args[0] }}/03-validation/validation-{idea-name}.md`
+
+### Gate 2
+
+Show verdicts:
+- If any **GO**: "Want me to run `/spartan:deep-dive` on this?"
+- If all **PASS**: "These didn't make it. Want to `/spartan:brainstorm` a different space?"
+- If **TEST MORE**: "Here's the cheapest test for each. Try those first."
+
+---
+
+## Rules
+
+- Don't rush through gates. Pause and ask.
+- It's fine if nothing passes. That saves months of building the wrong thing.
+- If the user already has a specific idea (not a theme), skip brainstorm and go straight to validate.
+- You are the orchestrator — run brainstorm and validate yourself, don't tell the user to chain commands.

package/commands/spartan/kotlin-service.md

@@ -0,0 +1,109 @@
+---
+name: spartan:kotlin-service
+description: Scaffold a new Kotlin Micronaut microservice following Spartan conventions and company rules
+argument-hint: "[service-name] [brief description]"
+---
+
+You are scaffolding a new Kotlin Micronaut microservice for the Spartan platform.
+
+**Before scaffolding, read these company rules:**
+- `rules/shared-backend/ARCHITECTURE.md` — Layered architecture
+- `rules/backend-micronaut/KOTLIN.md` — Kotlin conventions
+- `rules/database/SCHEMA.md` — Schema standards
+- `rules/backend-micronaut/API_DESIGN.md` — API design patterns
+
+## Service: {{ args[0] }}
+## Purpose: {{ args[1] }}
+
+Follow these steps exactly:
+
+### 1. Gather Context
+Ask the user:
+- What domain events does this service produce/consume?
+- What external dependencies (DB, Kafka, Redis, HTTP clients)?
+- What are the main domain entities?
+- Any specific SLA requirements?
+
+**Auto mode on?** → Infer from service name and description. Default: PostgreSQL, no Kafka, no Redis, standard REST. Proceed to scaffold immediately.
+**Auto mode off?** → Wait for answers before proceeding.
+
+### 2. Scaffold Directory Structure
+
+Create the following structure under `src/main/kotlin/com/spartan/{{ args[0] }}/`:
+
+```
+controller/        # @Controller classes, @Secured, @ExecuteOn
+manager/           # Business logic interfaces + implementations (returns Either)
+service/           # External API calls (HTTP clients)
+repository/        # Database access (Exposed ORM)
+model/             # Entities, DTOs, enums, value objects
+config/            # Micronaut configuration classes
+```
+
+### 3. Create Base Files
+
+**build.gradle.kts** — include:
+- io.micronaut:micronaut-http-server-netty
+- org.jetbrains.exposed:exposed-core
+- io.micronaut:micronaut-management
+- kotlinx-coroutines-reactor
+- testcontainers (test scope)
+- kotest or junit5
+
+**application.yml** — with:
+- micronaut.application.name
+- management endpoints (`/health`, `/info`)
+- placeholder for datasource (use env vars: `DATASOURCES_DEFAULT_URL`, etc.)
+
+**Main Application class**:
+```kotlin
+fun main(args: Array<String>) {
+    Micronaut.run(Application::class.java, *args)
+}
+```
+
+**Base error handling** — use Arrow's Either (per CORE_RULES):
+```kotlin
+// All Manager methods return Either<ClientException, T>
+// NEVER use sealed class Result<T> — use Either instead
+// NEVER throw exceptions for business errors
+
+suspend fun findUser(id: UUID): Either<ClientException, UserResponse> {
+    val user = userRepository.findById(id)
+        ?: return UserError.NOT_FOUND.asException().left()
+    return user.toResponse().right()
+}
+```
+
+### 4. Create First Test
+
+Create `src/test/kotlin/.../ApplicationContextTest.kt`:
+```kotlin
+@MicronautTest
+class ApplicationContextTest {
+    @Test
+    fun `application context loads`() { }
+}
+```
+
+### 5. Create Flyway Migration
+
+If PostgreSQL is a dependency:
+- `src/main/resources/db/migration/V1__create_initial_schema.sql`
+- Include base tables for the main domain entities
+
+### 6. Docker Compose for local dev
+
+Create `docker-compose.yml` with:
+- postgres:16 with healthcheck
+- (if Kafka) confluentinc/cp-kafka with zookeeper
+
+### 7. README.md
+
+Include:
+- Service description
+- Local setup instructions
+- Environment variables table
+- Key architectural decisions
+
+After scaffolding, run the TDD skill to write the first domain test.