agentic-orchestrator 0.1.0

package/docker/mcp.Dockerfile

@@ -0,0 +1,14 @@
+FROM node:22-bookworm-slim
+
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends git ca-certificates openssh-client \
+  && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY . /app
+RUN npm ci
+
+ENV AOP_REPO_ROOT=/repo
+ENTRYPOINT ["/bin/sh", "/app/docker/mcp.entrypoint.sh"]
+CMD ["npm", "run", "run", "--", "status", "--transport", "mcp"]

package/docker/mcp.compose.yaml

@@ -0,0 +1,15 @@
+services:
+  aop-mcp:
+    build:
+      context: ..
+      dockerfile: docker/mcp.Dockerfile
+    working_dir: /repo
+    volumes:
+      - ../:/repo
+      - npm-cache:/cache/npm
+    environment:
+      NPM_CONFIG_CACHE: /cache/npm
+    command: ["npm", "run", "run", "--", "status", "--transport", "mcp"]
+
+volumes:
+  npm-cache:

package/docker/mcp.entrypoint.sh

@@ -0,0 +1,17 @@
+#!/bin/sh
+set -eu
+
+if [ ! -d "/repo" ]; then
+  echo "Missing required /repo bind mount."
+  exit 64
+fi
+
+for tool in node npm npx git; do
+  if ! command -v "$tool" >/dev/null 2>&1; then
+    echo "Required toolchain binary is missing: $tool"
+    exit 69
+  fi
+done
+
+cd /repo
+exec "$@"

package/eslint.config.mjs

@@ -0,0 +1,93 @@
+import js from '@eslint/js';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  {
+    ignores: [
+      '**/node_modules/**',
+      '**/dist/**',
+      '**/coverage/**',
+      '**/.nx/**',
+      '**/.worktrees/**',
+      '.aop/**',
+      '**/.aop/**',
+      'agentic/features/**',
+      'agentic/runtime/**',
+      '**/*.d.ts'
+    ]
+  },
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    files: ['**/*.{js,mjs,cjs}'],
+    languageOptions: {
+      globals: {
+        ...globals.node
+      }
+    },
+    rules: {
+      'no-console': 'off'
+    }
+  },
+  {
+    files: ['**/*.ts'],
+    languageOptions: {
+      globals: {
+        ...globals.node
+      },
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname
+      }
+    },
+    rules: {
+      '@typescript-eslint/consistent-type-imports': 'error',
+      '@typescript-eslint/no-explicit-any': 'error',
+      '@typescript-eslint/no-floating-promises': 'error',
+      '@typescript-eslint/no-misused-promises': 'error',
+      '@typescript-eslint/no-unnecessary-type-assertion': 'error',
+      '@typescript-eslint/no-shadow': 'error',
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        {
+          argsIgnorePattern: '^_',
+          caughtErrorsIgnorePattern: '^_',
+          varsIgnorePattern: '^_'
+        }
+      ],
+      '@typescript-eslint/require-await': 'error',
+      '@typescript-eslint/return-await': 'off',
+      curly: ['error', 'all'],
+      eqeqeq: ['error', 'always', { null: 'ignore' }],
+      'no-console': [
+        'error',
+        {
+          allow: ['warn', 'error']
+        }
+      ],
+      'no-debugger': 'error',
+      'no-var': 'error',
+      'object-shorthand': ['error', 'always'],
+      'prefer-const': 'error'
+    }
+  },
+  {
+    files: ['apps/control-plane/scripts/**/*.{ts,mjs}', 'apps/control-plane/src/cli/aop.ts'],
+    rules: {
+      'no-console': 'off'
+    }
+  },
+  {
+    files: ['apps/control-plane/test/**/*.ts'],
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-unsafe-assignment': 'off',
+      '@typescript-eslint/no-unsafe-call': 'off',
+      '@typescript-eslint/no-unsafe-member-access': 'off',
+      '@typescript-eslint/no-unsafe-return': 'off',
+      '@typescript-eslint/require-await': 'off',
+      '@typescript-eslint/unbound-method': 'off'
+    }
+  }
+);

package/example-configurations/README.md

