ao-starter

CLI tool to scaffold Agent Orchestrator (AO) workflows for any project. Automatically detects project type and generates optimized workflow configurations.

Features • Installation • Usage • Templates • Troubleshooting • Contributing

Features

🔍 Auto-detection — Automatically detects project type (TypeScript, Rust, Python, Next.js, Go, and more)
📦 Monorepo Support — Works with Nx, Turborepo, pnpm workspaces, and Lerna
🎨 Pre-built Templates — Optimized workflow configurations for common project types
⚡ Quick Setup — Get started with AO in seconds
🔧 Customizable — Override auto-detection and customize templates

Installation

Global Installation (Recommended)

npm install -g ao-starter

Shell Script Installation (No npm required)

For systems with curl and Node.js but without npm, use the shell script installer:

curl -fsSL https://raw.githubusercontent.com/launchapp-dev/ao-starter/main/install.sh | bash

Or download and run locally:

curl -fsSL https://raw.githubusercontent.com/launchapp-dev/ao-starter/main/install.sh -o install.sh
chmod +x install.sh
./install.sh

Installer options:

# Install a specific version
curl -fsSL https://raw.githubusercontent.com/launchapp-dev/ao-starter/main/install.sh | bash -s -- --version 0.1.0

# Uninstall
curl -fsSL https://raw.githubusercontent.com/launchapp-dev/ao-starter/main/install.sh | bash -s -- --uninstall

# Force npm installation method
curl -fsSL https://raw.githubusercontent.com/launchapp-dev/ao-starter/main/install.sh | bash -s -- --npm

This installs ao (or create-ao) globally, making it available from anywhere:

ao --version
ao init

Using npx (No Installation)

Run directly without installing:

npx ao-starter init

Or use the shorter create-ao alias:

npx create-ao init

Requirements

Node.js >= 18.0.0
npm >= 9.0.0 (or yarn/pnpm)

Quick Start

Navigate to your project:
```
cd your-project
```
Initialize AO workflows (auto-detect):
```
ao init
```
Start the AO daemon:
```
ao daemon start
```
View available tasks:
```
ao task list
```

Usage

`ao init`

Initialize AO workflows for the current project. Automatically detects project type and generates optimized configurations.

Basic Usage

# Auto-detect project type and generate workflows
ao init

# Or use the full command name
create-ao init

Specify a Template

# Use a specific template
ao init --template nextjs
ao init --template rust
ao init --template python
ao init --template typescript-monorepo

# Shorthand
ao init -t nextjs

Preview Changes

# Preview changes without writing files
ao init --dry-run

Custom Output Directory

# Generate files to a custom directory
ao init --output ./my-ao-config

# Files will be created in ./my-ao-config/ instead of ./.ao/

Skip Auto-Detection

# Use default template without auto-detection
ao init --skip-detect

Force Override

# Force regeneration even if .ao directory exists
ao init --force

Combine Options

# Use specific template with dry-run
ao init --template nextjs --dry-run

# Force override with custom output
ao init --force --output ./config

`ao init` Options

Option	Short	Description	Default
`--template <id>`	`-t`	Template ID to use	Auto-detect
`--list`	`-l`	List available templates	-
`--output <path>`	`-o`	Output directory	`.ao`
`--skip-detect`	-	Skip auto-detection	`false`
`--force`	-	Force override existing files	`false`
`--dry-run`	-	Preview without writing	`false`

`ao detect`

Analyze the current project and display detected type, framework, and recommendations.

Human-Readable Output

ao detect

Example Output:

🚀 AO Starter - Scaffold AO workflows for any project

Analyzing project...

Project Detection Results:

  Type:       nextjs
  Framework:  Next.js
  Language:  TypeScript
  Package:   my-app

Recommendations:

  1. Use --template nextjs if this is a Next.js monorepo
  2. Consider using package-specific workflows for each app

Run `create-ao init` to generate AO workflow files.

JSON Output

# Output in JSON format for scripting
ao detect --json

Example JSON Output:

{
  "type": "nextjs",
  "confidence": 95,
  "framework": "Next.js",
  "language": "TypeScript",
  "monorepo": false,
  "rootPackage": "my-app",
  "buildTool": "next",
  "indicators": ["package.json", "tsconfig.json"],
  "recommendations": [
    "Run: ao init to generate Next.js optimized workflows",
    "Consider adding e2e testing phases"
  ]
}

`ao templates`

List all available templates with descriptions.

ao init --list
# or
ao templates

Example Output:

📦 Available Templates

  default                 Standard AO workflow configuration for general projects (default)
    Suitable for: Any project type

  typescript              TypeScript-optimized workflows with type checking phases
    Suitable for: TypeScript projects, Node.js backends

  typescript-monorepo     Multi-package workflows for Nx, Turborepo, or pnpm workspaces
    Suitable for: Monorepo projects, Shared libraries, Multiple packages

  javascript              JavaScript-focused workflows with linting and testing
    Suitable for: JavaScript projects, Legacy codebases

  nextjs                  Full-stack Next.js workflows with API routes and server components
    Suitable for: Next.js applications, React projects, Full-stack apps

  rust                    Rust-optimized workflows with clippy, fmt, and benchmarking
    Suitable for: Rust projects, Systems programming, CLI tools

  rust-workspace          Multi-crate Rust workflows for cargo workspaces
    Suitable for: Rust workspaces, Multiple crates, Library development

  python                  Python workflows with mypy, pytest, and poetry support
    Suitable for: Python projects, ML/data projects, API backends

  bun                     Bun-optimized workflows with fast test execution and bundling
    Suitable for: Bun projects, JavaScript/TypeScript, High-performance apps

  deno                    Deno-optimized workflows with built-in testing and security
    Suitable for: Deno projects, TypeScript, Secure serverless

  go                      Go-optimized workflows with go vet, golint, and testing
    Suitable for: Go projects, CLI tools, Network services, Microservices

  elixir                  Elixir-optimized workflows with mix, ExUnit, and credo
    Suitable for: Elixir projects, Phoenix apps, Distributed systems

Usage:
  ao init --template <template-id>

💡 Quick Recommendations:

  • For Next.js projects, use: --template nextjs
  • For Rust projects, use: --template rust
  • For Python projects, use: --template python
  • For Bun projects, use: --template bun
  • For Deno projects, use: --template deno
  • For Go projects, use: --template go
  • For Elixir projects, use: --template elixir

Templates

Template	Description	Project Types
default	Standard AO workflow configuration	Any project
typescript	TypeScript-optimized with type checking	TypeScript, Node.js
typescript-monorepo	Multi-package for monorepos	Nx, Turborepo, pnpm workspaces
javascript	JavaScript with linting and testing	JavaScript, Legacy code
nextjs	Next.js with API routes	Next.js, React, Full-stack
rust	Rust with clippy and fmt	Rust, CLI tools
rust-workspace	Multi-crate for workspaces	Rust workspaces
python	Python with pytest and mypy	Python, ML, APIs
bun	Bun with fast test and bundling	Bun, JavaScript, TypeScript
deno	Deno with built-in testing	Deno, TypeScript, Serverless
go	Go with vet and golint	Go, CLI tools, Microservices
elixir	Elixir with mix and credo	Elixir, Phoenix, Distributed systems

Template-Specific Features

Next.js Template

SSR/SSG build phases
API route testing
E2E testing with Playwright
Type checking with tsc

Rust Template

Cargo build phases
Clippy linting
Rustfmt formatting
Test and benchmark phases

Python Template

Pytest testing
MyPy type checking
Black formatting
Poetry/Pipenv support

TypeScript Monorepo Template

Package-specific workflows
Shared library builds
Workspace dependency resolution

Generated Files

The ao init command generates the following files in the .ao/ directory:

File	Description
`custom.yaml`	Custom configuration settings and scheduling
`agents.yaml`	Agent definitions and capabilities
`phases.yaml`	Phase definitions for workflows
`workflows.yaml`	Workflow compositions
`README.md`	Documentation for the generated configuration

File Structure Example

your-project/
├── .ao/
│   ├── custom.yaml      # Daemon settings, schedules
│   ├── agents.yaml      # Agent roles and capabilities
│   ├── phases.yaml      # Workflow phases
│   ├── workflows.yaml   # Workflow definitions
│   └── README.md        # Configuration documentation
├── package.json
└── src/
    └── index.ts

