File structure

Rapid OS keeps most of its governance state inside .rapid-os/, leaving visible the artifacts that must be versionable, inspectable and auditable.

Main structure

project/
├── .rapid-os/
│   ├── config.json
│   ├── project.json
│   ├── setup.json                  (onboarding state; written by `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                (active run; local state)
│   └── scratch/                    (local state of the porcelain layer)
│       ├── checks/<run-id>/<n>.log
│       ├── hooks.json
│       └── hooks.log
├── .claude/skills/  .agents/skills/  .cursor/skills/  .github/prompts/   (shortcuts)
├── .claude/settings.json                                                 (Claude Code hooks)
├── docs/
│   ├── PRODUCT_BRIEF.md            (onboarding doc: brief)
│   ├── BUSINESS_RULES.md           (onboarding doc: business)
│   ├── DATA_MODEL.md               (onboarding doc: data-model)
│   └── ARCHITECTURE.md             (onboarding doc: architecture)
├── SPECS.md
├── TASKS.md
├── ACCEPTANCE.md
├── references/
└── harness-specific files

Not all files exist from the start; they appear when the corresponding module is used.

Porcelain layer files (shortcuts)

Path	Who writes it	What it contains
.rapid-os/session.json	rapid start writes it; rapid abort deletes it	The active run: active_run_id, mode, harness, start_head and, if applicable, start_untracked and workspace_path. rapid finish does not touch it: that is why a second rapid finish finds the run already finished. Local state: not versioned.
.rapid-os/scratch/checks/<run-id>/<n>.log	rapid check	The full output of each command run with rapid check. The evidence (rapid:check) is recorded in .rapid-os/evidence/; the log is only a support.
.rapid-os/backups/<file>.<timestamp>.bak	rapid init, rapid setup (doc, finish) and the commands that regenerate CLAUDE.md, AGENTS.md, .cursorrules, INSTRUCTIONS.md and .agent/rules/constitution.md	The copy of the previous agent file. It is only created if the content changes, the 5 most recent per file are kept and they are not versioned.
.rapid-os/generated.json	rapid setup, rapid init	SHA-256 of each agent file Rapid OS generated (CLAUDE.md, AGENTS.md...), to tell one edited by hand (RAPID1427; line endings do not count). It is versioned with the project, so the check works in a clone.
.rapid-os/scratch/hooks.json	rapid hook	Guard of the Stop hook (prevents continuation loops).
.rapid-os/scratch/hooks.log	rapid hook	One line per hook decision; rotates to hooks.log.1.
.claude/skills/<name>/SKILL.md	rapid shortcuts install	Claude Code shortcuts.
.agents/skills/<name>/SKILL.md	rapid shortcuts install	Codex and Antigravity shortcuts (they share a folder).
.cursor/skills/<name>/SKILL.md	rapid shortcuts install	Cursor shortcuts.
.github/prompts/<name>.prompt.md	rapid shortcuts install	VS Code / Copilot shortcuts (prompt files).
.claude/settings.json	rapid shortcuts install --hooks, rapid init --hooks	The Claude Code Stop and PreToolUse hooks (rapid hook stop, rapid hook pre-tool). They are merged with your existing configuration.
../<repo>-<run-id>	rapid start --worktree	Isolated git worktree of the run, on the branch rapid/<run-id>; its path is stored in the session's workspace_path. It is a sibling directory of the repository, not a subfolder.

Adding the following to .gitignore is recommended:

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

rapid init and rapid setup finish add the missing lines to an existing .gitignore (they do not create one if there is none). The last three keep tool artifacts from being mistaken for project changes; even so, rapid finish ignores them by name even if they are not in the .gitignore (see file_change).

It is a good idea to version the shortcut files and .claude/settings.json, so the whole team uses the same workflow. rapid shortcuts remove deletes only files with the marker <!-- generated by rapid shortcuts -->.

Legacy context files

rapid init can generate files such as:

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

It also maintains standards inside .rapid-os/standards/.

Onboarding documents

Four documents in docs/ enter the context as sources of their own (rapid context and the agent files), with their provenance visible. See Project documents and their provenance.

Context source	Path	Priority	Type	Tags
doc.brief	docs/PRODUCT_BRIEF.md	high	product	product, feature, spec
doc.business	docs/BUSINESS_RULES.md	high	business	business, domain, product
doc.data-model	docs/DATA_MODEL.md	medium	data_model	data, database, backend, domain
doc.architecture	docs/ARCHITECTURE.md	high	architecture	architecture, topology, backend, frontend

A file in docs/ counts only if its frontmatter has rapid-doc: <id> with the id from the table (many repositories already have their own docs/, and Rapid OS itself has one). The frontmatter is never injected into the content. The path and priority come from the banks in templates/setup/docs/.

Immutable artifacts

The v3 registries prioritize append-only and digest integrity.

Examples:

• Spec revisions are not edited in place;
• historical RunState snapshots are not overwritten;
• Evidence records use sequential IDs;
• evaluation reports are added per revision;
• Evidence artifacts are copied and verified by SHA-256 and size.

Read-only commands

Examples:

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

Porcelain layer verbs

Class	Verbs
Read-only	rapid next, rapid status, rapid shortcuts list
Write state	rapid start, rapid check, rapid task, rapid attach, rapid finish, rapid approve, rapid abort, rapid shortcuts install, rapid shortcuts remove

rapid next and rapid status only read the ledger and the session. rapid check runs the command you pass it (or the test_command from .rapid-os/config.json) and records evidence; rapid start --worktree also creates the worktree. rapid hook only writes to .rapid-os/scratch/.

Some commands change behavior with flags. For example, rapid scan is read-only unless --write is used, and rapid eval run only persists a report with --write.

Commands that write state

Examples:

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

See the CLI reference for the exact flags and contracts of each command.

Path protection and backups

Rapid OS validates path containment to prevent path traversal and symlink escapes in the governed registries. Legacy operations that overwrite certain files use .bak backups where appropriate. The agent files that Rapid OS regenerates (CLAUDE.md, AGENTS.md, .cursorrules, INSTRUCTIONS.md, .agent/rules/constitution.md) leave no .bak in the project root: their previous copy goes to .rapid-os/backups/, only if the content changed, and the 5 most recent per file are kept.

Catalog stacks

Each topology component has its own stack (see Stacks and components). rapid init --stack <id> and rapid setup set stack <id> [--component <c>] write the templates/stacks/<component>/<id>.md template of each chosen stack to .rapid-os/standards/tech-stack.md, and the <id>.json sidecar declares its factors, sources, compatible topologies and supported services.

Component	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 only with doc-site
all	generic (no template: generated from what the scanner detects) and custom (the tech-stack.md written by the agent)

The previous ids (python-api, python-ai, nodejs-ai, web-modern, frontend-creative) are still accepted; see the migration guide.

rapid validate recognizes the stack by the mark <!-- rapid-stack: backend=go --> that Rapid OS writes at the end of each tech-stack.md block, and in an older file by its heading (TECH STACK: PYTHON API...).

Path safety protects Rapid OS artifacts, but it does not replace the permission controls of the operating system or of the environment where the coding harness runs.