plumbline-agent-team

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Agent Team

This skill is explicit only. It is the project-local team setup and audit boundary. Determine the active host, then read `AGENTS.md`, `CLAUDE.md` when Claude Code is the host, the host's project-local agent directory, relevant host settings, `.gitignore`, `.git/info/exclude`, `.worktreeinclude`, and established agent conventions before proposing changes. Keep discovery targeted; do not enumerate the whole repository.

## Non-negotiable scope

The host adapter is explicit:

- Codex uses only project-local `.codex/agents/*.toml` and `.codex/config.toml`. Current Codex releases enable subagents by default; set or verify `agents.enabled = true` only when the project records that intent explicitly. Recommend `agents.max_concurrent_threads_per_session = 12` as an adjustable starting value and preserve an approved alternative such as 6. Offer an approval-gated migration for legacy `features.multi_agent`, `agents.max_threads`, or `agents.max_depth` entries. A role's explicit `model` field selects its model, including a legacy-compatible leaf worker; Plumbline does not force a v1 delegation path.
- Claude Code uses only project-local `.claude/agents/*.md`. Claude has no required Plumbline project config switch; Markdown frontmatter carries `model`, `effort`, `tools`, and `permissionMode`. Do not edit global Claude settings or enable `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`; Plumbline uses bounded subagents, not the separate experimental Agent Teams feature. Claude reads `CLAUDE.md`, not `AGENTS.md`, so when shared guidance is kept in `AGENTS.md`, add the supported `@AGENTS.md` import to `CLAUDE.md` rather than duplicating the guidance. Claude discovers role files from the project, and the first creation of a new `.claude/agents/` directory may require a fresh session; later edits are hot-reloaded.

The global Codex config may be inspected for host capability and the current main model candidate, but personal/global agent files are never selected, copied, or used as fallbacks. Do not edit global settings, install a global team, or delete an old competing role.

A depth of one is a recommended delegation boundary, not a host setting Plumbline enforces. Claude applies the same recommended behavior by omitting the `Agent` tool from generated roles and stating it in every role prompt. Every worker instruction must say it cannot spawn children, own Git, or edit the active spec/plan. This main-mediated rule means every worker returns to the main thread; worker recommendations are advisory, and only the main thread selects and dispatches the next capability. Generated guidance must keep the orchestrator thin: delegate bounded read-heavy or otherwise useful discovery before broad repository search when a matching role can materially reduce main-thread context or improve quality, request a compact decision packet, and prevent the main thread from repeating worker exploration. When independent work is ready, the main thread may dispatch one parallel wave only after a stable contract, disjoint scopes, no result dependency, and a clear join condition are established. Give each worker only the exact read paths and anchored sections needed for its brief; do not pass full history or whole documentation trees when unchanged artifacts answer the question. Report-only roles (researcher, architect, code-reviewer, and QA) receive no write set. Codex `sandbox_mode = "read-only"` and Claude `permissionMode: plan` are intent; a writable or permissive parent may affect effective permissions and effective sandbox. Emit one compact dispatch line with role, configured model/reasoning or effort, and assignment; standard boundaries and routine status narration are omitted unless an exception matters. Inspect returned diffs; each approved write-capable role receives only its bounded write set.

Before each material action, classify it as semantic implementation, focused
validation, or administrative-only bookkeeping. Advance implementation and
focused validation first; skip or batch administrative-only work unless it
protects product integrity, input or revision identity, recovery, authorization
or ownership, singleton or duplicate prevention, or a user-requested artifact.
Delegate only when an approved role's expected quality or context value exceeds
startup, briefing, reporting, and integration cost. `direct` and
`not-applicable` are valid delegation states, not telemetry obligations.

Observe active workers through bounded host-native waits or snapshots rather than
repeated root turns with unchanged state. Continue independent work; report a
required nonterminal worker as `INCONCLUSIVE` or `Blocked` with the last
observation and leave it active for reconciliation. Optional workers never block
forward progress. This is execution guidance, not scheduler policy.

