@c0x12c/spartan-ai-toolkit 1.0.1 → 1.1.0

package/.claude-plugin/marketplace.json

@@ -8,9 +8,9 @@
   "plugins": [
     {
       "name": "spartan-ai-toolkit",
-      "description": "44 commands, 11 rules, 18 skills, 4 agents — organized in 11 packs with dependencies",
-      "source": "./",
-      "version": "1.0.1"
+      "description": "5 workflows, 48 commands, 11 rules, 18 skills, 4 agents — organized in 11 packs with dependencies",
+      "source": "./toolkit",
+      "version": "1.1.0"
     }
   ]
 }

package/.claude-plugin/plugin.json

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

package/README.md

@@ -51,6 +51,36 @@ After install, open any project, run `claude`, then type `/spartan`.
 
 ---
 
+## How to Use — Pick Your Style
+
+**Workflows** — guided multi-stage processes. Best for features, bug fixes, research. Uses more tokens but catches what you'd miss.
+
+| Workflow | Command | What it does |
+|----------|---------|-------------|
+| **Build** | `/spartan:build [backend\|frontend] [feature]` | Requirement → plan → TDD → review → PR |
+| **Fix** | `/spartan:fix [symptom]` | Reproduce → investigate → test-first fix → PR |
+| **Research** | `/spartan:research [topic]` | Frame → gather → analyze → report |
+| **Startup** | `/spartan:startup [idea]` | Brainstorm → validate → research → pitch |
+| **Onboard** | `/spartan:onboard` | Scan → map architecture → set up tooling |
+
+**Direct commands** — one command, one job. Best when you know what step you need. Saves tokens.
+
+```
+/spartan:quickplan "task"   ← just the planning step
+/spartan:review             ← just the code review
+/spartan:pr-ready           ← just the PR creation
+/spartan:migration "desc"   ← just the migration
+```
+
+**Rules only** — zero overhead. Rules load automatically and enforce coding standards every session. No commands needed.
+
+```bash
+# Install packs → rules work silently in every session
+npx @c0x12c/spartan-ai-toolkit@latest --packs=backend-micronaut
+```
+
+---
+
 ## Pick Your Packs
 
 Packs group commands, rules, skills, and agents by use case. **Core is always installed.** Pick the rest based on what you're building.
@@ -105,7 +135,7 @@ npx @c0x12c/spartan-ai-toolkit@latest --all
 
 | Pack | Category | Depends on | What you get |
 |------|----------|------------|--------------|
-| **core** | Core | — | Always installed. quickplan, debug, pr-ready, daily, init-project, safety commands |
+| **core** | Core | — | Always installed. Workflows (build, fix, onboard), quickplan, pr-ready, daily, safety commands |
 | **backend-micronaut** | Backend | database, shared-backend | Kotlin service scaffold, code review, testcontainers, API/DB/Kotlin rules, 5 skills, 2 agents |
 | **backend-nodejs** | Backend | database, shared-backend | Coming soon |
 | **backend-python** | Backend | database, shared-backend | Coming soon |
@@ -113,7 +143,7 @@ npx @c0x12c/spartan-ai-toolkit@latest --all
 | **project-mgmt** | Planning | — | Project lifecycle, phases, workstreams, GSD upgrade, forensics, brownfield, codebase mapping |
 | **product** | Planning | — | Think-before-build, validate, teardown, interview, lean canvas, brainstorm |
 | **ops** | Ship | — | Deploy + env-setup |
-| **research** | Research | product | Full startup pipeline — kickoff to investor outreach, 10 skills, 2 agents |
+| **research** | Research | product | Startup + research workflows, kickoff to investor outreach, 10 skills, 2 agents |
 
 Hidden packs (`database`, `shared-backend`) get pulled in as dependencies — you don't pick them directly.
 
@@ -125,12 +155,20 @@ All commands start with `/spartan:` (e.g., `/spartan:quickplan "task"`).
 
 Type `/spartan` to get the smart router — it asks what you need and picks the right command.
 
+### Workflows (core + research packs)
+| Command | What it does |
+|---------|-------------|
+| `build [mode] [feature]` | Build a feature end-to-end (backend, frontend, or auto-detect) |
+| `fix [symptom]` | Find and fix a bug with structured investigation |
+| `research [topic]` | Deep research with source tracking and report |
+| `startup [idea]` | Full startup pipeline: brainstorm to investor-ready |
+| `onboard` | Understand a new codebase and set up tooling |
+
 ### Core (always installed)
 | Command | What it does |
 |---------|-------------|
 | `quickplan "task"` | Task < 1 day — spec + plan + branch in one shot |
 | `daily` | Standup summary from git history |
