Three kinds of agent
"Agent" means three different things in paqad. It helps to keep them apart.
- Stage agents are real, separate AI sessions (subagents) that your coding tool starts to run one stage of a change. There are six, and they are used on Claude Code and Codex CLI.
- Specialist roles are written role descriptions, such as
adversarial-reviewerorux-ui-analyst. The AI takes on a role's point of view when a stage or skill calls for it. They are instructions, not separate processes. - Spec experts are a subset of the specialist roles that the optional spec pipeline can bring in to review a request before the spec is written.
Stage agents
On the graduated and full lanes, on Claude Code and Codex CLI, each mandatory stage of a code change runs in its own fresh subagent. A subagent starts with an empty memory, does one job and hands back a short result. This keeps each stage focused and means later stages do not carry the full history of earlier ones.
| Agent | Stage | Tools it is allowed |
|---|---|---|
paqad-planning | Plan the change and record the reuse-checked plan | Read, Grep, Glob, Bash |
paqad-specification | Write and freeze the spec before any code | Read, Grep, Glob, Bash |
paqad-development | Implement the frozen spec | Read, Edit, Write, NotebookEdit, Grep, Glob, Bash |
paqad-review | Review the change and record the review | Read, Grep, Glob, Bash |
paqad-checks | Run the project checks and record the result | Read, Grep, Glob, Bash |
paqad-documentation-sync | Update the documentation the change affects | Read, Edit, Write, Grep, Glob, Bash |
paqad-ai install and paqad-ai update write these six definitions into your user folder, never into a project: ~/.claude/agents/paqad-<stage>.md for Claude Code and ~/.codex/agents/paqad-<stage>.toml for Codex CLI. The Claude Code definitions use the same model as your main session.
How a stage agent run works
- Your main chat becomes a coordinator. It routes, narrates each stage, asks you the decision-pause questions and reports the final verdict. It does not edit source code itself.
- For each stage in order, it starts the matching stage agent and passes the change reference, the lane, the previous stage's output file and its own session ID, so every record lands on the same change.
- The stage agent loads the framework and, as a feature-development stage, the project rules. It reads its stage section of
feature-development.yaml, runspaqad-ai stage start, does the work, writes its official record with the matching command (plan compile,spec freeze,review record,checks run) and runspaqad-ai stage end. - A stage agent never asks you anything. If it reaches a decision pause, it creates the decision request and returns
paused: D-<id>. The coordinator asks you, records your answer, and starts the same stage again.
The evidence bundle on disk is the only memory shared between stages. The same pre-edit gates fire inside each stage agent as in a single session.
How a skipped isolation is caught
This is a machine check. Each time a stage agent finishes, a hook appends a row to the bundle's context-efficiency.jsonl, and every stage record notes which agent wrote it (orchestrator or paqad-<stage>). On a graduated or full lane on Claude Code or Codex CLI, a change whose bundle has no context-efficiency.jsonl fails the completeness check by name. The check stays silent on the fast lane, on tools without subagents and when the lane is unknown, so it cannot fail work it cannot classify. The final receipt adds one line estimating how much history isolation avoided re-sending, labelled estimate unless the figure is exact.
There is no setting to turn isolation off; the only way is to disable paqad for the project. On the fast lane, and on Gemini CLI and the IDE tools, the stages run in the main session as before.
Specialist roles
paqad ships 25 role files. Each file has the same sections: purpose, model tier, tools, inputs, instructions and the shape of its output. Keeping roles narrow means each one looks at the change from a single angle, for example the adversarial reviewer tries to break the finished change while the gap detector looks for what was never specified.
| Pack | Roles |
|---|---|
| Base (11) | router, requirement-analyst, gap-detector, market-researcher, product-owner, story-designer, test-planner, context-curator, adversarial-reviewer, verifier, final-reviewer |
| Coding (13) | solution-architect, data-modeler, database-expert, integration-architect, performance-analyst, ux-ui-analyst, user-flow-writer, qa-engineer, devops-engineer, chief-architect, doc-maintainer, app-cartographer, journey-designer |
| Security (1) | security-auditor |
The model tier (fast, standard or reasoning) is a hint about how much thinking the role needs. It maps to the model names in your project profile's model_routing settings; whether a particular model is actually used depends on your tool.
Role files resolve in layers like other paqad artifacts: base, then the active capabilities and matching stack packs. A file in a more specific layer replaces one with the same name in a less specific layer. See Pack precedence.
Spec experts
When the spec pipeline and its experts are switched on (spec_pipeline_enabled and spec_pipeline_experts_enabled, both off by default), the pipeline can bring in experts before the spec is written. Eleven roles are eligible: db-expert (the database-expert role), data-modeler, security-auditor, ux-ui-analyst, performance-analyst, integration-architect, solution-architect, devops-engineer, market-researcher, user-flow-writer and qa-engineer.
- AI judgement: a skill reads the request and decides which experts, if any, are needed. Choosing none is common and costs nothing. Each chosen expert writes short notes, and
chief-architectthen accepts or declines each finding and recommends how to settle conflicts. - Machine check: a script rejects any role outside the eleven, so the AI cannot invent an expert.
- Your decision: every conflict between experts becomes a decision pause for you. The chief architect recommends; it never applies its own recommendation.
The full sequence is described in From plan to frozen spec.