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 Workflow

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 structured; a focused agent produces better WP prompts than an orchestrator splitting attention. Reference the companion skill for the task-generation workflow.

Verify the returned report: WP count, subtask tally per WP, requirement coverage (unmapped_functional must be empty), finalize commit hash.

2e. Phase 4 — Implement-Review Loop

Use spec-kitty-implement-review as your loop engine. Per-WP pattern:

1. Dispatch implementer sub-agent with a prompt that includes the WP's dependencies, any cross-repo context (especially contracts from earlier repos), and explicit instructions to use the test-DB workaround for Django-backed projects (see issue #770 for why).
2. On for_review notification, dispatch reviewer sub-agent with a prompt that includes the adversarial checklist and any WP-specific risks surfaced during planning.
3. On approved, chain the next unblocked WP per the dependency DAG.
4. On rejected, read the review cycle file, dispatch a focused remediation agent with the exact blocker list, then re-review.

2f. Phase 5 — Accept and Merge

Run spec-kitty accept --mission <slug> after all WPs are approved. Treat it as a pre-merge readiness nudge for the orchestrator and the human operator. If it passes, run spec-kitty merge --mission <slug>. Expect potential stale-lane errors when many WPs touched overlapping files. The rebase pattern is: cd .worktrees/<slug>-lane-<letter> && git merge kitty/mission-<slug>, resolve conflicts (usually union-merge on TOML/imports/comments), commit, retry the outer merge. See issue #771 for planned auto-rebase support.

2g. Phase 6 — Move WPs Done (workaround for the invariant check)

The post-merge bookkeeping often fails on .worktrees/ being untracked. Workaround:

mv .worktrees /tmp/<slug>-worktrees-parked
for wp in WP01 WP02 ...; do
  spec-kitty agent tasks move-task "$wp" --to done --mission <slug>
done
mv /tmp/<slug>-worktrees-parked .worktrees

This is tracked upstream as issue #772.

2h. Phase 7 — Mission Review

Dispatch a sub-agent that invokes the spec-kitty-mission-review skill on the just-merged mission. Do not shortcut this step — the mission review reliably catches real bugs that slipped past per-WP review (FR-to-test coverage gaps, dead code, API whitelist misses, TOCTOU races on external side effects).

2i. Phase 8 — Retrospective

The canonical post-merge sequence is: mission review → author or verify retrospective (retrospect create) → surface findings (summary aggregates; synthesize reviews proposals).

Under default 3.2.0 policy, the retrospective.yaml is authored during merge. Verify it:

cat .kittify/missions/$(jq -r .mission_id kitty-specs/<slug>/meta.json)/retrospective.yaml

If the record is absent (older mission or generation failed), author it now — context decays fast:

spec-kitty retrospect create --mission <slug>

Then surface findings:

spec-kitty retrospect summary                              # cross-mission aggregation (read-only)
spec-kitty agent retrospect synthesize --mission <slug>  # inspect proposals (dry-run by default)
spec-kitty agent retrospect synthesize --mission <slug> --apply  # apply proposals (mutates)

If retrospective.yaml is missing and retrospect create fails, escalate — check status.events.jsonl for RetrospectiveCaptureFailed events and their remediation_hint.

2j. Phase 9 — Post-Merge Remediation

If the mission review verdict is PASS WITH NOTES with any HIGH or MEDIUM findings, dispatch a remediation sub-agent to fix them on a post-merge/<slug>-mission-review-fixes branch, then merge that branch back to main with --no-ff. LOW findings can be deferred as follow-up issues unless they are user-visible.

Step 3: Parallel Dispatch Pattern

Do not drive the program serially. Within each repo and across repos, dispatch work in parallel wherever the dependency graph allows.

Within a repo

• After WP01 + WP02 approve, WPs 03, 04, 06, 08 may all be independently unblocked depending on the DAG. Dispatch them all in parallel, one sub-agent per WP.
• Reviewers and next-WP implementers can run simultaneously — a reviewer for WP05 does not conflict with an implementer for WP07 if they own different files.

Across repos

• Once repo A reaches MVP (enough WPs merged for repo B to consume its APIs), begin repo B's phase 1 (specify) in parallel with repo A's remaining WPs.
• If the user has authorized autonomy on repo C, spawn the full-workflow sub-agent for repo C while repo A is still finishing. Nothing in phase 1-3 depends on earlier repos being merged unless the spec explicitly requires consuming a merged API during planning (rare).