orbital-command 0.2.0 → 1.0.0

package/templates/hooks/scope-prepare.sh

@@ -5,7 +5,7 @@
 # session recording, and gate cleanup into a single Bash call.
 #
 # Modes:
-#   --promote ID     Promote icebox idea to planning (renumber + move + scaffold)
+#   --promote SLUG|ID  Promote icebox idea to planning (renumber + move + scaffold)
 #   --scaffold ID    Apply template to existing planning scope
 #   --new            Create brand new scope
 #
@@ -13,6 +13,7 @@
 #   --title "..."    Scope title (required for --new)
 #   --desc "..."     Description / problem statement
 #   --category "..." Category tag (default: TBD)
+#   --effort "..."   Effort estimate (default: TBD)
 #
 # Output: JSON to stdout
 # Errors: to stderr
@@ -28,6 +29,7 @@ SOURCE_ID=""
 TITLE=""
 DESCRIPTION=""
 CATEGORY="TBD"
+EFFORT="TBD"
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -37,12 +39,13 @@ while [[ $# -gt 0 ]]; do
     --title)     TITLE="$2"; shift 2 ;;
     --desc)      DESCRIPTION="$2"; shift 2 ;;
     --category)  CATEGORY="$2"; shift 2 ;;
+    --effort)    EFFORT="$2"; shift 2 ;;
     *)           echo "Unknown argument: $1" >&2; exit 1 ;;
   esac
 done
 
 if [ -z "$MODE" ]; then
-  echo "Usage: scope-prepare.sh --promote ID | --scaffold ID | --new --title \"...\"" >&2
+  echo "Usage: scope-prepare.sh --promote SLUG|ID | --scaffold ID | --new --title \"...\"" >&2
   exit 1
 fi
 
@@ -77,13 +80,18 @@ fi
 
 # ─── Resolve source file + extract metadata ─────────────────────
 OLD_FILE=""
+FULL_BODY=""
 NOW_DATE=$(date +%Y-%m-%d)
 NOW_TIME=$(date +%H:%M)
 CREATED_DATE="$NOW_DATE"
 
 case "$MODE" in
   promote)
-    OLD_FILE=$(find_scope_by_id "$SOURCE_ID")
+    # Try slug-based lookup first (new format), fall back to numeric ID (legacy)
+    OLD_FILE=$(find_scope_by_slug "$SOURCE_ID")
+    if [ -z "$OLD_FILE" ] || [ ! -f "$OLD_FILE" ]; then
+      OLD_FILE=$(find_scope_by_id "$SOURCE_ID")
+    fi
     if [ -z "$OLD_FILE" ] || [ ! -f "$OLD_FILE" ]; then
       echo "Error: Scope $SOURCE_ID not found" >&2
       exit 2
@@ -92,13 +100,18 @@ case "$MODE" in
     # Preserve original created date
     orig_created=$(get_frontmatter "$OLD_FILE" "created")
     [ -n "$orig_created" ] && CREATED_DATE="$orig_created"
-    # Extract description from body (everything after frontmatter closing ---)
+    # Extract full body (everything after frontmatter closing ---) for template injection
+    FULL_BODY=$(awk 'BEGIN{fm=0} /^---$/{fm++; next} fm>=2{print}' "$OLD_FILE")
+    # Short description (first non-empty line) for JSON output
     if [ -z "$DESCRIPTION" ]; then
-      DESCRIPTION=$(awk 'BEGIN{fm=0} /^---$/{fm++; next} fm>=2{print}' "$OLD_FILE" | head -20 | sed '/^$/d' | head -5)
+      DESCRIPTION=$(printf '%s' "$FULL_BODY" | sed '/^$/d' | head -1)
     fi
     # Get category if set
     orig_cat=$(get_frontmatter "$OLD_FILE" "category")
     [ -n "$orig_cat" ] && [ "$orig_cat" != "TBD" ] && CATEGORY="$orig_cat"
+    # Get effort if set
+    orig_effort=$(get_frontmatter "$OLD_FILE" "effort_estimate")
+    [ -n "$orig_effort" ] && [ "$orig_effort" != "TBD" ] && EFFORT="$orig_effort"
     ;;
 
   scaffold)
@@ -110,11 +123,15 @@ case "$MODE" in
     [ -z "$TITLE" ] && TITLE=$(get_frontmatter "$OLD_FILE" "title")
     orig_created=$(get_frontmatter "$OLD_FILE" "created")
     [ -n "$orig_created" ] && CREATED_DATE="$orig_created"
