@c0x12c/ai-toolkit 1.15.0

package/commands/spartan/plan.md

@@ -0,0 +1,210 @@
+---
+name: spartan:plan
+description: Write an implementation plan — reads spec, designs architecture, breaks into tasks, runs Gate 2
+argument-hint: "[feature name]"
+preamble-tier: 3
+---
+
+# Plan: {{ args[0] | default: "unnamed feature" }}
+
+You are running the **Plan workflow** — turn a spec into a concrete implementation plan with architecture, file locations, and ordered tasks.
+
+```
+Epic → Spec → [Design] → ► Plan → Build → Review
+                               ↑
+                             Gate 2
+```
+
+The plan gets saved to `.planning/plans/{{ args[0] | default: "feature-name" }}.md`.
+
+---
+
+## Step 0: Find the Spec
+
+Look for the spec in this order:
+1. `.planning/specs/{{ args[0] | default: "feature-name" }}.md`
+2. If not found, ask: "No spec found for **{{ args[0] }}**. Want to:"
+   - A) Write the spec first → `/spartan:spec {{ args[0] }}`
+   - B) Give me a quick description and I'll plan from that (skip spec)
+
+If spec exists, read it. Confirm:
+> "Found spec: `.planning/specs/{{ args[0] }}.md`. Planning from this."
+
+Also check:
+```bash
+mkdir -p .planning/plans
+ls .planning/plans/{{ args[0] | default: "feature-name" }}.md 2>/dev/null
+```
+
+If a plan already exists, ask:
+> "A plan for **{{ args[0] }}** already exists. Want to **update** it or **start fresh**?"
+
+---
+
+## Step 1: Detect Stack
+
+Same auto-detect as `/spartan:build`:
+```bash
+ls build.gradle.kts settings.gradle.kts 2>/dev/null && echo "STACK:kotlin-micronaut"
+ls package.json 2>/dev/null && cat package.json 2>/dev/null | grep -q '"next"' && echo "STACK:nextjs-react"
+```
+
+| Detected | Mode |
+|----------|------|
+| Kotlin only | Backend plan |
+| Next.js only | Frontend plan |
+| Both | Ask: "Backend, frontend, or full-stack plan?" |
+| Neither | Ask the user |
+
+---
+
+## Step 2: Design Architecture
+
+Based on the spec and detected stack, lay out:
+
+### Components Table
+List every component this feature needs:
+```markdown
+| Component | Type | Purpose |
+|-----------|------|---------|
+| [Name] | [Controller / Manager / Service / Repository / Component / Hook / etc.] | [what it does] |
+```
+
+### File Locations Table
+Where every file goes:
+```markdown
+| File | Location | Purpose |
+|------|----------|---------|
+| [file name] | [directory path] | [what it does] |
+```
+
+### Files to Change
+Existing files that need changes:
+```markdown
+| File | What Changes | Why |
+|------|-------------|-----|
+| [file path] | [description] | [reason] |
+```
+
+**Backend plans** follow: Controller → Manager → Repository (layered architecture).
+**Frontend plans** follow: Types → Components → Pages → State.
+**Full-stack plans** do backend first, then frontend. Mark the integration point.
+
+---
+
+## Step 3: Break into Tasks
+
+Split the work into phases with ordered tasks.
+
+### Phase ordering by stack:
+
+**Backend:** Database → Business Logic → API → Tests
+**Frontend:** Types/Interfaces → Components → Pages/Routes → Tests
+**Full-stack:** Database → API → Types → Components → Integration → Tests
+
+### Task rules:
+- Each task: max 3 files, one commit
+- Each task has: description, files, what to test
+- Group into phases by dependency
+- Mark parallel vs sequential
+
+### Format:
+```markdown
+### Phase 1: [name]
+
+| # | Task | Files |
+|---|------|-------|
+| 1 | [description] | [file(s)] |
+| 2 | [description] | [file(s)] |
+
+### Phase 2: [name] (depends on Phase 1)
+
+| # | Task | Files |
+|---|------|-------|
+| 3 | [description] | [file(s)] |
+```
+
+### Parallel vs Sequential table:
+```markdown
+| Parallel Group | Tasks | Why |
+|---------------|-------|-----|
+| Group A | 1, 2 | independent files |
+
+| Sequential | Depends On | Why |
+|-----------|-----------|-----|
+| Task 3 | Task 1, 2 | needs their output |
+```
+
+---
+
+## Step 4: Testing Plan
+
+Map tests from the spec's testing criteria:
+
+- **Data layer tests** — insert, read, update, soft delete, query filters
+- **Business logic tests** — happy path, error cases, validation
+- **API / integration tests** — endpoints, auth, invalid input
+- **UI tests** (if applicable) — render, interaction, states
+
+Each test ties back to a spec requirement or edge case.
+
+---
+
+## Step 5: Run Gate 2
+
+Before saving, run the Gate 2 checklist from `quality-gates.md`:
+
+**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
+
+If any item fails → fix it before saving.
+
+---
+
+## Step 6: Save and Confirm
+
+Save the plan to `.planning/plans/{{ args[0] | default: "feature-name" }}.md`.
+
+Set the metadata:
+```
+**Spec**: .planning/specs/{{ args[0] }}.md
+**Epic**: [epic name or "none"]
+**Created**: [today's date]
+**Status**: draft
+```
+
+Then tell the user:
+
+> "Plan saved to `.planning/plans/{{ args[0] }}.md` — Gate 2 passed."
+>
+> **Next steps:**
+> - Small feature (1-4 tasks)? → `/spartan:build {{ args[0] }}`
+> - Big feature (5+ tasks)? → `/spartan:phase execute N`
+> - Want a dual-agent review first? → `/spartan:gate-review`
+
+---
+
+## Rules
+
+- **Read the spec first.** Don't invent requirements the spec doesn't have.
+- **Match the codebase.** Check existing patterns before proposing architecture. Run searches to find how similar features are built.
+- **Small tasks.** Each task = one commit, max 3 files, completable in minutes not hours.
+- **Gate 2 is not optional.** Every plan must pass before saving.
+- **Auto mode on?** → Skip confirmations, show the plan and save it directly.
+- **Link back to spec.** Every task should trace to a spec requirement. If a task doesn't come from the spec, question why it's there.

