orbital-command 0.1.0

package/templates/skills/test-checks/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: test-checks
+description: Runs 13 quality gates including linting, type checking, rule verification, and stale scope detection. Use before commits, after making changes, or when checking code quality quickly.
+user-invocable: true
+---
+
+# /test-checks - Run All Quality Gates
+
+---
+tokens: ~600
+trigger: /test-checks
+purpose: Run the complete 13-step quality gate pipeline before committing
+---
+
+## What This Does
+
+Executes the full pre-commit quality pipeline - same checks the git hook runs.
+
+## The 13 Checks
+
+| # | Check | Command (from orbital.config.json) | What It Catches |
+|---|-------|--------------------------------------|-----------------|
+| 1 | TypeScript | `commands.typeCheck` | Type errors |
+| 2 | Lint | `commands.lint` | Code style violations |
+| 3 | Build | `commands.build` | Compilation, imports |
+| 4 | Templates | `commands.validateTemplates` | Template syntax |
+| 5 | Doc Links | `commands.validateDocs` | Broken links |
+| 6 | Doc Freshness | `commands.docFreshness` | Stale auto-docs |
+| 7 | Enforcement | `commands.checkRules` | Rule violations |
+| 8 | Workarounds | grep patterns | Bypass attempts |
+| 9 | **Placeholders** | grep PLACEHOLDER/STUB | Incomplete implementations |
+| 10 | **Mock Data** | grep mock/fake in prod | Test data in production |
+| 11 | **Shortcuts** | grep "for now"/TODO | Unfinished work |
+| 12 | **Default Secrets** | grep fallback secrets | Security vulnerabilities |
+| 13 | **Stale Scopes** | grep completed scopes | Scopes needing move to completed/ |
+
+## Steps
+
+### Step 1: Run All Checks (with Orbital Gate Reporting)
+
+Read `.claude/orbital.config.json` for project-specific commands. Run each check, capture timing, and report results to Orbital Command. If the Orbital server isn't running, reporting is silently skipped.
+
+```bash
+HOOK_DIR="$(git rev-parse --show-toplevel)/.claude/hooks"
+export ORBITAL_GATE_COMMIT_SHA=$(git rev-parse --short HEAD 2>/dev/null)
+
+# Helper: run a gate check and report result
+# Usage: run_gate <gate_name> <check_number> <total> <command...>
+run_gate() {
+  local gate="$1" num="$2" total="$3"; shift 3
+  echo "[$num/$total] $gate..."
+  local start_ms=$(($(date +%s) * 1000))
+  if eval "$@" 2>&1; then
+    local end_ms=$(($(date +%s) * 1000))
+    "$HOOK_DIR/orbital-report-gates.sh" "$gate" "pass" "$(( end_ms - start_ms ))"
+    return 0
+  else
+    local end_ms=$(($(date +%s) * 1000))
+    "$HOOK_DIR/orbital-report-gates.sh" "$gate" "fail" "$(( end_ms - start_ms ))"
+    return 1
+  fi
+}
+
+# Checks 1-7: Read commands from orbital.config.json — skip any that are null
+# Run commands.typeCheck (if configured, skip if null)
+run_gate "type-check" 1 13 "<commands.typeCheck from orbital.config.json>"
+# Run commands.lint (if configured, skip if null)
+run_gate "lint" 2 13 "<commands.lint from orbital.config.json>"
+# Run commands.build (if configured, skip if null)
+run_gate "build" 3 13 "<commands.build from orbital.config.json>"
+# Run commands.validateTemplates (if configured, skip if null)
+run_gate "template-validation" 4 13 "<commands.validateTemplates from orbital.config.json>"
+# Run commands.validateDocs (if configured, skip if null)
+run_gate "doc-links" 5 13 "<commands.validateDocs from orbital.config.json>"
+# Run commands.docFreshness (if configured, skip if null)
+run_gate "doc-freshness" 6 13 "<commands.docFreshness from orbital.config.json>"
+
+# Enforcement: capture output for violation reporting
+# Run commands.checkRules (if configured, skip if null)
+echo "[7/13] rule-enforcement..."
+RULES_START=$(($(date +%s) * 1000))
+RULES_OUTPUT=$(<commands.checkRules from orbital.config.json> 2>&1)
+RULES_EXIT=$?
+RULES_END=$(($(date +%s) * 1000))
+if [ $RULES_EXIT -eq 0 ]; then
+  "$HOOK_DIR/orbital-report-gates.sh" "rule-enforcement" "pass" "$(( RULES_END - RULES_START ))"
+else
+  "$HOOK_DIR/orbital-report-gates.sh" "rule-enforcement" "fail" "$(( RULES_END - RULES_START ))"
+  echo "$RULES_OUTPUT"
+fi
+
+# Checks 8-13: Generic code quality checks (not project-specific)
+run_gate "no-placeholders" 8 13 '! grep -rEi "PLACEHOLDER|STUB_|DUMMY_" . --include="*.ts" --include="*.py" --include="*.js" | grep -v __tests__ | grep -v node_modules'
+run_gate "no-mock-data" 9 13 '! grep -rEi "mockSignature|fakeUser|MOCK_DATA" . --include="*.ts" --include="*.py" --include="*.js" | grep -v __tests__ | grep -v node_modules'
+run_gate "no-shortcuts" 10 13 'FOUND=$(grep -rc "for now\|// TODO:\|// FIXME:" . --include="*.ts" --include="*.py" --include="*.js" 2>/dev/null | grep -v node_modules | grep -v ":0$" | wc -l | tr -d " "); [ "$FOUND" -eq 0 ]'
+run_gate "no-default-secrets" 11 13 '! grep -rE "\|\| ['\''\"]\.\*(secret|key|token)" . --include="*.ts" --include="*.py" --include="*.js" | grep -v __tests__ | grep -v node_modules'
+run_gate "no-stale-scopes" 12 13 'STALE=$(grep -rl "^status: implementing" scopes/completed/ scopes/review/ 2>/dev/null | wc -l | tr -d " "); [ "$STALE" -eq 0 ]'
+# Run commands.test (if configured, skip if null)
+run_gate "tests" 13 13 "<commands.test from orbital.config.json>"
+```
+
+### Step 2: Report Results
+
+Display the summary table (same format as before — the Orbital Command dashboard gets data automatically via the gate reports above).
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║  PRE-COMMIT QUALITY GATES                                     ║
+╠═══════════════════════════════════════════════════════════════╣
+║                                                               ║
+║  [1/13]  TypeScript type-check   ✅/❌                        ║
+║  [2/13]  ESLint                  ✅/❌                        ║
+║  [3/13]  Build                   ✅/❌                        ║
+║  [4/13]  Template validation     ✅/❌                        ║
+║  [5/13]  Documentation links     ✅/❌                        ║
+║  [6/13]  Doc freshness           ✅/❌                        ║
+║  [7/13]  Enforcement rules       ✅/❌                        ║
+║  [8/13]  No placeholders         ✅/❌                        ║
+║  [9/13]  No mock data in prod    ✅/❌                        ║
+║  [10/13] No untracked shortcuts  ✅/❌                        ║
+║  [11/13] No default secrets      ✅/❌                        ║
+║  [12/13] No stale scopes         ✅/❌                        ║
+║  [13/13] Tests                   ✅/❌                        ║
+║                                                               ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+### Step 3: On Failure
+
+When a check fails:
+1. **Read the error** - It tells you what's wrong
+2. **Fix the issue** - Use Edit tool
+3. **Re-run that check** - Verify the fix
+4. **Continue** - Move to next check
+
+## Quick Fixes
+
+| Check | Common Fix |
+|-------|-----------|
+| TypeScript | Add missing types, fix type mismatches |
+| Lint | Run the lint fix command, remove any types |
+| Build | Same as TypeScript, check imports |
+| Templates | Fix placeholder syntax in template files |
+| Doc Links | Update/remove broken links |
+| Doc Freshness | Regenerate auto-docs |
+| Enforcement | See enforcement rules for specific fixes |
+| Workarounds | Use Write/Edit tools properly, not bash |
+| **Placeholders** | Replace with real implementation or throw error |
+| **Mock Data** | Move to `__tests__/fixtures/` or implement real logic |
+| **Shortcuts** | Complete the TODO or link to tracking ticket |
+| **Default Secrets** | Remove fallback, require env var with validation |
+| **Stale Scopes** | Run `/git-commit` to commit and transition reviewed scopes |
+
+## File Size Check
+
+Also verify no new files exceed the configured line limit (default: 400 lines). Check `orbital.config.json` for `maxFileLines` and `maxFileLinesExemptions`:
+
+```bash
+# Adjust the path and extension to match your project structure
+find src -name "*.ts" -o -name "*.py" -o -name "*.js" | xargs wc -l | awk '$1 > 400'
+```
+
+Check `orbital.config.json` for any exempt files listed under `maxFileLinesExemptions`.
+
+## After All Pass
+
+```bash
+git add -A && git commit -m "your message"
+```
+
+The git hook will run these same checks automatically.

