@c0x12c/ai-toolkit 1.15.0

package/templates/quality-gates.md

@@ -0,0 +1,230 @@
+# Quality Gates
+
+Each phase of the feature development workflow has a quality gate. The gate must pass before moving to the next phase.
+
+---
+
+## The Workflow
+
+```
+Epic → Spec → [Design] → Plan → Build → Review
+        ↑        ↑          ↑      ↑        ↑
+      Gate 1  Design      Gate 2  Gate 3  Gate 4
+              Gate               Gate 3.5
+```
+
+Design is optional — use it for features with UI work. See `design-doc.md`.
+
+---
+
+## Gate 1: Spec Review
+
+Run after writing a spec (`feature-spec.md`). Ask: "Is the WHAT clear enough to plan?"
+
+**Completeness:**
+- [ ] Problem is clearly stated (not vague)
+- [ ] Goal is specific and measurable
+- [ ] At least one user story exists
+- [ ] Requirements split into must-have, nice-to-have, out of scope
+- [ ] Out of scope section exists (prevents scope creep)
+
+**Data Model** (if applicable):
+- [ ] New tables have standard columns (id, timestamps)
+- [ ] Column types are correct
+- [ ] Soft delete strategy is defined (if needed)
+
+**API Design** (if applicable):
+- [ ] Endpoints follow the project's naming convention
+- [ ] Request/response examples included
+- [ ] JSON field naming matches project convention
+
+**UI Changes** (if applicable):
+- [ ] Affected screens/components listed
+- [ ] Design doc created for non-trivial UI work
+
+**Quality:**
+- [ ] Edge cases listed (at least 3)
+- [ ] Testing criteria defined for happy path
+- [ ] Testing criteria defined for edge cases
+- [ ] Dependencies listed
+
+---
+
+## Gate 2: Plan Review
+
+Run after writing a plan (`implementation-plan.md`). Ask: "Is the HOW clear enough to build?"
+
+**Architecture:**
+- [ ] Follows the project's existing architecture patterns
+- [ ] Each layer only calls the layer below it
+- [ ] Components are in the right directories
+
+**Task Breakdown:**
+- [ ] All files to change are listed
+- [ ] All new files are listed with their locations
+- [ ] Each task is small (one file or one function)
+- [ ] Dependencies between tasks are clear
+- [ ] Parallel vs sequential tasks are marked
+
+**Testing:**
+- [ ] Data layer tests planned
+- [ ] Business logic tests planned
+- [ ] API/integration tests planned
+- [ ] UI tests planned (if applicable)
+- [ ] Edge cases from spec are covered in test plan
+
+---
+
+## Gate 3: Implementation Review (Per Task)
+
+Run after each task is done during the build phase.
+
+**Code Quality:**
+- [ ] No unsafe operations or workarounds
+- [ ] Error handling follows project patterns
+- [ ] No temporary hacks or TODOs left behind
+- [ ] Config values come from config, not hardcoded
+- [ ] No dead code or unused imports
+
+**Architecture:**
+- [ ] Each component stays in its lane (no layer violations)
+- [ ] Handlers/controllers are thin (just delegate)
+- [ ] Business logic is in the service/manager layer
+- [ ] Data access is in the repository/data layer
+
+**Tests:**
+- [ ] Tests written for this task
+- [ ] Tests pass
+- [ ] Tests cover both happy path and error cases
+
+---
+
+## Gate 3.5: Phase Review (Dual-Agent)
+
+Run after all tasks in a phase are done. This is a **dual-agent review** — the builder and the `phase-reviewer` agent both evaluate the work. Both must accept.
+
+**Trigger:** `/spartan:gate-review [phase number]`
+
+### Agent Agreement (must pass first)
+- [ ] Reviewer agent spawned and given all changed files
+- [ ] Builder did self-assessment before calling reviewer
+- [ ] Both agents (builder + reviewer) confirmed they accept the result
+- [ ] All discussion points are resolved (no open disagreements)
+- [ ] If disagreement after 3 rounds → escalated to user
+
+### Code Design
+- [ ] Single responsibility (each class/module does one thing)
+- [ ] No god classes or methods doing too much
+- [ ] Proper separation of concerns between layers
+- [ ] Naming is clear and consistent
+- [ ] Method/function signatures are clean (not too many parameters)
+
+### Best Practices
+- [ ] No unnecessary complexity or over-engineering
+- [ ] No dead code or unused imports
+- [ ] Error messages are helpful (what went wrong + what to do)
+- [ ] Logging is right — enough to debug, not noisy
+- [ ] No magic numbers or strings (use config or constants)
+
+### Clean Code
+- [ ] Functions are short and focused
+- [ ] No deeply nested conditionals (max 2-3 levels)
+- [ ] No copy-paste duplication
+- [ ] Code reads top to bottom
+
+---
+
+## Gate 4: Final Review
+
+Run when all tasks are done. This is the "ship it?" check.
+
+**Completeness:**
+- [ ] All tasks from the plan are done
+- [ ] All planned files exist
+- [ ] No TODOs left in code
+- [ ] No placeholder implementations
+
+**Quality:**
+- [ ] All tests pass
+- [ ] Linter passes
+- [ ] Build passes
+- [ ] No regressions in existing tests
+
+**Documentation:**
+- [ ] API endpoints are documented or self-evident
+- [ ] Implementation notes captured
+- [ ] README updated if new components added
+
+---
+
+## Design Gate (Dual-Agent)
+
+Run after the designer and `design-critic` agent both review the design doc. Both must accept.
+
+**Trigger:** `/spartan:ux prototype [feature-name]`
+
+### Agent Agreement
+- [ ] Design-critic agent spawned and given the design doc
+- [ ] Designer did self-check before calling critic
+- [ ] Both agents (designer + critic) confirmed they accept
+- [ ] All discussion points resolved
+
+### AI Generic Detection
+- [ ] No colors outside the project palette (check design-config.md)
+- [ ] No generic gradient blobs or decorative noise
+- [ ] Layout has visual variety (not everything centered, same size)
+- [ ] Typography has clear hierarchy (3+ distinct sizes/weights)
+- [ ] Copy is specific to the project domain (not generic marketing)
+- [ ] Design personality matches design-config.md
+- [ ] Accent color used sparingly — max 10-15% of screen
+- [ ] Would you remember this design? (If no, it's too generic)
+
+### Design System Compliance (if design-config exists)
+- [ ] Colors match the design-config palette exactly
+- [ ] Font matches design-config
+- [ ] Shadows/radius match design-config values
+- [ ] No Tailwind default colors used
+
+### User Flows
+- [ ] Every user story from spec has a mapped flow
+- [ ] Each flow has clear steps: trigger, actions, end state
+- [ ] Edge case flows listed (empty data, error, loading, timeout)
+
+### Accessibility (WCAG AA)
+- [ ] Text contrast ratio meets 4.5:1
+- [ ] Interactive elements have focus states
+- [ ] Touch targets at least 44x44px on mobile
+- [ ] No information conveyed by color alone
+
+### Responsiveness
+- [ ] Layout works at mobile, tablet, desktop
+- [ ] No horizontal scroll on mobile
+- [ ] Content reflows properly
+
+### Completeness
+- [ ] All states shown (loading, empty, error, success)
+- [ ] Component specs have: name, props, states
+- [ ] Wireframes exist for key screens
+- [ ] A developer could build from just the design doc
+
+---
+
+## What to Do When a Gate Fails
+
+1. **Find the failing items** — which checkboxes are unchecked?
+2. **Fix them** — don't move on until ALL items pass
+3. **Re-run the gate** — make sure the fix works
+4. **If stuck** — ask for guidance, don't use workarounds
+
+---
+
+## Gate Summary
+
+| Gate | When | Ask Yourself |
+|------|------|--------------|
+| Gate 1 | After spec | Is the WHAT clear enough to plan? |
+| Gate 2 | After plan | Is the HOW clear enough to build? |
+| Gate 3 | After each task | Does this code follow the rules? |
+| Gate 3.5 | After each phase | Dual-agent review — builder + reviewer both accept? |
+| Gate 4 | After all tasks | Is this ready to ship? |
+| Design Gate | After design doc | Dual-agent — designer + critic both accept? Not AI-generic? |

package/templates/spartan-config.yaml

@@ -0,0 +1,164 @@
+# .spartan/config.yaml — Configurable Rules for Spartan AI Toolkit
+#
+# This file tells the toolkit which rules to check during build, review,
+# and other workflows. Without this file, the toolkit auto-detects your
+# stack and uses default rules.
+#
+# Generate this file: /spartan:init-rules
+# Validate this file: /spartan:lint-rules
+# Auto-detect rules from code: /spartan:scan-rules
+
+# ─── Stack & Architecture ───────────────────────────────────────────
+
+# Your tech stack. Used for auto-routing skills and review stages.
+# Built-in: kotlin-micronaut, react-nextjs, go-standard, python-django,
+#           python-fastapi, java-spring, typescript-node
+# Or set to "custom" and define everything yourself.
+stack: custom
+
+# Architecture pattern. Guides how build plans tasks and review checks layers.
+# Built-in: layered, hexagonal, clean, mvc, custom
+architecture: layered
+
+# ─── Inherit from a Profile (optional) ──────────────────────────────
+
+# Start from a built-in profile and customize on top.
+# Profiles live in toolkit/profiles/ — each has sensible defaults.
+# extends: kotlin-micronaut
+
+# ─── Rules ──────��───────────────────────────────────────────────────
+
+# Rules are markdown files that the reviewer reads before checking code.
+# Paths are relative to the project root (or ~/.claude/ for global rules).
+#
+# Group rules by mode. During review:
+#   backend mode  → backend + shared rules
+#   frontend mode → frontend + shared rules
+#   full-stack    → all rules
+
+rules:
+  shared: []
+    # - rules/core/NAMING_CONVENTIONS.md
+
+  backend: []
+    # - rules/backend/CONTROLLERS.md
+    # - rules/backend/ERROR_HANDLING.md
+    # - rules/database/SCHEMA.md
+
+  frontend: []
+    # - rules/frontend/COMPONENTS.md
+    # - rules/frontend/STATE_MANAGEMENT.md
+
+# ─── Override Rules (when extending a profile) ──────────────────────
+
+# Use these to customize an inherited profile without rewriting everything.
+# Only works when "extends" is set above.
+
+# rules-add:
+#   backend:
+#     - rules/custom/OUR_AUTH_RULES.md
+
+# rules-remove:
+#   backend:
+#     - rules/backend-micronaut/RETROFIT_PLACEMENT.md
+
+# rules-override:
+#   backend:
+#     rules/database/SCHEMA.md: rules/custom/OUR_SCHEMA.md
+
+# ─── Conditional Rules (advanced) ───────���───────────────────────────
+
+# Rules that only apply to files matching a glob pattern.
+# Useful for monorepos or projects with mixed concerns.
+
+# conditional-rules:
+#   - rule: rules/backend/BATCH_RULES.md
+#     applies-to: "src/**/batch/**"
+#   - rule: rules/database/SCHEMA.md
+#     applies-to: "*.sql"
+#   - rule: rules/custom/API_V2_RULES.md
+#     applies-to: "src/api/v2/**"
+
+# ─── File Type Mapping ──────────────────────────────────────────────
+
+# Maps file extensions to modes. Used for auto-detecting which rules
+# to apply when reviewing a specific file.
+
+file-types:
+  backend: [".kt", ".java", ".go", ".py", ".rb", ".rs", ".cs"]
+  frontend: [".tsx", ".ts", ".jsx", ".js", ".vue", ".svelte"]
+  migration: [".sql"]
+  config: [".yaml", ".yml", ".json", ".toml"]
+
+# ─── Review Stages ──────────────────────────────────────────────────
+
+# Which stages to run during build review and /spartan:review.
+# Remove stages you don't need. Add custom stages at the end.
+# Order matters — stages run top to bottom.
+
+review-stages:
+  - name: correctness
+    description: "Does the code match the spec? Edge cases handled?"
+    enabled: true
+
+  - name: stack-conventions
+    description: "Follows stack-specific patterns and idioms"
+    enabled: true
+
+  - name: test-coverage
+    description: "Tests exist, are independent, cover edge cases"
+    enabled: true
+
+  - name: architecture
+    description: "Proper layer separation, no logic in wrong layers"
+    enabled: true
+
+  - name: database-api
+    description: "Schema rules, API design, input validation"
+    enabled: true
+
+  - name: security
+    description: "Auth, injection, data exposure, OWASP top 10"
+    enabled: true
+
+  - name: documentation-gaps
+    description: "New patterns that should be documented"
+    enabled: true
+
+  # Add your own stages:
+  # - name: performance
+  #   description: "Check for N+1 queries, unnecessary allocations"
+  #   enabled: true
+  # - name: observability
+  #   description: "Logging, metrics, tracing present for new endpoints"
+  #   enabled: true
+
+# ─── Build Commands ─────────────────────────────────────────────────
+
+# Override the test and build commands for your stack.
+# These are used in /spartan:build Stage 3 verification.
+
+commands:
+  test:
+    backend: ""     # e.g., "./gradlew test", "go test ./...", "pytest"
+    frontend: ""    # e.g., "npm test", "yarn vitest"
+  build:
+    backend: ""     # e.g., "./gradlew build", "go build ./..."
+    frontend: ""    # e.g., "npm run build", "yarn build"
+  lint:
+    backend: ""     # e.g., "./gradlew ktlintCheck", "golangci-lint run"
+    frontend: ""    # e.g., "npm run lint", "eslint ."
+
+# ─── Skill Routing ─────────��────────────────────────────────────────
+
+# Map work types to skills. During build, the toolkit calls the right
+# skill based on what task it's working on.
+# Comment out skills you don't have installed.
+
+# skill-routing:
+#   database-migration: database-patterns
+#   new-endpoint: api-endpoint-creator
+#   backend-code: kotlin-best-practices
+#   writing-tests: testing-strategies
+#   ui-components: ui-ux-pro-max
+#   security: security-checklist

package/templates/user-interview.md

@@ -0,0 +1,69 @@
+# User Interview
+
+**Person:**
+**Date:**
+**Context:** How do you know them? What do they do?
+
+---
+
+## Rules (Mom Test)
+1. Talk about their life, not your idea
+2. Ask about the past, not the future
+3. Talk less, listen more
+4. Bad news is good news
+5. Never pitch during the interview
+
+---
+
+## Opening
+> "Tell me about the last time you [did the thing you're solving for]"
+
+## Questions
+
+### Understanding the Problem
+1. Walk me through how you currently handle [problem]?
+2. What's the hardest part about [problem]?
+3. Why is that hard?
+4. How often does this happen?
+5. What have you tried to fix it?
+6. What happened?
+
+### Finding Pain
+7. What does it cost you? (time, money, stress)
+8. How do you work around it now?
+9. If you could wave a magic wand, what would change?
+
+### Validating Importance
+10. When was the last time this happened?
+11. What did you do?
+12. Have you looked for solutions?
+13. What did you find?
+14. Why didn't you use them?
+
+---
+
+## Notes
+> Write their actual words, not your interpretation
+
+## Key Quotes
+> Exact quotes that prove pain
+
+## Insights
+> What did you learn?
+
+## Red Flags
+> Anything that suggests they don't really care?
+
+## Follow-ups
+> What should you ask next time?
+
+---
+
+## Score
+| Question | Answer |
+|----------|--------|
+| Real problem? | Yes / Maybe / No |
+| Happens often? | Daily / Weekly / Monthly / Rarely |
+| Currently pays to solve? | Yes ($___) / No |
+| Would pay for solution? | Yes ($___) / Maybe / No |
+| Warm intro potential? | Yes / No |

package/templates/validation-checklist.md

@@ -0,0 +1,108 @@
+# Validation Checklist
+
+**Project:**
+**Date:**
+
+---
+
+## Problem Validation
+
+### Do people have this problem?
+- [ ] Talked to 5+ potential users
+- [ ] Found 3+ people actively trying to solve it
+- [ ] Problem happens at least weekly
+- [ ] Problem costs them real time/money/stress
+
+**Evidence:**
+
+### Is the problem big enough?
+- [ ] Market has 10,000+ potential users
+- [ ] They currently spend money on solutions
+- [ ] Problem is getting worse, not better
+
+**Evidence:**
+
+---
+
+## Solution Validation
+
+### Does your solution make sense?
+- [ ] Explained it to 5 people and they got it in 30 seconds
+- [ ] At least 3 said "I'd use that"
+- [ ] No one said "that already exists" (or you know why yours is different)
+
+**Evidence:**
+
+### Would they pay?
+- [ ] Asked about willingness to pay
+- [ ] Got specific price points
+- [ ] At least 1 person offered to pre-pay or sign up for beta
+
+**Evidence:**
+
+---
+
+## Competition Check
+
+### Can you win?
+- [ ] Analyzed 3+ competitors
+- [ ] Found clear gaps in existing solutions
+- [ ] Your approach is meaningfully different
+- [ ] You have some unfair advantage
+
+**Evidence:**
+
+---
+
+## Build Check
+
+### Can you actually build this?
+- [ ] Scoped MVP to 2-4 weeks of work
+- [ ] Have the skills (or know who does)
+- [ ] No major technical unknowns
+- [ ] Don't need permission from anyone
+
+**Evidence:**
+
+---
+
+## Founder Fit
+
+### Should YOU build this?
+- [ ] You understand the users personally
+- [ ] You'd use this product yourself
+- [ ] You can reach first 10 users without ads
+- [ ] You're excited to work on this for 2+ years
+
+**Evidence:**
+
+---
+
+## Scoring
+
+| Category | Score (1-5) | Notes |
+|----------|-------------|-------|
+| Problem exists | | |
+| Problem is painful | | |
+| Solution makes sense | | |
+| Would pay | | |
+| Can beat competition | | |
+| Can build it | | |
+| Founder fit | | |
+
+**Total:** /35
+
+### Decision Guide
+- 28-35: Strong signal. Build it.
+- 21-27: Promising. Do more validation.
+- 14-20: Weak. Rethink the idea or pivot.
+- Below 14: Kill it. Move on.
+
+---
+
+## Decision
+
+- [ ] Build MVP
+- [ ] More validation needed on: ___________
+- [ ] Pivot to: ___________
+- [ ] Kill and move on