Shortcuts por harness

Los shortcuts son el flujo principal de Rapid OS. El primero es /rapid-init: tu agente conduce todo el onboarding del proyecto con rapid setup (stack, topología, arquetipo, agentes, comando de test y documentos). Después hay un comando por modo (/rapid-feature, /rapid-bugfix…) que tu agente ejecuta para llevar el trabajo de principio a fin dentro de un run gobernado. Tú describes el objetivo; el shortcut le enseña al agente el bucle (rapid next → rapid start → rapid check → rapid finish) y se detiene cuando hace falta una persona.

Los comandos v3 (rapid spec, rapid run, rapid evidence, rapid eval…) siguen disponibles como Modo avanzado: CI, depuración y auditoría. Están descritos en la referencia de CLI y en el flujo manual de cada guía de modo.

Instálalos una sola vez para todos tus proyectos (el instalador de Rapid OS te lo pregunta al terminar; cambia claude por tu agente):

rapid shortcuts install --global --harness claude

En VS Code, o si prefieres versionarlos con el repositorio, instálalos en el proyecto con rapid init --shortcuts. Después, en tu agente:

/rapid-init API de facturación para pymes, en Python   # onboarding (en Codex: $rapid-init)
/rapid-feature añadir exportación CSV al informe mensual

rapid debe estar en el PATH

Los shortcuts y los hooks ejecutan rapid desde el shell del agente. Si no se resuelve, rapid init y rapid doctor avisan con RAPID1414 (no es un error: exit 0). Instálalo con el instalador o con pipx install git+https://github.com/alyconr/Rapid-OS.git.

1. Instalación

Los archivos se generan desde una sola fuente (templates/shortcuts/), uno por harness y shortcut.

rapid init --shortcuts                                  # al inicializar, para los agentes elegidos
rapid shortcuts install                                 # para los harness de "tools" en .rapid-os/config.json
rapid shortcuts install --harness claude --harness codex
rapid shortcuts install --harness claude --hooks        # además, los hooks de Claude Code
rapid shortcuts install --harness claude --dry-run   # qué escribiría, sin escribir
rapid shortcuts install --harness claude --only rapid-init   # solo un shortcut
rapid shortcuts install --global --harness claude   # los 9, en tu carpeta de usuario (ver abajo)
rapid shortcuts list                                    # estado de cada archivo: installed, outdated, missing, unmanaged
rapid shortcuts remove --harness codex                  # quita solo lo generado

Sin --harness, se usan los harness soportados que figuren en tools de .rapid-os/config.json. En un proyecto sin ese archivo hay que pasar --harness (RAPID1312).
Cada archivo lleva el marcador . remove borra solo archivos con ese marcador y deja los tuyos intactos.
La instalación es idempotente: si el contenido es igual no escribe; si es distinto, guarda una copia .bak antes de reemplazar.
rapid init --shortcuts no instala hooks; se piden con --hooks (en rapid init o en rapid shortcuts install).
Se omiten los shortcuts de los modos que no tengan playbook en templates/modes/ (RAPID1315); hoy existen los cinco.

Instalación a nivel usuario (`--global`)

rapid shortcuts install --global --harness <id> [--only rapid-init] escribe los shortcuts en la carpeta de skills de tu usuario (bajo tu carpeta personal), así /rapid-init funciona en cualquier proyecto sin instalarlo en cada uno. Necesita --harness (no lee la config de ningún proyecto), y list y remove aceptan el mismo --global. --hooks (Claude Code) solo se admite dentro de un proyecto: instala los skills para el usuario y los hooks en el .claude/settings.json del proyecto, sin copiar allí los skills; fuera de un proyecto da RAPID1413. Solo está disponible donde la documentación oficial del harness da la carpeta:

Harness	Carpeta de usuario	Fuente
`claude`	`~/.claude/skills/<nombre>/SKILL.md`	Skills de Claude Code
`codex`	`~/.agents/skills/<nombre>/SKILL.md`	Skills de Codex
`cursor`	`~/.cursor/skills/<nombre>/SKILL.md`	Skills de Cursor
`antigravity`	`~/.gemini/config/skills/<nombre>/SKILL.md` (Antigravity App e IDE; el CLI de Antigravity lee `~/.gemini/antigravity-cli/skills/`, que `--global` no escribe)	Skills de Antigravity
`vscode`	No soportado: la documentación de los prompt files solo dice «Your user data (specific to your VS Code profile)», sin una ruta.	Prompt files de VS Code

