From 2df2d2f45eda95d89208d329a6f0b36eb9814149 Mon Sep 17 00:00:00 2001 From: suraj-markup Date: Fri, 13 Mar 2026 21:20:25 +0530 Subject: [PATCH] Replace design doc with HTML version Swap markdown design doc for a styled HTML version with dark theme, before/after comparisons, impact metrics, and flow diagrams. Co-Authored-By: Claude Opus 4.6 --- docs/design-onboarding-improvements.html | 581 +++++++++++++++++++++++ docs/design-onboarding-improvements.md | 157 ------ 2 files changed, 581 insertions(+), 157 deletions(-) create mode 100644 docs/design-onboarding-improvements.html delete mode 100644 docs/design-onboarding-improvements.md diff --git a/docs/design-onboarding-improvements.html b/docs/design-onboarding-improvements.html new file mode 100644 index 000000000..1cbd08ac2 --- /dev/null +++ b/docs/design-onboarding-improvements.html @@ -0,0 +1,581 @@ + + + + + + Design: Onboarding Friction Reduction — Agent Orchestrator + + + +
+

Design: Onboarding Friction Reduction

+
+ PR: feat/onboarding-improvements + Author: Suraj + Claude + Date: 2026-03-13 +
+ +

Motivation

+

New users hitting Agent Orchestrator for the first time faced multiple friction points that could cause them to abandon setup before ever spawning an agent. The goal of this PR is to make the path from git clone to ao spawn as smooth as possible — ideally zero interruptions.

+ +

Problems Identified

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
#ProblemSeverityWho it affects
1setup.sh crashes with EACCES on npm linkBlockingEvery macOS user
2ao init asks 13 prompts before generating configHigh frictionEvery new user
3Adding a second project requires editing YAML by handHigh frictionMulti-project users
4ao start crashes if configured port is busyMedium frictionUsers running other dev servers
5--smart flag shows "coming soon" placeholderLow frictionUsers exploring CLI flags
6Same npm link bug in ao update and ao doctor --fixBlockingUsers updating or diagnosing
+ +

Changes

+ +

1. Fix npm link permission error

+
+
+

Before

+

npm link fails with EACCES on macOS. Script exits. User is stuck with no ao command and no guidance.

+
+
+

After

+

Tries npm link first. If it fails and terminal is interactive, auto-retries with sudo. If non-interactive (CI), prints the manual command.

+
+
+
    +
  • scripts/setup.sh
    • +
  • scripts/ao-update.sh
    • +
  • scripts/ao-doctor.sh
    • +
+ +

2. Make ao init default to auto-detection

+
+
+

Before

+

ao init → 13 interactive prompts
ao init --auto → zero prompts

+

Most users should use --auto but it wasn't the default.

+
+
+

After

+

ao init → auto-detects everything, zero prompts
ao init --interactive → full wizard for manual control

+
+
+
    +
  • packages/cli/src/commands/init.ts
    • +
+ +

3. Add ao add-project <path> command

+
+
+

Before

+

Adding a project meant opening agent-orchestrator.yaml and manually writing YAML with the correct structure, session prefix, and repo format.

+
+
+

After

+

One command: ao add-project ~/Desktop/mono

+
+
+

The command automatically:

+
    +
  1. Resolves the path and finds the existing config
    2. +
  2. Detects git remote (owner/repo)
    3. +
  3. Detects default branch (main/master/etc.)
    4. +
  4. Generates a unique session prefix (validates against existing ones)
    5. +
  5. Detects project type (language, framework, test runner)
    6. +
  6. Generates agent rules from templates
    7. +
  7. Appends the project to the config
    8. +
+
    +
  • packages/cli/src/commands/add-project.ts
    • +
  • packages/cli/src/index.ts
    • +
+ +

4. Auto-find free port on ao start

+
+
+

Before

+ 
Port 3000 is already in use.
+Free it or change 'port' in agent-orchestrator.yaml.
+
+
+

After

+ 
Port 3000 is busy — using 3001 instead.
+
+
+
    +
  • packages/cli/src/commands/start.ts
    • +
+ +

5. Remove --smart placeholder

+
+
+

Before

+

ao init --auto --smart showed "AI-powered rule generation not yet implemented". A dead feature flag.

+
+
+

After

+

Removed entirely. Template-based rules are the default and work well.

+
+
+
    +
  • packages/cli/src/commands/init.ts
    • +
+ +

New Onboarding Flow

+
+
+

Before (5+ min, multiple failure points)

