Shortcuts by harness

Shortcuts are the main Rapid OS workflow. The first one is /rapid-init: your agent drives the whole project onboarding with rapid setup (stack, topology, archetype, agents, test command and documents). After that there is one command per mode (/rapid-feature, /rapid-bugfix…) that your agent runs to take the work from start to finish inside a governed run. You describe the goal; the shortcut teaches the agent the loop (rapid next → rapid start → rapid check → rapid finish) and stops when a person is needed.

The v3 commands (rapid spec, rapid run, rapid evidence, rapid eval…) remain available as Advanced mode: CI, debugging and auditing. They are described in the CLI reference and in the manual flow of each mode guide.

Install them once for all your projects (the Rapid OS installer asks you at the end; replace claude with your agent):

rapid shortcuts install --global --harness claude

In VS Code, or if you prefer to version them with the repository, install them in the project with rapid init --shortcuts. Then, in your agent:

/rapid-init Billing API for small businesses, in Python   # onboarding (in Codex: $rapid-init)
/rapid-feature add CSV export to the monthly report

rapid must be on the PATH

Shortcuts and hooks run rapid from the agent's shell. If it does not resolve, rapid init and rapid doctor warn with RAPID1414 (not an error: exit 0). Install it with the installer or with pipx install git+https://github.com/alyconr/Rapid-OS.git.

1. Installation

The files are generated from a single source (templates/shortcuts/), one per harness and shortcut.

rapid init --shortcuts                                  # on init, for the chosen agents
rapid shortcuts install                                 # for the "tools" harnesses in .rapid-os/config.json
rapid shortcuts install --harness claude --harness codex
rapid shortcuts install --harness claude --hooks        # also the Claude Code hooks
rapid shortcuts install --harness claude --dry-run   # what it would write, without writing
rapid shortcuts install --harness claude --only rapid-init   # only one shortcut
rapid shortcuts install --global --harness claude   # all 9, in your user folder (see below)
rapid shortcuts list                                    # status of each file: installed, outdated, missing, unmanaged
rapid shortcuts remove --harness codex                  # removes only what was generated

Without --harness, the supported harnesses listed in tools of .rapid-os/config.json are used. In a project without that file you must pass --harness (RAPID1312).
Each file carries the marker . remove deletes only files with that marker and leaves yours untouched.
Installation is idempotent: if the content is the same it writes nothing; if it differs, it saves a .bak copy before replacing.
rapid init --shortcuts does not install hooks; they are requested with --hooks (in rapid init or in rapid shortcuts install).
Shortcuts for modes that have no playbook in templates/modes/ are skipped (RAPID1315); today all five exist.

User-level installation (`--global`)

