---
name: rig-task-run
description: Rig task-run workflow contract — how an agent should execute a Rig-dispatched task end-to-end. Used by the server to brief the agent at run start.
audience: agent
---

# Rig Task-Run Workflow

Use the baked Rig runtime workflow only. Start by running `rig-agent info` and `rig-agent deps`. Use the baked agent binary via `$RIG_AGENT_BIN` for all Rig actions. Do not rely on bare `rig-agent` being on PATH.

## Environment

- `$RIG_TASK_WORKSPACE` and `$MONOREPO_ROOT` — absolute task worktree root.
- `$PROJECT_RIG_ROOT` — outer control-plane repo root.
- `$MONOREPO_MAIN_ROOT` — host monorepo checkout root (use only when you explicitly need the non-worktree path).
- `$RIG_LOGS_DIR` / `$RIG_TASK_ID` — task validation logs land under `$RIG_LOGS_DIR/$RIG_TASK_ID/`.

## Required first calls

1. `"$RIG_AGENT_BIN" info` — confirm your assigned task, scope, validators.
2. `"$RIG_AGENT_BIN" deps` — read decisions and next-actions from prior tasks.

## Validation and completion

- `"$RIG_AGENT_BIN" validate` — run validators for the task.
- `"$RIG_AGENT_BIN" completion-verification` — final gate before finish.

Before completion verification, scaffold and fill the required completion artifacts so the verifier has real inputs:

1. `"$RIG_AGENT_BIN" artifacts` — write template files.
2. Update `task-result.json`, `decision-log.md`, `next-actions.md`.
3. Re-run `"$RIG_AGENT_BIN" artifacts` after real file edits to refresh `changed-files.txt`. Do not hand-edit runtime/control-plane paths into it.

Make `decision-log.md` substantive: at least 3 distinct concrete lines covering what changed, why, and any downstream follow-up or risk. If you touch proto/OpenAPI/contract files, add `contract-changes.md` describing the contract impact before finishing.

## Git flow

After validation passes, use `"$RIG_AGENT_BIN" git status` or `"$RIG_AGENT_BIN" git preflight` to confirm branch state.

To inspect or customize the PR before finish:

- `"$RIG_AGENT_BIN" git commit --target monorepo`
- `"$RIG_AGENT_BIN" git open-pr --target monorepo`

Otherwise completion verification will auto-commit, open/refresh the PR, run Greptile review, and enable auto-merge when policy requires it.

## AI review loop

When AI review is required, **PR creation is not completion**. Treat `artifacts/<taskId>/review-status.txt`, `review-state.json`, and `review-feedback.md` as the source of truth.

If Greptile returns `SKIP`, `REJECTED`, a timeout, unresolved comments, or any verdict other than `APPROVE`:

1. Stay in the same runtime workspace.
2. Resolve the concrete review feedback.
3. Push the follow-up changes.
4. Rerun `"$RIG_AGENT_BIN" completion-verification`.
5. Repeat until `review-status.txt` is `APPROVED` and the review verdict is `APPROVE`.

Do not commit or push artifact-only refreshes on review-loop retries. Only create a new commit when scoped task code, tests, configs, or generated contract outputs actually changed.

Do not stop after opening the PR, after the first completion-verification run, or after an implementation-only success if review is still pending.

## Validation failures

If validation fails, inspect the generated task validation logs under `$RIG_LOGS_DIR/$RIG_TASK_ID/` and retry validation after fixing the concrete issue. Do not start searching unrelated workspace files for clues — the logs name the problem.

## Conventions

- Use `"$RIG_AGENT_BIN" git ...` commands for git status/commit/PR flow instead of raw git whenever possible.
- Do not inspect or guess hidden control-plane script paths; use the baked Rig commands and files available in the runtime worktree.
- Implement the task in the dedicated Rig runtime worktree, leave artifacts as needed, and finish through Rig's completion verification flow.
