ace

ACE — AI Connect Engine

Orchestrates the ACE lifecycle for Connect opportunities, from idea through app building, deployment, LLO management, and closeout.

ACE is a Claude Code plugin with the same architecture as canopy: agents orchestrate skills, skills are prompt-based capability definitions, and MCP servers provide programmatic access to external systems.

Prerequisites

Before /ace:setup will succeed, you need:

• Node.js v18+ with npm (https://nodejs.org). Apple Silicon: brew install node.
• 1Password CLI (op). Mac: brew install 1password-cli. Other platforms: https://developer.1password.com/docs/cli/get-started/.
  • On Mac, also enable 1Password.app → Settings → Developer → "Connect with 1Password CLI" for biometric unlock — that's the smoothest auth path. Alternative: op signin --account dimagi.1password.com interactively when /ace:setup prompts.
• 1Password account at dimagi.1password.com, with read access to the AI-Agents vault. Ask Jon (or whoever owns the vault) to grant access — without it, op inject will fail with cryptic permission errors. The full set of items ACE reads from AI-Agents: ACE - Google Service Account (Document), ACE - Open Chat Studio, ACE - CommCareHQ, ACE - Connect Labs, Content Generator API, connect-test-user, plus two UUID-referenced API-key items (linked from .env.tpl).
• GitHub access to jjackson/ace (currently public; no extra step needed). gh auth login is not required unless you plan to push.
• Network reachability to openchatstudio.com, connect.dimagi.com, commcarehq.org, labs.connect.dimagi.com, googleapis.com. Corp VPNs and proxies sometimes block these — /ace:doctor reports an explicit status per host.
• Playwright Chromium browser binary. Auto-installed on first use; if you hit "browser doesn't open" errors, run npx playwright install chromium.

Mobile (Phase 6 only) is currently Mac-only. Phases 1–4 and 6–9 work on Mac, Linux, and Windows. Phase 6 (mobile screenshot capture against an Android emulator) has only been live-validated on macOS Apple Silicon — the Linux/Windows installer commands in commands/mobile-bootstrap.md exist but haven't been tested end-to-end. If you're on Windows, you can run everything except Phase 6; ask Jon for the workaround.

Quick Start

/plugin marketplace add jjackson/ace     # Add the ACE marketplace
/plugin install ace@ace                  # Install the plugin
/ace:setup                               # Install deps + verify the service-account key
/ace:doctor                              # Sanity-check everything

/ace:run                                 # Run full lifecycle (smart defaults)
/ace:run <opp-name> --mode review        # Run full lifecycle for a named slug
/ace:run --dry-run                       # Test without side effects
/ace:run --sandbox                       # Route to staging endpoints
/ace:step <skill-name> <opp-name>        # Run a single step
/ace:status                              # Show all opportunities
/ace:eval <opp-name> --mode deep         # Umbrella eval (aggregates verdicts/*)
/ace:docs                                # Generate playbook
/ace:update                              # Pull the latest release from GitHub

First-Run Walkthrough

The commands above are only the happy path once everything is configured. For a fresh install (or a new machine), run through this checklist top-to-bottom. Stop at any step that fails — the next step won't work.

1. Install the plugin — /plugin marketplace add jjackson/ace then /plugin install ace@ace.

2. Run /ace:setup — does almost everything for you in one shot: verifies Node + op + 1Password signin, fetches the GWS service-account key from the AI-Agents vault into ${CLAUDE_PLUGIN_DATA}/gws-sa-key.json, runs npm install, injects .env from 1Password, and finishes by running /ace:doctor.

   • If op isn't signed in, the script prints the exact ! op signin --account dimagi.1password.com line — type it in the chat (the ! prefix runs the command in this session), then re-run /ace:setup.
   • If 1Password can't find the SA-key Document, the script lists candidate items in AI-Agents so you can pick the right one with ACE_GWS_KEY_OP_DOC=.... Worst case, ask Jon for the JSON and drop it manually at the path the script printed.

3. Authenticate to OCS — /ace:ocs-login opens a headed browser so you can sign in (SSO/MFA included). Session state is saved to ~/.ace/ocs-session-<team>.json for headless reuse.

   • Most colleagues won't need this step: if OCS_USERNAME / OCS_PASSWORD resolved into .env (they do by default for [email protected]), the MCP backend auto-logs-in on first call. /ace:ocs-login is the manual fallback for SSO/MFA edge cases.