@c0x12c/spartan-ai-toolkit 1.9.2 → 1.10.0

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.9.2"
+      "version": "1.10.0"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "spartan-ai-toolkit",
-  "version": "1.9.2",
+  "version": "1.10.0",
   "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/VERSION

@@ -1 +1 @@
-1.9.2
+1.10.0

package/commands/spartan/build.md

@@ -52,7 +52,25 @@ PARALLEL (multiple terminals — automatic):
 
 ---
 
-## FIRST: Load Build Config (silent — no questions)
+## Preamble (run first)
+
+```bash
+mkdir -p ~/.spartan/sessions
+touch ~/.spartan/sessions/"$PPID"
+_SESSIONS=$(find ~/.spartan/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ')
+find ~/.spartan/sessions -mmin +120 -type f -delete 2>/dev/null || true
+_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
+_PROJECT=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || basename "$(pwd)")
+echo "SESSIONS: $_SESSIONS"
+echo "BRANCH: $_BRANCH"
+echo "PROJECT: $_PROJECT"
+```
+
+**Read the output.** If `SESSIONS` >= 3, start EVERY response with: **[PROJECT / BRANCH]** Currently working on: [task]
+
+---
+
+## Load Build Config (silent — no questions)
 
 Check for a project-level build config that overrides default behavior:
 
@@ -307,46 +325,40 @@ Uses skills: `ui-ux-pro-max`, frontend rules
 
 **CRITICAL: Full-stack means BOTH layers must complete.** Don't move to Gate 3 after finishing backend only. The plan must include frontend tasks and ALL tasks must be done before review. If the spec mentions UI changes, API responses shown to users, or any user-facing behavior — frontend tasks are mandatory.
 
-### Create feature workspace
+### Create feature workspace (MANDATORY — do not skip)
+
+**MANDATORY:** Every build runs in a git worktree. Do NOT use `git checkout -b`. Do NOT work in the main repo directory. Create the worktree first, then do all work inside it. Skipping this breaks parallel builds.
 
-Each build runs in its own **git worktree** — a separate directory with its own branch. This happens automatically. The user doesn't set anything up. Multiple terminals running `/spartan:build` get separate worktrees, branches, and PRs.
+First, generate a slug from the feature description. Convert to lowercase, replace spaces with dashes, strip special characters (e.g., "user auth flow" → `user-auth-flow`).
 
-Use `branch-prefix` from config (default: `feature`). Generate a slug from the feature name.
+Then run this immediately — substitute the actual slug you generated:
 
 ```bash
-SLUG="[slug]"
+SLUG="the-slug-you-generated"
 BRANCH="feature/$SLUG"
 MAIN_REPO="$(git rev-parse --show-toplevel)"
 WORKSPACE="$MAIN_REPO/.worktrees/$SLUG"
-
-# Create worktree (or reuse if resuming)
-if [ -d "$WORKSPACE" ]; then
-  echo "RESUMING: Worktree exists at $WORKSPACE"
-else
-  git worktree add "$WORKSPACE" -b "$BRANCH" 2>/dev/null || git worktree add "$WORKSPACE" "$BRANCH"
-fi
-
-# Symlink shared dirs (gitignored, won't appear in worktree)
-for dir in .planning .memory .handoff .spartan; do
-  [ -d "$MAIN_REPO/$dir" ] && [ ! -e "$WORKSPACE/$dir" ] && ln -s "$MAIN_REPO/$dir" "$WORKSPACE/$dir"
-done
-
-# Copy .env if exists (API keys, secrets)
+if [ -d "$WORKSPACE" ]; then echo "RESUMING: $WORKSPACE"; else git worktree add "$WORKSPACE" -b "$BRANCH" 2>/dev/null || git worktree add "$WORKSPACE" "$BRANCH"; fi
+for dir in .planning .memory .handoff .spartan; do [ -d "$MAIN_REPO/$dir" ] && [ ! -e "$WORKSPACE/$dir" ] && ln -s "$MAIN_REPO/$dir" "$WORKSPACE/$dir"; done
 [ -f "$MAIN_REPO/.env" ] && [ ! -f "$WORKSPACE/.env" ] && cp "$MAIN_REPO/.env" "$WORKSPACE/.env"
-
-# Gitignore worktrees dir
 grep -qxF '.worktrees/' "$MAIN_REPO/.gitignore" 2>/dev/null || echo '.worktrees/' >> "$MAIN_REPO/.gitignore"
-
 echo "WORKSPACE=$WORKSPACE"
 echo "BRANCH=$BRANCH"
 ```
 
