rails

Files (1)

• SKILL.md

SKILL.md (first lines)

# The rails loop

One line of work = one claim, one worktree, one branch, one PR, many commits.

1. **Claim** before the first source edit: `rails claim "#123"` · `--milestone "<title>"` · `--adhoc "<line>"`.
   For an issue, `rails work from-issue 123` turns its Done-when lines into the work items this line owes.
   `rails claim --list` shows what sibling worktrees hold; join one rather than cut a second branch.
2. **Intent.** Write `.rails/intent.md` from `rails template intent` (tier `fix` for a
   small fix). End the turn SHOWING it, with its `intent:<hash>` line. The operator's next message
   acks it or corrects it; a correction means rewrite and show again. An agent's push refuses without
   an acked intent (`prepush_intent`).
3. **Walls first.** A new seam's first commit adds its declaration (contract, settings row, auth row,
   concept row, limit name) before code that uses it.
4. **Build and commit.** Tests red first, as the production role, on planted data. Commit freely:
   rails never blocks a commit.
5. **`rails check`** runs every lane the diff selects (`rails/lanes.toml`) and seals a marker for
   HEAD. Long lanes: run it in the background, or one lane at a time with `--lane`. A lane that
   cannot run (Docker down) fails with that reason: fix the environment, never skip it.
6. **Push.** The pre-push hook wants the marker (`--quick` before a PR exists, full after). No
   consent ceremony; the operator's word is `hold`.
7. **Review** a change to anything but prose: run the `rails:reviewer-coop` and `rails:reviewer-adversary`
   agents on the diff (each given only the diff and the intent), save each report, then
   `rails review record --coop <file> --adversary <file>` (on a clean, committed tree: the voices read the
   disk). Fix every must-fix first; a new commit needs a new review, because the receipt is for HEAD's
   tree. Once the PR is open, review a commit BEFORE pushing it: auto-merge merges whatever is pushed,
   so pre-push refuses an unreviewed code tree to an open PR (`ship_review`). A must-fix you judge wrong
   is recorded with `--accept "<why>"`; `rails ship` puts the reason in the PR body.
8. **`rails ship --closes <n>`** opens one Ready PR from the intent (and imports #n's Done-when lines), arms auto-squash, and posts the
   `rails/<lane>` statuses CI verifies. Then bind the monitor and run `rails work monitor-bound`.
   After a later push: `rails check --post`. A finding the PR leaves open is its own issue: each bullet
   under a section like "Findings left for later" carries `#N`, or `no-issue: <reason>` for an answer
   that is not a finding, or ship refuses (`ship_findings`).
9. **Walk** the named target: `rails walk`. An item closes only when its `step:` id passes:
   `rails work done <id>`.
10. **Stop** only with the work done or a recorded reason:
   `rails work stop decision_needed "<problem; options with costs; recommended first>"` | `blocked` | `hold` | `wip`.

Other commands: `rails whereis <term>` before saying anything does not exist; `rails receipt -- <cmd>`
to make a claim checkable; `rails metrics` for the four numbers before/since the cut, CI spend and gate
yield; `rails state`; `rails doctor`; `rails sync` (main checkout to trunk, when safe); `rails history
status` (worktrees on rewritten-away history: never push from one, cherry-pick onto a fresh worktree).
Templates (one set, no other): `rails template` lists intent, spec, adr, milestone, rulebook and the PR
template. A milestone closes with `rails close <n>`, which needs the operator's `used #<n>` and no open
issue. Retiring a hook script: `rails retire-hook <path>` (a deleted one blocks older worktrees).
The operator's words are typed in a prompt: `used #75 <task>`, `hold`, `release`, `approve`.
`rails close` honours only a `used` from a prompt, and a hold set in a prompt lifts only by `release`
in a prompt: nothing on a command line tells the operator's terminal from an agent's tool call (an
agent can clear `CLAUDECODE`, and its calls report a TTY on Windows). `rails used 75 <task>` from a
shell is recorded as `by: shell`, for the record only. `rails snapshot` and `rails enable` are the
operator's commands. `rails hold` anyone may ask for. An agent never sets or clears `CLAUDECODE`
(`operator_bounds`).

New app: `rails new <app>` gives a walking skeleton with contracts, settings, roots, clock, limits,
concepts and the auth matrix already enforced; its first milestone's step 0 is the operator using it.

From vancourse/apex, MIT.

More from vancourse/apex