tools-only Orchestration Workflow
Parallel stream execution using Claude Code's native Task tool. The /orchestrate command is a thin scaffolding layer -- it creates worktrees and validates streams, but does not launch agents.
How It Works
/orchestrate generate --> PRD + stream tasks created via @agent-ta
/orchestrate start --> Worktrees created, conflict check, launch instructions printed
Main session --> Launches Task agents (run_in_background: true) per stream
/orchestrate status --> Compact progress table
/orchestrate merge --> Merge completed worktrees back to main
Agents run in parallel inside isolated git worktrees. The tc CLI tracks progress. No external Python scripts or HTTP APIs required.
Subcommands
generate
Creates PRD and tasks with stream metadata. Default if no subcommand given.
| Step | Action |
|---|---|
| 1 | initiative_get({ mode: "lean" }) -- stop if no active initiative |
| 2 | initiative_link() to scope initiative and archive old streams |
| 3 | Invoke @agent-ta to design architecture and return structured JSON |
| 4 | Validate: no cycles, at least one foundation stream (dependencies: []) |
| 5 | tc prd create --title "..." --json then tc task create --title "..." --prd <id> --json for each task |
| 6 | Display plan summary, ask user to approve |
Required task metadata:
{
"streamId": "Stream-A",
"streamName": "Foundation",
"files": ["src/auth.ts"],
"streamDependencies": [],
"streamPaths": ["src/auth/**"],
"streamTokenBudget": 2500
}
| Field | Required | Description |
|---|---|---|
streamId |
Yes | Unique identifier (e.g., "Stream-A") |
streamName |
No | Human-readable label (defaults to streamId) |
files |
Yes | Files this stream touches (for conflict detection) |
streamDependencies |
Yes | Array of streamIds that must complete first ([] for foundation) |
streamPaths |
No | Optional path patterns (globs or directory prefixes) owned by the stream |
streamTokenBudget |
No | Optional per-stream token budget (estimated tokens) |
start
Sets up git isolation. Does NOT launch agents.
| Step | Action |
|---|---|
| 1 | tc stream list --json -- stop if no streams |
| 2 | Check for file overlaps between streams using git diff -- stop if conflicts |
| 3 | worktree_create({ taskId }) for each stream task |
| 4 | Print launch instructions for the main session |
After this command completes, the main session launches Task agents with run_in_background: true for each stream. Each agent receives its stream context, worktree path, and task list.
status
Shows compact progress.
Stream | Status | Progress
-----------|-------------|----------
Stream-A | completed | 100%
Stream-B | in_progress | 60%
Stream-C | pending | 0%
Uses tc progress --json and tc stream list --json.
merge
Merges completed stream worktrees back to main.
| Outcome | Action |
|---|---|
| Clean merge | worktree_merge(), then worktree_cleanup() |
| Conflicts | Report files, suggest worktree_conflict_resolve() |
| Not complete | Skip stream, note in output |
Stream Dependency Model
Execution order is determined entirely by the dependency graph in task metadata. No hardcoded phases.
| Pattern | Metadata | Behavior |
|---|---|---|
| Foundation | "dependencies": [] |
Starts immediately |
| Single dependency | "dependencies": ["Stream-A"] |
Waits for Stream-A to reach 100% |
| Multiple dependencies | "dependencies": ["Stream-A", "Stream-B"] |
Waits for both (AND logic) |
Typical structure:
Depth 0 (Foundation): Stream-A [no dependencies]
Depth 1 (Parallel): Stream-B [depends on A]
Stream-C [depends on A]
Depth 2 (Integration): Stream-Z [depends on B, C]
Stream Conflict Detection
Before creating worktrees, the orchestration compares the files arrays across streams (using git diff). If two streams declare overlapping files, orchestration stops.
Resolution: restructure streams so each file belongs to exactly one stream, or merge overlapping streams.
Worktree Isolation
Each stream gets a dedicated git worktree for complete filesystem isolation.
| Aspect | Detail |
|---|---|
| Location | .worktrees/{TASK-xxx} per task |
| Branch naming | task/{task-id-lowercase} |
| Creation | worktree_create({ taskId }) during start |
| Merge | worktree_merge({ taskId }) during merge |
| Cleanup | worktree_cleanup({ taskId }) after successful merge |
| Conflict resolution | worktree_conflict_status() then worktree_conflict_resolve() |
For full worktree details, see 05-worktree-isolation.md.
Initiative Scoping
Streams are scoped to the active initiative.
| Action | Effect |
|---|---|
initiative_link() with new initiative |
Archives streams from previous initiative |
tc stream list --json |
Returns only current initiative streams |
| Switching back | Re-link old initiative via Memory Copilot |
Monitoring
From Claude Code
Run /orchestrate status for a quick snapshot.
Live Dashboard (Legacy)
The ./watch-status script (from templates/orchestration/) provides a live terminal dashboard if the legacy infrastructure is installed:
Stream-A [===============] 100% DONE 2h31m Foundation
Stream-B [==========-----] 70% RUN 1h45m API Layer
Stream-C [========-------] 40% RUN 52m UI Components
Stream-Z [---------------] 0% --- --- Integration
Best Practices
| Practice | Rationale |
|---|---|
| Keep parallel streams at 3-5 | More streams increase merge complexity and resource usage |
| Ensure files do not overlap | Prevents merge conflicts; enforced by file overlap checks during start |
| Complete foundation before parallel | Downstream streams depend on shared infrastructure |
Verify after generate |
Call tc stream list --json to confirm tasks were created (not just markdown) |
Run merge promptly |
Long-lived worktrees diverge from main, increasing conflict risk |
Troubleshooting
| Symptom | Cause | Solution |
|---|---|---|
"No streams found" on start |
generate not run, or @agent-ta output markdown instead of calling tools |
Run /orchestrate generate; verify with tc stream list --json |
| File overlap detected | Two streams declare the same file in files metadata |
Restructure streams or merge overlapping ones |
| Circular dependency detected | Streams depend on each other in a cycle | Break cycle by making one stream foundation (dependencies: []) |
| Worktree already exists | Previous run not cleaned up | worktree_cleanup({ taskId, force: true }) or git worktree remove --force |
Merge conflicts on merge |
Parallel changes touched same lines | Use worktree_conflict_status() to inspect, resolve manually, then worktree_conflict_resolve() |
| Streams missing after initiative switch | initiative_link() auto-archives old streams |
Re-link old initiative via Memory Copilot |
| Database locked | Another process has SQLite open | Close other Claude sessions, wait 30s, retry |
| Task agent not starting | Main session did not launch Task tool | Main session must call Task with run_in_background: true per stream |
Tool Reference
| Tool / Command | Used In | Purpose |
|---|---|---|
initiative_get |
generate | Check active initiative (Memory Copilot MCP) |
initiative_link |
generate | Scope initiative, archive old streams (Memory Copilot MCP) |
tc prd create |
generate | Create PRD |
tc task create |
generate | Create stream tasks with metadata |
tc stream list |
start, status, merge | List streams with progress |
git diff |
start | Validate no file overlaps between streams |
worktree_create |
start | Create git worktree per stream |
worktree_merge |
merge | Merge branch to main |
worktree_conflict_status |
merge | Inspect merge conflicts |
worktree_conflict_resolve |
merge | Complete conflict resolution |
worktree_cleanup |
merge | Remove worktree and branch |
tc progress |
status | Overall completion percentage |
See Also
- Command source:
.claude/commands/orchestrate.md - Worktree isolation:
docs/50-features/05-worktree-isolation.md - Task Management:
tcCLI tool
Updated: February 2026 -- /orchestrate rewritten as thin scaffolding layer; Claude Code's native Task tool handles parallel agent execution