agents-workflow: Parallel Worktree Feature Development with Swarm Agents
System Blueprint Overview: The agents-workflow: Parallel Worktree Feature Development with Swarm Agents workflow is an elite agentic system designed to automate developer tools operations. By leveraging autonomous AI agents, it significantly reduces manual overhead, saving approximately 20-30h / week hours per week while ensuring high-fidelity output and operational scalability.
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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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
- Multi-file feature implementation: 65% failure rate single-pass → 90%+ success with parallel worktree agents (Source: l3wi development notes, 2026)
- Feature development time: 2-3 days sequential → 4-8 hours with 3 parallel agents
- Merge conflicts: 20-30% with sequential development → near 0% with worktree isolation
- Specification quality: ad-hoc specs miss 40% of edge cases → structured PRD+Spec catches 85%+
- Time to first ROI: first /skill:plan → /skill:swarm cycle for a 5-file feature saves 1-2 days of development time
CAVEATS
- agents-workflow requires Worktrunk CLI (wt) — an additional tool that must be installed separately. Without it, worktree management fails silently.
- 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.
- 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.
- 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.
Workflow Insights
Deep dive into the implementation and ROI of the agents-workflow: Parallel Worktree Feature Development with Swarm Agents system.
Yes, this workflow is designed with architectural clarity in mind. Most users can implement the core logic within 45-60 minutes using the provided steps and tool recommendations.
Absolutely. The blueprint provided is modular. You can easily swap tools or modify individual steps to fit your unique operational requirements while maintaining the core algorithmic efficiency.
Based on current benchmarks, this specific system can save approximately 20-30h / week hours per week by automating repetitive tasks that previously required manual intervention.
The tools vary. Some are free, while others may require a subscription. We always try to recommend tools with generous free tiers or high ROI to ensure the automation remains cost-effective.
We recommend reviewing each step carefully. If you encounter issues with a specific tool (like Zapier or OpenAI), their respective documentation is the best resource. You can also reach out to the Dailyaiworld collective for architectural guidance.