Spartan AI Toolkit

Workflow-first engineering discipline for AI coding tools. Workflows solve problems end-to-end. Skills provide knowledge at each step. Agent memory carries context across sessions.

Install

Three ways to install. Pick one.

Option 1: npx (recommended)

npx @c0x12c/ai-toolkit@latest

Interactive menu — pick your AI tool and packs. Works out of the box.

# Or specify packs directly
npx @c0x12c/ai-toolkit@latest --packs=backend-micronaut,product

# Install everything
npx @c0x12c/ai-toolkit@latest --all

# Install for Cursor instead of Claude Code
npx @c0x12c/ai-toolkit@latest --agent=cursor

Supported agents: claude-code (default), cursor, windsurf, codex, copilot

Option 2: Setup script

git clone https://github.com/c0x12c/ai-toolkit.git
cd ai-toolkit/toolkit
chmod +x scripts/setup.sh
./scripts/setup.sh --global

Option 3: Claude Code plugin

Search for "Spartan AI Toolkit" in the Claude Code plugin marketplace.

Global vs Local

• --global installs to ~/.claude/ — works across all projects (default)
• --local installs to ./.claude/ — only this project

After install, open any project, run claude, then type /spartan.

Demo: Web-to-PRD

Scan a live web app, extract every feature, generate a structured PRD with epics and stories, then export to Notion.

/spartan:web-to-prd "https://screensdesign.com"

Uses Playwright MCP (browser control) + Notion MCP (export). Auto-installs prerequisites, handles login, and asks for confirmation at each step.

How to Use

The core workflow

Every feature follows the same pipeline. Skip steps that don't apply.

/spartan:spec → /spartan:ux → /spartan:plan → /spartan:build → /spartan:pr-ready
      ↑             ↑               ↑              ↑ + 3.5           ↑
    Gate 1     Design Gate       Gate 2          Gate 3           Gate 4

| Step | What happens | |------|-------------| | spec | Interactive Q&A → saved spec → Gate 1 checks quality | | design | Design doc + dual-agent review (skip for backend-only) | | plan | Architecture + task breakdown from spec → Gate 2 | | build | TDD task by task, picks up saved spec/plan | | gate-review | Builder + reviewer agent both must accept | | pr-ready | Rebase, test, lint, create PR |

Bigger work? Use /spartan:epic to break it into features first, then run the pipeline for each one. For multi-week projects, use /spartan:project new with milestones and phases.

Skills load automatically based on your stack. Kotlin files → kotlin-best-practices. React components → ui-ux-pro-max. Migrations → database-patterns. You don't pick them.

Agent memory (.planning/, .memory/) carries specs, plans, decisions, and patterns across sessions. The AI builds on what it already knows instead of starting from scratch.

Rules load every session with zero tokens. They enforce coding standards silently.

Pick Your Packs

Packs group commands, rules, skills, and agents by use case. Core is always installed. Pick the rest based on what you're building.

"I'm building a Kotlin + Micronaut backend"

npx @c0x12c/ai-toolkit@latest --packs=backend-micronaut

This pulls in backend-micronaut + its dependencies (database and shared-backend auto-included). You get migration commands, API design rules, Kotlin coding standards, test patterns, and two expert agents.

"I'm building a React + Next.js frontend"

npx @c0x12c/ai-toolkit@latest --packs=frontend-react

You get Next.js scaffolding, Figma-to-code, E2E testing setup, frontend review, and the UI/UX design skill.

"Full-stack Kotlin + Next.js"

npx @c0x12c/ai-toolkit@latest --packs=backend-micronaut,frontend-react

"I'm managing AWS infrastructure with Terraform"

npx @c0x12c/ai-toolkit@latest --packs=infrastructure

You get Terraform scaffolding (ECS + EKS), module creation, security audits, drift detection, cost optimization, and two infrastructure agents. Rules enforce naming, state management, provider placement, and security patterns.

"I'm running a multi-week project"

npx @c0x12c/ai-toolkit@latest --packs=backend-micronaut,project-mgmt

