@c0x12c/spartan-ai-toolkit 1.9.1 → 1.9.2

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.9.1"
+      "version": "1.9.2"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "spartan-ai-toolkit",
-  "version": "1.9.1",
+  "version": "1.9.2",
   "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

@@ -359,24 +359,6 @@ 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/`:
@@ -386,11 +368,9 @@ Customize any Spartan command per project. Two config files in `.spartan/`:
 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: |

package/VERSION

@@ -1 +1 @@
-1.9.1
+1.9.2

package/commands/spartan/build.md

@@ -14,22 +14,23 @@ You decide which steps to run, which skills to call, and when to move forward. T
 ```
 SINGLE FEATURE:
 
-  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
+  Context → Spec → Design? → Plan+Worktree → Implement → Review Agent → Fix → Ship
+     │        │        │           │               │            │          │       │
+  .memory/ Gate 1   Design   git worktree       Gate 3    Spawn agent   Loop   Gate 4
+                    Gate     .worktrees/slug              fix until OK
 
 EPIC (multi-feature — auto-detected):
 
-  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
+  Context → Epic → Per feature: Spec/Design/Plan → Worktree → Implement → Review → Ship
+     │        │            │                           │            │          │       │
+  .planning/ read epic  fill gaps                git worktree  parallel    Loop   one PR
+  epics/                                        .worktrees/     by dep
 
-PARALLEL BUILDS (automatic — each build in its own worktree):
+PARALLEL (multiple terminals — automatic):
 
-  /spartan:build auth     → worktree .claude/worktrees/feature-auth/     → PR #1
-  /spartan:build payments → worktree .claude/worktrees/feature-payments/ → PR #2
+  Terminal 1: /spartan:build auth     → .worktrees/auth/     (feature/auth)     → PR #1
+  Terminal 2: /spartan:build payments → .worktrees/payments/  (feature/payments) → PR #2
+  (each gets its own worktree, branch, and PR — no conflicts, no manual setup)
 ```
 
 **Fast path:** For small work (< 1 day, ≤ 4 tasks), you do spec + plan inline. No separate commands needed.
@@ -51,9 +52,7 @@ PARALLEL BUILDS (automatic — each build in its own worktree):
 
 ---
 
-## FIRST: Load Build Config & Enter Worktree
-
-### Load project build config
+## FIRST: Load Build Config (silent — no questions)
 
 Check for a project-level build config that overrides default behavior:
 
@@ -65,11 +64,9 @@ If `.spartan/build.yaml` exists, read it and apply overrides. All fields are opt
 
 | 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 |
+| `skip-stages` | `[]` | Stages to skip. Valid: `spec`, `design`, `plan`, `ship`. Never `review`. |
 | `prompts.spec` | — | Custom instructions injected after spec questions |
 | `prompts.plan` | — | Custom instructions injected into the plan stage |
 | `prompts.implement` | — | Custom instructions injected during implementation |
@@ -80,55 +77,6 @@ If `.spartan/build.yaml` exists, read it and apply overrides. All fields are opt
 
 **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)
@@ -359,23 +307,47 @@ 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.
 
-### Verify workspace
+### Create feature workspace
+
+Each build runs in its own **git worktree** — a separate directory with its own branch. This happens automatically. The user doesn't set anything up. Multiple terminals running `/spartan:build` get separate worktrees, branches, and PRs.
 
-Confirm you're in the right place:
+Use `branch-prefix` from config (default: `feature`). Generate a slug from the feature name.
 
 ```bash
