[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M77HF16ENJ3V66CTMC2QVDEV":3,"skill-same:01M77HF16ENJ3V66CTMC2QVDEV":49},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":27,"commitSha":28,"skillDirectory":29,"forksCount":30,"repositoryHtmlUrl":31,"repositoryHomepageUrl":32,"ownerHtmlUrl":33,"ownerBlogUrl":34,"ownerDescription":6,"updatedAt":35,"install":36,"resources":48},"01M77HF16ENJ3V66CTMC2QVDEV","issue-orchestrator",null,"Plan, partition, and coordinate multi-wave parallel subagent campaigns to resolve and close GitHub issues. Uses `fak issue-orchestrator --plan-waves` (or `fak issue-lanes`) to partition the backlog into tree-disjoint cohorts, arbitrates lane and tree leases via `dos arbitrate`, dispatches isolated worker subagents per wave, independently witnesses landed fixes, commits with explicit paths and issue citations, and drives burndowns. Use when running bulk issue resolution, feature wave burndowns, or multi-agent issue campaigns.","anthony-chaudhary\u002Ffak","anthony-chaudhary","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F18080164?v=4","01M77GSKCAEKV3JS07J40B94DY","Anthony Chaudhary","01M77GSKD26Z7F4FQQD4VA30VX",48,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fanthony-chaudhary\u002Ffak\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fissue-orchestrator\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: issue-orchestrator\ndescription: Plan, partition, and coordinate multi-wave parallel subagent campaigns to resolve and close GitHub issues. Uses `fak issue-orchestrator --plan-waves` (or `fak issue-lanes`) to partition the backlog into tree-disjoint cohorts, arbitrates lane and tree leases via `dos arbitrate`, dispatches isolated worker subagents per wave, independently witnesses landed fixes, commits with explicit paths and issue citations, and drives burndowns. Use when running bulk issue resolution, feature wave burndowns, or multi-agent issue campaigns.\ndisable-model-invocation: false\nuser-invocable: true\nallowed-tools: Read, Bash, Write, Edit, Grep, Glob, Task\nargument-hint: \"[--top 10] [--target-issues 5] [--wave-size 4] [--max-waves 2] [--spawn-opencode] [--dry-run] [--worktree] [--model \u003Cmodel>] [--interactive] [--from-issues issues.json]\"\n---\n\n# \u002Fissue-orchestrator — campaign-scale multi-wave issue resolution\n\n> **The Campaign Coordinator for General Issue Work.** While atomic issue resolution targets 1–3\n> issues in isolation via [`\u002Fissue-queue`](..\u002Fissue-queue\u002FSKILL.md) (the issue counterpart of [`\u002Fdebt-clean`](..\u002Fdebt-clean\u002FSKILL.md)),\n> `\u002Fissue-orchestrator` coordinates **large volumes of general issue work**\n> across multiple concurrent subagent waves. It partitions the active issue backlog into\n> **pairwise tree-disjoint, concurrent-safe cohorts**, verifies or acquires lane leases via\n> `dos arbitrate`, dispatches parallel workers (via in-harness subagents or fresh OpenCode chat sessions),\n> independently witnesses each worker's effects, commits explicit paths with issue citations `(#N)`, and\n> tracks campaign burndown velocity against a baseline.\n\nThe shape: **baseline campaign (`fak issue-orchestrator --json`) → automated safe wave planning (`fak issue-orchestrator --plan-waves`) → pre-dispatch arbitration (`dos arbitrate`) → parallel dispatch (in-harness `task` or `fak issue-orchestrator --spawn-opencode`) → harvest & independently witness → commit leaf-by-leaf with `(#N)` → compare burndown → loop.**\n\n---\n\n## Dual Dispatch Execution Modes\n\n`\u002Fissue-orchestrator` supports two first-class dispatch execution modes depending on the execution context:\n\n- **Mode A: In-Harness Subagents (`task` tool calls with `subagent_type=\"worker\"`)**\n  - Best when running inside an interactive harness session that supports nested subagent orchestration.\n  - Workers run as child tasks within the coordinator harness, returning receipts directly into the coordinator turn.\n- **Mode B: Spawning Fresh OpenCode Chats of Their Own (`fak issue-orchestrator --spawn-opencode`)**\n  - Best when running headless, batch, or multi-session campaigns where each issue needs an independent, isolated agent process.\n  - Spawns fresh OpenCode chat processes (`opencode run` or interactive `opencode run -i`) with distinct session titles (`Issue #\u003CN>: \u003Ctitle>`), independent database sessions (`ses_...`), dedicated output logs, and optional detached worker worktrees.\n\n---\n\n## Defaults and Operational Boundaries\n\nWhen invoked without explicit arguments or under underspecified requests, apply these reasonable defaults:\n\n- **Bounded Evaluation (`--top 10`)**: ALWAYS bound backlog evaluation to the top 10–15 candidate issues (e.g. `fak issue-orchestrator --top 10`). Never run unbounded sweeps across hundreds of backlog tickets, which wastes tokens evaluating irrelevant triage queues.\n- **Action-First Velocity**: Prioritize immediate wave execution over prolonged baseline analysis. Plan Wave 1, arbitrate, dispatch workers, and land code.\n- **Target Issues**: Default to resolving a focused cohort of **3–5 issues** per session.\n- **Wave Concurrency (`--wave-size`)**: Default to **4–8 concurrent workers** per wave (scaling up to 16 with adaptive concurrency on capable multi-core hosts). Concurrency is safely gated by pairwise tree-disjointness (`dos.toml` declares 894 concurrent leaves).\n- **Max Waves per Run (`--max-waves`)**: Default to **1–2 waves** per run. Avoid unbounded multi-wave loops without checkpoints.\n- **Scratch & State Hygiene**: Baseline snapshots belong in allocated scratch or temporary JSON files (`fak tree-doctor --scratch-path issue-orchestrator\u002Fbaseline.json`), never untracked root dumps. Clean them up on completion.\n- **Worker Isolation**: Each subagent gets exactly one issue and one package lane (`internal\u002F\u003Clane>`), touches only declared files, runs only package-scoped tests (`go test -v .\u002Finternal\u002F\u003Clane>`, `go vet .\u002Finternal\u002F\u003Clane>`), and returns a 3-line receipt.\n- **Witness & Commit Cadence**: Coordinator independently verifies (`go vet`, `go test`) and commits each successful worker leaf individually with DCO sign-off, Conventional Commits, issue number citation `(#N)`, and lane ship-stamp `(fak \u003Clane>)` before proceeding to the next wave.\n\n---\n\n## Architectural Invariants (The Orchestration Laws)\n\n1. **Automated Tree-Disjoint Concurrency**:\n   Never allow concurrent subagents to touch overlapping directories or packages. Two workers\n   editing the same Go package break compilation for each other. Use `fak issue-orchestrator --plan-waves --wave-size N`\n   to partition candidate issues into verified pairwise tree-disjoint waves with zero cross-package\n   import contention.\n2. **Live Lease Arbitration & Exclusion**:\n   Before dispatching any subagent, the coordinator must verify or acquire the lane lease via\n   `dos arbitrate --workspace . --lane \u003Clane> --kind keyword --mode exclusive` (or the `dos_arbitrate` MCP tool).\n   `fak issue-orchestrator --plan-waves` automatically discovers and excludes any active leases held in\n   `.dos\u002Flane-journal.jsonl`. If an issue's lane is held by another agent, the orchestrator skips it and advances\n   the next candidate from the wave plan without colliding.\n3. **Multi-Orchestrator Concurrency**:\n   Multiple orchestrator loops or independent agents can operate concurrently on the repository:\n   each agent respects the shared lane taxonomy and lease journal. When two agents seek work simultaneously,\n   `dos arbitrate` grants mutually disjoint lanes to each, preventing collision by construction.\n4. **Serial Core Gates**:\n   High-blast-radius core leaves (`internal\u002Fabi`, `internal\u002Fkernel`, `internal\u002Fadjudicator`,\n   `internal\u002Fpolicy`, `internal\u002Fgateway`, `internal\u002Fvdso`, `internal\u002Fshipgate`, `internal\u002Farchitest`) touch root types imported across the repository.\n   They must NEVER run concurrently with peer workers—the planner automatically isolates them into\n   dedicated, single-worker serial waves (`serial_singleton`).\n5. **Strict Subagent Fences & Scoped Verification**:\n   Subagents must edit ONLY within their assigned package directory. They must NEVER touch root\n   files, `go.mod`, `go.sum`, `dos.toml`, or sibling packages. Subagents must run ONLY package-scoped\n   tests (`go test -v .\u002Finternal\u002F\u003Clane>`, `go vet .\u002Finternal\u002F\u003Clane>`), NEVER broad `go test .\u002F...` which\n   could fail on unrelated in-flight peer edits.\n6. **Subdivide Epics, Triage Unclear Scope**:\n   Oversized issues (>15 expected steps or touching 3+ subsystems) are routed to the `Subdivide` queue\n   to be broken into atomic leaves before dispatch. Issues with unclear scope or missing acceptance\n   criteria are routed to `Triage`. The orchestrator dispatches only concrete leaf units.\n7. **Coordinator Stays Clean**:\n   The coordinator dispatches, adjudicates conflicts, witnesses proofs, and tracks the campaign burndown.\n   Substantive implementation and test runs happen inside isolated subagent tasks (`subagent_type=\"general\"`\n   using Gemini 3.8 Flash high `variant: high`).\n8. **Witness Before Close**:\n   An issue is resolved only when its reproduction or contract test passes green on disk. The commit message\n   must cite the issue number `(#N)` and carry the `(fak \u003Clane>)` trailer.\n\n---\n\n## Phase 1 — Quick Bounded Planning & Target Selection\n\nPlan the immediate actionable wave bounded to top candidate issues:\n\n```bash\n# Fast path: plan immediate actionable wave bounded to top candidate issues:\nfak issue-orchestrator --top 10 --max-waves 1\n\n# If tracking a formal burndown comparison, capture baseline bounded to cohort:\nfak issue-orchestrator --top 15 --max-waves 2 --json > campaign-baseline.json\n```\n\nFrom the output, determine:\n- **Starting Scope**: e.g., `10 total issue(s) evaluated · 2 dispatchable · 0 subdivide · 8 triage`.\n- **Campaign Target**:\n  - *Default Focused Target*: Resolve **2–4 issues** in Wave 1 immediately.\n  - *Alternative Point Target*: Retire a fixed step budget (e.g. `--target-points 15`).\n- **Wave Capacity**: Standard reasonable wave size is **4–8 parallel subagents** (`--wave-size 8`, up to 16 on high-capacity hosts).\n- **Campaign Horizon**: Standard execution batch is **1–2 waves** (`--max-waves 1` or `2`).\n\n---\n\n## Phase 2 — Automated Concurrent-Safe Wave Planning\n\nGenerate provably collision-free, concurrent-safe waves using `fak issue-orchestrator`:\n\n```bash\n# Plan campaign waves bounded to top candidate issues (wave size 4, max 2 waves):\nfak issue-orchestrator --top 15 --wave-size 4 --max-waves 2\n\n# Or plan from a specific issue source (e.g. local snapshot or gh export):\nfak issue-orchestrator --from-issues issues.json --wave-size 4 --max-waves 2\n\n# Include ready-to-run OpenCode spawn commands in JSON\u002FMarkdown wave plan:\nfak issue-orchestrator --top 15 --wave-size 4 --max-waves 2 --opencode-commands\n\n# Or emit machine-readable wave plan JSON (includes opencode_command per issue and opencode_chats per wave):\nfak issue-orchestrator --top 15 --wave-size 4 --max-waves 2 --opencode-commands --json > wave-plan.json\n```\n\nThe planner automatically:\n1. **Discovers and Excludes Held Leases**: Scans `.dos\u002Flane-journal.jsonl` and excludes all active held leases in the workspace.\n2. **Enforces Pairwise Tree-Disjointness**: Proves that no two issues in a wave share directory paths or parent\u002Fchild containment.\n3. **Decouples Package Import Contention**: Checks the Go internal import graph to ensure workers in the same wave do not contend on shared internal package APIs.\n4. **Isolates Serial Singletons**: Identifies critical core leaves and schedules them into dedicated `serial_singleton` single-worker waves.\n5. **Extracts Subdivide & Triage Queues**: Pulls oversized epics into `Subdivide` with a child-issue budget and unready tickets into `Triage`.\n6. **Renders OpenCode Commands (`--opencode-commands`)**: Emits structured, copy-pasteable or machine-readable `opencode run` CLI invocations for each planned wave issue with appropriate titles, boundary path instructions, and verification commands.\n\n---\n\n## Phase 3 — Pre-Dispatch Arbitration & Parallel Worker Dispatch\n\nFor each wave in the plan:\n\n### 1. Pre-Dispatch Lane Arbitration\n\nBefore launching workers, verify each lane in the wave is free to acquire:\n\n```bash\ndos arbitrate --workspace . --lane \u003Clane> --kind keyword --mode exclusive\n```\n*(Or invoke the `dos_arbitrate` tool).*\n\n- **Admitted (`outcome: acquire`)**: Proceed to dispatch worker on `\u003Clane>`.\n- **Refused (`outcome: refuse`)**: Another peer agent took the lane. Log refusal, skip this lane, and advance the next candidate issue from the wave plan.\n\n### 2. Dispatch Workers (Option A or Option B)\n\nChoose between in-harness subagents (Option A) or spawning fresh OpenCode chat sessions (Option B):\n\n#### Option A: In-Harness Subagents (`task` tool)\n\nLaunch all admitted workers in parallel in a single turn using multiple `task` tool calls with `subagent_type=\"worker\"` under strict fences (using Gemini 3.8 Flash high `variant: high` for hard work):\n\n```json\n[\n  {\n    \"tool\": \"task\",\n    \"parameters\": {\n      \"subagent_type\": \"worker\",\n      \"description\": \"Resolve #1024 gateway streaming timeout\",\n      \"prompt\": \"You are an isolated worker for issue #1024: Fix gateway streaming timeout.\\nLane: gateway\\nBoundaries: Edit ONLY files under internal\u002Fgateway\u002F. NEVER touch go.mod, go.sum, dos.toml, or root files.\\nVerification: Run ONLY package-scoped tests: `go test -v .\u002Finternal\u002Fgateway` and `go vet .\u002Finternal\u002Fgateway`. NEVER run `go test .\u002F...`.\\nDeliverable: Fix the timeout issue and add a reproduction unit test.\\nReturn: Return a compact 3-line receipt: (1) files created\u002Fedited, (2) package test result, (3) confirmation of defect fix.\"\n    }\n  },\n  {\n    \"tool\": \"task\",\n    \"parameters\": {\n      \"subagent_type\": \"worker\",\n      \"description\": \"Resolve #1035 model kv cache recycling\",\n      \"prompt\": \"You are an isolated worker for issue #1035: Add model KV cache recycling.\\nLane: model\\nBoundaries: Edit ONLY files under internal\u002Fmodel\u002F. NEVER touch go.mod, go.sum, dos.toml, or root files.\\nVerification: Run ONLY package-scoped tests: `go test -v .\u002Finternal\u002Fmodel` and `go vet .\u002Finternal\u002Fmodel`. NEVER run `go test .\u002F...`.\\nDeliverable: Implement the KV cache recycling path with reproduction unit tests.\\nReturn: Return a compact 3-line receipt: (1) files created\u002Fedited, (2) package test result, (3) confirmation of defect fix.\"\n    }\n  }\n]\n```\n\n#### Option B: Spawn Fresh OpenCode Chats of Their Own (`fak issue-orchestrator --spawn-opencode`)\n\nSpawn fresh OpenCode chat processes directly from the CLI to resolve the planned wave:\n\n```bash\n# Standard batch headless spawn for Wave 1 (top 10 candidates):\nfak issue-orchestrator --spawn-opencode --top 10\n\n# Spawn with isolated detached worker worktrees:\nfak issue-orchestrator --spawn-opencode --top 10 --worktree\n\n# Preview spawn commands, titles, and prompts without launching processes:\nfak issue-orchestrator --spawn-opencode --top 10 --dry-run\n\n# Specify a target model or launch interactively:\nfak issue-orchestrator --spawn-opencode --top 10 --model \"anthropic\u002Fclaude-3-7-sonnet\"\nfak issue-orchestrator --spawn-opencode --top 10 --interactive\n```\n\n**What happens during `--spawn-opencode`**:\n- **Fresh Process Execution**: Spawns fresh OpenCode chat processes (headless `opencode run` with `--print-logs --dangerously-skip-permissions` or interactive `opencode run -i`) titled explicitly with `Issue #\u003CN>: \u003Ctitle>`.\n- **Database Isolation**: OpenCode automatically registers a brand-new session ID (`ses_...`) in its storage database for each issue, guaranteeing zero cross-session state or context pollution.\n- **Process Supervision & Logs**: Redirects stdout\u002Fstderr to `.dispatch-runs\u002Fresolve-\u003Cissue>-\u003Cstamp>.log` and writes the child process PID to `.dispatch-runs\u002Fresolve-\u003Cissue>-\u003Cstamp>.pid` for reliable status inspection and reaping.\n- **Detached Worker Worktrees (`--worktree`)**: When `--worktree` is specified, prepares an isolated Git worktree per worker using `fak worktree worker prepare`, hands off process ownership, and scopes changes away from the root working tree.\n- **Dry-Run Preview (`--dry-run`)**: Simulates planning and displays full command lines and session parameters without executing child processes.\n\n---\n\n## Phase 4 — Wave Harvest, Cross-Validation & Independent Witnessing\n\nWhen the parallel workers or spawned OpenCode chats finish:\n\n### 1. Harvest & Audit Results\n\n- **For Option A (In-Harness Subagents)**:\n  - Verify each subagent returned green test receipts strictly within its declared package lane.\n- **For Option B (Spawned OpenCode Chats)**:\n  - **List Active & Completed Sessions**: Check registered OpenCode sessions and status:\n    ```bash\n    opencode session list\n    ```\n  - **Inspect Execution Logs**: Read the background run logs in `.dispatch-runs\u002F`:\n    ```bash\n    # Tail or grep recent run logs\n    Get-Content .dispatch-runs\\resolve-\u003Cissue>-*.log -Tail 50\n    ```\n  - **Inspect Session Transcripts**: Export or inspect the exact turn history and tool calls:\n    ```bash\n    opencode export \u003CsessionID>\n    ```\n\n### 2. Parallel Adversarial Verification & Gap Audit\n\nLaunch parallel `cross-validator` and `issue-auditor` subagents (or run verification checks) to independently evaluate the changes:\n- `cross-validator`: Independently verifies git diff boundaries, executes on-device package tests, and produces DOS-style proof verdicts.\n- `issue-auditor`: Inspects diffs for unhandled edge cases, failure modes, and QA gaps, filing or drafting structured follow-on tickets.\n\n### 3. Independent Verification\n\nCoordinator independently executes package-scoped checks on the trunk or worker worktrees:\n```bash\ngo vet .\u002Finternal\u002F\u003ClaneA> .\u002Finternal\u002F\u003ClaneB>\ngo test -v .\u002Finternal\u002F\u003ClaneA> .\u002Finternal\u002F\u003ClaneB>\n```\n\n### 4. Commit by Explicit Path\n\nCommit each finished leaf independently on the trunk with the issue citation and ship-stamp trailer:\n```bash\nfak sync reconcile --apply\nfak commit --path internal\u002F\u003ClaneA> -m \"fix(\u003ClaneA>): resolve gateway streaming timeout (#1024) (fak \u003ClaneA>)\"\nfak commit --path internal\u002F\u003ClaneB> -m \"feat(\u003ClaneB>): add model KV cache recycling (#1035) (fak \u003ClaneB>)\"\nfak sync push\n```\n*(If changes were developed in detached worktrees via `--worktree`, land them with `fak worktree worker land` or merge the verified commits).*\n\n### 5. Release Lane Leases\n\nRelease the acquired lane leases so peer agents can work on the lanes:\n```bash\ndos lease-lane release --lane \u003ClaneA>\ndos lease-lane release --lane \u003ClaneB>\n```\n\n---\n\n## Phase 5 — Burndown Check & Loop Progression\n\nCompare against the campaign baseline to measure velocity and progress:\n\n```bash\nfak issue-orchestrator --compare campaign-baseline.json\n```\n\nCheck the delta:\n- How many issues closed in this wave?\n- What is the total campaign progress percentage?\n- How many waves remain in the current horizon?\n\n**Decision Gate**:\n- If the campaign target is achieved: emit the final campaign summary report.\n- If more progress is needed: generate Wave N+1 from `fak issue-orchestrator --plan-waves` and continue the loop.\n","# \u002Fissue-orchestrator — campaign-scale multi-wave issue resolution\n\n> **The Campaign Coordinator for General Issue Work.** While atomic issue resolution targets 1–3\n> issues in isolation via [`\u002Fissue-queue`](..\u002Fissue-queue\u002FSKILL.md) (the issue counterpart of [`\u002Fdebt-clean`](..\u002Fdebt-clean\u002FSKILL.md)),\n> `\u002Fissue-orchestrator` coordinates **large volumes of general issue work**\n> across multiple concurrent subagent waves. It partitions the active issue backlog into\n> **pairwise tree-disjoint, concurrent-safe cohorts**, verifies or acquires lane leases via\n> `dos arbitrate`, dispatches parallel workers (via in-harness subagents or fresh OpenCode chat sessions),\n> independently witnesses each worker's effects, commits explicit paths with issue citations `(#N)`, and\n> tracks campaign burndown velocity against a baseline.\n\nThe shape: **baseline campaign (`fak issue-orchestrator --json`) → automated safe wave planning (`fak issue-orchestrator --plan-waves`) → pre-dispatch arbitration (`dos arbitrate`) → parallel dispatch (in-harness `task` or `fak issue-orchestrator --spawn-opencode`) → harvest & independently witness → commit leaf-by-leaf with `(#N)` → compare burndown → loop.**\n\n---\n\n## Dual Dispatch Execution Modes\n\n`\u002Fissue-orchestrator` supports two first-class dispatch execution modes depending on the execution context:\n\n- **Mode A: In-Harness Subagents (`task` tool calls with `subagent_type=\"worker\"`)**\n  - Best when running inside an interactive harness session that supports nested subagent orchestration.\n  - Workers run as child tasks within the coordinator harness, returning receipts directly into the coordinator turn.\n- **Mode B: Spawning Fresh OpenCode Chats of Their Own (`fak issue-orchestrator --spawn-opencode`)**\n  - Best when running headless, batch, or multi-session campaigns where each issue needs an independent, isolated agent process.\n  - Spawns fresh OpenCode chat processes (`opencode run` or interactive `opencode run -i`) with distinct session titles (`Issue #\u003CN>: \u003Ctitle>`), independent database sessions (`ses_...`), dedicated output logs, and optional detached worker worktrees.\n\n---\n\n## Defaults and Operational Boundaries\n\nWhen invoked without explicit arguments or under underspecified requests, apply these reasonable defaults:\n\n- **Bounded Evaluation (`--top 10`)**: ALWAYS bound backlog evaluation to the top 10–15 candidate issues (e.g. `fak issue-orchestrator --top 10`). Never run unbounded sweeps across hundreds of backlog tickets, which wastes tokens evaluating irrelevant triage queues.\n- **Action-First Velocity**: Prioritize immediate wave execution over prolonged baseline analysis. Plan Wave 1, arbitrate, dispatch workers, and land code.\n- **Target Issues**: Default to resolving a focused cohort of **3–5 issues** per session.\n- **Wave Concurrency (`--wave-size`)**: Default to **4–8 concurrent workers** per wave (scaling up to 16 with adaptive concurrency on capable multi-core hosts). Concurrency is safely gated by pairwise tree-disjointness (`dos.toml` declares 894 concurrent leaves).\n- **Max Waves per Run (`--max-waves`)**: Default to **1–2 waves** per run. Avoid unbounded multi-wave loops without checkpoints.\n- **Scratch & State Hygiene**: Baseline snapshots belong in allocated scratch or temporary JSON files (`fak tree-doctor --scratch-path issue-orchestrator\u002Fbaseline.json`), never untracked root dumps. Clean them up on completion.\n- **Worker Isolation**: Each subagent gets exactly one issue and one package lane (`internal\u002F\u003Clane>`), touches only declared files, runs only package-scoped tests (`go test -v .\u002Finternal\u002F\u003Clane>`, `go vet .\u002Finternal\u002F\u003Clane>`), and returns a 3-line receipt.\n- **Witness & Commit Cadence**: Coordinator independently verifies (`go vet`, `go test`) and commits each successful worker leaf individually with DCO sign-off, Conventional Commits, issue number citation `(#N)`, and lane ship-stamp `(fak \u003Clane>)` before proceeding to the next wave.\n\n---\n\n## Architectural Invariants (The Orchestration Laws)\n\n1. **Automated Tree-Disjoint Concurrency**:\n   Never allow concurrent subagents to touch overlapping directories or packages. Two workers\n   editing the same Go package break compilation for each other. Use `fak issue-orchestrator --plan-waves --wave-size N`\n   to partition candidate issues into verified pairwise tree-disjoint waves with zero cross-package\n   import contention.\n2. **Live Lease Arbitration & Exclusion**:\n   Before dispatching any subagent, the coordinator must verify or acquire the lane lease via\n   `dos arbitrate --workspace . --lane \u003Clane> --kind keyword --mode exclusive` (or the `dos_arbitrate` MCP tool).\n   `fak issue-orchestrator --plan-waves` automatically discovers and excludes any active leases held in\n   `.dos\u002Flane-journal.jsonl`. If an issue's lane is held by another agent, the orchestrator skips it and advances\n   the next candidate from the wave plan without colliding.\n3. **Multi-Orchestrator Concurrency**:\n   Multiple orchestrator loops or independent agents can operate concurrently on the repository:\n   each agent respects the shared lane taxonomy and lease journal. When two agents seek work simultaneously,\n   `dos arbitrate` grants mutually disjoint lanes to each, preventing collision by construction.\n4. **Serial Core Gates**:\n   High-blast-radius core leaves (`internal\u002Fabi`, `internal\u002Fkernel`, `internal\u002Fadjudicator`,\n   `internal\u002Fpolicy`, `internal\u002Fgateway`, `internal\u002Fvdso`, `internal\u002Fshipgate`, `internal\u002Farchitest`) touch root types imported across the repository.\n   They must NEVER run concurrently with peer workers—the planner automatically isolates them into\n   dedicated, single-worker serial waves (`serial_singleton`).\n5. **Strict Subagent Fences & Scoped Verification**:\n   Subagents must edit ONLY within their assigned package directory. They must NEVER touch root\n   files, `go.mod`, `go.sum`, `dos.toml`, or sibling packages. Subagents must run ONLY package-scoped\n   tests (`go test -v .\u002Finternal\u002F\u003Clane>`, `go vet .\u002Finternal\u002F\u003Clane>`), NEVER broad `go test .\u002F...` which\n   could fail on unrelated in-flight peer edits.\n6. **Subdivide Epics, Triage Unclear Scope**:\n   Oversized issues (>15 expected steps or touching 3+ subsystems) are routed to the `Subdivide` queue\n   to be broken into atomic leaves before dispatch. Issues with unclear scope or missing acceptance\n   criteria are routed to `Triage`. The orchestrator dispatches only concrete leaf units.\n7. **Coordinator Stays Clean**:\n   The coordinator dispatches, adjudicates conflicts, witnesses proofs, and tracks the campaign burndown.\n   Substantive implementation and test runs happen inside isolated subagent tasks (`subagent_type=\"general\"`\n   using Gemini 3.8 Flash high `variant: high`).\n8. **Witness Before Close**:\n   An issue is resolved only when its reproduction or contract test passes green on disk. The commit message\n   must cite the issue number `(#N)` and carry the `(fak \u003Clane>)` trailer.\n\n---\n\n## Phase 1 — Quick Bounded Planning & Target Selection\n\nPlan the immediate actionable wave bounded to top candidate issues:\n\n```bash\n# Fast path: plan immediate actionable wave bounded to top candidate issues:\nfak issue-orchestrator --top 10 --max-waves 1\n\n# If tracking a formal burndown comparison, capture baseline bounded to cohort:\nfak issue-orchestrator --top 15 --max-waves 2 --json > campaign-baseline.json\n```\n\nFrom the output, determine:\n- **Starting Scope**: e.g., `10 total issue(s) evaluated · 2 dispatchable · 0 subdivide · 8 triage`.\n- **Campaign Target**:\n  - *Default Focused Target*: Resolve **2–4 issues** in Wave 1 immediately.\n  - *Alternative Point Target*: Retire a fixed step budget (e.g. `--target-points 15`).\n- **Wave Capacity**: Standard reasonable wave size is **4–8 parallel subagents** (`--wave-size 8`, up to 16 on high-capacity hosts).\n- **Campaign Horizon**: Standard execution batch is **1–2 waves** (`--max-waves 1` or `2`).\n\n---\n\n## Phase 2 — Automated Concurrent-Safe Wave Planning\n\nGenerate provably collision-free, concurrent-safe waves using `fak issue-orchestrator`:\n\n```bash\n# Plan campaign waves bounded to top candidate issues (wave size 4, max 2 waves):\nfak issue-orchestrator --top 15 --wave-size 4 --max-waves 2\n\n# Or plan from a specific issue source (e.g. local snapshot or gh export):\nfak issue-orchestrator --from-issues issues.json --wave-size 4 --max-waves 2\n\n# Include ready-to-run OpenCode spawn commands in JSON\u002FMarkdown wave plan:\nfak issue-orchestrator --top 15 --wave-size 4 --max-waves 2 --opencode-commands\n\n# Or emit machine-readable wave plan JSON (includes opencode_command per issue and opencode_chats per wave):\nfak issue-orchestrator --top 15 --wave-size 4 --max-waves 2 --opencode-commands --json > wave-plan.json\n```\n\nThe planner automatically:\n1. **Discovers and Excludes Held Leases**: Scans `.dos\u002Flane-journal.jsonl` and excludes all active held leases in the workspace.\n2. **Enforces Pairwise Tree-Disjointness**: Proves that no two issues in a wave share directory paths or parent\u002Fchild containment.\n3. **Decouples Package Import Contention**: Checks the Go internal import graph to ensure workers in the same wave do not contend on shared internal package APIs.\n4. **Isolates Serial Singletons**: Identifies critical core leaves and schedules them into dedicated `serial_singleton` single-worker waves.\n5. **Extracts Subdivide & Triage Queues**: Pulls oversized epics into `Subdivide` with a child-issue budget and unready tickets into `Triage`.\n6. **Renders OpenCode Commands (`--opencode-commands`)**: Emits structured, copy-pasteable or machine-readable `opencode run` CLI invocations for each planned wave issue with appropriate titles, boundary path instructions, and verification commands.\n\n---\n\n## Phase 3 — Pre-Dispatch Arbitration & Parallel Worker Dispatch\n\nFor each wave in the plan:\n\n### 1. Pre-Dispatch Lane Arbitration\n\nBefore launching workers, verify each lane in the wave is free to acquire:\n\n```bash\ndos arbitrate --workspace . --lane \u003Clane> --kind keyword --mode exclusive\n```\n*(Or invoke the `dos_arbitrate` tool).*\n\n- **Admitted (`outcome: acquire`)**: Proceed to dispatch worker on `\u003Clane>`.\n- **Refused (`outcome: refuse`)**: Another peer agent took the lane. Log refusal, skip this lane, and advance the next candidate issue from the wave plan.\n\n### 2. Dispatch Workers (Option A or Option B)\n\nChoose between in-harness subagents (Option A) or spawning fresh OpenCode chat sessions (Option B):\n\n#### Option A: In-Harness Subagents (`task` tool)\n\nLaunch all admitted workers in parallel in a single turn using multiple `task` tool calls with `subagent_type=\"worker\"` under strict fences (using Gemini 3.8 Flash high `variant: high` for hard work):\n\n```json\n[\n  {\n    \"tool\": \"task\",\n    \"parameters\": {\n      \"subagent_type\": \"worker\",\n      \"description\": \"Resolve #1024 gateway streaming timeout\",\n      \"prompt\": \"You are an isolated worker for issue #1024: Fix gateway streaming timeout.\\nLane: gateway\\nBoundaries: Edit ONLY files under internal\u002Fgateway\u002F. NEVER touch go.mod, go.sum, dos.toml, or root files.\\nVerification: Run ONLY package-scoped tests: `go test -v .\u002Finternal\u002Fgateway` and `go vet .\u002Finternal\u002Fgateway`. NEVER run `go test .\u002F...`.\\nDeliverable: Fix the timeout issue and add a reproduction unit test.\\nReturn: Return a compact 3-line receipt: (1) files created\u002Fedited, (2) package test result, (3) confirmation of defect fix.\"\n    }\n  },\n  {\n    \"tool\": \"task\",\n    \"parameters\": {\n      \"subagent_type\": \"worker\",\n      \"description\": \"Resolve #1035 model kv cache recycling\",\n      \"prompt\": \"You are an isolated worker for issue #1035: Add model KV cache recycling.\\nLane: model\\nBoundaries: Edit ONLY files under internal\u002Fmodel\u002F. NEVER touch go.mod, go.sum, dos.toml, or root files.\\nVerification: Run ONLY package-scoped tests: `go test -v .\u002Finternal\u002Fmodel` and `go vet .\u002Finternal\u002Fmodel`. NEVER run `go test .\u002F...`.\\nDeliverable: Implement the KV cache recycling path with reproduction unit tests.\\nReturn: Return a compact 3-line receipt: (1) files created\u002Fedited, (2) package test result, (3) confirmation of defect fix.\"\n    }\n  }\n]\n```\n\n#### Option B: Spawn Fresh OpenCode Chats of Their Own (`fak issue-orchestrator --spawn-opencode`)\n\nSpawn fresh OpenCode chat processes directly from the CLI to resolve the planned wave:\n\n```bash\n# Standard batch headless spawn for Wave 1 (top 10 candidates):\nfak issue-orchestrator --spawn-opencode --top 10\n\n# Spawn with isolated detached worker worktrees:\nfak issue-orchestrator --spawn-opencode --top 10 --worktree\n\n# Preview spawn commands, titles, and prompts without launching processes:\nfak issue-orchestrator --spawn-opencode --top 10 --dry-run\n\n# Specify a target model or launch interactively:\nfak issue-orchestrator --spawn-opencode --top 10 --model \"anthropic\u002Fclaude-3-7-sonnet\"\nfak issue-orchestrator --spawn-opencode --top 10 --interactive\n```\n\n**What happens during `--spawn-opencode`**:\n- **Fresh Process Execution**: Spawns fresh OpenCode chat processes (headless `opencode run` with `--print-logs --dangerously-skip-permissions` or interactive `opencode run -i`) titled explicitly with `Issue #\u003CN>: \u003Ctitle>`.\n- **Database Isolation**: OpenCode automatically registers a brand-new session ID (`ses_...`) in its storage database for each issue, guaranteeing zero cross-session state or context pollution.\n- **Process Supervision & Logs**: Redirects stdout\u002Fstderr to `.dispatch-runs\u002Fresolve-\u003Cissue>-\u003Cstamp>.log` and writes the child process PID to `.dispatch-runs\u002Fresolve-\u003Cissue>-\u003Cstamp>.pid` for reliable status inspection and reaping.\n- **Detached Worker Worktrees (`--worktree`)**: When `--worktree` is specified, prepares an isolated Git worktree per worker using `fak worktree worker prepare`, hands off process ownership, and scopes changes away from the root working tree.\n- **Dry-Run Preview (`--dry-run`)**: Simulates planning and displays full command lines and session parameters without executing child processes.\n\n---\n\n## Phase 4 — Wave Harvest, Cross-Validation & Independent Witnessing\n\nWhen the parallel workers or spawned OpenCode chats finish:\n\n### 1. Harvest & Audit Results\n\n- **For Option A (In-Harness Subagents)**:\n  - Verify each subagent returned green test receipts strictly within its declared package lane.\n- **For Option B (Spawned OpenCode Chats)**:\n  - **List Active & Completed Sessions**: Check registered OpenCode sessions and status:\n    ```bash\n    opencode session list\n    ```\n  - **Inspect Execution Logs**: Read the background run logs in `.dispatch-runs\u002F`:\n    ```bash\n    # Tail or grep recent run logs\n    Get-Content .dispatch-runs\\resolve-\u003Cissue>-*.log -Tail 50\n    ```\n  - **Inspect Session Transcripts**: Export or inspect the exact turn history and tool calls:\n    ```bash\n    opencode export \u003CsessionID>\n    ```\n\n### 2. Parallel Adversarial Verification & Gap Audit\n\nLaunch parallel `cross-validator` and `issue-auditor` subagents (or run verification checks) to independently evaluate the changes:\n- `cross-validator`: Independently verifies git diff boundaries, executes on-device package tests, and produces DOS-style proof verdicts.\n- `issue-auditor`: Inspects diffs for unhandled edge cases, failure modes, and QA gaps, filing or drafting structured follow-on tickets.\n\n### 3. Independent Verification\n\nCoordinator independently executes package-scoped checks on the trunk or worker worktrees:\n```bash\ngo vet .\u002Finternal\u002F\u003ClaneA> .\u002Finternal\u002F\u003ClaneB>\ngo test -v .\u002Finternal\u002F\u003ClaneA> .\u002Finternal\u002F\u003ClaneB>\n```\n\n### 4. Commit by Explicit Path\n\nCommit each finished leaf independently on the trunk with the issue citation and ship-stamp trailer:\n```bash\nfak sync reconcile --apply\nfak commit --path internal\u002F\u003ClaneA> -m \"fix(\u003ClaneA>): resolve gateway streaming timeout (#1024) (fak \u003ClaneA>)\"\nfak commit --path internal\u002F\u003ClaneB> -m \"feat(\u003ClaneB>): add model KV cache recycling (#1035) (fak \u003ClaneB>)\"\nfak sync push\n```\n*(If changes were developed in detached worktrees via `--worktree`, land them with `fak worktree worker land` or merge the verified commits).*\n\n### 5. Release Lane Leases\n\nRelease the acquired lane leases so peer agents can work on the lanes:\n```bash\ndos lease-lane release --lane \u003ClaneA>\ndos lease-lane release --lane \u003ClaneB>\n```\n\n---\n\n## Phase 5 — Burndown Check & Loop Progression\n\nCompare against the campaign baseline to measure velocity and progress:\n\n```bash\nfak issue-orchestrator --compare campaign-baseline.json\n```\n\nCheck the delta:\n- How many issues closed in this wave?\n- What is the total campaign progress percentage?\n- How many waves remain in the current horizon?\n\n**Decision Gate**:\n- If the campaign target is achieved: emit the final campaign summary report.\n- If more progress is needed: generate Wave N+1 from `fak issue-orchestrator --plan-waves` and continue the loop.\n",{"name":5,"description":7,"allowed-tools":24,"argument-hint":25,"user-invocable":26,"disable-model-invocation":20},"Read, Bash, Write, Edit, Grep, Glob, Task","[--top 10] [--target-issues 5] [--wave-size 4] [--max-waves 2] [--spawn-opencode] [--dry-run] [--worktree] [--model \u003Cmodel>] [--interactive] [--from-issues issues.json]",true,"main","f565b7b7db63e79649f3a02c08108132a86c5d05",".claude\u002Fskills\u002Fissue-orchestrator",16,"https:\u002F\u002Fgithub.com\u002Fanthony-chaudhary\u002Ffak","https:\u002F\u002Fanthony-chaudhary.github.io\u002Ffak\u002Fshowcase.html","https:\u002F\u002Fgithub.com\u002Fanthony-chaudhary","https:\u002F\u002Flinkedin.com\u002Fin\u002Fanthonychaudhary","2026-11-15 03:06:00",{"source":8,"skillName":5,"commands":37,"prompt":47,"zipAvailable":26},[38,41,44],{"tool":39,"command":40},"npx","npx skills add anthony-chaudhary\u002Ffak --skill issue-orchestrator",{"tool":42,"command":43},"bunx","bunx skills add anthony-chaudhary\u002Ffak --skill issue-orchestrator",{"tool":45,"command":46},"pnpm","pnpm dlx skills add anthony-chaudhary\u002Ffak --skill issue-orchestrator","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fanthony-chaudhary\u002Ffak\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fissue-orchestrator\u002FSKILL.md",[],[50,57,66,73,80,85],{"skillNo":51,"name":52,"nameZh":6,"description":53,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":54,"categories":55,"keywords":56,"publishedAt":19},"01M78V4059KRP2T88YR6Z05MJQ","serve-receipt","On-demand research protocol + deterministic receipt for serving a Hugging Face model on a concrete GPU target — fan out research lanes (model facts\u002Ffiles, engine support matrix, serving recipes, KV\u002Fstate memory math), compute the tiered feasibility verdict with `fak serve-receipt` (never narrated math), and emit a witnessed launch receipt. Use when asked for an \"initial config\", \"serving receipt\", or \"how do I serve \u003Cmodel> on \u003CGPUs>\".","https:\u002F\u002Fgithub.com\u002Fanthony-chaudhary\u002Ffak\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fserve-receipt\u002FSKILL.md",[],[],{"skillNo":58,"name":59,"nameZh":6,"description":60,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":61,"licenseFileUrl":62,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":19},"01M77HRGKQV2CJ2K6ZFN4YQ32K","caveman","Ultra-compressed communication mode. Cuts output tokens 65% (measured) by speaking like caveman while keeping full technical accuracy. Supports intensity levels: lite, full (default), ultra, wenyan-lite, wenyan-full, wenyan-ultra. Use when user says \"caveman mode\", \"talk like caveman\", \"use caveman\", \"less tokens\", \"be brief\", or invokes \u002Fcaveman. Also auto-triggers when token efficiency is requested.","MIT","https:\u002F\u002Fgithub.com\u002Fanthony-chaudhary\u002Ffak\u002Fblob\u002Fmain\u002Finternal\u002Fsyspromptmmu\u002Fthird_party\u002Fcaveman\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fanthony-chaudhary\u002Ffak\u002Fblob\u002Fmain\u002Finternal\u002Fsyspromptmmu\u002Fthird_party\u002Fcaveman\u002FSKILL.md",[],[],{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":19},"01M77HRAY3Y3BE7APN5PVJF7NV","quality-report","Score the repo quality and emit a report card.","https:\u002F\u002Fgithub.com\u002Fanthony-chaudhary\u002Ffak\u002Fblob\u002Fmain\u002Finternal\u002Fctxplans\u002Ftestdata\u002Frepo\u002F.claude\u002Fskills\u002Fquality-report\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":19},"01M77HR9807KHAX13DG9PW2K2Q","ctx-overlay","Compact the context window and prune the memory store when a session grows too long.","https:\u002F\u002Fgithub.com\u002Fanthony-chaudhary\u002Ffak\u002Fblob\u002Fmain\u002Finternal\u002Fctxplans\u002Ftestdata\u002Frepo\u002F.claude\u002Fskills\u002Fctx-overlay\u002FSKILL.md",[],[],{"skillNo":81,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":19},"01M77HR7XQ9X8F2CY9Z4F2ZEZ3","https:\u002F\u002Fgithub.com\u002Fanthony-chaudhary\u002Ffak\u002Fblob\u002Fmain\u002Finternal\u002Fctxplanlint\u002Ftestdata\u002Frepo\u002F.claude\u002Fskills\u002Fquality-report\u002FSKILL.md",[],[],{"skillNo":86,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":19},"01M77HR5BVKCTR1WNJGRBSDNX7","https:\u002F\u002Fgithub.com\u002Fanthony-chaudhary\u002Ffak\u002Fblob\u002Fmain\u002Finternal\u002Fctxplanlint\u002Ftestdata\u002Frepo\u002F.claude\u002Fskills\u002Fctx-overlay\u002FSKILL.md",[],[]]