Agterm Team

---
name: agterm-team
description: Create and coordinate Codex agents in project agterm workspaces, with readable session names, task handoffs, failure recovery, and lead-owned acceptance.
---
<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->

# Agterm team

The lead owns the outcome and all failures. Delegation transfers work, never accountability. A worker's done message requests verification; it never closes the task by itself.

Read the installed agterm skill for current CLI syntax and input safeguards; if absent, use agtermctl help and do not guess commands. Read the target project's AGENTS.md and ledger.json when present. Locate and verify a checkout of oleg-koval/agents, then explicitly read roles/olko-team.md, roles/olko-engineer.md, roles/olko-qa.md and pipelines/delivery.md; read pipelines/review.md when reviewing code. Do not invent missing backbone content. Keep roles and pipelines in that repository and task automation in the skill catalog.

## Plan and create sessions

Write the problem, constraints, task ID, authority, acceptance checks, retry budget and terminal condition before assignment. Start with one developer; add workers only for independent work worth the coordination cost. Use isolated worktrees and explicit file ownership.

Inspect fresh agtermctl tree --json output. Pass --socket with AGTERM_SOCKET when set. Identify the project's existing workspace from its session working directories and repository identity, not merely the active workspace. If multiple workspaces fit and context cannot disambiguate them, ask rather than launching into a guessed workspace. Do not move or rename unrelated sessions.

Automatically create needed agent sessions in that project workspace once team orchestration is requested. Default names:

- LEAD_ISSUE_123
- SENIOR_DEV_ISSUE_123
- QA_ISSUE_123
- REVIEWER_PR_456

For work without an issue use ROLE_TASK_SHORT_SLUG. For multiple workers on one issue append _A, _B. Keep agterm names concise and stable; Codex conversation titles may describe the task more verbosely where the installed client supports naming. Never pretend agterm naming also renames the Codex conversation.

Before creating, check for a matching task session and task artifact. Reuse only a verified owned session; a matching name alone proves nothing. Record the task-to-session mapping to prevent duplicate launches after resume. Check installed session new help for workspace targeting flags. Launch Codex using session new --command with the owned worktree as cwd and the task brief as data, never by typing shell commands into another pane. Prefer no-select when supported. Do not alter sandbox, approval, model or access settings beyond the user's authority. Verify the created node belongs to the intended workspace, is realized, and has Codex as its foreground process. A returned session ID alone does not prove startup. Report startup failures without duplicate retries.

## Handoff and return channel

Prefer `codex queue --thread <codex-thread-uuid> --message <text>` when the installed client supports it. A Codex thread UUID is distinct from an agterm session UUID or paneID. Capture it from the running Codex session or supported app-server interface and verify the mapping; never guess it from terminal names. Queue success proves enqueueing, not execution: require a task-ID ACK and result. Check the local CLI help because this capability varies by version. Use terminal input only as the fallback below.


Record each participant's fresh full session UUID and stable paneID from the live tree, including the lead return address. Validate hosting environment IDs against that tree; never reuse historical IDs or target active.

Keep briefs and results in shared local task artifacts. The lead owns task-state writes; each developer owns a separate result artifact. Append timestamped evidence and messages. States: assigned, acknowledged, working, blocked, ready-for-review, accepted. Do not put transient coordination data in the shared knowledge ledger.

Every message includes task ID, message ID, type, sender/recipient session and pane IDs, and artifact path. Types: ASSIGN, ACK, QUESTION, BLOCKED, READY_FOR_REVIEW, REWORK, ACCEPTED. Assignments state outcome, ownership, worktree, base SHA, acceptance commands and authority. Results state exact SHA, files, actual check outputs, failures, unavailable checks and remaining risks.

For an existing Codex session, read its pane text and current tree first. Verify the intended process is ready for input without a user draft or approval prompt. Unknown readiness means stage a copyable relay and report blocked; never interrupt or restart another session to force delivery.

Use agtermctl session type --stdin --target <session-uuid> --pane-id <pane-id>, with socket option when needed. This injects keystrokes into a shared buffer; it is not a message queue. Send a short single-line instruction to read the brief artifact. Verify installed submission behavior; avoid multiline injection and shell interpolation. Require readback and a task-ID ACK before calling the assignment received. CLI success proves only injection. Inspect uncertain delivery before retrying to avoid duplicate work. Workers return evidence to the verified lead address using the same readiness safeguards.

## Verify and recover

The lead inspects the actual diff and exact SHA and independently runs acceptance checks. Obtain independent diff review under project policy. Verify local proof, commit, remote SHA, complete check rollup, deployment and human/device acceptance as separate gates when in scope. Accept only proven criteria; return concrete failures and evidence as REWORK.

The lead diagnoses, repairs or reassigns failures within authority and reverifies. After two identical failures stop retrying and diagnose. Exhausted budgets or missing authority end as blocked with receipts, never accepted. Delegated workers cannot expand publishing, spending or external communication authority. Further delegation preserves parent accountability.

Agterm input does not guarantee waking an idle Codex session. This skill installs no daemon. Define bounded checkpoints or supported event-driven wakeups when available; do not promise unattended monitoring. If reliable wakeup is unavailable, leave a resume instruction and task artifact path and report that limitation.

Final report says delivered, blocked or intentionally unchanged, with accepted tasks, separate evidence gates, unresolved failures and the next responsible action. Never blame a worker in place of resolving or reporting failure. Do not close agent sessions automatically; preserve their evidence for inspection.