Table of Contents

Workspace and Worktree Layout

The dispatcher agent operates inside a dedicated ai-workspace repository. This page documents the directory layout, the role of reference clones, and how per-task isolated worktrees keep concurrent agent runs from interfering with each other.

Directory layout

ai-workspace/
├── CLAUDE.md                          ← Dispatcher agent instructions
├── .claude/
│   ├── settings.local.json            ← Local permission overrides for MCP tools and git
│   ├── skills/
│   │   └── notify-discord/
│   │       └── send.sh                ← Discord notification shell script
│   └── worktrees/                     ← Ephemeral per-task worktrees (auto-cleaned)
│       └── <repo>--<issue-id>/        ← One isolated worktree per task
└── worktrees/                         ← Reference clones (persistent)
    ├── dev-software-plugin/           ← devops-plugin source (agents, skills, settings)
    ├── doc/                           ← Documentation site (docfx)
    ├── officialsite/                  ← Public-facing website
    └── shop/                          ← Online Shop project

Reference clones vs. worktrees

Directory Type Lifecycle Purpose
worktrees/<repo>/ Reference clone Persistent Fetched on each dispatcher run; used only to create worktrees
.claude/worktrees/<repo>--<issue-id>/ Git worktree Ephemeral Isolated working directory for a single agent task

Reference clones are never modified directly. Sub-agents always work in their own isolated worktree.

Worktree lifecycle

sequenceDiagram
    %% Worktree creation and cleanup lifecycle
    participant D as dispatcher
    participant GIT as git worktree
    participant AG as pipeline agent

    D->>GIT: fetch origin (update refs)
    D->>GIT: worktree add .claude/worktrees/<repo>--<issue-id> origin/main --detach
    D->>AG: spawn subagent with worktree path
    AG->>GIT: checkout feature branch, implement, commit, push
    AG-->>D: completed (success or failure)
    D->>GIT: worktree remove .claude/worktrees/<repo>--<issue-id>
  1. The dispatcher fetches the reference clone to update remote refs.
  2. It creates a detached worktree from origin/main.
  3. The pipeline subagent checks out its feature branch inside the worktree, does all its work, and returns.
  4. The dispatcher removes the worktree after the agent completes (whether success or failure).

Concurrency model

The dispatcher enforces a maximum of 5 concurrent subagents. Tasks beyond that are queued and dispatched as slots free up. Because each task has its own worktree, two agents targeting the same repo never write to the same directory simultaneously.

Plugin installation

The devops-plugin is loaded from worktrees/dev-software-plugin/. The workspace .claude/settings.local.json grants the permissions defined in devops-plugin/settings.json. Run the sync-permissions skill after updating the plugin to merge any new permission entries.