Set up your software factory

This guide adds the implementation and reviewer agents to the triage and spec agents you set up previously, then connects all four into a software factory using GitHub labels as the state machine. Issues flow automatically from triage to a reviewable pull request.

Prerequisites

• A working triage agent and spec agent, each deployed individually
• 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 applies the next label:

| Label | Agent triggered | What it does | 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. Trigger the spec agent when an issue is labeled ready-to-spec

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 automates what you did manually in the previous guide — running both spec commands in sequence and opening a draft PR so you can review and approve the specs before implementation begins.

2. 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.

3. 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 the product and tech specs, and builds against them. It opens a PR with the code changes and the spec files committed together.

4. Trigger the reviewer agent when a PR is opened

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.

5. Human review: merge the PR

After the reviewer agent posts its comments, a human reviews the PR, including 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

• Validate before the reviewer runs — After the implementation agent opens a PR, run /validate-changes-match-specs to check the diff against PRODUCT.md and TECH.md. This catches any misalignments before the reviewer agent posts comments. The skill is available from warpdotdev/common-skills.
• 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.