# Horux Despachos — Índice del proyecto

Este documento es el punto de entrada para cualquier sesión de trabajo en el pivote "Horux Despachos". Empieza aquí.

**Producto:** SaaS para despachos contables mexicanos (MVP), extensible a otras verticales profesionales (jurídica, arquitectura).
**Base de código:** fork de Horux360 en esta carpeta.
**Estado:** diseño aprobado, Plan 1 listo para ejecución, Planes 2-8 pendientes de brainstorm.
**Fecha inicio:** 2026-04-16.

---

## Lo primero que debes leer

1. **[Spec de diseño](specs/2026-04-16-horux-despachos-design.md)** — 16 secciones, decisiones arquitectónicas, modelo de datos, flujos, riesgos, roadmap de fases. Fuente de verdad para qué se construye.

2. **[Plan 1 — Refactor preparatorio del monorepo](plans/2026-04-16-refactor-monorepo-packages.md)** — 20 tasks, ~100 steps. Se ejecuta primero porque desbloquea todas las fases siguientes.

---

## Roadmap de 8 planes

Cada plan se construye sobre los anteriores. Cada uno pasa por su propio ciclo brainstorm → spec → plan → ejecución con la skill apropiada.

| # | Plan | Estado | Estimado | Spec | Plan |
|---|------|--------|----------|------|------|
| **1** | **Refactor preparatorio del monorepo** | ✅ Plan listo | 1-2 sem | Ver spec §13 | [Plan 1](plans/2026-04-16-refactor-monorepo-packages.md) |
| 2 | Cimientos de Despachos | ⏳ Pendiente | 3-4 sem | Pendiente | Pendiente |
| 3 | Roles y carteras | ⏳ Pendiente | 2 sem | Pendiente | Pendiente |
| 4 | Pricing y pagos | ⏳ Pendiente | 2-3 sem | Pendiente | Pendiente |
| 5 | Connector BYO-DB | ⏳ Pendiente | 2 sem | Pendiente | Pendiente |
| 6 | Admin global + dashboard cross-despacho | ⏳ Pendiente | 2 sem | Pendiente | Pendiente |
| 7 | Métricas pre-calculadas | ⏳ Pendiente | 2 sem | Pendiente | Pendiente |
| 8 | Polish + launch privado | ⏳ Pendiente | 1-2 sem | Pendiente | Pendiente |

**Total estimado:** 15-19 semanas hasta launch privado.

Detalle de alcance de cada plan en el spec §15.

---

## Cómo arrancar la próxima sesión

### Si vas a ejecutar el Plan 1 (refactor):

1. Verifica estado del repo:
   ```bash
   cd /c/Users/chtr1/Downloads/Horux_despacho
   git status
   git log --oneline -5
   ```

2. Asegura deps instaladas:
   ```bash
   pnpm install
   pnpm -r typecheck   # baseline sin errores antes de empezar
   ```

3. Invoca la skill de ejecución:
   - **Recomendada:** `superpowers:subagent-driven-development` — fresh subagent por task, review entre tasks, contexto limpio.
   - **Alternativa:** `superpowers:executing-plans` — ejecución inline con checkpoints.

4. Apunta la skill al plan:
   - Path: `docs/superpowers/plans/2026-04-16-refactor-monorepo-packages.md`

5. Commits locales frecuentes (uno por task); **NO hacer `git push`** (no hay remote todavía).

### Si vas a brainstormear el siguiente plan (Plan 2):

1. Leer el spec completo (ya aprobado — no re-brainstorm decisiones ya cerradas).
2. Invocar `superpowers:brainstorming` con contexto: "brainstorm Plan 2 — Cimientos de Despachos: BD Central (Prisma), BD Tenant (migrations core + vertical contable), auth con despachoId, signup → trial → agregar contribuyente → FIEL/CSD → primera emisión CFDI."
3. El brainstorm genera un spec propio en `specs/` y termina en writing-plans que escribe el Plan 2 en `plans/`.

---

## Decisiones cerradas (no re-brainstorm)

Estas decisiones están aprobadas en el spec y NO deben revisarse salvo nueva evidencia:

- **Hosting:** Opción A (SaaS central + BYO-DB / Managed).
- **Tiers BD:** dos tiers (BYO barato, Managed premium).
- **Roles despacho:** Owner / Supervisor / Auxiliar / Cliente.
- **Carteras:** jerárquicas con cascada; Owner = Supervisor implícito.
- **Facturapi:** cuenta maestra Horux broker; 1 org por contribuyente; pool único timbres por despacho.
- **Connector:** Cloudflare Tunnel + Docker `horux/connector`.
- **Pricing:** tiers fijos + add-ons + paquetes one-shot.
- **Monorepo:** unificado, refactor preparatorio a `packages/core`, `packages/vertical-contable`, `packages/shared-ui`.
- **Admins globales:** impersonación con motivo + audit + dashboard cross-despacho.
- **Clientes-visores:** password + magic link + multi-RFC + multi-despacho.
- **Multi-vertical:** arquitectura preparada desde MVP.
- **Métricas:** hot/cold con drill-down + formula_version + invalidación dirigida.

---

## Archivos del directorio

```
docs/superpowers/
├── INDEX.md                                                    ← este archivo
├── specs/
│   └── 2026-04-16-horux-despachos-design.md                    ← spec completo
└── plans/
    └── 2026-04-16-refactor-monorepo-packages.md                ← Plan 1
```

Los Planes 2-8 agregarán specs y plans a sus respectivas carpetas conforme se vayan brainstormeando.

---

## Convenciones del proyecto

- **Disciplina TS:** `pnpm typecheck` tras cada cambio relevante. CI/guardrail local.
- **Tests:** Plan 1 NO agrega framework de tests (eso es proyecto aparte); valida con typecheck + smoke test manual.
- **Git:** commits locales por task; sin push (no hay remote); no `--amend` sobre commits existentes; no `--no-verify`.
- **Working directory único:** todo en `Downloads/Horux_despacho`. El repo de Horux360 en OneDrive NO se toca para este pivote.
- **Convenciones Prisma:** modelos en PascalCase, campos camelCase; relaciones explícitas con `@relation`.
- **Convenciones SQL (BD tenant):** snake_case, FK NOT NULL donde aplica, índices sobre `contribuyente_id` en todas las tablas verticales.