@c0x12c/ai-toolkit 1.15.0

package/commands/spartan/epic.md

@@ -0,0 +1,199 @@
+---
+name: spartan:epic
+description: Define an epic — break big work into ordered features with specs and plans
+argument-hint: "[epic name]"
+preamble-tier: 3
+---
+
+# Epic: {{ args[0] | default: "unnamed epic" }}
+
+You are running the **Epic workflow** — break a big piece of work into ordered features, each of which goes through the full spec → plan → build cycle.
+
+```
+► Epic → Spec → [Design] → Plan → Build → Review
+   ↑
+ start
+```
+
+The epic gets saved to `.planning/epics/{{ args[0] | default: "epic-name" }}.md`.
+
+---
+
+## Step 0: Setup
+
+```bash
+mkdir -p .planning/epics
+ls .planning/epics/{{ args[0] | default: "epic-name" }}.md 2>/dev/null
+```
+
+If it exists, ask:
+> "An epic for **{{ args[0] }}** already exists. Want to **update** it or **start fresh**?"
+>
+> - A) Update — I'll show the current epic and we'll revise
+> - B) Start fresh — overwrite
+
+---
+
+## Step 1: Understand the Big Picture
+
+Ask these questions **one at a time**:
+
+1. **"What are we building and why?"** — Get the big picture in 2-3 sentences. What outcome does this epic deliver?
+
+2. **"How do we know it's done?"** — Get 2-3 concrete success criteria. Not vague ("users are happy") — specific ("users can create and manage profiles").
+
+3. **"What are the main pieces?"** — Have the user list the features they can think of. Don't worry about order yet.
+
+4. **"Anything risky or tricky?"** — What could block the whole epic?
+
+---
+
+## Step 2: Break into Features
+
+Take the user's feature list and organize it:
+
+1. **Order by dependency.** Feature 2 shouldn't need Feature 5.
+2. **Keep features small.** Each should be 1-3 days of work. If one is bigger, split it.
+3. **Write a brief for each.** 2-3 sentences: what it does, why it matters, rough scope.
+
+Present as a table:
+
+```markdown
+| # | Feature | Depends On | Effort |
+|---|---------|------------|--------|
+| 1 | [name] | — | [S/M/L] |
+| 2 | [name] | #1 | [S/M/L] |
+| 3 | [name] | #1, #2 | [S/M/L] |
+```
+
+Ask:
+> "Here's how I'd order the features. Anything to change?"
+>
+> **Auto mode on?** → Show the order and continue.
+
+---
+
+## Step 3: Fill the Epic Document
+
+Use the `epic.md` template structure:
+
+```markdown
+# Epic: {{ args[0] }}
+
+**Created**: [today's date]
+**Status**: planning
+**Owner**: [user's name or "team"]
+
+---
+
+## Why
+
+[2-3 sentences from Step 1, question 1]
+
+---
+
+## Success Criteria
+
+- [ ] [from Step 1, question 2]
+- [ ] [criteria 2]
+- [ ] [criteria 3]
+
+---
+
+## Features
+
+| # | Feature | Status | Spec | Plan | Depends On |
+|---|---------|--------|------|------|------------|
+| 1 | [name] | todo | — | — | — |
+| 2 | [name] | todo | — | — | #1 |
+| 3 | [name] | todo | — | — | #1, #2 |
+
+---
+
+## Feature Briefs
+
+### Feature 1: [name]
+[2-3 sentences from Step 2]
+
+### Feature 2: [name]
+[2-3 sentences]
+
+---
+
+## Risks
+
+- [from Step 1, question 4]
+
+---
+
+## Notes
+
+- [anything else]
+```
+
+---
+
+## Step 4: Save and Confirm
+
+Save the epic to `.planning/epics/{{ args[0] | default: "epic-name" }}.md`.
+
+Then tell the user:
+
+> "Epic saved to `.planning/epics/{{ args[0] }}.md` with [N] features."
+>
+> **Next steps:**
+>
+> 1. Write specs for each feature (can do multiple before building):
+> ```
+> /spartan:spec [feature-1]
+> /spartan:spec [feature-2]
+> /spartan:ux prototype [feature-2]   ← if it has UI work
+> /spartan:spec [feature-3]
+> ```
+>
+> 2. When specs are ready, build the whole epic at once:
+> ```
+> /spartan:build {{ args[0] }}   ← builds all ready features, one branch, one PR
+> ```
+>
+> Build auto-detects the epic, plans all features together, parallelizes independent ones with Agent Teams, and ships one PR.
+>
+> **Start with:** `/spartan:spec [first-feature-name]`
+
+---
+
+## Tracking Progress
+
+When a spec or plan is written for a feature, update the epic's Features table:
+
+| Status change | When |
+|---|---|
+| `todo` → `spec` | After `/spartan:spec` saves |
+| `spec` → `planned` | After `/spartan:plan` saves |
+| `planned` → `building` | After `/spartan:build` starts |
+| `building` → `done` | After PR merged |
+| any → `skipped` | User decides to skip |
+
+The user can check progress anytime by reading `.planning/epics/{{ args[0] }}.md`.
+
+---
+
+## When NOT to Use This
+
+| Situation | Use instead |
+|---|---|
+| Single feature | `/spartan:spec` → `/spartan:plan` → `/spartan:build` |
+| Multi-week project with milestones | `/spartan:project new` (GSD lifecycle) |
+
+Epics sit between a single feature (too small) and full GSD projects (too big). Use them for a batch of 3-8 related features.
+
+---
+
+## Rules
+
+- **Ask questions one at a time.** Don't dump everything at once.
+- **Keep features small.** If a feature is > 3 days, split it.
+- **Order by dependency.** Feature N+1 can depend on Feature N, not the other way around.
+- **Each feature gets its own spec.** The epic is the container, not the spec.
+- **Update the epic as features progress.** Keep the Features table current.
+- **Auto mode on?** → Skip confirmations, save directly.

