Orchestration Setup

Service Information

• API Base URL: https://orc.aoendpoint.com
• Version: dev
• Required fields: invite_code, email, username, password

Prerequisites

Before starting, the user needs:

1. An invite code — provided by their administrator
2. The email address the invite was issued to

Setup Steps

Step 1: Collect Information

Ask the user for:

1. Invite code — the code they received from their administrator
2. Email address — must match the email the invite was issued to
3. Username — 3-30 characters, alphanumeric and hyphens, no leading/trailing hyphens
4. Password — minimum 12 characters, must contain uppercase, lowercase, digit, and special character

Also ask what they want to name their project (used for Triad tenant/project naming).

Step 2: Validate Invite (Optional Pre-check)

Before registration, you can verify the invite code is valid:

POST https://orc.aoendpoint.com/api/validate-invite
Content-Type: application/json

{
  "code": "THE_INVITE_CODE",
  "email": "user@example.com"
}

Success: 200 { "data": { "valid": true } }
Errors:
  404 INVALID_INVITE — code not found or email mismatch
  410 INVITE_ALREADY_USED — code already redeemed
  410 INVITE_EXPIRED — code past expiration

Step 3: Register

POST https://orc.aoendpoint.com/api/register
Content-Type: application/json

{
  "invite_code": "THE_INVITE_CODE",
  "email": "user@example.com",
  "username": "chosen-username",
  "password": "SecureP@ssw0rd!"
}

Success: 201
{
  "data": {
    "id": "uuid",
    "email": "user@example.com",
    "username": "chosen-username",
    "status": "active",
    "created_at": "2026-02-26T00:00:00Z"
  },
  "provisioning": {
    "akl": {
      "tenant_slug": "chosen-username",
      "api_key": "SHOWN_ONCE_SAVE_NOW",
      "api_key_prefix": "abcd1234",
      "project_slug": "default",
      "status": "success"
    },
    "doit": { ... same structure ... },
    "herald": { ... same structure ... }
  }
}

Errors:
  400 INVALID_INVITE — code not found or email mismatch
  400 INVALID_EMAIL — bad email format
  400 INVALID_USERNAME — bad username format
  400 WEAK_PASSWORD — password policy not met
  409 USERNAME_TAKEN — username already exists
  409 EMAIL_TAKEN — email already registered
  410 INVITE_ALREADY_USED — code already redeemed
  410 INVITE_EXPIRED — code past expiration

Step 4: Save API Keys

IMPORTANT: The API keys in the provisioning response are shown exactly once and cannot be retrieved again. Present them to the user immediately and warn them to save the keys.

Display something like:

Your accounts have been created. Here are your API keys — save them now, they will not be shown again:
AKL: [key]
Doit: [key]
Herald: [key]

Step 5: Install Scaffolding

Fetch the scaffolding templates:

GET https://orc.aoendpoint.com/api/scaffolding

This returns a JSON object with file paths and template contents. For each file:

1. Replace placeholders with the user's values:
   • {{PROJECT_NAME}} — the user's project name
   • {{PROJECT_KEY}} — the user's project key (slug form of project name)
   • {{AKL_URL}} — https://ama.aoendpoint.com
   • {{DOIT_URL}} — https://din.aoendpoint.com
   • {{HERALD_URL}} — https://herald.aoendpoint.com
   • {{AKL_API_KEY}} — the AKL API key from registration
   • {{DOIT_API_KEY}} — the Doit API key from registration
   • {{HERALD_API_KEY}} — the Herald API key from registration
2. Create the file at the specified path relative to the project root

This delivers 22 files total:

• CLAUDE.md — Governance instructions (principles, Triad, phases, gates, risk levels)
• .orchestra/config.yaml — Triad configuration with API keys and governance settings
• .mcp.json — MCP server connection configuration for Claude Code
• .claude/commands/ — 11 orchestration command files (orc-orchestrate, orc-create-epic, orc-backlog, etc.)
• .claude/agents/ — 9 agent definition files (architecture, code-generation, review, verification, etc.)

Step 6: Configure MCP Servers

Add the Triad MCP servers to the project's .mcp.json file:

{
  "mcpServers": {
    "akl": {
      "type": "url",
      "url": "https://ama.aoendpoint.com/mcp",
      "headers": { "Authorization": "Bearer {{AKL_API_KEY}}" }
    },
    "doit": {
      "type": "url",
      "url": "https://din.aoendpoint.com/mcp",
      "headers": { "Authorization": "Bearer {{DOIT_API_KEY}}" }
    },
    "herald": {
      "type": "url",
      "url": "https://herald.aoendpoint.com/mcp",
      "headers": { "Authorization": "Bearer {{HERALD_API_KEY}}" }
    }
  }
}

Replace {{...}} placeholders with the actual API keys from Step 4.

Verification

After setup, verify everything works by running these checks:

1. AKL: Call akl_overview() — expect a response with tenant data (not an auth error)
2. Doit: Call doit_list_projects() — expect the user's "default" project to appear
3. Herald: Call herald_agents() — expect no auth error
4. Config: Verify .orchestra/config.yaml exists with correct API keys
5. Governance: Verify CLAUDE.md exists with orchestration instructions

If all checks pass, setup is complete. Suggest the user run /orc-backlog to see the system working.

Troubleshooting