agents-workflow Guide: Parallel Feature Development in Pi CLI with Worktree Swarms

agents-workflow Guide: Parallel Feature Development in Pi CLI with Worktree Swarms

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. The system provides two integrated skills: /skill:plan (PRD interview → technical specification → task generation) and /skill:swarm (spawn parallel worker agents in worktrees, monitor progress, merge in dependency order). The result is a complete development pipeline from requirements to merged PR — all orchestrated by Pi. (Source: github.com/l3wi/agents-workflow)

The Real Problem

Feature development in Pi hits a coordination wall when multiple files need simultaneous work. A feature touching API, schema, UI, and tests cannot be implemented in one linear pass without the model losing cross-cutting concerns. According to l3wi's development notes, Pi sessions attempting multi-file development in a single pass fail 65% of the time — the model implements the API but forgets the schema, or writes tests that don't match the implementation. Separate sessions lose cross-file context. agents-workflow solves this with parallel agents in worktrees.

[ STAT ] 65% of single-pass multi-file implementations in Pi fail to produce consistent, correct results. — l3wi development notes, June 2026

What This Workflow Actually Does

agents-workflow provides a complete development pipeline: PRD → Specification → Tasks → Parallel Implementation → Merge. Each phase has dedicated agents in isolated worktrees.

[TOOL: /skill:plan] Unified planning workflow. PRD interview → Research-validated spec → Task generation with dependencies.

[TOOL: /skill:swarm] Parallel execution. Spawn worker agents in worktrees, monitor via .agent-state.json, merge in order.

[TOOL: Worktree Isolation] Each agent gets its own git worktree. Parallel file edits without conflicts.

Who This Is Built For

For Pi CLI developers building features touching 5+ files: parallel agents handle API, schema, UI, and tests consistently from one spec.

For tech leads managing feature branches: the defined PRD→Spec→Tasks→Implement→Merge process ensures every feature follows the same quality gates.

For developers tired of merge conflicts: worktree isolation means agents never touch the same files. Zero conflicts.

How It Runs Step by Step

1. PRD Generation: /skill:plan conducts an interview-driven requirements gathering.

2. Tech Spec: The planner researches the codebase and produces architecture decisions with component trees and API designs.

3. Task Decomposition: Tasks organize into phases — foundational (types, models), parallel (independent files), integration.

4. Feature Branch: /skill:swarm creates a feature branch and worktrees.

5. Parallel Spawn: Workers spawn in batches. Phase 1 (foundational) completes before Phase 2 (parallel) agents start.

6. Monitoring: The orchestrator polls .agent-state.json every 30 seconds for progress.

7. Merge: Completed phases merge to the feature branch in dependency order. PR generated with summary.

Setup and Tools

agents-workflow: pi install git:github.com/l3wi/agents-workflow. Requires Worktrunk CLI: npm install -g @anthropic-ai/worktrunk.

Gotcha: agents-workflow spawns full Pi sessions per agent. 5 parallel agents = 2-5GB RAM.

The Numbers

▸ Multi-file success rate: 35% single-pass → 90%+ with worktree agents ▸ Feature development time: 2-3 days → 4-8 hours with 3 parallel agents ▸ Merge conflicts: 20-30% sequential → near 0% worktree isolation ▸ Edge case coverage: ad-hoc 40% → structured spec 85%+ ▸ Time to first ROI: first 5-file feature completes in 4-8 hours (Source: agents-workflow docs, June 2026)

What It Cannot Do

1. Requires Worktrunk CLI — an additional tool installed separately.
2. Simple features (1-2 files) don't benefit from planning overhead.
3. Worktrees use 6x repo disk space (original + 5 worktrees).

Start in 10 Minutes

1. (2 min) Install Worktrunk CLI: npm install -g @anthropic-ai/worktrunk
2. (3 min) Install agents-workflow: pi install git:github.com/l3wi/agents-workflow
3. (5 min) Run /skill:plan for a small feature to experience the pipeline

Frequently Asked Questions

Q: What happens if an agent crashes mid-implementation? A: The orchestrator detects the failure via .agent-state.json. For orchestrated runs, the state is persisted for crash recovery. Resume with /skill:swarm feature-name --resume.

Q: Can agents-workflow handle any size of feature? A: Best for multi-file features (5+ files). For 1-2 file features, use /skill:feature (single-phase implementation) which skips the planning overhead.

Q: Do I need to clean up worktrees manually? A: No. The orchestrator cleans up worktrees after merging. If the orchestrator crashes mid-run, you may need to clean up .worktrees/ manually.