From e8d8199c5fd0e16314e53e2a754045a1c68ca339 Mon Sep 17 00:00:00 2001 From: Dayowe Date: Mon, 21 Sep 2026 11:26:18 +0200 Subject: [PATCH] Default progress requests to lightweight snapshots; preserve explicit deeper-review overrides; release staged-implementation 0.2.0-alpha.5 --- README.md | 2 +- .../staged-implementation/.codex-plugin/plugin.json | 2 +- plugins/staged-implementation/README.md | 4 +++- .../skills/coordinator/SKILL.md | 2 +- .../coordinator/references/execution-contract.md | 12 ++++++++++++ .../skills/orchestrator/SKILL.md | 2 +- 6 files changed, 19 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 0a62779..53d835e 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Codex plugin marketplace for reusable agent workflows. - `staged-implementation`: Planner, coordinator, bounded orchestrator, implementer and validator skills for staged implementation workflows. -This branch contains the experimental coordinated-workflow preview (`0.2.0-alpha.4`). Stable `0.1.5` remains on `master`; the Git install commands below select that stable branch. Do not mistake branch-local edits for an installed upgrade. See the plugin README for the preview boundaries and qualification procedure. +This branch contains the experimental coordinated-workflow preview (`0.2.0-alpha.5`). Stable `0.1.5` remains on `master`; the Git install commands below select that stable branch. Do not mistake branch-local edits for an installed upgrade. See the plugin README for the preview boundaries and qualification procedure. ## Install diff --git a/plugins/staged-implementation/.codex-plugin/plugin.json b/plugins/staged-implementation/.codex-plugin/plugin.json index 9b16867..ddbb720 100644 --- a/plugins/staged-implementation/.codex-plugin/plugin.json +++ b/plugins/staged-implementation/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "staged-implementation", - "version": "0.2.0-alpha.4", + "version": "0.2.0-alpha.5", "description": "Experimental coordinated staged implementation with planner, coordinator, bounded orchestrator, implementer, and validator roles.", "author": { "name": "Local developer" diff --git a/plugins/staged-implementation/README.md b/plugins/staged-implementation/README.md index 2d9b79a..eeae550 100644 --- a/plugins/staged-implementation/README.md +++ b/plugins/staged-implementation/README.md @@ -10,7 +10,7 @@ Staged Implementation bundles five skills with two execution entry points: Use this plugin when a feature or fix is too large or contract-heavy to handle as one open-ended coding pass. -**Experimental preview — `0.2.0-alpha.4`.** Stable `0.1.5` is preserved on `master`. This branch changes Orchestrator's boundary; old whole-checklist launch prompts must explicitly select Coordinator rather than silently losing scope. No installation, migration execution, measured savings or unattended-runtime qualification is implied by the files or structural validators. Qualify the [pilot](skills/coordinator/references/pilot-validation.md) before consequential coordinated execution. Do not mix stable and preview role instructions in one run. +**Experimental preview — `0.2.0-alpha.5`.** Stable `0.1.5` is preserved on `master`. This branch changes Orchestrator's boundary; old whole-checklist launch prompts must explicitly select Coordinator rather than silently losing scope. No installation, migration execution, measured savings or unattended-runtime qualification is implied by the files or structural validators. Qualify the [pilot](skills/coordinator/references/pilot-validation.md) before consequential coordinated execution. Do not mix stable and preview role instructions in one run. ## Plugin Structure @@ -119,6 +119,8 @@ The usual flow is: 3. Use `validator` when runtime, UI, API, integration, or regression evidence is needed. 4. Use `orchestrator` directly for bounded work, or `coordinator` to continue across a longer checklist with fresh scoped orchestrators. +Ordinary progress questions, such as "progress update" or "how's it going?", default to a brief [progress snapshot](skills/coordinator/references/execution-contract.md#user-requested-progress-snapshots). Each question requests one snapshot from the active orchestrator, reusing an already-pending request for that assignment; if none is active, the coordinator reports the latest known outcome. The orchestrator answers from existing knowledge without cascading worker queries or extra checks. Explicitly ask for investigation, fresh verification or a detailed review to override that default within existing authority; requesting an update does not start periodic reporting. + ## Execution Ownership | Responsibility | Owner | diff --git a/plugins/staged-implementation/skills/coordinator/SKILL.md b/plugins/staged-implementation/skills/coordinator/SKILL.md index 27de872..95c183d 100644 --- a/plugins/staged-implementation/skills/coordinator/SKILL.md +++ b/plugins/staged-implementation/skills/coordinator/SKILL.md @@ -28,7 +28,7 @@ Start with one active orchestrator assignment at a time. Coordinator + orchestra 1. Select the next eligible chunk or validation gate from written dependencies and actual accepted state. Do not treat a committed candidate as accepted without its acceptance evidence. Do not use held work as a dependency. Verify uncommitted accepted inputs explicitly when permitted by policy. If grouping is useful, enumerate the approved chunk IDs and order; preserve every acceptance/rollback boundary. 2. Assign the bounded work using the shared execution contract, including the run ID, unit scope/ID, role and attempt to propagate through delegation. Use its supported task-label encoding. Save or reference the assignment in existing prompt/handoff locations; no separate dispatch journal. Give a fresh orchestrator scoped context without full parent-history inheritance when supported, explicit authorized model/effort if needed, and the correct experimental skill path/version. It writes the detailed implementer prompt after verifying scoped readiness. Do not send it the entire historical run narrative. 3. Record the logical assignment/tool-label/actual-worker mapping, immediate parent and ownership before it may mutate shared resources. Delegate chunk review, acceptance and scoped commits under existing user authority. Reserve the candidate/index/integration target for that orchestrator; neither coordinator nor another worker may edit or stage there concurrently. Coordinator-owned scheduling records must be separate from the candidate's validated inputs, or updated only after its hold is released. -4. Wait for completion or material events using supported notifications/interruptible waits. Do not send routine acknowledgement prompts, poll continuously, or absorb raw logs merely to remain busy. Check liveness when expected progress, tool failure or other evidence warrants it; a wait timeout alone is insufficient. Prefer available status information before prompting. Required user updates use information already received, with uncertainty stated honestly; do not initiate inspections or descendant status requests solely to refresh a progress message. Follow the shared contract's communication boundary while preserving timely intervention, pause routing and required safety/resource checks. Do not let the orchestrator dispatch beyond its assignment. +4. Wait for completion or material events using supported notifications/interruptible waits. Do not send routine acknowledgement prompts, poll continuously, or absorb raw logs merely to remain busy. Check liveness when expected progress, tool failure or other evidence warrants it; a wait timeout alone is insufficient. Prefer available status information before prompting. Unsolicited progress messages use information already received, with uncertainty stated honestly; do not initiate inspections or descendant status requests solely to refresh them. For ordinary user progress questions, apply [User-Requested Progress Snapshots](references/execution-contract.md#user-requested-progress-snapshots), including its bounded freshness request and explicit detailed-review override. Follow the shared contract's communication boundary while preserving timely intervention, pause routing and required safety/resource checks. Do not let the orchestrator dispatch beyond its assignment. 5. Check the returned acceptance record and actual repository state under **Completion Verification**. Route concrete omissions or discrepancies back to the same orchestrator when continuity is useful. Do not start a new full review for every clerical correction. New contract or cross-chunk risk can require a scoped independent challenge; no required review may be skipped. 6. Verify ownership transfer from final results and retire the complete subtree's assignments under the shared lifecycle rules. Do not send post-completion acknowledgement/retirement messages. Closing or unloading a parent does not prove its children/processes stopped. Preserve held source, failed evidence and future gate/rollback consumers. Reconcile eligible cleanup and allocations, then dispatch normally; no recurring capacity probe or explicit-closure requirement. 7. Update the one current run handoff and affected checklist/readiness entries. Dispatch the next fresh orchestrator, or stop at the authorized boundary. No new user approval is needed for routine steps already authorized. diff --git a/plugins/staged-implementation/skills/coordinator/references/execution-contract.md b/plugins/staged-implementation/skills/coordinator/references/execution-contract.md index 418bb5b..3d29983 100644 --- a/plugins/staged-implementation/skills/coordinator/references/execution-contract.md +++ b/plugins/staged-implementation/skills/coordinator/references/execution-contract.md @@ -41,6 +41,18 @@ The active orchestrator alone stages/commits its accepted scope under its commit For `ask-before-each-commit`, return the concrete proposed commit and pause before Git mutation pending approval; for `do-not-commit`, preserve and identify accepted uncommitted work. Acceptance and Git completion are separate facts. User pauses and later authority restrictions override the assignment. +## User-Requested Progress Snapshots + +Treat ordinary progress questions as lightweight snapshots by default, recognizing intent rather than exact wording. Examples such as "status?", "progress update" and "how's it going?" are illustrative, not commands the user must memorize. + +For each ordinary progress request, Coordinator requests one bounded snapshot from the active Orchestrator. Reuse an already-pending snapshot request for that assignment instead of sending another. If no Orchestrator assignment is active, report the latest known outcome. The Orchestrator answers from existing knowledge without cascading status requests to workers, inspecting changing files, reconstructing evidence or running checks solely for the snapshot. In direct mode, Orchestrator answers the user from its own known state. Do not spawn a worker or wake a retired assignment for a snapshot. + +Return a short paragraph covering the current chunk/phase, meaningful progress, known blockers and what remains before acceptance/commit. Distinguish reported progress from verified acceptance; qualify older information as "last reported" and missing blocker information as "no blocker reported". Do not invent percentages, ETAs or fresh verification. A snapshot neither performs nor replaces acceptance. + +If a fresh reply is not promptly available, provide the last known state and its limitation without interrupting active work or repeatedly prompting. Use supported notifications/waits for the requested reply. Do not add acknowledgement exchanges, progress documents or periodic reporting solely because an update was requested; continue the authorized work or waiting afterward, preserving any user pause. + +An explicit request for deeper investigation, fresh verification or a detailed review overrides the lightweight default to the extent requested and within existing authority. It does not waive safety, ownership, pause handling or acceptance requirements. Material findings and urgent blockers still receive their required treatment. + ## Result and Durable Handoff Return concise fields with accessible evidence links; omit empty optional sections: diff --git a/plugins/staged-implementation/skills/orchestrator/SKILL.md b/plugins/staged-implementation/skills/orchestrator/SKILL.md index 325e3f2..e639132 100644 --- a/plugins/staged-implementation/skills/orchestrator/SKILL.md +++ b/plugins/staged-implementation/skills/orchestrator/SKILL.md @@ -211,7 +211,7 @@ For new implementer and independent-validator assignments, default to fresh scop Dispatch complete bounded assignments so workers can finish already-authorized routine steps without acknowledgement chatter. Coordinate candidate release, shared-resource acquisition, scope changes and required approvals explicitly; a completion notification does not release a workspace. Prefer completion notifications or interruptible waits, with proportionate polling when necessary. Preserve required user updates and immediate blocker/material-finding reports; do not add a permanent monitoring loop or wait so long that intervention is prevented. -Do not routinely send status-only prompts to a worker with a complete assignment. A wait timeout alone does not justify an acknowledgement or context replay; use notifications, independent safe work or an interruptible wait compatible with required user updates. Perform a proportionate liveness check when expected progress, a tool failure or other evidence suggests the worker is stuck; prefer available status information before prompting. Necessary intervention, blocker reporting and required safety/resource checks remain required. Apply the shared execution contract's communication boundary: routine in-scope corrections stay here, and user updates do not trigger descendant polling. +Do not routinely send status-only prompts to a worker with a complete assignment. A wait timeout alone does not justify an acknowledgement or context replay; use notifications, independent safe work or an interruptible wait compatible with required user updates. Perform a proportionate liveness check when expected progress, a tool failure or other evidence suggests the worker is stuck; prefer available status information before prompting. Necessary intervention, blocker reporting and required safety/resource checks remain required. Apply the shared execution contract's communication boundary: routine in-scope corrections stay here. Answer Coordinator or direct-user snapshot requests from existing knowledge under [User-Requested Progress Snapshots](../coordinator/references/execution-contract.md#user-requested-progress-snapshots), without descendant polling or extra checks; an explicit deeper request follows that rule's override within existing authority. While a worker owns an active implementation or validation pass, do not continuously inspect its changing work or duplicate its assigned investigation. Intervene for concrete risk, blockers, ownership conflicts or an agreed checkpoint; perform acceptance review against the stable returned candidate. This does not restrict required independent review or investigation of affected callers and shared behavior.