@c0x12c/spartan-ai-toolkit 1.5.0 → 1.6.0

package/.claude-plugin/marketplace.json

@@ -8,9 +8,9 @@
   "plugins": [
     {
       "name": "spartan-ai-toolkit",
-      "description": "5 workflows, 55 commands, 11 rules, 20 skills, 6 agents — organized in 11 packs with dependencies",
+      "description": "5 workflows, 56 commands, 12 rules, 22 skills, 7 agents — organized in 11 packs with dependencies",
       "source": "./toolkit",
-      "version": "1.5.0"
+      "version": "1.6.0"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "spartan-ai-toolkit",
-  "version": "1.5.0",
-  "description": "Engineering discipline layer for Claude Code — 5 workflows, 55 commands, 11 rules, 20 skills, 6 agents organized in 11 packs",
+  "version": "1.6.0",
+  "description": "Engineering discipline layer for Claude Code — 5 workflows, 56 commands, 12 rules, 22 skills, 7 agents organized in 11 packs",
   "author": {
     "name": "Khoa Tran",
     "url": "https://github.com/spartan-stratos"

package/VERSION

@@ -1 +1 @@
-1.5.0
+1.6.0

package/commands/spartan/build.md

@@ -224,6 +224,8 @@ Uses skills: `ui-ux-pro-max`, frontend rules
 
 **Full-stack mode** — backend tasks first, then frontend tasks. Mark the integration point clearly (where frontend starts depending on backend API).
 
+**CRITICAL: Full-stack means BOTH layers must complete.** Don't move to Gate 3 after finishing backend only. The plan must include frontend tasks and ALL tasks must be done before review. If the spec mentions UI changes, API responses shown to users, or any user-facing behavior — frontend tasks are mandatory.
+
 ### Create branch
 
 ```bash
@@ -299,7 +301,24 @@ Call the right skills based on what you're doing:
 | React components | `ui-ux-pro-max` |
 | Security-sensitive code | `security-checklist` |
 
-### After all tasks
+### After all tasks — Verify Definition of Done
+
+**Before moving to Gate 3, verify ALL layers are complete:**
+
+| Mode | Must be done before review |
+|------|---------------------------|
+| **Backend** | Migration applied, entity/table/repo created, manager with business logic, controller with endpoints, all tests passing (`./gradlew test`) |
+| **Frontend** | Types defined, API client updated, components built, page/routing wired, build passes (`yarn build` or `npm run build`) |
+| **Full-stack** | ALL backend items above + ALL frontend items above + frontend calls the new backend API correctly |
+
+**Full-stack verification (MANDATORY if mode is full-stack):**
+1. Backend tests pass: `./gradlew test`
+2. Frontend builds: `yarn build` or `npm run build`
+3. Frontend types match backend response DTOs
+4. API client has methods for all new endpoints
+5. UI shows the data from the new endpoints
+
+**If any layer is incomplete**, go back and finish it. Do NOT proceed to Gate 3 with only backend done.
 
 Run the full test suite:
 ```bash
@@ -307,15 +326,17 @@ Run the full test suite:
 ./gradlew test
 
 # Frontend
-npm test
+npm test && npm run build
 
-# Both
-./gradlew test && npm test
+# Both (full-stack)
+./gradlew test && npm test && npm run build
 ```
 
 **GATE 3 — STOP and ask:**
 > "All [N] tasks done. [X] tests passing. Ready for review?"
 >
+> **Full-stack:** "Backend: [N] tasks done, tests passing. Frontend: [N] tasks done, build passing. Ready for review?"
+>
 > If 3+ tasks were completed: "I'll run a self-review now. For a deeper dual-agent review, say 'gate review'."
 >
 > **Auto mode on?** → Continue to Review immediately.
@@ -401,3 +422,37 @@ If a previous session was interrupted (context overflow, user stopped, etc.), th
 - **Frontend checks for backend needs.** If a new page needs data that doesn't exist yet, say so at Stage 2 and add backend tasks first.
 - **Don't over-plan.** If the whole thing is 1-2 files and 30 minutes of work, don't force it into this workflow. Just do it. This workflow is for features that need structure — at least 2-3 tasks.
 - **Save state for big work.** If 5+ tasks, save artifacts to `.planning/` so future sessions can resume.
+- **Full-stack = both layers done.** If the feature touches both backend and frontend, you MUST implement both before creating the PR. Backend-only completion is NOT "done" for a full-stack feature.
+
+---
+
+## Definition of Done
+
+A feature is NOT done until every applicable item is checked:
+
+### Backend
+- [ ] Database migration (if new/changed table)
+- [ ] Kotlin entity, table object, repository with tests
+- [ ] Manager with business logic and Either error handling
+- [ ] Controller with proper annotations (@ExecuteOn, @Secured, @Validated)
+- [ ] Integration tests for all endpoints (happy path, 404, 401)
+- [ ] `./gradlew test` passes
+
+### Frontend
+- [ ] TypeScript types/interfaces match backend DTOs
+- [ ] API client methods for all new/changed endpoints
+- [ ] Components built and connected to data
+- [ ] Page routing and navigation working
+- [ ] `yarn build` (or `npm run build`) passes with no errors
+- [ ] Loading, empty, and error states handled
+
+### Full-Stack (ALL of the above, plus)
+- [ ] Frontend calls backend API correctly (snake_case conversion, auth headers)
+- [ ] Response data renders in the UI
+- [ ] End-to-end flow works: user action → API call → backend processing → response → UI update
+- [ ] Both `./gradlew test` AND `yarn build` pass
+
+### Always
+- [ ] Atomic commits (one per task)
+- [ ] Self-review passed (backend review + frontend review if applicable)
+- [ ] PR created with summary and test plan

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c0x12c/spartan-ai-toolkit",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Engineering discipline layer for AI coding agents — commands, rules, skills, agents, and packs for Claude Code",
   "type": "module",
   "bin": {

package/packs/core.yaml

@@ -26,6 +26,7 @@ commands:
 
 rules:
   - core/NAMING_CONVENTIONS.md
+  - core/SKILL_AUTHORING.md
 
 skills: []
 agents:

package/packs/packs.compiled.json

@@ -28,7 +28,8 @@
         "gate-review"
       ],
       "rules": [
-        "core/NAMING_CONVENTIONS.md"
+        "core/NAMING_CONVENTIONS.md",
+        "core/SKILL_AUTHORING.md"
       ],
       "skills": [],
       "agents": [

package/rules/core/SKILL_AUTHORING.md

@@ -0,0 +1,174 @@
+# Skill Authoring Rules
+
+Rules for creating and modifying skills in the Spartan AI Toolkit. Follow these when writing new skills or improving existing ones.
+
+## Frontmatter (REQUIRED)
+
+Every SKILL.md must have these fields:
+
+```yaml
+---
+name: skill-name
+description: "What it does. Use when [trigger conditions]."
+allowed_tools:
+  - Read
+  - Write
+  # ... tools the skill needs
+---
+```
+
+### Description Must Be a Trigger
+
+The description tells the model WHEN to activate the skill, not WHAT the skill is.
+
+| Bad (summary) | Good (trigger) |
+|----------------|----------------|
+| "Database design patterns including schemas and migrations" | "Database design patterns. Use when creating tables, writing migrations, or implementing repositories." |
+| "The full startup pipeline from brainstorm to outreach" | "Coordinates the full startup pipeline. Use when the user starts a new idea project or references stages/gates." |
+
+**Rule:** Every description must contain "Use when" followed by specific trigger conditions.
+
+### allowed_tools Must Match the Skill's Needs
+
+| Skill type | Typical tools |
+|------------|--------------|
+| Code/backend (writes files) | Read, Write, Edit, Glob, Grep, Bash |
+| Research/analysis (web searches) | WebSearch, WebFetch, Read |
+| Content/writing (creates + researches) | Read, Write, WebSearch |
+| Review/audit (reads only) | Read, Glob, Grep |
+
+---
+
+## Folder Structure (Skills Are Folders, Not Files)
+
+A skill is a directory, not just a markdown file. Use the file system for progressive disclosure.
+
+```
+toolkit/skills/my-skill/
+  SKILL.md              # Main definition — short, high-level (required)
+  code-patterns.md      # Code examples (if code-heavy skill)
+  examples.md           # Good/bad examples (if teaching a style)
+  checklists.md         # Review checklists (if audit/review skill)
+  workflows.md          # Ready-to-use templates (if scaffolding skill)
+```
+
+### When to Split Into Multiple Files
+
+| SKILL.md is... | Action |
+|-----------------|--------|
+| Under 100 lines | One file is fine |
+| 100-150 lines with code blocks | Split code into a reference file |
+| 150+ lines | Must split — too much for one read |
+
+### SKILL.md Should Be the Summary
+
+Keep SKILL.md short (60-120 lines). It should have:
+- Frontmatter
+- "When to Use" section
+- Key rules and principles (without detailed code)
+- Gotchas section
+- References to supporting files
+
+Move into supporting files:
+- Detailed code templates and examples
+- Long checklists
+- Good/bad comparisons
+- Ready-to-use templates
+
+Reference with: `> See code-patterns.md for complete implementation templates.`
+
+---
+
+## Gotchas Section (REQUIRED)
+
+Every skill must have a `## Gotchas` section. This is the highest-value content in any skill.
+
+### Format
+
+```markdown
+## Gotchas
+
+- **Bold lead-in sentence.** Explanation of why this matters and what to do instead.
+- **Another gotcha.** Details.
+```
+
+### What Makes a Good Gotcha
+
+- Specific failure patterns Claude hits when using this skill
+- Things that look right but are wrong
+- Common mistakes users make in this domain
+- Counter-intuitive rules that violate defaults
+
+### What is NOT a Gotcha
+
+- General best practices (put those in Rules)
+- Obvious things Claude already knows
+- Restating the instructions in negative form
+
+**Minimum 3 gotchas per skill. Build this section over time as you find new failure patterns.**
+
+---
+
+## Content Rules
+
+### Don't State the Obvious
+
+Claude already knows how to code, research, and write. Focus on information that pushes Claude OUT of its normal patterns.
+
+| Bad (obvious) | Good (non-obvious) |
+|----------------|---------------------|
+| "Use proper error handling" | "`!!` is banned — use `?.`, `?:`, or null check" |
+| "Write clean code" | "Don't add docstrings to code you didn't change" |
+| "Research thoroughly" | "Press releases aren't research — cross-check with third-party sources" |
+
+### Give Claude Flexibility
+
+Tell Claude WHAT to check and WHY, not exact steps for every situation. Skills are reused across many contexts — being too specific makes them brittle.
+
+| Bad (railroading) | Good (flexible) |
+|---------------------|------------------|
+| "Step 1: Open file X. Step 2: Find line Y. Step 3: Change to Z." | "Check the controller for @ExecuteOn annotation. If missing, add it." |
+
+### Use Examples Over Instructions
+
+A good/bad example teaches more than a paragraph of rules. When possible, show rather than tell.
+
+---
+
+## Config Pattern (for Stateful Skills)
+
+Skills that run repeatedly for the same user should store preferences:
+
+```json
+// content-config.json in the project root
+{
+  "defaultPlatforms": ["x", "linkedin"],
+  "brandVoice": "direct and technical",
+  "audience": "developers"
+}
+```
+
+Read config at skill start. Skip setup questions for configured fields.
+
+---
+
+## Naming
+
+| Type | Convention | Example |
+|------|-----------|---------|
+| Skill directory | `kebab-case` | `ci-cd-patterns/` |
+| Main file | `SKILL.md` (always) | `SKILL.md` |
+| Supporting files | `kebab-case.md` | `code-patterns.md` |
+
+---
+
+## Checklist: Before Shipping a Skill
+
+- [ ] Frontmatter has `name`, `description` (with trigger), and `allowed_tools`
+- [ ] Description says "Use when..." with specific conditions
+- [ ] SKILL.md is under 120 lines (split if longer)
+- [ ] Has a `## Gotchas` section with 3+ items
+- [ ] Code-heavy content is in supporting files, not inline
+- [ ] Examples show good AND bad patterns where applicable
+- [ ] Doesn't restate things Claude already knows
+- [ ] Gives Claude flexibility — principles over exact steps

package/skills/article-writing/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: article-writing
 description: Write blog posts, guides, tutorials, and long-form content. Sounds like a real person, not AI. Use when the user wants polished written content.
+allowed_tools:
+  - Read
+  - Write
+  - WebSearch
 ---
 
 # Article Writing
@@ -14,6 +18,8 @@ Write long-form content that sounds like a person wrote it.
 - Matching an existing voice from examples
 - Cleaning up and tightening existing writing
 
+> See `examples.md` for good vs bad writing examples that show what "sounds human" actually means.
+
 ## Rules
 
 1. Start with something concrete: example, number, story, or code block.
@@ -82,6 +88,14 @@ This is a two-way talk:
 - Skip the "this part is weak" feedback
 - Write AI-sounding content and call it done
 
+## Gotchas
+
+- **The intro is where most articles die.** If the first paragraph starts with "In this article, we'll explore..." — delete it and start with a story, stat, or code block.
+- **AI-written articles all sound the same.** They hedge ("it's important to note"), use transition words nobody says out loud ("Moreover"), and avoid strong opinions. Cut all of that.
+- **Don't explain the obvious.** If your audience is developers, don't explain what an API is. Write for the person, not the lowest common denominator.
+- **Long ≠ thorough.** A 3,000-word article with 1,500 words of filler is worse than a 1,500-word article where every sentence earns its spot.
+- **Every section needs evidence.** A claim without a number, example, or code block is just an opinion. Back it up or cut it.
+
 ## Before You Deliver
 
 - Facts match sources

package/skills/article-writing/examples.md

@@ -0,0 +1,59 @@
+# Article Writing — Good vs Bad Examples
+
+> Read these examples to calibrate your writing style. The "bad" versions are typical AI output. The "good" versions sound like a person wrote them.
+
+## Intro Paragraphs
+
+### Bad (AI-style)
+> In today's rapidly evolving technological landscape, the importance of effective error handling cannot be overstated. This comprehensive guide will walk you through the various aspects of implementing robust error handling strategies in your Kotlin applications, enabling you to build more resilient and maintainable software systems.
+
+### Good (human-style)
+> Last Tuesday, our payment service threw 4,000 unhandled exceptions in 20 minutes. The fix was 3 lines of code. Here's what went wrong and how to make sure it doesn't happen to you.
+
+---
+
+## Explaining a Concept
+
+### Bad (AI-style)
+> Dependency injection is a crucial software design pattern that facilitates the development of loosely coupled, maintainable, and testable code. By leveraging this paradigm, developers can effectively manage the complex dependencies between various components of their application architecture.
+
+### Good (human-style)
+> Dependency injection means your class doesn't create its own dependencies — someone hands them in. Instead of `val db = Database()` inside your class, you write `class UserRepo(val db: Database)` and let the framework wire it up. That's it. The rest is details.
+
+---
+
+## Technical Guide Section
+
+### Bad (AI-style)
+> To implement this feature, you'll want to start by carefully considering the architectural implications. First, create a new service class that will handle the business logic. Then, implement the necessary repository methods. Finally, wire everything together in the controller layer. This approach ensures a clean separation of concerns.
+
+### Good (human-style)
+> Three files to create:
+> 1. `PaymentManager.kt` — validates the amount, calls Stripe, saves the record
+> 2. `PaymentRepository.kt` — insert and soft-delete methods
+> 3. `PaymentController.kt` — one POST endpoint, delegates to the manager
+>
+> Start with the manager. The other two are boilerplate.
+
+---
+
+## Transitions Between Sections
+
+### Bad (AI-style)
+> Now that we've explored the fundamentals of error handling, let's delve into the more advanced aspects of this topic. In the following section, we'll examine how to implement custom error types that can provide more granular control over your application's error handling mechanisms.
+
+### Good (human-style)
+> The basics work for 80% of cases. But when you need different error responses for different callers (API vs webhook vs internal), you need custom error types.
+
+---
+
+## Conclusions
+
+### Bad (AI-style)
+> In conclusion, we've covered a comprehensive overview of error handling patterns in Kotlin. By implementing these strategies, you'll be well-equipped to build robust, maintainable applications. Remember that error handling is not just about catching exceptions — it's about creating a resilient system that gracefully handles the unexpected.
+
+### Good (human-style)
+> Three things to remember:
+> 1. Return `Either`, don't throw. Your callers will thank you.
+> 2. Log the actual error, not a generic message.
+> 3. Test the error paths. They run more often than you think.

package/skills/backend-api-design/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: backend-api-design
 description: Design RPC-style APIs with layered architecture (Controller → Manager → Repository). Use when creating new API endpoints, designing API contracts, or reviewing API patterns.
+allowed_tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
 ---
 
 # Backend API Design — Quick Reference
@@ -24,36 +30,6 @@ POST /api/v1/sync/employees         # Action
 - **Plural for collections** — `/employees`
 - **Verb sub-paths for actions** — `/delete`, `/restore`, `/sync`
 
-## Controller Template
-
-```kotlin
-@ExecuteOn(TaskExecutors.IO)    // REQUIRED for suspend
-@Validated
-@Controller("/api/v1/admin")
-@Secured(OAuthSecurityRule.ADMIN)
-class EmployeeController(
-  private val employeeManager: EmployeeManager  // Managers ONLY
-) {
-  @Get("/employee")
-  suspend fun getEmployee(@QueryValue id: UUID): EmployeeResponse {
-    return employeeManager.findById(id).throwOrValue()
-  }
-
-  @Get("/employees")
-  suspend fun listEmployees(
-    @QueryValue page: Int?,
-    @QueryValue limit: Int?,
-    @QueryValue status: String?
-  ): EmployeeListResponse {
-    return employeeManager.list(
-      page = page ?: 1,
-      limit = (limit ?: 20).coerceAtMost(100),
-      status = status
-    ).throwOrValue()
-  }
-}
-```
-
 ## Layered Architecture
 
 ```
@@ -81,107 +57,28 @@ Repository  →  data access only, no business logic
 - `db.replica` for reads, `db.primary` for writes
 - Always checks `deletedAt.isNull()`
 
-## Response Models
+## Quick Code Reference
 
-All in `module-client/response/{domain}/`:
+The core controller delegation pattern:
 
 ```kotlin
-data class EmployeeResponse(
-  val id: UUID,
-  val name: String,
-  val email: String,
-  val status: String,
-  val createdAt: Instant
-) {
-  companion object {
-    fun from(entity: EmployeeEntity) = EmployeeResponse(
-      id = entity.id,
-      name = entity.name,
-      email = entity.email,
-      status = entity.status,
-      createdAt = entity.createdAt
-    )
-  }
+@Get("/employee")
+suspend fun getEmployee(@QueryValue id: UUID): EmployeeResponse {
+  return employeeManager.findById(id).throwOrValue()
 }
-
-data class EmployeeListResponse(
-  val items: List<EmployeeResponse>,
-  val total: Int,
-  val page: Int,
-  val limit: Int,
-  val hasMore: Boolean
-)
 ```
 
-## Pagination Pattern
+- **Response models** — `companion object { fun from(entity) }` in `module-client/response/{domain}/`
+- **Pagination** — offset-based, manager returns `EmployeeListResponse` with `items`, `total`, `page`, `limit`, `hasMore`
+- **Errors** — return `ClientError.NOT_FOUND.asException().left()` from managers, never throw
+- **Factory beans** — `@Factory` class with `@Singleton` method, wire repos + db into manager
 
-```kotlin
-override suspend fun list(
-  page: Int,
-  limit: Int,
-  status: String?
-): Either<ClientException, EmployeeListResponse> {
-  val offset = (page - 1) * limit
-
-  val (items, total) = transaction(db.replica) {
-    val query = EmployeesTable
-      .selectAll()
-      .where { EmployeesTable.deletedAt.isNull() }
-
-    if (status != null) {
-      query.andWhere { EmployeesTable.status eq status }
-    }
-
-    val total = query.count().toInt()
-    val items = query
-      .orderBy(EmployeesTable.createdAt to SortOrder.DESC)
-      .limit(limit)
-      .offset(offset.toLong())
-      .map { convert(it) }
-
-    items to total
-  }
-
-  return EmployeeListResponse(
-    items = items.map { EmployeeResponse.from(it) },
-    total = total,
-    page = page,
-    limit = limit,
-    hasMore = (page * limit) < total
-  ).right()
-}
-```
+> See code-patterns.md for complete controller, response model, pagination, error handling, and factory bean templates.
 
-## Error Pattern
+## Gotchas
 
-```kotlin
-// Not found
-val entity = repository.byId(id)
-  ?: return ClientError.NOT_FOUND.asException().left()
-
-// Already exists
-val existing = repository.byEmail(email)
-if (existing != null) {
-  return ClientError.ALREADY_EXISTS.asException().left()
-}
-
-// Validation
-if (request.name.isBlank()) {
-  return ClientError.INVALID_INPUT.asException("Name is required").left()
-}
-```
-
-## Factory Bean
-
-```kotlin
-@Factory
-class EmployeeManagerFactory {
-  @Singleton
-  fun provideEmployeeManager(
-    employeeRepository: EmployeeRepository,
-    db: DatabaseContext
-  ): EmployeeManager {
-    return DefaultEmployeeManager(employeeRepository, db)
-  }
-}
-```
+- **Multi-word `@QueryValue` params MUST have explicit snake_case names.** The frontend axios interceptor sends `project_id` but Micronaut matches the literal param name. Write `@QueryValue("project_id") projectId: UUID`, not bare `@QueryValue projectId: UUID`.
+- **Don't use `@Put`, `@Delete`, or `@Patch`.** This is RPC-style — all mutations are `@Post`. The only `@Get` is for reads.
+- **Controllers that inject repositories are a code smell.** If you see `private val fooRepository: FooRepository` in a controller, move it to the manager.
+- **`andWhere {}` not second `.where {}`.** Calling `.where {}` twice replaces the first condition. Use `.andWhere {}` to chain.
+- **Don't forget `@ExecuteOn(TaskExecutors.IO)`.** Without it, suspend functions may hang or run on the wrong thread pool. Every controller needs it.