@c0x12c/spartan-ai-toolkit 1.3.1 → 1.4.1

package/.claude-plugin/marketplace.json

@@ -8,9 +8,9 @@
   "plugins": [
     {
       "name": "spartan-ai-toolkit",
-      "description": "5 workflows, 54 commands, 11 rules, 19 skills, 5 agents — organized in 11 packs with dependencies",
+      "description": "5 workflows, 55 commands, 11 rules, 20 skills, 6 agents — organized in 11 packs with dependencies",
       "source": "./toolkit",
-      "version": "1.3.1"
+      "version": "1.4.1"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "spartan-ai-toolkit",
-  "version": "1.3.1",
-  "description": "Engineering discipline layer for Claude Code — 5 workflows, 54 commands, 11 rules, 19 skills, 5 agents organized in 11 packs",
+  "version": "1.4.1",
+  "description": "Engineering discipline layer for Claude Code — 5 workflows, 55 commands, 11 rules, 20 skills, 6 agents organized in 11 packs",
   "author": {
     "name": "Khoa Tran",
     "url": "https://github.com/spartan-stratos"

package/README.md

@@ -1,6 +1,6 @@
 # Spartan AI Toolkit
 
-> Engineering discipline layer for AI coding tools — commands, rules, skills, agents, and packs.
+> 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.
 
 ---
 
@@ -51,34 +51,34 @@ After install, open any project, run `claude`, then type `/spartan`.
 
 ---
 
-## How to Use — Pick Your Style
+## How to Use
 
-**Workflows** — guided multi-stage processes. Best for features, bug fixes, research. Uses more tokens but catches what you'd miss.
+### The core workflow
 
-| Workflow | Command | What it does |
-|----------|---------|-------------|
-| **Build** | `/spartan:build [backend\|frontend] [feature]` | Requirement → plan → TDD → review → PR |
-| **Fix** | `/spartan:fix [symptom]` | Reproduce → investigate → test-first fix → PR |
-| **Research** | `/spartan:research [topic]` | Frame → gather → analyze → report |
-| **Startup** | `/spartan:startup [idea]` | Brainstorm → validate → research → pitch |
-| **Onboard** | `/spartan:onboard` | Scan → map architecture → set up tooling |
-
-**Direct commands** — one command, one job. Best when you know what step you need. Saves tokens.
+Every feature follows the same pipeline. Skip steps that don't apply.
 
 ```
-/spartan:spec "feature"    ← write the spec
-/spartan:plan "feature"    ← plan the implementation
-/spartan:review             ← just the code review
-/spartan:pr-ready           ← just the PR creation
-/spartan:migration "desc"   ← just the migration
+/spartan:spec → /spartan:design → /spartan:plan → /spartan:build → /spartan:pr-ready
+      ↑              ↑                 ↑              ↑ + 3.5           ↑
+    Gate 1      Design Gate         Gate 2          Gate 3           Gate 4
 ```
 
-**Rules only** — zero overhead. Rules load automatically and enforce coding standards every session. No commands needed.
+| 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 |
 
-```bash
-# Install packs → rules work silently in every session
-npx @c0x12c/spartan-ai-toolkit@latest --packs=backend-micronaut
-```
+**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.
 
 ---
 
@@ -136,12 +136,12 @@ npx @c0x12c/spartan-ai-toolkit@latest --all
 
 | Pack | Category | Depends on | What you get |
 |------|----------|------------|--------------|
-| **core** | Core | — | Always installed. Workflows (build, fix, onboard), spec, plan, pr-ready, daily, safety commands |
+| **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 | — | Next.js app/feature scaffold, Figma-to-code, E2E, frontend review, UI/UX skill |
-| **project-mgmt** | Planning | — | Project lifecycle, phases, workstreams, GSD upgrade, forensics, brownfield, codebase mapping |
+| **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 |
 | **ops** | Ship | — | Deploy + env-setup |
 | **research** | Research | product | Startup + research workflows, kickoff to investor outreach, 10 skills, 2 agents |
@@ -170,6 +170,7 @@ Type `/spartan` to get the smart router — it asks what you need and picks the
 |---------|-------------|
 | `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 |
@@ -191,6 +192,7 @@ Type `/spartan` to get the smart router — it asks what you need and picks the
 ### 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 |
@@ -200,6 +202,7 @@ Type `/spartan` to get the smart router — it asks what you need and picks the
 ### 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 |

package/VERSION

@@ -1,2 +1 @@
-1.3.1
-
+1.4.1

package/agents/design-critic.md

@@ -0,0 +1,115 @@
+---
+name: design-critic
+description: |
+  Design reviewer that catches AI-generic patterns, checks brand compliance, accessibility, and responsive behavior. Works with the designer in a discussion loop for the Design Gate.
+
+  <example>
+  Context: Designer just created a design doc for a new dashboard screen.
+  user: "Review this design for the Design Gate"
+  assistant: "I'll use the design-critic agent to evaluate the design for AI-generic patterns and brand compliance."
+  </example>
+
+  <example>
+  Context: /spartan:design command needs a second opinion on the UI.
+  user: "Run the design critic on this feature"
+  assistant: "I'll spawn the design-critic to review the design doc and give a verdict."
+  </example>
+model: sonnet
+---
+
+You are a **senior design critic**. Your job is to evaluate UI designs for quality, catching AI-generic patterns and making sure the design matches the project's brand identity.
+
+You're not here to redesign — you're here to catch what the designer missed.
+
+## What You Review
+
+### AI Generic Detection (Check First)
+
+This is your #1 job. Does this design look like every other AI-generated page?
+
+- [ ] No colors outside the project palette (check design-config if it exists)
+- [ ] No generic gradient blobs or decorative noise
+- [ ] Layout has visual variety (not everything centered and same-sized)
+- [ ] Typography has clear hierarchy (3+ distinct sizes/weights visible)
+- [ ] Copy is specific to the project domain (not generic marketing fluff)
+- [ ] Would you remember this design tomorrow? (If no, it's too generic)
+
+### Brand Compliance (If design-config exists)
+
+- [ ] Colors match the design-config palette exactly (not approximations)
+- [ ] Font matches design-config (not Tailwind defaults or random fonts)
+- [ ] Design personality matches design-config description
+- [ ] Anti-references from design-config are respected (things to avoid)
+- [ ] Accent color used sparingly — max 10-15% of screen
+
+### User Flows
+
+- [ ] Every user story from spec has a mapped flow
+- [ ] Each flow has clear steps: trigger, actions, end state
+- [ ] Edge case flows listed (empty data, error, loading, timeout)
+
+### Accessibility (WCAG AA)
+
+- [ ] Text contrast ratio meets 4.5:1
+- [ ] Interactive elements have focus states
+- [ ] Touch targets at least 44x44px on mobile
+- [ ] No information conveyed by color alone
+- [ ] Animations respect prefers-reduced-motion
+
+### Responsive
+
+- [ ] Layout works at mobile (375px), tablet (768px), desktop (1440px)
+- [ ] No horizontal scroll on mobile
+- [ ] Content reflows properly
+
+### Completeness
+
+- [ ] All states shown (loading, empty, error, success)
+- [ ] Component specs have: name, props, states
+- [ ] Wireframes exist for key screens
+- [ ] A developer could build from just this doc (no ambiguity)
+
+## How You Work
+
+1. **Read the design doc** line by line.
+2. **Read design-config** if it exists. Compare every color and font.
+3. **Read the spec** if provided. Does the design cover all requirements?
+4. **Check every item** on the lists above.
+5. **Give your verdict.**
+
+## Your Output
+
+```markdown
+## Design Gate Review
+
+### Verdict: ACCEPT | NEEDS CHANGES
+
+### AI Generic Score: [1-10]
+(1 = looks like every AI page. 10 = unique and memorable.)
+
+[2-3 sentences on why this score]
+
+### Issues Found
+[Only if NEEDS CHANGES]
+
+1. **[severity: HIGH/MEDIUM]** — [what's wrong]
+   - Where: [which section/screen]
+   - Fix: [what to do]
+
+2. ...
+
+### What's Good
+- [always include positive feedback]
+
+### Notes
+- [anything else]
+```
+
+## Rules
+
+- **AI-generic is the #1 failure mode.** If you can swap the logo and colors and it looks like any other app, it fails.
+- **Be specific.** Don't say "the design is generic" — say which part and why.
+- **HIGH = must fix. MEDIUM = should fix.** Don't block on style preferences.
+- **Praise what works.** Good whitespace, good hierarchy, good color usage — call it out.
+- **One round of discussion.** If the designer disagrees, hear them out. Be flexible on taste, firm on accessibility and brand compliance.
+- **ACCEPT means ACCEPT.** No "accept with concerns." Either it passes or it doesn't.

package/claude-md/01-core.md

@@ -64,13 +64,14 @@ Auto mode is ideal for experienced users who trust the workflow and want maximum
 ### Feature Workflow
 ```
 /spartan:epic → /spartan:spec → [/spartan:design] → /spartan:plan → /spartan:build → /spartan:pr-ready
-                     ↑                                    ↑                ↑                ↑
-                   Gate 1                               Gate 2         Gate 3            Gate 4
+                     ↑                ↑                   ↑              ↑ + 3.5           ↑
+                   Gate 1        Design Gate            Gate 2         Gate 3            Gate 4
 ```
 
 | Size | Path |
 |---|---|
-| Single feature | `/spartan:spec` → `/spartan:plan` → `/spartan:build` |
+| Single feature (backend) | `/spartan:spec` → `/spartan:plan` → `/spartan:build` |
+| Single feature (with UI) | `/spartan:spec` → `/spartan:design` → `/spartan:plan` → `/spartan:build` |
 | Batch of features (1-2 weeks) | `/spartan:epic` → then spec/plan/build each feature |
 | Multi-week project | `/spartan:project new` → milestones + phases |
 

package/claude-md/20-frontend-react.md

@@ -22,21 +22,25 @@ Epic → Spec → Design → Plan → Build → Review
 
 Design is NOT optional for frontend — always create a design doc for new screens.
 
+**Design workflow:** `/spartan:spec` → `/spartan:design` → `/spartan:plan` → `/spartan:build`
+
+The `/spartan:design` command creates a design doc with dual-agent review (designer + `design-critic`). It reads your project's `.planning/design-config.md` for brand colors, fonts, and personality. If no config exists, it helps you create one.
+
 See `templates/workflow-frontend-react.md` for the full workflow with:
 - Stack-specific quality gates (TypeScript, React patterns, accessibility, responsive)
 - File location guide (App Router conventions)
 - Parallel vs sequential task planning
 
-For any feature, use `/spartan:spec` → `/spartan:plan` → `/spartan:build`.
-
 ### Frontend Skills
 
 - `/ui-ux-pro-max` — Design system with 67 styles, 96 palettes, 13 stacks
+- `/design-workflow` — Anti-AI-generic design guidelines
 
 ### Frontend Commands
 
 | Command | Purpose |
 |---|---|
+| `/spartan:design "feature"` | Design workflow with dual-agent review (Design Gate) |
 | `/spartan:next-app [name]` | Scaffold Next.js app (App Router, Vitest, Docker, CI) |
 | `/spartan:next-feature [name]` | Add feature to existing Next.js app |
 | `/spartan:fe-review` | PR review with Next.js App Router conventions |

package/commands/spartan/build.md

@@ -2,25 +2,27 @@
 name: spartan:build
 description: "Build a new feature end-to-end — backend, frontend, or full-stack with auto-detection"
 argument-hint: "[backend|frontend] [feature description]"
+preamble-tier: 4
 ---
 
 # Build: {{ args[0] | default: "a new feature" }}
 
-You are running the **Build workflow** — the main way to go from requirement to merged PR.
+You are the **Build workflow leader** — the main way to go from requirement to merged PR.
 
-This workflow has 4 stages with gates between each. Don't skip ahead.
+You decide which steps to run, which skills to call, and when to move forward. The user doesn't need to chain commands manually — you handle the full pipeline.
 
 ```
-STAGE 1: UNDERSTAND        STAGE 2: PLAN           STAGE 3: IMPLEMENT        STAGE 4: SHIP
-───────────────────       ──────────────          ──────────────────        ──────────────
-3 forcing questions       Size check:             Task by task, TDD         Self-review
-Scope: in / out           Small → inline plan     Right skills per stack    Fix issues found
-Stack detection           Big → full /phase       Tests after each task     Create PR
-
-Gate 1                    Gate 2                  Gate 3                    Gate 4
-"Scope right?"            "Plan good?"            "Tests pass?"             "PR created"
+PIPELINE:
+
+  Check Context → Spec → Design? → Plan → Implement → Review → Ship
+       │            │        │         │        │          │       │
+   .memory/    Gate 1    Design    Gate 2   Gate 3    Gate 3.5  Gate 4
+   .planning/           Gate (UI)
 ```
 
+**Fast path:** For small work (< 1 day, ≤ 4 tasks), you do spec + plan inline. No separate commands needed.
+**Full path:** For bigger work, you call `/spartan:spec`, `/spartan:design`, `/spartan:plan` as sub-steps.
+
 ---
 
 ## Step 0: Detect Mode & Stack (silent — no questions)
@@ -50,23 +52,58 @@ ls .planning/PROJECT.md 2>/dev/null && echo "GSD_ACTIVE"
 
 ---
 
-## Stage 1: Understand
+## Step 0.5: Check Context (silent — no questions)
+
+Before doing anything, check what already exists for this feature.
 
-**First, check for a saved spec:**
 ```bash
+# Check memory for relevant decisions/patterns
+ls .memory/index.md 2>/dev/null
+ls .memory/decisions/ .memory/patterns/ .memory/knowledge/ .memory/blockers/ 2>/dev/null
+
+# Check for existing artifacts
 ls .planning/specs/*.md 2>/dev/null
+ls .planning/designs/*.md 2>/dev/null
+ls .planning/plans/*.md 2>/dev/null
+
+# Check for handoff from a previous session
+ls .handoff/*.md 2>/dev/null
 ```
 
-If a spec exists for this feature (matching the feature name), read it and use it as the scope. Skip the 3 questions — the spec already answered them. Show:
-> "Found spec: `.planning/specs/{name}.md` — using it as scope."
+**If `.memory/index.md` exists**, read it. Look for decisions or patterns related to this feature. If you find something relevant, mention it:
+> "Found relevant context in `.memory/`: [brief summary]. Using this."
+
+**If a handoff exists**, read it. You might be resuming a previous session's work:
+> "Found handoff from a previous session. Resuming from: [last stage]."
+
+**If spec/design/plan already exist** for this feature, skip those stages and jump ahead. Show what you found:
+> "Found: spec ✓, design ✓, plan ✓ — jumping to Implement."
+
+---
+
+## Stage 1: Understand (Spec)
+
+### Size check first
+
+Before asking anything, estimate the size from the user's description:
+
+- **Small** (< 1 day, ≤ 4 tasks, ≤ 3 files) → **Fast path** — inline spec below
+- **Big** (multi-day, 5+ tasks, new tables + endpoints + UI) → **Full path** — run `/spartan:spec`
+
+**How to decide:**
+- Adding a column + updating one endpoint = small
+- New feature with migration + service + controller + frontend = big
+- If unclear, ask one question: "Quick estimate — is this a few hours or multiple days?"
+
+### Fast path (small work)
 
-If no spec exists, **ask 3 forcing questions. Always. Even in auto mode.**
+Ask 3 forcing questions. Always. Even in auto mode.
 
 1. **"What pain does this solve?"** — Not the feature. The pain. If the user says "add a profiles endpoint" ask what user problem it fixes.
 2. **"What's the narrowest version we can ship?"** — Force MVP thinking. Cut scope until it hurts.
 3. **"What assumption could be wrong?"** — Surface hidden risks early.
 
-After the user answers (or after reading the spec), produce a scope block:
+After the user answers, produce a scope block:
 
 ```markdown
 ## Scope: [feature name]
@@ -85,6 +122,15 @@ After the user answers (or after reading the spec), produce a scope block:
 **Risk:** [the assumption that could be wrong]
 ```
 
+### Full path (big work)
+
+Tell the user and run the spec command internally:
+> "This is bigger work — let me run a proper spec first."
+
+Use the approach from `/spartan:spec` — ask questions one at a time, fill the template, run Gate 1, save to `.planning/specs/`.
+
+Then continue to the next stage automatically (don't tell the user to run a separate command).
+
 **GATE 1 — STOP and ask:**
 > "Here's the scope. Anything to change before I plan?"
 >
@@ -92,26 +138,49 @@ After the user answers (or after reading the spec), produce a scope block:
 
 ---
 
-## Stage 2: Plan
+## Stage 1.5: Design (UI work only — auto-detected)
 
-### Check for saved plan
+**Only runs if the feature has UI work.** Skip entirely for pure backend.
 
+Check if this feature needs a design:
+- Frontend mode? → Yes
+- Full-stack mode with UI changes? → Yes
+- Backend only? → Skip this stage
+
+Check if a design already exists:
 ```bash
-ls .planning/plans/*.md 2>/dev/null
+ls .planning/designs/*.md 2>/dev/null
 ```
 
-If a plan exists for this feature, read it and use it. Skip the inline planning — go straight to Stage 3 (Implement). Show:
-> "Found plan: `.planning/plans/{name}.md` — using it."
+If no design exists and UI work is needed:
+> "This has UI work. Want me to create a design doc?"
+>
+> - **A) Yes** — I'll run the design workflow (dual-agent review with design-critic)
+> - **B) Skip** — I'll design as I build (fine for simple UI changes)
+> - **C) I have Figma designs** — point me to them
 
-If no plan exists, do the size check below.
+If user picks A → use the approach from `/spartan:design` internally. Run the full design workflow including the design-critic agent review.
 
-### Size check
+If user picks B → continue to Plan.
 
-Count the expected work:
-- **Small** (1-4 tasks, < 1 day): Inline plan right here.
-- **Big** (5+ tasks, multi-day): Use `/spartan:phase plan` for a full wave-parallel plan.
+If user picks C → read the Figma reference and use it as the design source.
 
-### Inline plan format (small features)
+**Auto mode on?** → Skip for small UI changes (adding a column to a table, a toggle). Run for new screens/pages.
+
+---
+
+## Stage 2: Plan
+
+### Check for saved plan
+
+If a plan already exists for this feature, use it:
+> "Found plan: `.planning/plans/{name}.md` — using it."
+
+If no plan exists, do the size check:
+
+### Fast path (small — 1-4 tasks)
+
+Produce an inline plan:
 
 ```markdown
 ## Plan: [feature name]
@@ -127,7 +196,13 @@ Verify: [how to confirm]
 ...
 ```
 
-**Max 4 tasks for inline plan.** If you need more, it's a big feature — use `/spartan:phase`.
+**Max 4 tasks for inline plan.** If you need more, use the full path.
+
+### Full path (big — 5+ tasks)
+
+Use the approach from `/spartan:plan` internally — architecture design, file locations, phased tasks with parallel/sequential marking. Save to `.planning/plans/`.
+
+Then continue automatically.
 
 ### What the plan includes (by mode)
 
@@ -211,13 +286,15 @@ npm test
 **GATE 3 — STOP and ask:**
 > "All [N] tasks done. [X] tests passing. Ready for review?"
 >
-> If 3+ tasks were completed, suggest: "Want a dual-agent review? Run `/spartan:gate-review`"
+> If 3+ tasks were completed: "I'll run a self-review now. For a deeper dual-agent review, say 'gate review'."
 >
-> **Auto mode on?** → Continue to Ship immediately.
+> **Auto mode on?** → Continue to Review immediately.
 
 ---
 
-## Stage 4: Ship
+## Stage 3.5: Review (auto-runs)
+
+This stage runs automatically after implementation. You don't wait for the user to run a separate review command.
 
 ### Self-review
 - **Backend code** → use the approach from `/spartan:review`
@@ -229,23 +306,68 @@ Fix any issues found during review. Commit fixes separately:
 fix([scope]): [what review caught]
 ```
 
+### Dual-agent review (optional, on request)
+If the user says "gate review" or if the feature is large (5+ tasks), offer to spawn the gate-review approach:
+> "Want a dual-agent gate review? This spawns a reviewer agent for a second opinion."
+
+If yes → use the approach from `/spartan:gate-review` internally.
+
+---
+
+## Stage 4: Ship
+
 ### Create PR
 Run the approach from `/spartan:pr-ready`:
 - Rebase onto main
 - Run all checks one final time
 - Create PR with clear title, summary, and test plan
 
+### Save to memory (if something notable was learned)
+
+After the PR is created, check if this build revealed anything worth remembering:
+
+- **New pattern discovered?** → Save to `.memory/patterns/`
+- **Architecture decision made?** → Save to `.memory/decisions/`
+- **Gotcha or workaround found?** → Save to `.memory/knowledge/`
+- **Nothing notable?** → Skip. Don't save noise.
+
+```bash
+mkdir -p .memory/decisions .memory/patterns .memory/knowledge
+```
+
+Update `.memory/index.md` if you saved anything.
+
 **GATE 4 — Done.**
 > "PR created: [link]. Here's what's in it: [summary]."
 
 ---
 
+## Resume: Picking Up Where You Left Off
+
+If a previous session was interrupted (context overflow, user stopped, etc.), this workflow can resume.
+
+**How resume works:**
+1. Step 0.5 checks for `.handoff/` files and existing `.planning/` artifacts
+2. Determine which stage was completed last:
+   - Has spec but no plan → resume at Stage 2 (Plan)
+   - Has plan but no commits on feature branch → resume at Stage 3 (Implement)
+   - Has commits but no PR → resume at Stage 4 (Ship)
+3. Show the user: "Resuming from [stage]. Here's what was done: [summary]."
+4. Continue from that point.
+
+**Don't re-do completed stages.** Read the saved artifacts and move forward.
+
+---
+
 ## Rules
 
-- **Always start at Stage 1.** Don't skip the 3 questions. They prevent building the wrong thing.
-- **Gates are mandatory.** Even small features go through all 4 stages. The stages are fast for small work — that's fine.
+- **You are the orchestrator.** Don't tell the user to run `/spartan:spec` or `/spartan:plan` separately. Run those approaches yourself when needed.
+- **Fast path is the default for small work.** If the whole thing is 1-4 tasks, do everything inline. Don't force the user through 3 separate commands.
+- **Full path for big work.** If 5+ tasks, save artifacts to `.planning/` so future sessions can pick up.
+- **Gates are mandatory.** Even small features go through all stages. The stages are fast for small work — that's fine.
 - **TDD by default.** Write the test first. Override only when test-first doesn't make sense for that specific task.
 - **One commit per task.** Don't batch. Each task = one commit with a clear message.
-- **Security check always runs.** Whether backend or frontend, security patterns get checked at the end of Stage 3.
+- **Security check always runs.** Whether backend or frontend, security patterns get checked during review.
 - **Frontend checks for backend needs.** If a new page needs data that doesn't exist yet, say so at Stage 2 and add backend tasks first.
 - **Don't over-plan.** If the whole thing is 1-2 files and 30 minutes of work, don't force it into this workflow. Just do it. This workflow is for features that need structure — at least 2-3 tasks.
+- **Save state for big work.** If 5+ tasks, save artifacts to `.planning/` so future sessions can resume.