# Multi-Agent Orchestrator Backlog

## Product Goal

Build a provider-agnostic middleware that lets a parent agent orchestrate specialized subagents through explicit roles, task graphs, handoffs, evidence, review gates, and shared artifacts even when the underlying LLM platform does not support native agent-to-agent collaboration.

## Epic 1: Central Orchestration

### Story ORCH-001: Create Structured Task Brief
As a user, I want the parent agent to convert my request into a structured brief so that goals, scope, risks, assumptions, and Definition of Done are clear before work starts.

Acceptance criteria:
- Captures goal, backlog item, user value, scope, non-goals, assumptions, risks, constraints, and Definition of Done.
- Identifies missing readiness information.
- Blocks implementation when critical readiness fields are missing.

### Story ORCH-002: Select Required Roles
As a parent agent, I want to select only the roles required for the task so that work is complete without activating unnecessary agents.

Acceptance criteria:
- Maps task impact areas to roles.
- Records selected roles and skipped roles with rationale.
- Supports role combinations for cross-cutting work.

### Story ORCH-003: Build Task Graph
As a parent agent, I want to create a task graph with dependencies so that sequential and parallel work can be coordinated safely.

Acceptance criteria:
- Creates tasks with ID, owner role, status, dependencies, inputs, outputs, and exit criteria.
- Detects blocked tasks.
- Prevents downstream tasks from starting before required upstream outputs exist.

### Story ORCH-004: Require User Alignment Gate
As a user, I want to approve the proposed solution and architecture before implementation so that scope and design stay under control.

Acceptance criteria:
- Presents proposed approach, modules, data flow, trade-offs, risks, test strategy, and evidence plan.
- Records user approval or requested changes.
- Blocks non-trivial implementation until approval is recorded.

### Story ORCH-005: Resume Interrupted Work
As a parent agent, I want to rebuild workflow state from saved artifacts and events so that interrupted work can continue without starting over.

Acceptance criteria:
- Loads tasks, events, locks, decisions, handoffs, and evidence.
- Reconstructs current status and next actions.
- Flags inconsistent or missing workflow files.

## Epic 2: Role Registry and Capabilities

### Story ROLE-001: Define Role Catalog
As an administrator, I want to define roles and responsibilities so that each agent knows its ownership, authority, and handoff expectations.

Acceptance criteria:
- Supports roles such as Product Owner, Architect, Developer, Tech Lead, Frontend Specialist, Backend Specialist, Mobile Specialist, QA, SDET, Security, DevOps, Platform Engineer, SRE, DBA, UX/UI Designer, Release Manager, Compliance/Privacy, Technical Writer, AI Evaluation Engineer, Support/Customer Operations, and Game Designer.
- Stores role purpose, responsibilities, required inputs, outputs, and blockers.
- Allows project-specific role overrides.

### Story ROLE-002: Map Capabilities to Roles
As a parent agent, I want to query role capabilities so that tasks are assigned to the right agent.

Acceptance criteria:
- Supports capabilities such as coding, test planning, Playwright automation, threat review, infra review, docs, and release review.
- Resolves the best role for each task impact area.
- Reports when no configured role can own a needed capability.

### Story ROLE-003: Enforce Role Authority
As a reviewer, I want each role to have explicit approval and blocking authority so that release decisions are auditable.

Acceptance criteria:
- Supports approve, block, request changes, and risk accepted states.
- Records role, rationale, severity, and affected artifact.
- Prevents release when required role approval is missing.


### Story ROLE-004: Activate Tech Lead Profile
As a parent agent, I want to activate a Tech Lead when implementation coordination risk exists so that code ownership, sequencing, and integration quality are explicit.

Acceptance criteria:
- Activates Tech Lead for multi-developer, cross-module, or sequencing-sensitive work.
- Records ownership boundaries, implementation plan, review focus, and integration risks.
- Blocks integration when ownership or review evidence is missing for high-risk work.

### Story ROLE-005: Activate SDET Profile
As QA, I want an SDET profile for automation-heavy work so that Playwright coverage is reliable, maintainable, and evidence-based.

Acceptance criteria:
- Activates SDET for browser automation, flaky tests, critical regression paths, or CI test reliability risk.
- Requires automation scope, locator strategy, fixtures/page objects, and Playwright evidence.
- Flags brittle selectors, non-isolated tests, and missing trace/screenshot evidence.

### Story ROLE-006: Activate Platform Engineer Profile
As an administrator, I want a Platform Engineer profile so that reusable developer workflows become secure, governed golden paths.

Acceptance criteria:
- Activates Platform Engineer for reusable templates, CI/CD foundations, environment setup, or cross-repo standards.
- Requires platform capability, developer experience, guardrails, and adoption plan.
- Records template validation and self-service smoke evidence.

### Story ROLE-007: Activate Frontend Specialist Profile
As a parent agent, I want a Frontend Specialist profile so that user-facing web changes cover component architecture, responsive behavior, accessibility, and browser evidence.

Acceptance criteria:
- Activates Frontend Specialist for web UI, responsive, accessibility, component, or client-performance risk.
- Requires user flow, UI states, accessibility notes, and browser evidence.
- Coordinates with UX/UI, QA, and SDET for Playwright-visible behavior.

