Skip to content

Agent Bootstrap

AGENTS_GWZ.md is a short bootstrap hint for agents entering a GWZ-managed repository. It tells an agent to use GWZ for workspace-wide operations, how to install gwz, finish materializing a workspace, inspect status, and find the full docs.

gwz init creates this file in new workspace roots, and gwz init --update refreshes it in an existing workspace root. GWZ also ensures that the root AGENTS.md contains a one-line instruction to read AGENTS_GWZ.md. These files are root-only: GWZ does not write them into member repositories.

Hosted docs URL for bootstrap files: https://owebeeone.github.io/gwz-cli/

Agent Skill

A ready-made skill for agents that drive GWZ lives in the repository at skills/gwz/SKILL.md. It covers selecting targets, staging and committing across the set, member lifecycle, and local lanes, with the verification steps an agent should take before reporting success.

For Claude Code, copy it to ~/.claude/skills/gwz/SKILL.md (or the project's .claude/skills/gwz/). Other agent runtimes can load the same file as a system or tool instruction. To have Claude Code's worktree sessions land in GWZ lanes instead of member-less worktrees, see Claude Code.

Intended File Scope

An AGENTS_GWZ.md file belongs at the workspace root repository. It is not a member-repository policy file and should not try to replace local AGENTS.md instructions.

Keep it deliberately brief:

  • One sentence that the repository is managed by GWZ.
  • The GWZ commands to use for workspace-wide status, staging, and commits.
  • Install commands or links.
  • The command to clone a workspace when it is not cloned yet.
  • The command to materialize members when the root repository already exists.
  • A status check.
  • Links to gwz --help and the hosted docs.

Generated Template

<!-- gwz-managed-file: sha256=<template-body-sha256> -->

# GWZ Workspace

This repository is managed by GWZ, a multi-repository workspace tool.

For workspace-wide status, staging, and commits, use `gwz status`, `gwz add`,
and `gwz commit`. Do not substitute per-repository Git loops.

Install `gwz` from the latest release:

```sh
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/owebeeone/gwz-cli/releases/latest/download/gwz-installer.sh | sh
```

Or install from source:

```sh
cargo install gwz
```

If the workspace is not cloned yet:

```sh
gwz clone <workspace-git-url> [directory]
```

If this root repository is already cloned:

```sh
gwz materialize --lock
gwz status
```

Docs:

- `gwz --help`
- Quick Start: https://owebeeone.github.io/gwz-cli/QuickStart/
- Full documentation: https://owebeeone.github.io/gwz-cli/

Managed-File Updates

GWZ includes a managed-file header with a digest of the Markdown body after the header and separator line:

<!-- gwz-managed-file: sha256=<template-body-sha256> -->

gwz init --update overwrites AGENTS_GWZ.md automatically only when the current body still matches the digest in that header. When the header is missing or the body no longer matches, GWZ refuses to overwrite the file. Use global --force to replace a locally edited bootstrap file:

gwz --force init --update

GWZ preserves existing root AGENTS.md instructions. If the one-line reference to AGENTS_GWZ.md is missing, it appends it instead of replacing the file.

The update command discovers the workspace root from the current directory, or uses global --root <path> when supplied.

What Not To Put Here

Do not include detailed workflow guidance, complete command catalogs, contribution policy, release procedure, or package-specific build instructions. Those belong in README.md, AGENTS.md, package docs, or this docs directory.