@c0x12c/spartan-ai-toolkit 1.0.1

package/commands/spartan/pr-ready.md

@@ -0,0 +1,200 @@
+---
+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
+git fetch origin
+
+# See what's new on main
+git log HEAD..origin/main --oneline
+```
+
+If main has new commits:
+```bash
+git rebase origin/main
+```
+
+**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 %}

package/commands/spartan/quickplan.md

@@ -0,0 +1,122 @@
+---
+name: spartan:quickplan
+description: Fast-forward planning — scaffold spec + plan + branch in one shot for tasks too small for full GSD lifecycle but too important to skip planning.
+argument-hint: "[task description]"
+---
+
+# Quick Plan: {{ args[0] }}
+
+You are running a **fast-forward planning session** — inspired by OpenSpec's `/opsx:ff`.
+Goal: go from idea → actionable plan in one pass, without multi-step ceremony.
+
+This command is for tasks that are:
+- Too small for a full GSD milestone (< 1 day of work)
+- Too important to just "vibe code" without a plan
+- Self-contained with clear scope
+
+---
+
+## Step 1: Research (parallel, 2 min)
+
+Run these two investigations simultaneously using subagents:
+
+**Subagent A — Codebase scan:**
+- Find all files relevant to: {{ args[0] }}
+- Identify existing patterns, conventions already in use
+- Note any tests that might be affected
+
+**Subagent B — Impact analysis:**
+- What could break?
+- Any DB migrations needed?
+- API contract changes?
+- Dependencies between services?
+
+---
+
+## Step 2: Generate Spec (inline, no file needed)
+
+Present a concise spec in this format. Keep it under 30 lines:
+
+```markdown
+## Spec: [task name]
+
+**Goal:** [one sentence — what success looks like]
+
+**Scope:**
+- IN: [what will be built]
+- OUT: [what is explicitly NOT in scope]
+
+**Acceptance criteria:**
+1. [testable criterion]
+2. [testable criterion]
+3. [testable criterion]
+
+**Approach:** [2-3 sentences on implementation approach]
+
+**Risks / unknowns:** [any?]
+```
+
+Ask: "Does this spec match your intent? Any changes before we plan?"
+**Auto mode on?** → Skip this question, continue immediately. Show spec but don't wait.
+**Auto mode off (default)?** → Wait for approval. If the user says "yes" / "go" / "lgtm" → continue.
+
+---
+
+## Step 3: Generate Plan (immediately after spec approval)
+
+Break into **max 4 atomic tasks**. Each task must:
+- Be completable in one commit
+- Have a clear verification step
+- Follow TDD (test first)
+
+Format:
+```markdown
+## Plan: [task name]
+Branch: feature/[ticket-or-slug]
+
+### Task 1: [name]
+Files: [exact file paths]
+Test first: [what test to write]
+Implementation: [what to change]
+Commit: feat([scope]): [message]
+Verify: [how to confirm it works]
+
+### Task 2: ...
+```
+
+---
+
+## Step 4: Create branch + first test
+
+```bash
+git checkout -b feature/[slug]
+```
+
+Then immediately write the first failing test for Task 1.
+Do NOT write any production code yet.
+
+Show the red test output, then:
+**Auto mode on?** → Immediately start executing task by task. Don't wait.
+**Auto mode off?** → Say "Plan is ready. Say **'go'** to start executing task by task, or **'adjust'** to modify the plan."
+
+---
+
+## Execution mode (after "go")
+
+Execute each task in sequence:
+1. Write test → confirm it fails (red)
+2. Write minimal implementation → confirm test passes (green)
+3. Refactor if needed
+4. Commit with atomic message
+5. Show summary, move to next task
+
+After all tasks: run full test suite, then say:
+"All tasks complete. Ready for `/spartan:pr-ready` to prep the PR."
+
+## Rules
+
+- Max 4 tasks — if you need more, the scope is too big for quickplan
+- Every task must be one commit
+- Test first (TDD) — write the failing test before the implementation
+- Don't skip the spec approval step unless auto mode is on
+- Keep the spec under 30 lines — if it's longer, use `/spartan:phase` instead

package/commands/spartan/research.md

@@ -0,0 +1,19 @@
+---
+name: spartan:research
+description: Run a deep research session with web search, source checking, and structured report
+argument-hint: "[topic to research]"
+---
+
+# Research: {{ args[0] | default: "your topic" }}
+
+Run a deep research session.
+
+## Steps
+
+1. Use the `deep-research` skill
+2. Use web search to find real data
+3. Cross-check sources
+4. Write a structured report
+5. Save output to the project's `02-research/` folder
+
+If no project folder exists yet, ask which project this is for.

package/commands/spartan/review.md

@@ -0,0 +1,102 @@
+---
+name: spartan:review
+description: Perform a thorough PR review following Spartan Kotlin + Micronaut conventions and company rules
+argument-hint: "[optional: branch name or PR description]"
+---
+
+# Code Review: {{ args[0] | default: "current changes" }}
+
+Perform a comprehensive code review of the current changes. Use the `git diff` tool to inspect
+all modified files. Analyze the changes systematically.
+
+**Before reviewing, reference these company rules:**
+- `rules/backend-micronaut/KOTLIN.md` — Null safety, Either, coroutines
+- `rules/backend-micronaut/CONTROLLERS.md` — Controller → Manager → Service/Repository
+- `rules/backend-micronaut/API_DESIGN.md` — Query params only, RPC-style URLs
+- `rules/database/SCHEMA.md` — No FK, TEXT not VARCHAR, soft deletes
+
+## Review Checklist
+
+### Stage 1: Correctness & Business Logic
+- [ ] Does the implementation match the stated requirements/ticket?
+- [ ] Are all edge cases handled?
+- [ ] Is error handling using `Either<ClientException, T>` (not exceptions)?
+- [ ] Are there any `!!` operators? (BANNED — see CORE_RULES)
+- [ ] Are all coroutine scopes properly managed?
+
+### Stage 2: Kotlin & Micronaut Conventions
+- [ ] Controllers are thin — delegate to Manager immediately
+- [ ] `@ExecuteOn(TaskExecutors.BLOCKING)` on controller methods that call blocking code
+- [ ] `@Secured` annotation present on all controllers
+- [ ] Manager returns `Either<ClientException, T>`, not raw types or exceptions
+- [ ] Query parameters used (no path parameters like `/{id}`)
+- [ ] Null safety: safe call + elvis, no `!!`
+- [ ] Extension functions preferred over utility classes
+
+### Stage 3: Test Coverage
+- [ ] New endpoints have `@MicronautTest` integration tests
+- [ ] Tests follow the pattern from `/testing-strategies` skill
+- [ ] Tests are independent (no test order dependencies)
+- [ ] Edge cases are tested
+- [ ] Test uses proper test data builders
+
+### Stage 4: Clean Code & Architecture
+- [ ] Layered architecture: Controller → Manager → Service/Repository
+- [ ] No business logic in controllers or repositories
+- [ ] Package structure follows controller/manager/service/repository/model
+- [ ] No cyclic dependencies between packages
+- [ ] Functions are small and single-purpose
+
+### Stage 5: Database & API
+- [ ] Migrations use TEXT not VARCHAR (DATABASE_RULES)
+- [ ] No foreign key constraints (DATABASE_RULES)
+- [ ] Soft delete with `deleted_at` (no hard deletes)
+- [ ] Standard columns present: `id`, `created_at`, `updated_at`, `deleted_at`
+- [ ] UUID primary keys
+- [ ] API URLs follow RPC style (API_RULES)
+- [ ] No sensitive data logged
+- [ ] Input validation on all public API endpoints
+
+## Output Format
+
+Provide review results as:
+
+```
+## PR Review Summary
+
+### ✅ Approved / ⚠️ Needs Changes / ❌ Blocked
+
+### Critical Issues (must fix)
+- [issue with file:line reference]
+
+### Suggestions (nice to have)
+- [suggestion]
+
+### Praise (what was done well)
+- [positive note]
+
+### Verdict
+[Final recommendation]
+```
+
+### Stage 6: Documentation Gap Analysis (from pr-reviewer agent)
+After reviewing code, check if any patterns found should be documented:
+- [ ] New architectural pattern used? → Update `rules/shared-backend/ARCHITECTURE.md`
+- [ ] New error handling pattern? → Update `rules/backend-micronaut/KOTLIN.md`
+- [ ] New database pattern? → Update `rules/database/SCHEMA.md`
+- [ ] Recurring PR feedback theme? → Create new rule or update existing
+- [ ] New convention established? → Update CLAUDE.md or `.memory/patterns/`
+
+If documentation updates needed, list them at the end of the review:
+```
+### Documentation Updates Needed
+- [file]: [what to add/update and why]
+```
+
+## Rules
+
+- Always use `git diff` to inspect actual changes — don't guess from filenames
+- Reference the company rules files before checking code
+- Every finding must include file:line reference
+- Separate "must fix" from "nice to have" — don't block PRs on style nits
+- Praise good code — reviews aren't just for finding problems

package/commands/spartan/teardown.md

@@ -0,0 +1,161 @@
+---
+name: spartan:teardown
+description: Deep competitor analysis — pricing, features, strengths, weaknesses, and where they leave gaps
+argument-hint: "[competitor name or URL]"
+---
+
+# Competitor Teardown: {{ args[0] | default: "competitor" }}
+
+You are running a deep competitor analysis. Be brutally honest — don't downplay their strengths or inflate their weaknesses. The goal is to understand them clearly so we can find real gaps.
+
+If the user gives a URL, use web search to find real data about the company. If they give just a name, search for it.
+
+**Use web search** to find pricing pages, G2/Capterra reviews, traffic data, and social media mentions. Real data beats guessing.
+
+---
+
+## Section 1: Overview
+
+Write one paragraph: What do they do? Who do they serve? When were they founded? How big are they?
+
+Keep it factual. No opinions yet.
+
+---
+
+## Section 2: Pricing
+
+| Plan | Price | Key Features |
+|---|---|---|
+| Free / Trial | | |
+| Starter / Basic | | |
+| Pro / Growth | | |
+| Enterprise | | |
+
+Note: Do they have a free tier? Free trial length? Annual vs monthly pricing difference?
+What's the cheapest way to get started?
+
+---
+
+## Section 3: Feature Breakdown
+
+| Feature | Have It? | How Good? (1-5) | Notes |
+|---|---|---|---|
+| [core feature 1] | Yes/No | | |
+| [core feature 2] | Yes/No | | |
+| [core feature 3] | Yes/No | | |
+| ... | | | |
+
+List 10-15 features that matter for this market. Score quality honestly.
+
+---
+
+## Section 4: What They Do Well (Top 3)
+
+List their top 3 strengths. For each one:
+- What is it?
+- Evidence (user reviews, market position, product quality)
+- How hard would it be to match this?
+
+Don't skip this. If they're winning, there's a reason.
+
+---
+
+## Section 5: What They Do Poorly (Top 3)
+
+List their top 3 weaknesses. For each one:
+- What is it?
+- Evidence (user complaints, missing features, bad UX)
+- Is this a real gap or just nitpicking?
+
+Only list real problems. "Their logo is ugly" doesn't count.
+
+---
+
+## Section 6: User Reviews
+
+Search G2, Capterra, Reddit, Twitter/X, Product Hunt for real user feedback.
+
+**What users love:**
+- [quote or paraphrase + source]
+- [quote or paraphrase + source]
+- [quote or paraphrase + source]
+
+**What users hate:**
+- [quote or paraphrase + source]
+- [quote or paraphrase + source]
+- [quote or paraphrase + source]
+
+**Common themes:** What shows up over and over in reviews?
+
+---
+
+## Section 7: Traffic & Traction
+
+| Metric | Value | Source |
+|---|---|---|
+| Monthly visitors (estimate) | | SimilarWeb / search |
+| Growth trend | Growing / Flat / Declining | |
+| Team size (estimate) | | LinkedIn / Crunchbase |
+| Total funding | | Crunchbase |
+| Last funding round | | |
+| Notable customers | | |
+
+If data isn't available, say so. Don't make up numbers.
+
+---
+
+## Section 8: How They Get Users
+
+Check which channels they use:
+
+| Channel | Active? | Evidence |
+|---|---|---|
+| SEO / Content marketing | | Blog posts? Ranking for key terms? |
+| Paid ads (Google/Meta) | | Found ads? Sponsorships? |
+| Social media | | Active accounts? Engagement? |
+| Community / Forums | | Discord? Slack? Reddit presence? |
+| Partnerships / Integrations | | App stores? Partner pages? |
+| Word of mouth / Referrals | | Referral program? Organic mentions? |
+| Product Hunt / Launch sites | | Past launches? |
+
+What's their main growth channel? Where do most users come from?
+
+---
+
+## Section 9: Positioning
+
+- **How they describe themselves:** [their tagline / hero text]
+- **Target persona:** Who are they really building for?
+- **Positioning:** Are they the cheap option? The premium option? The easy option? The powerful option?
+- **Brand voice:** Corporate / Casual / Technical / Friendly?
+
+---
+
+## Section 10: Our Opportunity
+
+This is the "so what?" section. Based on everything above:
+
+**Gaps they leave open:**
+- [gap 1 — who's underserved?]
+- [gap 2 — what feature is missing or weak?]
+- [gap 3 — what segment do they ignore?]
+
+**What we'd do differently:**
+- [difference 1]
+- [difference 2]
+- [difference 3]
+
+---
+
+## So What?
+
+Write one paragraph: What does this teardown mean for our strategy? Where should we compete, and where should we avoid competing?
+
+Be specific. "We should differentiate" is useless. Say HOW and WHERE.
+
+---
+
+**Next steps:**
+- Want to analyze another competitor? Run `/spartan:teardown [name]` again
+- Ready to compare multiple competitors side by side? Ask me to build a comparison matrix
+- Want to validate your positioning? Run `/spartan:validate` with your idea