Role profiles are reusable; worker instances are disposable. Retire a worker
after a terminal result and use a fresh instance for a new checkpoint, correction,
failure, or acceptance task, even when selecting the same role. A follow-up is
only for the exact same unfinished assignment when continuity materially helps;
all new work gets a fresh instance. Use the host's no-history fresh-child path:
Codex `fork_turns="none"` when exposed, or
`multi_agent_v1__spawn_agent` with `fork_context=false` when selecting a named
`agent_type`. `fork_context=true` is a full-history fork, not a fresh-child path;
it must omit `agent_type` because full-history children inherit the parent agent
type and the router rejects that pair. If only full-history spawning is
available, omit `agent_type` and report the capability gap rather than retrying
the invalid combination. Never kill an active worker because it is quiet or
compacting.

Treat project-local role files and applicable host config as live dispatch inputs. Before each delegation wave, reread the selected files. A changed profile is a profile refresh: it updates the model, reasoning/effort, sandbox/permission, or instruction values used by new workers; it does not invalidate prior evidence or retune workers already running. If a role is missing in a worktree, refresh only the ignored project-local team files from the source checkout through the repository's propagation convention, reread them, and use `Direct: <reason>` only if the role is still unavailable. Never use global roles or copy secrets, dependencies, or source trees.

Worker reports cannot override lifecycle invariants. The main thread applies
`references/qa-audit.md` before assigning remediation; `CHANGES_REQUIRED` alone
does not reopen the same candidate checkpoint. A confirmed acceptance failure
reopens it; an inconclusive, environment, or harness result
blocks it only when safe progress cannot continue beyond a bounded Diagnose
repair. Severity alone cannot abandon the objective or select a successor objective;
the main thread preserves the candidate and owns that decision.

## Starting model recommendation

On every explicit initialize, audit, retune, add, or update invocation, read and
apply `references/model-selection.md` in full before proposing writes. It owns
the family recommendations, role/effort split, current supported model-ID
discovery, and existing-profile/deprecation comparison for both hosts. Recommend
the latest supported Sol/Luna for Codex and Opus/Sonnet for Claude; these are
families, not slugs to write. Claude's `opus`, `sonnet`, `haiku`, and `fable`
aliases may resolve differently by host/provider; `inherit` is an explicit
user-approved alternative, never an automatic fallback.

Claude can match a role automatically from its `description`, but the main
thread should name the selected role in its bounded dispatch prompt. Use
`@agent-<role>` when an explicit one-task invocation is needed; do not use
`--agent` for a worker because that makes the selected role the main session
agent. `/tasks` shows running subagents. Keep permission and no-child
boundaries in project-local files: Claude ignores `permissionMode`, hooks, and
MCP frontmatter when an agent is supplied by a plugin, which is why Plumbline
generates project-local `.claude/agents/*.md` definitions instead.

The bundled `maintainable-code` skill is model-invoked for implementation and
review. Implementers use its implementation branch; `code-reviewer` uses its
review branch before `qa-auditor` checks acceptance, proof, and documentation.

Use the reference's role-aware families only after verifying exact current
provider-native, host-supported IDs and effort values; `sol`/`luna` are not Codex
slugs. Model and reasoning/effort choices remain
user-owned and adjustable. The installers do not call provider APIs or require
credentials; the setup proposal performs the lookup and passes the approved
values to the adapter.

Label the proposal as a recommended starting point, not a permanent team policy.
Group approved roles by exact model/effort when calling the existing adapters;
both values are required when creating or changing a profile. The adapters have
no bundled model-version fallback. Audit and retune preserve tuned values unless
the user approves a change. Evaluate cheaper settings by accepted first-pass
work and remediation cost, not nominal price alone.

## Operations