-pwd
-git branch --show-current
-```
+SLUG="[slug]"
+BRANCH="feature/$SLUG"
+MAIN_REPO="$(git rev-parse --show-toplevel)"
+WORKSPACE="$MAIN_REPO/.worktrees/$SLUG"
+
+# Create worktree (or reuse if resuming)
+if [ -d "$WORKSPACE" ]; then
+  echo "RESUMING: Worktree exists at $WORKSPACE"
+else
+  git worktree add "$WORKSPACE" -b "$BRANCH" 2>/dev/null || git worktree add "$WORKSPACE" "$BRANCH"
+fi
+
+# Symlink shared dirs (gitignored, won't appear in worktree)
+for dir in .planning .memory .handoff .spartan; do
+  [ -d "$MAIN_REPO/$dir" ] && [ ! -e "$WORKSPACE/$dir" ] && ln -s "$MAIN_REPO/$dir" "$WORKSPACE/$dir"
+done
 
-**If worktree is enabled (default):** You should already be in a worktree from the "FIRST" step. If not, go back and create one.
+# Copy .env if exists (API keys, secrets)
+[ -f "$MAIN_REPO/.env" ] && [ ! -f "$WORKSPACE/.env" ] && cp "$MAIN_REPO/.env" "$WORKSPACE/.env"
 
-**If `worktree: false` in config:** Create a branch now:
+# Gitignore worktrees dir
+grep -qxF '.worktrees/' "$MAIN_REPO/.gitignore" 2>/dev/null || echo '.worktrees/' >> "$MAIN_REPO/.gitignore"
 
-```bash
-git checkout -b feature/[slug]
+echo "WORKSPACE=$WORKSPACE"
+echo "BRANCH=$BRANCH"
 ```
 
+**From this point, ALL work happens in `$WORKSPACE`:**
+- Bash commands: `cd $WORKSPACE && ./gradlew test`
+- File reads/writes: use `$WORKSPACE/src/...` absolute paths
+- Git operations: `git -C $WORKSPACE ...`
+
+> "Working in: `$WORKSPACE` on branch `$BRANCH`"
+
 **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.
@@ -772,6 +744,20 @@ mkdir -p .memory/decisions .memory/patterns .memory/knowledge
 
 Update `.memory/index.md` if you saved anything.
 
+### Clean up worktree
+
+After PR is created, the worktree stays in case the user needs to push review fixes. Tell the user:
+
+> "PR created. Worktree at `.worktrees/[slug]` is still active for review fixes."
+
+When the user says the PR is merged:
+
+```bash
+MAIN_REPO="$(git worktree list | head -1 | awk '{print $1}')"
+git -C "$MAIN_REPO" worktree remove ".worktrees/[slug]" --force 2>/dev/null
+git -C "$MAIN_REPO" worktree prune 2>/dev/null
+```
+
 **GATE 4 — Done.**
 > "PR created: [link]. Here's what's in it: [summary]."
 
@@ -828,20 +814,30 @@ Agent(
 ```
 Collect results after all finish, then `TeamDelete()`.
 
-### Step 2: Sort by dependency
+### Step 2: Sort by dependency and create workspace
 
 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
 
-**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]`
+Create a worktree for the epic (same pattern as single-feature builds):
 
 ```bash
