Merge pull request ComposioHQ#537 from suraj-markup/feat/onboarding-improvements

feat: zero-friction onboarding — ao start does everything

Author: suraj-markup

.changeset/config.json

@@ -7,7 +7,7 @@
     [
       "@composio/ao-core",
       "@composio/ao-cli",
-      "@composio/agent-orchestrator",
+      "@composio/ao",
       "@composio/ao-plugin-runtime-tmux",
       "@composio/ao-plugin-runtime-process",
       "@composio/ao-plugin-agent-claude-code",

README.md

@@ -44,78 +44,63 @@ Agent Orchestrator manages fleets of AI coding agents working in parallel on you
 
 ## Quick Start
 
-**Option A — Install via npm (recommended):**
+> **Prerequisites:** [Node.js 20+](https://nodejs.org), [Git 2.25+](https://git-scm.com), [tmux](https://github.com/tmux/tmux/wiki/Installing), [`gh` CLI](https://cli.github.com). Install tmux via `brew install tmux` (macOS) or `sudo apt install tmux` (Linux).
 
-```bash
-npm install -g @composio/agent-orchestrator
+### Install
 
-# Permission denied? Use one of these:
-sudo npm install -g @composio/agent-orchestrator   # quick fix
-npx @composio/agent-orchestrator                    # no install needed
+```bash
+npm install -g @composio/ao
 ```
 
-> **Prerequisites:** [Node.js 20+](https://nodejs.org), [Git 2.25+](https://git-scm.com), [tmux](https://github.com/tmux/tmux/wiki/Installing), [`gh` CLI](https://cli.github.com). Install tmux via `brew install tmux` (macOS) or `sudo apt install tmux` (Linux).
+<details>
+<summary>Permission denied? Install from source?</summary>
 
-**Option B — Install from source (for contributors):**
+If `npm install -g` fails with EACCES, prefix with `sudo` or [fix your npm permissions](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally).
+
+To install from source (for contributors):
 
 ```bash
 git clone https://github.com/ComposioHQ/agent-orchestrator.git
 cd agent-orchestrator && bash scripts/setup.sh
 ```
+</details>
+
+### Start
 
-Then set up your project:
+Point it at any repo — it clones, configures, and launches the dashboard in one command:
 
 ```bash
-# From a repo URL (fastest — clones, configures, and launches in one command)
 ao start https://github.com/your-org/your-repo
-
-# Or from an existing local repo
-cd ~/your-project && ao start   # auto-detects everything, zero prompts
-
-# Add more projects to an existing setup
-ao start ~/path/to/another-repo
 ```
 
-Spawn agents:
+Or from inside an existing local repo:
 
 ```bash
-ao spawn my-project 123    # GitHub issue, Linear ticket, or ad-hoc
+cd ~/your-project && ao start
 ```
 
-Dashboard opens at `http://localhost:3000`. Run `ao status` for the CLI view.
+That's it. The dashboard opens at `http://localhost:3000` and the orchestrator agent starts managing your project.
 
-## How It Works
+### Add more projects
 
+```bash
+ao start ~/path/to/another-repo
 ```
-ao spawn my-project 123
-```
-
-1. **Workspace** creates an isolated git worktree with a feature branch
-2. **Runtime** starts a tmux session (or Docker container)
-3. **Agent** launches Claude Code (or Codex, or Aider) with issue context
-4. Agent works autonomously — reads code, writes tests, creates PR
-5. **Reactions** auto-handle CI failures and review comments
-6. **Notifier** pings you only when judgment is needed
 
-### Plugin Architecture
-
-Eight slots. Every abstraction is swappable.
+## How It Works
 
-| Slot      | Default     | Alternatives             |
-| --------- | ----------- | ------------------------ |
-| Runtime   | tmux        | docker, k8s, process     |
-| Agent     | claude-code | codex, aider, opencode   |
-| Workspace | worktree    | clone                    |
-| Tracker   | github      | linear                   |
-| SCM       | github      | —                        |
-| Notifier  | desktop     | slack, composio, webhook |
-| Terminal  | iterm2      | web                      |
-| Lifecycle | core        | —                        |
+1. **You start** — `ao start` launches the dashboard and an orchestrator agent
+2. **Orchestrator spawns workers** — each issue gets its own agent in an isolated git worktree
+3. **Agents work autonomously** — they read code, write tests, create PRs
+4. **Reactions handle feedback** — CI failures and review comments are automatically routed back to the agent
+5. **You review and merge** — you only get pulled in when human judgment is needed
 
-All interfaces defined in [`packages/core/src/types.ts`](packages/core/src/types.ts). A plugin implements one interface and exports a `PluginModule`. That's it.
+The orchestrator agent uses the [AO CLI](docs/CLI.md) internally to manage sessions. You don't need to learn or use the CLI — the dashboard and orchestrator handle everything.
 
 ## Configuration
 
+`ao start` auto-generates `agent-orchestrator.yaml` with sensible defaults. You can edit it afterwards to customize behavior:
+
 ```yaml
 # agent-orchestrator.yaml
 port: 3000
@@ -149,54 +134,42 @@ reactions:
 
 CI fails → agent gets the logs and fixes it. Reviewer requests changes → agent addresses them. PR approved with green CI → you get a notification to merge.
 
-See [`agent-orchestrator.yaml.example`](agent-orchestrator.yaml.example) for the full reference.
-
-## CLI
-
-```bash
-ao start                               # Auto-detect project, generate config, and start
-ao start ~/other-repo                  # Add a new project and start
-ao config-help                         # Show full config schema reference
-ao status                              # Overview of all sessions
-ao spawn [issue]                       # Spawn an agent (project auto-detected)
-ao send <session> "Fix the tests"      # Send instructions
-ao session ls                          # List sessions
-ao session kill <session>              # Kill a session
-ao session restore <session>           # Revive a crashed agent
-ao dashboard                           # Open web dashboard
-ao doctor [--fix]                      # Check install, runtime, and stale temp issues
-ao update                              # Update local AO install and run smoke tests
-```
+See [`agent-orchestrator.yaml.example`](agent-orchestrator.yaml.example) for the full reference, or run `ao config-help` for the complete schema.
 
-## Maintenance
-
-```bash
-# Run deterministic install and runtime checks
-ao doctor
+## Plugin Architecture
 
-# Apply safe cleanup and launcher fixes
-ao doctor --fix
+Eight slots. Every abstraction is swappable.
 
-# Update this local AO checkout, rebuild critical packages, and verify the launcher
-ao update
-```
+| Slot      | Default     | Alternatives             |
+| --------- | ----------- | ------------------------ |
+| Runtime   | tmux        | docker, k8s, process     |
+| Agent     | claude-code | codex, aider, opencode   |
+| Workspace | worktree    | clone                    |
+| Tracker   | github      | linear                   |
+| SCM       | github      | —                        |
+| Notifier  | desktop     | slack, composio, webhook |
+| Terminal  | iterm2      | web                      |
+| Lifecycle | core        | —                        |
 
-`ao doctor` checks PATH and launcher resolution, required binaries, tmux and GitHub CLI health, config support directories, stale AO temp files, and core build/runtime sanity. `ao update` fast-forwards the local install repo on `main`, runs `pnpm install`, clean-rebuilds `@composio/ao-core`, `@composio/ao-cli`, and `@composio/ao-web`, refreshes the global `ao` launcher with `npm link`, and finishes with CLI smoke tests.
+All interfaces defined in [`packages/core/src/types.ts`](packages/core/src/types.ts). A plugin implements one interface and exports a `PluginModule`. That's it.
 
 ## Why Agent Orchestrator?
 
 Running one AI agent in a terminal is easy. Running 30 across different issues, branches, and PRs is a coordination problem.
 
 **Without orchestration**, you manually: create branches, start agents, check if they're stuck, read CI failures, forward review comments, track which PRs are ready to merge, clean up when done.
 
-**With Agent Orchestrator**, you: `ao spawn` and walk away. The system handles isolation, feedback routing, and status tracking. You review PRs and make decisions — the rest is automated.
+**With Agent Orchestrator**, you: `ao start` and walk away. The system handles isolation, feedback routing, and status tracking. You review PRs and make decisions — the rest is automated.
 
-## Prerequisites
+## Documentation
 
-- Node.js 20+
-- Git 2.25+
-- tmux (for default runtime)
-- `gh` CLI (for GitHub integration)
+| Doc                                      | What it covers                                               |
+| ---------------------------------------- | ------------------------------------------------------------ |
+| [Setup Guide](SETUP.md)                  | Detailed installation, configuration, and troubleshooting    |
+| [CLI Reference](docs/CLI.md)             | All `ao` commands (mostly used by the orchestrator agent)    |
+| [Examples](examples/)                    | Config templates (GitHub, Linear, multi-project, auto-merge) |
+| [Development Guide](docs/DEVELOPMENT.md) | Architecture, conventions, plugin pattern                    |
+| [Contributing](CONTRIBUTING.md)          | How to contribute, build plugins, PR process                 |
 
 ## Development
 
@@ -208,16 +181,6 @@ pnpm dev                       # Start web dashboard dev server
 
 See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for code conventions and architecture details.
 
-## Documentation
-
-| Doc                                      | What it covers                                               |
-| ---------------------------------------- | ------------------------------------------------------------ |
-| [Setup Guide](SETUP.md)                  | Detailed installation and configuration                      |
-| [Examples](examples/)                    | Config templates (GitHub, Linear, multi-project, auto-merge) |
-| [Development Guide](docs/DEVELOPMENT.md) | Architecture, conventions, plugin pattern                    |
-| [Contributing](CONTRIBUTING.md)          | How to contribute, build plugins, PR process                 |
-| [Troubleshooting](TROUBLESHOOTING.md)    | Common issues and fixes                                      |
-
 ## Contributing
 
 Contributions welcome. The plugin system makes it straightforward to add support for new agents, runtimes, trackers, and notification channels. Every plugin is an implementation of a TypeScript interface — see [CONTRIBUTING.md](CONTRIBUTING.md) and the [Development Guide](docs/DEVELOPMENT.md) for the pattern.