+
+
1
+
bash scripts/setup.sh
Could crash on npm link
+
+
+
2
+
cd ~/my-project
+
+
+
3
+
ao init
13 interactive prompts
+
+
+
4
+
nano agent-orchestrator.yaml
Edit YAML to add projects
+
+
+
5
+
ao start
Could crash on port conflict
+
+
+
6
+
ao spawn my-project 123
+
+
+
+

After (2 min, zero interruptions)

+
+
1
+
bash scripts/setup.sh
Handles permissions automatically
+
+
+
2
+
cd ~/my-project && ao init
Zero prompts, auto-detects
+
+
+
3
+
ao add-project ~/other-project
One command, auto-detects
+
+
+
4
+
ao start
Auto-finds free port
+
+
+
5
+
ao spawn my-project 123
Start working!
+
+
+
+ +

UX Impact

+
+
+
13
+
↓
+
0
+
Prompts in ao init
+
+
+
6+
+
↓
+
4
+
Steps to first ao spawn
+
+
+
3
+
↓
+
0
+
Fatal crash points
+
+
+ + + + + + + + + + + + + +
MetricBeforeAfter
Steps to first ao spawn6+ (with manual edits)4 (all automated)
Interactive prompts in ao init130
Permission errors during setupFatal crashAuto-handled
Port conflicts on ao startFatal crashAuto-resolved
Adding a second projectManual YAML editingao add-project <path>
Dead CLI flags--smart shows "coming soon"Removed
+ +

Backward Compatibility

+
+
    +
  • ✓ ao init --auto still works (now equivalent to ao init)
    • +
  • ✓ Interactive wizard still available via ao init --interactive
    • +
  • ✓ ao start auto-port was already the behavior for URL-based starts — now default for all
    • +
  • ✓ No config format changes
    • +
  • ✓ No breaking changes to any existing command
    • +
+
+ +

Related Issues

+

+ #454 — Codex plugin stability improvements (spawned as a parallel agent session)
+ #456 — Dashboard shows orchestrator as "Exited" due to startup race condition +

+ +

Test Plan

+
    +
  • Fresh bash scripts/setup.sh on macOS without sudo permissions pre-granted
    • +
  • ao init in a git repo with GitHub remote → generates correct config with zero prompts
    • +
  • ao init --interactive → shows full 13-prompt wizard
    • +
  • ao add-project ~/some-repo → appends project with correct detection
    • +
  • ao add-project on already-added project → shows clear error
    • +
  • ao start with port 3000 busy → auto-finds 3001 and starts
    • +
  • ao update with permission issue → auto-retries with sudo
    • +
  • ao doctor --fix with permission issue → auto-retries with sudo
    • +
