rockets-orchestrator

name: rockets-orchestrator description: This skill should be used when generating an entire Rockets SDK project from a spec, bootstrapping multiple entities at once, or when the user has a plan.json file. Orchestrates wave-based generation with dependency ordering and validation gates. Works sequentially by default; supports Agent Teams for parallel execution. Requires rockets-crud-generator.

Rockets Orchestrator

Generates complete Rockets SDK projects from a parsed spec — multiple entities, relations, ACL — with automatic dependency ordering, validation gates, and progress tracking.

Requires: rockets-crud-generator must be installed as a sibling skill.

Quick Start

# Sequential mode (no Agent Teams needed)
node skills/rockets-orchestrator/scripts/orchestrate.js \
  --project ./apps/api \
  --spec .rockets/plan.json

# Dry run (show waves without executing)
node skills/rockets-orchestrator/scripts/orchestrate.js \
  --project ./apps/api \
  --spec .rockets/plan.json \
  --dry-run

# Resume from last checkpoint
node skills/rockets-orchestrator/scripts/orchestrate.js \
  --project ./apps/api \
  --resume

How It Works

1. Topological Sort

Entities are sorted by dependency graph (relations). Entities with no dependencies are generated first. Entities that depend on others wait until their dependencies are done.

Wave 1: Category, Tag          (no deps)
Wave 2: Product                 (depends on Category)
Wave 3: ProductTag              (depends on Product, Tag)

2. Wave Execution

Each wave runs:

1. Generate: generate.js for each entity in the wave
2. Integrate: integrate.js writes files + wires into project
3. Validate: validate.js checks structural rules
4. Gate: if validation fails, stop and report (don't continue to next wave)

3. Migration Generation

After all waves complete and build passes:

1. Try typeorm migration:generate (requires a running database) — ~98% confidence
2. Fallback if no DB: static migration from entity configs — ~65-70% confidence
3. Static migrations carry a disclaimer comment; prefer DB-verified generation for production

4. Final Smoke Test

After all waves + migration:

1. Run validate.js --build for full TypeScript compilation check
2. Optionally run smoke-test-endpoints.js for HTTP endpoint testing

5. Cross-Session State

Progress is saved to .rockets/state.json in the project directory:

{
  "startedAt": "2026-02-25T10:00:00Z",
  "waves": [
    { "index": 0, "entities": ["category", "tag"], "status": "completed" },
    { "index": 1, "entities": ["product"], "status": "in_progress" }
  ],
  "completedEntities": ["category", "tag"],
  "failedEntities": [],
  "currentWave": 1
}

Use --resume to continue from the last checkpoint.

Spec Format (.rockets/plan.json)

The plan.json is created by the rockets-planner agent. See agents/rockets-planner.md for the full schema and rules.

Each entity in plan.json follows the same config schema as rockets-crud-generator (see skills/rockets-crud-generator/SKILL.md). The orchestrator passes each entity config directly to generate.js.

Agent Teams Mode

When CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is enabled, the /rockets-from-doc command creates a team instead of running the script:

Teammates communicate directly — Reviewer sends fixes to Generator without going through Lead. Tasks use the built-in task list with blockedBy dependencies matching the topological sort.

Scripts

Options

Output

{
  "success": true,
  "waves": [
    {
      "index": 0,
      "entities": ["category", "tag"],
      "status": "completed",
      "generated": 2,
      "validated": true
    }
  ],
  "summary": {
    "totalEntities": 4,
    "completed": 4,
    "failed": 0,
    "buildPassed": true,
    "smokeTestPassed": true
  }
}