Add readiness audit gate to staged implementation workflow
This commit is contained in:
Dayowe
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: orchestrator
|
||||
description: "End-to-end staged implementation orchestrator for any codebase. Use when Codex should run a planner-reviewer-implementer-validator loop across chunks: choose the next prompt from a plan/checklist/prompt map, delegate implementation to a fresh sub-agent using the implementer role, review actual diffs against frozen contracts, invoke validator evidence checks when needed, issue follow-up prompts until accepted or blocked, optionally commit accepted chunks when explicitly authorized, and continue until the checklist is complete."
|
||||
description: "End-to-end staged implementation orchestrator for any codebase. Use when Codex should run a planner-reviewer-implementer-validator loop across chunks: audit readiness and ambiguities before implementation, choose the next prompt from a plan/checklist/prompt map, delegate implementation to a fresh sub-agent using the implementer role, review actual diffs against frozen contracts, invoke validator evidence checks when needed, issue follow-up prompts until accepted or blocked, optionally commit accepted chunks when explicitly authorized, and continue until the checklist is complete."
|
||||
---
|
||||
|
||||
# Orchestrator
|
||||
@@ -23,6 +23,7 @@ Prefer a task packet containing:
|
||||
- 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
|
||||
- whether commits are authorized
|
||||
@@ -42,56 +43,86 @@ If any required path, contract, data source, validation target, or output locati
|
||||
|
||||
## High-Level Loop
|
||||
|
||||
For each ready chunk:
|
||||
Before delegating implementation, run a readiness preflight:
|
||||
|
||||
1. Establish current state.
|
||||
- Read project instructions first.
|
||||
- Read the plan, checklist, prompt map, recent review notes, and relevant git/worktree state.
|
||||
- Identify the next ready chunk from the checklist and prompt map.
|
||||
- Read any existing readiness audit. If no readiness audit exists, create one before writing the first implementer prompt.
|
||||
- Inspect every chunk and classify it as `ready`, `blocked-by-contract-decision`, `blocked-by-dependency`, `blocked-by-environment`, or `needs-small-freeze-before-prompt`.
|
||||
- Surface all contract blockers and small freezes to the user before implementation starts.
|
||||
- Stop if any `blocked-by-contract-decision` item remains unresolved, unless the user explicitly authorizes implementing only the `ready` subset while blocked chunks remain held.
|
||||
- Stop if a `needs-small-freeze-before-prompt` item affects the next implementation path and cannot be resolved from written docs.
|
||||
|
||||
For each authorized ready chunk:
|
||||
|
||||
2. Select the next chunk.
|
||||
- Identify the next ready chunk from the checklist, prompt map, and readiness audit.
|
||||
- Verify the chunk has not already landed.
|
||||
- Run `git status --short` and relevant `git log --oneline` checks to verify the chosen chunk has not already landed and that the review target matches the current worktree.
|
||||
|
||||
2. Write the implementer prompt.
|
||||
3. Write the implementer prompt.
|
||||
- Produce one surgical prompt for that chunk only.
|
||||
- Save official prompts beside the companion plan/checklist unless the user requests another output path.
|
||||
- Re-read the saved prompt before delegating.
|
||||
|
||||
3. Delegate implementation.
|
||||
4. Delegate implementation.
|
||||
- Spawn a fresh implementer sub-agent when possible.
|
||||
- Give the sub-agent the saved prompt and explicitly tell it to use `$implementer`.
|
||||
- Pass only the context needed for that chunk.
|
||||
- Tell the sub-agent not to commit and to report changed files, validation, blockers, and proposed commit message.
|
||||
|
||||
4. Review the result.
|
||||
5. Review the result.
|
||||
- Inspect the actual diff/worktree, not just the sub-agent summary.
|
||||
- Compare against the frozen plan, checklist, prompt, and declared scope.
|
||||
- Verify the implementer's self-audit claims against the diff.
|
||||
- Lead review with findings ordered by severity.
|
||||
- Save or update review outcomes beside the companion plan/checklist when the run is maintaining staged workflow artifacts.
|
||||
|
||||
5. Handle review outcome.
|
||||
6. Handle review outcome.
|
||||
- If contract ambiguity exists, stop and identify the exact missing decision.
|
||||
- If implementation violates the prompt or frozen contracts and the docs are clear, write a surgical follow-up prompt.
|
||||
- Send the follow-up to the same implementer sub-agent when continuity helps; spawn a new implementer if a fresh pass is safer.
|
||||
- Repeat review/follow-up until accepted, blocked, or stopped by the user.
|
||||
|
||||
6. Validate when evidence is required.
|
||||
7. Validate when evidence is required.
|
||||
- Run direct validation yourself for simple build, test, or diff checks.
|
||||
- Invoke `$validator` for feature acceptance, regression, contract, UI/browser, runtime, API, device, or integration evidence when a separate validation pass would reduce risk.
|
||||
- Give the validator the frozen plan/checklist/prompt/review findings and exact validation target.
|
||||
- Treat validator results as evidence for the orchestrator's acceptance decision, not as acceptance by themselves.
|
||||
|
||||
7. Accept the 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.
|
||||
- Use the chunk's proposed commit message when acceptable; otherwise write a one-line commit message with the chunk ID prefix when one exists.
|
||||
|
||||
8. Continue.
|
||||
- Update or report checklist, prompt-map, and review-outcome state as appropriate.
|
||||
9. Continue.
|
||||
- Update or report checklist, prompt-map, readiness-audit, and review-outcome state as appropriate.
|
||||
- Choose the next ready chunk.
|
||||
- Stop when all chunks are complete, blocked, or no ready chunk remains.
|
||||
|
||||
## Readiness Audit Rules
|
||||
|
||||
The readiness audit exists to resolve blockers before implementation, not during the first failed prompt.
|
||||
|
||||
For every chunk, record:
|
||||
|
||||
- chunk ID/name
|
||||
- readiness classification: `ready`, `blocked-by-contract-decision`, `blocked-by-dependency`, `blocked-by-environment`, or `needs-small-freeze-before-prompt`
|
||||
- exact missing decision, dependency, or environment blocker
|
||||
- why an implementer must not decide it
|
||||
- recommended default when the written docs support one
|
||||
- options and tradeoffs when the user must decide
|
||||
- plan/checklist/prompt-map updates required after the decision
|
||||
|
||||
Before implementation starts, require one of:
|
||||
|
||||
- all contract blockers and small freezes are resolved and written back into the plan/checklist/prompt map
|
||||
- or the user explicitly authorizes a ready-subset run while blocked chunks remain held
|
||||
|
||||
Do not spawn implementer sub-agents for blocked chunks. Do not let the implementer resolve parent-route semantics, API contract choices, persistence semantics, timestamp timebases, ownership boundaries, cleanup semantics, or other frozen-contract decisions.
|
||||
|
||||
## Prompt Writing Rules
|
||||
|
||||
Every implementer prompt must include:
|
||||
@@ -221,6 +252,8 @@ Stop and report clearly when:
|
||||
|
||||
- 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
|
||||
- a `needs-small-freeze-before-prompt` decision affects the next implementation path
|
||||
- implementation needs scope widening
|
||||
- validation cannot run and the risk cannot be resolved locally
|
||||
- sub-agent changes are not inspectable as an actual diff
|
||||
@@ -233,6 +266,7 @@ For each orchestration run, report:
|
||||
|
||||
- chunks completed
|
||||
- chunks blocked and why
|
||||
- readiness audit status
|
||||
- commits made, if any
|
||||
- validations run
|
||||
- residual risk
|
||||
|
||||
@@ -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, 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 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
|
||||
@@ -51,28 +51,37 @@ If a path, contract, data source, diff target, or output location is required an
|
||||
- Split work into gates or chunks.
|
||||
- Keep the checklist operational, with exit criteria and validation surfaces, not aspirational.
|
||||
|
||||
3. Choose the next chunk.
|
||||
3. Prepare or read the prompt map.
|
||||
- Map gates/chunks to implementer prompt artifacts.
|
||||
- Track readiness, sequencing, dependencies, and blocked chunks.
|
||||
|
||||
4. Run the implementation readiness audit.
|
||||
- Inspect every chunk in the plan, checklist, and prompt map.
|
||||
- Surface contract blockers, dependencies, environment blockers, and small decisions that should be frozen before prompting.
|
||||
- Do not write the first implementer prompt until contract blockers are resolved or the user explicitly authorizes starting only a ready subset.
|
||||
|
||||
5. Choose the next chunk.
|
||||
- Pick one coherent behavioral, contract, or validation unit.
|
||||
- Prefer chunks that are independently reviewable and testable.
|
||||
- Define in-scope work, explicit non-goals, invariants, validation, and test posture.
|
||||
|
||||
4. Write the implementer prompt.
|
||||
6. Write the implementer prompt.
|
||||
- Write one surgical prompt for the chosen chunk only.
|
||||
- Save official next-chunk prompts beside the companion plan/checklist unless the user explicitly asks for chat-only output or gives another path.
|
||||
- Do not save ad hoc follow-up/fix prompts unless explicitly asked.
|
||||
- Re-read any saved official prompt before finishing.
|
||||
|
||||
5. Review implementation.
|
||||
7. Review implementation.
|
||||
- Inspect the actual diff target. Use `git diff --cached` for staged review unless the user asks for another target.
|
||||
- Compare the diff to frozen docs, the prompt, and scope boundaries.
|
||||
- Start with findings ordered by severity. If no findings exist, start with a clear acceptable verdict.
|
||||
|
||||
6. Resolve ambiguity through docs.
|
||||
8. Resolve ambiguity through docs.
|
||||
- If docs allow multiple interpretations, identify the exact missing decision.
|
||||
- Clarify or request clarification before writing a fix prompt.
|
||||
- Do not leave important contract clarifications only in chat when docs should be updated.
|
||||
|
||||
7. Define the next handoff.
|
||||
9. Define the next handoff.
|
||||
- Continue only after the current chunk is accepted, corrected, or blocked on a documented ambiguity.
|
||||
|
||||
## Chunk Sizing
|
||||
@@ -136,6 +145,34 @@ When asked to write or update a prompt map, map checklist gates/chunks to implem
|
||||
|
||||
Use the prompt map to preserve sequencing for the planner/reviewer. Do not include the prompt map in downstream implementer prompts by default unless the chosen chunk uses prompt-map readiness or may update the prompt map.
|
||||
|
||||
## Readiness / Ambiguity Audit
|
||||
|
||||
After the plan, implementation checklist, and prompt map exist, proactively audit all chunks before writing the first implementer prompt or starting orchestration. Do this even if the user asks generally whether implementation can begin.
|
||||
|
||||
Classify every chunk as one of:
|
||||
|
||||
- `ready`
|
||||
- `blocked-by-contract-decision`
|
||||
- `blocked-by-dependency`
|
||||
- `blocked-by-environment`
|
||||
- `needs-small-freeze-before-prompt`
|
||||
|
||||
For every non-ready or weakly-ready chunk, produce a decision ledger entry with:
|
||||
|
||||
- chunk ID/name
|
||||
- exact missing decision, dependency, or environment blocker
|
||||
- why the implementer must not decide it
|
||||
- recommended default when the written docs support one
|
||||
- options and tradeoffs when the user must decide
|
||||
- plan/checklist/prompt-map updates required after the decision
|
||||
|
||||
Before implementation starts, require one of these outcomes:
|
||||
|
||||
- all contract blockers and small freezes are resolved and written back into the plan/checklist/prompt map
|
||||
- or the user explicitly authorizes starting only the `ready` subset while blocked chunks remain held
|
||||
|
||||
Do not treat dependency-pending chunks as contract-ambiguous unless a missing decision blocks their future prompt. Do not hide blockers inside the prompt map only; summarize them clearly for the user.
|
||||
|
||||
## Implementer Prompt Rules
|
||||
|
||||
Before writing the prompt:
|
||||
@@ -143,6 +180,8 @@ Before writing the prompt:
|
||||
- verify the correct next chunk from the checklist, prompt map, recent git history, and current worktree state when available
|
||||
- use `git status --short` and relevant `git log --oneline` checks before claiming a chunk is next, landed, or ready for review
|
||||
- state which chunk you chose and why
|
||||
- verify the readiness audit is complete, or complete it first
|
||||
- do not write the first implementer prompt if unresolved `blocked-by-contract-decision` or `needs-small-freeze-before-prompt` items affect the intended implementation path, unless the user explicitly authorized a ready-subset run
|
||||
- stop if an ambiguity blocks an implementer-quality prompt
|
||||
- include current-state context only to the extent needed for the implementer to execute the chunk without relying on prior chat memory
|
||||
|
||||
|
||||
Reference in New Issue
Block a user