Pedir --global para vscode (solo o junto a otros) da RAPID1413 y no escribe nada. rapid setup finish hace solo la mitad del proyecto cuando claude está entre los agentes: instala los hooks en el proyecto y ningún skill, para que cada /rapid-* salga una sola vez. Si el mismo /rapid-* queda a la vez en tu carpeta de usuario y en el proyecto, rapid shortcuts install y rapid doctor avisan con RAPID1321 y dicen qué lado quitar (rapid shortcuts remove --harness claude o rapid shortcuts remove --global --harness claude). install.sh e install.ps1 ofrecen este paso al terminar (solo si hay una terminal interactiva, y nunca por defecto).

Reinstalar tras actualizar Rapid OS

Los shortcuts son archivos del proyecto: una versión nueva de Rapid OS puede cambiar sus plantillas. Después de actualizar:

rapid shortcuts list        # los que cambiaron aparecen como "outdated"
rapid shortcuts install     # los actualiza (con .bak) y no toca los que ya están al día

Conviene versionar los archivos generados junto al código, para que todo el equipo use el mismo flujo.

2. Harnesses: qué carpeta se genera y cómo se invoca

Todo sale de los adaptadores de rapid_os/adapters/agents/; cada fila cita la documentación oficial del harness.

Harness (`--harness`)	Carpeta que se genera	Cómo se invoca	Documentación oficial
`claude` (Claude Code)	`.claude/skills/<nombre>/SKILL.md`	`/rapid-init`, `/rapid-feature <objetivo>`; al escribir `/rapid-` aparecen los 9	Skills de Claude Code
`codex` (Codex CLI y extensión de IDE)	`.agents/skills/<nombre>/SKILL.md`	`$rapid-init`, `$rapid-feature <objetivo>`, o elegirlo desde `/skills`. En Codex CLI, `/` no lista los skills: usa `$` (detalle)	Skills de Codex
`antigravity` (Google Antigravity)	`.agents/skills/<nombre>/SKILL.md` (la misma carpeta que Codex)	`/rapid-feature <objetivo>`	Skills de Antigravity
`cursor` (Cursor)	`.cursor/skills/<nombre>/SKILL.md`	`/rapid-feature <objetivo>` en el chat del Agent	Skills de Cursor
`vscode` (VS Code / Copilot)	`.github/prompts/<nombre>.prompt.md` (prompt files)	`/rapid-feature <objetivo>` en el chat	Prompt files de VS Code

Qué hace cada harness con el shortcut:

Harness	Ejecuta solo el `context-command`	Hooks
`claude`	Sí: !`rapid setup next --json` (o `rapid next --json`) corre antes del prompt; si falla, el skill se aborta.	Solo aquí (`--hooks`).
`codex`, `antigravity`, `cursor`, `vscode`	No: el texto le pide al agente que ejecute el comando él mismo.	No hay hooks de Rapid OS.

Detalles que conviene conocer:

Codex y Antigravity comparten .agents/skills. Si seleccionas ambos, cada archivo se escribe una sola vez.
Solo Claude Code ejecuta la línea !`rapid next --json` antes de enviar el prompt (y si ese comando falla, el skill se aborta, así que rapid debe estar en el PATH). En el resto de harnesses el texto le pide al agente que ejecute rapid next --json primero.
rapid-approve lleva disable-model-invocation en Claude Code y Cursor, que lo documentan: solo lo lanza la persona, el agente no lo invoca por su cuenta.

Si combinas harnesses

Algunas herramientas leen más carpetas que la suya, según su documentación oficial:

Herramienta	Carpetas de skills que lee (project)	Fuente
Cursor	`.cursor/skills/`, `.agents/skills/` y, por compatibilidad, `.claude/skills/` y `.codex/skills/`	Cursor: skills
VS Code / Copilot	`.github/skills/`, `.claude/skills/`, `.agents/skills/` (además de los prompt files de `.github/prompts/`)	VS Code: agent skills

Por eso, seleccionar cursor o vscode junto con claude, codex o antigravity deja el mismo /rapid-* en dos carpetas que esa herramienta lee. La documentación oficial de Cursor y de VS Code no especifica cómo muestran dos skills del mismo nombre en carpetas distintas (la de VS Code solo indica que, para skills de marketplace con el mismo nombre en otra ubicación, ambos aparecen en su página de Skills), así que aquí no se afirma que el menú los duplique. rapid shortcuts install, rapid shortcuts list y rapid init --shortcuts avisan con WARNING RAPID1321 (en stderr, y como warnings con --json) cuando tu selección entra en este caso; es solo un aviso, no cambia el exit code ni lo que se escribe. Para no depender de ello:

Usas	Instala	Nota
Una sola herramienta	`--harness <su-id>`	Sin solapes.
Codex y/o Antigravity, y quizá Cursor o VS Code	`--harness codex` (o `antigravity`)	`.agents/skills` lo leen las cuatro herramientas; no hace falta añadir `cursor` ni `vscode`.
Claude Code y Codex/Antigravity	`--harness claude --harness codex`	Sin solapes documentados: Claude Code documenta `.claude/skills` y Codex `.agents/skills`.
Claude Code y Cursor o VS Code	`--harness claude`	Cursor y VS Code leen `.claude/skills`. En ellos la línea !`rapid next --json` no está documentada como ejecutable: el agente debe correr `rapid next --json` por sí mismo. Si prefieres la variante propia de cada herramienta, añade `cursor` o `vscode` sabiendo que el mismo shortcut vivirá en dos carpetas.

3. Los 9 shortcuts

Shortcut	Qué hace	Argumento
`rapid-init`	Conduce el onboarding del proyecto con `rapid setup`: decisiones, documentos (borrador, pegado u omitido) y cierre. Nunca confirma un borrador por ti.	Descripción del proyecto (opcional).
`rapid-feature`	Implementa una funcionalidad con un run gobernado (modo `feature`).	Objetivo de la funcionalidad.
`rapid-bugfix`	Corrige un bug: reproduce primero con un test en rojo (modo `bugfix`).	Descripción del bug.
`rapid-refactor`	Refactoriza sin que bajen los tests que pasan (modo `refactor`).	Alcance del refactor.
`rapid-hardening`	Endurece seguridad o robustez en un worktree aislado (modo `hardening`).	Área a endurecer.
`rapid-research`	Spike de investigación, sin tests obligatorios (modo `research`).	Pregunta o tema.
`rapid-next`	Continúa el run activo con la siguiente acción determinista.	Ninguno.
`rapid-status`	Resume el run activo: tareas, gates y último veredicto (solo lectura).	Ninguno.
`rapid-approve`	No aprueba: muestra los gates humanos pendientes, la evidencia y el comando para tu terminal.	Opcional: el gate (`gate.final-verification`).

Qué hace el playbook de cada modo está en la guía de modos.

4. El bucle que siguen

Los shortcuts de modo enseñan solo estos pasos; no listan comandos de bajo nivel:

rapid next --json: devuelve la siguiente acción (action.kind: author_spec, run_baseline, activate, implement_task, verify, await_human_approval, finish, done o blocked).
author_spec: el agente redacta la spec desde tu objetivo, siguiendo la plantilla del modo (action.spec_template), y la pasa por stdin a rapid start <modo> --spec-file -. Sin run activo, rapid next solo conoce la plantilla de feature; los demás shortcuts piden la suya con rapid start <modo> --json.
action.command: si existe, se ejecuta. En implement_task el agente implementa solo esa tarea y ejecuta action.after (rapid task done …). Los tests siempre se corren con rapid check -- <comando> para que quede evidencia.
Se repite hasta done o await_human_approval; entonces el agente resume la evidencia y te pide ejecutar rapid approve <gate> en tu terminal. rapid finish cierra el run cuando ya no queda nada pendiente.
Nunca ejecuta rapid approve, rapid abort, rapid run gate ni rapid evidence add, y nunca edita .rapid-os/.

El motivo de la última regla: aprobar un gate humano, abortar un run o registrar evidencia a mano son decisiones de una persona. Si el agente pudiera hacerlo, la evidencia y las aprobaciones dejarían de significar algo. Cuando rapid next devuelve blocked con el comando rapid abort (porque una revisión fue rechazada), el agente explica la razón y espera tu decisión.

5. Aprobación humana

Los shortcuts piden aprobación solo cuando action.kind es await_human_approval. awaiting_human lista los gates humanos del contrato desde el inicio del run, así que con tareas abiertas ya trae gate.final-verification: pedirla entonces da RAPID1014 (y rapid approve añade una línea con la tarea que sigue en curso). Cuando llega el momento, el agente te da el comando exacto con el id del gate y tú lo ejecutas en otra terminal, fuera del agente.

/rapid-approve no aprueba nada. Lee rapid status --json, te muestra los gates humanos pendientes con la evidencia que los respalda y te da el comando exacto para tu terminal:

rapid approve gate.final-verification                                  # aprobar
rapid approve gate.review --waive --reason "cubierto por la auditoría"   # dispensar (solo gates waivable)
rapid approve gate.review --reject --reason "faltan casos límite"        # rechazar: el gate queda en FAIL en ese run

Sin argumentos, rapid approve lista los gates pendientes. Cambiar un gate falla con RAPID1310 en estos casos:

Sin TTY: la entrada no es una terminal interactiva (por ejemplo, un comando lanzado por un agente o por un pipe).
Desde el modo ! de Claude Code: ahí claude es un proceso ancestro y rapid approve se niega.
Bajo un agente: CLAUDE_CODE_CHILD_SESSION=1, o claude como ancestro del proceso.

La solución es siempre la misma: ejecútalo tú en tu propia terminal (la terminal integrada de un editor sirve). La comprobación de ancestros es de mejor esfuerzo; la regla es que una persona apruebe en su terminal. Los detalles están en límites del producto.

6. Hooks de Claude Code

Los hooks Stop y PreToolUse (opcionales, solo para Claude Code) evitan que el agente se detenga a mitad de un run y le deniegan los comandos reservados a la persona y la edición de .rapid-os/: rapid shortcuts install --harness claude --hooks. Todo el detalle está en la sección 6 de la integración con Claude Code.

7. Problemas frecuentes

El catálogo completo de códigos está en diagnósticos; estos son los que más verá quien usa shortcuts.

Código	Qué significa	Solución
`RAPID1301`	No hay `test_command` en `.rapid-os/config.json`.	`rapid init --test-command "<cmd>"` o añadirlo a la config como lista argv.
`RAPID1307`	No hay un run activo (`.rapid-os/session.json`).	Empieza uno con `/rapid-<modo> <objetivo>` o `rapid start <modo>`.
`RAPID1308`	Ya hay un run activo sin terminar.	Continúa con `/rapid-next`, o cancélalo tú con `rapid abort` en tu terminal.
`RAPID1310`	`rapid approve` sin TTY, desde el modo `!` de Claude Code o con `claude` como ancestro.	Ejecútalo en tu propia terminal (sección 5).
`RAPID1312`	No hay harness seleccionado para instalar.	`--harness <id>` o `rapid init --agents <lista>`.
`RAPID1413`	`--global` para un harness sin carpeta de usuario documentada (`vscode`), sin `--harness` o con `--hooks` fuera de un proyecto; o un `--only` con un shortcut inexistente. No se escribe nada.	Instalar en el proyecto (sin `--global`), o pasar `--harness` y un nombre de la tabla de la sección 3.
`RAPID1414`	Aviso: `rapid` no está en el `PATH` y hay shortcuts o hooks instalados.	Instalar Rapid OS con el instalador o con `pipx install git+https://github.com/alyconr/Rapid-OS.git`.
`RAPID1315`	Un shortcut de modo se omitió porque ese modo no tiene playbook.	Informativo; vuelve a ejecutar `rapid shortcuts install` cuando exista.
`RAPID1320`	`rapid check --expect fail` sin tarea (o ligado a un gate).	Indica `--task T001` o deja exactamente una tarea en curso.
`RAPID1321`	Aviso: la selección deja el mismo `/rapid-` en dos carpetas que Cursor o VS Code leen, o un `/rapid-` está instalado a la vez para el usuario y en el proyecto.	Instala solo la combinación recomendada en el aviso (ver «Si combinas harnesses»); no bloquea nada.
`RAPID1337`	`--hooks` sin el harness `claude`.	Selecciona `--harness claude` o quita `--hooks`.
`RAPID1339`	`rapid doctor`: hay hooks instalados pero `rapid` no está en el `PATH`.	Instala Rapid OS donde lo vea Claude Code o añade su directorio de scripts al `PATH`.

Sin código de error:

Síntoma	Causa	Solución
En Codex CLI, `/rapid-feature` no aparece al escribir `/`.	En Codex CLI, `/` solo lista los comandos de Codex; los skills se invocan con `$` o desde `/skills`.	Escribe `$rapid-feature <objetivo>` (detalle).

1. Instalación​

Instalación a nivel usuario (--global)​

Reinstalar tras actualizar Rapid OS​

2. Harnesses: qué carpeta se genera y cómo se invoca​

Si combinas harnesses​

3. Los 9 shortcuts​

4. El bucle que siguen​

5. Aprobación humana​

6. Hooks de Claude Code​

7. Problemas frecuentes​