@@ -0,0 +1,26 @@
+# Example Configurations
+
+This folder provides ready-to-copy configuration sets for common project stacks.
+
+- `node/`: Node.js-focused gate commands and coverage parsing (`lcov`).
+- `java/`: Java (Maven)-focused gate commands and coverage parsing (`jacoco_xml`).
+
+Each stack includes:
+
+- `policy.yaml`
+- `gates.yaml`
+- `agents.yaml`
+
+Usage:
+
+1. Pick a stack folder.
+2. Copy its files into `agentic/orchestrator/`.
+3. Adjust commands, paths, and thresholds to your repository.
+
+Important:
+
+- `policy.yaml -> implementation.workspace` and `policy.yaml -> testing.framework` are control-plane invariants for this project and stay `nx`/`vitest`.
+- Target-repo test/build behavior is defined by `gates.yaml` commands and coverage parsers.
+- For Java projects, use the Java `gates.yaml` Maven commands (`./mvnw ...`) and `jacoco_xml` parser.
+- `policy.yaml -> supervisor.max_iterations_per_phase` controls planner/builder/qa loop reconciliation iterations (default `6`).
+- `policy.yaml -> rbac.orchestrator` includes `feature.delete` for the delete command path.

package/example-configurations/java/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: java-default
+  provider_config_env: JAVA_PROVIDER_CONFIG_ENV
+  role_provider_overrides: {}

package/example-configurations/java/gates.yaml

@@ -0,0 +1,29 @@
+version: 1
+profiles:
+  default:
+    modes:
+      fast:
+        - name: compile_no_tests
+          cmd: ["./mvnw", "-q", "-DskipTests", "compile"]
+          timeout_seconds: 900
+      full:
+        - name: verify_with_tests
+          cmd: ["./mvnw", "-q", "verify"]
+          timeout_seconds: 1800
+      merge:
+        - name: verify_release_candidate
+          cmd: ["./mvnw", "-q", "verify"]
+          timeout_seconds: 1800
+    parsers:
+      coverage:
+        type: jacoco_xml
+        path: target/site/jacoco/jacoco.xml
+    thresholds:
+      coverage_line_min: 0.9
+      coverage_branch_min: 0.9
+      coverage_line_target: 1.0
+      coverage_branch_target: 1.0
+capabilities:
+  - none
+  - jacoco_xml
+  - junit_xml

package/example-configurations/java/policy.yaml

