Webton ADOS CLI

Install

Local dev:

npm install
npm run build
node dist/index.js --help

Global install test:

npm pack
npm i -g ./webton-ados-*.tgz
ados --help

Commands

• ados init — Bootstrap ADOS structure into the current repo (first-time setup)
• ados bootstrap — Sync/update ADOS files in an existing repo (ongoing sync)
• ados prime
• ados plan <issue>
• ados execute [branch]
• ados validate
• ados validate:simple
• ados review-pr [pr]
• ados create-pr
• ados commit
• ados sync [ref]
• ados doctor — Run environment + source-layer diagnostics

UX flags

• --no-ascii
• --plain

ados init — Repo Bootstrap

ados init copies ADOS workflow assets from the package bundle into the current directory's .agent/ folder, turning any repo into an ADOS-managed repo.

After init, commands like ados prime resolve from the repo layer (.agent/workflows/) instead of the package fallback — allowing per-repo customisation.

Modes

| Mode | Flag | Files copied | |------|------|-------------| | Minimal (default) | (none) or --minimal | Core workflows: prime, plan-feature, execute, validate, validate-simple, commit | | Full | --full | All minimal + review-pr, create-pr, sync-release, ASCII branding art |

Flags

| Flag | Description | |------|-------------| | --minimal | Create essential baseline only (default) | | --full | Include broader workflow + template set | | --force | Overwrite existing files (default: skip) | | --dry-run | Print planned operations, write nothing |

Examples

# Bootstrap with defaults (minimal, no overwrite)
ados init

# Full set (all workflows + branding)
ados init --full

# Preview what would be created without writing
ados init --dry-run
ados init --full --dry-run

# Overwrite existing files (e.g. to reset to package defaults)
ados init --force
ados init --full --force

# Verify the resolver picks up repo layer after init
ados --plain prime
# → "Workflow loaded (repo)"

Output summary

After running, ados init prints a summary of:

• ✅ Created — new files written to .agent/
• ♻️ Overwritten — files replaced (only with --force)
• ⏭ Skipped — files that already existed (omit --force to preserve customisations)
• ❌ Errors — failures (non-zero exit)

ados bootstrap — Ongoing Sync

ados bootstrap is for keeping an already-ADOS-managed repo up to date with the upstream baseline. Unlike ados init (which blindly creates/overwrites), bootstrap compares each file's content hash and classifies it before acting.

init vs bootstrap

| Aspect | ados init | ados bootstrap | |--------|-------------|-----------------| | Purpose | First-time setup | Ongoing sync / update | | Detects footprint | No | Yes (.agent/ detection) | | File classification | create / skip / overwrite | create / unchanged / diverged | | Default action | create missing, skip existing | Dry-run preview (no writes) | | Requires explicit write | No | Yes (--apply) | | Safe to run repeatedly | ⚠️ (may overwrite with --force) | ✅ (idempotent, hash-aware) |

File Classification

| Classification | Meaning | Default action | With --force | |----------------|---------|----------------|----------------| | create | Target missing | Write | Write | | unchanged | Hash matches source | Skip | Skip | | diverged | Content differs | Skip | Write |

Flags

| Flag | Description | |------|-------------| | --dry-run | Preview plan, write nothing (implicit default) | | --apply | Actually write changes | | --force | Overwrite diverged files (default: keep customisations) | | --from <layer> | Source layer: package (default) or home | | --minimal | Scope: essential files only (default) | | --full | Scope: full workflow + branding set |

Examples

# Preview what needs updating (safe — no writes)
ados bootstrap
ados bootstrap --full

# Apply updates: create missing, preserve customised files
ados bootstrap --apply

# Apply and overwrite diverged files (reset to package baseline)
ados bootstrap --apply --force

# Full scope + force (complete reset)
ados bootstrap --apply --full --force

# Sync from home layer instead of package
ados bootstrap --apply --from home

ados doctor — Environment & Source-Layer Diagnostics

ados doctor performs a non-destructive health check and reports the effective source layer for each ADOS asset type. It is safe to run from any directory — including outside an ADOS-managed repo.

Checks performed

| Check | Description | |-------|-------------| | Git repo | Whether the cwd is inside a git repository | | .agent directory | Whether an ADOS repo structure is detected | | .agent/workflows >= 5 | Minimum workflow count sanity check | | Working tree clean | Detects uncommitted changes | | gh auth | GitHub CLI authentication status | | Node >= 18 | Node.js version requirement | | ADOS_HOME | Path + existence/readability of $ADOS_HOME (default: ~/.webton-ados) | | Workflow source | Effective layer for prime.md: repo / home / package / missing | | Branding source | Effective layer for ASCII art: repo / home / package / missing | | Config source | Effective layer for ados.json: repo / home / package / missing — using defaults |

Source layer statuses

| Status | Meaning | |--------|---------| | repo | Asset found in .agent/ within the current repo | | home | Asset found in $ADOS_HOME (user-level override) | | package | Asset found in the npm package bundle (default fallback) | | missing | Asset not found in any layer |

Example output

=== ADOS Doctor ===

✅ Git repo
✅ .agent directory
✅ .agent/workflows >= 5 (8 files)
✅ Working tree clean (clean)
✅ gh auth
✅ Node >= 18 (22.14.0)
⚠️ Update check (skipped in MVP)
⚠️ ADOS_HOME (/home/user/.webton-ados — missing)
✅ Workflow source (prime.md) (repo)
✅ Branding source (ascii) (package)
⚠️ Config source (ados.json) (missing — using defaults)

Behaviour outside an ADOS repo

Doctor runs without error outside any ADOS-managed directory. Git-specific checks may fail (expected) but source-layer diagnostics still resolve correctly via package fallback:

⚠️ .agent directory (not in an ADOS repo)
⚠️ .agent/workflows >= 5 (not in an ADOS repo)
✅ Workflow source (prime.md) (package)
✅ Branding source (ascii) (package)
⚠️ Config source (ados.json) (missing — using defaults)

Asset Resolution (layered)

The CLI resolves workflow and branding assets through a three-layer hierarchy (highest → lowest priority):

1. repo — .agent/workflows/<file> in the current repo (if an ADOS-managed repo is detected)
2. home — $ADOS_HOME/<file> (default: ~/.webton-ados/)
3. package — bundled fallback assets shipped inside the npm package (assets/)

This means the CLI works out of the box in any directory, even without an ADOS-prepared repo. Package-bundled assets mirror the canonical versions from the Default-AI-Workflow-Commands repo and are updated with each CLI release.

Bundled assets (cli/assets/)

| Path | Description | |------|-------------| | assets/workflows/prime.md | Prime agent workflow | | assets/workflows/plan-feature.md | Feature planning workflow | | assets/workflows/execute.md | Execution workflow | | assets/workflows/validate.md | Full validation workflow | | assets/workflows/validate-simple.md | Quick validation workflow | | assets/workflows/review-pr.md | PR review workflow | | assets/workflows/create-pr.md | PR creation workflow | | assets/workflows/commit.md | Commit workflow | | assets/workflows/sync-release.md | Release sync workflow | | assets/branding/webton-ados-ascii-art.txt | ASCII art banner |