* docs: clarify one-orchestrator-per-project model (closes#2005)
The architecture design doc defined "Orchestrator" only as "the central
server that manages everything," conflating the central daemon with the
per-project orchestrator agent. This implied a single orchestrator agent
spanning all projects.
The actual (and intended) model: one central daemon (`ao start`) manages
all registered projects, but each project gets its own orchestrator agent
session — one per project, enforced by the canonical orchestrator in
session-manager (ensureOrchestrator). Disambiguate the term in the
nomenclature table and the server-centric design principle.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs: remove stale design/architecture artifacts (closes#2005)
Delete historical design research, implementation specs, and PR-handoff
notes that are superseded by the shipped code and the living docs
(DESIGN.md, CLAUDE.md, docs/ARCHITECTURE.md, docs/DEVELOPMENT.md). None
were linked from any current doc.
Removed:
- artifacts/ — original design research (incl. architecture-design.md,
the doc #2005 flagged for the misleading "one central orchestrator"
framing; removing it resolves the ambiguity at the source)
- docs/design/ — Feb 2026 dashboard design-research artifacts
- docs/specs/ + design-*.html — implemented feature specs/analyses
- docs/state-machine-stage2-evidence-recovery-plan.md — shipped plan
- docs/SECURITY-AUDIT-SUMMARY.md — point-in-time audit snapshot
- handoff/pr-1466/ — handoff notes for a long-merged PR
Drop the now-dangling artifacts/ entry from .cursor/BUGBOT.md ignore list.
Confirms the one-orchestrator-per-project model: code enforces a single
canonical orchestrator per project (ensureOrchestrator); no multiple
orchestrators within one project.
* docs: restore docs flagged as still-relevant by review (#2005)
@yyovil flagged several docs as still needed. Restore the full
artifacts/ and docs/design/ trees, docs/specs/project-based-dashboard-
architecture.md, and handoff/pr-1466/ (kept whole for link cohesion).
artifacts/architecture-design.md is kept WITH the one-orchestrator-per-
project clarification (the #2005 fix) rather than deleted — resolving the
ambiguity in place. Restores the artifacts/ entry in .cursor/BUGBOT.md.
Remaining removals are limited to clearly point-in-time/superseded docs:
docs/state-machine-stage2-evidence-recovery-plan.md,
docs/SECURITY-AUDIT-SUMMARY.md, and four design/spec HTML analyses.
Renames all npm package scopes from @composio/* to @aoagents/* and
updates GitHub repo references from ComposioHQ/agent-orchestrator
to aoagents/ao throughout the codebase.
- All package.json names and dependencies
- README badges, links, and install instructions
- Documentation references
- Changeset config
- Source code imports and test files
The static file is fully superseded by the auto-generated orchestrator
prompt in packages/core/src/orchestrator-prompt.ts, which gets injected
dynamically via `ao start`. Also clean up stale references in comments
and architecture docs.
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* feat: add npm publishing support with @composio scope
Set up Changesets for version management, add publish metadata to all 20
packages under the @composio scope, create an unscoped wrapper package
(@composio/agent-orchestrator) for global install, and add a GitHub
Actions release workflow.
- Rename all packages from @agent-orchestrator/* to @composio/ao-*
- Add @composio/agent-orchestrator wrapper (bin shim → @composio/ao-cli)
- Add license, repository, homepage, bugs, files, engines to all packages
- Add .npmrc (access=public), MIT LICENSE file
- Add .changeset/ config with linked versioning for all packages
- Add .github/workflows/release.yml (changesets publish CI)
- Add changeset, version-packages, release scripts to root
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix: exclude private web package from release build
The release script now filters out @composio/ao-web, matching the
workflow's existing exclusion and preventing a Next.js build failure
from blocking npm publishing.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Review fixes:
- metadata: sessionId validation to prevent path traversal
- event-bus: guard appendFileSync, remove unused import
- lifecycle-manager: fix reaction retry counting (track attempts,
clear on status transition), allow retry on send failure instead
of immediate escalation, detect killed sessions in polling loop,
map session.killed to agent-exited reaction
- session-manager: validate status against union, clean up runtime
and workspace on spawn failure, kill with default plugins when
project config is missing
Lint/format fixes:
- Remove unused imports across all test files
- Replace `Function` type with typed callback in tmux tests
- Replace require() with dynamic import() in tests
- Replace dynamic delete with object spread in metadata
- Apply prettier formatting to all files
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Maps dependency graph, identifies 7 truly independent work streams
after Phase 0 (scaffold + types), with Linear tickets and spawn
commands ready to go.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The human never polls. The system notifies the human. Two-tier event
handling: auto-handle routine issues silently, push notifications only
when human judgment is required. Escalation chains, priority-based
routing, and the dashboard is a drill-down tool, not the primary interface.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Comprehensive analysis of 16+ competing agent orchestration tools
(Gas Town, OpenHands, SWE-ReX, Par, claude-flow, etc.) and detailed
architecture design with 8-slot plugin system, session lifecycle state
machine, and human attention optimization patterns.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Harshit Singh Bhandari
Prateek