@c0x12c/spartan-ai-toolkit 1.0.1

package/commands/spartan/testcontainer.md

@@ -0,0 +1,97 @@
+---
+name: spartan:testcontainer
+description: Set up integration testing infrastructure for a Kotlin Micronaut service using @MicronautTest and Testcontainers
+argument-hint: "[postgres | kafka | redis | all]"
+---
+
+Set up integration testing in this Kotlin Micronaut project.
+
+**Reference:** `/testing-strategies` skill and `rules/project/API_RULES.md` (testing section)
+
+## Requested containers: {{ args[0] | default: "postgres" }}
+
+### 1. Add Dependencies (build.gradle.kts)
+
+```kotlin
+testImplementation("org.testcontainers:testcontainers:1.19.3")
+testImplementation("org.testcontainers:junit-jupiter:1.19.3")
+testImplementation("org.testcontainers:postgresql:1.19.3")
+testImplementation("io.micronaut.test:micronaut-test-junit5")
+```
+
+### 2. Create Base Test Configuration
+
+Create `src/test/kotlin/.../AbstractControllerTest.kt`:
+
+```kotlin
+@MicronautTest(environments = ["test"], transactional = false)
+@TestInstance(TestInstance.Lifecycle.PER_CLASS)
+abstract class AbstractControllerTest {
+
+    @Inject
+    lateinit var embeddedServer: EmbeddedServer
+
+    @BeforeAll
+    open fun beforeAll() {
+        // Setup test clients from embeddedServer.url
+    }
+
+    companion object {
+        @Container
+        @JvmStatic
+        val postgres = PostgreSQLContainer("postgres:16-alpine")
+            .withDatabaseName("testdb")
+            .withUsername("test")
+            .withPassword("test")
+
+        @DynamicPropertySource
+        @JvmStatic
+        fun overrideProperties(registry: DynamicPropertyRegistry) {
+            registry.add("datasources.default.url", postgres::getJdbcUrl)
+            registry.add("datasources.default.username", postgres::getUsername)
+            registry.add("datasources.default.password", postgres::getPassword)
+        }
+    }
+}
+```
+
+### 3. Create Example Integration Test
+
+```kotlin
+class EmployeeControllerTest : AbstractControllerTest() {
+
+    private lateinit var employeeClient: EmployeeClient
+
+    @BeforeAll
+    override fun beforeAll() {
+        super.beforeAll()
+        val url = embeddedServer.url.toString()
+        employeeClient = EmployeeClient(url)
+    }
+
+    @Test
+    fun `create employee returns success`() {
+        val request = CreateEmployeeRequest(name = "Test User", email = "test@example.com")
+        val response = employeeClient.create(request)
+        assertNotNull(response.id)
+        assertEquals("Test User", response.name)
+    }
+}
+```
+
+### 4. Application config for test profile
+
+Create `src/test/resources/application-test.yml`:
+```yaml
+datasources:
+  default:
+    # Overridden by Testcontainers DynamicPropertySource
+    dialect: POSTGRES
+flyway:
+  datasources:
+    default:
+      enabled: true
+      locations: classpath:db/migration
+```
+
+After setup, verify all tests pass with: `./gradlew test`

package/commands/spartan/think.md