- **Initialize:** create only approved missing roles from the six shared archetypes in `templates/agents/`. On Codex, use `scripts/install_agent_team.py` for local TOML/config setup. On Claude Code, use `scripts/install_claude_agent_team.py` for local Markdown subagents; it makes no global settings change and adds `@AGENTS.md` to `CLAUDE.md` so Claude loads the shared project guidance. Generate host guidance from the selected roles. When propagation is approved, include the root `.gitignore` patch and `.worktreeinclude` in the same proposal. Existing roles require an explicit initialize replacement approval before `--replace`. If the user explicitly invokes initialization again, audit the managed host guidance and offer `--update-agents --refresh-agents` as a guidance-only update; it does not replace roles or config. An older unmarked section requires the exact dry-run plus `--replace-agents-guidance`, and only that managed section may be replaced.
- **Audit:** read-only compare project agents, the repository-local router, and current repository docs; report stale facts, router or host-guidance schema drift, a missing Claude `@AGENTS.md` import, overlap, missing boundaries, required-field gaps, model/reasoning/effort/sandbox/permission drift, and capability gaps. Audit never needs `--replace` and never writes. A detected mismatch produces a proposed refresh, not an automatic overwrite. A later explicit initialization is the consent boundary for applying an approved guidance refresh.
- **Retune / Update:** first check current model availability and deprecation under `references/model-selection.md`, including older API IDs. Preserve every existing role field unless its change is approved. Use `--fill-missing` only to add absent required fields; it never overwrites a present value. Use `--update-instructions` only when the approved proposal changes instructions. For an approved replacement, use `--update-profile` with the resolved exact host-native model and supported reasoning/effort values; this changes only those fields, not instructions or permissions. A newer recommendation alone never authorizes replacing an active approved model.
- **Add:** add one specialist only for a demonstrated need; do not create a role for every technical layer.

Before approval, resolve current model values from the active host or the
provider's official model documentation/API, then show one role-by-role table
with `name`, purpose, exact host-native model value, reasoning/effort value,
sandbox/permission intent, and write access. Mark these values as the
recommended starting profile and explain that the user can adjust or hot-swap
them later. The adapter writes explicit values for reproducible local setup,
but those values are not immutable Plumbline policy. Do not invent slugs,
substitute `sol`/`luna` shorthand for Codex, or silently downgrade a user's
choice. Apply nothing before approval.

Before asking for approval, run the host-specific candidate installer with `--dry-run --format json` and include its exact file/operation/field manifest in the proposal: `install_agent_team.py` for Codex or `install_claude_agent_team.py` for Claude Code. The dry run is read-only and does not approve or apply changes.

After approval, audit and retune output must also report router freshness and host-guidance drift without overwriting either file. For Claude, guidance drift includes a missing `@AGENTS.md` import in `CLAUDE.md`. A stale router produces a proposed refresh only; applying it requires the explicit router installer `--replace` path.

After approval, rerun the dry-run manifest; if the target changed, refresh the proposal before writing. Then rerun the host-specific installer in `initialize|audit|retune` mode. On an explicit repeat initialization, perform model discovery again and compare current project values with the resolved host values; if a refresh is approved, use `--mode retune --update-profile` with the exact selected model and reasoning/effort pair. This updates only those fields and preserves role instructions, permissions, sandbox/permission intent, and custom fields. Retune does not require `--replace`; its output reports the exact changed fields for every file. Use `--update-agents` and `--propagate` during first initialization only, when approved; use `--update-agents --refresh-agents` on an explicit repeat initialization to update only the managed host guidance section and, for Claude, its `CLAUDE.md` import. Validate every host role's required model, reasoning/effort, permission/sandbox, and no-child boundary, structurally valid user-owned host settings, host guidance and Claude import when applicable, actual project-local discovery, ignore rules, and the manifest. Report one compact delegation-wave line with selected role names and host-native model plus reasoning/effort values; include effective values only when the host exposes a meaningful difference or the user asks, and use `Direct: <reason>` when no local role is available. If a matching local role is absent, stay on the main thread or report the capability gap; never fall back to a personal/global agent. Report that `.worktreeinclude` must be committed for future worktrees and that existing worktrees need explicit refresh. Run only a bounded, read-only discovery smoke test after approval.

## Completion

An audit is complete when it reports current role fields, instruction and
boundary drift, router/host-guidance drift, and a read-only change proposal

From nickyfactz/plumbline, MIT.

More from nickyfactz/plumbline