/ Directorio / Playground / pilot-shell
← Todos los servidores ↗ GitHub
● Comunidad maxritter ⚡ Instantáneo

pilot-shell

por maxritter · maxritter/pilot-shell

Claude Code guiado por especificaciones con quality gates integrados — cada cambio pasa por plan → spec → implementación → verificación antes de llegar a main.

pilot-shell envuelve Claude Code en un bucle guiado por especificaciones: las funcionalidades comienzan como planes, se convierten en specs, se implementan contra criterios de aceptación y se publican solo después de que los gates pasen (lint, tipos, tests, documentación). También persiste el conocimiento del proyecto — invariantes, decisiones, gotchas — para que la calidad se mantenga entre sesiones.

▶ Ver demo 📦 Instalar 💡 Casos de uso

Por qué usarlo

Características clave

Demo en vivo

Cómo se ve en la práctica

listo

Instalar

Elige tu cliente

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "pilot-shell-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/maxritter/pilot-shell",
        "~/.claude/skills/pilot-shell"
      ],
      "_inferred": true
    }
  }
}

Abre Claude Desktop → Settings → Developer → Edit Config. Reinicia después de guardar.

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "pilot-shell-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/maxritter/pilot-shell",
        "~/.claude/skills/pilot-shell"
      ],
      "_inferred": true
    }
  }
}

Cursor usa el mismo esquema mcpServers que Claude Desktop. La configuración del proyecto prevalece sobre la global.

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "pilot-shell-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/maxritter/pilot-shell",
        "~/.claude/skills/pilot-shell"
      ],
      "_inferred": true
    }
  }
}

Haz clic en el icono MCP Servers de la barra lateral de Cline y luego en "Edit Configuration".

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "pilot-shell-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/maxritter/pilot-shell",
        "~/.claude/skills/pilot-shell"
      ],
      "_inferred": true
    }
  }
}

Mismo formato que Claude Desktop. Reinicia Windsurf para aplicar.

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "pilot-shell-skill",
      "command": "git",
      "args": [
        "clone",
        "https://github.com/maxritter/pilot-shell",
        "~/.claude/skills/pilot-shell"
      ]
    }
  ]
}

Continue usa un array de objetos de servidor en lugar de un mapa.

~/.config/zed/settings.json
{
  "context_servers": {
    "pilot-shell-skill": {
      "command": {
        "path": "git",
        "args": [
          "clone",
          "https://github.com/maxritter/pilot-shell",
          "~/.claude/skills/pilot-shell"
        ]
      }
    }
  }
}

Añádelo a context_servers. Zed recarga en caliente al guardar.

claude mcp add pilot-shell-skill -- git clone https://github.com/maxritter/pilot-shell ~/.claude/skills/pilot-shell

Un solo comando. Verifica con claude mcp list. Quita con claude mcp remove.

Casos de uso

Usos del mundo real: pilot-shell

Publicar una funcionalidad con disciplina spec-first

👤 Devs cansados de funcionalidades a medias escritas por IA ⏱ ~90 min intermediate

Cuándo usarlo: Petición de funcionalidad vaga del PM; la quieres publicada correctamente, no rápidamente.

Requisitos previos
  • Skill instalada — git clone https://github.com/maxritter/pilot-shell ~/.claude/skills/pilot-shell
Flujo
  1. Planificar
    Use pilot-shell. Plan the feature 'export usage CSV per workspace per month'. List unknowns + risks.✓ Copiado
    → Plan con incógnitas explícitas; las rellenas antes del siguiente paso
  2. Especificar
    From the plan, write a spec with acceptance criteria + non-goals + edge cases.✓ Copiado
    → Spec guardada en /specs/<feature>.md
  3. Implementar
    Implement against the spec. Tests first, then code. Stop at any unmet criterion.✓ Copiado
    → Tests + implementación; tests fallando visibles hasta que la implementación los pase
  4. Verificar los gates
    Run all gates: lint, type, tests, docs. Block PR if any red.✓ Copiado
    → Informe de gates; solo verde = candidato a fusionar

Resultado: Funcionalidades que se publican completas según la spec, con tests y documentación.

Errores comunes
  • La spec se convierte en una maratón de planificación — Limita la fase de spec a 30 min; publica la spec más pequeña que fije los criterios de aceptación
Combinar con: filesystem

Dejar de abrir PRs que fallan en CI en la primera ejecución

👤 Devs cuyos PRs rebotan frecuentemente en errores de lint/tipos ⏱ ~30 min intermediate

