Orchestrator

On first invocation, read `references/orchestrator.md` and follow its welcome protocol.

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:

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:

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

Treat that direct read as the authoritative status source. The missing convenience command is not evidence that checkpoint state is unreliable, and it must not be reported as product progress or as a blocker. If the files exist, validate their claims against the named specs, git state, tests, and release artifacts as normal.

If .checkpoints/ doesn't exist at all, this is a cold start. The oc-checkpoint-protocol is not directly invocable. If this is the opchain.dev repo and its CLI exists, run its scaffolder:

node scripts/checkpoint.mjs init

In any other repo, create .checkpoints/ and the receiving skill's checkpoint directly with the file tools already available; do not assume scripts/checkpoint.mjs was copied into the project. Follow the oc-checkpoint-protocol SKILL.md § "Scaffold Phase" to add the package.json scripts and the .gitattributes merge driver only when the user asks to adopt the CLI. Do not scaffold a per-merge auto-stamp workflow — the protocol prohibits it (opchain shipped one and removed it 2026-06-22 after it deadlocked on branch protection and left ~24 open bot PRs). Routing and checkpoint writes do not wait for that tooling 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  │  │
│  │  Over-budget, then recency, 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 Constraints

1. Read-only coordinator. Orchestrator reads other skills' checkpoints but NEVER

writes to them. It persists its own state (registry, active project, routing history) in skill_state of .checkpoints/oc-orchestrator.checkpoint.json.

1. Additive, not gating. Skills work without the oc-orchestrator installed. The

oc-orchestrator makes the ecosystem smarter, not dependent.

1. No build artifacts. Orchestrator produces status reports and routing decisions,

never code, specs, designs, or documents.

1. Dispatch, don't duplicate. When routing, actively invoke the target skill

(read its SKILL.md, execute its command). Don't re-implement skill logic.

Project Registry

The registry tracks all projects the user is actively working on.

Persistence Model

Critical constraint: the worker filesystem is ephemeral — it resets between conversations and, on Claude Code for the web, between sessions on a fresh clone. Anything that must survive has to be committed to git. That is exactly why the checkpoint protocol tracks .checkpoints/ in git, and the oc-orchestrator persists the same way every other skill does: a single tracked file at

.checkpoints/oc-orchestrator.checkpoint.json

The project registry (names, paths, priority, monorepo apps) lives in that file's skill_state.registry. Routing history and the active project live in skill_state too. There is no memory_user_edits and no ~/.opchain/ session file — those were specified in an earlier draft and never worked on an ephemeral runner (memory edits aren't available in this runtime, and a home-dir file doesn't survive the clone). If you see references to them elsewhere, they're stale; the tracked checkpoint is the single source of truth.

On session start the oc-orchestrator reads its own checkpoint for the registry, then scans every other skill's checkpoint in the active project for live state — node scripts/checkpoint.mjs status where the project has the CLI, otherwise a direct read of .checkpoints/*.checkpoint.json. (Re-scanning is cheap — there's no separate cache layer to keep warm or invalidate.)

Registry Schema (stored in skill_state.registry of the tracked checkpoint)

{
  "projects": [
    {
      "id": "acme-core",
      "name": "acme-core",
      "path": "/Users/you/repos/acme-core",   // a real runtime path — see /oc-ops scan roots
      "type": "monorepo",
      "priority": "primary",
      "apps": ["storefront", "fieldkit", "atlas-crm", "acme-app", "billing"],
      "notes": "Main platform monorepo — Workers + D1 + KV"
    },
    {
      "id": "meridian",
      "name": "Meridian",
      "path": "/Users/you/repos/meridian",
      "type": "app",
      "priority": "secondary",
      "apps": null,
      "notes": "Compliance-training platform"
    }
  ],
  "default_project": "acme-core"
}

Schema design rationale:

• No `last_activity` or `tags` — derived at runtime from checkpoint timestamps

and manifest scanning. Caching derivable data creates staleness.

• `priority` instead of boolean `active` — values: primary, secondary,

archived. Primary projects surface first in /oc-ops next cross-project recommendations.

• `apps` array — for monorepos, lists sub-applications. Single-app projects

set this to null. Enables per-app checkpoint scanning and status grouping.

• `active_project` is not registry — it lives in skill_state.active_project,

starts as default_project each session, and is switched with /oc-ops switch.

Monorepo Sub-Project Handling

For monorepos like acme-core with multiple apps, the scanner checks for app-scoped checkpoints using subdirectories within .checkpoints/:

acme-core/
├── .checkpoints/
│   ├── oc-reverse-spec.checkpoint.json       ← project-wide (applies to whole repo)
│   ├── oc-git-ops.checkpoint.json            ← project-wide
│   ├── storefront/
│   │   ├── oc-app-architect.checkpoint.json  ← app-specific
│   │   └── oc-code-auditor.checkpoint.json
│   └── fieldkit/
│       └── oc-app-architect.checkpoint.json
├── apps/
│   ├── storefront/
│   ├── fieldkit/
│   └── atlas-crm/

This follows the existing checkpoint protocol convention (each skill writes {skill}.checkpoint.json) — the oc-orchestrator just adds an app-level directory grouping. Skills writing app-specific checkpoints set project_dir to {monorepo}/.checkpoints/{app}/ instead of {monorepo}/.checkpoints/.

Tooling-support note (important): the canonical CLI (scripts/checkpoint.mjs) scans only the top level of .checkpoints/ — it does not recurse into app subdirectories, and checkpoint:validate won't see subdir files either. A flat <app>-<skill>.checkpoint.json name does not work either: the validator requires every filename to equal <skill>.checkpoint.json (e.g. oc-app-architect.checkpoint.json). Per-app checkpoints are therefore not supported by the CLI today. The only validator-clean option is one checkpoint directory per app, pointed at explicitly: OPCHAIN_CHECKPOINTS_DIR=apps/storefront/.checkpoints node scripts/checkpoint.mjs status (and validate/doctor the same way). Without the CLI, read and write those files directly.

Status output groups by app within a monorepo:

▶ acme-core                               [active]
  Project-wide:
    ✅ oc-reverse-spec    complete     Specs for 4 apps
    ⏳ oc-git-ops         not started

  storefront:
    🔄 oc-app-architect   in_progress  Sprint 2/4
    ✅ oc-code-auditor    complete     Grade B+
    🚫 BLOCKER: F-003 rate limiting

  fieldkit:
    🔄 oc-app-architect   in_progress  Phase 3 design

Registration Flow (/oc-ops register)

1. Ask for project path (or detect from conversation context)
2. Scan {path}/.checkpoints/ for existing skill checkpoints
3. Read package.json, wrangler.toml, or other manifests for metadata
4. Detect monorepo structure (workspace config, apps/ directory)
5. If monorepo: inventory sub-applications, confirm app list with user
6. Determine priority (primary if first project, secondary otherwise)
7. Write skill_state.registry in .checkpoints/oc-orchestrator.checkpoint.json
8. Display initial status scan

Auto-Discovery

When any opchain skill is invoked and the project directory is NOT in the registry, the oc-orchestrator should auto-register it on next /oc-ops invocation. Detection: checkpoint files exist at a path not in the registry → suggest registration.

Cold Start (First-Ever Invocation)

When the oc-orchestrator is invoked with no skill_state.registry in its checkpoint and no checkpoint files found anywhere:

No projects registered yet. Let's set up your workspace.

I can scan for existing opchain checkpoints, or you can register a project manually.

  /oc-ops register [path]  — Register a specific project
  /oc-ops scan             — Scan common paths for checkpoint files

/oc-ops scan searches roots derived at runtime — never a hardcoded path. In order: the current working directory and its immediate children, then any parent that contains a .git, then the registry's existing project paths. It looks for .checkpoints/ directories or package.json / wrangler.* manifests and presents discovered projects for confirmation. (The old /home/claude/* literal was wrong on every runtime except one; don't reintroduce it.)

Checkpoint Scanner

The core read engine. For a given project, scans all skill checkpoints and produces a unified status view.

Scan Process

# Preferred where the project has the CLI (the opchain repo, or a project that
# adopted it): let it read + summarize the active project.
test -f {project.path}/scripts/checkpoint.mjs && \
  ( cd {project.path} && node scripts/checkpoint.mjs status )

# Raw fallback (flat layout — the supported default):
ls {project.path}/.checkpoints/*.checkpoint.json 2>/dev/null
# If you adopt the (unsupported-by-CLI) subdir layout, the glob is
# */*.checkpoint.json — NOT */checkpoint.json, which never matches the
# <app>/<skill>.checkpoint.json naming:
ls {project.path}/.checkpoints/*/*.checkpoint.json 2>/dev/null

For each checkpoint found:

1. Read header: skill, updated_at, status
2. Read progress_table: phase completion
3. Read blockers: any unresolved?
4. Read next_actions: what's queued?
5. Do NOT interpret skill_state (private to owning skill). The shared CLI's

drift check scans it for merged/shipped tokens only; this skill does not read it.

Every /oc-ops command re-scans; there is no scan cache to reuse or invalidate (see Persistence Model).

Unified Status Output (/oc-ops status)

OPCHAIN STATUS — All Projects
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

▶ acme-core                                [active]
  ✅ oc-reverse-spec      complete     Specs generated for 4 apps
  🔄 oc-app-architect     in_progress  Sprint 2/4 — CRUD API (storefront)
  ✅ oc-code-auditor      complete     Grade B+, 2 HIGH findings open
  ⏳ oc-deploy-ops        not started
  ⏳ oc-git-ops           not started
  🚫 BLOCKER: rate limiting gap (oc-code-auditor F-003)
  → Next: Fix F-003, then resume oc-app-architect sprint 2

▶ acme-app
  🔄 oc-app-architect     in_progress  Phase 3 — design pipeline
  ⏳ oc-code-auditor      not started
  → Next: Complete design approval gate

▶ meridian
  ✅ oc-dash-forge        complete     Exec archetype, prototype delivered
  ⏳ oc-app-architect     not started
  → Next: Feed oc-dash-forge handoff into oc-app-architect Phase 3d

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  3 projects | 2 active pipelines | 1 blocker

Single-Project Status (/oc-ops status [project])

Deeper view for one project — shows full progress tables per skill, all blockers with proposed resolutions, and the complete next_actions queue.

Priority Engine (/oc-ops next)

Recommends the single most important action across all projects (or for a specific project). Priority rules, in order:

Priority Hierarchy

1. BLOCKED items needing user_decision     (you're the bottleneck)
2. FAILED skills needing recovery          (something broke)
3. IN_PROGRESS skills at a gate            (approval needed to continue)
4. IN_PROGRESS skills mid-work             (resume where you left off)
5. Pipeline-next for completed skills      (chain to the next skill)
6. NOT_STARTED skills in pipeline order    (start the next logical skill)

Where the CLI matches, and where it doesn't. Ranks 1–5 are encoded in scripts/checkpoint.mjs (rankCheckpoint / the next command), with one addition: a checkpoint whose status is blocked (without a user_decision blocker) ranks with FAILED at 2. The CLI's rank 6 is the catch-all for any other checkpoint that exists; a skill with no checkpoint is never ranked, so "start the next logical skill" is this skill's reasoning, not the CLI's. Within a rank the CLI breaks ties over-budget first, then most recent updated_at; it has no pipeline-order concept. For a single project, follow node scripts/checkpoint.mjs next where the project has the CLI. The oc-orchestrator adds the cross-project weighting (below) on top. Before recommending, run node scripts/checkpoint.mjs doctor where the project has the CLI (otherwise compare next_actions against recent git history yourself) so you don't surface a next_action that's already been shipped (the stale-action failure mode).

Ties and pipeline order

Same-rank ties break the way the CLI breaks them: over-budget first, then the most recently updated checkpoint (user momentum). Pipeline order decides only which skill to suggest at ranks 5–6 (the next skill after a completed one, or the first not-started one), following the canonical map in references/orchestrator.md § 2 Pipeline Map rather than a copy kept here.

Cost / Budget Awareness (v1.6 — the instrumented pipeline)

When oc-cost-ops has written its cost block (it lives only in the oc-cost-ops checkpoint, so that is the one checkpoint this can flag), /oc-ops next factors budget into the ranking as a tiebreaker within a priority level (it does not override the hierarchy above — a decision blocker still wins). Among same-rank items, a checkpoint whose attributed spend has passed its ceiling (cost.total_usd > cost.budget_usd) sorts first, and the recommendation is prefixed ⚠ over budget ($X > $Y). Overspending is something you want surfaced now, alongside resuming the work. Encoded as budgetExceeded() in scripts/checkpoint.mjs and wired into pickNext / recommendedAction, so /oc-ops next and node scripts/checkpoint.mjs next agree. (eval_scores on a checkpoint inform the same "what needs attention?" read — a skill trending down on its rubric is a candidate for the next pass.)

Cross-Project Priority

When recommending across projects, the priority engine layers project weight on top of the action-level hierarchy:

1. Project priority class — primary projects outrank secondary at the same

action priority level. A blocker on a secondary project still outranks routine progress on a primary project (action priority wins first), but two in-progress items tie-break to the primary project.

1. Recency — within the same priority class, the more recently active project

gets slight priority (user momentum).

1. Session context — if the user has been working on project X this conversation,

favor project X for /oc-ops next unless another project has a strictly higher-priority action.

The user can override priority class with /oc-ops register or by editing skill_state.registry in the tracked checkpoint directly.

Output Format

NEXT ACTION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Project: acme-core (storefront)
Skill:   oc-code-auditor
Action:  Fix finding F-003 (missing rate limiting on /api/auth/*)
Why:     Blocks oc-app-architect sprint 2 evaluator pass + oc-deploy-ops gate
Command: /oc-audit fix F-003

Run it now? (Y) proceeds, (N) shows the next item in the queue.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

On (Y): oc-orchestrator actively invokes the recommended skill with the right context.

Router Engine (/oc-ops route)

Smart dispatch for vague or multi-skill requests. This operationalizes the Smart Routing Table in references/orchestrator.md § 4 — that table is the one copy, with a row for every skill; route from it. This skill adds no rows of its own. The one difference in use: when the user asks "what should I work on", answer with /oc-ops next (the single highest-priority action) after the /oc-ops status view § 4 names.

Routing Process

1. Parse the user's intent from their message
2. Check if a project context is clear (active project, or mentioned by name)
3. If project is ambiguous AND multiple projects exist, ask which project
4. Match intent to routing table
5. Check the target skill's checkpoint for that project (resume vs. fresh start)
6. Actively invoke the target skill — read its SKILL.md, execute the command

Fallback: No Match

If the intent doesn't match any routing table entry:

1. Check if it's a general question (not a pipeline action) → answer directly, no routing
2. If it seems like a pipeline action but is ambiguous → ask ONE clarifying question in

chat (AskUserQuestion when available) with 2-3 options mapped to the most likely skills

1. Never guess — a wrong route wastes more time than a clarifying question

Ambiguity Handling

If the intent is genuinely ambiguous (maps to 2+ skills equally), present the options with one-line explanations:

That could go a few directions:

1. oc-code-auditor /oc-audit security — if you want to find vulnerabilities
2. oc-security-auditor /oc-security posture — if you want a full security posture review
3. oc-code-auditor /oc-audit fix-all — if you already know the issues and want fixes

Which one?

Never present more than 3 options.

Pipeline Visualization (/oc-ops pipeline)

Shows the canonical pipeline DAG with the project's current position highlighted.

Text-Based Pipeline View

PIPELINE — acme-core (storefront)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✅ oc-reverse-spec ──► 🔄 oc-app-architect ──► ⏳ oc-git-ops ──► ⏳ oc-deploy-ops
                           │
                           ├── ✅ oc-stack-forge (Phase 2)
                           ├── ⏳ oc-ux-engineer (Phase 3/6)
                           └── 🔄 Sprint 2/4 in progress
                                  └── 🚫 Blocked: F-003

  Quality plugins:
    ✅ oc-code-auditor     Grade B+ (2 HIGH open)
    ⏳ oc-scale-ops        Not run
    ⏳ oc-integrations-engineer  Not needed (no external APIs)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Blockers Dashboard (/oc-ops blockers)

Aggregates all blockers from all checkpoints across all projects.

BLOCKERS — All Projects
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  acme-core (storefront)
  🚫 B1: Missing rate limiting on auth endpoints
     Source: oc-code-auditor F-003
     Blocking: oc-app-architect sprint 2
     Needs: code_fix
     Resolution: Add rate-limit middleware → /oc-audit fix F-003

  acme-app
  🚫 B1: Design direction not approved
     Source: oc-app-architect Phase 3 gate
     Blocking: oc-app-architect punch list
     Needs: user_decision
     Resolution: Review style book + wireframes → /approve

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  2 blockers | 1 code fix | 1 user decision

Skill Health Check (/oc-ops health)

Verifies the ecosystem is intact. Read every value at runtime — do not print remembered version numbers (they go stale, and a health check that lies is worse than none):

# For each skill directory under skills/:
# 1. SKILL.md exists and its YAML frontmatter parses.
# 2. version comes from that frontmatter (NOT a hardcoded table).
# 3. references/orchestrator.md + references/checkpoint-protocol.md are present
#    and in sync:  npm run sync-bundles:check
#    (node scripts/sync-skill-bundles.mjs --check — opchain repo only, like the
#    checkpoint CLI below)
# 4. The shared checkpoint writer exists ONCE at the repo root:
#    test -f scripts/checkpoint.mjs   (there is NO per-skill checkpoint.sh)
# 5. Checkpoints validate:  npm run checkpoint:validate

Sample shape (versions shown as vX.Y.Z because they're read live, not memorized):

ECOSYSTEM HEALTH
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✅ oc-app-architect     vX.Y.Z   SKILL.md ✓  references ✓ (in sync)
  ✅ oc-code-auditor      vX.Y.Z   SKILL.md ✓  references ✓ (in sync)
  ✅ oc-orchestrator      vX.Y.Z   SKILL.md ✓  (self)
  …one row per skill under skills/…

  shared writer: scripts/checkpoint.mjs ✓   checkpoints: npm run checkpoint:validate ✓
  N skills + 1 protocol | all healthy
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Activity Snapshot (/oc-ops recent)

Checkpoints store only their most recent updated_at — there's no historical event log. /oc-ops recent reconstructs a snapshot from what's available: each skill's last update timestamp and progress_summary, sorted reverse-chronologically.

LAST KNOWN STATE — Per Skill
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  15:30 today   acme-core      oc-code-auditor   Audit complete, grade B+
  14:45 today   acme-core      oc-app-architect  Sprint 2/4 in progress
  yesterday     acme-app       oc-app-architect  Phase 3 design started
  3 days ago    meridian       oc-dash-forge     Prototype delivered
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

This is a "last seen" view, not a timeline. For dispatch history, read skill_state.routing_history in this skill's tracked checkpoint.

Checkpoint Integration

One tracked checkpoint (like every other skill)

The oc-orchestrator stores its own state in .checkpoints/oc-orchestrator.checkpoint.json, tracked in git so it survives the ephemeral worker. The cross-project registry and the per-session routing history both live in that file's skill_state. It still reads other skills' checkpoints at their standard {project}/.checkpoints/ locations — but for its own state there is no memory layer and no ~/.opchain/ file.

skill_state shape

{
  "registry": {
    "projects": [ /* see Registry Schema above */ ],
    "default_project": "acme-core"
  },
  "active_project": "acme-core",         // starts as default each session; /oc-ops switch changes it
  "last_scan": "2026-04-21T15:30:00Z",
  "scan_summary": {
    "acme-core": { "skills_found": ["oc-reverse-spec", "oc-app-architect", "oc-code-auditor"], "blocker_count": 1, "status_summary": "Sprint 2/4, 1 blocker" }
  },
  "routing_history": [
    { "at": "2026-04-21T15:30:00Z", "intent": "audit the code", "routed_to": "oc-code-auditor", "project": "acme-core" }
  ]
}

