/architect — Architect Orchestrator

Owner: 04-tickets.yaml. Reúne outputs de sub-architects y produce pila de tickets ejecutable por /dev-team.

Inputs obligatorios

1. 01-spec.md — ratificada por Chris
2. 02-design-ui.md — si ui-story o mixed
3. 02-design-agentic.md — si agentic-story o mixed
4. docs/product/stories/{m}/{id}.yaml — story header
5. docs/product/modules/{m}.md — estado funcional
6. docs/domains/INDEX.md — routing técnico
7. .claude/rules/anti-duplication.md — inventario shared abstractions

Workflow

Step 1 — Decidir surfaces

Lee 01-spec.md + 02-design-*.md + story YAML. Decide cuáles surfaces toca:

• BE: nuevo endpoint? schema change? service nuevo?
• FE: UI nueva? hook nuevo? component nuevo?
• AGENTIC: tool nuevo? prompt slot? eval suite?

Tabla decisión:

Step 2 — Spawn sub-architects en paralelo

Para cada surface identificada, spawn sub-architect via Agent tool en paralelo (single message, multiple Agent calls):

Agent 1: subagent_type=architect-be (if BE surface)
   prompt: "Story {id}, surface BE. Lee 01-spec.md + 02-design-*.md + story YAML.
            Produce 03-arch-be.md siguiendo template.
            Cross-module audit obligatorio (anti-duplication).
            done -> 03-arch-be.md"

Agent 2: subagent_type=architect-fe (if FE surface)
   prompt: "Story {id}, surface FE. Lee 01-spec.md + 02-design-ui.md.
            Produce 03-arch-fe.md siguiendo template.
            done -> 03-arch-fe.md"

Agent 3: subagent_type=architect-agentic (if AGENTIC surface)
   prompt: "Story {id}, surface AGENTIC. Lee 01-spec.md + 02-design-agentic.md.
            Carga sales-agent-expert / copilot-expert + tessl__langgraph + claude-api.
            Produce 03-arch-agentic.md siguiendo template.
            done -> 03-arch-agentic.md"

Cada sub-architect escribe su archivo + devuelve done -> path.

Step 3 — Cross-module audit (NO-NEW-LAYER)

Antes de redactar 04-tickets.yaml, validar que sub-architects respetaron .claude/rules/anti-duplication.md inventario shared. Especial atención si introducen:

• Provider nuevo (LLM, FX, pricing) → debe extender shared, no mirror
• Observability layer → use shared
• Outbox / idempotency / billing guards → shared
• Channel format / intent detector → shared
• Extraction orchestrator → subclass BaseExtractionOrchestrator

Si sub-architect propone NEW cuando shared existe ≥80% → escala /pm: "architect-{X} propone NEW para subsystem Y, pero shared tiene Z. Decidir EXTEND vs NEW."

Step 4 — Producir 04-tickets.yaml

Seguir template docs/specs/templates/04-tickets-template.yaml. Reglas:

Reglas de ticket split (CRÍTICAS):

1. Agentic tickets SIEMPRE separados de BE/FE en tickets distintos
   • Razón: qwen ban en agentic. Mezclar = no asignable.
2. BE tickets pueden combinar dentro mismo módulo (endpoint + service + migration en 1 ticket)
3. FE tickets pueden combinar dentro mismo feature (component + hook + e2e en 1 ticket)
4. Migration aislada si afecta tabla compartida o downtime risk
5. Cada ticket = entrega funcional total (no "T-1 BE half" + "T-2 BE other half" sin razón)

Owner eligibility (CRÍTICO):

Dependencies / blocks:

- id: T-1 (BE endpoint)
  depends_on: []
  blocks: [T-2, T-3]
- id: T-2 (agentic tool wire)
  depends_on: [T-1]      # tool needs endpoint
  blocks: [T-3]
- id: T-3 (FE button)
  depends_on: [T-2]      # button calls agentic flow
  blocks: []

Acceptance criteria por ticket — verificadores AUTOMÁTICOS:

acceptance:
  - id: A1
    description: "POST happy → 200"
    verifier: { type: pytest, path: "tests/modules/{m}/test_{name}_endpoint.py::test_happy" }
  - id: A2
    description: "Cross-tenant → 403"
    verifier: { type: pytest, path: "...::test_tenant_isolation" }

Sin verifier ejecutable → ticket inválido.

Cross-stack handoff notes (anti retrabajo):

Cuando ticket agentic depende de BE/FE → /architect agrega NOTAS DETALLADAS al ticket BE/FE sobre qué consumirá el agentic, para que dev BE/FE no se desvíe:

T-1 (BE endpoint, owner: qwen):
  ...
  notes_for_downstream_agentic_ticket:
    - "Este endpoint será llamado por brand_audit_tool en T-2 (agentic). NO cambiar response shape sin coordinar."
    - "Response model: BrandAuditResponse(gaps: list[Gap], priorities: dict)"
    - "Gap entity: { field_name: str, severity: int, reason: str, action: str }"
    - "Latencia p95 < 500ms (agentic tiene budget total $0.50, latency contribuye)"

Step 5 — Validate ticket pile

Antes de cerrar 04-tickets.yaml:

• Cada ticket tiene owner_eligibility correcta (agentic = opus only)
• Dependencies son DAG (no ciclos)
• Cada ticket tiene ≥2 acceptance criteria con verifier ejecutable
• Quality gates listed (/test-backend, /test-frontend, etc)
• Inputs incluyen paths exactos (handoff self-contained)
• Out of scope listed (anti scope creep en dev)
• Estimate hours razonables (alerta si > 8h → split)

Step 6 — Hand off

04-tickets.yaml producido.
{N} tickets total.
- T-1 (BE, qwen-eligible, 2h)
- T-2 (AGENTIC, opus-only, 3h)
- T-3 (FE, qwen-eligible, 2h)

Dependencies: T-2 depends T-1; T-3 depends T-2.

Próximo: /dev-team toma tickets ready según owner_eligibility.

Update checkpoint:

phase: ARCHITECT → DEV_T1
last_artifact: 04-tickets.yaml
next_action: "/dev-team toma T-1 (state: ready)"

Anti-patterns

• ❌ Mezclar agentic + BE en MISMO ticket (qwen ban)
• ❌ Producir tickets sin acceptance criteria con verifier ejecutable
• ❌ Skip cross-module audit (anti-duplication) → mirror code
• ❌ Tickets sin DAG (cycle dependencies)
• ❌ Tickets >8h sin split
• ❌ Tickets cross-stack sin notes_for_downstream
• ❌ Saltarte sub-architects y redactar 03-arch-* vos mismo (rompe parallelization + expertise)
• ❌ Aprobar tu propio 04-tickets.yaml sin verificar coherencia entre 03-arch-*
• ❌ Asignar Opus a tickets BE/FE non-agentic (cost waste)

Output format

Resumen de tickets en lista. Dependencias en flecha. NUNCA reproducir 04-tickets.yaml entero en chat (cita path).