@c0x12c/spartan-ai-toolkit 1.8.0 → 1.8.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "spartan-ai-toolkit",
       "description": "5 workflows, 68 commands, 21 rules, 28 skills, 9 agents — organized in 12 packs with dependencies",
       "source": "./toolkit",
-      "version": "1.8.0"
+      "version": "1.8.1"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "spartan-ai-toolkit",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "description": "Engineering discipline layer for Claude Code — 5 workflows, 68 commands, 21 rules, 28 skills, 9 agents organized in 12 packs",
   "author": {
     "name": "Khoa Tran",

package/README.md

@@ -58,9 +58,9 @@ After install, open any project, run `claude`, then type `/spartan`.
 Every feature follows the same pipeline. Skip steps that don't apply.
 
 ```
-/spartan:spec → /spartan:design → /spartan:plan → /spartan:build → /spartan:pr-ready
-      ↑              ↑                 ↑              ↑ + 3.5           ↑
-    Gate 1      Design Gate         Gate 2          Gate 3           Gate 4
+/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 |

package/VERSION

@@ -1 +1 @@
-1.8.0
+1.8.1

package/agents/design-critic.md

@@ -10,7 +10,7 @@ description: |
   </example>
 
   <example>
-  Context: /spartan:design command needs a second opinion on the UI.
+  Context: /spartan:ux prototype 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>

package/claude-md/01-core.md

@@ -63,15 +63,15 @@ 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
-                     ↑                ↑                   ↑              ↑ + 3.5           ↑
-                   Gate 1        Design Gate            Gate 2         Gate 3            Gate 4
+/spartan:epic → /spartan:spec → [/spartan:ux] → /spartan:plan → /spartan:build → /spartan:pr-ready
+                     ↑              ↑                 ↑              ↑ + 3.5           ↑
+                   Gate 1      Design Gate          Gate 2         Gate 3            Gate 4
 ```
 
 | Size | Path |
 |---|---|
 | Single feature (backend) | `/spartan:spec` → `/spartan:plan` → `/spartan:build` |
-| Single feature (with UI) | `/spartan:spec` → `/spartan:design` → `/spartan:plan` → `/spartan:build` |
+| Single feature (with UI) | `/spartan:spec` → `/spartan:ux prototype` → `/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,25 +22,20 @@ 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`
+**Design workflow:** `/spartan:spec` → `/spartan:ux prototype` → `/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.
+The `/spartan:ux` command handles the full design pipeline — from user research to design QA. The `prototype` sub-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
 
-### 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:ux [phase]` | UX design workflow — research, define, ideate, system, prototype, test, handoff, qa |
 | `/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/claude-md/25-ux-design.md

@@ -53,4 +53,4 @@ Once design tokens exist, ALL downstream commands enforce them:
 | `/spartan:build frontend` | Checks for design tokens, nudges if missing |
 | `/spartan:spec` (UI feature) | Checks for user research, suggests if missing |
 | `/spartan:fe-review` | Checks code against design tokens |
-| `/spartan:design` | Alias for `/spartan:ux prototype` |
+| `/spartan:figma-to-code` | Merges with existing design tokens if they exist |

package/commands/spartan/build.md

@@ -28,7 +28,7 @@ EPIC (multi-feature — auto-detected):
 ```
 
 **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.
+**Full path:** For bigger work, you call `/spartan:spec`, `/spartan:ux prototype`, `/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.
 
 ### Stages That MUST NOT Be Skipped
@@ -205,7 +205,7 @@ If no design exists and UI work is needed:
 > - **B) Skip** — I'll design as I build (fine for simple UI changes)
 > - **C) I have Figma designs** — point me to them
 
-If user picks A → use the approach from `/spartan:design` internally. Run the full design workflow including the design-critic agent review.
+If user picks A → use the approach from `/spartan:ux prototype` internally. Run the full design workflow including the design-critic agent review.
 
 If user picks B → continue to Plan.
 
@@ -308,60 +308,104 @@ echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not_set}"
 - All tasks depend on each other in a chain
 - Agent Teams env var is not set
 
-**How to run it:**
+**How to run it (follow this exact sequence):**
 
-1. Check for design doc:
+> **Sub-agents vs Agent Teams — know the difference:**
+> - `Agent(run_in_background: true)` = sub-agent. Same session, 1 node. **NOT a team.**
+> - `Agent(team_name: "...", name: "...")` = teammate. Separate session, own node, can message others. **This is what you want.**
+> - Without `team_name` param, agents ALWAYS spawn as sub-agents. The `team_name` param is what makes them teammates.
+
+1. Check for design doc and tokens:
 ```bash
-ls .planning/designs/*.md 2>/dev/null
+ls .planning/designs/*.md .planning/design/screens/*.md 2>/dev/null
+ls .planning/design/system/tokens.md .planning/design-config.md 2>/dev/null
 ```
 
-2. Use `TeamCreate` with name `build-{feature-slug}`.
+2. Create the team with `TeamCreate`:
+```
+TeamCreate(team_name: "build-{feature-slug}", description: "Building: {feature name}")
+```
 
-3. Create tasks from the plan. Set `addBlockedBy` for real dependencies only.
+3. Create tasks with `TaskCreate` — one per work item from the plan. Set dependencies:
+```
+TaskCreate(subject: "Implement user repository", description: "...")
+TaskCreate(subject: "Implement user controller", description: "...")
+TaskUpdate(taskId: "2", addBlockedBy: ["1"])  // controller depends on repository
+```
 
-4. Spawn agents with `isolation: "worktree"`. Split by mode:
+4. Spawn teammates with `Agent` — **MUST include `team_name` and `name` params:**
 
-**Full-stack** — two agents:
-- **backend-dev** — backend tasks, Kotlin/Micronaut rules
-- **frontend-dev** — frontend tasks, React/Next.js rules, design doc
+**Full-stack** — two teammates:
+```
+Agent(
+  team_name: "build-{feature-slug}",
+  name: "backend-dev",
+  subagent_type: "general-purpose",
+  isolation: "worktree",
+  prompt: "You are the backend developer for {feature}.
+    Check TaskList, claim backend tasks with TaskUpdate(owner: 'backend-dev').
+    Follow TDD. Read .memory/index.md for project context.
+    Rules: ~/.claude/rules/backend-micronaut/ and ~/.claude/rules/database/
+    When done with a task, mark it completed and check TaskList for next work."
+)
+
+Agent(
+  team_name: "build-{feature-slug}",
+  name: "frontend-dev",
+  subagent_type: "general-purpose",
+  isolation: "worktree",
+  prompt: "You are the frontend developer for {feature}.
+    Read design doc at .planning/designs/{feature}.md FIRST — follow it exactly.
+    {if design tokens exist: Read .planning/design/system/tokens.md — use these exact values, not Tailwind defaults.}
+    Check TaskList, claim frontend tasks with TaskUpdate(owner: 'frontend-dev').
+    Follow TDD. Rules: ~/.claude/rules/frontend-react/"
+)
+```
 
 **Backend-only** — split by layer:
-- **data-layer** — migration + entity + repository
-- **api-layer** — service + controller (blocked by data-layer)
+```
+Agent(team_name: "build-{slug}", name: "data-layer", ...,
+  prompt: "Migration + entity + repository + repo tests. ...")
+
+Agent(team_name: "build-{slug}", name: "api-layer", ...,
+  prompt: "Service + controller + integration tests. ...")
+```
+Set `TaskUpdate(addBlockedBy)` so api-layer tasks wait for data-layer.
 
 **Frontend-only** — split by concern:
-- **components-dev** — types + components + API client
-- **pages-dev** — pages + routing + integration (blocked by components-dev)
+```
+Agent(team_name: "build-{slug}", name: "components-dev", ...,
+  prompt: "Types + components + API client. Read design doc FIRST. ...")
 
-**Design doc handoff (MANDATORY for frontend/UI agents):**
-If a design doc exists at `.planning/designs/` or `.planning/design/screens/`, EVERY frontend/UI agent MUST get this in its prompt:
+Agent(team_name: "build-{slug}", name: "pages-dev", ...,
+  prompt: "Pages + routing + integration. Read design doc FIRST. ...")
 ```
-Design doc: .planning/design/screens/{feature}.md — read this FIRST.
-Follow the screen designs, component specs, and visual details exactly.
-Do NOT invent your own layout or design. The design was already reviewed and approved.
+Set `TaskUpdate(addBlockedBy)` so pages-dev tasks wait for components-dev.
+
+**Design doc handoff (MANDATORY for frontend/UI teammates):**
+Every frontend/UI teammate MUST get the design doc path in its prompt:
+```
+Read design doc at .planning/designs/{feature}.md FIRST.
+Follow screen designs, component specs, and visual details exactly.
+Do NOT invent your own layout. The design was already reviewed and approved.
 ```
 
 **Design token enforcement (MANDATORY for frontend/UI work):**
-```bash
-ls .planning/design/system/tokens.md .planning/design-config.md 2>/dev/null
-```
-If design tokens exist, read them and inject into EVERY frontend/UI agent prompt:
+If design tokens exist, inject into EVERY frontend/UI teammate prompt:
 ```
 DESIGN TOKENS — BINDING CONSTRAINTS:
 Read .planning/design/system/tokens.md (or .planning/design-config.md).
-You MUST use these exact values. Do NOT use Tailwind defaults or generic colors.
-- Use token color names, not hex values or bg-blue-500
-- Use the project font, not Inter/Arial/system-ui
-- Use the spacing scale, not arbitrary padding/margin
-- Use the project border radius, not rounded-lg
-Every color, font, and spacing value in your code must come from the token list.
+Use these exact values. Not Tailwind defaults, not generic colors.
+Every color, font, and spacing value must come from the token list.
 ```
 
-5. Monitor progress. When all agents finish, merge worktrees and run full test suite.
+5. Monitor — messages from teammates arrive automatically. Use `TaskList` to check progress. Use `SendMessage` to redirect if needed.
+
+6. When all teammates finish, merge worktrees and run full test suite.
 
-6. `TeamDelete` to clean up.
+7. `TeamDelete()` to clean up.
 
-7. **MANDATORY: Continue to Stage 5 (Review) NOW.** Do NOT stop here. Do NOT ask "Want me to commit?" or "Should I create a PR?" — implementation is done but review hasn't happened yet. Go straight to Gate 3 → Stage 5.
+8. **MANDATORY: Continue to Stage 5 (Review) NOW.** Do NOT stop here. Do NOT ask "Want me to commit?" or "Should I create a PR?" — implementation is done but review hasn't happened yet. Go straight to Gate 3 → Stage 5.
 
 **If Agent Teams is NOT enabled** (env var not set), continue with sequential execution below.
 
@@ -639,26 +683,47 @@ After the reviewer says PASS, check its output for:
 echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not_set}"
 ```
 
-**If Agent Teams is enabled**, spawn parallel review agents for deeper coverage. Each agent gets the same rule files from Step 1, but focuses on its area:
+**If Agent Teams is enabled**, create a review team for parallel coverage:
 
 ```
-Agent 1: "quality-reviewer"
-  Focus: Stages 1-2, 4 (correctness, stack conventions, architecture)
-  Rules: all backend or frontend rules based on mode
-  Extra: check against spec and plan
-
-Agent 2: "test-reviewer"
-  Focus: Stage 3 (test coverage, edge cases, test quality)
-  Rules: testing-strategies skill patterns
-  Extra: check test independence, proper assertions, no test duplication
-
-Agent 3: "security-reviewer" (only if auth/input/data code changed)
-  Focus: Stage 6 (security)
-  Rules: security-checklist skill + OWASP top 10
-  Extra: check for injection, auth bypass, data exposure
+TeamCreate(team_name: "review-{feature-slug}", description: "Code review for {feature}")
+
+TaskCreate(subject: "Quality review", description: "Stages 1-2, 4: correctness, conventions, architecture")
+TaskCreate(subject: "Test review", description: "Stage 3: coverage, edge cases, test quality")
+TaskCreate(subject: "Security review", description: "Stage 6: auth, injection, data exposure")
+
+Agent(
+  team_name: "review-{feature-slug}",
+  name: "quality-reviewer",
+  subagent_type: "phase-reviewer",
+  prompt: "Review for correctness, stack conventions, architecture.
+    Changed files: {list}. Rules: {rule paths from config}.
+    Check against spec at {spec path} and plan at {plan path}.
+    Output: PASS or NEEDS CHANGES with file:line, rule broken, severity, fix."
+)
+
+Agent(
+  team_name: "review-{feature-slug}",
+  name: "test-reviewer",
+  subagent_type: "general-purpose",
+  prompt: "Review test coverage, edge cases, test quality.
+    Changed files: {list}. Check test independence, assertions, no duplication.
+    Output: PASS or NEEDS CHANGES with specifics."
+)
+
+Agent(
+  team_name: "review-{feature-slug}",
+  name: "security-reviewer",
+  subagent_type: "general-purpose",
+  prompt: "Review security: auth, input validation, data exposure, injection.
+    Changed files: {list}. Rules: security-checklist + OWASP top 10.
+    Output: PASS or NEEDS CHANGES with specifics."
+)
 ```
 
-All agents review at the same time. Combine their findings. All must PASS before moving to Ship. If any says NEEDS CHANGES → fix loop (Step 3) applies to the combined findings.
+All teammates review at the same time. Combine their findings. All must PASS before moving to Ship. If any says NEEDS CHANGES → fix loop (Step 3) applies to the combined findings.
+
+After review completes: `TeamDelete()` to clean up.
 
 **If Agent Teams is NOT enabled**, use a single review agent (Steps 1-2 above).
 
@@ -712,16 +777,36 @@ Read the epic file. For each feature with status `spec`, `planned`, or `building
 | 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.
+**Use Agent Teams to fill gaps in parallel** (if enabled): When 2+ features need plans or designs generated, use a team to do this at the same time.
 
 ```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/`
+```
+TeamCreate(team_name: "epic-prep-{slug}", description: "Preparing specs/plans for epic")
+
+// One task + teammate per feature that needs a plan
+Agent(
+  team_name: "epic-prep-{slug}",
+  name: "planner-{feature-1}",
+  subagent_type: "general-purpose",
+  isolation: "worktree",
+  prompt: "Generate the design (if needed) and plan for feature: {feature-1}.
+    Read spec at .planning/specs/{feature-1}.md.
+    Save design to .planning/designs/, plan to .planning/plans/."
+)
+
+Agent(
+  team_name: "epic-prep-{slug}",
+  name: "planner-{feature-2}",
+  subagent_type: "general-purpose",
+  isolation: "worktree",
+  prompt: "Generate the design (if needed) and plan for feature: {feature-2}. ..."
+)
+```
+Collect results after all finish, then `TeamDelete()`.
 
 ### Step 2: Sort by dependency and create branch
 
@@ -744,11 +829,36 @@ 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
+   ```
+   TeamCreate(team_name: "epic-build-{slug}", description: "Building epic features in parallel")
+
+   // One task per feature
+   TaskCreate(subject: "Build {feature-A}", description: "...")
+   TaskCreate(subject: "Build {feature-B}", description: "...")
+
+   // One teammate per feature — MUST use team_name + name
+   Agent(
+     team_name: "epic-build-{slug}",
+     name: "builder-{feature-A}",
+     subagent_type: "general-purpose",
+     isolation: "worktree",
+     prompt: "Build feature {A}. Spec: .planning/specs/{A}.md. Plan: .planning/plans/{A}.md.
+       Design doc: .planning/designs/{A}.md — read FIRST if exists.
+       Follow TDD. Mark tasks completed when done."
+   )
+
+   Agent(
+     team_name: "epic-build-{slug}",
+     name: "builder-{feature-B}",
+     subagent_type: "general-purpose",
+     isolation: "worktree",
+     prompt: "Build feature {B}. ..."
+   )
+   ```
+   - **Design doc handoff is MANDATORY** — every frontend/UI teammate must read the design doc first
+   - Wait for all teammates to finish (messages arrive automatically)
    - Merge worktrees, run full test suite
+   - `TeamDelete()` to clean up
    - If tests fail → fix before moving on
 
 2. **If sequential (Agent Teams not enabled or only one feature ready):**

package/commands/spartan/epic.md

@@ -147,7 +147,7 @@ Then tell the user:
 > ```
 > /spartan:spec [feature-1]
 > /spartan:spec [feature-2]
-> /spartan:design [feature-2]   ← if it has UI work
+> /spartan:ux prototype [feature-2]   ← if it has UI work
 > /spartan:spec [feature-3]
 > ```
 >

package/commands/spartan/gate-review.md

@@ -94,12 +94,45 @@ Offer to use a review team for parallel review:
 > - **A) Review team** — quality reviewer + test reviewer + security reviewer, all in parallel
 > - **B) Single reviewer** — one phase-reviewer agent (cheaper, faster for small changes)"
 
-If user picks A → run `/spartan:team review` internally. Three agents review in parallel:
-1. **quality-reviewer** — code design, SOLID, clean code, stack conventions
-2. **test-reviewer** — test coverage, edge cases, test quality
-3. **security-reviewer** — auth, input validation, data handling
+If user picks A → create a review team (NOT sub-agents):
 
-After all report back, synthesize findings and continue to Step 4 (Discussion).
+```
+TeamCreate(team_name: "gate-review-{phase}", description: "Gate 3.5 review")
+
+TaskCreate(subject: "Quality review", description: "Code design, SOLID, clean code, stack conventions")
+TaskCreate(subject: "Test review", description: "Test coverage, edge cases, test quality")
+TaskCreate(subject: "Security review", description: "Auth, input validation, data handling")
+
+Agent(
+  team_name: "gate-review-{phase}",
+  name: "quality-reviewer",
+  subagent_type: "phase-reviewer",
+  prompt: "Review for code design, SOLID, clean code, stack conventions.
+    Changed files: {list}. Spec: {path}. Plan: {path}.
+    Builder self-assessment: {findings from Step 2}.
+    Verdict: ACCEPT or NEEDS CHANGES. Check TaskList, claim your task."
+)
+
+Agent(
+  team_name: "gate-review-{phase}",
+  name: "test-reviewer",
+  subagent_type: "general-purpose",
+  prompt: "Review test coverage, edge cases, test quality.
+    Changed files: {list}. Check independence, assertions, no duplication.
+    Verdict: ACCEPT or NEEDS CHANGES. Check TaskList, claim your task."
+)
+
+Agent(
+  team_name: "gate-review-{phase}",
+  name: "security-reviewer",
+  subagent_type: "general-purpose",
+  prompt: "Review auth, input validation, data handling, injection risks.
+    Changed files: {list}. Check OWASP top 10.
+    Verdict: ACCEPT or NEEDS CHANGES. Check TaskList, claim your task."
+)
+```
+
+After all teammates report back, synthesize findings, `TeamDelete()`, continue to Step 4 (Discussion).
 
 If user picks B (or Agent Teams not enabled) → use single reviewer below.
 

package/commands/spartan/map-codebase.md

@@ -48,18 +48,51 @@ All documents include **file paths in backticks** so Claude can navigate directl
 echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not_set}"
 ```
 
-**If Agent Teams is enabled**, use a coordinated mapping team instead of independent subagents:
-
-1. Use `TeamCreate` with name `map-{project-slug}`
-2. Create 4 tasks — one per domain (tech, architecture, quality, concerns)
-3. Spawn 4 agents in parallel:
-   - **tech-mapper** — STACK.md + INTEGRATIONS.md
-   - **arch-mapper** — ARCHITECTURE.md + STRUCTURE.md
-   - **quality-mapper** — CONVENTIONS.md + TESTING.md
-   - **concerns-mapper** — CONCERNS.md
-4. Agents can message each other if they find cross-cutting issues (e.g., tech mapper finds a security concern → messages concerns-mapper)
-5. After all complete, verify 7 documents exist and are non-empty
-6. Clean up team with `TeamDelete`
+**If Agent Teams is enabled**, use a coordinated mapping team (NOT sub-agents):
+
+```
+TeamCreate(team_name: "map-{project-slug}", description: "Deep codebase analysis")
+
+TaskCreate(subject: "Map tech stack + integrations", description: "Write STACK.md + INTEGRATIONS.md to .planning/codebase/")
+TaskCreate(subject: "Map architecture + structure", description: "Write ARCHITECTURE.md + STRUCTURE.md to .planning/codebase/")
+TaskCreate(subject: "Map conventions + testing", description: "Write CONVENTIONS.md + TESTING.md to .planning/codebase/")
+TaskCreate(subject: "Map concerns", description: "Write CONCERNS.md to .planning/codebase/")
+
+Agent(
+  team_name: "map-{project-slug}",
+  name: "tech-mapper",
+  subagent_type: "Explore",
+  prompt: "Write STACK.md and INTEGRATIONS.md to .planning/codebase/.
+    Include file paths in backticks. Check TaskList, claim your task.
+    If you find security concerns, message concerns-mapper via SendMessage."
+)
+
+Agent(
+  team_name: "map-{project-slug}",
+  name: "arch-mapper",
+  subagent_type: "Explore",
+  prompt: "Write ARCHITECTURE.md and STRUCTURE.md to .planning/codebase/.
+    Trace data flow end-to-end. Check TaskList, claim your task."
+)
+
+Agent(
+  team_name: "map-{project-slug}",
+  name: "quality-mapper",
+  subagent_type: "Explore",
+  prompt: "Write CONVENTIONS.md and TESTING.md to .planning/codebase/.
+    Find patterns, code style, test coverage. Check TaskList, claim your task."
+)
+
+Agent(
+  team_name: "map-{project-slug}",
+  name: "concerns-mapper",
+  subagent_type: "Explore",
+  prompt: "Write CONCERNS.md to .planning/codebase/.
+    Find tech debt, bugs, security risks, fragile areas. Check TaskList, claim your task."
+)
+```
+
+After all teammates complete, verify 7 documents exist and are non-empty, then `TeamDelete()`.
 
 **If Agent Teams is NOT enabled**, delegate to GSD:
 

package/commands/spartan/onboard.md

@@ -112,13 +112,40 @@ echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not_set}"
 **If Agent Teams is enabled AND the codebase is large (50+ files or multi-module):**
 
 Run a parallel mapping team for faster analysis:
-1. Use `TeamCreate` with name `onboard-{project-slug}`
-2. Spawn 2-3 mapper agents in parallel:
-   - **stack-mapper** — tech stack, dependencies, build tools
-   - **arch-mapper** — architecture patterns, data flow, entry points
-   - **quality-mapper** — conventions, test patterns, concerns
-3. After all report back, synthesize into the architecture overview below
-4. Clean up team with `TeamDelete`
+
+```
+TeamCreate(team_name: "onboard-{project-slug}", description: "Mapping codebase for onboarding")
+
+TaskCreate(subject: "Map tech stack", description: "Languages, frameworks, dependencies, build tools, runtime")
+TaskCreate(subject: "Map architecture", description: "Patterns, layers, data flow, entry points, error handling")
+TaskCreate(subject: "Map quality", description: "Conventions, test patterns, code quality concerns")
+
+Agent(
+  team_name: "onboard-{project-slug}",
+  name: "stack-mapper",
+  subagent_type: "Explore",
+  prompt: "Map the tech stack: languages, frameworks, dependencies, build tools, runtime.
+    Write findings as structured markdown. Check TaskList, claim your task."
+)
+
+Agent(
+  team_name: "onboard-{project-slug}",
+  name: "arch-mapper",
+  subagent_type: "Explore",
+  prompt: "Map architecture: patterns, layers, data flow, entry points, error handling.
+    Trace one typical request end-to-end. Check TaskList, claim your task."
+)
+
+Agent(
+  team_name: "onboard-{project-slug}",
+  name: "quality-mapper",
+  subagent_type: "Explore",
+  prompt: "Map conventions, test patterns, code quality concerns. Find TODOs, tech debt.
+    Check TaskList, claim your task."
+)
+```
+
+After all teammates report back, synthesize into the architecture overview below, then `TeamDelete()`.
 
 **If Agent Teams is NOT enabled (or codebase is small)**, map manually:
 

package/commands/spartan/research.md

@@ -81,16 +81,44 @@ Options:
 echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not_set}"
 ```
 
-**If Agent Teams is enabled**, run parallel research agents for faster, broader coverage:
-
-1. Use `TeamCreate` with name `research-{topic-slug}`
-2. Spawn 2-3 agents based on the source strategy from Stage 1:
-   - **breadth-researcher** — runs direct + alternative + adjacent queries, collects 8-15 sources
-   - **depth-researcher** — picks the top 3-5 sources from breadth, goes deep on each
-   - **contrarian-researcher** (optional) — searches for counterarguments, failures, criticism
-3. Each agent tracks sources with credibility scores (see format below)
-4. After all report back, merge source lists and continue to Stage 3 (Analyze)
-5. Clean up team with `TeamDelete`
+**If Agent Teams is enabled**, create a research team (NOT sub-agents):
+
+```
+TeamCreate(team_name: "research-{topic-slug}", description: "Research: {topic}")
+
+TaskCreate(subject: "Breadth search", description: "Run direct + alternative + adjacent queries, collect 8-15 sources with credibility scores")
+TaskCreate(subject: "Depth analysis", description: "Deep dive on top 3-5 sources from breadth search")
+TaskCreate(subject: "Contrarian search", description: "Find counterarguments, failures, criticism")
+
+Agent(
+  team_name: "research-{topic-slug}",
+  name: "breadth-researcher",
+  subagent_type: "general-purpose",
+  prompt: "Search broadly for: {topic}. Run direct + alternative + adjacent queries.
+    Collect 8-15 sources. Track each with: title, URL, credibility (1-5), key data points.
+    Check TaskList, claim your task. Message depth-researcher when you have initial findings."
+)
+
+Agent(
+  team_name: "research-{topic-slug}",
+  name: "depth-researcher",
+  subagent_type: "general-purpose",
+  prompt: "Go deep on the top 3-5 sources for: {topic}.
+    Extract detailed data, cross-reference claims, note contradictions.
+    Check TaskList, claim your task. Wait for breadth-researcher findings if needed."
+)
+
+Agent(
+  team_name: "research-{topic-slug}",
+  name: "contrarian-researcher",
+  subagent_type: "general-purpose",
+  prompt: "Find counterarguments and criticism for: {topic}.
+    Search for failures, risks, overhyped claims, hidden costs.
+    Check TaskList, claim your task."
+)
+```
+
+After all teammates report back, merge source lists, `TeamDelete()`, continue to Stage 3 (Analyze).
 
 **If Agent Teams is NOT enabled**, gather sequentially:
 

package/commands/spartan/spec.md

@@ -115,7 +115,7 @@ Then tell the user:
 > "Spec saved to `.planning/specs/{{ args[0] }}.md` — Gate 1 passed."
 >
 > **Next steps:**
-> - Has UI work? → `/spartan:design {{ args[0] }}`
+> - Has UI work? → `/spartan:ux prototype {{ args[0] }}`
 > - Ready to plan? → `/spartan:plan {{ args[0] }}`
 > - Part of a bigger epic? → `/spartan:epic`
 

package/commands/spartan/startup.md

@@ -134,16 +134,41 @@ Based on results:
 echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not_set}"
 ```
 
-**If Agent Teams is enabled**, run market research and competitor teardowns in parallel:
+**If Agent Teams is enabled**, create a research team (NOT sub-agents):
 
-1. Use `TeamCreate` with name `research-{idea-slug}`
-2. Spawn 2-3 agents:
-   - **market-researcher** — TAM/SAM/SOM, growth signals, adjacent markets
-   - **competitor-analyst** — teardown 3+ competitors, find gaps
-   - **contrarian** (optional) — challenge assumptions, find risks
-3. After all report back, synthesize into a single research doc
-4. Clean up team with `TeamDelete`
+```
+TeamCreate(team_name: "research-{idea-slug}", description: "Market research for {idea}")
+
+TaskCreate(subject: "Market research", description: "TAM/SAM/SOM, growth signals, adjacent markets")
+TaskCreate(subject: "Competitor teardowns", description: "Teardown 3+ competitors, find gaps")
+TaskCreate(subject: "Contrarian analysis", description: "Challenge assumptions, find risks")
+
+Agent(
+  team_name: "research-{idea-slug}",
+  name: "market-researcher",
+  subagent_type: "general-purpose",
+  prompt: "Research the market for: {idea}. TAM/SAM/SOM, growth signals, adjacent markets.
+    Track sources with credibility scores. Check TaskList, claim your task."
+)
+
+Agent(
+  team_name: "research-{idea-slug}",
+  name: "competitor-analyst",
+  subagent_type: "general-purpose",
+  prompt: "Teardown 3+ competitors for: {idea}. Pricing, features, strengths, weaknesses, gaps.
+    Check TaskList, claim your task."
+)
+
+Agent(
+  team_name: "research-{idea-slug}",
+  name: "contrarian",
+  subagent_type: "general-purpose",
+  prompt: "Challenge assumptions about: {idea}. Find risks, failures in similar ideas, hidden costs.
+    Check TaskList, claim your task."
+)
+```
 
+After all teammates report back, `TeamDelete()`, synthesize into a single research doc.
 Skip to step 11 (synthesis) after team reports back.
 
 **If Agent Teams is NOT enabled**, run sequentially:

package/commands/spartan/team.md

@@ -294,18 +294,36 @@ Create 2-3 focused review tasks:
 2. **Test coverage** — are tests adequate, edge cases covered, test quality
 3. **Security** (if applicable) — auth, input validation, data handling
 
-### Step 4: Spawn reviewers
+### Step 4: Spawn reviewers — MUST use `team_name` + `name` params
 
-Spawn 2-3 agents with appropriate expertise:
-
-- **quality-reviewer** — use `phase-reviewer` agent type if available, otherwise `general-purpose`
-- **test-reviewer** — `general-purpose` agent focused on test analysis
-- **security-reviewer** (optional) — `general-purpose` agent focused on security
-
-Each reviewer gets:
-- The diff or changed file list
-- Their specific review focus
-- Instructions to report findings in the Gate 3.5 format
+```
+Agent(
+  team_name: "review-{branch-or-pr}",
+  name: "quality-reviewer",
+  subagent_type: "phase-reviewer",
+  prompt: "Review code design, SOLID, clean code, stack conventions.
+    Changed files: {list}. Check TaskList, claim your task.
+    Output: ACCEPT or NEEDS CHANGES with file:line, rule, severity, fix."
+)
+
+Agent(
+  team_name: "review-{branch-or-pr}",
+  name: "test-reviewer",
+  subagent_type: "general-purpose",
+  prompt: "Review test coverage, edge cases, test quality.
+    Changed files: {list}. Check TaskList, claim your task.
+    Output: ACCEPT or NEEDS CHANGES."
+)
+
+Agent(
+  team_name: "review-{branch-or-pr}",
+  name: "security-reviewer",
+  subagent_type: "general-purpose",
+  prompt: "Review auth, input validation, data exposure, injection.
+    Changed files: {list}. Check TaskList, claim your task.
+    Output: ACCEPT or NEEDS CHANGES."
+)
+```
 
 ### Step 5: Synthesize
 
@@ -339,13 +357,33 @@ Create 2-3 complementary research tasks:
 2. **Depth analysis** — go deep on the most promising findings from breadth
 3. **Contrarian view** (optional) — find counterarguments, risks, things that could go wrong
 
-### Step 4: Spawn researchers
-
-- **surveyor** — `Explore` or `general-purpose` with web search focus
-- **analyst** — `general-purpose` for deep analysis
-- **contrarian** — `general-purpose` playing devil's advocate (use `idea-killer` agent if available)
+### Step 4: Spawn researchers — MUST use `team_name` + `name` params
 
-Each gets the topic + their angle + instructions to report structured findings.
+```
+Agent(
+  team_name: "research-{topic-slug}",
+  name: "surveyor",
+  subagent_type: "general-purpose",
+  prompt: "Broad survey of: {topic}. Find 8-15 sources, map the landscape.
+    Track sources with credibility scores (1-5). Check TaskList, claim your task."
+)
+
+Agent(
+  team_name: "research-{topic-slug}",
+  name: "analyst",
+  subagent_type: "general-purpose",
+  prompt: "Deep analysis of top sources for: {topic}.
+    Cross-reference claims, extract data. Check TaskList, claim your task."
+)
+
+Agent(
+  team_name: "research-{topic-slug}",
+  name: "contrarian",
+  subagent_type: "general-purpose",
+  prompt: "Challenge assumptions about: {topic}. Find counterarguments, risks, failures.
+    Play devil's advocate. Check TaskList, claim your task."
+)
+```
 
 ### Step 5: Synthesize
 
@@ -397,15 +435,38 @@ TeamCreate:
 
 From the spec/plan, create tasks for each parallel track. Set `addBlockedBy` for tasks that depend on earlier ones (e.g., frontend depends on API being done).
 
-### Step 5: Spawn builders
+### Step 5: Spawn builders — MUST use `team_name` + `name` params
+
+```
+Agent(
+  team_name: "build-{feature-slug}",
+  name: "backend-dev",
+  subagent_type: "general-purpose",
+  isolation: "worktree",
+  prompt: "Backend implementation for {feature}.
+    Read .memory/index.md for context. Rules: ~/.claude/rules/backend-micronaut/.
+    Follow TDD. Check TaskList, claim backend tasks."
+)
+
+Agent(
+  team_name: "build-{feature-slug}",
+  name: "frontend-dev",
+  subagent_type: "general-purpose",
+  isolation: "worktree",
+  prompt: "Frontend implementation for {feature}.
+    Read design doc at .planning/designs/{feature}.md FIRST — follow it exactly.
+    Rules: ~/.claude/rules/frontend-react/. Follow TDD.
+    Check TaskList, claim frontend tasks."
+)
+```
 
-Each builder agent gets:
+Each builder teammate gets:
 - Worktree isolation (`isolation: "worktree"`)
 - Their track's tasks and file paths
 - Instructions to follow TDD
 - References to relevant rules from installed packs
 - `.memory/` context
-- **Design doc path** (if `.planning/designs/*.md` exists) — frontend/UI agents MUST read the design doc before building. Include in prompt: "Read `.planning/designs/{feature}.md` FIRST. Follow screen designs and component specs exactly."
+- **Design doc path** (if `.planning/designs/*.md` exists) — frontend/UI teammates MUST read the design doc before building.
 
 ### Step 6: Integration
 

package/commands/spartan/ux.md

@@ -583,7 +583,7 @@ If no design-config existed, save it to `.planning/design-config.md` too.
 
 Goal: Design all screens with states, responsive layouts, and accessibility. Get them approved by the design critic. Save to `.planning/design/screens/`.
 
-This phase absorbs what `/spartan:design` does. Same dual-agent review, same quality bar.
+This phase handles screen design with dual-agent review. Same quality bar as the original design workflow.
 
 ```bash
 mkdir -p .planning/design/screens

package/commands/spartan.md

@@ -108,7 +108,8 @@ Route here when the user wants a specific tool, not a full workflow.
 |---|---|
 | "plan a task", "write a spec" | `/spartan:spec` → `/spartan:plan` |
 | "break into features", "epic" | `/spartan:epic` |
-| "design a screen", "UI design", "design doc" | `/spartan:design` |
+| "design a screen", "UI design", "design doc" | `/spartan:ux prototype` |
+| "UX research", "user interviews", "design system" | `/spartan:ux` |
 | "review my code", "dual review", "gate review" | `/spartan:gate-review` |
 | "big project", "multi-day", "new milestone" | `/spartan:project new` |
 | "continue phase", "next phase" | `/spartan:phase` |

package/package.json

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

package/rules/backend-micronaut/API_DESIGN.md

@@ -17,6 +17,31 @@ All mutations use `@Post`. Never use `@Put`, `@Delete`, or `@Patch`.
 | Delete | `@Post("/delete")` | `@Post("/delete")` |
 | Custom action | `@Post("/close")` | `@Post("/close")` |
 
+### Bad — REST Verbs (NEVER use these)
+
+```kotlin
+// ❌ BAD — REST verbs
+@Patch("/{id}")
+suspend fun update(@PathVariable id: UUID, @Body request: UpdateRequest): Response
+
+@Delete("/{id}")
+suspend fun delete(@PathVariable id: UUID): Boolean
+
+@Put("/{id}")
+suspend fun replace(@PathVariable id: UUID, @Body request: ReplaceRequest): Response
+```
+
+### Good — RPC-Style
+
+```kotlin
+// ✅ GOOD — RPC-style
+@Post("/update")
+suspend fun update(@QueryValue id: UUID, @Body request: UpdateRequest): Response
+
+@Post("/delete")
+suspend fun delete(@QueryValue id: UUID): Boolean
+```
+
 ---
 
 ## URL Design

package/rules/backend-micronaut/CONTROLLERS.md

@@ -384,3 +384,5 @@ Before committing controller changes:
 - [ ] Business logic is in managers, not controllers
 - [ ] **NO inline data classes** - all models in `module-client`
 - [ ] **NO private converter functions** - use inline mapping or manager returns Response DTOs
+- [ ] **NO @Put, @Patch, @Delete** — only @Get and @Post (RPC-style, see API_DESIGN.md)
+- [ ] **NO @PathVariable** — only @QueryValue for all IDs

package/skills/api-endpoint-creator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api-endpoint-creator
-description: Creates REST endpoint following layered architecture (Controller → Manager → Repository). Use when creating new API endpoints or CRUD operations.
+description: Creates RPC-style endpoint following layered architecture (Controller → Manager → Repository). Use when creating new API endpoints or CRUD operations.
 allowed_tools:
   - Read
   - Write
@@ -11,7 +11,7 @@ allowed_tools:
 
 # API Endpoint Creator Skill
 
-Creates complete REST API endpoints following strict layered architecture patterns.
+Creates complete RPC-style API endpoints following strict layered architecture patterns.
 
 ## When to Use
 
@@ -388,9 +388,9 @@ Location: `app/api-application/src/test/kotlin/com/yourcompany/{Domain}Controlle
 
 ## Rules
 
-### RESTful API with Query Parameters (Not Path Params)
+### RPC-Style API (POST for Mutations, Query Params Only)
 
-This project uses **query parameters for all IDs** and RESTful endpoints:
+This project uses **RPC-style endpoints: @Get for reads, @Post for all mutations, query parameters for all IDs**:
 
 ```
 GET  /api/v1/employees              # List employees (plural)

package/templates/quality-gates.md

@@ -161,7 +161,7 @@ Run when all tasks are done. This is the "ship it?" check.
 
 Run after the designer and `design-critic` agent both review the design doc. Both must accept.
 
-**Trigger:** `/spartan:design [feature-name]`
+**Trigger:** `/spartan:ux prototype [feature-name]`
 
 ### Agent Agreement
 - [ ] Design-critic agent spawned and given the design doc

package/commands/spartan/design.md

@@ -1,23 +0,0 @@
----
-name: spartan:design
-description: "Alias for /spartan:ux prototype — design workflow with Design Gate"
-argument-hint: "[feature name]"
-preamble-tier: 1
----
-
-# Design: {{ args[0] | default: "unnamed feature" }}
-
-> **This command has moved to `/spartan:ux prototype`.** Running it now.
-
-Run `/spartan:ux prototype {{ args[0] }}` internally. Pass all arguments through.
-
-The full UX design workflow is now at `/spartan:ux` with sub-commands:
-- `/spartan:ux research` — user discovery
-- `/spartan:ux define` — problem definition
-- `/spartan:ux ideate` — solution exploration
-- `/spartan:ux system` — design system setup
-- `/spartan:ux prototype` — screen design + Design Gate (this is what `/spartan:design` used to do)
-- `/spartan:ux test` — usability testing plan
-- `/spartan:ux handoff` — developer handoff
-- `/spartan:ux qa` — design QA checklist
-- `/spartan:ux audit` — gap analysis