@c0x12c/spartan-ai-toolkit 1.6.4 → 1.6.5

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.4"
+      "version": "1.6.5"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "spartan-ai-toolkit",
-  "version": "1.6.4",
+  "version": "1.6.5",
   "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.4
+1.6.5

package/agents/phase-reviewer.md

@@ -81,11 +81,33 @@ Pick the right checks based on file types:
 
 ## How You Work
 
-1. **Read every changed file.** Don't skim. Read line by line.
-2. **Check against the lists above.** Be thorough.
-3. **Read project rules** if they exist (`.claude/rules/`). These override defaults.
-4. **Compare to the spec** if provided. Does the code match what was specified?
-5. **Compare to the plan** if provided. Are files in the right locations?
+1. **Load project rules first.** Before looking at any code, read the rule files that match the stack. These are the source of truth — they override your defaults.
+
+   **Find rules in this order** (use the first location that exists):
+   ```bash
+   ls rules/ 2>/dev/null                    # project root
+   ls .claude/rules/ 2>/dev/null             # project .claude dir
+   ls ~/.claude/rules/ 2>/dev/null           # global install
+   ```
+
+   **Backend rules (read if .kt files changed):**
+   - `rules/backend-micronaut/KOTLIN.md`
+   - `rules/backend-micronaut/CONTROLLERS.md`
+   - `rules/backend-micronaut/API_DESIGN.md`
+   - `rules/backend-micronaut/SERVICES_AND_BEANS.md`
+   - `rules/database/SCHEMA.md`
+   - `rules/database/ORM_AND_REPO.md`
+   - `rules/database/TRANSACTIONS.md`
+
+   **Frontend rules (read if .tsx/.ts files changed):**
+   - `rules/frontend-react/FRONTEND.md`
+
+   If a rule file doesn't exist, skip it. Don't guess what it says.
+
+2. **Read the spec and plan** if provided. Check that code matches what was specified and planned. Flag anything missing or different.
+3. **Read every changed file.** Don't skim. Read line by line.
+4. **Check against the rules you loaded**, then the checklists below.
+5. **Compare to the design doc** if one exists. UI must match the approved design.
 
 ## Your Output
 
@@ -98,14 +120,23 @@ Pick the right checks based on file types:
 [Only if NEEDS CHANGES]
 
 1. **[severity: HIGH/MEDIUM]** [file:line] — [what's wrong]
+   - Rule: [which rule file or checklist item this breaks]
    - Why: [why this matters]
    - Fix: [what to do]
 
 2. ...
 
+### Spec Compliance
+- [does the code match the spec? anything missing?]
+- [if no spec provided: "No spec to check against"]
+
 ### What's Clean
 - [what was done well — always include this]
 
+### Documentation Updates Needed
+- [rule file]: [what to add/update] — OR "none"
+- [.memory/patterns/]: [new pattern worth saving] — OR "none"
+
 ### Notes
 - [anything else worth mentioning]
 ```
@@ -113,8 +144,10 @@ Pick the right checks based on file types:
 ## Rules
 
 - **Be specific.** Every issue must have a file and line number.
+- **Cite the rule.** Every issue must reference which rule file or checklist item it breaks. If it's not in a rule, say which checklist section.
 - **Separate must-fix from nice-to-have.** HIGH = must fix before shipping. MEDIUM = fix if time allows.
-- **Don't invent rules.** Only flag things from the checklists above or from project rules files.
+- **Don't invent rules.** Only flag things from the checklists above or from project rules files you actually read.
 - **Praise good code.** Reviews aren't just for finding problems.
 - **One round of discussion.** If the builder disagrees with a finding, hear them out. Change your mind if they're right. Hold firm if they're wrong. No ego.
 - **ACCEPT means ACCEPT.** Don't say "accept with reservations." Either it passes or it doesn't.
+- **Flag documentation gaps.** If you see a new pattern, convention, or recurring issue that should be documented, add it to "Documentation Updates Needed". Don't skip this section.

package/claude-md/01-core.md

@@ -4,7 +4,7 @@
 ## Core Principles (Always Enforce)
 
 ### 1. Match the User's Language
-**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.
+**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:debug`) stay in their original form.
 
 ### 2. Spec Before Code
 - Task < 1 day → `/spartan:spec` + `/spartan:plan` + `/spartan:build`
@@ -80,7 +80,7 @@ Auto mode is ideal for experienced users who trust the workflow and want maximum
 |---|---|
 | `/spartan` | **Smart router** — routes to the right workflow or command |
 | `/spartan:build [backend\|frontend] "feature"` | Full feature workflow: understand → plan → TDD → review → PR |
-| `/spartan:fix "symptom"` | Bug workflow: reproduce → investigate → fix → PR |
+| `/spartan:debug "symptom"` | Bug workflow: reproduce → investigate → fix → review → PR |
 | `/spartan:onboard` | Codebase understanding: scan → map → setup |
 
 ### Spec & Plan (saved artifacts)

package/commands/spartan/build.md

@@ -403,45 +403,130 @@ npm test && npm run build
 
 **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
+### Step 1: Gather review context
 