Troubleshooting

Common Issues

Permission Denied

Error: Permission denied: Cannot write to directory ".ao"

Solutions:

Check directory permissions:
```
chmod u+w .ao
```
Run with elevated permissions if needed:
```
sudo ao init
```
Use a different output directory:
```
ao init --output ./my-ao-config
```

Invalid Template

Error: Invalid template "next". Available templates: default, typescript, nextjs, ...

Solutions:

Check available templates:
```
ao init --list
```
Use the correct template name (e.g., nextjs not next):
```
ao init --template nextjs
```

Project Not Detected

Detected project type: unknown

Solutions:

Verify you're in a project directory with recognizable files:

# Check for expected files
ls -la package.json Cargo.toml pyproject.toml

Manually specify a template:
```
ao init --template default
```
Check project detection with verbose output:
```
ao detect
```

Existing Files Warning

Warning: The following files already exist and will be overwritten:
  .ao/agents.yaml
  .ao/phases.yaml

Solutions:

Review the changes with dry-run:
```
ao init --dry-run
```
Force override:
```
ao init --force
```
Backup existing files first:
```
cp -r .ao .ao.backup
ao init --force
```

Node.js Version Requirement

npm install -g ao-starter
# Error: Unsupported engine

Solution: Upgrade Node.js to >= 18.0.0:

# Using nvm
nvm install 18
nvm use 18

# Or using official installer
# https://nodejs.org/

Getting Help

Check the documentation:

ao --help
ao init --help
ao detect --help

View the generated README:
```
cat .ao/README.md
```
Report an issue: GitHub Issues

Development

Prerequisites

Node.js >= 18.0.0
npm >= 9.0.0

Setup

# Clone the repository
git clone https://github.com/launchapp-dev/ao-starter.git
cd ao-starter

# Install dependencies
npm install

# Build the project
npm run build

Development Workflow

# Build in watch mode
npm run dev

# Run locally
npm start -- init

# Or run the built version
node dist/index.js init

Testing

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run specific test file
npm test -- src/commands/templates.test.ts

Linting

# Run linter
npm run lint

# Auto-fix issues
npm run lint -- --fix

Type Checking

npm run typecheck

Build

# Clean and rebuild
npm run clean
npm run build

# Prepare for publishing
npm run prepublishOnly

Related Projects

Project	Description
AO CLI	Agent Orchestrator CLI
AO Skills	Agent skills library
AO Docs	Documentation

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Getting Started

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Coding Standards

Follow TypeScript best practices
Run npm run lint and npm test before submitting
Add tests for new features
Update documentation as needed

Commit Messages

Follow Conventional Commits:

feat: New feature
fix: Bug fix
docs: Documentation changes
refactor: Code refactoring
test: Test changes
chore: Maintenance tasks

License

MIT License - see LICENSE for details.

Back to top

Name		Name	Last commit message	Last commit date
Latest commit History 67 Commits
.ao		.ao
.github/workflows		.github/workflows
src		src
.gitignore		.gitignore
.mcp.json		.mcp.json
.npmignore		.npmignore
LICENSE		LICENSE
README.md		README.md
VISION.md		VISION.md
eslint.config.js		eslint.config.js
install.sh		install.sh
jest.config.js		jest.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

ao-starter

Table of Contents

Features

Installation

Global Installation (Recommended)

Shell Script Installation (No npm required)

Using npx (No Installation)

Requirements

Quick Start

Usage

ao init

Basic Usage

Specify a Template

Preview Changes

Custom Output Directory

Skip Auto-Detection

Force Override

Combine Options

ao init Options

ao detect

Human-Readable Output

JSON Output

ao templates

Templates

Template-Specific Features

Next.js Template

Rust Template

Python Template

TypeScript Monorepo Template

Generated Files

File Structure Example

Troubleshooting

Common Issues

Permission Denied

Invalid Template

Project Not Detected

Existing Files Warning

Node.js Version Requirement

Getting Help

Development

Prerequisites

Setup

Development Workflow

Testing

Linting

Type Checking

Build

Related Projects

Contributing

Getting Started

Coding Standards

Commit Messages

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`ao init`

`ao init` Options

`ao detect`

`ao templates`

Packages