# FlyDocs Agents

Subagents are specialized AI configurations with restricted tools for separation of concerns.

## Source of Truth

**This directory is the canonical source for FlyDocs sub-agents.** It is shipped to user projects via `flydocs init` / `flydocs update`, and seeded into the relay for delivery via `flydocs update` to existing projects.

If you see a copy of these files at a workspace root or inside an installed project, that copy is a **synced result**, not a separate source. Edit only the files in this directory; downstream copies refresh on the next sync. Do not delete this directory — the install pipeline depends on it.

The Cursor variants in `template/.cursor/agents/` are a **hand-maintained
mirror** (copied verbatim to installs by `init`/`update`, no compile step) —
edit both sides when changing a role. Frontmatter dialects differ; body
sections must match.

## Agent Registry

| Agent                  | Model   | Role                                    | Tools                                                    | Skills           |
| ---------------------- | ------- | --------------------------------------- | -------------------------------------------------------- | ---------------- |
| `pm-agent`             | inherit | Workflow, specs, issue management       | Read, Glob, Grep, Bash, WebFetch                         | flydocs-workflow |
| `implementation-agent` | opus    | Building features, fixing bugs          | Read, Glob, Grep, Bash, Write, Edit, WebFetch, WebSearch | flydocs-workflow |
| `review-agent`         | sonnet  | Code review, quality analysis           | Read, Glob, Grep, Bash                                   | flydocs-workflow |
| `research-agent`       | sonnet  | Codebase exploration, context gathering | Read, Glob, Grep, WebFetch, WebSearch                    | flydocs-workflow |

The Model column mirrors each file's frontmatter `model:` — a structural test
(`src/lib/agent-registry.test.ts`) keeps the two in sync. Aliases only
(`opus` / `sonnet` / `haiku` / `inherit`), never pinned model IDs — they age.

## Model Tiers

Tiered by task shape, not prestige — the per-file frontmatter comment carries
each justification:

- **Orchestration and judgment** (`pm-agent`) — `inherit`: runs at the
  session's model, never a cheaper tier than the conversation that delegated.
- **Open-ended code work** (`implementation-agent`) — `opus`: model quality
  shows up directly in the diff.
- **Bounded, well-specified work with a fixed output shape** (`review-agent`,
  `research-agent`) — `sonnet`: cheaper tier; the caller re-judges anything
  blocking, and wrong research is cheap to re-derive.

The `.cursor/agents/` mirrors keep `model: inherit` throughout — Cursor's
`model:` field takes concrete model slugs (which age), not tier aliases.

## Return Contracts

Every agent carries a `## Report format` section: a subagent has its own
context window, and the caller absorbs only the final message. Each contract
names what the report must contain (compact findings, verbatim test counts
where relevant, file paths touched, deviations), a length discipline, and what
must never come back (file dumps, diffs, raw logs, transcripts). Without it,
the orchestrator absorbs the transcript and the isolation buys nothing.

## Design Principles

- **Skills do the teaching.** Agent body text describes role and constraints only. Procedures, checklists, and standards live in skills.
- **Tools enforce boundaries.** PM and review agents cannot Write/Edit. Research agent cannot run commands.
- **One workflow skill, shared.** All agents reference `flydocs-workflow` for lifecycle procedures.
- **Community skills are project-level.** Behavioral/pattern skills are installed per-project via skill discovery, not bundled in agents.