agent-team/README.md

agent-team

A portable agent team configuration for Claude Code and Codex CLI. Clone it, run the flake entrypoints or the just wrapper, and both tools get a full team of specialized subagents and shared skills on any machine.

Quick install

git clone <repo-url>
cd agent-team
nix develop              # enter devShell with yq + envsubst
nix run .#check          # validate protocols + generate artifacts
nix run .#install        # install into your Claude/Codex config dirs

The supported user-facing entrypoints are the flake apps and the just wrapper. generate.sh and install.sh remain the internal implementation layer behind them. Works on Linux, macOS, and Windows (Git Bash).

Nix entrypoints

The flake exposes formal workflow entrypoints:

nix run .#validate   # syntax + protocol presence/basic shape checks
nix run .#build      # generate settings.json + claude/ + codex/
nix run .#check      # validate + build
nix run .#install    # run install.sh
nix flake check      # run flake checks (validate + build in sandboxed check derivations)

just is also supported as a convenience wrapper over those same flake commands:

just validate
just build
just check
just install
just clean          # removes generated artifacts: settings.json + claude/ + codex/

generate.sh and install.sh are kept as internal implementation details for portability and debugging, but they are no longer the primary documented workflow.

Maintenance

Symlink fragility: the generated Claude files are installed as symlinks by install.sh. Some tools (including Claude Code itself when writing settings) resolve symlinks to regular files on write, silently breaking the link. If edits to the repo are no longer reflected in your Claude config dir, re-run ./install.sh to restore the symlinks.

Agents

Agent	Model	Role
worker	sonnet (haiku/opus by orchestrator)	Universal implementer. Model scaled to task complexity.
debugger	sonnet	Diagnoses and fixes bugs with minimal targeted changes.
documenter	sonnet	Writes and updates docs. Never modifies source code.
architect	opus	Triage, research coordination, architecture design, wave decomposition. Read-only.
researcher	sonnet	Parallel fact-finding. One instance per research question. Read-only.
reviewer	sonnet	Code quality review + AC verification + claim checking. Read-only.
auditor	sonnet	Security analysis + runtime validation. Read-only, runs in background.

Skills

Skill	Purpose
orchestrate	Orchestration framework — load on demand to decompose and delegate complex tasks
conventions	Core coding conventions and quality priorities shared by all agents
worker-protocol	Output format, feedback handling, and operational procedures for worker agents
qa-checklist	Self-validation checklist workers run before returning results
message-schema	Typed YAML frontmatter envelopes for all inter-agent communication
project	Instructs agents to check for and ingest a project-specific skill file before starting work

Rules

Global instructions are modularized in rules/ and auto-loaded by Claude Code from the installed Claude config on every session. Each file covers a focused topic (git workflow, Nix preferences, response style, etc.). Agent-team specific protocols live in skills, not rules.

How to use

Claude Code

Load the orchestrate skill when a task is complex enough to warrant delegation:

/skill orchestrate

Once loaded, Claude acts as orchestrator — decomposing tasks, selecting agents, reviewing output, and managing the git flow. Agents are auto-delegated based on task type; you don't invoke them directly.

For simple tasks, invoke an agent directly:

/agent worker Fix the broken pagination in the user list endpoint

Codex CLI

Agents are available as named agents in the installed Codex config. Invoke them with:

codex --agent worker "Fix the broken pagination in the user list endpoint"

Dual-target generation

This repo uses two authored protocol files:

• SETTINGS.yaml for runtime policy (filesystem, approvals, network, model intent)
• TEAM.yaml for team inventory metadata (agents, skills, rules)

