Implementations

Purpose

A reviewed spec is only useful if the build follows it. The build goes wrong in familiar ways: the implementer skips the review threads, changes the plan halfway through, or declares the work done before anyone has checked it. Best practice keeps three things together: the agreed spec, the code that builds it, and a record of who built it, with what, and at what cost.

In Roko Platform, that record is an implementation. It links a change request to the pull requests that build it. A change request can have more than one implementation, for example when a first attempt is closed and a second one starts. Each project numbers its implementations on their own, as IMPL-1, IMPL-2, and so on, so IMPL-3 and CR-3 are usually unrelated. The list is in the sidebar under Implement, as Implementations.

Two ways to build

Local strategyYour own agent

1. 1Your agent runs the implement-a-change-request prompt.
2. 2It builds the change on a branch on your computer.
3. 3After each push it calls report_implementation_usage.
4. 4It opens the pull request and calls link_pull_request.

Single agent or Writer + ReviewerA Platform agent

1. 1The platform starts an agent run as soon as you start the implementation.
2. 2The agent builds the change on the platform. You watch the transcript.
3. 3It asks you when it needs a decision, and waits.
4. 4It opens the pull requests and links them itself.

A person merges each pull request

On the code host, as usual.

Implementation: Complete

Automatic once all linked pull requests merge.

Change request: Mark complete

A person presses it. Model changes merge.

You pick the way when you start the implementation. Open the change request and press Start an implementation in the action rail, or Start another implementation when one exists. The dialog asks for:

• Title, prefilled with the change request title.
• Strategy. See Strategies.
• Model for Single agent, or Writer model and Reviewer model for Writer + Reviewer. A model left on its default follows that agent's project setting.
• Prefer stacked pull requests, a checkbox.

The strategy and the models are fixed once the implementation starts. To change either, start a new implementation.

Strategies

Default

Writer + Reviewer

WriterReviewer

A writer builds the change. An independent reviewer checks the diff, for at most ten review cycles.

One agent

Single agent

AgentPull requests

One agent does the whole job and reports the pull requests it opens. Only people review it.

Nothing runs on the platform

Local

You and your agentLink pull requests

You build the change on your own computer and link the pull requests.

If the dialog offers only Local, the project has no model provider yet. Model provider covers the setup.

Local, with your own agent

Pick Local and start the implementation. Then ask your agent to implement it. The agent works through these steps:

1. Read the change request in full

   The agent calls get_change_request and reads the sections, the model change diffs, the reviews, and the threads. If the intent is unclear, it asks you before it writes code.

2. Build and verify

   It works on its own branch, never on main, and follows the repository's conventions. It builds and runs the relevant tests before it opens anything.

3. Report token usage after every push

   After each successful push, it calls report_implementation_usage with the implementation number and a fresh cumulative token count from your agent's session. The platform stores only the increase since the last report and counts it toward the change request too.

4. Open the pull request and link it

   It opens the pull request, ready for review, with a link to the change request on the first line. Then it calls link_pull_request with the implementation number, the repository as owner/name, and the pull request number.

The agent stops at an open pull request. It does not move the change request forward.

• The repository must be registered to the project before link_pull_request accepts it.
• A pull request can link to only one implementation.
• To remove a link, for example to an abandoned pull request, call unlink_pull_request with the same arguments.
• report_implementation_usage works only on a Local implementation. The platform records a Platform agent's usage on its own.

The change request's Token usage dialog, opened from its header, shows the tokens reported for its creation, its updates, its reviews, and each implementation.

On the platform, with a Platform agent

Pick Single agent or Writer + Reviewer. The first agent run starts as soon as you start the implementation. The platform runs the agent in its own environment, so you need nothing installed.

Agent runs

Each run of an agent is an agent run. The implementation page shows the selected run's transcript, and each run also has its own Agent run page with its agent, model, elapsed time, turns, and token counts.

When the agent needs a decision, it asks and stops. The run shows Awaiting input until you answer.

Budgets

Each agent run has a time budget of one hour by default, counted across all its attempts. When the budget runs out, the platform cancels the run. The deployment sets the budget, and a project cannot change it. There is no cap on tokens or dollars. The implementation page reports cost as Agent spend, in US dollars.

Writer + Reviewer cycles

The writer builds the change. The reviewer checks the stable diff and returns findings. The writer addresses blocking findings and the reviewer checks again. If the tenth cycle still ends with blocking findings, the platform cancels the runs and the implementation shows as Blocked. Read the findings before you start another implementation. They usually show a disagreement about the work itself, which a new change request should settle.

Pull request comments

Review the agent's pull request on your code host as usual. To have an agent work through the open review comments, comment /roko address-comments on the pull request. The agent leaves resolving each thread to you.

Implementation states

The implementation page shows Elapsed, Pull requests as merged out of linked, and Agent spend. Its rail has Start a run, Mark complete, and Close incomplete.

Completion

An implementation completes on its own. The platform watches each linked pull request, through the code host's webhook and a check that runs every minute. When every linked pull request has merged and no run is still active, the implementation becomes Complete.

• A pull request closed without merging blocks completion until someone unlinks it.
• A person can press Mark complete on the implementation at any time. Linked pull requests stay as they are.
• Completing an implementation cancels any run that is still going.

The change request does not change when its implementation completes. It stays In implementation until a person presses Mark complete on it. That step merges its model changes into the working model. The one exception: when a Writer + Reviewer implementation ends with the reviewer's approval and no code changes, the platform completes the change request on its own.

Best practices

• Read everything first. The spec, the model change diffs, and the review threads. Threads often hold decisions the spec missed.
• Do not change what was agreed. If the spec is wrong, stop and open a new change request.
• Review the result yourself. Tests cannot tell you whether the change builds what the team decided.
• One implementation, one pull request set. Link each pull request to the implementation it builds. A pull request cannot belong to two.
• Report usage after every push. On a Local implementation, the usage report is part of the push, not an afterthought.
• Unlink what you abandon. A closed, unmerged pull request holds the implementation open.
• Complete the change request. Nothing lands in the working model until a person completes it.