Maxxwell by Rindler
Writing

Turning a feature spec into parallel agent tasks

2026-09-18

Past a certain point you stop waiting on the models and start waiting on yourself.

The real problem: one feature, twelve agent tabs

Past a certain point you stop waiting on the models and start waiting on yourself.

You’ve got Claude Code, Codex, Cursor, maybe GitHub Copilot /fleet all running. The feature spec is clear, but now you’re:

This tutorial walks through turning a single feature spec into a task tree that multiple coding agents can execute in parallel without you becoming mission control.

It’s a practical companion to the pillar piece, “AI coding agent orchestration: the complete guide for multi-agent development”. Here we stay concrete and step-by-step.

Example feature we’ll decompose

We’ll use a feature with enough moving parts to be realistic:

Feature: Add OAuth login with GitHub and Google to an existing SaaS app, including:

We’ll build a task tree for AI agents, then show how to run it in parallel.

Step 1: Turn the spec into concrete artifacts

Agents work best when the prompt is “produce these artifacts” not “implement login”. GitHub’s /fleet docs and OpenAI’s Codex guidance both say: map work items directly to files, test suites or docs.

Start with a flat list of outputs:

Write this down in the repo, not just in your head. Anthropic recommends a repo-level file (e.g. AGENTS.md or CLAUDE.md) for durable instructions.

Concrete move: add AGENTS.md at repo root:

# AGENTS task brief: OAuth login feature

Artifacts for this feature:
- Backend: GitHub & Google OAuth modules; user model fields
- Frontend: login/signup flow; account linking UI
- Tests: integration tests for success/failure cases
- Monitoring: basic auth failure metrics/log filters
- Docs: end-user & support doc for OAuth login

This becomes shared context for any agent you spin up.

Step 2: Build a task tree with dependencies

Now turn the artifacts into a task tree - each node is a concrete task that an agent can own. Anthropic’s multi-agent work and GitHub /fleet both emphasize separate, narrow jobs.

For our OAuth feature:

OAuth Login Feature
├─ Backend Foundations
│  ├─ 1.1 Analyze existing auth & user model
│  ├─ 1.2 Design data model changes (oauth_id, provider, email_verified)
│  └─ 1.3 Define OAuth callback & state handling contracts
├─ Provider Integrations
│  ├─ 2.1 Implement GitHub OAuth module
│  └─ 2.2 Implement Google OAuth module
├─ Frontend Flows
│  ├─ 3.1 Update /login and /signup pages
│  └─ 3.2 Account linking UI in settings
├─ Testing & QA
│  ├─ 4.1 Integration tests for success/failure
│  └─ 4.2 Regression tests for existing login
└─ Docs & Ops
   ├─ 5.1 OAuth login user doc
   └─ 5.2 Ops runbook & monitoring checklist

Dependencies:

Explicit dependencies keep agents from drifting. You know what can run in parallel and what must sequence.

Step 3: Mark tasks as parallelizable

Next, decide what can truly run in parallel without causing chaos.

Using the tree above, label tasks:

This is roughly the same pattern GitHub and Cursor push: plan first, then fan out.

Write this into AGENTS.md so every agent sees it:

## Task tree & dependencies

Serial foundation tasks:
- 1.1, 1.2, 1.3

Parallel cluster A (after foundation):
- 2.1, 2.2, 3.1, 3.2

Parallel cluster B (after A is code-complete):
- 4.x, 5.x

Now you have a concrete dependency graph that a coordinator - human or agent - can reason about.

Step 4: Write agent-friendly task briefs

The prompt for each worker should read like an issue, not a brainstorm. OpenAI recommends “write prompts as if you are writing a GitHub Issue.”

For each task, write:

Example: Task 2.1 - GitHub OAuth module

### Task 2.1 - Implement GitHub OAuth backend module

Goal
- Implement GitHub OAuth for login and account linking.

Inputs
- Existing auth code in `backend/auth/`
- User model in `backend/models/user.py`
- Contracts from tasks 1.2-1.3 in `AGENTS.md` (callback URL format, state handling).

Outputs
- New module: `backend/auth/github_oauth.py`
- Wiring into login flow without breaking existing password login.
- Docstring describing public functions and expected behavior.

Constraints
- Use existing HTTP framework and auth/session utilities.
- Don’t store access tokens long-term; keep only what we need for identity.

Do this for each node in the tree. You now have a backlog that maps 1:1 to agent tasks.

Step 5: Choose your orchestration surface

You need a way to:

You can do this a few ways:

The mechanics differ, but the coordination moves are the same: one orchestrator seat, many workers.

With Maxxwell, for example:

Regardless of tool, pick one place where you talk about the task tree and not twelve places.

Step 6: Spin up workers tied to tasks

Now we connect the task tree to actual agent sessions.

6.1 Create branches or worktrees per cluster

Use branches or Git worktrees to keep work separated:

# foundation work
git checkout -b feat/oauth-foundations

# parallel cluster A branches
git worktree add -b github-oauth ../feat-oauth-github
git worktree add -b google-oauth ../feat-oauth-google
git worktree add -b oauth-frontend ../feat-oauth-frontend

Each agent works in its own directory / branch, reducing merge conflicts.

6.2 Start sessions with specific briefs

Whatever agent UI you’re using, start each worker with:

Example (generic agent prompt):

You are working in branch github-oauth.

Task: 2.1 - Implement GitHub OAuth backend module.