-| `debug "symptom"` | 4-phase root cause investigation |
 | `pr-ready` | Full checklist before creating any PR |
 | `init-project` | Auto-generate CLAUDE.md from codebase scan |
 | `context-save` | Save session state to resume later |
@@ -187,15 +225,15 @@ Type `/spartan` to get the smart router — it asks what you need and picks the
 ### Research (research pack)
 | Command | What it does |
 |---------|-------------|
-| `kickoff` | Start new idea — brainstorm + validate |
-| `deep-dive` | Market research + competitor teardowns |
-| `full-run` | Full pipeline from brainstorm to outreach |
-| `fundraise` | Pitch materials + investor outreach |
-| `research` | Deep research with source checking |
-| `pitch` | Investor-facing materials |
-| `outreach` | Draft investor emails |
-| `content` | Turn ideas into platform-native content |
-| `write` | Write blog posts and articles |
+| `startup [idea]` | Full pipeline from brainstorm to outreach |
+| `kickoff [theme]` | Start new idea — brainstorm + validate |
+| `deep-dive [project]` | Market research + competitor teardowns |
+| `fundraise [project]` | Pitch materials + investor outreach |
+| `research [topic]` | Deep research with source checking |
+| `pitch [type]` | Investor-facing materials |
+| `outreach [investor]` | Draft investor emails |
+| `content [source]` | Turn ideas into platform-native content |
+| `write [topic]` | Write blog posts and articles |
 
 ---
 
@@ -292,9 +330,3 @@ Rules and skills are tuned for this stack, but the command framework works with
 
 > **Different stack?** Fork the repo, edit the rules and skills, run the installer. Commands work with any language or framework.
 
