Empezar.md
Conceptos
| Concepto | Qué es |
|---|---|
| Empresa | El cliente. Tiene miembros, proyectos, instalaciones de GitHub y su propio harness. Una persona puede pertenecer a varias empresas. |
| Proyecto | Lo que se construye. Agrupa repos, specs, backlog, harness y nivel de autonomía. |
| Repositorio | Una carpeta de código del proyecto en GitHub (front, back, infra…). Tiene rama de integración (develop) y de producción (main). |
| Casa de las specs | El repo donde vive specs/ de SpecKit para ese proyecto. |
| Spec | Una feature de SpecKit: spec.md (qué y por qué), plan.md (cómo) y tasks.md (tareas). |
| Harness | Las reglas que siguen tus agentes en un proyecto: estándares (AGENTS.md), comandos y qué decisiones exigen a una persona. |
| Agente | Claude Code, Codex u otro agente con acceso al CLI, que corre en la máquina de un desarrollador con su propia suscripción. |
| Fase / ola | Una fase es un hito con valor (MVP, v1…). Una ola es un grupo de tareas sin archivos compartidos que pueden correr en paralelo. |
| Clasificación de tarea | Cada tarea tiene un área (docs, ui, api, core, data, infra, security), una talla (XS–XL) y un riesgo (R0–R3). El riesgo decide cuánta documentación, revisión y aprobación necesita. |
| Subagente | Ayudante efímero que lanza un agente: explorer (lee), verifier (corre los checks), reviewer y challenger (revisión adversarial). |
| Reporte | Salida estructurada que un agente envía a ZPX Forge (spec, plan, avance, revisión, bloqueo, entrega). Las personas lo leen como vista, no como archivo. |
| Aprobación | Una decisión que exige a una persona: spec, arquitectura, acción riesgosa o pase a producción. |
El ciclo de una feature
Alcance → spec.md → aprobación (PM/PO) → plan.md + tasks.md → backlog
→ un dev toma una tarea → su agente trabaja en una worktree y una rama
→ PR a develop → revisión → release aprobado → main = producción
Ramas
| Rama | Para qué | Quién la cambia |
|---|---|---|
main | Producción | Solo por PR de release aprobado |
develop | Integración / staging | Por PR desde ramas de tarea |
feat/<tarea>-… | Una tarea, vida corta | El dev y su agente |
Evidencia y decisiones
Lo declarado es un reporte del equipo. Lo observado incluye el resultado que Forge consulta en GitHub para el commit y la prueba acordados. Un riesgo aceptado registra el motivo y quién lo asume. El responsable de la entrega decide si comparte la ficha. El cliente decide si acepta esa versión.