From 1cf20d191275bfe5c046ea6d1757ab590c5e86a8 Mon Sep 17 00:00:00 2001 From: Dayowe Date: Wed, 10 Jun 2026 20:42:02 +0200 Subject: [PATCH] Clarify orchestration handoff commit policy; require durable saved orchestrator prompts --- .../skills/orchestrator/SKILL.md | 37 ++++++++++++++--- .../skills/planner/SKILL.md | 41 ++++++++++++++++++- 2 files changed, 72 insertions(+), 6 deletions(-) diff --git a/plugins/staged-implementation/skills/orchestrator/SKILL.md b/plugins/staged-implementation/skills/orchestrator/SKILL.md index 0eb4a6b..8bfdcaf 100644 --- a/plugins/staged-implementation/skills/orchestrator/SKILL.md +++ b/plugins/staged-implementation/skills/orchestrator/SKILL.md @@ -26,10 +26,11 @@ Prefer a task packet containing: - readiness audit path or permission to create/update one beside the plan/checklist - prompt output directory or naming convention - validation expectations -- whether commits are authorized +- commit policy: `authorized-for-accepted-chunks`, `ask-before-each-commit`, or `do-not-commit` - stopping conditions If any required path, contract, data source, validation target, or output location is unclear, stop and ask. Do not guess. +If commit policy is missing or not one of the supported values, stop and ask. Do not silently choose a safer or more aggressive default. ## Authority Boundaries @@ -37,7 +38,7 @@ If any required path, contract, data source, validation target, or output locati - Implementer sub-agents own one scoped implementation pass at a time. - Implementer sub-agents must not commit. - Validator sub-agents or validator passes gather evidence only; they do not decide final acceptance. -- Commit only when the user explicitly authorizes committing accepted chunks. +- Commit only according to the explicit commit policy. - Do not push, reset, discard, or revert unrelated changes unless explicitly asked. - Stop on contract ambiguity instead of pushing an implementer to guess. @@ -94,7 +95,7 @@ For each authorized ready chunk: 8. Accept the chunk. - Confirm required validation passed or that the user accepted the validation gap. - Confirm no out-of-scope work remains. - - Commit only if the user authorized commits. + - Apply the explicit commit policy. - Use the chunk's proposed commit message when acceptable; otherwise write a one-line commit message with the chunk ID prefix when one exists. 9. Continue. @@ -226,7 +227,30 @@ If there are no findings, state an acceptable verdict clearly before summaries. ## Commit Rules -Commit accepted chunks only when the user has explicitly authorized commits for the run. +Commit behavior is controlled only by the explicit commit policy. Supported policies are: + +- `authorized-for-accepted-chunks` +- `ask-before-each-commit` +- `do-not-commit` + +If the commit policy is missing, stop and ask before starting implementation. Do not infer commit behavior from general intent. + +For `authorized-for-accepted-chunks`: + +- commit after each accepted chunk once review and required validation pass +- never commit unrelated dirty changes +- use one-line commit messages with the chunk ID prefix when one exists + +For `ask-before-each-commit`: + +- stop after each accepted chunk +- report the proposed one-line commit message +- ask the user before committing + +For `do-not-commit`: + +- do not commit +- report the proposed one-line commit message for each accepted chunk Before committing: @@ -244,12 +268,15 @@ Do not commit if: - a contract ambiguity is unresolved - required validation failed or could not run - unrelated dirty changes cannot be separated safely -- the user did not authorize commits +- the commit policy is `do-not-commit` +- the commit policy is `ask-before-each-commit` and the user has not approved that specific commit +- the commit policy is missing or unsupported ## Stopping Conditions Stop and report clearly when: +- commit policy is missing or unsupported - a contract, symbol, endpoint, data source, or output path is ambiguous - the plan/checklist/prompt map disagree and the correct contract cannot be inferred from written docs - the readiness audit has unresolved `blocked-by-contract-decision` items and the user has not authorized a ready-subset run diff --git a/plugins/staged-implementation/skills/planner/SKILL.md b/plugins/staged-implementation/skills/planner/SKILL.md index f3a80f8..4ab3bb5 100644 --- a/plugins/staged-implementation/skills/planner/SKILL.md +++ b/plugins/staged-implementation/skills/planner/SKILL.md @@ -1,6 +1,6 @@ --- name: planner -description: Staged implementation planner/reviewer workflow for any codebase. Use when Codex should prepare or update a plan/checklist/prompt map, run a readiness or ambiguity audit, choose the next implementation chunk, write an implementer prompt, review staged or supplied diffs against frozen docs, clarify contracts, control scope, or define the next handoff. Do not use for direct implementation unless the user explicitly asks the planner to implement. +description: Staged implementation planner/reviewer workflow for any codebase. Use when Codex should prepare or update a plan/checklist/prompt map, run a readiness or ambiguity audit, choose the next implementation chunk, write an implementer or orchestrator handoff prompt, review staged or supplied diffs against frozen docs, clarify contracts, control scope, or define the next handoff. Do not use for direct implementation unless the user explicitly asks the planner to implement. --- # Planner @@ -38,6 +38,7 @@ For planner/reviewer tasks, prefer a task packet containing: - current ground truth, such as plan, checklist, prompt map, recent review notes, or git verification notes - requested action: write next implementer prompt, review staged diff, clarify docs, update prompt map, prepare checklist, or similar - output path, when saving an official artifact is requested or expected +- commit policy, when writing an orchestrator handoff prompt If a path, contract, data source, diff target, or output location is required and cannot be discovered safely, stop and ask for the exact missing information. Do not guess. @@ -237,6 +238,44 @@ End implementer prompts by asking for a proposed commit message. When a chunk ID When the user asks the planner for a commit message, output a one-line commit message. If multiple sentence-like clauses are needed, separate them with semicolons. +## Orchestrator Handoff Prompts + +When asked to write, produce, or prepare an orchestrator prompt, treat it as an official durable handoff artifact, not casual chat output. + +Save official orchestration handoff prompts beside the plan/checklist/prompt map unless the user explicitly asks for chat-only output or gives another path. If no output path is clear, ask for the output path before presenting chat-only. Re-read the saved file before finishing. + +Every orchestrator prompt must include: + +- repo root +- feature/fix name or slug +- plan path +- implementation checklist path +- prompt map path +- readiness audit path or permission to create/update one beside the plan/checklist +- prompt output directory or naming convention +- validation expectations +- commit policy +- stopping conditions + +The commit policy must be explicit and must use one of: + +- `authorized-for-accepted-chunks` +- `ask-before-each-commit` +- `do-not-commit` + +If the user has not specified commit behavior and no project/workflow default exists, stop and ask before saving the prompt. Do not silently choose `do-not-commit`, `ask-before-each-commit`, or `authorized-for-accepted-chunks`. + +If the user says to orchestrate implementation and their stated workflow preference says the orchestrator should commit accepted chunks, use `authorized-for-accepted-chunks` and include this exact policy text: + +```text +Commit policy: +Commits are authorized for accepted chunks only. Commit after each accepted chunk once review and required validation pass. Do not commit unrelated dirty changes. Use one-line commit messages with the chunk ID prefix when one exists. +``` + +For `ask-before-each-commit`, require the orchestrator to stop after each accepted chunk and ask before committing. + +For `do-not-commit`, require the orchestrator to avoid commits and report the proposed one-line commit message for each accepted chunk. + ## Prompt Output Hygiene Before presenting or saving a prompt: