Orchestrate

---
name: orchestrate
description: Enhance any repository with CI, tests, skills, and security through phased PRs - self-replicating
---

```mermaid
flowchart TD
    START(["/orchestrate"]) --> HAS_SCAN{Has scan report?}

    HAS_SCAN -->|No| SCAN["orchestrate:scan"]:::orch
    SCAN --> PLAN["orchestrate:plan"]:::orch
    HAS_SCAN -->|Yes| HAS_PLAN{Has plan?}

    HAS_PLAN -->|No| PLAN
    HAS_PLAN -->|Yes| NEXT_PHASE{Next phase?}

    NEXT_PHASE -->|Phase 2| PRECOMMIT["orchestrate:precommit<br/>PR #1"]:::orch
    NEXT_PHASE -->|Phase 3| TESTS["orchestrate:tests<br/>PR #2"]:::orch
    NEXT_PHASE -->|Phase 4| CI["orchestrate:ci<br/>PR #3"]:::orch
    NEXT_PHASE -->|Phase 5| SECURITY["orchestrate:security<br/>PR #4"]:::orch
    NEXT_PHASE -->|Phase 6| REPLICATE["orchestrate:replicate<br/>PR #5"]:::orch
    NEXT_PHASE -->|Phase 7| REVIEW["orchestrate:review"]:::orch

    PRECOMMIT --> TESTS
    TESTS --> CI
    CI --> SECURITY
    SECURITY --> REPLICATE
    REPLICATE --> REVIEW
    REVIEW -->|optional| ONBOARD_LINK["onboard:link"]:::onb
    ONBOARD_LINK --> ONBOARD_STD["onboard:standards"]:::onb
    REVIEW --> DONE([All phases complete])

    classDef orch fill:#FF9800,stroke:#333,color:white
    classDef onb fill:#9C27B0,stroke:#333,color:white
    classDef check fill:#FFC107,stroke:#333,color:black
    class HAS_SCAN,HAS_PLAN,NEXT_PHASE check
```

> Follow this diagram as the workflow.

# Orchestrate Skills

Enhance any repository with CI, tests, skills, and security through a series of phased PRs. Each phase produces a focused, reviewable PR of 600-700 lines.

## Entry Point Routing

When `/orchestrate` is invoked, determine the action:

```
What was provided?
    |
    +-- /orchestrate <repo-path>
    |     New target. Clone or locate the repo, then start from scan.
    |     Example: /orchestrate .repos/my-service
    |
    +-- /orchestrate <phase>
    |     Jump to a specific phase. Requires scan + plan to already exist.
    |     Example: /orchestrate ci
    |
    +-- /orchestrate status
          Show current orchestration state for all tracked targets.
```

### Route logic

1. **`/orchestrate <repo-path>`** -- If the path points to a git repository, derive the target name from the directory basename. Check `/tmp/rossoctl/orchestrate/<target>/` for existing state. If no scan report exists, invoke `orchestrate:scan`. If scan exists but no plan, invoke `orchestrate:plan`. If both exist, determine the next incomplete phase and invoke it.

2. **`/orchestrate <phase>`** -- Validate that `scan-report.md` and `plan.md` exist for the current target. If missing, instruct the user to run `/orchestrate <repo-path>` first. Otherwise invoke the requested phase skill directly (e.g., `orchestrate:precommit`).

3. **`/orchestrate status`** -- List all directories under `/tmp/rossoctl/orchestrate/`, read each target's `phase-status.md`, and display a summary table showing target name, current phase, and completion percentage.

## Phase Status Tracking

All orchestration state is persisted under `/tmp/rossoctl/orchestrate/<target>/`:

| File | Purpose |
|------|---------|
| `scan-report.md` | Output of `orchestrate:scan` -- repo structure, tech stack, gaps |
| `plan.md` | Output of `orchestrate:plan` -- enhancement plan with phases and PR scope |
| `phase-status.md` | Tracks which phases are complete, in-progress, or pending |

The `phase-status.md` file uses this format:

```markdown
# Orchestration Status: <target>

| Phase | Status | PR | Updated |
|-------|--------|----|---------|
| scan | complete | -- | 2025-01-15 |
| plan | complete | -- | 2025-01-15 |
| precommit | complete | #42 | 2025-01-16 |
| tests | in-progress | #43 | 2025-01-17 |
| ci | pending | -- | -- |
| security | pending | -- | -- |
| replicate | pending | -- | -- |
| review | pending | -- | -- |
```

Each phase skill is responsible for updating `phase-status.md` when it starts and completes.

## Phase Overview

| Phase | Skill | PR | Description |
|-------|-------|-----|-------------|
| 0 | orchestrate:scan | -- | Assess target repo structure, tech stack, and gaps |
| 1 | orchestrate:plan | -- | Brainstorm enhancements and produce a phased plan |
| 2 | orchestrate:precommit | PR #1 | Pre-commit hooks, linting, and code formatting |
| 3 | orchestrate:tests | PR #2 | Test infrastructure and initial test coverage |
| 4 | orchestrate:ci | PR #3 | Comprehensive CI: lint, test, build, security scanning, dependabot, scorecard |
| 5 | orchestrate:security | PR #4 | Security governance: CODEOWNERS, SECURITY.md, CONTRIBUTING.md, LICENSE |
| 6 | orchestrate:replicate | PR #5 | Bootstrap Claude Code skills into the target repo |
| 7 | orchestrate:review | -- | Review all orchestration PRs before merge |

Phases are sequential. Each PR builds on the previous one. Tests come before CI (so CI can run them) and before security (so code refactoring for security fixes has test coverage as a safety net). The scan and plan phases do not produce PRs -- they produce artifacts that guide all subsequent phases.

## Self-Replication

Phase 6 (`orchestrate:replicate`) is what makes this system fractal. It copies a starter set of Claude Code skills into the target repository, including a tailored version of the orchestrate skill itself. Once replicated, the target repo can orchestrate other repos using the same phased approach.

This means every repository that goes through orchestration gains the ability to orchestrate others. The skills adapt to the target's tech stack (the scan report informs what language-specific linters, test frameworks, and CI patterns to use).

## Quick Start

```bash
# Clone target repo into a working directory
git clone git@github.com:org/repo.git .repos/repo-name

# Run the full orchestration pipeline
# /orchestrate .repos/repo-name

# Or jump to a specific phase (if scan + plan already exist)
# /orchestrate precommit

# Check status across all targets
# /orchestrate status
```

## Related Skills

### Orchestrate sub-skills

| Skill | Description |
|-------|-------------|
| `orchestrate:scan` | Assess target repo structure and identify gaps |
| `orchestrate:plan` | Produce a phased enhancement plan |
| `orchestrate:precommit` | Add pre-commit hooks, linters, formatters |
| `orchestrate:ci` | Comprehensive CI: lint, test, build, security scanning, dependabot, scorecard |
| `orchestrate:tests` | Add test infrastructure and initial test coverage |
| `orchestrate:security` | Security governance: CODEOWNERS, SECURITY.md, CONTRIBUTING.md, LICENSE |
| `orchestrate:replicate` | Bootstrap Claude Code skills into the target |
| `orchestrate:review` | Review all orchestration PRs before merge |

### Onboard skills

| Skill | Description |
|-------|-------------|
| `onboard:link` | Link a newly-orchestrated repo to Rossoctl |
| `onboard:standards` | Apply organizational standards and conventions |