### Story ROLE-008: Activate Backend Specialist Profile
As a parent agent, I want a Backend Specialist profile so that services, APIs, data flow, concurrency, and failure modes are reviewed by the right capability.

Acceptance criteria:
- Activates Backend Specialist for API contracts, domain services, persistence, transactions, or server reliability risk.
- Requires API contract, data flow, failure modes, and service test evidence.
- Coordinates with Security, SRE, DBA, and Architect when impact areas overlap.

### Story ROLE-009: Activate Mobile Specialist Profile
As a parent agent, I want a Mobile Specialist profile so that mobile runtime, device, offline, permissions, and store-readiness constraints are not treated as generic web work.

Acceptance criteria:
- Activates Mobile Specialist for native, hybrid, offline, permissions, device capability, or app-store release impact.
- Requires device matrix, mobile flow, offline behavior, and release constraints.
- Records mobile screenshots, recordings, or device test evidence.

### Story ROLE-010: Activate AI Evaluation Profile
As a parent agent, I want an AI Evaluation / Prompt Quality profile so that prompt, model, and provider-routing changes are evaluated with explicit rubrics and regression evidence.

Acceptance criteria:
- Activates AI Evaluation for system prompt, role prompt, model routing, provider fallback, or LLM output quality changes.
- Requires eval objective, dataset or cases, rubric, model behavior summary, and regression risk.
- Supports model comparison and human-calibrated review for high-risk outputs.

### Story ROLE-011: Activate Support / Customer Operations Profile
As a Release Manager, I want Support / Customer Operations activated for customer-visible releases so that support readiness and feedback loops are ready before go-live.

Acceptance criteria:
- Activates Support for customer-visible releases, known issues, workarounds, support workflow changes, or feedback intake needs.
- Requires customer impact, known issues, support runbook, and feedback loop.
- Includes support readiness in release-readiness evidence.

## Epic 3: Multi-Model Provider Layer

### Story MODEL-001: Define Provider Interface
As a developer, I want a common provider interface so that the orchestrator can call different LLM providers without coupling to their SDKs.

Acceptance criteria:
- Defines request, response, streaming, tool support, vision support, JSON mode, context length, timeout, and error contract.
- Hides provider-specific SDK details behind adapters.
- Includes test doubles for provider behavior.

### Story MODEL-002: Configure Models by Role
As an administrator, I want to assign provider and model preferences per role so that each role can use the right cost, quality, and capability profile.

Acceptance criteria:
- Supports provider, model, fallbacks, max tokens, max cost, timeout, and retry settings per role.
- Allows project-level defaults.
- Validates unknown providers or unsupported capabilities.

### Story MODEL-003: Record Model Provenance
As an auditor, I want every agent output to record provider, model, version, and cost metadata so that decisions are traceable.

Acceptance criteria:
- Logs provider, model, request ID, token usage, latency, estimated cost, and timestamp.
- Links model metadata to generated artifacts and decisions.
- Redacts sensitive content according to retention policy.

### Story MODEL-004: Support Provider Fallback
As a parent agent, I want fallback providers for non-critical tasks so that workflow can continue when one provider fails.

Acceptance criteria:
- Uses configured fallback order.
- Records fallback reason.
- Blocks fallback for tasks marked reproducibility-sensitive unless user approval is recorded.

### Story MODEL-005: Compare Model Outputs
As a reviewer, I want to run multiple models on critical analysis tasks so that high-risk decisions can be cross-checked.

Acceptance criteria:
- Runs configured comparison models.
- Produces a structured agreement/disagreement summary.
- Requires human or parent-agent resolution for material disagreement.

## Epic 4: Task Graph and State Management

### Story TASK-001: Persist Task State
As a parent agent, I want task state persisted to disk so that workflow status survives process restarts.

Acceptance criteria:
- Stores tasks in a structured file.
- Supports statuses: pending, ready, in_progress, blocked, review, approved, rejected, done, canceled.
- Validates task references and dependencies.

### Story TASK-002: Show Workflow Status
As a user, I want to see all tasks and blockers so that I understand progress.

Acceptance criteria:
- Shows tasks grouped by status and role.
- Highlights blockers, missing evidence, failed gates, and active locks.
- Provides next recommended action.

### Story TASK-003: Detect Dependency Violations
As a parent agent, I want to prevent tasks from running before dependencies are complete so that agents do not work from stale or missing inputs.

Acceptance criteria:
- Blocks task start when required dependencies are incomplete.
- Explains which dependency is missing.
- Allows explicit override only with recorded rationale.

## Epic 5: Handoffs Between Agents

### Story HAND-001: Generate Developer-to-QA Handoff
As a Developer, I want a structured handoff to QA so that QA can test with full context.

Acceptance criteria:
- Includes changed files/components, behavior changed, unit tests, commands run, known gaps, risks, and recommended Playwright coverage.
- Validates required fields before handoff is accepted.
- Links evidence artifacts.

### Story HAND-002: Generate Review Handoff
As a parent agent, I want role-specific handoff templates so that Security, SRE, DBA, UX, and Release Manager receive relevant context.

