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 — including team phases. 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

Team Phase Roles

Team phases also require a role file, but the role serves a different purpose: it becomes the requirements spec for the sub-team’s cliq req. There is no LLM agent reading the role — instead, the built-in team agent uses the role content directly as the specification document passed to the sub-team’s pipeline.

This means team phase roles should be written as requirement briefs rather than agent instructions. Focus on what the sub-team should accomplish, not how an agent should behave.

# Security Audit

Analyze the project at $(dirs.project) for security vulnerabilities.
Focus on:
- Authentication and authorization flows
- Input validation and sanitization
- Dependency vulnerabilities (run npm audit)

Write your findings report to $(dirs.project)/reports/security-report.md.

Template variables for team roles

Team phase roles support $(dirs.*) template variables that resolve to absolute paths at runtime.

Variable	Resolves to
`$(dirs.project)`	Absolute path to the project root (shared across all nesting levels)
`$(dirs.self)`	Absolute path to the current pipeline’s state directory (also the default `cwd`)
`$(dirs.parent)`	Absolute path to the parent pipeline’s state directory (null at top level)
`$(dirs.<phase>)`	Absolute path to a sibling team phase’s call frame

Working directory. Every agent’s cwd defaults to $(dirs.self). At top level, dirs.self equals the project root. In sub-teams, dirs.self is the call frame. This means bare relative paths in sub-team roles resolve inside the call frame — not the project root — preventing parallel team phases from colliding.

Pick the right $(dirs.*) prefix for the kind of path:

$(dirs.project) for files anchored to the project root (source files, top-level deliverables).
$(dirs.self) for orchestrator state and call-frame-local artifacts that should not leak between parallel team phases.
$(dirs.<phase>) to reach into a specific upstream phase’s call frame (e.g. consume an output produced by a sibling).

Read the source code at $(dirs.project)/src/ for context.
Write your report to $(dirs.project)/reports/security-report.md.
Store intermediate scratch at $(dirs.self)/scratch/.

cliq team validate warns about bare relative paths that should be qualified with one of these prefixes. cliq team publish blocks them by default; pass --force only when you’ve confirmed the flagged token is a false positive (e.g. prose like bold/italic).

Standard template variables like $(inputs.key), $(req_key), and $(team_name) are also available. See team.yml Reference — Template Variables for the full list.

Upstream context

When a team phase has dependencies, the upstream channel content is appended to the role to form the complete spec. The team agent combines the expanded role with any incoming handoff content, so the sub-team receives full context from predecessor phases without requiring additional configuration.

How to Read a Role

After assembling a team, read any role directly:

cat .cliq/roles/developer.md      # the deployed role

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? Check .cliq/orchestrator.log for any assembly errors.

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/ — including team phases. Re-run cliq assemble or check the team package.