@c0x12c/spartan-ai-toolkit 1.0.1

package/commands/spartan/brownfield.md

@@ -0,0 +1,157 @@
+---
+name: spartan:brownfield
+description: Analyze an existing codebase and generate a structured context map + onboarding spec before making any changes. Use when joining a legacy project or unfamiliar service.
+argument-hint: "[service name or directory] [optional: area of focus]"
+---
+
+# Brownfield Onboarding: {{ args[0] }}
+Focus area: {{ args[1] | default: "full codebase" }}
+
+You are performing a **brownfield analysis** — mapping an existing codebase before touching it.
+This prevents the most common AI coding mistake: making changes without understanding the terrain.
+
+Inspired by OpenSpec's change-isolation philosophy: understand first, change second.
+
+---
+
+## Phase 1: Structure Mapping (automated)
+
+Run these commands to get a high-level picture:
+
+```bash
+# Project structure
+find . -type f -name "*.kt" | head -60
+find . -type f -name "*.gradle.kts" | head -10
+
+# Dependencies
+cat build.gradle.kts 2>/dev/null || cat pom.xml 2>/dev/null
+
+# Database migrations (Flyway)
+ls src/main/resources/db/migration/ 2>/dev/null | sort
+
+# Test coverage picture
+find . -path "*/test/*" -name "*.kt" | wc -l
+find . -path "*/main/*" -name "*.kt" | wc -l
+
+# Recent git activity
+git log --oneline -20
+git log --oneline --since="30 days ago" | wc -l
+```
+
+---
+
+## Phase 2: Architecture Analysis
+
+Read and analyze these files (if they exist):
+- `README.md` / `docs/`
+- `CLAUDE.md` / `AGENTS.md`
+- `src/main/resources/application.yml`
+- Main `@MicronautApplication or Application.kt` class
+- Domain model files in `domain/model/`
+
+Then answer:
+1. **What does this service do?** (1-2 sentences)
+2. **What are the main domain entities?**
+3. **What external systems does it talk to?** (DB, Kafka, Redis, HTTP)
+4. **What are the main entry points?** (controllers, consumers)
+5. **What tech debt is visible?** (TODO comments, deprecated APIs, inconsistent patterns)
+
+---
+
+## Phase 3: Hotspot Detection
+
+```bash
+# Most-changed files (potential complexity hotspots)
+git log --format=format: --name-only | grep "\.kt$" | sort | uniq -c | sort -rn | head -15
+
+# Largest files (potential god classes)
+find . -name "*.kt" -exec wc -l {} \; | sort -rn | head -10
+
+# TODO/FIXME density
+grep -r "TODO\|FIXME\|HACK\|XXX" --include="*.kt" | wc -l
+grep -r "TODO\|FIXME\|HACK\|XXX" --include="*.kt" | head -10
+```
+
+---
+
+## Phase 4: Test Health Check
+
+```bash
+# Test types present
+find . -name "*Test*.kt" -o -name "*Spec*.kt" | head -20
+
+# Integration tests (Testcontainers)
+grep -r "Testcontainers\|@Container" --include="*.kt" -l
+
+# Test coverage (if JaCoCo configured)
+cat build.gradle.kts | grep -A5 "jacoco"
+```
+
+Assess:
+- Unit test coverage (estimate from file count ratio)
+- Integration test presence
+- Any tests using mocks where Testcontainers would be better
+
+---
+
+## Phase 5: Generate Context Map
+
+Save output as `docs/CONTEXT-MAP.md`:
+
+```markdown
+# Context Map: [service name]
+Generated: [date]
+
+## Service Purpose
+[1-2 sentences]
+
+## Architecture
+- Pattern: [layered / hexagonal / other]
+- Main layers: [list]
+- External dependencies: [list with protocols]
+
+## Domain Model
+[key entities and their relationships]
+
+## Entry Points
+[controllers + endpoints, consumers + topics]
+
+## Known Tech Debt
+[ordered by severity]
+
+## Test Health
+- Unit tests: [count / assessment]
+- Integration tests: [count / assessment]
+- Coverage gaps: [where tests are missing]
+
+## Safe Change Zones
+[areas that are well-tested and safe to modify]
+
+## Danger Zones  
+[areas that are fragile, under-tested, or have unclear behavior]
+
+## Recommended First Steps
+1. [what to do before making any changes]
+2. [what tests to add first]
+3. [what to refactor before building new features]
+```
+
+---
+
+## Phase 6: Change Isolation Setup
+
+For each planned change to this codebase, create a folder:
+```
+.changes/
+  [YYYY-MM-DD]-[change-name]/
+    PROPOSAL.md    ← what you want to change and why
+    DESIGN.md      ← how you'll change it
+    TASKS.md       ← atomic steps (max 4)
+    RISKS.md       ← what could break
+```
+
+This prevents scope creep and keeps each change independently reviewable.
+
+After analysis, present the Context Map summary and ask:
+"Analysis complete. What change would you like to make first?
+I'll create a change folder and use `/spartan:quickplan` for it."

