workspace-template

Convierte cualquier proyecto en un workspace de Claude Code con flujo de trabajo profesional listo para usar.

npx workspace-template

Sin clonar, sin configurar nada antes.

Qué te da

• Flujo work-item / tasks: planifica, implementa y lanzas PRs siguiendo un patrón estándar (estilo Linear / Vercel).
• Skills de Claude Code: comandos como /init, /plan, /apply, /build, /review que automatizan el ciclo completo.
• Modelo de branches: main + dev (obligatoria) + staging (opcional), creadas y normalizadas por el CLI.
• Integración con GitHub: issues, sub-issues nativos, PRs, GitHub Projects — todo conectado.
• Conventional Commits + drift detection automático contra dev.
• Single-repo o orchestrator indistintamente. El orchestrator es un repo coordinador que gestiona N repos satélites desde GitHub (con repos.yaml, bootstrap.sh, Makefile).
• Hook no-edit-without-plan enforcado por Claude Code: bloquea Edit en dev/main sin work-item planificado.

Inicio rápido

Sin Node.js instalado:

curl -fsSL https://raw.githubusercontent.com/Dev3ch/workspace_template/main/setup.sh | bash

Con Node.js:

npx workspace-template

El CLI te guía paso a paso (en español).

Cómo funciona — en 30 segundos

Hay tres niveles de uso. Empieza por el básico.

Flujo básico (el 80% del tiempo)

/init  →  /plan  →  /apply  →  /build  →  (review en GitHub)  →  merge

• /init — arranca la sesión. Te pone en dev, lista tus work-items pendientes y te pregunta qué quieres hacer.
• /plan — propone un work-item (feature / refactor / fix / chore) con sus tasks. Pide confirmación antes de crear nada en GitHub.
• /apply — implementa la task activa, corre tests.
• /build — commit + push (con tu confirmación) por cada task. Cuando todas las tasks del work-item están cerradas, abre un solo PR hacia dev.

Tras el merge, /build cierra el work-item, sus tasks colgantes y limpia la rama — todo automático. Para la siguiente sesión arrancas con /init de nuevo.

Conversacional: no necesitas escribir los slash commands literalmente. Si dices "planifiquemos un sistema de notificaciones" o "vamos a aplicar la siguiente task", Claude interpreta y avanza solo.

Ejemplo real paso a paso

Escenario: agregar un endpoint GET /users con paginación.

/init

Claude: Encontré 3 issues abiertos: #8 fix login, #9 add pagination, #11 refactor auth. ¿Trabajamos sobre alguno o tienes algo nuevo?

User: Tengo algo nuevo.

/plan

User: Quiero un endpoint GET /users con paginación.

Claude: Voy a crear en GitHub:

• Work-item padre: feat: paginated users endpoint
• Sub-issue #1: Crear ruta GET /users?page&limit
• Sub-issue #2: Query con offset a la DB
• Sub-issue #3: Respuesta { data, total, page }

¿Creo estos issues?

User: Sí.

Claude crea el work-item #15 y los sub-issues #16, #17, #18 en GitHub.

/apply

Claude: ¿Aplico el plan? Cada sub-issue será un commit.

User: Sí.

Claude implementa #16 → commit feat: add GET /users route Claude implementa #17 → commit feat: db query with pagination Claude implementa #18 → commit feat: paginated response format

Claude: 3 commits listos en rama feature/15-paginated-users. ¿Corro el build?

/build

User: Sí.

Claude corre npm run test

Claude: ✓ 24 tests pasando. ¿Abro el PR hacia dev?

User: Sí.

Claude crea PR #19: feat: GET /users with pagination → dev, closes #16 #17 #18, linked a #15.

Claude: PR listo → #19. ¿Cómo quieres cerrar este PR?

1. Dejar para review del equipo  (default)
2. Mergearlo yo mismo ahora      (squash + delete branch)
3. Auto-merge cuando pasen los checks
4. Asignar reviewer específico

User: 1, déjalo para review.

Claude: Hecho. Tu trabajo aquí terminó. Cuando otra persona apruebe y mergee, en la próxima /init cierro el work-item, las tasks colgantes y te ofrezco borrar la rama.

Review en GitHub → merge a dev ✓

Próxima /init o /build (post-merge):

Claude detecta que PR #19 fue mergeado.

Claude:

• Cerré work-item #15 y tasks #16 #17 #18 referenciando el merge.
• Quité los labels in-progress y review.
• ¿Borro la rama local y remota feature/15-paginated-users?

User: Sí.

Rama eliminada. Board limpio. ✓

Segundo ejemplo: drift contra dev en mitad del trabajo

Caso menos obvio: estás en una rama de feature, pero en dev se mergeó algo después de que arrancaste. /apply o /build lo detectan antes de dejarte commitear.

Estás en feature/15-paginated-users, vas por la task #17.

/apply

Claude: Antes de implementar — detecté que dev tiene 4 commits nuevos que no están en tu rama:

feat(auth): refresh token rotation
fix(users): null check en serializer
chore(deps): bump fastapi 0.115
refactor(db): pool de conexiones

Tu rama puede tener conflictos al abrir el PR. Opciones:

1. Rebasear contra dev ahora               (recomendado si los cambios son de tu zona)
2. Mergear dev en tu rama                  (preserva commits originales, deja merge commit)
3. Continuar y resolver al abrir el PR     (más riesgoso)
4. Cancelar y revisar manualmente

User: 1.

Claude rebasea. Hay conflicto en apps/users/serializer.py.

Claude: Conflicto en apps/users/serializer.py:42. El cambio de fix(users): null check toca el mismo serializer que tu task. ¿Lo resuelvo?

1. Ver el diff y resolver con tu input
2. Quedarte con dev y reescribir tu cambio encima  (riesgo: pierdes lógica)
3. Quedarte con tu rama y rechazar el cambio de dev (riesgo: regresión del fix)
4. Cancelar el rebase

User: 1.

Claude muestra ambos lados, propone fusión que mantiene el null check + tu paginación, espera OK.

User: Aplica.

Rebase completo, sin conflictos pendientes. Tests siguen verdes.

Claude: Rebase OK. Ahora sí, ¿implemento la task #17?

Esto es lo que hace que el flujo no se rompa cuando trabajas en paralelo con un equipo: drift detection automático en /init, /apply y /build, y nunca usa reset --hard para resolver. El detalle del flujo completo y todos los comandos están en docs/flujo-arquitectura.md.

¿Y si quiero pasar esto a producción?

Una vez que está en dev y quieres pase a producción, el flujo es /secure → /deploy. Si producción ya existe y está sana, /deploy lo detecta y no reconfigura nada — solo confirma. Si es la primera vez, crea un work-item con tasks por componente (Dockerfile, workflow, secrets, primer deploy) que trabajas con /apply como cualquier otro work-item.

Ver docs/flujo-arquitectura.md para el detalle.

Comandos disponibles

| Etapa | Comando | Para qué | |---|---|---| | Arrancar | /init | Lee estado, work-items activos, sincroniza con dev | | Planificar | /plan | Crea work-item (feature / refactor / fix / chore) + tasks | | Implementar | /apply | Trabaja la task activa, corre tests | | Guardar | /build | Commit + push + abre PR cuando todas las tasks cierran | | Revisar | /review | Code review del PR antes de mergear | | Pre-deploy | /secure | Checklist bloqueante; crea work-item con tasks si hay bloqueantes | | Deploy | /deploy | Diagnóstico + setup; crea work-item con tasks por componente |

Comandos de soporte: /branches, /sync, /cross, /audit, /pentest, /triage, /design, /setup, /debug, /rollback, /test, /tools.

Diagrama del flujo completo, modelo de trabajo y reglas detalladas → docs/flujo-arquitectura.md.

Single-repo vs Orchestrator

Dos modos. El CLI te pregunta cuál querés al inicio.

Single-repo

Un solo repositorio. Tres caminos: ya en GitHub, carpeta local, desde cero (clona template del stack). El flujo /init → /plan → /apply → /build corre dentro de ese repo. Es el caso del 80% de proyectos.

Orchestrator

Un repo coordinador (miapp-orchestrator o como lo nombres) que gestiona N repos satélites que ya existen en GitHub. Pasás las URLs de los satélites al CLI y se genera:

miapp-orchestrator/
  ├── .git/                ← el orchestrator es un repo en GitHub
  ├── CLAUDE.md            ← descripción del conjunto
  ├── .claude/             ← skills, rules, hook
  ├── repos.yaml           ← lista declarativa de satélites (NO es Docker Compose)
  ├── bootstrap.sh         ← script para clonar los satélites
  ├── Makefile             ← targets: bootstrap, up, down, <repo>
  ├── .gitignore           ← bloque managed que excluye los satélites
  ├── frontend/            ← clonado por bootstrap.sh, NO se commitea
  ├── api/                 ← idem
  └── worker/              ← idem

Flujo:

1. npx workspace-template → elegís orchestrator. Pegás N URLs de satélites.
2. Para cada satélite: el CLI detecta si tiene .claude/ y, si NO lo tiene, inyecta automáticamente la plantilla single (skills, rules, hook). Si SÍ lo tiene, lo actualiza.
3. Se genera repos.yaml con name, url, stack, port, runCommand por satélite.
4. Se asignan puertos del rango efímero (39100 backends, 39200 frontends — no chocan con 3000/8000/etc.).
5. Los satélites quedan en .gitignore: cada uno mantiene su propio .git y su propio remote, el orchestrator no los commitea.

Onboarding de un dev nuevo:

git clone <url-orchestrator>
cd miapp-orchestrator
bash bootstrap.sh           # clona los N satélites
make help                   # lista los comandos disponibles
make api                    # corre solo el satélite api
make up                     # corre todos los satélites en paralelo

Personalización: repos.yaml es del usuario (puede agregar/cambiar satélites a mano). bootstrap.sh y Makefile son del template (se regeneran al hacer update leyendo el repos.yaml actual). .gitignore tiene un bloque managed (entre marcadores # >>> orchestrator-managed) que se actualiza; lo que tengas afuera del bloque queda intacto.

Actualizar un workspace existente

npx workspace-template update

Compara hash por hash skills, rules y scripts contra el paquete actual. Marca cada cambio:

| Símbolo | Significa | |---|---| | + | Nuevo en el template, no estaba en tu workspace | | ~ | Actualizado upstream, sin cambios locales tuyos | | ! | Actualizado upstream pero tienes cambios locales (default unchecked) | | - | Obsoleto, ya no existe en el template (default checked = se elimina) | | × | Lo borraste localmente — no se reinstala salvo que lo marques explícitamente |

Eliges qué aplicar. Tus cambios locales se respetan por defecto:

• Si modificaste un skill localmente, el update no lo sobrescribe a menos que lo elijas.
• Si borraste un archivo del template a propósito (porque no lo usabas), el update no lo trae de vuelta. Aparece marcado con × para que lo recuperes solo si lo decides.
• Si añadiste skills/rules tuyos que no son del template, el updater no los toca ni los lista.

Stacks soportados

Next.js / React, Vue / Nuxt, Django, FastAPI, React Native, Flutter, Go, o cualquier otro como texto libre. Si el repo tiene manifest detectable (package.json, pyproject.toml, go.mod, etc.), el CLI lo detecta automáticamente. Si no, no te pregunta por stack — sirve igual para repos de configuración o agentes.

Integraciones MCP

Notion, Linear, Slack, Sentry, Postgres, Context7, n8n. La config queda en .claude/settings.json.

Requisitos

• Node.js 18+ (recomendado: 22 LTS)
• git y gh (GitHub CLI)

El CLI detecta lo que falta y muestra el comando de instalación según tu OS.

Más

• docs/flujo-arquitectura.md — diagrama completo, modelo work-item + tasks, reglas del flujo
• docs/flujo-autenticacion.md — cómo el CLI resuelve credenciales
• CHANGELOG.md — todas las versiones y cambios

Licencia

MIT