Spartan AI Toolkit

AI coding agents are fast. They're also careless. They skip tests, ignore your coding standards, push without review, and forget everything between sessions.

Spartan fixes that. One command runs a full engineering workflow — spec, plan, TDD, code review, PR — with quality gates between each step. Your rules, your standards, enforced every time.

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

Works with Claude Code, Codex, Cursor, Windsurf, and Copilot. Rules are plain markdown — works with any AI tool.

Before & After

Quick Start

# 1. Install (30 seconds, interactive menu)
npx @c0x12c/ai-toolkit@latest --local

# 2. Set up rules for your stack
/spartan:init-rules

# 3. Build something
/spartan:build "add user authentication"

That's it. The /spartan:build command handles the full pipeline:

spec → design (if UI) → plan → TDD → code review → PR
  |         |              |      |         |          |
Gate 1   Design Gate    Gate 2  Gate 3   Gate 3.5   Gate 4

Nothing ships without passing every gate.

What's Inside

5 Workflow Leaders

Each leader runs a full pipeline. One command — it handles the rest.

Or just type /spartan — the smart router figures out what you need.

Works With Any Stack

Pick a built-in profile or write your own rules in markdown:

Not on this list? Create rules in markdown, point the config at them. The toolkit reads whatever you give it.

# .spartan/config.yaml — you control everything
stack: go-standard
architecture: clean

rules:
  backend:
    - rules/go/ERROR_HANDLING.md
    - rules/go/INTERFACES.md
    - rules/custom/OUR_AUTH_RULES.md

commands:
  test:
    backend: "go test ./..."
  lint:
    backend: "golangci-lint run"

Install

Three ways. Pick one.

Option 1: npx (recommended)

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

Interactive menu. Pick your AI tool and packs. Done in 30 seconds.

# Pick specific packs
npx @c0x12c/ai-toolkit@latest --local --packs=backend-micronaut,frontend-react

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

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 --local

Option 3: Claude Code plugin

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

Local vs Global

• --local (recommended) — installs to ./.claude/ in your project. Your team can see, review, and version-control the setup.
• --global — installs to ~/.claude/, works across all your projects.

Not using Claude Code?

npx @c0x12c/ai-toolkit@latest --local --agent=claude-code  # default
npx @c0x12c/ai-toolkit@latest --local --agent=codex        # full install
npx @c0x12c/ai-toolkit@latest --local --agent=cursor       # rules only
npx @c0x12c/ai-toolkit@latest --local --agent=windsurf     # rules only
npx @c0x12c/ai-toolkit@latest --local --agent=copilot      # rules only

Uninstall

# Remove from current project
npx @c0x12c/ai-toolkit@latest --uninstall --local

# Remove global install
npx @c0x12c/ai-toolkit@latest --uninstall --global

# Remove for other agents
npx @c0x12c/ai-toolkit@latest --uninstall --local --agent=cursor

How It Works

Review uses your rules

When /spartan:build reaches the review step:

1. Reads .spartan/config.yaml to find your rules
2. Spawns a separate review agent (fresh eyes, not the same AI that wrote the code)
3. The reviewer reads all your rule files, then checks the code against them
4. Issues found → fix → re-review → repeat until clean

No config? The reviewer still runs — it just uses a generic checklist.

Skills: domain knowledge at each step

Leaders call the right skill at the right time based on your stack:

Agent memory: context across sessions

AI forgets everything when you close the terminal. Agent memory fixes that with 3 layers:

.memory/
  index.md        — Layer 1: always loaded, pointers only (~150 chars per line)
  decisions/      — Layer 2: loaded on demand when relevant
  patterns/       —   architecture decisions, code patterns
  knowledge/      —   domain facts, API gotchas
  blockers/       —   known issues and workarounds
  transcripts/    — Layer 3: never loaded, grep-only archive

Leaders read and write memory automatically. /spartan:memory-consolidate cleans stale entries. /spartan:magic-doc keeps docs in sync with code.

Configurable rules

Rules load every session. The AI follows them without you asking.

/spartan:init-rules go-standard      # Pick a profile
/spartan:scan-rules                   # Or auto-detect from your code
/spartan:lint-rules                   # Validate your config

Parallel builds

Build 2+ features at the same time. Each /spartan:build automatically creates a git worktree — no manual setup:

# Terminal 1                          # Terminal 2
/spartan:build auth                   /spartan:build payments
# → .worktrees/auth/ (feature/auth)  # → .worktrees/payments/ (feature/payments)
# → PR #1                            # → PR #2

Each build creates its own worktree, branch, and PR. No conflicts. Worktrees are cleaned up after PR merge.

Project config

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

.spartan/build.yaml — controls the build workflow:

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:                    # inject custom instructions per stage
  spec: |
    Always include performance requirements.
  review: |
    Check all API responses include request_id.
  ship: |
    PR title: [PROJ-123] Short description.

.spartan/commands.yaml — inject prompts into any command:

prompts:
  review: "Flag any function longer than 50 lines."
  pr-ready: "Always add Reviewers: @backend-team."
  daily: "Include blockers section."
  debug: "Always check CloudWatch logs first."

Templates in toolkit/templates/. The AI reads your config every session — no manual reminders needed.

Pick Your Packs

Packs group commands, rules, skills, and agents by use case. Core is always installed. You pick the rest.

Common setups

All packs

All Commands

Type /spartan for the smart router. Or go direct:

Workflow Leaders

Core (always installed)

Backend (backend-micronaut pack)

Frontend (frontend-react pack)

Product (product pack)

Ship (ops pack)

Research (research pack)

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.

Telegram Bridge

Control your AI coding sessions from your phone.

Phone (Telegram) <-> Bridge (Node.js) <-> Claude Agent SDK <-> Claude API

See bridges/ for setup.

Star History

Contributing

See CONTRIBUTING.md for how to add commands, skills, rules, and agents.

License

MIT