@c0x12c/spartan-ai-toolkit 1.7.0 → 1.7.2

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.7.0"
+      "version": "1.7.2"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "spartan-ai-toolkit",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "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.7.0
+1.7.2

package/commands/spartan/build.md

@@ -31,6 +31,19 @@ EPIC (multi-feature — auto-detected):
 **Full path:** For bigger work, you call `/spartan:spec`, `/spartan:design`, `/spartan:plan` as sub-steps.
 **Epic path:** If the feature name matches an epic with 2+ specs ready, build all features together — one branch, one PR.
 
+### Stages That MUST NOT Be Skipped
+
+| Stage | When it runs | Can skip? |
+|-------|-------------|-----------|
+| Stage 1 (Spec) | Always | NO — every feature needs a scope |
+| Stage 2 (Design) | Frontend/UI work | NO — must ask user (skip only if pure data change) |
+| Stage 3 (Plan) | Always | NO — every feature needs a plan |
+| Stage 4 (Implement) | Always | NO |
+| Stage 5 (Review) | Always | **NEVER** — this is the most commonly skipped stage. You MUST spawn the review agent. |
+| Stage 6 (Ship) | Always | NO |
+
+**If you finish Stage 4 and are about to commit/PR without running Stage 5 — STOP. You are skipping review. Go back and run it.**
+
 ---
 
 ## Step 0: Detect Mode & Stack (silent — no questions)
@@ -195,7 +208,7 @@ If user picks B → continue to Plan.
 
 If user picks C → read the Figma reference and use it as the design source.
 
-**Auto mode on?** → Still ask this question. Design skipping is the user's call, not yours. The only exception: if the ONLY UI change is a single field addition to an existing component (e.g., adding a column to a table), skip silently.
+**Auto mode on?** → Still ask this question. Design skipping is the user's call, not yours. The only exception: if the change is purely data (adding a column to an existing table, no new screens or layouts), skip silently. If there's ANY new component, screen, modal, or layout change — you MUST ask.
 
 ---
 
@@ -329,6 +342,8 @@ Do NOT invent your own layout or design. The design was already reviewed and app
 
 6. `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.
+
 **If Agent Teams is NOT enabled** (env var not set), continue with sequential execution below.
 
 ### Sequential execution (default)
@@ -392,14 +407,22 @@ npm test && npm run build
 ./gradlew test && npm test && npm run build
 ```
 
-**GATE 3 — Implementation complete.**
+**GATE 3 — Implementation complete. Review is NEXT.**
 > "All [N] tasks done. [X] tests passing. Starting review."
 >
 > **Auto mode on?** → Go straight to review.
+>
+> **CRITICAL: You MUST run Stage 5 (Review) after this gate. No exceptions. Do NOT commit, do NOT create a PR, do NOT ask the user what to do next. The next step is ALWAYS the review agent.**
 
 ---
 
-## Stage 5: Review (agent-based — mandatory)
+## Stage 5: Review (agent-based — MANDATORY, NEVER SKIP)
+
+> **CRITICAL: This stage MUST run for every build. No exceptions.**
+> - Not optional. Not skippable. Not deferrable.
+> - Do NOT ask the user "Want me to skip review?" or "Should I review?"
+> - Do NOT commit or create a PR before this stage completes.
+> - If you catch yourself about to skip this stage, STOP and run it.
 
 **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.
 
@@ -408,11 +431,8 @@ npm test && npm run build
 The review uses **configurable rules**. Load them in this order:
 
 ```bash
-# 1. Check for project config (source of truth)
-cat .spartan/config.yaml 2>/dev/null
-
-# 2. If no config, scan for installed rules
-ls rules/ .claude/rules/ ~/.claude/rules/ 2>/dev/null
+# 1. Check for project config
+cat .spartan/config.yaml 2>/dev/null || cat ~/.spartan/config.yaml 2>/dev/null
 ```
 
 **If `.spartan/config.yaml` exists:**
@@ -422,7 +442,30 @@ ls rules/ .claude/rules/ ~/.claude/rules/ 2>/dev/null
 - If `extends` is set, load the base profile first, then apply overrides (`rules-add`, `rules-remove`, `rules-override`)
 - If `conditional-rules` is set, match rules to changed files by glob pattern
 
-**If no config exists (fallback):**
+**If no config exists — auto-generate from installed packs:**
+
+```bash
+# Check what packs are installed
+cat .claude/.spartan-packs 2>/dev/null || cat ~/.claude/.spartan-packs 2>/dev/null
+```
+
+If a packs file exists, generate config from the matching profile:
+- Has `backend-micronaut` → use `kotlin-micronaut` profile
+- Has `frontend-react` → use `react-nextjs` profile
+- Has `backend-nodejs` → use `typescript-node` profile
+- Has `backend-python` → use `python-fastapi` profile
+- None of the above → use `custom` profile
+
+Look for the profile in the toolkit source:
+```bash
+REPO_PATH=$(cat ~/.claude/.spartan-repo 2>/dev/null || echo "")
+ls "$REPO_PATH/toolkit/profiles/" 2>/dev/null
+```
+
+Copy the matching profile to `.spartan/config.yaml`. Tell the user:
+> "No config found. Generated `.spartan/config.yaml` from {profile} profile. Edit it to customize."
+
+**If no packs file either (bare fallback):**
 - Scan `rules/` directory for all `.md` files
 - Group by subdirectory: `rules/backend-micronaut/` → backend, `rules/frontend-react/` → frontend, `rules/database/` → backend, `rules/core/` → shared
 - If no `rules/` dir, check `.claude/rules/` then `~/.claude/rules/`
