orbital-command 0.1.4 → 0.3.0

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

@@ -63,10 +63,16 @@ For each completed scope being pushed:
 bash .claude/hooks/scope-transition.sh --from completed --to main --scope NNN
 ```
 
-### Step 5: Signal Completion
+### Step 5: Signal Completion (REQUIRED)
+
+**Always emit after a successful push/PR** — this is not optional:
 
 ```bash
-bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_main"}' --scope "NNN"
+# With a scope:
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_main"}' --scope "{NNN}"
+
+# Without a scope:
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_main"}'
 ```
 
 ## Batch Support

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

@@ -96,12 +96,16 @@ gh pr merge --merge
 # Your CI/CD pipeline auto-deploys main to production (if configured)
 ```
 
-### Step 6: Signal Completion
+### Step 6: Signal Completion (REQUIRED)
 
-After the merge succeeds, emit the agent completion event if working on a dispatched scope:
+**Always emit after a successful merge** — this is not optional:
 
 ```bash
+# With a scope:
 bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_production"}' --scope "{NNN}"
+
+# Without a scope:
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_production"}'
 ```
 
 ### Step 7: Verify Production

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

@@ -20,8 +20,7 @@ Creates a GitHub PR from dev to staging. Staging is a release candidate — the
 
 Find scopes in `scopes/dev/`:
 1. For each scope file in `scopes/dev/*.md`:
-   - `mv scopes/dev/{file} scopes/staging/`
-   - Update frontmatter: `status: staging`
+   - Transition: `bash .claude/hooks/scope-transition.sh --from dev --to staging --scope {NNN}`
    - Update DASHBOARD: `🚀 **Status**: Staging PR Created`
 
 If BATCH_SCOPE_IDS is set, only transition those specific scopes.
@@ -59,10 +58,16 @@ gh pr create --base staging --head dev \
 - [ ] Files under 400 lines"
 ```
 
-### Step 4: Signal Completion
+### Step 4: Signal Completion (REQUIRED)
+
+**Always emit after a successful PR creation** — this is not optional:
 
 ```bash
+# With a scope:
 bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_staging"}' --scope "{NNN}"
+
+# Without a scope:
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_staging"}'
 ```
 
 ### Step 5: Monitor CI

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

@@ -46,10 +46,24 @@ Then run:
 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 script outputs JSON: `{"id", "path", "title", "description", "session_id", "category", "effort", "mode", "available_categories", "effort_buckets"}`.
 The scope file is fully scaffolded with template, frontmatter, dashboard, and process log.
 
-### Step 2: Fill Specification
+### Step 2: Categorize and Estimate
+
+Read the JSON output from Step 1. Using the title, description, and any preserved idea body
+in the scope file, update the frontmatter:
+
+1. **Category**: Select the best match from `available_categories` in the JSON output.
+   Match semantically — "feature" for new capabilities, "bugfix" for fixes, "refactor" for
+   restructuring, "infrastructure" for tooling/CI/config, "docs" for documentation.
+   If the category is still "TBD", update it in the scope file's frontmatter.
+
+2. **Effort**: Estimate using the bucket system from `effort_buckets` in the JSON output
+   (typically: `<1H`, `1-4H`, or `4H+`). Consider the scope of changes implied by the
+   title and description. If effort is still "TBD", update it in the scope file's frontmatter.
+
+### Step 3: 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:
@@ -57,7 +71,7 @@ actual problem statement and goal. If coming from a plan, also populate:
 - **Technical Approach** and rationale
 - **Implementation Phases** with files, changes, and verification steps
 
-### Step 3: Report
+### Step 4: Report
 
 ```
 Created: scopes/planning/NNN-feature-name.md

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

@@ -12,8 +12,8 @@ Takes ALL findings from the Phase 3 code review (`/test-code-review`) and execut
 
 ## 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
+- Phase 3 (`/test-code-review`) must have been run — either in the current pipeline or in a prior session
+- Code review findings must be available (conversation context OR `.claude/review-findings/NNN.json` on disk)
 - `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` must be enabled (a hook will block this skill otherwise)
 
 ## Steps