+    # Extract full body for template injection
+    FULL_BODY=$(awk 'BEGIN{fm=0} /^---$/{fm++; next} fm>=2{print}' "$OLD_FILE")
     if [ -z "$DESCRIPTION" ]; then
-      DESCRIPTION=$(awk 'BEGIN{fm=0} /^---$/{fm++; next} fm>=2{print}' "$OLD_FILE" | head -20 | sed '/^$/d' | head -5)
+      DESCRIPTION=$(printf '%s' "$FULL_BODY" | sed '/^$/d' | head -1)
     fi
     orig_cat=$(get_frontmatter "$OLD_FILE" "category")
     [ -n "$orig_cat" ] && [ "$orig_cat" != "TBD" ] && CATEGORY="$orig_cat"
+    orig_effort=$(get_frontmatter "$OLD_FILE" "effort_estimate")
+    [ -n "$orig_effort" ] && [ "$orig_effort" != "TBD" ] && EFFORT="$orig_effort"
     ;;
 esac
 
@@ -130,6 +147,8 @@ compute_next_id() {
         local num
         num=$(basename "$f" | grep -oE '^[0-9]+' | sed 's/^0*//')
         [ -z "$num" ] && continue
+        # Skip legacy icebox-origin IDs (500+) to prevent namespace pollution
+        [ "$num" -ge 500 ] 2>/dev/null && continue
         [ "$num" -gt "$max_id" ] 2>/dev/null && max_id=$num
       done
     done
@@ -173,7 +192,7 @@ fi
 # ─── Template scaffolding ───────────────────────────────────────
 TEMPLATE="$SCOPE_PROJECT_DIR/scopes/_template.md"
 if [ ! -f "$TEMPLATE" ]; then
-  echo "Error: Template not found: $TEMPLATE (run 'orbital init' first)" >&2
+  echo "Error: Template not found: $TEMPLATE (run 'orbital' first)" >&2
   exit 3
 fi
 
@@ -199,6 +218,7 @@ sed \
   -e "s/^id: NNN/id: $PADDED_ID/" \
   -e "s/^title: \"Scope Title\"/title: \"$ESCAPED_TITLE\"/" \
   -e "s/^category: \"TBD\".*/category: \"$CATEGORY\"/" \
+  -e "s/^effort_estimate: \"TBD\".*/effort_estimate: \"$EFFORT\"/" \
   -e "s/^created: YYYY-MM-DD/created: $CREATED_DATE/" \
   -e "s/^updated: YYYY-MM-DD/updated: $NOW_DATE/" \
   -e "s/^sessions: {}.*/$SESSIONS_REPLACEMENT/" \
@@ -209,6 +229,29 @@ sed \
   -e "s/\[What prompted this exploration\]/$ESCAPED_DESC/" \
   "$TEMPLATE" > "$NEW_FILE"
 
+# ─── Inject full body into Overview section ────────────────────
+# When promoting/scaffolding, preserve the original idea body in the
+# SPECIFICATION > Overview section instead of losing it to the template.
+if [ -n "$FULL_BODY" ] && [ "$(printf '%s' "$FULL_BODY" | sed '/^[[:space:]]*$/d' | wc -l)" -gt 0 ]; then
+  BODY_TMP=$(mktemp)
+  printf '%s\n' "$FULL_BODY" > "$BODY_TMP"
+
+  awk -v bodyfile="$BODY_TMP" '
+    /^### Overview/ {
+      print
+      print ""
+      while ((getline line < bodyfile) > 0) print line
+      # Skip the original placeholder lines (blank + [Problem statement...])
+      getline  # blank line after ### Overview
+      getline  # [Problem statement...] line
+      next
+    }
+    { print }
+  ' "$NEW_FILE" > "${NEW_FILE}.tmp" && mv "${NEW_FILE}.tmp" "$NEW_FILE"
+
+  rm -f "$BODY_TMP"
+fi
+
 # ─── Cleanup old file (promote only) ────────────────────────────
 if [ "$MODE" = "promote" ] && [ -n "$OLD_FILE" ] && [ "$OLD_FILE" != "$NEW_FILE" ]; then
   rm -f "$OLD_FILE"
@@ -223,22 +266,34 @@ rm -f "$MARKER"
   "{\"scope_file\":\"$NEW_FILE\",\"id\":$SCOPE_ID,\"mode\":\"$MODE\"}" \
   --scope "$SCOPE_ID" --session "$SESSION_ID" 2>/dev/null &
 
