orbital-command 0.1.0

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

@@ -0,0 +1,81 @@
+---
+name: scope-create
+description: Creates structured scope documents for planned work with clear phases and success criteria. Use when planning features, scoping work, or documenting requirements.
+user-invocable: true
+---
+
+# /scope-create - Create a Unified Scope Document
+
+Creates a three-part scope document (Dashboard / Specification / Process) in `scopes/planning/`.
+All mechanical work (file lookup, ID assignment, template scaffolding, session recording, gate cleanup)
+is handled by a single `scope-prepare.sh` call.
+
+## Post-Plan Workflow
+
+When invoked during plan mode:
+1. Plan mode handles exploration (write findings to plan file)
+2. After plan approval (ExitPlanMode), a hook reminds you to write the scope
+3. Run Step 1 below, then fill SPECIFICATION from your plan findings in Step 2
+4. **Stop.** Report the scope number. Implementation is `/scope-implement NNN` in a new session.
+
+## Execution
+
+### Step 1: Prepare Scope File
+
+One Bash call handles everything: finds the file, assigns a sequential ID (renumbering
+from icebox range if needed), scaffolds the full template, records the session UUID,
+and lifts the write gate.
+
+**If a scope number is provided** (e.g., `/scope-create 511`):
+
+```bash
+# For icebox ideas (ID >= 500) — promotes, renumbers, and scaffolds:
+bash .claude/hooks/scope-prepare.sh --promote 511
+
+# For existing planning scopes (ID < 500) — applies template to existing file:
+bash .claude/hooks/scope-prepare.sh --scaffold 106
+```
+
+**If no argument** — ask the user for:
+1. **Feature name**: Short descriptive name
+2. **What does it do?**: 1-2 sentence description
+3. **Category**: e.g., Backend, Frontend, Tooling, Infrastructure
+
+Then run:
+```bash
+bash .claude/hooks/scope-prepare.sh --new --title "Feature Name" --desc "Description" --category "Backend"
+```
+
+The script outputs JSON: `{"id", "path", "title", "description", "session_id", "category", "mode"}`.
+The scope file is fully scaffolded with template, frontmatter, dashboard, and process log.
+
+### Step 2: Fill Specification
+
+Edit the scope file to replace the placeholder in **SPECIFICATION > Overview** with the
+actual problem statement and goal. If coming from a plan, also populate:
+- **Requirements** (Must Have / Nice to Have / Out of Scope)
+- **Technical Approach** and rationale
+- **Implementation Phases** with files, changes, and verification steps
+
+### Step 3: Report
+
+```
+Created: scopes/planning/NNN-feature-name.md
+
+Structure:
+  PART 1: DASHBOARD  — Status: Planning
+  PART 2: SPECIFICATION — Overview filled (complete during planning)
+  PART 3: PROCESS — First exploration session started
+
+Next steps:
+1. Explore the codebase to understand current state
+2. Fill in SPECIFICATION (requirements, phases, files)
+3. Run `/scope-pre-review` to get agent team feedback
+4. Lock spec and begin implementation with `/scope-implement NNN`
+```
+
+## Tips
+
+- **Don't over-plan**: Start exploring, let the spec emerge
+- **Capture decisions**: Use the Decisions & Reasoning section
+- **Log uncertainties**: They help future sessions understand confidence levels

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

