Task Distribution

How the main agent distributes tasks to sub-agents for parallel execution.

Agent Profiles

Agent profiles are in .claude/agents/:

•backend.md – BE agent for be/
•frontend.md – FE agent for fe/
•test.md – Test agent for be/test/

Pre-Distribution: API Generation Decision

Think like a senior fullstack developer - decide if API generation is needed BEFORE spawning agents.

Decision Flow

code

1. What feature/module is this task for? (e.g., "product")
2. Check: Does `bff/<pkg>/<pkg>.proto` exist?
   - No → Skip generation, implement manually
   - Yes → Continue to step 3
3. Check: Is this task API-related?
   - Creates/modifies routes, services, hooks, api calls → Need generation
   - Only UI components, styling, state → Skip generation
4. Check: Are generated files already present?
   - `be/core/api/<pkg>/<pkg>.routes.ts` exists?
   - `fe/src/services/<pkg>/api.ts` exists?
   - If missing or proto changed → Run generation
   - If present and unchanged → Skip generation
5. Run: `npm run gen -- <pkg>` if needed

Quick Decision Table

Task Type	Proto Exists?	Generated Files?	Action
New API endpoint	Yes	No	`npm run gen -- <pkg>`
New API endpoint	No	-	Create proto first, then gen
Modify existing API	Yes	Yes, outdated	`npm run gen -- <pkg>`
UI component only	-	-	Skip generation
Styling/design	-	-	Skip generation
Add service logic	Yes	Yes	Skip (files exist)

Example

code

Task: T001 - Create product listing page

Analysis:
1. Feature: product
2. Proto: bff/product/product.proto ✅ exists
3. API-related: Yes (needs useGetProducts hook)
4. Generated files:
   - fe/src/services/product/api.ts ❌ missing
   - fe/src/services/product/useQuery.ts ❌ missing

Decision: Run `npm run gen -- product` before spawning Frontend Agent

Architecture

mermaid

flowchart TD
    MAIN[MAIN AGENT<br/>analyzes tasks, decides parallel vs sequential]
    MAIN -->|spawn| BE[Backend Agent]
    MAIN -->|spawn| FE[Frontend Agent]
    MAIN -->|spawn| TEST[Test Agent]
    BE --> BE_DIR[be/core/*]
    FE --> FE_DIR[fe/src/*]
    TEST --> TEST_DIR[be/test/*]

Note: E2E tests (e2e/) are run by user manually, not by agents.

Available Sub-Agents

Agent	File	Workspace	Handles
Backend	`.claude/agents/backend.md`	`be/`	Repos, Services, Routes
Frontend	`.claude/agents/frontend.md`	`fe/`	Components, Hooks, UI
Test	`.claude/agents/test.md`	`be/test/`	Integration tests only

When to Parallelize

Check these rules:

Condition	Decision
Tasks touch different workspaces (BE vs FE)	✅ Parallel OK
Tasks touch same file	❌ Sequential only
Task B depends on Task A output	❌ Sequential only
Tasks are independent features	✅ Parallel OK
Tasks share database schema changes	❌ Sequential only

Decision Flow

code

1. Load pending tasks from progress.md
2. For each pair of tasks, check:
   - Same workspace? → Sequential
   - Same file? → Sequential
   - Dependency? → Sequential
   - Otherwise → Can Parallel
3. Group into waves
4. Ask user to confirm
5. Spawn sub-agents for parallel tasks

Wave Execution

mermaid

flowchart TD
    subgraph Wave1["Wave 1 (Parallel)"]
        BE[Backend Agent<br/>T001 be/]
        FE[Frontend Agent<br/>T002 fe/]
    end
    subgraph Wave2["Wave 2 (Sequential)"]
        TEST[Test Agent<br/>T003 tests T001]
    end
    Wave1 -->|sync point| Wave2

File Lock Rules

When spawning sub-agents, assign file locks:

yaml

# Example lock assignment
T001 (Backend Agent):
  locks:
    - be/core/repo/product.repo.ts
    - be/core/services/product.service.ts

T002 (Frontend Agent):
  locks:
    - fe/src/components/product-module/*

Rules:

•One agent per file
•Lock acquired before task starts
•Lock released after verification
•Conflicts → force sequential

Spawn Format

When spawning a sub-agent, provide:

code

🤖 Spawning BACKEND Agent

Task: T001 - Create product.repo.ts
Profile: .claude/agents/backend.md
Locked Files:
  - be/core/repo/product.repo.ts

Instructions:
1. Read the agent profile
2. Execute task following profile patterns
3. Report back with completion status

Sync After Wave

After all agents in a wave complete:

•Collect results from each agent
•Update progress.md with completed tasks
•Release locks for completed tasks
•Check next wave dependencies
•Ask user before proceeding

Max Parallel

•Max 3 agents per wave
•If more tasks, split into multiple waves