How a task becomes a pull request

This is the page referenced throughout the rest of the documentation. It names each stage of execution so other articles can precisely identify where specific actions take place.

The pathway#

your description
   │
   ▼
   specification   what will be built, and how you will know it worked
   │
   ▼
   plan            the ordered steps, reviewed before any code is written
   │
   ▼
   build           code and tests written in an isolated workspace
   │
   ▼
   verify          your test suite, plus checks and quality gates
   │
   ▼
   review          an automated review pass over the diff
   │
   ▼
   pull request    on a branch, in your repository, waiting for you

Specification#

Coroid does not begin with your sentence. It first transforms your description into a specification: detailing what will be built, what is explicitly outside the scope, and the acceptance criteria used to determine if the work was successful.

This is important because the acceptance criteria serve as the benchmark for the verification stage later on. A vague specification leads to work that is difficult to assess.

You can view and edit the specification on the task's Specification tab prior to starting execution.

The specification-driven development guide outlines how to write testable criteria, define scope boundaries, and maintain a consistent definition of success throughout planning, implementation and review.

Plan#

For anything beyond a minor change, the specification becomes a plan: an ordered set of steps grouped into phases. You authorise the plan before any code is written.

Rejecting a plan is low-cost and the right action if the approach is unsuitable. Rejecting it after code has been written is costly. This is the stage where your judgement has the greatest impact.

Build#

An agent clones the repository into an isolated workspace and works there. It reads the code, makes the required changes, and creates or updates tests.

The workspace is disposable and tied to each task. Nothing an agent does affects your default branch, and two concurrent tasks cannot access each other's in-progress work.

Verify#

Your own test suite runs first — this provides the most reliable signal, as it reflects what your team has already agreed is important.

In addition, quality gates enforce whatever your organisation has configured: coverage thresholds, linting, security scans, and browser tests on a preview deployment. A blocking gate halts the task; an advisory gate logs a finding and allows the task to continue.

Review#

A reviewer agent examines the diff in the same way a colleague would and generates findings. Findings that require fixes are sent back for rework; the rest are attached to the pull request for your review.

This is why a Coroid pull request arrives already reviewed — not to replace your review, but to ensure your review is not the first one.

Pull request#

The branch is pushed and a pull request is opened against your base branch, containing the changes, tests, verification results, and review findings.

Coroid ends here. Merging is your responsibility.

Task statuses#

A task's Status indicates its position in the pathway described above:

What influences throughput#

One agent slot handles one task at a time. Slots determine how much work occurs in parallel; they do not reduce the duration of any single task. A task's completion time depends on the size of the changes and the time required for your test suite to run.

Next#

Agent roles — specifying which agent manages each stage and what actions each is allowed to perform.