-Use the `Agent` tool to spawn a reviewer:
+Before spawning the reviewer, collect everything it needs:
+
+```bash
+# 1. Get changed files by type
+git diff main...HEAD --name-only | grep '\.kt$'   # backend files
+git diff main...HEAD --name-only | grep '\.tsx\?$' # frontend files
+git diff main...HEAD --name-only | grep '\.sql$'   # migration files
+
+# 2. Find spec and plan for this feature
+ls .planning/specs/*.md .planning/plans/*.md .planning/designs/*.md 2>/dev/null
+
+# 3. Find installed rules (pick based on mode)
+ls rules/backend-micronaut/ rules/database/ rules/frontend-react/ 2>/dev/null
+# Also check ~/.claude/rules/ if project rules/ not found
+```
+
+### Step 2: Spawn the review agent
+
+Use the `Agent` tool to spawn a reviewer. **The prompt changes based on mode.**
+
+Build the prompt from these blocks — include only what matches the mode:
 
 ```
 Agent:
   name: "reviewer"
-  subagent_type: "phase-reviewer"  (or "general-purpose" if phase-reviewer not available)
+  subagent_type: "phase-reviewer"
   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}
+    ## What changed
+    - Backend files: {list .kt files from git diff, or "none"}
+    - Frontend files: {list .tsx/.ts files from git diff, or "none"}
+    - Migration files: {list .sql files from git diff, or "none"}
     - 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
+    ## Spec and plan
+    - Spec: {path to spec file, or inline scope block from Stage 1}
+    - Plan: {path to plan file, or inline plan from Stage 3}
+    Check that the code matches what was specified and planned. Flag missing pieces.
+
+    ## Rules to check against
+    Read these rule files BEFORE reviewing code. They are the source of truth.
+
+    {IF backend or full-stack mode, include:}
+    **Backend rules (read all of these):**
+    - `rules/backend-micronaut/KOTLIN.md` — null safety, Either error handling, coroutines, no `!!`
+    - `rules/backend-micronaut/CONTROLLERS.md` — thin controllers, @ExecuteOn, @Secured, delegate to Manager
+    - `rules/backend-micronaut/API_DESIGN.md` — query params only, RPC-style URLs, no path params
+    - `rules/backend-micronaut/SERVICES_AND_BEANS.md` — Manager returns Either, service layer patterns
+    - `rules/database/SCHEMA.md` — TEXT not VARCHAR, no FK, soft deletes, UUID PKs, standard columns
+    - `rules/database/ORM_AND_REPO.md` — Exposed ORM, repository pattern
+    - `rules/database/TRANSACTIONS.md` — transaction(db.primary) {} for multi-table ops
+
+    {IF frontend or full-stack mode, include:}
+    **Frontend rules (read all of these):**
+    - `rules/frontend-react/FRONTEND.md` — build check before commit, API case conversion, null safety, optimistic updates
+
+    {IF design doc exists, include:}
+    **Design compliance:**
+    - Read the design doc at {path}. Check that UI matches the approved design.
+    - Flag any component that looks different from the design spec.
+
+    ## Review stages (check all that apply)
+
+    **Stage 1 — Correctness & Requirements**
+    - Does the code match the spec? Any missing requirements?
+    - Are all edge cases handled?
+    - Is error handling using Either (not thrown exceptions)?
+
+    **Stage 2 — Stack Conventions**
+    {backend}: Controllers thin? Manager has business logic? Either<ClientException, T>? No `!!`? @ExecuteOn on blocking calls? @Secured on controllers?
+    {frontend}: Strict TypeScript? No `any`? Hooks rules followed? Server vs client components correct?
+
+    **Stage 3 — Test Coverage**
+    - New endpoints have @MicronautTest integration tests?
+    - Tests are independent (no order dependency)?
+    - Edge cases tested? Happy path + error paths?
+    - Frontend: components tested with Testing Library?
+
+    **Stage 4 — Architecture & Clean Code**
+    - Layered: Controller → Manager → Service/Repository?
+    - No business logic in controllers or repositories?
+    - Functions small and focused? No deep nesting?
+    - No duplication, no dead code?
+
+    **Stage 5 — Database & API**
+    - Migration uses TEXT not VARCHAR? No FK constraints?
+    - Soft delete with deleted_at? Standard columns (id, created_at, updated_at, deleted_at)?
+    - UUID primary keys? Input validation on public endpoints?
+    - API URLs follow RPC style?
+
+    **Stage 6 — Security**
+    - Auth checks on all endpoints?
+    - Input validated and sanitized?
+    - No sensitive data logged or exposed in responses?
+    - No SQL injection, XSS, or command injection risks?
+
+    **Stage 7 — Documentation Gaps**
+    - New pattern used that should be documented? → flag for rules update
+    - New convention established? → flag for .memory/patterns/
+    - Recurring issue that should become a rule? → flag it
+
+    ## Output format
+
+    For each issue:
+    - File and line number
     - What's wrong
+    - Which rule it breaks (with rule file reference)
     - 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).
+    End with:
+    - **PASS** or **NEEDS CHANGES** (list all HIGH/MEDIUM issues)
+    - **Documentation updates needed** (list any rule/pattern updates from Stage 7, or "none")
+    - **What's clean** (always include — praise good code)
 ```
 
