The agent pipeline

TradeMasterAPI uses a chain of specialized agents to move a product intent from idea → shipped code. Each agent has a single lane; handoffs are explicit.

The chain

user intent
    │
    ▼
┌─────────────────┐
│ product-manager │  breaks intent into atomic GitHub cards with acceptance criteria,
│                 │  links each to an epic, adds `needs-grooming`
└─────────────────┘
    │
    ▼
┌─────────────────┐    ┌──────────────────┐
│  card-groomer   │◀──▶│ product-manager  │  groomer refines; PM clarifies intent
│                 │    │                  │  when a card is ambiguous
└─────────────────┘    └──────────────────┘
    │
    ▼
┌─────────────────────┐
│ software-architect  │  when a card is too big / cross-cutting / security-sensitive:
│                     │  writes docs/architecture/<topic>.md + ADRs, splits into sub-cards
└─────────────────────┘
    │
    ▼
┌──────────────────┐
│ feature-developer│  takes a groomed, sized card. Lands backend + frontend + tests
│                  │  behind a flag. Opens PR. Hands off to ux-polisher.
└──────────────────┘
    │
    ▼
┌──────────────────┐
│   ux-polisher    │  iterates on the same branch: layout, density, tooltips, loading
│                  │  / empty / error states, keyboard paths, a11y. Pushes polish commits.
└──────────────────┘
    │
    ▼
  human review + merge
    │
    ▼
  (later) flag flip PR

Who does what

When each agent is the right call

• product-manager — the user describes a new capability or strategy in prose
• card-groomer — the backlog feels messy, before sprint planning, after a burst of auto-filed issues
• software-architect — a card touches auth, data retention, credentials, order flow, or spans multiple services
• feature-developer — a card is groomed, sized for one PR, and has acceptance criteria
• ux-polisher — a developer PR is working but clunky

Guardrails all agents share

• No Co-Authored-By: trailers in commits (user pref)
• No force-push to shared branches (main, merged PRs)
• No secrets in code or issues — gitleaks + scanners will catch it, but don't rely on them
• Escalate over-guess — when scope is ambiguous, comment on the card and wait
• Only humans close issues and merge PRs unless explicitly authorized (e.g. "close all duplicates")
• Respect product invariants — see software-architect.md for the full list (no stored creds, passkeys-only, GDPR, paper-first gating, email-only contact, audit trails)

Dispatch pattern: use isolation: "worktree" for mutation agents

When invoking feature-developer or ux-polisher via the Agent tool, always pass isolation: "worktree". Claude Code spawns the subagent in its own git worktree (shared .git dir, separate working tree at .claude/worktrees/agent-<id>/) so the subagent's Edit/Write operations don't contend with:

• The parent session's working tree
• Other concurrently-dispatched agents

Observed 2026-04-22: without worktree isolation, three parallel feature-developer dispatches all hit hard Write/Edit permission walls — Claude Code's mutation-safety heuristic triggers when multiple agents share a working tree. With worktree isolation, a single dispatch and parallel dispatches both work cleanly.

# Correct — mutation agent, worktree-isolated
Agent({
  subagent_type: "feature-developer",
  isolation: "worktree",         # required for parallel + recommended even solo
  run_in_background: true,
  prompt: "...self-contained brief..."
})

For software-architect, product-manager, card-groomer, marketing-strategist, business-legal-researcher, ux-designer, bookkeeper — worktree isolation is still recommended when running in parallel with other agents, but not strictly required for solo design/research work (those agents mostly write docs + file GitHub issues, which don't collide with source-code mutation).

Caveats to know:

• pip install and external-process spawn are sandbox-restricted separately from worktree isolation. If an agent needs new Python deps, it may need to mock them via sys.modules injection and let CI install them for real. Same for direct pytest invocations — CI runs tests, agent writes them.
• Worktree is auto-cleaned if the agent makes zero changes. Otherwise the path + branch are returned in the task-notification result and the agent's work is preserved on the branch.
• Cross-worktree merge conflicts are possible if two parallel agents touch the same file. Design dispatches so their scopes don't overlap (e.g. three parallel cards on different files = fine; three parallel cards all editing requirements.txt = conflict bound to happen).

Invocation examples

Product manager breaking down a new initiative:

Task product-manager to break down "production release to Heroku with versioning + docs + marketing site" into epic + sub-cards

Architect designing the auth layer:

Task software-architect to design multi-user auth with WebAuthn passkeys and GDPR compliance

Developer implementing a groomed sub-card:

Task feature-developer to implement #94 (WebAuthn registration endpoint)

UX polish on a developer's PR:

Task ux-polisher to polish [PR #123](https://github.com/raxx-app/TradeMasterAPI/pull/123)

Groomer sweeping:

Task card-groomer to triage the open backlog

Anti-patterns

• ❌ A single agent trying to both design and implement ("I'll architect + code this") — loses the clean handoff that keeps reviews scoped.
• ❌ UX polisher touching backend logic to "make the UI faster" — file a backend card instead.
• ❌ Feature developer shipping without a flag on a user-facing change — violates rollback invariant.
• ❌ Product manager merging PRs — PM never merges.
• ❌ Architect writing 5000-word design docs — if it's that big, it's multiple designs.

Why this pipeline

Each lane is optimized for its concern: PM for scope, groomer for quality, architect for constraints, developer for correctness, polisher for elegance. Mixing concerns means none get done well.

The pipeline also means a human reviews the PR with a specific question: "did feature-developer satisfy the card, and did ux-polisher polish it?" The reviewer's job is scoped, not open-ended.