+# ─── Read available categories from config ─────────────────────
+AVAILABLE_CATEGORIES=""
+CONFIG_FILE="$SCOPE_PROJECT_DIR/.claude/orbital.config.json"
+if command -v jq >/dev/null 2>&1 && [ -f "$CONFIG_FILE" ]; then
+  AVAILABLE_CATEGORIES=$(jq -r '.categories // [] | join(", ")' "$CONFIG_FILE" 2>/dev/null)
+fi
+EFFORT_BUCKETS="<1H, 1-4H, 4H+"
+
 # ─── JSON output ────────────────────────────────────────────────
 # Compute relative path
 REL_PATH="${NEW_FILE#"$SCOPE_PROJECT_DIR/"}"
 
 # Manual JSON construction (no jq dependency)
-printf '{"id":"%s","path":"%s","title":"%s","description":"%s","session_id":"%s","category":"%s","mode":"%s"}\n' \
+printf '{"id":"%s","path":"%s","title":"%s","description":"%s","session_id":"%s","category":"%s","effort":"%s","mode":"%s","available_categories":"%s","effort_buckets":"%s"}\n' \
   "$PADDED_ID" \
   "$REL_PATH" \
   "$(printf '%s' "$TITLE" | sed 's/"/\\"/g')" \
-  "$(printf '%s' "$DESCRIPTION" | head -1 | sed 's/"/\\"/g')" \
+  "$(printf '%s' "$DESCRIPTION" | sed 's/"/\\"/g')" \
   "$SESSION_ID" \
   "$CATEGORY" \
-  "$MODE"
+  "$EFFORT" \
+  "$MODE" \
+  "$AVAILABLE_CATEGORIES" \
+  "$EFFORT_BUCKETS"
 
 # Print reminder to stderr (visible to Claude but not parsed as JSON)
 echo "" >&2
-echo "Scope document written. Write gate lifted." >&2
-echo "Remember: STOP here. Implementation is a separate session:" >&2
+echo "Scope document scaffolded. Write gate lifted." >&2
+echo "Now proceed to Step 2: categorize and estimate effort." >&2
+echo "After specification is complete, STOP. Implementation is a separate session:" >&2
 echo "  /scope-implement $PADDED_ID" >&2

package/templates/hooks/scope-transition.sh

@@ -92,13 +92,21 @@ else
   exit 1
 fi
 
-# ─── File lock (flock-based, no TOCTOU race) ───
-LOCK_FILE="/tmp/orbital-scope-${SCOPE_ID:-all}.flock"
-exec 200>"$LOCK_FILE"
-if ! flock -n -x 200 2>/dev/null; then
-  echo "Scope ${SCOPE_ID:-all} locked by another process" >&2; exit 0
+# ─── File lock (flock on Linux, mkdir fallback on macOS) ───
+if command -v flock >/dev/null 2>&1; then
+  LOCK_FILE="/tmp/orbital-scope-${SCOPE_ID:-all}.flock"
+  exec 200>"$LOCK_FILE"
+  if ! flock -n -x 200 2>/dev/null; then
+    echo "Scope ${SCOPE_ID:-all} locked by another process" >&2; exit 0
+  fi
+  trap 'rm -f "$LOCK_FILE" 2>/dev/null' EXIT
+else
+  LOCK_DIR="/tmp/orbital-scope-${SCOPE_ID:-all}.lock"
+  if ! mkdir "$LOCK_DIR" 2>/dev/null; then
+    echo "Scope ${SCOPE_ID:-all} locked by another process" >&2; exit 0
+  fi
+  trap 'rmdir "$LOCK_DIR" 2>/dev/null' EXIT
 fi
-trap 'rm -f "$LOCK_FILE" 2>/dev/null' EXIT
 
 SOURCE_DIR="$SCOPE_PROJECT_DIR/scopes/$SOURCE_STATUS"
 TARGET_DIR="$SCOPE_PROJECT_DIR/scopes/$TARGET_STATUS"

package/templates/hooks/time-tracker.sh

@@ -13,12 +13,9 @@ NEW_STRING=$(echo "$INPUT" | jq -r '.tool_input.new_string // empty')
 source "$(dirname "$0")/scope-helpers.sh"
 is_scope_file "$FILE_PATH" || exit 0
 
-# Detect status transitions
+# Detect status transitions — match any status value, not a hardcoded list
 STATUS=""