+
+ + diff --git a/docs/design-onboarding-improvements.md b/docs/design-onboarding-improvements.md deleted file mode 100644 index bd0ff3e0a..000000000 --- a/docs/design-onboarding-improvements.md +++ /dev/null @@ -1,157 +0,0 @@ -# Design: Onboarding Friction Reduction - -**PR:** `feat/onboarding-improvements` -**Author:** Suraj + Claude -**Date:** 2026-03-13 - -## Motivation - -New users hitting Agent Orchestrator for the first time faced multiple friction points that could cause them to abandon setup before ever spawning an agent. The goal of this PR is to make the path from `git clone` to `ao spawn` as smooth as possible — ideally zero interruptions. - -## Problems Identified - -| # | Problem | Severity | Who it affects | -|---|---------|----------|----------------| -| 1 | `setup.sh` crashes with EACCES on `npm link` | **Blocking** | Every macOS user | -| 2 | `ao init` asks 13 prompts before generating config | **High friction** | Every new user | -| 3 | Adding a second project requires editing YAML by hand | **High friction** | Multi-project users | -| 4 | `ao start` crashes if configured port is busy | **Medium friction** | Users running other dev servers | -| 5 | `--smart` flag shows "coming soon" placeholder | **Low friction** | Users exploring CLI flags | -| 6 | Same `npm link` bug exists in `ao update` and `ao doctor --fix` | **Blocking** | Users updating or diagnosing | - -## Changes - -### 1. Fix `npm link` permission error (setup.sh, ao-update.sh, ao-doctor.sh) - -**Before:** `npm link` fails with EACCES on macOS. Script exits. User is stuck with no `ao` command and no guidance. - -**After:** Script tries `npm link` first. If it fails and the terminal is interactive, auto-retries with `sudo`. If non-interactive (CI), prints the manual command. - -**Files changed:** -- `scripts/setup.sh` -- `scripts/ao-update.sh` -- `scripts/ao-doctor.sh` - -### 2. Make `ao init` default to auto-detection - -**Before:** -- `ao init` → 13 interactive prompts (data dir, worktree dir, port, runtime, agent, workspace, notifiers, project ID, repo, path, branch, tracker, team ID) -- `ao init --auto` → auto-detection with zero prompts - -Most users should use `--auto` but it wasn't the default, pushing every new user through the long wizard. - -**After:** -- `ao init` → auto-detects everything, zero prompts (was `--auto`) -- `ao init --interactive` → full wizard for users who want manual control - -**Files changed:** -- `packages/cli/src/commands/init.ts` - -### 3. Add `ao add-project ` command - -**Before:** Adding a project to an existing config meant opening `agent-orchestrator.yaml` and manually writing YAML with the correct structure, session prefix, and repo format. - -**After:** -```bash -ao add-project ~/Desktop/mono -``` - -One command that: -1. Resolves the path -2. Finds the existing `agent-orchestrator.yaml` -3. Detects git remote (`owner/repo`) -4. Detects default branch (main/master/etc.) -5. Generates a unique session prefix (validates against existing ones) -6. Detects project type (language, framework, test runner) -7. Generates agent rules from templates -8. Appends the project to the config and writes it back - -**Files changed:** -- `packages/cli/src/commands/add-project.ts` (new) -- `packages/cli/src/index.ts` (command registration) - -### 4. Auto-find free port on `ao start` - -**Before:** If port 3000 (or whatever is in config) was busy, `ao start` threw an error and stopped: -``` -Port 3000 is already in use. Free it or change 'port' in agent-orchestrator.yaml. -``` - -**After:** Automatically finds the next available port and uses it: -``` -Port 3000 is busy — using 3001 instead. -``` - -Only fails if no port is available in the scan range. - -**Files changed:** -- `packages/cli/src/commands/start.ts` - -### 5. Remove `--smart` placeholder - -**Before:** `ao init --auto --smart` showed "AI-powered rule generation not yet implemented — using template-based rules for now". A dead feature flag that confused users. - -**After:** Removed entirely. Template-based rules are the default and work well. - -**Files changed:** -- `packages/cli/src/commands/init.ts` - -## New Onboarding Flow - -### Before (5+ minutes, multiple failure points) - -``` -git clone ... && cd agent-orchestrator -bash scripts/setup.sh # Could crash on npm link -cd ~/my-project -ao init # 13 prompts -# Want to add another project? # Edit YAML by hand -ao start # Could crash on port conflict -``` - -### After (2 minutes, zero interruptions) - -``` -git clone ... && cd agent-orchestrator -bash scripts/setup.sh # Handles permissions automatically -cd ~/my-project -ao init # Zero prompts, auto-detects everything -ao add-project ~/other-project # One command to add more projects -ao start # Auto-finds free port if needed -ao spawn my-project 123 # Start working -``` - -## UX Impact - -| Metric | Before | After | -|--------|--------|-------| -| Steps to first `ao spawn` | 6+ (with manual edits) | 4 (all automated) | -| Interactive prompts in `ao init` | 13 | 0 | -| Permission errors during setup | Fatal crash | Auto-handled | -| Port conflicts on `ao start` | Fatal crash | Auto-resolved | -| Adding a second project | Manual YAML editing | `ao add-project ` | -| Dead CLI flags | `--smart` shows "coming soon" | Removed | - -## Backward Compatibility - -- `ao init --auto` still works (now equivalent to `ao init`) -- `ao init` interactive wizard still available via `ao init --interactive` -- `ao start` behavior is strictly improved — auto-port was already the behavior for URL-based starts, now it's the default for all starts -- No config format changes -- No breaking changes to any existing command - -## Related Issues - -- [#454](https://github.com/ComposioHQ/agent-orchestrator/issues/454) — Codex plugin stability improvements (spawned as a parallel agent session) -- [#456](https://github.com/ComposioHQ/agent-orchestrator/issues/456) — Dashboard shows orchestrator as "Exited" due to startup race condition - -## Test Plan - -- [ ] Fresh `bash scripts/setup.sh` on macOS without sudo permissions pre-granted -- [ ] `ao init` in a git repo with GitHub remote → generates correct config with zero prompts -- [ ] `ao init --interactive` → shows full 13-prompt wizard -- [ ] `ao add-project ~/some-repo` → appends project with correct detection -- [ ] `ao add-project` on already-added project → shows clear error -- [ ] `ao start` with port 3000 busy → auto-finds 3001 and starts -- [ ] `ao update` with permission issue → auto-retries with sudo -- [ ] `ao doctor --fix` with permission issue → auto-retries with sudo