$quickstart
One job: Tell a new user what AgentOps does and what to do first. Fast.
YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.
Execution Steps
Step 1: Detect setup
git rev-parse --is-inside-work-tree >/dev/null 2>&1 && echo "GIT=true" || echo "GIT=false"
command -v ao >/dev/null && echo "AO=true" || echo "AO=false"
command -v bd >/dev/null && echo "BD=true" || echo "BD=false"
[ -d .agents ] && echo "AGENTS=true" || echo "AGENTS=false"
[ -d "$HOME/.agents" ] && echo "GLOBAL_AGENTS=true" || echo "GLOBAL_AGENTS=false"
[ -n "${CODEX_THREAD_ID:-}" ] || [ "${CODEX_INTERNAL_ORIGINATOR_OVERRIDE:-}" = "Codex Desktop" ] && echo "CODEX=true" || echo "CODEX=false"
Step 2: Show what AgentOps does
Output exactly this (no additions, no diagrams):
AgentOps is the operational layer for coding agents.
It gives your coding agent four things it doesn't have by default:
Bookkeeping — sessions capture learnings, findings, and reusable context in .agents/
Validation — $council, $pre-mortem, and $vibe challenge plans and code before shipping
Primitives — skills, execution packets, and the ao CLI give you building blocks for almost any interaction
Flows — $research, $implement, $validation, and $rpi can run alone or compose end to end
Key skills: $rpi $research $validation $implement $council $pre-mortem $swarm $status
Full reference: $quickstart --catalog
Step 3: One next action
Match the first row that applies. Output that message.
| Condition |
Message |
| GIT=false + AO=true + GLOBAL_AGENTS=true |
"🗂 You're outside a git repo but have a global corpus at ~/.agents. Global knowledge workflow:\n 1. $harvest — scan all .agents/ across your repos and promote artifacts into ~/.agents/learnings/\n 2. $compile — mine, synthesize, and write an interlinked wiki into .agents/compiled/ (runs from cwd; set AGENTOPS_COMPILE_RUNTIME=ollama or openai and the matching API key/host)\n 3. $knowledge-activation — turn the compiled corpus into playbooks, a belief book, and runtime briefings for future sessions\n 4. $status — flywheel health snapshot\nIf instead you want to start a fresh repo-local project here, git init first." |
| GIT=false |
"⚠ Not in a git repo. Run git init first.\n (If you meant to work against your global ~/.agents corpus, run $quickstart from a dir with .agents/ or see $harvest, $compile, $knowledge-activation.)" |
| AO=false + CODEX=true |
"📦 Install ao CLI first:\n brew tap boshu2/agentops https://github.com/boshu2/homebrew-agentops\n brew install agentops\n ao quick-start\nThen: $rpi \"a small goal\" to run your first cycle.\nUse $bootstrap after the core seed when you want PRODUCT.md, README.md, and PROGRAM.md." |
| AO=false |
"📦 Install ao CLI first:\n brew tap boshu2/agentops https://github.com/boshu2/homebrew-agentops\n brew install agentops\n ao quick-start\nThen: $rpi \"a small goal\" to run your first cycle.\nUse $bootstrap after the core seed when you want PRODUCT.md, README.md, and PROGRAM.md." |
| AGENTS=false + CODEX=true |
"🌱 ao is installed but not initialized here.\n Run ao quick-start to apply the repeatable core seed. ao quickstart is the stable alias.\n Then run $bootstrap only if you want the product/operations layer: PRODUCT.md, README.md, PROGRAM.md/AUTODEV.md, and optional hooks.\nThen: $rpi \"a small goal\" to run your first cycle." |
| AGENTS=false |
"🌱 ao is installed but not initialized here.\n Run ao quick-start to apply the repeatable core seed. ao quickstart is the stable alias.\n Then run $bootstrap only if you want the product/operations layer: PRODUCT.md, README.md, PROGRAM.md/AUTODEV.md, and optional hooks.\nThen: $rpi \"a small goal\" to run your first cycle." |
| BD=false + CODEX=true |
"✅ Codex plugin path ready.\n Start with $rpi \"your goal\", $research <topic>, or $status\n Default installs are hookless; native hooks are optional with install-codex.sh --with-hooks.\n Legacy explicit fallback commands remain ao codex ensure-start once per thread and ao codex ensure-stop during closeout when needed.\n Manual escape hatch: ao codex status\n Want issue tracking? brew install boshu2/agentops/beads && bd init --prefix <prefix>" |
| BD=false |
"✅ Flywheel active. Start now:\n $rpi \"your goal\" — full $discovery → $crank → $validation pipeline\n $validation — close out recent work and capture learnings\n $research <topic> — explore the codebase\n Want issue tracking? brew install boshu2/agentops/beads && bd init --prefix <prefix>" |
| BD=true + CODEX=true |
"✅ Codex full stack ready.\n bd ready — see open work\n Start with $rpi \"your goal\", $research <topic>, or $status\n Default installs are hookless; native hooks are optional with install-codex.sh --with-hooks.\n Legacy explicit fallback commands remain ao codex ensure-start once per thread and ao codex ensure-stop during closeout when needed.\n Manual escape hatch: ao codex status" |
| BD=true |
"✅ Full stack ready.\n bd ready — see open work\n $rpi \"your goal\" — start a new goal from scratch\n $status — see current session state" |
Starting a new project? Run $scaffold <language> <name> to generate project structure with best practices.
See Also
- scaffold — Project scaffolding and component generation
Examples
First-Time Setup
User says: $quickstart
What happens: Agent detects tools, shows one-line status, gives the single next action to run.
Already Set Up
User says: $quickstart
What happens: Agent detects full stack is ready and suggests $rpi "your goal" or bd ready.
Troubleshooting
| Problem |
Solution |
| Skills not installed |
bash <(curl -fsSL https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install.sh) |
| Hook activation |
AgentOps 3.0 is hookless — there is no ao command or flag that installs hooks, and CI is the authoritative gate. Hooks are opt-in and author-it-yourself via the hooks-authoring skill. Explicit lifecycle fallback commands remain ao codex ensure-start and ao codex ensure-stop. |
| Flywheel count is 0 |
First session — run $rpi "a small goal" to start it |
| Want the full skill catalog |
Ask: "show me all the skills" or see references/full-catalog.md |
Reference Documents
- references/getting-started.md
- references/troubleshooting.md
- references/full-catalog.md
Local Resources
references/
- references/full-catalog.md
- references/getting-started.md
- references/troubleshooting.md
scripts/
1---2name: quickstart-23description: Show AgentOps next action.4---5# $quickstart67> **One job:** Tell a new user what AgentOps does and what to do first. Fast.89**YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.**1011## Execution Steps1213### Step 1: Detect setup1415```bash16git rev-parse --is-inside-work-tree >/dev/null 2>&1 && echo "GIT=true" || echo "GIT=false"17command -v ao >/dev/null && echo "AO=true" || echo "AO=false"18command -v bd >/dev/null && echo "BD=true" || echo "BD=false"19[ -d .agents ] && echo "AGENTS=true" || echo "AGENTS=false"20[ -d "$HOME/.agents" ] && echo "GLOBAL_AGENTS=true" || echo "GLOBAL_AGENTS=false"21[ -n "${CODEX_THREAD_ID:-}" ] || [ "${CODEX_INTERNAL_ORIGINATOR_OVERRIDE:-}" = "Codex Desktop" ] && echo "CODEX=true" || echo "CODEX=false"22```2324### Step 2: Show what AgentOps does2526Output exactly this (no additions, no diagrams):2728```29AgentOps is the operational layer for coding agents.3031It gives your coding agent four things it doesn't have by default:3233 Bookkeeping — sessions capture learnings, findings, and reusable context in .agents/34 Validation — $council, $pre-mortem, and $vibe challenge plans and code before shipping35 Primitives — skills, execution packets, and the ao CLI give you building blocks for almost any interaction36 Flows — $research, $implement, $validation, and $rpi can run alone or compose end to end3738Key skills: $rpi $research $validation $implement $council $pre-mortem $swarm $status39Full reference: $quickstart --catalog40```4142### Step 3: One next action4344Match the first row that applies. Output that message.4546| Condition | Message |47|-----------|---------|48| GIT=false + AO=true + GLOBAL_AGENTS=true | "🗂 You're outside a git repo but have a global corpus at `~/.agents`. Global knowledge workflow:\n 1. `$harvest` — scan all `.agents/` across your repos and promote artifacts into `~/.agents/learnings/`\n 2. `$compile` — mine, synthesize, and write an interlinked wiki into `.agents/compiled/` (runs from cwd; set `AGENTOPS_COMPILE_RUNTIME=ollama` or `openai` and the matching API key/host)\n 3. `$knowledge-activation` — turn the compiled corpus into playbooks, a belief book, and runtime briefings for future sessions\n 4. `$status` — flywheel health snapshot\nIf instead you want to start a fresh repo-local project here, `git init` first." |49| GIT=false | "⚠ Not in a git repo. Run `git init` first.\n (If you meant to work against your global `~/.agents` corpus, run `$quickstart` from a dir with `.agents/` or see `$harvest`, `$compile`, `$knowledge-activation`.)" |50| AO=false + CODEX=true | "📦 Install ao CLI first:\n brew tap boshu2/agentops https://github.com/boshu2/homebrew-agentops\n brew install agentops\n ao quick-start\nThen: `$rpi \"a small goal\"` to run your first cycle.\nUse `$bootstrap` after the core seed when you want PRODUCT.md, README.md, and PROGRAM.md." |51| AO=false | "📦 Install ao CLI first:\n brew tap boshu2/agentops https://github.com/boshu2/homebrew-agentops\n brew install agentops\n ao quick-start\nThen: `$rpi \"a small goal\"` to run your first cycle.\nUse `$bootstrap` after the core seed when you want PRODUCT.md, README.md, and PROGRAM.md." |52| AGENTS=false + CODEX=true | "🌱 ao is installed but not initialized here.\n Run `ao quick-start` to apply the repeatable core seed. `ao quickstart` is the stable alias.\n Then run `$bootstrap` only if you want the product/operations layer: PRODUCT.md, README.md, PROGRAM.md/AUTODEV.md, and optional hooks.\nThen: `$rpi \"a small goal\"` to run your first cycle." |53| AGENTS=false | "🌱 ao is installed but not initialized here.\n Run `ao quick-start` to apply the repeatable core seed. `ao quickstart` is the stable alias.\n Then run `$bootstrap` only if you want the product/operations layer: PRODUCT.md, README.md, PROGRAM.md/AUTODEV.md, and optional hooks.\nThen: `$rpi \"a small goal\"` to run your first cycle." |54| BD=false + CODEX=true | "✅ Codex plugin path ready.\n Start with `$rpi \"your goal\"`, `$research <topic>`, or `$status`\n Default installs are hookless; native hooks are optional with `install-codex.sh --with-hooks`.\n Legacy explicit fallback commands remain `ao codex ensure-start` once per thread and `ao codex ensure-stop` during closeout when needed.\n Manual escape hatch: `ao codex status`\n Want issue tracking? `brew install boshu2/agentops/beads && bd init --prefix <prefix>`" |55| BD=false | "✅ Flywheel active. Start now:\n `$rpi \"your goal\"` — full $discovery → $crank → $validation pipeline\n `$validation` — close out recent work and capture learnings\n `$research <topic>` — explore the codebase\n Want issue tracking? `brew install boshu2/agentops/beads && bd init --prefix <prefix>`" |56| BD=true + CODEX=true | "✅ Codex full stack ready.\n `bd ready` — see open work\n Start with `$rpi \"your goal\"`, `$research <topic>`, or `$status`\n Default installs are hookless; native hooks are optional with `install-codex.sh --with-hooks`.\n Legacy explicit fallback commands remain `ao codex ensure-start` once per thread and `ao codex ensure-stop` during closeout when needed.\n Manual escape hatch: `ao codex status`" |57| BD=true | "✅ Full stack ready.\n `bd ready` — see open work\n `$rpi \"your goal\"` — start a new goal from scratch\n `$status` — see current session state" |5859---6061Starting a new project? Run `$scaffold <language> <name>` to generate project structure with best practices.6263## See Also6465- [scaffold](../scaffold/SKILL.md) — Project scaffolding and component generation6667## Examples6869### First-Time Setup7071**User says:** `$quickstart`7273**What happens:** Agent detects tools, shows one-line status, gives the single next action to run.7475### Already Set Up7677**User says:** `$quickstart`7879**What happens:** Agent detects full stack is ready and suggests `$rpi "your goal"` or `bd ready`.8081## Troubleshooting8283| Problem | Solution |84|---------|----------|85| Skills not installed | `bash <(curl -fsSL https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install.sh)` |86| Hook activation | AgentOps 3.0 is hookless — there is no `ao` command or flag that installs hooks, and CI is the authoritative gate. Hooks are opt-in and author-it-yourself via the `hooks-authoring` skill. Explicit lifecycle fallback commands remain `ao codex ensure-start` and `ao codex ensure-stop`. |87| Flywheel count is 0 | First session — run `$rpi "a small goal"` to start it |88| Want the full skill catalog | Ask: "show me all the skills" or see `references/full-catalog.md` |8990## Reference Documents9192- [references/getting-started.md](references/getting-started.md)93- [references/troubleshooting.md](references/troubleshooting.md)94- [references/full-catalog.md](references/full-catalog.md)9596## Local Resources9798### references/99100- [references/full-catalog.md](references/full-catalog.md)101- [references/getting-started.md](references/getting-started.md)102- [references/troubleshooting.md](references/troubleshooting.md)103104### scripts/105106- `scripts/validate.sh`
majiayu000