docs: add software factory concept page and 5 guides#236
Open
rachaelrenk wants to merge 12 commits into
Open
Conversation
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>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
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 Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
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-actiondifferently from the existing GitHub Actions docs by puttingWARP_API_KEYinenvinstead of passingwarp_api_keyas 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_TOKENexample 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
commented
Jun 18, 2026
Contributor
Author
There was a problem hiding this comment.
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
commented
Jun 18, 2026
| ], | ||
| }, | ||
| { | ||
| label: 'Build a software factory', |
Contributor
Author
There was a problem hiding this comment.
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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), andwarpdotdev/oz-for-ossas the canonical reference implementation.Guides (new "Build a software factory" Guides sidebar section):
guides/agent-workflows/build-a-triage-agent.mdxguides/agent-workflows/write-product-and-tech-specs-with-agents.mdxguides/agent-workflows/set-up-a-software-factory.mdx(renamed fromchain-a-software-factory.mdxbefore first publish — no redirect needed)*guides/agent-workflows/run-a-software-factory-in-the-cloud.mdxguides/agent-workflows/build-a-self-improving-agent.mdxSkill and template updates:
.agents/skills/draft_guide/SKILL.md— New "Oz CLI and GitHub Actions accuracy" guardrails section.agents/templates/guide-page.mdand.agents/templates/conceptual.md—title:field added to frontmatter; H1 now rendered automatically from titleWhy
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
softwar- Review the concept page (softwar- Review the cto it, andwarp-hosting` to 6-tab depthoz-agent-actioninput format — Moved -oz-agent-actioninput format — Moved -oz-agent-actioninput format — Moved -permissions:blocks — Added role-specific permissions to every workflowspecs/*/PRODUCT.mdandspecs/*/TECH.mdoz environment createsyntax — Corrected toowner/repoformat; removed unsupported--branchflagoz secret createsecurity — Removed--valueflag; CLI now prompts interactivelybashto slash-command fencesRound 2: human review (concept page and H1 cleanup)
title:); updated both agent templatessoftware-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 linkbuild-a-triage-agent.mdx: Restructured "Create the triage skill" and "Deploy with GitHub Actions" as numbered steps; fixedSTAKEHOLDERSbacktick code; replaced em dashes in "Review and improve"Round 3: guide titles and rename
------------------------------------graph into 4 numbered steps
Round 5:
build-a-triage-agent.mdxreview feedbackKey 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- `warcsValidation
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