----
-
-## Credits
-- [Superpowers](https://github.com/obra/superpowers) — Jesse Vincent
-- [GSD](https://github.com/gsd-build/get-shit-done) — TÂCHES
-- Inspired by [OpenSpec](https://github.com/Fission-AI/OpenSpec) fast-forward concept

package/VERSION

@@ -1 +1 @@
-1.0.1
+1.1.0

package/claude-md/11-backend-micronaut.md

@@ -14,6 +14,26 @@ Rules in `rules/backend-micronaut/` enforce coding standards:
 
 > Full patterns: use /kotlin-best-practices or /backend-api-design skill
 
+### Feature Development Workflow (Backend)
+
+When building a backend feature, follow this pipeline:
+
+```
+Epic → Spec → Plan → Build → Review
+              ↑         ↑       ↑        ↑
+            Gate 1    Gate 2  Gate 3   Gate 4
+```
+
+**Build phases:** Database → Business Logic → API Layer → Tests
+
+See `templates/workflow-backend-micronaut.md` for the full workflow with:
+- Stack-specific quality gates (Kotlin rules, Exposed ORM checks, API conventions)
+- Concrete code patterns (Controller, Manager, Repository, Factory, DTO, Test)
+- Real file locations per module
+- Parallel vs sequential task planning
+
+For small tasks (< 1 day), `/spartan:quickplan` covers spec + plan in one shot.
+
 ### Backend Skills
 
 - `/api-endpoint-creator` — Generate full Controller → Manager → Repository stack

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

@@ -8,6 +8,27 @@
 Rules in `rules/frontend-react/`:
 - `FRONTEND.md` — Build check before commit, API case conversion, null safety, optimistic updates
 
+### Feature Development Workflow (Frontend)
+
+When building a frontend feature, follow this pipeline:
+
+```
+Epic → Spec → Design → Plan → Build → Review
+              ↑                  ↑       ↑        ↑
+            Gate 1             Gate 2  Gate 3   Gate 4
+```
+
+**Build phases:** Types & API → Components → Pages/Routes → Tests
+
+Design is NOT optional for frontend — always create a design doc for new screens.
+
+See `templates/workflow-frontend-react.md` for the full workflow with:
+- Stack-specific quality gates (TypeScript, React patterns, accessibility, responsive)
+- File location guide (App Router conventions)
+- Parallel vs sequential task planning
+
+For small tasks (< 1 day), `/spartan:quickplan` covers spec + plan in one shot.
+
 ### Frontend Skills
 
 - `/ui-ux-pro-max` — Design system with 67 styles, 96 palettes, 13 stacks

package/claude-md/60-research.md

@@ -64,7 +64,7 @@ These skills are used by the commands above. You can also use them directly.
 
 Reference materials available in the toolkit:
 - **12 frameworks**: Lean Canvas, Design Sprint, Business Model Canvas, JTBD, Mom Test, Value Proposition Canvas, and more
-- **6 templates**: Idea canvas, competitor analysis, user interview, validation checklist, PRD, project readme
+- **13 templates**: Idea canvas, competitor analysis, user interview, validation checklist, PRD, project readme, epic, feature spec, implementation plan, quality gates, design doc, workflow-backend-micronaut, workflow-frontend-react
 
 ### Rules
 

package/commands/spartan/build.md

@@ -0,0 +1,230 @@
+---
+name: spartan:build
+description: "Build a new feature end-to-end — backend, frontend, or full-stack with auto-detection"
+argument-hint: "[backend|frontend] [feature description]"
+---
+
+# Build: {{ args[0] | default: "a new feature" }}
+
+You are running the **Build workflow** — the main way to go from requirement to merged PR.
+
+This workflow has 4 stages with gates between each. Don't skip ahead.
+
+```
+STAGE 1: UNDERSTAND        STAGE 2: PLAN           STAGE 3: IMPLEMENT        STAGE 4: SHIP
+───────────────────       ──────────────          ──────────────────        ──────────────
+3 forcing questions       Size check:             Task by task, TDD         Self-review
+Scope: in / out           Small → inline plan     Right skills per stack    Fix issues found
+Stack detection           Big → full /phase       Tests after each task     Create PR
+
+Gate 1                    Gate 2                  Gate 3                    Gate 4
+"Scope right?"            "Plan good?"            "Tests pass?"             "PR created"
+```
+
+---
+
+## Step 0: Detect Mode & Stack (silent — no questions)
+
+Parse the user's input to find the mode:
+- First arg is `backend` or `be` → **backend mode**
+- First arg is `frontend` or `fe` → **frontend mode**
+- No mode given → **auto-detect**
+
+**Auto-detect logic** (check the project files):
+```bash
+ls build.gradle.kts settings.gradle.kts 2>/dev/null && echo "STACK:kotlin-micronaut"
+ls package.json 2>/dev/null && cat package.json 2>/dev/null | grep -q '"next"' && echo "STACK:nextjs-react"
+ls .planning/PROJECT.md 2>/dev/null && echo "GSD_ACTIVE"
+```
+
+| Detected | Mode |
+|----------|------|
+| Kotlin only | Backend |
+| Next.js only | Frontend |
+| Both | Ask: "This is a full-stack project. Is this feature backend, frontend, or both?" |
+| Neither | Ask the user what stack they're using |
+
+**Check for installed skills:**
+- If backend mode but no `kotlin-best-practices` skill found → warn: "You don't have the backend pack installed. Run `/spartan:update` and add it, or continue without stack-specific guidance."
+- If frontend mode but no `ui-ux-pro-max` skill found → same warning for frontend pack.
+
+---
+
+## Stage 1: Understand
+
+**Ask 3 forcing questions. Always. Even in auto mode.**
+
+1. **"What pain does this solve?"** — Not the feature. The pain. If the user says "add a profiles endpoint" ask what user problem it fixes.
+2. **"What's the narrowest version we can ship?"** — Force MVP thinking. Cut scope until it hurts.
+3. **"What assumption could be wrong?"** — Surface hidden risks early.
+
+After the user answers, produce a scope block:
+
+```markdown
+## Scope: [feature name]
+
+**Pain:** [one sentence]
+**Stack:** [backend / frontend / full-stack] — [Kotlin+Micronaut / Next.js+React / both]
+
+**IN:**
+- [what will be built]
+- [what will be built]
+
+**OUT:**
+- [what is NOT in scope]
+- [what is NOT in scope]
+
+**Risk:** [the assumption that could be wrong]
+```
+
+**GATE 1 — STOP and ask:**
+> "Here's the scope. Anything to change before I plan?"
+>
+> **Auto mode on?** → Show scope, continue immediately without waiting.
+
+---
+
+## Stage 2: Plan
+
+### Size check
+
+Count the expected work:
+- **Small** (1-4 tasks, < 1 day): Inline plan right here. Like a mini-quickplan.
+- **Big** (5+ tasks, multi-day): Use `/spartan:phase plan` for a full wave-parallel plan.
+
+### Inline plan format (small features)
+
+```markdown
+## Plan: [feature name]
+Branch: `feature/[slug]`
+
+### Task 1: [name]
+Files: [exact paths]
+Test first: [what test to write]
+Implementation: [what to change]
+Verify: [how to confirm]
+
+### Task 2: [name]
+...
+```
+
+**Max 4 tasks for inline plan.** If you need more, it's a big feature — use `/spartan:phase`.
+
+### What the plan includes (by mode)
+
+**Backend mode** — tasks follow this order:
+1. Migration (if new/changed table)
+2. Entity + Table object + Repository + repo tests
+3. Service/Manager + service tests
+4. Controller + integration tests
+
+Uses skills: `database-patterns`, `api-endpoint-creator`, `kotlin-best-practices`, `testing-strategies`, `security-checklist`
+
+**Frontend mode** — tasks follow this order:
+1. Types / interfaces
+2. API client (if new endpoints needed — flag that backend work may be needed first)
+3. Components (bottom-up: small → composed → page-level)
+4. Page + routing + tests
+
+Uses skills: `ui-ux-pro-max`, frontend rules
+
+**Full-stack mode** — backend tasks first, then frontend tasks. Mark the integration point clearly (where frontend starts depending on backend API).
+
+### Create branch
+
+```bash
+git checkout -b feature/[slug]
+```
+
+Write the first failing test for Task 1. Show it fails.
+
+**GATE 2 — STOP and ask:**
+> "Plan has [N] tasks. Does this make sense?"
+>
+> **Auto mode on?** → Show plan, start executing immediately.
+
+---
+
+## Stage 3: Implement
+
+Execute each task in order:
+
+### For each task:
+1. **Write test** → run it → confirm it fails (red)
+2. **Write code** → run test → confirm it passes (green)
+3. **Refactor** if needed (tests still green)
+4. **Commit** with an atomic message:
+   ```
+   feat([scope]): [what this task does]
+   ```
+5. Brief status: "Task [N]/[total] done. Moving to next."
+
+### TDD override
+If a task is hard to test-first (UI components, config changes), say so and switch to implement-then-test. But always have a test when the task is done.
+
+### Skill routing during implementation
+
+Call the right skills based on what you're doing:
+
+| Working on... | Use skill |
+|---------------|-----------|
+| Database migration | `database-patterns` |
+| New endpoint | `api-endpoint-creator` |
+| Kotlin code | `kotlin-best-practices` |
+| Writing tests | `testing-strategies` |
+| React components | `ui-ux-pro-max` |
+| Security-sensitive code | `security-checklist` |
+
+### After all tasks
+
+Run the full test suite:
+```bash
+# Backend
+./gradlew test
+
+# Frontend
+npm test
+
+# Both
+./gradlew test && npm test
+```
+
+**GATE 3 — STOP and ask:**
+> "All [N] tasks done. [X] tests passing. Ready for review?"
+>
+> **Auto mode on?** → Continue to Ship immediately.
+
+---
+
+## Stage 4: Ship
+
+### 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
+
+Fix any issues found during review. Commit fixes separately:
+```
+fix([scope]): [what review caught]
+```
+
+### Create PR
+Run the approach from `/spartan:pr-ready`:
+- Rebase onto main
+- Run all checks one final time
+- Create PR with clear title, summary, and test plan
+
+**GATE 4 — Done.**
+> "PR created: [link]. Here's what's in it: [summary]."
+
+---
+
+## Rules
+
+- **Always start at Stage 1.** Don't skip the 3 questions. They prevent building the wrong thing.
+- **Gates are mandatory.** Even small features go through all 4 stages. The stages are fast for small work — that's fine.
+- **TDD by default.** Write the test first. Override only when test-first doesn't make sense for that specific task.
+- **One commit per task.** Don't batch. Each task = one commit with a clear message.
+- **Security check always runs.** Whether backend or frontend, security patterns get checked at the end of Stage 3.
+- **Frontend checks for backend needs.** If a new page needs data that doesn't exist yet, say so at Stage 2 and add backend tasks first.
+- **Don't over-plan.** If the whole thing is 1-2 files and 30 minutes of work, don't force it into this workflow. Just do it. This workflow is for features that need structure — at least 2-3 tasks.

package/commands/spartan/debug.md

@@ -1,156 +1,14 @@
 ---
 name: spartan:debug
-description: Structured root-cause debugging using a 4-phase investigation protocol. Produces a Debug Report with fix plan. Use for bugs that aren't immediately obvious.
+description: "Alias for /spartan:fix — use that instead"
 argument-hint: "[describe the symptom / error]"
 ---
 
-# Debug Investigation: {{ args[0] }}
+# Debug → Fix
 
-You are running a **structured debugging session**.
-Do NOT guess. Do NOT try random fixes. Follow the 4 phases in order.
+**This command has moved to `/spartan:fix`.**
 
----
-
-## Phase 1: Reproduce & Characterize (understand before touching anything)
-
-**Goal:** Make the failure deterministic and fully described.
-
-1. Get the exact error message, stack trace, or symptom
-2. Find the minimal reproduction case:
-   - What inputs trigger it?
-   - What inputs do NOT trigger it?
-   - Is it consistent or flaky?
-   - Environment-specific? (local / CI / prod)
-
-3. Gather context:
-```bash
-# Recent changes that could have introduced this
-git log --oneline -10
-git diff HEAD~5 --stat
-
-# Are tests failing?
-./gradlew test --info 2>&1 | tail -40
-
-# Logs around the failure time
-# (ask user for relevant log snippets if not in repo)
-```
-
-Document findings. Do NOT proceed until the bug is reproducible.
-
----
-
-## Phase 2: Isolate the Root Cause (narrow the search space)
-
-**Goal:** Find the exact line / decision / data that causes the failure.
-
-Use binary isolation:
-1. Start from the failure point, trace backwards through the call stack
-2. At each layer, ask: "Is the data correct at this point?"
-3. Keep narrowing until you find where correct data becomes incorrect data
-
-For common Kotlin/Micronaut patterns, check:
-- **Null safety violations**: Any `!!` operators? (BANNED — see CORE_RULES)
-- **Either handling**: Is `.left()` / `.right()` used correctly? Missing error cases?
-- **Coroutine scope leaks**: Is a coroutine cancelled before work completes?
-- **Exposed transaction scope**: Is `newSuspendedTransaction {}` wrapping DB calls correctly?
-- **Soft delete filtering**: Is `deleted_at IS NULL` included in queries? (DATABASE_RULES)
-- **Testcontainers state**: Is a previous test leaving dirty data?
-
-```kotlin
-// Add strategic logging to narrow the search
-log.debug("State at boundary: entity={}, dto={}", entity, dto)
-```
-
-Document: "The root cause is [X] because [evidence]."
-
----
-
-## Phase 3: Fix with Test First (TDD the fix)
-
-**Goal:** Fix correctly and ensure it cannot regress.
-
-1. **Write a failing test that captures the bug FIRST:**
-```kotlin
-@Test
-fun `given [condition that triggers bug], when [action], then [correct behavior]`() {
-    // Reproduce the exact scenario that fails
-    // This test must FAIL right now
-}
-```
-
-2. **Confirm test is red** — if it passes, you haven't reproduced the bug in the test
-
-3. **Write the minimal fix** — change as little as possible
-
-4. **Confirm test is green**
-
-5. **Check for similar patterns** in the codebase:
-```bash
-# Find similar code that might have the same bug
-grep -r "[pattern from the bug]" --include="*.kt" src/
-```
-
----
-
-## Phase 4: Verify & Harden
-
-**Goal:** Confirm fix is complete and add protection layers.
-
-```bash
-# Full test suite must pass
-./gradlew test
-
-# Integration tests specifically
-./gradlew integrationTest 2>/dev/null || ./gradlew test -Dmicronaut.environments=test
-```
-
-Check:
-- [ ] Fix addresses root cause, not symptom
-- [ ] No regression in existing tests
-- [ ] Edge cases covered in new test
-- [ ] Similar patterns in codebase checked and fixed if needed
-- [ ] Logging/observability added if this was hard to debug
-
----
-
-## Output: Debug Report
-
-After completing all phases, produce a brief report:
-
-```markdown
-## Debug Report: [symptom]
-
-**Root Cause:** [exact cause in one sentence]
-
-**Why it happened:**
-[2-3 sentences explaining the chain of events]
-
-**Fix:**
-[what was changed and why it fixes the root cause]
-
-**Test added:**
-[name of the regression test]
-
-**Similar patterns checked:**
-[files checked / changes made]
-
-**Prevention:**
-[what could prevent this class of bug in future — linting rule, convention, etc.]
-```
-
-Commit with:
-```
-fix([scope]): [root cause description]
-
-- Root cause: [one line]
-- Add regression test: [test name]
-- Checked [N] similar patterns
-```
-
-## Rules
+`/spartan:debug` still works, but `/spartan:fix` is the new name.
+It covers the full cycle: reproduce → investigate → fix → ship to PR.
 
-- Follow the 4 phases in order — don't skip to fixing
-- Never guess — every hypothesis must have evidence
-- Write a failing test before writing the fix
-- Change as little as possible — minimal fix, not refactor
-- Check for similar patterns in the codebase after fixing
+Run `/spartan:fix {{ args[0] | default: "" }}` now.