diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..215946669 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,50 @@ +# Contributing to Arc + +Thanks for your interest in contributing to Arc! + +## Getting started + +### Prerequisites + +- [Rust](https://rustup.rs/) (latest stable) +- [Bun](https://bun.sh/) (for the web frontend) +- Git + +### Build and test + +```bash +# Build all Rust crates +cargo build --workspace + +# Run all tests +cargo test --workspace + +# Check formatting and lint +cargo fmt --check --all +cargo clippy --workspace -- -D warnings +``` + +### Web frontend (arc-web) + +```bash +cd apps/arc-web +bun install +bun run dev # start dev server +bun test # run tests +bun run typecheck # type check +``` + +## Development workflow + +1. Fork the repository and create a branch from `main` +2. Make your changes +3. Ensure `cargo test --workspace`, `cargo fmt --check --all`, and `cargo clippy --workspace -- -D warnings` pass +4. Open a pull request + +## Reporting bugs + +Open an issue on [GitHub Issues](https://github.com/brynary/arc/issues) with steps to reproduce the problem. + +## License + +By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE.md). diff --git a/README.md b/README.md index c378d76f2..46e4ebb1f 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Arc -## The software factory for small teams of expert engineers +## The open source software factory for expert engineers AI coding agents are powerful but unpredictable. You either babysit every step or review a 50-file diff you don't trust. Arc gives you a middle path: define the process as a graph, let agents execute it, and intervene only where it matters. @@ -13,16 +13,16 @@ AI coding agents are powerful but unpredictable. You either babysit every step o ## Key Features -- **Deterministic workflow graphs** -- Define pipelines in Graphviz DOT with branching, loops, parallelism, and human gates. Diffable, reviewable, version-controlled. -- **Human-in-the-loop** -- Approval gates pause for human decisions. Steer running agents mid-turn. Interview steps collect structured input. You stay in control without babysitting. -- **Multi-model routing** -- Route each node to the right model and provider with CSS-like stylesheets. Cheap models for boilerplate, frontier models for hard reasoning, with automatic provider fallback. -- **Cloud sandboxes** -- Run agents in isolated Daytona cloud VMs with snapshot-based setup, network controls, and automatic cleanup. -- **SSH access and preview links** -- Shell into running sandboxes with `arc ssh` and expose ports with `arc preview` for live debugging while workflows run. -- **Git checkpointing** -- Every stage commits to a branch. Inspect changes, revert mistakes, or resume interrupted runs exactly where they left off. -- **Automatic retros** -- Each run generates a retrospective with cost, duration, files touched, and an LLM-written narrative rating smoothness and flagging friction points. -- **Comprehensive API** -- `arc serve` exposes a full REST API with SSE event streaming and a React web UI. Run workflows programmatically, build integrations, or operate Arc as a service. -- **Single binary, no runtime** -- One compiled Rust executable with zero dependencies. No Python, no Node, no Docker required to get started. -- **Open source (MIT)** -- Full source code, no vendor lock-in. Self-host, fork, or extend to fit your workflow. +- 🔀 **Deterministic workflow graphs** -- Define pipelines in Graphviz DOT with branching, loops, parallelism, and human gates. Diffable, reviewable, version-controlled. +- 🙋 **Human-in-the-loop** -- Approval gates pause for human decisions. Steer running agents mid-turn. Interview steps collect structured input. You stay in control without babysitting. +- 🎨 **Multi-model routing** -- Route each node to the right model and provider with CSS-like stylesheets. Cheap models for boilerplate, frontier models for hard reasoning, with automatic provider fallback. +- ☁️ **Cloud sandboxes** -- Run agents in isolated Daytona cloud VMs with snapshot-based setup, network controls, and automatic cleanup. +- 🔌 **SSH access and preview links** -- Shell into running sandboxes with `arc ssh` and expose ports with `arc preview` for live debugging while workflows run. +- 🌲 **Git checkpointing** -- Every stage commits code changes and execution metadata to Git branches. Inspect diffs, revert mistakes, resume interrupted runs, or trace exactly how and why each change was made. +- 📊 **Automatic retros** -- Each run generates a retrospective with cost, duration, files touched, and an LLM-written narrative rating smoothness and flagging friction points. +- ⚡ **Comprehensive API** -- `arc serve` exposes a full REST API with SSE event streaming and a React web UI. Run workflows programmatically, build integrations, or operate Arc as a service. +- 🦀 **Single binary, no runtime** -- One compiled Rust executable with zero dependencies. No Python, no Node, no Docker required to get started. +- ⚖️ **Open source (MIT)** -- Full source code, no vendor lock-in. Self-host, fork, or extend to fit your workflow. Read the full [documentation](https://arc.dev) for details. @@ -114,15 +114,6 @@ Agents run as multi-turn LLM sessions with tool access. Human gates (`hexagon`) --- -## System Requirements - -- **macOS** (Apple Silicon) or **Linux** (x86_64) -- **At least one LLM provider API key** (Anthropic, OpenAI, or Gemini) -- **Git** (for checkpoint and resume) -- **Rust** (only if building from source) - ---- - ## Help or Feedback - Read the [documentation](https://arc.dev) @@ -134,7 +125,7 @@ Agents run as multi-turn LLM sessions with tool access. Human gates (`hexagon`) ## Contributing -See [CLAUDE.md](CLAUDE.md) for build commands, architecture overview, and development conventions. +See [CONTRIBUTING.md](CONTRIBUTING.md) for build instructions and development workflow. ---