Quickstart — Tu primera spec en 5 minutos

¡Bienvenido a Conductor! Sigue estos pasos para tener tu primera spec ejecutándose automáticamente.

Paso 1: Crea tu cuenta y proyecto

1. Ve a conductor.software y regístrate con Google o email
2. Haz clic en "Nuevo proyecto" — ponle el nombre de tu app
3. Conductor genera tu API key automáticamente (la necesitarás en el paso 3)

Paso 2: Conecta Claude.ai con Conductor (MCP)

Esto permite que puedas crear specs directamente hablando con Claude en claude.ai:

1. Ve a claude.ai → Settings → Integrations → Add MCP Server
2. Pega esta URL (la encuentras en tu proyecto → tab Config → Quick Start):

1. Ahora puedes decirle a Claude: "Crea una spec para agregar autenticación con Google" y se crea directamente en Conductor.

Paso 3: Instala el orquestador en tu proyecto

Abre una terminal en la raíz de tu proyecto y ejecuta el setup:

export CONDUCTOR_API_KEY=cnd_tu_api_key_aqui
bash <(curl -s https://conductor.software/api/scripts/setup)

Esto instala todo automáticamente:

• Skill /conductor para Claude Code CLI
• Orquestador (scripts/orchestrator.mjs)
• Git hook que trackea tus commits en Conductor

Paso 4: Crea tu primera spec

Puedes crear specs de 3 formas:

Desde Claude.ai (recomendado): Habla con Claude y dile qué quieres construir. El MCP crea la spec automáticamente.

Desde Claude Code CLI: En tu terminal, escribe /conductor y describe lo que necesitas.

Desde el dashboard web: Ve a tu proyecto → New Spec → elige un template o empieza en blanco.

Paso 5: Lanza el orquestador

IMPORTANTE: Ejecuta esto en una terminal aparte, no dentro de Claude Code.

# Ejecuta todas las specs pendientes
CONDUCTOR_API_KEY=cnd_tu_api_key node scripts/orchestrator.mjs --run --all

El orquestador:

1. Lee las specs "Por Hacer" de Conductor
2. Lanza Claude Code para ejecutar cada una
3. Verifica que el build pasa
4. Hace commit y push automáticamente
5. Marca la spec como completada

Paso 6: Ve el progreso

Ve a tu dashboard en conductor.software para ver en tiempo real:

• Qué spec se está ejecutando
• Tareas completadas
• Commits generados
• Logs de ejecución

Comandos útiles

# Ver qué specs hay pendientes sin ejecutar nada
CONDUCTOR_API_KEY=cnd_tu_key node scripts/orchestrator.mjs --dry-run

# Ver estado actual
CONDUCTOR_API_KEY=cnd_tu_key node scripts/orchestrator.mjs --status

# Ejecutar en background (para dejar corriendo toda la noche)
CONDUCTOR_API_KEY=cnd_tu_key nohup node scripts/orchestrator.mjs --run --all > .orchestrator/logs/run.log 2>&1 &

Pro tips

• Agrega CONDUCTOR_API_KEY=cnd_tu_key a tu .env.local para no tener que exportarla cada vez
• Cada commit que hagas (manual o del orquestador) se trackea automáticamente en Conductor
• Puedes crear specs desde Claude.ai y ejecutarlas desde tu terminal — no necesitas abrir el dashboard

Conceptos clave de Conductor

Proyecto

Un proyecto es el contenedor principal de tu trabajo. Corresponde a un repositorio de código.

• Tiene un nombre, descripción y stack tecnológico
• Genera una API key única para autenticar el orquestador
• Puede tener múltiples specs y miembros de equipo

Spec

Una spec (especificación) describe una feature, fix o mejora que quieres implementar.

• Tiene un título, descripción, prioridad y status
• Contiene tareas concretas y accionables
• El orquestador ejecuta las specs en orden de prioridad
• Statuses posibles: Por Hacer → En Progreso → Completado / Bloqueado

Tarea (Task)

Una tarea es un paso atómico dentro de una spec.

• Debe ser lo suficientemente pequeña para que Claude Code la ejecute de una vez
• Tiene un ID único que el orquestador usa para actualizar su status
• Statuses: Pendiente → En Progreso → Completado / Fallido

Orquestador

El orquestador es un script Node.js que:

1. Se conecta a la API de Conductor con tu API key
2. Descarga las specs pendientes
3. Para cada spec, lanza Claude Code con las instrucciones
4. Actualiza el status de tareas y specs en tiempo real
5. Hace commit de los cambios al finalizar cada spec

Logs

Cada ejecución del orquestador genera logs que puedes ver en tiempo real en tu dashboard. Incluyen:

• Qué spec/tarea se está ejecutando
• Output de Claude Code
• Errores y advertencias
• Tiempo de ejecución

Cómo escribir specs que Claude Code entiende

La calidad de tus specs determina directamente la calidad del código generado. Aquí van los principios y templates.

Principios fundamentales

✅ Sé específico sobre el QUÉ, no el CÓMO

✅ Una tarea = un cambio atómico

✅ Incluye contexto del stack

✅ Define criterios de aceptación

Template de spec

# [tipo]: [descripción corta]

**Prioridad:** Alta | Media | Baja

## Problema
¿Qué problema resuelve esta spec?

## Solución
¿Cómo lo vamos a resolver a alto nivel?

## Archivos a crear/modificar
- `src/components/LoginForm.tsx` — Formulario principal
- `src/app/api/auth/route.ts` — Endpoint de autenticación

## Tareas
### T1: [Título de la tarea]
Descripción detallada de lo que debe hacer Claude Code.
Incluir: archivos a tocar, lógica esperada, edge cases.

### T2: [Siguiente tarea]
...

## Criterios de aceptación
- Criterio 1
- Criterio 2

Ejemplos reales

Ejemplo 1: Feature de UI

# feat: tabla de specs con filtros y búsqueda

## Problema
La lista de specs crece y no hay forma de filtrar por status o buscar por título.

## Solución
Agregar barra de búsqueda + filtro de status encima de la tabla de specs.

## Tareas
### T1: Agregar barra de búsqueda
En `src/app/projects/[slug]/page.tsx`, agregar input de búsqueda
que filtre specs por título client-side. Usar estado local con useState.
Placeholder: "Buscar specs..."

### T2: Agregar filtro por status
Agregar dropdown/tabs para filtrar por: Todos, Por Hacer, En Progreso,
Completado, Bloqueado. Combinar con el filtro de búsqueda.

## Criterios
- Búsqueda en tiempo real (sin debounce necesario)
- Filtros se combinan (AND)
- URL no cambia al filtrar (client-side state)

Ejemplo 2: Fix de bug

# fix: el orquestador no actualiza status cuando falla una tarea

## Problema
Si Claude Code falla al ejecutar una tarea, el status queda en "En Progreso"
indefinidamente en lugar de marcarse como "Fallido".

## Tareas
### T1: Manejar errores en el loop de tareas
En `orchestrator.mjs`, envolver la ejecución de cada tarea en try/catch.
Si hay error: llamar PATCH /api/v1/tasks/[id] con status "Fallido" y
loguear el error con POST /api/v1/logs.

## Criterios
- Tasks fallidas muestran status "Fallido" en el dashboard
- El orquestador continúa con la siguiente spec tras un fallo

Orquestador — Instalación y configuración

El orquestador es el corazón del sistema. Conecta Conductor con Claude Code para ejecutar specs automáticamente.

Instalación rápida

En tu terminal (NO en Claude Code), ejecuta:

export CONDUCTOR_API_KEY=cnd_tu_api_key
bash <(curl -s https://conductor.software/api/scripts/setup)

Esto instala todo: orquestador, skill /conductor, MCP server, y git hooks.

¿No puedes usar terminal? Copia este prompt en Claude Code:

Comandos disponibles

# Ejecutar todas las specs pendientes
CONDUCTOR_API_KEY=cnd_tu_key node scripts/orchestrator.mjs --run --all

# Preview sin ejecutar
CONDUCTOR_API_KEY=cnd_tu_key node scripts/orchestrator.mjs --dry-run

# Ver estado actual
CONDUCTOR_API_KEY=cnd_tu_key node scripts/orchestrator.mjs --status

# Ejecutar 3 specs en paralelo (más rápido)
CONDUCTOR_API_KEY=cnd_tu_key node scripts/orchestrator.mjs --run --all --parallel 3

Ejecución en paralelo

El orquestador puede ejecutar múltiples specs simultáneamente:

node scripts/orchestrator.mjs --run --all --parallel 3

Crea una branch por cada spec, ejecuta en paralelo, y hace merge automático. Si hay conflicto, marca la spec como "En Revisión". Máximo 5 agentes paralelos.

También puedes configurarlo desde la UI: tu proyecto → Config → slider "Agentes paralelos".

Quality Gates

El orquestador verifica automáticamente antes de marcar una spec como completada:

1. Build — npm run build debe pasar
2. Lint — npm run lint (si existe) debe pasar
3. Tests — npm run test (si existe) debe pasar

Si algún gate falla, intenta auto-fix una vez. Si sigue fallando, marca la spec como "En Revisión".

Configura qué gates activar desde: tu proyecto → Config → Quality Gates.

Cómo funciona internamente

1. Consulta specs "Por Hacer" en Conductor
2. Las ordena por prioridad (Crítica > Alta > Media > Baja)
3. Para cada spec:
   • Marca como "En Progreso"
   • Descarga contenido + tareas
   • Lanza Claude Code con el prompt
   • Ejecuta quality gates
   • Si todo pasa: commit, push, marca "Completado"
   • Si falla: revierte cambios, marca "En Revisión"
4. Registra logs y duración/costo estimado

Troubleshooting

| Error | Solución | |-------|----------| | 401 Unauthorized | Verifica tu CONDUCTOR_API_KEY | | No specs found | Crea una spec con status "Por Hacer" | | ETIMEDOUT | Error de red temporal, el orquestador reintenta automáticamente (3 intentos) | | Build failed | Revisa el error en los logs del dashboard | | Claude Code timeout | Aumenta el timeout: SPEC_TIMEOUT=900000 (15 min) |

Ejecutar en background

# Dejar corriendo toda la noche
export CONDUCTOR_API_KEY=cnd_tu_key
nohup node scripts/orchestrator.mjs --run --all > .orchestrator/logs/run.log 2>&1 &

# Evitar que el Mac entre en reposo
caffeinate -s &

Ejecución automática sin PC encendido

Hay dos formas de ejecutar specs sin tener tu ordenador encendido.

Opción 1: Remote Triggers (Claude Max — $100/mes)

Los Remote Triggers crean un agente en la nube de Anthropic que revisa y ejecuta specs automáticamente. No necesitas tu PC encendido.

Cómo configurarlo

1. Abre Claude Code en cualquier terminal
2. Copia y pega este comando:

1. Claude Code te guiará para configurar el trigger
2. Listo — cada hora el agente revisa si hay specs nuevas y las ejecuta

Gestionar triggers

• Ver tus triggers: claude.ai/code/scheduled
• Pausar/activar: desde la misma página
• Ver logs de ejecución: en tu dashboard de Conductor

Requisitos

• Plan Claude Max ($100/mes) — incluye Remote Triggers
• Repo en GitHub (público o privado)
• MCP de Conductor conectado en tu cuenta de Claude

Opción 2: Dejar el Mac encendido (gratis)

Si no tienes Claude Max, puedes dejar tu Mac ejecutando el orquestador:

macOS

# Evitar que el Mac entre en reposo
caffeinate -s &

# Ejecutar el orquestador en background
export CONDUCTOR_API_KEY=cnd_tu_key
nohup node scripts/orchestrator.mjs --run --all > .orchestrator/logs/run.log 2>&1 &

También puedes ir a Ajustes del sistema → Pantalla de bloqueo y desactivar el reposo automático.

Windows

# En PowerShell como administrador
powercfg /change standby-timeout-ac 0

# Ejecutar el orquestador
set CONDUCTOR_API_KEY=cnd_tu_key
node scripts/orchestrator.mjs --run --all

VPS en la nube ($5/mes)

Para ejecución 24/7 sin depender de tu PC:

1. Alquila un VPS en Hetzner, DigitalOcean, o Railway (~$5/mes)
2. Instala Node.js y Claude Code
3. Clona tu repo
4. Ejecuta el orquestador con nohup

Comparación

| | Remote Triggers | Mac encendido | VPS | |---|---|---|---| | Costo | $100/mes (Claude Max) | Gratis | ~$5/mes | | PC necesario | No | Sí | No | | Setup | 2 minutos | 1 minuto | 30 minutos | | Fiabilidad | Alta (nube Anthropic) | Media (depende de WiFi) | Alta | | Recomendado para | Equipos, producción | Proyectos personales | Freelancers |

Features de Conductor

Vista Kanban

Cambia entre vista de lista y tablero Kanban con drag & drop. Arrastra specs entre columnas para cambiar su status.

Actívalo en tu proyecto → tab Specs → icono de columnas (arriba a la derecha de los filtros).

Búsqueda global (⌘K)

Presiona ⌘K (o Ctrl+K) para abrir el buscador global. Busca por título y contenido de specs y tareas en todos tus proyectos. Usa Tab para filtrar por tipo (Todo, Specs, Tareas).

Comentarios en specs

Cada spec tiene una sección de comentarios para discutir con tu equipo. Los comentarios se actualizan en tiempo real — si alguien comenta mientras tú miras la spec, lo ves al instante.

Historial de versiones

Cada cambio en una spec se guarda automáticamente. Puedes ver el historial completo, comparar versiones (diff), y restaurar una versión anterior.

Accede desde: spec detail → panel lateral → sección "Historial".

Dependencias entre specs

Marca que una spec depende de otra: la spec dependiente no se ejecutará hasta que la otra esté completada. El orquestador la salta automáticamente.

Configúralo desde: spec detail → dropdown "Depende de".

Acciones en lote (Bulk actions)

Selecciona múltiples specs con los checkboxes y aplica acciones en lote: marcar como Completado, Por Hacer, o Archivar.

Export de datos

Exporta todas las specs de un proyecto en JSON, CSV, o Markdown. Útil para reportes, backups, o migración.

Botón "Export" en el header del proyecto.

Live Logs

Ve los logs del orquestador en tiempo real con diseño de terminal. Cuando el orquestador ejecuta specs, los logs aparecen al instante.

Accede desde: tu proyecto → Config → Live Logs.

Preview de spec (Dry-run)

Antes de ejecutar una spec, haz click en el botón "Preview" (👁) para ver: qué tareas se ejecutarán, qué archivos se modificarán, y el prompt exacto que recibirá Claude Code.

Cost tracking

Cada spec muestra cuánto tiempo tardó y el costo estimado en API tokens. Ve el costo total del proyecto en Analytics.

Notificaciones

Slack / Discord

Configura webhooks para recibir notificaciones cuando specs se completan o fallan. En tu proyecto → Config → Slack/Discord.

Email

Recibe un resumen diario por email con specs completadas, en revisión, y pendientes. Actívalo en Settings → Notificaciones.

AI Spec Writer (Pro/Team)

Haz click en "✨ Sugerir specs" en tu proyecto. Conductor analiza tu código y sugiere mejoras con specs listas para crear.

Approval workflow (Team)

Requiere que las specs creadas por miembros del equipo sean aprobadas por el owner antes de ejecutarse. Actívalo en Config → Requerir aprobación.

Referral program

Invita amigos a Conductor. Ambos ganan 1 mes de Pro gratis. Tu link de referido está en Settings → Invita y gana.

GitHub Integration

Conecta tu repositorio de GitHub para que el orquestador haga commits y pull requests automáticamente.

Configuración inicial

1. Conectar el repo

En tu proyecto en Conductor:

1. Ve a Settings del proyecto
2. En la sección "GitHub Integration", ingresa la URL de tu repositorio
3. Haz clic en Conectar

2. Configurar el orquestador con Git

El orquestador necesita que Git esté configurado localmente:

# Configura tu identidad (si no lo has hecho)
git config user.name "Tu Nombre"
git config user.email "tu@email.com"

# Asegúrate de estar en el branch correcto
git checkout main

3. Variables de entorno opcionales

# Para commits automáticos con mensaje personalizado
CONDUCTOR_GIT_AUTO_COMMIT=true
CONDUCTOR_GIT_COMMIT_PREFIX="feat(conductor):"

# Para crear PRs automáticos (requiere GitHub CLI)
CONDUCTOR_CREATE_PR=true

Commits automáticos

Cuando el orquestador termina una spec, hace commit automáticamente:

Pull Requests automáticos

Con GitHub CLI instalado, el orquestador puede crear PRs:

# Instalar GitHub CLI
brew install gh
gh auth login

# Habilitar PRs automáticos
CONDUCTOR_CREATE_PR=true node orchestrator.mjs --run --all

Ver commits en el dashboard

En la vista de spec, puedes ver todos los commits asociados:

• Hash del commit
• Mensaje
• Fecha y hora
• Link directo a GitHub

Webhook de GitHub (bidireccional)

Para sincronizar el status de specs con el estado de PRs en GitHub:

1. En GitHub: Settings → Webhooks → Add webhook
2. URL: https://conductor.software/api/github/webhook
3. Content type: application/json
4. Events: Pull requests, Pushes

Cuando un PR se mergea, Conductor marca automáticamente la spec como "Completado".

API Reference

Todos los endpoints de la API REST de Conductor. Autenticación con Bearer token.

Versión interactiva disponible: Explora y prueba los endpoints en la API Reference interactiva →

Autenticación

Authorization: Bearer cnd_tu_api_key_aqui

La API key se encuentra en: Settings → API Key

Specs

Listar specs pendientes

GET /api/v1/specs?status=Por+Hacer

curl -X GET "https://conductor.software/api/v1/specs?status=Por+Hacer" \
  -H "Authorization: Bearer cnd_tu_api_key"

Parámetros de query:

• status — Filtrar por status: Por Hacer, En Progreso, Completado, Bloqueado
• limit — Número máximo de resultados (default: 50)

Respuesta:

{
  "specs": [
    {
      "id": "spec-uuid",
      "title": "feat: nueva feature",
      "status": "Por Hacer",
      "priority": "Alta",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

Obtener detalle de spec

GET /api/v1/specs/[id]

curl -X GET "https://conductor.software/api/v1/specs/SPEC_ID" \
  -H "Authorization: Bearer cnd_tu_api_key"

Respuesta:

{
  "id": "spec-uuid",
  "title": "feat: nueva feature",
  "content": "# Spec content en markdown...",
  "status": "Por Hacer",
  "priority": "Alta",
  "tasks": [...]
}

Actualizar status de spec

PATCH /api/v1/specs/[id]

curl -X PATCH "https://conductor.software/api/v1/specs/SPEC_ID" \
  -H "Authorization: Bearer cnd_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"status": "En Progreso"}'

Body:

{ "status": "Por Hacer | En Progreso | Completado | Bloqueado" }

Tareas

Listar tareas de una spec

GET /api/v1/specs/[id]/tasks

curl -X GET "https://conductor.software/api/v1/specs/SPEC_ID/tasks" \
  -H "Authorization: Bearer cnd_tu_api_key"

Actualizar status de tarea

PATCH /api/v1/tasks/[id]

curl -X PATCH "https://conductor.software/api/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer cnd_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"status": "Completado"}'

Body:

{ "status": "Pendiente | En Progreso | Completado | Fallido" }

Logs

Registrar evento de ejecución

POST /api/v1/logs

curl -X POST "https://conductor.software/api/v1/logs" \
  -H "Authorization: Bearer cnd_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "spec_id": "spec-uuid",
    "level": "info",
    "message": "Ejecutando tarea T1",
    "metadata": { "task_id": "task-uuid" }
  }'

Body:

{
  "spec_id": "uuid (opcional)",
  "level": "info | warn | error | success",
  "message": "Mensaje del log",
  "metadata": {}
}

Códigos de error

| Código | Descripción | |--------|-------------| | 401 | API key inválida o faltante | | 403 | Sin permisos para este recurso | | 404 | Recurso no encontrado | | 422 | Datos de entrada inválidos | | 429 | Rate limit excedido | | 500 | Error interno del servidor |

MCP Setup — Conectar Claude con Conductor

El MCP (Model Context Protocol) permite que Claude (en claude.ai o Claude Code) interactúe directamente con Conductor: crear specs, ver tareas, y gestionar proyectos.

Opción 1: Claude.ai (Web) — Recomendado

La forma más fácil. Conectas una vez y puedes crear specs hablando con Claude.

Paso 1: Ve a Integrations

1. Abre claude.ai
2. Ve a Settings → Integrations → Add MCP Server

Paso 2: Agrega la URL

Pega la URL de tu proyecto (la encuentras en tu proyecto → tab Config → Quick Start):

Paso 3: Usa el skill

Ahora puedes decirle a Claude cosas como:

• "Crea una spec para agregar dark mode"
• "Muéstrame las specs pendientes"
• "Actualiza la spec 15 a Completado"

Claude usa las herramientas MCP automáticamente:

• conductor-list-specs — Ver specs del proyecto
• conductor-create-spec — Crear nueva spec con tareas
• conductor-get-spec — Leer detalle de una spec
• conductor-update-spec-status — Cambiar status
• conductor-get-repomix — Obtener contexto del código
• conductor-list-projects — Ver tus proyectos

Opción 2: Claude Code CLI (Terminal)

Si usas Claude Code en tu terminal, el setup se instala automáticamente con el script de setup:

export CONDUCTOR_API_KEY=cnd_tu_api_key
bash <(curl -s https://conductor.software/api/scripts/setup)

Esto instala:

• El skill /conductor — escribe /conductor en Claude Code para diseñar specs
• El skill /conductor-spec-executor — ejecuta specs automáticamente
• El orquestador en scripts/orchestrator.mjs

Verificar la instalación

En Claude Code, escribe:

Deberías ver el skill cargarse y preguntarte en qué proyecto quieres trabajar.

Troubleshooting

Claude no reconoce el MCP

• Verifica que la URL es correcta y termina con tu API key
• Recarga la página de Claude.ai
• Espera 10-30 segundos después de agregar el MCP

Error de autenticación

• Copia la API key directamente desde tu proyecto → tab Config → Quick Start
• No incluyas espacios ni saltos de línea en la URL

El skill /conductor no aparece en Claude Code

• Verifica que corriste el script de setup en la raíz de tu proyecto
• Verifica que existe el archivo .claude/skills/conductor/SKILL.md

Team — Invitar miembros, roles y permisos

Conductor soporta trabajo colaborativo en equipo con roles diferenciados.

Planes y límites de equipo

| Plan | Miembros | |------|----------| | Lite (gratis) | Solo tú | | Pro | Hasta 5 miembros | | Team | Ilimitados |

Roles disponibles

Owner (Propietario)

• Acceso completo al proyecto
• Puede invitar y remover miembros
• Puede eliminar el proyecto
• Acceso a billing y API keys

Admin

• Crear, editar y eliminar specs
• Invitar miembros (no puede remover owners)
• Ver y gestionar todos los logs
• No tiene acceso a billing

Member (Miembro)

• Crear y editar specs propias
• Ver todas las specs del proyecto
• Ver logs del proyecto
• No puede invitar miembros ni acceder a settings

Viewer (Lector)

• Solo lectura en todas las specs
• Ver logs pero no crear
• Ideal para stakeholders o revisores

Invitar miembros

1. Ve a tu proyecto → Settings → Team
2. Ingresa el email del nuevo miembro
3. Selecciona el rol
4. Haz clic en Enviar invitación

El miembro recibirá un email con un link para unirse al proyecto. Si no tiene cuenta en Conductor, se le pedirá que la cree.

Gestionar permisos

En Settings → Team puedes:

• Ver todos los miembros activos
• Cambiar el rol de un miembro
• Remover miembros del proyecto
• Ver invitaciones pendientes y reenviarlas

Colaboración en tiempo real

Cuando múltiples miembros trabajan al mismo tiempo:

• Ves un indicador de presencia (avatars) en la vista de proyecto
• Los cambios de status se actualizan en tiempo real
• Las notificaciones in-app te avisan cuando alguien modifica una spec

API keys por miembro

Cada miembro puede generar su propia API key en Settings → API Key. Las keys están asociadas al usuario, no al proyecto, por lo que cada miembro usa su propia key con el mismo project ID.

Audit logs (Plan Team)

En el plan Team, tienes acceso a logs de auditoría que muestran:

• Quién creó/modificó/eliminó cada spec
• Cambios de status con timestamp y usuario
• Invitaciones enviadas y aceptadas
• Ejecuciones del orquestador por usuario