New stage

What it's for

A stage is a task handed to a terminal, with three parts: the instruction (what you would ask the agent), who runs it (the CLI, the project and the side, Windows or WSL), and when it is done. The orange + New stage button, at the top of the window, puts this task together in a single dialog. With it, PrumoGrid opens the terminal, starts the agent with the instruction, follows the turn, and shows the stage in the Stages tab as running, done, or failed. If you ask, it also checks the work with a command before calling the stage done.

When to use it and when not to

Use New stage when you want PrumoGrid to follow the task and tell you when it finishes, when you want to check the result with npm test, or when the task is the start of a sequence in the Flow.

Calling the agent directly in the terminal still works. For a quick question, such as "what language is this project written in?", open Claude Code or Codex from the NEW row and type. New stage is optional and changes nothing in the terminals you use by hand.

It is also not the place to paste a whole document: the instruction is limited to 512 characters. For larger context, write a file in the project and point to it in the instruction.

Step by step

First stage in loja-api

1. Select the loja-api card and click + New stage.
2. In What needs to be done?, write: Count the files in the src and tests folders, including subfolders. Reply with the number only, without listing names.
3. In Runs on, check Claude Code. The note below reminds you that this agent is the one that reports the stage finished, through the CLI's own end of turn.
4. In Where this stage runs, leave New terminal. The summary line shows the agent, the project and the side: Claude Code · loja-api · native Windows.
5. In On creation, leave Now.
6. Click Create stage.
7. A new pane, Claude Code, opens in the Grid and receives the instruction right away. When the agent replies 7 and finishes its turn, the Stages tab shows the stage as done, with View result.

If this is the project's first stage, PrumoGrid first asks whether it may write guidance into the folder's CLAUDE.md or AGENTS.md. See Writing in projects.

Require the tests to pass

1. In + New stage, write Fix the PRIMEIRA coupon, which applies the discount twice with two items in the cart. Write a test that reproduces the case before fixing it, and run npm test.
2. Open More options.
3. In How does this stage finish and the next one start?, choose Automatic with verification · the command passes and the next stage starts automatically.
4. In Check with a command, check npm test, marked as project's, and passes when it exits with success (0).
5. Click Create stage.

Now the stage is only done if npm test passes after the agent's turn. The end-of-turn notification alone does not approve the stage. See Verification.

What you see on screen

Enlarge screenshot ↗

Enlarge screenshot ↗

Inside More options:

• Role (rules): No additional role, implementer, reviewer, checker, analyst, or a role of your own. The The agent will read line shows what goes into the guidance file. See Roles.
• How does this stage finish and the next one start?: Automatic (the agent reports it), Automatic with verification (the command passes), With your approval (the agent reports it and you approve), or Verification and your approval.
• Check with a command: the command, the expected exit code, and the maximum time in seconds.
• Stage options: the folder (In the project folder, In a new worktree, or In another folder…), the side (Windows or WSL), Model and permissions (optional), and what happens if this stage closes the flow. Leave the model blank to keep the CLI's configuration.

Continue in this terminal

When the project already has a stage, Where this stage runs gains Continue in this terminal. The new instruction goes into the same conversation, and the agent remembers what it has already read. With this option, Runs on shows that terminal's agent and is locked, because the agent of an open conversation does not change. Model, effort and permissions also stay those of the session.

With a planned flow, New stage opens on Add to the flow, after stage N and asks when the stage starts: right away, once the previous stage is done, or alongside it.

Another project

Another project links this stage to a flow in another open project, such as a change in loja-api that needs to reach portal-web. With only one project, the option is disabled; hover over it to read the reason, Only one project is open. With more projects, it asks for a source stage first. The full handoff is in Flow.

Start from a ticket

In the right sidebar, Start from a ticket… brings a GitHub or Jira issue in as a stage. The same is available in Tools → Tickets….

1. Register a source: Source name, Where the tickets come from, and Source command. The command runs in the folder of the selected project and must write JSON to standard output.
2. Click Fetch and pick a ticket from the list.
3. Click Create stage from this issue, review the draft, the project and the agent, and confirm.

To try it without any service, create chamados-demo.json in loja-api and use the Command source with type chamados-demo.json:

[
  {
    "id": "LOJA-42",
    "title": "Cupom PRIMEIRA dá desconto em dobro com dois itens",
    "body": "Com dois ou mais itens no carrinho, o desconto do cupom PRIMEIRA sai em dobro. Esperado: 10% sobre o subtotal.",
    "status": "aberto"
  },
  {
    "id": "LOJA-43",
    "title": "Banner do portal diz 'acima de R$ 200' em vez de 'a partir de'",
    "body": "O texto do banner não segue a regra do frete da loja-api.",
    "status": "aberto"
  }
]

Enlarge screenshot ↗

No credentials are stored in PrumoGrid: the GitHub and Jira sources use gh or the Jira CLI already authenticated on your machine. Importing a ticket does not change its status in the source service.

Tips

• Write instructions that say where to look and how to answer: file, folder, answer format. "Read src/frete.cjs and explain the free-shipping rule in up to three lines" works better than "explain shipping".
• The Create stage button is always enabled. If the instruction is missing, the warning appears when you click.
• When you change the agent in Runs on, PrumoGrid may ask Use Claude Code as the default agent for future stages?. The default can also be changed in Tools → Agents.
• For tasks in sequence, create the first stage here and the following ones in the Flow.

Known limitations

• The instruction is limited to 512 characters and goes on a single line: line breaks become spaces, because the instruction is passed as an argument to the command that starts the agent.
• The agent reporting that it finished its turn does not prove the task is right. For that, use Check with a command.
• A new worktree starts without installed dependencies. The plan summary shows the preparation needed.
• A folder that exists only inside WSL does not get the rules from the Windows side.
• Tickets: up to 100 per fetch, and each body up to 4,000 characters. The output must be JSON; a CLI that returns a table needs a different command.