# Multi-Agent Orchestrator Sprint 1 ## Sprint Goal Deliver a file-based MVP that can initialize a workflow workspace, define roles and tasks, record append-only events, enforce basic readiness gates, create structured handoffs, and show status. This sprint proves collaboration through artifacts before adding real LLM provider execution. ## Sprint Assumptions - The first implementation is local-first and file-based. - No real LLM provider integration is required in Sprint 1. - The CLI is the primary interface. - TypeScript/Node is the primary runtime for the CLI, schemas, workflow engine, and Playwright integration. - Python is allowed as an auxiliary worker runtime for tasks where it is clearly stronger, such as data processing, ML/AI utilities, report generation, or integrations with Python-first tooling. - The orchestrator must be provider-agnostic from the data model, even if providers are not implemented yet. - The MVP should work inside any git repository without requiring external services. ## Stack Decision - **Primary language**: TypeScript. - **Runtime**: Node.js. - **CLI**: Node-based `orchestra`. - **Schema validation**: TypeScript-first schema library. - **Automated browser testing**: Playwright. - **Unit tests**: TypeScript test runner selected during implementation. - **Auxiliary runtime**: Python workers invoked only through explicit command contracts. Rationale: - Web and Playwright are first-class priorities, so TypeScript keeps CLI, browser automation, schemas, and future UI work in one ecosystem. - Python remains available for specialized workers without making the orchestrator depend on Python for its core control plane. - Provider and tool integrations must stay behind interfaces so the runtime choice does not leak into workflow artifacts. ## In Scope - `.agent-workflow/` structure. - Configurable roles. - Task graph persistence. - Append-only event log. - Basic status command. - Basic handoff generation and validation. - Basic review recording. - Basic evidence registration. - Definition of Ready gate. - Provider configuration schema stub. - Version-controlled pre-commit hook contract for static analysis. ## Out of Scope - Real LLM API calls. - Automatic code editing. - Parallel process execution. - Playwright test generation. - Python worker implementation. - Web UI. - Cloud storage. - Multi-user authentication. ## Sprint Backlog ### Story CLI-001: Initialize Workflow Priority: P0 As a user, I want `orchestra init` to create workflow files so that a repo can opt into orchestrated agent work. Acceptance criteria: - Creates `.agent-workflow/`. - Creates `tasks.json`, `roles.json`, `locks.json`, `events.jsonl`, and `config.json`. - Creates `decisions/`, `handoffs/`, `evidence/`, and `reviews/`. - Does not overwrite existing workflow files unless `--force` is passed. - Prints next steps after initialization. Developer tasks: - Define default workspace layout. - Implement init command. - Add schema validation for generated files. - Add unit tests for normal init, existing files, and force mode. QA notes: - Verify init in empty repo. - Verify init in repo with existing `.agent-workflow/`. - Verify generated JSON is valid. Evidence required: - Unit test command and result. - Sample generated tree. ### Story ROLE-001: Define Role Catalog Priority: P0 As an administrator, I want default roles generated during init so that tasks can be assigned to explicit responsibilities. Acceptance criteria: - `roles.json` includes core roles: parent, product_owner, architect, developer, qa, security, devops, sre, dba, ux_ui_designer, release_manager, compliance_privacy, technical_writer. - Each role includes name, description, capabilities, required handoff fields, and blocking authority. - Role schema rejects missing role ID, description, or capabilities. Developer tasks: - Define role schema. - Add default roles. - Add validation tests. QA notes: - Verify all default roles are created. - Verify invalid roles fail validation. Evidence required: - Unit test command and result. - `roles.json` sample. ### Story TASK-001: Persist Task State Priority: P0 As a parent agent, I want task state persisted to disk so that workflow status survives process restarts. Acceptance criteria: - `tasks.json` stores task ID, title, owner role, status, dependencies, inputs, outputs, gates, and timestamps. - Supports statuses: pending, ready, in_progress, blocked, review, approved, rejected, done, canceled. - Rejects dependencies that point to unknown task IDs. - Rejects tasks assigned to unknown roles. Developer tasks: - Define task schema. - Implement task read/write helpers. - Add validation for dependencies and role references. - Add unit tests. QA notes: - Verify valid task file passes. - Verify unknown dependency fails. - Verify unknown owner role fails. Evidence required: - Unit test command and result. - Example task graph. ### Story MEM-001: Append Workflow Events Priority: P0 As a system, I want all workflow events stored in an append-only log so that collaboration is auditable. Acceptance criteria: - Appends JSON lines to `events.jsonl`. - Event includes ID, type, task ID, actor role, timestamp, summary, artifact links, and metadata. - Supports event types: WORKFLOW_INITIALIZED, TASK_ASSIGNED, HANDOFF_READY, REVIEW_RECORDED, EVIDENCE_ADDED, GATE_BLOCKED, GATE_PASSED. - Does not rewrite existing events. Developer tasks: - Define event schema. - Implement append helper. - Add event ID generation. - Add unit tests for append-only behavior. QA notes: - Verify multiple events append in order. - Verify invalid event is rejected. Evidence required: - Unit test command and result. - Example `events.jsonl`. ### Story CLI-002: Show Status Priority: P0 As a user, I want `orchestra status` to show workflow progress so that I can inspect current state quickly. Acceptance criteria: - Shows task counts by status. - Shows blocked tasks and reasons. - Shows pending reviews and missing evidence. - Shows active locks. - Supports `--json`. Developer tasks: - Implement status reader. - Add human-readable formatter. - Add JSON output. - Add unit tests for empty, normal, and blocked states. QA notes: - Verify status before and after sample tasks. - Verify JSON output is parseable. Evidence required: - Unit test command and result. - Example status output. ### Story GATE-001: Enforce Definition of Ready Priority: P0 As a parent agent, I want readiness validated before implementation so that work does not start with hidden ambiguity. Acceptance criteria: - Validates backlog item, goal, scope, acceptance criteria, assumptions, risks, selected roles, and test strategy. - Produces a readiness report. - Blocks tasks from moving to `ready` when required fields are missing. - Allows mechanical-task override with rationale. Developer tasks: - Define readiness schema. - Implement readiness validator. - Add transition guard for pending to ready. - Add unit tests. QA notes: - Verify complete task passes readiness. - Verify missing acceptance criteria blocks readiness. - Verify mechanical override records rationale. Evidence required: - Unit test command and result. - Example readiness report. ### Story HAND-001: Generate Developer-to-QA Handoff Priority: P1 As a Developer, I want a structured handoff to QA so that QA can test with full context. Acceptance criteria: - Generates handoff markdown under `handoffs/`. - Includes task ID, changed components, behavior changed, unit tests, commands run, known gaps, risks, and recommended Playwright coverage. - Validates required fields before recording HANDOFF_READY event. Developer tasks: - Create handoff template. - Implement `orchestra handoff`. - Validate required fields. - Add unit tests. QA notes: - Verify handoff generated from valid input. - Verify missing test evidence blocks handoff. Evidence required: - Unit test command and result. - Example handoff markdown. ### Story CLI-004: Record Review Priority: P1 As a reviewer, I want `orchestra review` to approve, block, or request changes so that gate status is auditable. Acceptance criteria: - Writes review markdown under `reviews/`. - Captures reviewer role, result, severity, findings, recommendation, and artifact links. - Appends REVIEW_RECORDED event. - Blocks invalid reviewer role. Developer tasks: - Create review template. - Implement review command. - Add validation. - Add unit tests. QA notes: - Verify approve, block, and request changes. - Verify unknown reviewer role fails. Evidence required: - Unit test command and result. - Example review artifact. ### Story CLI-005: Add Evidence Priority: P1 As an agent, I want `orchestra evidence add` to register evidence artifacts so that tests and reviews are traceable. Acceptance criteria: - Supports evidence types: command, file, screenshot, trace, video, log, report. - Links evidence to task and role. - Appends EVIDENCE_ADDED event. - Validates referenced file paths when evidence points to a file. Developer tasks: - Define evidence schema. - Implement evidence command. - Add validation and tests. QA notes: - Verify command evidence. - Verify file evidence with existing path. - Verify missing file fails validation. Evidence required: - Unit test command and result. - Example evidence artifact. ### Story MODEL-002: Configure Models by Role Priority: P2 As an administrator, I want provider and model preferences in config so that multi-model routing can be added without schema redesign. Acceptance criteria: - `config.json` supports provider defaults and per-role model settings. - Settings include provider, model, fallbacks, max tokens, max cost, timeout, retries, and required capabilities. - No real provider call is implemented. Developer tasks: - Define provider config schema. - Add default config stub. - Add validation tests. QA notes: - Verify valid multi-provider config passes. - Verify unknown provider reference fails if used by a role. Evidence required: - Unit test command and result. - Example provider config. ### Story CFG-004: Define Tool Runtime Contracts Priority: P1 As a developer, I want tool runtime contracts for Node, Playwright, and optional Python workers so that future agents can invoke tools consistently. Acceptance criteria: - `config.json` can declare tool runtimes for node, playwright, and python. - Tool entries include command, args, working directory, allowed roles, timeout, evidence behavior, and risk level. - Python tools are disabled by default unless explicitly configured. - Runtime config is validated without executing tools. Developer tasks: - Add tool runtime schema. - Add default Node and Playwright tool entries. - Add optional Python worker config example. - Add validation tests. QA notes: - Verify default tool config passes validation. - Verify invalid runtime command fails validation. - Verify Python runtime remains opt-in. Evidence required: - Unit test command and result. - Example tool runtime config. ### Story CFG-005: Enforce Static Analysis Git Hooks Priority: P0 As a maintainer, I want a version-controlled pre-commit hook contract so that static analysis runs before any commit. Acceptance criteria: - Defines required pre-commit checks for TypeScript/Node: format check, lint, typecheck, secret scan, and staged-file validation. - Defines optional Python checks when Python workers exist: Ruff, typecheck, Bandit, and dependency audit. - Pre-commit hook fails closed and blocks commit when checks fail. - `--no-verify` bypass requires explicit user approval and a recorded follow-up item. - CI requirements include the same checks plus deeper SAST, dependency scan, Playwright, container, and IaC checks when applicable. Developer tasks: - Add static analysis hook requirements to config schema. - Add default hook command definitions for Node/TypeScript. - Add optional Python hook command examples. - Add validation tests for required hook entries. QA notes: - Verify default hook config includes required checks. - Verify missing lint or typecheck entry fails validation. - Verify Python checks are only required when Python workers are enabled. Evidence required: - Unit test command and result. - Example pre-commit hook config. ## Sprint 1 Definition of Ready - Product goal and MVP scope are documented. - Stories have acceptance criteria. - Out-of-scope work is explicit. - File-based architecture is accepted for MVP. - No external provider dependency is required. ## Sprint 1 Definition of Done - CLI can initialize workflow state. - Roles, tasks, events, handoffs, reviews, and evidence have schemas. - Status command reports current workflow health. - Readiness gate blocks incomplete work. - Tool runtime contracts exist for Node, Playwright, and optional Python workers. - Static analysis pre-commit hook contract exists and is validated. - Unit tests cover core schema validation and CLI behavior. - Documentation includes setup, commands, examples, and known limitations. ## Proposed Technical Architecture ```text orchestra commands/ init status handoff review evidence core/ workspace schemas events tasks roles gates artifacts tools tools/ playwright python .agent-workflow/ config.json roles.json tasks.json locks.json events.jsonl decisions/ handoffs/ evidence/ reviews/ ``` ## Sprint Risks - Scope creep into real LLM orchestration before file workflow is proven. - Too much process overhead for small tasks. - Schema too rigid for different repos. - Evidence capture can become noisy if summaries are not concise. - Hybrid runtime can add complexity if Python workers are allowed without strict contracts. ## Recommended First Implementation Order 1. Workspace layout and init command. 2. Schemas for roles, tasks, events, and config. 3. Event append helper. 4. Status command. 5. Readiness gate. 6. Tool runtime contract schema. 7. Static analysis pre-commit hook contract. 8. Handoff, review, and evidence commands. 9. Documentation and examples.