@@ -42,7 +42,10 @@ Takes ALL findings from the Phase 3 code review (`/test-code-review`) and execut
 
 ### Step 2: Collect and Organize Findings
 
-1. Gather ALL findings from the Phase 3 code review (from conversation context)
+1. **Load findings** — check both sources in order:
+   - **Disk first:** Read `.claude/review-findings/NNN.json` (where NNN is the scope ID). This file is written by `/test-code-review` Phase 4 and enables standalone `/scope-fix-review` without re-running Phase 3.
+   - **Conversation fallback:** If the file doesn't exist, gather findings from the Phase 3 code review conversation context.
+   - If neither source has findings, report "No findings to fix" and **EXIT**.
 2. Deduplicate findings across the 6 review agents
 3. Group findings by **file ownership domain**:
 

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

@@ -26,7 +26,10 @@ user-invocable: true
 
 ### 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/`.
+**Before starting Phase 1**: Transition the scope and update the DASHBOARD to `🔄 **Status**: Implementing`:
+```bash
+bash .claude/hooks/scope-transition.sh --from backlog --to implementing --scope {NNN}
+```
 
 For each phase:
 

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

@@ -2,7 +2,7 @@
 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]
+orchestrates: [test-scaffold, test-checks, scope-verify, test-code-review, scope-fix-review]
 ---
 
 # /scope-post-review NNN — Post-Implementation Review
@@ -16,6 +16,11 @@ Orchestrates the full post-implementation review pipeline for a scope. Runs up t
 │                     /scope-post-review NNN                      │
 ├─────────────────────────────────────────────────────────────────┤
 │                                                                 │
+│  Phase 0: Test infrastructure check                            │
+│  └── If commands.test is null → /test-scaffold                 │
+│      Analyzes project, installs framework, writes tests.       │
+│      SKIPPED if tests already configured.                      │
+│                                                                 │
 │  Phase 1: /test-checks                                         │
 │  └── 13 machine-verifiable quality gates                       │
 │      Types, lint, build, templates, docs, enforcement, etc.    │
@@ -41,10 +46,49 @@ Orchestrates the full post-implementation review pipeline for a scope. Runs up t
 └─────────────────────────────────────────────────────────────────┘
 ```
 
-**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.
+**Rationale**: Test infrastructure is checked first so that gate #13 (tests) has something to run. Quality gates run next to catch obvious issues cheaply. Spec verification runs third to confirm the implementation is actually complete before spending tokens on AI code review. Code review runs fourth 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 0: Test Infrastructure Check
+
+Ensure the project has a test suite before running quality gates. This runs in a subagent to keep the main post-review context clean — the scaffolding work (codebase analysis, package installs, writing test files) can be extensive and is not relevant to the review phases that follow.
+
+1. Read `.claude/orbital.config.json`
+2. Check `commands.test`:
+   - **If non-null** → tests are configured. Print:
+     ```
+     Phase 0: Tests configured (commands.test = "<value>") — skipping.
+     ```
+     **Skip** to Phase 1.
+   - **If null** → no test suite configured. Print:
+     ```
+     Phase 0: No test suite configured — scaffolding tests via subagent...
+     ```
+     Launch a subagent to scaffold the test suite:
+     ```
+     Agent(
+       description: "Scaffold test infrastructure",
+       prompt: "Run the /test-scaffold skill for this project. The project has no test suite configured (commands.test is null in .claude/orbital.config.json). Follow the skill instructions to: detect the project stack, choose a test framework, install it, write real tests, verify they pass, and update commands.test in .claude/orbital.config.json. Report what you did when finished.",
+       mode: "auto"
+     )
+     ```
+3. After the subagent completes:
+   - Re-read `.claude/orbital.config.json` and confirm `commands.test` is now non-null
+   - Run the configured test command to verify tests actually pass:
+     ```bash
+     <commands.test value>   # e.g., npm run test
+     ```
+   - **If `commands.test` is still null or tests fail:**
+     ```
+     ╔═══════════════════════════════════════════════════════════════╗
+     ║  Phase 0 FAILED — Test scaffolding did not produce passing   ║
+     ║  tests. Fix manually and re-run: /scope-post-review NNN     ║
+     ╚═══════════════════════════════════════════════════════════════╝
+     ```
+     **STOP** — do not proceed to Phase 1 with broken tests.
+   - **If tests pass** → continue to Phase 1.
+
 ### Phase 1: Quality Gates (`/test-checks`)
 
 Run the 13 quality gates. This is the cheapest and fastest check.
@@ -83,8 +127,12 @@ 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.
+3. **Persist findings** — write all findings to `.claude/review-findings/NNN.json` so Phase 4 can read them even if run standalone in a separate session:
+   ```json
+   { "scopeId": NNN, "timestamp": "<ISO>", "blockers": [...], "warnings": [...], "suggestions": [...] }
+   ```
+4. If there are **any findings** (blockers, warnings, or suggestions), proceed to Phase 4.
+5. If there are **zero findings**, skip Phase 4 and go to Final Report.
 
 ### Phase 4: Fix Review Findings (`/scope-fix-review NNN`)
 
@@ -95,9 +143,14 @@ Execute all Phase 3 findings using a coordinated agent team. **This phase requir
    echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not set}"
    ```
 2. If **enabled** (`1`) and Phase 3 produced findings:
