# ZPX Forge Cuando un equipo construye software con Claude o Codex, su cliente necesita saber qué se acordó y qué se entregó. Forge conserva la revisión de alcance aceptada, consulta la ejecución de GitHub para el commit entregado y registra la decisión de la persona designada. Puedes empezar desde una idea o conectar un repositorio. Antes de construir, define el primer resultado que pueda probar tu cliente. Durante el desarrollo, el equipo consulta el plan, comunica bloqueos y registra lo probado. En la entrega, el cliente puede abrir la evidencia y aceptar la versión o pedir una corrección. Abre el [inicio rápido](/es/docs/inicio-rapido) para crear tu proyecto. Para incorporar tu agente, copia las [Instrucciones para Claude o Codex](/es/docs/instrucciones-agente). --- # Inicio rápido ## 1. Crea tu cuenta Abre [Crear cuenta](/signup) y elige **Continuar con GitHub**. Usa una cuenta de GitHub con correo verificado. Si recibiste una invitación, entra con la cuenta asociada al correo invitado. ## 2. Registra tu empresa En el onboarding escribe el nombre de la empresa y para qué usarán ZPX Forge. Tu empresa queda activa de inmediato. ## 3. Conecta GitHub En **GitHub → Instalar en GitHub** eliges la cuenta u organización y los repos que ZPX Forge puede ver. Al volver, la instalación queda vinculada a tu empresa. > Para instalarla debes administrar esa cuenta en GitHub. Es la forma de evitar que alguien vincule > repos que no le pertenecen. ## 4. Crea un proyecto y agrega sus carpetas de código Un proyecto puede tener uno o varios repos: `front`, `back`, un monorepo `app`… Uno de ellos es la **casa de las specs** (donde vive `specs/` de SpecKit). Con Pro puedes elegir **Partir de un proyecto base** en el paso de arquitectura. Al crear el proyecto, la ficha incluye el diseño, la primera entrega sugerida, su prueba de aceptación y las señales que conviene medir. Claude o Codex consulta ese mismo diseño con `zpx context --json`. ## 5. Protege las ramas En cada repo del proyecto, **Proteger develop y main** crea una regla en GitHub: esas ramas solo cambian por pull request, sin borrado ni *force-push*. ## 6. Invita a tu equipo Con Pro, en **Equipo** invitas por correo con un rol. Cada persona puede tener además un rol distinto en un proyecto concreto. Desde aquí, cada push, PR y check de tus repos aparece en la actividad del proyecto. ## Respaldo de entrega con Pro En Proyecto → Hitos, acuerda un resultado con la persona que va a recibirlo. Selecciona el repositorio, el workflow, el archivo de prueba y los nombres exactos del job y del paso. El workflow debe ejecutar la prueba acordada en un push a la rama de producción. Consulta CI en GitHub desde el hito. Si falta la ejecución de ese commit, la evidencia sigue pendiente. Desde el hito comprobado, crea la entrega, revisa los riesgos y comparte la ficha aprobada. La persona designada acepta esa versión o pide correcciones en su ficha privada. Para acompañar este recorrido con tu agente, abre [Instrucciones para Claude o Codex](/es/docs/instrucciones-agente). ## Ejemplo de prueba de aceptación en GitHub Actions Para un proyecto Python con una prueba de aislamiento en unittest, este workflow ejecuta un caso concreto. Sustituye la rama, el módulo y el método por los de tu proyecto e instala sus dependencias antes del paso de prueba. Confirma con el cliente qué comportamiento demuestra el caso. ```yaml name: Acceptance on: push: branches: [main] jobs: acceptance: name: Customer acceptance runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: "3.12" - name: Verify customer isolation run: python -m unittest tests.test_isolation.IsolationTest.test_other_customer_cannot_read ``` Guarda el workflow en `.github/workflows/acceptance.yml`. En el hito selecciona ese workflow, `tests/test_isolation.py`, job `Customer acceptance` y paso `Verify customer isolation`. El resultado solo está observado cuando Forge encuentra la ejecución del commit y del paso acordados. ## Activa Pro Individual permite una empresa y hasta dos proyectos de uso personal. Pro cuesta US$10 por miembro y incluye empresas, proyectos y miembros sin límite, feedback del equipo y respaldo de entrega con evidencia de CI. Inicia sesión y abre Inicio de la empresa para consultar las condiciones y activar Pro. --- # 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/-…` | 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. --- # Empresas y roles ## Registro de empresa Cualquier persona con una cuenta de GitHub y un correo verificado puede registrar una empresa. Se activa al crearla. Quien la registra es su primer **admin**. Una empresa nunca puede quedarse sin admin. ## Roles de empresa | Rol | Hace | |---|---| | Admin de empresa | Miembros, invitaciones, GitHub y configuración | | Product Owner | Visión, prioridades, aprueba specs y releases | | Project manager | Backlog, asignaciones, aprueba specs | | Líder técnico | Arquitectura, repos, harness, acciones riesgosas | | Desarrollador | Toma tareas y trabaja con su agente | | Revisor | Revisa pull requests | | QA | Valida en staging | | Observador | Solo ve el avance (por ejemplo, el cliente final) | ## Roles por proyecto Cada persona tiene un rol en la empresa y, opcionalmente, **otro rol en un proyecto concreto**. Un desarrollador puede ser líder técnico de un proyecto sin serlo en los demás. ## Permisos actuales | Acción | Roles | |---|---| | Administrar la empresa (miembros, invitaciones, GitHub, auditoría) | Admin | | Crear proyectos | Admin, Product Owner, Líder técnico | | Ajustar roles en un proyecto | Admin, Product Owner, Líder técnico | | Conectar repos y proteger ramas | Admin, Líder técnico | | Ver la empresa y sus proyectos | Todos los miembros | ## Invitaciones Con Pro, los administradores invitan a los miembros por correo. Las invitaciones incluyen un rol y vencen en 7 días. El enlace también se puede copiar y compartir. ## Aislamiento Quien no pertenece a una empresa recibe *no encontrada* en todo: ni siquiera puede saber que existe. ## Cliente externo de un hito El editor puede designar al cliente por correo electrónico sin invitarlo como miembro de la empresa. Con su correo verificado y el enlace privado, puede revisar el alcance y decidir sobre su entrega. Para compartir una ficha de solo lectura, usa el enlace público de la versión aprobada. --- # GitHub ZPX Forge se conecta a GitHub con una **GitHub App** que cada empresa instala en su cuenta u organización, eligiendo qué repos puede ver. ## Instalación verificada Al volver de GitHub, la instalación solo se vincula si: 1. la inició esa misma persona, para esa empresa; 2. es admin de la empresa en ZPX Forge; 3. controla la cuenta de GitHub: es la suya o es admin de la organización. Una instalación pertenece a una sola empresa. ## Permisos que pide la app | Permiso | Para qué | |---|---| | Contents · lectura y escritura | Leer `specs/`; proponer specs con pull requests | | Pull requests · lectura y escritura | Seguir y abrir PRs | | Checks y statuses · lectura y escritura | Consultar o publicar checks según la configuración | | Deployments · escritura | Autorizar o rechazar el commit en el entorno de producción protegido con Forge Pro | | Actions · lectura | Ver ejecuciones de CI | | Administration · lectura y escritura | Proteger `main` y `develop` (opcional) | | Members · lectura | Relacionar miembros de la organización | ## Protección de ramas Desde un proyecto, **Proteger develop y main** crea en el repo un *ruleset* `ZPX Forge · ramas protegidas`: cambios solo por pull request, sin borrado ni *force-push*. Si ya existe, lo actualiza. ## Webhooks y actividad Cada entrega se verifica con su firma (`X-Hub-Signature-256`), se guarda una sola vez aunque GitHub la reintente y se procesa en segundo plano. Se convierte en actividad del proyecto: | Evento de GitHub | Actividad | |---|---| | `push` | `push` (marca si cambió `specs/`) | | `pull_request` | `pr.opened`, `pr.merged`, `pr.closed`, `pr.reopened` | | `check_suite` fallido | `check.failed` | | `workflow_run` fallido | `ci.failed` | | `installation`, `installation_repositories` | Sincroniza instalaciones y repos | --- # Trabaja conmigo en ZPX Forge Trabaja desde el repositorio con mi agente y mi suscripción. Usa Forge para consultar el acuerdo con el cliente, coordinar tareas y dejar constancia de la entrega. El equipo comparte ese historial aunque cambie de agente o de sesión. Respeta el alcance que te autorizo en este chat. ## Identifica el proyecto 1. Ejecuta `zpx version` y `zpx doctor --json`. Si falta el CLI, la persona puede instalarlo con `uv tool install zpx` o actualizarlo con `uv tool upgrade zpx`. 2. Si falta acceso, pídeme que habilite Reportes del CLI en Equipo → perfil y autorice `zpx login` en mi navegador con mi cuenta de GitHub. Conserva las credenciales en mi máquina. 3. Usa `zpx whoami` y `zpx projects` para identificar mi cuenta y proyecto. Cuando el destino esté confirmado, vincula este directorio con `zpx use EMPRESA/PROYECTO --here`. Sustituye los identificadores de ejemplo por los reales. 4. Lee `zpx context --json`. Comprueba el proyecto, tus responsabilidades, el plan y los hitos en `milestones`. Con autorización para configurar este repo, ejecuta `zpx skill install` y lee el AGENTS.md y las skills instaladas. Si `harness.sync.required` indica cambios, sincroniza y comprueba el contexto de nuevo. Consulta conmigo cualquier conflicto con archivos editados localmente. ## Antes de construir Desde una idea, ayúdame a escribir el primer resultado que pueda demostrar al cliente. Desde un repositorio existente, con el CLI 0.2.4 puedes usar `zpx audit --json` para identificar archivos de entorno versionados y workflows de GitHub Actions en el índice local. Este diagnóstico solo examina nombres de archivos. En Proyecto → Hitos, el editor propone un criterio comprobable, cómo demostrarlo, exclusiones, fecha y quién decide. Esa persona recibe una ficha privada y acepta la revisión o pide cambios. Trabaja contra la última revisión aceptada. Si cambia la promesa, propón otra revisión. ## Durante el trabajo Lee `zpx today` y `zpx plan`. Abre la tarea real con `zpx task show T003`. Cuando la persona confirme la asignación, usa `zpx task take T003` y `zpx task start T003 --agent codex --branch mi-rama` con el agente y la rama reales. Registra avances con `zpx task progress T003 "resultado comprobado"`. Añade `--check tests=pass` solo después de ejecutar esas pruebas. Anota el commit probado y los pendientes. Usa `zpx task blocked T003 "motivo"` ante un bloqueo. Consulta `zpx can-publish RAMA` antes de publicar y respeta la autorización de la persona. Omite credenciales y datos del cliente en reportes. ## Respaldo de entrega y aceptación (Pro) En el hito, vincula el repositorio y el workflow de push de la rama de producción con el archivo de prueba y los nombres exactos del job y el paso. Un revisor comprueba que esa prueba cubre el criterio. Forge consulta GitHub para ese commit. Cada nuevo commit necesita su ejecución. Cambiar el workflow o la prueba acordados requiere renovar el acuerdo. Distingue lo **declarado** por el equipo de lo **observado** por Forge en GitHub. Un **riesgo aceptado** identifica a quien lo asume y su motivo. Cuando falte CI, indícalo como pendiente. Desde el hito comprobado, quien tiene permiso crea la entrega. Su responsable decide si publica la ficha de solo lectura, vigente durante 30 días. El cliente designado entra con su correo verificado en la ficha privada para aceptar esa versión o pedir correcciones. Dime qué versión y commit se entregaron, qué evidencia puedo abrir y de quién depende la próxima decisión. Para ayuda contextual usa `zpx help`, `zpx guide hito` y `zpx guide evidencia`. Consulta la documentación completa en https://www.zpxforge.com/es/llms-full.txt. --- # Construye con IA Abre [Instrucciones para Claude o Codex](/es/docs/instrucciones-agente), pulsa **Copiar instrucciones para Claude o Codex** y pega el contenido en una sesión abierta en tu repositorio. Incluye el alta, la selección de proyecto, el uso del harness, las tareas y la aceptación. Usa `zpx doctor --json` para diagnosticar el entorno y `zpx help` para explorar los comandos. La documentación completa también está disponible en [Markdown](/es/llms-full.txt). --- # API La API vive en `https://zpxforge.com/api/v1`. La especificación completa (OpenAPI) está en [`/api/v1/docs`](/api/v1/docs). ## Autenticación Hoy la API usa la **sesión del navegador** (cookie `httpOnly`). Las peticiones que cambian datos deben venir del propio sitio (cabecera `Origin`). El CLI usa un token personal autorizado en el navegador para las rutas habilitadas. Las decisiones del cliente se realizan en su sesión web verificada. ## Endpoints | Método y ruta | Qué hace | |---|---| | `GET /v1/health` | Salud de la plataforma (base de datos, Redis, worker) | | `GET /v1/me` | La persona, sus empresas e invitaciones pendientes | | `GET /v1/roles` | Roles disponibles | | `POST /v1/orgs` | Registra una empresa | | `GET /v1/orgs/{empresa}` | Empresa, tu rol y tus permisos | | `GET /v1/orgs/{empresa}/members` | Miembros | | `PATCH /v1/orgs/{empresa}/members/{id}` | Cambia el rol de un miembro | | `POST /v1/orgs/{empresa}/invitations` | Invita por correo | | `GET /v1/orgs/{empresa}/projects` | Proyectos | | `POST /v1/orgs/{empresa}/projects` | Crea un proyecto | | `PUT /v1/orgs/{empresa}/projects/{p}/roles/{id}` | Rol de una persona en un proyecto | | `GET /v1/orgs/{empresa}/github` | Instalaciones y repos de GitHub | | `POST /v1/orgs/{empresa}/projects/{p}/repos` | Conecta un repo al proyecto | | `POST /v1/orgs/{empresa}/projects/{p}/repos/{id}/protect` | Protege `develop` y `main` | | `GET /v1/orgs/{empresa}/audit` | Auditoría (solo admins) | ## Errores ```json { "detail": "Tu rol no permite esta acción", "code": "forbidden" } ``` | Código HTTP | Significado | |---|---| | `401` | Falta iniciar sesión | | `403` | Sin permiso, empresa inactiva u origen no permitido | | `404` | No existe o no perteneces a esa empresa | | `409` | Conflicto (por ejemplo, el último admin) | | `429` | Demasiados intentos | --- # Seguridad ## Tu código ZPX Forge no almacena código. Los agentes trabajan en la máquina de cada desarrollador; la plataforma solo guarda metadatos (proyectos, tareas, eventos) y lo que GitHub expone a la app que instalas. ## Empresas aisladas Todo dato de negocio pertenece a una empresa y se consulta a partir de ella. Quien no es miembro recibe *no encontrada*. Hay pruebas automáticas que lo verifican en cada cambio. ## Cuentas El acceso a la web requiere GitHub y un correo verificado. Para aceptar una invitación o decidir sobre una entrega, usa la cuenta asociada al correo designado. Forge mantiene la sesión en una cookie protegida y comprueba el origen de las solicitudes que modifican datos. ## GitHub - La instalación se vincula solo si la persona controla la cuenta de GitHub. - Los webhooks se verifican con su firma y se procesan una sola vez. - La llave privada de la app nunca sale del servidor. ## Infraestructura ``` Navegador → zpxforge.com (Vercel) → balanceador AWS (HTTPS) → backend privado ``` El backend no tiene IP pública y solo acepta tráfico que pasó por Vercel, identificado con una llave compartida. ## Auditoría Cada acción relevante (registro, aprobaciones, invitaciones, roles, repos, GitHub) queda registrada con quién, cuándo y desde dónde. ## Fichas compartidas Quien tenga el enlace público puede consultar la instantánea durante su vigencia de 30 días o hasta su revocación. Para decidir sobre una entrega, el cliente externo abre el enlace privado con su cuenta de correo verificada y designada para ese hito. ## Auditoría de seguridad Pro Desde el repositorio de destino conectado a Forge, inicia sesión con `zpx login`, elige el proyecto con `zpx use empresa/proyecto` y ejecuta `zpx audit`. Usa `zpx audit --pdf informe.pdf` para guardar el PDF al registrar la revisión. El diagnóstico básico `zpx audit` sigue disponible sin cuenta. La revisión Pro analiza el último commit guardado en Git. Los cambios que solo están en tu editor quedan para la próxima revisión. Añade `--agent claude` o `--agent codex` para generar la lectura ejecutiva con el perfil de auditor de Forge. El cliente elegido recibe los totales, una muestra de hasta 15 hallazgos priorizados y hasta 10 límites de cobertura. Su interpretación queda identificada en el portal y en el PDF junto a las tablas de criticidad, evidencia y correcciones. La autorización sigue a cargo del responsable. El CLI 0.3.0 comprueba archivos de entorno versionados, workflows, indicios de ejecución dinámica en Python, mensajes privilegiados con contenido dinámico y llamadas HTTP sin tiempo límite. En JavaScript y TypeScript revisa la inserción de HTML, la evaluación dinámica y el acceso síncrono a archivos en funciones asíncronas. Lee las versiones públicas de npm y PyPI en `package-lock.json` y `uv.lock`, consulta sus nombres y versiones en OSV y señala paquetes npm marcados como obsoletos. Para las dependencias directas públicas compara la versión fijada con la vigente en su registro. En despliegues Kubernetes revisa límites de memoria y pruebas de disponibilidad. Forge recibe las rutas, evidencias resumidas y propuestas de corrección. El portal identifica esta fuente como **declarada por el equipo**. Una prueba de carga del servicio y una evaluación del comportamiento del modelo requieren evidencia adicional. Si tu aplicación usa plantillas de mensajes JSON, guarda la plantilla real con el sufijo `.prompt.json`. La comprobación local coloca un documento de muestra donde aparece `{{document}}` y verifica en qué rol termina. Un ejemplo de estructura compatible es `{"messages":[{"role":"system","content":"Resume el documento."},{"role":"user","content":"{{document}}"}]}`. El informe indica cuántas plantillas se comprobaron. En **Proyecto → Auditoría de seguridad** puedes descargar el PDF de cada versión. Cada hallazgo genera una propuesta de especificación. Quien tiene la responsabilidad de **Specs** puede marcar hallazgos individuales o usar **Seleccionar todas**. Al aprobar la selección, las tareas nuevas entran en la primera ola abierta. Si la ola ya está aprobada o en curso, la persona necesita también permiso para aprobar el plan. Si todas están cerradas, el responsable del plan debe elegir explícitamente dónde continuar. Una vez incorporadas las correcciones, repite `zpx audit`. La comparación indica qué apareció, qué persiste y qué dejó de detectarse. Una comprobación incompleta deja los resultados anteriores pendientes de verificar. En **Plan → Gestión del plan**, elige **Revisiones de seguridad** para consultar las correcciones históricas por estado. El historial de informes está en **Entregas → Auditoría de seguridad**. El responsable con permiso de decisión de entrega autoriza o bloquea la revisión más reciente del repositorio. Los riesgos altos, críticos o de severidad desconocida y las comprobaciones incompletas impiden autorizar. Cada nuevo informe requiere otra decisión, incluso sobre el mismo commit. ### Aplicar el control al despliegue real En GitHub, habilita la regla de protección de la aplicación ZPX Forge en el entorno de producción y configura el trabajo que despliega para utilizar ese entorno. La instalación necesita permiso de escritura en **Deployments** y la aplicación debe recibir el evento `deployment_protection_rule`. Cuando GitHub solicita autorización, Forge responde para el repositorio y el commit exactos. Tras un rechazo, corrige los hallazgos, registra y aprueba la nueva revisión y vuelve a ejecutar el despliegue. La protección externa depende de que el proveedor use ese entorno para desplegar. El mismo comando consulta la suscripción y tus permisos. Pro habilita el informe completo automáticamente. Individual recibe el diagnóstico básico. Si solicitas PDF o lectura con IA sin acceso, Forge explica que necesitas activar Pro.