docs(projects): compare AO multi-project config

[christso]

Summary

This is a findings-only PR for the requested AO multi-project config comparison. I did not implement a code/config mechanism because the AO patterns that differ from AgentV are operational-agent concerns and do not currently fit AgentV's lightweight multi-project Dashboard registry.

What was compared

Local AO setup:

• /home/entity/.agent-orchestrator/config.yaml
  • projects.agentv_af00e23536
  • projects.allagents_4ce7565799
  • defaults
  • notificationRouting
  • notifiers
• /home/entity/projects/tsoyang-org/composio-ao-deploy/README.md
• /home/entity/projects/tsoyang-org/composio-ao-deploy/docs/agentv.md
• AO upstream local docs/examples:
  • agent-orchestrator.yaml.example
  • examples/multi-project.yaml
  • ARCHITECTURE.md
  • skills/agent-orchestrator/references/config.md

AgentV implementation:

• packages/core/src/projects.ts
• packages/core/test/projects.test.ts
• apps/web/src/content/docs/docs/tools/dashboard.mdx

Findings

• AgentV already has the AO lesson that matters for Dashboard multi-project mode: a single source of truth (~/.agentv/projects.yaml) that is re-read per /api/projects request, so direct edits/API writes/CLI changes are live without restart.
• AO's richer config (defaults, role-specific agent settings, repo/defaultBranch/sessionPrefix, trackers, notification routing, workspace policy) supports operating coding agents across repos. AgentV's multi-project registry only needs to locate eval artifact directories and optionally sync remotes.
• Importing AO-like config would add speculative fields and second modes. The most tempting option, an object-map projects: shape keyed by ID, would reduce repeated id fields but add save-format/migration/ordering complexity without demonstrated demand.
• AO's config uses camelCase fields (projectId, defaultBranch, displayName, sessionPrefix), while AgentV's wire convention requires snake_case. Copying AO shape directly would violate AgentV conventions.

Recommendation

Do not change AgentV's multi-project config right now. Keep the current array-of-projects registry, optional source sync, live reload, and snake_case wire format. If direct YAML editing becomes a demonstrated pain point, consider a separate AgentV-native proposal for a snake_case object-map shape, but do not add it speculatively.

Changes

• Added docs/research/ao-multi-project-config.md with the full comparison and recommendation.

Verification / UAT evidence

No behavior was changed, so red/green functional UAT is not applicable. Validation performed:

• Research inputs were read from the local AO config/deploy docs/upstream AO docs listed above.
• Existing AgentV project registry tests still pass:
  • bun test ./packages/core/test/projects.test.ts → 13 pass, 0 fail
• Pre-push hook passed on push:
  • build passed
  • typecheck passed
  • lint passed
  • tests passed
  • validate eval YAML files passed

[cloudflare-workers-and-pages]

Deploying agentv with    Cloudflare Pages

Latest commit:	61d159d
Status:	✅  Deploy successful!
Preview URL:	https://ef407210.agentv.pages.dev
Branch Preview URL:	https://session-age-6.agentv.pages.dev

View logs

[christso]

CI check-in (2026-06-02): AO reported failing checks, but re-inspection shows PR head 61d159d has all checks passing: Check Links, Validate Marketplace, Validate Evals, and Cloudflare Pages. No actionable CI fix was needed.

[christso]

Closing per user request. Findings were reviewed and no implementation is being pursued.