agentic-orchestrator 0.1.0

package/README.md

@@ -0,0 +1,679 @@
+# Agentic-Orchestrator
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-NodeNext-3178C6.svg)](https://www.typescriptlang.org/)
+[![Nx Workspace](https://img.shields.io/badge/Nx-Monorepo-143055.svg)](https://nx.dev/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A deterministic, MCP-first control plane for parallel multi-agent feature development.
+
+It combines:
+
+- a **deterministic kernel** (state, locks, collisions, gates, evidence)
+- a **supervisor runtime** (orchestrator/planner/builder/qa session coordination)
+- a **CLI contract** (`aop <run|status|resume|stop|delete>`) with deterministic spec ingestion, runtime control, and cleanup
+
+> For complete normative requirements, see [agentic_orchestrator_spec.md](spec-files/agentic_orchestrator_spec.md).
+> For implementation continuity and the latest status, see [progress.md](spec-files/progress.md).
+
+---
+
+## Quick Overview
+
+Without a deterministic control plane, agentic parallel development is fragile:
+
+```bash
+# brittle: no centralized state, lock ownership, or collision arbitration
+# (multiple agents independently edit overlapping files/resources)
+```
+
+With Agentic-Orchestrator:
+
+```bash
+# deterministic: canonical state + lock leases + collision checks + gate evidence
+npm run run -- -fi ./.aop/features/my_feature/spec.md --agent-provider custom
+```
+
+Core guarantees:
+
+- policy/schema validated plans before build
+- worktree-per-feature isolation
+- lock lease ownership for shared resources
+- gate execution with evidence artifacts
+- explicit merge promotion path (`feature.ready_to_merge`)
+
+## Installation
+
+```bash
+npm install
+```
+
+## Quick Start
+
+### 1. Prepare or use a feature spec
+
+Canonical path format:
+
+```text
+.aop/features/<feature_id>/spec.md
+```
+
+### 2. Run typecheck and build
+
+```bash
+npm run typecheck
+npm run build
+```
+
+### 3. Run one feature flow
+
+```bash
+npm run run -- -fi ./.aop/features/my_feature/spec.md --agent-provider custom
+```
+
+### 4. Check runtime status
+
+```bash
+npm run run -- status
+```
+
+### 5. Resume from persisted state
+
+```bash
+npm run run -- resume
+```
+
+---
+
+## Development
+
+This repository is the **control-plane workspace** for Agentic-Orchestrator.
+
+### Project Structure
+
+```text
+Agentic-Orchestrator/
+├── .aop/
+│   ├── features/                      # runtime-generated feature artifacts
+│   │   └── index.json                # global orchestration index
+│   └── runtime/
+│       └── operation-ledger/
+├── agentic/
+│   ├── orchestrator/                  # policy/gates/agents config + schemas + prompts
+│   │   ├── policy.yaml
+│   │   ├── gates.yaml
+│   │   ├── agents.yaml
+│   │   ├── schemas/
+│   │   └── tools.md
+├── apps/
+│   └── control-plane/
+│       ├── src/
+│       │   ├── cli/                   # aop CLI
+│       │   ├── core/                  # deterministic kernel
+│       │   ├── providers/             # provider resolution + adapter
+│       │   └── supervisor/            # runtime orchestration loop
+│       ├── test/                      # Vitest suites
+│       ├── project.json               # Nx targets
+│       └── vitest.config.ts
+├── spec-files/
+│   ├── agentic_orchestrator_spec.md
+│   ├── agentic_orchestrator_mcp_formalization_spec.md
+│   ├── agentic_orchestrator_single_global_orchestrator_spec.md
+│   ├── agentic_orchestrator_oop_refactor_spec.md
+│   └── progress.md                     # implementation continuity log
+└── README.md
+```
+
+### Setup
+
+```bash
+git clone https://github.com/Eric-Taurone-Software/Agentic-Orchestrator.git
+cd Agentic-Orchestrator
+npm install
+```
+
+### Development Workflow
+
+#### Type-check
+
+```bash
+npm run typecheck
+```
+
+#### Build
+
+```bash
+npm run build
+```
+
+`npm run build` is lint-gated (`npm run lint && ...`) and fails on any lint warning/error.
+
+#### Lint
+
+```bash
+npm run lint
+```
+
+#### Run tests
+
+```bash
+npm test
+```
+
+#### Validate MCP contract pins and registry/docs consistency
+
+```bash
+npm run validate:mcp-contracts
+```
+
+#### Validate architecture boundaries
+
+```bash
+npm run validate:architecture
+```
+
+#### Validate Docker MCP deployment contract
+
+```bash
+npm run validate:docker-mcp
+```
+
+#### Run orchestrator CLI
+
+```bash
+# source mode (tsx)
+npm run run -- -fi ./.aop/features/my_feature/spec.md --agent-provider custom
+
+# built artifact
+node dist/apps/control-plane/cli/aop.js run -fi ./.aop/features/my_feature/spec.md --agent-provider custom
+```
+
+---
+
+## CLI Contract
+
+Primary command:
+
+```bash
+aop <run|status|resume|stop|delete> [options]
+```
+
+If no command is provided, the CLI defaults to `run`.
+
+All commands print JSON to stdout. Errors use:
+
+```json
+{ "ok": false, "error": { "code": "...", "message": "...", "details": { ... } } }
+```
+
+### `run`
+
+Starts orchestration for feature specs and returns runtime metadata (`runtime_status`, `queue_depth`, dashboard snapshot, and active feature list).
+
+Examples:
+
+```bash
+# Installed binary
+aop run -fi ./.aop/features/my_feature/spec.md --agent-provider custom
+
+# In-repo dev command
+npm run run -- -fi ./.aop/features/my_feature/spec.md --agent-provider custom
+```
+
+Behavior:
+
+- Input resolution:
+  - `-fi <path>` uses one file.
+  - `-fl <path>` recursively discovers all `*.md` files in deterministic lexical order.
+  - no `-fi/-fl` calls `feature.discover_specs` and runs discovered canonical specs.
+- Canonical ingestion:
+  - canonical input (`.aop/features/<feature_id>/spec.md`) runs in place.
+  - non-canonical input is copied to `.aop/features/<feature_id>/spec.md`.
+  - `feature_id` is derived from file stem (strips `.spec` or `-spec` suffixes when present).
+  - each ingested feature runs `feature.init`, then state source metadata is patched with source path/hash.
+- Provider selection precedence:
+  1. CLI flags (`--agent-provider`, `--agent-model`, `--provider-config-env`)
+  2. env vars (`AOP_AGENT_PROVIDER`, `AOP_AGENT_MODEL`, `AOP_PROVIDER_CONFIG_ENV`)
+  3. `agentic/orchestrator/agents.yaml` runtime defaults
+- Runtime start:
+  - starts `SupervisorRuntime` with `max_active_features=5`, `max_parallel_gate_runs=3`.
+  - `max_iterations_per_phase` resolves from `policy.yaml` (`supervisor.max_iterations_per_phase`, default `6`).
+  - `--takeover-stale-run` enables stale run-lease takeover when another run is stale.
+
+### `status`
+
+Returns orchestration snapshot via `report.dashboard`:
+
+- global index (`active`, `blocked`, `merged`, locks, runtime session metadata)
+- per-feature summaries (status, held locks, gate profile/results, timestamps)
+
+Example:
+
+```bash
+aop status
+```
+
+### `resume`
+
+Runs recovery (`kernel.recoverFromState`), reconstructs resumable non-terminal feature work, and restarts `SupervisorRuntime` from persisted state:
+
+- candidate sources:
+  - `index.active`
+  - `index.blocked`
+  - `index.blocked_queue`
+  - `runtime_sessions.feature_sessions`
+  - `feature.discover_specs`
+- feature selection:
+  - excludes terminal states (`merged`, `failed`)
+  - computes deterministic `resume_phase` (`planning|building|qa|ready_to_merge`)
+  - sorts by earliest phase then `feature_id`
+- runtime restart:
+  - reuses persisted `runtime_sessions.run_id` and `owner_instance_id` when present
+  - starts supervisor loop with reconstructed feature set
+
+If no resumable features are found, `resume` returns recovery metadata only and does not start a new loop.
+
+Example:
+
+```bash
+aop resume
+```
+
+---
+
+## Docker MCP Deployment
+
+Baseline container artifacts:
+
+- image definition: `docker/mcp.Dockerfile`
+- runtime preflight entrypoint: `docker/mcp.entrypoint.sh`
+- compose contract: `docker/mcp.compose.yaml`
+
+Required runtime assumptions:
+
+- target repository is bind-mounted at `/repo`
+- container includes `node`, `npm`, `npx`, and `git`
+- commands execute from `/repo`
+
+Quick usage:
+
+```bash
+docker compose -f docker/mcp.compose.yaml build aop-mcp
+docker compose -f docker/mcp.compose.yaml run --rm aop-mcp npm run run -- status --transport mcp
+```
+
+Contract validation:
+
+```bash
+npm run validate:docker-mcp
+node apps/control-plane/scripts/validate-docker-mcp-contract.mjs --smoke
+```
+
+### `stop`
+
+Current behavior is a placeholder only:
+
+```json
+{ "ok": true, "data": { "status": "stop_not_implemented_yet" } }
+```
+
+It does not currently terminate active sessions or revoke leases.
+
+Example:
+
+```bash
+aop stop
+```
+
+### `delete`
+
+Performs deterministic feature cleanup. Default behavior is preview-only (`dry_run=true`); destructive execution requires `--yes`.
+
+Examples:
+
+```bash
+# Preview cleanup plan only (default behavior)
+aop delete --feature-id my_feature
+
+# Apply cleanup (remove runtime artifacts + worktree; keep local branch)
+aop delete --feature-id my_feature --yes
+
+# Apply cleanup and force-delete local branch
+aop delete --feature-id my_feature --yes --remove-branch force
+```
+
+Behavior:
+
+- blocks deletion when a fresh run lease exists (`run_already_active`)
+- preview reports planned cleanup for feature files, index/session references, locks, blocked queue entries, worktree, and branch
+- execution removes feature residue from index/runtime state, deletes `.aop/features/<feature_id>`, optionally removes worktree, and optionally removes local branch
+
+### CLI Options
+
+Supported options:
+
+| Option                                                | Description                                                                       |
+|-------------------------------------------------------|-----------------------------------------------------------------------------------|
+| `-fi <path>`                                          | Run exactly one spec file                                                         |
+| `-fl <path>`                                          | Resolve all `**/*.md` files recursively in a folder (deterministic lexical order) |
+| `--agent-provider <codex\\|claude\\|gemini\\|custom>` | Provider selection                                                                |
+| `--agent-model <model-id>`                            | Model selection                                                                   |
+| `--provider-config-env <ENV_VAR>`                     | Provider auth/config environment variable name                                    |
+| `--transport <mcp\\|inprocess>`                       | Tool transport selection (default `mcp`)                                          |
+| `--takeover-stale-run`                                | Allow stale run-lease takeover during `run`                                       |
+| `--feature-id <id>`                                   | Target feature for `delete`                                                       |
+| `--dry-run [true\\|false]`                            | Delete mode selector (defaults to preview behavior)                               |
+| `--yes`                                               | Confirm destructive `delete` execution                                            |
+| `--remove-worktree [true\\|false]`                    | Whether `delete` removes `.worktrees/<feature_id>` (default `true`)               |
+| `--remove-branch <none\\|safe\\|force>`               | Optional local branch cleanup mode for `delete` (default `none`)                  |
+
+Validation behavior:
+
+- `-fi` and `-fl` are mutually exclusive (`invalid_cli_args`)
+- missing path/folder -> `input_path_not_found`
+- no discovered specs -> `no_specs_found`
+- unsupported command -> `invalid_cli_args`
+- invalid `--transport` -> `invalid_cli_args`
+- `delete` without `--feature-id` -> `invalid_cli_args`
+- destructive `delete` without `--yes` -> `invalid_cli_args` when explicitly requested via `--dry-run false`
+
+Feature ID derivation for non-canonical inputs:
+
+1. start from filename stem
+2. remove `.spec` suffix if present
+3. else remove `-spec` suffix if present
+4. result must match `^[a-z0-9_][a-z0-9_-]*$`
+
+Provider resolution precedence:
+
+1. CLI flags
+2. env vars (`AOP_AGENT_PROVIDER`, `AOP_AGENT_MODEL`, `AOP_PROVIDER_CONFIG_ENV`)
+3. `agentic/orchestrator/agents.yaml` runtime defaults
+
+Transport behavior:
+
+- default transport is `mcp`
+- use `--transport inprocess` for test/recovery fallback paths
+- `--transport mcp` remains available for explicitness
+
+---
+
+## Configuration
+
+### Policy (`agentic/orchestrator/policy.yaml`)
+
+Current defaults include:
+
+- plan and allowed-area patch enforcement enabled
+- collision policy `reject`
+- lock resources: `openapi`, `events`, `db_migrations`, `protected:libs/core`
+- lock acquisition behavior: wait + backoff, lease TTL `300s`
+- default execution timeout `600s`
+- coverage minimums `line>=0.90`, `branch>=0.90`
+- coverage targets `line=1.00`, `branch=1.00`
+- implementation constraints: `workspace=nx`, `framework=vitest`
+- merge requires explicit user approval token
+- supervisor iteration loop is policy-configurable via `supervisor.max_iterations_per_phase` (default `6`)
+
+### Gates (`agentic/orchestrator/gates.yaml`)
+
+Default profile modes:
+
+- `fast`
+- `full`
+- `merge`
+
+Coverage parser:
+
+- `lcov` from `coverage/control-plane/lcov.info`
+
+### Agents (`agentic/orchestrator/agents.yaml`)
+
+- role-specific system prompt paths
+- default provider/model/config-env fallback values
+- stack-specific examples: [`example-configurations/node/`](example-configurations/node) and [`example-configurations/java/`](example-configurations/java)
+
+### Example configuration bundles
+
+- overview: [`example-configurations/README.md`](example-configurations/README.md)
+- Node.js bundle: [`example-configurations/node/`](example-configurations/node)
+- Java (Maven) bundle: [`example-configurations/java/`](example-configurations/java)
+- note: `policy.yaml` `implementation.workspace` and `testing.framework` are control-plane schema invariants; language-specific test execution lives in each bundle's `gates.yaml`.
+
+---
+
+## Required Schemas
+
+This section defines the schema-governed files the target repository must contain or will be expected to produce at runtime.
+
+### Who provides what
+
+Files you provide/configure:
+
+- `agentic/orchestrator/policy.yaml`
+- `agentic/orchestrator/gates.yaml`
+- `agentic/orchestrator/agents.yaml` (recommended; if present it is schema validated)
+- `.aop/features/<feature_id>/spec.md` (input spec per feature)
+
+Files the runtime creates/maintains:
+
+- `.aop/features/index.json`
+- `.aop/features/<feature_id>/state.md`
+- `.aop/features/<feature_id>/plan.json`
+- `.aop/features/<feature_id>/qa_test_index.json`
+- `.aop/features/<feature_id>/logs/*`
+- `.aop/features/<feature_id>/evidence/*`
+
+### Schema mapping
+
+| Runtime file                                       | Schema file                                              | Required/expected essentials                                                                                                                                                                    |
+|----------------------------------------------------|----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `.aop/features/<feature_id>/plan.json`             | `agentic/orchestrator/schemas/plan.schema.json`          | `feature_id`, `plan_version`, `summary`, `allowed_areas`, `forbidden_areas`, `base_ref`, `files.{create,modify,delete}`, `contracts.{openapi,events,db}`, `acceptance_criteria`, `gate_profile` |
+| `.aop/features/<feature_id>/state.md` front matter | `agentic/orchestrator/schemas/state.schema.json`         | `feature_id`, `version`, `branch`, `worktree_path`, `status`, `gate_profile`, `gates`, `locks.held`, `collisions`, `cluster`, `role_status`, `last_updated`                                     |
+| `.aop/features/index.json`                         | `agentic/orchestrator/schemas/index.schema.json`         | `version`, `active`, `blocked`, `merged`, `locks`, `lock_leases`, `blocked_queue`, `runtime_sessions.{run_id,orchestrator_session_id,owner_instance_id,lease_expires_at,feature_sessions}`      |
+| `agentic/orchestrator/gates.yaml`                  | `agentic/orchestrator/schemas/gates.schema.json`         | `version`, `profiles.<profile>.modes.<mode>[{name,cmd,...}]`, optional parser/threshold metadata                                                                                                |
+| `agentic/orchestrator/policy.yaml`                 | `agentic/orchestrator/schemas/policy.schema.json`        | commit/merge policy, patch policy, lock config, collision policy, path rules, execution policy, RBAC, Nx/Vitest implementation constraints                                                      |
+| `agentic/orchestrator/agents.yaml`                 | `agentic/orchestrator/schemas/agents.schema.json`        | `version`, `roles`, `missing_prompt_behavior`, optional runtime defaults                                                                                                                        |
+| `.aop/features/<feature_id>/qa_test_index.json`    | `agentic/orchestrator/schemas/qa_test_index.schema.json` | `feature_id`, `version`, `source_diff_ref`, `items[]` with path/hunks/required_tests/status                                                                                                     |
+
+### Important operational notes
+
+- `state.md`, `index.json`, `plan.json`, and `qa_test_index.json` are not just data files; they are part of the runtime contract and are versioned/validated.
+- mutating operations are optimistic-concurrency guarded (`expected_version`/`expected_plan_version` semantics).
+- schema failures are blocked and returned as structured errors.
+
+---
+
+## Branches, Worktrees, and Review Before Merge
+
+This runtime uses **feature branches + git worktrees**, not GitHub/GitLab fork automation.
+
+- A feature flow creates/uses branch `<feature_id>`
+- It creates worktree `.worktrees/<feature_id>`
+- Changes are visible on host filesystem before merge
+- Merge is never implicit on gate pass; it requires explicit promotion via `feature.ready_to_merge` after approval
+
+### What gets created
+
+For feature `my_feature`:
+
+- branch: `my_feature`
+- worktree path: `.worktrees/my_feature`
+
+Base branch used for cut is configured in `policy.yaml` (`worktree.base_branch`, currently `main`).
+
+### Manual review workflow (recommended)
+
+1. Inspect working changes in the feature worktree:
+   ```bash
+   git -C .worktrees/my_feature status
+   git -C .worktrees/my_feature diff --stat
+   git -C .worktrees/my_feature diff
+   ```
+2. Inspect commit history for the feature branch:
+   ```bash
+   git log --oneline --decorate main..my_feature
+   ```
+3. Compare branch delta against base:
+   ```bash
+   git diff --name-status main...my_feature
+   git diff main...my_feature
+   ```
+4. Inspect runtime evidence and logs:
+   ```bash
+   ls -la .aop/features/my_feature/evidence
+   ls -la .aop/features/my_feature/logs
+   ```
+5. Only after review/approval, allow merge promotion (`feature.ready_to_merge` path).
+
+### If you want remote forks anyway
+
+The runtime does not create remote forks automatically. If your workflow requires forks, push feature branches manually to your fork remote.
+
+---
+
+## Deterministic Tool Surface (Detailed Definitions)
+
+Defined in [agentic/orchestrator/tools.md](agentic/orchestrator/tools.md).
+
+All failures return structured error payloads with stable error codes.
+
+### MCP contract artifacts
+
+- `agentic/orchestrator/tools/catalog.json`: canonical tool list, roles, handler bindings, mutating/idempotency requirements, and schema refs.
+- `agentic/orchestrator/tools/protocol.json`: pinned MCP protocol + SDK metadata and required transports.
+- `agentic/orchestrator/tools/errors.schema.json`: normalized error envelope contract.
+- `agentic/orchestrator/tools/schemas/input/*.schema.json`: per-tool request schemas.
+- `agentic/orchestrator/tools/schemas/output/*.schema.json`: per-tool success payload schemas.
+
+Validation workflow:
+
+```bash
+npm run validate:mcp-contracts
+npm run validate:architecture
+```
+
+This verifies protocol pinning, `catalog.json`/`tools.md`/schema parity, and enforced layering boundaries before CI or release.
+
+### Tool definitions
+
+| Tool                     | Purpose                                                                | Mutates state/files | Typical caller role(s)                 |
+|--------------------------|------------------------------------------------------------------------|---------------------|----------------------------------------|
+| `feature.discover_specs` | Discover canonical `spec.md` files under `.aop/features/*`             | No                  | orchestrator, system                   |
+| `feature.init`           | Initialize feature folder/state and ensure branch/worktree             | Yes                 | orchestrator, system                   |
+| `feature.get_context`    | Return spec + state + plan + latest evidence + QA index bundle         | No                  | orchestrator, planner, builder, qa     |
+| `feature.state_get`      | Read parsed state front matter/body                                    | No                  | orchestrator/planner/builder/qa/system |
+| `feature.state_patch`    | Patch canonical feature state with version guard                       | Yes                 | orchestrator, system                   |
+| `feature.log_append`     | Append stamped note to feature decision log                            | Yes                 | orchestrator, system                   |
+| `plan.submit`            | Validate and accept initial plan (schema/policy/lock/collision checks) | Yes                 | orchestrator, planner                  |
+| `plan.get`               | Get accepted plan                                                      | No                  | orchestrator, planner, builder, qa     |
+| `plan.update`            | Submit versioned plan revision (`+1` version) with full revalidation   | Yes                 | orchestrator, planner                  |
+| `repo.ensure_worktree`   | Ensure feature branch + worktree exist                                 | Yes                 | orchestrator, system                   |
+| `repo.apply_patch`       | Apply unified diff with plan/policy/path/lock enforcement              | Yes                 | builder, qa, orchestrator              |
+| `repo.status`            | Return porcelain status from feature worktree                          | No                  | builder, orchestrator                  |
+| `repo.diff`              | Return git diff for feature worktree                                   | No                  | builder, qa, orchestrator              |
+| `repo.read_file`         | Read file content from feature worktree path                           | No                  | planner, builder, qa, orchestrator     |
+| `repo.search`            | Repo-safe text search (`rg`) in feature worktree                       | No                  | planner, builder, qa, orchestrator     |
+| `repo.diff_bundle`       | Return review bundle (stat/full diff/files/latest gate summary)        | No                  | orchestrator                           |
+| `feature.ready_to_merge` | Commit + merge promotion after required gates and approval checks      | Yes                 | orchestrator, system                   |
+| `feature.delete`         | Delete feature runtime artifacts and optional local git/worktree state | Yes                 | orchestrator, system                   |
+| `gates.list`             | List available gate profiles/modes                                     | No                  | orchestrator, builder, qa              |
+| `gates.run`              | Execute gate profile/mode, capture logs/evidence, enforce thresholds   | Yes                 | builder, qa, orchestrator              |
+| `evidence.latest`        | Return latest evidence summary for feature                             | No                  | qa, orchestrator                       |
+| `qa.test_index_get`      | Return QA index + pending obligations summary                          | No                  | qa, orchestrator                       |
+| `qa.test_index_update`   | Update QA hunk statuses with version guard and evidence refs           | Yes                 | qa, orchestrator, system               |
+| `locks.acquire`          | Acquire/renew resource lease lock for feature                          | Yes                 | orchestrator, system                   |
+| `locks.release`          | Release held resource lock                                             | Yes                 | orchestrator, system                   |
+| `collisions.scan`        | Compute collision matrix across accepted plans                         | No                  | planner, orchestrator                  |
+| `report.dashboard`       | Return global orchestration summary                                    | No                  | orchestrator                           |
+| `report.feature_summary` | Return per-feature state/diff/evidence summary                         | No                  | orchestrator                           |
+
+### Role expectations at a glance
+
+- `planner`: plan-focused, read/search, collision visibility
+- `builder`: patch application + fast gate execution
+- `qa`: patch/test follow-up + QA index updates + evidence inspection
+- `orchestrator`: lifecycle coordination, locks, reporting, merge promotion, and feature cleanup (`delete`)
+- `system`: internal automation fallback with broad access
+
+---
+
+## Quality & Testing
+
+- framework: Vitest (`apps/control-plane/vitest.config.ts`)
+- coverage output: `coverage/control-plane`
+- configured thresholds: lines/branches/functions/statements at `90%`
+- workspace tooling: Nx targets (`run`, `build`, `test`, `typecheck`)
+- Nx launcher: use `npm run nx -- <target>`; this workspace defaults to `NX_DAEMON=false` and `NX_ISOLATE_PLUGINS=false` to avoid Unix-socket worker failures in restricted environments.
+- Shell setup for raw `npx nx` commands:
+  ```bash
+  source scripts/dev-shell-env.sh
+  npx nx run control-plane:test
+  ```
+
+---
+
+## Current Status
+
+From [progress.md](spec-files/progress.md):
+
+- Nx + TypeScript + Vitest migration complete
+- Kernel + supervisor + CLI implemented end-to-end
+- strict linting is enforced (`npm run lint`) and build is lint-gated
+- `npm run typecheck` passes
+- architecture boundary checks are CI-enforced via `npm run validate:architecture`
+
+Environment note observed during implementation sessions:
+
+- intermittent `npm install` DNS failures (`EAI_AGAIN` to `registry.npmjs.org`) can block full test runs in constrained environments.
+
+---
+
+## Contributing
+
+Contributions are welcome.
+
+Suggested workflow:
+
+1. Create a feature branch (`feature/<name>`)
+2. Implement changes with tests
+3. Run quality checks:
+   ```bash
+   npm run typecheck
+   npm run build
+   npm test
+   ```
+4. Commit with clear, conventional commit messages
+5. Open a pull request with scope, rationale, and verification notes
+
+### Commit Convention
+
+Recommended conventional prefixes:
+
+- `feat:` new feature
+- `fix:` bug fix
+- `docs:` documentation
+- `refactor:` internal structure change
+- `test:` tests added/updated
+- `chore:` maintenance and tooling
+
+---
+
+## License
+
+MIT © Eric Taurone
+
+See [LICENSE](LICENSE).
+
+---
+
+## Support & Links
+
+- Repository: [Eric-Taurone-Software/Agentic-Orchestrator](https://github.com/Eric-Taurone-Software/Agentic-Orchestrator)
+- Author: Eric Taurone
+- Specification: [agentic_orchestrator_spec.md](spec-files/agentic_orchestrator_spec.md)
+- Implementation log: [progress.md](spec-files/progress.md)
+- Example bundles: [example-configurations/README.md](example-configurations/README.md)
+- Tool catalog: [agentic/orchestrator/tools.md](agentic/orchestrator/tools.md)
+- Policy config: [agentic/orchestrator/policy.yaml](agentic/orchestrator/policy.yaml)
+- Gates config: [agentic/orchestrator/gates.yaml](agentic/orchestrator/gates.yaml)
+- Agents config: [agentic/orchestrator/agents.yaml](agentic/orchestrator/agents.yaml)

package/agentic/orchestrator/agents.yaml

@@ -0,0 +1,14 @@
+version: 1
+roles:
+  planner:
+    system_prompt_path: agentic/orchestrator/prompts/planner.system.md
+  builder:
+    system_prompt_path: agentic/orchestrator/prompts/builder.system.md
+  qa:
+    system_prompt_path: agentic/orchestrator/prompts/qa.system.md
+missing_prompt_behavior: ignore
+runtime:
+  default_provider: custom
+  default_model: local-default
+  provider_config_env: AOP_PROVIDER_CONFIG_ENV
+  role_provider_overrides: {}