@@ -0,0 +1,168 @@
+---
+name: scope-fix-review
+description: Executes all code review findings from Phase 3 using a coordinated agent team. Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
+user-invocable: true
+agent-mode: team
+requires: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
+---
+
+# /scope-fix-review NNN — Fix All Code Review Findings With Agent Team
+
+Takes ALL findings from the Phase 3 code review (`/test-code-review`) and executes fixes using a coordinated agent team. Each teammate owns a non-overlapping slice of the codebase to avoid conflicts.
+
+## Prerequisites
+
+- Phase 3 (`/test-code-review`) must have been run in the current post-review pipeline
+- Code review findings must exist in the conversation context
+- `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` must be enabled (a hook will block this skill otherwise)
+
+## Steps
+
+### Step 0: Record Session ID
+
+1. Run: `bash .claude/hooks/get-session-id.sh` — capture the UUID output
+2. Find the scope file: `scopes/review/*{NNN}*.md` (primary) or `scopes/implementing/*{NNN}*.md`
+3. Read the scope file's YAML frontmatter `sessions` field
+4. If `sessions:` key doesn't exist in frontmatter, add `sessions: {}` after `tags:`
+5. If the UUID is NOT already in `sessions.fixReview`, append it (skip if duplicate)
+6. Write the updated frontmatter back to the scope file
+
+### Step 1: Validate Environment
+
+1. Confirm agent teams are enabled — if the hook didn't catch it, verify:
+   ```bash
+   echo "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not set}"
+   ```
+   If not set to `1`:
+   - Read `~/.claude/settings.json`
+   - Merge `"env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }` into the existing JSON (preserve all other settings)
+   - Write the updated file back to `~/.claude/settings.json`
+   - Inform the user the setting was enabled and they need to restart the session for it to take effect
+   - **STOP** — the env var won't be available until the next session
+
+### Step 2: Collect and Organize Findings
+
+1. Gather ALL findings from the Phase 3 code review (from conversation context)
+2. Deduplicate findings across the 6 review agents
+3. Group findings by **file ownership domain**:
+
+| Domain | File Patterns | Typical Agent Name |
+|--------|--------------|-------------------|
+| Server | `server/**/*.ts` | `server-agent` |
+| Frontend | `src/**/*.{ts,tsx}` (excluding `src/types/`) | `frontend-agent` |
+| Shared/Types | `shared/**/*.ts`, `src/types/**/*.ts` | `types-agent` |
+| CLI/Templates | `bin/**/*.js`, `templates/**/*` | `templates-agent` |
+
+4. Within each domain, order findings by severity: CRITICAL > HIGH > MEDIUM > LOW
+5. Identify cross-domain dependencies (e.g., type changes that require import updates)
+
+### Step 3: Create the Agent Team
+
+```
+TeamCreate(team_name: "review-fixes", description: "Fix all Phase 3 code review findings")
+```
+
+### Step 4: Create Tasks With Dependencies
+
+Create one task per domain group. Each task description MUST include:
+- Every finding in that domain with file path, line number, and exact fix
+- Severity level for prioritization
+- The agent's file ownership boundary (what it can and cannot modify)
+
+**Dependency rules:**
+- Server, Frontend, and CLI/Templates tasks can run in parallel (no file overlap)
+- Types/Shared task should be blocked by Server task (if both modify `server/services/` files)
+- A final Verification task should be blocked by ALL other tasks
+
+**Verification task** (always last):
+```
+TaskCreate(
+  subject: "Run typecheck and build verification",
+  description: "Run tsc --noEmit, tsc --noEmit -p tsconfig.server.json, vite build, and bash -n on all shell scripts. Fix any compilation errors."
+)
+```
+
+### Step 5: Spawn Teammates
+
+Spawn one teammate per domain that has findings. Each teammate prompt MUST include:
+
+1. **File ownership boundary** — explicit list of directories/files they own
+2. **Instruction to NOT modify** files outside their ownership
+3. **Instruction to read files BEFORE editing** (other agents may be modifying nearby files)
+4. **The task number(s) to claim**
+5. **Mode**: `bypassPermissions`
+
+**Example spawn:**
+```
+Agent(
+  name: "server-agent",
+  team_name: "review-fixes",
+  mode: "bypassPermissions",
+  prompt: "You are on the review-fixes team. You own server/ files ONLY.
+           Claim task #1. Read each file before editing. Do not modify shared/, src/, bin/, or templates/."
+)
+```
+
+**Guidelines for team size:**
+- Only spawn agents for domains that have findings
+- 2-4 agents is typical (one per domain with findings)
+- Do NOT spawn agents for domains with no findings
+
+### Step 6: Monitor and Coordinate
+
+1. As teammates complete tasks, check if blocked tasks are now unblocked
+2. When the Types/Shared task unblocks, spawn the types agent (or assign if already spawned)
+3. Shut down teammates as they finish (`shutdown_request`)
+4. When all implementation tasks complete, handle the Verification task yourself:
+   - Run `tsc --noEmit` (client + shared)
+   - Run `tsc --noEmit -p tsconfig.server.json` (server + shared)
+   - Run `vite build` (production build)
+   - Run `bash -n` on any modified shell scripts
+   - Fix any type errors introduced by teammates
+
+### Step 7: Report Results
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║  /scope-fix-review COMPLETE — Scope NNN                      ║
+╠═══════════════════════════════════════════════════════════════╣
+║                                                               ║
+║  Findings addressed: XX / YY                                  ║
+║  Tasks completed:    N / N                                    ║
+║  Typecheck:          ✅ PASSED                                ║
+║  Build:              ✅ PASSED                                ║
+║                                                               ║
+║  Agents used:                                                 ║
+║    server-agent:     [N findings fixed]                       ║
+║    frontend-agent:   [N findings fixed]                       ║
+║    types-agent:      [N findings fixed]                       ║
+║    templates-agent:  [N findings fixed]                       ║
+║                                                               ║
+║  Next: /git-commit                                            ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+### Step 8: Emit Completion Event
+
+```bash
+bash .claude/hooks/orbital-emit.sh REVIEW_FIXES_COMPLETED \
+  '{"scope_id":"NNN","findings_total":YY,"findings_fixed":XX,"agents_used":N}' \
+  --scope "NNN"
+```
+
+## Important Rules
+
+1. **Never use parallel subagents** (`Agent` with `run_in_background`) — always use `TeamCreate` + `Agent` with `team_name`
+2. **File ownership is sacred** — each agent MUST stay within its domain boundary
+3. **Read before edit** — agents MUST read files before modifying them
+4. **Verify at the end** — always run typecheck + build after all agents finish
+5. **Shut down agents cleanly** — send `shutdown_request` when each agent finishes
+6. **Dependencies matter** — types/shared changes should happen AFTER server changes if they touch the same files
+
+## On Failure
+
+If teammates encounter errors they cannot resolve:
+1. The teammate should message the team lead with the specific error
+2. The team lead can provide guidance or reassign the task
+3. If a fix is infeasible, log it as a remaining finding in the final report
+4. The skill still completes — unresolvable findings are reported, not blocking

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

