bkinnightskytw
/
agent-orchestrator
mirror of https://github.com/ComposioHQ/agent-orchestrator.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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 <noreply@anthropic.com>
This commit is contained in:
suraj-markup 2026-03-13 21:20:25 +05:30
parent fa6c475d48
commit 2df2d2f45e
2 changed files with 581 additions and 157 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

581
docs/design-onboarding-improvements.html Normal file
View File

@ -0,0 +1,581 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Design: Onboarding Friction Reduction — Agent Orchestrator</title>
<style>
:root {
--bg: #0d1117;
--surface: #161b22;
--border: #30363d;
--text: #e6edf3;
--text-muted: #8b949e;
--accent: #58a6ff;
--green: #3fb950;
--red: #f85149;
--yellow: #d29922;
--orange: #db6d28;
--code-bg: #1c2128;
}
* { margin: 0; padding: 0; box-sizing: border-box; }
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
background: var(--bg);
color: var(--text);
line-height: 1.6;
padding: 40px 20px;
}
.container {
max-width: 900px;
margin: 0 auto;
}
h1 {
font-size: 2rem;
margin-bottom: 8px;
border-bottom: 1px solid var(--border);
padding-bottom: 16px;
}
.meta {
color: var(--text-muted);
font-size: 0.9rem;
margin-bottom: 32px;
}
.meta span {
margin-right: 24px;
}
h2 {
font-size: 1.4rem;
margin-top: 40px;
margin-bottom: 16px;
color: var(--accent);
}
h3 {
font-size: 1.1rem;
margin-top: 28px;
margin-bottom: 12px;
}
p {
margin-bottom: 12px;
}
table {
width: 100%;
border-collapse: collapse;
margin: 16px 0 24px;
font-size: 0.9rem;
}
th {
background: var(--surface);
text-align: left;
padding: 10px 14px;
border: 1px solid var(--border);
font-weight: 600;
}
td {
padding: 10px 14px;
border: 1px solid var(--border);
}
tr:nth-child(even) td {
background: rgba(22, 27, 34, 0.5);
}
code {
background: var(--code-bg);
padding: 2px 6px;
border-radius: 4px;
font-size: 0.85em;
font-family: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace;
}
pre {
background: var(--code-bg);
border: 1px solid var(--border);
border-radius: 8px;
padding: 16px;
overflow-x: auto;
margin: 12px 0 20px;
font-size: 0.85rem;
line-height: 1.5;
}
pre code {
background: none;
padding: 0;
}
.badge {
display: inline-block;
padding: 2px 8px;
border-radius: 12px;
font-size: 0.75rem;
font-weight: 600;
}
.badge-blocking { background: rgba(248, 81, 73, 0.2); color: var(--red); }
.badge-high { background: rgba(219, 109, 40, 0.2); color: var(--orange); }
.badge-medium { background: rgba(210, 153, 34, 0.2); color: var(--yellow); }
.badge-low { background: rgba(63, 185, 80, 0.2); color: var(--green); }
.before-after {
display: grid;
grid-template-columns: 1fr 1fr;
gap: 16px;
margin: 16px 0 24px;
}
.before-after > div {
background: var(--surface);
border: 1px solid var(--border);
border-radius: 8px;
padding: 16px;
}
.before-after h4 {
font-size: 0.8rem;
text-transform: uppercase;
letter-spacing: 0.05em;
margin-bottom: 10px;
}
.before-after .before h4 { color: var(--red); }
.before-after .after h4 { color: var(--green); }
.files-changed {
list-style: none;
padding: 0;
}
.files-changed li {
color: var(--text-muted);
font-size: 0.85rem;
padding: 2px 0;
}
.files-changed li::before {
content: "~";
color: var(--yellow);
margin-right: 8px;
}
.files-changed li.new::before {
content: "+";
color: var(--green);
}
.flow-comparison {
display: grid;
grid-template-columns: 1fr 1fr;
gap: 16px;
margin: 16px 0 24px;
}
.flow-comparison > div {
background: var(--surface);
border-radius: 8px;
border: 1px solid var(--border);
padding: 20px;
}
.flow-comparison h4 {
margin-bottom: 12px;
font-size: 0.9rem;
}
.flow-step {
display: flex;
align-items: flex-start;
margin-bottom: 8px;
font-size: 0.85rem;
}
.flow-step .num {
background: var(--border);
color: var(--text);
width: 22px;
height: 22px;
border-radius: 50%;
display: flex;
align-items: center;
justify-content: center;
font-size: 0.7rem;
font-weight: 600;
margin-right: 10px;
flex-shrink: 0;
margin-top: 2px;
}
.flow-step .comment {
color: var(--text-muted);
font-size: 0.8rem;
}
.flow-step.problem .comment { color: var(--red); }
.checklist {
list-style: none;
padding: 0;
}
.checklist li {
padding: 6px 0;
font-size: 0.9rem;
}
.checklist li::before {
content: "[ ]";
font-family: monospace;
color: var(--text-muted);
margin-right: 8px;
}
.impact-card {
background: var(--surface);
border: 1px solid var(--border);
border-radius: 8px;
padding: 20px;
margin: 16px 0;
}
.impact-grid {
display: grid;
grid-template-columns: repeat(3, 1fr);
gap: 16px;
margin: 16px 0 24px;
}
.impact-item {
background: var(--surface);
border: 1px solid var(--border);
border-radius: 8px;
padding: 16px;
text-align: center;
}
.impact-item .number {
font-size: 2rem;
font-weight: 700;
}
.impact-item .number.before { color: var(--red); }
.impact-item .number.after { color: var(--green); }
.impact-item .label {
color: var(--text-muted);
font-size: 0.8rem;
margin-top: 4px;
}
.impact-item .arrow {
color: var(--text-muted);
margin: 4px 0;
}
a {
color: var(--accent);
text-decoration: none;
}
a:hover {
text-decoration: underline;
}
ol {
padding-left: 20px;
margin: 8px 0 16px;
}
ol li {
margin-bottom: 4px;
font-size: 0.9rem;
}
@media (max-width: 640px) {
.before-after, .flow-comparison, .impact-grid {
grid-template-columns: 1fr;
}
}
</style>
</head>
<body>
<div class="container">
<h1>Design: Onboarding Friction Reduction</h1>
<div class="meta">
<span>PR: <code>feat/onboarding-improvements</code></span>
<span>Author: Suraj + Claude</span>
<span>Date: 2026-03-13</span>
</div>
<h2>Motivation</h2>
<p>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 <code>git clone</code> to <code>ao spawn</code> as smooth as possible — ideally zero interruptions.</p>
<h2>Problems Identified</h2>
<table>
<thead>
<tr><th>#</th><th>Problem</th><th>Severity</th><th>Who it affects</th></tr>
</thead>
<tbody>
<tr>
<td>1</td>
<td><code>setup.sh</code> crashes with EACCES on <code>npm link</code></td>
<td><span class="badge badge-blocking">Blocking</span></td>
<td>Every macOS user</td>
</tr>
<tr>
<td>2</td>
<td><code>ao init</code> asks 13 prompts before generating config</td>
<td><span class="badge badge-high">High friction</span></td>
<td>Every new user</td>
</tr>
<tr>
<td>3</td>
<td>Adding a second project requires editing YAML by hand</td>
<td><span class="badge badge-high">High friction</span></td>
<td>Multi-project users</td>
</tr>
<tr>
<td>4</td>
<td><code>ao start</code> crashes if configured port is busy</td>
<td><span class="badge badge-medium">Medium friction</span></td>
<td>Users running other dev servers</td>
</tr>
<tr>
<td>5</td>
<td><code>--smart</code> flag shows "coming soon" placeholder</td>
<td><span class="badge badge-low">Low friction</span></td>
<td>Users exploring CLI flags</td>
</tr>
<tr>
<td>6</td>
<td>Same <code>npm link</code> bug in <code>ao update</code> and <code>ao doctor --fix</code></td>
<td><span class="badge badge-blocking">Blocking</span></td>
<td>Users updating or diagnosing</td>
</tr>
</tbody>
</table>
<h2>Changes</h2>
<h3>1. Fix <code>npm link</code> permission error</h3>
<div class="before-after">
<div class="before">
<h4>Before</h4>
<p><code>npm link</code> fails with EACCES on macOS. Script exits. User is stuck with no <code>ao</code> command and no guidance.</p>
</div>
<div class="after">
<h4>After</h4>
<p>Tries <code>npm link</code> first. If it fails and terminal is interactive, auto-retries with <code>sudo</code>. If non-interactive (CI), prints the manual command.</p>
</div>
</div>
<ul class="files-changed">
<li>scripts/setup.sh</li>
<li>scripts/ao-update.sh</li>
<li>scripts/ao-doctor.sh</li>
</ul>
<h3>2. Make <code>ao init</code> default to auto-detection</h3>
<div class="before-after">
<div class="before">
<h4>Before</h4>
<p><code>ao init</code> → 13 interactive prompts<br><code>ao init --auto</code> → zero prompts</p>
<p>Most users should use <code>--auto</code> but it wasn't the default.</p>
</div>
<div class="after">
<h4>After</h4>
<p><code>ao init</code> → auto-detects everything, zero prompts<br><code>ao init --interactive</code> → full wizard for manual control</p>
</div>
</div>
<ul class="files-changed">
<li>packages/cli/src/commands/init.ts</li>
</ul>
<h3>3. Add <code>ao add-project &lt;path&gt;</code> command</h3>
<div class="before-after">
<div class="before">
<h4>Before</h4>
<p>Adding a project meant opening <code>agent-orchestrator.yaml</code> and manually writing YAML with the correct structure, session prefix, and repo format.</p>
</div>
<div class="after">
<h4>After</h4>
<p>One command: <code>ao add-project ~/Desktop/mono</code></p>
</div>
</div>
<p>The command automatically:</p>
<ol>
<li>Resolves the path and finds the existing config</li>
<li>Detects git remote (<code>owner/repo</code>)</li>
<li>Detects default branch (main/master/etc.)</li>
<li>Generates a unique session prefix (validates against existing ones)</li>
<li>Detects project type (language, framework, test runner)</li>
<li>Generates agent rules from templates</li>
<li>Appends the project to the config</li>
</ol>
<ul class="files-changed">
<li class="new">packages/cli/src/commands/add-project.ts</li>
<li>packages/cli/src/index.ts</li>
</ul>
<h3>4. Auto-find free port on <code>ao start</code></h3>
<div class="before-after">
<div class="before">
<h4>Before</h4>
<pre><code>Port 3000 is already in use.
Free it or change 'port' in agent-orchestrator.yaml.</code></pre>
</div>
<div class="after">
<h4>After</h4>
<pre><code>Port 3000 is busy — using 3001 instead.</code></pre>
</div>
</div>
<ul class="files-changed">
<li>packages/cli/src/commands/start.ts</li>
</ul>
<h3>5. Remove <code>--smart</code> placeholder</h3>
<div class="before-after">
<div class="before">
<h4>Before</h4>
<p><code>ao init --auto --smart</code> showed "AI-powered rule generation not yet implemented". A dead feature flag.</p>
</div>
<div class="after">
<h4>After</h4>
<p>Removed entirely. Template-based rules are the default and work well.</p>
</div>
</div>
<ul class="files-changed">
<li>packages/cli/src/commands/init.ts</li>
</ul>
<h2>New Onboarding Flow</h2>
<div class="flow-comparison">
<div>
<h4 style="color: var(--red);">Before (5+ min, multiple failure points)</h4>
<div class="flow-step problem">
<div class="num">1</div>
<div><code>bash scripts/setup.sh</code><br><span class="comment">Could crash on npm link</span></div>
</div>
<div class="flow-step">
<div class="num">2</div>
<div><code>cd ~/my-project</code></div>
</div>
<div class="flow-step problem">
<div class="num">3</div>
<div><code>ao init</code><br><span class="comment">13 interactive prompts</span></div>
</div>
<div class="flow-step problem">
<div class="num">4</div>
<div><code>nano agent-orchestrator.yaml</code><br><span class="comment">Edit YAML to add projects</span></div>
</div>
<div class="flow-step problem">
<div class="num">5</div>
<div><code>ao start</code><br><span class="comment">Could crash on port conflict</span></div>
</div>
<div class="flow-step">
<div class="num">6</div>
<div><code>ao spawn my-project 123</code></div>
</div>
</div>
<div>
<h4 style="color: var(--green);">After (2 min, zero interruptions)</h4>
<div class="flow-step">
<div class="num">1</div>
<div><code>bash scripts/setup.sh</code><br><span class="comment" style="color: var(--green);">Handles permissions automatically</span></div>
</div>
<div class="flow-step">
<div class="num">2</div>
<div><code>cd ~/my-project && ao init</code><br><span class="comment" style="color: var(--green);">Zero prompts, auto-detects</span></div>
</div>
<div class="flow-step">
<div class="num">3</div>
<div><code>ao add-project ~/other-project</code><br><span class="comment" style="color: var(--green);">One command, auto-detects</span></div>
</div>
<div class="flow-step">
<div class="num">4</div>
<div><code>ao start</code><br><span class="comment" style="color: var(--green);">Auto-finds free port</span></div>
</div>
<div class="flow-step">
<div class="num">5</div>
<div><code>ao spawn my-project 123</code><br><span class="comment" style="color: var(--green);">Start working!</span></div>
</div>
</div>
</div>
<h2>UX Impact</h2>
<div class="impact-grid">
<div class="impact-item">
<div class="number before">13</div>
<div class="arrow">↓</div>
<div class="number after">0</div>
<div class="label">Prompts in <code>ao init</code></div>
</div>
<div class="impact-item">
<div class="number before">6+</div>
<div class="arrow">↓</div>
<div class="number after">4</div>
<div class="label">Steps to first <code>ao spawn</code></div>
</div>
<div class="impact-item">
<div class="number before">3</div>
<div class="arrow">↓</div>
<div class="number after">0</div>
<div class="label">Fatal crash points</div>
</div>
</div>
<table>
<thead>
<tr><th>Metric</th><th>Before</th><th>After</th></tr>
</thead>
<tbody>
<tr><td>Steps to first <code>ao spawn</code></td><td>6+ (with manual edits)</td><td>4 (all automated)</td></tr>
<tr><td>Interactive prompts in <code>ao init</code></td><td>13</td><td>0</td></tr>
<tr><td>Permission errors during setup</td><td>Fatal crash</td><td>Auto-handled</td></tr>
<tr><td>Port conflicts on <code>ao start</code></td><td>Fatal crash</td><td>Auto-resolved</td></tr>
<tr><td>Adding a second project</td><td>Manual YAML editing</td><td><code>ao add-project &lt;path&gt;</code></td></tr>
<tr><td>Dead CLI flags</td><td><code>--smart</code> shows "coming soon"</td><td>Removed</td></tr>
</tbody>
</table>
<h2>Backward Compatibility</h2>
<div class="impact-card">
<ul style="list-style: none; padding: 0;">
<li style="padding: 4px 0;">&#10003; <code>ao init --auto</code> still works (now equivalent to <code>ao init</code>)</li>
<li style="padding: 4px 0;">&#10003; Interactive wizard still available via <code>ao init --interactive</code></li>
<li style="padding: 4px 0;">&#10003; <code>ao start</code> auto-port was already the behavior for URL-based starts — now default for all</li>
<li style="padding: 4px 0;">&#10003; No config format changes</li>
<li style="padding: 4px 0;">&#10003; No breaking changes to any existing command</li>
</ul>
</div>
<h2>Related Issues</h2>
<p>
<a href="https://github.com/ComposioHQ/agent-orchestrator/issues/454">#454</a> — Codex plugin stability improvements (spawned as a parallel agent session)<br>
<a href="https://github.com/ComposioHQ/agent-orchestrator/issues/456">#456</a> — Dashboard shows orchestrator as "Exited" due to startup race condition
</p>
<h2>Test Plan</h2>
<ul class="checklist">
<li>Fresh <code>bash scripts/setup.sh</code> on macOS without sudo permissions pre-granted</li>
<li><code>ao init</code> in a git repo with GitHub remote → generates correct config with zero prompts</li>
<li><code>ao init --interactive</code> → shows full 13-prompt wizard</li>
<li><code>ao add-project ~/some-repo</code> → appends project with correct detection</li>
<li><code>ao add-project</code> on already-added project → shows clear error</li>
<li><code>ao start</code> with port 3000 busy → auto-finds 3001 and starts</li>
<li><code>ao update</code> with permission issue → auto-retries with sudo</li>
<li><code>ao doctor --fix</code> with permission issue → auto-retries with sudo</li>
</ul>
</div>
</body>
</html>

157
docs/design-onboarding-improvements.md
View File

@ -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 <path>` 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 <path>` |
| 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