/dev-team — Developer Team Router (Conv 2 autonomous build)

WS=$(git rev-parse --show-toplevel)
BRAND={brand}                                                # vitalia | nicolify | comunify | lupulo | platform
STORY_DIR=${WS}/docs/product/stories/{story-id}
cat ${STORY_DIR}/checkpoint.md      # verify state=ready (o state=developing si retomas)
cat ${STORY_DIR}/06-tickets.yaml    # pila tickets
cat ${STORY_DIR}/04-validators.yaml # ★ corazón autonomous loop ★
cat ${STORY_DIR}/05-guidelines.md   # patterns + files in scope

# checkpoint.md
state: developing   # ★ TRANSITION ready → developing ★
phase: BUILD_T1

WS=$(git rev-parse --show-toplevel)
BRAND={brand}

# Listar todos los checkpoints stories del brand
for cp in ${WS}/docs/product/stories/*/checkpoint.md; do
  STORY_ID=$(basename $(dirname $cp))
  STATE=$(grep -E "^state:" $cp | head -1 | awk '{print $2}')
  DEFER=$(grep -E "^defer_audit:" $cp 2>/dev/null | awk '{print $2}')
  if [[ "$STATE" =~ ^(developing|developed|reviewing)$ ]] && [[ "$DEFER" != "true" ]]; then
    echo "BLOCK: story $STORY_ID en state=$STATE sin defer_audit"
  fi
done

❌ Story closure gate: cannot pickup ticket T-{n} de story {new-story-id}
   porque story {open-story-id} está en state={state} sin defer_audit.

   Acciones disponibles:
   1. Continuar story {open-story-id} hasta state=done (default forward-motion)
   2. Ratificar defer_audit:true en {open-story-id}/checkpoint.md con razón
      documentada + Chris explícito
   3. Cleanup-session el worktree actual y crear nuevo
      (scripts/git/new-session.sh --story-id {new-story-id})

   SSoT regla: .claude/rules/story-closure-gate.md (Layer 2)

BRIEF=$STORY_DIR/CONTEXT-BRIEF.md
LATEST_COMMIT=$(git log -1 --format=%H -- $STORY_DIR)

Agent({
  description: "Build context brief for ticket T-{n} brand={brand}",
  subagent_type: "context-builder",
  model: "haiku",
  prompt: "<brand>: {brand}                          # ★ REQUIRED — single-project scope
           <pr_folder>: <STORY_DIR absolute>;
           <modules>: <comma list from story spec>;
           <phase>: builder;
           <subsystem_keywords>: <comma list>;
           <frameworks>: <fastapi, langgraph, anthropic, sqlalchemy, pydantic, etc.>"
})

ERROR — hot-fix ticket missing repro_verified per
.claude/rules/hotfix-repro-mandatory.md.
Run repro command first, document evidence, then proceed.

state: assigned
assigned_to: qwen-opencode | claude-opus | claude-sonnet
assigned_at: 2026-05-06T...
transitions:
  - { state: assigned, at: ..., by: "/dev-team", to: "<owner>" }

## Skills consulted (must_load enforcement v4.1)

| Skill / Rule | Status | When consulted |
|---|---|---|
| backend-expert | ✅ loaded | Step 0 — DDD pattern check |
| frontend-expert | n/a | surface=BE only |
| .claude/rules/tenant-isolation.md | ✅ loaded | mid-build — verify query filter |
| .claude/rules/anti-duplication.md | ✅ loaded | Step 0 grep cross-module |
| playwright-expert | ✅ loaded | mid-build — POM patterns |
| ... | ... | ... |

WS=$(git rev-parse --show-toplevel)
BRAND={brand}                                                # vitalia | nicolify | comunify | lupulo | platform
STORY_DIR=${WS}/docs/product/stories/{story-id}

cat > /tmp/T-{n}-qwen-prompt.md <<EOF
Eres developer Luana ({brand} brand) ejecutando T-{n} de story {story-id}.
Brand scope: ${BRAND} — TODO edit debe respetar paths bajo . NO editar ${WS}/core/luana-core-*/src/ (engine, requires /pm promotion gate). NO editar {other_brand}/... (cross-module).

PRIORITY READ — CONTEXT-BRIEF (Haiku-built, 5-8k tokens, contiene spec+arch+rules+anti-dup+canonical docs):
- ${STORY_DIR}/CONTEXT-BRIEF.md

