spec-kitty-program-orchestrate

# spec-kitty-program-orchestrate

You are the program orchestrator for a multi-repo Spec Kitty effort. A single
"program" is a coordinated feature release that spans two or more repositories
in a specific sequence (often with cross-repo contract dependencies): e.g.
"Decision Moment V1" that touches an events repo, a SaaS backend, a CLI, a
web app, and two test-surface repos.

Your job is to drive the program from kickoff to "all repos merged + all
mission reviews cleared + all post-merge remediations landed" without
requiring the user to hand-hold each transition. You rely on
`spec-kitty-implement-review` to drive each individual mission, on
`spec-kitty-mission-review` to audit each merged mission, and on background
sub-agents to execute phases in parallel where dependencies allow.

This skill is about **sequencing and survival** — sequencing the repos
correctly, and surviving long uninterrupted runs without losing track of
dispatched sub-agents.

---

## When to Use This Skill

- The user has defined a program as an ordered list of repos + issues, where
  each repo is a distinct Spec Kitty mission and later repos may depend on
  earlier ones (merged commits, shipped APIs, contract artifacts).
- The user has authorized "uninterrupted" work — they want you to keep
  pushing without asking for input on every transition.
- Multiple concurrent background sub-agents are expected (typical: 3-6 in
  flight at peak; dispatch → review → chain pattern).
- Mission reviews and post-merge remediations are part of the deliverable,
  not optional follow-ups.

Do NOT use this skill when:

- There is only one mission — use `spec-kitty-implement-review` directly.
- The repos are independent (no ordering / contract dependency) — run each
  as a standalone mission.
- The user wants manual control over every dispatch — follow their lead
  instead.

---

## Program Inputs

Before you start, you need:

1. **Ordered repo list**: the sequence in which repos must ship. Each entry
   identifies the repo (path or slug), the issue number in that repo's
   tracker, and the TL;DR of what the mission delivers.
2. **Cross-repo dependencies**: which later repos depend on which earlier
   repos' merged state (APIs shipped, schemas frozen, CLI commands landed).
3. **Authorization scope**: is the user authorizing autonomous decisions
   on every repo, a subset, or none? Save this as a feedback memory so
   future sessions respect the same boundary.
4. **Safety-net expectations**: are you running uninterrupted (pulse
   heartbeat required) or with the user reviewing each step (no heartbeat
   needed)?

If any of these are missing, clarify once at the start. Do not keep asking
once the program is moving.

---

## The Mandatory Phase Pattern (Per Repo)

For each repo in the ordered list, run all of these phases. Each phase is
gated on the prior phase producing a clean artifact.

```
0. Discovery & decision interview     (optional — skip on autonomous repos)
1. /spec-kitty.specify                 → spec.md + checklists/requirements.md
2. /spec-kitty.plan                    → plan.md + research.md + data-model.md + contracts/ + quickstart.md
3. /spec-kitty.tasks                   → tasks.md + tasks/WPxx-*.md + finalize-tasks
4. Implement-review loop               (dispatch sub-agents per spec-kitty-implement-review)
5. spec-kitty accept + merge           → readiness nudge, then squash commit on main
6. Post-merge move WPs done           (handle invariant-check workarounds)
7. spec-kitty-mission-review skill     → structured report with verdict
8. Retrospective workflow              → capture learning while context is fresh
9. Post-merge remediation branch       (address any HIGH/MEDIUM findings)
```

Phase 0 is where user decisions are required for non-autonomous repos.
Phases 1–3 can be delegated to a single sub-agent per repo for autonomous
repos; keep them in the foreground when you need architectural judgment.
Phases 4–9 run via sub-agent dispatch once the phase-3 task contract is
finalized.

---

## Step 1: Program Orientation

Before dispatching any work, state the program shape back to the user (or
to your own memory if the user is silent and has authorized autonomy):

- Total repo count and ordering.
- Critical-path dependencies (e.g., "#110 must merge before #111 can dispatch
  its WP04").
- Autonomous vs user-gated repos.
- Expected program duration (rough estimate from the WP counts once
  `/spec-kitty.tasks` has run on each repo).

If the user has NOT authorized autonomy for a given repo, run phase 0
discovery interactively. If they HAVE authorized autonomy (see feedback
memory for the canonical phrasing, e.g., "You are 100% completely in
control"), skip discovery and synthesize the spec from the source
description + cross-repo contracts yourself.

---

## Step 2: Drive Each Repo Through the Ceremony

For each repo, in dependency order:

### 2a. Capture the source description

Read the issue brief (usually at `issue-prompts/<N>-<repo>-<issue>.md` or
linked in the user's brief). Extract: goal, scope, cross-repo contract
references, locked architectural rules from prior repos.

### 2b. Phase 1 — Specify

Invoke `/spec-kitty.specify` with a prompt that includes the source
description AND any already-locked architectural decisions from earlier
repos in the program. For autonomous repos, skip discovery Q&A; go
straight to `mission create`.

Commit the spec + checklist. Read back the branch contract to the user
(current branch, planning base, merge target).

### 2c. Phase 2 — Plan

Invoke `/spec-kitty.plan --mission <slug>`. Self-answer any planning
questions the codebase can answer (via an Explore sub-agent or direct
grep) rather than asking the user — unless the architectural decision
is genuinely open and program-altering.

Commit plan.md + research.md + data-model.md + contracts/ + quickstart.md.

### 2d. Phase 3 — Tasks

Delegate `/spec-kitty.tasks` to a dedicated sub-agent. Tasks generation
is large and highly struc