@c0x12c/spartan-ai-toolkit 1.2.0 → 1.2.1

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/VERSION

@@ -1 +1 @@
-1.2.0
+1.2.1

package/bin/cli.js

@@ -48,11 +48,15 @@ function blue(s) { return `${C.blue}${s}${C.reset}`; }
 
 // ── Pack definitions (loaded from YAML manifests) ───────────────
 import { PACKS, PACK_ORDER } from '../lib/packs.js';
-import { assembleCLAUDEmd } from '../lib/assembler.js';
-import { resolve as resolveDeps, resolveAliases, loadManifests } from '../lib/resolver.js';
+import { assembleCLAUDEmd, assembleAGENTSmd } from '../lib/assembler.js';
+import { resolve as resolveDeps, resolveAliases, loadManifests, loadExternalPacks } from '../lib/resolver.js';
+import { detectStacks } from '../lib/detector.js';
 
 const manifests = loadManifests(join(PKG_ROOT, 'packs'));
 
+// Maps community pack names to their source directory (for file resolution)
+const externalPackSources = {};
+
 // ── Parse args ──────────────────────────────────────────────────
 const args = process.argv.slice(2);
 
@@ -61,12 +65,18 @@ let packsArg = '';
 let installAll = false;
 let mode = 'global';  // default for claude-code
 let showHelp = false;
+let format = '';  // '' = default, 'agents-md' = export AGENTS.md
+let autoDetect = false;
+let packDirArg = '';  // external community pack directory
 
 for (const arg of args) {
   if (arg === '--help' || arg === '-h') showHelp = true;
   else if (arg.startsWith('--agent=')) agent = arg.split('=')[1];
   else if (arg.startsWith('--packs=')) packsArg = arg.split('=')[1];
+  else if (arg.startsWith('--format=')) format = arg.split('=')[1];
+  else if (arg.startsWith('--pack-dir=')) packDirArg = arg.split('=')[1];
   else if (arg === '--all') installAll = true;
+  else if (arg === '--auto') autoDetect = true;
   else if (arg === '--global') mode = 'global';
   else if (arg === '--local') mode = 'local';
 }
@@ -100,6 +110,9 @@ if (showHelp) {
                     Choices: claude-code, cursor, windsurf, codex, copilot
     --packs=LIST    Comma-separated packs (claude-code only)
                     Example: --packs=backend-micronaut,product
+    --auto          Auto-detect tech stack and suggest packs (no menu)
+    --pack-dir=DIR  Load community packs from an external directory
+    --format=NAME   Output format: agents-md (exports AGENTS.md for cross-tool use)
     --all           Install all packs
     --global        Install to home dir (default for claude-code/codex)
     --local         Install to current project dir
@@ -124,6 +137,12 @@ ${lines.join('\n')}`).join('\n')}
 
     ${cyan('npx spartan-ai-toolkit@latest --agent=cursor')}
       Install rules for Cursor (rules + AGENTS.md only)
+
+    ${cyan('npx spartan-ai-toolkit@latest --auto')}
+      Auto-detect your tech stack and install matching packs
+
+    ${cyan('npx spartan-ai-toolkit@latest --format=agents-md --packs=backend-micronaut')}
+      Export AGENTS.md for any AI coding tool
 `);
   process.exit(0);
 }
@@ -220,6 +239,11 @@ function copyDir(src, dest) {
   cpSync(src, dest, { recursive: true });
 }
 