-echo "$NEW_STRING" | grep -qiE "status:.*planning" && STATUS="planning"
-echo "$NEW_STRING" | grep -qiE "status:.*backlog" && STATUS="backlog"
-echo "$NEW_STRING" | grep -qiE "status:.*implementing" && STATUS="implementing"
-echo "$NEW_STRING" | grep -qiE "status:.*complete" && STATUS="complete"
+STATUS=$(echo "$NEW_STRING" | grep -oE '^status:[[:space:]]*[a-z][-a-z]*' | sed 's/^status:[[:space:]]*//' | head -1)
 echo "$NEW_STRING" | grep -qiE "🔄.*In Progress" && STATUS="phase_started"
 echo "$NEW_STRING" | grep -qiE "✅.*Done" && STATUS="phase_done"
 [ -z "$STATUS" ] && exit 0

package/templates/migrations/renames.json

@@ -0,0 +1 @@
+{}

package/templates/orbital.config.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://orbital-command.dev/schemas/orbital.config.schema.json",
+  "$schema": "https://raw.githubusercontent.com/SakaraLabs/orbital-command/main/schemas/orbital.config.schema.json",
   "projectName": "My Project",
   "scopesDir": "scopes",
   "eventsDir": ".claude/orbital-events",
@@ -19,10 +19,7 @@
     "typeCheck": null,
     "lint": null,
     "build": null,
-    "test": null,
-    "validateTemplates": null,
-    "validateDocs": null,
-    "checkRules": null
+    "test": null
   },
   "categories": ["feature", "bugfix", "refactor", "infrastructure", "docs"],
   "agents": [
@@ -31,5 +28,10 @@
     { "id": "frontend-designer", "label": "Frontend Designer", "emoji": "\ud83c\udfa8", "color": "#EC4899" },
     { "id": "architect", "label": "Architect", "emoji": "\ud83c\udfd7\ufe0f", "color": "#536dfe" },
     { "id": "rules-enforcer", "label": "Rules Enforcer", "emoji": "\ud83d\udccb", "color": "#6B7280" }
-  ]
+  ],
+  "telemetry": {
+    "enabled": true,
+    "url": "https://orbital-telemetry.mike-calle.workers.dev/ingest/a7f3x9k2m1",
+    "headers": {}
+  }
 }

package/{shared/default-workflow.json → templates/presets/default.json}

@@ -100,6 +100,7 @@
       "label": "Team Review",
       "description": "Runs full agent team review, locks spec, moves to backlog.",
       "dispatchOnly": true,
