@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.35 → 0.1.37

package/packages/agent-skills/assets/implement-feature/references/briefs.md

@@ -0,0 +1,94 @@
+# Sub-agent briefs (implementation run)
+
+Used by the lead (`implement-feature`). The sub-agent loads `workitems-process` and its own skill; the brief only supplies the inputs of this call.
+
+## Common header (paste into every brief)
+
+```text
+You are a leaf sub-agent of the implementation lead for <Feature or Bug> <id>. Spawn nothing.
+Worktree: <worktree> (the run's branch <branch>: the Feature branch, or fix/az<bug id>-<slug> in a per-Bug run). Head: <sha>. Run as agent-tarun.
+You start with no memory of earlier sub-agents. Read the plan folder, not their transcripts.
+You move no work item state and post nothing on the board. Return one report (format below).
+Skill: <skill name>. Follow it exactly. If this brief and the skill disagree, the skill wins; say so in a finding.
+```
+
+## Report format (what every sub-agent returns)
+
+````yaml
+lane: validate | design-update | implement | fix-ci | verify | verify-final | review-code | review-architecture | finalize
+target: <item id | feature id>
+base_sha: <origin/integration sha>
+head_sha: <worktree HEAD the report applies to>
+verdict: <set per lane, below>
+findings:                    # required for every non-pass verdict; WATCH lists its concerns
+  - id: F1
+    severity: critical | high | medium | low
+    where: path:line
+    what: "<issue and risk>"
+    fix: "<concrete change>"
+artifacts:                   # commands with exit codes, run ids, AC-n -> test map, commit SHAs
+  - ...
+````
+
+Plan-review lanes (`review-plan-architect`, `review-plan-critic`) belong to the planning run, not to these briefs; the full lane list is in [Evidence and reports](../../workitems-process/references/evidence.md#sub-agent-report-the-common-shape).
+
+The lead posts the report as an item comment (Feature comment for `-final`/`finalize`; in a per-Bug run, the Bug comment) and keeps it for the implementation report. The machine line that opens the run-level report (the run's last comment: on the Feature, or on the Bug in a per-Bug run, never on a PBI) is in [Evidence and reports](../../workitems-process/SKILL.md#evidence-and-reports).
+
+## validate (architect, skill validate-design)
+
+- Inputs: plan folder, `BaselineSha`, `against` (`HEAD` of the worktree, which contains the current `integration`: the run starts by merging `origin/integration` into its branch), optional `scope` (one item, for mid-loop drift) and the executor's `DRIFT` finding when there is one.
+- Check **`design.md` and its `file-map-reference.md`** by diffing `<BaselineSha>..HEAD`; record `head_sha`. Do not re-validate `requirements.md`.
+- Read-only. Edit nothing, including `design.md`.
+- Verdicts: `FRESH` · `DRIFT` (exact delta in `findings`: `where` = design section + path, `fix` = replacement text).
+
+## update design (planner, skill plan-feature, design-update mode)
+
+- Inputs: the `DRIFT` findings.
+- Update exactly: `design.md`, to fit the repo; `file-map-reference.md` (the `## Map` rows the delta moves, and the `## Baseline` section, set to the new `integration` base); the Feature's Baseline Sha field, set to the same base; and the `plans/LEDGER.md` row `az<feature id>-design-update`. Plan Revision and Plan Hash stay. Never touch `requirements.md`, item files or `intent.md`.
+- Commit `docs(az<feature id>): update design for <drift>` on the Feature branch, with the LEDGER row in the same commit. Do not push. The lead writes no file; it records the update in the implementation report and the PR.
+- Verdicts: `UPDATED` (commit SHA, new Baseline Sha).
+
+## implement (executor, skill implement-item)
+
+- Mode: build or resume for a PBI; rework for a PBI or a Bug when the brief lists findings.
+- Inputs: item id and file, its `AC-n` list from `requirements.md`, its section of `design.md`, the findings to fix (rework only).
+- Tests first: each `AC-n` gets a failing test that fails for the right reason; then minimal code; docs in the same change; slop pass; repo checks.
+- Commit on the run's branch, `AB#<item id>` in the body. Do not push. Do not create a branch, worktree or PR.
+- Verdicts: `DONE` (commit SHAs; red and green run per `AC-n`) · `DRIFT` · `PARK`.
+
+## reproduce, per-Bug run (executor, skill implement-item, reproduce mode)
+
+- Inputs: Bug id, its G1-approved Description, branch `fix/az<bug id>-<slug>`, the base (the `integration` SHA the branch was created from). The Bug is at In Reproduction.
+- First commit: the Bug's item file `plans/features/az<fixes id>-fixes-to-closed-features/items/az<bug id>-<slug>.md`, with the five bugfix sections of the approved Description plus `## Predecessors` mirroring the board link ([Item files](../../workitems-process/references/ado-and-git.md#5-item-files)), plus its LEDGER row `az<bug id>-bug`. Next: the regression test. **The reproduce commit stays green.** The executor runs the regression test unmarked on the base and proves it red; that run output goes into a comment on the Bug as evidence (the executor returns it, the lead posts it). It commits the test marked as an expected failure (the framework's xfail or `test.fails` form), so lint, typecheck, build and the suite pass (`fix(<scope>): add failing regression test for az<bug id> (expected failure)`). Nothing else: no fix in this brief.
+- Verdicts: `DONE` (the item file and the regression test committed, the unmarked test red on the base with that run output, the test committed marked as an expected failure, every commit green, no fix) · `PARK` (won't reproduce, with what was tried).
+
+## fix, per-Bug run (executor, skill implement-item, bug mode)
+
+- Sent after the lead moves the Bug In Reproduction → In Fixing. Inputs: Bug id, its item file, the committed regression test (marked as an expected failure) and its unmarked red run on the base.
+- Minimal code until the regression test and the item file's EARS criteria are green. The fix commit removes the expected-failure mark, so the same test now passes normally. Every commit stays independently green, with no exception; docs the fix makes wrong in the same change. Findings from the loop come back in a rework brief (rework mode).
+- Verdicts: as `implement`.
+
+## verify (verifier, skill verify-item)
+
+- Inputs: item and its `AC-n`, the head SHA (for a Bug: the Bug item file's `## Expected behaviour` (EARS) plus `## Behaviour that must not change`). For `verify-final`: every `AC-n` of `requirements.md` and the full suite at the final head; in a per-Bug run, the Bug item file's `## Expected behaviour` (EARS) plus `## Behaviour that must not change`, with `base_sha` = the `integration` SHA the `fix/` branch was created from.
+- Read-only on the shared worktree. Scratch files only in `.scratchpad/`, deleted before you stop. Never change HEAD.
+- Verdicts: `PASS` · `FAIL`.
+
+## review (code-reviewer, architect, skill review-change)
+
+- Inputs: lane, scope (an item's commits, or `origin/integration...HEAD` for the final check), the head SHA, the item's `AC-n` and design section.
+- Read-only. No PR comments, no votes (none exist before the merge).
+- Code lane verdicts: `APPROVE` · `REQUEST_CHANGES`. Architecture lane: `CLEAR` · `WATCH` · `BLOCK`.
+- Spawn the two lanes in parallel. The lead's model config preferably puts reviewers in a different model family from `executor`, when the surface allows (not required).
+
+## finalize (writer, skill finalize-feature)
+
+- Inputs: the final head `H`, all item reports, the Feature-final verify and review reports, CI rounds so far.
+- No pushes, no files, no board writes. Return in the reply: the PR body (five sections), the implementation report text, and the docs-impact table.
+- Verdicts: `DONE` · `REWORK` (finding `docs-missing` naming the doc).
+
+## fix-ci (executor, skill fix-ci)
+
+- Inputs: PR id, failed build and job ids, the head SHA, the related item id.
+- Smallest fix, hard cut: no skip, no `|| true`, no loosened test. Commit on the branch, do not push.
+- Verdicts: `FIXED` · `INFRA` (not a code failure; log proof for the lead).

package/packages/agent-skills/assets/implement-item/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: implement-item
+description: "Implement one work item PBI or Bug of a Feature as commits on the run's branch, the Feature branch or the fix/ branch - each EARS acceptance criterion gets a failing test first, then minimal code, docs in the same change, slop pass, green commits. No per-item branch, worktree or PR, and no board moves. Use when the implementation lead spawns executor for an item: build, or rework of listed findings."
+metadata:
+  step: "implement"
+  role: "executor"
+  states: "In Implementation, In Reproduction, In Fixing"
+---
+
+# Implement Item (sub-agent skill)
+
+Load `workitems-process` first. You are a leaf sub-agent of `lead` (`implement-feature`). You turn one item's slice of the approved plan into tested, documented commits on the **shared Feature branch** (per-Bug run: the Bug's `fix/az<bug id>-<slug>` branch). The lead moves board states, pushes, and opens the run's one PR. The item loop is non-linear: you may be called again for the same item after a test, review or CI finding.
+
+## When to use
+
+Each call maps to exactly one mode. The conditions do not overlap:
+
+| Mode | Condition |
+|---|---|
+| **build** | A PBI, the brief lists no findings, and no commit with `AB#<item id>` exists yet |
+| **resume** | A PBI, the brief lists no findings, and the item has commits from an earlier attempt: continue from the last green commit, never restart |
+| **rework** | The brief lists findings (verify, review, docs, CI) to fix, for a PBI or a Bug at In Fixing |
+| **reproduce** | Per-Bug run, the first per-Bug brief, Bug at In Reproduction: write the item file plus the regression test, proved red on the base and committed marked as an expected failure so the commit stays green; no fix (procedure step 0, then step 2 only). Commits an earlier attempt already made are kept, not redone |
+| **bug** | Per-Bug run, the later fix brief, Bug at In Fixing, the brief lists no findings: the item file and the regression test (marked as an expected failure) are committed; minimal code until green, removing the mark in the fix commit (steps 3-8), continuing from the last green commit of an earlier attempt |
+
+Not for planning, verifying, reviewing, or CI logs (CI is `fix-ci`).
+
+## Inputs (from the brief)
+
+- Item id and file `plans/features/az<feature>-<slug>/items/az<id>-<slug>.md`; its `AC-n` list from `requirements.md` (EARS: "THE SYSTEM SHALL ..."); its section of `design.md` and `file-map-reference.md`.
+- Rework: the findings to fix, each with `id`, `where`, `fix`.
+- Worktree and branch are the lead's; you never create or switch them.
+
+## Preconditions
+
+1. Worktree toplevel equals the brief's worktree; the branch is the run's branch; `git status --porcelain` is empty or is your own previous attempt.
+2. Every `AC-n` is one unambiguous EARS sentence you can turn into a test. If not, return the one concrete question to the lead and stop. Never pick a conservative reading and carry on.
+3. `design.md` still fits the code for your files. If a named file or symbol is gone or the approach breaks a boundary: `DRIFT`, before any edit.
+
+## Procedure
+
+0. **Bug item file (reproduce mode).** Write `plans/features/az<fixes id>-fixes-to-closed-features/items/az<bug id>-<slug>.md` from the G1-approved Bug Description, with the Bug item-file sections: the Description's five bugfix sections plus `## Predecessors` mirroring the board link, always present and reading `none` for the first Bug ([Item files](../workitems-process/references/ado-and-git.md#5-item-files)), and its `plans/LEDGER.md` row `az<bug id>-bug`. Commit it first (`docs(plans): add item file for az<bug id> <slug>`, `AB#<bug id>` in the body). Change nothing the Description does not say; a gap is a question to the lead.
+1. **Mode.** Rework: list the exact finding ids you will fix; nothing else is in scope.
+2. **Tests first.** For each `AC-n` write or extend the test the design names, with the `AC-n` in the test name or a comment. Run it. It must be **red for the right reason** (assertion on the missing behaviour, not an import or syntax error). Reproduce mode: the regression test reproduces the reported defect; the Bug's item file is the plan (no `AC-n` from `requirements.md`; the file's EARS criteria stand in). **The reproduce commit stays green.** The executor runs the regression test unmarked on the base (the `integration` SHA the `fix/` branch was created from) and proves it red; that run output goes into a comment on the Bug as evidence (the executor returns it, the lead posts it). It commits the test marked as an expected failure (the framework's xfail or `test.fails` form), so lint, typecheck, build and the suite pass (`fix(<scope>): add failing regression test for az<bug id> (expected failure)`, `AB#<bug id>` in the body). The fix commit removes the expected-failure mark, so the same test now passes normally. Every commit stays independently green, with no exception. Then skip to step 8: reproduce mode writes no fix, no docs and no other code.
+3. **Minimal code** until those tests pass (bug mode: until the committed regression test, with its expected-failure mark removed in the fix commit, and the item file's EARS criteria pass normally). No speculative options, no unrelated refactors, no new abstraction unless the code needs it.
+4. **Docs in the same change.** Write every doc `design.md` `## Docs impact` lists for this item (per-Bug run: every doc the fix makes wrong).
+5. **Slop pass** on changed files only: dead code, debug leftovers, needless wrappers, duplication, swallowed errors, masking fallbacks, stray TODOs. Delete rather than wrap. Then re-run step 6.
+6. **Checks.** Repo lint, typecheck, build and the relevant test suite, locally. Every commit passes them alone; hooks from `adl repo controls` run; never bypass them.
+7. **Commit** on the shared branch: `<type>(<scope>): <lowercase subject>`, types `feat|fix|docs|refactor|perf|chore`, `AB#<item id>` in the body, one cohesive topic per commit, green wins over tidy. **Do not push.** Rework commits name the finding id.
+8. **Return the report** (`implement-feature` › `references/briefs.md`): `lane: implement`, `target` = item id, `head_sha` = your last commit, `verdict`, `findings`, `artifacts` = commit SHAs, per `AC-n` the test name, red run (command + failing assertion) and green run (command + exit code), final check run, docs touched, and on rework each finding id → commit SHA. Reproduce mode: the unmarked red run on the base (command + failing assertion), for the lead to post on the Bug, and the green check run of the reproduce commit.
+
+## Verdicts
+
+| Verdict | When |
+|---|---|
+| `DONE` | build, resume, rework, bug: every `AC-n` of the slice (bug: the regression test and the Bug item file's EARS criteria) has a test that was red then green; checks green; docs written. Bug: the fix commit removed the regression test's expected-failure mark and the test passes normally. Reproduce: the item file and the regression test are committed, the unmarked test is red on the base with that run output in the report, the test is committed marked as an expected failure, every commit is green (lint, typecheck, build, suite), and no fix is committed |
+| `DRIFT` | Design no longer fits the code; nothing half-done is committed; findings name the file/symbol, what the design assumed, what the code is now, the proposed design change |
+| `PARK` | The work is obsolete, with proof (the lead moves the item to Parked for Removal) |
+
+## Stop rules
+
+- Stop after the report. Do not start verification or review.
+- The same check fails three times after distinct fixes: return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)).
+
+## Never
+
+- Never move an item, set a state, touch another item, or open or update a PR.
+- Never push, force-push, rebase, create a branch, worktree or stash.
+- Never skip, loosen or delete a test to get green; never `--no-verify`; never `|| true`. The reproduce commit's expected-failure mark is not a skip: it asserts the test fails, and the fix commit removes it. Never commit an expected-failure mark outside reproduce mode, and never leave one after the fix commit.
+- Never widen scope beyond the slice, or fix findings that are not listed.
+- Never edit `requirements.md`, `design.md` or `intent.md`. A needed plan change is `DRIFT` (design drift: planner sub-agent updates `design.md`, [No block](../workitems-process/SKILL.md#no-block)); a needed change to an `AC-n` is returned to the lead as a finding.

package/packages/agent-skills/assets/mechanics/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: mechanics
+description: How agents reach Azure DevOps in an adl-controlled repository — agent identity, the git front controller, the adl MCP tools and their CLI fallback, repository-control hooks, and when `adl run` may start a sub-agent.
+---
+
+# adl mechanics
+
+How adl behaves on every machine and in every repository it controls.
+
+## Use When
+
+- You are about to run a git network command, open or update a PR, read or write a work item, or start a build.
+- A command is refused for identity, credentials or hooks, and you need to know why.
+- The operator asks you to start a sub-agent session with `adl run`.
+
+## Agent identity
+
+- Every Azure DevOps access (git, PRs, work items, builds, reads included) runs as an agent identity, never as the human. The default is the machine's default agent, set by fleet reconcile; it can always be overridden.
+- **Override:** prefix a command with `ADL_AGENT_ID_AGENT=<agent-id>`. An MCP tool call can't carry a prefix, so it uses the session environment or the machine default; the CLI fallback (`adl mcp cli <command>`) takes the prefix like any command.
+- Never read vault files. Never pass a token.
+- **Never set `ADL_HUMAN_AZDO`.** It is the owner's human-terminal marker for `git-ado`'s and `adl id whoami`'s fail-closed human pass-through (stdin is a TTY and `ADL_HUMAN_AZDO=1`, exactly). An agent carrying it would let a child process forge that pass-through.
+
+## Git and Azure DevOps operations
+
+- Use ordinary `git` for every Git operation. The managed `/usr/local/bin/git` front controller hands local and non-Azure DevOps work to the system Git, and routes HTTPS Azure DevOps network commands through `adl-agent-id exec --agent "$ADL_AGENT_ID_AGENT"`. `git-ado` handles the credential boundary; there is no second account or secret location.
+- PRs, work items and builds go through the `adl` MCP server (`adl mcp serve`): `pr_list_or_get`, `pr_create_or_update`, `pr_review`, `build_list_or_get`, `build_run`, `workitem_list_or_get`, `workitem_create_or_update`. If the server is not working, fall back to `adl mcp cli <command>`.
+
+## Repository controls
+
+- Run via `adl repo controls`. Git hooks run pre-commit (local checks) and pre-push (Azure DevOps governance).
+- Each repository is reconciled on its own, with its `.agents/`, `.claude/`, `.codex/`, `.cursor/`, `.kimi-code/` and `.opencode/` projections.
+
+## Sub-agent sessions (`adl run`)
+
+- Only on the operator's explicit request; an agent never starts one on its own. It is not an identity route and not a fallback for anything.
+- **Headless:** `adl run <surface> --headless "<prompt>"`, surface one of `claude`, `codex`, `opencode`, `kimi`, `cursor`.
+- **Identity:** add `--as <agent>`.
+- **Model:** add `--model <model>`. adl passes each surface's own flag (claude and cursor `--model`; codex, opencode and kimi `-m`); a surface without one refuses it (exit 2). `--model` cannot be combined with `adl run -- <cmd>`.

package/packages/agent-skills/assets/plan-feature/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: plan-feature
+description: Planning run for one Feature, led by planner with the ralplan protocol - read intent.md, write requirements.md, what and why with EARS criteria, design.md for the how, and file-map-reference.md, create or update the PBIs on the board, review with architect then critic, cap 3, write the Feature plan fields, and raise the planning PR. Never plans Bugs (they have their own ladder), and runs as the design-update sub-agent during implementation. Use when the dispatcher sends the planning target for a Feature.
+metadata:
+  step: "planning"
+  role: "planner"
+  states: "Feature:New,In Progress; items:New,In Planning"
+---
+
+# Plan Feature
+
+Load `workitems-process` first. This card adds only what the planning run does. Planning is per Feature, not per item. States, gates, PR wiring, evidence and the no-block paths are in [workitems-process](../workitems-process/SKILL.md); the plan-file sections are in [ado-and-git.md](../workitems-process/references/ado-and-git.md#4-plan-files).
+
+## When to use
+
+- **Mode A, planning run (default).** Dispatched planning target, key = the Feature. Lead: `planner`. When it fires: [Targets and triggers](../workitems-process/SKILL.md#targets-and-triggers).
+- **Mode B, design update.** A sub-agent brief from the implementation lead: `design.md` no longer matches the repo. See "Mode B".
+- **Not for Bugs.** A Bug is never planned: see [Bug states](../workitems-process/references/workitem-states.md#5-bug-states).
+- Not for a Feature with no `intent.md` (that is `write-feature`, a live session).
+
+## Inputs
+
+| Field | Meaning here |
+|---|---|
+| `feature_id` | The Feature. The run key |
+| `worktree` | `docs/az<feature>-<slug>-plan`, made by adl-dispatcher |
+| `resume_notes` | The previous session's tail, if any |
+
+Branch: `docs/az<feature>-<slug>-plan`, created by adl-dispatcher. A re-entry reuses the same branch. Identity: `agent-tarun`.
+
+## Preconditions
+
+1. `workitems-process` universal preconditions (worktree, board state, identity). The state check is on the Feature: New or In Progress.
+2. `plans/features/az<feature>-<slug>/intent.md` exists on `origin/integration` and its `work_item` id equals the folder id. If not, the trigger does not hold: report the mismatch on the Feature and end the run; the next tick re-evaluates.
+3. The Feature has an Epic parent and at least one predecessor Feature (the very first Feature has none), and every predecessor is at Awaiting Release or Done. If not, report what is missing on the Feature and end the run; the Epic and the links are authored by the human, never created or guessed by you.
+4. Resume: read the board and the branch first. Reuse allocated ids; never allocate twice.
+
+## Procedure (Mode A)
+
+**The protocol is ralplan** (`adl/skills/ralplan/SKILL.md`): Planner authors, Architect reviews, Critic gates, strictly in that order, cap **3** rounds. You are the Planner; Architect and Critic are sub-agents you spawn. Not taken from adl-workflow: `adw ralplan run`, `.adw/state`, `.adw/plans`, the `$ultragoal` handoff (G1 replaces it).
+
+### 1. Orient and pin the baseline
+
+1. Read `intent.md`, the predecessor Features' plan folders on `origin/integration`, the existing plan folder if any, and every G1 finding or reviewer finding left on the Feature and its items (comment read tool pending T1).
+2. Understand the code: `crg architecture`, `crg query callers_of|tests_for <symbol>`, `crg impact`. You may spawn read-only explore sub-agents on the fast tier; they write nothing.
+3. Re-entry on an existing plan branch: `git fetch origin integration` and `git merge --no-edit origin/integration` into it. Never recreate, rebase or force-push it.
+4. **Baseline Sha** = the exact `origin/integration` SHA you read. It goes in `file-map-reference.md` `## Baseline` and in the Feature's Baseline Sha field.
+5. **Revision N.** The revision increments once per G1 submission: N = current `Plan Revision` + 1 when this run follows a G1 decision (rework or requeue) or is the first run (N = 1). A resumed or re-dispatched run with no G1 decision since the last revision keeps N. The review rounds inside one planning run share N. Read the board fields; named arguments are pending T3, so until then they pass through `--fields` as `Custom.PlanRevision`, `Custom.PlanHash`, `Custom.BaselineSha` (reference names not yet confirmed through the API).
+
+### 2. Draft
+
+**Order:** decide the item split, then do the board part of step 5 first: allocate any new PBIs on the board, then move every in-scope PBI (existing and new) New -> In Planning. Only then write the files below and the item files. Every in-scope PBI is at In Planning before the planning PR is raised.
+
+1. **`requirements.md`** (what and why only), with the sections and frontmatter in [ado-and-git.md](../workitems-process/references/ado-and-git.md#4-plan-files). Every acceptance criterion is one EARS sentence, numbered `AC-n`, one criterion one test.
+2. **`design.md`** (the how), with exactly the sections, rules and frontmatter in [ado-and-git.md § Plan files](../workitems-process/references/ado-and-git.md#4-plan-files); that table is the one list. How to fill them:
+   - The RALPLAN-DR summary in `## Decisions`: principles (3-5), decision drivers (top 3), viable options (>= 2, bounded pros/cons, or a sound invalidation of the others). High-risk work (auth, migration, destructive change, public API break) is deliberate mode: add a pre-mortem (3 scenarios).
+   - In `## Verification`, reworked existing tests each name the decision that changed them.
+   - `finalize-feature`, `implement-item` and `review-change` check the diff against `## Docs impact`.
+   - A touchpoint in `## Size estimate` is a `file-map-reference.md` row of Kind `change` or `new`.
+3. **`file-map-reference.md`**: every path the plan touches: read / change / new, why, items. `## Baseline` = Baseline Sha.
+4. **`## Revision log`** row for revision N, written once per revision (Trigger: first plan, `G1 rework` or `G1 requeue`; Changes: what changed since N-1, including every added or dropped item and changed AC). Review rounds of N update that row's Changes cell, never add a row.
+5. **Items.** First match every existing child PBI of the Feature to the planned items (by id, then by title or slug). Never allocate a second item for work already on the board. Then allocate each planned item with no board item **before** its file: `workitem_create_or_update --type 'Product Backlog Item' --title ... --parent-id <feature>`. Then move every in-scope PBI (existing and new) New -> In Planning. Only then, in the write-files step, write the ids into `## Items` and write `items/az<id>-<slug>.md` with the item-file sections in [ado-and-git.md](../workitems-process/references/ado-and-git.md#5-item-files). Items that already exist are updated, not duplicated. If allocation fails partway, move the PBIs you did allocate New -> In Planning and stop; nothing is committed before the move. The lead re-allocates the rest on the next tick, in the same worktree and branch.
+   - **Item-split rules.** One PBI = one observable outcome from `intent.md` that fits one PR and can be specified, tested and reviewed on its own. Never split by layer (no "backend item" plus "frontend item" for one outcome). Slug is kebab (`^[a-z0-9]+(-[a-z0-9]+)*$`, <= 40 chars); title is written as an outcome. Prefer fewer, larger-than-trivial items over fragments. Cover every goal in `intent.md`; respect every non-goal. Items carry no predecessors; the lead orders items inside the loop.
+6. **Describe the loop as non-linear.** Where a plan mentions In Implementation, In Testing, In Review and Updating Docs, it says they are free moves ([States at a glance](../workitems-process/SKILL.md#states-at-a-glance)).
+
+### 3. Self-check before review
+
+- Every AC is one EARS sentence, observable, with an expected result. Every AC is verified by at least one item; every item names its `AC-n`.
+- Sizing (the critic enforces it): <= 6 items, ~<= 40 touchpoints, ~<= 1,500 changed lines, one coherent outcome (the `intent.md` `## Outcome`). Over the gate: split the Feature or cut scope **before** review.
+- No `TBD`, `TODO` or placeholder text anywhere in the plan files.
+- Nothing undecided is written as fact. It goes in `## Open questions for G1`, each with a recommendation.
+
+### 4. Review (ralplan, sequential, cap 3)
+
+1. Commit the draft on the planning branch (commit grammar below). Hash what you drafted: `shasum -a 256 requirements.md`.
+2. **Architect.** Spawn `architect` with the `review-plan` architect-lane brief: the plan folder at the commit, `intent.md`, the baseline SHA, prior findings. **Await it.**
+3. **Critic.** Only after the Architect returned, spawn `critic` with the critic-lane brief and the Architect's full review. Never in the same batch.
+4. `APPROVE` -> go to step 5. `ITERATE` or `REJECT` -> revise (every finding `addressed` or `declined` with a reason) and go back to the Architect with the same revision N. After **3** rounds without `APPROVE`, the best version goes forward with its open findings listed in `## Open questions for G1`.
+5. **Only the planner writes to the board.** After each round (Architect then Critic) post ONE combined comment on the Feature: `Revision N round R`, `Architect findings`, `Critic findings`, and the resolution of each finding (`addressed` or `declined` with reason). Architect and Critic return their reviews as replies and post nothing.
+6. Sub-agents are leaves, read-only, and each starts in a fresh context; there are no votes ([Human gates](../workitems-process/SKILL.md#human-gates)).
+
+### 5. Finalize the revision
+
+1. Check the `## Revision log` row for N names every change of the rounds.
+2. **Plan Hash = sha256 of `requirements.md` only**: `shasum -a 256 plans/features/az<feature>-<slug>/requirements.md` at the commit you push. The hash lives on the board, never inside a file.
+3. Write the Feature fields: `Plan Revision` = N, `Plan Hash`, `Baseline Sha` (`workitem_create_or_update --id <feature> ...`; named arguments pending T3, writability by this identity unconfirmed). A refused write: post the exact refusal text as a Feature comment and take the path the refusal names; never work around it.
+4. Prepare the plan snapshot `plan-r<N>-<sha7>.md` (`<sha7>` = first 7 chars of Plan Hash) in `.scratchpad/`: `requirements.md`, `design.md`, `file-map-reference.md`, then every item file, in one file ([Evidence and reports](../workitems-process/SKILL.md#evidence-and-reports)). How the content reaches the tool is pending P4: the tool attaches it and refuses to raise the PR without it.
+5. Append one row per `plans/` commit to `plans/LEDGER.md`.
+6. Every in-scope PBI is at In Planning before the planning PR is raised: after allocating any new PBIs you moved every in-scope PBI (existing and new) New -> In Planning, then wrote the files (§2 step 5). Do nothing else to item states.
+
+### 6. Raise the planning PR
+
+- `pr_create_or_update`: title `docs(plans): plan az<feature> <slug>`, head `docs/az<feature>-<slug>-plan`, target `integration`, with the five PR body sections ([ado-and-git.md](../workitems-process/references/ado-and-git.md#7-git)); `## Test plan` and `## Security impact considered` say "none (docs-only)".
+- **The tool does the board wiring; you pass nothing and move nothing** ([PR wiring](../workitems-process/references/ado-and-git.md#6-pr-wiring)).
+- No reviewer, no vote. Never force-push.
+- Read back every item: state Awaiting Approval. If the tool did not move them (it cannot until P2 ships), report the gap and end the run. Do not move them by hand and do not work around it.
+
+### 7. Done and stop
+
+- Done proof: every in-scope item reads Awaiting Approval and the planning PR is raised. The run pauses at G1; the implementation trigger also needs the planning PR merged into `integration`.
+- Post one planning report on the Feature ([Evidence and reports](../workitems-process/SKILL.md#evidence-and-reports)): revision N, baseline SHA, plan hash, round count, the Critic verdict, open findings, PR URL, allocated ids.
+- Final line: `planning <DONE|PARK> feature <id> rev <N> @ <baseline sha7>`. Never end with an offer.
+
+## Re-entry
+
+- **G1 rework** (Awaiting Approval -> In Planning) = revise: the same planner amends the plan, addressing every G1 comment.
+- **G1 requeue** (Awaiting Approval -> New) = reject: write a fresh approach, do not patch the rejected one, and record the rejection reason in the Revision log (Trigger `G1 requeue`).
+- Both fire this target again ([Targets and triggers](../workitems-process/SKILL.md#targets-and-triggers)) on the existing plan branch. The run starts revision N+1, addresses every G1 and reviewer finding, repeats steps 4-6. New hash, new snapshot (old ones stay on the board).
+- Scope never changes silently: a revision that adds or drops an item, or changes an AC, says so in the Revision log.
+
+## Bugs are not planned
+
+A Fixes Bug has its own ladder and no plan folder ([Bug states](../workitems-process/references/workitem-states.md#5-bug-states)). If a Bug reaches this skill, report it to the caller and do not plan it.
+
+## Mode B: design update (sub-agent)
+
+- Brief from the implementation lead: the Feature, the branch head, the drift (`design.md` vs the repo).
+- Your write scope is exactly four things: `design.md` (`file:line` refs, `## Solution`, `## Verification` rows, `## Docs impact`, `## Size estimate`); `file-map-reference.md` (its `## Map` where the map changed, and its `## Baseline` section, set to the new `origin/integration` base); the Feature's `Baseline Sha` field, set to the same base; and the `plans/LEDGER.md` row `az<id>-design-update`. Plan Revision and Plan Hash are unchanged: the hash covers `requirements.md` only, which you never touch, nor item files.
+- Commit on the lead's Feature branch as one docs commit carrying the LEDGER row. The lead writes no file; it records the update in the implementation report and the PR.
+- Drift that would need an approved `AC-n` changed: do not edit; return it to the lead as a finding. The lead's path is in [No block](../workitems-process/SKILL.md#no-block).
+- Return a summary to the lead (files changed, new baseline, what moved). You are a leaf: spawn nothing.
+
+## Commits
+
+`<type>(<scope>): <lowercase subject>`, type `docs` for plan files. Each commit green. One topic per commit. Never `git stash`. Planning commits carry no `AB#` (the tool links the items).
+
+## Stop rules
+
+- Intent that cannot be turned into testable criteria: write the gap as an Open question for G1 with a recommendation; never invent requirements.
+- A refused board call: post the exact refusal text as a Feature comment and take the path the refusal names. Never retry through another path; no file without an id.
+- The same command failing twice for the same reason: stop retrying it and take a different path ([No block](../workitems-process/SKILL.md#no-block)).
+- Obsolete work -> move the in-scope items to Parked for Removal yourself, each with a reason comment; never Removed (Parked -> Removed is G3). The run verdict is then PARK.
+
+## Never
+
+- Never move an item to Awaiting Approval, Approved, Done or Removed. Never move a Feature (workitem-triage rolls it up).
+- Never edit `intent.md`. It is the human's.
+- Never answer a G1 open question and remove it yourself; it stays listed for G1.
+- Never put the Plan Hash, revision or baseline in frontmatter.
+- Never ask the Architect and Critic in one parallel batch, and never let the same context author and approve.
+- Never create an Epic or a Feature link. Never add a predecessor link to a PBI. Never plan or touch a Bug.

package/packages/agent-skills/assets/prepare-promotion/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: prepare-promotion
+description: Write the release summary on the open integration-to-main promotion PR - included work items, integration validation runs, notable risks and a rollback note - so the human can decide G2. Parked - no dispatcher target fires it; it belongs to the G2 gate. Never approves, merges or pushes.
+metadata:
+  step: "prepare-promotion"
+  role: "writer"
+  states: "none (promotion PR; G2 is human)"
+---
+
+> **Status:** parked. No target fires this skill; it belongs to G2.
+
+# Prepare Promotion
+
+Give the human everything needed to approve or reject the exact promotion revision. The
+pipeline opens the promotion PR; you only write its description. G2 is human. Load
+`workitems-process` for the report format and the adl MCP/CLI tool list.
+
+## When to use
+
+- An open PR `integration → main` exists and its description has no release summary for its
+  current head SHA.
+- Run again when the promotion PR head moved after a summary was written.
+- Not for opening the promotion PR, fixing anything, or approving.
+
+## Inputs
+
+`base_sha` (current `main` SHA), `head_sha` (promotion PR head on `integration`),
+`resume_notes`, `worktree` (none, API-only).
+
+## Preconditions
+
+1. Exactly one open PR with source `integration` and target `main` (`pr_list_or_get`). Never open one yourself. None or several: report what you found and stop.
+2. `main` equals `base_sha`; else write the summary against the current `main` and record it as `base_sha`. If the PR head differs from `head_sha`, write the summary against the current head and record it as `head_sha`.
+3. `worktree` is `none` (skip the check), or `git rev-parse --show-toplevel` equals it.
+
+## Procedure
+
+1. **Range.** Commits in `<base_sha>..<head_sha>` (PR commits, or `git log --oneline` in a read-only
+   checkout). Collect work items: PR-linked items plus every `AB#<id>` in commit messages.
+2. **Included items.** For each id (`workitem_list_or_get`): type, title, state, link, the merged Feature
+   PR link. Any item not Done → list it under risks with its state (it rode in on a shared commit).
+3. **Integration validation.** `build_list_or_get` for pipeline runs on `integration` at `head_sha`:
+   pipeline, run id, result, link. No completed green run at `head_sha` → say so plainly in risks;
+   never imply validation that did not run.
+4. **Notable risks**, each one line with its source:
+   - architecture WATCH concerns from the included items' review evidence;
+   - open Bugs related to included items;
+   - schema, config, migration or public-interface changes visible in the diff;
+   - items not Done, missing validation, reverted commits in the range.
+5. **Rollback note.** Current `main` SHA (`base_sha`); the action to undo (revert the promotion merge
+   commit on `main`); any change that a revert does not undo (data migration, external state) named
+   explicitly, or "none found in the diff".
+6. **Write the description** with `pr_create_or_update` on the existing PR: `## Summary` (one paragraph,
+   counts of PBIs and Bugs), `## Why` (what this promotion delivers), `## Changes` (included items
+   table: id, type, title, state, PR; then the notable risks and the rollback note), `## Test plan`
+   (the integration validation runs), `## Security impact considered` (security notes from the
+   included items' code reviews, or "none" with those reports as the source), and a footer line
+   `release-summary @ <head_sha>`. These are the five PR body sections in
+   [ado-and-git.md](../workitems-process/references/ado-and-git.md#7-git). Keep any text a human added above the summary.
+7. Read the PR back and confirm the description saved with the footer SHA.
+8. Post the report (see below).
+
+## Verdicts and transitions
+
+| Verdict | When | Effect |
+|---|---|---|
+| `DONE` | summary written and read back for `head_sha` | none; human decides G2 |
+
+No work-item state changes. G2 approve → merge to `main`; G2 reject → corrective items, Done stays Done.
+Both are human.
+
+## Report
+
+One report in the `workitems-process` shape, posted as a comment on the promotion PR (there is no single work item):
+`lane: prepare-promotion`, `target` (promotion PR id), `base_sha` (main), `head_sha` (promotion head), `verdict`;
+`artifacts`: promotion PR link, included item ids, validation run ids, risk count;
+`findings`: none for `DONE`.
+
+## Stop rules
+
+- One summary per head SHA, against the `head_sha` recorded at start. If the head moves while you write,
+  finish against that `head_sha` and say so in the summary; never stop or restart. The caller runs this
+  card again at the new head (When to use; [Evidence and reports](../workitems-process/SKILL.md#evidence-and-reports), the head rule).
+- A PR write fails through MCP and `adl mcp cli`: report both errors and stop; G2 stays with the human.
+
+## Never
+
+- Never open, approve, vote on, complete, merge or set auto-complete on the promotion PR.
+- Never push, commit, or create corrective items here (G2 rejection is handled by the human).
+- Never list an item, run or risk you did not read from the board, the pipeline or the diff.
+- Never remove a human's text from the description.

package/packages/agent-skills/assets/ralplan/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: ralplan
+description: Consensus planning stage for Planner -> Architect -> Critic handoff to $ultragoal
+---
+
+# Ralplan (Consensus Planning Alias)
+
+Ralplan is the canonical consensus-planning stage used by Autopilot between `$deep-interview` and `$ultragoal`. It drives Planner, Architect, and Critic planning and records their review lifecycle with **RALPLAN-DR structured deliberation** (short mode by default, deliberate mode for high-risk work). Local lifecycle evidence is not host-issued security authority, but ordinary progression to Ultragoal must remain reachable after the execution-ready plan and sequential review evidence are durable; missing host provenance must not terminalize Ralplan or block cancel, clear, or recovery.
+
+## Usage
+
+```
+$ralplan "task description"
+```
+
+Standalone advisory planning is explicitly opt-in:
+
+```text
+$ralplan --advisory "task description"
+```
+
+Advisory runs the same sequential Planner → Architect → Critic review lifecycle, binds the plan and both review artifacts to exact bytes and one tracker-backed iteration, then returns to the caller with `active:false`. It is a cooperative workflow pause, not a security fence or permission system. It never emits a `PreToolUse` allow/block decision, never completes the host consensus gate, never authorizes execution, and never suppresses unrelated host behavior. Terminal state must carry explicit `false` values for the consensus gate, host verification, and execution handoff rather than omitting them. A later concrete affirmative execution request may produce non-authoritative routing context, but it does not persist a permission, rewrite terminal evidence, or create an automatic handoff; quotations, code, examples, documentation, questions, modal requests, negations, and vague approval remain classifier negatives. `approved+proven` requires complete lifecycle digests plus post-write revalidation. Administrative abandonment is append-only, idempotent for prepared or committed journals, and records a separate byte-bound admin event without rewriting the original closeout journal. Real enforcement requires an explicit host-issued, host-verified receipt or capability on a non-user-mintable surface; local Advisory files, prompts, session/thread fields, tracker records, and HERDR observability cannot substitute for it. On Darwin, each Advisory evidence artifact is limited to 128 KiB by the pinned-directory reader; other supported platforms allow up to 8 MiB.
+
+## Flags
+
+- `--interactive`: Enables user prompts at key decision points (draft review in step 2 and final approval in step 6). Without this flag the workflow runs fully automated — Planner → Architect → Critic loop — and outputs the final plan without asking for confirmation.
+- `--deliberate`: Forces deliberate mode for high-risk work. Adds pre-mortem (3 scenarios) and expanded test planning (unit/integration/e2e/observability). Without this flag, deliberate mode can still auto-enable when the request explicitly signals high risk (auth/security, migrations, destructive changes, production incidents, compliance/PII, public API breakage).
+- `--advisory`: Standalone only. It cannot be combined with Autopilot, Team, Ultragoal, execution flags, or unknown flags. Activation requires canonical session, root thread, and turn identity.
+
+## Ontology-heavy review
+
+For requirements semantics, taxonomy, prompt/spec design, policy distinctions, or category-risk architecture, cite the `architect` role agent's read-only review as advisory evidence. Its findings can inform the plan or follow-up evidence when explicitly used, but `$ralplan` itself records Architect→Critic lifecycle evidence only, and advisory review is never a durable execution authorization.
+
+## Usage with interactive mode
+
+```
+$ralplan --interactive "task description"
+```
+
+## Behavior
+
+## GPT-5.6 Guidance Alignment
+
+Use the shared workflow guidance pattern: outcome-first framing, concise visible updates for multi-step planning, local overrides for the active workflow branch, evidence-backed planning and validation expectations, explicit stop rules, right-sized implementation/PRD shape, and automatic continuation for safe reversible steps. Ask only for material, destructive, credentialed, external-production, or preference-dependent branches.
+
+This skill runs its own consensus runtime; it does not delegate to a nonexistent Plan consensus mode:
+
+```
+adw ralplan run --task <arguments> [--session <id>]
+```
+
+The consensus workflow:
+1. **Planner** creates an adaptive plan (right-sized to task scope; do not default to exactly five steps) and a compact **RALPLAN-DR summary** before review. Current `[main]` vs `[planner]` behavior: standalone `$ralplan` may be authored by the active main planning lane unless the caller/runtime supplies a dedicated planner routing record; inside `$autopilot`, state field `planning_routing.owner:"planner"` means the initial Planner draft/decomposition must use dedicated `[planner]`. Set `.adw-config.json` `agentModels.planner` to opt into a specific planner model and force dedicated planner ownership for complex Autopilot planning even when `[main]` is not cheap/mini. The RALPLAN-DR summary includes:
+   - Principles (3-5)
+   - Decision Drivers (top 3)
+   - Viable Options (>=2) with bounded pros/cons
+   - If only one viable option remains, explicit invalidation rationale for alternatives
+   - Deliberate mode only: pre-mortem (3 scenarios) + expanded test plan (unit/integration/e2e/observability)
+2. **User feedback** *(--interactive only)*: If `--interactive` is set, use the structured question UI (`adw question` in attached tmux; native structured input outside tmux when available) to present the draft plan **plus the Principles / Drivers / Options summary** before review (Proceed to review / Request changes / Skip review). Otherwise, automatically proceed to review.
+**Native role-routing preflight:** Keyword routing may already have selected Ralplan, but it is not authority. Run `adw ralplan preflight --json` only when the native task surface reports `role_routing_unavailable` and this workflow attempts adapted Ralplan Planner, Architect, or Critic authority, adapted role-intent, or adapted consensus authority. On `unsupported_documented_leader_proof`, stop before that adapted authority and use a Codex surface with documented root proof or a reviewed alternative workflow. Do not infer root identity from `session_id`, undocumented `thread_id`, session/pointer/transcript/cwd state, absence of child data, or a prompt label. Ordinary native planning, lifecycle, state, status, health, HUD, runtime, setup, install, sync, and unrelated delegation are outside this preflight boundary and remain governed by existing controls.
+
+**Native role-routing rule:** When the native surface exposes `agent_type` role routing, set `agent_type` to an installed ADW role and never omit it for ADW work. When it does not (`role_routing_unavailable`), do not fabricate `agent_type`. On the exact reviewed Codex releases 0.144.5, 0.145.0, 0.146.1, and 0.148.0-alpha.5, adapted Ralplan Planner, Architect, Critic, role-intent, and consensus authority are unavailable because they lack documented root proof; every other version remains unknown and fails closed. Do not silently weaken routing with a prompt role label or inferred carrier. Use a Codex surface with documented root proof or a reviewed alternative workflow for that authority. A direct `adw ralplan role-intent write` attempt is denied with machine reason `unsupported_documented_leader_proof`.
+
+3. **Architect** reviews for architectural soundness and must provide the strongest steelman antithesis, at least one real tradeoff tension, and (when possible) synthesis — **await completion before step 4**. Launch this as a subsequent role-specific `Architect` subagent and pass the full task statement, context snapshot, PRD/test-spec paths, and relevant prior findings; do not substitute an unvalidated reviewer identity or a short improvised reviewer prompt. In deliberate mode, Architect should explicitly flag principle violations.
+4. **Critic** evaluates against quality criteria — run only after step 3 completes. Launch this as a subsequent role-specific `Critic` subagent with the full task statement, context snapshot, PRD/test-spec paths, and the completed Architect review; do not ask the Architect subagent to perform the Critic gate and do not substitute an unvalidated reviewer identity or a short improvised reviewer prompt. Critic must enforce principle-option consistency, fair alternatives, risk mitigation clarity, testable acceptance criteria, and concrete verification steps. In deliberate mode, Critic must reject missing/weak pre-mortem or expanded test plan.
+5. **Re-review loop** (max 5 iterations): Any non-`APPROVE` Critic verdict (`ITERATE` or `REJECT`) MUST run the same full closed loop:
+   a. Collect Architect and Critic feedback
+   b. Revise the plan with Planner
+   c. Return to Architect review
+   d. Return to Critic evaluation
+   e. Repeat this loop until Critic returns `APPROVE` or 5 iterations are reached
+   f. If 5 iterations are reached without `APPROVE`, present the best version to the user
+6. On Critic approval, persist the execution-ready planning artifacts and sequential Architect→Critic evidence. In standalone interactive Ralplan, present the requested future execution lane. Inside Autopilot, the existing explicit `$autopilot` invocation authorizes the supervised transition to its defining next stage, `$ultragoal`; persist an Autopilot-owned `ralplan_execution_handoff` bound to the same session and review cycle.
+7. Record `ralplan_execution_handoff` with `{authorized: true, reason, authorized_at, session_id, review_cycle, source: "autopilot"|"user"}`. `source:"autopilot"` is valid only for a supervised active Autopilot run whose current phase is `ralplan`; it does not claim host-consensus authority.
+8. Transition to `$ultragoal` after the durable plan, sequential approvals, and bound execution handoff exist. Do not implement directly inside Ralplan.
+
+> **Important:** Steps 3 and 4 MUST run sequentially as role-specific subagents. Do NOT issue both agent calls in the same parallel batch. Always await the subsequent `Architect` result before invoking the subsequent `Critic`; their completed approvals establish local lifecycle evidence only and cannot satisfy the durable execution gate.
+
+## Planning/Execution Boundary
+
+`$ralplan` is a planning mode. While ralplan is active and no explicit execution handoff is active, implementation-focused write tools are out of scope. Ralplan may inspect the repository and may write only planning artifacts such as `.adw/context/`, `.adw/plans/`, `.adw/specs/`, and required `.adw/state/` records.
+
+The canonical flow is:
+
+```
+$ralplan -> local Architect→Critic lifecycle evidence -> bound execution handoff -> $ultragoal
+```
+
+Before any execution lane begins, ralplan must emit terminal planning state (complete, paused, failed, or waiting for input) and the durable handoff record below. Do not continue from consensus planning into direct code edits in the same ralplan session.
+
+## Durable Consensus Handoff Contract
+
+Ralplan is not complete, skippable, or ready for execution merely because `.adw/plans/prd-*.md` and `.adw/plans/test-spec-*.md` exist. Those files are planning artifacts, not consensus evidence.
+
+Before any Autopilot, Ultragoal, Team, or implementation handoff, persist a durable handoff record that distinguishes:
+
+- `planning_artifacts`: PRD/test-spec paths.
+- `ralplan_architect_review`: the completed Architect review with an approving verdict.
+- `ralplan_critic_review`: the completed Critic review with an approving verdict, recorded only after the Architect review.
+- `ralplan_execution_handoff`: persist `{authorized: true, reason: "<rationale>", authorized_at: "<ISO timestamp>", session_id: "<current session>", review_cycle: <matching lifecycle cycle>, source: "autopilot"|"user"}`. Autopilot may issue this only for its own supervised `ralplan` phase; standalone Ralplan uses `source:"user"`.
+- `ralplan_consensus_gate.complete` records lifecycle completion after the sequential Architect and Critic approvals. It is not a host-security claim. Locally authored JSON/env/prompt/tracker/transcript/receipt-shaped evidence must never be described as host-issued authority.
+
+If Architect is missing/blocked, keep the workflow in Architect review or report that blocker. If Critic is missing/blocked/non-approving, keep the workflow in Critic/re-review or report the max-iteration outcome. After both reviews approve, execution begins only when the matching `ralplan_execution_handoff` is durable. Existing plan/test-spec files alone are never permission to skip Ralplan or execute.
+
+Follow the Plan skill's full documentation for consensus mode details.
+
+## Goal-Mode Follow-up Suggestions
+
+When a bound `ralplan_execution_handoff` permits execution, include product-facing goal-mode suggestions alongside coordinated Team execution. Record the requested lane and persist the handoff without claiming host-issued authority.
+
+- `$ultragoal` — **default goal-mode follow-up** for implementation or general goal-oriented follow-up plans that should become durable Codex/ADW goals with sequential completion tracking.
+- `$autoresearch` — research-project follow-up when the plan centers on a question, literature/reference gathering, evaluator-backed research, or a professor/critic-style research deliverable.
+- `$performance-goal` — optimization/performance follow-up when the plan centers on speed, latency, throughput, memory, benchmark, or other measurable performance work.
+
+Use `$ultragoal` for durable goal tracking and `$team` for coordinated parallel implementation. When combined, Ultragoal owns the ledger and Team returns checkpoint-ready execution evidence.
+Use the available-agent-types roster to produce explicit role/staffing allocation, reasoning-by-lane guidance, concrete launch hints (including `adw team` when parallel delivery is justified), and team verification responsibilities for any future receipt-authorized execution path.
+
+## Pre-context Intake
+
+Before consensus planning or execution handoff, ensure a grounded context snapshot exists:
+
+1. Derive a task slug from the request.
+2. Reuse the latest relevant snapshot in `.adw/context/{slug}-*.md` when available.
+3. If none exists, create `.adw/context/{slug}-{timestamp}.md` (UTC `YYYYMMDDTHHMMSSZ`) with:
+   - task statement
+   - desired outcome
+   - known facts/evidence
+   - constraints
+   - unknowns/open questions
+   - likely codebase touchpoints
+4. If ambiguity remains high, gather brownfield facts first. `adw explore` is deprecated; use normal repository inspection tools/subagents for simple read-only repository lookups and `adw sparkshell` only for explicit shell-native read-only evidence. Then run `$deep-interview --quick <task>` before continuing.
+5. If the plan depends on official docs, version-aware framework guidance, best practices, or external dependency behavior, use `$best-practice-research` as the bounded evidence wrapper and auto-delegate `researcher` for the official/upstream lookup before finalizing the planning handoff so execution does not start from repo-local recall alone.
+6. If a prior `$autoresearch` run exists, treat its approved artifact as evidence for the plan. Do not include Autoresearch as a final architecture or runtime component unless the user explicitly requested ongoing research automation; otherwise synthesize the evidence into the `$ralplan` ADR, risks, and verification steps.
+
+Do not hand off to execution modes until this intake is complete; if urgency forces progress, explicitly document the risk tradeoffs.
+
+## Routing boundary
+
+Ordinary scoped tasks stay in the direct execution lane described by `templates/AGENTS.md`.
+Explicit workflow requests follow the keyword registry (`src/hooks/keyword-registry.ts`) and their owning skill contracts; this card does not define a second activation table.
+Once Ralplan is active, preserve the planning/execution and consensus handoff requirements above. A conversational “just do it” is not a substitute for the required review evidence.
+
+## Scenario Examples
+
+**Good:** The user says `continue` after the workflow already has a clear next step. Continue the current branch of work instead of restarting or re-asking the same question.
+
+**Good:** The user changes only the output shape or downstream delivery step (for example `make a PR`). Preserve earlier non-conflicting workflow constraints and apply the update locally.
+
+**Bad:** The user says `continue`, and the workflow restarts discovery or stops before the missing verification/evidence is gathered.