-### Step 2: Fix loop
+### Step 3: Fix loop
 
 When the reviewer reports back:
 
-**If PASS** → continue to Ship.
+**If PASS** → save any documentation updates the reviewer flagged, then continue to Ship.
 
 **If NEEDS CHANGES:**
 
@@ -458,23 +543,42 @@ When the reviewer reports back:
 **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?"
 
-### Step 3: Parallel review with Agent Teams
+### Step 4: Capture review learnings
+
+After the reviewer says PASS, check its output for:
+
+- **Documentation updates needed** → save to `.memory/knowledge/` so the next build knows
+- **New pattern flagged** → save to `.memory/patterns/`
+- **Rule violation that keeps showing up** → note it for the user to consider adding to rules
+
+### Step 5: Parallel review with Agent Teams
 
 ```bash
 echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not_set}"
 ```
 
-**If Agent Teams is enabled**, always spawn parallel review agents for deeper coverage:
+**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:
 
 ```
-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
+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
 ```
 
-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.
+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.
 
-**If Agent Teams is NOT enabled**, use a single review agent (Step 1 above).
+**If Agent Teams is NOT enabled**, use a single review agent (Steps 1-2 above).
 
 ---
 

package/commands/spartan/contribute.md

@@ -117,7 +117,7 @@ If the user asks for deeper analysis, group reports by command and show:
 | Command | Reports | Avg Score | Lowest | Top Issue |
 |---------|---------|-----------|--------|-----------|
 | /spartan:build | N | X.X | X | [most common complaint] |
-| /spartan:fix | N | X.X | X | [most common complaint] |
+| /spartan:debug | N | X.X | X | [most common complaint] |
 
 {% else %}
 ## Unknown argument: {{ args[0] }}

package/commands/spartan/debug.md

@@ -1,14 +1,308 @@
 ---
 name: spartan:debug
-description: "Alias for /spartan:fix — use that instead"
-argument-hint: "[describe the symptom / error]"
+description: "Find and fix a bug end-to-end — structured investigation, root cause, test-first fix, and PR"
+argument-hint: "[describe the symptom or error]"
+preamble-tier: 3
 ---
 
-# Debug → Fix
+# Debug: {{ args[0] | default: "a bug" }}
 
-**This command has moved to `/spartan:fix`.**
+You are the **Debug workflow leader** — structured debugging from symptom to merged PR.
 
-`/spartan:debug` still works, but `/spartan:fix` is the new name.
-It covers the full cycle: reproduce → investigate → fix → ship to PR.
+You decide when to investigate deeper, when to check memory for known issues, and when to ship. Don't guess. Don't try random fixes. Follow the pipeline.
 
