docs: add software factory concept page and 5 guides by rachaelrenk · Pull Request #236 · warpdotdev/docs

rachaelrenk · 2026-06-17T18:07:56Z

What

Adds a conceptual anchor page and five practical guides covering the software factory model — a system where specialized agents handle the full development loop from issue to PR.

New pages

Concept page (Agents sidebar → Oz Cloud Agents & Orchestration):

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 warpdotdev/oz-for-oss as the canonical reference implementation.

Guides (new "Build a software factory" Guides sidebar section):

guides/agent-workflows/build-a-triage-agent.mdx
guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx
guides/agent-workflows/set-up-a-software-factory.mdx (renamed from chain-a-software-factory.mdx before first publish — no redirect needed)*
guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx
guides/agent-workflows/build-a-self-improving-agent.mdx

Skill and template updates:

.agents/skills/draft_guide/SKILL.md — New "Oz CLI and GitHub Actions accuracy" guardrails section
.agents/templates/guide-page.md and .agents/templates/conceptual.md — title: field added to frontmatter; H1 now rendered automatically from title

Why

Turns ZL's X/Twitter articles and Warp blog posts on software factories into actionable, Warp/Oz-native documentation. A reader — or an AI engine answering "how do I build cloud agents that execute a software factory" — should clearly land on Oz/Warp as the solution.

Review notes

