diff --git a/skills/meta/agent-workflow-protocol/references/handoff.md b/skills/meta/agent-workflow-protocol/references/handoff.md index 8d2f88a..0cb8dbb 100644 --- a/skills/meta/agent-workflow-protocol/references/handoff.md +++ b/skills/meta/agent-workflow-protocol/references/handoff.md @@ -5,6 +5,7 @@ Elsewhere a handoff is often a document that compacts a conversation for another - Write for a fresh agent with none of your context. Reference artifacts (PR, issue, commit, check run) by link instead of copying them, and redact secrets and personal data. - Open with one sentence that says where things stand, then the sections. Keep it short enough to skim: a long handoff hides the one line a human needs. - Compose it in a file in the OS temp directory, then post it with `gh pr comment N --body-file FILE`. **Never write it into the repository.** +- **Record the runner.** Every comment an agent leaves (outcome, handoff, triage notes, escalation, failure note) must include the runner name near the top of the body, for example `**Runner:** grok` or `Runner: $runner`. Use the `runner` input (default `unknown`). Without it, debugging which automation produced the comment is guesswork. - End the comment with the marker the step requires. The marker is the last line: - `` - `` @@ -15,11 +16,11 @@ Elsewhere a handoff is often a document that compacts a conversation for another | Author | Comment | Required content | |---|---|---| -| Shepherding | the "ready" handoff on a PR | **Changes** made, **Decisions** taken and why, **Risks**, **Verification** actually run (commands and results, and a link to the green check run), **Reviewer focus** (where to look hardest), **Not done** (anything the issue asked for that this PR leaves out, and why) | -| Reviewing, not merged | the "review" handoff on a PR | **Verdict**, **Findings**: each with what is wrong, why, and whether it is fixed (with the commit) or still open; **What remains**; **Verification** you ran; **Round** (`review_rounds N` of `max_review_rounds`) | -| Reviewing, merged | the "merged" note on a PR, posted right after the merge | **Verdict** from `merge-safety` (compatibility, reversibility, GitHub readiness) and the outcome of `code-review`; **Verification** you ran; the merge commit and `merge_method`. It keeps the reason for an unattended merge with the PR | -| Any step that escalates | the escalation comment | see `escalate.md` | +| Shepherding | the "ready" handoff on a PR | **Runner**, **Changes** made, **Decisions** taken and why, **Risks**, **Verification** actually run (commands and results, and a link to the green check run), **Reviewer focus** (where to look hardest), **Not done** (anything the issue asked for that this PR leaves out, and why) | +| Reviewing, not merged | the "review" handoff on a PR | **Runner**, **Verdict**, **Findings**: each with what is wrong, why, and whether it is fixed (with the commit) or still open; **What remains**; **Verification** you ran; **Round** (`review_rounds N` of `max_review_rounds`) | +| Reviewing, merged | the "merged" note on a PR, posted right after the merge | **Runner**, **Verdict** from `merge-safety` (compatibility, reversibility, GitHub readiness) and the outcome of `code-review`; **Verification** you ran; the merge commit and `merge_method`. It keeps the reason for an unattended merge with the PR | +| Any step that escalates | the escalation comment | see `escalate.md` (include **Runner**) | ## Issues -For an issue, the comment `unattended-triage` writes is the handoff: an **Agent Brief** for `ready-for-agent`, the same structure plus why it cannot be delegated for `ready-for-human`, or **Triage Notes** for `needs-info`. A conversation summary on top would only duplicate it. +For an issue, the comment `unattended-triage` writes is the handoff: an **Agent Brief** for `ready-for-agent`, the same structure plus why it cannot be delegated for `ready-for-human`, or **Triage Notes** for `needs-info`. A conversation summary on top would only duplicate it. Every such comment must still include `**Runner:** $runner`. diff --git a/skills/meta/agent-workflow-protocol/references/log.md b/skills/meta/agent-workflow-protocol/references/log.md index 56b54db..fb9b2d4 100644 --- a/skills/meta/agent-workflow-protocol/references/log.md +++ b/skills/meta/agent-workflow-protocol/references/log.md @@ -51,7 +51,7 @@ problems_count: 1 |---|---|---| | `step` | yes | Exploring, Triaging, Implementing, Shepherding, Reviewing | | `run` | yes | `RUN_ID` | -| `runner` | yes | Runner name | +| `runner` | yes | Runner name (from the `runner` input; default `unknown`). Required so log and issue comments can be attributed | | `at` | yes | When the entry was written, UTC ISO-8601 (`log_run` adds it if missing) | | `outcome` | yes | Short summary string (same facts as **Outcome:**) | | `problems_count` | yes | Number of tagged problem lines (0 if none) | @@ -79,6 +79,7 @@ Rules: - **One entry per run and step.** `log_run` skips an entry whose `run` and `step` are already on the log issue, so a retry is safe. A runner with no shell checks the issue's comments (`hasLogEntry`) first. - Write real line breaks, never the two characters backslash and `n`. `log_run` repairs an entry written that way, but do not rely on it. - Write the entry to a temp file, then run `log_run FILE` (shell) or post the same body with GitHub tools (no-shell). Use `formatLogComment` from `scripts/helpers.mjs` so the header and field order stay identical across runners. +- The prose header line must include `**Runner:**` with the same value as the YAML `runner` key. Agent comments on issues and PRs (outside the log) follow the same rule; see `references/handoff.md`. ## Reading