@c0x12c/ai-toolkit 1.15.0

package/commands/spartan/workstreams.md

@@ -0,0 +1,109 @@
+---
+name: spartan:workstreams
+description: Manage parallel workstreams for concurrent milestone work. List, create, switch between, and track progress across independent work tracks. This is the Spartan wrapper for GSD workstream commands.
+argument-hint: "[list | create <name> | switch <name> | status <name> | progress | complete <name> | resume <name>]"
+---
+
+# Workstreams: {{ args[0] | default: "list" }}
+
+You are managing parallel workstreams using GSD under the hood.
+The user does NOT need to know about `/gsd:*` commands — everything runs through `/spartan:*`.
+
+**What are workstreams?** Independent work tracks that run in parallel within a project. Each workstream has its own milestone, phases, and progress — useful when multiple features or initiatives need to move forward simultaneously.
+
+---
+
+## Route by argument
+
+{% if args[0] == "list" or args[0] == nil %}
+## List Workstreams
+
+Show all active workstreams and their current state.
+
+**Run:** `/gsd:workstreams list`
+
+Display each workstream with:
+- Name and description
+- Current milestone/phase
+- Progress status
+
+Then suggest next actions using `/spartan:` commands:
+- Want to create a new workstream? → "Run `/spartan:workstreams create <name>`"
+- Want to switch to a different workstream? → "Run `/spartan:workstreams switch <name>`"
+- Want overall progress? → "Run `/spartan:workstreams progress`"
+
+**Never suggest `/gsd:*` commands to the user.** Always translate to `/spartan:*`.
+
+{% elif args[0] == "create" %}
+## Create Workstream: {{ args[1] | default: "<name>" }}
+
+Create a new parallel workstream for independent work.
+
+**Run:** `/gsd:workstreams create {{ args[1] | default: "<name>" }}`
+
+After creation, tell the user:
+"Workstream '{{ args[1] | default: "<name>" }}' created. You are now working in this workstream. Next step: `/spartan:project new` or `/spartan:spec` to start work."
+
+{% elif args[0] == "switch" %}
+## Switch Workstream: {{ args[1] | default: "<name>" }}
+
+Switch active context to a different workstream.
+
+**Run:** `/gsd:workstreams switch {{ args[1] | default: "<name>" }}`
+
+After switching, tell the user:
+"Switched to workstream '{{ args[1] | default: "<name>" }}'. Run `/spartan:project status` to see where you left off."
+
+{% elif args[0] == "status" %}
+## Workstream Status: {{ args[1] | default: "<name>" }}
+
+Show detailed status for a specific workstream.
+
+**Run:** `/gsd:workstreams status {{ args[1] | default: "<name>" }}`
+
+Display:
+- Current milestone and phase
+- Completed vs remaining work
+- Any blockers or dependencies
+
+{% elif args[0] == "progress" %}
+## All Workstreams Progress
+
+Show progress overview across all active workstreams.
+
+**Run:** `/gsd:workstreams progress`
+
+Display a summary table showing each workstream's completion percentage and current phase.
+
+{% elif args[0] == "complete" %}
+## Complete Workstream: {{ args[1] | default: "<name>" }}
+
+Mark a workstream as complete and archive it.
+
+**Run:** `/gsd:workstreams complete {{ args[1] | default: "<name>" }}`
+
+After completion, tell the user:
+"Workstream '{{ args[1] | default: "<name>" }}' completed and archived. Run `/spartan:workstreams list` to see remaining workstreams."
+
+{% elif args[0] == "resume" %}
+## Resume Workstream: {{ args[1] | default: "<name>" }}
+
+Resume a paused or previously active workstream.
+
+**Run:** `/gsd:workstreams resume {{ args[1] | default: "<name>" }}`
+
+After resuming, tell the user:
+"Workstream '{{ args[1] | default: "<name>" }}' resumed. Run `/spartan:project status` to pick up where you left off."
+
+{% else %}
+## Unknown argument: {{ args[0] }}
+
+Available options:
+- `/spartan:workstreams` — List all workstreams (default)
+- `/spartan:workstreams create <name>` — Create a new parallel workstream
+- `/spartan:workstreams switch <name>` — Switch to a different workstream
+- `/spartan:workstreams status <name>` — Check status of a workstream
+- `/spartan:workstreams progress` — Overview of all workstream progress
+- `/spartan:workstreams complete <name>` — Archive a completed workstream
+- `/spartan:workstreams resume <name>` — Resume a paused workstream
+{% endif %}

package/commands/spartan/write.md

