@c0x12c/spartan-ai-toolkit 1.6.2 → 1.6.4

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "spartan-ai-toolkit",
       "description": "5 workflows, 56 commands, 12 rules, 22 skills, 7 agents — organized in 11 packs with dependencies",
       "source": "./toolkit",
-      "version": "1.6.2"
+      "version": "1.6.4"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "spartan-ai-toolkit",
-  "version": "1.6.2",
+  "version": "1.6.4",
   "description": "Engineering discipline layer for Claude Code — 5 workflows, 56 commands, 12 rules, 22 skills, 7 agents organized in 11 packs",
   "author": {
     "name": "Khoa Tran",

package/VERSION

@@ -1 +1 @@
-1.6.2
+1.6.4

package/commands/spartan/build.md

@@ -12,16 +12,24 @@ You are the **Build workflow leader** — the main way to go from requirement to
 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.
 
 ```
-PIPELINE:
+SINGLE FEATURE:
 
-  Check Context → Spec → Design? → Plan → Implement → Review → Ship
-       │            │        │         │        │          │       │
-   .memory/    Gate 1    Design    Gate 2   Gate 3    Gate 3.5  Gate 4
-   .planning/           Gate (UI)
+  Context → Spec → Design? → Plan → Implement → Review Agent → Fix → Ship
+     │        │        │        │        │            │          │       │
+  .memory/ Gate 1   Design   Gate 2   Gate 3    Spawn agent   Loop   Gate 4
+                    Gate                        fix until OK
+
+EPIC (multi-feature — auto-detected):
+
+  Context → Epic detected → Per feature: Spec/Design/Plan → Implement → Review Agent → Fix → Ship
+     │            │                │                             │            │          │       │
+  .planning/  read epic    fill gaps if needed          parallel by      Spawn agent  Loop   one PR
+  epics/                                                dependency       fix until OK
 ```
 
 **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.
+**Epic path:** If the feature name matches an epic with 2+ specs ready, build all features together — one branch, one PR.
 
 ---
 
@@ -66,6 +74,9 @@ ls .planning/specs/*.md 2>/dev/null
 ls .planning/designs/*.md 2>/dev/null
 ls .planning/plans/*.md 2>/dev/null
 
+# Check for epic
+ls .planning/epics/*.md 2>/dev/null
+
 # Check for handoff from a previous session
 ls .handoff/*.md 2>/dev/null
 ```
@@ -79,6 +90,25 @@ ls .handoff/*.md 2>/dev/null
 **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."
 
+### Epic detection (auto — no questions)
+
+**If an epic exists** that matches the feature name (or the user passed an epic name):
+
+1. Read the epic file at `.planning/epics/{name}.md`
+2. Find all features listed in the epic's Features table
+3. Check which features have specs ready (status = `spec` or `planned`)
+4. Check which features are already `done` or `skipped`
+
+**If 2+ features have specs ready → switch to Epic mode:**
+> "Found epic **{name}** with {N} features. {X} specs ready, {Y} already done. Building all ready features together — one branch, one PR."
+
+Then jump to **Stage E: Epic Build** below.
+
+**If only 1 feature has a spec** → build that one normally (single feature mode).
+
+**If no features have specs yet** → tell the user to write specs first:
+> "Epic exists but no specs are ready. Run `/spartan:spec {first-feature}` to start."
+
 ---
 
 ## Stage 1: Understand (Spec)
@@ -138,7 +168,7 @@ Then continue to the next stage automatically (don't tell the user to run a sepa
 
 ---
 
-## Stage 1.5: Design (UI work only — auto-detected)
+## Stage 2: Design (UI work only — auto-detected)
 
 **Only runs if the feature has UI work.** Skip entirely for pure backend.
 
@@ -169,7 +199,7 @@ If user picks C → read the Figma reference and use it as the design source.
 
 ---
 
-## Stage 2: Plan
+## Stage 3: Plan
 
 ### Check for saved plan
 
@@ -241,7 +271,7 @@ Write the first failing test for Task 1. Show it fails.
 
 ---
 
-## Stage 3: Implement
+## Stage 4: Implement
 
 ### Auto-parallelize with Agent Teams
 
@@ -333,7 +363,7 @@ Call the right skills based on what you're doing:
 
 ### After all tasks — Verify Definition of Done
 
-**Before moving to Gate 3, verify ALL layers are complete:**
+**Before moving to review, verify ALL layers are complete:**
 
 | Mode | Must be done before review |
 |------|---------------------------|
@@ -348,7 +378,7 @@ Call the right skills based on what you're doing:
 4. API client has methods for all new endpoints
 5. UI shows the data from the new endpoints
 
-**If any layer is incomplete**, go back and finish it. Do NOT proceed to Gate 3 with only backend done.
+**If any layer is incomplete**, go back and finish it. Do NOT proceed to review with only backend done.
 
 Run the full test suite:
 ```bash
@@ -362,40 +392,93 @@ npm test && npm run build
 ./gradlew test && npm test && npm run build
 ```
 
-**GATE 3 — STOP and ask:**
-> "All [N] tasks done. [X] tests passing. Ready for review?"
->
-> **Full-stack:** "Backend: [N] tasks done, tests passing. Frontend: [N] tasks done, build passing. Ready for review?"
->
-> If 3+ tasks were completed: "I'll run a self-review now. For a deeper dual-agent review, say 'gate review'."
+**GATE 3 — Implementation complete.**
+> "All [N] tasks done. [X] tests passing. Starting review."
 >
-> **Auto mode on?** → Continue to Review immediately.
+> **Auto mode on?** → Go straight to review.
 
 ---
 
-## Stage 3.5: Review (auto-runs)
+## Stage 5: Review (agent-based — mandatory)
+
+**This is NOT a self-review.** Spawn a separate review agent to get a fresh perspective. The reviewer finds issues, you fix them, repeat until clean.
+
+### Step 1: Spawn the review agent
+
+Use the `Agent` tool to spawn a reviewer:
+
+```
+Agent:
+  name: "reviewer"
+  subagent_type: "phase-reviewer"  (or "general-purpose" if phase-reviewer not available)
+  prompt: |
+    You are reviewing code changes for the feature: {feature name}.
+
+    Review scope:
+    - Backend code: {list changed backend files}
+    - Frontend code: {list changed frontend files}
+    - Design doc: {path if exists, or "none"}
+
+    Run `git diff main...HEAD` to see all changes.
+
+    Review checklist:
+    **Code quality:** SOLID, clean code, no duplication, proper error handling
+    **Tests:** adequate coverage, edge cases, test quality
+    **Security:** auth, input validation, injection risks
+    **Stack conventions:** {backend: Kotlin/Micronaut rules | frontend: React/Next.js rules | both}
+    **Design compliance:** if a design doc exists, check that UI matches it
+
+    For each issue found, report:
+    - File and line
+    - What's wrong
+    - Severity: HIGH (must fix) / MEDIUM (should fix) / LOW (nice to have)
+    - Suggested fix
+
+    End with a verdict: **PASS** or **NEEDS CHANGES** (with the list of HIGH/MEDIUM issues).
+```
+
+### Step 2: Fix loop
+
+When the reviewer reports back:
+
+**If PASS** → continue to Ship.
+
+**If NEEDS CHANGES:**
+
+1. Read the reviewer's findings
+2. Fix all HIGH issues. Fix MEDIUM issues if they make sense.
+3. Commit fixes:
+   ```
+   fix([scope]): [what review caught]
+   ```
+4. Run tests again to make sure fixes didn't break anything
+5. Spawn the review agent AGAIN with the updated diff — only the remaining/new changes need review
+6. Repeat until the reviewer says PASS
+
+**Max 3 review rounds.** If still failing after 3 rounds, stop and ask the user:
+> "Review found issues I can't fully fix. Here's what's left: [list]. Want to continue anyway or address these manually?"
 
-This stage runs automatically after implementation. You don't wait for the user to run a separate review command.
+### Step 3: Parallel review with Agent Teams
+
+```bash
+echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not_set}"
+```
 
-### Self-review
-- **Backend code** → use the approach from `/spartan:review`
-- **Frontend code** → use the approach from `/spartan:fe-review`
-- **Both** → review backend first, then frontend
+**If Agent Teams is enabled**, always spawn parallel review agents for deeper coverage:
 
-Fix any issues found during review. Commit fixes separately:
 ```
-fix([scope]): [what review caught]
+Agent 1: "quality-reviewer" — code design, SOLID, conventions, stack rules
+Agent 2: "test-reviewer" — test coverage, edge cases, test quality
+Agent 3: "security-reviewer" (if auth/input/data code changed) — security checklist
 ```
 
-### 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."
+All agents review at the same time. Combine their findings. All must PASS before moving to Ship. If any says NEEDS CHANGES → fix loop applies to the combined findings.
 
-If yes → use the approach from `/spartan:gate-review` internally.
+**If Agent Teams is NOT enabled**, use a single review agent (Step 1 above).
 
 ---
 
-## Stage 4: Ship
+## Stage 6: Ship
 
 ### Create PR
 Run the approach from `/spartan:pr-ready`:
@@ -423,6 +506,84 @@ Update `.memory/index.md` if you saved anything.
 
 ---
 
+## Stage E: Epic Build (multi-feature mode)
+
+**This replaces Stages 1–4 when epic mode is active.** It builds all ready features from the epic on one branch and creates one PR. Review and Ship still run normally after.
+
+### Step 1: Collect and fill gaps
+
+Read the epic file. For each feature with status `spec`, `planned`, or `building`:
+
+1. Read its spec from `.planning/specs/`
+2. Read its design from `.planning/designs/` (if exists)
+3. Read its plan from `.planning/plans/` (if exists)
+
+**Fill gaps for each feature that's missing something:**
+
+| Missing | Action |
+|---------|--------|
+| Spec | Skip this feature — tell user to run `/spartan:spec {feature}` first |
+| Design (and feature has UI work) | Ask user: create design now or skip? Same logic as Stage 2 |
+| Plan | Generate a plan inline (fast path for small, full path for big) |
+
+**Use Agent Teams to fill gaps in parallel** (if enabled): When 2+ features need plans or designs generated, spawn one agent per feature to do this work at the same time. Each agent runs the spec/design/plan logic for its feature independently.
+
+```bash
+echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not_set}"
+```
+
+If Agent Teams enabled and 2+ features need plans:
+- Spawn one `general-purpose` agent per feature
+- Each agent generates the design (if needed) and plan for its feature
+- Collect results, save to `.planning/designs/` and `.planning/plans/`
+
+### Step 2: Sort by dependency and create branch
+
+Read the epic's Features table. Sort features by dependency order:
+- Features with no dependencies → can build first
+- Features that depend on others → build after their dependencies are done
+
+```bash
+git checkout -b feature/[epic-slug]
+```
+
+### Step 3: Implement in dependency order
+
+Go through features in dependency order. **When 2+ features have no dependency between them, build them at the same time using Agent Teams** (if enabled). Otherwise build one by one.
+
+```bash
+echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not_set}"
+```
+
+**For each feature (or group of parallel features):**
+
+1. **If Agent Teams enabled and 2+ features can run at the same time:**
+   - Spawn one agent per feature with `isolation: "worktree"`
+   - Each agent gets: its spec, design doc (if exists), plan, TDD instructions, relevant rules
+   - **Design doc handoff is MANDATORY** — every frontend/UI agent must read the design doc first
+   - Wait for all parallel agents to finish
+   - Merge worktrees, run full test suite
+   - If tests fail → fix before moving on
+
+2. **If sequential (Agent Teams not enabled or only one feature ready):**
+   - Build each task with TDD: test → implement → refactor → commit
+   - Follow the same skill routing as Stage 4
+
+3. **After each feature completes:**
+   - Update epic Features table (status → `done`)
+   - Check: does this unblock the next features? If yes, start those next.
+
+### Step 4: After all features built
+
+Run the full test suite. Then continue to **Stage 5: Review** — the review agent reviews ALL changes across all features. One review, one fix loop, one PR.
+
+**GATE 3 (Epic):**
+> "All {N} features built. {X} tests passing. Starting review."
+>
+> **Auto mode on?** → Go straight to review.
+
+---
+
 ## Resume: Picking Up Where You Left Off
 
 If a previous session was interrupted (context overflow, user stopped, etc.), this workflow can resume.
@@ -430,9 +591,9 @@ If a previous session was interrupted (context overflow, user stopped, etc.), th
 **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)
+   - Has spec but no plan → resume at Stage 3 (Plan)
+   - Has plan but no commits on feature branch → resume at Stage 4 (Implement)
+   - Has commits but no PR → resume at Stage 5 (Review) or Stage 6 (Ship)
 3. Show the user: "Resuming from [stage]. Here's what was done: [summary]."
 4. Continue from that point.
 
@@ -448,11 +609,14 @@ If a previous session was interrupted (context overflow, user stopped, etc.), th
 - **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.
+- **Review is always an agent.** Never self-review. Always spawn a separate review agent for a fresh perspective. Fix issues until the reviewer says PASS.
 - **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.
+- **Frontend checks for backend needs.** If a new page needs data that doesn't exist yet, say so at Stage 3 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.
 - **Full-stack = both layers done.** If the feature touches both backend and frontend, you MUST implement both before creating the PR. Backend-only completion is NOT "done" for a full-stack feature.
+- **Epic = one branch, one PR.** When building from an epic, all features go on one branch and ship as one PR. Don't create separate PRs per feature. Parallelize independent features with Agent Teams when available.
+- **Epic auto-detection.** If the user's feature name matches an epic in `.planning/epics/`, switch to epic mode automatically. Don't ask.
 
 ---
 
@@ -484,5 +648,5 @@ A feature is NOT done until every applicable item is checked:
 
 ### Always
 - [ ] Atomic commits (one per task)
-- [ ] Self-review passed (backend review + frontend review if applicable)
+- [ ] Review agent passed (all HIGH/MEDIUM issues fixed)
 - [ ] PR created with summary and test plan

package/commands/spartan/epic.md

@@ -141,13 +141,22 @@ Then tell the user:
 
 > "Epic saved to `.planning/epics/{{ args[0] }}.md` with [N] features."
 >
-> **The workflow for each feature:**
+> **Next steps:**
+>
+> 1. Write specs for each feature (can do multiple before building):
+> ```
+> /spartan:spec [feature-1]
+> /spartan:spec [feature-2]
+> /spartan:design [feature-2]   ← if it has UI work
+> /spartan:spec [feature-3]
 > ```
-> /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
+>
+> 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]`
 

package/package.json

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