Adds project lifecycle, phases, workstreams, and GSD v5 wave execution on top of your backend tools.

"I'm exploring startup ideas"

npx @c0x12c/ai-toolkit@latest --packs=research

Research pack pulls in product as a dependency. You get brainstorming, validation, market research, competitor teardowns, pitch materials, and investor outreach.

"Give me everything"

npx @c0x12c/ai-toolkit@latest --all

All Packs

| Pack | Category | Depends on | What you get | |------|----------|------------|--------------| | core | Core | — | Always installed. Workflows (build, fix, onboard), spec, plan, gate-review, pr-ready, daily, safety commands, phase-reviewer agent | | backend-micronaut | Backend | database, shared-backend | Kotlin service scaffold, code review, testcontainers, API/DB/Kotlin rules, 5 skills, 2 agents | | backend-nodejs | Backend | database, shared-backend | Coming soon | | backend-python | Backend | database, shared-backend | Coming soon | | frontend-react | Frontend | — | Design workflow, Next.js scaffold, Figma-to-code, E2E, frontend review, UI/UX + design-workflow skills, design-critic agent | | project-mgmt | Planning | — | Epics, project lifecycle, phases, workstreams, GSD upgrade, forensics, brownfield, codebase mapping | | product | Planning | — | Think-before-build, validate, teardown, interview, lean canvas, brainstorm | | infrastructure | Ops | — | Terraform + AWS: scaffold, modules, review, plan, deploy, import, drift, cost, security. 7 rules, 5 skills, 2 agents | | ops | Ship | — | Deploy + env-setup, 2 skills (ops-investigate-alert, ops-oncall-log) | | research | Research | product | Startup + research workflows, kickoff to investor outreach, 10 skills, 2 agents |

Hidden packs (database, shared-backend) get pulled in as dependencies — you don't pick them directly.

Commands

All commands start with /spartan: (e.g., /spartan:spec "feature").

Type /spartan to get the smart router — it asks what you need and picks the right command.

Workflows (core + research packs)

| Command | What it does | |---------|-------------| | build [mode] [feature] | Build a feature end-to-end (backend, frontend, or auto-detect) | | fix [symptom] | Find and fix a bug with structured investigation | | research [topic] | Deep research with source tracking and report | | startup [idea] | Full startup pipeline: brainstorm to investor-ready | | onboard | Understand a new codebase and set up tooling |

Core (always installed)

| Command | What it does | |---------|-------------| | spec "feature" | Write a feature spec — saves to .planning/specs/ | | plan "feature" | Write implementation plan from spec — saves to .planning/plans/ | | gate-review [phase] | Dual-agent review (Gate 3.5) — builder + reviewer both accept | | daily | Standup summary from git history | | pr-ready | Full checklist before creating any PR | | init-project | Auto-generate CLAUDE.md from codebase scan | | context-save | Save session state to resume later | | update | Check for toolkit updates | | careful | Warn before destructive ops | | freeze <dir> | Lock edits to one directory | | unfreeze | Remove directory lock | | guard <dir> | careful + freeze combined |

Backend (backend-micronaut pack)

| Command | What it does | |---------|-------------| | kotlin-service "name" | Scaffold new Micronaut microservice | | review | PR review with Kotlin/Micronaut conventions | | testcontainer "type" | Setup Testcontainers integration testing | | migration "desc" | Create Flyway database migration |

Frontend (frontend-react pack)

| Command | What it does | |---------|-------------| | design "feature" | Design workflow with dual-agent review (Design Gate) | | next-app "name" | Scaffold new Next.js app | | next-feature "name" | Add feature to existing Next.js app | | fe-review | PR review with Next.js conventions | | figma-to-code "url" | Figma design to production React | | e2e "feature" | Setup Playwright E2E testing |

Planning (project-mgmt pack)

| Command | What it does | |---------|-------------| | epic "name" | Break big work into ordered features | | project [action] | Large project lifecycle (new, status, milestone) | | phase [action] | Phase lifecycle (discuss, plan, execute, verify) | | workstreams [action] | Parallel work tracks | | gsd-upgrade | Upgrade to GSD v5 with memory + waves | | forensics "problem" | Post-mortem for failed workflows | | brownfield "svc" | Map unfamiliar codebase before touching it | | map-codebase | Deep codebase analysis with parallel agents |

