scrum-control

Files (1)

• SKILL.md

SKILL.md (first lines)

Managed profiles may save an optional `model` via agent_manage create/update with a human actor. Blank uses the provider default; explicit IDs/aliases pass as `--model` on the next authorized run, without restarting current work. Syntax errors are immediate; unavailable models surface provider errors in Agents/Chat. No catalog probing, paid discovery calls or automatic substitution occurs. Claude initialization metadata is compared for exact IDs; aliases may resolve dynamically. See [scrum-agents](../scrum-agents/SKILL.md).

Use cached project/folder identity. Inspect agent_status only on demand; web Agents and green task dots show recent cooperative heartbeat plus live claim, not OS proof. An expired/stale heartbeat is not an actively verified worker. Preserve distinct persistent identities for simultaneous workers.

Bridges call worker_launch in code before invoking a model. No eligible unreserved work means skip inference and record the reason in Chat. Atomic ten-minute startup offers prevent duplicate launches for one task or overlapping planned files. These offers grant no editing ownership; review retrospective/own locks and claim the suggested task normally. Other work selection respects pending offers. Offers release after the run or failure/Stop/disconnect and expire after crashes. Idle bridges perform no model polling; retry requires another authorized Start/Wakeup or eligible opted-in quota reset.

For human-requested Stop/Wakeup call project_control(project,actor=<existing human>,action=stop|wakeup,reason?). Stop blocks new agent work immediately; it does not forcibly free another agent's files. Desktop sessions must reach an agent_checkpoint and stop editing before their own cleanup. Wakeup restores the saved enabled managed-agent set, preserving identities, roles and clients. If no profiles or manual bridge exist, it creates/reuses one default Codex profile. Starting a bridge does not prove a model is running: fresh quota and normal task/file claims still apply. This control does not resume arbitrary desktop chats.

An opt-in external bridge can receive the signal without model polling. From the Scrum Studio installation run `python scripts/agent_bridge.py --project ID --client codex --worker NAME --allow-run`, or client claude with --usage-file ABSOLUTE_JSON from the Claude status-line adapter. Start only when the human authorizes running that CLI worker, not merely to inspect status. Use a unique NAME for each simultaneous bridge. Startup consumes no old Wakeup; the human must click/send a new Wakeup after connection. The bridge starts only its own configured CLI under existing permissions; Stop interrupts that process group and then records a handoff. It never stops unrelated desktop processes. Do not launch a bridge to bypass account limits or sandbox restrictions.

Wakeup starts disconnected profiles marked resume_on_wakeup; individual Stop clears that flag, and explicit Start enables it again. Saved roles are reused; missing desktop conversations are not reconstructed. Claude restart requires confirm_client_account=true and explicit authorization of that configured account; otherwise report authorization_required and open Agents for confirmation. Never silently switch a Claude profile to Codex. A fresh empty project uses Codex by default. Do not trigger real provider runs merely to test this feature.

Inspect `project_control`'s `launches` and `wakeup` result or `agent_status.wakeup`: they report launch requests/errors, connected/ready/running/held bridge counts, quota hold reasons and a next step. signal_recorded/starting are not proof of model execution. Existing connected bridges receive the signal without another process. Restored managed bridges use an immediate-start request and do not need another click. Use start_agents=false only when explicitly requesting the previous signal-only behavior; manually connected bridges still ignore old signals on startup and need a fresh Wakeup. The web keeps readiness visible without model polling or additional API calls.

A connected bridge posts its exact continuation instruction and bounded final CLI response to project Chat using its worker actor; held/failed/interrupted runs are marked. This is not the Desktop conversation. Each Wakeup starts a new CLI run that resumes task context via MCP; it does not attach an existing Desktop thread. Full tool/reasoning logs remain local. Use fresh Claude usage telemetry and explicit account authorization; compatibility support alone does not authorize launching that account. Chat notifications are best-effort and never replace task status/evidence or pause cleanup.

Managed Codex workers and quota reads use the same installed runtime: SCRUM_CODEX_EXECUTABLE overrides discovery; otherwise prefer the Desktop app's bundled executable, then PATH. No download or model substitution occurs. A failed run exposes its exit code and bounded provider error in Agents, readiness and Chat; a connected failed bridge is not ready work. Wakeup authorizes claiming existing eligible pending work, verification and continuing to the next task until no eligible work remains or a real stop condition applies.

See [core guidance](../scrum-work/references/core-guidance.md) for shared task and batch semantics. The continuation instruction includes the worker's absolute Python executable for bounded stdio MCP access; quota is refreshed by the supervisor, without worker startup probes. Use it when the worker sandbox has no `python` on PATH; this requires no installation or policy bypass.

Managed Codex runs request approval through the automatic reviewer while retaining workspace-write. This avoids noninteractive exec's default `never` rejecting every approval-required MCP call. Reviewer rejections and managed policy still apply; never switch to full access or use alternate transport to evade a rejected operation.

The supervisor supplies its actual quota reading and original observation timestamp in the startup instruction. Pass those measured fields to work_start while fresh; later agent_checkpoint can check the same actor's supervisor-refreshed telemetry without inventing values. Serialize approval-required calls and resolve each pending approval before starting another; concurrent requests can cancel each other.

Start/Wakeup authorizes routine Scrum work coordination. Managed Codex preauthorizes only its enumerated Scrum work tools for that run (startup, task selection/claims/updates/completion, checkpoints, file reservations and authored notes/chat). This does not preauthorize user/project/agent administration, arbitrary MCP servers, shell/network access or settings changes. Global client configuration remains unchanged; task ownership, quotas and server validation remain enforced.

