WorkRail

Agents on rails. Tickets in, reviewed work out.

WorkRail is a GitHub-native execution layer for AI agents, engineering teams, and product operators. It lets an agent pick up a real ticket, execute the work, validate the result, and move the ticket through a lifecycle.

No SaaS. No dashboard. No orchestration server. Just files, folders, scripts, validation, and logs.

What This Actually Does

This repo turns agent work into a deterministic loop:

1. Pick a real ticket from tickets/todo.
2. Move it to tickets/in-progress.
3. Execute the smallest safe change.
4. Run validation.
5. Move it to tickets/review.

Tickets are the unit of work. Folders are the state machine. Scripts are the transition functions. Logs are the audit trail.

60-Second Demo

Clone it and run the built-in demo agent:

git clone https://github.com/bennewell35/workrail
cd workrail
./scripts/reset-demo.sh
./scripts/run-agent.sh --agent ./scripts/demo-agent.sh

What you will see:

• A ticket moves from tickets/todo to tickets/in-progress.
• The demo agent fixes examples/demo-app/status.md.
• Validation runs.
• The ticket moves to tickets/review.
• The Work Log records what happened.

Inspect the result:

./scripts/agent-status.sh
git diff -- tickets examples

Reset and replay:

./scripts/reset-demo.sh

Bring Your Own Agent

Use any local agent command that can accept a ticket path:

./scripts/run-agent.sh --agent "your-agent-command"

run-agent.sh passes the active ticket path as the final argument and exposes:

AGENT_ROOT=/path/to/repo
AGENT_TICKET=/path/to/active-ticket.md

If no agent command is supplied, run-agent.sh still selects and starts the next ticket, then prints the active ticket path for manual execution.

Why This Is Different

Common agent workflows	WorkRail
Prompt-driven	Ticket-driven
Invisible state	Folder-based state
Vague scope	Markdown contract
Optional validation	Validation gate
Hard to audit	Append-only Work Log
Hosted workflow dependency	Local-first files

This is not an agent framework. It is an execution layer for real work.

Who It Is For

• Developers who want agents to work from clear tickets instead of loose prompts.
• Engineering leads who need state, validation, and auditability before trusting agent work.
• Product operators who want ideas, bugs, and customer feedback converted into executable work.
• Small teams that want issue-tracker discipline without another hosted system.

The Mental Model

WorkRail turns a repo into a workflow engine:

• Tickets are contracts.
• Folders are state.
• Scripts are transitions.
• Validation is the gate.
• Work Logs are the audit trail.

If an agent can read files and run commands, it can run on WorkRail.

Quick Start

Create a ticket:

./scripts/new-ticket.sh TICKET-002 "Fix login loading state" high

Start it:

./scripts/start-ticket.sh TICKET-002

Validate before review:

./scripts/validate.sh
./scripts/review-ticket.sh TICKET-002

Folder Model

tickets/
  todo/
  in-progress/
  blocked/
  review/
  done/

templates/
scripts/
docs/
sops/
skills/
logs/
decisions/
examples/

Ticket state is the folder the file lives in. The status field in frontmatter must match the folder.

Ticket Lifecycle

flowchart LR
  A["todo"] --> B["in-progress"]
  B --> C["review"]
  C --> D["done"]
  B --> E["blocked"]
  E --> B

Loading

Core Commands

./scripts/agent-status.sh
./scripts/new-ticket.sh TICKET-002 "Title" high
./scripts/start-ticket.sh TICKET-002
./scripts/run-agent.sh --agent ./scripts/demo-agent.sh
./scripts/block-ticket.sh TICKET-002 "Missing API credentials"
./scripts/review-ticket.sh TICKET-002
./scripts/complete-ticket.sh TICKET-002
./scripts/validate.sh

Operating Rules

• Work one ticket at a time.
• Make the smallest viable change.
• Keep work logs append-only.
• Move tickets by script or by physically moving files.
• Do not push, merge, deploy, or rewrite ticket history unless the human explicitly approves.
• If requirements are unclear, block the ticket instead of guessing.

Integrations

This repo is tracker-neutral.

• Use docs/linear-import.md to map Markdown tickets to Linear.
• Use docs/personal-automation-agent.md to convert repeated workflows into approved, versioned skills.
• Use source links in ticket frontmatter to connect issue trackers or docs.
• Keep this repo as the durable execution layer even when the external tracker is the stakeholder-facing layer.

Launch Thread

Use docs/launch-thread.md for a copy-ready X thread and demo recording checklist.

Roadmap

See ROADMAP.md.

Contributing

See CONTRIBUTING.md.

License

MIT.