-pwd
-git branch --show-current
+SLUG="[epic-slug]"
+BRANCH="feature/$SLUG"
+MAIN_REPO="$(git rev-parse --show-toplevel)"
+WORKSPACE="$MAIN_REPO/.worktrees/$SLUG"
+
+git worktree add "$WORKSPACE" -b "$BRANCH" 2>/dev/null || git worktree add "$WORKSPACE" "$BRANCH"
+
+for dir in .planning .memory .handoff .spartan; do
+  [ -d "$MAIN_REPO/$dir" ] && [ ! -e "$WORKSPACE/$dir" ] && ln -s "$MAIN_REPO/$dir" "$WORKSPACE/$dir"
+done
+[ -f "$MAIN_REPO/.env" ] && [ ! -f "$WORKSPACE/.env" ] && cp "$MAIN_REPO/.env" "$WORKSPACE/.env"
 ```
 
+All epic work happens in `$WORKSPACE`.
+
 ### Step 3: Implement in dependency order
 
 Go through features in dependency order. **When 2+ features have no dependency between them, build them at the same time using Agent Teams** (if enabled). Otherwise build one by one.
@@ -909,13 +905,19 @@ 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. Step 0.5 checks for `.handoff/` files and existing `.planning/` artifacts
-2. Determine which stage was completed last:
+1. Check for existing worktrees from a previous build:
+   ```bash
+   ls .worktrees/ 2>/dev/null
+   git worktree list 2>/dev/null
+   ```
+   If a worktree exists for this feature, set `WORKSPACE` to it and work there. 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:
    - 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)
-3. Show the user: "Resuming from [stage]. Here's what was done: [summary]."
-4. Continue from that point.
+4. Show the user: "Resuming from [stage] in `$WORKSPACE`. Here's what was done: [summary]."
+5. Continue from that point.
 
 **Don't re-do completed stages.** Read the saved artifacts and move forward.
 
@@ -938,8 +940,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.
-- **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.
+- **Build config is `.spartan/build.yaml`.** Controls branch prefix, max review rounds, skip stages, and custom prompts per stage. All fields optional.
+- **Every build creates a worktree automatically.** `git worktree add .worktrees/[slug]` runs at Stage 3. All work happens in the worktree using `$WORKSPACE` paths. Multiple terminals get separate worktrees, branches, and PRs. No conflicts. Cleanup happens after PR merge.
 
 ---
 
@@ -974,7 +976,3 @@ A feature is NOT done until every applicable item is checked:
 - [ ] 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/package.json

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

package/rules/core/TIMEZONE.md

@@ -4,20 +4,80 @@
 
 **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.
+The frontend is the only place that converts to/from local time — for display only.
 
 ```
-Database (UTC) → Backend (UTC) → API JSON (UTC) → Frontend receives (UTC) → Display (local)
-                                                  ← Frontend sends (UTC) ←  Input (local → UTC)
+Database (TIMESTAMPTZ/UTC) → Backend (Instant/UTC) → API JSON (ISO 8601 Z) → Frontend (UTC) → Display (local)
+                                                                              ← Send (local → UTC) ←  Input
 ```
 
 ---
 
-## Backend
+## Database
+
+### Use `TIMESTAMPTZ` — Not `TIMESTAMP`
+
+**Always use `TIMESTAMPTZ` (with timezone).** PostgreSQL docs and wiki both say this.
+
+Why: `TIMESTAMPTZ` converts to UTC on insert and converts back on read. If a connection has a non-UTC session timezone (DBA tools, connection pool quirks, migration scripts), `TIMESTAMPTZ` still stores the correct UTC value. `TIMESTAMP` without timezone silently stores whatever you give it — if the session isn't UTC, you get wrong data and can't tell.
+
+```sql
+-- CORRECT — TIMESTAMPTZ is the safe default
+CREATE TABLE events (
+  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+  starts_at TIMESTAMPTZ NOT NULL,
+  ends_at TIMESTAMPTZ NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ,
+  deleted_at TIMESTAMPTZ
+);
+
+-- WRONG — TIMESTAMP without timezone is fragile
+CREATE TABLE events (
+  id UUID PRIMARY KEY,
+  starts_at TIMESTAMP NOT NULL,  -- Breaks if session timezone isn't UTC
+  created_at TIMESTAMP DEFAULT NOW()
+);
+```
+
+Both types use 8 bytes internally. No storage difference.
+
+### Server Must Run in UTC
+
+The database server, application server, and all containers must run in UTC:
+
+```yaml
+# application.yml
+datasources:
+  default:
+    connection-properties:
+      timezone: UTC
+```
+
+```sql
+-- PostgreSQL: verify
+SHOW timezone;  -- Should return 'UTC'
+```
+
+```dockerfile
+# Dockerfile
+ENV TZ=UTC
+```
+
+```yaml
+# Kubernetes pod spec
+env:
+  - name: TZ
+    value: "UTC"
+```
+
+---
+
+## Backend (Kotlin)
 
 ### Always Use `Instant` — Never `LocalDateTime`
 
-`Instant` is UTC by definition. `LocalDateTime` has no timezone info and leads to bugs.
+`Instant` is UTC by definition. `LocalDateTime` has no timezone info and causes bugs.
 
 ```kotlin
 // CORRECT — Instant is always UTC