rapid shortcuts install --global --harness <id> [--only rapid-init] writes the shortcuts to the skills folder of your user (under your home folder), so /rapid-init works in any project without installing it in each one. It needs --harness (it does not read any project's config), and list and remove accept the same --global. --hooks (Claude Code) is accepted only inside a project: it installs the skills for the user and the hooks in the project's .claude/settings.json, without copying the skills there; outside a project it is RAPID1413. It is only available where the harness's official documentation gives the folder:

Harness	User folder	Source
`claude`	`~/.claude/skills/<name>/SKILL.md`	Claude Code skills
`codex`	`~/.agents/skills/<name>/SKILL.md`	Codex skills
`cursor`	`~/.cursor/skills/<name>/SKILL.md`	Cursor skills
`antigravity`	`~/.gemini/config/skills/<name>/SKILL.md` (Antigravity App and IDE; the Antigravity CLI reads `~/.gemini/antigravity-cli/skills/`, which `--global` does not write)	Antigravity skills
`vscode`	Not supported: the prompt files documentation only says "Your user data (specific to your VS Code profile)", with no path.	VS Code prompt files

Requesting --global for vscode (alone or together with others) gives RAPID1413 and writes nothing. rapid setup finish does the project half by itself when claude is among the agents: it installs the hooks in the project and no skills, so each /rapid-* shows once. If the same /rapid-* ends up both in your user folder and in the project, rapid shortcuts install and rapid doctor warn with RAPID1321 and say which side to remove (rapid shortcuts remove --harness claude or rapid shortcuts remove --global --harness claude). install.sh and install.ps1 offer this step at the end (only if there is an interactive terminal, and never by default).

Reinstall after updating Rapid OS

Shortcuts are project files: a new version of Rapid OS may change their templates. After updating:

rapid shortcuts list        # the ones that changed show up as "outdated"
rapid shortcuts install     # updates them (with .bak) and leaves the up-to-date ones alone

It is a good idea to version the generated files alongside the code, so the whole team uses the same workflow.

2. Harnesses: which folder is generated and how it is invoked

Everything comes from the adapters in rapid_os/adapters/agents/; each row cites the harness's official documentation.

Harness (`--harness`)	Generated folder	How it is invoked	Official documentation
`claude` (Claude Code)	`.claude/skills/<name>/SKILL.md`	`/rapid-init`, `/rapid-feature <goal>`; typing `/rapid-` shows all 9	Claude Code skills
`codex` (Codex CLI and IDE extension)	`.agents/skills/<name>/SKILL.md`	`$rapid-init`, `$rapid-feature <goal>`, or pick it from `/skills`. In Codex CLI, `/` does not list skills: use `$` (details)	Codex skills
`antigravity` (Google Antigravity)	`.agents/skills/<name>/SKILL.md` (the same folder as Codex)	`/rapid-feature <goal>`	Antigravity skills
`cursor` (Cursor)	`.cursor/skills/<name>/SKILL.md`	`/rapid-feature <goal>` in the Agent chat	Cursor skills
`vscode` (VS Code / Copilot)	`.github/prompts/<name>.prompt.md` (prompt files)	`/rapid-feature <goal>` in the chat	VS Code prompt files

What each harness does with the shortcut:

Harness	Runs the `context-command` on its own	Hooks
`claude`	Yes: !`rapid setup next --json` (or `rapid next --json`) runs before the prompt; if it fails, the skill aborts.	Only here (`--hooks`).
`codex`, `antigravity`, `cursor`, `vscode`	No: the text asks the agent to run the command itself.	There are no Rapid OS hooks.

Details worth knowing:

Codex and Antigravity share .agents/skills. If you select both, each file is written only once.
Only Claude Code runs the !`rapid next --json` line before sending the prompt (and if that command fails, the skill aborts, so rapid must be on the PATH). In the other harnesses the text asks the agent to run rapid next --json first.
rapid-approve carries disable-model-invocation in Claude Code and Cursor, which document it: only the person launches it, the agent does not invoke it on its own.

If you combine harnesses

Some tools read more folders than their own, according to their official documentation:

Tool	Skills folders it reads (project)	Source
Cursor	`.cursor/skills/`, `.agents/skills/` and, for compatibility, `.claude/skills/` and `.codex/skills/`	Cursor: skills
VS Code / Copilot	`.github/skills/`, `.claude/skills/`, `.agents/skills/` (in addition to the `.github/prompts/` prompt files)	VS Code: agent skills

Cursor added Agent Skills in 2.4; use Cursor 2.4 or newer for /rapid-* skills. Cursor 1.1.6 predates that support. Source: Cursor 2.4 changelog.

That is why selecting cursor or vscode together with claude, codex or antigravity leaves the same /rapid-* in two folders that tool reads. The official Cursor and VS Code documentation does not specify how they display two skills with the same name in different folders (the VS Code one only says that, for marketplace skills with the same name in another location, both appear on its Skills page), so it is not claimed here that the menu duplicates them. rapid shortcuts install, rapid shortcuts list and rapid init --shortcuts warn with WARNING RAPID1321 when your selection falls into this case. rapid shortcuts install and rapid doctor also scan project compatibility folders read by Cursor or VS Code and warn if a same-named /rapid-* already exists, even when only that reader is selected; user-level folders are excluded. The warning does not change the exit code or files. To avoid depending on it:

You use	Install	Note
A single tool	`--harness <its-id>`	No overlap.
Codex and/or Antigravity, and maybe Cursor or VS Code	`--harness codex` (or `antigravity`)	`.agents/skills` is read by all four tools; there is no need to add `cursor` or `vscode`.
Claude Code and Codex/Antigravity	`--harness claude --harness codex`	No documented overlap: Claude Code documents `.claude/skills` and Codex `.agents/skills`.
Claude Code and Cursor or VS Code	`--harness claude`	Cursor and VS Code read `.claude/skills`. In them the !`rapid next --json` line is not documented as executable: the agent must run `rapid next --json` itself. If you prefer each tool's own variant, add `cursor` or `vscode`, knowing the same shortcut will live in two folders.

3. The 9 shortcuts

Shortcut	What it does	Argument
`rapid-init`	Drives the project onboarding with `rapid setup`: decisions, documents (drafted, pasted or skipped) and closing. It never confirms a draft for you.	Project description (optional).
`rapid-feature`	Implements a feature with a governed run (`feature` mode).	Feature goal.
`rapid-bugfix`	Fixes a bug: reproduces it first with a failing test (`bugfix` mode).	Bug description.
`rapid-refactor`	Refactors without breaking tests that pass (`refactor` mode).	Refactor scope.
`rapid-hardening`	Hardens security or robustness in an isolated worktree (`hardening` mode).	Area to harden.
`rapid-research`	Research spike, no required tests (`research` mode).	Question or topic.
`rapid-next`	Continues the active run with the next deterministic action.	None.
`rapid-status`	Summarizes the active run: tasks, gates and last verdict (read-only).	None.
`rapid-approve`	Does not approve: shows the pending human gates, the evidence and the command for your terminal.	Optional: the gate (`gate.final-verification`).

What each mode's playbook does is in the modes guide.

4. The loop they follow

The mode shortcuts teach only these steps; they do not list low-level commands:

rapid next --json: returns the next action (action.kind: author_spec, run_baseline, activate, implement_task, verify, await_human_approval, finish, done or blocked).
author_spec: the agent writes the spec from your goal, following the mode's template (action.spec_template), and passes it via stdin to rapid start <mode> --spec-file -. With no active run, rapid next only knows the feature template; the other shortcuts request theirs with rapid start <mode> --json.
action.command: if present, it is run. In implement_task the agent implements only that task and runs action.after (rapid task done …). Tests are always run with rapid check -- <command> so that evidence is recorded.
It repeats until done or await_human_approval; then the agent summarizes the evidence and asks you to run rapid approve <gate> in your terminal. rapid finish closes the run when nothing is left pending.
It never runs rapid approve, rapid abort, rapid run gate or rapid evidence add, and never edits .rapid-os/.

The reason for the last rule: approving a human gate, aborting a run or registering evidence by hand are decisions for a person. If the agent could do them, evidence and approvals would stop meaning anything. When rapid next returns blocked with the rapid abort command (because a review was rejected), the agent explains the reason and waits for your decision.

5. Human approval

Shortcuts ask for approval only when action.kind is await_human_approval. awaiting_human lists the contract's human gates from the start of the run, so with open tasks it already carries gate.final-verification: requesting it then gives RAPID1014 (and rapid approve adds a line with the task still in progress). When the time comes, the agent gives you the exact command with the gate id and you run it in another terminal, outside the agent.

/rapid-approve approves nothing. It reads rapid status --json, shows you the pending human gates with the evidence that backs them and gives you the exact command for your terminal:

rapid approve gate.final-verification                                  # approve
rapid approve gate.review --waive --reason "covered by the audit"        # waive (waivable gates only)
rapid approve gate.review --reject --reason "edge cases missing"         # reject: the gate stays FAIL in that run

Without arguments, rapid approve lists the pending gates. Changing a gate fails with RAPID1310 in these cases:

No TTY: the input is not an interactive terminal (for example, a command launched by an agent or through a pipe).
From Claude Code's ! mode: there claude is an ancestor process and rapid approve refuses.
Under an agent: CLAUDE_CODE_CHILD_SESSION=1, or claude as an ancestor of the process.

The solution is always the same: run it yourself in your own terminal (an editor's integrated terminal works). The ancestor check is best-effort; the rule is that a person approves in their terminal. The details are in product boundaries.

6. Claude Code hooks

The Stop and PreToolUse hooks (optional, Claude Code only) keep the agent from stopping midway through a run and deny it the commands reserved for the person and the editing of .rapid-os/: rapid shortcuts install --harness claude --hooks. All the detail is in section 6 of the Claude Code integration.

7. Common problems

The full catalog of codes is in diagnostics; these are the ones shortcut users will see most.

Code	What it means	Fix
`RAPID1301`	There is no `test_command` in `.rapid-os/config.json`.	`rapid init --test-command "<cmd>"` or add it to the config as an argv list.
`RAPID1307`	There is no active run (`.rapid-os/session.json`).	Start one with `/rapid-<mode> <goal>` or `rapid start <mode>`.
`RAPID1308`	There is already an unfinished active run.	Continue with `/rapid-next`, or cancel it yourself with `rapid abort` in your terminal.
`RAPID1310`	`rapid approve` without a TTY, from Claude Code's `!` mode or with `claude` as an ancestor.	Run it in your own terminal (section 5).
`RAPID1312`	No harness selected to install.	`--harness <id>` or `rapid init --agents <list>`.
`RAPID1413`	`--global` for a harness with no documented user folder (`vscode`), without `--harness` or with `--hooks` outside a project; or an `--only` with a nonexistent shortcut. Nothing is written.	Install in the project (without `--global`), or pass `--harness` and a name from the table in section 3.
`RAPID1414`	Warning: `rapid` is not on the `PATH` and shortcuts or hooks are installed.	Install Rapid OS with the installer or with `pipx install git+https://github.com/alyconr/Rapid-OS.git`.
`RAPID1315`	A mode shortcut was skipped because that mode has no playbook.	Informational; run `rapid shortcuts install` again once it exists.
`RAPID1320`	`rapid check --expect fail` without a task (or tied to a gate).	Pass `--task T001` or leave exactly one task in progress.
`RAPID1321`	Warning: the selection leaves the same `/rapid-` in two folders that Cursor or VS Code read, or a `/rapid-` is installed both for the user and in the project.	Install only the combination recommended in the warning (see "If you combine harnesses"); it blocks nothing.
`RAPID1337`	`--hooks` without the `claude` harness.	Select `--harness claude` or remove `--hooks`.
`RAPID1339`	`rapid doctor`: hooks are installed but `rapid` is not on the `PATH`.	Install Rapid OS where Claude Code can see it or add its scripts directory to the `PATH`.

Without an error code:

Symptom	Cause	Fix
In Codex CLI, `/rapid-feature` does not appear when typing `/`.	In Codex CLI, `/` only lists Codex commands; skills are invoked with `$` or from `/skills`.	Type `$rapid-feature <goal>` (details).

1. Installation​

User-level installation (--global)​

Reinstall after updating Rapid OS​

2. Harnesses: which folder is generated and how it is invoked​

If you combine harnesses​

3. The 9 shortcuts​

4. The loop they follow​

5. Human approval​

6. Claude Code hooks​

7. Common problems​