+   - If `.claude/review-findings/NNN.json` exists, load findings from there (enables standalone `/scope-fix-review` without re-running Phase 3)
    - 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
+   - After fixes complete, **re-run quality gates** to catch regressions:
+     ```
+     Skill(skill: "test-checks")
+     ```
+     If any gate fails, report which gates regressed and **STOP**.
 3. If **not enabled**:
    - Read `~/.claude/settings.json`
    - Merge `"env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }` into the existing JSON (preserve all other settings)
@@ -120,6 +173,11 @@ Execute all Phase 3 findings using a coordinated agent team. **This phase requir
 
 ### Final Report
 
+Emit the completion event so the dispatch resolves and the dashboard card stops showing the active animation:
+```bash
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"post_review"}' --scope "{NNN}"
+```
+
 ```
 ╔═══════════════════════════════════════════════════════════════╗
 ║  /scope-post-review COMPLETE — Scope NNN                     ║

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

@@ -188,8 +188,11 @@ J items are implementation notes (no spec change).
 ### Step 8: Update Scope Status
 
 After applying spec fixes and writing the AGENT REVIEW:
-- Update frontmatter: `status: backlog`, `spec_locked: true`
-- Move file: `mv scopes/planning/{file} scopes/backlog/`
+- Transition the scope (handles frontmatter + file move atomically):
+  ```bash
+  bash .claude/hooks/scope-transition.sh --from planning --to backlog --scope {NNN}
+  ```
+- Update frontmatter: `spec_locked: true` (scope-transition.sh handles status, this is the extra field)
 - 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.`
 

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

@@ -146,9 +146,11 @@ Overall verdict is PASS only if ALL 4 criteria are PASS.
 ### Step 6: Scope Transition (on PASS only)
 
 If all criteria passed:
-1. Move scope file: `mv scopes/implementing/{file} scopes/review/` (or leave in place if already in `scopes/review/`)
-2. Update frontmatter: `status: review`
-3. Update DASHBOARD: `✅ **Status**: Reviewed | Ready to Commit`
+1. Transition the scope (handles frontmatter + file move atomically):
+   ```bash
+   bash .claude/hooks/scope-transition.sh --from implementing --to review --scope {NNN}
+   ```
+2. Update DASHBOARD: `✅ **Status**: Reviewed | Ready to Commit`
 
 ### Step 7: Report & Next Steps
 

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

@@ -21,9 +21,9 @@ 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 1: /test-checks (13 quality gates)                               │
+│  ├── TypeScript, Lint, Build, Templates, Docs, Enforcement              │
+│  └── Placeholders, Mock data, Shortcuts, Secrets, Stale scopes, Tests   │
 │                                                                         │
 │  Phase 2: pre-push (3 checks)                                                  │
 │  ├── Documentation sync                                                 │