Acceptance criteria:
- Selects template by target role.
- Includes role-specific required fields.
- Links decisions, task context, and evidence.

### Story HAND-003: Reject Incomplete Handoffs
As a reviewer, I want incomplete handoffs to be rejected automatically so that reviews do not start with missing context.

Acceptance criteria:
- Validates required fields.
- Reports missing fields and owner.
- Keeps target task blocked until corrected.

## Epic 6: Shared Memory and Event Log

### Story MEM-001: Append Workflow Events
As a system, I want all workflow events stored in an append-only log so that collaboration is auditable.

Acceptance criteria:
- Records event type, task ID, actor, timestamp, summary, artifact links, and metadata.
- Supports events such as TASK_ASSIGNED, HANDOFF_READY, REVIEW_BLOCKED, QA_FAILED, APPROVED, RISK_ACCEPTED, and RELEASE_READY.
- Does not overwrite historical events.

### Story MEM-002: Store Decision Log
As an Architect, I want decisions stored separately from chat so that important trade-offs remain visible.

Acceptance criteria:
- Stores decision title, context, decision, alternatives, consequences, owner, and status.
- Links decisions to tasks and reviews.
- Supports superseded decisions.

### Story MEM-003: Query Shared Context
As an agent, I want to query current assumptions, decisions, risks, and evidence so that I do not work in isolation.

Acceptance criteria:
- Returns relevant task context by task ID.
- Includes upstream handoffs, active decisions, blockers, and evidence.
- Flags stale or superseded context.

## Epic 7: Artifact Store and Evidence

### Story ART-001: Store Test Evidence
As QA, I want to store test plans, results, screenshots, logs, videos, and traces so that release decisions are evidence-based.

Acceptance criteria:
- Stores artifacts under predictable paths.
- Links artifacts to task, role, and event.
- Supports pass, fail, blocked, and deferred outcomes.

### Story ART-002: Store Command Evidence
As a Developer, I want commands and results captured so that reviewers know exactly what was verified.

Acceptance criteria:
- Records command, working directory, exit code, timestamp, and summarized output.
- Marks failed commands as blockers unless explicitly deferred.
- Links command evidence to handoff and final summary.

### Story ART-003: Generate Final Evidence Summary
As a user, I want a final evidence summary so that I can understand what was changed, tested, and left risky.

Acceptance criteria:
- Summarizes tasks, tests, reviews, approvals, blockers, risk acceptances, and artifacts.
- Highlights unresolved risks and follow-up items.
- Can be used as PR body input.

### Story ART-004: Maintain Prompt Registry
As an agent, I want generated prompts stored by artifact type so that future agents can preserve project conventions and trace AI-generated work back to its prompt intent.

Acceptance criteria:
- `orchestra init` creates `.generated-prompts/` with stack-agnostic register files for code, UI, services, tests, CI/CD, docs, diagrams, and evals.
- Existing register files are not overwritten unless `--force` is used.
- Register files document the before/after protocol, substantial-change rules, entry format, task, role, key decisions, evidence, and prompt summary.
- AI-assisted development rules require reading the relevant register before substantial generation and updating it after substantial changes.

## Epic 8: File Ownership and Locking

### Story LOCK-001: Assign File Ownership
As a parent agent, I want to assign files or modules to a task owner so that parallel agents do not overwrite each other.

Acceptance criteria:
- Records owner, task ID, path pattern, reason, and expiration.
- Prevents another task from claiming overlapping paths without integration owner.
- Supports module-level and file-level locks.

### Story LOCK-002: Detect Lock Conflicts
As an integrator, I want lock conflicts detected before edits so that merge conflicts are avoided.

Acceptance criteria:
- Detects overlapping path claims.
- Reports owners and impacted tasks.
- Requires integration owner assignment to continue.

### Story LOCK-003: Release Locks
As an agent, I want locks released when work completes or is canceled so that future tasks can proceed.

Acceptance criteria:
- Releases locks on task done or canceled.
- Supports manual release with rationale.
- Reports stale locks.

## Epic 9: Quality Gates

### Story GATE-001: Enforce Definition of Ready
As a parent agent, I want readiness validated before implementation so that work does not start with hidden ambiguity.

Acceptance criteria:
- Checks backlog item, goal, scope, acceptance criteria, non-goals, risks, user alignment, roles, and test strategy.
- Blocks implementation when required fields are missing.
- Produces a readiness report.

### Story GATE-002: Enforce Architecture Approval
As an Architect, I want non-trivial implementation blocked until architecture is approved so that design risk is handled early.

Acceptance criteria:
- Detects non-trivial work.
- Requires solution proposal and user approval.
- Records approval event.

### Story GATE-003: Enforce QA Gate
As QA, I want release blocked without a test plan and execution evidence so that unverified changes do not ship.

Acceptance criteria:
- Requires QA plan, execution status, and evidence.
- Supports deferred test cases only with rationale and follow-up owner.
- Blocks release on unresolved critical QA findings.

### Story GATE-004: Enforce Security/SRE/DBA Gates
As a risk owner, I want required reviews enforced when a change touches my area so that material risk is not bypassed.

