Plan de Orquestación Multiagente — NutriFlow Billing Module

Workers Paralelos

DB · API · Frontend · Tests

Ahorro de Tiempo

~68%

vs. ejecución secuencial

Tokens Estimados

~480K

total sesión completa

Archivos Generados

schema · endpoints · UI · tests

Tiempo Real Est.

~45min

en paralelo (vs 2h 20min)

Vista tmux — sesión activa

tmux · nutriflow-billing

1:orchestrator 2:db-schema 3:api-billing 4:frontend 5:tests

Orchestrator — Pane 0 idle · esperando workers

# ~/nutriflow $ dmux start --session nutriflow-billing --workers 4 ✔ tmux session 'nutriflow-billing' created with 5 panes ✔ Git worktrees creados: feat/billing-db · feat/billing-api · feat/billing-ui · feat/billing-tests ✔ Workers lanzados en panes 1-4
# Comandos útiles: n → nuevo pane con prompt m → merge output al pane principal Ctrl+b 1-4 → navegar entre workers
# Estado actual Pane 1 [DB-schema] ████████████░░░ 78% — Generando migraciones... Pane 2 [API-billing] ██████░░░░░░░░░ 42% — Implementando /subscribe... Pane 3 [Frontend] █████████░░░░░░ 60% — PlanSelector listo, BillingHistory... Pane 4 [Tests] ████░░░░░░░░░░░ 25% — Esperando endpoints de Pane 2...

Pane 1 — DB Schema running · Claude Code

claude "Crea schema PostgreSQL para el módulo billing de NutriFlow: tablas subscriptions, invoices, payment_methods. Incluye migraciones Flyway..." Creating: db/migrations/ V001__create_subscriptions.sql ✔ V002__create_invoices.sql ✔ V003__payment_methods.sql...

Pane 2 — API Billing running · Claude Code

claude "Implementa endpoints REST: POST /subscribe, POST /cancel, GET /invoices, POST /webhook Stripe. Express + Zod validation..." Creating: src/api/billing/ routes.js ✔ controllers/subscribe.js ✔ middleware/stripe-webhook.js...

Prompts por Worker

DB Schema & Migrations

feat/billing-db

⬡ Claude Code · Worktree: feat/billing-db

Tarea: Crea el esquema de base de datos completo para el módulo de facturación de NutriFlow. Tablas requeridas: - subscriptions (id, clinic_id, plan_id, stripe_subscription_id, status, current_period_end, created_at) - invoices (id, subscription_id, amount_eur, status, stripe_invoice_id, pdf_url, issued_at) - payment_methods (id, clinic_id, stripe_pm_id, type, last4, is_default) Archivos a crear: db/migrations/V001__create_subscriptions.sql db/migrations/V002__create_invoices.sql db/migrations/V003__payment_methods.sql db/seeds/billing_plans.sql Escribe resultados en /tmp/handoff-db.md al terminar.

~85K tokens ~8 min 4 archivos SQL merge → main antes de Pane 2

API Billing Endpoints

feat/billing-api

⬡ Claude Code · Worktree: feat/billing-api

Tarea: Implementa los endpoints de billing para la API Express de NutriFlow. Endpoints: - POST /api/billing/subscribe — crear suscripción Stripe + guardar en DB - POST /api/billing/cancel — cancelar al final del período - GET /api/billing/invoices — listar facturas de la clínica - POST /api/billing/webhook — manejar eventos Stripe Stack: Express 4, Zod, stripe-node@14, pg pool. Crea tests básicos de humo en src/api/billing/__tests__/smoke.test.js

~120K tokens ~12 min 8 archivos JS merge → main después de DB

Frontend Dashboard Billing

feat/billing-ui

⬡ Claude Code · Worktree: feat/billing-ui

Tarea: Crea los componentes React del panel de facturación para NutriFlow. Componentes: - PlanSelector.tsx — cards con planes Free/Pro/Clinic; Stripe Checkout - BillingHistory.tsx — tabla de facturas con descarga PDF - PaymentCard.tsx — mostrar/cambiar método de pago - BillingPage.tsx — página contenedora con tabs Stack: React 18, TypeScript, Tailwind CSS. Usa datos mock para desarrollar independientemente de la API.

