Metadata-Version: 2.4
Name: ai-rail
Version: 0.1.0a15
Summary: A local-first workflow rail and portable project brain for AI-assisted development.
Project-URL: Homepage, https://github.com/afshinsb/ai-rail
Project-URL: Repository, https://github.com/afshinsb/ai-rail
Project-URL: Documentation, https://github.com/afshinsb/ai-rail/tree/master/docs
Project-URL: Changelog, https://github.com/afshinsb/ai-rail/blob/master/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/afshinsb/ai-rail/issues
Author: Afshin Saberi
License: Apache-2.0
License-File: LICENSE
Keywords: ai,chatgpt,claude,cli,codex,cursor,developer-tools,github,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.10
Requires-Dist: tomli>=2.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# AI Rail

[![Tests](https://github.com/afshinsb/ai-rail/actions/workflows/tests.yml/badge.svg?branch=master)](https://github.com/afshinsb/ai-rail/actions/workflows/tests.yml)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
[![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)](docs/RELEASE.md)

**Never explain your project twice to AI.**

AI Rail is a local-first CLI that keeps AI-assisted development focused, repeatable, and safe.

It gives every Git repo a portable project brain, a simple daily workflow, and scoped prompts for tools like ChatGPT, Codex, Claude, Cursor, and Aider - so you can move between AI tools without re-explaining the codebase, losing context, or letting the coding agent drift into unrelated files.

```text
rail n  -> start the next scoped task
rail v  -> review, run local checks, and create an audit prompt
rail s  -> safely commit, merge to default, push, and close
rail h  -> continue in a new AI chat with full project context
```

AI Rail keeps the coding agent on the active issue, keeps an AI reviewer (ChatGPT, Claude, or any LLM) in the audit loop, and lets your own machine run the tests - saving tokens, reducing over-coding, and making AI development feel controlled instead of chaotic.

<p align="center">
  <img src="docs/assets/ai-rail.png" alt="AI Rail overview" width="900">
</p>

## Prerequisites

- Python 3.10+ and [pipx](https://pipx.pypa.io/)
- [Git](https://git-scm.com/) with a configured remote
- [GitHub CLI (`gh`)](https://cli.github.com/) installed and authenticated (`gh auth login`)

AI Rail uses Git for repository state and delegates GitHub Issue operations to `gh`. Run `gh auth login` before using AI Rail on a new machine.

## Who This Is For

AI Rail is for developers who:

- use more than one AI coding tool on the same repo
- want GitHub Issues to be the task source of truth
- want repeatable prompts, review packs, checks, and handoffs
- prefer local-first tooling over hosted workflow state
- work solo or in small repos where conservative commit safety matters

## What AI Rail Is Not

AI Rail is not:

- an AI model, agent runtime, or hosted service
- a replacement for Git, GitHub Issues, or your test suite
- a project management system for large teams
- a tool that sends code to a remote service by itself
- a way to bypass review, checks, or secret-file safety

## Install

AI Rail is currently alpha software.

Recommended public install:

```bash
pipx install ai-rail
rail --version
rail demo
```

If `pipx` is not installed yet:

```bash
python -m pip install --user pipx
python -m pipx ensurepath
```

Restart your terminal, then run:

```bash
pipx install ai-rail
```

Latest source from GitHub:

```bash
pipx install git+https://github.com/afshinsb/ai-rail.git
rail --version
```

Contributor install from this source checkout:

```bash
git clone https://github.com/afshinsb/ai-rail.git
cd ai-rail
python -m pip install -e ".[dev]"
rail --version
```

## Quick Demo

Print the built-in walkthrough:

```bash
rail demo
```

Try the bundled demo app:

```bash
cd examples/demo-todo
rail init --stack node --project-name "AI Rail Demo TODO"
rail doctor
npm run check
# requires: gh auth login
gh issue create --title "Add todo body validation" --body-file issues/001-add-body-validation.md
rail next --copy
```

## Full Workflow

For a new repo with no scoped issues yet:

```bash
rail plan --copy
# paste into a GitHub-connected AI agent
```

The AI creates or updates one GitHub roadmap issue as the remote roadmap mirror and creates all issues for the first active execution slice.

```bash
rail import
# import the roadmap issue into local .rail/PROJECT.md
```

`.rail/PROJECT.md` is the full local project memory and roadmap brain. GitHub Issues are the active task execution queue, not the entire long-term roadmap.

Then work one issue at a time:

```bash
rail n
# paste into coding agent

rail v
# paste into AI reviewer

rail s "type(scope): message"
```

After several shipped issues, audit and update the phase:

```bash
rail phase --copy
# paste into a GitHub-connected AI reviewer/agent
```

The phase audit updates project memory, checks completed work against the roadmap, and creates all issues for the next active execution slice when needed.

```bash
rail import
# refresh local .rail/PROJECT.md from the updated roadmap issue
```

Then continue:

```bash
rail n
```

## 60-Second Quickstart

Inside any Git repo:

```bash
rail init --stack node --project-name "My Project"
rail doctor
rail resume
```

Daily loop:

```bash
rail next --copy
# paste/run the generated prompt in your AI coding tool
rail verify --copy
# paste the generated review prompt into any AI reviewer for audit
rail ship "type(scope): message"
```

Short alias loop:

```bash
rail n
# paste/run the generated prompt in your AI coding tool
rail v
# paste the generated review prompt into any AI reviewer for audit
rail s "type(scope): message"
```

`rail verify` runs checks and saves a verified snapshot of the reviewed diff. `rail ship` trusts that snapshot when the working tree still matches it, so the normal ship path does not rerun checks. Use `rail ship --recheck "type(scope): message"` when you intentionally want checks rerun during ship. `rail ship` closes the issue only after the issue branch is merged into the configured default branch and that default branch is pushed.

When switching AI tools or opening a new chat:

```bash
rail snapshot
rail handoff --for chatgpt --include-review --include-checks --copy
```

To update tool-specific AI instruction files from the same project brain:

```bash
rail export
```

## Core Commands

| Command | Purpose |
|---|---|
| `rail init` | Add AI Rail files to a repo |
| `rail resume` | Show where you stopped |
| `rail plan` | Generate a GitHub-connected AI prompt to create a phased issue roadmap |
| `rail import` | Import the GitHub roadmap issue into local `.rail/PROJECT.md` |
| `rail phase` | Generate a GitHub-connected AI prompt to audit/update the current roadmap phase |
| `rail next` | Start the next issue and generate the first prompt |
| `rail handoff` | Generate portable context for another AI session/model |
| `rail verify` | Capture review info, run checks, and generate an audit prompt |
| `rail ship` | Commit the issue branch, merge/push the default branch, then close and mark done |
| `rail snapshot` | Refresh `.rail/brain/` project-brain files |
| `rail export` | Generate `AGENTS.md`, `CLAUDE.md`, Cursor rules, `AIDER.md`, and Copilot instructions |
| `rail demo` | Print the public demo script |
| `rail release-check` | Check packaging/docs readiness |

Common aliases are thin wrappers over the long commands: `rail r` for `resume`, `rail n` for `next --copy`, `rail p` for `plan --copy`, `rail ph` for `phase --copy`, `rail im` for `import`, `rail v` for `verify --copy`, `rail s` for `ship`, `rail snap` for `snapshot`, `rail h`/`hc`/`hg`/`hl` for handoffs, `rail x`/`xd`/`xf` for exports, and `rail rc` for `release-check`.

Detailed commands such as `rail start`, `rail prompt`, `rail review`, `rail checks`, `rail commit`, `rail issue-close`, `rail done`, and `rail sync` remain available for manual control.

For Node repos, `rail init --stack node` inspects `package.json` scripts and chooses the first available check command from `check`, `typecheck`, `lint`, `test`, then `build`. You can override checks manually:

```bash
rail checks --run "npm run typecheck"
rail checks --run "npm run typecheck" --run "npm run lint"
```

## Portable Project Brain

`.rail/PROJECT.md` is the full local project memory, roadmap brain, phase tracker, and next-task direction file. The GitHub roadmap issue is the remote roadmap mirror. GitHub implementation issues are only the active execution queue.

`.rail/PROJECT.md` may contain human-readable context, but roadmap task state lives in exactly one `AI RAIL ROADMAP START/END` block. Rail only updates task status inside that strict block. Task lines use `- [ ] TASK_ID | ISSUE | TITLE`, where `TASK_ID` looks like `P1-T01` and `ISSUE` is `#123` for active GitHub issues or `TBD` for future tasks. The phase AI creates the next issue slice and replaces `TBD` with issue numbers during `rail phase --copy` / `rail import`.

`rail snapshot` writes:

```text
.rail/brain/PROJECT.md
.rail/brain/CURRENT_TASK.md
.rail/brain/STATUS.md
.rail/brain/RECENT_HISTORY.md
.rail/brain/HANDOFF.md
```

`rail handoff --for codex|chatgpt|claude|cursor|aider --copy` turns that brain into a paste-ready handoff so a new AI session can continue from the current project state.

## Tool-Specific Exports

`rail export` turns the single AI Rail project brain into files that different AI coding tools already know how to read:

```text
AGENTS.md
CLAUDE.md
AIDER.md
.cursor/rules/ai-rail.mdc
.github/copilot-instructions.md
```

Exports are safe by default. AI Rail updates its own managed block when markers are present, but refuses to overwrite existing human files unless you pass `--force`, which first writes a `.rail.bak` backup.

## Safety Defaults

`rail ship` refuses unsafe commits by default when:

- there is no passing verified snapshot from `rail verify`
- files changed after the last verified snapshot
- configured checks changed after the last verified snapshot
- dangerous/generated files such as `.env`, keys, local databases, `node_modules/`, `dist/`, or `.rail/state/` are changed

Escape hatches exist for advanced users, but the normal path is intentionally conservative.

## Local-First Privacy

AI Rail does not send your code anywhere by itself. It shells out to `git`, `gh`, and your configured local checks.

> **Security:** `rail verify` runs the check commands configured in `.rail/config.json` using the system shell. Always review `.rail/config.json` in repositories you did not author before running `rail verify` or `rail checks`.

By default, `.rail/state/history.jsonl` is ignored by git to avoid committing personal workflow history into team repos.

License: Apache License 2.0.

## Author

- Afshin Saberi
- GitHub: https://github.com/afshinsb
- Website: https://theafshin.com

## Docs

- [Quickstart](docs/QUICKSTART.md)
- [Install](docs/INSTALL.md)
- [Commands](docs/COMMANDS.md)
- [Workflows](docs/WORKFLOWS.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Release checklist](docs/RELEASE.md)
- [Roadmap](docs/ROADMAP.md)