+/** Get the source root for a pack (built-in uses PKG_ROOT, community uses pack-dir). */
+function getPackSource(packName) {
+  return externalPackSources[packName] || PKG_ROOT;
+}
+
 /** Get all items for a category across selected packs, deduplicated. */
 function gatherItems(selectedPacks, category) {
   const seen = new Set();
@@ -237,6 +261,24 @@ function gatherItems(selectedPacks, category) {
   return result;
 }
 
+/** Like gatherItems but includes the source root for each item (for community pack support). */
+function gatherItemsWithSource(selectedPacks, category) {
+  const seen = new Set();
+  const result = [];
+  for (const pack of selectedPacks) {
+    const def = PACKS[pack];
+    if (!def) continue;
+    const srcRoot = getPackSource(pack);
+    for (const item of def[category]) {
+      if (!seen.has(item)) {
+        seen.add(item);
+        result.push({ item, srcRoot });
+      }
+    }
+  }
+  return result;
+}
+
 // ── Pack selection (grouped menu) ───────────────────────────────
 async function selectPacks(targets) {
   // --all flag
@@ -253,6 +295,44 @@ async function selectPacks(targets) {
     return resolveDeps(aliased, manifests);
   }
 
+  // --auto flag: detect tech stack
+  if (autoDetect) {
+    const cwd = process.cwd();
+    console.log(`\n  ${blue('Scanning')} ${dim(cwd)} ${blue('for tech stack...')}\n`);
+    const { detected, comingSoon } = detectStacks(cwd);
+
+    if (detected.length > 0) {
+      console.log(`  ${bold('Detected stacks:')}`);
+      for (const d of detected) {
+        console.log(`    ${green('✓')} ${bold(d.pack)} ${dim(`(${d.reason})`)}`);
+      }
+
+      if (comingSoon.length > 0) {
+        console.log('');
+        for (const d of comingSoon) {
+          console.log(`    ${yellow('~')} ${d.pack} ${dim(`(${d.reason})`)} ${dim('— coming soon, skipped')}`);
+        }
+      }
+      console.log('');
+
+      const packNames = detected.map(d => d.pack);
+      const confirm = await ask(`  Install ${bold(packNames.join(' + '))}? [Y/n]: `);
+      if (confirm !== 'n' && confirm !== 'N') {
+        return resolveDeps(packNames, manifests);
+      }
+      // User said no — fall through to interactive menu
+      console.log('');
+    } else {
+      console.log(`  ${dim('No stacks detected.')}`);
+      if (comingSoon.length > 0) {
+        for (const d of comingSoon) {
+          console.log(`    ${yellow('~')} ${d.pack} ${dim(`(${d.reason})`)} ${dim('— coming soon')}`);
+        }
+      }
+      console.log(`  ${dim('Falling back to interactive menu...')}\n`);
+    }
+  }
+
   // Check saved packs
   if (existsSync(targets.packsFile)) {
     let saved = readFileSync(targets.packsFile, 'utf-8').trim().split('\n').filter(Boolean);
@@ -358,9 +438,9 @@ async function installFull() {
     cmdCount++;
   }
 
-  const selectedCommands = gatherItems(selectedPacks, 'commands');
-  for (const cmd of selectedCommands) {
-    const src = join(SRC.commandsSub, `${cmd}.md`);
+  const selectedCommands = gatherItemsWithSource(selectedPacks, 'commands');
+  for (const { item: cmd, srcRoot } of selectedCommands) {
+    const src = join(srcRoot, 'commands', 'spartan', `${cmd}.md`);
     if (existsSync(src)) {
       copyFile(src, join(targets.commands, `${cmd}.md`));
       console.log(`  ${green('+')} /spartan:${cmd}`);
@@ -372,14 +452,13 @@ async function installFull() {
   console.log(`  ${bold(cmdCount + ' commands')} installed\n`);
 
   // 3) Rules (now with subdirectory structure)
-  const selectedRules = gatherItems(selectedPacks, 'rules');
-  if (selectedRules.length > 0) {
+  const rulesWithSource = gatherItemsWithSource(selectedPacks, 'rules');
+  if (rulesWithSource.length > 0) {
     console.log(`${blue('[3/5]')} ${bold('Installing rules...')}`);
     let ruleCount = 0;
 
-    for (const rule of selectedRules) {
-      // Rules now have subdir paths like "database/SCHEMA.md"
-      const src = join(SRC.rules, rule);
+    for (const { item: rule, srcRoot } of rulesWithSource) {
+      const src = join(srcRoot, 'rules', rule);
       const dest = join(targets.rules, rule);
       if (existsSync(src)) {
         copyFile(src, dest);
@@ -393,14 +472,14 @@ async function installFull() {
   }
 
   // 4) Skills
-  const selectedSkills = gatherItems(selectedPacks, 'skills');
-  if (selectedSkills.length > 0) {
+  const skillsWithSource = gatherItemsWithSource(selectedPacks, 'skills');
+  if (skillsWithSource.length > 0) {
     console.log(`${blue('[4/5]')} ${bold('Installing skills...')}`);
     ensureDir(targets.skills);
     let skillCount = 0;
 
-    for (const skill of selectedSkills) {
-      const src = join(SRC.skills, skill);
+    for (const { item: skill, srcRoot } of skillsWithSource) {
+      const src = join(srcRoot, 'skills', skill);
       if (existsSync(src)) {
         copyDir(src, join(targets.skills, skill));
         console.log(`  ${green('+')} ${skill}`);
@@ -413,14 +492,14 @@ async function installFull() {
   }
 
   // 5) Agents
-  const selectedAgents = gatherItems(selectedPacks, 'agents');
-  if (selectedAgents.length > 0) {
+  const agentsWithSource = gatherItemsWithSource(selectedPacks, 'agents');
+  if (agentsWithSource.length > 0) {
     console.log(`${blue('[5/5]')} ${bold('Installing agents...')}`);
     ensureDir(targets.agents);
     let agentCount = 0;
 
-    for (const agentFile of selectedAgents) {
-      const src = join(SRC.agents, agentFile);
+    for (const { item: agentFile, srcRoot } of agentsWithSource) {
+      const src = join(srcRoot, 'agents', agentFile);
       if (existsSync(src)) {
         copyFile(src, join(targets.agents, agentFile));
         console.log(`  ${green('+')} ${agentFile.replace('.md', '')}`);
@@ -495,23 +574,15 @@ async function installRulesOnly() {
     console.log(`\n${blue('[1/2]')} ${bold('Rules')} — ${dim('no rule packs selected')}\n`);
   }
 
-  // Install AGENTS.md
+  // Install AGENTS.md — assembled from pack sections + agents
   console.log(`${blue('[2/2]')} ${bold('Installing AGENTS.md...')}`);
 
-  const allAgents = gatherItems([...PACK_ORDER], 'agents');
-  if (allAgents.length > 0 && targets.agentsMd) {
-    let agentsContent = '# Spartan AI Toolkit — Agents\n\n';
-    agentsContent += 'Expert agents for your AI coding assistant.\n\n---\n\n';
-    for (const agentFile of allAgents) {
-      const src = join(SRC.agents, agentFile);
-      if (existsSync(src)) {
-        agentsContent += readFileSync(src, 'utf-8') + '\n\n---\n\n';
-      }
-    }
-    writeFileSync(targets.agentsMd, agentsContent.trimEnd() + '\n', 'utf-8');
+  if (targets.agentsMd) {
+    const agentsContent = assembleAGENTSmd(SRC.claudeMd, SRC.agents, selectedPacks, PACKS);
+    writeFileSync(targets.agentsMd, agentsContent, 'utf-8');
     console.log(`  ${green('+')} AGENTS.md\n`);
   } else {
-    console.log(`  ${dim('No agents to install')}\n`);
+    console.log(`  ${dim('No AGENTS.md target')}\n`);
   }
 
   // Save selection
@@ -538,6 +609,49 @@ async function main() {
     process.exit(1);
   }
 
+  // Load community packs if --pack-dir is set
+  if (packDirArg) {
+    const packDirPath = pathResolve(process.cwd(), packDirArg);
+    const builtinNames = new Set(manifests.keys());
+    console.log(`\n  ${blue('Loading community packs from')} ${dim(packDirPath)}`);
+    const { loaded, errors } = loadExternalPacks(packDirPath, builtinNames);
+
+    if (errors.length > 0) {
+      for (const err of errors) {
+        console.log(`  ${yellow('!')} ${err}`);
+      }
+    }
+
+    if (loaded.size > 0) {
+      for (const [name, manifest] of loaded) {
+        manifests.set(name, manifest);
+        externalPackSources[name] = packDirPath;
+        // Add to PACKS and PACK_ORDER so menus and install work
+        PACKS[name] = {
+          description: manifest.description,
+          category: manifest.category || 'Community',
+          priority: manifest.priority ?? 500,
+          hidden: manifest.hidden || false,
+          comingSoon: manifest['coming-soon'] || false,
+          depends: manifest.depends || [],
+          commands: manifest.commands || [],
+          rules: manifest.rules || [],
+          skills: manifest.skills || [],
+          agents: manifest.agents || [],
+          claudeSections: manifest['claude-sections'] || [],
+        };
+        PACK_ORDER.push(name);
+      }
+      // Re-sort PACK_ORDER by priority
+      PACK_ORDER.sort((a, b) => (PACKS[a]?.priority ?? 999) - (PACKS[b]?.priority ?? 999));
+
+      const names = [...loaded.keys()].join(', ');
+      console.log(`  ${green('+')} Loaded: ${bold(names)}\n`);
+    } else {
+      console.log(`  ${dim('No valid community packs found')}\n`);
+    }
+  }
+
   let selectedPacks;
 
   try {
@@ -554,6 +668,16 @@ async function main() {
     closeRL();
   }
 
+  // Export AGENTS.md alongside normal install when --format=agents-md
+  if (format === 'agents-md' && (agent === 'claude-code' || agent === 'codex')) {
+    const cwd = process.cwd();
+    const agentsMdPath = join(cwd, 'AGENTS.md');
+    console.log(`${blue('[+]')} ${bold('Exporting AGENTS.md for cross-tool use...')}`);
+    const agentsContent = assembleAGENTSmd(SRC.claudeMd, SRC.agents, selectedPacks, PACKS);
+    writeFileSync(agentsMdPath, agentsContent, 'utf-8');
+    console.log(`  ${green('+')} AGENTS.md (works with Cursor, Copilot, Windsurf, Codex, and 20+ tools)\n`);
+  }
+
   // Success
   const userPacks = selectedPacks.filter(p => !PACKS[p]?.hidden);
   console.log(`${bold(green('================================================'))}`);

package/claude-md/01-core.md

@@ -3,16 +3,19 @@
 
 ## Core Principles (Always Enforce)
 
-### 1. Spec Before Code
+### 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.
+
+### 2. Spec Before Code
 - Task < 1 day → `/spartan:quickplan` for fast spec + plan
 - Task > 1 day → `/spartan:project new` or `/spartan:project milestone-new`
 - Never write production code without a written spec or plan
 
-### 2. TDD is Non-Negotiable
+### 3. TDD is Non-Negotiable
 - Red → Green → Refactor, always
 - Write tests first, then the code that makes them pass
 
-### 3. Atomic Commits
+### 4. Atomic Commits
 Each commit = one task, tests passing:
 ```
 type(scope): what changed
@@ -21,7 +24,7 @@ type(scope): what changed
 ```
 Types: `feat` · `fix` · `test` · `refactor` · `chore` · `docs`
 
-### 4. Context Hygiene (Auto-Managed)
+### 5. Context Hygiene (Auto-Managed)
 Claude proactively manages its own context window:
 - When detecting context pressure (slow responses, forgetting earlier context, long conversation) → auto-run `/compact` to summarize and free space
 - If compaction isn't enough → auto-save critical state to `.handoff/` and `.memory/`, then tell user to start a fresh session
@@ -35,7 +38,7 @@ Claude proactively manages its own context window:
 - Response quality dropping → warn user + compact
 - Multi-step command taking unusually long → consider compacting between steps
 
-### 5. Auto Mode
+### 6. Auto Mode
 When user says **"auto on"** or **"auto mode"**, all Spartan commands skip confirmation prompts and execute straight through. Claude will:
 - Show the spec/plan/output but NOT pause to ask "does this match?" or "shall I proceed?"
 - Continue to the next step automatically after each step completes
@@ -46,7 +49,7 @@ Turn off with **"auto off"**. Default is **auto off** (commands ask for confirma
 
 Auto mode is ideal for experienced users who trust the workflow and want maximum velocity.
 
-### 6. Safety Guardrails
+### 7. Safety Guardrails
 
 | Command | What it does |
 |---|---|

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

@@ -42,3 +42,4 @@ For small tasks (< 1 day), `/spartan:quickplan` covers spec + plan in one shot.
 | `/spartan:fe-review` | PR review with Next.js App Router conventions |
 | `/spartan:figma-to-code [url]` | Convert Figma screen to production code via MCP |
 | `/spartan:e2e [feature]` | Scaffold Playwright E2E testing |
+| `/spartan:qa [url] [feature]` | Real browser QA — opens Chromium, tests flows, finds bugs |

package/commands/spartan/contribute.md

@@ -0,0 +1,140 @@
+---
+name: spartan:contribute
+description: Toggle contributor mode — Claude rates its own skill experience (0-10) after each command and files improvement reports to ~/.spartan/contributor-logs/. Opt-in only.
+argument-hint: "[on | off | reports]"
+preamble-tier: 2
+---
+
+# Contributor Mode: {{ args[0] | default: "on" }}
+
+You are managing **contributor mode** — a self-improvement loop for Spartan.
+
+When active, after every `/spartan:*` command finishes, Claude writes a short field report rating how well the skill worked.
+
+---
+
+{% if args[0] == "on" or args[0] == nil %}
+## Activate Contributor Mode
+
+```bash
+mkdir -p ~/.spartan/contributor-logs
+echo "enabled" > ~/.spartan/contributor-mode
+```
+
+Say: "Contributor mode ON. I'll file a quick report after each command — you won't notice unless something scored low."
+
+### What Happens Now
+
+After every `/spartan:*` command completes, **silently** evaluate and write a report:
+
+```bash
+mkdir -p ~/.spartan/contributor-logs
+```
+
+Write a file to `~/.spartan/contributor-logs/YYYY-MM-DD-HH-MM-command-name.md`:
+
+```markdown
+## Field Report: /spartan:[command]
+Date: [ISO timestamp]
+Score: [0-10]
+Branch: [current branch]
+Directory: [project directory]
+
+### What worked
+- [1-2 bullets on what the skill did well]
+
+### What didn't work
+- [1-2 bullets on friction, confusion, or missing features]
+- [skip this section if score >= 8]
+
+### Suggestion
+[One concrete improvement — a specific change to the command/skill, not vague feedback]
+```
+
+### Scoring Guide
+
+| Score | Meaning |
+|-------|---------|
+| 9-10 | Nailed it. No friction. Would use again without changes. |
+| 7-8 | Good. Minor friction but got the job done. |
+| 5-6 | OK. Needed manual intervention or workarounds. |
+| 3-4 | Poor. Missed the point or gave bad guidance. |
+| 0-2 | Broken. Actively wasted time or caused errors. |
+
+### Rules for Reporting
+
+1. **Be honest.** Don't inflate scores. A 6 is a 6.
+2. **Be specific.** "The migration template assumed Flyway but we use Liquibase" is useful. "Could be better" is not.
+3. **One suggestion per report.** The best improvement, not a wish list.
+4. **Don't slow down the user.** Write the report silently after the command finishes. Never ask the user to rate anything.
+5. **Score relative to the skill's promise.** If `/spartan:qa` says it'll find bugs but only checked if the page loads, that's a 4.
+
+{% elif args[0] == "off" %}
+## Deactivate Contributor Mode
+
+```bash
+rm -f ~/.spartan/contributor-mode
+```
+
+Say: "Contributor mode OFF. No more field reports. Your existing reports are still in `~/.spartan/contributor-logs/`."
+
+{% elif args[0] == "reports" %}
+## View Reports
+
+```bash
+echo "=== Contributor Reports ==="
+echo ""
+
+if [ ! -d ~/.spartan/contributor-logs ] || [ -z "$(ls ~/.spartan/contributor-logs/ 2>/dev/null)" ]; then
+  echo "No reports yet. Enable contributor mode with /spartan:contribute"
+  exit 0
+fi
+
+# Summary stats
+TOTAL=$(ls ~/.spartan/contributor-logs/*.md 2>/dev/null | wc -l | tr -d ' ')
+echo "Total reports: $TOTAL"
+echo ""
+
+# Show last 10 reports with scores
+echo "Recent reports:"
+for f in $(ls -t ~/.spartan/contributor-logs/*.md 2>/dev/null | head -10); do
+  FNAME=$(basename "$f" .md)
+  SCORE=$(grep "^Score:" "$f" 2>/dev/null | head -1 | awk '{print $2}')
+  echo "  [$SCORE/10] $FNAME"
+done
+```
+
+Show the results in a clean table. Then:
+
+- If any score < 5: "Some skills scored low. Want me to read those reports and suggest fixes?"
+- If average > 7: "Skills are working well overall."
+- Always: "Reports are in `~/.spartan/contributor-logs/`. You can share them as GitHub issues to help improve Spartan."
+
+### Aggregate Analysis
+
+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] |
+
+{% else %}
+## Unknown argument: {{ args[0] }}
+
+Available options:
+- `/spartan:contribute` — Turn on contributor mode (default)
+- `/spartan:contribute off` — Turn it off
+- `/spartan:contribute reports` — View and analyze filed reports
+{% endif %}
+
+---
+
+## How to Check if Active
+
+Any skill can check:
+```bash
+[ -f ~/.spartan/contributor-mode ] && echo "CONTRIBUTOR_MODE=on"
+```
+
+If the file exists and contains "enabled", file a report after the skill finishes.

package/commands/spartan/kotlin-service.md

@@ -7,10 +7,10 @@ argument-hint: "[service-name] [brief description]"
 You are scaffolding a new Kotlin Micronaut microservice for the Spartan platform.
 
 **Before scaffolding, read these company rules:**
-- `rules/project/ARCHITECTURE_RULES.md` — Layered architecture
-- `rules/project/CORE_RULES.md` — Kotlin conventions
-- `rules/project/DATABASE_RULES.md` — Schema standards
-- `rules/project/API_RULES.md` — API design patterns
+- `rules/shared-backend/ARCHITECTURE.md` — Layered architecture
+- `rules/backend-micronaut/KOTLIN.md` — Kotlin conventions
+- `rules/database/SCHEMA.md` — Schema standards
+- `rules/backend-micronaut/API_DESIGN.md` — API design patterns
 
 ## Service: {{ args[0] }}
 ## Purpose: {{ args[1] }}

package/commands/spartan/migration.md

@@ -6,7 +6,7 @@ argument-hint: "[description of the migration]"
 
 Create a migration for: {{ args[0] }}
 
-**Before creating, read:** `rules/project/DATABASE_RULES.md`
+**Before creating, read:** `rules/database/SCHEMA.md`
 
 ## Hard Rules (from DATABASE_RULES)
 - **TEXT not VARCHAR** — always