orbital-command 0.3.0 → 1.0.0

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:

package/templates/skills/git-commit/SKILL.md

@@ -20,7 +20,8 @@ BRANCHING_MODE=$(grep '^WORKFLOW_BRANCHING_MODE=' .claude/config/workflow-manife
 ### Step 0b: Record Session ID
 
 1. Run: `bash .claude/hooks/get-session-id.sh`
-2. For each scope in `scopes/review/` with a passing verdict:
+2. For each scope in `scopes/review/` with a passing verdict
+   (if BATCH_SCOPE_IDS is set, only record on those specific scopes):
    - Append session UUID to `sessions.commit` in frontmatter
 
 ### Step 1: Check Branch
@@ -39,6 +40,9 @@ Find scopes in `scopes/review/` that have a passing verdict:
 
 1. List files in `scopes/review/*.md`
 2. For each, extract the scope number and check `.claude/review-verdicts/{NNN}.json`
+
+If BATCH_SCOPE_IDS is set, only process those specific scopes (skip any not in the list).
+
 3. If verdict exists and `verdict === "PASS"`:
    - Transition: `bash .claude/hooks/scope-transition.sh --from review --to completed --scope {NNN}`
    - Update DASHBOARD: `📦 **Status**: Committed`
@@ -49,25 +53,36 @@ Find scopes in `scopes/review/` that have a passing verdict:
 
 ### Step 3: Commit
 
+**Determine which files to stage** — scope-aware, not a blanket `git add .`:
+
+1. For each scope being committed (from Step 2), read its **Files Summary** table from the scope document (`scopes/review/{NNN}*.md` or `scopes/completed/{NNN}*.md`)
+2. Also check `.claude/review-findings/{NNN}.json` — each finding has a `file` field listing reviewed files
+3. Cross-reference against `git status` — only stage files that appear in the scope's Files Summary or review findings
+4. If files exist in `git status` that don't belong to any scope being committed, leave them unstaged
+
 ```bash
-git add <specific code files — scopes are gitignored>
+git add <files from scope Files Summary + review findings>
 git commit -m "type(scope): description"
 ```
 
-- Stage only code files (scopes/ is gitignored, no need to worry about them)
+- Stage only scope-owned code files (scopes/ is gitignored, no need to worry about them)
+- If multiple scopes are being committed (batch), include files from ALL scopes in the batch
 - Follow conventional commit format
 - Do NOT push or create PRs — those are separate skills
 
 ### Step 4: Signal Completion (REQUIRED)
 
-**Always emit after a successful commit** — this is not optional:
+**Always emit when finished** — this is not optional. Emit success or failure so the dispatch resolves immediately:
 
 ```bash
-# With a scope:
+# On success — with a scope:
 bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"save"}' --scope "{NNN}"
 
-# Without a scope (general commit):
+# On success — without a scope (general commit):
 bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"save"}'
+
+# On failure (commit failed, no files to stage, etc.):
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"failure","action":"save"}' --scope "{NNN}"
 ```
 
 The `--scope` flag is optional. Omit it when committing work that isn't tied to a specific scope.

package/templates/skills/git-dev/SKILL.md

@@ -19,7 +19,8 @@ Direct merge from feature branch into dev. The review gate already provides the
 ### Step 0: Record Session ID
 
 1. Run: `bash .claude/hooks/get-session-id.sh`
-2. For each scope in `scopes/completed/`:
+2. For each scope in `scopes/completed/`
+   (if BATCH_SCOPE_IDS is set, only record on those specific scopes):
    - Append session UUID to `sessions.prDev` in frontmatter
 
 ### Step 1: Verify Ready State
@@ -69,14 +70,17 @@ If merge conflicts occur, resolve them before continuing.
 
 ### Step 4: Signal Completion (REQUIRED)
 
-**Always emit after a successful merge** — this is not optional:
+**Always emit when finished** — this is not optional. Emit success or failure so the dispatch resolves immediately:
 
 ```bash
-# With a scope:
+# On success — with a scope:
 bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_dev"}' --scope "{NNN}"
 
-# Without a scope:
+# On success — without a scope:
 bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_dev"}'
+
+# On failure (merge conflicts, push rejected, etc.):
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"failure","action":"pr_dev"}' --scope "{NNN}"
 ```
 
 ## Output

package/templates/skills/git-main/SKILL.md

@@ -20,7 +20,8 @@ BRANCHING_MODE=$(grep '^WORKFLOW_BRANCHING_MODE=' .claude/config/workflow-manife
 ### Step 1: Record Session ID
 
 1. Run: `bash .claude/hooks/get-session-id.sh` — capture the UUID output
-2. For each scope in `scopes/completed/`:
+2. For each scope in `scopes/completed/`
+   (if BATCH_SCOPE_IDS is set, only record on those specific scopes):
    - Append session UUID to `sessions.pushToMain` in frontmatter
 
 ### Step 2: Check Current Branch
@@ -65,14 +66,17 @@ bash .claude/hooks/scope-transition.sh --from completed --to main --scope NNN
 
 ### Step 5: Signal Completion (REQUIRED)
 
-**Always emit after a successful push/PR** — this is not optional:
+**Always emit when finished** — this is not optional. Emit success or failure so the dispatch resolves immediately:
 
 ```bash
-# With a scope:
+# On success — with a scope:
 bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_main"}' --scope "{NNN}"
 
-# Without a scope:
+# On success — without a scope:
 bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_main"}'
+
+# On failure (push rejected, PR failed, merge conflicts, etc.):
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"failure","action":"pr_main"}' --scope "{NNN}"
 ```
 
 ## Batch Support

package/templates/skills/git-production/SKILL.md

@@ -98,14 +98,17 @@ gh pr merge --merge
 
 ### Step 6: Signal Completion (REQUIRED)
 
-**Always emit after a successful merge** — this is not optional:
+**Always emit when finished** — this is not optional. Emit success or failure so the dispatch resolves immediately:
 
 ```bash
-# With a scope:
+# On success — with a scope:
 bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_production"}' --scope "{NNN}"
 
-# Without a scope:
+# On success — without a scope:
 bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_production"}'
+
+# On failure (PR failed, merge conflicts, health check failed, etc.):
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"failure","action":"pr_production"}' --scope "{NNN}"
 ```
 
 ### Step 7: Verify Production

package/templates/skills/git-staging/SKILL.md

@@ -60,14 +60,17 @@ gh pr create --base staging --head dev \
 
 ### Step 4: Signal Completion (REQUIRED)
 
-**Always emit after a successful PR creation** — this is not optional:
+**Always emit when finished** — this is not optional. Emit success or failure so the dispatch resolves immediately:
 
 ```bash
-# With a scope:
+# On success — with a scope:
 bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_staging"}' --scope "{NNN}"
 
-# Without a scope:
+# On success — without a scope:
 bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_staging"}'
+
+# On failure (PR creation failed, push rejected, etc.):
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"failure","action":"pr_staging"}' --scope "{NNN}"
 ```
 
 ### Step 5: Monitor CI

package/templates/skills/scope-fix-review/SKILL.md

@@ -145,12 +145,16 @@ Agent(
 ╚═══════════════════════════════════════════════════════════════╝
 ```
 
-### Step 8: Emit Completion Event
+### Step 8: Signal Completion (REQUIRED)
+
+**Always emit when finished** — this is not optional. Emit success or failure so the dispatch resolves immediately:
 
 ```bash
-bash .claude/hooks/orbital-emit.sh REVIEW_FIXES_COMPLETED \
-  '{"scope_id":"NNN","findings_total":YY,"findings_fixed":XX,"agents_used":N}' \
-  --scope "NNN"
+# On success:
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"fix_review","findings_total":YY,"findings_fixed":XX}' --scope "{NNN}"
+
+# On failure (agents couldn't resolve, verification failed, etc.):
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"failure","action":"fix_review","findings_total":YY,"findings_fixed":XX}' --scope "{NNN}"
 ```
 
 ## Important Rules

package/templates/skills/scope-implement/SKILL.md

@@ -26,11 +26,15 @@ user-invocable: true
 
 ### 2. Implement
 
-**Before starting Phase 1**: Transition the scope and update the DASHBOARD to `🔄 **Status**: Implementing`:
+**Before starting Phase 1**: Read the scope's frontmatter `status` field. If the scope is not already in `implementing`, transition it and update the DASHBOARD to `🔄 **Status**: Implementing`:
+
 ```bash
-bash .claude/hooks/scope-transition.sh --from backlog --to implementing --scope {NNN}
+# Use the scope's CURRENT status as the source (backlog, planning, review, completed, etc.)
+bash .claude/hooks/scope-transition.sh --from <current-status> --to implementing --scope {NNN}
 ```
 
+If the scope is already `status: implementing` (resuming), skip the transition.
+
 For each phase:
 
 1. **Update DASHBOARD** — Mark phase as `🔄 In Progress`
@@ -92,12 +96,16 @@ After Step 3, the scope remains in `scopes/implementing/` with `status: implemen
 
 **Do NOT proceed to review in this session.** The review gate enforces session separation to ensure the implementing agent doesn't approve its own work.
 
-### 4. Signal Completion
+### 4. Signal Completion (REQUIRED)
 
-Emit the agent completion event so the Orbital Command dashboard turns off the progress indicator:
+**Always emit when finished** — this is not optional. Emit success or failure so the dispatch resolves immediately:
 
 ```bash
-bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success"}' --scope "{NNN}"
+# On success:
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"implement"}' --scope "{NNN}"
+
+# On failure (build errors, blocked, etc.):
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"failure","action":"implement"}' --scope "{NNN}"
 ```
 
 ## Resuming After Compaction

package/templates/skills/scope-post-review/SKILL.md

@@ -86,7 +86,10 @@ Ensure the project has a test suite before running quality gates. This runs in a
      ║  tests. Fix manually and re-run: /scope-post-review NNN     ║
      ╚═══════════════════════════════════════════════════════════════╝
      ```
-     **STOP** — do not proceed to Phase 1 with broken tests.
+     Emit failure and **STOP** — do not proceed to Phase 1 with broken tests:
+     ```bash
+     bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"failure","action":"post_review","phase":0}' --scope "{NNN}"
+     ```
    - **If tests pass** → continue to Phase 1.
 
 ### Phase 1: Quality Gates (`/test-checks`)
@@ -102,7 +105,10 @@ Run the 13 quality gates. This is the cheapest and fastest check.
    ║  Fix the failing gates and re-run: /scope-post-review NNN    ║
    ╚═══════════════════════════════════════════════════════════════╝
    ```