~145K tokens ~14 min 6 componentes TSX merge → main en paralelo con API

Tests + OpenAPI Docs

feat/billing-tests

◈ Codex CLI · Worktree: feat/billing-tests

Tarea: Escribe la suite de tests y documentación para el módulo billing. Tests: - tests/billing/subscribe.test.js — flujo completo con Stripe mock - tests/billing/webhook.test.js — eventos: payment_succeeded, failed, canceled - tests/billing/invoices.test.js — paginación y filtrado Docs: - docs/openapi/billing.yaml — spec OpenAPI 3.1 completa Usa handoff de Pane 2 en /tmp/handoff-api.md cuando esté disponible. Ejecuta: npm test -- --testPathPattern=billing

~130K tokens ~13 min 4 test files + 1 YAML merge → main al final

plan.json — ECC Orchestrate Worktrees

{ } .claude/plan/nutriflow-billing.json

Copiar

{ "sessionName": "nutriflow-billing", "baseRef": "HEAD", "launcherCommand": "claude --cwd {worktree_path} --task-file {task_file}", "seedPaths": [ ".claude/plan/nutriflow-billing.json", "docs/architecture/billing-spec.md" ], "workers": [ { "name": "billing-db", "task": "Crea schema PostgreSQL y migraciones Flyway para subscriptions, invoices, payment_methods. Escribe handoff en /tmp/handoff-db.md." }, { "name": "billing-api", "task": "Implementa endpoints Express: /subscribe, /cancel, /invoices, /webhook. Usa stripe-node@14 + Zod. Escribe handoff en /tmp/handoff-api.md." }, { "name": "billing-ui", "task": "Crea componentes React: PlanSelector, BillingHistory, PaymentCard, BillingPage. TypeScript + Tailwind. Mock data." }, { "name": "billing-tests", "task": "Escribe tests Jest para billing API + spec OpenAPI 3.1. Lee /tmp/handoff-api.md cuando esté disponible.", "dependsOn": ["billing-api"] } ] } # Ejecutar con: # node scripts/orchestrate-worktrees.js .claude/plan/nutriflow-billing.json --execute

Orden de Merge e Integración

Pane 1
billing-db
~8 min

→

Merge DB
a main
git merge

→

API

Pane 2
billing-api
~12 min

⇅

Pane 3
billing-ui
~14 min

→

Merge API+UI
a main
revisar conflicts

→

Pane 4
billing-tests
~13 min

→

✓

Integración
final + CI
npm test

Estimación de Tokens y Tiempo

Worker	Agente	Tokens Input	Tokens Output	Total	Tiempo Est.
Pane 1 — DB Schema	Claude Sonnet	12K	73K	85K	~8 min
Pane 2 — API Billing	Claude Sonnet	18K	102K	120K	~12 min
Pane 3 — Frontend	Claude Sonnet	20K	125K	145K	~14 min
Pane 4 — Tests + Docs	Codex CLI	22K	108K	130K	~13 min
Total sesión paralela				480K	~45 min

Buenas Prácticas Aplicadas

🌿

Git Worktrees

Cada worker opera en su propia rama aislada (feat/billing-*), evitando conflictos de archivos durante el desarrollo paralelo.

📄

Handoff Files

Cada pane escribe /tmp/handoff-*.md al terminar. El orquestador y workers dependientes los leen para coordinar sin race conditions.

🔗

Dependencias explícitas

Pane 4 (tests) declara dependsOn: billing-api en plan.json. El orquestador lo lanza solo cuando el pane de API escribe su handoff.

⚡

Tareas independientes

DB, API y Frontend tocan archivos completamente distintos (/db, /src/api, /src/components). Cero riesgo de conflictos al paralelizar.

🔢

Máximo 5-6 panes

4 workers + 1 orquestador es el sweet spot. Más panes aumentan tokens exponencialmente sin proporcional ganancia de velocidad.

🔍

Revisión antes de merge

El orquestador revisa el output de cada pane (tmux capture-pane) antes de hacer merge. Nunca merge automático ciego.

Plan de Orquestación — NutriFlow Billing