Product (product pack)

| Command | What it does | |---------|-------------| | think | Guided thinking before coding | | validate | Score an idea — GO / TEST MORE / KILL | | teardown | Deep competitor analysis | | interview | Mom Test interview questions | | lean-canvas | Fill out a 9-block Lean Canvas | | brainstorm | Generate and rank ideas | | web-to-prd "URL" | Scan a live web app with Playwright, extract features, generate PRD with epics/stories, export to Notion |

Infrastructure (infrastructure pack)

| Command | What it does | |---------|-------------| | tf-scaffold "service" | Scaffold service-level Terraform (ECS or EKS) | | tf-module "name" | Create/extend Terraform modules | | tf-review | PR review for Terraform changes (8-stage checklist) | | tf-plan "env" | Guided plan workflow with destructive change flagging | | tf-deploy "env" | Deployment checklist with pre/post verification | | tf-import "resource" | Import existing AWS resources into state | | tf-drift "env" | Detect and categorize infrastructure drift | | tf-cost | Cost estimation and optimization guidance | | tf-security | Security audit (IAM, network, encryption, secrets) |

Ship (ops pack)

| Command | What it does | |---------|-------------| | deploy "svc" "target" | Deploy + verify | | env-setup "svc" | Audit env vars across environments |

Research (research pack)

| Command | What it does | |---------|-------------| | startup [idea] | Full pipeline from brainstorm to outreach | | kickoff [theme] | Start new idea — brainstorm + validate | | deep-dive [project] | Market research + competitor teardowns | | fundraise [project] | Pitch materials + investor outreach | | research [topic] | Deep research with source checking | | pitch [type] | Investor-facing materials | | outreach [investor] | Draft investor emails | | content [source] | Turn ideas into platform-native content | | write [topic] | Write blog posts and articles |

Skills

Skills give Claude deeper knowledge in specific areas. They're loaded automatically when you use related commands.

| Skill | Pack | What it does | |-------|------|-------------| | api-endpoint-creator | backend-micronaut | Generate Controller → Manager → Repository stack | | database-table-creator | database | SQL migration → Table → Entity → Repository → Tests | | backend-api-design | backend-micronaut | RPC-style API design patterns | | database-patterns | database | Schema design, migrations, Exposed ORM | | kotlin-best-practices | backend-micronaut | Null safety, Either, coroutines | | testing-strategies | backend-micronaut | Integration test patterns for Micronaut | | security-checklist | backend-micronaut | Auth, validation, OWASP prevention | | ui-ux-pro-max | frontend-react | Design intelligence — styles, palettes, font pairings, stacks | | terraform-service-scaffold | infrastructure | Scaffold service Terraform (ECR, RDS, Redis, S3, ECS/EKS) | | terraform-module-creator | infrastructure | Create reusable Terraform modules | | terraform-review | infrastructure | PR review checklist for Terraform | | terraform-security-audit | infrastructure | 6-area security audit for Terraform | | terraform-best-practices | infrastructure | Quick reference for Terraform conventions | | brainstorm | research | Idea generation and ranking | | idea-validation | research | Score ideas with structured checklist | | market-research | research | Market sizing, trends, opportunities | | competitive-teardown | research | Deep competitor analysis | | deep-research | research | Multi-source research with citations | | investor-materials | research | Pitch deck, one-pager, financial model | | investor-outreach | research | Investor targeting and outreach | | article-writing | research | Long-form content creation | | content-engine | research | Content strategy and production | | startup-pipeline | research | Full startup research pipeline | | web-to-prd | product | Scan web apps, extract features, generate PRD, export to Notion | | ops-investigate-alert | ops | Investigate monitoring alerts end-to-end | | ops-oncall-log | ops | Create on-call log from monitoring alerts |

Agents