-**From this point, ALL work happens in `$WORKSPACE`:**
-- Bash commands: `cd $WORKSPACE && ./gradlew test`
-- File reads/writes: use `$WORKSPACE/src/...` absolute paths
-- Git operations: `git -C $WORKSPACE ...`
+**Read the output.** It prints `WORKSPACE=<path>` and `BRANCH=<name>`. You MUST use these for all remaining work:
+
+- If `WORKSPACE` is missing from output → the worktree creation failed. Stop and tell the user.
+- If `RESUMING` appears → a previous build started this feature. Continue from where it left off.
+
+**From this point, ALL file operations use the WORKSPACE path:**
+- Bash: `cd <WORKSPACE> && ./gradlew test`
+- Read/Write/Edit: use `<WORKSPACE>/src/...` absolute paths
+- Git: `git -C <WORKSPACE> add` / `git -C <WORKSPACE> commit`
+
+**Do NOT read or write files in the main repo.** Only the worktree.
 
-> "Working in: `$WORKSPACE` on branch `$BRANCH`"
+> "Working in: `<WORKSPACE>` on branch `<BRANCH>`"
 
 **Custom plan prompts:** If `.spartan/build.yaml` has `prompts.plan`, apply those instructions now.
 
@@ -746,16 +758,16 @@ Update `.memory/index.md` if you saved anything.
 
 ### Clean up worktree
 
-After PR is created, the worktree stays in case the user needs to push review fixes. Tell the user:
+After PR is created, the worktree stays for review fixes. Tell the user the worktree path so they know.
 
-> "PR created. Worktree at `.worktrees/[slug]` is still active for review fixes."
-
-When the user says the PR is merged:
+When the user says the PR is merged, clean up by substituting the actual slug:
 
 ```bash
 MAIN_REPO="$(git worktree list | head -1 | awk '{print $1}')"
-git -C "$MAIN_REPO" worktree remove ".worktrees/[slug]" --force 2>/dev/null
+SLUG="the-actual-slug-used-earlier"
+git -C "$MAIN_REPO" worktree remove ".worktrees/$SLUG" --force 2>/dev/null
 git -C "$MAIN_REPO" worktree prune 2>/dev/null
+echo "Cleaned up worktree for $SLUG"
 ```
 
 **GATE 4 — Done.**