@@ -0,0 +1,148 @@
+version: 1
+commit_policy:
+  allow_commit: false
+  allow_merge: false
+patch_policy:
+  enforce_plan: true
+  enforce_allowed_areas: true
+locks:
+  resources:
+    - openapi
+    - events
+    - db_migrations
+    - protected:src/main/java
+  contract_to_resource:
+    openapi: openapi
+    events: events
+    db: db_migrations
+  lease_ttl_seconds: 300
+  acquire_behavior: wait
+  default_wait_timeout_seconds: 300
+  acquire_backoff:
+    initial_ms: 200
+    max_ms: 5000
+    multiplier: 2
+    jitter_ms: 150
+protected_areas:
+  - agentic/orchestrator/schemas
+  - pom.xml
+exclusive_areas:
+  - src/main/java
+required_modes:
+  - fast
+  - full
+required_merge_mode: merge
+collision_policy: reject
+config_precedence:
+  policy_hard_constraints:
+    - execution.default_step_timeout_seconds
+    - testing.coverage.minimums
+    - testing.coverage.targets
+  gates_profile_defaults:
+    - profiles
+  plan_verification_overrides:
+    - verification_overrides
+path_rules:
+  matching: repo_prefix
+  normalize_paths: true
+  allow_symlink_traversal: false
+execution:
+  default_step_timeout_seconds: 1200
+  retry_policy:
+    transient_max_retries: 1
+    transient_error_codes:
+      - 124
+    non_retryable_error_codes:
+      - 2
+      - 126
+      - 127
+  env_allowlist:
+    - PATH
+    - HOME
+    - JAVA_HOME
+    - MAVEN_OPTS
+implementation:
+  # Control-plane invariant (schema-enforced for this orchestrator project),
+  # not a claim about the managed repository build system.
+  workspace: nx
+testing:
+  # Control-plane invariant (schema-enforced). Java test execution is driven
+  # by gates.yaml Maven commands and JaCoCo parsing.
+  framework: vitest
+  coverage:
+    minimums:
+      line: 0.9
+      branch: 0.9
+    targets:
+      line: 1.0
+      branch: 1.0
+merge_policy:
+  require_user_approval: true
+  allowed_strategies:
+    - merge_commit
+    - squash
+    - rebase
+worktree:
+  base_branch: main
+supervisor:
+  max_iterations_per_phase: 6
+rbac:
+  orchestrator:
+    - feature.discover_specs
+    - feature.init
+    - feature.get_context
+    - feature.state_get
+    - feature.state_patch
+    - feature.log_append
+    - plan.submit
+    - plan.get
+    - plan.update
+    - repo.ensure_worktree
+    - repo.apply_patch
+    - repo.status
+    - repo.diff
+    - repo.read_file
+    - repo.search
+    - repo.diff_bundle
+    - gates.list
+    - gates.run
+    - evidence.latest
+    - qa.test_index_get
+    - qa.test_index_update
+    - locks.acquire
+    - locks.release
+    - collisions.scan
+    - report.dashboard
+    - report.feature_summary
+    - feature.ready_to_merge
+    - feature.delete
+  planner:
+    - feature.get_context
+    - feature.state_get
+    - plan.submit
+    - plan.update
+    - collisions.scan
+    - repo.read_file
+    - repo.search
+  builder:
+    - feature.get_context
+    - feature.state_get
+    - repo.apply_patch
+    - repo.status
+    - repo.diff
+    - repo.read_file
+    - repo.search
+    - gates.run
+  qa:
+    - feature.get_context
+    - feature.state_get
+    - repo.apply_patch
+    - repo.diff
+    - repo.read_file
+    - repo.search
+    - gates.run
+    - evidence.latest
+    - qa.test_index_get
+    - qa.test_index_update
+  system:
+    - "*"

package/example-configurations/node/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: node-default
+  provider_config_env: NODE_PROVIDER_CONFIG_ENV
+  role_provider_overrides: {}

package/example-configurations/node/gates.yaml

@@ -0,0 +1,32 @@
+version: 1
+profiles:
+  default:
+    modes:
+      fast:
+        - name: lint
+          cmd: ["npm", "run", "lint"]
+          timeout_seconds: 600
+      full:
+        - name: unit_with_coverage
+          cmd: ["npm", "test", "--", "--coverage"]
+          timeout_seconds: 1200
+      merge:
+        - name: release_checks
+          cmd: ["npm", "run", "build"]
+          timeout_seconds: 1200
+        - name: regression_with_coverage
+          cmd: ["npm", "test", "--", "--coverage"]
+          timeout_seconds: 1200
+    parsers:
+      coverage:
+        type: lcov
+        path: coverage/lcov.info
+    thresholds:
+      coverage_line_min: 0.9
+      coverage_branch_min: 0.9
+      coverage_line_target: 1.0
+      coverage_branch_target: 1.0
+capabilities:
+  - none
+  - lcov
+  - junit_xml

package/example-configurations/node/policy.yaml

