Agents & subagents

Alfred ships with one primary agent and five subagents. Each has a single responsibility, a declared mode, and a deterministic scope. Source-of-truth lives in .ai/agents/.

The panel

orchestrator — primary

The only primary agent. Loads the architecture kernel, classifies incoming tasks, and delegates to subagents. Owns the trace stream and the eval gate.

Inputs: user prompt, kernel, project signals.
Outputs: task classification, delegation decision, final synthesis.
May not: modify AGENTS.md, broaden its own permissions, or skip evals.

developer — subagent

Coding tasks inside the architecture kernel. Reads and writes code, skills, and adapters. Always diffs before committing.

qa — subagent

Authors eval cases, runs the eval runner, owns the baseline file, blocks regressions. Never declares a change done without a regression-safe eval result.

librarian — subagent

Owns AGENTS.md, docs/, and skill activation. Lazy-loads skills by trigger and project signal.

architect — subagent

DDD boundaries and hexagonal ports. Refuses PRs that leak adapter imports into packages/core or that weaken the kernel invariants.

reviewer — subagent

Policy enforcement and release readiness. Compares every change against a baseline. Signs off releases.

Temporary specialists

Beyond the panel, the orchestrator can spawn temporary subagents for one-off jobs: write a migration, generate fixtures, run a single benchmark. Temporary agents:

Are scoped to a single TaskClassification.
Retire when the task is done.
Cannot promote themselves to permanent agents.
Require a human approval trace to be reused.

Promotion requires a human. A temporary agent that proves useful becomes a candidate. A human reviews the trace, the evals, and the prompt diff, then either merges it into .ai/agents/ or lets it retire.

Authoring a new permanent agent

Add a spec under .ai/agents/<name>.md with frontmatter: id, mode (primary / subagent), description, owner.
Generate a harness preview with the relevant adapter package to see the generated agent file.
In the Alfred source repo, run cd packages/evals && npm run test. All existing evals must remain regression-safe.
Author at least one new eval case in .ai/evals/cases/ that exercises the new agent.
Open a PR. The architect and reviewer subagents will validate.