{
  "id": "parallel-agents-worktrees",
  "type": "loadout",
  "title": "Parallel agents in git worktrees",
  "summary": "Rules and two skills for running several coding agents at once, one task per git worktree: isolation, ports, dependencies, rebasing and clean-up.",
  "description": "Running three or four agents in parallel is now routine, and the tools have caught up: Claude Code has --worktree and\nworktree-isolated subagents, Codex manages worktrees, and gh can create one per issue. What breaks is the etiquette:\nagents editing the main checkout, two dev servers on one port, a shared database migrated twice, or a worktree deleted\nwith unpushed work. This loadout gives every agent the same rules and a start and land procedure.\n",
  "highlights": [
    "Isolation rules: own directory, own branch, no branch switching",
    "Port and shared-resource conventions so agents do not collide",
    "Start skill: worktree outside the repo, lockfile install, baseline test run",
    "Land skill: rebase, checks, PR, safe clean-up with git branch -d",
    "Notes for claude --worktree, isolation: worktree subagents, Codex managed worktrees and gh issue develop --worktree"
  ],
  "version": "1.0.0",
  "license": "MIT",
  "author": {
    "name": "Agent Loadout",
    "url": "https://loadout.jnw-it.com"
  },
  "credits": [
    {
      "title": "Claude Code docs: worktrees",
      "url": "https://code.claude.com/docs/en/worktrees"
    },
    {
      "title": "GitHub CLI 2.99.0 release notes",
      "url": "https://github.com/cli/cli/releases/tag/v2.99.0"
    },
    {
      "title": "git-worktree documentation",
      "url": "https://git-scm.com/docs/git-worktree"
    }
  ],
  "categories": [
    "workflow",
    "ai-agents"
  ],
  "stacks": [
    "git"
  ],
  "files": [
    {
      "path": "AGENTS.md",
      "role": "instructions",
      "description": "Rules for agents working in parallel worktrees.",
      "skill": null,
      "agent": null,
      "install_to": {
        "claude-code": "AGENTS.md",
        "codex": "AGENTS.md",
        "cursor": "AGENTS.md",
        "gemini-cli": "AGENTS.md",
        "antigravity-cli": "AGENTS.md",
        "copilot": "AGENTS.md"
      },
      "raw_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/1.0.0/AGENTS.md",
      "raw_latest_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/latest/AGENTS.md",
      "bytes": 1709,
      "lang": "markdown",
      "content": "# AGENTS.md: parallel agents in git worktrees\n\nSeveral agents may work on this repository at once, each in its own git worktree on its own branch.\nThese rules keep them from colliding.\n\n## Inside a worktree\n- Work only inside your worktree directory. Never edit, check out or reset files in the main checkout or another worktree.\n- One task per worktree, one branch per task: `agent/<short-task-name>`.\n- Never switch branches inside a worktree; finish or abandon the task instead.\n- Commit small and often. Uncommitted work in a worktree is easy to lose.\n- Each worktree has its own `node_modules`, `.venv` and build output. Install dependencies in the worktree.\n- Dev servers: use the port the human assigned, or `3000 + N` where N is your worktree number. Never kill a process you did not start.\n- Shared resources (one local database, one emulator) are single-writer. Ask before migrating or seeding a shared database.\n- Secrets: do not copy `.env` files between worktrees yourself. Ask the human to provide them.\n\n## Starting and finishing\n- Start with the `start-worktree` skill. Finish with the `land-worktree` skill.\n- Do not delete a worktree or its branch until its pull request is merged, or the human says to drop it.\n\n## Tool-specific notes\n- Claude Code: `claude --worktree <name>` starts a session in a new worktree. A subagent with `isolation: worktree` gets a\n  temporary worktree branched from the default branch, not from your current HEAD; commit and push what it needs first.\n- Codex: the app and CLI can create managed worktrees (Codex 0.162+). Treat them the same way.\n- GitHub CLI: `gh issue develop <number> --worktree` creates a linked branch and a worktree for an issue (gh 2.99+).\n"
    },
    {
      "path": "CLAUDE.md",
      "role": "adapter",
      "description": "Imports AGENTS.md for Claude Code.",
      "skill": null,
      "agent": "claude-code",
      "install_to": {
        "claude-code": "CLAUDE.md",
        "codex": null,
        "cursor": null,
        "gemini-cli": null,
        "antigravity-cli": null,
        "copilot": null
      },
      "raw_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/1.0.0/CLAUDE.md",
      "raw_latest_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/latest/CLAUDE.md",
      "bytes": 409,
      "lang": "markdown",
      "content": "# CLAUDE.md\n\n@AGENTS.md\n\n## Claude Code notes\n- Skills from this loadout live in `.claude/skills/`: `start-worktree`, `land-worktree`. Use them when their description matches the task.\n- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.\n\n<!-- From the Agent Loadout \"Parallel agents in git worktrees\" v1.0.0 — https://loadout.jnw-it.com/loadouts/parallel-agents-worktrees/ -->\n"
    },
    {
      "path": "GEMINI.md",
      "role": "adapter",
      "description": "Imports AGENTS.md for Gemini CLI.",
      "skill": null,
      "agent": "gemini-cli",
      "install_to": {
        "claude-code": null,
        "codex": null,
        "cursor": null,
        "gemini-cli": "GEMINI.md",
        "antigravity-cli": null,
        "copilot": null
      },
      "raw_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/1.0.0/GEMINI.md",
      "raw_latest_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/latest/GEMINI.md",
      "bytes": 410,
      "lang": "markdown",
      "content": "# GEMINI.md\n\n@./AGENTS.md\n\n## Gemini CLI notes\n- Skills from this loadout live in `.agents/skills/`: `start-worktree`, `land-worktree`. Use them when their description matches the task.\n- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.\n\n<!-- From the Agent Loadout \"Parallel agents in git worktrees\" v1.0.0 — https://loadout.jnw-it.com/loadouts/parallel-agents-worktrees/ -->\n"
    },
    {
      "path": "skills/start-worktree/SKILL.md",
      "role": "skill",
      "description": "Create a worktree for one task with deps, port and baseline tests.",
      "skill": "start-worktree",
      "agent": null,
      "install_to": {
        "claude-code": ".claude/skills/start-worktree/SKILL.md",
        "codex": ".agents/skills/start-worktree/SKILL.md",
        "cursor": ".agents/skills/start-worktree/SKILL.md",
        "gemini-cli": ".agents/skills/start-worktree/SKILL.md",
        "antigravity-cli": ".agents/skills/start-worktree/SKILL.md",
        "copilot": ".agents/skills/start-worktree/SKILL.md"
      },
      "raw_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/1.0.0/skills/start-worktree/SKILL.md",
      "raw_latest_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/latest/skills/start-worktree/SKILL.md",
      "bytes": 1233,
      "lang": "markdown",
      "content": "---\nname: start-worktree\ndescription: Create a git worktree and branch for one task, install dependencies and pick a free port. Use before starting a task that will run alongside other agents.\n---\n\n# Start a worktree\n\nInputs: a short task name (kebab-case) and the base branch (default `main`; use the repo's default branch).\n\n1. From the main checkout, update the base: `git fetch origin`.\n2. Create the worktree next to the repository, never inside it:\n   `git worktree add ../$(basename \"$PWD\")-<task> -b agent/<task> origin/<base>`\n   If the branch exists already, stop and ask; another agent may own it.\n3. `cd` into the new directory. Confirm with `git status` and `git branch --show-current`.\n4. Install dependencies with the project's lockfile command (`npm ci`, `pnpm install --frozen-lockfile`, `uv sync`, …).\n5. Environment files: list which ones the project needs (`ls ../<main-checkout>/.env*` names only) and ask the human to copy them.\n6. Pick a port: `git worktree list` gives N; use `3000 + N` unless the human assigned one. Record it in your first report.\n7. Run the test command once, before changing anything, so later failures are known to be yours.\n\nReport: worktree path, branch, port, baseline test result.\n"
    },
    {
      "path": "skills/land-worktree/SKILL.md",
      "role": "skill",
      "description": "Rebase, check, open a PR and clean up after merge.",
      "skill": "land-worktree",
      "agent": null,
      "install_to": {
        "claude-code": ".claude/skills/land-worktree/SKILL.md",
        "codex": ".agents/skills/land-worktree/SKILL.md",
        "cursor": ".agents/skills/land-worktree/SKILL.md",
        "gemini-cli": ".agents/skills/land-worktree/SKILL.md",
        "antigravity-cli": ".agents/skills/land-worktree/SKILL.md",
        "copilot": ".agents/skills/land-worktree/SKILL.md"
      },
      "raw_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/1.0.0/skills/land-worktree/SKILL.md",
      "raw_latest_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/latest/skills/land-worktree/SKILL.md",
      "bytes": 1277,
      "lang": "markdown",
      "content": "---\nname: land-worktree\ndescription: Rebase a finished worktree branch, run checks, open a pull request and clean up after merge. Use when a task in a worktree is done.\n---\n\n# Land a worktree\n\n1. Commit everything. `git status` must be clean.\n2. `git fetch origin && git rebase origin/<base>`. On conflicts in files you did not change, stop and ask; another agent's work may be landing.\n3. Run the full check command (tests, lint, type-check). Fix failures you caused; report others.\n4. Push the branch: `git push -u origin agent/<task>`. Never push to `<base>` directly, never force-push a shared branch.\n   After a rebase of your own unshared branch, `git push --force-with-lease` is the only acceptable force.\n5. Open a pull request (`gh pr create --fill` then edit the body): what changed, how it was tested, anything left.\n6. Stop any dev server you started in this worktree.\n7. After the human merges, clean up from the main checkout:\n   `git worktree remove ../<repo>-<task>` then `git branch -d agent/<task>` and `git worktree prune`.\n   `git branch -d` refuses unmerged branches. After a squash or rebase merge on GitHub it refuses too, because the\n   commits differ: confirm with `gh pr view --json state` that the PR is merged, then ask the human before using `-D`.\n"
    }
  ],
  "requires": {
    "tools": [
      "git"
    ],
    "env": [],
    "mcp": []
  },
  "tested": {
    "status": "untested",
    "last_run": null,
    "fixture": null,
    "per_agent": {
      "claude-code": "untested",
      "codex": "untested",
      "cursor": "untested",
      "gemini-cli": "untested",
      "antigravity-cli": "untested",
      "copilot": "untested"
    }
  },
  "security": {
    "scanned": true,
    "scanner": "intake-precheck/1",
    "verdict": "clean",
    "network": false,
    "scripts": []
  },
  "featured": false,
  "deprecated": false,
  "last_checked": "2026-10-17",
  "published": "2026-10-17",
  "updated": "2026-10-17",
  "compatibility": {
    "claude-code": "native",
    "codex": "native",
    "cursor": "native",
    "gemini-cli": "native",
    "antigravity-cli": "native",
    "copilot": "native"
  },
  "counts": {
    "rules": 1,
    "skills": 2,
    "mcp": 0
  },
  "url": "https://loadout.jnw-it.com/loadouts/parallel-agents-worktrees/",
  "api_url": "https://loadout.jnw-it.com/api/loadouts/parallel-agents-worktrees.json",
  "verification": {
    "level": "verified-install",
    "status": "verified",
    "label": "Verified install",
    "verified": true,
    "checked_at": "2026-10-17T07:47:06Z",
    "commit": "316f4bcae9d3c1f64f8f5e32a12e27e0c36f13b5",
    "content_current": true,
    "agent_tests": "not-run",
    "counts": {
      "pass": 9,
      "fail": 0,
      "skip": 0,
      "not_applicable": 1
    },
    "meaning": "Level 1: automated checks on the files (parse, install paths, MCP config, safety scan, references, size, licence, starter build). No AI agent was run.",
    "checks": [
      {
        "id": "listing",
        "name": "Listing",
        "status": "pass",
        "summary": "Schema valid; 5 files declared, none missing or extra",
        "details": [
          "tested.status: untested (agent tests are separate from Level 1)"
        ]
      },
      {
        "id": "parse",
        "name": "Files parse",
        "status": "pass",
        "summary": "All 5 files parse; front matter valid",
        "details": []
      },
      {
        "id": "adapters",
        "name": "Adapters",
        "status": "pass",
        "summary": "CLAUDE.md and GEMINI.md import AGENTS.md and are up to date",
        "details": [
          "CLAUDE.md: matches the generator",
          "GEMINI.md: matches the generator"
        ]
      },
      {
        "id": "install-paths",
        "name": "Install paths",
        "status": "pass",
        "summary": "Correct paths for all 6 agents; layouts re-discovered",
        "details": [
          "Claude Code: 4 files, 2 skills in .claude/skills/",
          "Codex CLI: 3 files, 2 skills in .agents/skills/",
          "Cursor: 3 files, 2 skills in .agents/skills/",
          "Gemini CLI: 4 files, 2 skills in .agents/skills/",
          "Antigravity CLI: 3 files, 2 skills in .agents/skills/",
          "GitHub Copilot: 3 files, 2 skills in .agents/skills/"
        ]
      },
      {
        "id": "mcp",
        "name": "MCP config",
        "status": "n/a",
        "summary": "No MCP servers in this loadout",
        "details": []
      },
      {
        "id": "safety",
        "name": "Safety scan",
        "status": "pass",
        "summary": "Clean: no credentials, risky shell or hidden text",
        "details": [
          "Scanner intake-precheck/1: verdict clean; network no (listing says no)"
        ]
      },
      {
        "id": "references",
        "name": "References",
        "status": "pass",
        "summary": "2 references between files resolve for every agent",
        "details": []
      },
      {
        "id": "size",
        "name": "Size limits",
        "status": "pass",
        "summary": "5 files, 4.9 KB total; largest AGENTS.md 1.7 KB",
        "details": [
          "Limits: 30 files, 32 KB per file, 128 KB total, 500 lines per skill or rule"
        ]
      },
      {
        "id": "licence",
        "name": "Licence",
        "status": "pass",
        "summary": "MIT, by Agent Loadout; text in the repository LICENSE",
        "details": []
      },
      {
        "id": "starter-build",
        "name": "Starter build",
        "status": "pass",
        "summary": "The worktree commands in the start-worktree and land-worktree skills run cleanly on a scratch repository: create, commit, rebase, refuse an unmerged delete, remove and prune",
        "details": [
          "Applied 7 loadout files at every agent's paths",
          "✓ skills name the exact commands: bash -c s=.agents/skills; grep -q 'git worktree add ../' $s/start-worktree/SKILL.md && grep -q 'git worktree remove' $s/land-worktree/SKILL.md && grep -q 'git branch -d' $s/land-worktree/SKILL.md && grep -q 'force-with-lease' $s/land-worktree/SKILL.md && echo commands present",
          "✓ start, land and clean up a worktree: bash -c set -e; export GIT_AUTHOR_NAME=t GIT_AUTHOR_EMAIL=t@example.com GIT_COMMITTER_NAME=t GIT_COMMITTER_EMAIL=t@example.com; root=$(mktemp -d); git init -q -b main $root/origin.git --bare; git clone -q $root/origin.git $root/app 2>/dev/null; cd $root/app; echo a > a.txt; git add a.txt; git commit -qm init; git push -q origin main; git fetch -q origin; git worktree add -q ../app-task -b agent/task origin/main; cd ../app-task; test \"$(git branch --show-cur",
          "Covers: git worktree add outside the repository on a new agent/<task> branch from origin/main",
          "Covers: Rebasing the worktree branch onto new upstream commits",
          "Covers: git branch -d refuses an unmerged branch, as the land skill relies on",
          "Covers: git worktree remove and prune leave only the main checkout"
        ]
      }
    ]
  },
  "install": {
    "claude-code": {
      "files": [
        {
          "path": "AGENTS.md",
          "target": "AGENTS.md",
          "raw_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/1.0.0/AGENTS.md",
          "role": "instructions"
        },
        {
          "path": "CLAUDE.md",
          "target": "CLAUDE.md",
          "raw_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/1.0.0/CLAUDE.md",
          "role": "adapter"
        },
        {
          "path": "skills/start-worktree/SKILL.md",
          "target": ".claude/skills/start-worktree/SKILL.md",
          "raw_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/1.0.0/skills/start-worktree/SKILL.md",
          "role": "skill"
        },
        {
          "path": "skills/land-worktree/SKILL.md",
          "target": ".claude/skills/land-worktree/SKILL.md",
          "raw_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/1.0.0/skills/land-worktree/SKILL.md",
          "role": "skill"
        }
      ],
      "manual_steps": [],
      "zip_url": "https://loadout.jnw-it.com/download/parallel-agents-worktrees/claude-code.zip"
    },
    "codex": {
      "files": [
        {
          "path": "AGENTS.md",
          "target": "AGENTS.md",
          "raw_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/1.0.0/AGENTS.md",
          "role": "instructions"
        },
        {
          "path": "skills/start-worktree/SKILL.md",
          "target": ".agents/skills/start-worktree/SKILL.md",
          "raw_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/1.0.0/skills/start-worktree/SKILL.md",
          "role": "skill"
        },
        {
          "path": "skills/land-worktree/SKILL.md",
          "target": ".agents/skills/land-worktree/SKILL.md",
          "raw_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/1.0.0/skills/land-worktree/SKILL.md",
          "role": "skill"
        }
      ],
      "manual_steps": [],
      "zip_url": "https://loadout.jnw-it.com/download/parallel-agents-worktrees/codex.zip"
    },
    "cursor": {
      "files": [
        {
          "path": "AGENTS.md",
          "target": "AGENTS.md",
          "raw_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/1.0.0/AGENTS.md",
          "role": "instructions"
        },
        {
          "path": "skills/start-worktree/SKILL.md",
          "target": ".agents/skills/start-worktree/SKILL.md",
          "raw_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/1.0.0/skills/start-worktree/SKILL.md",
          "role": "skill"
        },
        {
          "path": "skills/land-worktree/SKILL.md",
          "target": ".agents/skills/land-worktree/SKILL.md",
          "raw_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/1.0.0/skills/land-worktree/SKILL.md",
          "role": "skill"
        }
      ],
      "manual_steps": [],
      "zip_url": "https://loadout.jnw-it.com/download/parallel-agents-worktrees/cursor.zip"
    },
    "gemini-cli": {
      "files": [
        {
          "path": "AGENTS.md",
          "target": "AGENTS.md",
          "raw_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/1.0.0/AGENTS.md",
          "role": "instructions"
        },
        {
          "path": "GEMINI.md",
          "target": "GEMINI.md",
          "raw_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/1.0.0/GEMINI.md",
          "role": "adapter"
        },
        {
          "path": "skills/start-worktree/SKILL.md",
          "target": ".agents/skills/start-worktree/SKILL.md",
          "raw_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/1.0.0/skills/start-worktree/SKILL.md",
          "role": "skill"
        },
        {
          "path": "skills/land-worktree/SKILL.md",
          "target": ".agents/skills/land-worktree/SKILL.md",
          "raw_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/1.0.0/skills/land-worktree/SKILL.md",
          "role": "skill"
        }
      ],
      "manual_steps": [],
      "zip_url": "https://loadout.jnw-it.com/download/parallel-agents-worktrees/gemini-cli.zip"
    },
    "antigravity-cli": {
      "files": [
        {
          "path": "AGENTS.md",
          "target": "AGENTS.md",
          "raw_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/1.0.0/AGENTS.md",
          "role": "instructions"
        },
        {
          "path": "skills/start-worktree/SKILL.md",
          "target": ".agents/skills/start-worktree/SKILL.md",
          "raw_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/1.0.0/skills/start-worktree/SKILL.md",
          "role": "skill"
        },
        {
          "path": "skills/land-worktree/SKILL.md",
          "target": ".agents/skills/land-worktree/SKILL.md",
          "raw_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/1.0.0/skills/land-worktree/SKILL.md",
          "role": "skill"
        }
      ],
      "manual_steps": [],
      "zip_url": "https://loadout.jnw-it.com/download/parallel-agents-worktrees/antigravity-cli.zip"
    },
    "copilot": {
      "files": [
        {
          "path": "AGENTS.md",
          "target": "AGENTS.md",
          "raw_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/1.0.0/AGENTS.md",
          "role": "instructions"
        },
        {
          "path": "skills/start-worktree/SKILL.md",
          "target": ".agents/skills/start-worktree/SKILL.md",
          "raw_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/1.0.0/skills/start-worktree/SKILL.md",
          "role": "skill"
        },
        {
          "path": "skills/land-worktree/SKILL.md",
          "target": ".agents/skills/land-worktree/SKILL.md",
          "raw_url": "https://loadout.jnw-it.com/raw/parallel-agents-worktrees/1.0.0/skills/land-worktree/SKILL.md",
          "role": "skill"
        }
      ],
      "manual_steps": [],
      "zip_url": "https://loadout.jnw-it.com/download/parallel-agents-worktrees/copilot.zip"
    }
  },
  "source_zip_url": "https://loadout.jnw-it.com/download/parallel-agents-worktrees/source.zip"
}