--- name: priivacy-ai/spec-kitty-program-orchestrate source: https://app.decimal.ai/s/priivacy-ai-spec-kitty-program-orchestrate@1/SKILL.md source_sha256: 9d10137518d7 --- # 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/--.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 `. 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 ` 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 `. Expect potential stale-lane errors when many WPs touched overlapping files. The rebase pattern is: `cd .worktrees/-lane- && git merge kitty/mission-`, 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: ```bash mv .worktrees /tmp/-worktrees-parked for wp in WP01 WP02 ...; do spec-kitty agent tasks move-task "$wp" --to done --mission done mv /tmp/-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: ```bash cat .kittify/missions/$(jq -r .mission_id kitty-specs//meta.json)/retrospective.yaml ``` If the record is absent (older mission or generation failed), author it now — context decays fast: ```bash spec-kitty retrospect create --mission ``` Then surface findings: ```bash spec-kitty retrospect summary # cross-mission aggregation (read-only) spec-kitty agent retrospect synthesize --mission # inspect proposals (dry-run by default) spec-kitty agent retrospect synthesize --mission --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/-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). ### Dispatch hygiene - Cap concurrent sub-agents at ~6 to avoid overwhelming the task notification channel. More than that and you lose track of which agent owns which WP. - Use distinctive descriptions in every `Agent` dispatch (`description` field). "Implement repo4 WP06 slack webhook" is readable; "Implement the thing" is not. - Track dispatched IDs in a scratchpad you can grep. When you get a ``, you need to know which repo and which WP it corresponds to without re-reading your own prior turns. --- ## Step 4: Pulse Heartbeat (Mandatory for Uninterrupted Runs) When the user has authorized uninterrupted work ("keep pushing", "work without interruption", or equivalent), always keep a `ScheduleWakeup` armed at all times as a pulse-monitor safety net. ### Why Task notifications wake you on sub-agent completion, but: - A sub-agent can die silently (sandbox kill, OOM, hung tool call). - The notification can be delayed or lost (backend hiccup). - You yourself can silently hang — the only thing that will unstick you is a scheduled wakeup. Silence is not success. A scheduled heartbeat is the difference between "I was working the whole time" and "I sat silent for two hours waiting for a dead agent". ### How - Delay: 1200–1800s (20–30 min). Shorter than ~270s burns cache without useful signal; longer than ~1800s risks the user noticing a stall before you do. - Reason: one specific sentence (`"Checking in on repo 4 WP06 impl after dispatch + 2 parallel reviews; expect for_review or approved state"`). - Prompt: pass the same `/loop ...` instruction verbatim each turn so the wakeup re-enters this skill and continues the loop. On each heartbeat fire: 1. Run `TaskList` to find running agents. 2. For each running agent, peek output (via `TaskOutput` non-blocking). 3. For each repo, run `spec-kitty agent tasks status --mission ` and check for stuck WPs (in_review >15min with no active reviewer, for_review with no reviewer dispatched). 4. If everything is green and still-working, report "all green" with the specific signal you saw (N tool calls in last 5min from each agent), then re-arm the wakeup. 5. If anything is stuck, dispatch a repair or chase agent. Stop the pulse only when the entire program is closed (all repos merged, all mission reviews cleared, all remediations landed). --- ## Step 5: Handle the Recurring Friction Points These friction points are known and tracked upstream. Expect them; have the workaround ready in your dispatch prompts. | Friction | When it hits | Workaround | Upstream | |---|---|---|---| | Test-DB collisions across parallel lanes | Django-backed projects with ≥2 concurrent lane runs | `DJANGO_TEST_DATABASE_NAME=test__lane_ --create-db` | #770 | | Stale lane on merge | Missions where multiple WPs touched `pyproject.toml` / `urls.py` / shared `__init__.py` | `cd .worktrees/-lane- && git merge kitty/mission-` per stale lane, resolve, retry outer merge | #771 | | Post-merge invariant check on `.worktrees/` | Every successful merge | `mv .worktrees /tmp/park && move-task WP## --to done && mv back` | #772 | | Silent repo fallback when target isn't initialized | Phase 1 on a repo without `.kittify/` scaffold | Detect via `ls /kitty-specs/` after the status commit phase; if empty and another repo got the artifacts, relocate + `spec-kitty init --ai ` in the real target | #773 | | `spec-kitty decision` not found | Sub-agents referencing the `decision` command group | Use `spec-kitty agent decision ...` | #774 | | `review-request` is not a real command | Sub-agents trying to submit a WP for review | Use `spec-kitty agent tasks move-task WP## --to for_review` | #775 | --- ## Step 6: Memory and Feedback Capture At the start and throughout the program, persist specific feedback to the memory system: - **Autonomy scope**: the exact phrasing the user used to authorize autonomous operation on which repos. - **Architectural decisions locked in by earlier repos**: these become constraints for later repos. Save as project memories so later repo phases can load them without re-asking. - **Recurring user preferences**: the user's cadence preference ("never wait more than 5 min"), their preferred sub-agent model, their tolerance for parallelism. At the end of the program: - Capture the debrief patterns the user surfaces — which frictions cost the most time, which parts of the mission workflow they valued, what they would change. These inform future programs. --- ## Step 7: Final Report At the end of the program, produce a concise shipping summary: ``` Decision Moment V1 — Program Complete | # | Repo | Issue | Merge | Mission review | Post-merge fixes | |---|---|---|---|---|---| | 1 | ... | ... | ... | ... | ... | Architecture locks in place: - owns - owns <...> - ... Known follow-ups (non-blocking): - — ``` If the user asks for a debrief, be honest about what worked and what didn't. The retrospective is worth more than the shipping report for future programs. --- ## Key Rules 1. **Sequence the repos, don't serialize the work.** Many phases can run in parallel across repos; the serial constraint is on the dependency graph, not on your calendar. 2. **Pulse heartbeat or it didn't happen.** If you run uninterrupted without a ScheduleWakeup armed, you will eventually silently stall. 3. **Mission review catches real bugs.** Never skip it. Budget for remediation. 4. **Dispatch with context, not just a task ID.** Every sub-agent prompt should include the cross-repo contract references, the locked architectural rules from earlier repos, and the known friction workarounds (test-DB name, stale-lane pattern). Do not make them re-derive what you already know. 5. **When you discover a friction point not in Step 5 above**, file it as a GitHub issue against the tracker and add it to this skill in a follow-up PR. The program is also an opportunity to make the tool better. 6. **Be honest in the debrief.** The user is tracking whether the program landed AND whether it was worth running it this way. Give them real signal, not a success-narrative.