package/commands/spartan/pr-ready.md

@@ -0,0 +1,202 @@
+---
+name: spartan:pr-ready
+description: Full pre-PR workflow — rebase onto main, run all checks (tests, conventions, security), generate PR description, and create the GitHub PR. Run when a feature/fix is complete.
+argument-hint: "[optional: PR title]"
+---
+
+# PR Ready: {{ args[0] | default: "current branch" }}
+
+Full workflow: rebase → checks → push → create PR.
+Fix ALL blockers before proceeding to the next step.
+
+---
+
+## Step 1: Current State
+
+```bash
+git branch --show-current
+git status
+git log main...HEAD --oneline
+git diff main...HEAD --shortstat
+```
+
+If uncommitted changes exist → commit or stash before continuing.
+
+---
+
+## Step 2: Rebase onto Main
+
+```bash
+# Fetch latest and detect default branch
+git fetch origin
+DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
+[ -z "$DEFAULT_BRANCH" ] && DEFAULT_BRANCH=$(git rev-parse --verify origin/master >/dev/null 2>&1 && echo master || echo main)
+
+# See what's new on the default branch
+git log HEAD..origin/$DEFAULT_BRANCH --oneline
+```
+
+If the default branch has new commits:
+```bash
+git rebase origin/$DEFAULT_BRANCH
+```
+
+**Conflict resolution:**
+1. Find conflict markers `<<<<<<<` / `=======` / `>>>>>>>`
+2. Resolve each file — keep the correct version
+3. `git add [file]` → `git rebase --continue`
+4. Repeat until done
+
+Abort if needed: `git rebase --abort`
+
+Verify after rebase:
+```bash
+git log main...HEAD --oneline    # commits look correct?
+git diff main...HEAD --stat      # changes still intact?
+```
+
+---
+
+## Step 3: Tests (hard blocker)
+
+```bash
+# Kotlin BE
+./gradlew clean test
+./gradlew integrationTest 2>/dev/null
+
+# Next.js FE
+npm run test:run 2>/dev/null
+```
+
+**Any failure = stop. Fix tests before continuing.**
+
+---
+
+## Step 4: Code Quality
+
+```bash
+./gradlew ktlintCheck 2>/dev/null
+./gradlew detekt 2>/dev/null
+./gradlew compileKotlin 2>&1 | grep -i "warning"
+```
+
+Check the diff for:
+- [ ] No `!!` operator (null safety violation)
+- [ ] No `println` — use SLF4J
+- [ ] No hardcoded values (URLs, secrets, magic numbers)
+- [ ] No commented-out code
+- [ ] No TODOs without ticket reference
+
+---
+
+## Step 5: Architecture Check
+
+```bash
+# Verify layered architecture (Controller → Manager → Repository)
+# Controllers should only call Managers
+grep -r "Repository\|Service" src/main/kotlin/*/controller/ --include="*.kt" | grep -v "import"
+```
+
+- [ ] Controllers are thin — delegate to Manager only
+- [ ] `@Secured` annotation on all controllers
+- [ ] `@ExecuteOn(TaskExecutors.BLOCKING)` on blocking endpoints
+- [ ] Manager returns `Either<ClientException, T>`, not raw types
+- [ ] No business logic in controllers or repositories
+- [ ] Query parameters only — no path parameters (API_RULES)
+
+---
+
+## Step 6: DB & Security
+
+```bash
+# Migration order correct?
+ls src/main/resources/db/migration/ | sort | tail -5
+./gradlew flywayValidate 2>/dev/null
+
+# Accidental secrets?
+git diff main...HEAD | grep -iE "(password|secret|api_key|token)\s*=" \
+  | grep -v "test\|mock\|example\|placeholder\|your-"
+```
+
+- [ ] Flyway migration version number is next in sequence
+- [ ] Migration is backward-compatible
+- [ ] No secrets committed
+
+---
+
+## Step 7: Generate PR Description
+
+From `git log main...HEAD` and `git diff`, write:
+
+```markdown
+## Summary
+[2-3 sentences: what and why]
+
+## Changes
+- [change 1]
+- [change 2]
+- [change 3]
+
+## Testing
+- [ ] Unit tests added/updated
+- [ ] Integration tests pass
+- [ ] Manual testing: [describe if any]
+
+## DB Changes
+[None / Migration V{N}__desc — backward compatible]
+
+## Breaking Changes
+[None / describe]
+
+## Related
+- Ticket: [if applicable]
+```
+
+---
+
+## Step 8: Push & Create PR
+
+```bash
+# Push (force-with-lease is safe after rebase — won't overwrite others' work)
+git push origin HEAD --force-with-lease
+```
+
+**Create PR with GitHub CLI (if installed):**
+```bash
+gh pr create \
+  --title "{{ args[0] | default: "type(scope): description" }}" \
+  --body "[PR description from Step 7]" \
+  --base main \
+  --draft
+```
+
+Creates as **draft** — review on GitHub, then mark "Ready for review" when satisfied.
+
+**If `gh` not installed:**
+```bash
+# Get remote URL to open in browser
+git remote get-url origin
+```
+Go to GitHub → compare & pull request → paste description from Step 7.
+
+Install `gh` CLI for next time: `brew install gh && gh auth login`
+
+---
+
+## Final Verdict
+
+**✅ PR CREATED** — link above. Review on GitHub and mark ready when satisfied.
+
+**❌ BLOCKERS:**
+```
+[file:line — what to fix]
+```
+Fix → re-run `/spartan:pr-ready`.
+
+---
+
+## Rebase Rules (Spartan Convention)
+
+- Always rebase **feature/fix branches** onto `main` before PR
+- Never rebase `main`, `develop`, or any shared branch
+- `--force-with-lease` instead of `--force` — safer, won't overwrite teammates' pushes

