Set up your software factory: from triage to PR

By the time you reach this guide, you have a triage agent that labels new issues and a spec agent that drafts specs for approved issues. This guide adds the remaining two roles — an implementation agent that builds against approved specs, and a reviewer agent that validates the result — and wires all four together using GitHub labels as the state machine. Issues flow automatically from triage to a reviewable pull request.

Prerequisites

• Each agent role working individually (triage agent and spec agent guides)
• An Oz cloud environment with access to your repository (create one)
• warpdotdev/oz-agent-action installed (see GitHub Actions integration)

How the loop works

GitHub labels serve as the state machine that connects the agents. Each agent watches for a specific label, does its work, and sets the next label:

Label	Agent triggered	What it does	Sets next label
(new issue filed)	Triage agent	Reviews the issue, flags questions	ready-to-spec or needs-info
ready-to-spec	Spec agent	Writes PRODUCT.md and TECH.md	(human sets ready-to-implement after review)
ready-to-implement	Implementation agent	Opens a PR with code and specs	(PR opening triggers reviewer)
(PR opened)	Reviewer agent	Reviews PR against specs and conventions	Posts inline review comments

A human intervenes at two points: approving the spec before implementation begins, and merging the PR after review. Everything else runs automatically.

1. Wire up the triage agent

Your triage agent runs on issues: [opened] via GitHub Actions. When it completes, it applies a ready-to-spec label if the issue is clear and actionable, or needs-info if it needs more detail from the reporter.

See Build a triage agent for the full setup.

2. Trigger the spec agent on label change

Add a GitHub Actions workflow that runs when the ready-to-spec label is applied:

name: Write specs for ready issues

on:
  issues:
    types: [labeled]

permissions:
  contents: write
  pull-requests: write
  issues: write

jobs:
  write-specs:
    if: github.event.label.name == 'ready-to-spec'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: warpdotdev/oz-agent-action@v1
        with:
          skill: spec-driven-implementation
          prompt: |
            Write a product spec and tech spec for GitHub issue #${{ github.event.issue.number }} in ${{ github.repository }}.
            Issue title: ${{ github.event.issue.title }}
            Issue body: ${{ github.event.issue.body }}
          environment: YOUR_OZ_ENVIRONMENT_SLUG
          warp_api_key: ${{ secrets.WARP_API_KEY }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The spec-driven-implementation skill from warpdotdev/common-skills guides the full spec-first workflow. It writes PRODUCT.md and TECH.md, then opens a draft PR so you can review and approve the specs before implementation begins.

3. Human review: approve the specs

When the spec agent opens a draft PR, review the PRODUCT.md and TECH.md files. This is the most important human checkpoint in the loop — an accurate spec leads to a correct implementation; a wrong spec leads to a correct implementation of the wrong thing.

When the specs look right, apply the ready-to-implement label to the original issue.

4. Trigger the implementation agent

Add a workflow that triggers when ready-to-implement is applied:

name: Implement from approved specs

on:
  issues:
    types: [labeled]

permissions:
  contents: write
  pull-requests: write

jobs:
  implement:
    if: github.event.label.name == 'ready-to-implement'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: warpdotdev/oz-agent-action@v1
        with:
          skill: implement-specs
          prompt: |
            Implement the approved specs for GitHub issue #${{ github.event.issue.number }} in ${{ github.repository }}.
            The specs are in specs/${{ github.event.issue.number }}/.
          environment: YOUR_OZ_ENVIRONMENT_SLUG
          warp_api_key: ${{ secrets.WARP_API_KEY }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The implement-specs skill from warpdotdev/common-skills reads PRODUCT.md and TECH.md and builds against them. It opens a PR with the code changes and the spec files committed together.

5. Trigger the reviewer agent on PR open

Add a workflow that triggers when a PR is opened or updated:

name: Review new pull requests

on:
  pull_request:
    types: [opened, synchronize]

permissions:
  pull-requests: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: warpdotdev/oz-agent-action@v1
        with:
          skill: review-pr
          prompt: |
            Review pull request #${{ github.event.pull_request.number }} in ${{ github.repository }}.
            If spec files are included in this PR, locate the changed specs/*/PRODUCT.md and specs/*/TECH.md files and validate the implementation against them.
          environment: YOUR_OZ_ENVIRONMENT_SLUG
          warp_api_key: ${{ secrets.WARP_API_KEY }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The review-pr skill from warpdotdev/common-skills reviews the PR diff against your codebase conventions and, when spec files are available, validates the implementation against the specs. It posts inline review comments.

6. Human review: merge the PR

After the reviewer agent posts its comments, a human reviews the PR — the diff, the agent’s inline comments, and the spec files. Address any gaps, run the project’s tests, and merge.

The reviewer agent surfaces issues and inconsistencies; the human makes the final call on quality and correctness. See Review AI-generated code for the full human review workflow.

Reference implementation

warpdotdev/oz-for-oss is Warp’s complete, deployable software factory for GitHub-hosted repositories. It includes all four agent roles, a Vercel webhook layer that handles GitHub events without GitHub Actions boilerplate, and self-improvement loops that propose skill updates based on maintainer feedback. If you want a production-grade system rather than individual GitHub Actions workflows, start there instead.

Productivity tips

• Start with triage only — Get your triage agent running well before adding spec and implementation. A groomed, labeled backlog is immediately useful to every developer on the team.
• Use @oz-agent for one-off requests — Teammates can mention @oz-agent in an issue comment to kick off an agent run directly, bypassing the label workflow for urgent requests.
• Monitor runs in the Oz web app — Every cloud agent run appears in the Oz web app with a session link. Use it to inspect what each agent did, steer a stuck run, or hand work back to a local session.

Next steps

• What is a software factory? — The conceptual overview of the full loop.
• Run a software factory in the cloud — Move the loop into a managed Oz deployment.
• Build a self-improving agent — Add the outer improvement loop.
• Review AI-generated code — The human review workflow for agent-generated PRs.
• warpdotdev/oz-for-oss — The complete reference implementation.
• GitHub Actions integration — Full documentation for triggering Oz agents from CI.