@@ -50,26 +50,13 @@ Combines all validation layers into one comprehensive check:
 
 ### Phase 1: Pre-Commit Checks
 
-Run all 8 quality gates. Read commands from `.claude/orbital.config.json` — skip any that are null:
+Run all 13 quality gates via `/test-checks`:
 
-```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"
 ```
+Skill(skill: "test-checks")
+```
+
+This runs the full pipeline: typecheck, lint, build, templates, docs, enforcement, placeholders, mock data, shortcuts, secrets, stale scopes, and tests (13 gates total). See `/test-checks` for details.
 
 **Stop here if any check fails. Fix before proceeding.**
 
@@ -120,21 +107,44 @@ Prompt: "Review type design quality"
 
 ### Phase 4: Synthesize Results
 
-Collect all findings and report:
+Collect all findings, categorize by severity, and **persist to disk** so `/scope-fix-review` can load them in a standalone session.
+
+**4a. Categorize findings** from all 6 agents into BLOCKERS, WARNINGS, and SUGGESTIONS.
+
+**4b. Write findings to disk** — if running in a scope context (scope NNN is known from the pipeline), write:
+
+```bash
+mkdir -p .claude/review-findings
+```
+
+Write `.claude/review-findings/NNN.json`:
+```json
+{
+  "scopeId": NNN,
+  "timestamp": "<ISO timestamp>",
+  "blockers": [{ "agent": "...", "file": "...", "line": N, "message": "...", "fix": "..." }],
+  "warnings": [{ "agent": "...", "file": "...", "line": N, "message": "...", "fix": "..." }],
+  "suggestions": [{ "agent": "...", "file": "...", "line": N, "message": "...", "fix": "..." }]
+}
+```
+
+If no scope context is available (standalone `/test-code-review` outside post-review), skip the file write — findings remain in conversation context only.
+
+**4c. Display summary:**
 
 ```
 ╔═══════════════════════════════════════════════════════════════════════╗
-║                         /test-code-review RESULTS                                 ║
+║                       /test-code-review RESULTS                       ║
 ╠═══════════════════════════════════════════════════════════════════════╣
 ║                                                                       ║