Long-form instructions remain authored in Markdown (agents/*.md, skills/*/SKILL.md, rules/*.md).

Runtime policy is documented in spec/agent-runtime-v1.md and described by schemas/agent-runtime.schema.json. Team inventory is documented in spec/team-protocol-v1.md. generate.sh derives tool-specific outputs for both Claude Code and OpenAI Codex CLI.

What gets generated

Source	Generated	Location
TEAM.yaml + agents/*.md	claude/agents/*.md	Claude config dir
TEAM.yaml + agents/*.md	codex/agents/*.toml	Codex config dir
SETTINGS.yaml	settings.json (compatibility artifact, generated)	repo root
SETTINGS.yaml	claude/settings.json	Claude config dir
SETTINGS.yaml	codex/config.toml	Codex config dir
TEAM.yaml + rules/*.md	codex/AGENTS.md	Codex config dir
TEAM.yaml + skills/*/SKILL.md	installed skill dirs	installed skill dirs

All final config files are generated artifacts. The authored protocol sources are SETTINGS.yaml, TEAM.yaml, and Markdown instruction content. The primary workflows are nix run .#build / nix run .#install or the equivalent just commands.

Narrow compatibility caveats:

• TEAM schema is intentionally rigid/repo-specific in v1. Inventory changes require schema updates in lockstep.
• Claude generated agent frontmatter is normalized by generator serialization (field order/quoting), which may produce non-semantic diffs.
• Codex skill installation is TEAM-authoritative when TEAM.yaml is present. Legacy directory fallback is used only when TEAM is absent or unparseable.

Shared runtime intent is generated conservatively across tools:

Shared source	Claude Code	Codex CLI
runtime.filesystem = read-only	permissions.defaultMode = "plan"	sandbox_mode = "read-only"
runtime.filesystem = workspace-write	permissions.defaultMode = "acceptEdits"	sandbox_mode = "workspace-write"
runtime.approval = manual	partially represented	approval_policy = "on-request"
runtime.approval = guarded-auto	partially represented	approval_policy = "untrusted"
runtime.approval = full-auto	partially represented	approval_policy = "never"

Codex does not support Claude's per-tool allow / deny / ask patterns directly. The shared protocol keeps the intent portable, then adapters derive the closest target behavior. Use target-specific fields only where there is no shared equivalent:

targets:
  codex:
    approval_policy: untrusted
    network_access: false
  claude:
    claude_md_excludes:
      - .claude/agent-memory/**

Shared protocol

The protocol source is YAML because it is easier to read and annotate than JSON or TOML while still being easy to validate with JSON Schema.

• Runtime policy: SETTINGS.yaml
• Runtime schema: schemas/agent-runtime.schema.json
• Runtime spec: spec/agent-runtime-v1.md
• Team/inventory spec: spec/team-protocol-v1.md

The protocol is intentionally small in v1:

• portable model tier and reasoning level
• filesystem access intent
• approval intent
• network access
• portable tool classes
• protected paths
• dangerous shell command prompts
• limited target-specific escape hatches

Example:

version: 1

model:
  class: balanced
  reasoning: medium

runtime:
  filesystem: workspace-write
  approval: guarded-auto
  network_access: false
  tools:
    - shell
    - read
    - edit
    - write
    - glob
    - grep
    - web_fetch
    - web_search

safety:
  protected_paths:
    - ~/.ssh/**
    - ~/.aws/**
    - ~/.gnupg/**
    - "**/.env*"
  dangerous_shell_commands:
    ask:
      - rm *
      - git reset --hard*
      - sudo *

Model mapping

Claude Code	Codex CLI
opus	gpt-5.4
sonnet	gpt-5.3-codex
haiku	gpt-5.1-codex-mini

Template variables

Agent body text uses ${VAR} placeholders that are expanded per-target by generate.sh:

Variable	Claude	Codex
${PLANS_DIR}	.claude/plans	plans
${WEB_SEARCH}	via WebFetch/WebSearch	via web search
${SEARCH_TOOLS}	Use Grep/Glob/Read	Search the codebase

Skills and rules are tool-agnostic and shared as-is — do not add tool-specific references to them.

Project-specific config

Each project repo can extend the team with local config in .claude/:

• .claude/CLAUDE.md — project-specific instructions (architecture notes, domain conventions, stack details)
• .claude/agents/ — project-local agent overrides or additions
• .claude/skills/project.md — skill file that agents automatically ingest before starting work (see the project skill)

Commit .claude/ with the project so the team has context wherever it runs.

Memory

Two memory systems coexist:

• Manual memory (.claude/memory/) — curated context files with YAML frontmatter, indexed by MEMORY.md. Loaded as part of the CLAUDE.md hierarchy on every session. Use this for project decisions, user preferences, and reference pointers.
• Agent memory (.claude/agent-memory/) — Claude Code's built-in runtime memory, written automatically by agents with memory: project scope. Excluded from CLAUDE.md context via claudeMdExcludes to avoid polluting the context window.

Commit both directories with the repo so memory persists across machines and sessions.