+      "autoRevert": true,
       "hooks": ["session-enforcer", "blocker-check", "dependency-check", "scope-transition", "orbital-scope-update"]
     },
     {
@@ -128,6 +129,7 @@
       "label": "Start Implementing",
       "description": "Opens a Claude session running /scope-implement.",
       "dispatchOnly": true,
+      "autoRevert": true,
       "hooks": ["session-enforcer", "blocker-check", "dependency-check", "scope-transition", "orbital-scope-update"]
     },
     {
@@ -139,6 +141,7 @@
       "label": "Launch Post-Review",
       "description": "Runs quality gates, formal verification, and code review.",
       "dispatchOnly": true,
+      "autoRevert": true,
       "hooks": ["session-enforcer", "review-gate-check", "blocker-check", "dependency-check", "scope-transition", "orbital-scope-update"]
     },
     {
@@ -179,6 +182,7 @@
       "label": "Commit",
       "description": "Commits scope work.",
       "dispatchOnly": true,
+      "autoRevert": true,
       "hooks": ["session-enforcer", "completion-checklist", "blocker-check", "dependency-check", "scope-transition", "orbital-scope-update", "scope-commit-logger"]
     },
     {
@@ -190,6 +194,7 @@
       "label": "Push to Main",
       "description": "Pushes or PRs scope work to the main branch.",
       "dispatchOnly": true,
+      "autoRevert": true,
       "hooks": ["session-enforcer", "blocker-check", "dependency-check", "scope-transition", "orbital-scope-update", "scope-commit-logger"]
     },
     {
@@ -248,6 +253,66 @@
       "dispatchOnly": false,
       "humanOnly": true,
       "hooks": ["session-enforcer", "scope-transition", "orbital-scope-update"]
+    },
+    {
+      "from": "backlog",
+      "to": "icebox",
+      "direction": "backward",
+      "command": null,
+      "confirmLevel": "quick",
+      "label": "Shelve to Icebox",
+      "description": "Shelves this scope back to the icebox for later consideration.",
+      "dispatchOnly": false,
+      "humanOnly": true,
+      "hooks": ["session-enforcer", "scope-transition", "orbital-scope-update"]
+    },
+    {
+      "from": "implementing",
+      "to": "icebox",
+      "direction": "backward",
+      "command": null,
+      "confirmLevel": "full",
+      "checklist": [
+        "No uncommitted work will be lost",
+        "This scope is being abandoned, not paused"
+      ],
+      "label": "Shelve to Icebox",
+      "description": "Abandons implementation and shelves this scope back to the icebox.",
+      "dispatchOnly": false,
+      "humanOnly": true,
+      "hooks": ["session-enforcer", "scope-transition", "orbital-scope-update"]
+    },
+    {
+      "from": "review",
+      "to": "icebox",
+      "direction": "backward",
+      "command": null,
+      "confirmLevel": "full",
+      "checklist": [
+        "No uncommitted work will be lost",
+        "This scope is being abandoned, not paused"
+      ],
+      "label": "Shelve to Icebox",
+      "description": "Abandons review and shelves this scope back to the icebox.",
+      "dispatchOnly": false,
+      "humanOnly": true,
+      "hooks": ["session-enforcer", "scope-transition", "orbital-scope-update"]
+    },
+    {
+      "from": "completed",
+      "to": "icebox",
+      "direction": "backward",
+      "command": null,
+      "confirmLevel": "full",
+      "checklist": [
+        "Committed work has been reverted or is acceptable to leave",
+        "This scope is being abandoned, not paused"
+      ],
+      "label": "Shelve to Icebox",
+      "description": "Shelves this completed scope back to the icebox.",
+      "dispatchOnly": false,
+      "humanOnly": true,
+      "hooks": ["session-enforcer", "scope-transition", "orbital-scope-update"]
     }
   ],
   "hooks": [

package/templates/presets/development.json

@@ -10,10 +10,10 @@
     { "id": "dev", "label": "Dev", "order": 4, "group": "deploy", "color": "197 100% 63%", "hex": "#42c3ff", "hasDirectory": true, "gitBranch": "dev" }
   ],
   "edges": [
-    { "from": "backlog", "to": "implementing", "direction": "forward", "command": "/scope-implement {id}", "confirmLevel": "quick", "label": "Start Implementing", "description": "Opens a Claude session running /scope-implement.", "dispatchOnly": true },
-    { "from": "implementing", "to": "review", "direction": "forward", "command": "/scope-post-review {id}", "confirmLevel": "full", "label": "Run Review Gate", "description": "Launches formal review gate.", "dispatchOnly": true },
-    { "from": "review", "to": "completed", "direction": "forward", "command": "/git-commit", "confirmLevel": "full", "label": "Commit", "description": "Commits scope work to feature branch.", "dispatchOnly": true },
-    { "from": "completed", "to": "dev", "direction": "forward", "command": "/git-dev", "confirmLevel": "full", "label": "Merge to Dev", "description": "Merges feature branch into dev.", "dispatchOnly": true },
+    { "from": "backlog", "to": "implementing", "direction": "forward", "command": "/scope-implement {id}", "confirmLevel": "quick", "label": "Start Implementing", "description": "Opens a Claude session running /scope-implement.", "dispatchOnly": true, "autoRevert": true },
+    { "from": "implementing", "to": "review", "direction": "forward", "command": "/scope-post-review {id}", "confirmLevel": "full", "label": "Run Review Gate", "description": "Launches formal review gate.", "dispatchOnly": true, "autoRevert": true },
+    { "from": "review", "to": "completed", "direction": "forward", "command": "/git-commit", "confirmLevel": "full", "label": "Commit", "description": "Commits scope work to feature branch.", "dispatchOnly": true, "autoRevert": true },
+    { "from": "completed", "to": "dev", "direction": "forward", "command": "/git-dev", "confirmLevel": "full", "label": "Merge to Dev", "description": "Merges feature branch into dev.", "dispatchOnly": true, "autoRevert": true },
     { "from": "review", "to": "implementing", "direction": "backward", "command": null, "confirmLevel": "quick", "label": "Back to Implementing", "description": "Re-opens implementation to address review findings.", "dispatchOnly": false },
     { "from": "completed", "to": "implementing", "direction": "backward", "command": null, "confirmLevel": "quick", "label": "Back to Implementing", "description": "Re-opens implementation to fix issues.", "dispatchOnly": false },
     { "from": "implementing", "to": "backlog", "direction": "backward", "command": null, "confirmLevel": "quick", "label": "Back to Backlog", "description": "Returns scope to backlog.", "dispatchOnly": false, "humanOnly": true }

package/templates/presets/gitflow.json

@@ -123,6 +123,7 @@
       "label": "Team Review",
       "description": "Runs full agent team review, locks spec, moves to backlog.",
       "dispatchOnly": true,
+      "autoRevert": true,
       "hooks": ["session-enforcer", "blocker-check", "dependency-check", "scope-transition", "orbital-scope-update"]
     },
     {
@@ -151,6 +152,7 @@
       "label": "Start Implementing",
       "description": "Opens a Claude session running /scope-implement.",
       "dispatchOnly": true,
+      "autoRevert": true,
       "hooks": ["session-enforcer", "blocker-check", "dependency-check", "scope-transition", "orbital-scope-update"]
     },
     {
@@ -162,6 +164,7 @@
       "label": "Run Review Gate",
       "description": "Launches formal review gate. Moves to review only if all criteria pass.",
       "dispatchOnly": true,
+      "autoRevert": true,
       "hooks": ["session-enforcer", "review-gate-check", "blocker-check", "dependency-check", "scope-transition", "orbital-scope-update"]
     },
     {
@@ -190,6 +193,7 @@
       "label": "Commit",
       "description": "Commits scope work to feature branch.",
       "dispatchOnly": true,
+      "autoRevert": true,
       "hooks": ["session-enforcer", "completion-checklist", "blocker-check", "dependency-check", "scope-transition", "orbital-scope-update", "scope-commit-logger"]
     },
     {
@@ -201,6 +205,7 @@
       "label": "Merge to Dev",
       "description": "Merges feature branch into dev. Batches multiple completed scopes.",
       "dispatchOnly": true,
+      "autoRevert": true,
       "hooks": ["session-enforcer", "blocker-check", "dependency-check", "scope-transition", "orbital-scope-update"]
     },
     {
@@ -212,6 +217,7 @@
       "label": "PR to Staging",
       "description": "Creates a GitHub PR from dev to staging.",
       "dispatchOnly": true,
+      "autoRevert": true,
       "hooks": ["session-enforcer", "lifecycle-gate", "blocker-check", "dependency-check", "scope-transition", "orbital-scope-update", "scope-commit-logger"]
     },
     {
@@ -228,6 +234,7 @@
       "label": "PR to Production",
       "description": "Creates a release PR from staging to main for production.",
       "dispatchOnly": true,
+      "autoRevert": true,
       "hooks": ["session-enforcer", "lifecycle-gate", "blocker-check", "dependency-check", "scope-transition", "orbital-scope-update", "scope-commit-logger"]
     },
     {

package/templates/prompts/README.md

@@ -0,0 +1,23 @@
+# Prompt Library
+
+Tested, refined prompts for common high-stakes tasks. Each prompt encodes lessons learned from real sessions — the framing, constraints, and structure that produce the best results.
+
+## How to Use
+
+Copy the prompt and paste it at the start of a new Claude Code session. Adjust the bracketed `[placeholders]` to your context.
+
+## Available Prompts
+
+| Prompt | When to Use |
+|--------|-------------|
+| [deep-dive-audit.md](./deep-dive-audit.md) | Pre-launch codebase health review, major refactoring, tech debt assessment |
+
+## Prompt Design Principles
+
+These prompts are optimized for Claude Code sessions. Key patterns:
+
+1. **Explicit permission to be thorough** — override the default pressure to be fast
+2. **Scope boundary upfront** — tell it whether analysis only or implementation included
+3. **Verification requirement built in** — don't add this as an afterthought
+4. **Output format defined** — what "done" looks like
+5. **Resource permission** — explicitly allow parallel agents, long context, high token usage

package/templates/prompts/deep-dive-audit.md

@@ -0,0 +1,94 @@
+# Deep Dive Codebase Audit
+
+**When to use:** Pre-launch reviews, major refactoring, tech debt assessment, periodic health checks.
+
+**Session setup:** Start in plan mode (`/plan`), set effort to max (`/effort max`).
+
+---
+
+## The Prompt
+
+```
+Conduct a deep, thorough audit of our codebase. This is a [pre-launch review / periodic health check / tech debt assessment] and we will implement all confirmed findings — not just analyze them.
+
+SCOPE AND EXPECTATIONS:
+
+- Leave no file untouched. We value thoroughness and 100% coverage over speed.
+- Take as long as you need. Slow down. Resist the urge to start editing before you've finished reading.
+- Use resources freely — launch parallel exploration agents, analysis agents, and implementation agents. Do not optimize for token cost; optimize for coverage and correctness.
+- Every change must be independently verified before we consider it done. Build verification into your plan, not as an afterthought.
+
+DELIVERABLES:
+
+1. Build a complete inventory of every section, service, and function. Track progress in the plan file.
+2. Create a brief summary of each — how they work and how they're architected.
+3. Conduct deep analysis: identify duplication, structural issues, dead code, and simplification opportunities. Quantify everything — "15 hooks duplicate this pattern" not "some hooks are duplicated."
+4. Produce a tiered recommendation plan: Tier 1 (high impact, low risk), Tier 2 (high impact, moderate effort), Tier 3 (discuss first), and explicitly state what you considered but don't recommend.
+5. After implementation, produce a before/after metrics table and a verification report with pass/fail counts.
+
+WORKFLOW:
+
+- Do NOT write any code until the plan is reviewed and confirmed together. The plan is a separate deliverable from the implementation.
+- During exploration (plan mode): use subagents for parallel coverage. Create lists that track progress.
+- During implementation (after plan approval): execute one tier at a time. Typecheck and test after every individual change. Use parallel agents only for independent file sets.
+- After implementation: launch independent verification agents to prove each work item is correct. Run the full validation pipeline. Do UI testing if frontend was modified.
+
+[ADDITIONAL CONTEXT: describe any specific concerns, recent feature work, or areas you suspect need attention]
+```
+
+---
+
+## Why Each Section Exists
+
+### "Leave no file untouched" + "take as long as you need"
+Overrides the default pressure to be fast and concise. Without this, the agent samples a few files and pattern-matches. With it, the agent inventories everything, which is what finds unexpected results like "zero dead code."
+
+### "Do not optimize for token cost"
+Explicitly permits launching 3+ parallel agents per phase. Without this, the agent tries to do everything sequentially in one context window, which caps the achievable scope.
+
+### "Every change must be independently verified"
+Knowing verification is coming makes the agent more careful during implementation. This instruction must be in the initial prompt, not added after implementation is done.
+
+### "Do NOT write any code until the plan is reviewed"
+Forces the audit-then-plan-then-execute structure. Prevents the failure mode where the agent starts editing during exploration and introduces bugs while still forming its understanding.
+
+### "Quantify everything"
+Prevents vague findings. "Some duplication" is not actionable. "15 hooks with identical fetch boilerplate across 500 lines" is actionable and lets you evaluate ROI.
+
+### "Explicitly state what you don't recommend"
+Shows the agent considered and rejected options rather than missing them. The "Not recommended" section in a plan is often the most valuable — it prevents future sessions from re-investigating the same ideas.
+
+### Deliverable 5 (before/after + verification)
+Defines what "done" looks like. Without this, the session ends with "I think everything is good" instead of "23/23 test files, 374/374 tests, 279 verification checks."
+
+---
+
+## Variations
+
+### Analysis Only (No Implementation)
+Remove the "we will implement all confirmed findings" line and deliverable 5. Change the workflow section to end at plan delivery.
+
+### Targeted Audit (Specific Area)
+Add to additional context:
+```
+Focus on [server/hooks/frontend components]. The rest of the codebase is out of scope for this session.
+```
+
+### Post-Incident Review
+Replace the scope section with:
+```
+We just had [describe incident]. Audit the codebase for similar patterns that could cause the same class of problem. Don't fix unrelated issues — stay focused on this failure mode.
+```
+
+---
+
+## Origin
+
+Developed during the v0.3 pre-launch refactoring session (2026-04-10). That session achieved:
+- 10 files decomposed (avg 832 → 291 lines, 65% reduction)
+- 5 shared abstractions created (useFetch, useSocketListener, workflow-constants, json-fields, catchRoute)
+- 40 new tests added
+- 279 manual verification checks, all passing
+- 23/23 UI checks across 4 views, zero console errors
+
+The prompt structure — explicit permission to slow down, free resource usage, mandatory verification, plan-before-code discipline — was identified as the primary driver of the session's quality.

package/templates/quick/rules.md

@@ -52,14 +52,14 @@ grep -rE "console\.(log|error|warn|info)" src --include="*.ts" --include="*.tsx"
 
 ### Rule 3: File Size Limit (400 lines)
 
-**Rule**: Production files must be < 400 lines, tests < 800 lines
-**Why**: Maintainability, cognitive load
+**Rule**: Production files must be < 400 lines, tests < 800 lines. Applies to `src/`, `server/`, and `bin/`.
+**Why**: The v0.3 refactor found 10 files over 500 lines. Large files mix concerns, resist review, and accumulate tech debt silently. The cleanup took a full session to unwind.
 **Verify**:
 ```bash
-find src -name "*.ts" -o -name "*.tsx" | xargs wc -l | awk '$1 > 400' | grep -v __tests__
+find src server -name "*.ts" -o -name "*.tsx" | xargs wc -l | sort -rn | awk '$1 > 400 && !/test|__fixtures__/' | head -20
 ```
-**Expected**: No output
-**Fix**: Split into focused modules
+**Expected**: No output (or only justified exceptions like types/index.ts, aggregate-routes.ts)
+**Fix**: Extract sub-components, split into focused modules, move types to companion files
 
 ---
 
@@ -202,6 +202,57 @@ it('should return user by ID', async () => {
 
 ---
 
+## Duplication Prevention Rules
+
+### Rule 13: Single Source of Truth for Constants
+
+**Rule**: Color maps, config objects, icon maps, and display constants must be defined once and imported everywhere. Never define inline.
+**Why**: The v0.3 audit found ENFORCEMENT_COLORS defined 3x, CATEGORY_CONFIG 4x, and CATEGORY_HEX 2x across the codebase. Each copy drifted slightly (singular vs plural labels, different lifecycle colors).
+**Verify**:
+```bash
+grep -rn "const.*COLORS.*Record\|const.*CONFIG.*Record.*icon\|const.*HEX.*Record" src/components src/views --include="*.tsx" --include="*.ts" | grep -v "import "
+```
+**Expected**: No output — all constants come from `src/lib/workflow-constants.ts` or similar shared modules
+**Fix**: Move to `src/lib/workflow-constants.ts` and import
+
+---
+
+### Rule 14: Use Shared Hook Primitives
+
+**Rule**: Data-fetching hooks must use `useFetch()`. Socket listeners must use `useSocketListener()`. Never duplicate the fetch lifecycle or socket.on/off pattern manually.
+**Why**: The v0.3 audit found 15+ hooks with identical fetch boilerplate (useState triple, AbortController, useReconnect) and 86 manual socket.on/off calls. This was ~500 lines of pure duplication.
+**Verify**:
+```bash
+# Check no hook manually manages AbortController (should be in useFetch)
+grep -rn "new AbortController" src/hooks --include="*.ts" | grep -v useFetch | grep -v test
+```
+**Expected**: No output (only useFetch.ts should create AbortControllers)
+**Fix**: Use `useFetch(fetchFn)` for data fetching, `useSocketListener(event, handler, deps)` for socket events
+
+---
+
+### Rule 15: Use catchRoute for Express Handlers
+
+**Rule**: Route handlers that can throw must use `catchRoute()` from `server/utils/route-helpers.ts` instead of inline try-catch.
+**Why**: The v0.3 audit found identical try-catch + errMsg + status-inference blocks in 7+ route handlers. The pattern is mechanical and should be centralized.
+**Verify**:
+```bash
+grep -rn "try {" server/routes --include="*.ts" | grep -v test | grep -v node_modules
+```
+**Expected**: Minimal matches — most routes should use catchRoute
+**Fix**: Wrap handler with `catchRoute(fn)` or `catchRoute(fn, inferErrorStatus)`
+
+---
+
+### Rule 16: No Inline Utility Functions in Large Files
+
+**Rule**: Pure functions (parsers, formatters, validators) that don't close over component/hook state must live in companion `*-utils.ts` files, not inline in the consuming file.
+**Why**: The v0.3 audit found `parseJsonFields` copied verbatim between two files, and `parseDragId` + `checkActiveDispatch` buried inside a 490-line hook. Extracting them enabled testing and reuse.
+**Verify**: Manual review — if a function doesn't reference `useState`, `useCallback`, or local state, it belongs in a utils file
+**Fix**: Extract to a companion file (e.g., `useKanbanDnd.ts` → `kanban-dnd-utils.ts`)
+
+---
+
 ## Quick Verification Checklist
 
 Run before every commit: