parallel-development-workflow

name	parallel-development-workflow
description	This skill should be used when the user asks about "parallel development", "multiple agents", "worktree + Graphite", "parallel issues", "agent isolation", or needs to coordinate multiple agents or issues in parallel using git worktrees + Graphite stacks (gt). Each agent isolates work in its own worktree + local stack and avoids global restacks. Canonical, reusable parallel development workflow.

For humans: Coordinates multiple agents or parallel issues. Each gets its own worktree and Graphite stack. Relevant for 2+ simultaneous agents. If running one agent at a time, the simpler execute-issue workflow suffices. See the glossary.

Parallel Development Workflow (Worktrees + Graphite)

This skill is the reusable, canonical procedure for parallel development using git worktrees and Graphite stacks.

Agent Identifier (Required)

Every parallel development workflow MUST include an agent identifier. This is mandatory.

Input: <agent-id> — a short identifier for the agent (e.g., A, B, C, agent1)

Branch naming: agent-<agent-id>-<M#>-<issue-id>-<title-slug> (with milestone) or agent-<agent-id>-<issue-id>-<title-slug> (without milestone)

Worktree directory: $WORKTREES_ROOT/wt-agent-<agent-id>-... (mirrors the branch name), where WORKTREES_ROOT="$WORKTREES_ROOT"

<core_invariants>

• Each agent owns exactly one issue + one isolated worktree.
• Agent prefix is required: Every branch/worktree name MUST start with agent-<agent-id>-.
• Graphite-first: prefer gt for branching/stacking/sync/restack; use git freely for inspection/non-mutating commands (e.g. git status, git diff, git log, git show, git grep, git rev-parse, git branch --show-current). Use mutating git primarily for worktree mechanics (add/remove) or explicit admin needs.
• Graphite metadata is shared repo-wide; avoid global operations that restack everyone.
• For generic worktree mechanics + safety (create/switch/stay/cleanup + patch-path guard), follow the shared skill: git-worktrees. </core_invariants>

1. Confirm agent identifier (<agent-id>). This is required for all branch/worktree naming.
2. Inspect current stack state:

   gt ls
   git branch --show-current
   

3. Locate the local issue doc from docs/projects/*/issues/ using the Linear ID; ask only if multiple candidates match.
4. Derive the base branch name with agent prefix:
   • With milestone: agent-<agent-id>-<M#>-<linear-id>-<kebab-case-title> (e.g., agent-A-M8-PROJ-42-story-pipeline)
   • Without milestone: agent-<agent-id>-<linear-id>-<kebab-case-title> (e.g., agent-B-PROJ-42-story-pipeline)
5. Worktree directory: $WORKTREES_ROOT/wt-<branch-name> (includes agent prefix).
6. Choose parent branch:
   • Default: parent from the active stack tip (aligned with the milestone).
   • Use main only if the issue is clearly independent of current stack work.

1. Make sure trunk is current without restacking all stacks:

   gt sync --no-restack
   

2. Create + enter the isolated worktree (use git-worktrees skill, step create-and-enter-new-worktree) with:
   • <agent-id> = agent identifier (required)
   • <branch-name> = issue base branch with agent prefix (e.g., agent-A-M8-PROJ-42-story-pipeline)
   • <worktree-dir> = $WORKTREES_ROOT/wt-<branch-name> (includes agent prefix)
   • <parent-branch> = chosen parent
3. Register the issue base branch with Graphite (select <parent-branch> as the parent when prompted):

   gt track
   gt ls
   

4. Prepare environment immediately after entering the worktree:
   • Install dependencies (use the repo's package manager):

     pnpm install   # or npm install, bun install, yarn install, etc.
     

   • Run baseline verification (build/typecheck/test) to confirm environment is healthy before starting work.

1. Apply the git-worktrees patch-path guard before edits/patches.
2. Ground scope from the local issue doc (dependencies, acceptance, likely touch points).
3. Implement changes on your stack only.
4. Commit/stack with Graphite:
   • First layer on the base branch:

     gt add -A
     gt modify --commit -am "type(scope): <summary>"
     

   • Additional layers:

     gt add -A
     gt create -am "type(scope): <summary>" <child-branch-name>
     

5. If trunk updates while you work:

   gt sync --no-restack
   gt restack --upstack
   

1. Run the workflow’s required checks (use project conventions / issue doc).
2. Submit draft PR(s) for your stack:

   gt ss --draft
   

3. Update the local issue doc checkboxes ([x]) as you complete items.
4. When done, free the branch lock by removing the worktree directory (use git-worktrees skill, step remove-worktree-cleanup).

<hard_safety_constraints> You must not:

• Run gt sync without --no-restack.
• Change parents of branches that did not originate in your worktree/stack.
• Delete worktrees or branches you didn’t create.
• If git status shows unexpected changes: first confirm branch (git branch --show-current). If you are on the intended branch, stop and tell the user (do not stash/restore/reset). If you are not, leave this checkout alone and go to the intended branch/worktree before continuing.
• Use destructive cleanup for unrelated changes unless explicitly instructed (never use cleanup to “make it clean” by default). </hard_safety_constraints>