Review the concept page (softwar- Review the concept page (softwar- Review the cto it
Guides form a series (triage → specs → set up the full loop → cl- Guides form a series (triage → specs → set up the full loop → cl- Guides form a series (triage → specs → set ideb- Guides form a series (triage → specs → set up the full loop �-factory, and warp-hosting` to 6-tab depth
oz-agent-action input format — Moved - oz-agent-action input format — Moved - oz-agent-action input format — Moved - permissions: blocks — Added role-specific permissions to every workflow
Reviewer prompt spec path — Fixed to search for changed specs/*/PRODUCT.md and specs/*/TECH.md
oz environment create syntax — Corrected to owner/repo format; removed unsupported --branch flag
oz secret create security — Removed --value flag; CLI now prompts interactively
Code fence language identifiers — Added bash to slash-command fences

Round 2: human review (concept page and H1 cleanup)

Removed H1s from all 6 new pages (rendered from frontmatter title:); updated both agent templates
software-factory.mdx: Rewrote description and opening; cleaned up inner/outer loop prose; removed stale TODO and unsourced claim; changed oz-for-oss 30-minute claim to onboarding guide link
build-a-triage-agent.mdx: Restructured "Create the triage skill" and "Deploy with GitHub Actions" as numbered steps; fixed STAKEHOLDERS backtick code; replaced em dashes in "Review and improve"

Round 3: guide titles and rename

- - - - -t up y- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -t up y- o build a triage agent" → "Build a triage agent")
Reframed opening paragraph of renamed guide to clarify its unique contribution: adds the implementation and reviewer agents and wires all four into the full loop
Updated all cross-references and link text across all 6 files
Fixed "Warp with Oz" prereq → "A Warp acco- Fixed "Warp with Oz" prereq → "A Warp acco- Fixed "Warp with Oz" prereq → "A Warp acco- Fixed "Warp with Oz" prereq → "A Warp acco- Fixed "Warp with Oz" prereq ��x` polish
"agents do the execution and humans review the results" → "agents execute and humans review"
Rephrased "when this model is a good fit" → "how to decide if this model is right for your team"
------------------------------------graph into 4 numbered steps
Added framing line before outer loop paragraph; "before implementation starts" → "before implementation begins"

Round 5: `build-a-triage-agent.mdx` review feedback

Added "using Oz" to intro (first mention of Oz before prerequisites)
Rem- Rem- Rem- Rem- Rem- Rem- Rem- Rem- Rem- Rem- Rem- Rem- Rem- Rem- Rem- Rem- Rem- Rem- Rem- Rem- Rem- Rem- Rem- Rem- Rem- Rem- Rem- Rem- Rem- Rem- Rem- Rempository"
- - - - mi- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - mi- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - mi- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - mi- - - - - - - - - - - - - - - - - - - - - - - -d-term + em-dash prereq format with plain prose + parenthetical links throughout all guides, matching the style in the Azure DevOps integration doc

Key sources

[warpdotdev/oz-for-oss](https://github.- [warpdotdev/oz-for-oss](https://github.- [`warpdotdev/oference for all guides)
warpdotdev/common-skills — spec skills (write-product-spec, write-tech-spec, validate-change- [warpdotdev/common-skills](https://github.com/warpdotdev/common-s f- [warpdotdev/common-skills](https://github.com/warpdotdev/common-skills) — spec skills (write-product-spec, write-tech-spec, validate-change- `warcs

Validation

npm run build — 345 pages ✓

Conversation: https://staging.warp.dev/conversation/1a4548e0-e8be-4016-bbc4-687462faba8b
Plan: https://staging.warp.dev/drive/notebook/LD1WUNi1YdAdPmNuKvU6mX

Co-Authored-By: Oz oz-agent@warp.dev

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 <oz-agent@warp.dev>

vercel · 2026-06-17T18:08:06Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jun 19, 2026 12:29am

oz-for-oss · 2026-06-17T18:08:13Z

@rachaelrenk

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss

Overview

This PR adds a software factory concept page and five related guides for triage, specs, chaining, cloud operation, and self-improvement. The structure and internal links are broadly coherent, and the attached spec context contains no approved spec to validate against.

Concerns

Several copied workflow examples configure warpdotdev/oz-agent-action differently from the existing GitHub Actions docs by putting WARP_API_KEY in env instead of passing warp_api_key as an action input.
The new workflow examples omit explicit GitHub token permissions even though the documented agents need to label issues, post comments, create branches, open PRs, or review PRs.
One reviewer workflow uses the PR number to locate specs even though the implementation workflow writes specs under the issue number.
One cloud setup command documents an unsupported/undocumented environment CLI shape, and one secrets command both uses the wrong secrets syntax and encourages passing a token value on the command line.
A few slash-command code fences are missing language identifiers.

Security

The oz secret create --name GITHUB_TOKEN --value YOUR_TOKEN example would put real token material in shell history and process arguments. The docs should use the interactive or value-file secret flow instead.

Verdict

Found: 3 critical, 3 important, 1 suggestion

Request changes

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

…re-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 <oz-agent@warp.dev>

- 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 <oz-agent@warp.dev>

rachaelrenk · 2026-06-18T18:57:18Z

Open to feedback on the location for this conceptual doc. Currently in Agents > Cloud Agents > Software Factory

- 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 <oz-agent@warp.dev>

rachaelrenk · 2026-06-18T19:59:21Z

 					],
 				},
+				{
+					label: 'Build a software factory',


Added a subsection to the navigation sidebar where all 5 new guides live. It's called "Build a software factory". Open to feedback on this approach.

…titles - 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 <oz-agent@warp.dev>

…How it works - '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 <oz-agent@warp.dev>

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 <oz-agent@warp.dev>

…5 guides 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 <oz-agent@warp.dev>

…shed The guide was new to this PR, so no existing URLs need redirecting. Co-Authored-By: Oz <oz-agent@warp.dev>

petradonka

Good start, left some comments

petradonka · 2026-06-22T09:43:53Z

+  - "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.


Hmh, I'm not sure about the premise of this, because you wouldn't run the whole software factory on a dev's machine anyway...

What would be our options for slightly shifting the premise of this article while retaining the value?

petradonka · 2026-06-22T09:44:44Z

+  - "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.


If this is a part 2 to something, I think we should make it clearer and link to part 1 more prominently

petradonka · 2026-06-22T09:46:21Z

+  - "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.


I think we could expand a bit more on why specs are important, how to use them, how to think about them. It's kinda in there, but a bit terse in a way that someone new to the concept may not grok it

cla-bot Bot added the cla-signed label Jun 17, 2026

oz-for-oss Bot reviewed Jun 17, 2026

View reviewed changes

rachaelrenk self-assigned this Jun 17, 2026

Merge branch 'main' into docs/software-factory

6c767e6

vercel Bot deployed to Preview June 17, 2026 18:20 View deployment

fix: normalize sidebar.ts indentation for deployment-patterns, softwa…

104c0ec

…re-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 <oz-agent@warp.dev>

vercel Bot deployed to Preview June 17, 2026 18:27 View deployment

vercel Bot deployed to Preview June 17, 2026 19:33 View deployment

Merge branch 'main' into docs/software-factory

449f140

vercel Bot deployed to Preview June 18, 2026 17:20 View deployment

rachaelrenk commented Jun 18, 2026

View reviewed changes

vercel Bot deployed to Preview June 18, 2026 19:57 View deployment

rachaelrenk commented Jun 18, 2026

View reviewed changes

vercel Bot deployed to Preview June 18, 2026 21:17 View deployment

vercel Bot deployed to Preview June 18, 2026 21:46 View deployment

vercel Bot deployed to Preview June 18, 2026 23:36 View deployment

Merge branch 'main' into docs/software-factory

0dde269

vercel Bot deployed to Preview June 18, 2026 23:46 View deployment

vercel Bot deployed to Preview June 18, 2026 23:56 View deployment

Remove unnecessary redirect: chain-a-software-factory was never publi…

d294e68

…shed The guide was new to this PR, so no existing URLs need redirecting. Co-Authored-By: Oz <oz-agent@warp.dev>

vercel Bot deployed to Preview June 19, 2026 00:29 View deployment

petradonka reviewed Jun 22, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add software factory concept page and 5 guides#236

docs: add software factory concept page and 5 guides#236
rachaelrenk wants to merge 12 commits into
mainfrom
docs/software-factory

rachaelrenk commented Jun 17, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jun 17, 2026 •

edited

Loading

Uh oh!

oz-for-oss Bot commented Jun 17, 2026 •

edited

Loading

Uh oh!

oz-for-oss Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rachaelrenk Jun 18, 2026 •

edited

Loading

Uh oh!

rachaelrenk Jun 18, 2026

Uh oh!

petradonka left a comment

Uh oh!

petradonka Jun 22, 2026

Uh oh!

petradonka Jun 22, 2026

Uh oh!

petradonka Jun 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

rachaelrenk commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

New pages

Why

Review notes

Round 2: human review (concept page and H1 cleanup)

Round 3: guide titles and rename

Round 5: build-a-triage-agent.mdx review feedback

Key sources

Validation

Uh oh!

vercel Bot commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot left a comment

Choose a reason for hiding this comment

Overview

Concerns

Security

Verdict

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rachaelrenk Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rachaelrenk Jun 18, 2026

Choose a reason for hiding this comment

Uh oh!

petradonka left a comment

Choose a reason for hiding this comment

Uh oh!

petradonka Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

petradonka Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

petradonka Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rachaelrenk commented Jun 17, 2026 •

edited

Loading

Round 5: `build-a-triage-agent.mdx` review feedback

vercel Bot commented Jun 17, 2026 •

edited

Loading

oz-for-oss Bot commented Jun 17, 2026 •

edited

Loading

rachaelrenk Jun 18, 2026 •

edited

Loading