-   **STOP** — do not proceed to Phase 2.
+   Emit failure and **STOP** — do not proceed to Phase 2:
+   ```bash
+   bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"failure","action":"post_review","phase":1}' --scope "{NNN}"
+   ```
 3. If all gates PASS → continue to Phase 2.
 
 ### Phase 2: Formal Verification (`/scope-verify NNN`)
@@ -118,7 +124,10 @@ Run the scope-specific formal review gate.
    ║  Fix the issues and re-run: /scope-post-review NNN           ║
    ╚═══════════════════════════════════════════════════════════════╝
    ```
-   **STOP** — do not proceed to Phase 3.
+   Emit failure and **STOP** — do not proceed to Phase 3:
+   ```bash
+   bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"failure","action":"post_review","phase":2}' --scope "{NNN}"
+   ```
 3. If verdict is PASS → continue to Phase 3.
 
 ### Phase 3: AI Code Review (`/test-code-review`)
@@ -150,7 +159,10 @@ Execute all Phase 3 findings using a coordinated agent team. **This phase requir
      ```
      Skill(skill: "test-checks")
      ```
-     If any gate fails, report which gates regressed and **STOP**.
+     If any gate fails, report which gates regressed, emit failure and **STOP**:
+     ```bash
+     bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"failure","action":"post_review","phase":4}' --scope "{NNN}"
+     ```
 3. If **not enabled**:
    - Read `~/.claude/settings.json`
    - Merge `"env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }` into the existing JSON (preserve all other settings)

package/templates/skills/scope-pre-review/SKILL.md

@@ -196,12 +196,16 @@ After applying spec fixes and writing the AGENT REVIEW:
 - Update DASHBOARD Quick Status: `🟢 **Status**: Backlog | **Spec Locked**: Yes`
 - Add to Recent Activity: `Review completed — N blockers, M warnings. X items applied to spec, K clarifications resolved.`
 
-### Step 9: Signal Completion
+### Step 9: Signal Completion (REQUIRED)
 
-Emit the agent completion event so the Orbital Command dashboard turns off the progress indicator:
+**Always emit when finished** — this is not optional. Emit success or failure so the dispatch resolves immediately:
 
 ```bash
+# On success:
 bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"team_review"}' --scope "{NNN}"
+
+# On failure (agent launch failed, unrecoverable error, etc.):
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"failure","action":"team_review"}' --scope "{NNN}"
 ```
 
 ## Modes