From 462dadf741b90d81bfa07bd17bb8e90a42852c19 Mon Sep 17 00:00:00 2001 From: Carson Davis Date: Fri, 26 Jun 2026 10:03:42 -0500 Subject: [PATCH 1/2] add initial orchestration skill --- .claude/skills/orchestrating-issues/SKILL.md | 91 ++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 .claude/skills/orchestrating-issues/SKILL.md diff --git a/.claude/skills/orchestrating-issues/SKILL.md b/.claude/skills/orchestrating-issues/SKILL.md new file mode 100644 index 000000000..fcb1877c5 --- /dev/null +++ b/.claude/skills/orchestrating-issues/SKILL.md @@ -0,0 +1,91 @@ +--- +name: orchestrating-issues +description: Use when the user hands off one or more GitHub issues for you to take from intake to a draft PR — especially when they ask you to pull latest, spin up a worktree per issue, run sub-agents in parallel to implement and review, commit and push, and report back when branches are ready for a live smoke test. +--- + +# Orchestrating Issues to Draft PRs + +## Overview + +Run one or more GitHub issues end-to-end — intake to draft PR — as a **thin orchestrator**: sequence the phases, hold the human gates, and delegate the actual work to the skills named in the phase table below. + +**Core principle: one issue = one worktree = one branch = one booted deployment = one draft PR.** Issues never share state. Run independent issues in parallel; when one depends on another, sequence them. You are the conductor — sub-agents do the implementing and reviewing inside their own worktrees. + +## Human gates (do not blow past these) + +The whole point is that the user stays in the loop at three moments. Stop and wait for them: + +1. **After intake** — present your plan back: per-issue scope against each issue's acceptance criteria, the dependency/parallelism graph, and any file/migration overlap between issues. Surface clarifying questions. *Wait* for approval before touching code. +2. **At smoke test** — report each branch as ready and *wait* while you and the user go back and forth on the live deployment until it actually works. +3. **At PR review** — open *draft* PRs, then read the user's GitHub comments and address them in a loop until they're satisfied. Re-verify each change in proportion to its size — a logic change re-runs tests + smoke (Verify 6, Smoke 7); a comment/doc tweak gets a lighter check. + +Everything between gates runs autonomously. + +## Phases + +| Phase | What you do | Delegate to | +|-------|-------------|-------------| +| 1. Intake | Read each issue — **body and all comments** (`gh issue view --comments`). Distill scope against each issue's acceptance criteria; map dependencies (seed from the issues' own parent/sequence links); spot file/migration overlap between issues; list genuine clarifying questions. **Gate: present the plan, wait for approval.** | — | +| 2. Sync | Pull the latest default branch (usually `development`) so worktrees branch from current code. | — | +| 3. Provision | Create each issue's branch **linked to the issue**, then a worktree + local deployment on it (see *Branch creation* below). | **mmgis-deployment** (`create.sh`, `start.sh`) | +| 4. Implement | Dispatch one sub-agent per worktree, scoped to that directory, to do the work — committing and pushing as it goes. Tell it the issue's collapsed plan is a stale sketch to re-investigate, but to heed any marked gotcha. Run independent issues in parallel; sequence dependent ones (downstream branches off the upstream branch, not bare `development`). | **superpowers-extended-cc:dispatching-parallel-agents** | +| 5. Review | After each implementation, have a **fresh agent that didn't write the code** review it; the implementer addresses findings, then the reviewer re-checks the changed lines. | **superpowers-extended-cc:requesting-code-review** (or the `code-reviewer` agent) | +| 6. Verify | Run that branch's tests **and check the issue's acceptance criteria** (coverage is partial — acceptance is the real bar). Never report "tested" without seeing the output. | **mmgis-deployment** (`test.sh`), **superpowers-extended-cc:verification-before-completion** | +| 7. Smoke handoff | Boot each deployment, capture the dashboard URL/port, and report (see contract below). Make sure the branch is pushed first. **Gate: iterate with the user until it works live.** | **mmgis-deployment** (`start.sh`) | +| 8. Draft PR | Open a **draft** PR per issue; body must close the issue (`Closes #N`). | **superpowers-extended-cc:finishing-a-development-branch** | +| 9. Address feedback | Read the user's PR comments from GitHub and resolve them. Each substantive change loops back through **Verify (6) and Smoke (7)** before it counts as resolved. Repeat until the user is satisfied. | **superpowers-extended-cc:receiving-code-review** | + +## Branch creation (link the branch to its issue) + +Make each branch with **`gh issue develop`** so it's natively tied to the issue (the +only way — you can't link a branch after the fact), then hand it to `create.sh`: + +```bash +gh issue develop --name # add --base for a dependent/stacked issue +git fetch origin : # local ref so create.sh reuses it (plain `fetch origin ` won't) +.../mmgis-deployment/scripts/create.sh --branch +``` + +This covers the pre-PR and stacked window that `Closes #N` (Phase 8) can't. + +## The smoke-test report contract + +At the Phase 7 gate, report per issue — only claim what you've verified: + +- **Issue / branch / worktree** — `#N`, branch name, worktree path. +- **Tested** — which suites ran and that they passed (cite the result, don't assert it). +- **Acceptance** — each criterion from the issue's top layer, met or not. +- **Reviewed** — review done and findings addressed. +- **Committed & pushed** — branch is on the remote. +- **Live** — the booted dashboard URL/port the user opens to smoke-test. + +Then hand control back: the user drives the live test, you fix what they find, and you only open draft PRs once the smoke test passes. + +## Parallelism and ordering + +Work out the dependency graph at intake. **Independent issues** run concurrently — provision and dispatch them at once, one sub-agent per worktree, each blind to the others. **Dependent issues** run in sequence — the downstream worktree branches off the upstream branch so it builds on that work, and its sub-agent starts only once the upstream is committed. + +A stacked downstream's base keeps moving — the upstream branch changes through review, smoke fixes, and PR feedback. Each time it does, **rebase the downstream worktree onto the updated upstream and re-run Verify**, so the base never drifts. The downstream draft PR targets the **upstream branch** (a stacked PR); retarget it to the default branch once the upstream merges — only then does its `Closes #N` fire. + +Isolation holds regardless of ordering: the orchestrator (you) owns the deployment lifecycle and the gates; sub-agents own implementation and review inside their assigned directory. Don't let one agent reach into another's worktree. + +## When to stop and ask + +You run autonomously between gates, but stop and surface these rather than pushing through: + +- **An issue is bigger than one PR.** Even right-sized issues sometimes sprawl once you're in the code. Propose a split (per the issue right-sizing convention) instead of ballooning the PR. +- **Tests can't pass locally** (flaky, infra, environment). Don't claim a green you didn't get — document why and get the user's call. +- **Merge conflicts you can't cleanly resolve** — surface them, especially across stacked issues. + + + +## Common mistakes + +- **Skipping the issue comments.** The body is half the story; decisions and corrections live in the comments. Read both. +- **Following the issue's bottom-layer plan literally.** It's pinned to an old commit and meant to be re-verified — re-investigate the current code; only the explicitly marked gotchas are meant to be trusted. +- **Starting before the intake gate.** Surfacing questions *and then coding anyway* defeats the purpose. Wait for real answers. +- **Claiming "tested/reviewed/ready" without evidence.** The report contract is a verification claim — back each line with the actual run, per verification-before-completion. +- **Sharing state across issues.** One worktree, branch, DB, and port per issue. Cross-contamination here is the one failure this structure exists to prevent. +- **Opening a non-draft PR, or merging.** PRs are drafts the user reviews; they decide when it's ready. Never merge on their behalf. +- **Forgetting `Closes #N`.** Each PR body must close its issue (per the repo's PR convention). +- **Creating the branch unlinked.** A plain `git checkout -b` / bare `create.sh` makes a branch with no tie to its issue, and you can't link it afterward. Always create it via `gh issue develop` (see *Branch creation*). From 0824d08e93caf6c1a891f4f1e7e7e207a6268bc1 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Fri, 26 Jun 2026 15:06:57 +0000 Subject: [PATCH 2/2] chore: bump version to 4.2.12-20260626 [version bump] --- configure/package.json | 2 +- package.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/configure/package.json b/configure/package.json index b920c8496..2d0ff6e99 100644 --- a/configure/package.json +++ b/configure/package.json @@ -1,6 +1,6 @@ { "name": "configure", - "version": "4.2.11-20260611", + "version": "4.2.12-20260626", "homepage": "./configure/build", "private": true, "dependencies": { diff --git a/package.json b/package.json index b55026871..63354f6d6 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "mmgis", - "version": "4.2.11-20260611", + "version": "4.2.12-20260626", "description": "A web-based mapping and localization solution for science operation on planetary missions.", "homepage": "build", "repository": {