docs: add software factory concept page and 5 guides

[rachaelrenk]

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/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

Skill update:

• .agents/skills/draft_guide/SKILL.md — New "Oz CLI and GitHub Actions accuracy" section with guardrails for oz-agent-action input format, permissions blocks, Oz CLI verification, oz secret create security, and slash-command code fence convention.

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 (software-factory.mdx) first — all 5 guides link back to it
• Guides form a series that builds sequentially (triage → specs → chain → cloud → self-improve); each can also stand alone

Changes since initial push (addressing oz-for-oss bot review)

• Sidebar indentation — Normalized deployment-patterns, software-factory, and warp-hosting to 6-tab depth matching the rest of the Oz Cloud Agents items array
• oz-agent-action input format — Moved WARP_API_KEY from env: to warp_api_key: under with: in all four GitHub Actions workflow examples (triage, spec, implementation, reviewer)
• permissions: blocks — Added role-specific permissions to every workflow: issues: write for triage; contents: write + pull-requests: write for spec/implementation; pull-requests: write for reviewer
• Reviewer prompt spec path — Fixed reviewer workflow prompt to search for changed specs/*/PRODUCT.md and specs/*/TECH.md files rather than using the PR number (which often differs from the issue number that specs were written under)
• oz environment create syntax — Corrected to owner/repo format; removed unsupported --branch flag
• oz secret create security — Removed --value flag (exposes secrets in shell history); CLI now prompts interactively
• Code fence language identifiers — Added bash to the three slash-command fences (/write-product-spec, /write-tech-spec, /validate-changes-match-specs) per style guide

Key sources

• warpdotdev/oz-for-oss — deployable software factory (reference for all guides)
• warpdotdev/common-skills — spec skills (write-product-spec, write-tech-spec, validate-changes-match-specs)
• ZL X/Twitter: "How to build a self-improvement loop for your Skills" (Jun 2026)
• ZL X/Twitter: "Three skills you need for spec-driven development"
• Rectangle Health Rex case study
• Full source catalog: Investigate software factory content for docs

Validation

• npm run build — 345 pages ✓
• npm run typecheck — 0 errors ✓

---

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

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jun 18, 2026 5:20pm

[oz-for-oss]

@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

[oz-for-oss]

🚨 [CRITICAL] The action docs configure warp_api_key as a with: input, not an environment variable, so this copied workflow may fail authentication. Keep GITHUB_TOKEN in env if needed, but pass the Warp API key through the action input.

Suggested change

	environment: YOUR_OZ_ENVIRONMENT_SLUG
	env:
	WARP_API_KEY: ${{ secrets.WARP_API_KEY }}
	GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
	environment: YOUR_OZ_ENVIRONMENT_SLUG
	warp_api_key: ${{ secrets.WARP_API_KEY }}
	env:
	GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

[oz-for-oss]

⚠️ [IMPORTANT] This workflow says the agent will apply labels and post comments, but it never grants issues: write. Repositories with read-only default workflow permissions will fail; add an explicit permissions block before jobs:.

[oz-for-oss]

⚠️ [IMPORTANT] The workflow blocks on this page omit explicit GitHub token permissions even though the agents need to read issues, push branches, open PRs, and post PR reviews. Add role-specific permissions blocks to each example so copied workflows work under restricted repository defaults.