package/commands/spartan/careful.md

@@ -0,0 +1,94 @@
+---
+name: spartan:careful
+description: Activate destructive operation warnings. Claude will detect and require explicit confirmation before running dangerous commands like rm -rf, DROP TABLE, force-push, git reset --hard, overwriting migrations, or deleting production resources.
+---
+
+# Careful Mode — ACTIVATED
+
+You are now in **careful mode**. Before executing any destructive operation, you MUST:
+1. Print a clear warning
+2. Explain what will be destroyed/changed irreversibly
+3. Wait for explicit confirmation ("I confirm" or "proceed anyway")
+
+**Never skip this — not even in auto mode.**
+
+---
+
+## Destructive Operations Watchlist
+
+Detect and block these patterns. This list is not exhaustive — use judgment for anything that smells destructive.
+
+### Filesystem
+- `rm -rf` / `rm -r` on any directory
+- Overwriting files without backup (especially config, migrations, `.env`)
+- `chmod 777` or `chown` on sensitive paths
+- Truncating or overwriting log files
+
+### Git
+- `git push --force` or `git push -f` (use `--force-with-lease` instead, still warn)
+- `git reset --hard`
+- `git clean -fd`
+- `git branch -D` (force delete branch)
+- `git rebase` on shared branches (main, develop)
+- Amending commits already pushed to remote
+
+### Database
+- `DROP TABLE` / `DROP DATABASE` / `DROP SCHEMA`
+- `TRUNCATE TABLE`
+- `DELETE FROM` without `WHERE` clause
+- `ALTER TABLE ... DROP COLUMN`
+- Overwriting or renaming existing Flyway migrations (breaks checksum)
+- Running migrations on production database
+
+### Infrastructure
+- `terraform destroy`
+- `terraform apply` without prior `terraform plan` review
+- `docker system prune`
+- `railway delete` / removing Railway services
+- Modifying production env vars (DATASOURCES_DEFAULT_*, secrets)
+- Scaling down to 0 replicas
+
+### Application
+- Changing API endpoints that other services depend on (breaking changes)
+- Removing Kafka topics or consumer groups
+- Invalidating all user sessions / tokens
+
+---
+
+## Warning Format
+
+When a destructive operation is detected, print:
+
+```
+⚠️  DESTRUCTIVE OPERATION DETECTED
+
+Action:    [what will happen]
+Impact:    [what will be destroyed/changed irreversibly]
+Recovery:  [how to undo, or "NOT RECOVERABLE"]
+
+Alternatives:
+  - [safer approach if one exists]
+
+Type "I confirm" or "proceed anyway" to execute.
+Type "cancel" or "no" to abort.
+```
+
+---
+
+## Behavior Rules
+
+1. **Always warn, even if user explicitly asked for the destructive action.** They may not realize the full impact.
+2. **Suggest safer alternatives when possible.** E.g., `--force-with-lease` instead of `--force`, soft delete instead of DROP, backup before overwrite.
+3. **In auto mode, careful mode OVERRIDES auto mode.** Destructive actions always require confirmation.
+4. **Chain detection:** If a script contains multiple destructive operations, warn about ALL of them upfront, not one at a time.
+5. **Stay active until `/spartan:careful off` or session ends.** This is sticky — once activated, it stays on.
+
+---
+
+## Quick Toggle
+
+- `/spartan:careful` — activate (this command)
+- `/spartan:careful off` — deactivate (say: "Careful mode OFF. Destructive operations will execute without extra confirmation.")
+
+Claude should acknowledge activation:
+"🛡️ Careful mode ON — tôi sẽ cảnh báo trước mọi thao tác destructive. Nói 'careful off' để tắt."

package/commands/spartan/content.md