-Run `/spartan:fix {{ args[0] | default: "" }}` now.
+```
+PIPELINE:
+
+  Check Context → Reproduce → Investigate → Fix → Review Agent → Fix Loop → Ship
+       │              │            │          │         │             │        │
+   .memory/        Gate 1       Gate 2     Gate 3   Spawn agent   Loop    Gate 4
+   known issues                                    fix until OK
+```
+
+---
+
+## Step 0: Check Context (silent — no questions)
+
+Before touching anything, check if this is a known issue.
+
+```bash
+# Check memory for known blockers and gotchas
+ls .memory/blockers/ .memory/knowledge/ 2>/dev/null
+
+# Check for handoff from a previous debug session
+ls .handoff/*.md 2>/dev/null
+```
+
+**If `.memory/blockers/` has files**, scan them for anything matching the symptom. If you find a match:
+> "This might be a known issue. Found in `.memory/blockers/[file]`: [summary]. Let me verify if this is the same problem."
+
+**If `.memory/knowledge/` has files**, scan for related gotchas or patterns that might explain the bug.
+
+**If a handoff exists**, check if someone was already debugging this:
+> "Found a previous debug session for this. Resuming from: [last stage]."
+
+---
+
+## Stage 1: Reproduce
+
+**Goal:** Make the bug deterministic. Understand it fully before touching anything.
+
+### Gather info
+1. Get the exact error message, stack trace, or symptom
+2. Ask if not clear:
+   - What inputs trigger it?
+   - What inputs do NOT trigger it?
+   - Consistent or flaky?
+   - Which environment? (local / CI / prod)
+
+### Check recent changes
+```bash
+# What changed recently?
+git log --oneline -15
+git diff HEAD~5 --stat
+
+# Are tests already failing?
+./gradlew test --info 2>&1 | tail -40
+```
+
+### Find minimal reproduction
+- Trace the code path from the symptom
+- Identify the smallest input that triggers the bug
+- Confirm you can make it happen on demand
+
+**If you can't reproduce it:**
+> Stop. Ask for more context — logs, steps, environment details. Don't move forward until you can see the bug happen.
+
+**GATE 1 — STOP and ask:**
+> "I can reproduce the bug. Here's what happens: [symptoms]. Here's how to trigger it: [steps]. Moving to investigation?"
+>
+> **Auto mode on?** → Show findings, continue immediately.
+
+---
+
+## Stage 2: Investigate
+
+**Goal:** Find the exact line, value, or decision that causes the failure.
+
+### Binary isolation
+Start from the failure point. Trace backwards:
+
+1. At the crash/error point — what's the value?
+2. One layer up — is the data correct here?
+3. Keep going back until you find where correct data becomes wrong data
+
+### Common patterns to check
+
+**Kotlin/Micronaut:**
+- `!!` operators (banned — null safety violation)
+- Either handling — is `.left()` / `.right()` correct? Missing error branch?
+- Coroutine scope — is a job cancelled before it finishes?
+- `newSuspendedTransaction {}` — is it wrapping the right calls?
+- Soft delete — is `deleted_at IS NULL` in the query?
+
+**React/Next.js:**
+- Missing dependency in `useEffect` array
+- State update after unmount
+- Server/client hydration mismatch
+- Missing error boundary
+- Wrong key prop in list rendering
+
+**General:**
+- Race condition — does order of execution matter?
+- Stale cache — is old data being served?
+- Config mismatch — different values between environments?
+
+### Form a hypothesis
+Write it down: "The root cause is [X] because [evidence]."
+
+If your first hypothesis is wrong, try the next one. **Max 3 hypotheses** before stopping and asking for help. Don't go in circles.
+
+**GATE 2 — STOP and ask:**
+> "Root cause: [one sentence]. Evidence: [what proves it]. Here's my fix plan: [approach]. Sound right?"
+>
+> **Auto mode on?** → Show root cause, continue to fix.
+
+---
+
+## Stage 3: Fix
+
+**Goal:** Fix correctly. Make sure it can't come back.
+
+### Step 1: Write failing test
+```
+Write a test that captures the exact bug scenario.
+This test MUST FAIL right now — if it passes, you haven't reproduced the bug in the test.
+```
+
+Run it. Confirm red.
+
+### Step 2: Write the minimal fix
+Change as little as possible. This is a fix, not a refactor. Don't clean up nearby code. Don't "improve" things while you're here.
+
+Run the test. Confirm green.
+
+### Step 3: Check for similar patterns
+The same mistake might exist elsewhere:
+```bash
+# Find code with the same pattern as the bug
+grep -rn "[pattern from the bug]" --include="*.kt" --include="*.tsx" src/
+```
+
+If you find similar issues, fix them too. Each gets its own test.
+
+### Step 4: Run full test suite
+```bash
+# Make sure nothing else broke
+./gradlew test
+# or
+npm test
+```
+
+### Commit
+```
+fix([scope]): [root cause description]
+
+- Root cause: [one line]
+- Add regression test: [test name]
+- Checked [N] similar patterns
+```
+
+**GATE 3 — Implementation complete.**
+> "Fixed. [X] tests passing, including the new regression test. Found [N] similar patterns — [fixed/clean]. Starting review."
+>
+> **Auto mode on?** → Go straight to review.
+
+---
+
+## Stage 4: Review (agent-based — mandatory)
+
+**Don't self-review bug fixes.** Spawn a separate review agent to catch things you missed.
+
+### Spawn the review agent
+
+```bash
+echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not_set}"
+```
+
+Use the `Agent` tool to spawn a reviewer:
+
+```
+Agent:
+  name: "reviewer"
+  subagent_type: "phase-reviewer"  (or "general-purpose" if not available)
+  prompt: |
+    You are reviewing a bug fix for: {symptom description}.
+
+    Root cause: {root cause}
+    Fix: {what was changed}
+
+    Run `git diff main...HEAD` to see all changes.
+
+    Review checklist:
+    **Root cause:** Does the fix address the root cause, not just the symptom?
+    **Regression test:** Does the test cover the exact scenario that failed?
+    **Side effects:** Could this fix break anything else?
+    **Similar patterns:** Were similar patterns in the codebase checked?
+    **No extras:** Is the change minimal? No unrelated cleanup?
+
+    Verdict: **PASS** or **NEEDS CHANGES** (with the list of issues).
+```
+
+**If Agent Teams is enabled**, also spawn a test-reviewer in parallel:
+```
+Agent 2: "test-reviewer" — checks test quality, edge cases, coverage gaps
+```
+
+### Fix loop
+
+**If PASS** → continue to Ship.
+
+**If NEEDS CHANGES:**
+1. Fix the issues
+2. Commit: `fix([scope]): address review feedback`
+3. Run tests
+4. Spawn reviewer AGAIN with updated diff
+5. Repeat until PASS
+
+**Max 3 rounds.** If stuck, ask the user.
+
+---
+
+## Stage 5: Ship
+
+### Create PR
+Clear description matters more for bug fixes than features:
+
+```markdown
+## What was broken
+[User-visible symptom]
+
+## Root cause
+[One paragraph — what went wrong and why]
+
+## Fix
+[What was changed and why it fixes the root cause]
+
+## How to verify
+[Steps to confirm the bug is gone]
+
+## Regression test
+[Name of the test that guards against this]
+```
+
+### Save to memory (if this bug reveals a pattern)
+
+After the PR, check if this bug is worth remembering:
+
+- **Recurring pattern?** (same type of bug seen before) → Save to `.memory/knowledge/`
+- **Known blocker for other work?** → Save to `.memory/blockers/`
+- **One-off typo or simple mistake?** → Don't save. Not worth remembering.
+
+```bash
+mkdir -p .memory/knowledge .memory/blockers
+```
+
+Update `.memory/index.md` if you saved anything.
+
+**GATE 4 — Done.**
+> "PR created: [link]. Bug: [symptom]. Root cause: [one line]. Fix: [one line]."
+
+---
+
+## Debug Report
+
+After the PR is created, produce this summary:
+
+```markdown
+## Debug Report: [symptom]
+
+**Root Cause:** [exact cause in one sentence]
+
+**Why it happened:** [2-3 sentences — the chain of events]
+
+**Fix:** [what changed and why]
+
+**Test added:** [test name]
+
+**Similar patterns checked:** [files checked / changes made]
+
+**Prevention:** [what could stop this class of bug — lint rule, convention, type change, etc.]
+
+**Saved to memory:** [yes/no — what was saved and why]
+```
+
+---
+
+## Rules
+
+- **You are the leader.** Check memory, investigate, fix, review, ship — all in one flow. Don't tell the user to run separate commands.
+- **Follow the pipeline in order.** Don't skip to fixing. Understanding comes first.
+- **Never guess.** Every hypothesis needs evidence. "I think it might be..." is not enough.
+- **Write a failing test before writing the fix.** Always.
+- **Minimal fix.** Change as little as possible. Don't refactor while fixing.
+- **Check for siblings.** The same bug pattern might exist nearby. Always look.
+- **Max 3 hypotheses in Stage 2.** If none pan out, stop and ask for help. Don't spiral.
+- **Review is always an agent.** Never self-review. Spawn a reviewer, fix until PASS.
+- **Save patterns to memory.** If this bug type could happen again, save it so future sessions know.
+- **Small bugs don't need this workflow.** If you can see the typo, just fix it. This is for bugs that aren't obvious.

