diff --git a/README.md b/README.md index e7728fc81..f1b3df4ff 100644 --- a/README.md +++ b/README.md @@ -96,10 +96,9 @@ atomic chat -a claude "/research-codebase Research implementing GraphRAG using \ ## Table of Contents - [What Engineers Use Atomic For](#what-engineers-use-atomic-for) -- [Set up Atomic](#set-up-atomic) +- [Quick Start Guide](#quick-start-guide) - [The Flywheel](#the-flywheel) - [How It Works](#how-it-works) -- [The Workflow](#the-workflow) - [Commands, Agents, and Skills](#commands-agents-and-skills) - [TUI Features](#tui-features) - [Supported Coding Agents](#supported-coding-agents) @@ -116,31 +115,19 @@ atomic chat -a claude "/research-codebase Research implementing GraphRAG using \ --- -## Set up Atomic +## Quick Start Guide -> Install Atomic and start using it with your preferred AI coding agent. - -### System requirements +### Prerequisites - **Operating Systems**: macOS, Linux, or Windows (with PowerShell) -- **Hardware**: Minimal requirements -- **Network**: Internet connection required for installation -- **Coding agent installed** (at least one): +- **At least one coding agent installed**: - [Claude Code](https://code.claude.com/docs/en/quickstart) - [OpenCode](https://opencode.ai) - [GitHub Copilot CLI](https://github.com/features/copilot/cli) -#### Additional dependencies - -- **Bun**: Only required for [bun installation](#bun-installation) - -### Installation - -To install Atomic, use one of the following methods: +### Step 1: Install Atomic -#### Native install (Recommended) - -**macOS, Linux:** +**macOS / Linux:** ```bash curl -fsSL https://raw.githubusercontent.com/flora131/atomic/main/install.sh | bash @@ -152,186 +139,148 @@ curl -fsSL https://raw.githubusercontent.com/flora131/atomic/main/install.sh | b irm https://raw.githubusercontent.com/flora131/atomic/main/install.ps1 | iex ``` -#### bun installation - -```bash -# Using bun -bun add -g @bastani/atomic -``` - -**Without installation (one-time use):** - -```bash -bunx @bastani/atomic -``` - -### Install a specific version - -**macOS, Linux:** - -```bash -curl -fsSL https://raw.githubusercontent.com/flora131/atomic/main/install.sh | bash -s -- v1.0.0 -``` - -**Windows PowerShell:** - -```powershell -iex "& { $(irm https://raw.githubusercontent.com/flora131/atomic/main/install.ps1) } -Version v1.0.0" -``` - -### Getting started - -After installation, navigate to your project and set up Atomic: +### Step 2: Initialize Your Project ```bash cd your-awesome-project atomic init ``` -Select your agent. The CLI configures your project automatically. +Select your coding agent when prompted. The CLI configures your project automatically. -`atomic init` configures source-control-specific skills in your project (GitHub/Git or Sapling), while Atomic's baseline agents/skills are installed globally under `~/.atomic/.claude`, `~/.atomic/.opencode`, and `~/.atomic/.copilot` during install/update (including `bun install` for editable/package installs). +### Step 3: Generate Context Files -Then start a chat session and run `/init` to generate `CLAUDE.md` and `AGENTS.md`: +Start a chat session and run `/init` to generate `CLAUDE.md` and `AGENTS.md`: ```bash -atomic chat -a claude +atomic chat -a ``` ``` /init ``` -The `/init` command explores your codebase using sub-agents and generates populated `CLAUDE.md` and `AGENTS.md` files tailored to your project. These files give coding agents the context they need to work effectively in your repository. +The `/init` command explores your codebase using sub-agents and generates documentation tailored to your project. These files give coding agents the context they need to work effectively. -### Source Control Selection +### Step 4: Ship Features -During `atomic init`, you'll be prompted to select your source control system: +``` +Research → Spec → Implement → (Debug) → PR +``` -| SCM Type | CLI Tool | Code Review | Use Case | -| --------------------- | -------- | ----------------- | ---------------------------- | -| GitHub / Git | `git` | Pull Requests | Most open-source projects | -| Sapling + Phabricator | `sl` | Phabricator Diffs | Meta-style stacked workflows | +**Research the codebase:** -The selection is saved to `.atomic/settings.json` in your project and configures the appropriate commit and code review commands for your workflow. +``` +/research-codebase [Describe your feature or question] +/clear +``` -#### Sapling + Phabricator Setup +Review: Confirm the agent understood your codebase and requirements. -If you select Sapling + Phabricator: +**Create a specification:** -1. Ensure `.arcconfig` exists in your repository root (required for Phabricator) -2. Use `/sl-commit` for creating commits with `sl commit` -3. Use `/sl-submit-diff` for submitting to Phabricator for code review +``` +/create-spec [research-path] +/clear +``` -**Note for Windows users:** Sapling templates use the full path `& 'C:\Program Files\Sapling\sl.exe'` to avoid conflicts with PowerShell's built-in `sl` alias for `Set-Location`. +Review (**critical**): This is your main decision point. The spec becomes the contract. -### Custom install directory +**Implement features:** -**macOS, Linux:** - -```bash -ATOMIC_INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/flora131/atomic/main/install.sh | bash +``` +/ralph "" ``` -**Windows PowerShell:** +**Commit and ship:** -```powershell -$env:ATOMIC_INSTALL_DIR = "C:\tools"; irm https://raw.githubusercontent.com/flora131/atomic/main/install.ps1 | iex +``` +/gh-commit +/gh-create-pr ``` ---- - -## The Flywheel +**Debugging:** If something breaks during implementation, use the debugging agent: ``` -Research → Specs → Execution → Outcomes → Specs (persistent memory) - ↑ ↓ - └────────────────────────────────────┘ +Use the debugging agent to create a debugging report for [insert error message here]. ``` -Every feature follows this cycle. Specs and research become memory for future sessions. +Then follow the debugging report to resolve the issue. ---- +### Advanced Installation -## How It Works +
+Install a specific version -[![Architecture](assets/architecture.svg)](assets/architecture.svg) +**macOS / Linux:** ---- +```bash +curl -fsSL https://raw.githubusercontent.com/flora131/atomic/main/install.sh | bash -s -- v1.0.0 +``` -## The Workflow +**Windows PowerShell:** +```powershell +iex "& { $(irm https://raw.githubusercontent.com/flora131/atomic/main/install.ps1) } -Version v1.0.0" ``` -Research → Plan (Spec) → Implement (Ralph) → (Debug) → PR -``` -### 1. Research the Codebase +
+ +
+Custom install directory -Start a chat session and use the `/research-codebase` command: +**macOS / Linux:** ```bash -atomic chat -a +ATOMIC_INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/flora131/atomic/main/install.sh | bash ``` -Then type in the chat: - -``` -/research-codebase [Describe your feature or question] -``` +**Windows PowerShell:** +```powershell +$env:ATOMIC_INSTALL_DIR = "C:\tools"; irm https://raw.githubusercontent.com/flora131/atomic/main/install.ps1 | iex ``` -/clear -``` - -**You review:** Confirm the agent understood your codebase and requirements. -### 2. Create a Specification +
-``` -/create-spec [research-path] -``` +
+Source control selection -``` -/clear -``` - -**You review (CRITICAL):** This is your main decision point. The spec becomes the contract. +During `atomic init`, you'll be prompted to select your source control system: -### 3. Implement Features +| SCM Type | CLI Tool | Code Review | Use Case | +| --------------------- | -------- | ----------------- | ---------------------------- | +| GitHub / Git | `git` | Pull Requests | Most open-source projects | +| Sapling + Phabricator | `sl` | Phabricator Diffs | Meta-style stacked workflows | -Use the Ralph workflow to autonomously implement features from the task list. More in [Ralph Section](#autonomous-execution-ralph): +The selection is saved to `.atomic/settings.json` and configures the appropriate commit and code review commands. -``` -/ralph "" -``` +**Sapling + Phabricator:** -### 4. Commit Changes +1. Ensure `.arcconfig` exists in your repository root +2. Use `/sl-commit` for commits and `/sl-submit-diff` for code review -``` -/gh-commit -``` +**Note for Windows users:** Sapling templates use the full path `& 'C:\Program Files\Sapling\sl.exe'` to avoid conflicts with PowerShell's built-in `sl` alias. -### 5. Debugging +
-Software engineering is highly non-linear. You are bound to need to debug along the way. +--- -If something breaks during implementation that the agent did not catch, you can manually debug. Type in the chat: +## The Flywheel ``` -Use the debugging agent to create a debugging report for [insert error message here]. +Research → Specs → Execution → Outcomes → Specs (persistent memory) + ↑ ↓ + └────────────────────────────────────┘ ``` -Then, use the debugging report to guide your agent: +Every feature follows this cycle. Specs and research become memory for future sessions. -``` -Follow the debugging report above to resolve the issue. -``` +--- -### 6. Create Pull Request +## How It Works -``` -/gh-create-pr -``` +[![Architecture](assets/architecture.svg)](assets/architecture.svg) --- diff --git a/bun.lock b/bun.lock index 15b827ad0..c24a14869 100644 --- a/bun.lock +++ b/bun.lock @@ -1,6 +1,5 @@ { "lockfileVersion": 1, - "configVersion": 0, "workspaces": { "": { "name": "atomic",