@@ -0,0 +1,17 @@
+---
+name: spartan:content
+description: Turn research or ideas into platform-native content — blog posts, tweets, LinkedIn, newsletters
+argument-hint: "[source material and target platform]"
+---
+
+# Content: {{ args[0] | default: "from existing research" }}
+
+Create platform-native content from existing work.
+
+## Steps
+
+1. Use the `content-engine` skill
+2. Find the source material (research report, idea, validation, etc.)
+3. Ask: What platform? What audience? What goal?
+4. Create platform-specific drafts
+5. No copy-paste between platforms — each platform gets native format

package/commands/spartan/context-save.md

@@ -0,0 +1,161 @@
+---
+name: spartan:context-save
+description: Manage context window — first tries /compact to free space, then saves full handoff if needed. Auto-triggered when Claude detects context pressure, or run manually anytime.
+---
+
+# Context Save — Smart Context Management
+
+## Step 0: Triage — Compact or Full Save?
+
+Assess the situation before doing a full handoff:
+
+**Option A: Compact (stay in same session)**
+If the session has useful remaining capacity and user wants to keep working:
+1. Summarize the conversation so far into key decisions + current state
+2. Run `/compact` to free context space
+3. Continue working in the same session
+
+Use compact when: mid-task, still productive, just need to free space.
+
+**Option B: Full Save (end session, resume in new one)**
+If the session is too deep to recover, or user is done for now:
+1. Save everything to `.handoff/` file
+2. Update `.memory/` with new knowledge
+3. User starts fresh session and reads the handoff file
+
+Use full save when: session > 60%, quality visibly degrading, end of work day, switching to different task.
+
+**Auto-triggered?** When Claude detects its own context pressure (forgetting earlier context, slow responses, repeating itself), it should:
+1. First try compact (Option A)
+2. If already compacted once this session → go to full save (Option B)
+3. Tell the user what's happening: "Context getting heavy — compacting to stay productive."
+
+---
+
+## Full Save Process (Option B)
+
+## Step 1: Capture Current State
+
+Answer these by reviewing the conversation and codebase:
+
+**1. What was being worked on?**
+(Feature name, ticket, GSD phase, etc.)
+
+**2. What was completed in this session?**
+(List commits made, tasks finished)
+
+**3. What is the current status?**
+(In-progress task, where exactly we stopped)
+
+**4. What are the immediate next steps?**
+(Exactly what to do next — be specific enough that a fresh agent can start without asking)
+
+**5. What context is critical to carry forward?**
+(Key decisions made, tradeoffs chosen, things tried that didn't work)
+
+**6. What are the known risks / things to watch out for?**
+
+---
+
+## Step 2: Check Git State
+
+```bash
+# Uncommitted changes?
+git status
+git diff --stat
+
+# Last commits this session
+git log --oneline -5
+
+# Current branch
+git branch --show-current
+```
+
+If there are uncommitted changes:
+- Stash them: `git stash save "wip: [description]"`
+- Or commit as WIP: `git commit -m "chore: wip - [what's in progress]"`
+
+---
+
+## Step 3: Write Handoff File
+
+Save as `.handoff/[YYYY-MM-DD-HH]-[feature-slug].md`:
+
+```markdown
+# Session Handoff: [feature/task name]
+Created: [timestamp]
+Branch: [current branch]
+Author: [git user.name]
+
+## What We Were Building
+[1-2 sentences on the feature/task]
+
+## Session Progress
+### Completed ✅
+- [task 1 — commit hash if available]
+- [task 2]
+
+### In Progress 🔨
+- [exactly what was being done when session ended]
+- Current file being edited: [path]
+- Stopped at: [line/function/what was next]
+
+## Resume Instructions
+To pick up immediately:
+1. `git checkout [branch]`
+2. [specific command or action to run first]
+3. [next step]
+4. Goal: [what "done" looks like for the next session]
+
+## Key Decisions Made This Session
+- [decision 1 and why]
+- [decision 2 and why]
+
+## Things Tried That Didn't Work
+- [approach X] — didn't work because [reason], don't try again
+- [approach Y] — causes [problem]
+
+## Critical Context
+[Any important information that isn't obvious from the code:
+- Business rules that affected implementation
+- Gotchas discovered
+- Dependencies or constraints to be aware of]
+
+## Blockers / Risks
+- [any outstanding questions or blockers]
+
+## GSD State (if using GSD)
+- Project: [PROJECT.md location]
+- Milestone: [current milestone]
+- Phase: [current phase N of M]
+- Resume with: `/gsd:status` then `/gsd:execute-phase [N]`
+
+## Files Modified This Session
+[list of key files changed]
+
+## Tests Status
+- All tests passing: [yes/no]
+- Tests added: [list]
+- Known failing tests: [list if any, why]
+```
+
+---
+
+## Step 4: Verify Handoff is Complete
+
+Read back the handoff file you just wrote and confirm:
+- [ ] Someone could resume without asking any questions
+- [ ] The "Resume Instructions" are specific enough to act on immediately
+- [ ] Git state is clean (committed or stashed)
+- [ ] No context is locked in this conversation that isn't in the file
+
+---
+
+## How to Resume in Next Session
+
+Start the new session with:
+```
+Read .handoff/[filename].md and resume where we left off.
+```
+
+The fresh Claude session will have full 200k context and all the state from this file.

package/commands/spartan/daily.md

@@ -0,0 +1,42 @@
+---
+name: spartan:daily
+description: Generate a daily standup summary based on recent git history and GSD status
+---
+
+Generate a daily engineering standup summary for the current project.
+
+## Steps
+
+1. **Check recent git history** (last 24-48h):
+   ```bash
+   git log --since="2 days ago" --oneline --author="$(git config user.name)"
+   ```
+
+2. **Check GSD status** (if GSD project exists):
+   Read `.planning/` directory for current milestone and phase status.
+
+3. **Check for any failing tests or CI notes** (if available):
+   Look for recent test output files or CI logs.
+
+## Output Format
+
+```markdown
+## Daily Standup — [DATE]
+
+### ✅ Yesterday / Done
+- [completed items from git log / GSD progress]
+
+### 🔨 Today / In Progress
+- [current phase or active task]
+- [next planned task]
+
+### 🚧 Blockers
+- [any blockers found, or "None"]
+
+### 📊 Progress on Current Milestone
+- Phase X of Y complete
+- Est. completion: [if determinable from roadmap]
+```
+
+Keep it concise — each section max 3-4 bullet points.
+This is for a 15-minute standup, not a status report.

package/commands/spartan/debug.md

@@ -0,0 +1,156 @@
+---
+name: spartan:debug
+description: Structured root-cause debugging using a 4-phase investigation protocol. Produces a Debug Report with fix plan. Use for bugs that aren't immediately obvious.
+argument-hint: "[describe the symptom / error]"
+---
+
+# Debug Investigation: {{ args[0] }}
+
+You are running a **structured debugging session**.
+Do NOT guess. Do NOT try random fixes. Follow the 4 phases in order.
+
+---
+
+## Phase 1: Reproduce & Characterize (understand before touching anything)
+
+**Goal:** Make the failure deterministic and fully described.
+
+1. Get the exact error message, stack trace, or symptom
+2. Find the minimal reproduction case:
+   - What inputs trigger it?
+   - What inputs do NOT trigger it?
+   - Is it consistent or flaky?
+   - Environment-specific? (local / CI / prod)
+
+3. Gather context:
+```bash
+# Recent changes that could have introduced this
+git log --oneline -10
+git diff HEAD~5 --stat
+
+# Are tests failing?
+./gradlew test --info 2>&1 | tail -40
+
+# Logs around the failure time
+# (ask user for relevant log snippets if not in repo)
+```
+
+Document findings. Do NOT proceed until the bug is reproducible.
+
+---
+
+## Phase 2: Isolate the Root Cause (narrow the search space)
+
+**Goal:** Find the exact line / decision / data that causes the failure.
+
+Use binary isolation:
+1. Start from the failure point, trace backwards through the call stack
+2. At each layer, ask: "Is the data correct at this point?"
+3. Keep narrowing until you find where correct data becomes incorrect data
+
+For common Kotlin/Micronaut patterns, check:
+- **Null safety violations**: Any `!!` operators? (BANNED — see CORE_RULES)
+- **Either handling**: Is `.left()` / `.right()` used correctly? Missing error cases?
+- **Coroutine scope leaks**: Is a coroutine cancelled before work completes?
+- **Exposed transaction scope**: Is `newSuspendedTransaction {}` wrapping DB calls correctly?
+- **Soft delete filtering**: Is `deleted_at IS NULL` included in queries? (DATABASE_RULES)
+- **Testcontainers state**: Is a previous test leaving dirty data?
+
+```kotlin
+// Add strategic logging to narrow the search
+log.debug("State at boundary: entity={}, dto={}", entity, dto)
+```
+
+Document: "The root cause is [X] because [evidence]."
+
+---
+
+## Phase 3: Fix with Test First (TDD the fix)
+
+**Goal:** Fix correctly and ensure it cannot regress.
+
+1. **Write a failing test that captures the bug FIRST:**
+```kotlin
+@Test
+fun `given [condition that triggers bug], when [action], then [correct behavior]`() {
+    // Reproduce the exact scenario that fails
+    // This test must FAIL right now
+}
+```
+
+2. **Confirm test is red** — if it passes, you haven't reproduced the bug in the test
+
+3. **Write the minimal fix** — change as little as possible
+
+4. **Confirm test is green**
+
+5. **Check for similar patterns** in the codebase:
+```bash
+# Find similar code that might have the same bug
+grep -r "[pattern from the bug]" --include="*.kt" src/
+```
+
+---
+
+## Phase 4: Verify & Harden
+
+**Goal:** Confirm fix is complete and add protection layers.
+
+```bash
+# Full test suite must pass
+./gradlew test
+
+# Integration tests specifically
+./gradlew integrationTest 2>/dev/null || ./gradlew test -Dmicronaut.environments=test
+```
+
+Check:
+- [ ] Fix addresses root cause, not symptom
+- [ ] No regression in existing tests
+- [ ] Edge cases covered in new test
+- [ ] Similar patterns in codebase checked and fixed if needed
+- [ ] Logging/observability added if this was hard to debug
+
+---
+
+## Output: Debug Report
+
+After completing all phases, produce a brief report:
+
+```markdown
+## Debug Report: [symptom]
+
+**Root Cause:** [exact cause in one sentence]
+
+**Why it happened:**
+[2-3 sentences explaining the chain of events]
+
+**Fix:**
+[what was changed and why it fixes the root cause]
+
+**Test added:**
+[name of the regression test]
+
+**Similar patterns checked:**
+[files checked / changes made]
+
+**Prevention:**
+[what could prevent this class of bug in future — linting rule, convention, etc.]
+```
+
+Commit with:
+```
+fix([scope]): [root cause description]
+
+- Root cause: [one line]
+- Add regression test: [test name]
+- Checked [N] similar patterns
+```
+
+## Rules
+
+- Follow the 4 phases in order — don't skip to fixing
+- Never guess — every hypothesis must have evidence
+- Write a failing test before writing the fix
+- Change as little as possible — minimal fix, not refactor
+- Check for similar patterns in the codebase after fixing

package/commands/spartan/deep-dive.md

@@ -0,0 +1,55 @@
+---
+name: spartan:deep-dive
+description: "Go deep on a validated idea: market research + competitor teardowns (Stage 3)"
+argument-hint: "[project name or idea]"
+---
+
+# Deep Dive: {{ args[0] | default: "your idea" }}
+
+Runs Stage 3: deep market research and competitor teardowns.
+Only do this AFTER validation says GO or TEST MORE.
+
+## Steps
+
+### Check Prior Work
+1. Find the project folder in `projects/`
+2. Read everything in `01-brainstorm/` and `03-validation/`
+3. Pull out: the idea, target user, competitors found, market signals
+
+### Market Research
+4. Use the `market-research` skill
+5. Run market sizing (TAM/SAM/SOM with math shown)
+6. Find industry data, reports, trends
+7. Check demand signals: search volume, forum posts, review complaints
+8. Look for tailwinds (new regulation, tech shift, behavior change)
+9. Save to `02-research/market-research-{date}.md`
+
+### Competitor Teardowns
+10. Use the `competitive-teardown` skill
+11. Identify top 3-5 competitors from validation step
+12. For each competitor:
+    - Product teardown (what they do, pricing, strengths, weaknesses)
+    - Business teardown (funding, team, traction)
+    - User feedback (reviews, Reddit, forums)
+13. Save each to `02-research/teardown-{competitor}-{date}.md`
+
+### Synthesis
+14. Create a summary that connects everything:
+    - Market size and growth
+    - Competitor landscape (table comparison)
+    - The gap: what nobody does well
+    - Our positioning: where we win
+    - Biggest risks
+15. Save to `02-research/synthesis-{date}.md`
+
+### Gate 3 Check
+16. Show findings to user
+17. If strong signals: "This looks worth building. Want me to run /spartan:fundraise?"
+18. If weak signals: "Here's what's concerning: [X]. Still want to go forward?"
+19. If dead: "I'd archive this. Here's why: [X]"
+
+## Rules
+
+- Read ALL prior work before starting. Don't re-research what we already know.
+- If validation was TEST MORE, ask what test the user ran and what happened.
+- Be honest if the data kills the idea. Better now than after building.