package/commands/spartan/kickoff.md

@@ -2,51 +2,72 @@
 name: spartan:kickoff
 description: "Start a new idea: create project folder, brainstorm, then validate top picks (Stages 1-2)"
 argument-hint: "[theme or problem space]"
+preamble-tier: 3
 ---
 
 # Kickoff: {{ args[0] | default: "new idea" }}
 
-Runs Stage 1 (Brainstorm) and Stage 2 (Validate) back to back.
-Creates the project and gets you to a GO / PASS decision fast.
-
-## Steps
-
-### Setup
-1. Create project folder: `projects/[idea-name]/` with all stage subfolders
-2. Copy project readme template if available
-
-### Stage 1: Brainstorm
-3. Use the `brainstorm` skill
-4. Set the frame: space, target user, limits, goal
-5. Generate 8-15 ideas
-6. Rate each: demand signal, buildability, moat (0-5)
-7. Pick top 3
-8. Save to `01-brainstorm/brainstorm-session-{date}.md`
-
-### Gate 1 Check
-9. Show top 3 to user
-10. Ask: "Which ones should I validate? Or brainstorm more?"
-11. Wait for answer before continuing
-
-### Stage 2: Validate
-12. Use the `idea-validation` skill
-13. For each picked idea:
-    - Problem check (real pain or nice-to-have?)
-    - Quick market check
-    - Quick competitor check (5 min search)
-    - Distribution check
-    - Build check
-14. Give verdict: GO / TEST MORE / PASS
-15. Save to `03-validation/validation-{idea-name}-{date}.md`
-
-### Gate 2 Check
-16. Show verdicts
-17. If any GO: "Want me to run /spartan:deep-dive on this?"
-18. If all PASS: "These didn't make it. Want to /spartan:brainstorm a different space?"
-19. If TEST MORE: "Here's the cheapest test for each. Try those first."
+Runs Brainstorm + Validate back to back. Gets you to a GO / PASS decision fast.
+
+If the user already has a specific idea (not a theme), skip brainstorm and go straight to validate.
+
+---
+
+## Step 1: Setup
+
+Create project folder with stage subfolders:
+
+```bash
+mkdir -p "projects/{{ args[0] | default: "new-idea" }}"/{01-brainstorm,02-interviews,03-validation,04-research,05-pitch}
+```
+
+---
+
+## Step 2: Brainstorm
+
+Run `/spartan:brainstorm {{ args[0] | default: "" }}` internally — don't tell the user to run it separately.
+
+This will:
+1. Set the frame: space, target user, limits, goal
+2. Generate 8-15 ideas
+3. Rate each: demand signal, buildability, moat (0-5)
+4. Pick top 3
+5. Save to `projects/{{ args[0] }}/01-brainstorm/brainstorm-session.md`
+
+### Gate 1
+
+Show top 3 to user. Ask:
+> "Which ones should I validate? Or brainstorm more?"
+
+Wait for answer before continuing.
+
+---
+
+## Step 3: Validate
+
+Run `/spartan:validate` internally for each picked idea.
+
+This will:
+1. Problem check (real pain or nice-to-have?)
+2. Quick market check
+3. Quick competitor check
+4. Distribution check
+5. Build check
+6. Give verdict: GO / TEST MORE / PASS
+7. Save to `projects/{{ args[0] }}/03-validation/validation-{idea-name}.md`
+
+### Gate 2
+
+Show verdicts:
+- If any **GO**: "Want me to run `/spartan:deep-dive` on this?"
+- If all **PASS**: "These didn't make it. Want to `/spartan:brainstorm` a different space?"
+- If **TEST MORE**: "Here's the cheapest test for each. Try those first."
+
+---
 
 ## Rules
 
 - Don't rush through gates. Pause and ask.
 - It's fine if nothing passes. That saves months of building the wrong thing.
 - If the user already has a specific idea (not a theme), skip brainstorm and go straight to validate.