@@ -733,7 +776,8 @@ If a previous session was interrupted (context overflow, user stopped, etc.), th
 - **Gates are mandatory.** Even small features go through all stages. The stages are fast for small work — that's fine.
 - **TDD by default.** Write the test first. Override only when test-first doesn't make sense for that specific task.
 - **One commit per task.** Don't batch. Each task = one commit with a clear message.
-- **Review is always an agent.** Never self-review. Always spawn a separate review agent for a fresh perspective. Fix issues until the reviewer says PASS.
+- **Review is ALWAYS an agent. NEVER skip.** This is the #1 rule. After implementation finishes — whether via Agent Teams or sequential — you MUST spawn the review agent (Stage 5). Never self-review. Never skip review. Never ask the user if they want to skip. Never commit or create a PR without review. Fix issues until the reviewer says PASS.
+- **Design gate runs for frontend work.** If the feature has UI work (new components, screens, modals, layouts), you MUST trigger the design question in Stage 2. Only skip for pure data changes (adding a field to an existing table/component).
 - **Security check always runs.** Whether backend or frontend, security patterns get checked during review.
 - **Frontend checks for backend needs.** If a new page needs data that doesn't exist yet, say so at Stage 3 and add backend tasks first.
 - **Don't over-plan.** If the whole thing is 1-2 files and 30 minutes of work, don't force it into this workflow. Just do it. This workflow is for features that need structure — at least 2-3 tasks.

package/commands/spartan/pr-ready.md

@@ -27,16 +27,18 @@ If uncommitted changes exist → commit or stash before continuing.
 ## Step 2: Rebase onto Main
 
 ```bash
-# Fetch latest
+# Fetch latest and detect default branch
 git fetch origin
+DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
+[ -z "$DEFAULT_BRANCH" ] && DEFAULT_BRANCH=$(git rev-parse --verify origin/master >/dev/null 2>&1 && echo master || echo main)
 
-# See what's new on main
-git log HEAD..origin/main --oneline
+# See what's new on the default branch
+git log HEAD..origin/$DEFAULT_BRANCH --oneline
 ```
 
-If main has new commits:
+If the default branch has new commits:
 ```bash
-git rebase origin/main
+git rebase origin/$DEFAULT_BRANCH
 ```
 
 **Conflict resolution:**

package/commands/spartan/review.md

@@ -14,12 +14,9 @@ Perform a thorough review of the current changes. Use `git diff` to inspect all
 
 ```bash
 # 1. Check for project config
-cat .spartan/config.yaml 2>/dev/null
+cat .spartan/config.yaml 2>/dev/null || cat ~/.spartan/config.yaml 2>/dev/null
 
-# 2. If no config, scan for installed rules
-ls rules/ .claude/rules/ ~/.claude/rules/ 2>/dev/null
-
-# 3. Classify changed files
+# 2. Classify changed files
 git diff main...HEAD --name-only
 ```
 
@@ -30,7 +27,15 @@ git diff main...HEAD --name-only
 - If `extends` is set, load the base profile, then apply `rules-add`/`rules-remove`/`rules-override`
 - If `conditional-rules` is set, match rules to changed files by glob pattern
 
-**If no config (fallback):**
+**If no config — auto-generate from installed packs:**
+
+```bash
+cat .claude/.spartan-packs 2>/dev/null || cat ~/.claude/.spartan-packs 2>/dev/null
+```
+
+If packs file exists, generate config from the matching profile (same logic as `/spartan:build` Step 1). Copy the profile to `.spartan/config.yaml` and tell the user it was generated.
+
+**If no packs file either (bare fallback):**
 - Scan `rules/` for all `.md` files, group by subdirectory
 - If no `rules/`, check `.claude/rules/` then `~/.claude/rules/`
 - Use all stages below

package/commands/spartan/update.md

@@ -18,16 +18,34 @@ echo "Current version: $LOCAL_VER"
 echo "Repo path: $REPO_PATH"
 ```
 
-If `REPO_PATH` is empty or the directory doesn't exist, ask the user where they cloned `spartan-ai-toolkit`:
-"I don't know where the Spartan repo is. Where did you clone it? (e.g., `~/spartan-ai-toolkit`)"
+If `REPO_PATH` is empty or the directory doesn't exist, try to find it:
+
+```bash
+# Common locations
+for dir in ~/spartan-ai-toolkit ~/Documents/Code/Spartan/spartan-ai-toolkit ~/Code/spartan-ai-toolkit; do
+  [ -d "$dir/toolkit" ] && echo "Found: $dir" && break
+done
+```
+
+If still not found, ask the user: "Where did you clone spartan-ai-toolkit?"
 
 ---
 
-## Step 2: Check for updates
+## Step 2: Detect default branch and check for updates
 
 ```bash