Acceptance criteria:
- Maps change impact to required reviewers.
- Blocks release for missing or blocking reviews.
- Supports explicit risk acceptance by authorized role.

## Epic 10: CLI / Operator Interface

### Story CLI-001: Initialize Workflow
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/` with tasks, roles, locks, events, decisions, handoffs, evidence, and reviews directories/files.
- Does not overwrite existing files without confirmation.
- Validates generated structure.

### Story CLI-002: Show Status
As a user, I want `orchestra status` to show workflow progress so that I can inspect current state quickly.

Acceptance criteria:
- Shows tasks, blockers, locks, pending reviews, missing evidence, and next action.
- Returns non-zero when critical blockers exist if configured for CI.
- Supports human-readable and JSON output.

### Story CLI-003: Create Handoff
As an agent, I want `orchestra handoff` to generate and validate a handoff so that downstream agents get complete context.

Acceptance criteria:
- Accepts from role, to role, task ID, and artifact links.
- Generates role-specific template.
- Validates required fields.

### Story CLI-004: Record Review
As a reviewer, I want `orchestra review` to approve, block, or request changes so that gate status is auditable.

Acceptance criteria:
- Records reviewer role, result, severity, findings, and artifact links.
- Updates task and gate status.
- Appends event log entry.

### Story CLI-005: Add Evidence
As an agent, I want `orchestra evidence add` to register evidence artifacts so that tests and reviews are traceable.

Acceptance criteria:
- Supports command, file, screenshot, trace, video, log, and report evidence types.
- Links evidence to task and role.
- Validates referenced files exist when applicable.

## Epic 11: Final Integration

### Story INT-001: Validate Ready for Final Response
As an integrator, I want to verify all gates before final response so that the user receives a coherent and complete result.

Acceptance criteria:
- Checks tasks, blockers, locks, handoffs, reviews, evidence, and risks.
- Reports anything incomplete.
- Blocks final "done" status when required gates fail.

### Story INT-002: Generate Final Summary
As a user, I want a final summary with changes, tests, evidence, risks, and follow-ups so that I can make a release or review decision.

Acceptance criteria:
- Summarizes completed tasks by role.
- Includes evidence links and commands run.
- Lists unresolved risks and risk acceptances.

### Story INT-003: Generate PR Body
As a contributor, I want a PR body generated from workflow artifacts so that review context is complete.

Acceptance criteria:
- Produces summary, test plan, evidence, risks, screenshots, migrations, rollout, and rollback sections.
- Links backlog item and relevant decisions.
- Flags missing required PR sections.

## Epic 12: QA Automation

### Story QA-001: Identify Automation Candidates
As QA, I want manual checks classified for automation so that critical flows become repeatable.

Acceptance criteria:
- Identifies smoke, regression, high-risk, and low-value manual checks.
- Recommends Playwright for browser flows.
- Records automation owner and follow-up item.

### Story QA-002: Generate Playwright Test Plan
As QA, I want Playwright automation planned from acceptance criteria so that E2E coverage targets user value.

Acceptance criteria:
- Defines scenarios, fixtures, page objects, selectors, assertions, and evidence settings.
- Covers happy path and critical failure paths.
- Avoids brittle selectors.

### Story QA-003: Attach Playwright Evidence
As QA, I want screenshots, videos, and traces linked to E2E runs so that failures are diagnosable.

Acceptance criteria:
- Stores Playwright artifacts by task and test run.
- Links failed tests to traces/screenshots/videos.
- Includes artifact links in QA handoff.

## Epic 13: Configuration and Extensibility

### Story CFG-001: Configure Project Workflow
As an administrator, I want project-specific workflow configuration so that different repos can customize roles, gates, and templates.

Acceptance criteria:
- Supports config for roles, gates, templates, provider routing, evidence requirements, and severity thresholds.
- Validates config schema.
- Provides sensible defaults.

### Story CFG-002: Add Custom Templates
As a team, I want custom templates for handoffs, reviews, and evidence so that workflow matches local process.

Acceptance criteria:
- Loads templates from project config.
- Falls back to default templates.
- Validates required placeholders.

### Story CFG-003: Support Provider-Agnostic Tools
As a developer, I want tool availability configured separately from models so that agents can use shell, git, tests, Playwright, CI, and cloud tools safely.

Acceptance criteria:
- Defines tool name, permission level, allowed roles, and risk level.
- Blocks tool use when role is unauthorized.
- Logs tool use events.

### Story CFG-004: Support Hybrid Tool Runtimes
As a developer, I want Node, Playwright, and optional Python tool runtimes configured through explicit contracts so that the orchestrator can prioritize web automation while still supporting Python-specialized work.

Acceptance criteria:
- TypeScript/Node is the default runtime for the CLI and workflow engine.
- Playwright is a first-class tool runtime for browser automation and evidence.
- Python workers are opt-in and invoked only through configured command contracts.
- Tool runtime config defines command, args, working directory, allowed roles, timeout, evidence behavior, and risk level.
- Runtime configuration is validated before any tool is executed.

### Story CFG-005: Enforce Static Analysis Git Hooks
As a maintainer, I want version-controlled git hooks to run static analysis before commits so that low-quality or unsafe changes are blocked early.

Acceptance criteria:
- Pre-commit hook runs formatting check, lint, typecheck, secret scan, and staged-file validation.
- Hook fails closed and blocks commit on failure.
- `--no-verify` bypass is disallowed unless explicitly approved and recorded as a follow-up risk.
- CI runs the same checks plus deeper project-wide SAST, dependency, container, IaC, and E2E checks when applicable.
- Hook commands are configured through tool runtime contracts.

## Epic 14: Governance, Privacy, and Cost

### Story GOV-001: Enforce Retention Policy
As Compliance/Privacy, I want prompt, response, and artifact retention controlled so that sensitive information is not stored unnecessarily.

Acceptance criteria:
- Supports retention periods by artifact type.
- Supports redaction rules for secrets and PII.
- Records deletion events.

### Story GOV-002: Track Cost and Usage
As an administrator, I want model and tool usage tracked so that agent workflows stay within budget.

Acceptance criteria:
- Tracks tokens, cost, provider, role, task, and duration.
- Enforces max cost per task or workflow when configured.
- Reports cost by role and provider.

### Story GOV-003: Audit Risk Acceptance
As an auditor, I want risk acceptances recorded with owner and rationale so that exceptions are traceable.

Acceptance criteria:
- Records risk, severity, owner, expiration, compensating controls, and approval.
- Links risk acceptance to release decision.
- Flags expired risk acceptances.

## Epic 15: Dynamic Skills and Context Loading

### Story SKILL-001: Define Skill Manifest
As a parent agent, I want each skill to expose structured metadata so that the orchestrator can decide what to load without reading every skill file.

Acceptance criteria:
- Manifest includes id, name, summary, triggers, roles, capabilities, risk areas, entry file, assets, evidence types, and load budget.
- Unknown skill IDs and missing entry files fail validation.
- Skill metadata is available to CLI, web, VS Code, and future middleware adapters.

### Story SKILL-002: Select Skills from Task Context
As a parent agent, I want to select skills from task signals so that agents receive only the instructions needed for the current work.

Acceptance criteria:
- Selection uses task goal, touched paths, active roles, requested outputs, capabilities, and risk areas.
- Explains selected and skipped skills with rationale.
- Supports explicit user or project overrides.

### Story SKILL-003: Scaffold Built-in Skills
As an administrator, I want built-in skills for common delivery work so that teams can reuse consistent procedures without bloating main MD files.

Acceptance criteria:
- Provides prompt-registry, diagram-export, static-analysis, pr-review, playwright-evidence, backlog-sync, release-readiness, and model-evaluation skills.
- Each skill has a focused `SKILL.md` plus optional assets, templates, or scripts.
- Skills stay stack-agnostic unless explicitly scoped by project config.

### Story SKILL-004: Record Loaded Skills in Evidence and Handoffs
As a reviewer, I want loaded skills recorded in workflow artifacts so that I can audit why an agent used specific instructions.

Acceptance criteria:
- Task context includes selected skill IDs and rationale.
- Handoffs and final summaries include materially used skills.
- Evidence events can link to skill-driven commands, scripts, checks, or generated artifacts.

### Story SKILL-005: Support Middleware Injection for Non-Skill LLMs
As an administrator, I want Open Orchestra to inject selected skill text for LLMs that do not support native skills so that dynamic context loading works across providers.

Acceptance criteria:
- Parent orchestrator loads selected skill text and injects only that text into the child prompt.
- Full skill catalog is never embedded in the base prompt.
- Provider output records which skills were injected.


### Story SKILL-007: Define Source of Truth Catalog
As a parent agent, I want a configured source-of-truth catalog so that agents and subagents know which local files, workflow artifacts, and official docs are authoritative for each task.

Acceptance criteria:
- Catalog groups sources by project instructions, backlog, architecture, codebase, quality/security, DevOps/runtime, vendor docs, and agent memory.
- Skill selection can reference source groups without loading every source eagerly.
- Conflicting sources are surfaced as blockers or decisions instead of silently resolved.

### Story SKILL-008: Record Agent Lessons Learned
As a parent agent, I want reusable tool, syntax, escaping, permission, and workflow failures recorded so that agents do not repeat the same mistakes.

Acceptance criteria:
- Lessons are stored as append-only JSONL with task, actor, operation, failed action, error signature, root cause, fix, prevention, applicable tools, and verification.
- Agents search relevant lessons before repeating risky operations.
- Lessons never store secrets, raw credentials, or sensitive customer data.
- Repeated lessons can be promoted into skills or always-loaded rules.

### Story SKILL-006: Enforce Main Instruction File Budget
As a maintainer, I want main MD files kept context-bounded so that long-term agent instructions remain fast, readable, and maintainable.

Acceptance criteria:
- Main files contain core rules, skill index, and activation rules only.
- Detailed procedures move to skills or supporting docs.
- Validation warns when primary instruction files exceed configured size or section budgets.

### Story SKILL-009: Manage Generated Instruction File Updates
As a maintainer, I want generated MD/MDC instruction sections updated through managed blocks and declarative profile imports so that Open Orchestra can refresh runtime adapters without overwriting user-authored documentation or inflating always-loaded context.

Acceptance criteria:
- Generated sections use explicit start/end markers with generator, version, source manifest, target, block ID, and content hash metadata.
- Generators support `--dry-run`, `--check`, and `--force` behavior.
- Rerunning without source changes produces no diff.
- Manual edits inside managed blocks are detected as drift and reported before overwrite.
- User-authored content outside managed blocks is preserved.
- Profiles and skills can declare imports using Open Orchestra syntax, for example `@orchestra/import <profile-or-skill-id>`.
- Import resolution validates missing references, prevents cycles, and renders target-compatible output for generic, Claude, Cursor, Codex, and VS Code runtimes.
- Main instruction files keep only the import index or resolved minimal context needed by the selected target.

## Epic 16: Consent-Based Telemetry

### Story TEL-001: Configure Explicit Telemetry Consent
As a user, I want telemetry disabled by default and enabled only through explicit consent so that prompt and workflow data are never collected silently.

Acceptance criteria:
- Default telemetry mode is `off`.
- CLI supports telemetry status, enable, and disable commands.
- Consent state records timestamp, actor, selected collection level, and policy version.
- Telemetry status is visible in config and local workflow context.

### Story TEL-002: Define Telemetry Collection Levels
As a user, I want separate telemetry levels so that I can share metadata, prompt summaries, prompt samples, or eval datasets with different consent boundaries.

Acceptance criteria:
- Supports `off`, `metadata`, `prompt-summary`, `prompt-sample`, and `eval-dataset` levels.
- Prompt sample and eval dataset modes require explicit opt-in distinct from metadata.
- Each exported record includes the active telemetry level and consent reference.
- Collection level can be downgraded or disabled without deleting local workflow data.

### Story TEL-003: Redact Sensitive Data Locally
As a privacy owner, I want telemetry redacted before export or submission so that secrets, PII, local paths, and sensitive customer data are not transmitted.

Acceptance criteria:
- Redaction runs locally before export or submit.
- Secret-like values, tokens, keys, emails, and configured PII patterns are masked.
- Raw `.env`, credentials, stack traces with secrets, and private customer data are blocked.
- Redaction report lists fields changed without revealing original sensitive values.

### Story TEL-004: Export Reviewable Telemetry Dataset
As a user, I want telemetry exported locally before submission so that I can inspect exactly what would be shared.

Acceptance criteria:
- `orchestra telemetry export` writes JSONL under local runtime state.
- Export includes task type, selected roles, selected skills, source groups, provider/model metadata, quality outcome, and allowed prompt summary/sample fields.
- Export supports `--dry-run` and produces a review summary.
- Export never submits data automatically.

### Story TEL-005: Submit Telemetry with Audit Trail
As a user, I want telemetry submission to be explicit and auditable so that shared data can be traced back to consent.

Acceptance criteria:
- `orchestra telemetry submit --file <path>` requires telemetry enabled and compatible collection level.
- Submission records endpoint, file hash, consent reference, timestamp, and result.
- Failed submissions keep the local export and do not retry indefinitely without user action.
- User can request deletion/export references for submitted datasets.

### Story TEL-006: Curate Eval Dataset from Approved Prompts
As an AI Evaluation Engineer, I want approved prompts and outcomes curated into eval datasets so that model routing and future fine-tuning decisions use consented, high-quality examples.

Acceptance criteria:
- Dataset items require explicit consent and review status.
- Each item includes prompt summary or prompt sample, expected behavior, selected skills, source groups, model/provider, outcome, and quality labels.
- Dataset excludes secrets, PII, and customer-sensitive data after redaction.
- Dataset can be exported separately from operational telemetry.


## Epic 17: Standalone Web Console

### Story WEB-001: Bundle Standalone Console Client
As a user, I want the standalone console client bundled from shared code so that the web UI can grow without inline scripts or duplicated contracts.

Acceptance criteria:
- Build uses `tsc` for Node/CLI outputs and `esbuild` for browser bundle output.
- Server serves the generated browser bundle from `/assets/web-console.js`.
- Shared chart/data contracts are reused by the browser bundle and tests.
- Package dry-run includes the generated bundle.

### Story WEB-002: Expose Skills, Sources, and Lessons APIs
As a web or IDE client, I want stable JSON APIs for skills, source-of-truth, and lessons so that clients can render orchestration context without parsing CLI output.

Acceptance criteria:
- Exposes skills list, validate, plan, and render endpoints.
- Exposes source-of-truth list endpoint.
- Exposes lessons list, add, and promote endpoints with JSON contracts.
- Mutation endpoints use POST and validate required fields.
- Tests cover success and error responses.

### Story WEB-003: Render Skills in Standalone Console
As a user, I want a Skills panel in the standalone console so that I can inspect selected skills and rendered target context for a task.

Acceptance criteria:
- UI lists available skills and source groups.
- UI can select a task and display planned skills with rationale.
- UI can preview render output for generic, Claude, Cursor, Codex, and VS Code targets.
- UI handles empty task state and API errors cleanly.

### Story WEB-004: Render Source of Truth and Lessons in Standalone Console
As a user, I want the standalone console to show source-of-truth and lessons so that agents and humans can understand what context is authoritative and what failures have been learned.

Acceptance criteria:
- UI lists source groups and locations.
- UI lists local lessons with operation and error signature.
- UI supports adding a lesson with required fields.
- UI supports promoting lessons to a reviewable artifact.

## Epic 18: External Baseline Feature Harvest

### Story UPD-001: Detect Stale Generated Instruction Files
As a maintainer, I want Open Orchestra to detect stale generated instruction files without touching user-authored files so that runtime adapters can be safely refreshed.

Acceptance criteria:
- Stale detection uses managed block markers, generator version, source manifest, target, block ID, and content hash.
- Files without Open Orchestra markers are skipped and reported as user-owned.
- Known generated files are derived from catalogs/manifests instead of hand-maintained maps.
- CLI reports fresh, stale, drifted, missing, and user-owned files separately.
- Tests cover stale, fresh, missing marker, and catalog drift scenarios.

### Story UPD-002: Add Generated Instruction Metadata Frontmatter
As a maintainer, I want generated MD/MDC files to include stable metadata so that humans and tools can understand provenance and update eligibility.

Acceptance criteria:
- Generated files include metadata for generator, version, target, source manifest, content hash, and updated timestamp.
- Cursor MDC frontmatter and Markdown comment metadata use target-compatible syntax.
- Metadata is idempotent on rerun when source content is unchanged.
- Metadata never overwrites user-authored frontmatter outside managed sections.
- Tests cover Markdown and MDC output formats.

### Story UPD-003: Apply Instruction Updates with Dry Run and Drift Gates
As a user, I want instruction updates to support dry-run, check, apply, and force modes so that I can refresh generated files without losing manual edits.

Acceptance criteria:
- CLI supports checking planned file changes without writing.
- CLI supports dry-run output with per-file diff summary.
- Apply mode updates only safe generated blocks.
- Drifted blocks are blocked unless force is supplied.
- Update results are exposed as JSON for web and extension clients.

### Story DET-001: Auto-Detect Project Profiles and Skills
As a parent agent, I want Open Orchestra to detect project signals so that relevant roles and skills are suggested automatically for each codebase.

Acceptance criteria:
- Detects Playwright, GitHub Actions, Docker/Compose, Terraform/IaC, package managers, frontend source layout, Python, and API/service signals.
- Detection output maps signals to recommended roles, skills, and source groups.
- Users can review and accept detected profiles before applying changes.
- Detection never enables tools or telemetry without explicit user action.
- Tests cover representative Node, Python, frontend, Playwright, and DevOps fixtures.

### Story REL-001: Formalize Candidate Release Workflow
As a release owner, I want a candidate release workflow so that production releases only proceed when stories, QA evidence, changelog, rollback, and smoke tests are ready.

Acceptance criteria:
- Candidate release collects stories from local workflow state and GitHub issues when available.
- Story readiness gate checks acceptance criteria, QA evidence, reviews, docs, dependencies, rollback plan, and unresolved blockers.
- Release plan generates changelog from approved stories only.
- Tag/release actions require explicit user approval.
- Post-release smoke test and rollback evidence can be attached.

### Story PRR-001: Strengthen Pull Request Review Workflow
As a reviewer, I want PR review to detect architectural scope, risk, conflicts, and evidence gaps so that risky changes get the right specialist review before merge.

Acceptance criteria:
- PR review summarizes behavior, risk, files changed, test evidence, and unresolved questions.
- Architectural scope triggers route to Architect, Security, DevOps, DBA, UX, or QA when needed.
- Review checklist adapts by file type and detected stack.
- Merge remains blocked until explicit human approval is recorded.
- Tests cover PR summary generation, risk routing, and required-review blockers.

### Story DIA-001: Add Real Diagram Lint and Evidence
As an architect, I want diagram exports to run a real Mermaid lint/render check so that diagrams are validated before they are shared as architecture evidence.

Acceptance criteria:
- Diagram skill can run lint-only mode without side effects.
- Mermaid validation uses real tool exit codes when available and reports installation guidance when missing.
- Diagram type decision matrix recommends diagram style by question/domain.
- Render/lint evidence is attached to the workflow.
- Tests cover lint success, lint failure, missing tool, and evidence generation.

### Story HLT-001: Add Local Health Checks
As a user, I want Open Orchestra to report local health checks so that CLI, package, browser, Playwright, Git, GitHub auth, and workflow readiness problems are actionable.

Acceptance criteria:
- Health check command reports installed CLI version, package root, Node/npm, Git, GitHub auth, Playwright/browser availability, and workflow validity.
- Health checks produce actionable messages and remediation commands.
- Web console can consume health status through JSON API.
- Checks avoid network calls unless explicitly requested or already authenticated.
- Tests cover healthy, missing optional tool, and invalid workflow states.

### Story MCP-001: Evaluate MCP OAuth Proxy Integration
As an integration user, I want Open Orchestra to evaluate an MCP OAuth proxy pattern so that HTTP MCP servers can be used from tools that only support stdio or need token injection.

Acceptance criteria:
- Research notes compare stdio proxy, direct HTTP, and tool-native OAuth behavior.
- Prototype stores tokens only in approved local secret storage or explicitly configured secure paths.
- Proxy refresh behavior is documented and tested without real credentials.
- Integration remains opt-in and does not alter MCP config without user approval.
- Security review covers token storage, refresh, logs, and revocation.

## Epic 19: Runtime Subagent Orchestration

### Story ORCH-011: Add Delegation Decision Engine
As a parent agent, I want Open Orchestra to decide when work should stay local or be delegated so that subagents are used only when they reduce risk or unblock parallel progress.

Acceptance criteria:
- Delegation decision evaluates task complexity, impacted paths, risk areas, role fit, dependencies, locks, urgency, and available context.
- Decision output recommends local execution, single-role delegation, parallel delegation, review-only delegation, or no delegation.
- Decision includes rationale, required context bundle, expected outputs, disjoint write scopes, and blocking conditions.
- Decision is recorded in task context and events before subagent work starts.
- Tests cover local-only, single delegate, parallel delegates, review delegate, blocked-by-lock, and insufficient-context cases.

### Story HAND-002: Render Portable Subagent Protocol
As a user, I want Open Orchestra to render a subagent protocol from the active role catalog and task graph so that any LLM runtime can understand role routing without loading large generated rules.

Acceptance criteria:
- Protocol lists active roles, rule or skill references, task-to-role routing, conflict precedence, and handoff requirements.
- Render targets support generic, Claude, Cursor, Codex, and VS Code output.
- Output is generated from role/task/skill metadata, not hardcoded per platform.
- Main instruction files can import or reference the protocol through managed blocks without overwriting user content.
- Tests cover target rendering, role filtering, conflict precedence, and idempotent managed-block output.

### Story ROLE-003: Add Role Collaboration Flow Catalog
As a parent agent, I want role-to-role collaboration flows modeled as data so that handoffs are consistent across product, architecture, development, QA, security, DevOps, and release work.

Acceptance criteria:
- Catalog defines domain-agnostic chains such as Product -> Analyst, Analyst -> Architect, Architect -> Developer, Developer -> QA, QA -> Release, and risk-owner review flows.
- Each flow declares trigger conditions, required artifacts, required context, exit criteria, and optional reviewers.
- Task context exposes recommended collaboration flow for a task.
- Handoff generation can include flow-specific required fields.
- Tests cover flow selection, missing artifact detection, and multi-reviewer flows.

### Story WFLOW-001: Add Portable Workflow Template Catalog
As a user, I want reusable workflow templates that are not tied to a single vendor or IDE so that common agent workflows can run across CLI, web, VS Code, Cursor, Claude, and Codex.

Acceptance criteria:
- Workflow templates cover implementation, QA test plan, PR review, release readiness, incident/runbook, architecture decision, static analysis, and Playwright evidence.
- Templates declare roles, triggers, inputs, outputs, evidence requirements, gates, and compatible skills.
- Workflows render to Markdown for human/LLM execution and JSON for clients.
- Templates can be selected from task metadata and risk areas.
- Tests cover template validation, task-based selection, target rendering, and evidence requirements.

### Story ROLE-004: Expand Domain-Agnostic Specialist Profiles
As a parent agent, I want a richer domain-neutral specialist profile catalog so that delegation decisions can assign work to the right expert without assuming a specific platform.

Acceptance criteria:
- Profiles include product manager, product owner, business analyst, architect, tech lead, developer, frontend, backend, mobile, QA, SDET, UX/UI, accessibility, security, DevOps, SRE, DBA/data, release manager, technical writer, and compliance/privacy.
- Each profile declares activation criteria, capabilities, risk areas, expected evidence, handoff fields, and blocking authority.
- Profiles remain stack-agnostic and reference skills/source groups instead of vendor-specific implementation details.
- Role activation and execution planning use these profiles without increasing always-loaded instruction size.
- Tests cover activation metadata, risk owner mapping, execution-plan routing, and rendered protocol references.

### Story DOC-002: Document Runtime LLM Flow
As a user, I want a practical guide that explains how to use Open Orchestra from Claude, Codex, Cursor, VS Code, or another LLM runtime so that I understand which model is acting as the parent agent and how Open Orchestra coordinates context, skills, plans, evidence, and future provider routing.

Acceptance criteria:
- Guide explains that the active LLM runtime is the parent agent today, while Open Orchestra acts as the local control plane.
- Guide includes startup flow for a new task: init, health, task/context/plan, skills plan, skills render by target, evidence, gates, and summary.
- Guide provides copy-paste prompt examples for Claude, Codex, Cursor, and generic LLM runtimes.
- Guide clarifies current limitations: no real provider execution yet beyond fake/provider-routing primitives, and no automatic subagent spawning until delegation runtime stories are implemented.
- Guide explains model/provider routing concepts and how future multi-model delegation should work by role.
- README links to the guide from the quick-start or usage section.
- Tests or documentation checks verify that referenced CLI commands exist in the help text.

Technical refinement:
- Keep the guide stack-agnostic and runtime-neutral.
- Cross-link skill loading strategy, orchestra MVP, model routing commands, and new runtime subagent orchestration backlog items.
- Avoid promising real provider execution until implemented.