| Agent | Pack | What it does | |-------|------|-------------| | micronaut-backend-expert | backend-micronaut | Micronaut framework, database design, API architecture | | solution-architect-cto | backend-micronaut | System design, scalability, tech decisions | | infrastructure-expert | infrastructure | AWS + Terraform, c0x12c modules, EKS/ECS, security | | sre-architect | infrastructure | Multi-account strategy, cost optimization, DR planning | | idea-killer | research | Stress-test ideas, find weaknesses | | research-planner | research | Plan and coordinate research workflows |

Rules

Rules are enforced automatically every session. No action needed — they're active as long as the pack is installed.

| Rule | Pack | |------|------| | NAMING_CONVENTIONS | core | | TIMEZONE | core | | ARCHITECTURE | shared-backend | | SCHEMA | database | | ORM_AND_REPO | database | | TRANSACTIONS | database | | KOTLIN | backend-micronaut | | CONTROLLERS | backend-micronaut | | SERVICES_AND_BEANS | backend-micronaut | | API_DESIGN | backend-micronaut | | RETROFIT_PLACEMENT | backend-micronaut | | FRONTEND | frontend-react | | STRUCTURE | infrastructure | | MODULES | infrastructure | | STATE_AND_BACKEND | infrastructure | | NAMING | infrastructure | | SECURITY | infrastructure | | VARIABLES | infrastructure | | PROVIDERS | infrastructure |

Using with Other AI Tools

All content is standard markdown. The npx installer supports multiple agents:

# Cursor — installs rules to .cursor/rules/
npx @c0x12c/ai-toolkit@latest --agent=cursor

# Windsurf — installs rules to .windsurf/rules/
npx @c0x12c/ai-toolkit@latest --agent=windsurf

# Codex — installs to .codex/
npx @c0x12c/ai-toolkit@latest --agent=codex

# Copilot — installs to .github/copilot/
npx @c0x12c/ai-toolkit@latest --agent=copilot

For other tools, copy the rule files from toolkit/rules/ into your tool's config directory.

Project Config

Customize any Spartan command per project. Two config files in .spartan/:

.spartan/build.yaml — Build workflow config

Controls /spartan:build behavior:

branch-prefix: "feature"    # branch name: [prefix]/[slug]
max-review-rounds: 3        # review-fix cycles before asking user
skip-stages: []             # skip: spec, design, plan, ship (never review)

prompts:
  spec: |
    Always include performance requirements.
  plan: |
    Every task must reference a Jira ticket.
  implement: |
    Add structured logging to new service methods.
  review: |
    Check all API responses include request_id.
  ship: |
    PR title: [PROJ-123] Short description.

.spartan/commands.yaml — Per-command prompt injection

Inject custom instructions into ANY Spartan command:

prompts:
  review: |
    Flag any function longer than 50 lines.
  pr-ready: |
    Always add "Reviewers: @backend-team" for backend changes.
  daily: |
    Include blockers section. Tag by project area.
  debug: |
    Always check CloudWatch logs first.
  migration: |
    Migration files must start with ticket number.

Templates for both files are in toolkit/templates/.

AI-Powered Design (Optional)

The design workflow (/spartan:ux) can generate real images for prototypes using Google Gemini.

Setup

1. Get a Gemini API key

2. Create .spartan/ai.env in your project root:

echo "GEMINI_API_KEY=your-key-here" > .spartan/ai.env

3. Install Python dependencies:

pip install google-genai Pillow

4. Use it:

/spartan:ux prototype    # generates images for your design

Note: The installer adds .spartan/ai.env to .gitignore automatically. If you set this up manually, make sure .spartan/ai.env is in your .gitignore — never commit API keys.

Target Stack

Rules and skills are tuned for this stack, but the command framework works with anything:

| Layer | Technology | |-------|-----------| | Backend | Kotlin + Micronaut | | Frontend | React + Next.js + TypeScript | | Infrastructure | Terraform + AWS (EKS/ECS, RDS, ElastiCache, S3) | | Database | PostgreSQL | | CI/CD | GitHub Actions |

Different stack? Fork the repo, edit the rules and skills, run the installer. Commands work with any language or framework.