@@ -0,0 +1,110 @@
+---
+name: scope-implement
+description: Executes scope documents end-to-end following defined phases and checkpoints. Use when ready to implement a scoped feature, executing planned work, or following a scope.
+user-invocable: true
+---
+
+# /scope-implement - Execute a Scope
+
+## Workflow
+
+### 0. Record Session ID
+
+1. Run: `bash .claude/hooks/get-session-id.sh` — capture the UUID output
+2. Read the scope file's YAML frontmatter `sessions` field
+3. If `sessions:` key doesn't exist in frontmatter, add `sessions: {}` after `tags:`
+4. If the UUID is NOT already in `sessions.implementScope`, append it (skip if duplicate)
+5. Write the updated frontmatter back to the scope file
+
+### 1. Read Scope
+
+- Read `scopes/*{NNN}*.md` or `scopes/implementing/*{NNN}*.md` (also check `scopes/backlog/`)
+- Understand: goal, files affected, phases, success criteria
+- Check DASHBOARD for current progress (resuming?)
+- Check PROCESS Implementation Log for prior work
+- Create todo list for tracking
+
+### 2. Implement
+
+**Before starting Phase 1**: Update scope frontmatter to `status: implementing` and DASHBOARD to `🔄 **Status**: Implementing`. Move file: `mv scopes/backlog/{file} scopes/implementing/`.
+
+For each phase:
+
+1. **Update DASHBOARD** — Mark phase as `🔄 In Progress`
+2. **Execute** the phase changes
+3. **Verify** — Run configured verification commands from `.claude/orbital.config.json`:
+      - Run `commands.typeCheck` (if configured, skip if null)
+      - Run `commands.build` (if configured, skip if null)
+4. **Log** — Append to PROCESS Implementation Log:
+   ```markdown
+   ### Phase N: Completed YYYY-MM-DD HH:MM
+   - [What was done]
+   - [Issues encountered, if any]
+   - Commit: `hash`
+   - Time: X minutes
+   ```
+5. **Update DASHBOARD** — Mark phase as `✅ Done`
+
+If deviating from spec:
+- Document in PROCESS > Deviations from Spec section
+- Include: what was specified, what was done, why
+
+### 3. Validate
+
+- Run configured verification commands from `.claude/orbital.config.json`:
+  - Read `.claude/orbital.config.json` for commands configuration
+  - Run `commands.typeCheck` (if configured, skip if null)
+  - Run `commands.lint` (if configured, skip if null)
+  - Run `commands.build` (if configured, skip if null)
+  - Run `commands.test` (if configured, skip if null)
+- Fix any issues found
+
+**Self-assess Definition of Done** — before finishing, honestly evaluate each DoD item:
+
+1. Read the `### Definition of Done` section in the scope document
+2. For each `- [ ]` item, determine whether it was genuinely completed and verified during this implementation
+3. Check `- [x]` items that you can confirm are true (e.g., you ran the build and it passed)
+4. **Leave unchecked** `- [ ]` any items you did NOT complete or cannot verify — do not assume
+5. If any items remain unchecked, explain why in PROCESS > Implementation Log
+
+This self-assessment is what the reviewer will use to gauge completeness. Be honest — unchecked items are fine and expected when something couldn't be verified (e.g., "Visual verification in browser"). Checking a box you didn't verify is worse than leaving it unchecked.
+
+- Update DASHBOARD to `🏁 **Status**: Implemented | Awaiting Review`
+- **Keep the file in `scopes/implementing/`** — do NOT move to review or update frontmatter status
+
+### Implementation Complete
+
+After Step 3, the scope remains in `scopes/implementing/` with `status: implementing`. Output:
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║  Implementation complete. Scope ready for review.            ║
+║                                                              ║
+║  Next: /scope-verify {NNN} (in a NEW session)                ║
+║                                                              ║
+║  The review gate must be run by a different session           ║
+║  than the one that implemented the scope.                    ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+**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
+
+Emit the agent completion event so the Orbital Command dashboard turns off the progress indicator:
+
+```bash
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success"}' --scope "{NNN}"
+```
+
+## Resuming After Compaction
+
+1. Read scope doc (check `scopes/implementing/`, `scopes/backlog/`, and `scopes/`)
+2. Check DASHBOARD for current phase status
+3. Check PROCESS Implementation Log for last completed phase
+4. Check git status for uncommitted work
+5. Resume from next pending phase
+
+## Agent Selection Guide
+
+Select agents based on the project's `.claude/config/agent-triggers.json` configuration. The trigger file maps file patterns to the agents that should review changes in those areas.

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