+- You are the orchestrator — run brainstorm and validate yourself, don't tell the user to chain commands.

package/commands/spartan.md

@@ -90,7 +90,7 @@ These are the 5 leaders. Each one runs a full pipeline. Route here first.
 | User says something like... | Route to | What the leader does |
 |---|---|---|
 | "build feature X", "add Y", "implement Z", "new endpoint", "new page" | `/spartan:build` | Checks context → spec → design? → plan → implement → review → ship |
-| "bug", "broken", "error", "not working", "fix this", "debug" | `/spartan:fix` | Checks known issues → reproduce → investigate → fix → ship |
+| "bug", "broken", "error", "not working", "fix this", "debug" | `/spartan:debug` | Checks known issues → reproduce → investigate → fix → ship |
 | "research X", "dig into", "find out about", "what's the market for" | `/spartan:research` | Frame question → gather sources → analyze → report |
 | "startup idea", "new idea", "validate idea", "full pipeline" | `/spartan:startup` | Auto-resumes → brainstorm → validate → research → pitch |
 | "new project", "just joined", "understand this codebase", "onboard" | `/spartan:onboard` | Checks memory → scan → map → setup → save findings |
@@ -202,7 +202,7 @@ Before running the routed command, give a 1-sentence reason:
 
 Examples:
 - "Building a feature → `/spartan:build` walks you through understand → plan → implement → ship."
-- "Sounds like a bug → `/spartan:fix` does structured investigation before touching code."
+- "Sounds like a bug → `/spartan:debug` does structured investigation before touching code."
 - "New codebase → `/spartan:onboard` scans and maps everything before you start."
 
 Then run the command. Don't ask "shall I proceed?" — just do it.
@@ -215,7 +215,7 @@ Not every command needs the same amount of context. Check the command/skill's `p
 |------|---------------|---------|----------|
 | **1** | Minimal — just run | Toggles, simple actions | `/spartan:careful`, `/spartan:freeze`, `/spartan:sessions` |
 | **2** | Light — project context only | Quick tasks, status checks | `/spartan:daily`, `/spartan:contribute`, `/spartan:context-save` |
-| **3** | Standard — project + stack context | Most commands | `/spartan:build`, `/spartan:fix`, `/spartan:review` |
+| **3** | Standard — project + stack context | Most commands | `/spartan:build`, `/spartan:debug`, `/spartan:review` |
 | **4** | Full — everything, deep context | Complex workflows, multi-phase | `/spartan:project`, `/spartan:phase`, `/spartan:onboard` |
 
 **How tiers affect behavior:**
@@ -246,7 +246,7 @@ You don't have to wait for the user to type `/spartan`. When you notice these pa
 |---|---|
 | User describes a product idea or feature concept | "This sounds like a good fit for `/spartan:think` before we code." |
 | User just finished building/coding something | "Ready to test? `/spartan:qa` can check it in a real browser." |
-| User says something is broken or not working | "Want me to run `/spartan:fix`? It does structured debugging." |
+| User says something is broken or not working | "Want me to run `/spartan:debug`? It does structured debugging." |
 | User is about to merge or says "ready for PR" | "Run `/spartan:pr-ready` to do the full pre-PR checklist." |
 | User asks about competitors or market | "I can dig deeper with `/spartan:research`." |
 | User mentions deploying or going live | "Want to use `/spartan:deploy` for a proper deploy checklist?" |
@@ -322,7 +322,7 @@ Show the 5 workflow leaders first, then mention commands exist for specific task
 **Build** — `/spartan:build [backend|frontend] [feature]`
 The main orchestrator. Checks for existing specs/plans, runs spec → design → plan → implement → review → ship. For small work, does everything inline. For big work, saves artifacts and can resume across sessions.
 
-**Fix** — `/spartan:fix [symptom]`
+**Debug** — `/spartan:debug [symptom]`
 Checks memory for known issues, then runs reproduce → investigate → fix → ship. Saves recurring patterns for future sessions.
 
 **Startup** — `/spartan:startup [idea]`

package/package.json

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

package/packs/core.yaml

@@ -8,12 +8,11 @@ commands:
   - spec
   - plan
   - build