Cuándo usarlo: Abriste 3 PRs esta semana; todos fallaron en CI por lo básico.

Flujo
  1. Configurar los gates
    Use pilot-shell. Configure quality gates to mirror our CI: eslint, tsc, vitest, prettier.✓ Copiado
    → .pilot.config.json con los gates listados
  2. Bloquear en rojo
    Set policy: don't open PR until all gates green locally.✓ Copiado
    → Política aplicada
  3. Medir
    After 2 weeks, compare CI first-run pass rate before/after.✓ Copiado
    → Tasa de aprobación al alza

Resultado: PRs que pasan CI a la primera; menos revisión innecesaria para los revisores.

Errores comunes
  • Los gates locales difieren sutilmente del CI (versión de Node) — Fija la versión local de Node con .nvmrc; refleja los comandos exactos del CI
Combinar con: github

Preservar el conocimiento del proyecto a medida que el equipo crece

👤 Propietarios de proyecto incorporando nuevos colaboradores ⏱ ~30 min beginner

Cuándo usarlo: Estás transfiriendo / compartiendo el proyecto; quieres que las decisiones e invariantes queden capturados.

Flujo
  1. Sembrar el archivo de conocimiento
    Use pilot-shell. Initialize project knowledge with: architecture, key invariants, decisions log.✓ Copiado
    → /.pilot/knowledge.md creado con secciones
  2. Capturar sobre la marcha
    Whenever a decision is made (chose Postgres over MySQL), record with date + reason.✓ Copiado
    → Las decisiones se acumulan; los nuevos colaboradores pueden leer el historial
  3. Usar en la incorporación
    When a new collaborator starts, point Claude Code to this file as primary context.✓ Copiado
    → Incorporación más rápida; menos 'por qué es así'

Resultado: El conocimiento sobrevive a los cambios de equipo.

Errores comunes
  • El archivo de conocimiento se convierte en un diario de trivialidades — Mantenlo conciso: invariantes, decisiones, gotchas. No un registro diario

Combinaciones

Combínalo con otros MCPs para multiplicar por 10

pilot-shell-skill + github

Plantilla de PR rellenada automáticamente desde la spec; CI valida los gates

When opening a PR, populate the body from the spec markdown; CI checks gates match.✓ Copiado
pilot-shell-skill + filesystem

Specs y conocimiento comprometidos al repositorio

Persist /specs/ and /.pilot/knowledge.md in repo for review history.✓ Copiado

Herramientas

Lo que expone este MCP

HerramientaEntradasCuándo llamarCoste
plan feature_description Paso 1 de cualquier nueva funcionalidad 0
spec plan_id Después de resolver las incógnitas del plan 0
implement spec_id Después de aprobar la spec 0
run_gates scope? Pre-PR; espejo del CI 0
knowledge_update decision_or_invariant Capturar una decisión a nivel de proyecto 0

Coste y límites

Lo que cuesta ejecutarlo

Cuota de API
Ninguna — local
Tokens por llamada
Los documentos de spec ~500–2000 tokens; el archivo de conocimiento se limita a ~3000 para que sea manejable
Monetario
Gratuito
Consejo
Limita knowledge.md a ~3000 tokens; consolida entradas antiguas periódicamente

Seguridad

Permisos, secretos, alcance

Ámbitos mínimos: filesystem-write
Almacenamiento de credenciales: Ninguna
Salida de datos: Ninguna

Resolución de problemas

Errores comunes y soluciones

Los gates pasan localmente pero fallan en CI

Fija la versión de Node, las dependencias específicas del SO; refleja el comando exactamente como en CI

Verificar: Diff local vs CI command output
El paso de implementación omite el test-first

Define strict_tdd=true en .pilot.config; la herramienta se negará a escribir implementación antes de los tests

La fase de spec se alarga

Usa --time-box 30m; fuerza decisiones sobre las incógnitas en lugar de buscar specs perfectas

El archivo de conocimiento es demasiado largo

Ejecuta knowledge_consolidate; archiva entradas antiguas en /.pilot/archive/

Alternativas

pilot-shell vs otros

AlternativaCuándo usarlaContrapartida
spec-workflow-mcpQuieres esto como servidor MCP con alcance multi-herramienta (no una skill de Claude Code)Más configuración; despliegue más flexible
Plain CLAUDE.md + manual TDDProyecto en solitario, no necesitas automatizaciónDependiente de la disciplina; menos barreras de seguridad

Más

Recursos

📖 Lee el README oficial en GitHub

🐙 Ver issues abiertas

🔍 Ver todos los 400+ servidores MCP y Skills