The run-local `scrum-worker` permission profile extends `:workspace` and grants read access only to the installed Codex/agent skill directories and selected worker Python runtime (the existing desktop bundle on Windows when available). This permits required skills and Python execution in Windows sandboxes without granting write access to those locations or reading the entire Codex home. For Unity projects on Windows only, the profile additionally grants write access to the exact user Unity/Caches folder needed at Editor startup; it never grants write access to the Python installation or all AppData. Managed permission restrictions continue to apply.

Stop handoff: the bridge confirms its CLI has exited before cleanup. Each claimed task returns to TODO with one bounded continuity summary of recorded progress and the next step. Checklist, acceptance, planned files and evidence remain in their task fields. Own task/file locks are released; concise Chat/activity references locate that continuity without copying it. No note is generated. No automatic Daily or Retrospective is written. Captured final text is for human Chat only and is not copied into task continuity; never invent missing progress. Existing records are reused without another model call. Stop does not mark work Done. Repeated pause without claims adds no notes.

For named agents managed from the website or MCP, use [scrum-agents](../scrum-agents/SKILL.md). agent_manage creates local profiles from a name and optional role, starts immediately by explicit creation default, and provides per-profile start/stop. Creation is human-authorized execution; testing the feature alone does not authorize provider runs. Manual bridge connection continues to wait for a fresh Wakeup.

Cost control: project_settings(max_parallel_agents=1..20) is human-only, default one. Atomic startup offers and actual claims share this project capacity; the same actor may resume its current work. Additional workers defer without model inference. Lowering the limit leaves active work intact and prevents new actors until capacity is free. The supervisor holds/renews its slot until process-exit cleanup, even if the worker has released its task. Existing quota/WIP/file ownership rules still apply. Never increase this limit to bypass a hold without human authorization.


The supervisor collects structured CLI usage from existing logs on completion/interruption and sends it in its existing checkpoint. CLI execution UUIDs deduplicate cleanup callbacks. No extra model/usage polling is introduced. Inspect measured counters only on demand through coordination_metrics(include_cli_usage=true); shared batch totals must never be attributed in full to each member.


Idle transport: the supervisor checks a local control-change marker every two seconds, sends heartbeat checkpoints at most once per minute while waiting and every ten seconds during a run, and checks immediately on control/process transitions. Connected means a heartbeat within 90 seconds waiting / 30 seconds running, not proof of an OS process. Missing notifications fall back to the periodic checkpoint. Idle supervisors reuse cached provider observations and do not repeatedly probe quota unless starting/running or opted into quota autoresume. Web refresh uses conditional page responses; unchanged browser polls do not fetch task snapshots. These local operations are not model tokens.

Installed Unity test recovery uses `scripts/unity_verify.py --editor INSTALLED_EDITOR --project UNITY_ROOT [--filter TEST_NAME]` through normal reviewed tool execution when per-user licensing IPC/cache is inaccessible. It runs once with a bounded timeout, unique Logs XML/log paths, classifies final compiler errors ahead of earlier license warnings, and requires executed passing tests plus a successful process. It never changes licensing or permissions, retries silently, or kills shared Hub/licensing clients. An actual unresolved impediment is recorded as Blocked; after CLI exit the supervisor can select other eligible work without retrying the blocked task. Stop/quota and reservations still gate every launch.

Managed Codex uses its installed app-server protocol for native approvals and questions. The existing supervisor retains Stop/quota/claim control. project_settings(agent_approval_mode="Auto review"|"Ask in chat") is human-only; automatic review never self-approves in SCRUM. Human responses are returned only to the exact live native callback. Chat checks while visible and pending-decision polling are local HTTP/stdio operations, not model turns; idle agents do not poll interactions.

Codex project permission modes: `Auto review` reviews sandbox escalation requests; `Ask in chat` routes real requests to human buttons; human-selected `Full access` launches workers without local sandbox restrictions or permission prompts. Full access does not override organization/OS restrictions, Stop, quota policy, task dependencies or reservations. Do not change a project to Full access without explicit human authorization. If a blocked task leaves dirty files on its branch, preserve them: do not stash, discard or commit unrelated edits to switch branches. Use isolated Worktrees when authorized, or report the checkout blocker with the saved continuity. Only checked prerequisites count; Done prerequisites permit execution.

Exit code 0 is not task completion. The supervisor checks the owned task, including TODO handoffs with saved continuity, before releasing the session and allows one automatic closure recovery per unfinished task in that supervisor lifetime. It preserves the final worker response in continuity, targets the same task through normal reservations, and respects Stop/quota/profile policy. A repeated incomplete exit stops for diagnosis instead of launching an inference loop. This behavior requires a supervisor launched with the updated code.

Worktrees transition recovery: if the task branch is already checked out in the canonical project folder and no managed mapping exists, claim preparation can reuse that folder without switching branches or creating a duplicate checkout. Dependencies and live claims still apply. The canonical folder is never registered for managed-worktree cleanup. Preserve existing edits/staging; do not force a duplicate branch checkout. New branches continue to use isolated worktrees.

Human-only agent_followup_tasks=true enables necessary autonomous recovery/prerequisite planning within the authorized outcome (default false). The web exposes the same option. The supervisor can register/reuse one scoped Git recovery task when real checkout or Git preparation errors prevent any model launch; it does not start models while idle, bypass Stop/quota, overwrite human changes or retry an unchanged failure endlessly. Use the same context_group for a prerequisite that must reuse the current branch and partial edits.

Native lifecycle checkpoints use `automatic=true` for verified task-session closure and supervisor quota handoff. This preserves opted-in continuation through a quota reset; ordinary pause/offline still cancels it. Actual fresh provider quota establishes a hold, never message text alone. Project Stop, individual profile Stop/deletion, manual pause and disabled autoresume remain authoritative. No model polling or new timer is added.

From martiin3d/scrumstudio, MIT.

More from martiin3d/scrumstudio