# AI.conf

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

```bash
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:

```bash
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:

```bash
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](SETTINGS.yaml) for runtime policy (filesystem, approvals, network, model intent)
- [TEAM.yaml](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](spec/agent-runtime-v1.md) and described by [schemas/agent-runtime.schema.json](schemas/agent-runtime.schema.json). Team inventory is documented in [spec/team-protocol-v1.md](spec/team-protocol-v1.md). `generate.sh` derives tool-specific outputs for both Claude Code and [OpenAI Codex CLI](https://github.com/openai/codex).

### 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:

```yaml
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](SETTINGS.yaml)
- Runtime schema: [schemas/agent-runtime.schema.json](schemas/agent-runtime.schema.json)
- Runtime spec: [spec/agent-runtime-v1.md](spec/agent-runtime-v1.md)
- Team/inventory spec: [spec/team-protocol-v1.md](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:

```yaml
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.