package/commands/spartan/project.md

@@ -0,0 +1,106 @@
+---
+name: spartan:project
+description: Manage large multi-session projects (> 3 days). Handles full lifecycle — create, check status, start new milestones, complete milestones. This is the Spartan wrapper for GSD project commands.
+argument-hint: "[new | status | milestone-new | milestone-complete | milestone-summary | manager]"
+---
+
+# Project Management: {{ args[0] | default: "status" }}
+
+You are managing a large project using the GSD lifecycle under the hood.
+The user does NOT need to know about `/gsd:*` commands — everything runs through `/spartan:*`.
+
+---
+
+## Route by argument
+
+{% if args[0] == "new" %}
+## New Project
+
+Starting a full project lifecycle. This is for work spanning multiple days/weeks.
+
+**Run:** `/gsd:new-project`
+
+Claude will interview the user about:
+- What is the project?
+- Tech stack and constraints?
+- Milestones and goals?
+
+Then generate:
+- `PROJECT.md` — full project brief
+- `ROADMAP.md` — all milestones + phases
+- `.planning/config.json` — GSD settings
+
+After creation, tell the user:
+"Project created. Next step: `/spartan:phase discuss 1` to start Phase 1."
+
+{% elif args[0] == "status" or args[0] == nil %}
+## Project Status
+
+**Run:** `/gsd:status`
+
+Show current state:
+- Which project is active
+- Current milestone and phase
+- What was completed, what's next
+
+Then suggest the next action using `/spartan:` commands:
+- Need to discuss next phase? → "Run `/spartan:phase discuss N`"
+- Need to plan? → "Run `/spartan:phase plan N`"
+- Need to execute? → "Run `/spartan:phase execute N`"
+- Need to verify? → "Run `/spartan:phase verify N`"
+- Milestone done? → "Run `/spartan:project milestone-complete`"
+
+**Never suggest `/gsd:*` commands to the user.** Always translate to `/spartan:*`.
+
+{% elif args[0] == "milestone-new" %}
+## New Milestone
+
+Starting the next milestone on an existing project.
+
+**Run:** `/gsd:new-milestone`
+
+After creation, tell the user:
+"Milestone created. Next step: `/spartan:phase discuss 1` to start Phase 1 of this milestone."
+
+{% elif args[0] == "milestone-complete" %}
+## Complete Milestone
+
+Archiving current milestone and tagging the release.
+
+**Run:** `/gsd:complete-milestone`
+
+After completion, tell the user:
+"Milestone archived and tagged. Next step: `/spartan:project milestone-new` if there's more work, or you're done!"
+
+{% elif args[0] == "milestone-summary" %}
+## Milestone Summary
+
+Generate a comprehensive summary document from completed milestone artifacts. Useful for team onboarding, stakeholder updates, or reviewing what was accomplished.
+
+**Run:** `/gsd:milestone-summary`
+
+After generation, tell the user:
+"Milestone summary generated. Share it with your team for onboarding or review."
+
+{% elif args[0] == "manager" %}
+## Project Manager (Interactive Command Center)
+
+Launch an interactive command center for managing multiple phases from one terminal. Power user tool for overseeing complex projects.
+
+**Run:** `/gsd:manager`
+
+This provides a dashboard view of all phases, their status, and quick actions — all through `/spartan:*` commands.
+
+**Never suggest `/gsd:*` commands to the user.** Always translate to `/spartan:*`.
+
+{% else %}
+## Unknown argument: {{ args[0] }}
+
+Available options:
+- `/spartan:project new` — Start a new multi-day project
+- `/spartan:project status` — Check where you are
+- `/spartan:project milestone-new` — Start next milestone
+- `/spartan:project milestone-complete` — Archive current milestone
+- `/spartan:project milestone-summary` — Generate onboarding doc from milestone
+- `/spartan:project manager` — Interactive command center for power users
+{% endif %}