Parallel Work Orchestration Plan

Version: 0.1.0 Last Reviewed: 2026-02-12 Status: Draft

Overview

Strategy for multi-agent parallel development using git worktrees and Hearth v0.6.0 coordination tools.

Prerequisites (Sequential, One Agent)

Parallel work is only safe after "first patterns" are established. These must be done sequentially by a single agent:

Backend API

1. API project scaffold (BB-1z2s47ox) — plugin order, error handler, route registration, Zod schemas, Prisma setup
2. Database schema — Prisma model conventions, relations, enums, audit fields
3. Auth - email/password — first complete route (schema -> service -> route -> test), middleware pattern
4. API test infrastructure (BB-jf8sv1zl) — test DB setup, fixtures, helpers
5. First feature (e.g., Feedings) — establishes the repeatable feature pattern

iOS App

1. iOS app shell + scaffold — MVVM pattern, Repository protocol, Network service, @Observable
2. Auth flow — first complete feature (View -> ViewModel -> Repository -> Network), Keychain
3. Shared iOS components — reusable LoadingButton, ErrorView, etc.
4. First feature sheet (e.g., Feeding) — establishes the repeatable sheet pattern

After each "first pattern" item, the implementing agent posts a bulletin:

hearth bulletin --author "api-feedings" "Pattern established: route/schema/service/test. See src/routes/feedings.ts"

Parallel Batching Plan

Backend API (after prerequisites)

Batch	Items	Why parallel is safe
A	Feedings + Diapers	Separate route/schema/service/test files
B	Sleep + Notes	Same isolation
C	Children CRUD + Share Links	Separate route files (share links uses children but doesn't modify them)
D	Dashboard API + Timeline API	Read-only endpoints, no schema changes

iOS App (after prerequisites)

Batch	Items	Why parallel is safe
A	Feeding sheet + Diaper sheet	Separate Feature/ directories
B	Sleep sheet + Notes sheet	Same isolation
C	Dashboard + Timeline	Touch TabView — keep as one unit

Cross-Layer (always safe)

• 1 API agent + 1 iOS agent on different features
• 1 API agent + 1 infra agent
• API features + iOS components

Agent Limits

• 2-3 max simultaneous agents
• 2 agents on API features — each feature touches isolated files
• 1 agent on iOS features — more shared state risk (NavigationStack, TabView)
• Never 2 agents modifying the same shared file (Prisma schema, route index, TabView)

Worktree Setup

# From the main repo:
hearth worktree add ../baby-feedings bb-XXXX-feedings
hearth worktree add ../baby-diapers bb-YYYY-diapers

# Verify:
hearth worktree list

Each worktree:

• Branches from develop
• Has its own node_modules and .env
• Runs its own test DB (unique docker-compose port)
• Shares hearth/forge data via symlinks (automatic with hearth worktree add)

PR Merge Order

1. Scaffold/pattern PRs merge first (establish conventions)
2. Feature PRs merge in batch order (A before B before C)
3. Within a batch, order doesn't matter
4. After each merge, other branches rebase on develop

Merge Checklist

• Tests pass on the branch
• Reviewed by at least one other agent or the user
• Rebased on latest develop
• No merge conflicts
• Bulletin posted if PR establishes or changes a pattern

Orchestration

User Role (Variable)

The user may:

• Actively monitor — watching sage status, reviewing PRs in real-time
• Periodically check in — agents work autonomously, escalating when blocked
• PR gatekeeper — agents work fully autonomously, user reviews and merges PRs

Coordinator Agent

An optional coordinator agent monitors the project and makes recommendations:

1. Runs sage status --json — current state
2. Checks bulletins — resolves or escalates
3. Checks gh pr list — assigns reviews
4. Checks forge backlog list — recommends next items
5. Posts bulletins with instructions

The coordinator reads the board, makes calls, communicates. It never writes code.

Blocking Issue Resolution

When an agent discovers a blocking issue:

1. Posts bulletin: hearth bulletin --author "agent-name" "BLOCKING: [description]. Pausing BB-XXXX."
2. Logs it: hearth log --tag blocked "[BB-XXXX]: Waiting on resolution of Y"
3. The blocking agent pauses or picks up a different unblocked item
4. Resolution path:
   • Another agent sees the bulletin on their next sage status check and responds via log/bulletin
   • The user sees the bulletin during a check-in and decides
   • The coordinator agent triages and resolves
5. After resolution: hearth log --tag decision "Resolved: [description]" + clear the bulletin

Not In Scope

• Agent-to-agent direct messaging (async via bulletins/logs is sufficient)
• Auto-spawning agents (Claude Code doesn't support nested spawning)
• Real-time conflict detection (agents check manually via git and PR reviews)