@c0x12c/ai-toolkit 1.15.0

package/commands/spartan/qa.md

@@ -0,0 +1,222 @@
+---
+name: spartan:qa
+description: Run real browser QA on your app using Playwright. Opens Chromium, clicks through flows, finds bugs, and reports issues. Use after building a feature to test it like a real user.
+argument-hint: "[URL or localhost port] [optional: feature to test]"
+---
+
+# Browser QA: {{ args[1] | default: "full app" }}
+
+You are running **real browser QA** — not unit tests, not mocks. A real Chromium browser hitting a real running app.
+
+**Target:** {{ args[0] | default: "http://localhost:3000" }}
+
+---
+
+## Step 0: Pre-flight Check
+
+```bash
+# Is the app running?
+TARGET="{{ args[0] | default: 'http://localhost:3000' }}"
+curl -s -o /dev/null -w "%{http_code}" "$TARGET" || echo "APP_NOT_RUNNING"
+
+# Is Playwright installed?
+npx playwright --version 2>/dev/null || echo "PLAYWRIGHT_MISSING"
+```
+
+**If app not running:**
+> "Your app isn't running at $TARGET. Start it first (`npm run dev` or `./gradlew run`), then re-run `/spartan:qa`."
+
+**If Playwright missing:**
+> "Playwright isn't installed. Run `npm install -D @playwright/test && npx playwright install chromium` first."
+
+---
+
+## Step 1: Discover What to Test
+
+{% if args[1] %}
+Focus QA on: **{{ args[1] }}**
+
+Find the routes and components related to this feature:
+```bash
+# Find related pages
+find . -path "*/app/**/page.tsx" -o -path "*/pages/**/*.tsx" 2>/dev/null | head -20
+
+# Find related API routes
+find . -path "*/app/api/**/route.ts" -o -path "*/pages/api/**/*.ts" 2>/dev/null | head -20
+```
+
+Build a test plan for this specific feature.
+{% else %}
+No specific feature given — run a **full smoke test**.
+
+Discover all routes:
+```bash
+# Next.js App Router pages
+find . -path "*/app/**/page.tsx" -not -path "*/node_modules/*" 2>/dev/null | sort
+
+# Next.js Pages Router
+find . -path "*/pages/**/*.tsx" -not -path "*/node_modules/*" -not -name "_*" 2>/dev/null | sort
+
+# API routes
+find . -path "*/app/api/**/route.ts" -o -path "*/pages/api/**/*.ts" 2>/dev/null | sort
+```
+
+Build a test plan that hits every discoverable page.
+{% endif %}
+
+### Test Plan Format
+
+Before testing, show the plan:
+
+```
+QA Plan: [feature or "full smoke"]
+Target:  [URL]
+
+Flows to test:
+  1. [Page/flow name] — [what to check]
+  2. [Page/flow name] — [what to check]
+  3. ...
+
+Checks per page:
+  - Page loads without console errors
+  - No broken images or missing assets
+  - Interactive elements respond (buttons, links, forms)
+  - Mobile viewport doesn't break layout
+  - API calls return 2xx
+```
+
+---
+
+## Step 2: Run QA Tests
+
+Use Playwright to test each flow. Write and run tests inline:
+
+```typescript
+import { chromium } from 'playwright'
+
+const browser = await chromium.launch({ headless: true })
+const context = await browser.newContext({
+  viewport: { width: 1280, height: 720 },
+})
+const page = await context.newPage()
+
+// Collect console errors
+const consoleErrors: string[] = []
+page.on('console', msg => {
+  if (msg.type() === 'error') consoleErrors.push(msg.text())
+})
+
+// Collect failed network requests
+const networkErrors: string[] = []
+page.on('requestfailed', req => {
+  networkErrors.push(`${req.method()} ${req.url()} — ${req.failure()?.errorText}`)
+})
+
+// Test each flow...
+await page.goto('TARGET_URL')
+// [test logic here]
+
+await browser.close()
+```
+
+### What to Check on Every Page
+
+1. **Console errors** — collect all `console.error` messages
+2. **Network failures** — any 4xx/5xx responses or failed requests
+3. **Missing assets** — broken images, failed CSS/JS loads
+4. **Layout issues** — check at 1280px and 375px (mobile) viewports
+5. **Interactive elements** — click buttons, fill forms, check they respond
+6. **Navigation** — links go where they should, no dead ends
+
+### What to Check for Specific Features
+
+- **Forms:** Submit with valid data → success. Submit empty → validation shows.
+- **Auth flows:** Login → redirect to dashboard. Protected page → redirect to login.
+- **CRUD:** Create → appears in list. Edit → shows updated. Delete → gone from list.
+- **Search/filter:** Type → results update. Clear → back to full list.
+
+---
+
+## Step 3: Report Findings
+
+After testing, produce a QA report:
+
+```markdown
+## QA Report: [feature or "full smoke"]
+Date: [today]
+Target: [URL]
+
+### Summary
+- Pages tested: [N]
+- Bugs found: [N]
+- Warnings: [N]
+- All clear: [N pages with no issues]
+
+### Bugs (fix these)
+
+#### BUG-1: [title]
+- **Page:** [URL]
+- **Steps:** [how to reproduce]
+- **Expected:** [what should happen]
+- **Actual:** [what happened]
+- **Severity:** [blocker / major / minor]
+- **Fix suggestion:** [if obvious]
+
+### Warnings (review these)
+
+#### WARN-1: [title]
+- **Page:** [URL]
+- **Issue:** [what's not ideal]
+- **Suggestion:** [how to improve]
+
+### Passed
+- [page] — all checks passed
+- [page] — all checks passed
+```
+
+---
+
+## Step 4: Auto-Fix (when possible)
+
+For simple issues, offer to fix them right away:
+
+**Auto-fixable:**
+- Missing alt text on images
+- Console errors from missing env vars
+- Broken internal links (wrong href)
+- Missing viewport meta tag
+- Unclosed HTML tags
+
+**NOT auto-fixable (just report):**
+- Layout bugs (need design decision)
+- Logic errors (need understanding of intent)
+- Performance issues (need profiling)
+- API errors (need backend investigation)
+
+For each auto-fixable bug:
+> "BUG-1 is auto-fixable. Want me to fix it? [Y/n]"
+
+Fix one at a time. Re-run that specific check after each fix to verify.
+
+---
+
+## Step 5: Next Steps
+
+After the report, suggest:
+
+- Bugs found → "Want me to fix these? I'll go one by one."
+- All clear → "QA passed. Ready for `/spartan:pr-ready`."
+- Need deeper testing → "For E2E test coverage, run `/spartan:e2e` to scaffold permanent Playwright tests."
+
+---
+
+## Rules
+
+1. **Always check if the app is running first.** Don't waste time if there's nothing to test.
+2. **Real browser only.** No curl-based testing. No mock browsers. Playwright with real Chromium.
+3. **Headless by default.** Don't pop up browser windows unless user asks for `--headed`.
+4. **Report ALL issues found.** Don't stop at the first bug.
+5. **Mobile viewport is not optional.** Always check at 375px width.
+6. **Console errors are bugs.** Even if the page "looks fine," console errors need fixing.
+7. **Auto-fix only with permission.** Show the fix, ask before applying.
+8. **This is a one-shot run.** No persistent daemon. Spin up browser, test, close, done.

