Mission Engine Worker Skill

Mission Engine Worker

NOTE: Startup and cleanup are handled by worker-base. This skill defines the WORK PROCEDURE.

When to Use This Skill

Use for features that implement the mission engine subsystem and production infrastructure:

Mission orchestrator wiring (dispatch loop, handoff pipeline, milestone gates)
Plugin marketplace (manifest, registry, resolver, loader, CLI)
Headless execution engine (autonomy tiers, output formats, permission enforcement)
Code review system (diff engine, severity matrix, 2-pass pipeline)
Mission workspace provisioning and state management
features.json state machine and precondition DAG
state.json mutex and lock management
Handoff directory watching and processing
Worker-to-features dispatching and persona injection
Friction loop engine
Validation contract parsing and state gatekeeper
Scrutiny reviewer auto-spawn and milestone gates
services.yaml command registry
init.sh bootstrap system
Readiness scoring engine and auto-remediation

Work Procedure

1. Understand the Feature

Read the feature's description, expectedBehavior, and verificationSteps carefully. Cross-reference with the validation contract assertions listed in fulfills to understand exactly what behavior must be verified.

2. Write Tests FIRST (TDD Red Phase)

Before writing ANY implementation code:

Create test file in tests/mission/ (or tests/services/, tests/readiness/ as appropriate)
Use node:test with describe() and it() blocks
Use assert from node:assert/strict
Write tests that cover ALL assertions in the feature's fulfills array
Run tests with node --test <test-file> to confirm they FAIL (red phase)

Test file conventions:

Filename: <module-name>.test.cjs
Use temp directories for filesystem tests (clean up in after())
Mock external dependencies with manual stubs (no sinon/jest)
Use path.join() for all paths (Windows compatibility)

3. Implement the Module (TDD Green Phase)

Create module in .claude/lib/mission/ (or .claude/lib/services/, .claude/lib/readiness/)
Use CommonJS: module.exports = { ... }
Use AJV for all JSON schema validation
Use atomic writes for state files: write to .tmp then rename
Use path.normalize() for all file paths
Handle Windows-specific concerns:
- fs.watch may be unreliable on NTFS - provide polling fallback
- Use process.platform === 'win32' checks where needed
- Use where instead of command -v on Windows
Run tests to confirm they PASS (green phase)

4. Verify Your Work

Run the specific test file: node --test tests/mission/<file>.test.cjs
Run the full test suite: pnpm test (must not break existing tests)
Run format check: pnpm format:check
If format fails, run: pnpm format then re-check
Manually verify by requiring the module and calling key functions from a Node REPL or inline script

5. Check for Integration Issues

Verify your module exports match what other modules expect to import
Check that file paths used match the mission workspace structure
Ensure no circular dependencies with existing .claude/lib/ modules

Example Handoff

{
  "salientSummary": "Implemented features.json state machine with 5 valid transitions, precondition DAG evaluation, circular dependency detection, and atomic write safety. Wrote 14 test cases covering all VAL-FS assertions. All tests pass, pnpm test green, format:check clean.",
  "whatWasImplemented": "Created .claude/lib/mission/features-state-machine.cjs with loadFeatures(), transitionFeature(), validateFeatures(), and getEligibleFeatures(). Uses AJV for schema validation, atomic write via writeFileSync to .tmp + renameSync. Topological sort for cycle detection. Full state transition matrix: pending->in_progress, in_progress->validating, validating->completed, in_progress->failed, failed->pending.",
  "whatWasLeftUndone": "",
  "verification": {
    "commandsRun": [
      {
        "command": "node --test tests/mission/features-state-machine.test.cjs",
        "exitCode": 0,
        "observation": "14 tests passing, 0 failing"
      },
      { "command": "pnpm test", "exitCode": 0, "observation": "Full suite passes, no regressions" },
      { "command": "pnpm format:check", "exitCode": 0, "observation": "All files formatted" }
    ],
    "interactiveChecks": [
      {
        "action": "Required module and called loadFeatures() with valid fixtures",
        "observed": "Returns parsed features array with correct schema"
      },
      {
        "action": "Called transitionFeature with invalid transition pending->completed",
        "observed": "Throws INVALID_TRANSITION error as expected"
      }
    ]
  },
  "tests": {
    "added": [
      {
        "file": "tests/mission/features-state-machine.test.cjs",
        "cases": [
          { "name": "pending to in_progress succeeds", "verifies": "VAL-FS-001" },
          { "name": "in_progress to completed succeeds", "verifies": "VAL-FS-002" },
          { "name": "failed increments retry counter", "verifies": "VAL-FS-003" },
          { "name": "pending to completed rejected", "verifies": "VAL-FS-004" },
          { "name": "completed is terminal", "verifies": "VAL-FS-005" },
          { "name": "precondition blocks dependent", "verifies": "VAL-FS-006" },
          { "name": "precondition passes when met", "verifies": "VAL-FS-007" },
          { "name": "circular dependency detected", "verifies": "VAL-FS-008" },
          { "name": "malformed JSON rejected", "verifies": "VAL-FS-009" },
          { "name": "atomic write used", "verifies": "VAL-FS-010" }
        ]
      }
    ]
  },
  "discoveredIssues": []
}

When to Return to Orchestrator

Feature requires modifying existing .claude/lib/workers/ modules (bridge only, not modify)
Circular dependency found between new mission modules and existing modules
AJV schema from existing codebase conflicts with PRD-specified schema
Windows-specific issue blocks implementation (NTFS, path, process management)
Feature's preconditions reference modules that don't exist yet

Agent Skills: Mission Engine Worker

Install this agent skill to your local

Skill Files