Roles

A role is a markdown file that gives an agent its identity. It defines what the agent is responsible for, what files it should read and produce, what boundaries it must respect, and how it should hand off work. When the orchestrator activates an agent, the agent’s first instruction is to read its role file — everything else follows from there.

Roles are the single most important lever you have over agent behavior. A well-written role produces focused, predictable work. A vague role produces wandering, inconsistent output.

Where Roles Live

Roles exist in two places:

Location	What it is
`<team>/roles/<phase>.md`	The source role, inside the team package (in `~/.cliqrc/teams/` or your development directory)
`.cliq/roles/<phase>.md`	The deployed copy, inside your project (created by `cliq assemble`)

When you run cliq assemble @cliq/hello-world, cliq copies the team’s roles/ directory into .cliq/roles/. At runtime, agents read the deployed copies — not the source. This means your project is self-contained after assembly.

Every non-exec phase in the workflow must have a matching role file. The file name matches the phase name: if the phase is called developer, the role file is roles/developer.md. cliq req validates this and errors if a role is missing.

How Agents Read Roles

The cliq agent SDK reads the role file automatically and includes it in the context passed to the implementation. For CLI agents (Cursor, Claude Code, etc.), the SDK assembles a prompt that includes the full role brief along with input channel content, requirements, and task board state:

You are the developer agent.

## Role

[full contents of .cliq/roles/developer.md]

## Requirements

[req_spec.md content]

## Task Board

[current task board]

## Context from Prior Phases

### From tester
[tester channel content]

## Your Task

Complete your work as described in your role.
All coordination and handoff is handled automatically.

The implementation receives pure task context — no .cliq/ paths, no signal instructions, no channel directories. The SDK handles all protocol interactions: reading role files, reading channels, writing output channels, updating the task board, and signaling completion.

For custom agents built with the SDK, the role content is available directly as ctx.role in the execute function.

You can see the role files at .cliq/roles/<phase>.md after running cliq assemble.

What Goes in a Role

Role files are plain markdown with no required schema. But well-written roles follow a consistent structure. Here are the sections you’ll find in most roles from official teams:

Title and identity

# Role: Developer Agent

You are the **Developer** for this project. You implement code to make
the Tester's failing tests pass. This is the **Green** phase of TDD.

One or two sentences establishing who the agent is and what its primary mission is. Be specific — “you implement code to make tests pass” is better than “you write code.”

Responsibilities

A numbered list of the agent’s core tasks, in execution order:

## Your Responsibilities

1. **Check for gate context** — If `.cliq/gate_context.md` exists, read it FIRST.
2. **Read the architect's design** — Study the design doc in `.cliq/design/`
3. **Read incoming channel handoffs** — Check your incoming channel(s)
4. **Implement source code** — Write the minimum code to make ALL tests pass
5. **Run tests as you work** — Use tests to guide your implementation
6. **Update the task board** — Mark your tasks as you complete them

Boundaries

Explicit statements about what the agent does and does not do. These prevent agents from stepping on each other’s work:

## Your Boundaries

- You **DO** create/modify: source files in `src/`
- You **DO NOT** modify: test files in `tests/` — the tests are the spec
- You **DO NOT** modify: architect's design docs or interfaces
- You **MAY** add: additional source files not in the original plan

The DO / DO NOT / MAY pattern works well. Without explicit boundaries, agents will “helpfully” edit files that belong to other roles.

Workflow steps

A concrete sequence the agent should follow — the operational heart of the role:

## Workflow

1. Read the task board — find your assigned tasks
2. Read the architect's design doc in `.cliq/design/`
3. Read incoming channel handoffs for tester's notes
4. Run the test suite to see all failing tests
5. Implement code following the design
6. After each file, run relevant tests to check progress
7. Update the task board — mark your tasks DONE
8. Write handoff notes to your outgoing channel(s)

Domain-specific sections

Whatever the role needs: output templates, coding standards, review checklists, evaluation criteria. These vary by role. For gate roles, describe when to pass, route, or escalate in plain language — the orchestrator automatically injects the verdict protocol at runtime.

Quality checklist

A final self-verification step before signaling completion:

## Quality Checklist

Before signaling completion, verify:
- [ ] All interfaces are defined and exported
- [ ] File inventory is complete
- [ ] Task board updated with clear status

How to Read a Role

After assembling a team, read any role directly:

cat .cliq/roles/developer.md      # the deployed role
cat .cliq/prompts/3_developer.md   # the activation prompt the agent receives

To read the source role (before assembly), find the team in the registry or your development directory:

cat ~/cliq-teams/@cliq/feature-dev-js/roles/developer.md

How to Edit a Role

There are two levels of editing:

Quick iteration — edit the deployed copy. Change .cliq/roles/<phase>.md directly and re-run with cliq run -f. This is the fastest feedback loop: edit, run, observe. These changes are local to the project and will be overwritten by the next cliq assemble.

Permanent change — edit the source. Change the role in the team package (e.g. ~/cliq-teams/@cliq/hello-world/roles/planner.md or ~/.cliqrc/teams/@local/my-team/roles/writer.md), then re-assemble:

cliq assemble @local/my-team

You can also use the builder to refine a role with natural language:

cliq builder improve my-team --role writer --instruction "add more emphasis on storytelling"

After any source change, run cliq assemble so the deployed copy in .cliq/roles/ picks up the update.

Writing Tips

Name exact file paths. Agents follow “write to .cliq/design/outline.md” much better than “write your outline somewhere.”
Draw hard boundaries. Without DO NOT statements, agents will modify files that belong to other roles.
Mention predecessors. The activation prompt lists incoming channels, but the role should explain what to expect from each predecessor so the agent knows what to prioritize.
Include output templates. When a role produces structured artifacts, showing the expected format dramatically improves consistency.
Handle re-engagement. If a gate can route work back to this agent, tell it to check .cliq/gate_context.md first. Otherwise it repeats its original work instead of addressing feedback.
End with a checklist. A quality checklist reminds the agent what “done” looks like.

For a complete tutorial on writing roles from scratch, see Team Development.

Debugging

Agent ignoring instructions? Read .cliq/roles/<name>.md — is the right role deployed? Then read .cliq/prompts/ — is the activation prompt wiring it correctly?

Agent overstepping? Strengthen the Boundaries section with explicit DO NOT statements.

Wrong output format? Add a template to the role showing the exact structure you want.

Agent not reading handoffs? Mention what to expect from predecessors in the role file, not just in the activation prompt.

Agent confused after re-engagement? Add “check .cliq/gate_context.md first” to the top of the responsibilities list.

Role not found during cliq run? Every non-exec phase needs a matching file in .cliq/roles/. Re-run cliq assemble or check the team package.