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

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

@@ -0,0 +1,153 @@
+---
+name: implement-feature
+description: "Run the implementation target for one Feature as its lead - move Approved items to Design Validation, have design.md checked against the repo, run the non-linear item loop: In Implementation, In Testing, In Review, Updating Docs, through sub-agents, run the Feature-final check, raise the one implementation PR to integration, and carry it through CI to the merge. Use when the adl dispatcher starts an implementation session, lead lead for a Feature whose in-scope items are all Approved or later."
+metadata:
+  step: "implementation"
+  role: "lead"
+  states: "Approved, Design Validation, In Implementation, In Testing, In Review, Updating Docs"
+---
+
+# Implement Feature (run skill of the lead)
+
+Load `workitems-process` first. This card is the lead's whole procedure. Sub-agents run their own skills; the briefs you give them are in `references/briefs.md`. Tags: **[pending Fx/Px/Hx]** = an adl-agent-control change that is not built. Never act as if a pending change is live.
+
+## When to use
+
+- The dispatcher started you for one Feature: every in-scope item (not Parked/Removed) is at Approved or later, at least one is not Done, every predecessor Feature is at Awaiting Release or Done.
+- **Per-Bug run.** The dispatcher may instead start you for one Fixes Bug at Approved through Updating Docs, until its PR merges, keyed by the Bug **[pending L5, X2]**, on branch `fix/az<bug id>-<slug>`. A Bug has no plan folder, no Plan Hash and no Design Validation: skip only Preconditions 4-5 and procedure step 1. Preconditions 1-3 apply in their per-Bug form (below). The Bug's ladder and moves are in [Bug states](../workitems-process/references/workitem-states.md#5-bug-states). A Bug at In Reproduction or later is a resumed run: continue from its state (Resume, below). On a fresh run (Bug at Approved) your first board write is Approved → **In Reproduction**. Then spawn `executor` (`implement-item`, reproduce mode, `reproduce` brief in `references/briefs.md`): its first commit is the Bug's item file, written from the G1-approved Bug Description, with its LEDGER row; its next commit is the regression test, proved red on the base and committed marked as an expected failure so the commit stays green, and that brief writes nothing else. Post the executor's unmarked red run on the base as a comment on the Bug, as evidence. Then move In Reproduction → **In Fixing**; the `fix` brief (bug mode) writes the minimal fix until green, in the loop, and its fix commit removes the expected-failure mark. Every commit stays independently green, with no exception. Run the loop and the one PR as usual. You write no file yourself. Won't reproduce: post what you tried as a comment on the Bug and move it to Parked for Removal (G3 is the human's). You resolve everything else in the run ([No block](../workitems-process/SKILL.md#no-block)).
+- One run = one worktree, one branch, one lead session (you), **one implementation PR** to `integration`.
+- Resume is not a separate mode: if the trigger still holds on a later tick you are started again in the **same worktree on the same branch**. Read the board and the branch, continue (Resume, below).
+
+## Inputs
+
+| Field | Meaning |
+|---|---|
+| `feature_id` | The Feature (the run key) |
+| `worktree` | Dispatcher-created checkout on branch `feat/az<id>-<slug>` (or the fitting `<type>/`); per-Bug run: `fix/az<bug id>-<slug>`. Agents never create worktrees |
+| Plan folder | `plans/features/az<id>-<slug>/`: `intent.md`, `requirements.md` (EARS criteria `AC-n`, `## Items`), `design.md`, `file-map-reference.md`, `items/az<id>-<slug>.md` |
+| Feature fields | `BaselineSha`, `PlanHash`, `PlanRevision` **[pending T3: named arguments; reference names not yet confirmed through the API]** |
+
+Identity `agent-tarun`.
+
+## Preconditions
+
+1. `git rev-parse --show-toplevel` equals `worktree`; the branch is the Feature's `<type>/az<id>-<slug>` (per-Bug run: `fix/az<bug id>-<slug>`); `git status --porcelain` is empty, or the dirt is your own previous attempt.
+2. `adl id whoami` reports `agent-tarun`.
+3. Read the Feature's children (`workitem_list_or_get`). Every in-scope item is at Approved or later; if not, the trigger does not hold: report the item and its state on the Feature and end the run. Per-Bug run: read only the Bug; it must be at Approved through Updating Docs with its PR not merged (other Bugs in the Fixes Feature do not matter); if not, report its state on the Bug and end the run.
+4. The plan folder is on the branch (planning PR merged into `integration`): the four plan documents and every `items/az<id>-*.md` exist. If the planning PR is not merged yet, end the run and report it; the next tick re-evaluates.
+5. `sha256` of `requirements.md` equals `PlanHash` (the hash covers `requirements.md` only). On a mismatch, post both hashes as a Feature comment and do not start Design Validation: the approved plan is not the one on the branch. **[pending F7: the tool will refuse the Design Validation move on a mismatch; the field reference name is not yet confirmed through the API.]**
+
+## Procedure
+
+### 1. Design Validation
+
+1. The run starts by merging `origin/integration` into its branch: `git fetch origin`, then `git merge origin/integration` (a fast-forward on a fresh start; never rebase, never force). The worktree `HEAD` then contains the current `integration`, and Design Validation diffs `<BaselineSha>..HEAD`.
+2. Move every Approved item → **Design Validation** (adjacent forward move; the fence allows it). This is your first board write.
+3. Spawn `architect` with the `validate-design` brief. It checks `design.md` and its `file-map-reference.md` by diffing `<BaselineSha>..HEAD`, records `head_sha`, and rules `FRESH`, or `DRIFT` (with the exact delta). `requirements.md` is **not** re-validated: it was validated in planning and approved at G1.
+4. `FRESH`: continue. `DRIFT`: **drift never leaves the run**. Spawn `planner` (skill `plan-feature`, Mode B: design update) with the delta. It updates `design.md`, `file-map-reference.md` (the `## Map` rows the drift moves, and the `## Baseline` section) and the Feature's Baseline Sha to the new `integration` base, adds the LEDGER row `az<id>-design-update`, and commits on the Feature branch; Plan Hash is unchanged. You write no file: record the update in the implementation report and the PR. Then re-validate once. Items never go to New or In Planning.
+5. A delta that would change an approved `AC-n`: `requirements.md` stays frozen. Deliver every other AC, comment the reason on that PBI and move it to Parked for Removal (G3); the next Feature plans the outcome if it is still wanted ([No block](../workitems-process/SKILL.md#no-block)).
+6. Design-update cap: 2 rounds. Past it, post the reason as a Feature comment and change approach ([No block](../workitems-process/SKILL.md#no-block)).
+
+### 2. The item loop (non-linear)
+
+The four states **In Implementation, In Testing, In Review, Updating Docs** are a **non-linear loop**: free moves among them in either direction, per item. **You move the items**; sub-agents move nothing. **[pending F1: until it ships the fence refuses some loop moves (e.g. In Testing → In Implementation). Post the refusal text as an item comment and take the path the refusal names. Never work around it.]**
+
+- **Order is yours.** Pick the item order from `design.md` (shared files, risk first). Default staffing is conservative: one executor at a time on the shared branch. Fan out only items with disjoint file scopes in `file-map-reference.md`, as native sub-agents of this session, never the adl-workflow `team` worker pool. You may also spawn read-only explore sub-agents on the fast tier.
+- The usual order is In Testing before In Review (green code before a reviewer's time). A default, not a rule.
+- **Every commit is on the run's one branch** (the Feature branch, or `fix/az<bug id>-<slug>` in a per-Bug run). No per-item branch, worktree or PR. Commits carry `AB#<item id>`.
+
+Per item, in the order you chose:
+
+| Step | You do | Sub-agent (skill) | Item state |
+|---|---|---|---|
+| Build | Give the item, its `AC-n` list and its design section | `executor` (`implement-item`) | → In Implementation |
+| Test | Give the item, `AC-n`, the head SHA | `verifier` (`verify-item`) | → In Testing |
+| Review | Run both lanes at the head SHA, in parallel, preferably a different model family from the executor (not required) | `code-reviewer` + `architect` (`review-change`) | → In Review |
+| Docs | A docs gap (finding `docs-missing`, or an item with docs still open) goes to an executor, docs only | `executor` (`implement-item`) | → Updating Docs |
+
+- **TDD:** each EARS criterion becomes a failing test first, then minimal code. The executor's report names the red run and the green run per `AC-n`. A report without the red run is not accepted.
+- **A finding goes back, inside the run:** post it as an item comment (`id`, `severity`, `where`, `what`, `fix`), move the item → In Implementation (a Bug: → In Fixing), send the executor **only the listed findings**. Cap: **3 rounds per item**; past it, post the reason as an item comment and change approach ([No block](../workitems-process/SKILL.md#no-block)).
+- **Mid-loop drift** (executor returns `DRIFT`): the item moves In Implementation → **Design Validation** **[pending F1]** ([States at a glance](../workitems-process/SKILL.md#states-at-a-glance)), run step 1.3 to 1.6 for that item, then back to In Implementation.
+- **In Review** = reviewer sub-agents in fresh contexts. No PR reviewer, no votes, no PR threads before the merge ([Human gates](../workitems-process/SKILL.md#human-gates)). Findings go to **item comments and the implementation report**. `REQUEST_CHANGES` or `BLOCK` sends the item back. `WATCH` and medium/low are recorded, not blocking.
+- Sub-agents return a report (format in `references/briefs.md`). **You** post it on the item as a comment and keep it for the implementation report.
+- Push the branch (plain `git push`, never force) after each item's executor reports `DONE` so that heads are durable for resume. Verifiers, reviewers, the validate lane and the writer record `head_sha` at their start and finish against it; compare each report's `head_sha` with the branch head, and re-run the lane at the new head when the head moved ([Evidence and reports](../workitems-process/SKILL.md#evidence-and-reports), the head rule).
+- A later commit voids earlier test and review evidence for what it touches. The Feature-final check is the evidence the merge relies on.
+
+### 3. Feature-final check
+
+When every item has been through Build, Test and Review and the tree is clean and pushed:
+
+1. Record the final head `H`.
+2. Spawn `verifier` in **Feature-final mode** (every `AC-n` of `requirements.md`, the full suite; in a per-Bug run, the Bug item file's `## Expected behaviour` (EARS) plus `## Behaviour that must not change`, base = the `integration` SHA the `fix/` branch was created from) and both review lanes (code, architecture) over `origin/integration...H`.
+3. All pass at `H` → continue. Any finding → fix loop as above (the same 3-round cap, counted per finding), then repeat this step at the new head. Evidence binds to the head it ran at.
+
+### 4. Finalize and raise the PR
+
+1. Spawn `writer` (`finalize-feature`): docs-impact check against `design.md`, then the **PR body** (five sections) and the **implementation report** content. It returns text; it pushes and writes nothing. Finding `docs-missing` → an executor writes it, then repeat 3.
+2. PR body: the five sections in [ado-and-git.md](../workitems-process/references/ado-and-git.md#7-git). Title in commit grammar. Branch `feat/az<id>-<slug>`, or `fix/az<bug id>-<slug>` in a per-Bug run (the `-plan` suffix marks a planning PR and is never used here).
+3. `git push` the branch. `pr_create_or_update` (action create, target `integration`) with the body and the report content. **The tool does the wiring [pending P1/P2/P4]** ([PR wiring](../workitems-process/references/ado-and-git.md#6-pr-wiring)); you pass nothing for it. Until built, report which parts you could not observe.
+4. Read the PR and the items back: items at Updating Docs, PR linked. A mismatch is reported in the Feature comment, never patched by hand-linking or hand-moving to Done.
+
+### 5. CI stage (the last gate)
+
+CI is the gate before the merge (ADR-019). Poll `pr_list_or_get` and `build_list_or_get` for the head, every 60 s, printing status each poll.
+
+| Result | You do |
+|---|---|
+| Green, PR completes | Read the items back; they should be **Done** with the PR link (V2 not yet verified on a real PR). Never set Done yourself. End `MERGED` |
+| Red | Spawn `executor` (`fix-ci`): smallest fix, no skip, no `\|\| true`, no loosened test. Push. Then `verifier` and `code-reviewer` re-check the **delta** at the new head. Append the round to the implementation report (`pr_create_or_update` update). Cap **3** rounds; past it, post the reason as a Feature comment and change approach. Expired check: scoped `build_run` (pending H1). Integration moved: merge `origin/integration` |
+| Cancelled or infrastructure failure with log proof | Re-queue only your own PR's validation on the PR's source branch with `build_run` **[pending H1; refusal = report it, stop]**. A failing test or check is never re-queued to get a lucky green |
+| Merge conflict | Executor merges `origin/integration` into the branch (`git merge`, never a force-push), re-runs checks, then the delta is re-verified and re-reviewed as for red |
+
+## Board moves (yours)
+
+| Move | When | Status |
+|---|---|---|
+| Approved → In Reproduction | Per-Bug run: first act | **pending F9** |
+| In Reproduction → In Fixing | Per-Bug run: the reproduce brief returned `DONE` (the regression test proved red on the base, that run output posted as a Bug comment, and the test committed marked as an expected failure, so the commit is green) | **pending F9** |
+| Bug: In Fixing ↔ In Testing ↔ In Review ↔ Updating Docs | Free moves | **pending F9** |
+| Bug: In Reproduction → Parked for Removal | Won't reproduce, with a comment of what was tried | **pending F9** |
+| Approved → Design Validation | First act, all PBIs (not Bugs) | live |
+| Design Validation → In Implementation | Item's Build starts | live |
+| In Implementation ↔ In Testing ↔ In Review ↔ Updating Docs | Free moves, per item, your call | **pending F1** |
+| In Implementation → Design Validation | Mid-loop drift | **pending F1** |
+| Any → Parked for Removal | Work provably obsolete, or a PBI whose AC drift needs a changed approved AC, with proof | live |
+
+Never move an item to Approved, Done or Removed. Never move a Feature. `pr_create_or_update` moves items to Updating Docs when it raises the PR **[pending P2]**; ADO completion moves them to Done on the merge **[verify V2]**.
+
+## Resume
+
+The trigger holds until the merge, so you may be restarted in the same worktree on the same branch (session died, run ended with the PR open, merge conflict). Do not restart finished work.
+
+1. Read every child's board state and its comments (the earlier sub-agent reports are there) **[pending T1: no comment-read tool yet; without it, work from board states, `git log` and the PR, and re-run any evidence whose head is stale]**.
+2. `git log origin/integration..HEAD` with `AB#` ids shows which items have commits. `pr_list_or_get` shows whether the PR exists.
+3. PR open: go to step 5. No PR: for each item resume from its board state (In Testing means run Test at the current head; In Review means run Review; and so on). Evidence at an older head is stale: re-run. Per-Bug run: a Bug at In Reproduction gets the `reproduce` brief again (it keeps the commits already made); a Bug at In Fixing or later resumes from its state in the loop.
+4. Reuse the branch and the PR. Never recreate either.
+
+## Verdicts
+
+| Verdict | When |
+|---|---|
+| `MERGED` | PR completed into `integration` |
+| `PR_OPEN` | PR raised and CI not finished when the session must end; the next tick resumes at step 5 |
+
+## Stop rules
+
+- One Feature, one PR. Do not start another Feature.
+- Never spin: the same command failing twice for the same reason means stop retrying it and take a different path.
+- Never wait on a person inside the session; only the planned gates G1, G2 and G3 wait on a person.
+- Keep producing output while you wait (a 60 s poll prints status); 20 min of silence gets the session restarted.
+- Sub-agents are leaves. You may spawn them; they spawn nothing.
+
+## Terminal handoff
+
+Post the run-level report as the run's last comment: on the Feature, or on the Bug in a per-Bug run, never on a PBI. Its first line is the `adl-evidence v1` machine line ([Evidence and reports](../workitems-process/SKILL.md#evidence-and-reports)); then per item the final state, the commits, the sub-agent verdicts and head SHAs; design updates; CI rounds; PR link; verdict. Then one line: `implementation <verdict> feature <id> @ <sha>`, or `implementation <verdict> bug <id> @ <sha>` in a per-Bug run. Never end with an offer or a question.
+
+## Never
+
+- Never write code, tests, docs or specs yourself. Never review. Your files are the run branch's push and scratch only; the design-update LEDGER row is the planner sub-agent's.
+- Never force-push. Never `--no-verify`. Never create a worktree or another branch.
+- Never skip, loosen or delete a test; never accept a sub-agent report without its evidence.
+- Never hand-link items to the PR, hand-move items to Done, set a vote or a PR reviewer.
+- Never send an item to New or In Planning for drift.
+- Never edit `requirements.md` or `intent.md`.

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.