From f09791e0496eac5e32c9c4c1d617eaf1e89df180 Mon Sep 17 00:00:00 2001 From: Jason Walker <913443@dadeschools.net> Date: Thu, 2 Jul 2026 18:17:03 -0400 Subject: [PATCH] docs: require Controller Handoff Summary + codify LLM workflow rules (#101) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - SKILL.md: new §K Controller Handoff Summary (required every task type) with the exact format and a worked blocked-handoff example; issue-first rule extended (discussion/RFC issues, unclear-tracker-home stop rule, no new repo/tracker without owner approval); merge workflow now names identity+author verification, profile gates, independent validation, and pinned head SHA / expected changed-file merges; tagging rules extended (no tag ops unless instructed, tag only the verified final master merge commit, always report tag target). - llm-workflow-runbooks.md: Controller Handoff Summary section pointing at SKILL §K, incl. discussion/RFC rule (e.g. #100 stays a discussion issue). - templates/start-issue.md + review-pr.md: handoff lines now reference the required summary format and the exact-gate reporting rule. Docs only; no code behavior changed. No tags touched; #100 not modified. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/llm-workflow-runbooks.md | 23 +++ skills/llm-project-workflow/SKILL.md | 155 +++++++++++++++++- .../templates/review-pr.md | 4 +- .../templates/start-issue.md | 4 +- 4 files changed, 182 insertions(+), 4 deletions(-) diff --git a/docs/llm-workflow-runbooks.md b/docs/llm-workflow-runbooks.md index 4542a90..868f6c0 100644 --- a/docs/llm-workflow-runbooks.md +++ b/docs/llm-workflow-runbooks.md @@ -337,6 +337,29 @@ touching anything. files, detected secret, or any production/deploy behavior — **stop, report the blocker, and take no mutating action.** Fail closed; never work around a gate. +## Controller Handoff Summary (required, every task) + +Every task — implementation, review, merge, triage, documentation, +discussion-only, or blocked planning — **must end with a +`Controller Handoff Summary`** so a controller LLM can pick up the state +without rereading the conversation. The canonical format and rules live in the +portable skill: +[`../skills/llm-project-workflow/SKILL.md`](../skills/llm-project-workflow/SKILL.md) §K. + +Sections (in order): Work performed · Current state (repo, branch/master +commit, issue #s, PR #s, complete/blocked/ready-for-review/discussion-only) · +Files changed · Validation · Issues encountered · Review needed? (one of the +five fixed answers) · Next recommended action · Safety confirmations +(no self-review; no self-merge; no release/tag changes unless requested; no +secrets; no production access unless authorized). + +Hard rules: never omit it; never bury blockers earlier only; an opened PR +means "Review needed — PR is open"; a blocked merge names the exact gate; +discussion-only comments need owner/design feedback, not code review; any +touched release state names the exact tag/commit and why. Design debates +belong in **discussion/RFC issues** (e.g. #100 `profiles.json v2`) — comment +on the issue, create no branches/PRs, and end the comment with this summary. + ## Fail-closed behavior Before any mutating action the workflow verifies identity, active profile, diff --git a/skills/llm-project-workflow/SKILL.md b/skills/llm-project-workflow/SKILL.md index 3d4fd70..2cd53a4 100644 --- a/skills/llm-project-workflow/SKILL.md +++ b/skills/llm-project-workflow/SKILL.md @@ -41,6 +41,18 @@ editing, deleting, or `chmod`-ing files; docs; scripts; commits; pushes; and PRs Reading the repo, running read-only status/`git log`, and creating/claiming the issue itself are allowed from the orchestration checkout without a prior issue. +Additional issue-first rules: + +- Do not implement code without an issue unless explicitly authorized. +- **Design-only work uses a discussion/RFC issue** — create one or comment on + the existing one. Design debates belong on the issue, where other LLMs + comment directly. Discussion-only tasks must **not** create branches or PRs; + their comments should include recommendations, risks, open questions, and a + Controller Handoff Summary (§K). +- **If the repo/tracker home for the work is unclear, stop and ask for an + owner decision.** Do not create a new repository or a new tracker unless + explicitly approved by the owner. + ## B. Isolated worktree rule **Never implement or review in the main checkout.** The main checkout is for @@ -162,7 +174,12 @@ Worktree folder = branch with `/` replaced by `-` ## G. Merge / cleanup workflow -Only an eligible (non-author) reviewer merges. After a real merge: +Only an eligible (non-author) reviewer merges. Before merging: always verify +the authenticated identity **and** the PR author; respect runtime profile +gates; run independent validation (do not trust the author's reported +results); and merge with a **pinned head SHA** and, where supported, the +**expected changed-file set**, so a moved head or widened diff refuses the +merge. After a real merge: 1. Confirm remote `master` actually contains the merge commit (A PR is not done just because `master` moved. A PR is done only when: Gitea reports the PR merged or reconciliation documents equivalent content on `master`; remote `master` contains the expected content; linked issues are closed; `status:in-progress` is removed). 2. Close/release the issue. @@ -230,6 +247,132 @@ Ready-to-copy templates live in [`templates/`](templates/): - [`worktree-cleanup.md`](templates/worktree-cleanup.md) — clean up after merge. - [`release-tag.md`](templates/release-tag.md) — create a release tag. +## K. Controller Handoff Summary (required, every task) + +Every LLM task **must end with a `Controller Handoff Summary`** — whether the +task was implementation, review, merge, issue triage, documentation, +discussion-only, or blocked planning. It lets a controller LLM understand the +current state immediately, without rereading the conversation. + +Rules: + +- Never omit the summary. +- Never bury blockers in earlier text only — they must appear here. +- If you opened a PR, state clearly that review is needed. +- If you reviewed but could not merge, name the exact gate that blocked it. +- If you only commented on a discussion issue, say no code review is needed + but owner/design feedback may be needed. +- If release state was touched, state exactly which tag/commit changed and why. +- If blocked (permissions, missing repo, missing second reviewer identity, + stale dependency, unclear tracker home): stop and report clearly; **never + bypass classifiers, profile gates, missing permissions, or live-consent + requirements**; give the owner concrete options. + +Required format: + +```md +## Controller Handoff Summary + +### Work performed + +Briefly state what was done. + +### Current state + +Include: +- current repo +- current branch or master commit +- issue number(s) +- PR number(s), if any +- whether work is complete, blocked, ready for review, or discussion-only + +### Files changed + +List files changed, or say `None`. + +### Validation + +List commands run and results, or say `Not applicable — discussion only`. + +### Issues encountered + +List errors, confusing state, permission/profile problems, stale branches, +failing tests, missing labels, or blocked decisions. + +### Review needed? + +Say one of: +- `No review needed — discussion/comment only` +- `Review needed — PR is open` +- `Independent non-author review needed` +- `Owner decision needed` +- `Blocked` + +### Next recommended action + +State exactly what should happen next. + +### Safety confirmations + +Confirm: +- no self-review +- no self-merge +- no release/tag changes unless explicitly requested +- no secrets committed +- no production access used unless explicitly authorized +``` + +### Example blocked handoff + +```md +## Example blocked handoff + +### Work performed + +Audited phase-2 MCP Control Plane planning. Found target repo +`mcp-control-plane` does not exist. Prepared issue pack but did not file it. + +### Current state + +- Repo: `Scaled-Tech-Consulting/Gitea-Tools`, unmodified +- Target repo: `mcp-control-plane`, missing +- Issues: none open in Gitea-Tools +- PRs: none open +- Status: blocked pending owner decision + +### Files changed + +None. + +### Validation + +Tracker/repo audit only. No code validation required. + +### Issues encountered + +Repo creation was denied by permission/classifier because it would be scope +escalation without live consent. + +### Review needed? + +Owner decision needed. + +### Next recommended action + +Owner must choose: +1. create `Scaled-Tech-Consulting/mcp-control-plane` +2. authorize repo creation while present +3. file phase-2 issues in Gitea-Tools instead + +### Safety confirmations + +- no self-review +- no self-merge +- no release/tag changes +- no secrets committed +- no production access used +``` + ## Adapting to a project Replace these project-specific names when copying the skill elsewhere: @@ -242,7 +385,7 @@ Replace these project-specific names when copying the skill elsewhere: | `branches/` | Ignored worktree directory | `branches/` | | helper scripts | Worktree helpers | `scripts/worktree-start` / `-review` / `-clean` | -The rules in §A–§I are project-agnostic and should not change. +The rules in §A–§K are project-agnostic and should not change. ## Versioning And Tagging @@ -263,6 +406,14 @@ Tags must: **Never tag** feature branches, dirty worktrees, unreviewed or self-authored work, or commits not present on remote `master`. +Additional tag rules: + +- Do **not** create, move, delete, or push tags unless explicitly instructed. +- Tag only **after** the intended PR is merged, and tag only the **verified + final master merge commit** (never the PR branch head unless the merge + commit is exactly that commit). +- Always **report the tag target commit** in the final report / handoff. + Release process (see [`templates/release-tag.md`](templates/release-tag.md)): 1. `git fetch --prune`. diff --git a/skills/llm-project-workflow/templates/review-pr.md b/skills/llm-project-workflow/templates/review-pr.md index 49a8f3e..afd44d1 100644 --- a/skills/llm-project-workflow/templates/review-pr.md +++ b/skills/llm-project-workflow/templates/review-pr.md @@ -32,5 +32,7 @@ Steps: - MCP-Profile: - Eligibility: passed/failed -Handoff: reviewer identity, PR author, scope verdict, checks + results, decision. +Handoff: reviewer identity, PR author, scope verdict, checks + results, decision — +formatted as the Controller Handoff Summary (SKILL.md §K); if you could not +merge, name the exact gate that blocked it. ``` diff --git a/skills/llm-project-workflow/templates/start-issue.md b/skills/llm-project-workflow/templates/start-issue.md index 1bbdb6c..aec81e5 100644 --- a/skills/llm-project-workflow/templates/start-issue.md +++ b/skills/llm-project-workflow/templates/start-issue.md @@ -36,5 +36,7 @@ Steps: - Self-review allowed: no 8. Stop before review/merge — you are the author. -Handoff: issue #, branch, worktree path, files changed, checks + results, PR URL. +Handoff: issue #, branch, worktree path, files changed, checks + results, PR URL — +formatted as the Controller Handoff Summary (SKILL.md §K); end with +"Review needed — PR is open". ``` -- 2.43.7