-  - fix
+  - debug
   - onboard
   - daily
   - context-save
   - update
-  - debug
   - pr-ready
   - init-project
   - careful

package/packs/packs.compiled.json

@@ -11,12 +11,11 @@
         "spec",
         "plan",
         "build",
-        "fix",
+        "debug",
         "onboard",
         "daily",
         "context-save",
         "update",
-        "debug",
         "pr-ready",
         "init-project",
         "careful",
@@ -299,7 +298,6 @@
         "startup",
         "kickoff",
         "deep-dive",
-        "full-run",
         "fundraise",
         "research",
         "pitch",

package/packs/research.yaml

@@ -10,7 +10,6 @@ commands:
   - startup
   - kickoff
   - deep-dive
-  - full-run
   - fundraise
   - research
   - pitch

package/skills/startup-pipeline/SKILL.md

@@ -107,7 +107,7 @@ projects/my-idea/
 | `/kickoff [theme]` | 1 → 2 | Brainstorm + validate top ideas |
 | `/deep-dive [project]` | 3 | Research + teardown competitors |
 | `/fundraise [project]` | 4 | Pitch materials + outreach drafts |
-| `/full-run [theme]` | 1 → 2 → 3 → 4 | Everything, with pauses at each gate |
+| `/startup [theme]` | 1 → 2 → 3 → 4 | Everything, with pauses at each gate |
 
 ## Interaction Style
 

package/commands/spartan/fix.md