package/templates/skills/test-code-review/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: test-code-review
+description: Runs complete validation suite including pre-commit checks, pre-push verification, and code review agents. Use when preparing major commits, before creating PRs, or for comprehensive quality checks.
+user-invocable: true
+---
+
+# /test-code-review - Complete Validation Suite
+
+---
+tokens: ~600
+trigger: /test-code-review
+purpose: Run the full validation pipeline: pre-commit checks, pre-push checks, and parallel code review
+---
+
+## What This Does
+
+Combines all validation layers into one comprehensive check:
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                            /test-code-review                                        │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│  Phase 1: /test-checks (8 checks)                                              │
+│  ├── TypeScript, ESLint, Build, Templates                               │
+│  └── Doc links, Doc freshness, Enforcement, Workarounds                 │
+│                                                                         │
+│  Phase 2: pre-push (3 checks)                                                  │
+│  ├── Documentation sync                                                 │
+│  ├── Auto-generated docs                                                │
+│  └── Code review scan                                                   │
+│                                                                         │
+│  Phase 3: code-review (6 agents in parallel)                                    │
+│  ├── code-reviewer, silent-failure-hunter, code-simplifier              │
+│  └── comment-analyzer, pr-test-analyzer, type-design-analyzer           │
+│                                                                         │
+│  Phase 4: Synthesize Results                                            │
+│  └── Collect findings, categorize by severity                           │
+│                                                                         │
+│  Phase 5: Scope Completion Check (if all pass)                          │
+│  └── Check if branch scopes can move to /scopes/completed/              │
+│                                                                         │
+│  Phase 6: Reflection Prompt (optional)                                  │
+│  └── Ask if user wants to capture learnings in lessons-learned.md       │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## Steps
+
+### Phase 1: Pre-Commit Checks
+
+Run all 8 quality gates. Read commands from `.claude/orbital.config.json` — skip any that are null:
+
+```bash
+echo "═══ PHASE 1: PRE-COMMIT ═══"
+# Run commands.typeCheck from orbital.config.json (skip if null)
+echo "[1/8] TypeScript..."
+# Run commands.lint from orbital.config.json (skip if null)
+echo "[2/8] Lint..."
+# Run commands.build from orbital.config.json (skip if null)
+echo "[3/8] Build..."
+# Run commands.validateTemplates from orbital.config.json (skip if null)
+echo "[4/8] Templates..."
+# Run commands.validateDocs from orbital.config.json (skip if null)
+echo "[5/8] Doc links..."
+# Run commands.docFreshness from orbital.config.json (skip if null)
+echo "[6/8] Doc freshness..."
+# Run commands.checkRules from orbital.config.json (skip if null)
+echo "[7/8] Enforcement..."
+echo "[8/8] Workarounds..." && echo "✅ Check staged files manually"
+```
+
+**Stop here if any check fails. Fix before proceeding.**
+
+### Phase 2: Pre-Push Checks
+
+```bash
+echo "═══ PHASE 2: PRE-PUSH ═══"
+
+# Check documentation sync
+CHANGED=$(git diff --name-only HEAD~1..HEAD 2>/dev/null || git diff --name-only)
+
+echo "Changed files:"
+echo "$CHANGED"
+
+# Check critical files from orbital.config.json criticalFiles list (if configured)
+echo "Critical files needing docs:"
+echo "$CHANGED" | grep -E "<criticalFiles pattern from orbital.config.json>" || echo "None"
+
+# Run commands.docFreshness from orbital.config.json (skip if null)
+echo "Auto-docs check..."
+```
+
+### Phase 3: Parallel Code Review
+
+Launch ALL 6 review agents simultaneously using Task tool:
+
+**You MUST send a single message with 6 parallel Task invocations:**
+
+```
+Task: pr-review-toolkit:code-reviewer
+Prompt: "Review current changes for bugs, security, conventions"
+
+Task: pr-review-toolkit:silent-failure-hunter
+Prompt: "Review for silent failures; swallowed errors, bad fallbacks"
+
+Task: pr-review-toolkit:code-simplifier
+Prompt: "Review for unnecessary complexity"
+
+Task: pr-review-toolkit:comment-analyzer
+Prompt: "Review comment accuracy and maintainability"
+
+Task: pr-review-toolkit:pr-test-analyzer
+Prompt: "Analyze test coverage gaps"
+
+Task: pr-review-toolkit:type-design-analyzer
+Prompt: "Review type design quality"
+```
+
+### Phase 4: Synthesize Results
+
+Collect all findings and report:
+
+```
+╔═══════════════════════════════════════════════════════════════════════╗
+║                         /test-code-review RESULTS                                 ║
+╠═══════════════════════════════════════════════════════════════════════╣
+║                                                                       ║
+║  PHASE 1: Pre-Commit          [8/8 passed]  ✅                        ║
+║  PHASE 2: Pre-Push            [3/3 passed]  ✅                        ║
+║  PHASE 3: Code Review         [findings below]                        ║
+║                                                                       ║
+║  ─────────────────────────────────────────────────────────────────    ║
+║  🚫 BLOCKERS (must fix):       0                                      ║
+║  ⚠️  WARNINGS (should fix):     2                                      ║
+║  💡 SUGGESTIONS (consider):    5                                      ║
+║                                                                       ║
+╚═══════════════════════════════════════════════════════════════════════╝
+```
+
+### Phase 5: Scope Completion Check (Only If All Phases Pass)
+
+**Only run this phase if Phases 1-3 pass with no blockers.**
+
+This phase checks if any scope documents should be moved to the `/scopes/completed/` folder.
+
+#### Step 1: Extract Scope Numbers from Branch Name
+
+```bash
+# Get current branch name and extract scope numbers
+BRANCH=$(git branch --show-current)
+echo "Current branch: $BRANCH"
+
+# Extract all 3-digit scope numbers from branch name
+# Handles patterns like: feature/scopes-007-012, fix/scope-018, feature/024-dynamic-convergence
+SCOPE_NUMS=$(echo "$BRANCH" | grep -oE '[0-9]{3}' | sort -u)
+echo "Scope numbers found in branch: $SCOPE_NUMS"
+```
+
+#### Step 2: Check for Matching Scope Files
+
+```bash
+# For each scope number, check if a matching file exists in /scopes/ (not completed/)
+for num in $SCOPE_NUMS; do
+  SCOPE_FILE=$(ls scopes/${num}-*.md 2>/dev/null)
+  if [ -n "$SCOPE_FILE" ]; then
+    echo "📋 Found scope file: $SCOPE_FILE"
+  fi
+done
+```
+
+#### Step 3: Prompt for Scope Completion
+
+If matching scope files are found and all tests passed:
+
+```
+╔═══════════════════════════════════════════════════════════════════════╗
+║                    🎯 SCOPE COMPLETION CHECK                          ║
+╠═══════════════════════════════════════════════════════════════════════╣
+║                                                                       ║
+║  All validation phases PASSED! ✅                                     ║
+║                                                                       ║
+║  The following scope files match your branch and may be complete:     ║
+║                                                                       ║
+║    📋 scopes/018-feature-name.md                                      ║
+║                                                                       ║
+║  ─────────────────────────────────────────────────────────────────    ║
+║  Would you like to move completed scopes to /scopes/completed/?       ║
+║                                                                       ║
+║  Before moving, verify:                                               ║
+║    ✓ All acceptance criteria in the scope are met                     ║
+║    ✓ No remaining TODOs in the scope file                             ║
+║    ✓ Related code changes are committed                               ║
+║                                                                       ║
+╚═══════════════════════════════════════════════════════════════════════╝
+```
+
+#### Step 4: Move Completed Scopes (If User Confirms)
+
+```bash
+# Only after user confirmation (scopes are gitignored, use plain mv)
+mv scopes/XXX-scope-name.md scopes/completed/
+echo "✅ Moved scope XXX to completed folder"
+```
+
+**Note:** Scopes are gitignored — use plain `mv`, not `git mv`.
+
+## Modes
+
+| Command | What Runs |
+|---------|-----------|
+| `/test-code-review` | All 6 phases (full validation + scope check + reflect prompt) |
+| `/test-code-review quick` | Phase 1 only (pre-commit checks) |
+| `/test-code-review review` | Phase 3 only (parallel code review) |
+
+## On Failure
+
+1. Fix issues found in each phase before proceeding
+2. Re-run `/test-code-review` to verify fixes
+3. Only commit/push when all phases pass
+
+## On Success
+
+When all phases pass with no blockers:
+1. Phase 5 automatically checks for scope files matching your branch
+2. If found, you'll be prompted to move them to `/scopes/completed/`
+3. Verify acceptance criteria are met before confirming the move
+4. Use plain `mv` when moving scope files (scopes are gitignored)
+
+### Phase 6: Reflection Prompt (Optional)
+
+After successful validation, prompt for reflection:
+
+```
+╔═══════════════════════════════════════════════════════════════════════╗
+║                    🎯 ALL VALIDATION PASSED                           ║
+╠═══════════════════════════════════════════════════════════════════════╣
+║                                                                       ║
+║  Before you commit, consider capturing learnings:                     ║
+║                                                                       ║
+║    📚 Record any lessons in .claude/lessons-learned.md                ║
+║    🪝 Note any hook/skill improvements for future sessions            ║
+║                                                                       ║
+║  This helps improve the system for future work!                       ║
+║                                                                       ║
+║  Capture learnings now? (or skip and commit)                          ║
+║                                                                       ║
+╚═══════════════════════════════════════════════════════════════════════╝
+```
+
+If user chooses to reflect, help them write an entry in `.claude/lessons-learned.md` before proceeding to commit.

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src", "shared"]
+}

package/vite.config.ts

@@ -0,0 +1,38 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import path from 'path';
+
+const serverPort = process.env.ORBITAL_SERVER_PORT || '4444';
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+    },
+  },
+  server: {
+    port: 4445,
+    proxy: {
+      '/api/orbital': {
+        target: `http://localhost:${serverPort}`,
+        changeOrigin: true,
+      },
+      '/socket.io': {
+        target: `http://localhost:${serverPort}`,
+        ws: true,
+      },
+    },
+  },
+  build: {
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          vendor: ['react', 'react-dom', 'react-router-dom'],
+          charts: ['recharts'],
+          ui: ['@radix-ui/react-dialog', '@radix-ui/react-scroll-area', '@radix-ui/react-tabs', '@radix-ui/react-tooltip'],
+        },
+      },
+    },
+  },
+});