Roles

What it's for

A role describes a responsibility: analyzing, implementing, reviewing, checking. It does not depend on the tool. The CLI type (Claude Code, Codex, Gemini) says how the agent is started; the role says what it should do in that stage. "Reviewer" does not install any agent, and "Codex" does not say what its responsibility is. When a stage has a role, PrumoGrid prepares a file with the role's description and the rules that apply only to it, and the instruction delivered to the agent starts with "Your role for this stage is: …", asking it to read that file before proceeding. That keeps the stage instruction short, because the rest is already in the role.

When to use it and when not to

Use a role when the same kind of work repeats with the same guidance. A review that always writes its findings to REVISAO.md, a security analysis that never changes code, a fix that always comes with a test. It also helps you read a flow with several stages: the cards show "Claude Code · analyst", "Codex CLI · implementer", "Claude Code · reviewer", and you understand the sequence without opening each instruction.

Do not create a role for a task that will happen only once; write the request in the stage itself. Also do not count on the role for things it does not do:

• It does not pick another agent's terminal. To send the reviewer's findings back to the implementer, create the next stage and, in Where this stage runs, choose In terminal: with the name of the implementer's terminal (only live terminals of the project appear). Ask the reviewer for a file, such as REVISAO.md, and tell the implementer to read that file: one agent's conversation does not pass to the other.
• Being a reviewer does not turn on human approval. What makes the stage wait for you is the With your approval condition.
• Having a role does not prove that the agent followed the guidance. To check, use a verification.

The four built-in roles

PrumoGrid comes with four roles. They appear in Tools → Rules and roles…, in the Define roles section, and can be edited.

Step by step

The example creates a seguranca role for loja-api. It looks for secrets in the code and for unvalidated input, writes its findings to a file and does not touch the code.

Create the role

1. Open Tools → Rules and roles… and click Define roles. The list shows the four built-in roles.
2. Click + New role.
3. In role name, type seguranca. Prefer short names, in lowercase and without accents: that is how the role appears in the rules and in the agent's file.
4. In description, write what is expected of whoever fills the role, for example: Looks for secrets in the code and unvalidated input. Reports in SEGURANCA.md and does not change code.
5. Click Create role. The notice says Role "seguranca" created. and the role joins the list.

Give the role a rule of its own

1. On the seguranca role, click Rule for this role. The new rule screen opens, already applying only to whoever is in that role.
2. Write the instruction, for example Cite file and line for each finding.
3. Click Save and deliver. The rule appears with the line applies only to agents in the seguranca role, followed by where it lives (on this machine only or in the repository).

Use the role in a stage

1. Close the rules screen and click New stage, the orange button at the top.
2. In What needs to be done?, write only the request: Analyze the src folder using your role.
3. In Runs on, choose Claude Code.
4. Open More options and, in Role (rules), choose seguranca. The section summary now says role: seguranca · ready when the agent reports, and the line The agent will read: shows what will be delivered.
5. Click Create stage. If it is the project's first stage, PrumoGrid asks before writing CLAUDE.md (see Writing in projects).
6. When the agent finishes, run this in the project's PowerShell:

git status --short

You should see ?? SEGURANCA.md, besides the files PrumoGrid itself writes (CLAUDE.md and .terminal-grid/), and nothing inside src. Open SEGURANCA.md and check that each finding has a file and a line, as the role's rule asks.

What you see on screen

Enlarge screenshot ↗

Each role in the list has Edit, Rule for this role and Delete. In New stage, No additional role delivers only the project's rules. In Flow, the stage card shows the agent and the role, such as Claude Code · analyst.

Roles in Flow

At the end of the Flow chain there is a button for each role, plus Configure roles…. Clicking one of them, for example implementer, opens New stage with that role already set and chained after the last stage, as planned. You write the instruction and create the stage.

To change the role of a stage that already exists, use Other actions → Role and sequence on the card. There you change the role, the Position in project and the This stage ends the flow checkbox, and confirm with Save changes. The terminal stays open and the agent does not restart. A stage that has already started stays in the terminal it was delivered to; changing its role does not transfer the work. Stages from a routine or from parallel groups are reordered in the full Flow editor.

Skills folder

When you edit a role, the Skills folder (optional) field accepts a path relative to the project or an absolute path. The agent is told to read the SKILL.md files in that folder before it starts. PrumoGrid does not prove that the skills were loaded; if that matters, ask in the instruction for the agent to say which ones it read.

Tips

• Write short descriptions, with what the role does and what it does not do ("does not change code"). The task for each run goes in the stage.
• Ask each role for an output file with a fixed name (ANALISE.md, REVISAO.md, SEGURANCA.md). That makes it easy for the next stage to read and for you to check in git status.
• For guidance that applies to every agent in the project, use a project rule in Rules. Leave to the role only what is specific to it.

Known limitations

• Up to 32 roles per profile. The name takes up to 48 characters and the description up to 200.
• Roles are stored in this machine's profile and apply to every project. A role's rule can live in the repository or on this machine only, and the screen shows which.
• The registry needs at least one role: the last one cannot be deleted, only edited.
• Deleting a role does not delete the stages that mention it; they show the old identifier until they are edited.
• The role's preferred CLI type and suggested memory and CPU fields are only suggestions. Registering the role does not apply any limit.