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/.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 new file mode 100644 index 00000000..64198e96 --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/software-factory.mdx @@ -0,0 +1,76 @@ +--- +title: Software factory +description: >- + 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" +--- + +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 how to decide if this model is right for your team. + +## The two loops + +A software factory has two loops that work together. + +**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 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. + +## 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 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. + +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. + +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. + +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 + +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, 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 + +[`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 + +* [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 new file mode 100644 index 00000000..13e8921c --- /dev/null +++ b/src/content/docs/guides/agent-workflows/build-a-self-improving-agent.mdx @@ -0,0 +1,124 @@ +--- +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: + label: "Build a self-improving agent" +tags: + - "agents" + - "software-factory" + - "cloud-agents" + - "schedules" +--- + +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 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 + +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 + +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. + --- + + # 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. + ``` + +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 + +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: + + ```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. + +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. + +## 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. +* [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 new file mode 100644 index 00000000..d0cd97ec --- /dev/null +++ b/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx @@ -0,0 +1,127 @@ +--- +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. Your backlog stays actionable without manual effort. +sidebar: + label: "Build a triage agent" +tags: + - "agents" + - "cloud-agents" + - "software-factory" +--- + +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 ([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 + +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 have? + +Identify: + +* 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? + +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. 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 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. + +:::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 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 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 + +on: + issues: + types: [opened] + +permissions: + issues: write + +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 + warp_api_key: ${{ secrets.WARP_API_KEY }} + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +2. Replace `YOUR_OZ_ENVIRONMENT_SLUG` with the slug of the Oz environment you created in the prerequisites. + +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, 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. + +## Next steps + +* [What is a software factory?](/agent-platform/cloud-agents/software-factory) — How the triage agent fits into the full development loop. +* [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 new file mode 100644 index 00000000..d1958717 --- /dev/null +++ b/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx @@ -0,0 +1,109 @@ +--- +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: + label: "Run a software factory in the cloud" +tags: + - "agents" + - "cloud-agents" + - "software-factory" + - "orchestration" +--- + +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 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 + +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 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. + +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 +``` + +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: + +* **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. +* [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/set-up-a-software-factory.mdx b/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx new file mode 100644 index 00000000..e1319f96 --- /dev/null +++ b/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx @@ -0,0 +1,174 @@ +--- +title: "Set up your software factory: from triage to PR" +description: >- + 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: "Set up your software factory" +tags: + - "agents" + - "software-factory" + - "cloud-agents" +--- + +By the time you reach this guide, you have a triage agent that labels new issues and a spec agent that drafts specs for approved issues. This guide adds the remaining two roles — an implementation agent that builds against approved specs, and a reviewer agent that validates the result — and wires all four together using GitHub labels as the state machine. Issues flow automatically from triage to a reviewable pull request. + +## Prerequisites + +* Each agent role working individually ([triage agent](/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 + +GitHub labels serve as the state machine that connects the agents. Each agent watches for a specific label, does its work, and sets the next label: + +| Label | Agent triggered | What it does | Sets next label | +|-------|-----------------|--------------|-----------------| +| *(new issue filed)* | Triage agent | Reviews the issue, flags questions | `ready-to-spec` or `needs-info` | +| `ready-to-spec` | Spec agent | Writes PRODUCT.md and TECH.md | *(human sets `ready-to-implement` after review)* | +| `ready-to-implement` | Implementation agent | Opens a PR with code and specs | *(PR opening triggers reviewer)* | +| *(PR opened)* | Reviewer agent | Reviews PR against specs and conventions | Posts inline review comments | + +A human intervenes at two points: approving the spec before implementation begins, and merging the PR after review. Everything else runs automatically. + +## 1. Wire up the triage agent + +Your triage agent runs on `issues: [opened]` via GitHub Actions. When it completes, it applies a `ready-to-spec` label if the issue is clear and actionable, or `needs-info` if it needs more detail from the reporter. + +See [Build a triage agent](/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] + +permissions: + contents: write + pull-requests: write + issues: write + +jobs: + write-specs: + if: github.event.label.name == 'ready-to-spec' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: warpdotdev/oz-agent-action@v1 + with: + skill: spec-driven-implementation + prompt: | + Write a product spec and tech spec for GitHub issue #${{ github.event.issue.number }} in ${{ github.repository }}. + Issue title: ${{ github.event.issue.title }} + Issue body: ${{ github.event.issue.body }} + environment: YOUR_OZ_ENVIRONMENT_SLUG + warp_api_key: ${{ secrets.WARP_API_KEY }} + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +The `spec-driven-implementation` skill from [`warpdotdev/common-skills`](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] + +permissions: + contents: write + pull-requests: write + +jobs: + implement: + if: github.event.label.name == 'ready-to-implement' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: warpdotdev/oz-agent-action@v1 + with: + skill: implement-specs + prompt: | + Implement the approved specs for GitHub issue #${{ github.event.issue.number }} in ${{ github.repository }}. + The specs are in specs/${{ github.event.issue.number }}/. + environment: YOUR_OZ_ENVIRONMENT_SLUG + warp_api_key: ${{ secrets.WARP_API_KEY }} + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +The `implement-specs` skill from [`warpdotdev/common-skills`](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] + +permissions: + pull-requests: write + +jobs: + review: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: warpdotdev/oz-agent-action@v1 + with: + skill: review-pr + prompt: | + Review pull request #${{ github.event.pull_request.number }} in ${{ github.repository }}. + If spec files are included in this PR, locate the changed specs/*/PRODUCT.md and specs/*/TECH.md files and validate the implementation against them. + environment: YOUR_OZ_ENVIRONMENT_SLUG + warp_api_key: ${{ secrets.WARP_API_KEY }} + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +The `review-pr` skill from [`warpdotdev/common-skills`](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. +* [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 new file mode 100644 index 00000000..04f591bb --- /dev/null +++ b/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx @@ -0,0 +1,92 @@ +--- +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: + label: "Write specs with agents" +tags: + - "agents" + - "software-factory" +--- + +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 + +* 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 + ``` + +## 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." + +1. Open the issue you want to spec in Warp and run: + + ```bash + /write-product-spec + ``` + +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 + + 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." + +1. After reviewing the product spec, run: + + ```bash + /write-tech-spec + ``` + +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 + + 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 + +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 +``` + +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. +* [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 758c6273..3a2c7827 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -398,6 +398,7 @@ 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' }, { label: 'Self-hosting', @@ -652,6 +653,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/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' }, + ], + }, { label: 'Configuration', collapsed: true,