@c0x12c/spartan-ai-toolkit 1.8.4 → 1.9.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "spartan-ai-toolkit",
       "description": "5 workflows, 68 commands, 21 rules, 28 skills, 9 agents — organized in 12 packs with dependencies",
       "source": "./toolkit",
-      "version": "1.8.4"
+      "version": "1.9.1"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "spartan-ai-toolkit",
-  "version": "1.8.4",
+  "version": "1.9.1",
   "description": "Engineering discipline layer for Claude Code — 5 workflows, 68 commands, 21 rules, 28 skills, 9 agents organized in 12 packs",
   "author": {
     "name": "Khoa Tran",

package/README.md

@@ -316,6 +316,7 @@ Rules are enforced automatically every session. No action needed — they're act
 | Rule | Pack |
 |------|------|
 | `NAMING_CONVENTIONS` | core |
+| `TIMEZONE` | core |
 | `ARCHITECTURE` | shared-backend |
 | `SCHEMA` | database |
 | `ORM_AND_REPO` | database |
@@ -358,6 +359,74 @@ For other tools, copy the rule files from `toolkit/rules/` into your tool's conf
 
 ---
 
+## Parallel Builds
+
+By default, `/spartan:build` creates a **git worktree** per feature — a separate directory with its own branch. This means you can build 2+ features in parallel from different terminals:
+
+```bash
+# Terminal 1                          # Terminal 2
+claude                                claude
+> /spartan:build auth                 > /spartan:build payments
+# → .claude/worktrees/feature-auth/   # → .claude/worktrees/feature-payments/
+# → PR #1                            # → PR #2
+```
+
+No conflicts. Each session gets its own worktree, branch, and PR.
+
+To disable worktrees (single-terminal mode), set `worktree: false` in `.spartan/build.yaml`.
+
+---
+
+## Project Config
+
+Customize any Spartan command per project. Two config files in `.spartan/`:
+
+### `.spartan/build.yaml` — Build workflow config
+
+Controls `/spartan:build` behavior:
+
+```yaml
+worktree: true              # git worktree per feature (default: true)
+branch-prefix: "feature"    # branch name: [prefix]/[slug]
+max-review-rounds: 3        # review-fix cycles before asking user
+skip-stages: []             # skip: spec, design, plan, ship (never review)
+worktree-symlinks: []       # extra dirs to share across worktrees
+
+prompts:
+  spec: |
+    Always include performance requirements.
+  plan: |
+    Every task must reference a Jira ticket.
+  implement: |
+    Add structured logging to new service methods.
+  review: |
+    Check all API responses include request_id.
+  ship: |
+    PR title: [PROJ-123] Short description.
+```
+
+### `.spartan/commands.yaml` — Per-command prompt injection
+
+Inject custom instructions into ANY Spartan command:
+
+```yaml
+prompts:
+  review: |
+    Flag any function longer than 50 lines.
+  pr-ready: |
+    Always add "Reviewers: @backend-team" for backend changes.
+  daily: |
+    Include blockers section. Tag by project area.
+  debug: |
+    Always check CloudWatch logs first.
+  migration: |
+    Migration files must start with ticket number.
+```
+
+Templates for both files are in `toolkit/templates/`.
+
+---
+
 ## Target Stack
 
 Rules and skills are tuned for this stack, but the command framework works with anything:

package/VERSION

@@ -1 +1 @@
-1.8.4
+1.9.1

package/commands/spartan/build.md

@@ -14,23 +14,22 @@ You decide which steps to run, which skills to call, and when to move forward. T
 ```
 SINGLE FEATURE:
 
-  Context → Spec → Design? → Plan+Worktree → Implement → Review Agent → Fix → Ship
-     │        │        │           │               │            │          │       │
-  .memory/ Gate 1   Design      Gate 2          Gate 3    Spawn agent   Loop   Gate 4
-                    Gate      EnterWorktree               fix until OK
+  Context → Spec → Design? → Plan → Implement → Review Agent → Fix → Ship
+     │        │        │        │        │            │          │       │
+  .memory/ Gate 1   Design   Gate 2   Gate 3    Spawn agent   Loop   Gate 4
+                    Gate                        fix until OK
 
 EPIC (multi-feature — auto-detected):
 
-  Context → Epic detected → Per feature: Spec/Design/Plan → Worktree → Implement → Review → Ship
-     │            │                │                            │            │          │       │
-  .planning/  read epic    fill gaps if needed          EnterWorktree  parallel by    Loop   one PR
-  epics/                                                             dependency
+  Context → Epic detected → Per feature: Spec/Design/Plan → Implement → Review Agent → Fix → Ship
+     │            │                │                             │            │          │       │
+  .planning/  read epic    fill gaps if needed          parallel by      Spawn agent  Loop   one PR
+  epics/                                                dependency       fix until OK
 
-PARALLEL BUILDS (multiple terminals):
+PARALLEL BUILDS (automatic — each build in its own worktree):
 
-  Terminal 1: /spartan:build auth     → worktree .claude/worktrees/feature-auth/     → branch feature/auth     → PR #1
-  Terminal 2: /spartan:build payments → worktree .claude/worktrees/feature-payments/ → branch feature/payments → PR #2
-  (each terminal gets its own worktree, branch, and PR — no conflicts)
+  /spartan:build auth     → worktree .claude/worktrees/feature-auth/     → PR #1
+  /spartan:build payments → worktree .claude/worktrees/feature-payments/ → PR #2
 ```
 
 **Fast path:** For small work (< 1 day, ≤ 4 tasks), you do spec + plan inline. No separate commands needed.
@@ -52,6 +51,86 @@ PARALLEL BUILDS (multiple terminals):
 
 ---
 
+## FIRST: Load Build Config & Enter Worktree
+
+### Load project build config
+
+Check for a project-level build config that overrides default behavior:
+
+```bash
+cat .spartan/build.yaml 2>/dev/null || cat .spartan/build.yml 2>/dev/null
+```
+
+If `.spartan/build.yaml` exists, read it and apply overrides. All fields are optional — omit to use defaults.
+
+| Field | Default | What it does |
+|-------|---------|-------------|
+| `worktree` | `true` | Create a git worktree per build. Set `false` for single-terminal workflow. |
+| `branch-prefix` | `"feature"` | Branch name: `[prefix]/[slug]` (e.g., `feature/user-auth`) |
+| `max-review-rounds` | `3` | Max review-fix cycles before asking the user |
+| `skip-stages` | `[]` | Stages to skip. Valid: `spec`, `design`, `plan`, `review`, `ship` |
+| `worktree-symlinks` | `[]` | Extra gitignored dirs to symlink into worktrees |
+| `prompts.spec` | — | Custom instructions injected after spec questions |
+| `prompts.plan` | — | Custom instructions injected into the plan stage |
+| `prompts.implement` | — | Custom instructions injected during implementation |
+| `prompts.review` | — | Custom instructions injected into the review agent's prompt |
+| `prompts.ship` | — | Custom instructions injected before PR creation |
+
+**If config has `prompts.*` sections**, inject those instructions at the relevant stage. They run AFTER the built-in instructions.
+
+**If config has `skip-stages`**, skip those stages. But NEVER skip `review` even if listed — review is always mandatory.
+
+### Enter Worktree
+
+**Default: every build runs in a git worktree.** A worktree is a separate directory with its own branch — lets you run `/spartan:build` in multiple terminals without conflicts.
+
+**Check if already in a worktree:**
+
+```bash
+git rev-parse --show-toplevel 2>/dev/null
+git worktree list 2>/dev/null | head -3
+```
+
+If already in a worktree (not the main repo), skip — you're already isolated.
+
+**If `worktree: false` in config**, skip worktree creation. Use `git checkout -b` later in Stage 3 instead.
+
+**Otherwise, create a worktree now:**
+
+Generate a slug from the feature description (e.g., "user auth" → `user-auth`). Use `branch-prefix` from config (default: `feature`).
+
+```
+EnterWorktree(name: "[prefix]-[slug]")
+```
+
+This creates a worktree at `.claude/worktrees/[prefix]-[slug]/` with a new branch and switches your working directory there.
+
+**Symlink shared directories** — gitignored dirs don't appear in worktrees. Symlink them from the main repo:
+
+```bash
+MAIN_REPO="$(git worktree list | head -1 | awk '{print $1}')"
+SYMLINKS=".planning .memory .handoff .spartan"
+
+# Add extra symlinks from config (worktree-symlinks field)
+for dir in $SYMLINKS; do
+  [ -d "$MAIN_REPO/$dir" ] && [ ! -e "$dir" ] && ln -s "$MAIN_REPO/$dir" "$dir"
+done
+```
+
+> "Working in worktree: `[path]` on branch `[prefix]-[slug]`"
+
+**If `EnterWorktree` fails** (e.g., name conflict), fall back to manual worktree:
+
+```bash
+SLUG="[slug]"
+MAIN_REPO="$(pwd)"
+git worktree add "$MAIN_REPO/.worktrees/$SLUG" -b "feature/$SLUG" 2>/dev/null
+```
+
+Then tell the user: "Created worktree at `.worktrees/[slug]/`. Open a new terminal there and run `claude` + `/spartan:build`."
+
+---
+
 ## Step 0: Detect Mode & Stack (silent — no questions)
 
 Parse the user's input to find the mode:
@@ -183,6 +262,8 @@ Use the approach from `/spartan:spec` — ask questions one at a time, fill the
 
 Then continue to the next stage automatically (don't tell the user to run a separate command).
 
+**Custom spec prompts:** If `.spartan/build.yaml` has `prompts.spec`, apply those instructions now — ask any extra questions, add any extra requirements to the scope.
+
 **GATE 1 — STOP and ask:**
 > "Here's the scope. Anything to change before I plan?"
 >
@@ -278,28 +359,24 @@ Uses skills: `ui-ux-pro-max`, frontend rules
 
 **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 feature workspace
+### Verify workspace
 
-Every build runs in its own **git worktree** — a separate directory with its own branch. This lets you run `/spartan:build` in multiple terminals on the same repo. Each terminal gets its own worktree, branch, and PR. No conflicts.
+Confirm you're in the right place:
 
-Use `EnterWorktree` to create the worktree. The name should be the feature branch slug:
-
-```
-EnterWorktree(name: "feature-[slug]")
+```bash
+pwd
+git branch --show-current
 ```
 
-This creates a worktree at `.claude/worktrees/feature-[slug]/` on a new branch and switches your working directory to it. All file reads, writes, and bash commands now happen inside the worktree.
+**If worktree is enabled (default):** You should already be in a worktree from the "FIRST" step. If not, go back and create one.
 
-**Symlink shared directories** — `.planning/`, `.memory/`, `.handoff/`, and `.spartan/` are gitignored and won't appear in the worktree. Symlink them from the main repo so specs, plans, and memory are shared:
+**If `worktree: false` in config:** Create a branch now:
 
 ```bash
-MAIN_REPO="$(git worktree list | head -1 | awk '{print $1}')"
-for dir in .planning .memory .handoff .spartan; do
-  [ -d "$MAIN_REPO/$dir" ] && [ ! -e "$dir" ] && ln -s "$MAIN_REPO/$dir" "$dir"
-done
+git checkout -b feature/[slug]
 ```
 
-> "Working in worktree: `.claude/worktrees/feature-[slug]/` on branch `feature-[slug]`"
+**Custom plan prompts:** If `.spartan/build.yaml` has `prompts.plan`, apply those instructions now.
 
 Write the first failing test for Task 1. Show it fails.
 
@@ -485,6 +562,8 @@ ls .planning/specs/*.md .planning/plans/*.md .planning/designs/*.md 2>/dev/null
 
 Classify each changed file into backend/frontend/migration using the `file-types` from config (or defaults: `.kt/.java/.go/.py` = backend, `.tsx/.ts/.vue` = frontend, `.sql` = migration).
 
+**Custom review prompts:** If `.spartan/build.yaml` has `prompts.review`, include those instructions in the review agent's prompt below — they're injected after the standard review stages.
+
 ### Step 3: Spawn the review agent
 
 Use the `Agent` tool to spawn a reviewer. **The prompt is built from the config.**
@@ -605,7 +684,7 @@ When the reviewer reports back:
 5. Spawn the review agent AGAIN with the updated diff — only the remaining/new changes need review
 6. Repeat until the reviewer says PASS
 
-**Max 3 review rounds.** If still failing after 3 rounds, stop and ask the user:
+**Max review rounds** (default: 3, configurable via `max-review-rounds` in `.spartan/build.yaml`). If still failing after max rounds, stop and ask the user:
 > "Review found issues I can't fully fix. Here's what's left: [list]. Want to continue anyway or address these manually?"
 
 ### Step 4: Capture review learnings
@@ -670,6 +749,8 @@ After review completes: `TeamDelete()` to clean up.
 
 ## Stage 6: Ship
 
+**Custom ship prompts:** If `.spartan/build.yaml` has `prompts.ship`, apply those instructions — PR naming rules, extra checks, deploy notes, etc.
+
 ### Create PR
 Run the approach from `/spartan:pr-ready`:
 - Rebase onto main
@@ -691,22 +772,6 @@ mkdir -p .memory/decisions .memory/patterns .memory/knowledge
 
 Update `.memory/index.md` if you saved anything.
 
-### Clean up worktree
-
-After the PR is created, exit the worktree. Keep it around in case the user needs to make PR review fixes:
-
-```
-ExitWorktree(action: "keep")
-```
-
-> "PR created. Worktree kept at `.claude/worktrees/feature-[slug]/` in case you need to push fixes. To clean up later: `git worktree remove .claude/worktrees/feature-[slug]`"
-
-If the user says the PR is merged and they're done, clean up:
-
-```
-ExitWorktree(action: "remove")
-```
-
 **GATE 4 — Done.**
 > "PR created: [link]. Here's what's in it: [summary]."
 
@@ -763,25 +828,18 @@ Agent(
 ```
 Collect results after all finish, then `TeamDelete()`.
 
-### Step 2: Sort by dependency and create workspace
+### Step 2: Sort by dependency
 
 Read the epic's Features table. Sort features by dependency order:
 - Features with no dependencies → can build first
 - Features that depend on others → build after their dependencies are done
 
-Create a worktree for the epic:
-
-```
-EnterWorktree(name: "feature-[epic-slug]")
-```
-
-Symlink shared directories:
+**If worktree enabled (default):** You should already be in a worktree from the "FIRST" step.
+**If `worktree: false`:** Create a branch: `git checkout -b feature/[epic-slug]`
 
 ```bash
-MAIN_REPO="$(git worktree list | head -1 | awk '{print $1}')"
-for dir in .planning .memory .handoff .spartan; do
-  [ -d "$MAIN_REPO/$dir" ] && [ ! -e "$dir" ] && ln -s "$MAIN_REPO/$dir" "$dir"
-done
+pwd
+git branch --show-current
 ```
 
 ### Step 3: Implement in dependency order
@@ -851,19 +909,13 @@ Run the full test suite. Then continue to **Stage 5: Review** — the review age
 If a previous session was interrupted (context overflow, user stopped, etc.), this workflow can resume.
 
 **How resume works:**
-1. Check for existing worktrees from a previous build:
-   ```bash
-   git worktree list
-   ls .claude/worktrees/ 2>/dev/null
-   ```
-   If a worktree exists for this feature, re-enter it with `EnterWorktree(name: "feature-[slug]")`. Don't create a new one.
-2. Step 0.5 checks for `.handoff/` files and existing `.planning/` artifacts
-3. Determine which stage was completed last:
+1. Step 0.5 checks for `.handoff/` files and existing `.planning/` artifacts
+2. Determine which stage was completed last:
    - Has spec but no plan → resume at Stage 3 (Plan)
    - Has plan but no commits on feature branch → resume at Stage 4 (Implement)
    - Has commits but no PR → resume at Stage 5 (Review) or Stage 6 (Ship)
-4. Show the user: "Resuming from [stage] in worktree `[path]`. Here's what was done: [summary]."
-5. Continue from that point.
+3. Show the user: "Resuming from [stage]. Here's what was done: [summary]."
+4. Continue from that point.
 
 **Don't re-do completed stages.** Read the saved artifacts and move forward.
 
@@ -886,8 +938,8 @@ If a previous session was interrupted (context overflow, user stopped, etc.), th
 - **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.
 - **Epic = one branch, one PR.** When building from an epic, all features go on one branch and ship as one PR. Don't create separate PRs per feature. Parallelize independent features with Agent Teams when available.
 - **Epic auto-detection.** If the user's feature name matches an epic in `.planning/epics/`, switch to epic mode automatically. Don't ask.
-- **Every build uses a worktree.** Always create a worktree with `EnterWorktree` before writing code. This lets multiple `/spartan:build` sessions run in parallel — each terminal gets its own worktree, branch, and PR. Never `git checkout -b` in the main repo.
-- **Worktree cleanup.** After PR is created, `ExitWorktree(action: "keep")` so the user can push fixes. After PR is merged, `ExitWorktree(action: "remove")` to clean up. Users can also clean up manually: `git worktree remove .claude/worktrees/feature-[slug]`.
+- **Worktree by default.** The first step is `EnterWorktree` (unless `worktree: false` in `.spartan/build.yaml`). This lets multiple terminals run `/spartan:build` simultaneously. If already in a worktree, skip. If `EnterWorktree` fails, fall back to manual worktree.
+- **Build config is `.spartan/build.yaml`.** Controls worktrees, branch prefix, max review rounds, skip stages, custom prompts per stage, and extra worktree symlinks. All fields optional.
 
 ---
 
@@ -921,3 +973,8 @@ A feature is NOT done until every applicable item is checked:
 - [ ] Atomic commits (one per task)
 - [ ] Review agent passed (all HIGH/MEDIUM issues fixed)
 - [ ] PR created with summary and test plan
+
+### Worktree
+- [ ] Worktree created and working directory switched (automatic unless `worktree: false`)
+- [ ] All commits pushed to feature branch
+- [ ] Worktree cleaned up after PR merged (`git worktree remove .claude/worktrees/[slug]`)

package/commands/spartan.md

@@ -48,6 +48,18 @@ This prevents confusion when the user is running multiple windows. Keep it to on
 
 ---
 
+## Step 0.9: Load Command Config (silent, always runs)
+
+Check for per-command custom prompts. Commands config lets users inject custom instructions into any Spartan command.
+
+```bash
+cat .spartan/commands.yaml 2>/dev/null || cat .spartan/commands.yml 2>/dev/null
+```
+
+If the file exists and has a `prompts.[command-name]` entry matching the command being routed to, pass those custom instructions to the command. They're appended after the built-in prompt.
+
+---
+
 ## Step 1: Detect Project Context (silent, no questions)
 
 Before asking anything, scan the environment:

package/package.json

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

package/packs/core.yaml

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

package/packs/packs.compiled.json

@@ -31,6 +31,7 @@
       ],
       "rules": [
         "core/NAMING_CONVENTIONS.md",
+        "core/TIMEZONE.md",
         "core/SKILL_AUTHORING.md"
       ],
       "skills": [],

package/rules/core/TIMEZONE.md

@@ -0,0 +1,261 @@
+# Timezone Rules
+
+## One Rule: Everything is UTC
+
+**Server stores UTC. API sends UTC. API receives UTC. No exceptions.**
+
+The frontend is the only place that converts to/from local time — and only for display.
+
+```
+Database (UTC) → Backend (UTC) → API JSON (UTC) → Frontend receives (UTC) → Display (local)
+                                                  ← Frontend sends (UTC) ←  Input (local → UTC)
+```
+
+---
+
+## Backend
+
+### Always Use `Instant` — Never `LocalDateTime`
+
+`Instant` is UTC by definition. `LocalDateTime` has no timezone info and leads to bugs.
+
+```kotlin
+// CORRECT — Instant is always UTC
+val now: Instant = Instant.now()
+val expiresAt: Instant = Instant.now().plusSeconds(3600)
+
+// WRONG — LocalDateTime has no timezone, ambiguous
+val now: LocalDateTime = LocalDateTime.now()  // What timezone? Nobody knows.
+val expiresAt: LocalDateTime = LocalDateTime.now().plusHours(1)
+```
+
+### Never Use `ZonedDateTime` in Business Logic
+
+`ZonedDateTime` is only for converting when absolutely needed (e.g., generating a report for a specific timezone). Don't pass it between layers.
+
+```kotlin
+// CORRECT — use Instant everywhere
+data class UserEntity(
+  val createdAt: Instant,
+  val lastLoginAt: Instant?,
+  val subscriptionExpiresAt: Instant?
+)
+
+// WRONG — ZonedDateTime in entities/DTOs
+data class UserEntity(
+  val createdAt: ZonedDateTime,   // NO — carries timezone baggage
+  val lastLoginAt: LocalDateTime? // NO — ambiguous
+)
+```
+
+### Never Store Timezone in the Database
+
+Don't add `timezone` columns. Don't save user timezone preferences alongside timestamps. If the frontend needs to display local time, it does the conversion itself.
+
+```sql
+-- CORRECT — just UTC timestamps
+CREATE TABLE events (
+  id UUID PRIMARY KEY,
+  starts_at TIMESTAMP NOT NULL,     -- UTC
+  ends_at TIMESTAMP NOT NULL,       -- UTC
+  created_at TIMESTAMP DEFAULT NOW() -- UTC
+);
+
+-- WRONG — storing timezone info
+CREATE TABLE events (
+  id UUID PRIMARY KEY,
+  starts_at TIMESTAMP NOT NULL,
+  ends_at TIMESTAMP NOT NULL,
+  timezone TEXT DEFAULT 'America/New_York'  -- DON'T DO THIS
+);
+```
+
+### Jackson Serialization
+
+Jackson must serialize all `Instant` fields as ISO 8601 with the `Z` (UTC) suffix. This should be configured globally:
+
+```kotlin
+// ObjectMapper config (usually already set)
+objectMapper.configure(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS, false)
+// Output: "2024-01-15T10:30:00Z"
+```
+
+Every datetime field in API JSON looks like: `"2024-01-15T10:30:00Z"`
+
+Never output offsets like `+07:00` or timezone names like `Asia/Ho_Chi_Minh`.
+
+---
+
+## API Contract
+
+### All Datetime Fields Are ISO 8601 UTC
+
+```json
+{
+  "created_at": "2024-01-15T10:30:00Z",
+  "updated_at": "2024-01-15T14:22:33Z",
+  "expires_at": "2024-02-15T00:00:00Z"
+}
+```
+
+### Request Bodies — Frontend Sends UTC
+
+When the frontend sends a datetime, it MUST be UTC:
+
+```json
+{
+  "starts_at": "2024-01-20T09:00:00Z",
+  "ends_at": "2024-01-20T17:00:00Z"
+}
+```
+
+### Query Parameters — Also UTC
+
+```
+GET /events?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z
+```
+
+### No Timezone Fields in Request or Response
+
+```json
+// WRONG — timezone info in API
+{
+  "starts_at": "2024-01-20T09:00:00Z",
+  "timezone": "America/New_York"
+}
+
+// CORRECT — just UTC, frontend handles display
+{
+  "starts_at": "2024-01-20T09:00:00Z"
+}
+```
+
+---
+
+## Frontend
+
+### Receive UTC, Convert for Display
+
+All API responses return UTC. Convert to local only when showing to the user:
+
+```typescript
+// CORRECT — convert at display time
+function formatDate(utcString: string): string {
+  return new Date(utcString).toLocaleString()
+  // Or use Intl.DateTimeFormat for more control
+}
+
+// CORRECT — with specific format
+function formatDate(utcString: string, locale = 'en-US'): string {
+  return new Intl.DateTimeFormat(locale, {
+    dateStyle: 'medium',
+    timeStyle: 'short',
+  }).format(new Date(utcString))
+}
+```
+
+### Send UTC to Server
+
+Convert local input to UTC before sending:
+
+```typescript
+// CORRECT — convert to UTC before API call
+const localDate = new Date(userInput)  // user picks "Jan 20, 2024 9:00 AM"
+const utcString = localDate.toISOString()  // "2024-01-20T02:00:00.000Z" (if user is UTC+7)
+
+await api.post('/events', {
+  startsAt: utcString,  // Always UTC
+})
+
+// WRONG — sending local time string
+await api.post('/events', {
+  startsAt: '2024-01-20T09:00:00',  // No Z suffix — ambiguous!
+})
+```
+
+### Date Libraries
+
+If using a date library (date-fns, dayjs, luxon), still follow the same pattern:
+
+```typescript
+// date-fns example
+import { formatInTimeZone } from 'date-fns-tz'
+
+// Display: UTC → user's local timezone
+const display = formatInTimeZone(
+  new Date(apiResponse.createdAt),  // UTC from API
+  Intl.DateTimeFormat().resolvedOptions().timeZone,  // user's timezone
+  'MMM d, yyyy h:mm a'
+)
+
+// Send: local → UTC
+const utc = new Date(localInput).toISOString()
+```
+
+### Never Store Timezone in Frontend State
+
+Don't track the user's timezone in state or send it to the backend. The browser already knows the timezone — use it at render time.
+
+```typescript
+// WRONG — tracking timezone in state
+const [timezone, setTimezone] = useState('America/New_York')
+
+// CORRECT — use browser timezone at render time
+const userTimezone = Intl.DateTimeFormat().resolvedOptions().timeZone
+```
+
+---
+
+## Database
+
+### TIMESTAMP Without Timezone
+
+Use `TIMESTAMP` (not `TIMESTAMPTZ`). The value is always UTC. No timezone info needed.
+
+```sql
+-- CORRECT
+created_at TIMESTAMP DEFAULT NOW()  -- NOW() returns UTC in a UTC-configured server
+
+-- ALSO ACCEPTABLE (PostgreSQL stores both as UTC internally)
+created_at TIMESTAMPTZ DEFAULT NOW()
+```
+
+### Server Must Be Configured for UTC
+
+The database server and application server must run in UTC:
+
+```yaml
+# application.yml
+datasources:
+  default:
+    connection-properties:
+      timezone: UTC
+```
+
+```sql
+-- PostgreSQL: verify server timezone
+SHOW timezone;  -- Should return 'UTC'
+```
+
+---
+
+## Quick Reference
+
+| Layer | Type | Format | Example |
+|-------|------|--------|---------|
+| Database | Column type | `TIMESTAMP` | `2024-01-15 10:30:00` |
+| Backend (Kotlin) | Property type | `Instant` | `Instant.now()` |
+| API JSON | String | ISO 8601 + Z | `"2024-01-15T10:30:00Z"` |
+| Frontend (receive) | Parse | `new Date(utcString)` | `new Date("2024-01-15T10:30:00Z")` |
+| Frontend (display) | Format | `toLocaleString()` | `"Jan 15, 2024, 5:30 PM"` (UTC+7) |
+| Frontend (send) | Serialize | `toISOString()` | `"2024-01-15T10:30:00.000Z"` |
+
+## What NOT to Do
+
+- Don't use `LocalDateTime` in Kotlin — use `Instant`
+- Don't store timezone names or offsets in the database
+- Don't send timezone info in API requests or responses
+- Don't use `TIMESTAMPTZ` thinking it "stores the timezone" — PostgreSQL converts everything to UTC anyway
+- Don't convert to local time on the backend — that's the frontend's job
+- Don't assume a timezone — let the browser handle it
+- Don't format dates on the server for display — return UTC, let the client format

package/templates/build-config.yaml

@@ -0,0 +1,63 @@
+# .spartan/build.yaml — Project-level build config
+# Copy this file to .spartan/build.yaml in your project and customize.
+# All fields are optional. Omit a field to use the default.
+
+# --- Worktree ---
+
+# Worktree isolation (default: true)
+# When true, /spartan:build creates a git worktree per feature.
+# Each terminal gets its own directory, branch, and PR — no conflicts.
+# Set to false to use simple git checkout (single terminal only).
+worktree: true
+
+# Branch prefix (default: "feature")
+# Controls the branch name: [prefix]/[slug] (e.g., "feature/user-auth")
+branch-prefix: "feature"
+
+# Extra directories to symlink into worktrees
+# Gitignored dirs (.planning, .memory, .handoff, .spartan) are always symlinked.
+# Add more here if your project has other shared gitignored dirs.
+# worktree-symlinks:
+#   - .env
+#   - config/local
+
+# --- Build stages ---
+
+# Max review-fix cycles before asking the user (default: 3)
+# max-review-rounds: 3
+
+# Stages to skip (use carefully — most stages exist for a reason)
+# Valid: spec, design, plan, review, ship
+# Note: review can never actually be skipped — it's always enforced
+# skip-stages: []
+
+# --- Custom prompts ---
+
+# Custom instructions injected into build stages.
+# Claude reads these alongside the built-in workflow instructions.
+# Use this to add project-specific rules, naming conventions, or checklists.
+prompts:
+  # Injected after spec questions, before scope is finalized
+  # spec: |
+  #   Always include performance requirements.
+  #   Ask about expected load/traffic.
+
+  # Injected into the plan stage, after the task list is generated
+  # plan: |
+  #   Every backend task must include a Flyway migration version check.
+  #   Frontend tasks must reference the Figma frame URL.
+
+  # Injected during implementation
+  # implement: |
+  #   Always add structured logging to new service methods.
+  #   Use the project's error code registry for new error types.
+
+  # Injected into the review agent's prompt
+  # review: |
+  #   Check that all API responses include request_id for tracing.
+  #   Verify that new endpoints have rate limiting annotations.
+
+  # Injected before PR creation
+  # ship: |
+  #   PR title must start with the Jira ticket number.
+  #   Add "Tested on staging" to the test plan if it touches payments.

package/templates/commands-config.yaml

@@ -0,0 +1,55 @@
+# .spartan/commands.yaml — Per-command overrides
+# Inject custom prompts into ANY Spartan command. Claude reads these
+# alongside the built-in instructions when the command runs.
+# All fields are optional.
+
+# --- Per-command prompt injection ---
+# Key = command name (without "spartan:" prefix)
+# Value = custom instructions appended to the command's prompt
+
+# prompts:
+#   spec: |
+#     Always ask about performance requirements.
+#     Include acceptance criteria in BDD format.
+#
+#   plan: |
+#     Tasks must reference Jira ticket numbers.
+#     Estimate hours per task.
+#
+#   review: |
+#     Check that all new endpoints have OpenAPI annotations.
+#     Flag any function longer than 50 lines.
+#
+#   pr-ready: |
+#     PR title format: [PROJ-123] Short description
+#     Always add "Reviewers: @backend-team" for backend changes.
+#
+#   daily: |
+#     Include blockers section.
+#     Tag items by project area (auth, payments, infra).
+#
+#   debug: |
+#     Always check CloudWatch logs first.
+#     Include the request_id in every investigation.
+#
+#   migration: |
+#     Migration files must start with ticket number.
+#     Always add a rollback section.
+#
+#   onboard: |
+#     Focus on the payments module first — it's the most complex.
+#     Skip the legacy admin/ directory.
+
+# --- Command defaults ---
+# Override default behavior for specific commands
+
+# defaults:
+#   build:
+#     worktree: true
+#     branch-prefix: "feature"
+#     max-review-rounds: 3
+#     skip-stages: []
+#   spec:
+#     save-path: ".planning/specs"  # where specs are saved
+#   review:
+#     parallel: true  # use Agent Teams for parallel review if available