Constructdocs
repo
section · guides

Agents and personas

One public persona, 28 specialists, why we made that split.

5 min read·guides / concepts / agents-and-personas

Construct presents one interface to you: a persona named construct. Behind it lives a team of 28 specialists that operate as that persona's domain experts.

The split is deliberate. You ask Construct for an outcome. Construct decides which specialist authority is needed and routes internally.

You@construct fix the login redirectconstruct personaclassifies intent dispatches to specialistsSpecialist chaintyped contracts gate checksResultsingle voice response back to you

The public persona

construct is defined in personas/construct.md. It's the only persona you address.

The persona's job is to:

  • Hold the conversation with you in one consistent voice.
  • Classify intent — is this a quick clarification, an architecture decision, a code change, a security review?
  • Dispatch to specialists according to the orchestration policy.
  • Synthesize specialist output back into a single response.
  • Enforce hard gates on any work that mutates the world (code edits, commits, pushes).

You never see the specialist chain unless you ask for it. The persona returns the result.

The specialists

28 cx-prefixed specialists live in specialists/org and specialists/prompts/cx-*.md. Each has:

  • A role — what authority they exercise (cx-architect makes trade-off calls; cx-reviewer pushes back; cx-security blocks).
  • A prompt that frames their voice and decision boundaries. Source prompts stay readable in markdown; runtime composition adds role overlays and compact operating-profile shaping when needed.
  • An optional skills allowlist — which Construct skills they can invoke.
  • A model tier — reasoning / standard / fast. Configurable per specialist.

Specialists ship pre-wired but you can add custom ones.

R&D & Research
Orchestrator
assembles the right chain
R&D Lead
slows down at the right moment
Researcher
sources every claim
Explorer
reads before concluding
Evaluator
defines what better means
Data Analyst
measures before deciding
Strategy & Product
Product Manager
user reality to deliverables
UX Researcher
guards against assumptions
Business Strategist
asks if we're building the right thing
Devil's Advocate
surfaces the argument against
Engineering
Architect
makes trade-offs explicit
Engineer
reads before writing
AI Engineer
designs for failure
Data Engineer
builds trustworthy pipelines
Platform Engineer
reduces team friction
Test Automation
bad automation is worse than none
Operations
maps dependencies and sequences
Quality & Safety
Reviewer
pushes back before it ships
QA
tests what matters
Debugger
traces to root cause
Security
thinks like an attacker
SRE
plans for failure first
Release Manager
guards the verified to safe gap
Legal & Compliance
catches risk before architecture locks
Accessibility
tests with screen reader and keyboard
Craft & Records
Designer
visual decisions are interaction decisions
Docs Keeper
owns the record of why
Trace Reviewer
fleet-level performance patterns

How the chain runs

When you ask Construct for an outcome:

  1. Intent classification. lib/orchestration-policy.mjs reads the request and your .construct/context.md and decides whether this is conversational (answer directly), exploratory (research first), or mutational (specialist chain).
  2. R&D triage (when the request arrives as a file in inbox/). The daemon classifies the signal via classifyRdIntake and writes a packet to .construct/intake/pending/<id>.json naming the primary owner persona and the recommended chain. Construct reads this with construct intake show <id> before dispatch.
  3. Gate checks. Framing gate, external research gate, doc owner gate. Each blocks the chain if its precondition isn't met (e.g., framing gate fails on a vague request — Construct asks you to clarify).
  4. Contract chain. Each specialist hands off to the next under a typed contract from specialists/contracts.json. Postconditions are checked between handoffs. A failed postcondition re-runs the producer.
  5. Role-aware context routing. Each dispatched specialist receives a context packet built by lib/context-router.mjs — per-role artifact preferences (e.g. product-manager prefers PRDs and user signals; engineer prefers target files and tests), token budget honored, reasons attached. Unrelated artifacts are omitted explicitly.
  6. Verification gates. Before the chain ends: npm test, comment lint, docs verify, contract postconditions all pass — or the chain re-runs. Worker-executed steps record evidence linked to the task graph node; nodes can't transition to done without an evidence record.
  7. Single response. Construct synthesizes specialist output and returns one answer in its voice.

Cross-platform parity

You install the SAME team across Construct's supported hosts via construct sync. The registry is canonical; sync writes the host-specific adapter shape each tool actually supports: agent adapters for Claude Code, OpenCode, and Codex; prompt profiles for Copilot; MCP registrations for VS Code/Copilot and Cursor when those configs already exist.

construct doctor runs a parity check that diffs your registry against every installed editor's adapter state. Drift is flagged with the missing/extra entries.

Why one persona, not pick-an-agent

The agent-picker pattern (where the user types @architect or @reviewer) puts cognitive load on the user. They have to know which specialist to call, what each specialist does, when to escalate. That's the wrong model for everyday use.

One persona means you ask for outcomes, not assignments. Construct routes. Directly addressing a specific specialist (@cx-security) is possible for focused one-off conversations, but the entry point is always @construct.

Reference