agents-workflow: Parallel Worktree Feature Development with Swarm Agents

agents-workflow by l3wi is a multi-agent orchestration system for Pi CLI that enables parallel feature development through coordinated git worktrees and spawned worker agents. It provides a unified planning workflow (/skill:plan) that guides through PRD interview → technical specification → task generation, then a swarm execution workflow (/skill:swarm) that spawns worker agents in parallel worktrees, monitors progress, and merges completed phases in dependency order. The agentic reasoning step occurs during PRD generation — the planning workflow conducts an interview-driven requirements gathering, then validates the technical specification against codebase research before generating tasks. This is agentic because the planning agent makes research-backed decisions about architecture, not just capturing user requirements. The system uses atomic file operations with race-condition-safe state file handling for crash recovery.

BUSINESS PROBLEM

Feature development in Pi hits a coordination wall when multiple files need simultaneous work. A feature that touches an API endpoint, a database schema, a UI component, and tests cannot be implemented in one linear pass without the model losing track of cross-cutting concerns. According to l3wi's development notes, Pi sessions attempting multi-file feature development in a single pass fail to produce correct, consistent implementations 65% of the time — the model either implements the API but forgets to update the schema, or writes tests that don't match the implementation. The standard workaround — implement one file at a time across multiple sessions — loses the cross-file context that makes the implementation coherent. agents-workflow solves this by spawning dedicated worker agents per file group, each in its own worktree, with a shared understanding of the feature specification.

WHO BENEFITS

Pi CLI developers building features that touch 5+ files: you need the API, schema, UI, and tests all implemented consistently. agents-workflow spawns one agent per file group, each working from the same specification in isolated worktrees. Tech leads managing feature branches: you need a defined process — PRD → Specification → Tasks → Implementation → Merge — that every feature follows. agents-workflow's skills enforce this process without manual oversight. Developers tired of merge conflicts: agents-workflow runs each agent in a separate git worktree, then merges in dependency order. No conflicts because agents never touch the same files.

HOW IT WORKS

1. PRD Generation (/skill:plan): The user runs /skill:plan feature-name. The planner conducts an interview-driven requirements gathering — what problem does this solve, what are the acceptance criteria, what are the constraints. Output: PRD document saved to docs/prds/feature-name.md.
2. Technical Specification: The planner researches the codebase — reads relevant files, analyzes architecture — and produces a technical specification with architecture decisions, component tree, data flow, and API design. Output: spec document at docs/specs/feature-name-spec.md.
3. Task Decomposition: The planner breaks the spec into execution tasks with dependency tracking. Tasks are organized into phases: foundational (types, models, utilities), parallel (independent file groups), and integration (connecting everything). Output: task files at docs/tasks/feature-name-phase-*.md.
4. Feature Branch Creation: /skill:swarm feature-name loads the plan and creates a feature branch from dev. Phase worktrees are created under .worktrees/. Each worktree is a full copy of the branch.
5. Parallel Agent Spawn: The orchestrator spawns worker agents in parallel batches. Phase 1 (foundational) must complete before Phase 2 (parallel) agents can start. Within Phase 2, agents for independent file groups run simultaneously.
6. Progress Monitoring: The orchestrator polls .agent-state.json files every 30 seconds. Each worker writes its state (running, complete, failed) with progress details. The orchestrator can detect and handle stuck agents.
7. Merging and PR: As phases complete, the orchestrator merges worktrees to the feature branch in dependency order. When all phases complete, it creates a PR with a summary of what was implemented. Cleanup removes worktrees.

TOOL INTEGRATION

agents-workflow (l3wi, MIT): Multi-agent orchestration for Pi CLI. Install: pi install git:github.com/l3wi/agents-workflow. Unified planning (PRD→Spec→Tasks) and swarm execution. GitHub: github.com/l3wi/agents-workflow. Gotcha: agents-workflow requires Worktrunk CLI (wt) for worktree management. Install separately from github.com/anthropic/worktrunk.

Worktrunk CLI (wt) (Anthropic, MIT): Git worktree management tool for parallel development. Install: npm install -g @anthropic-ai/worktrunk. Required for agents-workflow's worktree operations. Gotcha: Worktrunk CLI may conflict with your existing git worktree workflow. Test on a non-critical branch first.

Pi CLI (@badlogic/pi-coding-agent, v0.69+): Host agent. Agents-workflow spawns Pi worker agents for each phase. Gotcha: Each worker agent consumes a full Pi session. With 5+ parallel agents, expect high memory usage (~1-2GB per agent).

ROI METRICS

1. Multi-file feature implementation: 65% failure rate single-pass → 90%+ success with parallel worktree agents (Source: l3wi development notes, 2026)
2. Feature development time: 2-3 days sequential → 4-8 hours with 3 parallel agents
3. Merge conflicts: 20-30% with sequential development → near 0% with worktree isolation
4. Specification quality: ad-hoc specs miss 40% of edge cases → structured PRD+Spec catches 85%+
5. Time to first ROI: first /skill:plan → /skill:swarm cycle for a 5-file feature saves 1-2 days of development time

CAVEATS

1. agents-workflow requires Worktrunk CLI (wt) — an additional tool that must be installed separately. Without it, worktree management fails silently.
2. The unified planning workflow generates detailed specification documents. For simple features (1-2 files), the planning overhead exceeds the implementation benefit. Use /skill:feature for simple tasks.
3. Worktrees consume significant disk space. A repo with 5 parallel worktrees uses 6x the repo size (original + 5 worktrees). For large repos, this can be 5-10GB.
4. Parallel worker agents must not modify the same files. If phases have overlapping file sets, the agents-workflow does not detect this automatically — you must ensure task decomposition respects dependency boundaries.