@@ -1,260 +0,0 @@
----
-name: spartan:fix
-description: "Find and fix a bug end-to-end — structured investigation, root cause, test-first fix, and PR"
-argument-hint: "[describe the symptom or error]"
-preamble-tier: 3
----
-
-# Fix: {{ args[0] | default: "a bug" }}
-
-You are the **Fix workflow leader** — structured debugging from symptom to merged PR.
-
-You decide when to investigate deeper, when to check memory for known issues, and when to ship. Don't guess. Don't try random fixes. Follow the pipeline.
-
-```
-PIPELINE:
-
-  Check Context → Reproduce → Investigate → Fix → Ship
-       │              │            │          │      │
-   .memory/        Gate 1       Gate 2     Gate 3  Gate 4
-   known issues
-```
-
----
-
-## Step 0: Check Context (silent — no questions)
-
-Before touching anything, check if this is a known issue.
-
-```bash
-# Check memory for known blockers and gotchas
-ls .memory/blockers/ .memory/knowledge/ 2>/dev/null
-
-# Check for handoff from a previous debug session
-ls .handoff/*.md 2>/dev/null
-```
-
-**If `.memory/blockers/` has files**, scan them for anything matching the symptom. If you find a match:
-> "This might be a known issue. Found in `.memory/blockers/[file]`: [summary]. Let me verify if this is the same problem."
-
-**If `.memory/knowledge/` has files**, scan for related gotchas or patterns that might explain the bug.
-
-**If a handoff exists**, check if someone was already debugging this:
-> "Found a previous debug session for this. Resuming from: [last stage]."
-
----
-
-## Stage 1: Reproduce
-
-**Goal:** Make the bug deterministic. Understand it fully before touching anything.
-
-### Gather info
-1. Get the exact error message, stack trace, or symptom
-2. Ask if not clear:
-   - What inputs trigger it?
-   - What inputs do NOT trigger it?
-   - Consistent or flaky?
-   - Which environment? (local / CI / prod)
-
-### Check recent changes
-```bash
-# What changed recently?
-git log --oneline -15
-git diff HEAD~5 --stat
-
-# Are tests already failing?
-./gradlew test --info 2>&1 | tail -40
-```
-
-### Find minimal reproduction
-- Trace the code path from the symptom
-- Identify the smallest input that triggers the bug
-- Confirm you can make it happen on demand
-
-**If you can't reproduce it:**
-> Stop. Ask for more context — logs, steps, environment details. Don't move forward until you can see the bug happen.
-
-**GATE 1 — STOP and ask:**
-> "I can reproduce the bug. Here's what happens: [symptoms]. Here's how to trigger it: [steps]. Moving to investigation?"
->
-> **Auto mode on?** → Show findings, continue immediately.
-
----
-
-## Stage 2: Investigate
-
-**Goal:** Find the exact line, value, or decision that causes the failure.
-
-### Binary isolation
-Start from the failure point. Trace backwards:
-
-1. At the crash/error point — what's the value?
-2. One layer up — is the data correct here?
-3. Keep going back until you find where correct data becomes wrong data
-
-### Common patterns to check
-
-**Kotlin/Micronaut:**
-- `!!` operators (banned — null safety violation)
-- Either handling — is `.left()` / `.right()` correct? Missing error branch?
-- Coroutine scope — is a job cancelled before it finishes?
-- `newSuspendedTransaction {}` — is it wrapping the right calls?
-- Soft delete — is `deleted_at IS NULL` in the query?
-
-**React/Next.js:**
-- Missing dependency in `useEffect` array
-- State update after unmount
-- Server/client hydration mismatch
-- Missing error boundary
-- Wrong key prop in list rendering
-
-**General:**
-- Race condition — does order of execution matter?
-- Stale cache — is old data being served?
-- Config mismatch — different values between environments?
-
-### Form a hypothesis
-Write it down: "The root cause is [X] because [evidence]."
-
-If your first hypothesis is wrong, try the next one. **Max 3 hypotheses** before stopping and asking for help. Don't go in circles.
-
-**GATE 2 — STOP and ask:**
-> "Root cause: [one sentence]. Evidence: [what proves it]. Here's my fix plan: [approach]. Sound right?"
->
-> **Auto mode on?** → Show root cause, continue to fix.
-
----
-
-## Stage 3: Fix
-
-**Goal:** Fix correctly. Make sure it can't come back.
-
-### Step 1: Write failing test
-```
-Write a test that captures the exact bug scenario.
-This test MUST FAIL right now — if it passes, you haven't reproduced the bug in the test.
-```
-
-Run it. Confirm red.
-
-### Step 2: Write the minimal fix
-Change as little as possible. This is a fix, not a refactor. Don't clean up nearby code. Don't "improve" things while you're here.
-
-Run the test. Confirm green.
-
-### Step 3: Check for similar patterns
-The same mistake might exist elsewhere:
-```bash
-# Find code with the same pattern as the bug
-grep -rn "[pattern from the bug]" --include="*.kt" --include="*.tsx" src/
-```
-
-If you find similar issues, fix them too. Each gets its own test.
-
-### Step 4: Run full test suite
-```bash
-# Make sure nothing else broke
-./gradlew test
-# or
-npm test
-```
-
-### Commit
-```
-fix([scope]): [root cause description]
-
-- Root cause: [one line]
-- Add regression test: [test name]
-- Checked [N] similar patterns
-```
-
-**GATE 3 — STOP and ask:**
-> "Fixed. [X] tests passing, including the new regression test. Found [N] similar patterns — [fixed/clean]. Ready for review?"
->
-> **Auto mode on?** → Continue to Ship.
-
----
-
-## Stage 4: Ship
-
-### Self-review
-Quick self-review:
-- Fix addresses root cause, not just symptom?
-- No leftover debug code (log statements, commented code)?
-- Test covers the exact scenario that failed?
-- Similar patterns in codebase checked?
-
-### Create PR
-Clear description matters more for bug fixes than features:
-
-```markdown
-## What was broken
-[User-visible symptom]
-
-## Root cause
-[One paragraph — what went wrong and why]
-
-## Fix
-[What was changed and why it fixes the root cause]
-
-## How to verify
-[Steps to confirm the bug is gone]
-
-## Regression test
-[Name of the test that guards against this]
-```
-
-### Save to memory (if this bug reveals a pattern)
-
-After the PR, check if this bug is worth remembering:
-
-- **Recurring pattern?** (same type of bug seen before) → Save to `.memory/knowledge/`
-- **Known blocker for other work?** → Save to `.memory/blockers/`
-- **One-off typo or simple mistake?** → Don't save. Not worth remembering.
-
-```bash
-mkdir -p .memory/knowledge .memory/blockers
-```
-
-Update `.memory/index.md` if you saved anything.
-
-**GATE 4 — Done.**
-> "PR created: [link]. Bug: [symptom]. Root cause: [one line]. Fix: [one line]."
-
----
-
-## Debug Report
-
-After the PR is created, produce this summary:
-
-```markdown
-## Debug Report: [symptom]
-
-**Root Cause:** [exact cause in one sentence]
-
-**Why it happened:** [2-3 sentences — the chain of events]
-
-**Fix:** [what changed and why]
-
-**Test added:** [test name]
-
-**Similar patterns checked:** [files checked / changes made]
-
-**Prevention:** [what could stop this class of bug — lint rule, convention, type change, etc.]
-
-**Saved to memory:** [yes/no — what was saved and why]
-```
-
----
-
-## Rules
-
-- **You are the leader.** Check memory, investigate, fix, ship — all in one flow. Don't tell the user to run separate commands.
-- **Follow the pipeline in order.** Don't skip to fixing. Understanding comes first.
-- **Never guess.** Every hypothesis needs evidence. "I think it might be..." is not enough.
-- **Write a failing test before writing the fix.** Always.
-- **Minimal fix.** Change as little as possible. Don't refactor while fixing.
-- **Check for siblings.** The same bug pattern might exist nearby. Always look.
-- **Max 3 hypotheses in Stage 2.** If none pan out, stop and ask for help. Don't spiral.
-- **Save patterns to memory.** If this bug type could happen again, save it so future sessions know.
-- **Small bugs don't need this workflow.** If you can see the typo, just fix it. This is for bugs that aren't obvious.

package/commands/spartan/full-run.md

@@ -1,13 +0,0 @@
----
-name: spartan:full-run
-description: "Alias for /spartan:startup — use that instead"
-argument-hint: "[theme or problem space]"
----
-
-# Full Run → Startup
-
-**This command has moved to `/spartan:startup`.**
-
-`/spartan:full-run` still works, but `/spartan:startup` is the new name.
-
-Run `/spartan:startup {{ args[0] | default: "" }}` now.