scan_summary is a convenience snapshot from the last scan — it's re-derived by re-scanning (node scripts/checkpoint.mjs status where the project has the CLI), never trusted as a cache.

Session Start Sequence

1. Read .checkpoints/oc-orchestrator.checkpoint.json → skill_state.registry.

If the file or the key is absent (a checkpoint holding only session logs has none), treat it as a cold start, not as corruption.

1. If the registry has projects: scan each path (node scripts/checkpoint.mjs status

where that project has the CLI; otherwise read its .checkpoints/*.checkpoint.json directly), refresh scan_summary, and write the checkpoint.

1. If the registry is empty or absent: cold start flow (see Project Registry § Cold

Start). On a project with no .checkpoints/ at all, run node scripts/checkpoint.mjs init where the CLI exists; otherwise create .checkpoints/ with the file tools.

Error Handling

Cross-Skill Reads

When to Write

All writes go to the one tracked checkpoint. With the CLI, object values need the :json suffix and appends a trailing +, e.g. node scripts/checkpoint.mjs update oc-orchestrator --skill_state.active_project=acme-core --skill_state.routing_history:json+='{"at":"2026-04-21T15:30:00Z","intent":"audit the code","routed_to":"oc-code-auditor","project":"acme-core"}'; without it, edit the file directly:

/checkpoint Behavior

Like every other skill, the oc-orchestrator has one tracked checkpoint. /checkpoint summarizes its skill_state:

ORCHESTRATOR STATE  (.checkpoints/oc-orchestrator.checkpoint.json — tracked in git)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Registry:
  3 projects (acme-core [primary], meridian, acme-app)
  Default: acme-core

Session:
  Active: acme-core
  Last scan: 2 min ago
  Routing history: 3 dispatches this session
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Smart Behaviors

Session Start Detection

When the oc-orchestrator is invoked at the start of a conversation (no prior messages), run an automatic scan and present the most relevant status:

Welcome back. Here's where things stand:

▶ acme-core has a blocker (rate limiting fix needed)
▶ acme-app is waiting on your design approval

/oc-ops next recommends: Fix F-003 on acme-core (unblocks the build pipeline)

Stale Checkpoint Detection

If a checkpoint's updated_at is >7 days old and status is in_progress:

⚠️ acme-core / oc-app-architect hasn't been updated in 9 days.
   Last status: Sprint 2 in progress.
   This might be stale. Resume or reset?

Pipeline Completion Detection

Not every project uses every skill. The oc-orchestrator determines the applicable pipeline for a project by checking which skills have ever written a checkpoint (or were referenced in another skill's checkpoint as a dependency).

A project is "pipeline complete" when all skills that have checkpoints show status: complete AND no skill's next_actions references an uninvoked skill.

When detected:

🎉 meridian — pipeline complete!
   oc-dash-forge ✅ → oc-app-architect ✅ → oc-git-ops ✅ → oc-deploy-ops ✅
   (oc-scale-ops, oc-integrations-engineer not applicable — no checkpoints)
   Archive this project? (/oc-ops unregister meridian)

Implicit Project Detection

If the user says "deploy storefront" and storefront is a known app in the acme-core monorepo, the oc-orchestrator should:

1. Set active project to acme-core
2. Route to oc-deploy-ops with the storefront app context
3. No extra question needed

Relationship to orchestrator.md

Two different things share the word "oc-orchestrator" — don't conflate them: - `oc-orchestrator` (this skill) — /oc-ops: multi-project registry, cross-project status, priority engine, routing. Has commands and a checkpoint. - `orchestrator.md` (the shared protocol doc) — bundled into every skill's references/, read on first invocation. Defines the welcome protocol, pipeline map, chaining, and novice mode. No commands; it's a spec every skill follows.

>

(The filename is kept as-is deliberately: every skill except oc-checkpoint-protocol is instructed to "read references/orchestrator.md" on startup (build-enforced by scripts/gen-skills-catalog.mjs), so renaming it is a high-blast-radius change for low value. The disambiguation header at the top of that file makes the distinction clear in place.)

The shared orchestrator.md file bundled in every skill remains as-is. It defines:

• Welcome protocol (each skill's own entry behavior)
• Pipeline map (reference for all skills)
• Active chaining protocol (how skills invoke each other)
• Novice mode (guided walkthrough)

The oc-orchestrator skill adds:

• Multi-project registry (orchestrator.md has no concept of multiple projects)
• Cross-project status aggregation (orchestrator.md scans one project at a time)
• Priority engine (orchestrator.md has no prioritization logic)
• Routing with project context (orchestrator.md's routing table doesn't consider which project)
• Activity history (orchestrator.md has no temporal tracking)

Over time, skills may choose to delegate their welcome protocol to the oc-orchestrator (check if oc-orchestrator checkpoint exists → read active project from it → skip own project detection). But this is opt-in, not required.

PM-Tool MCP Integration (v1.2+)

The oc-orchestrator already reads every skill's checkpoint to answer "where did I leave off?". v1.2 makes it PM-aware by reading the pm_refs field added in oc-checkpoint-protocol v1.2 — the oc-orchestrator becomes a router by ticket id, not just by project / phase.

See pm-mcp-protocol.md in oc-integrations-engineer/references for the shared PM-MCP contract, including advisory failure handling and checkpoint reconciliation rules.

Cross-skill PM thread aggregation

/oc-ops reads pm_refs across every skill checkpoint in every registered project, then aggregates:

Active threads (by ticket):

  PLAT-4471 — Add CSV export to /api/customers
    oc-app-architect     spec-approved   (source)
    oc-git-ops           PR opened       (linked)
    oc-deploy-ops        shipped         (deploy: PLAT-4485)
    oc-monitoring-ops    resolved        (incident: PLAT-4503)

  AEGIS-9 — Migrate auth provider Auth0 → Clerk
    oc-migration-ops     step 4/9        (parent + 9 children)
    oc-deploy-ops        ─               (waiting)

  EXP-12 — Image-search prototype
    oc-app-architect     /oc-discover       (source)
    oc-stack-forge       decided         (ADR-7)

The view collapses by project but is queryable by ticket: /oc-ops ticket PLAT-4471 shows that thread alone.

/oc-ops resume TICKET-ID — route by ticket

New verb (v1.2). User says "resume work on PLAT-4471" and the oc-orchestrator:

1. Searches pm_refs across all skill checkpoints for the

ticket id.

1. Identifies which skill last touched it + what phase.
2. Recommends the next action, citing the specific skill and

command. Examples:

• "Last touched by oc-git-ops 2 days ago — PR is in review.

Run /oc-git-sync to refresh it."

• "Last touched by oc-app-architect Phase 4. Next: /oc-build."

/oc-ops next (existing verb, v1.2-enhanced)

/oc-ops next already considers project + phase. v1.2 also considers PM-ticket priority:

• A ticket marked Urgent or priority:high in the PM tool

surfaces ahead of lower-priority backlog work.

• Tickets with an unblocked dependency surface ahead of blocked

ones.

• Stale-but-active threads (no checkpoint write in > 7d) get a

stale? annotation.

/oc-ops pm-status — what does the PM tool say?

New advisory verb. Queries the configured PM-MCP for the user's assigned tickets in In Progress state, cross-references with checkpoint state, and reports inconsistencies:

PM ↔ checkpoint reconciliation:

  PLAT-4471 — In Progress (PM)   ↔   shipped (oc-deploy-ops)
    ⚠  PM ticket should be Done. Likely auto-transition failed.
    Suggested: /oc-git-sync --retry-pm

  AEGIS-9 — In Progress (PM)     ↔   step 4/9 (oc-migration-ops)
    ✓  In sync.

  CHURN-3 — In Progress (PM)     ↔   no checkpoint
    ⚠  PM says you're working on this; no opchain skill
       has a checkpoint. Did you start outside opchain?

This is a hygiene tool, not an enforcement layer. Reconciliation problems are usually transient (deferred PM writes, MCP outages during a transition).

Multi-project routing

In a multi-project setup (oc-orchestrator's existing strength), pm_refs are namespaced by project so the oc-orchestrator never confuses PLAT-1 from project A with PLAT-1 from project B (different PM workspaces, different broker scopes).

Failure modes

• No PM-MCP configured anywhere → /oc-ops operates as v1.1; no

PM aggregation; the existing project / phase view is the full picture.

• PM-MCP available but pm_refs field absent in a skill's

checkpoint → that skill simply doesn't appear in the PM thread view; oc-checkpoint-protocol v1.2 backfill happens on the skill's next write.

• Cross-project PM ambiguity → oc-orchestrator prompts the user

to disambiguate when a ticket id appears in multiple PM workspaces.

Principles

1. Read everything, write only your own state. The oc-orchestrator's power

comes from its cross-skill read access. It never modifies another skill's checkpoints. Its own state lives in skill_state of its tracked checkpoint.

1. Recommend, don't block. /oc-ops next is a recommendation, not a gate. The user

can always invoke any skill directly.

1. One answer per question. /oc-ops next returns ONE action, not a list. The user

can ask again for the next item in the queue.

1. Project context is first-class. Every command accepts an optional project

argument. If omitted, use skill_state.active_project or skill_state.registry.default_project.

1. Pipeline order picks the next skill. Same-rank ties break over-budget, then

most recent; pipeline order chooses which skill to start or chain to next.

1. Dispatch, don't duplicate. When routing, read the target skill's SKILL.md and

invoke its command. Don't re-implement skill logic inside the oc-orchestrator.

1. Stale data is worse than no data. Flag old checkpoints. Don't present week-old

status as current truth.