Helix Rails

Orchestrator cloud context (check before setup)

If HELIX_ORCHESTRATOR_RUN_ID or HELIX_SKILL_CREDENTIAL_FILE is set, this skill runs in Helix Console. This section takes precedence over local setup and browser instructions below.

• First call the plugin's bin/helix orchestrator-protocol (Windows: bin/helix.cmd orchestrator-protocol). It must print 1. Otherwise stop with an actionable request to update the Helix plugin/CLI; never run an older binary's setup commands.
• Use the normal helix <surface> up, push, state, and wait commands. The CLI selects cloud transport and the assigned project automatically. Keep the same slug within this task.
• Do not start local servers or Fleet, open a browser, curl localhost, use --local, log in, or change profiles/projects. Do not read or print the credential file. Do not remove the injected environment variables.
• up returns the Console session URL. Use that URL wherever the local instructions request Board/Fleet links. Events go to Console; human responses and gate approvals still come from the person through the normal wait protocol.
• On cloud or compatibility errors, report the error. Never fall back to local mode. Outside this context, follow the local behavior below unchanged.

Rails are how a team tells its agents how we do things here, graded by how hard each one binds. Memory informs and blocks nothing; Rails bind — a rail in scope is the standard the work is judged against, and where hooks are installed the platform refuses on its behalf.

One file, one rail. Eight kinds, four modes:

refuse stops the act. gate asks a person. check warns and records. guide informs and is cited.

Setup

Call the binary by its full path every time:

${CLAUDE_PLUGIN_ROOT}/bin/helix rails <verb> [flags]

On Windows, ${CLAUDE_PLUGIN_ROOT}\bin\helix.cmd in place of bin/helix; the rest of the command is the same.

Never put it in a shell variable or function. The skill pre-approves this command, and that approval stops matching past a variable assignment — wrap it and every call prompts instead. Prose below names commands as rails <verb>; run them with the full path.

One store per machine, at ~/.helix/rails, with two layers: global (every project on this machine) and project, named by the repo's .helix/project file — or the directory name when there is none. Project overrides global. Nothing else is written into the repo.

The first thing every session does

${CLAUDE_PLUGIN_ROOT}/bin/helix rails for --surface <loop|arena|swarm|canvas|stream|spark|all>

Read what comes back as binding. It lists every ratified rail that applies to this project and this surface, first paragraph each, with its id, kind and mode — and any waiver that relaxes one. Cite rail ids when you act on them (per rail no-force-push), and when a playbook applies, follow its steps and report progress against them in your status.

Need the full text — a playbook's steps, a template's body?

${CLAUDE_PLUGIN_ROOT}/bin/helix rails get <id>

What you may and may not do

A proposal is a draft on the board, marked proposed by you, binding nothing until a person ratifies it. Humans author rails; you may suggest them.

The commands

${CLAUDE_PLUGIN_ROOT}/bin/helix rails for --surface <name> [--tool Bash] [--path src/…] [--format json]
${CLAUDE_PLUGIN_ROOT}/bin/helix rails get <id>
${CLAUDE_PLUGIN_ROOT}/bin/helix rails list [--kind K] [--status S] [--scope global|project]
${CLAUDE_PLUGIN_ROOT}/bin/helix rails propose      # a rail file on stdin → status: proposed
${CLAUDE_PLUGIN_ROOT}/bin/helix rails report <id> --ok|--failed --evidence "…"
${CLAUDE_PLUGIN_ROOT}/bin/helix rails seed <nestjs|react> [--layer global|project]   # a starter pack; never overwrites an edited rail
${CLAUDE_PLUGIN_ROOT}/bin/helix rails up [--no-open]   # the board, for the person

Seeding is the one write you may do on a person's say-so: when they ask for the NestJS or React starter rails, run seed and list what it wrote. Each seed is an ordinary rail afterwards — theirs to edit, retire or restore.

Every verb takes --dir <projectDir> when the project is not the cwd.

Proposing a rail

Propose only what a person would otherwise have to say twice. The file is frontmatter and a body:

---
id: commit-format
kind: standard
mode: check
scope: project
applies:
  surfaces: [all]
  tools: [Bash]
  match: "git commit"
owner:
---

Commit subjects are imperative, under 72 characters, no trailing period.

## When it fires
Rewrite the subject before committing; do not amend history to fix it later.

printf '%s' "$RAIL" | ${CLAUDE_PLUGIN_ROOT}/bin/helix rails propose --agent claude --model <model-id>

Say in chat that you proposed it and why. The person ratifies or declines on the board; you never do.

Checklists and evidence

A checklist rail lists what "done" means. When its items hold for your work, report it with the evidence a critic could check:

${CLAUDE_PLUGIN_ROOT}/bin/helix rails report definition-of-done --ok --evidence "pnpm test: 84 passed; screenshots in audit"

Where the Stop hook is installed, an unreported checklist keeps the turn from ending. A report without evidence is the one thing worse than no report.

Hooks

Rails work without hooks — rails for is the contract every skill keeps. With rails install a person wires the same store into Claude Code so the platform enforces it: refuse rails block a tool call before it runs, gate rails turn it into a question for the person, check rails warn after, and open checklists hold the Stop. Installing, uninstalling and what is mandatory for an organisation are the person's decisions, not yours.

What Rails is not

• Not Memory. A fact goes to Memory; a rule goes to Rails. Never express a rule as a memory — it silently will not apply.
• Not a place to record what you did. That is the session's log and Archive.
• Not yours to edit. A rail you disagree with is a conversation with the person, then a proposal.

Sharp edges

• Read rails for at the start, not when something goes wrong. A refusal you meet mid-task was almost always a rail you could have read.
• A waiver has an expiry. Past it the rail binds again; do not rely on one you read an hour ago.
• --surface all is for session start; inside a surface name it, so surface-specific rails reach you.
• Exit 3 means the rail does not exist in any layer; check rails list before proposing a duplicate.