@c0x12c/spartan-ai-toolkit 1.2.1 → 1.3.0

package/.claude-plugin/marketplace.json

@@ -8,9 +8,9 @@
   "plugins": [
     {
       "name": "spartan-ai-toolkit",
-      "description": "5 workflows, 51 commands, 11 rules, 19 skills, 4 agents — organized in 11 packs with dependencies",
+      "description": "5 workflows, 53 commands, 11 rules, 19 skills, 4 agents — organized in 11 packs with dependencies",
       "source": "./toolkit",
-      "version": "1.2.1"
+      "version": "1.3.0"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "spartan-ai-toolkit",
-  "version": "1.2.1",
-  "description": "Engineering discipline layer for Claude Code — 5 workflows, 51 commands, 11 rules, 19 skills, 4 agents organized in 11 packs",
+  "version": "1.3.0",
+  "description": "Engineering discipline layer for Claude Code — 5 workflows, 53 commands, 11 rules, 19 skills, 4 agents organized in 11 packs",
   "author": {
     "name": "Khoa Tran",
     "url": "https://github.com/spartan-stratos"

package/README.md

@@ -66,7 +66,8 @@ After install, open any project, run `claude`, then type `/spartan`.
 **Direct commands** — one command, one job. Best when you know what step you need. Saves tokens.
 
 ```
-/spartan:quickplan "task"   ← just the planning step
+/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
@@ -135,7 +136,7 @@ npx @c0x12c/spartan-ai-toolkit@latest --all
 
 | Pack | Category | Depends on | What you get |
 |------|----------|------------|--------------|
-| **core** | Core | — | Always installed. Workflows (build, fix, onboard), quickplan, pr-ready, daily, safety commands |
+| **core** | Core | — | Always installed. Workflows (build, fix, onboard), spec, plan, pr-ready, daily, safety commands |
 | **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 |
@@ -151,7 +152,7 @@ Hidden packs (`database`, `shared-backend`) get pulled in as dependencies — yo
 
 ## Commands
 
-All commands start with `/spartan:` (e.g., `/spartan:quickplan "task"`).
+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.
 
@@ -167,7 +168,8 @@ Type `/spartan` to get the smart router — it asks what you need and picks the
 ### Core (always installed)
 | Command | What it does |
 |---------|-------------|
-| `quickplan "task"` | Task < 1 day — spec + plan + branch in one shot |
+| `spec "feature"` | Write a feature spec — saves to `.planning/specs/` |
+| `plan "feature"` | Write implementation plan from spec — saves to `.planning/plans/` |
 | `daily` | Standup summary from git history |
 | `pr-ready` | Full checklist before creating any PR |
 | `init-project` | Auto-generate CLAUDE.md from codebase scan |

package/VERSION

@@ -1 +1,2 @@
-1.2.1
+1.3.0
+

package/claude-md/00-header.md

@@ -34,6 +34,6 @@ What do you need?
 | Size | Use |
 |---|---|
 | < 30 min, ≤ 3 files | Just ask Claude (no command needed) |
-| < 1 day | `/spartan:quickplan` |
-| 1–3 days | `/spartan:project new` (lightweight lifecycle) |
+| < 1 day | `/spartan:spec` → `/spartan:build` |
+| 1–3 days | `/spartan:spec` → `/spartan:plan` → `/spartan:build` |
 | > 3 days, multi-session | `/spartan:project new` (full lifecycle) |

package/claude-md/01-core.md

@@ -7,7 +7,7 @@
 **Detect the language of the user's message and respond entirely in that same language.** This is not optional — it overrides the default English behavior of all commands. If the user writes in Vietnamese, ALL output must be in Vietnamese. If in French, respond in French. If in English, respond in English. This applies to everything: explanations, questions, gate prompts, debug reports, summaries, and PR descriptions. Only code syntax, variable names, file paths, and command names (e.g., `/spartan:fix`) stay in their original form.
 
 ### 2. Spec Before Code
-- Task < 1 day → `/spartan:quickplan` for fast spec + plan
+- Task < 1 day → `/spartan:spec` + `/spartan:plan` + `/spartan:build`
 - Task > 1 day → `/spartan:project new` or `/spartan:project milestone-new`
 - Never write production code without a written spec or plan
 
@@ -61,6 +61,19 @@ Auto mode is ideal for experienced users who trust the workflow and want maximum
 
 ## Core Commands (always available)
 
+### Feature Workflow
+```
+/spartan:epic → /spartan:spec → [/spartan:design] → /spartan:plan → /spartan:build → /spartan:pr-ready
+                     ↑                                    ↑                ↑                ↑
+                   Gate 1                               Gate 2         Gate 3            Gate 4
+```
+
+| Size | Path |
+|---|---|
+| Single feature | `/spartan:spec` → `/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 |
+
 ### Workflows (start here)
 | Command | Purpose |
 |---|---|
@@ -69,10 +82,16 @@ Auto mode is ideal for experienced users who trust the workflow and want maximum
 | `/spartan:fix "symptom"` | Bug workflow: reproduce → investigate → fix → PR |
 | `/spartan:onboard` | Codebase understanding: scan → map → setup |
 
+### Spec & Plan (saved artifacts)
+| Command | Purpose |
+|---|---|
+| `/spartan:spec "feature"` | Write a feature spec → saves to `.planning/specs/` → Gate 1 |
+| `/spartan:plan "feature"` | Write implementation plan from spec → saves to `.planning/plans/` → Gate 2 |
+| `/spartan:epic "name"` | Break big work into ordered features → saves to `.planning/epics/` |
+
 ### Individual Commands
 | Command | Purpose |
 |---|---|
-| `/spartan:quickplan "task"` | Spec + plan + branch in one shot (< 1 day) |
 | `/spartan:pr-ready` | Pre-PR checklist + auto PR description |
 | `/spartan:daily` | Standup summary from git log |
 | `/spartan:init-project` | Auto-generate CLAUDE.md from codebase |

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

@@ -27,7 +27,7 @@ See `templates/workflow-frontend-react.md` for the full workflow with:
 - File location guide (App Router conventions)
 - Parallel vs sequential task planning
 
-For small tasks (< 1 day), `/spartan:quickplan` covers spec + plan in one shot.
+For any feature, use `/spartan:spec` → `/spartan:plan` → `/spartan:build`.
 
 ### Frontend Skills
 

package/claude-md/30-project-mgmt.md

@@ -5,6 +5,7 @@
 
 | Command | Purpose |
 |---|---|
+| `/spartan:epic "name"` | Break big work into ordered features → each goes through spec → plan → build |
 | `/spartan:project [action]` | Manage large projects: `new`, `status`, `milestone-new`, `milestone-complete`, `milestone-summary`, `manager` |
 | `/spartan:phase [action] [N]` | Manage phases: `discuss`, `plan`, `execute`, `verify` |
 | `/spartan:workstreams [action]` | Parallel workstreams: `list`, `create`, `switch`, `status`, `progress`, `complete`, `resume` |

package/claude-md/40-product.md

@@ -19,7 +19,9 @@ These commands help you think deep before writing code. Use them when starting a
        ↓
 /spartan:think "feature"          ← 6-phase deep thinking before code
        ↓
-/spartan:quickplan "task"         ← Then build it
+/spartan:spec "task"              ← Write the spec
+/spartan:plan "task"              ← Plan the work
+/spartan:build "task"             ← Then build it
 ```
 
 You don't have to use all of them. Pick what fits your stage.

package/commands/spartan/brownfield.md

@@ -154,4 +154,4 @@ This prevents scope creep and keeps each change independently reviewable.
 
 After analysis, present the Context Map summary and ask:
 "Analysis complete. What change would you like to make first?
-I'll create a change folder and use `/spartan:quickplan` for it."
+I'll create a change folder and use `/spartan:spec` → `/spartan:build` for it."

package/commands/spartan/build.md

@@ -52,13 +52,21 @@ ls .planning/PROJECT.md 2>/dev/null && echo "GSD_ACTIVE"
 
 ## Stage 1: Understand
 
-**Ask 3 forcing questions. Always. Even in auto mode.**
+**First, check for a saved spec:**
+```bash
+ls .planning/specs/*.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 no spec exists, **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, produce a scope block:
+After the user answers (or after reading the spec), produce a scope block:
 
 ```markdown
 ## Scope: [feature name]
@@ -86,10 +94,21 @@ After the user answers, produce a scope block:
 
 ## Stage 2: Plan
 
+### Check for saved plan
+
+```bash
+ls .planning/plans/*.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 plan exists, do the size check below.
+
 ### Size check
 
 Count the expected work:
-- **Small** (1-4 tasks, < 1 day): Inline plan right here. Like a mini-quickplan.
+- **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.
 
 ### Inline plan format (small features)

package/commands/spartan/epic.md

@@ -0,0 +1,190 @@
+---
+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."
+>
+> **The workflow for each feature:**
+> ```
+> /spartan:spec [feature-name]     ← write the spec, pass Gate 1
+> /spartan:design [feature-name]   ← if it has UI work (optional)
+> /spartan:plan [feature-name]     ← write the plan, pass Gate 2
+> /spartan:build [feature-name]    ← build it, TDD, pass Gates 3-4
+> ```
+>
+> **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/map-codebase.md

@@ -66,7 +66,7 @@ Once mapping is complete, suggest next steps based on context:
 
 - **Starting a new project?** → `/spartan:project new` (map feeds into roadmap creation)
 - **Planning a phase?** → `/spartan:phase plan N` (agents read codebase docs automatically)
-- **Major refactoring?** → `/spartan:quickplan "refactor description"` (informed by CONCERNS.md)
+- **Major refactoring?** → `/spartan:spec "refactor description"` → `/spartan:build` (informed by CONCERNS.md)
 - **Team onboarding?** → Share `.planning/codebase/` docs with new team members
 
 The codebase map is consumed automatically by GSD planning and execution agents — no manual wiring needed.

package/commands/spartan/plan.md

@@ -0,0 +1,210 @@
+---
+name: spartan:plan
+description: Write an implementation plan — reads spec, designs architecture, breaks into tasks, runs Gate 2
+argument-hint: "[feature name]"
+preamble-tier: 3
+---
+
+# Plan: {{ args[0] | default: "unnamed feature" }}
+
+You are running the **Plan workflow** — turn a spec into a concrete implementation plan with architecture, file locations, and ordered tasks.
+
+```
+Epic → Spec → [Design] → ► Plan → Build → Review
+                               ↑
+                             Gate 2
+```
+
+The plan gets saved to `.planning/plans/{{ args[0] | default: "feature-name" }}.md`.
+
+---
+
+## Step 0: Find the Spec
+
+Look for the spec in this order:
+1. `.planning/specs/{{ args[0] | default: "feature-name" }}.md`
+2. If not found, ask: "No spec found for **{{ args[0] }}**. Want to:"
+   - A) Write the spec first → `/spartan:spec {{ args[0] }}`
+   - B) Give me a quick description and I'll plan from that (skip spec)
+
+If spec exists, read it. Confirm:
+> "Found spec: `.planning/specs/{{ args[0] }}.md`. Planning from this."
+
+Also check:
+```bash
+mkdir -p .planning/plans
+ls .planning/plans/{{ args[0] | default: "feature-name" }}.md 2>/dev/null
+```
+
+If a plan already exists, ask:
+> "A plan for **{{ args[0] }}** already exists. Want to **update** it or **start fresh**?"
+
+---
+
+## Step 1: Detect Stack
+
+Same auto-detect as `/spartan:build`:
+```bash
+ls build.gradle.kts settings.gradle.kts 2>/dev/null && echo "STACK:kotlin-micronaut"
+ls package.json 2>/dev/null && cat package.json 2>/dev/null | grep -q '"next"' && echo "STACK:nextjs-react"
+```
+
+| Detected | Mode |
+|----------|------|
+| Kotlin only | Backend plan |
+| Next.js only | Frontend plan |
+| Both | Ask: "Backend, frontend, or full-stack plan?" |
+| Neither | Ask the user |
+
+---
+
+## Step 2: Design Architecture
+
+Based on the spec and detected stack, lay out:
+
+### Components Table
+List every component this feature needs:
+```markdown
+| Component | Type | Purpose |
+|-----------|------|---------|
+| [Name] | [Controller / Manager / Service / Repository / Component / Hook / etc.] | [what it does] |
+```
+
+### File Locations Table
+Where every file goes:
+```markdown
+| File | Location | Purpose |
+|------|----------|---------|
+| [file name] | [directory path] | [what it does] |
+```
+
+### Files to Change
+Existing files that need changes:
+```markdown
+| File | What Changes | Why |
+|------|-------------|-----|
+| [file path] | [description] | [reason] |
+```
+
+**Backend plans** follow: Controller → Manager → Repository (layered architecture).
+**Frontend plans** follow: Types → Components → Pages → State.
+**Full-stack plans** do backend first, then frontend. Mark the integration point.
+
+---
+
+## Step 3: Break into Tasks
+
+Split the work into phases with ordered tasks.
+
+### Phase ordering by stack:
+
+**Backend:** Database → Business Logic → API → Tests
+**Frontend:** Types/Interfaces → Components → Pages/Routes → Tests
+**Full-stack:** Database → API → Types → Components → Integration → Tests
+
+### Task rules:
+- Each task: max 3 files, one commit
+- Each task has: description, files, what to test
+- Group into phases by dependency
+- Mark parallel vs sequential
+
+### Format:
+```markdown
+### Phase 1: [name]
+
+| # | Task | Files |
+|---|------|-------|
+| 1 | [description] | [file(s)] |
+| 2 | [description] | [file(s)] |
+
+### Phase 2: [name] (depends on Phase 1)
+
+| # | Task | Files |
+|---|------|-------|
+| 3 | [description] | [file(s)] |
+```
+
+### Parallel vs Sequential table:
+```markdown
+| Parallel Group | Tasks | Why |
+|---------------|-------|-----|
+| Group A | 1, 2 | independent files |
+
+| Sequential | Depends On | Why |
+|-----------|-----------|-----|
+| Task 3 | Task 1, 2 | needs their output |
+```
+
+---
+
+## Step 4: Testing Plan
+
+Map tests from the spec's testing criteria:
+
+- **Data layer tests** — insert, read, update, soft delete, query filters
+- **Business logic tests** — happy path, error cases, validation
+- **API / integration tests** — endpoints, auth, invalid input
+- **UI tests** (if applicable) — render, interaction, states
+
+Each test ties back to a spec requirement or edge case.
+
+---
+
+## Step 5: Run Gate 2
+
+Before saving, run the Gate 2 checklist from `quality-gates.md`:
+
+**Architecture:**
+- [ ] Follows the project's existing architecture patterns
+- [ ] Each layer only calls the layer below it
+- [ ] Components are in the right directories
+
+**Task Breakdown:**
+- [ ] All files to change are listed
+- [ ] All new files are listed with their locations
+- [ ] Each task is small (one file or one function)
+- [ ] Dependencies between tasks are clear
+- [ ] Parallel vs sequential tasks are marked
+
+**Testing:**
+- [ ] Data layer tests planned
+- [ ] Business logic tests planned
+- [ ] API/integration tests planned
+- [ ] UI tests planned (if applicable)
+- [ ] Edge cases from spec are covered in test plan
+
+If any item fails → fix it before saving.
+
+---
+
+## Step 6: Save and Confirm
+
+Save the plan to `.planning/plans/{{ args[0] | default: "feature-name" }}.md`.
+
+Set the metadata:
+```
+**Spec**: .planning/specs/{{ args[0] }}.md
+**Epic**: [epic name or "none"]
+**Created**: [today's date]
+**Status**: draft
+```
+
+Then tell the user:
+
+> "Plan saved to `.planning/plans/{{ args[0] }}.md` — Gate 2 passed."
+>
+> **Next steps:**
+> - Small feature (1-4 tasks)? → `/spartan:build {{ args[0] }}`
+> - Big feature (5+ tasks)? → `/spartan:phase execute N`
+> - Want a dual-agent review first? → `/spartan:gate-review`
+
+---
+
+## Rules
+
+- **Read the spec first.** Don't invent requirements the spec doesn't have.
+- **Match the codebase.** Check existing patterns before proposing architecture. Run searches to find how similar features are built.
+- **Small tasks.** Each task = one commit, max 3 files, completable in minutes not hours.
+- **Gate 2 is not optional.** Every plan must pass before saving.
+- **Auto mode on?** → Skip confirmations, show the plan and save it directly.
+- **Link back to spec.** Every task should trace to a spec requirement. If a task doesn't come from the spec, question why it's there.

package/commands/spartan/spec.md

@@ -0,0 +1,131 @@
+---
+name: spartan:spec
+description: Write a feature spec — interactive Q&A, saves to .planning/specs/, runs Gate 1
+argument-hint: "[feature name]"
+preamble-tier: 3
+---
+
+# Spec: {{ args[0] | default: "unnamed feature" }}
+
+You are running the **Spec workflow** — turn a feature idea into a clear, written spec that other commands (`/spartan:plan`, `/spartan:build`) can use.
+
+The spec gets saved to `.planning/specs/{{ args[0] | default: "feature-name" }}.md`.
+
+---
+
+## Step 0: Setup
+
+Create the directory if it doesn't exist:
+```bash
+mkdir -p .planning/specs
+```
+
+Check if a spec already exists:
+```bash
+ls .planning/specs/{{ args[0] | default: "feature-name" }}.md 2>/dev/null
+```
+
+If it exists, ask:
+> "A spec for **{{ args[0] }}** already exists. Want to **update** it or **start fresh**?"
+>
+> - A) Update — I'll show you the current spec and we'll revise it
+> - B) Start fresh — overwrite with a new spec
+
+---
+
+## Step 1: Understand the Problem
+
+Ask these questions **one at a time**, not all at once. Wait for an answer before the next question.
+
+1. **"What problem does this solve?"** — Not the feature. The pain. If the user says "add a profiles endpoint", ask what user problem it fixes.
+
+2. **"Who's affected and how?"** — Get at least one concrete user story. Push for specifics: role, action, benefit.
+
+3. **"What's out of scope?"** — Force the user to draw a line. What are we NOT building? This prevents scope creep later.
+
+4. **"Any data or API changes needed?"** — Only ask if it's backend-touching. Skip for pure frontend or config changes.
+
+5. **"What could go wrong?"** — Get at least 3 edge cases. Prompt with examples if the user is stuck: "What about empty data? Concurrent access? Permission denied?"
+
+---
+
+## Step 2: Fill the Template
+
+Use the `feature-spec.md` template structure. Fill in every section from the user's answers.
+
+The spec must have:
+- **Problem** — 2-3 sentences, specific
+- **Goal** — what success looks like
+- **User Stories** — at least 1, in "As a [role]..." format
+- **Requirements** — must-have, nice-to-have, out of scope
+- **Data Model** — if applicable (tables, columns, types)
+- **API Changes** — if applicable (endpoints, request/response)
+- **UI Changes** — if applicable (screens, components)
+- **Edge Cases** — at least 3
+- **Testing Criteria** — happy path + edge case tests
+- **Dependencies** — what this needs to work
+
+Set the metadata:
+```
+**Created**: [today's date]
+**Status**: draft
+**Author**: [user's name or "team"]
+**Epic**: [epic name if part of one, otherwise "none"]
+```
+
+---
+
+## Step 3: Run Gate 1
+
+Before saving, run the Gate 1 checklist from `quality-gates.md`:
+
+**Completeness:**
+- [ ] Problem is clearly stated (not vague)
+- [ ] Goal is specific and measurable
+- [ ] At least one user story exists
+- [ ] Requirements split into must-have, nice-to-have, out of scope
+- [ ] Out of scope section exists
+
+**Data Model** (if applicable):
+- [ ] New tables have standard columns (id, timestamps)
+- [ ] Column types are correct
+- [ ] Soft delete strategy is defined
+
+**API Design** (if applicable):
+- [ ] Endpoints follow project naming convention
+- [ ] Request/response examples included
+- [ ] JSON field naming matches project convention
+
+**Quality:**
+- [ ] Edge cases listed (at least 3)
+- [ ] Testing criteria for happy path
+- [ ] Testing criteria for edge cases
+- [ ] Dependencies listed
+
+If any item fails → fix it before saving. Don't skip the gate.
+
+---
+
+## Step 4: Save and Confirm
+
+Save the spec to `.planning/specs/{{ args[0] | default: "feature-name" }}.md`.
+
+Then tell the user:
+
+> "Spec saved to `.planning/specs/{{ args[0] }}.md` — Gate 1 passed."
+>
+> **Next steps:**
+> - Has UI work? → `/spartan:design {{ args[0] }}`
+> - Ready to plan? → `/spartan:plan {{ args[0] }}`
+> - Part of a bigger epic? → `/spartan:epic`
+
+---
+
+## Rules
+
+- **One feature per spec.** If the user describes multiple features, suggest splitting into separate specs or using `/spartan:epic` first.
+- **Ask questions one at a time.** Don't dump all 5 questions in one message.
+- **Use the Structured Question Format** when asking for decisions: simplify → recommend → options (A/B/C) → one decision per turn.
+- **Be specific.** Push back on vague answers. "Make it faster" → "What's the target latency?"
+- **Gate 1 is not optional.** Every spec must pass before saving.
+- **Auto mode on?** → Still ask the questions, but skip the "anything to change?" confirmation. Show the spec and save it.

package/commands/spartan/think.md

@@ -208,7 +208,7 @@ Ask: **"This is the final scope. Ready to build?"**
 
 Based on the T-shirt size from Phase 4, route to the right build command:
 
-- **S (< 1 day):** "Run `/spartan:quickplan` with this scope to start building."
+- **S (< 1 day):** "Run `/spartan:spec` then `/spartan:build` with this scope to start building."
 - **M-L (1-7 days):** "Run `/spartan:project new` to set up the full project lifecycle."
 - **XL (> 1 week):** "Run `/spartan:project new` — this needs milestones and wave planning."
 

package/commands/spartan/workstreams.md

@@ -42,7 +42,7 @@ Create a new parallel workstream for independent work.
 **Run:** `/gsd:workstreams create {{ args[1] | default: "<name>" }}`
 
 After creation, tell the user:
-"Workstream '{{ args[1] | default: "<name>" }}' created. You are now working in this workstream. Next step: `/spartan:project new` or `/spartan:quickplan` to start work."
+"Workstream '{{ args[1] | default: "<name>" }}' created. You are now working in this workstream. Next step: `/spartan:project new` or `/spartan:spec` to start work."
 
 {% elif args[0] == "switch" %}
 ## Switch Workstream: {{ args[1] | default: "<name>" }}

package/commands/spartan.md

@@ -104,7 +104,7 @@ Route here when the user wants a specific tool, not a full workflow.
 **Planning & project management:**
 | User says... | Route to |
 |---|---|
-| "plan a task" (small, < 1 day) | `/spartan:quickplan` |
+| "plan a task", "write a spec" | `/spartan:spec` → `/spartan:plan` |
 | "big project", "multi-day", "new milestone" | `/spartan:project new` |
 | "continue phase", "next phase" | `/spartan:phase` |
 | "workstreams", "parallel work" | `/spartan:workstreams` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c0x12c/spartan-ai-toolkit",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Engineering discipline layer for AI coding agents — commands, rules, skills, agents, and packs for Claude Code",
   "type": "module",
   "bin": {

package/packs/core.yaml

@@ -5,10 +5,11 @@ priority: 0
 hidden: false
 
 commands:
+  - spec
+  - plan
   - build
   - fix
   - onboard
-  - quickplan
   - daily
   - context-save
   - update

package/packs/packs.compiled.json

@@ -8,10 +8,11 @@
       "comingSoon": false,
       "depends": [],
       "commands": [
+        "spec",
+        "plan",
         "build",
         "fix",
         "onboard",
-        "quickplan",
         "daily",
         "context-save",
         "update",
@@ -175,6 +176,7 @@
       "comingSoon": false,
       "depends": [],
       "commands": [
+        "epic",
         "project",
         "phase",
         "workstreams",

package/packs/project-mgmt.yaml

@@ -5,6 +5,7 @@ priority: 30
 hidden: false
 
 commands:
+  - epic
   - project
   - phase
   - workstreams

package/templates/epic.md

@@ -96,5 +96,5 @@ What could block us or go wrong?
 |-----------|-----|
 | Big feature set (3+ features, multi-week) | This epic template |
 | Single feature (1-3 days) | Skip epic, start with `feature-spec.md` |
-| Quick task (< 1 day) | Skip both, use `/spartan:quickplan` |
+| Quick task (< 1 day) | Skip epic, use `/spartan:spec` → `/spartan:build` |
 | Product-level vision doc for stakeholders | Use `prd-template.md` instead |

package/commands/spartan/quickplan.md

@@ -1,122 +0,0 @@
----
-name: spartan:quickplan
-description: Fast-forward planning — scaffold spec + plan + branch in one shot for tasks too small for full GSD lifecycle but too important to skip planning.
-argument-hint: "[task description]"
----
-
-# Quick Plan: {{ args[0] }}
-
-You are running a **fast-forward planning session** — inspired by OpenSpec's `/opsx:ff`.
-Goal: go from idea → actionable plan in one pass, without multi-step ceremony.
-
-This command is for tasks that are:
-- Too small for a full GSD milestone (< 1 day of work)
-- Too important to just "vibe code" without a plan
-- Self-contained with clear scope
-
----
-
-## Step 1: Research (parallel, 2 min)
-
-Run these two investigations simultaneously using subagents:
-
-**Subagent A — Codebase scan:**
-- Find all files relevant to: {{ args[0] }}
-- Identify existing patterns, conventions already in use
-- Note any tests that might be affected
-
-**Subagent B — Impact analysis:**
-- What could break?
-- Any DB migrations needed?
-- API contract changes?
-- Dependencies between services?
-
----
-
-## Step 2: Generate Spec (inline, no file needed)
-
-Present a concise spec in this format. Keep it under 30 lines:
-
-```markdown
-## Spec: [task name]
-
-**Goal:** [one sentence — what success looks like]
-
-**Scope:**
-- IN: [what will be built]
-- OUT: [what is explicitly NOT in scope]
-
-**Acceptance criteria:**
-1. [testable criterion]
-2. [testable criterion]
-3. [testable criterion]
-
-**Approach:** [2-3 sentences on implementation approach]
-
-**Risks / unknowns:** [any?]
-```
-
-Ask: "Does this spec match your intent? Any changes before we plan?"
-**Auto mode on?** → Skip this question, continue immediately. Show spec but don't wait.
-**Auto mode off (default)?** → Wait for approval. If the user says "yes" / "go" / "lgtm" → continue.
-
----
-
-## Step 3: Generate Plan (immediately after spec approval)
-
-Break into **max 4 atomic tasks**. Each task must:
-- Be completable in one commit
-- Have a clear verification step
-- Follow TDD (test first)
-
-Format:
-```markdown
-## Plan: [task name]
-Branch: feature/[ticket-or-slug]
-
-### Task 1: [name]
-Files: [exact file paths]
-Test first: [what test to write]
-Implementation: [what to change]
-Commit: feat([scope]): [message]
-Verify: [how to confirm it works]
-
-### Task 2: ...
-```
-
----
-
-## Step 4: Create branch + first test
-
-```bash
-git checkout -b feature/[slug]
-```
-
-Then immediately write the first failing test for Task 1.
-Do NOT write any production code yet.
-
-Show the red test output, then:
-**Auto mode on?** → Immediately start executing task by task. Don't wait.
-**Auto mode off?** → Say "Plan is ready. Say **'go'** to start executing task by task, or **'adjust'** to modify the plan."
-
----
-
-## Execution mode (after "go")
-
-Execute each task in sequence:
-1. Write test → confirm it fails (red)
-2. Write minimal implementation → confirm test passes (green)
-3. Refactor if needed
-4. Commit with atomic message
-5. Show summary, move to next task
-
-After all tasks: run full test suite, then say:
-"All tasks complete. Ready for `/spartan:pr-ready` to prep the PR."
-
-## Rules
-
-- Max 4 tasks — if you need more, the scope is too big for quickplan
-- Every task must be one commit
-- Test first (TDD) — write the failing test before the implementation
-- Don't skip the spec approval step unless auto mode is on
-- Keep the spec under 30 lines — if it's longer, use `/spartan:phase` instead