@deniscodp/skills 0.0.0-stage → 1.0.0

package/skills/denisco-implementation-coordinator/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: denisco-implementation-coordinator
+description: "Turn a decided handoff into a launchable coordination plan, then execute or resume it through sequential programmers with fresh contexts, bounded assignments and a report per worker. Use when explicitly invoked to prepare, run or resume coordinated development, or when denisco-handoff-implementation planning selects the coordinated path; not for specification, single-session direct programming or parallel execution."
+disable-model-invocation: true
+metadata:
+  version: "4.3.0"
+---
+
+# Implementation coordinator
+
+Input: a decided handoff, its PLAN/STATE when already planned, and a request to prepare, execute or
+resume coordination. Read [coordination documents](references/documents.md) before writing:
+COORDINATOR.md, COORDINATOR-HISTORY.md and the packet files are the coordinator's documents,
+alongside STATE by default. HANDOFF, PLAN, STATE, STATE-HISTORY, the operational sidecar and
+application code remain read-only for the coordinator, even between workers. The programmer
+updates them only through the existing denisco-handoff-implementation workflow, including its scope,
+permission and verification rules. An inconsistency is a finding to route through that workflow,
+not permission to rewrite its inputs. The planning phase and the post-closure session below are
+denisco-handoff-implementation sessions of this conversation, under that skill's rules and its own claim.
+
+Load the installed `denisco-handoff-implementation` skill and read its `references/delegated-implementation.md`,
+session plan and ownership contract before preparation or dispatch. Version 8.0.0 or a compatible
+later version must support the worker profile and delivery template; an older installation is a
+capability blocker, not something to override in a prompt. Locate the actual installed package and
+pass its path to each worker. Read [runtime capabilities](references/runtimes.md) for the current
+provider during preparation and recheck actual capabilities before launch. Preparation never
+launches trial workers or judges.
+
+## From handoff to a launchable plan
+
+One preparation phase takes a decided handoff to a plan the user can launch. It starts on the
+user's yes to the specification's planning question when planning selects the coordinated path,
+on an explicit invocation naming a handoff or STATE, or on an explicit preparation request. A
+generic first request to coordinate through completion still prepares first. Complete the entry and
+ownership checks in Establish the run before any preparation writes.
+
+1. **Technical plan.** Without PLAN, STATE and the planned block map, run denisco-handoff-implementation's
+   planning-only phase in this conversation first, including its blocker check and saved direct
+   execution prompt, then release its claim. An undecided handoff goes back to
+   denisco-interactive-spec-definition. An existing plan is read and reconciled, not replanned.
+2. **Path check.** Count implementation blocks, final integration excluded. With one block, or when
+   the runtime cannot create fresh-context workers, state the reason and end with
+   denisco-handoff-implementation's "Plan ready. Start <block>?" instead of a coordination proposal. An
+   explicit user request to coordinate a one-block task is honored.
+3. **Session plan.** Draft all remaining groups, including blocked work and final integration, with
+   block IDs, dependencies and grouping reasons. This is a tentative session plan, not a replacement
+   PLAN. Save both coordination documents, the preparation record and a concrete execution prompt;
+   reread them before reporting readiness. If no work is dependency-ready, record the blocker and a
+   pending continuation rather than ask to launch an unusable assignment.
+4. **Start question.** Ask "Coordination ready. Start A1?" with the first assignment's ID, the worker
+   profile and the extra skills the operating guide lists, or that it lists none. Recommend starting
+   execution in a fresh conversation with the saved prompt, because the coordinator re-reads its
+   whole context at every return and relay; a yes here remains valid. Add that after a usage-limit
+   stop only the launching conversation, continued without clearing it, can resume the interrupted
+   worker; a new conversation gives the residual to a new worker.
+
+The user's yes starts execution in this conversation; otherwise end preparation with the saved
+prompt. A later user-submitted execution prompt or equivalent scoped request starts the prepared
+coordination. If the user explicitly requests both phases without a pause, preserve that
+authorization, materialize/check preparation and proceed; do not invent an extra approval contrary
+to the explicit request. Native plan approval, a bare "Implement the plan." or tool-mode changes
+alone never authorize programmer launches.
+
+In Plan Mode propose only the current phase and identify pending writes. After permission to write,
+finish that phase; preparation then reaches its start question, not automatic execution. An execution
+request for missing coordination documents prepares them first under the same phase boundary.
+On an explicitly requested resume, reconcile the existing execution authorization and lifecycle;
+do not ask for approval of every group. Reading saved prompts or stale active metadata never launches work.
+
+## Worker profile
+
+The default profile is light: model inherited and effort `medium` for every programmer and the
+integration worker, red blocks included. Request the effort through the spawn tool; where the runtime
+exposes no effort setting, the worker inherits and COORDINATOR says so. Every packet limits reading
+to the assigned HANDOFF points plus the sections they cite, and asks for targeted checks: browser
+checks of the assigned criteria, and test or build output read as summary and failures only, with
+the full log kept in a file. The full profile (inherited effort) applies to the one automatic recovery
+attempt and whenever the user asks for it. Extra skills come only from the operating guide's
+coordinated-workers section; without that section workers get none. Record the requested and
+observed profile for every attempt.
+
+## Establish the run
+
+Read project instructions, handoff, PLAN, STATE, operational JSON and relevant operating guidance.
+Preserve user changes and existing evidence. On a new human session, ask about pending Your actions
+and external changes once; a same-conversation start or internal worker rotation does not repeat it.
+Resolve the authorized scope and any explicit limits from the current request and recorded decisions.
+Between workers record new human answers in COORDINATOR for the next programmer to integrate through
+the standard workflow. During an active assignment relay answers for the worker to record; defer
+your own document writes until handover. Do not write them into STATE yourself. Reconcile COORDINATOR,
+the technical evidence and actual ownership before proceeding. A technical plan change requires
+refreshing the proposed groups, with its reason preserved in COORDINATOR-HISTORY.
+
+Require fresh-context creation, worker communication/results and a safe ownership handover;
+[runtime capabilities](references/runtimes.md) says how each runtime closes a returned worker.
+Check capacity before each launch against the next assignment, never the whole plan: launch when
+it fits. When the remaining chain outgrows what the runtime can reclaim, stop at a checkpoint with
+the resume prompt, so a new conversation continues the same chain, authorization and recovery
+allowance. Capability findings, capacity included, live in COORDINATOR and are rechecked at every
+entry; a saved prompt carries only the user's authorization and limits. A recorded user condition
+that repeats an earlier capability finding still binds: when the remaining work no longer depends
+on it, say so and ask once whether to lift it.
+If these capabilities become unavailable after preparation, leave a manual continuation in COORDINATOR before
+execution and report the missing capability. Every blocked stop names the ways on, each with the
+prompt to send: what can launch now, a runtime that has the missing capability, or direct
+execution if the user chooses it. Do not silently perform all implementation in this
+conversation, launch another CLI as a fallback, or change global configuration. Record limitations
+without claiming that a handoff was saved if writes are blocked. Live context telemetry is optional;
+cumulative token usage is not window occupancy.
+
+Acquire the worktree claim for coordinator bookkeeping only when no worker can still write.
+Record phase, authorization and limits in COORDINATOR, with decisions in COORDINATOR-HISTORY.
+Document ownership remains limited even while holding the claim. With explicitly enabled and
+already bound measurement, register this conversation before its workers using the benchmark
+contract: planning for preparation, implementation for execution-only entry; one native conversation
+keeps one registration with its phase history explained. Ownership bookkeeping and permitted
+measurement records are the only non-document writes for the coordinator. Never call benchmark
+close, prompt save/clear or bind to mutate technical documents. Missing setup goes through the
+programmer's standard workflow; keep attribution gaps explicit. Otherwise leave measurement inactive.
+Release the claim before dispatching a worker; keep its token out of prompts and STATE.
+
+## Assign, receive, repeat
+
+1. Select dependency-ready work within the authorized plan. Use colors as difficulty estimates,
+   then consider shared code, exploration and verification effort. A red block alone, two related
+   yellows or several greens are examples, not quotas. Preserve coherent changes, prerequisite
+   order and the plan's release boundaries. Narrow future groups when deliveries show underestimated
+   effort; explain the selection in COORDINATOR, preserving the prior proposal and rationale in
+   COORDINATOR-HISTORY. An unresolved verification gap blocks only work that depends on it. User
+   checks in Your actions do not stop the chain: relay them and continue with ready work. A verdict
+   asking for a change becomes a correction assignment placed before final integration and before
+   any release that needs it; a small correction within the next worker's points may open that
+   assignment. Recheck proposed groups against current technical documents before dispatch; only
+   the programmer can change technical blocks or criteria.
+2. Under coordinator ownership, save the exact packet in the attempt's packet file, record the
+   assignment (ordered block IDs and the delegated contract's fields) in COORDINATOR and append a
+   prepared-attempt entry to COORDINATOR-HISTORY. Release ownership and create a new worker with
+   no inherited conversation, using the worker profile. Pass document paths, authorization evidence,
+   known answers and the assignment, not full transcripts; cite the COORDINATOR-HISTORY entries the
+   worker needs instead of the whole history. A failed launch leaves a prepared, unexecuted
+   assignment. Follow the document contract for deferred lifecycle recording: no post-launch write
+   may race the worker's acquisition.
+3. While the worker owns the worktree, remain read-only, including tests/builds, STATE and metrics.
+   Keep the user informed with short progress updates, checking the worker's actual status
+   whenever the user writes: a stop may arrive without a notification. Relay necessary worker
+   questions to the user and return answers without inventing them. The worker records answers and
+   continues independent work; the coordinator is the sole user-facing questioner. Route user stop or scope
+   changes promptly; request orderly checkpoint/cleanup and verify quiescence before another writer.
+   A stop or launch restriction covers every agent the coordinator would start, judges included,
+   unless the user exempts it. An announced plan with an opt-out is not consent: wait for the
+   answer before launching and never record silence as approval. A worker paused for a judge
+   relay keeps ownership; relay per [runtime capabilities](references/runtimes.md) and resume
+   that worker with the verbatim observations.
+4. Receive the structured delivery. Inspect STATE, history and cited evidence for scope, unresolved
+   criteria and consistency; inspect code/logs when a discrepancy requires it. A worker's "done"
+   alone is insufficient. An interim runtime notice that the worker still waits on its own
+   background commands is not a delivery: stay read-only and keep waiting.
+   Close the returned worker right away with the runtime's stop/close operation, or the closure
+   runtime capabilities define where none exists, and confirm that it, its tasks and its resources
+   cannot continue writing. Services
+   that stay up are the ones the delivery hands over with port and PID; a worker never stays alive
+   to keep a service running. Release finite runtime slots; if capacity cannot be reclaimed, stop
+   with a continuation rather than reuse a full context.
+5. Acquire a fresh claim for bookkeeping. Record the delivery, closure, usage row and coordination
+   decision as the document contract specifies, update COORDINATOR, prepare the next attempt and
+   release. Request any technical reconciliation from a programmer through the standard workflow;
+   do not edit STATE or certify criteria yourself. Once the next worker is launched, or the run
+   stops, report the return to the user with the return card.
+
+Every assignment gets a new worker, including a continuation of the same unfinished block; a worker
+never expands its own range. The one exception is an external interruption, such as a usage limit
+(429) or network failure, of a worker that holds the claim or has work in progress: resume that same
+worker by message, naming the cause, and record the resume after its return. It is not a recovery
+and leaves the allowance unchanged. Only the conversation that launched the worker can message it,
+and a usage limit usually stops that conversation too. When it is gone (closed, cleared or replaced
+by a new one), the worker cannot resume: verify the stop under the stopped-writer rule, release its
+claims by their exact IDs and give the residual to a new worker with the same profile. That is
+still no recovery.
+
+A worker that ends without a delivery and without your stop, for example stopped by the user from
+the runtime's interface, leaves a user decision. Keep it stopped and launch nothing. Report its last
+checkpoint, uncommitted work and held claims, then ask once: resume that worker, give the residual
+to a new worker, or stop the run. A resume or a new worker follows the rules above; a stop follows
+Final integration and stopping.
+
+Keep the coordinator context small: retain current decisions, delivery summaries and evidence
+paths. Read historical details only for a concrete inconsistency or recovery. Save a coordination
+resume prompt in COORDINATOR. The ordinary implementation prompt in STATE remains worker-owned.
+
+## Partial progress and recovery
+
+A worker may return early for context pressure, a real blocker or an explicit limit. Preserve
+unfinished work and assign a precise residual task to a new worker; partial progress is not
+verification. For an assignment ending without useful progress, allow one automatic recovery with
+a documented diagnosis, the full profile and a changed approach or smaller scope. Persist that
+recovery allowance across workers and coordinator resumes. After another no-progress outcome on the
+same unresolved obstacle, ask the user and stop that retry chain; continue only independently ready
+work. Renaming an assignment or repeating the same failed check does not reset the allowance.
+Useful progress means a supported implementation, verified criterion or resolved prerequisite, not
+another summary or reread. A perceptual criterion still failing after denisco-visual-check's single
+correction round is a user question relayed through the coordinator, not another correction
+assignment or judge.
+
+A crash or missing delivery requires ownership recovery first. Check actual worker/process status
+and children; neither idle files nor an old claim proves exit. Apply the existing stopped-writer
+recovery contract. If safety is uncertain, remain read-only and request the concrete coordination
+needed. Preserve failures and recover from repository evidence rather than assuming completion.
+Use the document contract's legacy migration: read old Coordination notes without changing them;
+only a programmer can archive/replace those notes through the standard STATE/HISTORY procedure.
+
+## Final integration and stopping
+
+After all implementation groups, dispatch a fresh worker with kind `integration`: complete the
+plan's cross-block checks and remaining acceptance verification, correcting defects only within
+the approved task. Use the same bounded contract with explicit correction scope. If too large,
+checkpoint and split the residual integration work into fresh assignments. Reverify affected
+criteria after corrections; do not rerun unchanged valid checks without a reason.
+
+Finish only when Done when and required checks are met, with waivers and user-reported checks
+identified. Keep technical verification separate from user acceptance and pending accounting.
+If remaining work needs user/external action, a capability, an exhausted recovery decision or an
+explicit limit, persist the unfinished state and continuation. Without an explicit limit, continue
+until completion or a real stop; elapsed 20-30 minutes is not a default deadline. Honor feasible
+time/assignment limits at safe checkpoints; claim enforcement of a monetary limit only with
+reliable cost data. If a requested hard limit cannot be enforced, resolve it before dispatch.
+
+Call a release or intermediate commit ready to merge only after checking commit order: every
+commit of that release, its corrections included, precedes the first commit of later work.
+
+Before ending, reconcile ownership, active workers, evidence and saved prompts. Report completed
+work, failed/unavailable checks and the precise next step. End with Your actions or "Nothing needed
+from you." This protocol is procedural: local tests do not prove model adherence or token savings.
+
+After closure, a user request in this conversation, such as a merge, a push or a small correction,
+runs as a direct denisco-handoff-implementation session: acquire its claim, follow its permission list and
+always-ask rules, and update STATE and STATE-HISTORY consistently. Record the switch and its outcome
+in COORDINATOR-HISTORY under the same claim, then release. A new goal still becomes a new task.

package/skills/denisco-implementation-coordinator/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/skills/denisco-implementation-coordinator/references/documents.md

@@ -0,0 +1,175 @@
+# Coordination documents
+
+Read before preparation, execution or resume. Default to COORDINATOR.md, COORDINATOR-HISTORY.md and
+the `coordinator-packets/` folder beside the actual STATE resolved from the handoff's operational
+context, not an assumed task root. Honor explicit project paths and put the real paths in prompts.
+An existing document must match this task/worktree; report collisions rather than overwrite another
+task. No new sidecar schema. Write these documents and the user-facing reports in the user's language.
+
+## Authority and writers
+
+| Resource | Writer during coordinated execution | Authority |
+|---|---|---|
+| HANDOFF | Programmer through the standard workflow | Decided scope, requirements and permission rules |
+| PLAN and operational block map | Programmer through the standard workflow | Technical blocks, dependencies and criteria |
+| STATE | Programmer through the standard workflow | Current technical results, evidence, blockers and direct continuation |
+| STATE-HISTORY | Programmer, append-only | Session history and replaced technical decisions/results |
+| COORDINATOR | Coordinator | Current grouping proposal, assignment, worker usage, coordination limits and continuation |
+| COORDINATOR-HISTORY | Coordinator, append-only | Proposed/revised groups, actual attempts, observations and reasons |
+| `coordinator-packets/<attempt-id>.md` | Coordinator, once per attempt | Exact packet sent to that worker |
+
+The coordinator reads technical evidence and reports discrepancies; the programmer resolves them
+through denisco-handoff-implementation. Regrouping existing blocks does not authorize creating, deleting
+or reinterpreting them. Neither holding the worktree claim nor owning a document expands task scope.
+Programmers, including the final integration worker, read but never edit the coordination documents.
+The coordinator never appends technical session entries, rewrites technical state, changes the map,
+or repairs HANDOFF/PLAN on its own. All required technical updates follow the existing workflow.
+Standard measurement helpers remain opt-in and run only under ownership; coordinator registration
+and reports may update measurement records, but never technical documents through indirect commands.
+
+## COORDINATOR.md: current picture
+
+Keep it short enough to resume without reading the full history. Use these sections:
+
+1. **Task and phase:** links to HANDOFF, PLAN, STATE, STATE-HISTORY, operational JSON and coordination
+   history; worktree; observed technical plan revision/date or content fingerprint; last update.
+   Distinguish preparation requested, prepared, executing, blocked, finished and cancelled.
+2. **Authorization and constraints:** preparation request and, separately, execution request/answer,
+   dates and scope. State the scope as the task's work: the plan's blocks, corrections arising from
+   the user's verdicts within HANDOFF points, and final integration; never a list of assignment IDs,
+   so regrouping leaves it current. Permission-list reference; limits and progress against them;
+   measurement state; worker profile and extra skills with their source. Include newly received
+   human answers awaiting the programmer's standard recording. Prepared does not mean authorized or
+   launched. Remove forwarded pending answers only after technical recording.
+3. **Proposed session plan:** ordered groups covering all remaining authorized work and integration.
+   Each row names stable assignment ID, kind, exact block IDs, dependencies/readiness, residual work,
+   reason for grouping and a one-line status: proposed, current, returned or superseded, plus, once
+   returned, verified blocks, commits and pending user checks. Mark blocked proposals. Future rows
+   are provisional; revise grouping when technical evidence changes, preserving history.
+4. **Worker usage:** one row per attempt with raw observations only: attempt, profile, blocks with
+   colors, criteria worked, tokens, tool uses and duration as the runtime reports them at completion,
+   and lines added/removed by the attempt's commits; then the total. Under the table state that
+   tokens are the worker's accumulated context rather than billed usage, that the coordinator is
+   excluded, and which rows a resume makes partial. Unknown values stay unknown. Add derived ratios
+   or analysis only when the user asks.
+5. **Current execution:** link to the current packet file, attempt ID, worker handle if observed,
+   requested and observed provider/model/effort, lifecycle observation and source, last returned
+   assignment/evidence references, services handed over (port, PID, owner), outstanding cleanup and
+   next action. Where the runtime has a concurrent-agent limit, record live agents against it at
+   each launch. Persist recovery usage per unresolved obstacle (`0` or `1`); new attempt names,
+   external-interruption resumes and coordinator resumes do not change it.
+6. **Continuation:** phase-correct launch/resume prompt or exact blocker. Keep prompts here outside
+   STATE's generated section. On completion/cancellation remove runnable obsolete prompts, keeping
+   remaining gaps and history. A manual fallback names the pending technical step and uses the
+   existing STATE continuation where applicable; it does not rewrite STATE. When STATE has no
+   continuation for that step, the fallback gives the complete direct request in the
+   denisco-handoff-implementation next-prompt form, so the user can always continue.
+
+Do not duplicate the full criterion table or technical history. A summary such as "worker reports
+B3-B5 verified; checked against STATE and linked artifacts; B6 remains incomplete" points at its
+sources and names the inspection. Unknown model/effort or occupancy stays unknown. The configured
+model is not proof of the actual runtime model. Record a new context only with observed fresh-instance
+creation; never describe a clear/reset operation that was not performed.
+
+## COORDINATOR-HISTORY.md: append-only observations
+
+Create it during preparation with the initial grouping and rationale. Keep dated entries for
+revisions, prepared attempts, launch failures, interruptions and resumes, returned attempts,
+recovery, post-closure sessions and final closure. Preserve the replaced grouping before updating
+the current proposal. Give each returned attempt one entry with these fields, writing "unknown" for
+anything not observed rather than a reconstructed guess:
+
+- **Assignment:** assignment/attempt IDs, kind, exact blocks or residual work, grouping reason,
+  authorization reference and packet file link.
+- **Launch:** native worker reference (agent ID), launch time, fresh-context setting, profile
+  requested versus observed, each with its tool/log evidence. Keep private log bodies and secrets out.
+- **Interruptions:** cause (external, user stop or crash), time, resume by message or new worker
+  with the reason (for a user stop, the user's answer), recovery allowance after it.
+- **Delivery:** the worker's report in brief: blocks worked, criteria, commits, questions, residual
+  work and stop reason.
+- **Coordinator check:** what was checked against STATE, its dated HISTORY entry and actual evidence;
+  discrepancies stay explicit. Code revision and relevant dirty-worktree facts link to worker evidence.
+- **Closure:** return time, how the worker was closed, ownership release, child/resource cleanup and
+  services handed over, each supported or explicitly unconfirmed. A response alone does not prove
+  exit or release.
+- **Usage:** the values of its Worker usage row.
+- **Next decision:** continue, regroup, recover, wait or finish, with the reason and recovery allowance.
+
+Distinguish planned work, worker statements and coordinator observations. Link to stable assignment
+IDs, dated technical history entries and concrete artifacts instead of relying only on mutable STATE.
+Later evidence corrects a prior assertion by a new entry, never by erasing the original.
+
+## Return card
+
+After each return, once the next worker is launched or the run stops, report in chat:
+
+- one headline sentence with the outcome;
+- **Ax-n (blocks):** what changes for the user, criteria passed or pending, commits, usage;
+- **Now:** the worker just launched and its blocks, or why the run stopped;
+- **Your actions:** numbered user checks saying where and how to verify, or "Nothing needed from you."
+
+The card states only what COORDINATOR-HISTORY records; details stay there and in STATE.
+
+## Lifecycle recording without competing writers
+
+Before launch, while holding its own claim, the coordinator writes the exact packet to
+`coordinator-packets/<attempt-id>.md`, records the prepared attempt ID in both coordination
+documents with a link to that file, then releases. A packet file is written once; a new attempt gets
+a new file. After dispatch the coordinator remains read-only even if the programmer has not acquired
+yet: a transient free claim is not a safe write window.
+The programmer records assignment/attempt ID and observed worker identity in STATE and its technical
+history through the standard workflow. It returns launch/configuration and closure evidence in its
+delivery; it never edits COORDINATOR. The coordinator appends the actual observations only after
+quiescence, release and its own fresh claim, retaining both occurrence and recording times when known.
+
+Consequently a coordination file may still say prepared while a worker is active. It is a last
+persisted observation, not a live process registry. On resume, correlate attempt ID with native
+peer/invocation metadata, ownership and the worker's technical records before any relaunch. If launch
+outcome or continued writes are uncertain, stay read-only and resolve that uncertainty; no timeout
+turns a prepared record into proof that nothing started.
+
+## Prompts and phase boundary
+
+Save concrete paths and actual scope, not placeholders. These templates illustrate the contract:
+
+```text
+Use denisco-implementation-coordinator to execute the prepared coordination in <COORDINATOR.md>
+for <HANDOFF.md>. Read <STATE.md>, the technical plan and applicable instructions.
+I authorize sequential bounded programmers through the recorded task scope, including final
+integration, with the recorded worker profile. Recheck readiness, capabilities and ownership;
+preserve existing permissions and measurement state. Return questions requiring my decision
+through the coordinator.
+```
+
+```text
+Use denisco-implementation-coordinator to resume <COORDINATOR.md> for <HANDOFF.md>.
+Read <STATE.md> and the recorded authorization/limits. Reconcile the last attempt with actual
+workers, ownership and evidence before dispatch. Continue only unfinished authorized work.
+```
+
+Model invocation of this skill is disabled, so plain text does not load it: save each prompt after
+the runtime's explicit invocation (`/denisco-implementation-coordinator` in Claude Code,
+`$denisco-implementation-coordinator` in Codex). Planning that selects the coordinated path loads the
+installed skill by its path after the user's yes to the planning question.
+The first is prepared before execution is authorized; reading it is not its submission by the user.
+A preparation-only resume finishes preparation and reaches the start question. Native Plan Mode
+approval materializes only the current phase. A later explicit execution request may name these
+documents without copying the template. No additional approval is needed between ordinary groups.
+
+## Existing coordination notes
+
+When upgrading from coordination embedded in STATE, first inspect actual workers and ownership.
+The coordinator reads the old notes and HISTORY, imports their supported facts into its own
+documents with source references, and preserves authorization, pending work and consumed recovery.
+Missing facts remain unknown. An import is not a new launch or a fresh execution authorization.
+
+The next authorized programmer, during its ordinary STATE update, archives replaced Coordination
+text unchanged in STATE-HISTORY and replaces it with a short coordinator link and current assignment
+reference. It preserves technical outcomes, pending answers and the normal implementation prompt.
+Old HISTORY entries stay untouched. If no programmer can run yet, leave the legacy notes in place;
+record migration pending in COORDINATOR. Do not launch a worker solely during preparation to migrate.
+The coordinator uses the imported current record plus source evidence; stale notes never replenish
+retries or override newer user restrictions. Conflicts are reconciled explicitly, not guessed away.
+
+A COORDINATOR written before version 3.0.0 keeps its content: on the next bookkeeping write add the
+missing sections and keep earlier packets where they are, with unknown values for unrecorded fields.

package/skills/denisco-implementation-coordinator/references/runtimes.md

@@ -0,0 +1,105 @@
+# Runtime capabilities
+
+Discover the tools available in the actual session. Installed CLI versions or a skill file alone
+do not prove that this session can spawn workers. Keep the implementation contract provider-neutral;
+record actual capability gaps in COORDINATOR. Preparation inspects available tool metadata without
+launching a test worker; execution rechecks actual availability. Do not install adapters or enable telemetry implicitly.
+
+## Codex
+
+When the exposed spawn tool offers `fork_turns`, select `none` for each programmer. For another
+tool interface use its documented fresh-context equivalent, not an assumed parameter. Supply
+the task packet and actual installed skill paths explicitly. Verify the child has the required
+filesystem, shell and applicable verification tools; do not assume it inherits every tool.
+Use available message/wait/status/close operations. A completed response and a released worktree
+claim answer different questions; check both. Keep the model inherited; request the profile's effort
+only through a documented spawn setting, otherwise record it as inherited.
+
+Codex multi-agent tools (`spawn_agent`, `send_message`, `followup_task`, `wait_agent`,
+`list_agents`, `interrupt_agent`) expose no close operation, so closure is defined here. A returned
+worker is closed, and the next one may launch, when its final answer has arrived, `list_agents` no
+longer shows it running (otherwise `interrupt_agent` ends the turn first), its claim is released and
+its delivery reports children drained. From then on it receives no `send_message` or
+`followup_task`, which would reopen a closed context. Resuming a worker after an external
+interruption uses `followup_task` before closure, as the message resume does elsewhere.
+
+The tool instructions state the concurrent limit, for example "up to 4 agents can be active at once,
+including you", and a closed worker may keep its slot. Before each launch count live agents with
+`list_agents` and launch when the next assignment fits; after the first return record whether the
+closed worker still appears. When no slot is left and work remains, record the capacity stop in
+COORDINATOR and end with the resume prompt: a new conversation starts a new root thread, whose
+slots the coordinator rechecks on entry. Only the user changes Codex's configured agent limits.
+
+## Claude Code
+
+Create a new subagent instance for every assignment with an isolated context, in the background,
+passing the Agent tool's `effort` setting for the profile. A resumed agent retains history and is
+not a reset. Close a returned worker by stopping its background task (TaskStop) and confirm the
+stop. A process the worker started can outlive it, so services that stay up are recorded by port
+and PID from the delivery. Supply the installed skill paths and require the worker to
+load them, or use the runtime's supported skill-preloading configuration if already available.
+Do not rely on skills invoked in the parent having loaded in the child. Check its editing tools,
+permission mode and working directory. Honor any restrictions on subagents spawning further agents.
+Subagents cannot start further agents, so a programmer's blind judge goes through the relay below.
+A subagent's hand-back ends its run, but a message to it resumes the same agent: use that to return
+judge observations to the paused worker and to continue a worker stopped by a usage limit (429) or
+a network error. A long pause makes the resume re-read its whole context;
+relay promptly. A hand-back delivers one report per agent: when a relay pause used it, the packet
+tells the worker to send its final delivery as a message to the coordinator. General-purpose agents can run shells. For judges prefer an agent type whose tools
+are limited to reading files, such as a project agent definition with `tools: Read`; adding one
+changes project configuration and needs the user's yes. Without it, rely on the judge boundary.
+
+Usage limits apply to the whole account, so a 429 normally stops the coordinator conversation
+together with its worker. `SendMessage` reaches a subagent only from the conversation that
+launched it: after `/clear` or in a new conversation the subagent is absent from `ListAgents` and
+cannot be resumed.
+
+A subagent that ends its turn while its own background commands run sends a completion
+notification saying it is waiting on its own background work, with interim usage. It resumes when
+those commands finish; only its hand-back is the delivery. The user can stop a subagent from the
+interface, and the coordinator may receive no notification. Check its state with `ListAgents` and
+its metadata file, `subagents/agent-<id>.meta.json` beside the conversation transcript, which
+records `finished` and `stoppedByUser`; a killed background command's output file reads `[killed]`.
+`TaskStop` stops a worker, so it is never a status probe.
+
+## Verification and lifecycle limits
+
+The programmer is the implementation owner, including ordinary visual captures and measurements.
+If perceptual verification needs a fresh blind judge and the worker cannot create one, it can
+send the coordinator the anonymized judge packet from denisco-visual-check. The coordinator may relay
+that packet to an independent read-only judge and return its observations while the programmer
+retains ownership. The worker pauses for the relay instead of ending its assignment; the
+coordinator resumes that same worker with the observations. Only when resuming is unavailable does
+the judgment become residual work for a new worker. This is verification delegation, not parallel
+implementation. The judge gets no implementation transcript. Record actual native parentage
+separately from operational roles.
+If this capability or a slot is unavailable, retain the verification gap and request the existing
+user-review/waiver options; do not claim an independent judgment occurred.
+
+Before dispatch, check that the runtime can retire/release workers or has enough available
+capacity for the next assignment. Do not hard-code a universal slot limit. A runtime without
+usable status or communication may support bounded completion but not safe interruption: state
+that limit and never start a replacement while the old worker may still be writing.
+
+## Telemetry
+
+Coordination requires no live context counter. When a trustworthy per-worker occupancy observation
+is already exposed, it can inform conservative sizing; record its source and observation time.
+Unknown occupancy stays unknown. Benchmark totals describe cumulative usage, not context occupancy.
+No fixed token threshold, polling integration, cost estimate or model-routing table is installed.
+
+The Worker usage row takes what the runtime reports when a worker finishes. In Claude Code the
+completion notification carries `subagent_tokens`, `tool_uses` and `duration_ms`. After a message
+resume the tokens cover the worker's whole life while tool uses and duration cover only the last
+segment, an interim notification carries only the usage so far, and an interrupted or stopped run
+may report no usage at all: take the row from the final notification and mark such rows partial. Lines come from
+`git show --shortstat` of the attempt's commits. Where a runtime reports none of this, the row says unknown.
+Record provider/model/effort requested and actually observed separately in the coordination history,
+with the source of each observation. Inherited configuration is the request, not runtime proof.
+Likewise record actual fresh-instance creation rather than claiming a clear command was executed.
+
+Provider integration references, to consult when developing an adapter rather than on every task:
+[Codex subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents),
+[Codex App Server](https://learn.chatgpt.com/docs/app-server),
+[Claude subagents](https://code.claude.com/docs/en/sub-agents),
+[Claude subagent status lines](https://code.claude.com/docs/en/statusline#subagent-status-lines).