Context:
- Read AGENTS.md for the overall OAuth feature plan, task tree, and contracts.
- Inspect backend/auth/ and backend/models/user.py to understand existing auth.

Deliverables:
- Create backend/auth/github_oauth.py with functions for login and account linking.
- Wire into the existing login flow without breaking password auth.
- Add or update tests if they exist; otherwise leave TODOs listed clearly.

Ask me before changing public API signatures.

Repeat for Google OAuth, frontend flows, tests, docs.

In Maxxwell, you’d:

Maxxwell’s orchestrator seat lets you keep these briefs in one place and see which session is “working”, “waiting on you”, “blocked”, or “possibly stalled”.

Step 7: Coordinate dependencies in real time

The main failure mode in multi-agent setups is drift: a downstream agent assumes a contract that the upstream one never implemented.

You avoid this by making a few coordination rules explicit:

  1. Contracts live in one file.
    • Keep callback URLs, state formats, request/response shapes in AGENTS.md or contracts/oauth.md.
  1. Upstream signals "ready" deliberately.
    • Don’t start 3.x and 4.x based on vibes; start them when the foundation tasks are merged into the foundation branch.
  1. Downstream agents read contracts first.
    • Every prompt for 2.x / 3.x / 4.x should explicitly say: “Do not invent new endpoints; use the ones documented in contracts/oauth.md.”

With GitHub /fleet, that’s the handoff description between agents. With Maxxwell or a tmux setup, this is simply you editing the contract file and telling workers to re-read.

Step 8: Monitor sessions and identify stalls

Anthropic notes multi-agent systems are powerful but expensive and failure-prone. The expensive part isn’t just tokens (15× chat in their experiments), it’s your attention.

So you need a cheap way to answer:

With plain terminals, this is manual tab-flipping. With Maxxwell, you get a single window listing sessions and their states:

You still make the decisions - Maxxwell doesn’t auto-restart or auto-correct drift - but the visibility is centralized.

This is where the orchestrator seat pays off: you ask it, in plain language, “Summarize which OAuth tasks are done, which are blocked, and where code is diverging from the contracts.” It reads the lanes and answers.

Step 9: Synchronize outputs before merging

Parallel agents without a clean synthesis step is how you get broken builds. Coordinate merges like you would a small team.

9.1 Gate cluster completion on tests and review

For each cluster:

Example orchestrator prompt:

You are the orchestrator for the OAuth feature.

Summarize the changes from the following branches:
- github-oauth
- google-oauth
- oauth-frontend

For each, list:
- New endpoints and routes
- Changes to the User model
- Any TODOs left in tests or docs

Then tell me where they disagree with contracts/oauth.md.

You merge only after that report looks sane.

9.2 Compact context when agents get lost

Long-running sessions can accumulate a lot of context. With Maxxwell you get a live context-pressure readout and a one-click compact; other tools have similar “summarize and continue” features.

Use compaction:

You don’t need autopilot; you just need enough tools to keep sessions legible.

Step 10: Close the loop and update AGENTS.md

When the feature is done, your task tree should reflect reality:

This matters because you’re likely to reuse this pattern. OpenAI says agentic AI shifts the unit of work from single interactions to long-horizon tasks; this OAuth feature is one such horizon.

Update AGENTS.md:

## OAuth feature status

Done:
- 1.1-1.3 foundations
- 2.1 GitHub, 2.2 Google modules
- 3.1-3.2 frontend flows
- 4.x tests (see tests/auth/test_oauth_flows.py)
- 5.1-5.2 docs & ops

Notes:
- User model gained `oauth_provider` and `oauth_subject_id`.
- Callback paths differ slightly from the initial sketch; see contracts/oauth.md.

Next time you decompose a feature, this file is your starting point.

FAQ: decomposing features for parallel AI coding agents

How granular should I make agent tasks?

Aim for “small ticket” level, not line-item level.

A task that comfortably fits into 30-90 minutes of human work is usually right. OpenAI’s Codex data shows over 80% of sampled users submit at least one request worth 30+ minutes of work, and about 25% submit one worth 8+ hours - you don’t want a single agent owning that entire 8-hour chunk.

How many agents should I run in parallel for one feature?

Most teams do well with 3-6 concurrent sessions per feature.

Anthropic’s multi-agent research system shows parallel breadth-first work is effective but 15× more token-hungry than chat, so you want meaningful parallelism without saturating your own ability to review outputs.

How do I avoid agents building conflicting APIs?

Put API contracts in a single source of truth file and make every prompt reference it explicitly.

Use language like: “You may not introduce new routes or fields; use only what’s defined in contracts/oauth.md. If you need a change, ask me.” Then funnel all changes through one orchestrator session.

Where does Maxxwell fit in this workflow?

Maxxwell sits above your coding agents and manages them; it doesn’t replace them.

You keep using Claude Code, Codex, Cursor or Copilot as workers. Maxxwell gives you one window showing every session’s state and an orchestrator seat that reports what landed, what is waiting for you, and which lanes look stalled. Fleet controls draft changes - they write unsent commands into the composer - so you stay the one who presses enter.

Is this worth it for simple features?

No.

If you’re adding a single endpoint or tweaking one component, a single agent session is usually faster than spinning up a task tree and a fleet. This decomposition pattern is for features that naturally split into backend, frontend, tests, docs, and ops - where you already feel the cost of coordinating work.