-cd "$REPO_PATH" && git fetch origin main --quiet 2>/dev/null
-REMOTE_VER=$(git show origin/main:toolkit/VERSION 2>/dev/null || echo "unknown")
+cd "$REPO_PATH"
+
+# Detect the default branch (master or main)
+DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
+if [ -z "$DEFAULT_BRANCH" ]; then
+  # Fallback: check which branch exists
+  git rev-parse --verify origin/master >/dev/null 2>&1 && DEFAULT_BRANCH="master" || DEFAULT_BRANCH="main"
+fi
+echo "Default branch: $DEFAULT_BRANCH"
+
+git fetch origin "$DEFAULT_BRANCH" --quiet 2>/dev/null
+REMOTE_VER=$(git show "origin/$DEFAULT_BRANCH:toolkit/VERSION" 2>/dev/null || echo "unknown")
 echo "Local:  $LOCAL_VER"
 echo "Remote: $REMOTE_VER"
 ```
@@ -56,7 +74,7 @@ Show the user their current packs and ask:
 ## Step 4: Pull and reinstall
 
 ```bash
-cd "$REPO_PATH" && git pull origin main
+cd "$REPO_PATH" && git pull origin "$DEFAULT_BRANCH"
 ```
 
 Then run the setup script with saved packs:
@@ -73,6 +91,41 @@ cd "$REPO_PATH/toolkit" && ./scripts/setup.sh --global
 
 ---
 
+## Step 4.5: Generate config if missing
+
+After the install finishes, check if `.spartan/config.yaml` exists:
+
+```bash
+ls .spartan/config.yaml 2>/dev/null || ls ~/.spartan/config.yaml 2>/dev/null
+```
+
+**If no config exists**, generate one from the installed packs:
+
+1. Read the saved packs file:
+```bash
+cat ~/.claude/.spartan-packs 2>/dev/null || cat .claude/.spartan-packs 2>/dev/null
+```
+
+2. Pick the matching profile:
+   - Has `backend-micronaut` → copy `toolkit/profiles/kotlin-micronaut.yaml`
+   - Has `frontend-react` → copy `toolkit/profiles/react-nextjs.yaml`
+   - Has `backend-nodejs` → copy `toolkit/profiles/typescript-node.yaml`
+   - Has `backend-python` → copy `toolkit/profiles/python-fastapi.yaml`
+   - None of the above → copy `toolkit/profiles/custom.yaml`
+
+3. Copy the profile:
+```bash
+mkdir -p .spartan 2>/dev/null || mkdir -p ~/.spartan
+cp "$REPO_PATH/toolkit/profiles/{profile}.yaml" .spartan/config.yaml 2>/dev/null || \
+cp "$REPO_PATH/toolkit/profiles/{profile}.yaml" ~/.spartan/config.yaml
+```
+
+Tell the user: "Generated `.spartan/config.yaml` from {profile} profile. Edit it to customize rules and review stages."
+
+**If config already exists**, skip this step.
+
+---
+
 ## Step 5: Confirm
 
 After setup completes, tell the user:

package/commands/spartan.md

@@ -63,7 +63,9 @@ ls .planning/PROJECT.md 2>/dev/null && echo "GSD_ACTIVE"
 LOCAL_VER=$(cat ~/.claude/.spartan-version 2>/dev/null || echo "")
 REPO_PATH=$(cat ~/.claude/.spartan-repo 2>/dev/null || echo "")
 if [ -n "$REPO_PATH" ] && [ -d "$REPO_PATH/.git" ]; then
-  REMOTE_VER=$(cd "$REPO_PATH" && git fetch origin main --quiet 2>/dev/null && git show origin/main:toolkit/VERSION 2>/dev/null || echo "")
+  DEFAULT_BRANCH=$(cd "$REPO_PATH" && git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
+  [ -z "$DEFAULT_BRANCH" ] && DEFAULT_BRANCH=$(cd "$REPO_PATH" && git rev-parse --verify origin/master >/dev/null 2>&1 && echo master || echo main)
+  REMOTE_VER=$(cd "$REPO_PATH" && git fetch origin "$DEFAULT_BRANCH" --quiet 2>/dev/null && git show "origin/$DEFAULT_BRANCH:toolkit/VERSION" 2>/dev/null || echo "")
   if [ -n "$REMOTE_VER" ] && [ -n "$LOCAL_VER" ] && [ "$REMOTE_VER" != "$LOCAL_VER" ]; then
     echo "SPARTAN_UPDATE_AVAILABLE=$REMOTE_VER"
   fi

package/package.json

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