Estructura de archivos

Rapid OS guarda la mayor parte de su estado de gobernanza dentro de .rapid-os/, dejando visibles los artefactos que deben poder versionarse, inspeccionarse y auditarse.

Estructura principal

project/
├── .rapid-os/
│   ├── config.json
│   ├── project.json
│   ├── setup.json                  (estado del onboarding; lo escribe `rapid setup`)
│   ├── policy.json
│   ├── capabilities.lock
│   ├── standards/
│   ├── specs/
│   │   └── <spec-id>/
│   │       ├── spec.json
│   │       └── revisions/
│   ├── runs/
│   │   └── <run-id>/
│   │       ├── run.json
│   │       ├── contract.json
│   │       ├── context.md
│   │       ├── context-manifest.json
│   │       └── states/
│   ├── harnesses/
│   ├── evidence/
│   │   └── <run-id>/
│   │       ├── records/
│   │       └── artifacts/
│   ├── evals/
│   │   └── <run-id>/
│   │       └── reports/
│   ├── session.json                (run activo; estado local)
│   └── scratch/                    (estado local de la capa porcelain)
│       ├── checks/<run-id>/<n>.log
│       ├── hooks.json
│       └── hooks.log
├── .claude/skills/  .agents/skills/  .cursor/skills/  .github/prompts/   (shortcuts)
├── .claude/settings.json                                                 (hooks de Claude Code)
├── docs/
│   ├── PRODUCT_BRIEF.md            (doc del onboarding: brief)
│   ├── BUSINESS_RULES.md           (doc del onboarding: business)
│   ├── DATA_MODEL.md               (doc del onboarding: data-model)
│   └── ARCHITECTURE.md             (doc del onboarding: architecture)
├── SPECS.md
├── TASKS.md
├── ACCEPTANCE.md
├── references/
└── archivos específicos del harness

No todos los archivos existen desde el inicio; aparecen cuando se usa el módulo correspondiente.

Archivos de la capa porcelain (shortcuts)

Ruta	Quién la escribe	Qué contiene
.rapid-os/session.json	rapid start lo escribe; rapid abort lo borra	El run activo: active_run_id, mode, harness, start_head y, si aplica, start_untracked y workspace_path. rapid finish no lo toca: por eso un segundo rapid finish encuentra el run ya terminado. Estado local: no se versiona.
.rapid-os/scratch/checks/<run-id>/<n>.log	rapid check	La salida completa de cada comando ejecutado con rapid check. La evidencia (rapid:check) la registra en .rapid-os/evidence/; el log es solo un apoyo.
.rapid-os/backups/<archivo>.<timestamp>.bak	rapid init, rapid setup (doc, finish) y los comandos que regeneran CLAUDE.md, AGENTS.md, .cursorrules, INSTRUCTIONS.md y .agent/rules/constitution.md	La copia del archivo de agente anterior. Solo se crea si el contenido cambia, se conservan las 5 más recientes por archivo y no se versionan.
.rapid-os/generated.json	rapid setup, rapid init	SHA-256 de cada archivo de agente que generó Rapid OS (CLAUDE.md, AGENTS.md...), para reconocer uno editado a mano (RAPID1427; los finales de línea no cuentan). Se versiona con el proyecto, así que la comprobación funciona en un clon.
.rapid-os/scratch/hooks.json	rapid hook	Guarda del hook Stop (evita bucles de continuación).
.rapid-os/scratch/hooks.log	rapid hook	Una línea por decisión de los hooks; rota a hooks.log.1.
.claude/skills/<nombre>/SKILL.md	rapid shortcuts install	Shortcuts de Claude Code.
.agents/skills/<nombre>/SKILL.md	rapid shortcuts install	Shortcuts de Codex y Antigravity (comparten carpeta).
.cursor/skills/<nombre>/SKILL.md	rapid shortcuts install	Shortcuts de Cursor.
.github/prompts/<nombre>.prompt.md	rapid shortcuts install	Shortcuts de VS Code / Copilot (prompt files).
.claude/settings.json	rapid shortcuts install --hooks, rapid init --hooks	Los hooks Stop y PreToolUse de Claude Code (rapid hook stop, rapid hook pre-tool). Se fusionan con tu configuración existente.
../<repo>-<run-id>	rapid start --worktree	Worktree git aislado del run, en la rama rapid/<run-id>; su ruta queda en workspace_path de la sesión. Es un directorio hermano del repositorio, no una subcarpeta.

Se recomienda añadir a .gitignore:

.rapid-os/session.json
.rapid-os/scratch/
.rapid-os/backups/
__pycache__/
*.pyc
.pytest_cache/

rapid init y rapid setup finish añaden las líneas que falten a un .gitignore existente (no lo crean si no hay uno). Las tres últimas evitan que los artefactos de las herramientas se confundan con cambios del proyecto; aun así rapid finish los ignora por nombre aunque no estén en el .gitignore (ver file_change).

Los archivos de shortcuts y .claude/settings.json sí conviene versionarlos, para que todo el equipo use el mismo flujo. rapid shortcuts remove borra solo los archivos con el marcador <!-- generated by rapid shortcuts -->.

Archivos heredados de contexto