Lee TAMBIÉN estos archivos del READY PACKAGE (si brief insuficiente):
- ${STORY_DIR}/01-spec.md — Gherkin scenarios + (si UI std) wireframes
- ${STORY_DIR}/03-arch.md — technical decisions (★ v4.1: incluye § Test Construction Plan)
- ${STORY_DIR}/04-validators.yaml — ★ comandos must_pass + § test_construction_plan (orden + POMs + fixtures + scenario_to_test mapping)
- ${STORY_DIR}/05-guidelines.md — patterns required/forbidden + § must_load_skills (★ v4.1 enforceable)
- ${STORY_DIR}/06-tickets.yaml — find your ticket entry T-{n} + gherkin_coverage

★ MUST LOAD SKILLS (v4.1 enforceable — DEBE cargar TODAS antes de codear):
<LIST EXTRACTED FROM 05-guidelines.md § must_load_skills RESOLVED, e.g.:>
- backend-expert
- playwright-expert (si test_construction_plan.playwright_required=true)
- .claude/rules/tenant-isolation.md
- .claude/rules/anti-duplication.md
- .claude/rules/spanish-text.md
- .claude/rules/auditor-self-fix-policy.md (saber qué auditor self-fix vs spawn dev-team)
- tessl__fastapi (si BE endpoint nuevo)
- ... (extractar verbatim según ticket surface + module)

AUTONOMOUS LOOP:
1. Load must_load_skills listed above (Step 0). Each Skill tool invocation registrado.
2. Read 04-validators.yaml § test_construction_plan — sigue creation_order para Playwright tests (no inventes orden).
3. Read 04-validators.yaml validators list. Run validators ASOCIADOS al ticket T-{n} (acceptance.validator_ids list).
4. RED: tests fallarán (no implementation yet).
5. Implementá MÍNIMO para que validators GREEN — solo files dentro 05-guidelines.md "Files in scope" (TODOS brand-scoped bajo ).
6. Re-run validators. Si fallan: fix targeted file por error trace, re-run failing validator only.
7. Repeat hasta TODOS validators GREEN o iteration cap reached (default 10).
8. Update T-{n}-impl-log.md con iteration_log VIVO mientras trabajás (cada iter: timestamp + validator + result + fix applied).
9. ★ v4.1: T-{n}-result.md MUST incluir sección "Skills consulted (must_load enforcement v4.1)" con tabla skill/rule + status + when consulted (ver dev-team SKILL.md § must_load_skills enforcement).

Reglas TDD obligatorias:
1. RED: validators fallan primero (sin implementation)
2. GREEN: implementa mínimo
3. REFACTOR: limpiar