@@ -26,63 +86,48 @@ 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` — Only at Computation Boundaries
+
+Never put `ZonedDateTime` in entities, DTOs, or API payloads. It's OK for:
+- Scheduling logic (computing "next 9 AM in user's timezone")
+- DST-aware date arithmetic ("add 1 day" at DST boundary)
+- Generating reports in a specific timezone
 
-`ZonedDateTime` is only for converting when absolutely needed (e.g., generating a report for a specific timezone). Don't pass it between layers.
+Always convert back to `Instant` before passing to other layers.
 
 ```kotlin
-// CORRECT — use Instant everywhere
+// CORRECT — entities and DTOs use Instant
 data class UserEntity(
   val createdAt: Instant,
   val lastLoginAt: Instant?,
   val subscriptionExpiresAt: Instant?
 )
 
-// WRONG — ZonedDateTime in entities/DTOs
+// CORRECT — ZonedDateTime only for scheduling computation
+fun nextNotificationTime(userTimezone: String, localTime: LocalTime): Instant {
+  val zone = ZoneId.of(userTimezone)
+  val nextLocal = ZonedDateTime.now(zone).with(localTime)
+  return nextLocal.toInstant()  // Convert back to Instant
+}
+
+// WRONG — ZonedDateTime in entity
 data class UserEntity(
-  val createdAt: ZonedDateTime,   // NO — carries timezone baggage
-  val lastLoginAt: LocalDateTime? // NO — ambiguous
+  val createdAt: ZonedDateTime  // NO — keep entities in Instant
 )
 ```
 
-### 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:
+Jackson must serialize `Instant` as ISO 8601 with the `Z` suffix:
 
 ```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`.
+Never output offsets like `+07:00` or timezone names in API responses.
 
 ---
 
@@ -100,8 +145,6 @@ Never output offsets like `+07:00` or timezone names like `Asia/Ho_Chi_Minh`.
 
 ### Request Bodies — Frontend Sends UTC
 
-When the frontend sends a datetime, it MUST be UTC:
-
 ```json
 {
   "starts_at": "2024-01-20T09:00:00Z",
@@ -115,19 +158,16 @@ When the frontend sends a datetime, it MUST be UTC:
 GET /events?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z
 ```
 
-### No Timezone Fields in Request or Response
+### No Timezone Fields in Timestamp Payloads
+
+Don't put timezone info alongside timestamps. The exception is user preferences (see below).
 
 ```json
-// WRONG — timezone info in API
-{
-  "starts_at": "2024-01-20T09:00:00Z",
-  "timezone": "America/New_York"
-}
+// WRONG — timezone alongside a timestamp
+{ "starts_at": "2024-01-20T09:00:00Z", "timezone": "America/New_York" }
 
-// CORRECT — just UTC, frontend handles display
-{
-  "starts_at": "2024-01-20T09:00:00Z"
-}
+// CORRECT — just UTC
+{ "starts_at": "2024-01-20T09:00:00Z" }
 ```
 
 ---
@@ -136,18 +176,10 @@ GET /events?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z
 
 ### 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
+// 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, {
+  return new Intl.DateTimeFormat(undefined, {
     dateStyle: 'medium',
     timeStyle: 'short',
   }).format(new Date(utcString))
@@ -156,106 +188,129 @@ function formatDate(utcString: string, locale = 'en-US'): string {
 
 ### 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!
-})
+// Convert local input to UTC before API call
+const localDate = new Date(userInput)
+const utcString = localDate.toISOString()  // "2024-01-20T02:00:00.000Z"
+
+await api.post('/events', { startsAt: utcString })
+
+// WRONG — no Z suffix, ambiguous
+await api.post('/events', { startsAt: '2024-01-20T09:00:00' })
 ```
 
-### Date Libraries
+### Use Browser Timezone at Render Time
 
-If using a date library (date-fns, dayjs, luxon), still follow the same pattern:
+Don't track the user's timezone in frontend state. The browser already knows it.
 
 ```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'
-)
+// CORRECT — use at render time
+const userTz = Intl.DateTimeFormat().resolvedOptions().timeZone
 
-// Send: local → UTC
-const utc = new Date(localInput).toISOString()
+// WRONG — storing timezone in state
+const [timezone, setTimezone] = useState('America/New_York')
 ```
 
-### 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.
+## When You DO Need Timezone
 
-```typescript
-// WRONG — tracking timezone in state
-const [timezone, setTimezone] = useState('America/New_York')
+There are cases where storing a user's IANA timezone is correct. The rule is:
+
+**Past events (created_at, login_at, order_placed_at):** Never store timezone. `TIMESTAMPTZ` (UTC) is enough.
+
+**User preferences (notification time, business hours):** Store the user's IANA timezone as a separate column. Don't mix it with timestamps.
+
+```sql
+-- CORRECT — timezone as a user preference, not part of timestamps
+CREATE TABLE user_preferences (
+  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+  user_id UUID NOT NULL,
+  timezone TEXT NOT NULL DEFAULT 'UTC',          -- IANA timezone: 'America/New_York'
+  notification_time TEXT NOT NULL DEFAULT '09:00', -- local time, not a timestamp
+  created_at TIMESTAMPTZ DEFAULT NOW()
+);
 
-// CORRECT — use browser timezone at render time
-const userTimezone = Intl.DateTimeFormat().resolvedOptions().timeZone
+-- Then compute UTC fire time dynamically in code:
+-- nextFire = ZonedDateTime.of(today, LocalTime.parse("09:00"), ZoneId.of("America/New_York")).toInstant()
 ```
 
+**Why dynamic computation?** Because DST shifts change the UTC offset. "9 AM New York" is `14:00 UTC` in winter but `13:00 UTC` in summer. Storing a fixed UTC value would drift by an hour.
+
+**Never use fixed offsets as timezone identifiers.** `+05:30` is an offset, not a timezone. It changes with DST. Use IANA names: `Asia/Kolkata`, `America/New_York`.
+
 ---
 
-## Database
+## Microservices
 
-### TIMESTAMP Without Timezone
+### Inter-Service Communication
 
-Use `TIMESTAMP` (not `TIMESTAMPTZ`). The value is always UTC. No timezone info needed.
+All service-to-service datetime fields use ISO 8601 UTC, same as external APIs.
 
-```sql
--- CORRECT
-created_at TIMESTAMP DEFAULT NOW()  -- NOW() returns UTC in a UTC-configured server
+### Event Streaming (Kafka, RabbitMQ)
 
--- ALSO ACCEPTABLE (PostgreSQL stores both as UTC internally)
-created_at TIMESTAMPTZ DEFAULT NOW()
-```
+- Use epoch-based types: Avro `timestamp-millis`, Protobuf `google.protobuf.Timestamp`
+- These are UTC by definition — no timezone ambiguity
+- Document in your schema that all timestamps are UTC epoch
 
-### Server Must Be Configured for UTC
+### Logging
 
-The database server and application server must run in UTC:
+All services must log in UTC. If services in different timezones log in local time, correlating logs across services is a nightmare.
 
-```yaml
-# application.yml
-datasources:
-  default:
-    connection-properties:
-      timezone: UTC
+```xml
+<!-- logback.xml — force UTC -->
+<timestamp key="timestamp" datePattern="yyyy-MM-dd'T'HH:mm:ss.SSS'Z'" timeReference="UTC"/>
 ```
 
-```sql
--- PostgreSQL: verify server timezone
-SHOW timezone;  -- Should return 'UTC'
+### Distributed Tracing
+
+OpenTelemetry spans use nanosecond UTC timestamps internally. No action needed — but make sure NTP is configured on all nodes. Clock skew (not timezone) is the bigger concern.
+
+### Cron / Scheduler Jobs
+
+Cron expressions are timezone-sensitive. DST transitions can cause jobs to fire twice, or not at all, in the 1-3 AM window.
+
+```kotlin
+// CORRECT — schedule in UTC to avoid DST issues
+@Scheduled(cron = "0 0 14 * * *", zone = "UTC")  // 2 PM UTC, not "2 PM local"
+fun dailyDigest() { ... }
+
+// If the job MUST fire at local wall-clock time, use IANA timezone explicitly:
+@Scheduled(cron = "0 0 9 * * *", zone = "America/New_York")  // 9 AM New York, DST-aware
+fun morningNotification() { ... }
 ```
 
+Avoid scheduling jobs in the 1:00-3:00 AM local time window for any timezone with DST.
+
+### IANA Timezone Database Updates
+
+Governments change DST rules. Your JVM and OS timezone databases need updating. If you run long-lived JVMs, update the JDK or use the TZUpdater tool.
+
 ---
 
 ## Quick Reference
 
 | Layer | Type | Format | Example |
 |-------|------|--------|---------|
-| Database | Column type | `TIMESTAMP` | `2024-01-15 10:30:00` |
+| Database | Column type | `TIMESTAMPTZ` | `2024-01-15 10:30:00+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 (display) | Format | `Intl.DateTimeFormat` | `"Jan 15, 2024, 5:30 PM"` |
 | Frontend (send) | Serialize | `toISOString()` | `"2024-01-15T10:30:00.000Z"` |
+| Events (Kafka) | Type | epoch millis | `1705312200000` |
+| Cron jobs | Zone | IANA or UTC | `zone = "UTC"` |
+| User preference | Column | IANA timezone | `America/New_York` |
 
 ## What NOT to Do
 
+- Don't use `TIMESTAMP` without timezone — use `TIMESTAMPTZ`
 - 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 put `ZonedDateTime` in entities or DTOs
+- Don't use fixed offsets (`+05:30`) as timezone identifiers — use IANA names
+- Don't store timezone alongside timestamps for past events
 - 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
+- Don't schedule cron jobs in the 1-3 AM DST window
+- Don't assume the host timezone is UTC — set `TZ=UTC` in containers
+- Don't log in local time — all services log UTC

package/rules/database/SCHEMA.md

@@ -15,13 +15,13 @@
 - **No ON DELETE CASCADE** — Handle deletions in application
 - **TEXT not VARCHAR** — Always use TEXT for strings
 - **UUID primary keys** — `uuid_generate_v4()`
-- **Soft delete** — Use `deleted_at TIMESTAMP`, never hard delete records
+- **Soft delete** — Use `deleted_at TIMESTAMPTZ`, never hard delete records
 - Standard columns: `id`, `created_at`, `updated_at`, `deleted_at`
 
 ### Data Type Standards
 - Strings: TEXT (not VARCHAR)
 - IDs: UUID
-- Dates: TIMESTAMP
+- Dates: TIMESTAMPTZ (all timestamps are UTC, see `TIMEZONE.md`)
 - Booleans: BOOLEAN
 - Flexible data: JSONB
 - IP addresses: INET
@@ -107,9 +107,9 @@ CREATE TABLE products (
     id UUID PRIMARY KEY,
     name TEXT NOT NULL,
     status TEXT DEFAULT 'active',
-    created_at TIMESTAMP DEFAULT NOW(),
-    updated_at TIMESTAMP,
-    deleted_at TIMESTAMP
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    updated_at TIMESTAMPTZ,
+    deleted_at TIMESTAMPTZ
 );
 ```
 

package/templates/build-config.yaml

@@ -2,37 +2,18 @@
 # 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
+# Valid: spec, design, plan, ship
+# Note: review can never 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.