package/commands/spartan/research.md

@@ -0,0 +1,254 @@
+---
+name: spartan:research
+description: "Deep research on any topic — frame the question, gather sources, analyze, and produce a structured report"
+argument-hint: "[topic to research]"
+---
+
+# Research: {{ args[0] | default: "your topic" }}
+
+You are running the **Research workflow** — turn a question into an actionable report backed by real sources.
+
+```
+STAGE 1: FRAME             STAGE 2: GATHER           STAGE 3: ANALYZE          STAGE 4: REPORT
+──────────────            ──────────────            ────────────────          ───────────────
+Sharpen the question      Web search (multiple)     Cross-reference           Structured report
+What's useful output?     Read sources              Patterns + contradictions Key findings
+Source strategy           Track credibility         Form a clear view         Recommendations
+
+Gate 1                                              Gate 2                    Gate 3
+"Right question?"                                   "Key findings so far"     "Full report"
+```
+
+---
+
+## Style
+
+Be direct. Give options with your honest take. Pick a side — never say "it depends" without choosing. No filler.
+
+---
+
+## Stage 1: Frame
+
+**Goal:** Turn a vague topic into a specific, answerable question.
+
+### Sharpen the question
+The user's topic is probably too broad. Narrow it:
+
+| Too broad | Better |
+|-----------|--------|
+| "AI dev tools" | "Which AI coding assistants have >10k paying users and why?" |
+| "competitor landscape" | "Who are the top 5 competitors in [space], what do they charge, and where are the gaps?" |
+| "market for X" | "How big is the [X] market, who's buying, and is it growing?" |
+
+### Define useful output
+Ask: "What would a useful answer look like?"
+
+Options:
+- **Comparison table** — if comparing things (competitors, tools, approaches)
+- **Number + context** — if sizing a market or measuring something
+- **Recommendation** — if deciding between options
+- **Landscape map** — if understanding a space
+
+### Pick source strategy
+
+| Research type | Best sources |
+|---------------|-------------|
+| Market sizing | Industry reports, investor decks, public filings |
+| Competitor analysis | Product pages, pricing pages, reviews, job postings |
+| Tech evaluation | Docs, GitHub repos, benchmarks, community forums |
+| Trend research | News, social media, conference talks, funding announcements |
+| Academic/deep | Papers, books, expert blogs |
+
+**GATE 1 — STOP and ask:**
+> "Here's how I'd frame the research:
+> - Question: [specific question]
+> - Output format: [table/number/recommendation/map]
+> - Sources: [what I'll search for]
+>
+> Right direction, or should I adjust the focus?"
+>
+> **Auto mode on?** → Show framing, continue immediately.
+
+---
+
+## Stage 2: Gather
+
+**Goal:** Find real data from real sources. Track everything.
+
+### Agent Teams boost (if enabled)
+
+```bash
+echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not_set}"
+```
+
+**If Agent Teams is enabled**, create a research team (NOT sub-agents):
+
+```
+TeamCreate(team_name: "research-{topic-slug}", description: "Research: {topic}")
+
+TaskCreate(subject: "Breadth search", description: "Run direct + alternative + adjacent queries, collect 8-15 sources with credibility scores")
+TaskCreate(subject: "Depth analysis", description: "Deep dive on top 3-5 sources from breadth search")
+TaskCreate(subject: "Contrarian search", description: "Find counterarguments, failures, criticism")
+
+Agent(
+  team_name: "research-{topic-slug}",
+  name: "breadth-researcher",
+  subagent_type: "general-purpose",
+  prompt: "Search broadly for: {topic}. Run direct + alternative + adjacent queries.
+    Collect 8-15 sources. Track each with: title, URL, credibility (1-5), key data points.
+    Check TaskList, claim your task. Message depth-researcher when you have initial findings."
+)
+
+Agent(
+  team_name: "research-{topic-slug}",
+  name: "depth-researcher",
+  subagent_type: "general-purpose",
+  prompt: "Go deep on the top 3-5 sources for: {topic}.
+    Extract detailed data, cross-reference claims, note contradictions.
+    Check TaskList, claim your task. Wait for breadth-researcher findings if needed."
+)
+
+Agent(
+  team_name: "research-{topic-slug}",
+  name: "contrarian-researcher",
+  subagent_type: "general-purpose",
+  prompt: "Find counterarguments and criticism for: {topic}.
+    Search for failures, risks, overhyped claims, hidden costs.
+    Check TaskList, claim your task."
+)
+```
+
+After all teammates report back, merge source lists, `TeamDelete()`, continue to Stage 3 (Analyze).
+
+**If Agent Teams is NOT enabled**, gather sequentially:
+
+### Search strategy
+Use the `deep-research` skill. Run multiple search queries — not just one:
+
+1. **Direct query** — the obvious search
+2. **Alternative framing** — same question, different words
+3. **Adjacent query** — related topic that might have useful data
+4. **Contrarian query** — "why [topic] is wrong/failing/overhyped"
+
+### For each source found, track:
+
+```markdown
+**Source:** [title]
+**URL:** [link]
+**Credibility:** [1-5, where 5 = primary data/official, 1 = random blog]
+**Key data points:**
+- [fact 1]
+- [fact 2]
+**Notes:** [anything to flag — bias, outdated, contradicts other sources]
+```
+
+### Source credibility rules
+- **5 — Primary data:** Company filings, official announcements, published research with methodology
+- **4 — Expert source:** Industry analyst, domain expert blog, respected publication
+- **3 — Good secondary:** Tech publication, well-sourced article, community consensus
+- **2 — Weak secondary:** Random blog, social media opinion, anonymous source
+- **1 — Unreliable:** Unsourced claims, obvious bias, marketing material presented as research
+
+**Don't stop at 3 sources.** Aim for 8-15 depending on topic size. More sources = more signal.
+
+**No gate here — continue to Analyze.** But if the data is thin, say so:
+> "I found limited data on this. Here's what exists: [X]. Want me to dig in a different direction?"
+
+---
+
+## Stage 3: Analyze
+
+**Goal:** Turn raw data into insight. Form a view.
+
+### Cross-reference
+- Do multiple sources agree? That's stronger signal.
+- Do sources contradict? Flag it — and say which you trust more and why.
+- Is there a pattern across sources that none of them call out directly?
+
+### Separate fact from opinion
+For every claim in your notes, tag it:
+- **FACT** — backed by data, multiple sources agree
+- **LIKELY** — strong signal but not confirmed
+- **OPINION** — one source's view, not proven
+- **CONTESTED** — sources disagree
+
+### Form a view
+Don't be neutral. After analyzing the data, take a position:
+- "The data says [X]."
+- "Most sources agree on [Y] but I think [Z] is more accurate because [evidence]."
+- "There's not enough data to be confident, but the best guess is [W]."
+
+**GATE 2 — STOP and ask:**
+> "Here's what I found:
+> - [Key finding 1]
+> - [Key finding 2]
+> - [Key finding 3]
+> - Surprise: [something unexpected]
+>
+> Want the full report, or should I dig deeper on any of these?"
+>
+> **Auto mode on?** → Show findings, continue to report.
+
+---
+
+## Stage 4: Report
+
+**Goal:** Structured, actionable document. No filler.
+
+### Report format
+
+```markdown
+# Research Report: [topic]
+Date: [YYYY-MM-DD]
+
+## Question
+[The specific, sharpened question from Stage 1]
+
+## Key Findings
+1. [Most important finding — one paragraph]
+2. [Second finding]
+3. [Third finding]
+
+## Analysis
+
+### [Section based on question type]
+[Deep analysis with data. Every claim linked to a source.]
+
+### What the data doesn't tell us
+[Gaps in the research. What you couldn't find or confirm.]
+
+### Surprises
+[Anything unexpected that changes the picture.]
+
+## Recommendation
+[Clear, actionable recommendation. Not "it depends."]
+[If the user needs to make a decision, pick a side and explain why.]
+
+## Sources
+| # | Source | Credibility | Key contribution |
+|---|--------|-------------|-----------------|
+| 1 | [name + URL] | [1-5] | [what it provided] |
+| 2 | ... | ... | ... |
+
+## Methodology
+[What you searched for, how many sources reviewed, what was excluded and why]
+```
+
+### Save the report
+If a project folder exists → save to `02-research/research-[topic-slug]-YYYY-MM-DD.md`
+If no project folder → save to current directory or ask where.
+
+**GATE 3 — Done.**
+> "Report saved to [path]. Key takeaway: [one sentence]. Want me to go deeper on anything, or use this for something? (e.g., `/spartan:content` to turn it into a blog post)"
+
+---
+
+## Rules
+
+- **Sharpen the question first.** A vague question gets a vague answer. Always narrow it at Stage 1.
+- **Track credibility.** Not all sources are equal. Say which you trust and why.
+- **Take a position.** "The data suggests..." is better than "there are many perspectives."
+- **Flag what you don't know.** Honest gaps are better than padded content.
+- **Aim for 8-15 sources.** Less than 5 is usually too thin. More than 20 is diminishing returns.
+- **No filler.** Every sentence should add information. If you can cut a paragraph without losing meaning, cut it.
+- **Separate facts from opinions.** Label them. The reader needs to know what's proven vs. guessed.

package/commands/spartan/review.md

@@ -0,0 +1,132 @@
+---
+name: spartan:review
+description: Perform a thorough PR review using your project's configured rules
+argument-hint: "[optional: branch name or PR description]"
+---
+
+# Code Review: {{ args[0] | default: "current changes" }}
+
+Perform a thorough review of the current changes. Use `git diff` to inspect all modified files.
+
+---
+
+## Step 0: Load rules
+
+```bash
+# 1. Check for project config
+cat .spartan/config.yaml 2>/dev/null || cat ~/.spartan/config.yaml 2>/dev/null
+
+# 2. Classify changed files
+git diff main...HEAD --name-only
+```
+
+**If `.spartan/config.yaml` exists:**
+- Read `rules.backend`, `rules.frontend`, `rules.shared` — these are the rules to check against
+- Read `file-types` — use these to classify changed files into backend/frontend/migration
+- Read `review-stages` — only run enabled stages
+- 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 — 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
+- Classify files by extension: `.kt/.java/.go/.py` = backend, `.tsx/.ts/.vue` = frontend, `.sql` = migration
+
+**Read all matched rule files** before reviewing any code. These are the source of truth.
+
+---
+
+## Review Checklist
+
+Run each enabled stage. Skip stages that are disabled in the config.
+
+### Stage 1: Correctness & Business Logic
+- [ ] Does the code match the stated requirements/ticket?
+- [ ] Are all edge cases handled?
+- [ ] Is error handling following the project's pattern? (check the loaded rules)
+- [ ] Are there any banned patterns? (check the loaded rules for forbidden items)
+
+### Stage 2: Stack Conventions
+- [ ] Code follows the patterns in the loaded rule files
+- [ ] Stack idioms are correct for this language/framework
+- [ ] Naming conventions match the project style (check NAMING rules if loaded)
+
+### Stage 3: Test Coverage
+- [ ] New code has tests
+- [ ] Tests are independent (no test order dependencies)
+- [ ] Edge cases are tested
+- [ ] Tests verify behavior, not implementation details
+
+### Stage 4: Clean Code & Architecture
+- [ ] Architecture matches what the config says (layered, hexagonal, clean, mvc, etc.)
+- [ ] No business logic in the wrong layer (check loaded arch rules)
+- [ ] No cyclic dependencies between packages/modules
+- [ ] Functions are small and single-purpose
+
+### Stage 5: Database & API
+- [ ] Schema follows the loaded database rules (if any)
+- [ ] API design follows the loaded API rules (if any)
+- [ ] Input validation on all public endpoints
+- [ ] No sensitive data logged or exposed
+
+### Stage 6: Security
+- [ ] Auth checks present where needed
+- [ ] Input validated and sanitized
+- [ ] No injection risks (SQL, XSS, command injection)
+- [ ] No sensitive data in logs or error responses
+- [ ] No hardcoded secrets or credentials
+
+### Stage 7: Documentation Gap Analysis
+After reviewing, check if any patterns should be documented:
+- [ ] New pattern used that isn't in the rules yet? → flag for rules update
+- [ ] New convention established? → flag for `.memory/patterns/` or new rule file
+- [ ] Recurring issue? → suggest creating a rule so it gets caught automatically
+
+---
+
+## Output Format
+
+```
+## PR Review Summary
+
+### Approved / Needs Changes / Blocked
+
+### Rules Checked
+- [list of rule files that were loaded and checked against]
+
+### Critical Issues (must fix)
+- [issue with file:line reference and which rule it breaks]
+
+### Suggestions (nice to have)
+- [suggestion]
+
+### Praise (what was done well)
+- [positive note]
+
+### Documentation Updates Needed
+- [rule file or .memory/ path]: [what to add/update] — OR "none"
+
+### Verdict
+[Final recommendation]
+```
+
+---
+
+## Rules
+
+- Always use `git diff` to inspect actual changes — don't guess from filenames
+- Read rule files from config BEFORE reviewing code — they're the source of truth
+- Every finding must include file:line reference
+- Every finding must cite which rule it breaks (or which checklist item)
+- Separate "must fix" from "nice to have" — don't block PRs on style nits
+- Praise good code — reviews aren't just for finding problems
+- If no config and no rules found, still review using the generic checklist above