rapid init puede generar archivos como:

• .cursorrules
• CLAUDE.md
• .agent/rules/constitution.md
• INSTRUCTIONS.md
• AGENTS.md

También mantiene estándares dentro de .rapid-os/standards/.

Documentos del onboarding

Cuatro documentos de docs/ entran al contexto como fuentes propias (rapid context y los archivos de agente), con la procedencia visible. Ver Documentos del proyecto y su procedencia.

Fuente de contexto	Ruta	Prioridad	Tipo	Tags
doc.brief	docs/PRODUCT_BRIEF.md	alta	product	product, feature, spec
doc.business	docs/BUSINESS_RULES.md	alta	business	business, domain, product
doc.data-model	docs/DATA_MODEL.md	media	data_model	data, database, backend, domain
doc.architecture	docs/ARCHITECTURE.md	alta	architecture	architecture, topology, backend, frontend

Un archivo de docs/ cuenta solo si su frontmatter tiene rapid-doc: <id> con el id de la tabla (muchos repositorios ya tienen su propio docs/, y Rapid OS mismo lo tiene). El frontmatter nunca se inyecta en el contenido. La ruta y la prioridad salen de los bancos de templates/setup/docs/.

Artefactos inmutables

Los registries v3 priorizan append-only e integridad por digest.

Ejemplos:

• revisiones de Specs no se editan en sitio;
• snapshots históricos de RunState no se sobrescriben;
• records de Evidence usan IDs secuenciales;
• reportes de evaluación se agregan por revisión;
• artefactos de Evidence se copian y verifican por SHA-256 y tamaño.

Comandos de solo lectura

Ejemplos:

rapid guide
rapid scan
rapid validate
rapid doctor
rapid inspect-context
rapid context
rapid spec list
rapid spec show
rapid policy show
rapid run list
rapid run show
rapid harness list
rapid harness show
rapid harness resolve
rapid evidence list
rapid evidence show
rapid evidence verify
rapid eval list
rapid eval show

Verbos de la capa porcelain

Clase	Verbos
Solo lectura	rapid next, rapid status, rapid shortcuts list
Escriben estado	rapid start, rapid check, rapid task, rapid attach, rapid finish, rapid approve, rapid abort, rapid shortcuts install, rapid shortcuts remove

rapid next y rapid status solo leen el ledger y la sesión. rapid check ejecuta el comando que le pasas (o el test_command de .rapid-os/config.json) y registra evidencia; rapid start --worktree crea además el worktree. rapid hook solo escribe en .rapid-os/scratch/.

Algunos comandos cambian de comportamiento con flags. Por ejemplo, rapid scan es de solo lectura salvo que se use --write, y rapid eval run solo persiste un reporte con --write.

Comandos que escriben estado

Ejemplos:

rapid init
rapid scan --write
rapid scope
rapid spec create
rapid spec revise
rapid spec status
rapid spec export-legacy
rapid policy init
rapid run create
rapid run status
rapid run task
rapid run gate
rapid harness init
rapid harness lock
rapid evidence add
rapid eval run --write
rapid mcp
rapid vision
rapid deploy

Consulta la referencia CLI para los flags y contratos exactos de cada comando.

Protección de rutas y backups

Rapid OS valida contención de rutas para evitar path traversal y escapes mediante symlinks en los registries gobernados. Las operaciones heredadas que sobrescriben ciertos archivos utilizan backups .bak cuando corresponde. Los archivos de agente que Rapid OS regenera (CLAUDE.md, AGENTS.md, .cursorrules, INSTRUCTIONS.md, .agent/rules/constitution.md) no dejan .bak en la raíz del proyecto: su copia anterior va a .rapid-os/backups/, solo si el contenido cambió, y se conservan las 5 más recientes por archivo.

Stacks del catálogo

Cada componente de la topología tiene su stack (ver Stacks y componentes). rapid init --stack <id> y rapid setup set stack <id> [--component <c>] escriben en .rapid-os/standards/tech-stack.md la plantilla templates/stacks/<componente>/<id>.md de cada stack elegido, y el sidecar <id>.json declara sus factores, fuentes, topologías compatibles y servicios soportados.

Componente	Stacks
backend	python-fastapi, python-django, node-nestjs, node-fastify, go, rust-axum, ruby-rails, dotnet-aspnetcore, java-spring-boot, kotlin-spring-boot, php-laravel
frontend	react-vite, nextjs, angular, vue-vite, nuxt, svelte-vite, sveltekit, astro
docs	docs-modern (Docusaurus), compatible solo con doc-site
todos	generic (sin plantilla: se genera con lo que detecta el escáner) y custom (el tech-stack.md que escribe el agente)

Los ids de antes (python-api, python-ai, nodejs-ai, web-modern, frontend-creative) se siguen aceptando; ver la guía de migración.

rapid validate reconoce el stack por la marca <!-- rapid-stack: backend=go --> que Rapid OS escribe al final de cada bloque de tech-stack.md, y en un archivo anterior por su encabezado (TECH STACK: PYTHON API...).

La seguridad de rutas protege los artefactos de Rapid OS, pero no sustituye los controles de permisos del sistema operativo o del entorno donde se ejecute el coding harness.