@c0x12c/ai-toolkit 1.15.0

package/templates/feature-spec.md

@@ -0,0 +1,181 @@
+# Spec: [Feature Name]
+
+> **Workflow position:** Spec defines WHAT to build. After this passes Gate 1, create a **design doc** (if UI feature) or go straight to the **implementation plan** (`implementation-plan.md`).
+>
+> ```
+> Epic → ► Spec → [Design] → Plan → Build → Review
+>              ↑
+>            Gate 1
+> ```
+
+**Created**: [date]
+**Status**: draft | ready | approved
+**Author**: [who wrote this]
+**Epic**: [epic name or "none"]
+
+---
+
+## Problem
+
+What problem are we solving? Why does it matter?
+
+[Describe the problem in 2-3 sentences. Be specific.]
+
+---
+
+## Goal
+
+What does success look like? How do we know we're done?
+
+[Describe the end state. What can users do that they couldn't before?]
+
+---
+
+## User Stories
+
+Who uses this and why?
+
+- As a [role], I want to [action] so that [benefit]
+- As a [role], I want to [action] so that [benefit]
+
+---
+
+## Requirements
+
+### Must Have
+- [requirement 1]
+- [requirement 2]
+
+### Nice to Have
+- [requirement]
+
+### Out of Scope
+- [what we're NOT building]
+- [what we're NOT changing]
+
+---
+
+## Data Model
+
+What data do we need? New tables? Changes to existing tables?
+
+*Skip this section if the feature doesn't touch the database.*
+
+### New Tables
+
+| Table | Purpose |
+|-------|---------|
+| [table_name] | [what it stores] |
+
+### Table Schema
+
+```sql
+CREATE TABLE [table_name] (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  -- columns here
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  deleted_at TIMESTAMP
+);
+```
+
+### Changes to Existing Tables
+
+| Table | Change | Why |
+|-------|--------|-----|
+| [table] | [add/modify/remove column] | [reason] |
+
+---
+
+## API Changes
+
+What endpoints are needed?
+
+*Skip this section if the feature doesn't add or change APIs.*
+
+### New Endpoints
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| GET | /api/v1/[path] | [what it does] |
+| POST | /api/v1/[path] | [what it does] |
+
+### Request/Response Examples
+
+```json
+// GET /api/v1/[path]?param=value
+// Response:
+{
+  "field_name": "value",
+  "created_at": "2025-01-01T00:00:00Z"
+}
+```
+
+### Changes to Existing Endpoints
+
+| Endpoint | Change | Why |
+|----------|--------|-----|
+| [endpoint] | [what changes] | [reason] |
+
+---
+
+## UI Changes
+
+What screens or components are affected?
+
+*Skip this section if the feature is backend-only. For detailed UI work, create a design doc (`design-doc.md`) after this spec passes Gate 1.*
+
+- [screen/component 1]: [what changes]
+- [screen/component 2]: [what changes]
+
+---
+
+## Edge Cases
+
+What could go wrong? What are the weird scenarios?
+
+- [edge case 1]: [how to handle it]
+- [edge case 2]: [how to handle it]
+- [edge case 3]: [how to handle it]
+
+---
+
+## Testing Criteria
+
+How do we know this works?
+
+### Happy Path Tests
+- [test 1]
+- [test 2]
+
+### Edge Case Tests
+- [test 1]
+- [test 2]
+
+### Integration Tests
+- [test 1]
+
+---
+
+## Dependencies
+
+What does this need to work?
+
+- [dependency 1]: [why]
+- [dependency 2]: [why]
+
+---
+
+## Notes
+
+- [note]
+
+---
+
+## Tips
+
+- **Be specific** — "fast" is vague, "under 200ms" is specific
+- **List what's out of scope** — prevents scope creep
+- **Include edge cases** — think about nulls, empty lists, concurrent access
+- **Match existing patterns** — check how similar features are built in the codebase
+- **Spec defines the contract** — data model and API shapes go here. Architecture and file structure go in the plan.

package/templates/idea-canvas.md

@@ -0,0 +1,47 @@
+# Idea Canvas: [Name]
+
+**Date:** YYYY-MM-DD
+
+## The Problem
+> What's broken? What sucks? What takes too long?
+
+## Who Has This Problem?
+> Be specific. "Everyone" is not an answer.
+
+## How Do They Solve It Now?
+> What workarounds exist? What competitors are there?
+
+## Your Solution (30 seconds)
+> Explain it like you're texting a friend.
+
+## Why You?
+> What do you know that others don't? Any unfair advantages?
+
+## How Big Is This?
+- How many people have this problem?
+- How often do they have it?
+- How much would they pay to fix it?
+
+## Risks
+> What could kill this idea?
+
+1.
+2.
+3.
+
+## First Experiment
+> What's the cheapest way to test if this works?
+
+## Gut Check
+- [ ] I've seen this problem myself
+- [ ] I know at least 3 people with this problem
+- [ ] They've tried to solve it before
+- [ ] I could build v1 in 2 weeks
+- [ ] I'd use this product myself
+
+**Score:** _/5 boxes checked
+
+## Decision
+- [ ] Worth exploring
+- [ ] Kill it
+- [ ] Need more info on: ___________

package/templates/implementation-plan.md

@@ -0,0 +1,159 @@
+# Plan: [Feature Name]
+
+> **Workflow position:** Plan defines HOW to build it. It turns the spec into tasks with clear architecture, file locations, and dependencies. After this passes Gate 2, start building.
+>
+> ```
+> Epic → Spec → [Design] → ► Plan → Build → Review
+>                                ↑
+>                              Gate 2
+> ```
+
+**Spec**: [path to spec file]
+**Epic**: [epic name or "none"]
+**Created**: [date]
+**Status**: draft | ready | approved
+
+---
+
+## Architecture
+
+How does this fit into the existing system?
+
+### Components
+
+List the main components this feature needs. Adapt to your stack.
+
+| Component | Type | Purpose |
+|-----------|------|---------|
+| [Name] | [Controller / Service / Repository / Component / Hook / etc.] | [what it does] |
+| [Name] | [Controller / Service / Repository / Component / Hook / etc.] | [what it does] |
+| [Name] | [Controller / Service / Repository / Component / Hook / etc.] | [what it does] |
+
+### Where Things Go
+
+| File | Location | Purpose |
+|------|----------|---------|
+| [file name] | [directory path] | [what it does] |
+| [file name] | [directory path] | [what it does] |
+
+---
+
+## Files to Change
+
+Existing files that need changes:
+
+| File | What Changes | Why |
+|------|-------------|-----|
+| [file path] | [description] | [reason] |
+
+---
+
+## New Files
+
+Files to create:
+
+| File | Purpose |
+|------|---------|
+| [file path] | [what it does] |
+
+---
+
+## Task Breakdown
+
+Ordered list of tasks. Each task should be small enough for one person or agent to do.
+
+Organize into phases that make sense for your stack. Some examples:
+
+**Backend features:** Database → Business Logic → API → Tests
+**Frontend features:** Components → Pages/Routes → State/Data → Tests
+**Full-stack features:** Database → API → Components → Integration → Tests
+
+### Phase 1: [name]
+
+| # | Task | Files |
+|---|------|-------|
+| 1 | [task description] | [file(s)] |
+| 2 | [task description] | [file(s)] |
+
+### Phase 2: [name]
+
+| # | Task | Files |
+|---|------|-------|
+| 3 | [task description] | [file(s)] |
+| 4 | [task description] | [file(s)] |
+
+### Phase 3: [name]
+
+| # | Task | Files |
+|---|------|-------|
+| 5 | [task description] | [file(s)] |
+| 6 | [task description] | [file(s)] |
+
+---
+
+## Parallel vs Sequential
+
+Which tasks can run at the same time?
+
+| Parallel Group | Tasks | Why |
+|---------------|-------|-----|
+| Group A | [tasks] | [they don't depend on each other] |
+| Group B | [tasks] | [they don't depend on each other] |
+
+| Sequential | Depends On | Why |
+|-----------|-----------|-----|
+| Task [N] | Task [M] | [reason] |
+
+---
+
+## Risk Areas
+
+What's tricky? What could break?
+
+- [risk 1]: [how to handle]
+- [risk 2]: [how to handle]
+
+---
+
+## Testing Plan
+
+Adapt these categories to your stack:
+
+### Data Layer Tests
+- Insert + read back
+- Update fields
+- Delete behavior
+- Query filters
+
+### Business Logic Tests
+- Happy path for each method
+- Error cases (not found, validation failures)
+
+### API / Integration Tests
+- Each endpoint or route works correctly
+- Auth/permission checks
+- Invalid input returns proper errors
+
+### UI Tests (if applicable)
+- Component renders correctly
+- User interactions work
+- Loading/error/empty states
+
+---
+
+## Checklist Before Starting
+
+- [ ] Read the spec
+- [ ] Read project coding rules
+- [ ] Check existing codebase for similar patterns
+- [ ] Understand the data model
+
+---
+
+## Tips
+
+- **Small tasks** — each task should take minutes, not hours
+- **Clear dependencies** — know what has to finish before what
+- **List ALL files** — don't leave anyone guessing where things go
+- **Match architecture** — follow the project's existing patterns
+- **Plan defines HOW** — architecture, files, and task order go here. WHAT to build is in the spec.

package/templates/prd-template.md

@@ -0,0 +1,86 @@
+# PRD: [Feature/Product Name]
+
+> **When to use this:** PRDs are for stakeholder alignment — "should we build this?" They're high-level and non-technical. For the development workflow (epic → spec → plan → build), use `epic.md` and `feature-spec.md` instead. A PRD can feed into an epic, but they serve different audiences.
+
+**Author:**
+**Date:**
+**Status:** Draft / Review / Approved
+
+---
+
+## TL;DR
+What are we building and why? (2-3 sentences max)
+
+## Problem
+What problem does this solve? Include evidence from user research.
+
+## Goals
+What does success look like?
+
+| Goal | Metric | Target |
+|------|--------|--------|
+| | | |
+| | | |
+
+## Non-Goals
+What are we NOT doing?
+
+-
+
+## User Stories
+| As a... | I want to... | So that... |
+|---------|--------------|------------|
+| | | |
+| | | |
+
+## Solution
+
+### Overview
+How does it work? (simple explanation)
+
+### User Flow
+1. User does X
+2. System shows Y
+3. User clicks Z
+4. ...
+
+### Wireframes
+(Link to designs or paste images)
+
+## Technical Notes
+Anything the dev team needs to know?
+
+## Open Questions
+| Question | Answer | Owner |
+|----------|--------|-------|
+| | | |
+
+## Scope
+
+### MVP (Must Have)
+-
+
+### Nice to Have
+-
+
+### Future
+-
+
+## Timeline
+| Milestone | Target Date |
+|-----------|-------------|
+| Design complete | |
+| Dev complete | |
+| Launch | |
+
+## Risks
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| | | | |
+
+## Success Criteria
+How do we know this worked?
+
+1.
+2.
+3.

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.

package/templates/project-readme.md

@@ -0,0 +1,35 @@
+# [Project Name]
+
+## One-liner
+What is this in one sentence?
+
+## Problem
+What problem are you solving? Who has this problem?
+
+## Solution
+How does your product solve it?
+
+## Status
+- [ ] Brainstorming
+- [ ] Research
+- [ ] Validation
+- [ ] Building
+
+## Key Links
+- [Idea Canvas](./01-brainstorm/idea-canvas.md)
+- [Competitor Research](./02-research/)
+- [User Interviews](./03-validation/)
+- [PRD](./04-build/)
+
+## Quick Stats
+| Metric | Value |
+|--------|-------|
+| Target users | ? |
+| Competitors found | ? |
+| Interviews done | ? |
+| Validation score | ?/10 |
+
+## Next Steps
+1. ...
+2. ...
+3. ...