From b67a8832c8815ef619b611c2ccf22d794e989eee Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Wed, 17 Jun 2026 12:04:32 -0600 Subject: [PATCH 1/9] docs: add software factory concept page and guides Add a conceptual anchor page explaining the software factory model and five practical guides covering each stage of the loop: - agent-platform/cloud-agents/software-factory.mdx: What is a software factory? Introduces the inner/outer loop framework, the four agent roles (triage, spec, implement, review), and oz-for-oss as the canonical reference implementation. - guides/agent-workflows/build-a-triage-agent.mdx - guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx - guides/agent-workflows/chain-a-software-factory.mdx - guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx - guides/agent-workflows/build-a-self-improving-agent.mdx Sidebar: adds 'Software factory' under Oz Cloud Agents & Orchestration and a new 'Build a software factory' section in the Guides sidebar. Key sources: warpdotdev/oz-for-oss (reference implementation), warpdotdev/common-skills (spec skills), ZL X/Twitter articles on self-improvement loops and spec-driven development, Rectangle Health Rex case study. Co-Authored-By: Oz --- .../cloud-agents/software-factory.mdx | 70 ++++++++ .../build-a-self-improving-agent.mdx | 124 +++++++++++++ .../agent-workflows/build-a-triage-agent.mdx | 120 +++++++++++++ .../chain-a-software-factory.mdx | 168 ++++++++++++++++++ .../run-a-software-factory-in-the-cloud.mdx | 112 ++++++++++++ ...ite-product-and-tech-specs-with-agents.mdx | 100 +++++++++++ src/sidebar.ts | 16 +- 7 files changed, 708 insertions(+), 2 deletions(-) create mode 100644 src/content/docs/agent-platform/cloud-agents/software-factory.mdx create mode 100644 src/content/docs/guides/agent-workflows/build-a-self-improving-agent.mdx create mode 100644 src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx create mode 100644 src/content/docs/guides/agent-workflows/chain-a-software-factory.mdx create mode 100644 src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx create mode 100644 src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx diff --git a/src/content/docs/agent-platform/cloud-agents/software-factory.mdx b/src/content/docs/agent-platform/cloud-agents/software-factory.mdx new file mode 100644 index 00000000..491ba781 --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/software-factory.mdx @@ -0,0 +1,70 @@ +--- +title: Software factory +description: >- + A software factory chains specialized agents through the full development loop — from issue triage through spec, implementation, and review — so teams get PRs to review instead of executing every step. +sidebar: + label: "Software factory" +--- + +# Software factory + +A software factory is a development system where specialized agents handle the full cycle from a new issue to a reviewable pull request. Instead of every developer executing every step — reading each issue, writing specs, implementing changes, reviewing output — agents handle the execution and humans review the results. The team's job shifts from doing the work to defining the process and raising the quality bar over time. + +Warp uses this model to build Warp itself. The [agent dashboard at build.warp.dev](https://build.warp.dev) shows the work Warp's agents are tackling across the open source repository in real time. Rectangle Health's Rex agent — built on Oz — ships 35,000 lines of production code per week and has written more than 50% of its own codebase. + +## The two loops + +Every software factory has two loops that work together. + +The **inner loop** is the execution loop. A new issue enters the backlog. A triage agent reviews it for clarity, labels it, and flags open questions before any implementation starts. A spec agent drafts a product spec (what the feature should do) and a tech spec (how to implement it). An implementation agent builds against the approved specs. A reviewer agent checks the result for correctness, style, and spec compliance. The output is a pull request in GitHub for a human to review and merge. + +The **outer loop** is the improvement loop. A scheduled cloud agent runs on a cadence, reviews past inner-loop runs, and observes where maintainers corrected the agents — relabeled issues, revised comments, adjusted code. It opens a pull request to improve the skill files that drive the inner-loop agents. Over time, the factory gets better without anyone manually rewriting prompts. + +The inner loop ships software. The outer loop improves the factory that ships it. + +## Agent roles + +A software factory delegates work to specialized agents, each with a narrow responsibility: + +* **Triage agent** - Reviews new issues for clarity and completeness. Labels issues as ready to implement, needs more information, or a duplicate. Flags open questions for the reporter before implementation starts, so the backlog stays clean and actionable. +* **Spec agent** - Drafts a product spec (user stories and acceptance criteria) and a tech spec (implementation strategy, relevant code locations, and edge cases). The specs serve as the blueprint for the implementation agent and the review criteria for the reviewer agent. +* **Implementation agent** - Builds against approved specs. Uses spec context to make better architectural decisions and raises a blocked status when specs are missing or ambiguous rather than guessing. +* **Reviewer agent** - Checks the implementation against specs, code conventions, and security requirements. Posts inline review comments and validates that acceptance criteria are met before a human reviewer opens the PR. + +In practice, a single agent often covers multiple roles in early-stage setups, and most teams start with just a triage agent before adding the rest. The [`warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss) repository is the complete reference implementation with all four roles deployed in a working system. + +## How it works + +Each agent role is backed by a **skill** — a markdown file checked into a Git repository that defines the agent's behavior: what to check, how to classify results, what to output, and when to escalate. Skills are versioned, reviewed as code changes, and composable across repositories. + +When a new issue is filed on GitHub, a webhook or GitHub Action triggers the triage agent. The agent runs in a cloud environment using the triage skill, analyzes the issue, and applies labels and comments. When an issue is labeled `ready-to-spec`, the spec agent runs and creates `PRODUCT.md` and `TECH.md` files in a `specs/` directory in the repository. A human reviews and approves those specs. When the implementation label is applied, the implementation agent runs and opens a PR that includes the spec files alongside the code. + +Oz orchestrates each agent as a cloud run. Every run has its own environment (repository checkout, secrets, toolchain), its own permissions, and a session link your team can use to inspect what the agent did, steer it mid-run, or hand work back to a local session. + +The outer improvement loop runs as a scheduled cloud agent. It collects signals from past inner-loop runs — maintainer relabels, edits to agent-written comments, code changes after agent PRs — and generates a diff to the relevant skill files. That diff goes through a normal pull request review before merging. Humans decide what improves; agents propose it. + +## When to use a software factory + +A software factory is a strong fit when: + +* Your team has a repeatable development workflow — a backlog of issues with consistent shape, and a process you can write down and teach to an agent. +* The cost of a missed edge case in agent output is recoverable — the agent opens a pull request, not a deploy, so humans stay in control of what ships. +* You want to scale throughput without scaling headcount linearly, or you want to move faster on a large backlog with a small team. + +Start with one agent role. Most teams start with a triage agent — it is the simplest loop to close correctly, and a well-groomed backlog immediately benefits every developer on the team. Add spec, implementation, and reviewer agents as you build confidence in each step. + +## Reference implementation + +[`warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss) is Warp's open-source software factory platform for GitHub-hosted repositories. It includes a Vercel webhook layer, GitHub App, and skill files for every agent role in the loop: triage, spec, implementation, review, verification, and self-improvement. Deploy it to your repository in about 30 minutes using the [onboarding guide](https://github.com/warpdotdev/oz-for-oss/blob/main/docs/onboarding.md). + +## Related pages + +{/* TODO: Update guide links once software-factory guide PRs are merged */} +* [How to build a triage agent for your issue backlog](/guides/agent-workflows/build-a-triage-agent) — Start the series with the simplest agent role. +* [How to write product and tech specs with agents](/guides/agent-workflows/write-product-and-tech-specs-with-agents) — Write specs that guide implementation agents. +* [How to chain a software factory: from triage to PR](/guides/agent-workflows/chain-a-software-factory) — Connect the four roles into a working loop. +* [How to run a software factory in the cloud](/guides/agent-workflows/run-a-software-factory-in-the-cloud) — Move the loop off your laptop with Oz. +* [How to build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Add the outer improvement loop. +* [Skills](/agent-platform/capabilities/skills) — How skill files work in Warp and Oz. +* [Cloud agents overview](/agent-platform/cloud-agents/overview) — Setting up cloud agents on Oz. +* [Deployment patterns](/agent-platform/cloud-agents/deployment-patterns) — Common architectures for cloud agent deployment. diff --git a/src/content/docs/guides/agent-workflows/build-a-self-improving-agent.mdx b/src/content/docs/guides/agent-workflows/build-a-self-improving-agent.mdx new file mode 100644 index 00000000..c3fb4ede --- /dev/null +++ b/src/content/docs/guides/agent-workflows/build-a-self-improving-agent.mdx @@ -0,0 +1,124 @@ +--- +title: How to build a self-improving agent +description: >- + Build an outer improvement loop where a scheduled agent reviews past runs, learns from team corrections, and proposes skill file updates — so your factory gets better over time. +sidebar: + label: "Build a self-improving agent" +tags: + - "agents" + - "software-factory" + - "cloud-agents" + - "schedules" +--- + +# How to build a self-improving agent + +A self-improving agent is the outer loop of a software factory: it watches how maintainers correct the inner-loop agents — relabeled issues, edited comments, changed code — and opens a pull request to improve the skill files that drive those agents. Every correction from a teammate becomes a proposed improvement to the factory. + +This guide shows how to build the outer loop for a triage agent. The same pattern applies to any agent role. + +:::note +The outer loop proposes improvements; it doesn't apply them silently. Every change to a skill file goes through a normal pull request review before merging. The team decides what improves; the agent proposes it. +::: + +## Prerequisites + +* **A working inner loop** — Follow [How to chain a software factory: from triage to PR](/guides/agent-workflows/chain-a-software-factory) to set up the inner loop first. The outer loop improves agents that are already running. +* **Warp with Oz** — [Sign in and set up Oz](/agent-platform/getting-started/agents-in-warp) if you haven't already. +* **Oz environment** — A cloud environment with your repository checked out. See [Environments](/agent-platform/cloud-agents/environments). + +## Why principles beat rules + +Most agent skills start as a list of rules: "if the reporter doesn't include a reproduction step, add `needs-info`." Rules overfit. They break when a situation arrives that the rules didn't anticipate, and a longer rule list makes the skill harder to maintain. + +Effective skill files describe **principles**: durable ideas about how to approach a class of situation. A principle — "confirm that a bug report includes enough context for a fresh contributor to reproduce the issue" — transfers to situations the original rules didn't cover. When the outer loop proposes a skill update, it should always aim for a principle that generalizes, not a new rule that handles one more edge case. + +## 1. Collect correction signals + +The outer loop needs signals that the inner loop got something wrong. For a triage agent, the most useful signals are: + +* **Maintainer relabels** — A maintainer changes a label the triage agent applied (for example, `needs-info` → `ready-to-implement`). +* **Maintainer re-opens** — A maintainer reopens an issue the triage agent closed. +* **Follow-up comments** — A maintainer explains in a comment why the triage agent's assessment was wrong. + +GitHub captures all of these in the issue timeline and audit log. + +The [`update-triage`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents/skills/update-triage/SKILL.md) skill in `warpdotdev/oz-for-oss` includes a Python helper script (`aggregate_triage_feedback.py`) that collects these signals for the past N days. Copy and adapt it for your repository. + +## 2. Create the update skill + +Create `.agents/skills/update-triage/SKILL.md`. This skill describes how the outer-loop agent should reason about the correction signals it collects: + +```markdown +--- +name: update-triage +description: Review recent maintainer corrections to the triage agent's output and propose skill file updates that generalize from those corrections. +--- + +# Update triage skill + +You are reviewing recent maintainer corrections to the triage agent's output. + +## What to look for + +For each correction: +1. Identify what the triage agent did (the original label or comment). +2. Identify what the maintainer did instead (the correction). +3. Ask: why would the triage agent have gotten this wrong? +4. Ask: what principle would prevent this class of error in the future? + +## What to update + +Update only the triage-issue-local companion skill for this repository. +Write principles, not rules. Do not update the shared triage-issue skill. + +Commit changes to a branch named oz-agent/update-triage. +Do not push directly to main. Open a pull request for human review. +``` + +Use the full [`update-triage` skill from `warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents/skills/update-triage/SKILL.md) as the complete reference — it includes the collection script, write-surface restrictions that prevent the agent from modifying the wrong files, and the PR-opening workflow. + +## 3. Schedule the outer loop + +Run the outer loop on a cadence. Weekly on Monday morning works well for most teams — it processes the previous week's corrections and opens PRs for review at the start of the week. + +Create a scheduled cloud agent from the Oz CLI: + +```bash +oz schedule create \ + --name update-triage-weekly \ + --skill update-triage \ + --environment YOUR_ENVIRONMENT_SLUG \ + --cron "0 9 * * 1" +``` + +Or create the schedule from the Oz web app: open **Agents** > **Schedules**, click **New schedule**, and set the skill, environment, and cron expression. + +See [Scheduled agents](/agent-platform/cloud-agents/triggers/scheduled-agents) for the full reference. + +## 4. Review the proposed skill changes + +Each time the outer loop runs, it opens a pull request with proposed changes to the `triage-issue-local` companion skill. Review that PR the same way you would review any other code change: + +* Does the proposed principle generalize correctly, or is it another specific rule in disguise? +* Is the change scoped to the companion skill rather than the shared base skill? +* Does it improve the agent's reasoning, or does it just patch one edge case? + +Merge the PR when the improvement is sound. Close it if the proposal is too narrow or incorrect. + +Over time, the companion skill accumulates a clear description of how your team thinks about issue triage — not as a list of rules, but as a set of principles that a new maintainer or a new agent can learn from. + +## Productivity tips + +* **Give feedback in the right place** — The outer loop collects signals from GitHub. If you want the triage agent to learn from a correction, add a comment to the issue explaining why the original label was wrong. That comment becomes signal for the next outer-loop run. +* **Apply the pattern to other agent roles** — The [`update-pr-review`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents/skills/update-pr-review/SKILL.md) and [`update-dedupe`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents/skills/update-dedupe/SKILL.md) skills from `warpdotdev/oz-for-oss` apply the same outer-loop pattern to the PR reviewer and deduplication agents. +* **Don't skip the PR review** — The value of the outer loop is compounding improvement, not speed. A bad skill change that merges silently creates more work than it saves. Every proposed change should get a review. + +## Next steps + +* [What is a software factory?](/agent-platform/cloud-agents/software-factory) — How the outer improvement loop fits into the full factory model. +* [How to chain a software factory: from triage to PR](/guides/agent-workflows/chain-a-software-factory) — The inner loop the outer loop improves. +* [How to run a software factory in the cloud](/guides/agent-workflows/run-a-software-factory-in-the-cloud) — Move the loop to Oz for team-wide visibility. +* [Scheduled agents](/agent-platform/cloud-agents/triggers/scheduled-agents) — Full reference for running cloud agents on a cadence. +* [`warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss) — The complete reference implementation including all outer-loop skills. +* [Skills](/agent-platform/capabilities/skills) — How skill files work in Warp and Oz. diff --git a/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx b/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx new file mode 100644 index 00000000..6c8ac363 --- /dev/null +++ b/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx @@ -0,0 +1,120 @@ +--- +title: How to build a triage agent for your issue backlog +description: >- + Create a triage agent that reviews new GitHub issues, applies labels, and flags open questions — so your backlog stays actionable without manual effort. +sidebar: + label: "Build a triage agent" +tags: + - "agents" + - "cloud-agents" + - "software-factory" +--- + +# How to build a triage agent for your issue backlog + +Build a triage agent that reviews every new GitHub issue for clarity, applies labels, and flags open questions before any implementation starts. By the end of this guide, you will have a working triage skill deployed as a GitHub Action that runs automatically whenever someone files an issue. + +## Prerequisites + +* **Warp with Oz** — Oz is Warp's cloud agent platform. [Sign in and set up Oz](/agent-platform/getting-started/agents-in-warp) if you haven't already. +* **GitHub repository** — Your repository needs Issues enabled. The triage agent will read issues and post comments. +* **Oz environment** — A cloud environment with your repository checked out. See [Environments](/agent-platform/cloud-agents/environments) to create one. +* **`WARP_API_KEY`** — A Warp API key with permission to start cloud runs. Generate one in the Oz web app under **Settings** > **API Keys**. + +## 1. Define your triage criteria + +Before writing a skill, decide what your triage agent should do. A good triage agent answers three questions for every new issue: + +1. Is the report clear enough to act on? +2. Is it a duplicate of an existing issue? +3. What label should it get? + +Write down: + +* The label taxonomy for your repository (for example: `bug`, `enhancement`, `ready-to-implement`, `needs-info`, `duplicate`) +* Who owns each area of the codebase — this becomes your STAKEHOLDERS file +* What makes an issue "ready to implement": does it need a reproduction step? A version number? A proposed approach? + +You will encode these decisions in a skill file in the next step. + +## 2. Create the triage skill + +A skill is a markdown file that tells the agent what to do, how to classify results, and what to output. Create a `.agents/skills/triage-issue/` directory in your repository with a `SKILL.md` file. + +Use the [`triage-issue` skill from `warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents/skills/triage-issue/SKILL.md) as the starting point — it is the production triage skill Warp uses for its own open source repository. Copy it into your repository and adapt: + +* Replace the label taxonomy with your labels +* Update the ownership section to reflect your codebase +* Adjust the definition of "ready to implement" to match your team's bar + +Write the skill file in terms of principles, not rules. A rule says "if the reporter doesn't include a reproduction step, add `needs-info`." A principle says "confirm that a bug report includes enough context for a fresh contributor to reproduce the issue." Principles transfer to situations the original rules didn't cover; long rule lists overfit and become harder to maintain. + +Also create `.github/issue-triage/config.json` with your label taxonomy. See the [`config.json` from `warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss/blob/main/.github/issue-triage/config.json) for the format. + +:::tip +The [`bootstrap-issue-config`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents/skills/bootstrap-issue-config/SKILL.md) skill from `oz-for-oss` can generate an initial `config.json` and STAKEHOLDERS file by analyzing your existing labels and CODEOWNERS file. Run it once when setting up a new repository. +::: + +## 3. Test the triage agent locally + +Before deploying to GitHub Actions, test the triage agent against a real issue using the Oz CLI: + +```bash +oz agent run \ + --skill .agents/skills/triage-issue \ + --prompt "Triage GitHub issue #ISSUE_NUMBER in OWNER/REPO" \ + --share +``` + +The `--share` flag generates a session link your team can use to inspect what the agent did. Review the session output — check that the labels and comments match what you would write manually. If something is off, refine the skill file and run again. + +For the full reference of `oz agent run` flags, see the [Oz CLI reference](/reference/cli/). + +## 4. Deploy with GitHub Actions + +Once the skill output looks right, deploy it as a GitHub Action that triggers automatically when a new issue is opened. Create `.github/workflows/triage-issue.yml`: + +```yaml +name: Triage new issues + +on: + issues: + types: [opened] + +jobs: + triage: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: warpdotdev/oz-agent-action@v1 + with: + skill: triage-issue + prompt: | + Triage 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 + env: + WARP_API_KEY: ${{ secrets.WARP_API_KEY }} + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +Replace `YOUR_OZ_ENVIRONMENT_SLUG` with the slug of the Oz environment you created in the prerequisites. + +Add `WARP_API_KEY` to your repository's GitHub Actions secrets under **Settings** > **Secrets and variables** > **Actions**. + +See [GitHub Actions integration](/agent-platform/cloud-agents/integrations/github-actions) for the full setup guide for `warpdotdev/oz-agent-action`. + +## 5. Review and improve + +Watch the first few runs in the [Oz web app](https://oz.warp.dev) to verify the agent is labeling and commenting correctly. When you disagree with the agent — when you relabel an issue or edit a comment — note the pattern. Patterns you see repeatedly are signals to update your skill file. + +Add repo-specific context without forking the core skill by creating a `triage-issue-local` companion skill. This file specializes the base skill for your repository — your label taxonomy, your ownership map, your definition of readiness — while keeping the shared skill stable. See the [docs repo example](https://github.com/warpdotdev/docs/blob/main/.agents/skills/triage-issue-local/SKILL.md) for the companion skill pattern. + +## Next steps + +* [What is a software factory?](/agent-platform/cloud-agents/software-factory) — How the triage agent fits into the full development loop. +* [How to write product and tech specs with agents](/guides/agent-workflows/write-product-and-tech-specs-with-agents) — Add the spec role once your backlog is well-triaged. +* [How to build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Automate skill improvement based on your corrections. +* [GitHub Actions integration](/agent-platform/cloud-agents/integrations/github-actions) — Full documentation for `warpdotdev/oz-agent-action`. +* [Run agents unattended](/guides/agent-workflows/how-to-run-unattended-agents) — Broader patterns for cloud agents triggered by external events. diff --git a/src/content/docs/guides/agent-workflows/chain-a-software-factory.mdx b/src/content/docs/guides/agent-workflows/chain-a-software-factory.mdx new file mode 100644 index 00000000..e2bac9ee --- /dev/null +++ b/src/content/docs/guides/agent-workflows/chain-a-software-factory.mdx @@ -0,0 +1,168 @@ +--- +title: "How to chain a software factory: from triage to PR" +description: >- + Connect specialized agents through the full development loop — triage, spec, implement, and review — so new issues become reviewable PRs with minimal manual execution. +sidebar: + label: "Chain a software factory" +tags: + - "agents" + - "software-factory" + - "cloud-agents" +--- + +# How to chain a software factory: from triage to PR + +A software factory chains four specialized agents through the full development loop: a triage agent classifies new issues, a spec agent drafts product and tech specs, an implementation agent builds against those specs, and a reviewer agent validates the result. The output of each agent becomes the input for the next. You review pull requests — not individual steps. + +This guide shows how to connect those agents into a working loop using GitHub labels as the state machine, skills as the agent instructions, and Oz as the orchestration layer. + +## Prerequisites + +* Each agent role working individually. Follow the individual guides first: + * [How to build a triage agent](/guides/agent-workflows/build-a-triage-agent) + * [How to write product and tech specs with agents](/guides/agent-workflows/write-product-and-tech-specs-with-agents) +* **Oz environment** — A cloud environment with your repository checked out. See [Environments](/agent-platform/cloud-agents/environments). +* **`warpdotdev/oz-agent-action`** installed — See [GitHub Actions integration](/agent-platform/cloud-agents/integrations/github-actions). + +## 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 [How to build a triage agent](/guides/agent-workflows/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: + +```yaml +name: Write specs for ready issues + +on: + issues: + types: [labeled] + +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 + env: + WARP_API_KEY: ${{ secrets.WARP_API_KEY }} + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +The `spec-driven-implementation` skill from [`warpdotdev/common-skills`](https://github.com/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: + +```yaml +name: Implement from approved specs + +on: + issues: + types: [labeled] + +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 + env: + WARP_API_KEY: ${{ secrets.WARP_API_KEY }} + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +The `implement-specs` skill from [`warpdotdev/common-skills`](https://github.com/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: + +```yaml +name: Review new pull requests + +on: + pull_request: + types: [opened, synchronize] + +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 specs are available in specs/${{ github.event.pull_request.number }}/, validate the implementation against them. + environment: YOUR_OZ_ENVIRONMENT_SLUG + env: + WARP_API_KEY: ${{ secrets.WARP_API_KEY }} + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +The `review-pr` skill from [`warpdotdev/common-skills`](https://github.com/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](/guides/agent-workflows/how-to-review-ai-generated-code) for the full human review workflow. + +## Reference implementation + +[`warpdotdev/oz-for-oss`](https://github.com/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](https://oz.warp.dev) 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?](/agent-platform/cloud-agents/software-factory) — The conceptual overview of the full loop. +* [How to run a software factory in the cloud](/guides/agent-workflows/run-a-software-factory-in-the-cloud) — Move the loop into a managed Oz deployment. +* [How to build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Add the outer improvement loop. +* [Review AI-generated code](/guides/agent-workflows/how-to-review-ai-generated-code) — The human review workflow for agent-generated PRs. +* [`warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss) — The complete reference implementation. +* [GitHub Actions integration](/agent-platform/cloud-agents/integrations/github-actions) — Full documentation for triggering Oz agents from CI. diff --git a/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx b/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx new file mode 100644 index 00000000..c74c443e --- /dev/null +++ b/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx @@ -0,0 +1,112 @@ +--- +title: How to run a software factory in the cloud +description: >- + Move your software factory loop off developer machines and into Oz — with cloud environments, event-driven triggers, least-privilege permissions, and full run auditability. +sidebar: + label: "Run a software factory in the cloud" +tags: + - "agents" + - "cloud-agents" + - "software-factory" + - "orchestration" +--- + +# How to run a software factory in the cloud + +A software factory running on a developer's machine is limited by local compute, requires the machine to be on, and is invisible to the rest of the team. Moving it to Oz gives you parallel cloud runs, event-driven triggers, team-visible sessions with sharing links, and a control plane that runs around the clock. + +This guide covers the four things you need to move the factory loop into Oz: environments, secrets and permissions, triggers, and observability. + +## Prerequisites + +* **A working factory loop** — Follow [How to chain a software factory: from triage to PR](/guides/agent-workflows/chain-a-software-factory) to set up the individual agent roles first. +* **An Oz team** — Sign into [oz.warp.dev](https://oz.warp.dev) or access Oz from within Warp. + +## Why cloud agents, not cloud computers + +A common approach to cloud-based agents is to spin up a persistent virtual machine — a "cloud computer" — that the agent logs into and uses like a developer's laptop. Oz uses a different model: each agent run is a short-lived, scoped execution with its own environment and permissions, similar to a cloud function rather than a long-running server. + +The practical difference: + +* **Per-agent permissions** — Your triage agent only needs to read issues and post comments. Your implementation agent needs to push branches and open PRs. Each agent gets exactly the permissions it needs, not a single shared credential that everything uses. +* **Audit trails** — Every cloud agent run is logged separately. You can see exactly what the triage agent did versus what the implementation agent did, when it ran, and what it produced. +* **Team visibility** — Any teammate can open a run in the Oz web app to inspect the session transcript, steer a stuck agent, or pick up where the agent left off. +* **Scale without contention** — Multiple triage runs can execute in parallel without fighting over a shared dev box, local git checkouts, or CPU. + +See [Deployment patterns](/agent-platform/cloud-agents/deployment-patterns) for a full comparison of Oz-hosted, CLI-based, and self-hosted execution patterns. + +## 1. Set up a cloud environment + +An Oz environment is a Docker-based sandbox with your repository, secrets, and any tools the agents need. Create one from the Oz web app or the CLI: + +```bash +oz environment create \ + --name my-factory \ + --repo https://github.com/YOUR_ORG/YOUR_REPO \ + --branch main +``` + +For repositories that need language toolchains, databases, or other dependencies, start from a predefined environment in [`warpdotdev/oz-dev-environments`](https://github.com/warpdotdev/oz-dev-environments). These are Docker images pre-configured for common stacks. Copy the relevant Dockerfile into your repository and reference it when creating the environment. + +See [Environments](/agent-platform/cloud-agents/environments) for the full reference. + +## 2. Add secrets and permissions + +Each agent role in your factory needs access to different secrets. Add them at the environment level rather than embedding them in prompts: + +```bash +oz secret create --name GITHUB_TOKEN --value YOUR_TOKEN +``` + +Secrets are scoped to your team, injected into cloud runs at execution time, and never visible in session transcripts. + +Grant each agent role only the GitHub permissions it needs: + +* **Triage agent** — Read issues and post comments +* **Spec agent** — Push branches and open draft PRs +* **Implementation agent** — Push branches and open PRs +* **Reviewer agent** — Post review comments on PRs + +Use fine-grained personal access tokens or separate GitHub App installations to enforce least privilege per role. See [Secrets](/agent-platform/cloud-agents/secrets) for management details and [GitHub Actions integration](/agent-platform/cloud-agents/integrations/github-actions) for token setup patterns. + +## 3. Configure triggers + +With GitHub Actions, your factory already has event-based triggers. Oz also provides first-party integrations that handle triggering without GitHub Actions boilerplate: + +* **Slack** — Teammates can kick off a run by mentioning `@warp` in a Slack thread. Useful for one-off requests that don't need the full label workflow. See [Slack integration](/agent-platform/cloud-agents/integrations/slack). +* **Linear** — When an issue in Linear reaches a specific status, a cloud agent run starts automatically. Useful for teams that track work in Linear rather than GitHub Issues. See [Linear integration](/agent-platform/cloud-agents/integrations/linear). +* **Scheduled agents** — For the outer improvement loop (which runs on a cadence rather than an event), use a scheduled cloud agent. See [Scheduled agents](/agent-platform/cloud-agents/triggers/scheduled-agents). +* **Oz API and SDK** — For custom triggers — webhooks, internal dashboards, other events — use the [Oz API and SDK](/reference/api-and-sdk) to start runs programmatically. + +## 4. Monitor factory runs + +Every cloud agent run in your factory appears in the Oz dashboard with: + +* A session transcript showing every action the agent took +* Artifacts: PRs, branches, plans, and reports the agent produced +* Status history: queued, in progress, succeeded, or failed with error details +* A session sharing link any teammate can open to inspect or steer the run + +Open runs from [oz.warp.dev](https://oz.warp.dev) or from the **Agent Management Panel** in the Warp app. Include the session link in PR descriptions so reviewers can see exactly how the agent built the change — see [Attach agent context to GitHub PRs](/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs). + +See [Viewing cloud agent runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs) for the full reference. + +## 5. Use multi-agent orchestration for large backlogs + +When a sprint starts and you want to process many issues in parallel, Oz can fan out to child agents — one per issue — from a single parent run. The parent coordinates; the children execute in parallel, each with their own environment, prompt, and permissions. + +See [Multi-agent orchestration](/agent-platform/cloud-agents/orchestration) for fan-out, sharding, and result aggregation patterns. + +## Productivity tips + +* **Start with one agent role in the cloud** — Get the triage agent running as a cloud run before moving all four roles. Confirm that the environment, secrets, and permissions work correctly before expanding. +* **Add session links to PR descriptions** — When the implementation agent opens a PR, include the Oz run link so reviewers get the full context. See [Attach agent context to GitHub PRs](/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs) for a template. +* **Monitor credit usage** — Cloud agent runs consume credits. Monitor usage in the Oz web app and adjust run scope if needed. See [Credits](/support-and-community/plans-and-billing/credits). + +## Next steps + +* [What is a software factory?](/agent-platform/cloud-agents/software-factory) — The conceptual overview of the full loop. +* [How to build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Add the outer improvement loop on a schedule. +* [Environments](/agent-platform/cloud-agents/environments) — Full reference for cloud agent environments. +* [Deployment patterns](/agent-platform/cloud-agents/deployment-patterns) — Choose the right architecture for your team. +* [Self-hosting](/agent-platform/cloud-agents/self-hosting) — Run Oz agent workers on your own infrastructure when code must stay on-premises. diff --git a/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx b/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx new file mode 100644 index 00000000..10f67c1a --- /dev/null +++ b/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx @@ -0,0 +1,100 @@ +--- +title: How to write product and tech specs with agents +description: >- + Use agents to turn a ready-to-implement issue into a product spec and a tech spec — the blueprints that guide implementation and anchor code review. +sidebar: + label: "Write specs with agents" +tags: + - "agents" + - "software-factory" +--- + +# How to write product and tech specs with agents + +Use agents to turn a triaged GitHub issue into two spec files: a product spec that describes what the feature should do from the user's perspective, and a tech spec that describes how to implement it. Implementation agents use these specs as blueprints; reviewers use them as acceptance criteria. The agent does the drafting — you do the reviewing. + +:::note +Writing a good spec requires understanding the problem. The agent can draft the spec and fill in structure, but you need to read and approve it before implementation begins. A well-reviewed spec saves more time in implementation than it takes to write. +::: + +## Prerequisites + +* **Warp with Oz** — [Sign in and set up Oz](/agent-platform/getting-started/agents-in-warp) if you haven't already. +* **A triaged issue** — An issue labeled `ready-to-spec` or equivalent. See [How to build a triage agent](/guides/agent-workflows/build-a-triage-agent) to set up triaging. +* **`common-skills` installed** — The spec skills live in `warpdotdev/common-skills`. Install them globally: + + ```bash + npx skills@latest add warpdotdev/common-skills --skill write-product-spec --agent warp --global + npx skills@latest add warpdotdev/common-skills --skill write-tech-spec --agent warp --global + ``` + + See [`warpdotdev/common-skills`](https://github.com/warpdotdev/common-skills) for all available skills and installation options. + +## 1. Write the product spec + +A product spec defines what the feature should do from the user's perspective: user stories, acceptance criteria, and edge cases. It is the "what," not the "how." + +Open the issue you want to spec in Warp and run: + +``` +/write-product-spec +``` + +The agent creates a `PRODUCT.md` file in a `specs/[issue-number]/` directory in your repository. The file includes: + +* A summary of the feature +* User stories in the format "As a [user], I want [behavior] so that [outcome]" +* Acceptance criteria the implementation agent and reviewers can verify +* Edge cases and constraints + +Review the draft carefully. The agent makes reasonable assumptions, but you know your users. Correct any misunderstandings before moving to the tech spec — a wrong product spec leads to a correct implementation of the wrong thing. + +## 2. Write the tech spec + +A tech spec defines how the feature will be implemented: architecture decisions, relevant code locations, API shapes, and implementation notes. It is the "how." + +After reviewing the product spec, run: + +``` +/write-tech-spec +``` + +The agent reads your codebase (using [Codebase Context](/agent-platform/capabilities/codebase-context)), the product spec you just approved, and creates a `TECH.md` file in the same `specs/[issue-number]/` directory. + +The file includes: + +* An overview of the implementation approach +* The specific files and functions that need to change +* Any new data structures, API endpoints, or interfaces +* Testing strategy +* Known risks or tradeoffs + +Review the tech spec with the same care as the product spec. An accurate `TECH.md` reduces the number of implementation iterations and gives reviewers the context to understand why the code looks the way it does. + +## 3. Validate that the implementation matches the specs + +When an implementation agent opens a PR for this issue, run the validation skill to check the diff against both spec files: + +``` +/validate-changes-match-specs +``` + +The agent checks the PR diff against `PRODUCT.md` and `TECH.md` and returns a list of any inconsistencies for you to review before submitting the PR for human review. This skill is also available from [`warpdotdev/common-skills`](https://github.com/warpdotdev/common-skills). + +## 4. Include specs in the implementation PR + +The `specs/[issue-number]/` directory should be committed alongside the code changes in the implementation PR. This gives reviewers the full picture: what was intended (PRODUCT.md), how it was planned (TECH.md), and what was built (the code diff). There is no need to cross-reference separately. + +## Productivity tips + +* **Spec before you code, not after** — The biggest value from specs is catching misaligned assumptions before any code is written. Running `/write-product-spec` first forces that alignment to happen early, when fixing it is cheap. +* **Attach Figma mocks** — If your feature has a UI component, attach a Figma screenshot or mockup to your prompt when running `/write-product-spec`. The agent incorporates visual context into the acceptance criteria. +* **Use `/plan` for smaller tasks** — For changes that don't warrant a full PRODUCT.md and TECH.md, use Warp's built-in [planning feature](/agent-platform/capabilities/planning). Plans can be saved, versioned, and attached to PRs without a full spec workflow. + +## Next steps + +* [What is a software factory?](/agent-platform/cloud-agents/software-factory) — How specs fit into the full development loop. +* [How to chain a software factory: from triage to PR](/guides/agent-workflows/chain-a-software-factory) — Connect the spec role to implementation and review. +* [`warpdotdev/common-skills`](https://github.com/warpdotdev/common-skills) — The full set of shared skills including `write-product-spec`, `write-tech-spec`, and `validate-changes-match-specs`. +* [Planning](/agent-platform/capabilities/planning) — Warp's built-in planning feature for smaller tasks. +* [Skills](/agent-platform/capabilities/skills) — How skill files work in Warp and Oz. diff --git a/src/sidebar.ts b/src/sidebar.ts index 14dafded..64ea52d1 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -396,8 +396,9 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ ], }, { slug: 'agent-platform/cloud-agents/mcp', label: 'MCP servers' }, - { slug: 'agent-platform/cloud-agents/deployment-patterns', label: 'Deployment patterns' }, - { slug: 'agent-platform/cloud-agents/warp-hosting', label: 'Warp-hosted agents' }, + { slug: 'agent-platform/cloud-agents/deployment-patterns', label: 'Deployment patterns' }, + { slug: 'agent-platform/cloud-agents/software-factory', label: 'Software factory' }, + { slug: 'agent-platform/cloud-agents/warp-hosting', label: 'Warp-hosted agents' }, { label: 'Self-hosting', collapsed: true, @@ -651,6 +652,17 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'guides/agent-workflows/running-multiple-agents-at-once-with-warp', label: 'Coordinate agents on separate tasks' }, ], }, + { + label: 'Build a software factory', + collapsed: true, + items: [ + { slug: 'guides/agent-workflows/build-a-triage-agent', label: 'Build a triage agent' }, + { slug: 'guides/agent-workflows/write-product-and-tech-specs-with-agents', label: 'Write specs with agents' }, + { slug: 'guides/agent-workflows/chain-a-software-factory', label: 'Chain a software factory' }, + { slug: 'guides/agent-workflows/run-a-software-factory-in-the-cloud', label: 'Run a software factory in the cloud' }, + { slug: 'guides/agent-workflows/build-a-self-improving-agent', label: 'Build a self-improving agent' }, + ], + }, { label: 'Configuration', collapsed: true, From 104c0ec9fca28156fe74b31a750ae6b64bdb3a14 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Wed, 17 Jun 2026 12:24:58 -0600 Subject: [PATCH 2/9] fix: normalize sidebar.ts indentation for deployment-patterns, software-factory, warp-hosting Align three entries to 6-tab depth matching all other items in the Oz Cloud Agents & Orchestration items array. Co-Authored-By: Oz --- src/sidebar.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/sidebar.ts b/src/sidebar.ts index 32ea7f6a..2a0a2065 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -397,9 +397,9 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ ], }, { slug: 'agent-platform/cloud-agents/mcp', label: 'MCP servers' }, - { slug: 'agent-platform/cloud-agents/deployment-patterns', label: 'Deployment patterns' }, - { slug: 'agent-platform/cloud-agents/software-factory', label: 'Software factory' }, - { slug: 'agent-platform/cloud-agents/warp-hosting', label: 'Warp-hosted agents' }, + { slug: 'agent-platform/cloud-agents/deployment-patterns', label: 'Deployment patterns' }, + { slug: 'agent-platform/cloud-agents/software-factory', label: 'Software factory' }, + { slug: 'agent-platform/cloud-agents/warp-hosting', label: 'Warp-hosted agents' }, { label: 'Self-hosting', collapsed: true, From 1366a6527b51ee3213936bc49b81cf3dcf96b570 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Wed, 17 Jun 2026 13:31:10 -0600 Subject: [PATCH 3/9] fix: address oz-for-oss bot review comments - build-a-triage-agent: add permissions block, move warp_api_key to with: - chain-a-software-factory: add role-specific permissions blocks to all three workflows, move warp_api_key to with:, fix reviewer prompt to search changed specs/ files instead of using PR number - write-product-and-tech-specs: add bash language to slash-command fences - run-a-software-factory-in-the-cloud: fix oz environment create syntax (owner/repo format, remove unsupported --branch flag), fix oz secret create to not expose --value on command line Also adds Oz CLI + GitHub Actions guardrails to draft_guide/SKILL.md to prevent these classes of error in future guide drafts. Co-Authored-By: Oz --- .agents/skills/draft_guide/SKILL.md | 23 +++++++++++++++++++ .../agent-workflows/build-a-triage-agent.mdx | 5 +++- .../chain-a-software-factory.mdx | 20 ++++++++++++---- .../run-a-software-factory-in-the-cloud.mdx | 7 +++--- ...ite-product-and-tech-specs-with-agents.mdx | 6 ++--- 5 files changed, 49 insertions(+), 12 deletions(-) diff --git a/.agents/skills/draft_guide/SKILL.md b/.agents/skills/draft_guide/SKILL.md index d8659f89..209b8d51 100644 --- a/.agents/skills/draft_guide/SKILL.md +++ b/.agents/skills/draft_guide/SKILL.md @@ -49,6 +49,29 @@ When drafting a guide, check for relevant SEO and AEO data: 4. **Frame the title for non-branded search.** The page should answer the user's actual question, with Warp features as the natural solution in the guide body. 5. **Avoid keyword stuffing.** Preserve high-intent query terms only where they make the guide clearer or more discoverable. Rewrite awkward source-data phrasing into natural developer language. +## Oz CLI and GitHub Actions accuracy + +When a guide includes Oz CLI commands or GitHub Actions workflows using `warpdotdev/oz-agent-action`: + +- **Verify Oz CLI commands against `/reference/cli/`.** Do not infer flag names or argument formats. Use only flags documented in the CLI reference. When in doubt, link to the reference page instead of showing a command. +- **`oz-agent-action` input format**: `warp_api_key` is a `with:` input to the action, not an `env:` variable. `GITHUB_TOKEN` goes in `env:`. The correct pattern is: + ```yaml + - uses: warpdotdev/oz-agent-action@v1 + with: + skill: SKILL_NAME + environment: YOUR_OZ_ENVIRONMENT_SLUG + warp_api_key: ${{ secrets.WARP_API_KEY }} + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + ``` +- **Every GitHub Actions workflow example that performs write operations must include a `permissions:` block** at the workflow level, before `jobs:`. Use the minimum permissions for the task: + - Triage (label/comment on issues): `issues: write` + - Spec/implementation (push branches, open PRs): `contents: write`, `pull-requests: write` + - Review (post PR comments): `pull-requests: write` + Without an explicit `permissions:` block, workflows fail in repositories with restricted default permissions. +- **`oz secret create` must not include `--value` on the command line.** The `--value` flag exposes secrets in shell history and process arguments. Show `oz secret create --name SECRET_NAME` and note that the CLI prompts for the value interactively. +- **Slash commands** (`/command-name`) in standalone code fences should use `bash` as the language identifier, consistent with the docs style guide for terminal input. + ## Third-party tool accuracy When a guide documents a third-party tool (Claude Code, Codex, OpenCode, etc.): diff --git a/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx b/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx index 6c8ac363..dbc13e55 100644 --- a/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx +++ b/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx @@ -81,6 +81,9 @@ on: issues: types: [opened] +permissions: + issues: write + jobs: triage: runs-on: ubuntu-latest @@ -94,8 +97,8 @@ jobs: 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: - WARP_API_KEY: ${{ secrets.WARP_API_KEY }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} ``` diff --git a/src/content/docs/guides/agent-workflows/chain-a-software-factory.mdx b/src/content/docs/guides/agent-workflows/chain-a-software-factory.mdx index e2bac9ee..98bb01b1 100644 --- a/src/content/docs/guides/agent-workflows/chain-a-software-factory.mdx +++ b/src/content/docs/guides/agent-workflows/chain-a-software-factory.mdx @@ -54,6 +54,11 @@ on: issues: types: [labeled] +permissions: + contents: write + pull-requests: write + issues: write + jobs: write-specs: if: github.event.label.name == 'ready-to-spec' @@ -68,8 +73,8 @@ jobs: 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: - WARP_API_KEY: ${{ secrets.WARP_API_KEY }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} ``` @@ -92,6 +97,10 @@ on: issues: types: [labeled] +permissions: + contents: write + pull-requests: write + jobs: implement: if: github.event.label.name == 'ready-to-implement' @@ -105,8 +114,8 @@ jobs: 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: - WARP_API_KEY: ${{ secrets.WARP_API_KEY }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} ``` @@ -123,6 +132,9 @@ on: pull_request: types: [opened, synchronize] +permissions: + pull-requests: write + jobs: review: runs-on: ubuntu-latest @@ -133,10 +145,10 @@ jobs: skill: review-pr prompt: | Review pull request #${{ github.event.pull_request.number }} in ${{ github.repository }}. - If specs are available in specs/${{ github.event.pull_request.number }}/, validate the implementation against them. + 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: - WARP_API_KEY: ${{ secrets.WARP_API_KEY }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} ``` diff --git a/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx b/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx index c74c443e..1842bdea 100644 --- a/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx +++ b/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx @@ -42,8 +42,7 @@ An Oz environment is a Docker-based sandbox with your repository, secrets, and a ```bash oz environment create \ --name my-factory \ - --repo https://github.com/YOUR_ORG/YOUR_REPO \ - --branch main + --repo YOUR_ORG/YOUR_REPO ``` For repositories that need language toolchains, databases, or other dependencies, start from a predefined environment in [`warpdotdev/oz-dev-environments`](https://github.com/warpdotdev/oz-dev-environments). These are Docker images pre-configured for common stacks. Copy the relevant Dockerfile into your repository and reference it when creating the environment. @@ -55,10 +54,10 @@ See [Environments](/agent-platform/cloud-agents/environments) for the full refer Each agent role in your factory needs access to different secrets. Add them at the environment level rather than embedding them in prompts: ```bash -oz secret create --name GITHUB_TOKEN --value YOUR_TOKEN +oz secret create --name GITHUB_TOKEN ``` -Secrets are scoped to your team, injected into cloud runs at execution time, and never visible in session transcripts. +The CLI prompts for the value interactively so it never appears in shell history or process arguments. Secrets are scoped to your team, injected into cloud runs at execution time, and never visible in session transcripts. Grant each agent role only the GitHub permissions it needs: diff --git a/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx b/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx index 10f67c1a..2546ad52 100644 --- a/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx +++ b/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx @@ -36,7 +36,7 @@ A product spec defines what the feature should do from the user's perspective: u Open the issue you want to spec in Warp and run: -``` +```bash /write-product-spec ``` @@ -55,7 +55,7 @@ A tech spec defines how the feature will be implemented: architecture decisions, After reviewing the product spec, run: -``` +```bash /write-tech-spec ``` @@ -75,7 +75,7 @@ Review the tech spec with the same care as the product spec. An accurate `TECH.m When an implementation agent opens a PR for this issue, run the validation skill to check the diff against both spec files: -``` +```bash /validate-changes-match-specs ``` From fbd37e77fa60ca00a1d1b3099c93b2747d9fb27e Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Thu, 18 Jun 2026 13:54:26 -0600 Subject: [PATCH 4/9] docs(software-factory): address concept page review feedback - Rewrite description: remove 'chains' and em-dashes, improve SEO framing - Opening sentence: add 'development' back, replace 'handle the full cycle' with concrete triage/spec/implement/review flow - Remove Rectangle Health sentence from intro (awkward placement) - Add orienting sentence before H2 sections - Soften 'Every software factory' to 'A software factory' - Shorten inner/outer loop numbered lists to brief prose; detail lives in Agent roles section - Remove unsourced 'In practice, most teams...' claim - Remove em dash from skill definition - Remove stale TODO comment (guide links are live in this PR) Co-Authored-By: Oz --- .../cloud-agents/software-factory.mdx | 27 ++++++++++--------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/software-factory.mdx b/src/content/docs/agent-platform/cloud-agents/software-factory.mdx index 491ba781..6dcefdef 100644 --- a/src/content/docs/agent-platform/cloud-agents/software-factory.mdx +++ b/src/content/docs/agent-platform/cloud-agents/software-factory.mdx @@ -1,24 +1,26 @@ --- title: Software factory description: >- - A software factory chains specialized agents through the full development loop — from issue triage through spec, implementation, and review — so teams get PRs to review instead of executing every step. + A software factory uses specialized agents to take new issues through triage, spec, implementation, and review, producing pull requests for your team to merge. sidebar: label: "Software factory" --- # Software factory -A software factory is a development system where specialized agents handle the full cycle from a new issue to a reviewable pull request. Instead of every developer executing every step — reading each issue, writing specs, implementing changes, reviewing output — agents handle the execution and humans review the results. The team's job shifts from doing the work to defining the process and raising the quality bar over time. +A software factory is a development system where specialized agents take new issues through triage, spec, implementation, and review, producing pull requests for your team to merge. Instead of every developer executing every step — reading each issue, writing specs, implementing changes, reviewing output — agents do the execution and humans review the results. The team's job shifts from doing the work to defining the process and raising the quality bar over time. -Warp uses this model to build Warp itself. The [agent dashboard at build.warp.dev](https://build.warp.dev) shows the work Warp's agents are tackling across the open source repository in real time. Rectangle Health's Rex agent — built on Oz — ships 35,000 lines of production code per week and has written more than 50% of its own codebase. +Warp uses this model to build Warp itself. The [agent dashboard at build.warp.dev](https://build.warp.dev) shows the work Warp's agents are tackling across the open source repository in real time. + +Read on to learn about the two loops that make up a software factory, the agent roles involved, and when this model is a good fit. ## The two loops -Every software factory has two loops that work together. +A software factory has two loops that work together. -The **inner loop** is the execution loop. A new issue enters the backlog. A triage agent reviews it for clarity, labels it, and flags open questions before any implementation starts. A spec agent drafts a product spec (what the feature should do) and a tech spec (how to implement it). An implementation agent builds against the approved specs. A reviewer agent checks the result for correctness, style, and spec compliance. The output is a pull request in GitHub for a human to review and merge. +**The inner loop** is the execution loop: a triage agent, spec agent, implementation agent, and reviewer agent work in sequence, turning a new issue into a pull request for human review. -The **outer loop** is the improvement loop. A scheduled cloud agent runs on a cadence, reviews past inner-loop runs, and observes where maintainers corrected the agents — relabeled issues, revised comments, adjusted code. It opens a pull request to improve the skill files that drive the inner-loop agents. Over time, the factory gets better without anyone manually rewriting prompts. +**The outer loop** is the improvement loop: a scheduled agent reviews past inner-loop runs, observes where maintainers made corrections, and opens a pull request to update the skill files that drive the inner-loop agents. Over time, the factory gets better without anyone manually rewriting prompts. The inner loop ships software. The outer loop improves the factory that ships it. @@ -31,27 +33,27 @@ A software factory delegates work to specialized agents, each with a narrow resp * **Implementation agent** - Builds against approved specs. Uses spec context to make better architectural decisions and raises a blocked status when specs are missing or ambiguous rather than guessing. * **Reviewer agent** - Checks the implementation against specs, code conventions, and security requirements. Posts inline review comments and validates that acceptance criteria are met before a human reviewer opens the PR. -In practice, a single agent often covers multiple roles in early-stage setups, and most teams start with just a triage agent before adding the rest. The [`warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss) repository is the complete reference implementation with all four roles deployed in a working system. +The [`warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss) repository is the complete reference implementation with all four roles deployed in a working system. ## How it works -Each agent role is backed by a **skill** — a markdown file checked into a Git repository that defines the agent's behavior: what to check, how to classify results, what to output, and when to escalate. Skills are versioned, reviewed as code changes, and composable across repositories. +Each agent role is backed by a **skill**, a markdown file checked into a Git repository that defines the agent's behavior: what to check, how to classify results, what to output, and when to escalate. Skills are versioned, reviewed as code changes, and composable across repositories. When a new issue is filed on GitHub, a webhook or GitHub Action triggers the triage agent. The agent runs in a cloud environment using the triage skill, analyzes the issue, and applies labels and comments. When an issue is labeled `ready-to-spec`, the spec agent runs and creates `PRODUCT.md` and `TECH.md` files in a `specs/` directory in the repository. A human reviews and approves those specs. When the implementation label is applied, the implementation agent runs and opens a PR that includes the spec files alongside the code. Oz orchestrates each agent as a cloud run. Every run has its own environment (repository checkout, secrets, toolchain), its own permissions, and a session link your team can use to inspect what the agent did, steer it mid-run, or hand work back to a local session. -The outer improvement loop runs as a scheduled cloud agent. It collects signals from past inner-loop runs — maintainer relabels, edits to agent-written comments, code changes after agent PRs — and generates a diff to the relevant skill files. That diff goes through a normal pull request review before merging. Humans decide what improves; agents propose it. +The outer improvement loop runs as a scheduled cloud agent. It collects signals from past inner-loop runs and generates a diff to the relevant skill files. That diff goes through a normal pull request review before merging. Humans decide what improves; agents propose it. ## When to use a software factory A software factory is a strong fit when: -* Your team has a repeatable development workflow — a backlog of issues with consistent shape, and a process you can write down and teach to an agent. -* The cost of a missed edge case in agent output is recoverable — the agent opens a pull request, not a deploy, so humans stay in control of what ships. +* Your team has a repeatable development workflow: a backlog of issues with consistent shape, and a process you can write down and teach to an agent. +* The cost of a missed edge case in agent output is recoverable. The agent opens a pull request, not a deploy, so humans stay in control of what ships. * You want to scale throughput without scaling headcount linearly, or you want to move faster on a large backlog with a small team. -Start with one agent role. Most teams start with a triage agent — it is the simplest loop to close correctly, and a well-groomed backlog immediately benefits every developer on the team. Add spec, implementation, and reviewer agents as you build confidence in each step. +Start with one agent role. Most teams start with a triage agent, which is the simplest loop to close correctly. A well-groomed backlog immediately benefits every developer on the team. Add spec, implementation, and reviewer agents as you build confidence in each step. ## Reference implementation @@ -59,7 +61,6 @@ Start with one agent role. Most teams start with a triage agent — it is the si ## Related pages -{/* TODO: Update guide links once software-factory guide PRs are merged */} * [How to build a triage agent for your issue backlog](/guides/agent-workflows/build-a-triage-agent) — Start the series with the simplest agent role. * [How to write product and tech specs with agents](/guides/agent-workflows/write-product-and-tech-specs-with-agents) — Write specs that guide implementation agents. * [How to chain a software factory: from triage to PR](/guides/agent-workflows/chain-a-software-factory) — Connect the four roles into a working loop. From 389a15de48859f2b64c5b75cd40dfccfa004d278 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Thu, 18 Jun 2026 15:14:26 -0600 Subject: [PATCH 5/9] Rename and retitle software factory guides; remove 'How to' from all titles MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename chain-a-software-factory.mdx → set-up-a-software-factory.mdx - Retitle to 'Set up your software factory: from triage to PR' - Remove 'How to' prefix from all five guide titles - Reframe opening paragraph to describe unique contribution of guide 3 (adds implementation + reviewer agents and wires all four into full loop) - Update sidebar.ts slug and label for renamed guide - Add vercel.json redirect for old URL - Update all cross-references and link text across all six files - Fix 'Warp with Oz' prereq → 'A Warp account' in two remaining guides - Update .agents/templates to add title field and remove H1 line note Co-Authored-By: Oz --- .agents/templates/conceptual.md | 3 +- .agents/templates/guide-page.md | 5 +- .../cloud-agents/software-factory.mdx | 14 ++-- .../build-a-self-improving-agent.mdx | 76 +++++++++---------- .../agent-workflows/build-a-triage-agent.mdx | 58 +++++++------- .../run-a-software-factory-in-the-cloud.mdx | 8 +- ...tory.mdx => set-up-a-software-factory.mdx} | 22 +++--- ...ite-product-and-tech-specs-with-agents.mdx | 56 ++++++-------- src/sidebar.ts | 2 +- vercel.json | 5 ++ 10 files changed, 118 insertions(+), 131 deletions(-) rename src/content/docs/guides/agent-workflows/{chain-a-software-factory.mdx => set-up-a-software-factory.mdx} (83%) diff --git a/.agents/templates/conceptual.md b/.agents/templates/conceptual.md index 0f90858d..6cd6158a 100644 --- a/.agents/templates/conceptual.md +++ b/.agents/templates/conceptual.md @@ -1,11 +1,10 @@ --- +title: [Feature or concept name — sentence case. Title convention: noun or "About [subject]". The title field renders as the page H1; do not add a separate H1 in the body.] description: >- [1-2 sentences: what the concept/feature is + why it matters. Write as a standalone summary for search results. Lead with user benefit.] --- -# [Feature or concept name — sentence case. Title convention: noun or "About [subject]"] - [Opening paragraph: What this feature/concept is and its primary benefit. 1-3 sentences. Lead with what the user gains from understanding this.] diff --git a/.agents/templates/guide-page.md b/.agents/templates/guide-page.md index 2a7aea40..01ad2024 100644 --- a/.agents/templates/guide-page.md +++ b/.agents/templates/guide-page.md @@ -1,13 +1,10 @@ --- +title: [Task-oriented title in sentence case — reads like a search query. Capture the non-branded query a developer would actually search for, not "How to do X in Warp." The title field renders as the page H1; do not add a separate H1 in the body.] description: >- [1-2 sentence summary of what this guide covers and what the reader will achieve. Keep under 160 characters for SEO.] --- -# [Task-oriented title in sentence case — reads like a search query] - -[TITLE GUIDANCE: Title should describe what the reader will DO, not what the feature IS. For SEO, capture the non-branded query — write the title a developer would actually search for, not "How to do X in Warp." Good: "How to set up Claude Code". Bad: "How to set up Claude Code in Warp".] - [One sentence: what you'll accomplish by following this guide. Mention Warp by name. Include a time estimate if possible (e.g., "takes about 10 minutes").] [AEO GUIDANCE: If this guide is based on Peec, answer-engine prompts, search-query data, or AEO goals, create an AEO brief first using `.agents/skills/aeo_brief/SKILL.md`. Use the brief to preserve high-intent vocabulary naturally, translate awkward source-data phrasing into developer-friendly docs language, and decide whether this should be a new guide or an update to an existing page.] diff --git a/src/content/docs/agent-platform/cloud-agents/software-factory.mdx b/src/content/docs/agent-platform/cloud-agents/software-factory.mdx index 6dcefdef..c04b293d 100644 --- a/src/content/docs/agent-platform/cloud-agents/software-factory.mdx +++ b/src/content/docs/agent-platform/cloud-agents/software-factory.mdx @@ -6,8 +6,6 @@ sidebar: label: "Software factory" --- -# Software factory - A software factory is a development system where specialized agents take new issues through triage, spec, implementation, and review, producing pull requests for your team to merge. Instead of every developer executing every step — reading each issue, writing specs, implementing changes, reviewing output — agents do the execution and humans review the results. The team's job shifts from doing the work to defining the process and raising the quality bar over time. Warp uses this model to build Warp itself. The [agent dashboard at build.warp.dev](https://build.warp.dev) shows the work Warp's agents are tackling across the open source repository in real time. @@ -57,15 +55,15 @@ Start with one agent role. Most teams start with a triage agent, which is the si ## Reference implementation -[`warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss) is Warp's open-source software factory platform for GitHub-hosted repositories. It includes a Vercel webhook layer, GitHub App, and skill files for every agent role in the loop: triage, spec, implementation, review, verification, and self-improvement. Deploy it to your repository in about 30 minutes using the [onboarding guide](https://github.com/warpdotdev/oz-for-oss/blob/main/docs/onboarding.md). +[`warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss) is Warp's open-source software factory platform for GitHub-hosted repositories. It includes a Vercel webhook layer, GitHub App, and skill files for every agent role in the loop: triage, spec, implementation, review, verification, and self-improvement. Get started with the [onboarding guide](https://github.com/warpdotdev/oz-for-oss/blob/main/docs/onboarding.md). ## Related pages -* [How to build a triage agent for your issue backlog](/guides/agent-workflows/build-a-triage-agent) — Start the series with the simplest agent role. -* [How to write product and tech specs with agents](/guides/agent-workflows/write-product-and-tech-specs-with-agents) — Write specs that guide implementation agents. -* [How to chain a software factory: from triage to PR](/guides/agent-workflows/chain-a-software-factory) — Connect the four roles into a working loop. -* [How to run a software factory in the cloud](/guides/agent-workflows/run-a-software-factory-in-the-cloud) — Move the loop off your laptop with Oz. -* [How to build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Add the outer improvement loop. +* [Build a triage agent for your issue backlog](/guides/agent-workflows/build-a-triage-agent) — Start the series with the simplest agent role. +* [Write product and tech specs with agents](/guides/agent-workflows/write-product-and-tech-specs-with-agents) — Write specs that guide implementation agents. +* [Set up your software factory: from triage to PR](/guides/agent-workflows/set-up-a-software-factory) — Connect the four roles into a working loop. +* [Run a software factory in the cloud](/guides/agent-workflows/run-a-software-factory-in-the-cloud) — Move the loop off your laptop with Oz. +* [Build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Add the outer improvement loop. * [Skills](/agent-platform/capabilities/skills) — How skill files work in Warp and Oz. * [Cloud agents overview](/agent-platform/cloud-agents/overview) — Setting up cloud agents on Oz. * [Deployment patterns](/agent-platform/cloud-agents/deployment-patterns) — Common architectures for cloud agent deployment. diff --git a/src/content/docs/guides/agent-workflows/build-a-self-improving-agent.mdx b/src/content/docs/guides/agent-workflows/build-a-self-improving-agent.mdx index c3fb4ede..91b25415 100644 --- a/src/content/docs/guides/agent-workflows/build-a-self-improving-agent.mdx +++ b/src/content/docs/guides/agent-workflows/build-a-self-improving-agent.mdx @@ -1,5 +1,5 @@ --- -title: How to build a self-improving agent +title: Build a self-improving agent description: >- Build an outer improvement loop where a scheduled agent reviews past runs, learns from team corrections, and proposes skill file updates — so your factory gets better over time. sidebar: @@ -11,8 +11,6 @@ tags: - "schedules" --- -# How to build a self-improving agent - A self-improving agent is the outer loop of a software factory: it watches how maintainers correct the inner-loop agents — relabeled issues, edited comments, changed code — and opens a pull request to improve the skill files that drive those agents. Every correction from a teammate becomes a proposed improvement to the factory. This guide shows how to build the outer loop for a triage agent. The same pattern applies to any agent role. @@ -23,8 +21,8 @@ The outer loop proposes improvements; it doesn't apply them silently. Every chan ## Prerequisites -* **A working inner loop** — Follow [How to chain a software factory: from triage to PR](/guides/agent-workflows/chain-a-software-factory) to set up the inner loop first. The outer loop improves agents that are already running. -* **Warp with Oz** — [Sign in and set up Oz](/agent-platform/getting-started/agents-in-warp) if you haven't already. +* **A working inner loop** — Follow [Set up your software factory: from triage to PR](/guides/agent-workflows/set-up-a-software-factory) to set up the inner loop first. The outer loop improves agents that are already running. +* **A Warp account** — Oz is included with Warp. [Sign up at warp.dev](https://www.warp.dev) if you don't have an account. * **Oz environment** — A cloud environment with your repository checked out. See [Environments](/agent-platform/cloud-agents/environments). ## Why principles beat rules @@ -47,52 +45,54 @@ The [`update-triage`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents ## 2. Create the update skill -Create `.agents/skills/update-triage/SKILL.md`. This skill describes how the outer-loop agent should reason about the correction signals it collects: +1. Create `.agents/skills/update-triage/SKILL.md` with the following content as a starting point: -```markdown ---- -name: update-triage -description: Review recent maintainer corrections to the triage agent's output and propose skill file updates that generalize from those corrections. ---- + ```markdown + --- + name: update-triage + description: Review recent maintainer corrections to the triage agent's output and propose skill file updates that generalize from those corrections. + --- -# Update triage skill + # Update triage skill -You are reviewing recent maintainer corrections to the triage agent's output. + You are reviewing recent maintainer corrections to the triage agent's output. -## What to look for + ## What to look for -For each correction: -1. Identify what the triage agent did (the original label or comment). -2. Identify what the maintainer did instead (the correction). -3. Ask: why would the triage agent have gotten this wrong? -4. Ask: what principle would prevent this class of error in the future? + For each correction: + 1. Identify what the triage agent did (the original label or comment). + 2. Identify what the maintainer did instead (the correction). + 3. Ask: why would the triage agent have gotten this wrong? + 4. Ask: what principle would prevent this class of error in the future? -## What to update + ## What to update -Update only the triage-issue-local companion skill for this repository. -Write principles, not rules. Do not update the shared triage-issue skill. + Update only the triage-issue-local companion skill for this repository. + Write principles, not rules. Do not update the shared triage-issue skill. -Commit changes to a branch named oz-agent/update-triage. -Do not push directly to main. Open a pull request for human review. -``` + Commit changes to a branch named oz-agent/update-triage. + Do not push directly to main. Open a pull request for human review. + ``` -Use the full [`update-triage` skill from `warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents/skills/update-triage/SKILL.md) as the complete reference — it includes the collection script, write-surface restrictions that prevent the agent from modifying the wrong files, and the PR-opening workflow. +2. For the complete implementation — including the correction-collection script, write-surface restrictions, and PR-opening workflow — use the [`update-triage` skill from `warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents/skills/update-triage/SKILL.md) as your reference. ## 3. Schedule the outer loop -Run the outer loop on a cadence. Weekly on Monday morning works well for most teams — it processes the previous week's corrections and opens PRs for review at the start of the week. +Weekly is a good starting cadence: it processes the previous week's corrections and opens PRs for review at the start of the week. + +1. Create a scheduled cloud agent from the Oz CLI: -Create a scheduled cloud agent from the Oz CLI: + ```bash + oz schedule create \ + --name update-triage-weekly \ + --skill update-triage \ + --environment YOUR_ENVIRONMENT_SLUG \ + --cron "0 9 * * 1" + ``` -```bash -oz schedule create \ - --name update-triage-weekly \ - --skill update-triage \ - --environment YOUR_ENVIRONMENT_SLUG \ - --cron "0 9 * * 1" -``` + Or, from the Oz web app: open **Agents** > **Schedules**, click **New schedule**, and set the skill, environment, and cron expression. -Or create the schedule from the Oz web app: open **Agents** > **Schedules**, click **New schedule**, and set the skill, environment, and cron expression. +2. Replace `YOUR_ENVIRONMENT_SLUG` with the slug of your Oz environment. See [Scheduled agents](/agent-platform/cloud-agents/triggers/scheduled-agents) for the full reference. @@ -117,8 +117,8 @@ Over time, the companion skill accumulates a clear description of how your team ## Next steps * [What is a software factory?](/agent-platform/cloud-agents/software-factory) — How the outer improvement loop fits into the full factory model. -* [How to chain a software factory: from triage to PR](/guides/agent-workflows/chain-a-software-factory) — The inner loop the outer loop improves. -* [How to run a software factory in the cloud](/guides/agent-workflows/run-a-software-factory-in-the-cloud) — Move the loop to Oz for team-wide visibility. +* [Set up your software factory: from triage to PR](/guides/agent-workflows/set-up-a-software-factory) — The inner loop the outer loop improves. +* [Run a software factory in the cloud](/guides/agent-workflows/run-a-software-factory-in-the-cloud) — Move the loop to Oz for team-wide visibility. * [Scheduled agents](/agent-platform/cloud-agents/triggers/scheduled-agents) — Full reference for running cloud agents on a cadence. * [`warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss) — The complete reference implementation including all outer-loop skills. * [Skills](/agent-platform/capabilities/skills) — How skill files work in Warp and Oz. diff --git a/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx b/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx index dbc13e55..dae802e2 100644 --- a/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx +++ b/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx @@ -1,7 +1,7 @@ --- -title: How to build a triage agent for your issue backlog +title: Build a triage agent for your issue backlog description: >- - Create a triage agent that reviews new GitHub issues, applies labels, and flags open questions — so your backlog stays actionable without manual effort. + Create a triage agent that reviews new GitHub issues, applies labels, and flags open questions. Your backlog stays actionable without manual effort. sidebar: label: "Build a triage agent" tags: @@ -10,16 +10,14 @@ tags: - "software-factory" --- -# How to build a triage agent for your issue backlog - -Build a triage agent that reviews every new GitHub issue for clarity, applies labels, and flags open questions before any implementation starts. By the end of this guide, you will have a working triage skill deployed as a GitHub Action that runs automatically whenever someone files an issue. +Learn how to build a triage agent that reviews each new GitHub issue for clarity, applies labels, and flags open questions before any implementation starts. After completing the steps in this guide, you will have a working triage skill deployed as a GitHub Action that runs automatically whenever someone opens an issue. ## Prerequisites -* **Warp with Oz** — Oz is Warp's cloud agent platform. [Sign in and set up Oz](/agent-platform/getting-started/agents-in-warp) if you haven't already. -* **GitHub repository** — Your repository needs Issues enabled. The triage agent will read issues and post comments. +* **A Warp account** — Oz is included with Warp. [Sign up at warp.dev](https://www.warp.dev) if you don't have an account. +* **GitHub repository** — Your repository with Issues enabled. The triage agent will read issues and post comments. * **Oz environment** — A cloud environment with your repository checked out. See [Environments](/agent-platform/cloud-agents/environments) to create one. -* **`WARP_API_KEY`** — A Warp API key with permission to start cloud runs. Generate one in the Oz web app under **Settings** > **API Keys**. +* **Warp API key** — Required to start cloud agent runs. See [API keys](/reference/cli/api-keys) to create one and add it to your CI secrets as `WARP_API_KEY`. ## 1. Define your triage criteria @@ -27,32 +25,32 @@ Before writing a skill, decide what your triage agent should do. A good triage a 1. Is the report clear enough to act on? 2. Is it a duplicate of an existing issue? -3. What label should it get? +3. What label should it have? Write down: -* The label taxonomy for your repository (for example: `bug`, `enhancement`, `ready-to-implement`, `needs-info`, `duplicate`) -* Who owns each area of the codebase — this becomes your STAKEHOLDERS file -* What makes an issue "ready to implement": does it need a reproduction step? A version number? A proposed approach? +* The label taxonomy for your repository (for example: `bug`, `enhancement`, `ready-to-implement`, `needs-info`, `duplicate`). +* Who owns each area of the codebase. This becomes your `STAKEHOLDERS` file. +* What makes an issue "ready to implement": does it need a reproduction step, version number, or proposed approach? You will encode these decisions in a skill file in the next step. ## 2. Create the triage skill -A skill is a markdown file that tells the agent what to do, how to classify results, and what to output. Create a `.agents/skills/triage-issue/` directory in your repository with a `SKILL.md` file. - -Use the [`triage-issue` skill from `warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents/skills/triage-issue/SKILL.md) as the starting point — it is the production triage skill Warp uses for its own open source repository. Copy it into your repository and adapt: +A skill is a markdown file that defines the agent's behavior: what to check, how to classify results, and what to output. -* Replace the label taxonomy with your labels -* Update the ownership section to reflect your codebase -* Adjust the definition of "ready to implement" to match your team's bar +1. Create a `.agents/skills/triage-issue/` directory in your repository with a `SKILL.md` file. +2. Copy the [`triage-issue` skill from `warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents/skills/triage-issue/SKILL.md) into your repository. This is the production triage skill Warp uses for its own open source repository. +3. Adapt the skill for your repository: + * Replace the label taxonomy with your labels. + * Update the ownership section to reflect your codebase. + * Adjust the definition of "ready to implement" to match your team's bar. +4. Create `.github/issue-triage/config.json` with your label taxonomy. See the [`config.json` from `warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss/blob/main/.github/issue-triage/config.json) for the format. Write the skill file in terms of principles, not rules. A rule says "if the reporter doesn't include a reproduction step, add `needs-info`." A principle says "confirm that a bug report includes enough context for a fresh contributor to reproduce the issue." Principles transfer to situations the original rules didn't cover; long rule lists overfit and become harder to maintain. -Also create `.github/issue-triage/config.json` with your label taxonomy. See the [`config.json` from `warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss/blob/main/.github/issue-triage/config.json) for the format. - :::tip -The [`bootstrap-issue-config`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents/skills/bootstrap-issue-config/SKILL.md) skill from `oz-for-oss` can generate an initial `config.json` and STAKEHOLDERS file by analyzing your existing labels and CODEOWNERS file. Run it once when setting up a new repository. +The [`bootstrap-issue-config`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents/skills/bootstrap-issue-config/SKILL.md) skill from `oz-for-oss` can generate an initial `config.json` and `STAKEHOLDERS` file by analyzing your existing labels and CODEOWNERS file. Run it once when setting up a new repository. ::: ## 3. Test the triage agent locally @@ -66,13 +64,15 @@ oz agent run \ --share ``` -The `--share` flag generates a session link your team can use to inspect what the agent did. Review the session output — check that the labels and comments match what you would write manually. If something is off, refine the skill file and run again. +The `--share` flag generates a session link your team can use to inspect what the agent did. Review the session output: check that the labels and comments match what you would write manually. If something is wrong, refine the skill file and run again. For the full reference of `oz agent run` flags, see the [Oz CLI reference](/reference/cli/). ## 4. Deploy with GitHub Actions -Once the skill output looks right, deploy it as a GitHub Action that triggers automatically when a new issue is opened. Create `.github/workflows/triage-issue.yml`: +Once the skill output looks correct, deploy it as a GitHub Action that triggers automatically when a new issue is opened. + +1. Create `.github/workflows/triage-issue.yml` with the following content: ```yaml name: Triage new issues @@ -102,22 +102,22 @@ jobs: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} ``` -Replace `YOUR_OZ_ENVIRONMENT_SLUG` with the slug of the Oz environment you created in the prerequisites. +2. Replace `YOUR_OZ_ENVIRONMENT_SLUG` with the slug of the Oz environment you created in the prerequisites. -Add `WARP_API_KEY` to your repository's GitHub Actions secrets under **Settings** > **Secrets and variables** > **Actions**. +3. Add `WARP_API_KEY` to your repository's GitHub Actions secrets under **Settings** > **Secrets and variables** > **Actions**. See [GitHub Actions integration](/agent-platform/cloud-agents/integrations/github-actions) for the full setup guide for `warpdotdev/oz-agent-action`. ## 5. Review and improve -Watch the first few runs in the [Oz web app](https://oz.warp.dev) to verify the agent is labeling and commenting correctly. When you disagree with the agent — when you relabel an issue or edit a comment — note the pattern. Patterns you see repeatedly are signals to update your skill file. +Watch the first few runs in the [Oz web app](https://oz.warp.dev) to verify the agent is labeling and commenting correctly. When you disagree with the agent, e.g. when you relabel an issue or edit a comment, note the pattern. Patterns you see repeatedly are signals to update your skill file. -Add repo-specific context without forking the core skill by creating a `triage-issue-local` companion skill. This file specializes the base skill for your repository — your label taxonomy, your ownership map, your definition of readiness — while keeping the shared skill stable. See the [docs repo example](https://github.com/warpdotdev/docs/blob/main/.agents/skills/triage-issue-local/SKILL.md) for the companion skill pattern. +Add repo-specific context without forking the core skill by creating a `triage-issue-local` companion skill. This file specializes the base skill for your repository (your label taxonomy, ownership map, and definition of readiness) while keeping the shared skill stable. See the [docs repo example](https://github.com/warpdotdev/docs/blob/main/.agents/skills/triage-issue-local/SKILL.md) for the companion skill pattern. ## Next steps * [What is a software factory?](/agent-platform/cloud-agents/software-factory) — How the triage agent fits into the full development loop. -* [How to write product and tech specs with agents](/guides/agent-workflows/write-product-and-tech-specs-with-agents) — Add the spec role once your backlog is well-triaged. -* [How to build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Automate skill improvement based on your corrections. +* [Write product and tech specs with agents](/guides/agent-workflows/write-product-and-tech-specs-with-agents) — Add the spec role once your backlog is well-triaged. +* [Build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Automate skill improvement based on your corrections. * [GitHub Actions integration](/agent-platform/cloud-agents/integrations/github-actions) — Full documentation for `warpdotdev/oz-agent-action`. * [Run agents unattended](/guides/agent-workflows/how-to-run-unattended-agents) — Broader patterns for cloud agents triggered by external events. diff --git a/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx b/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx index 1842bdea..450d6c43 100644 --- a/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx +++ b/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx @@ -1,5 +1,5 @@ --- -title: How to run a software factory in the cloud +title: Run a software factory in the cloud description: >- Move your software factory loop off developer machines and into Oz — with cloud environments, event-driven triggers, least-privilege permissions, and full run auditability. sidebar: @@ -11,15 +11,13 @@ tags: - "orchestration" --- -# How to run a software factory in the cloud - A software factory running on a developer's machine is limited by local compute, requires the machine to be on, and is invisible to the rest of the team. Moving it to Oz gives you parallel cloud runs, event-driven triggers, team-visible sessions with sharing links, and a control plane that runs around the clock. This guide covers the four things you need to move the factory loop into Oz: environments, secrets and permissions, triggers, and observability. ## Prerequisites -* **A working factory loop** — Follow [How to chain a software factory: from triage to PR](/guides/agent-workflows/chain-a-software-factory) to set up the individual agent roles first. +* **A working factory loop** — Follow [Set up your software factory: from triage to PR](/guides/agent-workflows/set-up-a-software-factory) to set up the individual agent roles first. * **An Oz team** — Sign into [oz.warp.dev](https://oz.warp.dev) or access Oz from within Warp. ## Why cloud agents, not cloud computers @@ -105,7 +103,7 @@ See [Multi-agent orchestration](/agent-platform/cloud-agents/orchestration) for ## Next steps * [What is a software factory?](/agent-platform/cloud-agents/software-factory) — The conceptual overview of the full loop. -* [How to build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Add the outer improvement loop on a schedule. +* [Build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Add the outer improvement loop on a schedule. * [Environments](/agent-platform/cloud-agents/environments) — Full reference for cloud agent environments. * [Deployment patterns](/agent-platform/cloud-agents/deployment-patterns) — Choose the right architecture for your team. * [Self-hosting](/agent-platform/cloud-agents/self-hosting) — Run Oz agent workers on your own infrastructure when code must stay on-premises. diff --git a/src/content/docs/guides/agent-workflows/chain-a-software-factory.mdx b/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx similarity index 83% rename from src/content/docs/guides/agent-workflows/chain-a-software-factory.mdx rename to src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx index 98bb01b1..0e6363b9 100644 --- a/src/content/docs/guides/agent-workflows/chain-a-software-factory.mdx +++ b/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx @@ -1,26 +1,22 @@ --- -title: "How to chain a software factory: from triage to PR" +title: "Set up your software factory: from triage to PR" description: >- - Connect specialized agents through the full development loop — triage, spec, implement, and review — so new issues become reviewable PRs with minimal manual execution. + Add the implementation and reviewer agents to complete your software factory, then wire all four agent roles together using GitHub labels as the state machine. sidebar: - label: "Chain a software factory" + label: "Set up your software factory" tags: - "agents" - "software-factory" - "cloud-agents" --- -# How to chain a software factory: from triage to PR - -A software factory chains four specialized agents through the full development loop: a triage agent classifies new issues, a spec agent drafts product and tech specs, an implementation agent builds against those specs, and a reviewer agent validates the result. The output of each agent becomes the input for the next. You review pull requests — not individual steps. - -This guide shows how to connect those agents into a working loop using GitHub labels as the state machine, skills as the agent instructions, and Oz as the orchestration layer. +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. Follow the individual guides first: - * [How to build a triage agent](/guides/agent-workflows/build-a-triage-agent) - * [How to write product and tech specs with agents](/guides/agent-workflows/write-product-and-tech-specs-with-agents) + * [Build a triage agent](/guides/agent-workflows/build-a-triage-agent) + * [Write product and tech specs with agents](/guides/agent-workflows/write-product-and-tech-specs-with-agents) * **Oz environment** — A cloud environment with your repository checked out. See [Environments](/agent-platform/cloud-agents/environments). * **`warpdotdev/oz-agent-action`** installed — See [GitHub Actions integration](/agent-platform/cloud-agents/integrations/github-actions). @@ -41,7 +37,7 @@ A human intervenes at two points: approving the spec before implementation begin 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 [How to build a triage agent](/guides/agent-workflows/build-a-triage-agent) for the full setup. +See [Build a triage agent](/guides/agent-workflows/build-a-triage-agent) for the full setup. ## 2. Trigger the spec agent on label change @@ -173,8 +169,8 @@ The reviewer agent surfaces issues and inconsistencies; the human makes the fina ## Next steps * [What is a software factory?](/agent-platform/cloud-agents/software-factory) — The conceptual overview of the full loop. -* [How to run a software factory in the cloud](/guides/agent-workflows/run-a-software-factory-in-the-cloud) — Move the loop into a managed Oz deployment. -* [How to build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Add the outer improvement loop. +* [Run a software factory in the cloud](/guides/agent-workflows/run-a-software-factory-in-the-cloud) — Move the loop into a managed Oz deployment. +* [Build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Add the outer improvement loop. * [Review AI-generated code](/guides/agent-workflows/how-to-review-ai-generated-code) — The human review workflow for agent-generated PRs. * [`warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss) — The complete reference implementation. * [GitHub Actions integration](/agent-platform/cloud-agents/integrations/github-actions) — Full documentation for triggering Oz agents from CI. diff --git a/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx b/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx index 2546ad52..266a2893 100644 --- a/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx +++ b/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx @@ -1,5 +1,5 @@ --- -title: How to write product and tech specs with agents +title: Write product and tech specs with agents description: >- Use agents to turn a ready-to-implement issue into a product spec and a tech spec — the blueprints that guide implementation and anchor code review. sidebar: @@ -9,8 +9,6 @@ tags: - "software-factory" --- -# How to write product and tech specs with agents - Use agents to turn a triaged GitHub issue into two spec files: a product spec that describes what the feature should do from the user's perspective, and a tech spec that describes how to implement it. Implementation agents use these specs as blueprints; reviewers use them as acceptance criteria. The agent does the drafting — you do the reviewing. :::note @@ -19,8 +17,8 @@ Writing a good spec requires understanding the problem. The agent can draft the ## Prerequisites -* **Warp with Oz** — [Sign in and set up Oz](/agent-platform/getting-started/agents-in-warp) if you haven't already. -* **A triaged issue** — An issue labeled `ready-to-spec` or equivalent. See [How to build a triage agent](/guides/agent-workflows/build-a-triage-agent) to set up triaging. +* **A Warp account** — Oz is included with Warp. [Sign up at warp.dev](https://www.warp.dev) if you don't have an account. +* **A triaged issue** — An issue labeled `ready-to-spec` or equivalent. See [Build a triage agent](/guides/agent-workflows/build-a-triage-agent) to set up triaging. * **`common-skills` installed** — The spec skills live in `warpdotdev/common-skills`. Install them globally: ```bash @@ -34,42 +32,38 @@ Writing a good spec requires understanding the problem. The agent can draft the A product spec defines what the feature should do from the user's perspective: user stories, acceptance criteria, and edge cases. It is the "what," not the "how." -Open the issue you want to spec in Warp and run: - -```bash -/write-product-spec -``` +1. Open the issue you want to spec in Warp and run: -The agent creates a `PRODUCT.md` file in a `specs/[issue-number]/` directory in your repository. The file includes: + ```bash + /write-product-spec + ``` -* A summary of the feature -* User stories in the format "As a [user], I want [behavior] so that [outcome]" -* Acceptance criteria the implementation agent and reviewers can verify -* Edge cases and constraints +2. Review the generated `PRODUCT.md` in `specs/[issue-number]/`. The file includes: + * A summary of the feature + * User stories in the format "As a [user], I want [behavior] so that [outcome]" + * Acceptance criteria the implementation agent and reviewers can verify + * Edge cases and constraints -Review the draft carefully. The agent makes reasonable assumptions, but you know your users. Correct any misunderstandings before moving to the tech spec — a wrong product spec leads to a correct implementation of the wrong thing. + Correct any misunderstandings before moving to the tech spec. A wrong product spec leads to a correct implementation of the wrong thing. ## 2. Write the tech spec A tech spec defines how the feature will be implemented: architecture decisions, relevant code locations, API shapes, and implementation notes. It is the "how." -After reviewing the product spec, run: - -```bash -/write-tech-spec -``` - -The agent reads your codebase (using [Codebase Context](/agent-platform/capabilities/codebase-context)), the product spec you just approved, and creates a `TECH.md` file in the same `specs/[issue-number]/` directory. +1. After reviewing the product spec, run: -The file includes: + ```bash + /write-tech-spec + ``` -* An overview of the implementation approach -* The specific files and functions that need to change -* Any new data structures, API endpoints, or interfaces -* Testing strategy -* Known risks or tradeoffs +2. Review the generated `TECH.md` in the same `specs/[issue-number]/` directory. The file includes: + * An overview of the implementation approach + * The specific files and functions that need to change + * Any new data structures, API endpoints, or interfaces + * Testing strategy + * Known risks or tradeoffs -Review the tech spec with the same care as the product spec. An accurate `TECH.md` reduces the number of implementation iterations and gives reviewers the context to understand why the code looks the way it does. + An accurate `TECH.md` reduces the number of implementation iterations and gives reviewers context for why the code looks the way it does. ## 3. Validate that the implementation matches the specs @@ -94,7 +88,7 @@ The `specs/[issue-number]/` directory should be committed alongside the code cha ## Next steps * [What is a software factory?](/agent-platform/cloud-agents/software-factory) — How specs fit into the full development loop. -* [How to chain a software factory: from triage to PR](/guides/agent-workflows/chain-a-software-factory) — Connect the spec role to implementation and review. +* [Set up your software factory: from triage to PR](/guides/agent-workflows/set-up-a-software-factory) — Connect the spec role to implementation and review. * [`warpdotdev/common-skills`](https://github.com/warpdotdev/common-skills) — The full set of shared skills including `write-product-spec`, `write-tech-spec`, and `validate-changes-match-specs`. * [Planning](/agent-platform/capabilities/planning) — Warp's built-in planning feature for smaller tasks. * [Skills](/agent-platform/capabilities/skills) — How skill files work in Warp and Oz. diff --git a/src/sidebar.ts b/src/sidebar.ts index 2a0a2065..3a2c7827 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -659,7 +659,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ items: [ { slug: 'guides/agent-workflows/build-a-triage-agent', label: 'Build a triage agent' }, { slug: 'guides/agent-workflows/write-product-and-tech-specs-with-agents', label: 'Write specs with agents' }, - { slug: 'guides/agent-workflows/chain-a-software-factory', label: 'Chain a software factory' }, + { slug: 'guides/agent-workflows/set-up-a-software-factory', label: 'Set up your software factory' }, { slug: 'guides/agent-workflows/run-a-software-factory-in-the-cloud', label: 'Run a software factory in the cloud' }, { slug: 'guides/agent-workflows/build-a-self-improving-agent', label: 'Build a self-improving agent' }, ], diff --git a/vercel.json b/vercel.json index 5cb15d36..b5f1ddb2 100644 --- a/vercel.json +++ b/vercel.json @@ -95,6 +95,11 @@ } ], "redirects": [ + { + "source": "/guides/agent-workflows/chain-a-software-factory", + "destination": "/guides/agent-workflows/set-up-a-software-factory", + "statusCode": 308 + }, { "source": "/advanced/command-line-flags", "destination": "/terminal/sessions/launch-configurations/", From fa786480355211f3b2a1cb569d4e243a979ce0f9 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Thu, 18 Jun 2026 15:44:24 -0600 Subject: [PATCH 6/9] Polish software-factory.mdx: tighten phrasing, add numbered steps to How it works MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 'agents do the execution and humans review the results' → 'agents execute and humans review' - Rephrase 'when this model is a good fit' → 'how to decide if this model is right for your team' - Break up wall-of-text paragraph in 'How it works' into 4 numbered steps Co-Authored-By: Oz --- .../agent-platform/cloud-agents/software-factory.mdx | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/software-factory.mdx b/src/content/docs/agent-platform/cloud-agents/software-factory.mdx index c04b293d..b4278a77 100644 --- a/src/content/docs/agent-platform/cloud-agents/software-factory.mdx +++ b/src/content/docs/agent-platform/cloud-agents/software-factory.mdx @@ -6,11 +6,11 @@ sidebar: label: "Software factory" --- -A software factory is a development system where specialized agents take new issues through triage, spec, implementation, and review, producing pull requests for your team to merge. Instead of every developer executing every step — reading each issue, writing specs, implementing changes, reviewing output — agents do the execution and humans review the results. The team's job shifts from doing the work to defining the process and raising the quality bar over time. +A software factory is a development system where specialized agents take new issues through triage, spec, implementation, and review, producing pull requests for your team to merge. Instead of every developer executing every step — reading each issue, writing specs, implementing changes, reviewing output — agents execute and humans review. The team's job shifts from doing the work to defining the process and raising the quality bar over time. Warp uses this model to build Warp itself. The [agent dashboard at build.warp.dev](https://build.warp.dev) shows the work Warp's agents are tackling across the open source repository in real time. -Read on to learn about the two loops that make up a software factory, the agent roles involved, and when this model is a good fit. +Read on to learn about the two loops that make up a software factory, the agent roles involved, and how to decide if this model is right for your team. ## The two loops @@ -37,7 +37,12 @@ The [`warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss) reposito Each agent role is backed by a **skill**, a markdown file checked into a Git repository that defines the agent's behavior: what to check, how to classify results, what to output, and when to escalate. Skills are versioned, reviewed as code changes, and composable across repositories. -When a new issue is filed on GitHub, a webhook or GitHub Action triggers the triage agent. The agent runs in a cloud environment using the triage skill, analyzes the issue, and applies labels and comments. When an issue is labeled `ready-to-spec`, the spec agent runs and creates `PRODUCT.md` and `TECH.md` files in a `specs/` directory in the repository. A human reviews and approves those specs. When the implementation label is applied, the implementation agent runs and opens a PR that includes the spec files alongside the code. +The inner loop runs when a new issue is filed: + +1. A webhook or GitHub Action triggers the triage agent. The agent runs in a cloud environment, analyzes the issue, and applies labels and comments. +2. When the issue is labeled `ready-to-spec`, the spec agent creates `PRODUCT.md` and `TECH.md` in a `specs/` directory in the repository. +3. A human reviews and approves the specs. +4. When the implementation label is applied, the implementation agent opens a PR that includes the spec files alongside the code. Oz orchestrates each agent as a cloud run. Every run has its own environment (repository checkout, secrets, toolchain), its own permissions, and a session link your team can use to inspect what the agent did, steer it mid-run, or hand work back to a local session. From c1fa3dc3144427c10c8ca1fc69d438a608bf6f7c Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Thu, 18 Jun 2026 17:33:53 -0600 Subject: [PATCH 7/9] Address review comments on build-a-triage-agent and software-factory build-a-triage-agent.mdx: - Add 'using Oz' to intro paragraph so Oz is introduced before prereqs - Remove article from bold prereq term: 'A Warp account' -> 'Warp account' - Clarify Oz environment prereq: 'checked out' -> 'with access to your repository' - Change 'Write down:' -> 'Identify:' - Fix 'e.g.' -> 'e.g.,' (add missing comma) - Change 'what to check' -> 'what to analyze' in skill definition - Change 'before any implementation starts' -> 'before implementation begins' - Fix trailing whitespace on restructured principles paragraph software-factory.mdx: - 'before implementation starts' -> 'before implementation begins' (consistency) - 'agents do the execution and humans review the results' -> 'agents execute and humans review' - Rephrase 'when this model is a good fit' ending - Break inner-loop wall-of-text into numbered steps - Add framing line before outer loop paragraph Co-Authored-By: Oz --- .../cloud-agents/software-factory.mdx | 6 +++-- .../agent-workflows/build-a-triage-agent.mdx | 22 +++++++++++-------- 2 files changed, 17 insertions(+), 11 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/software-factory.mdx b/src/content/docs/agent-platform/cloud-agents/software-factory.mdx index b4278a77..64198e96 100644 --- a/src/content/docs/agent-platform/cloud-agents/software-factory.mdx +++ b/src/content/docs/agent-platform/cloud-agents/software-factory.mdx @@ -26,7 +26,7 @@ The inner loop ships software. The outer loop improves the factory that ships it A software factory delegates work to specialized agents, each with a narrow responsibility: -* **Triage agent** - Reviews new issues for clarity and completeness. Labels issues as ready to implement, needs more information, or a duplicate. Flags open questions for the reporter before implementation starts, so the backlog stays clean and actionable. +* **Triage agent** - Reviews new issues for clarity and completeness. Labels issues as ready to implement, needs more information, or a duplicate. Flags open questions for the reporter before implementation begins, so the backlog stays clean and actionable. * **Spec agent** - Drafts a product spec (user stories and acceptance criteria) and a tech spec (implementation strategy, relevant code locations, and edge cases). The specs serve as the blueprint for the implementation agent and the review criteria for the reviewer agent. * **Implementation agent** - Builds against approved specs. Uses spec context to make better architectural decisions and raises a blocked status when specs are missing or ambiguous rather than guessing. * **Reviewer agent** - Checks the implementation against specs, code conventions, and security requirements. Posts inline review comments and validates that acceptance criteria are met before a human reviewer opens the PR. @@ -46,7 +46,9 @@ The inner loop runs when a new issue is filed: Oz orchestrates each agent as a cloud run. Every run has its own environment (repository checkout, secrets, toolchain), its own permissions, and a session link your team can use to inspect what the agent did, steer it mid-run, or hand work back to a local session. -The outer improvement loop runs as a scheduled cloud agent. It collects signals from past inner-loop runs and generates a diff to the relevant skill files. That diff goes through a normal pull request review before merging. Humans decide what improves; agents propose it. +The outer loop runs on a schedule, not in response to events. + +A scheduled cloud agent collects signals from past inner-loop runs and generates a diff to the relevant skill files. That diff goes through a normal pull request review before merging. Humans decide what improves; agents propose it. ## When to use a software factory diff --git a/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx b/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx index dae802e2..8667f621 100644 --- a/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx +++ b/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx @@ -10,13 +10,13 @@ tags: - "software-factory" --- -Learn how to build a triage agent that reviews each new GitHub issue for clarity, applies labels, and flags open questions before any implementation starts. After completing the steps in this guide, you will have a working triage skill deployed as a GitHub Action that runs automatically whenever someone opens an issue. +Learn how to build a triage agent using Oz that reviews each new GitHub issue for clarity, applies labels, and flags open questions before implementation begins. After completing the steps in this guide, you will have a working triage skill deployed as a GitHub Action that runs automatically whenever someone opens an issue. ## Prerequisites -* **A Warp account** — Oz is included with Warp. [Sign up at warp.dev](https://www.warp.dev) if you don't have an account. +* **Warp account** — Oz is included with Warp. [Sign up at warp.dev](https://www.warp.dev) if you don't have an account. * **GitHub repository** — Your repository with Issues enabled. The triage agent will read issues and post comments. -* **Oz environment** — A cloud environment with your repository checked out. See [Environments](/agent-platform/cloud-agents/environments) to create one. +* **Oz environment** — A cloud environment with access to your repository. See [Environments](/agent-platform/cloud-agents/environments) to create one. * **Warp API key** — Required to start cloud agent runs. See [API keys](/reference/cli/api-keys) to create one and add it to your CI secrets as `WARP_API_KEY`. ## 1. Define your triage criteria @@ -27,9 +27,9 @@ Before writing a skill, decide what your triage agent should do. A good triage a 2. Is it a duplicate of an existing issue? 3. What label should it have? -Write down: +Identify: -* The label taxonomy for your repository (for example: `bug`, `enhancement`, `ready-to-implement`, `needs-info`, `duplicate`). +* The label taxonomy for your repository (e.g., `bug`, `enhancement`, `ready-to-implement`, `needs-info`, `duplicate`). * Who owns each area of the codebase. This becomes your `STAKEHOLDERS` file. * What makes an issue "ready to implement": does it need a reproduction step, version number, or proposed approach? @@ -37,17 +37,21 @@ You will encode these decisions in a skill file in the next step. ## 2. Create the triage skill -A skill is a markdown file that defines the agent's behavior: what to check, how to classify results, and what to output. +A skill is a markdown file that defines the agent's behavior. It tells the agent what to analyze, how to classify results, and what to output. 1. Create a `.agents/skills/triage-issue/` directory in your repository with a `SKILL.md` file. 2. Copy the [`triage-issue` skill from `warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents/skills/triage-issue/SKILL.md) into your repository. This is the production triage skill Warp uses for its own open source repository. 3. Adapt the skill for your repository: * Replace the label taxonomy with your labels. * Update the ownership section to reflect your codebase. - * Adjust the definition of "ready to implement" to match your team's bar. + * Adjust the definition of "ready to implement" to match your team's requirements. 4. Create `.github/issue-triage/config.json` with your label taxonomy. See the [`config.json` from `warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss/blob/main/.github/issue-triage/config.json) for the format. -Write the skill file in terms of principles, not rules. A rule says "if the reporter doesn't include a reproduction step, add `needs-info`." A principle says "confirm that a bug report includes enough context for a fresh contributor to reproduce the issue." Principles transfer to situations the original rules didn't cover; long rule lists overfit and become harder to maintain. +Write the skill file in terms of principles, not rules. +* A rule says "if the reporter doesn't include a reproduction step, add `needs-info`." +* A principle says "confirm that a bug report includes enough context for a fresh contributor to reproduce the issue." + +Principles transfer to situations the original rules didn't cover; long rule lists overfit and become harder to maintain. :::tip The [`bootstrap-issue-config`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents/skills/bootstrap-issue-config/SKILL.md) skill from `oz-for-oss` can generate an initial `config.json` and `STAKEHOLDERS` file by analyzing your existing labels and CODEOWNERS file. Run it once when setting up a new repository. @@ -110,7 +114,7 @@ See [GitHub Actions integration](/agent-platform/cloud-agents/integrations/githu ## 5. Review and improve -Watch the first few runs in the [Oz web app](https://oz.warp.dev) to verify the agent is labeling and commenting correctly. When you disagree with the agent, e.g. when you relabel an issue or edit a comment, note the pattern. Patterns you see repeatedly are signals to update your skill file. +Watch the first few runs in the [Oz web app](https://oz.warp.dev) to verify the agent is labeling and commenting correctly. When you disagree with the agent, e.g., when you relabel an issue or edit a comment, note the pattern. Patterns you see repeatedly are signals to update your skill file. Add repo-specific context without forking the core skill by creating a `triage-issue-local` companion skill. This file specializes the base skill for your repository (your label taxonomy, ownership map, and definition of readiness) while keeping the shared skill stable. See the [docs repo example](https://github.com/warpdotdev/docs/blob/main/.agents/skills/triage-issue-local/SKILL.md) for the companion skill pattern. From 19be5454bf85d2928483d9d42565c1ca798c86df Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Thu, 18 Jun 2026 17:53:20 -0600 Subject: [PATCH 8/9] Reformat prerequisites sections to match screenshot style across all 5 guides MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace bold-term + em-dash prereqs with plain prose format: '* **Term** — Description. See [link].' → '* A thing (brief context and [link])' Files updated: - build-a-triage-agent.mdx - write-product-and-tech-specs-with-agents.mdx - set-up-a-software-factory.mdx - run-a-software-factory-in-the-cloud.mdx - build-a-self-improving-agent.mdx Co-Authored-By: Oz --- .../agent-workflows/build-a-self-improving-agent.mdx | 6 +++--- .../docs/guides/agent-workflows/build-a-triage-agent.mdx | 8 ++++---- .../run-a-software-factory-in-the-cloud.mdx | 4 ++-- .../guides/agent-workflows/set-up-a-software-factory.mdx | 8 +++----- .../write-product-and-tech-specs-with-agents.mdx | 8 +++----- 5 files changed, 15 insertions(+), 19 deletions(-) diff --git a/src/content/docs/guides/agent-workflows/build-a-self-improving-agent.mdx b/src/content/docs/guides/agent-workflows/build-a-self-improving-agent.mdx index 91b25415..13e8921c 100644 --- a/src/content/docs/guides/agent-workflows/build-a-self-improving-agent.mdx +++ b/src/content/docs/guides/agent-workflows/build-a-self-improving-agent.mdx @@ -21,9 +21,9 @@ The outer loop proposes improvements; it doesn't apply them silently. Every chan ## Prerequisites -* **A working inner loop** — Follow [Set up your software factory: from triage to PR](/guides/agent-workflows/set-up-a-software-factory) to set up the inner loop first. The outer loop improves agents that are already running. -* **A Warp account** — Oz is included with Warp. [Sign up at warp.dev](https://www.warp.dev) if you don't have an account. -* **Oz environment** — A cloud environment with your repository checked out. See [Environments](/agent-platform/cloud-agents/environments). +* A working inner loop with at least one agent running ([set up your software factory](/guides/agent-workflows/set-up-a-software-factory)) +* A Warp account ([sign up at warp.dev](https://www.warp.dev)) +* An Oz cloud environment with access to your repository ([create one](/agent-platform/cloud-agents/environments)) ## Why principles beat rules diff --git a/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx b/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx index 8667f621..d0cd97ec 100644 --- a/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx +++ b/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx @@ -14,10 +14,10 @@ Learn how to build a triage agent using Oz that reviews each new GitHub issue fo ## Prerequisites -* **Warp account** — Oz is included with Warp. [Sign up at warp.dev](https://www.warp.dev) if you don't have an account. -* **GitHub repository** — Your repository with Issues enabled. The triage agent will read issues and post comments. -* **Oz environment** — A cloud environment with access to your repository. See [Environments](/agent-platform/cloud-agents/environments) to create one. -* **Warp API key** — Required to start cloud agent runs. See [API keys](/reference/cli/api-keys) to create one and add it to your CI secrets as `WARP_API_KEY`. +* A Warp account ([sign up at warp.dev](https://www.warp.dev)) +* A GitHub repository with Issues enabled +* An Oz cloud environment with access to your repository ([create one](/agent-platform/cloud-agents/environments)) +* A Warp API key added to your CI secrets as `WARP_API_KEY` ([create one](/reference/cli/api-keys)) ## 1. Define your triage criteria diff --git a/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx b/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx index 450d6c43..d1958717 100644 --- a/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx +++ b/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx @@ -17,8 +17,8 @@ This guide covers the four things you need to move the factory loop into Oz: env ## Prerequisites -* **A working factory loop** — Follow [Set up your software factory: from triage to PR](/guides/agent-workflows/set-up-a-software-factory) to set up the individual agent roles first. -* **An Oz team** — Sign into [oz.warp.dev](https://oz.warp.dev) or access Oz from within Warp. +* A working software factory loop ([set one up](/guides/agent-workflows/set-up-a-software-factory)) +* A Warp account ([sign in at oz.warp.dev](https://oz.warp.dev) or access Oz from within Warp) ## Why cloud agents, not cloud computers diff --git a/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx b/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx index 0e6363b9..e1319f96 100644 --- a/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx +++ b/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx @@ -14,11 +14,9 @@ By the time you reach this guide, you have a triage agent that labels new issues ## Prerequisites -* Each agent role working individually. Follow the individual guides first: - * [Build a triage agent](/guides/agent-workflows/build-a-triage-agent) - * [Write product and tech specs with agents](/guides/agent-workflows/write-product-and-tech-specs-with-agents) -* **Oz environment** — A cloud environment with your repository checked out. See [Environments](/agent-platform/cloud-agents/environments). -* **`warpdotdev/oz-agent-action`** installed — See [GitHub Actions integration](/agent-platform/cloud-agents/integrations/github-actions). +* Each agent role working individually ([triage agent](/guides/agent-workflows/build-a-triage-agent) and [spec agent](/guides/agent-workflows/write-product-and-tech-specs-with-agents) guides) +* An Oz cloud environment with access to your repository ([create one](/agent-platform/cloud-agents/environments)) +* `warpdotdev/oz-agent-action` installed ([see GitHub Actions integration](/agent-platform/cloud-agents/integrations/github-actions)) ## How the loop works diff --git a/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx b/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx index 266a2893..04f591bb 100644 --- a/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx +++ b/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx @@ -17,17 +17,15 @@ Writing a good spec requires understanding the problem. The agent can draft the ## Prerequisites -* **A Warp account** — Oz is included with Warp. [Sign up at warp.dev](https://www.warp.dev) if you don't have an account. -* **A triaged issue** — An issue labeled `ready-to-spec` or equivalent. See [Build a triage agent](/guides/agent-workflows/build-a-triage-agent) to set up triaging. -* **`common-skills` installed** — The spec skills live in `warpdotdev/common-skills`. Install them globally: +* A Warp account ([sign up at warp.dev](https://www.warp.dev)) +* A triaged issue labeled `ready-to-spec` or equivalent ([set up triaging](/guides/agent-workflows/build-a-triage-agent)) +* `common-skills` installed globally from [`warpdotdev/common-skills`](https://github.com/warpdotdev/common-skills): ```bash npx skills@latest add warpdotdev/common-skills --skill write-product-spec --agent warp --global npx skills@latest add warpdotdev/common-skills --skill write-tech-spec --agent warp --global ``` - See [`warpdotdev/common-skills`](https://github.com/warpdotdev/common-skills) for all available skills and installation options. - ## 1. Write the product spec A product spec defines what the feature should do from the user's perspective: user stories, acceptance criteria, and edge cases. It is the "what," not the "how." From d294e681730f7c25861211722844ffb018bf2de6 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Thu, 18 Jun 2026 18:27:21 -0600 Subject: [PATCH 9/9] Remove unnecessary redirect: chain-a-software-factory was never published The guide was new to this PR, so no existing URLs need redirecting. Co-Authored-By: Oz --- vercel.json | 5 ----- 1 file changed, 5 deletions(-) diff --git a/vercel.json b/vercel.json index b5f1ddb2..5cb15d36 100644 --- a/vercel.json +++ b/vercel.json @@ -95,11 +95,6 @@ } ], "redirects": [ - { - "source": "/guides/agent-workflows/chain-a-software-factory", - "destination": "/guides/agent-workflows/set-up-a-software-factory", - "statusCode": 308 - }, { "source": "/advanced/command-line-flags", "destination": "/terminal/sessions/launch-configurations/",