docs: Add Direct monorepo worktree example

[warp-agent-staging]

What this feature does

Direct backend setup and teardown hooks can create a dedicated Git worktree for each task, letting concurrent agents share monorepo Git objects without sharing a checkout. Shipped in worker release v2026-09-18-23-15-02 (2026-09-18).

Summary

Adds a practical Direct backend deployment pattern for running concurrent agents against a large monorepo with isolated branches and working files.

Changes

• Adds direct-monorepo-worktrees.mdx with a shared base clone, complete setup and teardown hooks, worker configuration, validation, and troubleshooting.
• Documents why the worktree must use OZ_WORKSPACE_ROOT/repo instead of the already-created workspace root.
• Clarifies that the Direct backend starts oz in the task workspace and requires task prompts or loaded agent instructions to target repo/.
• Documents target_dir and adds navigation and related-page links.

Content design plan

Target audience and their JTBD: A platform engineer operating a Direct backend worker for a large monorepo who needs concurrent runs without repeated full clones or a shared mutable checkout.

Problem statement: The Direct backend documents lifecycle hooks but does not show how to use them to create and remove task-scoped Git worktrees. Creating a worktree at OZ_WORKSPACE_ROOT fails because the worker has already populated that directory.

Goals:

• The reader can prepare a shared base clone with the right access.
• The reader can install tested setup and teardown hooks.
• The reader can confirm that each task branch and checkout is removed after the run.

Purpose and value added: The page captures a reusable monorepo pattern and the non-obvious nested-worktree constraint without turning the general Direct backend page into a repository-management tutorial.

Content type and model: Feature documentation (combined) because the reader needs the lifecycle model, scripts, configuration, and recovery steps together.

Skills and templates to use: draft_feature_doc and .agents/templates/feature-doc.md, with procedural guidance from draft_procedural.

High-impact scenarios: Covers concurrent tasks using one shared Git object store and a main-branch base. Excludes container isolation, submodule-specific setup, and customer-specific dependency bootstrapping.

Unverified claims

None. Direct workspace creation, CLI working directory, environment-file timing, target_dir, and teardown ordering were verified against oz-agent-worker@530bbe934a632910dfe8818ab7b4c6027a3473ef, including internal/config/config.go, internal/worker/direct.go, and their tests.

Documentation risk

Risk: engineering-review-required
Rationale: Adds executable setup and teardown scripts and documents Direct backend workspace lifecycle behavior.
Source files consulted: oz-agent-worker/internal/config/config.go@530bbe9, oz-agent-worker/internal/worker/direct.go@530bbe9
Docs override: none

Verification

• python3 .agents/skills/style_lint/style_lint.py --changed — exited 0 with one inherited meta-opener warning in managed-direct.mdx.
• npm run build — passed.
• python3 .agents/skills/check_for_broken_links/check_links.py --internal-only — passed with 0 broken links.
• python3 .agents/skills/doc_quality_policy/check_compression_contract.py src/content/docs/platform/self-hosting/direct-monorepo-worktrees.mdx --content-type feature-doc — passed.
• Extracted both documented hook scripts and ran them against a temporary Git remote — setup created the nested worktree, task branch, and environment values; teardown removed the worktree and branch.

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
docs	Ready	Preview	Sep 21, 2026 4:57pm UTC

[warp-agent-staging]

This PR was generated with Warp.

Comment @warp-staging-factory on this PR to send it follow-up work.

  

[warp-for-oss]

@warp-agent-staging[bot]

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 /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[warp-for-oss]

Overview

This PR adds a new Direct backend documentation page for using task-scoped Git worktrees with a shared monorepo base clone, updates the Direct backend and self-hosted worker reference pages, and adds the new page to the sidebar.

Concerns

• No blocking correctness, documentation quality, security, or spec-drift concerns found in the reviewed diff.

Verdict

Found: 0 critical, 0 important, 0 suggestions

Approve

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

Powered by Oz

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/platform/self-hosting/managed-direct.mdx:84 - [NIT] The new sentence 'To reuse a large monorepo without sharing one checkout between concurrent tasks, see Direct backend monorepo worktrees.' runs on immediately after the existing line 83 sentence with no blank line between them, so it renders as the same paragraph instead of its own paragraph like the target_dir sentence two lines below. Requested change: insert a blank line before this sentence so it forms its own paragraph.
• PR body ## Documentation risk section - [SUGGESTION] The section omits the 'Source files consulted' field from the doc-quality-policy.md template, even though the PR cites oz-agent-worker paths (internal/config/config.go, internal/worker/direct.go) under 'Unverified claims' instead. Requested change: add a 'Source files consulted' line to the Documentation risk section listing those paths and the verified commit SHA so engineering reviewers can find them without reading the full PR body.

Verdict

Approve with nits

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• PR description — ## Documentation risk section (right after Docs override: none) — [SUGGESTION] The risk section omits the Source files consulted field even though this PR is engineering-review-required and the source verification is described only in prose under ## Unverified claims ("verified against oz-agent-worker@530bbe934a632910dfe8818ab7b4c6027a3473ef, including internal/config/config.go, internal/worker/direct.go, and their tests"). Requested resolution: add a Source files consulted: line to the ## Documentation risk section per the format in .agents/references/doc-quality-policy.md, e.g. Source files consulted: oz-agent-worker/internal/worker/direct.go@530bbe9, oz-agent-worker/internal/config/config.go@530bbe9.
• src/content/docs/platform/self-hosting/reference.mdx:167 — [SUGGESTION] The new target_dir field is documented under the backend.direct config-file schema, but the equivalent --target-dir CLI flag (confirmed in oz-agent-worker's main.go: TargetDir string help:"Run all tasks in this directory instead of creating per-task workspaces (direct backend only)") is missing from the "Worker flags" > "Optional" list above. Requested resolution: add a --target-dir bullet to the Optional worker flags list so CLI-only users can discover this option.

Verdict

Approve with nits