@@ -814,29 +826,27 @@ Agent(
 ```
 Collect results after all finish, then `TeamDelete()`.
 
-### Step 2: Sort by dependency and create workspace
+### Step 2: Sort by dependency and create workspace (MANDATORY)
 
 Read the epic's Features table. Sort features by dependency order:
 - Features with no dependencies → can build first
 - Features that depend on others → build after their dependencies are done
 
-Create a worktree for the epic (same pattern as single-feature builds):
+**MANDATORY:** Create a worktree for the epic. Same pattern as single-feature builds. Generate a slug from the epic name, then run immediately:
 
 ```bash
-SLUG="[epic-slug]"
+SLUG="the-epic-slug-you-generated"
 BRANCH="feature/$SLUG"
 MAIN_REPO="$(git rev-parse --show-toplevel)"
 WORKSPACE="$MAIN_REPO/.worktrees/$SLUG"
-
-git worktree add "$WORKSPACE" -b "$BRANCH" 2>/dev/null || git worktree add "$WORKSPACE" "$BRANCH"
-
-for dir in .planning .memory .handoff .spartan; do
-  [ -d "$MAIN_REPO/$dir" ] && [ ! -e "$WORKSPACE/$dir" ] && ln -s "$MAIN_REPO/$dir" "$WORKSPACE/$dir"
-done
+if [ -d "$WORKSPACE" ]; then echo "RESUMING: $WORKSPACE"; else git worktree add "$WORKSPACE" -b "$BRANCH" 2>/dev/null || git worktree add "$WORKSPACE" "$BRANCH"; fi
+for dir in .planning .memory .handoff .spartan; do [ -d "$MAIN_REPO/$dir" ] && [ ! -e "$WORKSPACE/$dir" ] && ln -s "$MAIN_REPO/$dir" "$WORKSPACE/$dir"; done
 [ -f "$MAIN_REPO/.env" ] && [ ! -f "$WORKSPACE/.env" ] && cp "$MAIN_REPO/.env" "$WORKSPACE/.env"
+echo "WORKSPACE=$WORKSPACE"
+echo "BRANCH=$BRANCH"
 ```
 
-All epic work happens in `$WORKSPACE`.
+**Read the output.** All epic work happens in the WORKSPACE path printed above. Use `cd <WORKSPACE> && ...` for all commands.
 
 ### Step 3: Implement in dependency order
 

package/commands/spartan.md

@@ -18,45 +18,43 @@ Your job: understand what the user needs, then route to the right **workflow lea
 
 ---
 
-## Step 0.5: Session Tracking (silent, always runs)
-
-Track this session so other Claude windows know what's happening here:
+## Preamble (run first)
 
 ```bash
 mkdir -p ~/.spartan/sessions
-echo "branch=$(git branch --show-current 2>/dev/null || echo 'unknown') dir=$(basename $(pwd)) time=$(date +%s)" > ~/.spartan/sessions/$$
+touch ~/.spartan/sessions/"$PPID"
+_SESSIONS=$(find ~/.spartan/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ')
+find ~/.spartan/sessions -mmin +120 -type f -delete 2>/dev/null || true
+_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
+_PROJECT=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || basename "$(pwd)")
+echo "SESSIONS: $_SESSIONS"
+echo "BRANCH: $_BRANCH"
+echo "PROJECT: $_PROJECT"
+cat .spartan/commands.yaml 2>/dev/null || true
 ```
 
-Count active sessions (modified in last 2 hours):
+**Read the output.** Use `SESSIONS`, `BRANCH`, and `PROJECT` for the rest of this session.
 
-```bash
-ACTIVE_SESSIONS=0
-NOW=$(date +%s)
-CUTOFF=$((NOW - 7200))
-for f in ~/.spartan/sessions/*; do
-  [ -f "$f" ] || continue
-  MOD=$(stat -f %m "$f" 2>/dev/null || stat -c %Y "$f" 2>/dev/null || echo 0)
-  [ "$MOD" -gt "$CUTOFF" ] && ACTIVE_SESSIONS=$((ACTIVE_SESSIONS + 1))
-done
-```
+**If `SESSIONS` >= 3:** Start EVERY response with a grounding line:
 
-**If 3+ active sessions**, start your response with a grounding line:
+> **[PROJECT / BRANCH]** Currently working on: [brief task description]
 
-> **[Session ground]** You're in `[directory]` on branch `[branch]`. Last commit: `[git log --oneline -1]`.
+This prevents "which terminal am I?" confusion during parallel builds. One line, no big deal.
 
-This prevents confusion when the user is running multiple windows. Keep it to one line — don't make it a big deal.
+**If `.spartan/commands.yaml` exists** and has a `prompts.[command-name]` entry matching the command being routed to, pass those custom instructions to the command after the built-in prompt.
 
----
+## Completeness Principle
 
-## Step 0.9: Load Command Config (silent, always runs)
+AI makes completeness near-free. Always recommend the complete option over shortcuts. See `ETHOS.md` for the full philosophy. When presenting options, include `Completeness: X/10` (10 = all edge cases, 7 = happy path, 3 = shortcut).
 
-Check for per-command custom prompts. Commands config lets users inject custom instructions into any Spartan command.
+## AskUserQuestion Format
 
-```bash
-cat .spartan/commands.yaml 2>/dev/null || cat .spartan/commands.yml 2>/dev/null
-```
+**ALWAYS use this structure for every question to the user:**
 
-If the file exists and has a `prompts.[command-name]` entry matching the command being routed to, pass those custom instructions to the command. They're appended after the built-in prompt.
+1. **Re-ground:** State project + branch (from preamble). One sentence.
+2. **Simplify:** Explain so a smart 16-year-old can follow. No function names. Say what it DOES.
+3. **Recommend:** `RECOMMENDATION: Choose [X] because [reason]` — prefer the complete option.
+4. **Options:** `A) ... B) ... C) ...` — one decision per question. Never ask two things at once.
 
 ---
 

package/package.json

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

package/templates/preamble.md

@@ -0,0 +1,89 @@
+# Spartan Preamble — Standard Block for All Commands
+
+This preamble is injected into every Spartan command. Copy the relevant sections
+into your command's `## Preamble (run first)` block.
+
+---
+
+## Preamble (run first)
+
+```bash
+mkdir -p ~/.spartan/sessions
+touch ~/.spartan/sessions/"$PPID"
+_SESSIONS=$(find ~/.spartan/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ')
+find ~/.spartan/sessions -mmin +120 -type f -delete 2>/dev/null || true
+_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
+_PROJECT=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || basename "$(pwd)")
+echo "SESSIONS: $_SESSIONS"
+echo "BRANCH: $_BRANCH"
+echo "PROJECT: $_PROJECT"
+```
+
+**Read the output.** Then apply these rules:
+
+**If `SESSIONS` >= 3:** You are in multi-session mode. Start EVERY response with a grounding line:
+
+> **[`PROJECT` / `BRANCH`]** Currently working on: [brief description of current task]
+
+This prevents confusion when the user has multiple terminals open. Keep it to one line.
+
+**If `SESSIONS` < 3:** No grounding needed. Proceed normally.
+
+---
+
+## Completeness Principle — Boil the Lake
+
+AI makes completeness near-free. Always recommend the complete option over shortcuts. A "lake" (100% coverage, all edge cases) is boilable. An "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans.
+
+When presenting options, include `Completeness: X/10` for each:
+- 10 = all edge cases, full coverage
+- 7 = covers happy path, skips some edges
+- 3 = shortcut that defers work
+
+---
+
+## AskUserQuestion Format
+
+**ALWAYS follow this structure for every question:**
+
+1. **Re-ground:** State the project and current branch (use `_BRANCH` from preamble output). One sentence.
+2. **Simplify:** Explain the problem so a smart 16-year-old could follow. No function names, no jargon. Say what it DOES, not what it's called.
+3. **Recommend:** `RECOMMENDATION: Choose [X] because [one-line reason]` — always prefer the complete option. Include `Completeness: X/10` for each option.
+4. **Options:** Lettered options: `A) ... B) ... C) ...` — one decision per question. Never ask two things at once.
+
+Example:
+
+> **[myapp / feature/auth]** Working on: user authentication
+>
+> We need to handle what happens when the login token expires. Two choices:
+>
+> RECOMMENDATION: Choose A — it handles all edge cases and takes 5 minutes more.
+>
+> A) Full token refresh flow with retry and error UI — Completeness: 10/10
+> B) Just redirect to login page on expiry — Completeness: 5/10
+
+---
+
+## Build Config
+
+Check for project-level config before starting:
+
+```bash
+cat .spartan/build.yaml 2>/dev/null
+cat .spartan/commands.yaml 2>/dev/null
+```
+
+If `.spartan/commands.yaml` has a `prompts.[command-name]` entry matching this command, apply those custom instructions after the built-in ones.
+
+---
+
+## Voice
+
+Direct. Concrete. Sharp. Never corporate, never academic. Sound like a builder, not a consultant.
+
+- Name the file, the function, the line number
+- Show the exact command, not "you should test this"
+- Use real numbers: not "might be slow" but "~200ms per request with 50 items"
+- No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, leverage, facilitate
+- Short paragraphs. End with what to do.
+- The user decides. You recommend. Never act on their behalf without asking.