@@ -0,0 +1,143 @@
+version: 1
+commit_policy:
+  allow_commit: false
+  allow_merge: false
+patch_policy:
+  enforce_plan: true
+  enforce_allowed_areas: true
+locks:
+  resources:
+    - openapi
+    - events
+    - db_migrations
+    - protected:apps/api
+  contract_to_resource:
+    openapi: openapi
+    events: events
+    db: db_migrations
+  lease_ttl_seconds: 300
+  acquire_behavior: wait
+  default_wait_timeout_seconds: 300
+  acquire_backoff:
+    initial_ms: 200
+    max_ms: 5000
+    multiplier: 2
+    jitter_ms: 150
+protected_areas:
+  - agentic/orchestrator/schemas
+  - package-lock.json
+exclusive_areas:
+  - apps/api
+required_modes:
+  - fast
+  - full
+required_merge_mode: merge
+collision_policy: reject
+config_precedence:
+  policy_hard_constraints:
+    - execution.default_step_timeout_seconds
+    - testing.coverage.minimums
+    - testing.coverage.targets
+  gates_profile_defaults:
+    - profiles
+  plan_verification_overrides:
+    - verification_overrides
+path_rules:
+  matching: repo_prefix
+  normalize_paths: true
+  allow_symlink_traversal: false
+execution:
+  default_step_timeout_seconds: 900
+  retry_policy:
+    transient_max_retries: 1
+    transient_error_codes:
+      - 124
+    non_retryable_error_codes:
+      - 2
+      - 126
+      - 127
+  env_allowlist:
+    - PATH
+    - HOME
+    - NODE_ENV
+implementation:
+  workspace: nx
+testing:
+  framework: vitest
+  coverage:
+    minimums:
+      line: 0.9
+      branch: 0.9
+    targets:
+      line: 1.0
+      branch: 1.0
+merge_policy:
+  require_user_approval: true
+  allowed_strategies:
+    - merge_commit
+    - squash
+    - rebase
+worktree:
+  base_branch: main
+supervisor:
+  max_iterations_per_phase: 6
+rbac:
+  orchestrator:
+    - feature.discover_specs
+    - feature.init
+    - feature.get_context
+    - feature.state_get
+    - feature.state_patch
+    - feature.log_append
+    - plan.submit
+    - plan.get
+    - plan.update
+    - repo.ensure_worktree
+    - repo.apply_patch
+    - repo.status
+    - repo.diff
+    - repo.read_file
+    - repo.search
+    - repo.diff_bundle
+    - gates.list
+    - gates.run
+    - evidence.latest
+    - qa.test_index_get
+    - qa.test_index_update
+    - locks.acquire
+    - locks.release
+    - collisions.scan
+    - report.dashboard
+    - report.feature_summary
+    - feature.ready_to_merge
+    - feature.delete
+  planner:
+    - feature.get_context
+    - feature.state_get
+    - plan.submit
+    - plan.update
+    - collisions.scan
+    - repo.read_file
+    - repo.search
+  builder:
+    - feature.get_context
+    - feature.state_get
+    - repo.apply_patch
+    - repo.status
+    - repo.diff
+    - repo.read_file
+    - repo.search
+    - gates.run
+  qa:
+    - feature.get_context
+    - feature.state_get
+    - repo.apply_patch
+    - repo.diff
+    - repo.read_file
+    - repo.search
+    - gates.run
+    - evidence.latest
+    - qa.test_index_get
+    - qa.test_index_update
+  system:
+    - "*"

package/nx.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "./node_modules/nx/schemas/nx-schema.json",
+  "namedInputs": {
+    "default": ["{projectRoot}/**/*", "sharedGlobals"],
+    "sharedGlobals": []
+  },
+  "plugins": [],
+  "targetDefaults": {
+    "test": {
+      "inputs": ["default", "^default"],
+      "cache": true
+    }
+  },
+  "useDaemonProcess": false,
+  "defaultBase": "main"
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "agentic-orchestrator",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "MCP-first, platform-agnostic multi-agent orchestrator control plane",
+  "scripts": {
+    "nx": "node scripts/nx-safe.mjs",
+    "test": "npm run nx -- run control-plane:test",
+    "run": "tsx apps/control-plane/src/cli/aop.ts",
+    "build": "npm run lint && npm run nx -- run control-plane:build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "validate:mcp-contracts": "tsx apps/control-plane/scripts/validate-mcp-contracts.ts",
+    "validate:docker-mcp": "node apps/control-plane/scripts/validate-docker-mcp-contract.mjs",
+    "validate:architecture": "node apps/control-plane/scripts/validate-architecture-rules.mjs",
+    "lint": "eslint . --max-warnings 0",
+    "lint:fix": "npm run lint -- --fix"
+  },
+  "bin": {
+    "aop": "dist/apps/control-plane/cli/aop.js"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.37.0",
+    "@types/node": "^22.13.10",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^9.37.0",
+    "globals": "^16.4.0",
+    "nx": "^20.5.0",
+    "tsx": "^4.19.3",
+    "typescript-eslint": "^8.46.1",
+    "typescript": "^5.8.2",
+    "vitest": "^3.2.4"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "minimatch": "^10.0.1",
+    "yaml": "^2.6.1"
+  }
+}