@opengsd/gsd-path 1.0.0

package/skills/gsd-path-plan/scripts/workflow_run.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Run canonical workflow helpers with fixed arguments and fail-stop receipts."""
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+try:
+    from scripts import _common
+except ImportError:  # bundled copy inside a skill's scripts directory
+    import _common
+
+
+class StepFailed(RuntimeError):
+    pass
+
+
+def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str = None,
+                 task_id: str = None, round_size: int = None) -> dict:
+    steps = []
+    scripts = Path(__file__).resolve().parent
+
+    def step(script, *arguments):
+        command = [sys.executable, "-B", str(scripts / script), *arguments]
+        completed = subprocess.run(command, cwd=repo, capture_output=True, text=True)
+        receipt = {"script": script, "command": command, "exit_code": completed.returncode,
+                   "stdout": completed.stdout, "stderr": completed.stderr}
+        steps.append(receipt)
+        if completed.stderr:
+            sys.stderr.write(completed.stderr)
+        if completed.returncode:
+            raise StepFailed(script)
+        try:
+            receipt["result"] = json.loads(completed.stdout)
+        except json.JSONDecodeError as error:
+            raise StepFailed(f"{script} did not return JSON") from error
+        return receipt["result"]
+
+    common = ["--repo", str(repo), "--project-dir", project_dir]
+    try:
+        if action == "route":
+            step("pipeline_state.py", "route", *common)
+        elif action == "lint-round":
+            head = subprocess.run(["git", "rev-parse", "--verify", "HEAD"],
+                                  cwd=repo, capture_output=True, text=True, check=True).stdout.strip()
+            step("check_task_briefs.py", "--repo", str(repo), "--base", head,
+                 "--tasks-dir", f"{project_dir}/tasks")
+            step("check_handoffs.py", "plan", *common)
+        elif action == "prepare-task":
+            task = step("isolation.py", "isolate-task", "--repo", str(repo),
+                        "--base", expected_head, "--task-id", task_id,
+                        "--round-size", str(round_size))
+            if task["mode"] == "serial":
+                step("isolation.py", "isolate-verify", "--repo", str(repo),
+                     "--base", expected_head, "--name", f"task-{task_id.lower()}-verify")
+        elif action == "build-evidence":
+            proof = step("build_state.py", "verify-landed", *common, "--head", expected_head)
+            # The landing proof has one canonical home; lean final-review reuse allows only this path.
+            evidence = repo / project_dir / "build" / "evidence.json"
+            _common.atomic_write(evidence, json.dumps(proof, indent=2, sort_keys=True) + "\n")
+            steps.append({"script": "workflow_run.py", "evidence": str(evidence)})
+        elif action == "prepare-final":
+            if project_dir != ".project":
+                raise StepFailed("final review requires the active milestone")
+            pending = step("discussion_records.py", "pending", "--repo", str(repo))
+            if pending["pending"]:
+                raise StepFailed("pending discussion requires its owner disposition")
+            step("build_state.py", "verify-landed", *common, "--head", expected_head)
+            step("lean_verification.py", "--repo", str(repo), "--expected-head", expected_head)
+        else:
+            pending = step("discussion_records.py", "pending", "--repo", str(repo))
+            if pending["pending"]:
+                raise StepFailed("pending discussion requires its owner disposition")
+            step("check_handoffs.py", "plan", *common)
+            head = subprocess.run(["git", "rev-parse", "--verify", "HEAD"],
+                                  cwd=repo, capture_output=True, text=True, check=True).stdout.strip()
+            step("check_task_briefs.py", "--repo", str(repo), "--base", head,
+                 "--tasks-dir", f"{project_dir}/tasks")
+            panel = ["validate-plan", "--plan", str(repo / project_dir / "plan/PLAN.md"),
+                     "--intent", str(repo / project_dir / "intent/INTENT.md")]
+            charter = repo / ".project/CHARTER.md"
+            if charter.exists():
+                panel += ["--charter", str(charter)]
+            step("review_panel.py", *panel)
+            if action == "approve-plan":
+                step("pipeline_state.py", "approve", *common, "--kind", "plan",
+                     "--expected-head", expected_head)
+    except (StepFailed, OSError, subprocess.CalledProcessError) as error:
+        return {"status": "blocked", "reason": str(error), "steps": steps,
+                "next": "$gsd-path-forensics"}
+    return {"status": "complete", "steps": steps}
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("action", choices=("route", "gate-plan", "approve-plan", "build-evidence", "lint-round", "prepare-task", "prepare-final"))
+    parser.add_argument("--repo", type=Path, required=True)
+    parser.add_argument("--project-dir", choices=(".project", ".project/next"), default=".project")
+    parser.add_argument("--expected-head")
+    parser.add_argument("--task-id")
+    parser.add_argument("--round-size", type=int)
+    arguments = parser.parse_args(argv)
+    if arguments.action in {"approve-plan", "build-evidence", "prepare-task", "prepare-final"} and not arguments.expected_head:
+        parser.error(f"{arguments.action} requires --expected-head")
+    if arguments.action == "prepare-task" and (not arguments.task_id or arguments.round_size is None):
+        parser.error("prepare-task requires --task-id and --round-size")
+    result = run_workflow(arguments.repo.resolve(), arguments.action,
+                          arguments.project_dir, arguments.expected_head,
+                          arguments.task_id, arguments.round_size)
+    print(json.dumps(result, sort_keys=True))
+    return 0 if result["status"] == "complete" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/gsd-path-plan/templates/patch-findings.md

@@ -0,0 +1,16 @@
+# Patch Findings
+
+<!-- Written by final review when it blocks and consumed by patch planning. -->
+
+Reviewed HEAD: <full SHA>
+State: ship/blocked
+
+## Findings
+
+<!-- Copy only evidenced, selected findings. Keep IDs contiguous and ordered. -->
+### P001 — <short finding title>
+
+- **Source**: `.project/review/FINAL.md`
+- **Locator**: `<SC number or gap risk row>`
+- **Evidence**: <observed result copied from the source review>
+- **Fix direction**: <concrete direction for the patch task>

package/skills/gsd-path-plan/templates/plan-panel.md

@@ -0,0 +1,25 @@
+# Plan panel — <family>
+
+<!-- Written by one review-panel child. The orchestrator validates this file
+     with scripts/review_panel.py merge and never treats it as a plan gate.
+     Kind criterion requires a named PLAN/task criterion; preference is
+     taste or an alternate design and must not flip approval. -->
+
+- Family: <claude | gpt | grok | composer | gemini | deepseek | kimi | qwen>
+- Model: <exact advertised slug>
+
+## Findings
+
+<!-- One ### F# block per finding, or a single `- none` line. -->
+
+### F1
+- Severity: high
+- Kind: criterion
+- Criterion: Wave 1 / T001 / acceptance 1
+- Evidence: .project/tasks/T001-slug.md:12
+- Found: <what is missing or wrong>
+- Fix direction: <concrete plan/task edit>
+
+## Summary
+
+<one paragraph; do not edit PLAN.md or tasks>

package/skills/gsd-path-plan/templates/plan.md

@@ -0,0 +1,89 @@
+# Plan — <project name>
+
+<!-- Written by the planner role. Executed wave-by-wave by $gsd-path-build. -->
+
+Project verify: `<command that installs dependencies, builds + tests the whole project>`
+<!-- Run once at ship, in a fresh sidecar worktree checked out at the
+     reviewed commit: no node_modules, virtualenv, build output, or untracked
+     env files exist there. The command must provision what it needs first,
+     e.g. `pnpm install --frozen-lockfile && pnpm test`. A task Verify must
+     not copy this command unless an owned INTENT success criterion names it.
+     Otherwise the task Verify names a path from that task's files. -->
+
+## Config
+
+- max_review_cycles: 3   <!-- review→fix→re-review loops per wave before escalating -->
+- wave_budget: none      <!-- none | optional per-wave resource cap: wall-clock,
+                             tokens, or cost (e.g. 2h, 500k tokens). Reaching the
+                             cap blocks the wave like an exhausted cycle cap and
+                             escalates to the user. none is default. -->
+- review_panel: off      <!-- off | detected | claude,gpt,grok — optional
+                             cross-model panel. off is default. detected uses
+                             advertised host families except the parent, cap 3.
+                             Named families are an assertion. Quick lane stays
+                             off. The planner copies INTENT.md; it does not
+                             invent a non-off value. -->
+- finding_skeptics: off  <!-- off | on — deep waves only. on spawns one
+                             read-only skeptic per blocking finding before
+                             fix tasks are batched; a refuted finding spawns
+                             no fix task unless the user explicitly overrides
+                             all cycle refutations. off is default. The planner
+                             copies INTENT.md; it does not invent on. -->
+
+## Wave 1 — risk burn-down
+
+Goal: <what this wave proves; if it fails, what changes>
+Review depth: full   <!-- full | deep | verify-only. Wave 1 and auth/payments/
+                          data migration/concurrency waves must be full or
+                          deep. Assign deep sparingly: irreversible or
+                          security-critical merges. -->
+
+<!-- No task table. Task id, title, deps, and files live only in each
+     `tasks/T###-slug.md` frontmatter; `wave: N` there assigns it here. -->
+
+## Wave 2 — walking skeleton
+
+Goal: <the end-to-end slice that runs>
+Review depth: <full | deep | verify-only>
+
+<!-- More waves: features by dependency, then polish. Rules:
+     - deps only in earlier waves, or same wave with no file overlap
+     - no two same-wave tasks share files
+     - nothing from INTENT.md scope-out appears anywhere -->
+
+## Surface contract
+
+<!-- Required when INTENT.md `Surfaces:` is not `none`; omit the section
+     entirely when it is. One block per declared surface, named exactly as
+     INTENT.md names it, owned by the task that delivers it. That task must
+     name in Criteria the success criteria this surface is proven by — the
+     owning task must own every listed criterion in its Intent coverage. A
+     criterion may appear in only one surface block. This is what the final
+     reviewer walks before the milestone is called done, and FINAL.md records
+     the surface it was walked on. Replace every whole-value angle-bracket
+     placeholder; angle brackets may appear inside concrete routes, commands,
+     states, and walkthrough steps. -->
+
+### <surface name as INTENT.md writes it> — T001
+
+Criteria: SC1
+Entry: <the route, screen, or command a person opens>
+States: <what empty, loading, error, and success each show>
+Walkthrough:
+1. <step a reviewer performs to see this surface working>
+
+## Intent coverage
+
+<!-- Every INTENT.md success criterion, as SCn, maps to at least one task
+     acceptance item. The named task's Verify command is what must fail if
+     that criterion is skipped. `scripts/check_handoffs.py plan` gates this
+     table against INTENT.md and each task's Intent coverage section. -->
+
+| Criterion | Task | Acceptance |
+|-----------|------|------------|
+| SC1 | T001 | AC1 |
+
+## Dependency notes
+
+<Per non-obvious edge: the exact data or landed effect that makes X precede Y,
+and how a reviewer sees it. Narrative order is not a dependency.>

package/skills/gsd-path-plan/templates/task.md

@@ -0,0 +1,74 @@
+---
+id: T001
+title: <imperative, specific>
+wave: 1
+deps: []            # task ids whose output or landed effect this task needs
+status: pending     # orchestrator-owned: pending | in-progress | done | failed | blocked
+agent: null         # orchestrator-owned: set at dispatch
+base: null          # orchestrator-owned: clean layer SHA for isolated Verify
+worktree: null      # orchestrator-owned: isolated task worktree while active
+task_branch: null   # orchestrator-owned: gsd-path-task/<id> while parallel; null when serial
+files:              # every file this task may touch — dispatch checks overlap
+  - <path>
+---
+
+# T001 — <title>
+
+## Context
+
+<!-- 3–5 sentences. Everything the coder needs from SYNTHESIS, inlined.
+     The coder reads this file, INTENT.md, and the codebase. -->
+
+## Approach
+
+<!-- Constraints, applicable pitfalls from research, and pointers to real
+     paths, symbols, and schemas. Not an edit script — the coder owns the
+     how within these constraints and the acceptance criteria. -->
+- <constraint or pointer>
+
+## Interface contract
+
+<!-- Planner-owned. The exact shared symbols, signatures, types, paths,
+     schemas, or formats this task exchanges with other tasks. Required when
+     another task consumes this task's output or this task consumes a
+     sibling's; write the identical contract in every involved task. Otherwise
+     write `None`. Only shapes this task's `files` define or consume — never
+     the whole plan's contracts. Binding like the acceptance criteria: needing to deviate
+     is a plan defect — block, never negotiate or improvise. -->
+- None
+
+## Intent coverage
+
+<!-- SCn ids this task owns, matching PLAN.md Intent coverage. Write
+     `- None` when this task owns no INTENT success criterion. -->
+- SC1
+
+## Acceptance criteria
+
+<!-- Observable. The reviewer checks the diff against exactly these. -->
+1. <behavior/command/output that must be true>
+
+## Verify
+
+```bash
+<one command that fails if this task wasn't done; names a path from files>
+```
+<!-- Runs in a fresh sidecar worktree at the landed commit with nothing
+     installed. Provision dependencies inside the command when the project
+     needs them, e.g. `pnpm install --frozen-lockfile && pnpm vitest run
+     src/x.test.ts`. -->
+
+Heavy: no   <!-- yes when this command must not run beside another heavy Verify -->
+
+<!-- Fix tasks only: add ## Review findings before Log, with one
+     ### <canonical locator> block per group in the helper's batch.
+     Each block contains Criterion: <verbatim criterion> and all supplied
+     observations verbatim. Set deps to include the source tasks and files
+     to the batch's files. Ordinary tasks omit this section. -->
+
+## Log
+
+<!-- Append-only: coder summary, blocks (`NEEDS-ORCHESTRATOR: <question> —
+     readings: <candidates>` for contract ambiguity), orchestrator answers,
+     review verdicts, fixes. -->
+- <date> — created by planner

package/skills/gsd-path-research/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: gsd-path-research
+description: Dispatch parallel researchers and collect cited GSD Path evidence about domain, stack, pitfalls, and comparable products. Use only when the user explicitly invokes $gsd-path-research or an active $gsd-path router explicitly routes to this phase.
+---
+
+# GSD Path Research Phase
+
+Dispatch independent researchers and gate their evidence. Keep synthesis out
+of this phase. The durable output is a research dispatch manifest plus one
+evidence file per dispatched dimension.
+
+Routing instructions below are caller handoffs under the AGENTS.md handoff
+rule; never invoke an explicit-only sibling skill yourself.
+
+Before dispatch and again before completion, apply the AGENTS.md
+pending-answer rule with the bundled `scripts/discussion_records.py`; a
+follow-up owned by research is resolved through its evidence handoff, or
+the phase blocks.
+
+## Preconditions
+
+Require `pipeline_state.py validate --repo <absolute root> [--project-dir
+.project/next]` to pass; otherwise return to `$gsd-path` for ownership
+checking. Legal entry is `define/done` or `research/active|blocked`. On
+`define/done`, enter with `pipeline_state.py transition`, expected phase/status
+`define/done`, exact branch and archive values, event `research started`, and
+set phase/status `research/active` (plus the same `--project-dir` in
+lookahead); never edit STATE directly. `research/done`
+`research/done` or any later phase blocks rather than replacing settled
+evidence beneath downstream artifacts. When an active router supplies the
+lookahead track root `.project/next/`, evaluate these preconditions against
+the track instead; see Lookahead mode. Require
+`.project/intent/INTENT.md` — or, in program flow, `.project/CHARTER.md` when
+the router dispatched program-scope research before any milestone INTENT
+exists. If neither exists, stop and route to
+`$gsd-path-define`. Confirm live search or web-reading capability before
+dispatch; if unavailable, block rather than allowing memory-based citations.
+
+Program scope: when working from CHARTER.md, dimensions decompose the full
+charter scope, not one milestone. Add program dimensions such as
+`domain-decomposition` (capability areas and their boundaries) and
+`capability-map` (what exists vs. what must be built) as custom dimensions
+alongside the standard set, so the roadmap phase inherits a complete scope
+map. The manifest's `Intent:` line names `.project/CHARTER.md` in this flow.
+
+## Lookahead mode
+
+Entered only when an active router supplies the lookahead track root
+`.project/next/` while the active STATE.md is `build/active` in program
+flow. Evaluate every state and artifact precondition against the track:
+`.project/next/STATE.md` is the state file, INTENT.md is
+`.project/next/intent/INTENT.md`, and the manifest and evidence files live
+under `.project/next/research/`. Program-level inputs (CHARTER.md,
+ROADMAP.md, top-level SYNTHESIS.md) are read from their active `.project/`
+paths. Brownfield input is the track's
+`.project/next/research/evidence-codebase.md` after lookahead inspect;
+do not substitute the building milestone's map. Archived evidence from
+earlier milestones uses the same archived-manifest rule as the roadmap
+phase. Validate the handoff with
+`python3 <absolute check_handoffs.py> research --repo <absolute repo root>
+--project-dir .project/next`. Dispatch, gates, and completion rules are
+unchanged; never write an active-path artifact.
+
+## Dispatch contract
+
+Read the local [researcher role](references/researcher.md), then follow the
+local [runtime dispatch contract](references/dispatch.md). Resolve the local
+[evidence template](templates/evidence.md), research-handoff template
+(`templates/research-handoff.md`), and `scripts/check_handoffs.py` to absolute
+paths. Include the role, `AGENTS.md`, `WORKFLOW.md`, INTENT.md, manifest,
+dimension, assigned questions, deterministic logical task name
+`research_<dimension>`, and exact output path in every brief. When
+`evidence-codebase.md` exists, include its absolute path in every brief as
+settled brownfield input.
+
+## Process
+
+1. Read INTENT.md — or CHARTER.md in program flow. Extract constraints,
+   vetoes, risks, and `RESEARCH`
+   questions. Create `.project/research/RESEARCH.md` from the local handoff
+   template before dispatch. Record every standard dimension exactly once as
+   `dispatched` or `skipped` with a reason, and assign every research question
+   to at least one dispatched dimension. No question may remain unassigned.
+2. Decide which standard dimensions have work: dispatch a dimension only when
+   it has at least one assigned `RESEARCH` question from INTENT.md or
+   CHARTER.md. Unsettled choices and risks need that source question before
+   dispatch. Skip a dimension
+   with nothing to answer — never spawn a researcher to fill a file — and
+   record every skipped dimension with its reason in `RESEARCH.md`. The
+   standard dimensions:
+
+   | Dimension | Output file | Focus |
+   | --- | --- | --- |
+   | domain | `evidence-domain.md` | prior art, domain rules, terminology, practitioner expectations |
+   | stack | `evidence-stack.md` | two or three viable stacks against the constraints |
+   | pitfalls | `evidence-pitfalls.md` | security, scale, reliability, and UX failure modes |
+   | similar | `evidence-similar.md` | comparable products and reusable lessons |
+
+   Dispatch up to the available child capacity, then dispatch each remaining
+   dimension when a slot opens. A pending corrected redispatch takes the slot
+   before any queued not-yet-dispatched dimension. Keep all briefs independent.
+   A custom fifth dimension supplements at least one dispatched standard
+   dimension; it never replaces the standard set.
+
+   In brownfield work, require stack research to weigh migration cost and
+   pitfalls research to check which failure modes already exist in the mapped
+   codebase.
+
+3. If a risk needs a distinct dimension, add one researcher, up to five total
+   (project policy).
+   Derive its filename deterministically as `evidence-<dimension-slug>.md`:
+   lowercase the label, replace non-alphanumeric runs with one hyphen, and
+   trim hyphens. Append `-2` only if it collides with an existing dimension.
+4. Validate each dispatched evidence file as its researcher returns. Require
+   at least one `## Finding` — a documented `no reliable source found` null
+   result recorded as a finding satisfies this gate, with the searches that
+   came up empty noted as its evidence — require Claim, Source, Confidence,
+   and Why it matters fields for every finding, and require an answer for
+   every question assigned to that dimension. For a missing or invalid file,
+   redispatch one complete corrected brief under the same logical task name,
+   following the runtime dispatch contract, as soon as a child slot allows —
+   never held until the remaining dimensions settle.
+5. After every dimension settles — validated, or its one corrected
+   redispatch collected — confirm every extracted `RESEARCH` question was
+   assigned to a dispatched dimension. Then run:
+
+   `python3 <absolute check_handoffs.py> research --repo <absolute repo root>`
+
+   The manifest is the source of truth for dispatched and skipped dimensions;
+   the STATE log records only a human-readable summary.
+   If any expected file still fails after its one corrected redispatch,
+   run `pipeline_state.py transition` with
+   expected `research/active`, exact branch and archive values,
+   `--set-status blocked`, and an event listing the failed evidence gate; then
+   present **Outcome** with the
+   failed gate, **Review** linking RESEARCH.md or STATE.md when the manifest is
+   missing, and **Next** naming the one correction or user decision required.
+   Stop; never advance with partial research.
+6. When all dispatched files and `RESEARCH.md` pass, run
+   `pipeline_state.py transition` with expected `research/active`, exact
+   branch and archive values, `--set-phase research --set-status done`, and
+   an event naming the manifest path, dispatched dimensions, skipped
+   dimensions, and question count. Include `--project-dir .project/next` for
+   lookahead. Require the returned state to be `research/done`. Report the
+   outcome, link the resolved absolute `RESEARCH.md` path,
+   summarize the dispatched evidence files, and name the decide phase as next.
+   The decide phase reads the manifest; it must not infer dispatch state from
+   a glob or free-form log. When routed by an active
+   `$gsd-path`, return control to that router. When invoked directly, stop and
+   tell the user to explicitly invoke `$gsd-path`, which routes to decide; do
+   not invoke an explicit-only sibling skill yourself.
+
+## Rules
+
+- Require evidence, not opinion: every claim needs a source actually checked
+  and a one-line tie-back to this project's intent.
+- Record conflicting sources rather than resolving them here.
+- Preserve dead ends and explicit `no reliable source found` answers.
+- Do not summarize the evidence; `$gsd-path-decide` owns that work.

package/skills/gsd-path-research/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "GSD Path Research"
+  short_description: "Gather cited evidence for project decisions"
+  default_prompt: "Use $gsd-path-research to gather cited evidence for the approved project intent."
+policy:
+  allow_implicit_invocation: false

package/skills/gsd-path-research/references/dispatch.md

@@ -0,0 +1,131 @@
+# Shared Agent Skills dispatch
+
+Apply this contract whenever a GSD Path skill delegates work from the shared
+`~/.agents/skills` bundle. Inspect the advertised child-agent tool schema and
+use exactly one matching branch:
+
+- A `spawn_agent` tool exposing `task_name`, `agent_type`, and `fork_turns` is
+  Codex. Use `fork_turns: "none"`; coders use the built-in `worker` type and
+  every other role uses `default`. Reuse a completed logical target with
+  `followup_task`. For Codex reasoning effort, use `high` for the portable
+  `heavy` tier and `low` for the portable `light` tier; leave reasoning effort
+  unset for the session-default tier, and never pass `heavy` or `light` as a
+  literal Codex value.
+- A `spawn_agent` tool without those Codex fields is Zed. Spawn one isolated,
+  full-capability child per brief. Zed children are not resumable, so retries
+  use a fresh child and a complete prompt.
+- An `invoke_subagent` tool advertising `TypeName`, `Workspace`, and `Role` is
+  Antigravity. Use `TypeName: self`, the exact supplied root as `Workspace`,
+  and the logical task name as `Role`. Keep the returned child ID and use
+  `send_message` for follow-up work when available; otherwise start a fresh
+  child with the complete prompt.
+- A `spawn_subagent` tool advertising the `general-purpose` type is Grok. Use
+  `subagent_type: general-purpose`, `capability_mode: all`, the exact supplied
+  root as `cwd`, `isolation: none`, and `background: true`. Supply the logical
+  task name as `description`, keep the returned ID, and use `resume_from` with
+  the complete new prompt for later work. Wait for a colliding active child and
+  collect results with `wait_commands_or_subagents`.
+- A `Task` tool advertising the custom `gsd-path` subagent is Cursor. Use that
+  model-inheriting, full-capability child. Resume it by returned agent ID when
+  available; otherwise retry with a fresh child and a complete prompt.
+- A `Task` tool advertising the built-in `general` subagent is OpenCode. Use
+  that child; if an installed OpenCode v2 host exposes the renamed `subagent`
+  tool instead, use its advertised schema with the built-in `general` agent.
+  Supply the logical task name as the child description. Reuse a returned
+  child-session ID only when the host advertises a resume parameter; otherwise
+  use a fresh `general` child and the complete prompt.
+- A `task` tool advertising the `general-purpose` child is GitHub Copilot CLI.
+  Use that child. Keep its returned ID for follow-up while the host exposes
+  it; otherwise retry with a fresh child and a complete prompt.
+- An `invoke_sub_agent` tool with a `general-purpose` subagent is Kiro. Use
+  that child for every role; there is no worker/default type split. Start a
+  fresh general-purpose child for every correction, retry, post-patch review,
+  repeated audit, or later milestone — Kiro subagents are not resumable and
+  disk artifacts are the source of truth. Supply the logical task name as the
+  task description. Set the child working directory to the exact repository or
+  linked-worktree root supplied by GSD Path; do not ask Kiro or the child to
+  create another worktree. Encode task dependencies explicitly; launch
+  independent children concurrently up to the host's advertised
+  concurrent-subagent capacity.
+
+For every branch:
+
+- Supply the deterministic logical task name: `inspect_codebase`,
+  `inspect_docs`, `docs_audit`, `research_<dimension>`, `decide`, `roadmap`,
+  `plan`,
+  `plan_patch`, `build_<task_id>`, `review_wave_<wave>_cycle_<cycle>`
+  (a `deep` wave review appends the lens suffix `_contract` or
+  `_adversarial`; an optional review panel uses
+  `review_wave_<wave>_cycle_<cycle>_panel_<family>`; an optional finding
+  skeptic uses `review_wave_<wave>_cycle_<cycle>_skeptic_<criterion_locator>`),
+  `review_plan_panel_<family>`,
+  `review_final`, or `review_gap_<number>`. Normalize variable parts to
+  lowercase ASCII and replace non-alphanumeric runs with one underscore.
+  Never add a random suffix or collide with a running logical target.
+- Resolve the phase's linked role brief to an absolute path, include it in the
+  prompt, and require the child to read it before acting. The role brief
+  supplies the read-only boundary for auditors and reviewers.
+- Tier hints: use the portable `heavy` tier for `plan`, `plan_patch`, `decide`,
+  and `roadmap`, the portable `light` tier for `inspect_docs` and `docs_audit`,
+  and the session-default tier for every other role. Apply the Codex mapping
+  above when its schema advertises reasoning-effort selection. On every other
+  host, use only an exact native equivalent advertised by that host; otherwise
+  do not override the model or reasoning effort. The only exception is a
+  review-panel child: when the host advertises model selection, pass the exact
+  slug returned by `scripts/review_panel.py resolve` for that family. Never
+  override the model on the canonical reviewer, planner, coder, or any other
+  role.
+  Host isolation: none. The child's working directory is the exact absolute
+  root GSD Path supplied; a host SHA checkout or extra worktree is a contract
+  failure. Never ask the host to create a worktree. Give the child the exact
+  repository or linked-worktree root supplied by GSD Path.
+- Send a self-contained prompt with absolute input, template, and output paths
+  plus the child's bounded responsibility. Every brief also names the absolute
+  `AGENTS.md` and `WORKFLOW.md` paths (or explicitly says they are absent), the
+  next phase that consumes the output, the gate it must satisfy, and the
+  terminal result it must return. A coder prompt also names its isolated
+  linked-worktree root; no child may infer the primary worktree.
+- The parent is the sole dispatcher and lifecycle owner. If the runtime exposes
+  structured Run/Task/Dispatch orchestration, bind one Run, create one Task per
+  independent brief with explicit dependencies, inject the brief, and wait for
+  every `worker_done`, `escalation`, or question before applying the gate.
+  Verify the task and dispatch records before reporting the work as
+  orchestrated. On runtimes without that layer, use the host adapter's
+  equivalent and preserve the same logical name, completion state,
+  timeout/cancellation, and cleanup rules; never silently delegate again from a
+  child.
+- When the structured layer exposes a blocking ask/reply channel, route a
+  coder's `NEEDS-ORCHESTRATOR` question through it as a live question with
+  the worker held alive for the reply, instead of block-and-redispatch. The
+  answer is still appended to the task Log as
+  `Orchestrator answer:` so the portable on-disk record stays complete, and a
+  timed-out or unavailable channel falls back to the portable block path.
+- A child that receives a disposable worktree stages its assigned artifact
+  under that root. The parent validates it and atomically transfers it to the
+  canonical project path before removing the exact disposable root. A child
+  never writes a disposable-review output directly into the primary worktree.
+- Launch independent briefs concurrently up to the advertised child capacity,
+  batch any remainder without combining briefs, and collect every result
+  before applying the phase gate. Do not leave an active child, logical task, or
+  temporary worktree after collection; a timeout or cancellation is a blocked
+  result, not a silent success.
+- If the tool schema is ambiguous or the required full-capability child is
+  unavailable, stop and report the missing capability. Do not guess the host
+  or silently collapse an independence boundary into the main context.
+
+## Configured output budgets
+
+When the owner supplies token budgets, use the router bundle's
+`scripts/token_budget.py` with the owner's exact task and session values and
+quoted authority. Keep one ledger outside the worktree under the Git common
+directory for the full logical session; resumptions reuse it. Record completed
+parent CLI run events and each native child's session events with stable logical
+task names before the next dispatch. The helper reads host counters and refuses
+incomplete or ambiguous usage; never estimate tokens or reset the ledger.
+Run `admit` for the next task and stop dispatch on a blocked result. Preserve
+its output in the dispatch evidence. This gates observed usage only: concurrent
+or in-flight work can overrun before the host reports usage. Codex CLI has no
+advertised hard output cap; report that limitation once. If the owner requires
+hard generation enforcement, use `admit --require-hard-cap`; unsupported means
+blocked, not budget compliance. Other hosts require a verified native counter
+and cap adapter before any enforcement claim.