name: Systematic git worktree isolation for concurrent task agents
description: "implement-feature dispatches multiple agents concurrently into the same working directory. Two agents editing the same file simultaneously produce merge conflicts or silent overwrites. The Agent tool supports isolation: 'worktree' but implement-feature never uses it.\n\nSymphony enforces three workspace invariants per issue: agent runs only inside workspace_path; workspace_path must be inside workspace_root; workspace key characters restricted to [A-Za-z0-9.-].\n\nProposed behaviour:\n- implement-feature: set isolation: 'worktree' on all Agent tool calls for task execution.\n- Worktree naming: derive from task ID using Symphony's sanitization rule (replace non-[A-Za-z0-9.-] with _): e.g., .worktrees/task-1-2/.\n- After agent completes in the worktree, merge changes back to the main branch (or flag conflicts for operator resolution).\n- start-task skill: detect if running inside a worktree and adapt file path references accordingly.\n\nAcceptance criteria:\n- Concurrent task agents each write to a distinct worktree; no shared file edits between agents on separate tasks.\n- Worktree is cleaned up automatically if the agent makes no changes (already the default Agent tool behaviour).\n- Merge-back step produces a clear conflict report if two agents modified the same file."
metadata:
topic: systematic-git-worktree-isolation-for-concurrent-task-agents
source: 'GitHub Issue #453'
added: '2026-03-22'
priority: P2
type: Feature
status: needs-grooming
issue: '#453'
last_synced: '2026-03-22T15:10:09Z'
Story
As a developer using Claude Code skills, I want to systematic git worktree isolation for concurrent task agents so that the tooling becomes more capable and complete.
Description
implement-feature dispatches multiple agents concurrently into the same working directory. Two agents editing the same file simultaneously produce merge conflicts or silent overwrites. The Agent tool supports isolation: "worktree" but implement-feature never uses it.
Symphony enforces three workspace invariants per issue: agent runs only inside workspace_path; workspace_path must be inside workspace_root; workspace key characters restricted to [A-Za-z0-9._-].
Proposed behaviour:
- implement-feature: set
isolation: "worktree"on all Agent tool calls for task execution. - Worktree naming: derive from task ID using Symphony's sanitization rule (replace non-[A-Za-z0-9._-] with
_): e.g.,.worktrees/task-1-2/. - After agent completes in the worktree, merge changes back to the main branch (or flag conflicts for operator resolution).
- start-task skill: detect if running inside a worktree and adapt file path references accordingly.
Acceptance criteria:
- Concurrent task agents each write to a distinct worktree; no shared file edits between agents on separate tasks.
- Worktree is cleaned up automatically if the agent makes no changes (already the default Agent tool behaviour).
- Merge-back step produces a clear conflict report if two agents modified the same file.
Acceptance Criteria
- Work matches description
- Plan or implementation complete
Context
- Source: OpenAI Symphony SPEC.md §9 — per-issue workspace isolation: agent runs only inside workspace_path; workspace_path must have workspace_root as prefix; workspace key restricted to [A-Za-z0-9._-]
- Priority: P2
- Added: 2026-03-06
- Research questions: None