@@ -0,0 +1,221 @@
+---
+name: spartan:think
+description: Guided thinking before coding — 6-phase structured process to prevent building the wrong thing
+argument-hint: "[idea or feature description]"
+---
+
+# Think Before Build: {{ args[0] | default: "new idea" }}
+
+You are running a **structured thinking session**. The goal: think through everything BEFORE writing any code.
+
+Most rework comes from skipping the thinking phase. This command prevents that.
+
+---
+
+## First Question
+
+Ask the user:
+
+> **"Is this a new project (starting from zero) or a new feature (adding to something that exists)?"**
+
+- **New project** → Start at Phase 0, then continue through Phase 6
+- **New feature** → Skip Phase 0, start at Phase 1
+
+**Auto mode on?** → Still pause between phases. Thinking phases need human input — that's the whole point. Show each phase output, then ask "Ready for the next phase?" before moving on.
+
+---
+
+## Phase 0: PRODUCT + MVP MAP (new projects only, ~20 min)
+
+Only run this phase for new projects. Skip to Phase 1 for features.
+
+### 0A — Find the Core Loop
+Ask: "What's the one thing a user does repeatedly that makes this product valuable?"
+Write it as: **[User] does [action] to get [result], which makes them [come back because...]**
+
+### 0B — Feature Dump
+List every feature you can think of. Don't filter yet. Get it all out.
+
+### 0C — Kill Most of Them
+Go through the list. For each feature ask: "Can the core loop work without this?"
+If yes → cut it from v1. Be brutal. v1 should have 3-5 features max.
+
+### 0D — Dependency Map
+For the surviving features, draw the build order:
+- What needs to exist before something else can work?
+- What's independent and can be built in parallel?
+
+### 0E — Build Order
+Number the features 1-N based on dependencies. Feature 1 = the core loop itself.
+
+### 0F — Stack Pick
+Based on what you're building, confirm or pick the tech stack.
+Only discuss stack if the user hasn't decided yet.
+
+**Output:** Core loop statement + v1 feature list (max 5) + build order + stack
+
+Ask: **"Happy with this MVP scope? Phase 1 will dig into the first feature."**
+
+---
+
+## Phase 1: DUMP (~5 min)
+
+Brain dump using Jobs-to-be-Done (JTBD) framework. Ask the user to fill in:
+
+| Question | Answer |
+|---|---|
+| **The job:** When I [situation], I want to [motivation], so I can [outcome] | |
+| **Trigger:** What event makes someone need this RIGHT NOW? | |
+| **Current pain:** How do they solve it today? What sucks about that? | |
+| **Dream state:** If this worked perfectly, what does the user's life look like? | |
+
+Help the user write clear answers. Challenge vague ones. "Everyone" is not a user. "It's annoying" is not a pain.
+
+**Output:** Filled JTBD table
+
+Ask: **"Does this capture the real job? Phase 2 will stress-test it."**
+
+---
+
+## Phase 2: CHALLENGE (~10 min)
+
+Three exercises to pressure-test the idea:
+
+### 2A — Pre-mortem
+Pretend it's 6 months later and this feature FAILED. List the 5 most likely reasons it failed.
+Be honest. Common ones: nobody wanted it, too complicated, built the wrong thing, took too long, tech didn't work.
+
+### 2B — MoSCoW Sort
+Take everything from Phase 1 and sort into:
+
+| Category | Items |
+|---|---|
+| **Must have** (won't work without it) | |
+| **Should have** (important but can ship without) | |
+| **Could have** (nice but won't miss it) | |
+| **Won't have** (explicitly out of scope for v1) | |
+
+### 2C — Bar Test
+Write one sentence that explains this feature to a stranger in a bar.
+If you can't do it in one sentence, the scope is too big. Simplify until you can.
+
+**Output:** Pre-mortem list + MoSCoW table + bar test sentence
+
+Ask: **"Any surprises in the pre-mortem? Phase 3 is the big one — we'll walk through every screen."**
+
+---
+
+## Phase 3: WALK THROUGH (~15 min)
+
+**This is the most important phase.** 80% of rework comes from skipping this.
+
+### 3A — Screen State Matrix
+
+For every screen/view the user will see, fill out this table:
+
+| Screen | State | What User Sees | Actions Available | Edge Cases |
+|---|---|---|---|---|
+| [name] | Empty (no data yet) | | | |
+| [name] | Loading | | | |
+| [name] | Success (happy path) | | | |
+| [name] | Error (something broke) | | | |
+| [name] | Partial (some data, some missing) | | | |
+
+Go through EVERY screen. Don't skip any state. The empty state and error state are where most bugs hide.
+
+### 3B — Happy Path Narration
+Tell the story of a user doing the main flow from start to finish. Step by step. Click by click.
+"User opens the page. Sees X. Clicks Y. System does Z. User sees W."
+
+### 3C — Sad Path Narration
+Now tell the story of everything going wrong:
+- Network fails mid-action
+- User enters garbage data
+- User does things in unexpected order
+- User has no data yet (first time)
+- User has too much data (power user)
+
+**Output:** Full screen state matrix + happy path + sad path narrations
+
+Ask: **"Did we miss any screens or states? Phase 4 checks the tech side."**
+
+---
+
+## Phase 4: TECH CHECK (~10 min)
+
+Impact map — what does this touch in the codebase?
+
+### 4A — New Stuff Needed
+
+| Type | Details |
+|---|---|
+| New database tables | |
+| New API endpoints | |
+| New UI components | |
+| New background jobs | |
+| New integrations | |
+
+### 4B — Existing Code Impact
+
+| Existing Code | What Changes | Risk Level |
+|---|---|---|
+| [file/module] | [what changes] | LOW/MEDIUM/HIGH |
+
+### 4C — Reuse Check
+- What existing code can we reuse as-is?
+- What existing code needs changes?
+- Any conflicts with in-progress work?
+- External dependencies or API limits?
+
+### 4D — T-shirt Size
+Overall estimate: **S** (< 1 day) / **M** (1-3 days) / **L** (3-7 days) / **XL** (> 1 week)
+
+**Output:** Impact tables + reuse list + size estimate
+
+Ask: **"Any surprises on the tech side? Phase 5 is the final cut."**
+
+---
+
+## Phase 5: FINAL CUT (~5 min)
+
+### 5A — Confidence Check
+
+For each must-have from Phase 2, rate your confidence:
+
+| Must-Have | Confidence | Why |
+|---|---|---|
+| [item] | HIGH / MEDIUM / LOW | [reason] |
+
+Anything rated LOW → discuss with user. Either find a way to de-risk it, or move it to v2.
+
+### 5B — v1 / v2 Split
+
+| v1 (build now) | v2 (build later) |
+|---|---|
+| | |
+
+### 5C — Regret Test
+Ask: "If we ship v1 without [each v2 item], will users complain loudly?"
+If yes → move it back to v1. If no → it stays in v2.
+
+**Output:** Confidence table + v1/v2 split + final scope
+
+Ask: **"This is the final scope. Ready to build?"**
+
+---
+
+## Phase 6: BUILD
+
+Based on the T-shirt size from Phase 4, route to the right build command:
+
+- **S (< 1 day):** "Run `/spartan:quickplan` with this scope to start building."
+- **M-L (1-7 days):** "Run `/spartan:project new` to set up the full project lifecycle."
+- **XL (> 1 week):** "Run `/spartan:project new` — this needs milestones and wave planning."
+
+Show the complete thinking output as a summary the user can copy into their planning tool:
+- JTBD statement
+- MoSCoW scope
+- Screen state matrix (key screens only)
+- Impact map
+- v1/v2 split
+- Size estimate + next command to run

package/commands/spartan/unfreeze.md

@@ -0,0 +1,13 @@
+---
+name: spartan:unfreeze
+description: Remove the directory edit lock set by /spartan:freeze. Claude can edit files anywhere again.
+---
+
+# Unfreeze — Directory Lock Removed
+
+Freeze mode is now **OFF**. Claude can edit files in any directory.
+
+If guard mode was active (`/spartan:guard`), only the freeze portion is removed — careful mode remains active.
+
+Claude should acknowledge:
+"🧊 Freeze OFF — tôi có thể edit files ở bất kỳ đâu. Careful mode vẫn {{ 'ON' if careful_active else 'OFF' }}."

package/commands/spartan/update.md

@@ -0,0 +1,81 @@
+---
+name: spartan:update
+description: Check for updates and upgrade Spartan AI Toolkit to the latest version. Pulls from GitHub and re-runs the setup script automatically.
+---
+
+# Spartan Update
+
+Check for new versions and upgrade the toolkit.
+
+---
+
+## Step 1: Read current version and repo path
+
+```bash
+LOCAL_VER=$(cat ~/.claude/.spartan-version 2>/dev/null || echo "unknown")
+REPO_PATH=$(cat ~/.claude/.spartan-repo 2>/dev/null || echo "")
+echo "Current version: $LOCAL_VER"
+echo "Repo path: $REPO_PATH"
+```
+
+If `REPO_PATH` is empty or the directory doesn't exist, ask the user where they cloned `spartan-ai-toolkit`:
+"I don't know where the Spartan repo is. Where did you clone it? (e.g., `~/spartan-ai-toolkit`)"
+
+---
+
+## Step 2: Check for updates
+
+```bash
+cd "$REPO_PATH" && git fetch origin main --quiet 2>/dev/null
+REMOTE_VER=$(git show origin/main:toolkit/VERSION 2>/dev/null || echo "unknown")
+echo "Local:  $LOCAL_VER"
+echo "Remote: $REMOTE_VER"
+```
+
+If versions match: "You're on the latest version (v$LOCAL_VER). No update needed."
+
+If versions differ or either is "unknown": proceed to Step 3.
+
+---
+
+## Step 3: Read current pack selection
+
+```bash
+SAVED_PACKS=$(cat ~/.claude/.spartan-packs 2>/dev/null | tr '\n' ',' | sed 's/,$//')
+echo "Installed packs: $SAVED_PACKS"
+```
+
+Show the user their current packs and ask:
+"You have these packs: $SAVED_PACKS. Want to keep the same packs, or change them?"
+
+- Keep same → use `--packs=$SAVED_PACKS` flag
+- Change → run without `--packs` flag (interactive menu)
+
+---
+
+## Step 4: Pull and reinstall
+
+```bash
+cd "$REPO_PATH" && git pull origin main
+```
+
+Then run the setup script with saved packs:
+
+```bash
+cd "$REPO_PATH/toolkit" && ./scripts/setup.sh --global --packs=$SAVED_PACKS
+```
+
+Or if user wants to change packs:
+
+```bash
+cd "$REPO_PATH/toolkit" && ./scripts/setup.sh --global
+```
+
+---
+
+## Step 5: Confirm
+
+After setup completes, tell the user:
+"Updated to Spartan v$REMOTE_VER. Restart Claude Code to pick up all changes."
+
+**Never suggest `/gsd:*` commands to the user.** Always translate to `/spartan:*`.

package/commands/spartan/validate.md

@@ -0,0 +1,193 @@
+---
+name: spartan:validate
+description: Score a product idea with a quick canvas + 7-area validation checklist — get a GO / TEST MORE / KILL decision
+argument-hint: "[idea or product name]"
+---
+
+# Validate: {{ args[0] | default: "your idea" }}
+
+You are running a two-part validation session. Part 1 is a quick idea canvas (5 min). Part 2 is a scoring checklist (10 min). At the end, you'll get a clear GO / TEST MORE / KILL decision.
+
+Be honest. The point is to kill bad ideas early, not to make every idea sound good.
+
+---
+
+## Part 1: Quick Idea Canvas (~5 min)
+
+Walk the user through each question. Challenge weak or vague answers. "Everyone" is not a target user. "It's better" is not a differentiator.
+
+### The Canvas
+
+| # | Question | Answer |
+|---|---|---|
+| 1 | **The problem:** What specific pain does this solve? | |
+| 2 | **Who has it:** Describe the person (not "everyone") | |
+| 3 | **Current solution:** How do they solve it today? | |
+| 4 | **Your solution:** 30-second pitch — what is it and what does it do? | |
+| 5 | **Why you:** What do you know or have that gives you an edge? | |
+| 6 | **Market size:** How many people have this problem? (rough is fine) | |
+| 7 | **Top 3 risks:** What could kill this idea? | |
+| 8 | **First experiment:** What's the cheapest way to test demand? | |
+
+### Gut Check (yes/no)
+
+Ask these 5 questions. The user answers yes or no:
+
+1. Would you use this yourself?
+2. Do you know 3 real people who have this problem?
+3. Have you seen people complain about this online?
+4. Can you explain it in one sentence to a stranger?
+5. Would you still work on this if it took twice as long?
+
+Count the "yes" answers:
+- 5/5 = Strong founder conviction
+- 3-4 = Good, but check what's missing
+- 0-2 = Red flag — you might not care enough to push through the hard parts
+
+**Output:** Filled canvas table + gut check score
+
+Ask: **"Ready for the scoring checklist? This gets more specific."**
+
+---
+
+## Part 2: Validation Checklist (~10 min)
+
+Score each area 1-5. Ask the user probing questions to arrive at the right score. Don't let them rate themselves high without evidence.
+
+### Area 1: Problem (is it real?)
+
+| Score | Meaning |
+|---|---|
+| 1 | You think it's a problem but haven't talked to anyone |
+| 2 | A few people mentioned it casually |
+| 3 | Multiple people describe this pain unprompted |
+| 4 | People are actively spending money/time to solve it |
+| 5 | People are desperate — current solutions are awful and expensive |
+
+Ask: How often does this problem happen? Daily? Weekly? Once a year?
+Ask: How do they solve it now? How much time/money does that cost them?
+
+### Area 2: Solution (does it work?)
+
+| Score | Meaning |
+|---|---|
+| 1 | Just an idea, no proof it works |
+| 2 | Mockup or prototype exists |
+| 3 | A few people have tried it and gave feedback |
+| 4 | Users understand it in 30 seconds and want to use it |
+| 5 | Users try it and don't want to go back to the old way |
+
+Ask: Can a stranger understand what this does in 30 seconds?
+Ask: Is this simpler than what they use now, or more complicated?
+
+### Area 3: Competition (can you win?)
+
+| Score | Meaning |
+|---|---|
+| 1 | Strong incumbents, no clear angle |
+| 2 | Competitors exist but are beatable on one dimension |
+| 3 | Competitors are weak or serving a different segment |
+| 4 | No direct competitors, only workarounds |
+| 5 | You have a clear unfair advantage they can't copy |
+
+Ask: Who are the top 3 alternatives? What do they charge?
+Ask: Why would someone pick you over them?
+
+### Area 4: Market (big enough?)
+
+| Score | Meaning |
+|---|---|
+| 1 | Tiny niche, hard to grow beyond 100 users |
+| 2 | Small market, maybe a lifestyle business |
+| 3 | Medium market, can build a real company |
+| 4 | Large market with clear growth trends |
+| 5 | Massive market, multiple entry points |
+
+Ask: How many people/companies have this problem?
+Ask: Is this market growing or shrinking?
+
+### Area 5: Build Ability (can you build it?)
+
+| Score | Meaning |
+|---|---|
+| 1 | Needs tech that doesn't exist yet |
+| 2 | Very hard — needs specialized skills you don't have |
+| 3 | Doable but will take 2-3 months for MVP |
+| 4 | Can build MVP in 2-4 weeks with your current skills |
+| 5 | Can build MVP in under 2 weeks, mostly known tech |
+
+Ask: What's the hardest part to build?
+Ask: Any tech risk — things that might not work?
+
+### Area 6: Founder Fit (should YOU build it?)
+
+| Score | Meaning |
+|---|---|
+| 1 | No connection to this space, just saw an opportunity |
+| 2 | Some interest but no experience with these users |
+| 3 | You understand the space, have used similar products |
+| 4 | You've worked in this space or have the problem yourself |
+| 5 | Deep expertise + network + personal obsession with the problem |
+
+Ask: Do you know this type of user personally?
+Ask: Would you still work on this in 2 years if growth is slow?
+
+### Area 7: Business Model (will it make money?)
+
+| Score | Meaning |
+|---|---|
+| 1 | No idea how to make money from this |
+| 2 | Could maybe add ads or freemium later |
+| 3 | Users might pay, but unclear how much |
+| 4 | Clear pricing model, comparable products charge similar amounts |
+| 5 | Users already pay for worse alternatives — willingness to pay is proven |
+
+Ask: How will you charge? Subscription? One-time? Usage-based?
+Ask: What would users pay? What are they paying for alternatives now?
+
+---
+
+## Scoring
+
+Add up all 7 scores.
+
+| Total | Verdict | What to Do |
+|---|---|---|
+| 28-35 | **BUILD** | Strong idea. Start with `/spartan:think` to plan it out. |
+| 21-27 | **TEST MORE** | Promising but gaps. Do more user research on the low-scoring areas. |
+| 14-20 | **RETHINK** | Too many weak spots. Pivot the approach or park the idea. |
+| Below 14 | **KILL** | Not ready. Save your time for a stronger idea. |
+
+---
+
+## Output: One-Page Scorecard
+
+Show this at the end:
+
+```
+## Validation Scorecard: [idea name]
+
+### Scores
+| Area | Score | Notes |
+|---|---|---|
+| Problem | X/5 | [one-liner] |
+| Solution | X/5 | [one-liner] |
+| Competition | X/5 | [one-liner] |
+| Market | X/5 | [one-liner] |
+| Build Ability | X/5 | [one-liner] |
+| Founder Fit | X/5 | [one-liner] |
+| Business Model | X/5 | [one-liner] |
+| **TOTAL** | **XX/35** | |
+
+### Verdict: [BUILD / TEST MORE / RETHINK / KILL]
+
+### Weakest Areas (focus here):
+1. [lowest scoring area] — [what to do about it]
+2. [second lowest] — [what to do about it]
+
+### Recommended Next Step:
+- BUILD → Run `/spartan:think` to start structured planning
+- TEST MORE → Run `/spartan:interview` to talk to real users
+- RETHINK → Run `/spartan:brainstorm` to explore other angles
+- KILL → Move on. Run `/spartan:brainstorm` for new ideas.
+```