@@ -0,0 +1,144 @@
+---
+name: scope-post-review
+description: Orchestrates post-implementation review — runs quality gates, formal verification, code review, and optional agent-team fix execution. Use when a scope is ready to move from implementing to review.
+user-invocable: true
+orchestrates: [test-checks, scope-verify, test-code-review, scope-fix-review]
+---
+
+# /scope-post-review NNN — Post-Implementation Review
+
+Orchestrates the full post-implementation review pipeline for a scope. Runs up to four phases sequentially — each must pass before the next begins.
+
+## Pipeline
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     /scope-post-review NNN                      │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  Phase 1: /test-checks                                         │
+│  └── 13 machine-verifiable quality gates                       │
+│      Types, lint, build, templates, docs, enforcement, etc.    │
+│      MUST PASS before proceeding.                              │
+│                                                                 │
+│  Phase 2: /scope-verify NNN                                    │
+│  └── Formal review gate                                        │
+│      Session separation, spec compliance, no follow-on work    │
+│      Writes verdict file. MUST PASS before proceeding.         │
+│                                                                 │
+│  Phase 3: /test-code-review                                    │
+│  └── 6 parallel AI code review agents                          │
+│      code-reviewer, silent-failure-hunter, code-simplifier,    │
+│      comment-analyzer, pr-test-analyzer, type-design-analyzer  │
+│      Reports findings. Proceeds to Phase 4 if findings exist.  │
+│                                                                 │
+│  Phase 4: /scope-fix-review NNN (if agent teams enabled)       │
+│  └── Coordinated agent team fixes all Phase 3 findings         │
+│      Groups by file ownership, spawns teammates, verifies.     │
+│      Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.          │
+│      Skipped if no findings or agent teams not enabled.        │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Rationale**: Quality gates run first to catch obvious issues cheaply. Spec verification runs second to confirm the implementation is actually complete before spending tokens on AI code review. Code review runs third on verified, passing code. Fix execution runs last, using an agent team to address all findings in parallel across non-overlapping file domains.
+
+## Steps
+
+### Phase 1: Quality Gates (`/test-checks`)
+
+Run the 13 quality gates. This is the cheapest and fastest check.
+
+1. Invoke: `Skill(skill: "test-checks")`
+2. If any gates FAIL:
+   ```
+   ╔═══════════════════════════════════════════════════════════════╗
+   ║  Phase 1 FAILED — Quality gates did not pass                 ║
+   ║                                                               ║
+   ║  Fix the failing gates and re-run: /scope-post-review NNN    ║
+   ╚═══════════════════════════════════════════════════════════════╝
+   ```
+   **STOP** — do not proceed to Phase 2.
+3. If all gates PASS → continue to Phase 2.
+
+### Phase 2: Formal Verification (`/scope-verify NNN`)
+
+Run the scope-specific formal review gate.
+
+1. Invoke: `Skill(skill: "scope-verify", args: "NNN")`
+2. If verdict is FAIL:
+   ```
+   ╔═══════════════════════════════════════════════════════════════╗
+   ║  Phase 2 FAILED — Scope verification did not pass            ║
+   ║                                                               ║
+   ║  Fix the issues and re-run: /scope-post-review NNN           ║
+   ╚═══════════════════════════════════════════════════════════════╝
+   ```
+   **STOP** — do not proceed to Phase 3.
+3. If verdict is PASS → continue to Phase 3.
+
+### Phase 3: AI Code Review (`/test-code-review`)
+
+Run the 6 parallel code review agents on the verified code.
+
+1. Invoke: `Skill(skill: "test-code-review")`
+2. Collect all findings — count BLOCKERS, WARNINGS, and SUGGESTIONS.
+3. If there are **any findings** (blockers, warnings, or suggestions), proceed to Phase 4.
+4. If there are **zero findings**, skip Phase 4 and go to Final Report.
+
+### Phase 4: Fix Review Findings (`/scope-fix-review NNN`)
+
+Execute all Phase 3 findings using a coordinated agent team. **This phase requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`.**
+
+1. Check if agent teams are enabled:
+   ```bash
+   echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not set}"
+   ```
+2. If **enabled** (`1`) and Phase 3 produced findings:
+   - Invoke: `Skill(skill: "scope-fix-review", args: "NNN")`
+   - This spawns an agent team that fixes all findings in parallel across non-overlapping file domains
+   - Includes a verification step (typecheck + build) at the end
+3. If **not enabled**:
+   - Read `~/.claude/settings.json`
+   - Merge `"env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }` into the existing JSON (preserve all other settings)
+   - Write the updated file back
+   - Inform the user:
+   ```
+   ╔═══════════════════════════════════════════════════════════════╗
+   ║  Phase 4 SKIPPED — Agent teams were not enabled              ║
+   ║                                                               ║
+   ║  Phase 3 found [N] issues that could be auto-fixed.          ║
+   ║  Agent teams have now been enabled in ~/.claude/settings.json ║
+   ║                                                               ║
+   ║  Restart your session, then re-run:                           ║
+   ║    /scope-fix-review NNN                                      ║
+   ║                                                               ║
+   ║  Or fix findings manually and re-run: /scope-post-review NNN ║
+   ╚═══════════════════════════════════════════════════════════════╝
+   ```
+   Phase 4 is skipped but does **not** block the pipeline. The setting is enabled for next time.
+
+### Final Report
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║  /scope-post-review COMPLETE — Scope NNN                     ║
+╠═══════════════════════════════════════════════════════════════╣
+║                                                               ║
+║  Phase 1: Quality Gates      ✅ PASSED                       ║
+║  Phase 2: Scope Verification ✅ PASSED                       ║
+║  Phase 3: Code Review        [N blockers, M warnings]        ║
+║  Phase 4: Fix Execution      ✅ DONE / ⏭ SKIPPED            ║
+║                                                               ║
+║  Scope is in review. Next: /git-commit                       ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+## Notes
+
+- Each phase can be run independently: `/test-checks`, `/scope-verify NNN`, `/test-code-review`, `/scope-fix-review NNN`
+- Phase 2 (`/scope-verify`) enforces session separation — this skill must be run in a different session than the implementing session
+- Phase 2 writes the verdict file that unlocks `/git-commit`
+- Phase 3 findings flow into Phase 4 — the agent team addresses all issues found
+- Phase 4 requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` — skipped gracefully if not enabled
+- Phase 4 can also be run standalone: `/scope-fix-review NNN` (after running `/test-code-review`)