Convenciones (.claude/rules/* — citados también en 05-guidelines.md):
- backend-ddd.md o frontend-fsd.md
- tenant-isolation.md
- spanish-text.md (Spanish neutro, no voseo)
- backend-migrations.md (idempotente)
- anti-duplication.md (cross-module mirror ban)
- tdd-mandatory.md
- git-safety.md (triple-branch: wip/* | main | release/*; NO 'origin development')

Quality gates antes push (★ HARD — G5 pre-commit smoke gate):
- TODOS validators de 04-validators.yaml asociados al ticket → GREEN antes commit
- Lint + format clean (cd backend && ../../.venv/bin/ruff check + ruff format --check; cd frontend && npx eslint + tsc --noEmit)
- Env-gated validators corridos con env real (NO skip si validator dice EVAL_*=1)
- Case-sensitivity check si validator compara enum/string-literal
- 05-guidelines.md "Files in scope" respected (no escape; SOLO  paths)
- RED bloquea commit. Fix file → re-run validator → repeat hasta GREEN.

Push destination (triple-branch policy):
- git push origin "\$(git branch --show-current)"   # wip/{slug} autosave, main post squash, release/vX.Y.Z
- NUNCA 'git push origin development' (branch eliminado en reorg 2026-05-15)

Output al terminar:
- T-{n}-result.md con diff resumen + validator gates output literal + commit SHA
- Estado ticket: pushed (en 06-tickets.yaml)
- Last line del response: "done -> T-{n}-result.md"

Si cap_reached (10 iter sin GREEN):
- T-{n}-impl-log.md sección "Cap reached — escalating"
- Estado ticket: blocked
- Last line: "blocked -> T-{n}-impl-log.md (see iteration_log)"
EOF

cd ${WS}
opencode run \
  --prompt-file /tmp/T-{n}-qwen-prompt.md \
  --workspace ${WS} \
  --model qwen-coder \
  --max-iterations 50

# Si opencode falla / API no disponible → fallback: copiá prompt + Chris ejecuta manual:
# echo "Pegá esto en opencode CLI: $(cat /tmp/T-{n}-qwen-prompt.md)"

Agent({
  description: "Build agentic ticket T-{n} brand={brand}",
  subagent_type: "builder-agentic",
  prompt: "<brand>: {brand}                          # ★ REQUIRED — single-project scope
           <pr_folder>: docs/product/stories/{story-id}/
           PRIORITY READ: docs/product/stories/{story-id}/CONTEXT-BRIEF.md (Haiku-built, 5-8k tokens compresses spec+arch+rules+anti-dup+canonical docs)
           READY PACKAGE (todos bajo docs/product/stories/{story-id}/): 01-spec.md + 02-design-agentic.md + 03-arch.md (★ v4.1: incluye § Test Construction Plan) + 03-arch-agentic.md + 04-validators.yaml (★ v4.1: 5 categorías + test_construction_plan + scenario_coverage sub-categorías) + 05-guidelines.md (★ v4.1: must_load_skills enforceable) + 06-tickets.yaml (gherkin_coverage por ticket)
           ★ MUST_LOAD SKILLS (v4.1 enforceable): <list extracted from 05-guidelines.md § must_load_skills resolved per ticket surface — typical agentic: copilot-expert/sales-agent-expert + tessl__langgraph + claude-api + graceful-degradation + auditor-self-fix-policy.md + tenant-isolation.md + spanish-text.md>
           ★ MUST DELIVER in T-{n}-result.md: sección "Skills consulted (must_load enforcement v4.1)" con tabla skill/rule + status + when. Auditor flag CHANGES_REQUESTED si missing.
           Surface scope: SOLO backend/src/modules/{copilot,sales_agent}/{tools,extractors,workflows,personas,goldens,kb}/ (brand-extension). NUNCA core/luana-core-*/src/ (engine — requires /pm lift).
           AUTONOMOUS LOOP: implement → run validators (acceptance.validator_ids) → fix → repeat hasta GREEN o cap_reached
           TDD: eval goldens RED first, integration tests, tools tests, etc.
           ★ G5 PRE-COMMIT SMOKE GATE: validators GREEN + lint + format + env-gated tests con env real + case-sensitivity match — TODO antes commit.
           ★ Test Construction (v4.1): seguir test_construction_plan.creation_order del 04-validators.yaml para Playwright tests (no inventar orden, POMs ni fixtures).
           Push destination: git push origin \$(git branch --show-current). NUNCA 'origin development'.
           Output: T-{n}-result.md (con Skills consulted) + commit pushed
           Last line: done -> docs/product/stories/{story-id}/T-{n}-result.md (o blocked -> T-{n}-impl-log.md)"
})

Agent({
  description: "Build {surface} ticket T-{n} brand={brand}",
  subagent_type: "builder-{backend|frontend}",
  model: "sonnet",
  prompt: "<brand>: {brand}                          # ★ REQUIRED — single-project scope
           <pr_folder>: docs/product/stories/{story-id}/
           Read docs/product/stories/{story-id}/CONTEXT-BRIEF.md FIRST (saves 30-50k tokens vs raw docs).
           READY PACKAGE (todos bajo docs/product/stories/{story-id}/): 01-spec.md + 03-arch.md (★ v4.1 § Test Construction Plan) + 04-validators.yaml (★ v4.1 5 categorías) + 05-guidelines.md (★ v4.1 must_load_skills) + 06-tickets.yaml
           ★ MUST_LOAD SKILLS (v4.1 enforceable): <list extracted from 05-guidelines.md § must_load_skills resolved>
           ★ MUST DELIVER in T-{n}-result.md: sección "Skills consulted (must_load enforcement v4.1)".
           Surface scope: SOLO backend/src/ + frontend/src/. NUNCA core/luana-core-*/src/ (engine). NUNCA {other_brand}/...
           AUTONOMOUS LOOP: implement → run validators → fix → repeat
           TDD obligatorio.
           ★ G5 PRE-COMMIT SMOKE GATE: validators GREEN + lint + format + env-gated tests con env real + case-sensitivity match — TODO antes commit. RED bloquea commit.
           ★ Test Construction (v4.1): seguir test_construction_plan.creation_order del 04-validators.yaml.
           Push destination: git push origin \$(git branch --show-current). NUNCA 'origin development'.
           Last line: done -> docs/product/stories/{story-id}/T-{n}-result.md"
})

WS=$(git rev-parse --show-toplevel)
STORY_DIR=${WS}/docs/product/stories/{story-id}

# Extract scenarios from 01-spec.md
grep -nE "^### Scenario" ${STORY_DIR}/01-spec.md > /tmp/scenarios.txt
SCENARIO_COUNT=$(wc -l < /tmp/scenarios.txt)

# Extract gherkin_coverage from 06-tickets.yaml
grep -A 10 "gherkin_coverage:" ${STORY_DIR}/06-tickets.yaml > /tmp/coverage.txt
COVERED_COUNT=$(grep -c "scenario:" /tmp/coverage.txt)