@@ -0,0 +1,16 @@
+---
+name: spartan:write
+description: Write a blog post or article — sounds human, not AI
+argument-hint: "[topic]"
+---
+
+# Write: {{ args[0] | default: "your topic" }}
+
+Write long-form content.
+
+## Steps
+
+1. Use the `article-writing` skill
+2. Check if there's existing research in the project folders to use as source
+3. Ask: Who's the audience? What's the goal?
+4. No AI slop. Sound like a human.

package/commands/spartan.md

@@ -0,0 +1,386 @@
+---
+name: spartan
+description: Smart entry point for the Spartan AI Toolkit. Detects project context, routes to the right workflow or command. Use this when you're not sure where to start.
+---
+
+# Spartan AI Toolkit — What do you need?
+
+You are the **smart router** — the single entry point for the Spartan AI Toolkit.
+Your job: understand what the user needs, then route to the right **workflow leader** or command.
+
+**Workflow leaders first. Commands second.** Each leader runs a full pipeline — spec, plan, implement, review, ship — so the user doesn't chain commands manually. Route to a leader whenever the user has a job to do.
+
+---
+
+## Language Rule
+
+**Detect the language of the user's message and respond entirely in that same language.** This overrides the default English behavior. Vietnamese input → Vietnamese output. French → French. English → English. Only code syntax, file paths, and command names stay in their original form.
+
+---
+
+## 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"
+cat .spartan/commands.yaml 2>/dev/null || true
+```
+
+**Read the output.** Use `SESSIONS`, `BRANCH`, and `PROJECT` for the rest of this session.
+
+**If `SESSIONS` >= 3:** Start EVERY response with a grounding line:
+
+> **[PROJECT / BRANCH]** Currently working on: [brief task description]
+
+This prevents "which terminal am I?" confusion during parallel builds. One line, no 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
+
+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).
+
+## AskUserQuestion Format
+
+**ALWAYS use this structure for every question to the user:**
+
+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.
+
+---
+
+## Step 1: Detect Project Context (silent, no questions)
+
+Before asking anything, scan the environment:
+
+```bash
+# What kind of project is this?
+ls CLAUDE.md .planning/ .memory/ .handoff/ 2>/dev/null
+ls build.gradle.kts package.json next.config.* 2>/dev/null
+ls .git 2>/dev/null && git branch --show-current 2>/dev/null
+ls .planning/PROJECT.md 2>/dev/null && echo "GSD_ACTIVE"
+
+# Check for Spartan updates (silent, non-blocking)
+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
+  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
+fi
+```
+
+**If update available**, show banner before anything else:
+> **Update available:** Spartan vX.Y.Z (you have v$LOCAL_VER). Run `/spartan:update` to upgrade.
+
+Classify silently:
+- **No project files** → New project journey
+- **Has code but no CLAUDE.md** → Needs onboarding → suggest `/spartan:onboard`
+- **Has CLAUDE.md + .planning/** → Active GSD project, resume
+- **Has CLAUDE.md, no .planning/** → Active project, task-based work
+
+---
+
+## Step 2: Route to Workflow or Command
+
+### Primary routing: Workflow Leaders
+
+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: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 |
+
+**Route to leaders when the user has a JOB to do.** The leader decides which skills and sub-commands to call — the user doesn't need to know about them.
+
+### Secondary routing: Individual commands
+
+Route here when the user wants a specific tool, not a full workflow.
+
+**Planning & project management:**
+| User says... | Route to |
+|---|---|
+| "plan a task", "write a spec" | `/spartan:spec` → `/spartan:plan` |
+| "break into features", "epic" | `/spartan:epic` |
+| "design a screen", "UI design", "design doc" | `/spartan:ux prototype` |
+| "UX research", "user interviews", "design system" | `/spartan:ux` |
+| "review my code", "dual review", "gate review" | `/spartan:gate-review` |
+| "big project", "multi-day", "new milestone" | `/spartan:project new` |
+| "continue phase", "next phase" | `/spartan:phase` |
+| "workstreams", "parallel work" | `/spartan:workstreams` |
+| "agent team", "spawn team", "create team", "multi-agent" | `/spartan:team` |
+| "run wave with agents", "execute wave with team" | `/spartan:team wave` |
+| "parallel review", "team review" | `/spartan:team review` |
+| "research swarm", "parallel research" | `/spartan:team research` |
+| "parallel build", "team build" | `/spartan:team build` |
+| "standup", "what did I do" | `/spartan:daily` |
+
+**Product thinking:**
+| User says... | Route to |
+|---|---|
+| "think through this", "before we build" | `/spartan:think` |
+| "brainstorm ideas" | `/spartan:brainstorm` |
+| "validate this idea" | `/spartan:validate` |
+| "competitor teardown" | `/spartan:teardown` |
+| "user interviews", "mom test" | `/spartan:interview` |
+| "lean canvas", "business model" | `/spartan:lean-canvas` |
+
+**Backend tools:**
+| User says... | Route to |
+|---|---|
+| "database migration", "add table" | `/spartan:migration` |
+| "new Kotlin service" | `/spartan:kotlin-service` |
+| "add testcontainers" | `/spartan:testcontainer` |
+| "review backend code" | `/spartan:review` |
+
+**Frontend tools:**
+| User says... | Route to |
+|---|---|
+| "new Next.js app" | `/spartan:next-app` |
+| "new feature/page" (frontend-specific) | `/spartan:next-feature` |
+| "Figma to code" | `/spartan:figma-to-code` |
+| "add E2E tests" | `/spartan:e2e` |
+| "review frontend code" | `/spartan:fe-review` |
+
+**Shipping:**
+| User says... | Route to |
+|---|---|
+| "ready for PR", "create PR" | `/spartan:pr-ready` |
+| "deploy", "push to prod" | `/spartan:deploy` |
+| "env setup", "environment vars" | `/spartan:env-setup` |
+
+**Startup pipeline (individual stages):**
+| User says... | Route to |
+|---|---|
+| "kickoff", "brainstorm + validate" | `/spartan:kickoff` |
+| "deep dive", "market + competitors" | `/spartan:deep-dive` |
+| "pitch deck", "investor materials" | `/spartan:pitch` |
+| "investor emails", "outreach" | `/spartan:outreach` |
+| "fundraise", "raise money" | `/spartan:fundraise` |
+| "write a post", "blog" | `/spartan:write` |
+| "content", "social media" | `/spartan:content` |
+
+**QA & Testing:**
+| User says... | Route to |
+|---|---|
+| "test in browser", "QA", "check the app", "test the UI" | `/spartan:qa` |
+| "add E2E tests" | `/spartan:e2e` |
+
+**Rules & Config:**
+| User says... | Route to |
+|---|---|
+| "set up rules", "configure rules", "init rules" | `/spartan:init-rules` |
+| "scan for patterns", "detect conventions" | `/spartan:scan-rules` |
+| "check my config", "validate rules" | `/spartan:lint-rules` |
+
+**Safety:**
+| User says... | Route to |
+|---|---|
+| "be careful", "careful mode" | `/spartan:careful` |
+| "lock to directory", "freeze" | `/spartan:freeze` |
+| "max safety", "guard mode" | `/spartan:guard` |
+| "unlock", "unfreeze" | `/spartan:unfreeze` |
+
+**Sessions:**
+| User says... | Route to |
+|---|---|
+| "what sessions", "active sessions", "other windows" | `/spartan:sessions` |
+| "clean sessions" | `/spartan:sessions clean` |
+
+**Feedback & Meta:**
+| User says... | Route to |
+|---|---|
+| "contributor mode", "self-improvement", "file reports" | `/spartan:contribute` |
+| "view reports", "skill ratings" | `/spartan:contribute reports` |
+| "what went wrong", "post-mortem" | `/spartan:forensics` |
+| "map the codebase" | `/spartan:map-codebase` |
+| "save context", "running out of context" | `/spartan:context-save` |
+| "upgrade GSD" | `/spartan:gsd-upgrade` |
+| "update spartan" | `/spartan:update` |
+
+---
+
+## Step 3: Explain briefly WHY, then run it
+
+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: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.
+
+### Preamble Tiers
+
+Not every command needs the same amount of context. Check the command/skill's `preamble-tier` field:
+
+| Tier | Context Weight | Use for | Examples |
+|------|---------------|---------|----------|
+| **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:debug`, `/spartan:review` |
+| **4** | Full — everything, deep context | Complex workflows, multi-phase | `/spartan:project`, `/spartan:phase`, `/spartan:onboard` |
+
+**How tiers affect behavior:**
+- **Tier 1:** Skip project detection (Step 1). Just run.
+- **Tier 2:** Run Step 1 but skip stack-specific context loading.
+- **Tier 3:** Full Step 1 + load relevant stack skills. (Default if no tier specified.)
+- **Tier 4:** Full Step 1 + load all relevant skills + check `.memory/` + check `.planning/`.
+
+### Contributor Mode Check
+
+After a command finishes, check if contributor mode is active:
+
+```bash
+[ -f ~/.spartan/contributor-mode ] && echo "CONTRIBUTOR_MODE=on"
+```
+
+If active, silently file a field report (see `/spartan:contribute` for format). Don't ask the user. Don't slow anything down.
+
+---
+
+## Step 2.5: Proactive Suggestions (always active)
+
+You don't have to wait for the user to type `/spartan`. When you notice these patterns in conversation, **suggest the right command** — one line, not pushy.
+
+### When to suggest
+
+| You notice... | Suggest |
+|---|---|
+| 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: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?" |
+| User is confused about what to do next | "Type `/spartan` and I'll figure out the right workflow." |
+| User just finished a big feature, no tests mentioned | "Should we add tests? `/spartan:e2e` for browser tests, or unit tests first." |
+| User has been coding for a while, no review mentioned | "Want a quick review before moving on? `/spartan:review`" |
+| User has a wave plan with 3+ parallel work units | "This wave has parallel tasks — want to use `/spartan:team wave` to run them with Agent Teams?" |
+| User wants multiple things reviewed or researched at once | "I can spin up a team for parallel work — `/spartan:team`" |
+
+### How to suggest
+
+- **One line.** Don't write a paragraph about why they should use the command.
+- **Suggest, don't force.** Say "want me to run X?" not "I'm running X now."
+- **Max once per conversation turn.** Don't spam 3 suggestions at once.
+- **Skip if obvious.** If the user clearly knows what they're doing, don't suggest.
+- **Context matters.** Don't suggest `/spartan:qa` if there's no frontend. Don't suggest `/spartan:deploy` for a library.
+
+---
+
+## Structured Question Format (all skills must follow)
+
+When any `/spartan:*` command needs to ask the user a question, follow this format. Every time. No exceptions.
+
+### The Format
+
+1. **Simplify** — State the question in plain English. No jargon. One sentence.
+2. **Recommend** — Give your recommendation. Say which option you'd pick and why.
+3. **Options** — List 2-3 lettered options (A/B/C). Each option = one line with a clear trade-off.
+4. **One decision** — Never bundle two unrelated questions. One question per turn.
+
+### Example
+
+**Bad (vague, no options):**
+> "How would you like to handle the authentication flow? There are several approaches we could take depending on your requirements."
+
+**Good (structured):**
+> "How should login work?
+>
+> I'd go with **B** — it's simpler and covers 90% of cases.
+>
+> - **A) Session-based** — server stores state, simpler frontend, harder to scale
+> - **B) JWT tokens** — stateless, easy to scale, needs refresh logic
+> - **C) OAuth only** — delegate to Google/GitHub, no password management"
+
+### Rules
+
+- **Always pick a side.** Don't say "it depends." Say which option you'd choose and why.
+- **Trade-offs, not descriptions.** Each option should say what you gain AND what you lose.
+- **Short options.** One line each. If you need more detail, the user will ask.
+- **Never ask without options.** If you can't think of options, you probably don't need to ask.
+- **Skip questions when possible.** If there's an obvious best choice, just do it and explain why.
+
+---
+
+## When NOT to route
+
+**Not everything needs a command.** If the user's request is:
+- A simple question → Just answer it
+- A small code change (< 30 min, 1-2 files) → Just do it
+- Asking for an explanation → Just explain
+- Chatting / discussing → Have the conversation
+
+Say: "This doesn't need a command — let me handle it directly."
+
+---
+
+## If user asks "what can you do?"
+
+Show the 5 workflow leaders first, then mention commands exist for specific tasks:
+
+"Spartan has **5 workflow leaders** — each one runs a full pipeline end-to-end. You don't need to chain commands manually.
+
+**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.
+
+**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]`
+Full pipeline: brainstorm → validate → research → pitch. Auto-resumes from where you left off if you come back later.
+
+**Onboard** — `/spartan:onboard`
+Scan → map architecture → set up tooling → save findings to memory. Future sessions start with the knowledge this one captured.
+
+**Research** — `/spartan:research [topic]`
+Deep research with source tracking and a structured report.
+
+**Fast path:** For quick work (< 1 day), just run `/spartan:build` — it handles spec + plan inline. No separate commands needed.
+
+There are also 40+ individual commands for specific tasks. Type `/spartan` anytime and I'll route you to the right one."
+
+---
+
+## Auto Mode
+
+If user says **"auto on"** or **"auto mode"**:
+- Acknowledge: "Auto mode ON — running straight through without confirmations. Say 'auto off' or 'stop' anytime."
+- All commands skip confirmation gates and run through
+- Still SHOW output at each step
+- Still STOP for destructive actions (force push, drop table, delete files)
+
+If user says **"auto off"**:
+- Acknowledge: "Auto mode OFF — asking for confirmation at each step."
+
+---
+
+## Context Management (always active)
+
+Monitor your own context health:
+- Losing track of earlier decisions → **compact now**
+- Repeating questions already answered → **compact now**
+- Responses getting slower or less precise → **warn user + compact**
+
+Action sequence:
+1. First sign of pressure → run `/compact` silently, tell user: "Context getting heavy — compacted."
+2. If still struggling after compact → trigger `/spartan:context-save`
+3. Never let quality drop silently — always tell the user.