-║  PHASE 1: Pre-Commit          [8/8 passed]  ✅                        ║
-║  PHASE 2: Pre-Push            [3/3 passed]  ✅                        ║
+║  PHASE 1: Pre-Commit          [13/13 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                                      ║
+║  BLOCKERS (must fix):       0                                         ║
+║  WARNINGS (should fix):     2                                         ║
+║  SUGGESTIONS (consider):    5                                         ║
 ║                                                                       ║
 ╚═══════════════════════════════════════════════════════════════════════╝
 ```
@@ -199,13 +209,11 @@ If matching scope files are found and all tests passed:
 #### 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"
+# Only after user confirmation — uses atomic transition (frontmatter + move)
+bash .claude/hooks/scope-transition.sh --from review --to completed --scope XXX
+echo "✅ Moved scope XXX to completed"
 ```
 
-**Note:** Scopes are gitignored — use plain `mv`, not `git mv`.
-
 ## Modes
 
 | Command | What Runs |

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

@@ -0,0 +1,222 @@
+---
+name: test-scaffold
+description: Analyzes any project, scaffolds test infrastructure, writes real unit and integration tests, and configures orbital.config.json. Use when a project has no test suite or when commands.test is null.
+user-invocable: true
+---
+
+# /test-scaffold - Scaffold Test Infrastructure & Write Tests
+
+---
+tokens: ~1200
+trigger: /test-scaffold
+purpose: Detect, install, configure, and write a complete test suite for any project
+---
+
+## What This Does
+
+Analyzes the current project, picks the right test framework, installs it, writes real unit and integration tests for the most testable code, and configures `orbital.config.json` so the test gate runs automatically in future quality checks.
+
+## Steps
+
+### Step 1: Detect Existing Test Infrastructure
+
+Check if the project already has tests.
+
+1. Read `.claude/orbital.config.json` — check if `commands.test` is non-null
+2. Check `package.json` (or equivalent) for a `test` script
+3. Search for existing test files: `*.test.*`, `*.spec.*`, `__tests__/` directories
+4. Search for test config files: `vitest.config.*`, `jest.config.*`, `pytest.ini`, `pyproject.toml [tool.pytest]`, `*_test.go`
+
+If tests exist AND `commands.test` is non-null, **verify they actually pass** by running the test command:
+
+```bash
+<commands.test value>   # e.g., npm run test
+```
+
+- **If tests pass** → print "Tests already configured and passing" and **EXIT**.
+- **If tests fail** → print "Tests exist but are failing — proceeding to diagnose and fix." Continue to Step 2, but focus on fixing the existing tests rather than scaffolding from scratch.
+
+If no test infrastructure exists at all, continue to Step 2.
+
+### Step 2: Analyze the Project
+
+Read the project's configuration and source code to determine the stack:
+
+**2a. Identify language and runtime:**
+- Read `package.json` → Node.js/TypeScript project
+- Read `pyproject.toml` or `setup.py` or `requirements.txt` → Python project
+- Read `go.mod` → Go project
+- Read `Cargo.toml` → Rust project
+- Read `pom.xml` or `build.gradle` → Java/Kotlin project
+
+**2b. Identify build tooling (for framework selection):**
+- Check for `vite.config.*` → Vite-based (use Vitest)
+- Check for `webpack.config.*` → Webpack-based
+- Check for `tsconfig.json` → TypeScript project
+- Check for `next.config.*` → Next.js
+
+**2c. Identify code structure:**
+- List top-level directories (e.g., `src/`, `server/`, `shared/`, `lib/`, `app/`)
+- Note path aliases (from tsconfig `paths`, webpack aliases, etc.)
+- **Monorepo detection:** Check for `pnpm-workspace.yaml`, `lerna.json`, `rush.json`, or `workspaces` field in `package.json`. If detected, scope test scaffolding to the current package (the directory containing the nearest `package.json`), not the workspace root.
+
+**2d. Find the most testable code — prioritize in this order:**
+
+1. **Pure functions and classes** — no I/O, no side effects. Look for:
+   - Utility modules, parsers, validators, transformers
+   - Engine/logic classes that take config and return computed results
+   - Type guard functions, normalizers, formatters
+
+2. **Services with injectable dependencies** — constructor takes DB, event emitter, or other services:
+   - Database services (CRUD operations)
+   - Business logic services
+   - Cache/store classes
+
+3. **API routes** — if the project uses Express, Fastify, Flask, etc.:
+   - Route handlers with dependency injection
+   - REST endpoints that can be tested with HTTP assertions
+
+For each candidate, note: file path, exported functions/classes, whether it has side effects, and what test data it would need.
+
+### Step 3: Choose Test Framework
+
+Based on the analysis in Step 2, select the appropriate test framework:
+
+| Project Type | Framework | HTTP Testing | Why |
+|---|---|---|---|
+| Vite / React / Vue | **Vitest** | supertest | Shares Vite transform pipeline, native ESM |
+| Node.js (no Vite) | **Vitest** | supertest | Fast, modern, good ESM support |
+| Next.js | **Vitest** or **Jest** | supertest | Check if Jest is already a dependency |
+| Python | **pytest** | pytest + httpx/requests | De facto standard |
+| Go | **built-in testing** | net/http/httptest | No external framework needed |
+| Rust | **built-in #[test]** | actix-test / axum::test | No external framework needed |
+
+**Do not install a framework the project already has** — check existing dependencies first.
+
+### Step 4: Install and Configure
+
+**4a. Install the framework and test utilities:**
+
+For Node.js projects:
+```bash
+npm install -D vitest  # (or chosen framework)
+# Add HTTP testing if the project has API routes:
+npm install -D supertest @types/supertest
+```
+
+For Python projects:
+```bash
+pip install pytest  # or add to dev dependencies
+```
+
+**4b. Create the test configuration file:**
+
+For Vitest — create `vitest.config.ts` (separate from `vite.config.ts`):
+- Configure `test.environment: 'node'` for server/pure logic tests
+- Configure path aliases to match the project's tsconfig
+- If the project has both pure logic and I/O-dependent code, configure two projects:
+  - `unit` — pure logic tests (fast, no setup)
+  - `integration` — tests requiring DB, filesystem, or network (may need setup/teardown)
+
+**4c. Add test scripts** to `package.json` (or equivalent):
+
+```json
+"test": "<framework> run",
+"test:unit": "<framework> run --project unit",
+"test:integration": "<framework> run --project integration",
+"test:watch": "<framework>",
+"test:coverage": "<framework> run --coverage"
+```
+
+**4d. Add `coverage/` to `.gitignore`** if not already present.
+
+### Step 5: Create Test Helpers
+
+Based on what the project needs, create shared test utilities:
+
+**If the project uses a database (SQLite, Postgres, etc.):**
+- Create a DB test helper that sets up an isolated test database (in-memory SQLite, test schema, etc.)
+- Helper should return `{ db, cleanup }` for use in `beforeEach`/`afterEach`
+- **Finding the schema:** Search for `schema.*` files (`.ts`, `.js`, `.sql`), `schema/` directories, or migration files. For TypeScript projects, look for exported DDL constants (e.g., `export const SCHEMA_DDL`). For SQL files, import them directly. Apply the discovered schema to the test database.
+
+**If services depend on event emitters, websockets, or message buses:**
+- Create a mock factory (e.g., `createMockEmitter()`) that returns a spy-instrumented object matching the real interface
+
+**If tests need fixture data (config objects, sample records, etc.):**
+- Create a `__fixtures__/` directory with reusable test data
+- Export named constants: `MINIMAL_CONFIG`, `DEFAULT_CONFIG`, `INVALID_CONFIGS`, etc.
+- Build fixtures from the project's actual config schemas, not invented formats
+
+### Step 6: Write Real Test Cases
+
+Write actual, meaningful test cases for the code identified in Step 2. **Do not write stubs or placeholder tests.**
+
+**For each testable module, write tests that cover:**
+
+1. **Happy path** — normal inputs produce expected outputs
+2. **Edge cases** — empty inputs, boundary values, null/undefined
+3. **Error cases** — invalid inputs throw or return error results
+4. **Constructor/initialization** — validation logic, required params
+
+**Organize tests by module:**
+- Co-locate test files next to source files: `foo.ts` → `foo.test.ts`
+- Exception: integration tests spanning multiple modules go in `__tests__/` directories
+
+**Naming convention:**
+```
+describe('ClassName', () => {
+  describe('methodName()', () => {
+    it('returns X when given Y', () => { ... });
+    it('throws when given invalid input', () => { ... });
+  });
+});
+```
+
+**Prioritize coverage by test value:**
+1. Pure logic with complex branching (highest value)
+2. Services that write/read data (catches data bugs)
+3. API routes (catches contract breaks)
+4. Simple getters/setters (lowest value — skip if time-constrained)
+
+### Step 7: Verify
+
+Run the complete test suite and confirm all tests pass:
+
+```bash
+npm run test  # or equivalent
+```
+
+If any tests fail:
+1. Read the failure output
+2. Fix the test or the test helper (not the source code — tests should match existing behavior)
+3. Re-run until all pass
+
+Also verify the project still builds:
+```bash
+npm run typecheck  # if TypeScript
+npm run build      # if applicable
+```
+
+### Step 8: Update orbital.config.json
+
+Set `commands.test` so the test gate (#13 in `/test-checks`) runs automatically:
+
+Read `.claude/orbital.config.json`, update the `commands.test` field:
+
+```json
+{
+  "commands": {
+    "test": "npm run test"
+  }
+}
+```
+
+Use the appropriate command for the project's package manager and framework.
+
+## Notes
+
+- This skill is framework-agnostic — the framework choice emerges from project analysis
+- For projects with both frontend and backend, focus tests on backend/shared logic first (higher value per test)
+- Do not add component tests (React Testing Library, etc.) unless the project specifically needs them — they require additional setup (jsdom, etc.) and are lower priority than logic tests
+- Do not modify source code to make it testable — tests should work with the existing API surface
+- If the project already has _some_ tests but `commands.test` is null, configure the command without rewriting existing tests