https://github.com/michaelasper/arise
https://github.com/michaelasper/arise
Last synced: about 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/michaelasper/arise
- Owner: michaelasper
- License: mit
- Created: 2026-04-07T00:35:49.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-12T02:46:11.000Z (3 months ago)
- Last Synced: 2026-04-12T03:09:25.180Z (3 months ago)
- Language: Rust
- Size: 2.7 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
- Roadmap: docs/roadmap.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Arise
[](https://github.com/michaelasper/arise/actions/workflows/ci.yml)
[](./LICENSE)
Arise is a Git-native orchestration engine for CLI coding agents. It turns serious software work into strict PRDs, reviewable YAML plans, isolated Git worktrees, durable run state, and recovery artifacts you can inspect after the model has stopped talking.
The pitch is simple: agent work should leave a trail. Arise gives you the trail.
Use it when you want coding agents to work from a real plan, touch the repo in isolated task worktrees, checkpoint completed phases, and leave enough evidence on disk for a human or a fresh agent to understand what happened next week.
Arise is local-first tooling. Install it once, point it at a repository, and use the `arise` binary from your normal shell. The first supported execution provider is the Codex CLI.
## Why Arise
Modern coding agents can move fast. That speed is only useful when the work is reviewable, resumable, and safe to integrate.
Arise is built around a few hard opinions:
- **Start from written intent.** Use a strict PRD, GitHub issue PRD, roadmap slice, existing YAML plan, or explicit supervisor goal.
- **Plan before mutation.** Generate a typed execution plan that can be reviewed before work starts.
- **Isolate task work.** Run tasks in Git worktrees instead of letting every agent write into the same checkout at once.
- **Persist the evidence.** Store plans, events, attempts, failures, gates, and recovery bundles under `.arise/`.
- **Recover from reality.** Inspect, cancel, resume, replay, or repair local runs without reconstructing the story from chat logs.
## What Works Today
Arise already supports the core local orchestration loop:
- `init`: write the default project config.
- `doctor`: check Git, Codex, Rust, workspace, and provider readiness.
- `start --prd`: validate a strict local PRD, generate a YAML plan, save review artifacts, and optionally execute.
- `start --github-issue`: fetch a GitHub issue body as a strict PRD source, snapshot metadata, generate a plan, and optionally execute.
- `supervise`: generate a plan from an explicit goal.
- `roadmap inspect`, `roadmap plan`, `roadmap sessions`, and `roadmap resume`: work from `docs/roadmap.md`.
- `run`: execute a hand-authored or generated YAML plan.
- `live`, `history`, and `export`: inspect persisted local run state.
- `cancel`, `resume`, `replay`, and `recover`: handle interrupted, blocked, or stale runs.
- `dashboard serve` and `editor plan`: early local surfaces over the same persisted artifacts.
- `completions`: print shell completion scripts.
Not first-class yet:
- fully autonomous backlog management
- GitHub issue comments, labels, milestones, assignees, linked PRs, or writeback
- production support promises for providers beyond the Codex CLI adapter
## Install
Use a release binary unless you are contributing to Arise or intentionally building from source. Rust is required for Cargo installs, source checkouts, and workspace verification; it is not required to run the packaged release binary.
Prerequisites for normal use:
- Git.
- Codex CLI on your `PATH`, or a matching provider entry in [`arise.yaml`](./arise.yaml), for planning and execution.
- A Git checkout with at least one commit before non-dry-run task execution, because Arise creates Git worktrees for tasks.
Install the latest release with the shell script on macOS or Linux:
```bash
curl -fsSL https://raw.githubusercontent.com/michaelasper/arise/main/scripts/install.sh | bash
```
The macOS/Linux script installs to `$HOME/.local/bin/arise` by default. Use `--install-dir` to choose another directory:
```bash
curl -fsSL https://raw.githubusercontent.com/michaelasper/arise/main/scripts/install.sh | bash -s -- --install-dir "$HOME/bin"
```
Install the latest release with PowerShell on Windows:
```powershell
irm https://raw.githubusercontent.com/michaelasper/arise/main/scripts/install.ps1 | iex
```
The Windows script installs to `$HOME\.arise\bin\arise.exe` by default.
Install the latest release with Homebrew:
```bash
brew install michaelasper/arise/arise
```
Install the latest source with Cargo:
```bash
cargo install --git https://github.com/michaelasper/arise arise-cli --locked
```
Release archives are published for:
- `aarch64-apple-darwin`
- `x86_64-apple-darwin`
- `aarch64-unknown-linux-gnu`
- `x86_64-unknown-linux-gnu`
- `aarch64-pc-windows-msvc`
- `x86_64-pc-windows-msvc`
Verify the installed binary:
```bash
arise --version
arise doctor
```
Install or roll back to a specific GitHub release:
```bash
curl -fsSL https://raw.githubusercontent.com/michaelasper/arise/main/scripts/install.sh | bash -s -- --version v0.1.2
```
Install a specific release with Cargo:
```bash
cargo install --git https://github.com/michaelasper/arise --tag v0.1.2 arise-cli --locked --force
```
Upgrade through the same channel you used to install:
macOS or Linux release script:
```bash
curl -fsSL https://raw.githubusercontent.com/michaelasper/arise/main/scripts/install.sh | bash
```
Homebrew:
```bash
brew update
brew upgrade michaelasper/arise/arise
```
Cargo:
```bash
cargo install --git https://github.com/michaelasper/arise arise-cli --locked --force
```
Before upgrading across a major version, finish or cancel active runs unless the release notes explicitly say the old `.arise/` state is compatible. After every upgrade, run `arise --version` and `arise doctor` in the repositories where you use Arise.
For the full setup and upgrade procedure, read [How to Install and Upgrade Arise](./docs/guides/how-to-install-and-upgrade.md).
## Agent Skill
Arise also publishes a `using-arise` skill for agents that support the `npx skills` ecosystem.
Install the latest repo-backed skill:
```bash
npx skills add michaelasper/arise --skill using-arise -a codex -y
```
Install a pinned released skill from a tag:
```bash
npx skills add https://github.com/michaelasper/arise/tree/using-arise-vX.Y.Z/skills/using-arise -a codex -y
```
The skill teaches review-first Arise usage: `doctor`, PRD planning with `--dry-run --no-auto-run`, `.arise/` artifact review, and the correct use of `recover inspect`, `resume`, and `replay`.
## Releases
Releases are automated from `main`. The release workflow plans the next SemVer tag from commit history, updates the Cargo workspace version, builds provenance-attested archives for every supported target, publishes the GitHub Release, verifies Cargo install from the release tag, updates the Homebrew tap, and smoke-tests `arise --version`.
Release-significant commits follow Conventional Commit meaning:
- `feat:` creates a minor release.
- `fix:`, `perf:`, `refactor:`, and `security:` create patch releases.
- `!` or `BREAKING CHANGE` creates a major release.
The workflow also understands the repository's bracketed maintenance prefixes for compatibility. Configure either `HOMEBREW_TAP_TOKEN` or `RELEASE_TOKEN`; set `HOMEBREW_TAP` and `HOMEBREW_TAP_REPOSITORY` if the tap differs from `michaelasper/arise` and `michaelasper/homebrew-arise`. If `CARGO_REGISTRY_TOKEN` is configured, the workflow also publishes the available `arise-cli` package to crates.io.
## Quickstart
Initialize local Arise config:
```bash
arise init
```
Generate your first reviewable plan from the example PRD:
```bash
arise start --prd examples/prd/bootstrap.md --dry-run --no-auto-run
```
`--dry-run --no-auto-run` keeps task execution off. Planning still writes local review artifacts under `.arise/` and promotes the generated YAML to `.arise/plans//generated-plan.arise.yaml` so you can inspect exactly what would run.
Run the deterministic verification lane:
```bash
cargo fmt --all --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace
cargo test --doc --workspace
```
If you use `just`, the same lane is:
```bash
just verify
```
## Core Workflow
Arise turns intent into artifacts:
```text
strict PRD or issue
|
v
generated execution plan
|
v
human review and approval
|
v
task worktrees + verification gates
|
v
checkpointed phases + durable run history
```
Plan from a strict local PRD:
```bash
arise start --prd examples/prd/bootstrap.md --dry-run --no-auto-run
```
Plan from a GitHub issue whose body is already a strict PRD:
```bash
arise start --github-issue michaelasper/arise#123 --dry-run --no-auto-run
```
Run an existing plan:
```bash
arise run .arise/plans/my-plan/generated-plan.arise.yaml
```
Inspect and recover runs:
```bash
arise live
arise history --limit 10
arise recover inspect
arise resume
arise replay
```
Use `--yolo` only when you intentionally want dangerous unsandboxed worker execution.
## Runtime Artifacts
Arise writes local runtime state under `.arise/`, which is ignored by Git.
Important paths:
- [`arise.yaml`](./arise.yaml): project defaults.
- `.arise/state.db`: SQLite run and task state.
- `.arise/events.ndjson`: append-only event stream.
- `.arise/plans//generated-plan.arise.yaml`: latest generated YAML plan for the plan slug.
- `.arise/plans//revisions/rev-/`: saved planning revision bundles.
- `.arise/runs//`: run artifacts and task output files.
- `.arise/runs///attempt-/`: per-attempt recovery bundles.
- `.arise/runs//phase-/integration/`: blocked checkpoint recovery bundles.
- `.arise/runs//phase-/checkpoint/`: successful checkpoint provenance bundles.
- `.arise/worktrees/`: active or preserved task worktrees.
- `.arise/sessions/`: saved roadmap planning sessions.
These artifacts can include prompts, provider output, command logs, file paths, local repo details, and private issue content. Review generated plans and `.arise/` bundles before sharing logs, exports, or issue-backed plans.
## Learn Arise
Start with the public guide pack:
- [Install and Upgrade Arise](./docs/guides/how-to-install-and-upgrade.md)
- [Getting Started Tutorial](./docs/guides/tutorial-getting-started.md)
- [Plan From a PRD or GitHub Issue](./docs/guides/how-to-plan-from-prd.md)
- [Inspect and Recover Runs](./docs/guides/how-to-inspect-and-recover-runs.md)
- [Core Concepts Guide](./docs/guides/guide-core-concepts.md)
- [Contributor Onboarding](./docs/guides/onboarding-contributors.md)
Deeper references:
- [Guides Index](./docs/guides/README.md)
- [Development Guide](./docs/development.md)
- [Strict PRD Workflow](./docs/prd-workflow.md)
- [Roadmap](./docs/roadmap.md)
- [PRD Index](./docs/prds/README.md)
- [Terminal UX Roadmap](./docs/terminal-ux-roadmap.md)
- [Commit Message Policy](./docs/commit-message-policy.md)
- [ADR 0001: Unified Hybrid Core](./docs/adr/0001-unified-hybrid-core.md)
## Project Layout
- `crates/arise-core`: typed config, plan, PRD, roadmap, provider, and state models.
- `crates/arise-engine`: scheduler, state store, Git helpers, coordination, and orchestration runtime.
- `crates/arise-provider-codex`: Codex CLI provider adapter.
- `crates/arise-provider-openai-compatible`: OpenAI-compatible planning provider adapter.
- `crates/arise-provider-rig-worker`: experimental Rig worker provider scaffold.
- `crates/arise-mcp`: MCP resource projections and guarded local controls.
- `crates/arise-cli`: CLI commands, planning flows, roadmap sessions, dashboard API, and terminal output.
- `examples/`: example PRDs and plans.
- `docs/`: guides, roadmap, ADRs, PRDs, implementation plans, and development notes.
## Contributing And Security
Read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a pull request. It documents setup, verification expectations, commit style, and public-tree hygiene.
Report vulnerabilities through [SECURITY.md](./SECURITY.md). Do not open public issues for security-sensitive reports.
Arise is released under the [MIT License](./LICENSE).