oc-orchestrator

# Orchestrator

Pipeline coordinator for the opchain dev ecosystem. This skill does NOT build, audit,
deploy, or design — it reads every other skill's checkpoints, maintains a project
registry, and answers three questions:

1. **Where am I?** — Cross-skill status across all registered projects.
2. **What's next?** — The single highest-priority action based on pipeline position.
3. **Route me.** — Smart dispatch to the right skill based on intent.

This is an **additive layer**. Every existing skill retains its own welcome protocol
and works independently. The oc-orchestrator provides a better front door and a unified
view across projects — it doesn't replace any skill's internal logic.

---

## /oc-ops — Command Reference

```
ORCHESTRATOR COMMANDS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  STATUS
  /oc-ops                 Show all projects + active skill state
  /oc-ops status          Same as /oc-ops — full status dashboard
  /oc-ops status [project] Status for one project (all skills)

  ROUTING
  /oc-ops next            Recommend the single highest-priority action
  /oc-ops next [project]  Next action for a specific project
  /oc-ops route [intent]  Route a vague request to the right skill + phase

  PROJECT REGISTRY
  /oc-ops projects        List all registered projects with health
  /oc-ops register        Register a new project (path + name)
  /oc-ops unregister      Remove a project from the registry
  /oc-ops switch [project] Set the active project for this session
  /oc-ops scan            Auto-discover projects by scanning workspace

  PIPELINE
  /oc-ops pipeline        Show the canonical pipeline DAG
  /oc-ops pipeline [project] Show where a project sits in the pipeline
  /oc-ops blockers        Show all blockers across all projects
  /oc-ops recent          Last-known state per skill (sorted by recency)

  META
  /oc-ops health          Self-check: are all skill files accessible?
  /oc-ops skills          List all installed opchain skills with versions
  /checkpoint          Show oc-orchestrator state (registry + session, from the tracked checkpoint)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Type any command, or just describe what you need.
```

> **What's wired vs. what's a pattern.** The oc-orchestrator is a *reasoning* skill —
> most "commands" are behaviors Claude performs by reading checkpoints and routing,
> not shell entry points. The pieces backed by **real tooling** are the checkpoint
> reads/writes: `node scripts/checkpoint.mjs status | next | doctor | validate |
> update | done | init`. `/oc-ops status`, `/oc-ops next`, and `/oc-ops blockers` lean on
> those directly. `/oc-ops register`, `/oc-ops switch`, `/oc-ops scan`, `/oc-ops route`,
> `/oc-ops health`, `/oc-ops skills`, and the v1.2 PM verbs (`/oc-ops resume`, `/oc-ops ticket`,
> `/oc-ops pm-status`) are **agent behaviors** — described here as patterns, executed by
> Claude, with state persisted to the tracked checkpoint. None are dead ends, but
> don't expect a binary named `ops`.

---

## Session-Start Protocol

Run this on every new session, before doing any other oc-orchestrator work:

```bash
npm run checkpoint:status
```

That command prints a markdown summary of every `.checkpoints/<skill>.checkpoint.json`
in the project — phase, step, status, `next_actions`, and blockers. It
**is** the registry scanner for a single project; the architecture
diagram below describes how the same protocol scales to multi-project.

If the project doesn't have `npm run checkpoint:status` wired up
(common on cold projects), fall back to:

```bash
ls .checkpoints/*.checkpoint.json 2>/dev/null && cat .checkpoints/*.checkpoint.json
```

If `.checkpoints/` doesn't exist at all, this is a cold start. The
`oc-checkpoint-protocol` is not directly invocable — instead run its scaffolder:

```bash
node scripts/checkpoint.mjs init
```

That creates `.checkpoints/` + a starter README. Follow the oc-checkpoint-protocol
SKILL.md § "Scaffold Phase" to add the `package.json` scripts, the `.gitattributes`
merge driver, and the optional post-merge auto-stamp workflow before routing work.

**Do not** start routing or dispatching work until you've read the
checkpoint state. The whole point of the protocol is that the next
session resumes from the prior session's `next_actions[0]`, not from
chat history.

---

## Architecture

```
┌──────────────────────────────────────────────────────┐
│                    ORCHESTRATOR                       │
│                                                      │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────┐  │
│  │   Project    │  │  Checkpoint  │  │   Router    │  │
│  │   Registry   │  │   Scanner    │  │   Engine    │  │
│  │              │  │              │  │             │  │
│  │  Multi-proj  │  │  Reads ALL   │  │  Intent →   │  │
│  │  tracking    │  │  skill CPs   │  │  skill +    │  │
│  │              │  │  per project │  │  phase      │  │
│  └──────────────┘  └──────────────┘  └────────────┘  │
│           │                │                │         │
│           ▼                ▼                ▼         │
│  ┌─────────────────────────────────────────────────┐  │
│  │              Priority Engine                    │  │
│  │  Blockers > Failed > In-progress > Not-started  │  │
│  │  Pipeline order breaks ties                     │  │
│  └─────────────────────────────────────────────────┘  │
│                          │                            │
│                          ▼                            │
│                   /oc-ops next output                    │
│                   /oc-ops status output                  │
│                   /oc-ops route → active invocation      │
└──────────────────────────────────────────────────────┘
         │ reads                        │ dispatches to
         ▼                              ▼
  .checkpoints/*.json            Other opchain skills
  (all projects)                 (oc-app-architect, oc-code-auditor, etc.)
```

### Design