Rail Skills

English | 中文

Local-first Agent Skills for a clear engineering flow: align → spec → slice → build. All rail docs (work artifacts, glossary, ADRs) live under docs/monorail/ — no GitHub/GitLab Issues dependency.

Install

Via skills.sh / the Skills CLI:

npx skills add guangzan/monorail

In each business repo, run /rail-setup once before other rail engineering skills.

Main chain

/rail-align ─┬─ light ──→ align.md  ══╗
             └─ map   ──→ decisions* ═╩══→ /rail-spec ══→ /rail-slice ──→ /rail-build*

══→ auto-continues in the same session (planning chain). * marks the next step as user-triggered: /rail-build runs frontier tasks serially in one session (fresh implementer sub-agent per non-trivial task; no fresh session required). Concurrent builds require one git worktree per task (same cwd is forbidden). /rail-spec refuses to write without align.md or a cleared map.

Skills

Main chain

Skill	Role
rail-setup	Configure all rail docs under docs/monorail/
rail-align	Align (light → align.md; or map mode)
rail-spec	Write spec.md from align.md / cleared map
rail-slice	Break spec.md into tasks/NN-*.md with blockers
rail-build	Implement tasks serially in one session (parallel ⇒ worktrees)

Side paths & helpers

Skill	Role
rail	Router — which skill/flow fits
rail-grill	Stateless grilling
rail-pass	Cross-session pass document
rail-debug	Hard-bug diagnosis loop
rail-review	Standards + Spec review (opt-in; not part of build)

Vocabulary

Skill	Role
rail-tdd	Red-green-refactor (also used inside build)

Acknowledgments

Ideas and inspiration from mattpocock/skills and obra/superpowers.