package/commands/spartan/fe-review.md

@@ -0,0 +1,181 @@
+---
+name: spartan:fe-review
+description: Thorough PR review for frontend code — loads rules from config, defaults to React/Next.js conventions
+argument-hint: "[optional: PR title or focus area]"
+---
+
+# Frontend PR Review: {{ args[0] | default: "current branch" }}
+
+Performing a thorough review of frontend changes.
+
+## Step 0: Load rules
+
+```bash
+# Check for project config
+cat .spartan/config.yaml 2>/dev/null
+
+# Get changed frontend files
+git diff main...HEAD --name-only | grep -E '\.(tsx?|jsx?|vue|svelte|css)$'
+```
+
+**If `.spartan/config.yaml` exists:**
+- Read `rules.frontend` + `rules.shared` — check against these rules
+- Read `review-stages` — only run enabled stages
+- If `conditional-rules` is set, match rules to changed files
+
+**If no config:** Use the default React/Next.js checklist below + scan for `rules/frontend-react/` or `~/.claude/rules/frontend-react/`.
+
+Read all matched rule files before reviewing code.
+
+---
+
+Run `git diff main...HEAD` and analyze all modified frontend files.
+
+## Stage 1: App Router Conventions
+
+- [ ] New pages use **Server Components by default**
+  - Only `'use client'` when strictly needed (event handlers, browser APIs, stateful UI)
+  - No `'use client'` just to use async/await (Server Components handle async natively)
+- [ ] Data fetching is in Server Components, not `useEffect`
+- [ ] Mutations use **Server Actions** (`'use server'`), not client-side fetch to API routes
+- [ ] `revalidatePath` or `revalidateTag` called after mutations (not manual router.refresh())
+- [ ] Route groups `(group)/` used to avoid URL pollution when grouping by auth/layout
+- [ ] Dynamic segments typed correctly: `{ params: { id: string } }`
+- [ ] `loading.tsx` and `error.tsx` present for routes with async data
+
+```bash
+# Check for anti-patterns
+git diff main...HEAD -- "*.tsx" "*.ts" | grep "'use client'" | wc -l  # count client components
+git diff main...HEAD -- "*.tsx" | grep "useEffect.*fetch\|axios\|fetch(" # data fetching in effects
+```
+
+---
+
+## Stage 2: TypeScript Strictness
+
+- [ ] No `any` types — use `unknown` + type guard if uncertain
+- [ ] API response types defined and mirror Kotlin DTOs
+- [ ] Zod validation used for runtime API response checking
+- [ ] No `!` non-null assertions without comment explaining why it's safe
+- [ ] Props interfaces defined (not inline objects for complex shapes)
+- [ ] Return types explicit on exported functions
+
+```bash
+# Check for type escape hatches
+git diff main...HEAD -- "*.tsx" "*.ts" | grep ": any\|as any\|@ts-ignore\|@ts-expect"
+```
+
+---
+
+## Stage 3: Performance
+
+- [ ] Images use `next/image` (not `<img>`)
+- [ ] Links use `next/link` (not `<a href>`)
+- [ ] Heavy components lazy-loaded with `dynamic()` if not needed on initial paint
+- [ ] No unnecessary `'use client'` that pushes rendering to browser
+- [ ] `fetch` calls in Server Components use `next: { revalidate }` or `next: { tags }` appropriately
+- [ ] No fetching the same data multiple times (Request Memoization across same render)
+
+---
+
+## Stage 4: Component Quality
+
+- [ ] Components are small and single-purpose (< ~100 lines ideally)
+- [ ] No business logic in UI components — logic lives in Server Actions or custom hooks
+- [ ] Custom hooks extracted for reusable client-side logic (`useFeature.ts`)
+- [ ] Props destructured in function signature
+- [ ] No prop drilling deeper than 2 levels (consider composition or Context)
+- [ ] `key` prop on list items uses stable ID, not array index
+
+---
+
+## Stage 5: Test Coverage
+
+- [ ] New components have test files (co-located: `Component.test.tsx`)
+- [ ] Tests use `@testing-library/react` — no shallow rendering
+- [ ] Tests verify **behavior**, not implementation details
+- [ ] Server Actions tested with mocked dependencies
+- [ ] No `querySelector` in tests — use accessible queries (`getByRole`, `getByLabelText`)
+
+```bash
+# Find components without tests
+git diff main...HEAD --name-only | grep "\.tsx$" | while read f; do
+  testfile="${f%.tsx}.test.tsx"
+  [[ ! -f "$testfile" ]] && echo "⚠️  Missing test: $testfile"
+done
+```
+
+---
+
+## Stage 6: Accessibility
+
+- [ ] Interactive elements are semantic HTML (`<button>`, not `<div onClick>`)
+- [ ] Form inputs have associated `<label>` (htmlFor + id, or `aria-label`)
+- [ ] Images have meaningful `alt` text (empty `alt=""` for decorative)
+- [ ] Color is not the only way to convey information
+- [ ] Focus management handled on modal/dialog open/close
+
+---
+
+## Stage 7: Full-Stack Contract (FE ↔ Kotlin BE)
+
+- [ ] TypeScript types in `_types/` match Kotlin DTOs exactly
+- [ ] API base URL from env var (`process.env.NEXT_PUBLIC_API_URL`), never hardcoded
+- [ ] Error handling for failed API calls — user-visible error state exists
+- [ ] Loading states present for async operations
+- [ ] No sensitive data logged to console
+
+---
+
+## Stage 8: Design Token Compliance
+
+**Only runs if `.planning/design/system/tokens.md` or `.planning/design-config.md` exists.**
+
+Read the design tokens file first. Then check every changed frontend file:
+
+- [ ] Colors use token names or CSS variables, not hardcoded hex or Tailwind defaults
+  - Search for: raw hex values (#xxx), `bg-blue-*`, `bg-purple-*`, `text-gray-*`
+  - Each match: is this value in the token list? If not → flag as **critical**
+- [ ] Font family matches design config, not generic fallbacks
+  - Search for: `font-sans`, `Inter`, `Roboto`, `Arial`, `system-ui`
+  - If project font is different → flag as **critical**
+- [ ] Spacing uses the token scale, not arbitrary values
+  - Random values like `p-[13px]` or `mt-[7px]` → flag as **warning**
+- [ ] Border radius matches token definitions
+- [ ] New components reference the design system, not reinventing styles
+
+```bash
+# Quick scan for hardcoded colors (should be tokens)
+git diff main...HEAD -- "*.tsx" "*.ts" "*.css" | grep -E '#[0-9a-fA-F]{3,8}|bg-(blue|red|green|purple|pink|indigo|violet)-[0-9]' | head -20
+
+# Quick scan for generic fonts
+git diff main...HEAD -- "*.tsx" "*.ts" "*.css" | grep -E "font-sans|Inter|Roboto|Arial|system-ui" | head -10
+```
+
+---
+
+## Output Format
+
+```markdown
+## Frontend PR Review: [title]
+
+### Approved / Needs Changes / Blocked
+
+### Critical Issues (must fix before merge)
+- [issue with file:line reference and suggested fix]
+
+### Suggestions (improve code quality)
+- [suggestion]
+
+### Performance Notes
+- [any perf observations]
+
+### Accessibility Notes
+- [any a11y issues]
+
+### Praise
+- [what was done well — be specific]
+
+### Verdict
+[recommendation + any conditions]
+```

package/commands/spartan/figma-to-code.md

@@ -0,0 +1,260 @@
+---
+name: spartan:figma-to-code
+description: Convert a Figma design screen to production code using Figma MCP. Manages token budget (one screen per session), extracts design tokens, and generates typed React components following App Router conventions.
+argument-hint: "[figma URL or screen name] [optional: component | page | feature]"
+---
+
+# Figma → Code: {{ args[0] }}
+Output type: {{ args[1] | default: "feature" }}
+
+You are converting a Figma design into production React/Next.js code using **Figma MCP**.
+
+**Critical constraint:** Figma MCP responses are ~13k tokens each. Budget **one screen per Claude Code session** to avoid context exhaustion. If more screens are needed, use `/spartan:context-save` after each screen.
+
+---
+
+## Phase 0: Check for existing design tokens (silent)
+
+```bash
+ls .planning/design/system/tokens.md .planning/design-config.md 2>/dev/null
+```
+
+If design tokens already exist, read them FIRST. When extracting from Figma:
+- **MERGE** Figma colors with existing tokens — don't create a second conflicting token set
+- Use existing token NAMES (e.g., `--color-primary`) even if Figma uses different hex values
+- If Figma colors differ from tokens, flag the mismatch and ask the user which to keep
+- Any NEW tokens from Figma get added to the existing file, not written to a separate one
+
+If NO tokens exist, proceed normally — extract from Figma and create new tokens.
+
+---
+
+## Phase 1: Extract Design Data (single MCP call)
+
+Call Figma MCP to get the screen data:
+
+```
+Use the Figma MCP tool to read the design at: {{ args[0] }}
+Extract: layout structure, colors, typography, spacing, component hierarchy
+```
+
+**Parse and organize immediately** — don't make a second MCP call unless absolutely necessary.
+
+Extract into a structured brief:
+
+```markdown
+## Design Brief: [screen name]
+
+### Layout
+- Container: [width, padding, layout direction]
+- Grid: [columns, gap, breakpoints if visible]
+
+### Color Tokens
+- Primary: [hex]
+- Secondary: [hex]
+- Background: [hex]
+- Text primary: [hex]
+- Text secondary: [hex]
+- Border: [hex]
+- [any other colors]
+
+### Typography
+- Heading 1: [font, weight, size, line-height, color]
+- Heading 2: [font, weight, size, line-height, color]
+- Body: [font, weight, size, line-height, color]
+- Caption: [font, weight, size, line-height, color]
+
+### Spacing Scale
+- [extract consistent spacing values: 4, 8, 12, 16, 24, 32, 48, etc.]
+
+### Components Identified
+1. [ComponentName] — [brief description, interactive? server/client?]
+2. [ComponentName] — ...
+
+### Assets Needed
+- Icons: [list]
+- Images: [list — placeholder or Cloudinary URLs]
+```
+
+---
+
+## Phase 2: Map to Code Architecture
+
+Based on output type ({{ args[1] | default: "feature" }}):
+
+**If `component`:**
+```
+components/[ComponentName]/
+  [ComponentName].tsx        ← Server or Client component
+  [ComponentName].test.tsx   ← Tests
+  index.ts                   ← Re-export
+```
+
+**If `page`:**
+```
+app/[route]/
+  page.tsx                   ← Server Component
+  loading.tsx                ← Skeleton matching Figma layout
+  _components/               ← Page-local components
+```
+
+**If `feature` (default):**
+```
+app/[feature]/
+  page.tsx                   ← Server Component, data fetching
+  loading.tsx                ← Skeleton from Figma layout
+  error.tsx                  ← Error boundary
+  _components/
+    [Component1].tsx
+    [Component2].tsx
+  _actions/                  ← Server Actions for mutations
+  _types/
+    [feature].types.ts       ← Types mirroring Kotlin DTOs
+```
+
+**Decision: Server vs Client Component**
+- Default = Server Component
+- `'use client'` ONLY if: onClick handlers, useState, browser APIs, animations
+- Interactive parts should be the smallest possible client component, wrapped in a server component parent
+
+---
+
+## Phase 3: Generate Design Tokens
+
+Create or update `src/lib/design-tokens.ts`:
+
+```typescript
+// Auto-generated from Figma — [screen name] — [date]
+// Do NOT edit manually. Re-run /spartan:figma-to-code to update.
+
+export const colors = {
+  primary: '[hex]',
+  secondary: '[hex]',
+  background: '[hex]',
+  surface: '[hex]',
+  textPrimary: '[hex]',
+  textSecondary: '[hex]',
+  border: '[hex]',
+  // ...
+} as const
+
+export const typography = {
+  h1: 'text-[size] font-[weight] leading-[lh]',    // Tailwind classes
+  h2: 'text-[size] font-[weight] leading-[lh]',
+  body: 'text-[size] font-[weight] leading-[lh]',
+  caption: 'text-[size] font-[weight] leading-[lh]',
+} as const
+
+export const spacing = {
+  xs: '[value]',   // e.g., '0.25rem'
+  sm: '[value]',
+  md: '[value]',
+  lg: '[value]',
+  xl: '[value]',
+} as const
+```
+
+If `tailwind.config.ts` exists, extend it with these tokens instead of a separate file.
+
+---
+
+## Phase 4: Generate Components (TDD)
+
+For each component identified in Phase 1:
+
+### 4a. Write test FIRST
+
+```typescript
+// [ComponentName].test.tsx
+import { render, screen } from '@testing-library/react'
+import { describe, it, expect } from 'vitest'
+import { ComponentName } from './ComponentName'
+
+describe('ComponentName', () => {
+  it('renders with required props', () => {
+    render(<ComponentName {...mockProps} />)
+    expect(screen.getByRole('[role]')).toBeInTheDocument()
+  })
+
+  it('matches Figma layout structure', () => {
+    // Test key layout assertions from design
+  })
+})
+```
+
+### 4b. Implement component
+
+```typescript
+// [ComponentName].tsx
+// Figma source: [screen name] > [layer path]
+
+interface ComponentNameProps {
+  // typed from Figma + Kotlin DTO
+}
+
+export function ComponentName({ ...props }: ComponentNameProps) {
+  return (
+    // Tailwind classes derived from Figma tokens
+    // Use design-tokens.ts for colors/typography
+  )
+}
+```
+
+### 4c. Verify test passes
+
+```bash
+npm test -- --run [ComponentName]
+```
+
+---
+
+## Phase 5: Loading Skeleton
+
+Generate `loading.tsx` that matches the Figma layout with skeleton placeholders:
+
+```typescript
+// loading.tsx — skeleton matching [screen name] layout
+export default function Loading() {
+  return (
+    <div className="animate-pulse">
+      {/* Mirror exact Figma layout with gray placeholder blocks */}
+    </div>
+  )
+}
+```
+
+---
+
+## Phase 6: Handoff Summary
+
+```markdown
+## Figma → Code Complete: [screen name]
+
+### Files Created
+- [list all files]
+
+### Design Tokens
+- Colors: [N] tokens extracted
+- Typography: [N] styles mapped
+- Spacing: [scale]
+
+### Components
+- [ComponentName]: Server/Client — [status]
+
+### Figma Fidelity Notes
+- [any deviations from design and why]
+- [responsive adaptations made]
+
+### Next Steps
+- [ ] Connect to real API data (replace mock props)
+- [ ] Add remaining screens: [list if multi-screen feature]
+- [ ] Review with designer for pixel accuracy
+
+### Token Budget Used
+- Figma MCP calls: [N] (~[N*13]k tokens)
+- Remaining context: [estimate]
+- Need more screens? → `/spartan:context-save` first
+```
+
+If context is above 40% after this screen, proactively suggest:
+"Context at ~[X]%. If you need another screen, I recommend `/spartan:context-save` now, then resume in a fresh session."

package/commands/spartan/forensics.md

@@ -0,0 +1,46 @@
+---
+name: spartan:forensics
+description: Post-mortem investigation for failed or stuck workflows. Analyzes git history, planning artifacts, and project state to diagnose what went wrong. Use when a phase failed, work got stuck, or you need to understand why something broke.
+argument-hint: "\"problem description\""
+---
+
+# Forensics Investigation
+
+You are running a post-mortem investigation using GSD forensics under the hood.
+The user does NOT need to know about `/gsd:*` commands — everything runs through `/spartan:*`.
+
+---
+
+## What this does
+
+Forensics analyzes your project's history to figure out **what went wrong** and **why**:
+- Git commit history and branch state
+- Planning artifacts (`.planning/` files)
+- Phase execution logs and deviations
+- State inconsistencies
+
+This is a **diagnostic tool** — it reads and analyzes, it does not modify anything.
+
+---
+
+## Run the investigation
+
+**Run:** `/gsd:forensics {{ args | join: " " }}`
+
+{% if args[0] %}
+Investigating: **{{ args | join: " " }}**
+{% else %}
+No problem description provided. Claude will analyze the current project state and ask what went wrong.
+{% endif %}
+
+---
+
+## After the investigation
+
+Present findings using `/spartan:` commands for next steps:
+- Need to re-plan a phase? → "Run `/spartan:phase plan N`"
+- Need to re-execute? → "Run `/spartan:phase execute N`"
+- Need to debug a specific issue? → "Run `/spartan:debug \"symptom\"`"
+- Project state is corrupted? → Consider `/spartan:project status` to assess
+
+**Never suggest `/gsd:*` commands to the user.** Always translate to `/spartan:*`.