if [ $SCENARIO_COUNT -gt $COVERED_COUNT ]; then
  echo "❌ Phase D local gap: $SCENARIO_COUNT scenarios en 01-spec.md, $COVERED_COUNT cubiertos en gherkin_coverage"
  echo "   STOP — agrega entries faltantes a 06-tickets.yaml::gherkin_coverage antes auto-handoff auditor"
  exit 1
fi

# Verify cada test citado existe + PASS
# (lectura gherkin_coverage + pytest/playwright targeted run + report)
echo "✅ Phase D local coverage: $SCENARIO_COUNT/$SCENARIO_COUNT scenarios mapeados"

state: pushed
push_commit_sha: abc1234
transitions:
  - { state: tests-passing, ... }
  - { state: pushed, ..., commit: "abc1234" }

# docs/product/stories/{story-id}/checkpoint.md
brand: {brand}     # ★ REQUIRED — single-project scope
state: developed   # ★ TRANSITION developing → developed ★
phase: HANDOFF_TO_AUDITOR
last_artifact: T-{N}-result.md (last ticket)
next_action: "/auditor <brand>: {brand} toma story {id} para Conv 3 review+merge (AUTO-HANDOFF default)"

DEFER=$(grep -E "^defer_audit:" ${STORY_DIR}/checkpoint.md 2>/dev/null | awk '{print $2}')

✅ Story {story-id} all tickets pushed.
- T-1 (commit abc1234) ✅
- T-2 (commit def5678) ✅
- T-3 (commit 9876abc) ✅

Quality gates: validators all GREEN.
Story state: developing → developed.
WIP cap check: developing (was 1) now 0; developed (was 0) now 1 / cap 1.

→ AUTO-HANDOFF /auditor <brand>: {brand} story={story-id}

  (Conv 3 default post 2026-05-18 story-closure-gate.
   Lee T-{n}-result.md + Phase D gherkin verification + CHECKPOINTS.md C1-C5.
   No arrancar nueva story hasta state=done de esta.)

✅ Story {story-id} all tickets pushed.
Story state: developing → developed.
defer_audit: true (razón: "{defer_audit_reason}", ratified_by: {defer_audit_ratified_by})

⏸  AUDIT DEFERRED.

  /pm-{brand} bootstrap pingeará esta deuda en cada sesión futura hasta
  resolución. Cuando Chris quiera reanudar, dice "audita {story-id}" y
  /auditor toma el handoff con full context del defer.

❌ NUNCA: cerrar state=developed + pickup ticket de otra story en el mismo worktree.
   Layer 2 enforcement: si Step 0.4 detecta otra story abierta sin defer_audit,
   REFUSE pickup. Si esta story (la actual) acaba de cerrar developed, ANTES
   de cualquier nueva story el worktree debe llegar a state=done (auditor → merge → archive).

WS=$(git rev-parse --show-toplevel)
python3 ${WS}/scripts/emit_process_metric.py \
  --brand "{brand}" \
  --story "{story-id}" \
  --ticket "T-{n}" \
  --phase build \
  --agent-type "<builder-backend|builder-agentic|builder-frontend|qwen-opencode>" \
  --verdict "<tests-passing|tests-failing|pushed|blocked>" \
  --commit-sha "$(git log -1 --format=%h)" \
  --total-tokens "<from agent tool result if visible, else omit>" \
  --tool-use-count "<from agent tool result if visible, else omit>" \
  --duration-ms "<wall-clock ms agent ran, else omit>" \
  --iter <N> \
  --note "<1-line context if relevant>"

# docs/product/stories/{story-id}/checkpoint.md
brand: {brand}     # ★ REQUIRED — single-project scope
state: blocked     # NOT review — autonomous failed
phase: BUILD_T{n}_BLOCKED
last_artifact: T-{n}-impl-log.md
next_action: "Chris reviews iteration_log to decide: refine validators / refine guidelines / split ticket / restart"

Story {id} ticket T-{n} BLOCKED — autonomous loop cap reached (10 iter).

Last error trace (verbatim):
---
{paste last validator failure}
---

iteration_log summary:
- Iter 1-3: implementation phase, RED on validator X
- Iter 4-6: refactor approach Y, still RED
- Iter 7-10: edge case Z not handled by guidelines

Story state: developing → blocked.

Próximo: Chris reviews docs/product/stories/{story-id}/T-{n}-impl-log.md →
decide:
- Refine 04-validators.yaml (validator was wrong)
- Refine 05-guidelines.md (missing pattern guidance)
- Split T-{n} (too large)
- Restart with different approach