agentic-engineering-harness 0.4.16

package/skills/github-delivery-lifecycle/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: github-delivery-lifecycle
+description: Safe issue-linked GitHub delivery and Paseo worktree handoff.
+license: Apache-2.0
+---
+# GitHub Delivery Lifecycle
+
+Use only when project delivery integration is enabled or explicitly requested.
+
+- Treat the validated local SDD/TaskContract as normative; the GitHub issue is a delivery mirror unless project policy explicitly says otherwise.
+- Read tokens from environment only; never write credentials into specs, logs or delivery state.
+- Create at most one issue and one issue-linked branch per task; persist identifiers after each successful remote write.
+- Base the branch on the originating branch captured when the spec was created.
+- Never force-push, amend, rebase or rewrite shared history as recovery.
+- Create/reuse one Paseo worktree workspace for implementation, review and repair.
+- Report issue URL/number, branch, workspace id/path and partial-state failures.

package/skills/implementation-worker/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: implementation-worker
+purpose: Constrain an implementation agent to a frozen task and deterministic acceptance gates.
+---
+
+# Implementation Worker
+
+Implement the frozen TaskContract. You do not own requirements or architecture.
+
+Rules:
+
+- Stay within allowed paths and scope.
+- Never alter frozen contracts or frozen acceptance validators.
+- Do not add dependencies, schema changes or breaking API changes unless explicitly authorized.
+- Run the specified validation commands.
+- Report blockers instead of silently expanding scope.
+- At completion report changed files, tests run, failures, deviations and remaining risks.

package/skills/lead-engineer/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: lead-engineer
+purpose: Keep the strongest agent as requirements/architecture owner while delegating implementation safely.
+---
+
+# Lead Engineer
+
+You are the semantic and architectural owner of the change.
+
+## Before implementation
+
+1. Inspect current code and structural graph.
+2. Recall historical memory only for context; verify it against Git.
+3. Complete SDD artifacts: explore/proposal/spec/design/acceptance/tasks.
+4. Ensure business acceptance is expressed in executable Gherkin where appropriate.
+5. Create the TaskContract and freeze it.
+6. Delegate routine implementation to an OpenCode workhorse through Paseo.
+
+## During implementation
+
+- Remain the parent/owner of the task.
+- For independent tasks, use parallel workers; avoid parallel edits to highly overlapping files.
+- If a worker discovers a plan defect, evaluate it and update the authoritative design/contract yourself.
+
+## After implementation
+
+- Run the deterministic harness.
+- Inspect the actual diff, not only worker summaries.
+- If deterministic gates fail, prefer targeted worker repair packets.
+- Perform semantic/architectural review only after deterministic checks pass.

package/skills/memory-hygiene/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: memory-hygiene
+purpose: Prevent stale agent memory from becoming an authority source.
+---
+
+# Memory Hygiene
+
+Memory is advisory historical context.
+
+Store:
+- decisions and their rationale;
+- bugs and discoveries;
+- conventions;
+- useful implementation summaries.
+
+Do not treat memory as authoritative for:
+- current requirements;
+- current API/schema state;
+- current acceptance criteria;
+- current architecture when Git contradicts it.
+
+When a decision changes, supersede or explicitly invalidate the old memory instead of storing contradictory facts without provenance.

package/skills/prompt-drift-audit/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: prompt-drift-audit
+description: Detect drift among source topology, prompts, skills, routing and generated runtime artifacts.
+license: Apache-2.0
+---
+# Prompt and Configuration Drift Audit
+
+Check source -> generated runtime consistency and all referenced prompt/skill paths. Verify agent role charters match routing ownership, skill/MCP names resolve, generated files are not hand-edited and duplicated policy text has not diverged across prompts.
+
+Prefer `aeh agents check` and schema/reference checks for deterministic drift. Use semantic review only for role/policy contradictions that cannot be reduced to references or hashes.

package/skills/recovery-classifier/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: recovery-classifier
+description: Classify agent/validation failures and select the smallest deterministic recovery path.
+license: Apache-2.0
+---
+# Recovery Classifier
+
+Classify evidence into the Harness failure taxonomy before retrying:
+PATCH_CONTEXT_MISMATCH, TOOL_FAILURE, MISSING_CONTEXT, WRONG_AGENT, VALIDATION_FAILURE, REVIEW_FAILURE, AMBIGUOUS_OUTPUT, CONFLICTING_RESULTS.
+
+Use exact stderr/stdout, validator failures and routing evidence. Do not label a product/spec contradiction as an implementation failure.
+
+Recovery preference: same agent with better context -> narrow reroute/quality remediation -> senior/oracle -> lead/human only for true exceptions. Preserve the failure packet and retry history.

package/skills/routing-normalizer/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: routing-normalizer
+description: Convert a plan into bounded, ownership-safe delegation tasks.
+license: Apache-2.0
+---
+# Routing Normalizer
+
+Every delegated task must identify: id, summary, owning agent, scope, dependencies, acceptance evidence and risk.
+
+Reject or repair plans when:
+- two parallel writers overlap the same files without an ordering dependency;
+- a dependency references a missing task;
+- the selected agent does not own the stated domain;
+- acceptance is vague or cannot be validated;
+- the task silently expands sealed scope.
+
+Prefer the narrowest capable agent and explicit dependency edges over broad generalists.

package/skills/sdd/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: sdd
+purpose: Drive a strict spec-driven change from exploration to archival.
+---
+
+# Spec-Driven Development
+
+Phases:
+
+1. Explore: understand current state without deciding prematurely.
+2. Proposal: state problem, desired outcome, scope and non-goals.
+3. Specification: define requirements/invariants without implementation detail.
+4. Design: define architecture, interfaces, data/API impact and trade-offs.
+5. Acceptance: encode observable business behavior in Gherkin where appropriate.
+6. Tasks: decompose design into implementation work.
+7. Contract: create and freeze a machine-readable TaskContract.
+8. Apply: delegate implementation to constrained workers.
+9. Verify: deterministic harness first, semantic review second.
+10. Archive: persist final artifacts and curated learnings to memory.
+
+Do not let a later phase silently rewrite the intent of an earlier approved phase.

package/skills/simplify/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: simplify
+description: Reduce unnecessary complexity without changing observable behavior or sealed contracts.
+license: Apache-2.0
+---
+# Simplify
+
+Use after correctness is established or when complexity itself causes risk.
+
+- Preserve behavior, public contracts and acceptance criteria.
+- Remove accidental abstraction, duplication and confusing control flow only when evidence supports it.
+- Prefer small local simplifications over broad rewrites.
+- Keep changes within task scope and rerun the focused deterministic checks.
+- Do not trade explicit invariants for cleverness.
+
+Report what became simpler and the evidence that behavior remains unchanged.

package/skills/verification-planning/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: verification-planning
+description: Design deterministic evidence and validation gates before implementation.
+license: Apache-2.0
+---
+# Verification Planning
+
+Use before non-trivial implementation.
+
+1. Map each requirement to observable evidence.
+2. Prefer an existing deterministic validator over LLM review.
+3. Separate fast focused checks from final integration checks.
+4. Identify environment, fixture and external-service prerequisites.
+5. Define failure signals that are unambiguous and machine-readable.
+6. Do not weaken acceptance criteria to fit the implementation.
+
+Return: requirement -> validator -> command/evidence -> expected pass condition -> fallback if the validator cannot run.

package/skills/worktree-lifecycle/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: worktree-lifecycle
+description: Manage isolated Git/Paseo workspaces without history rewriting or cross-task contamination.
+license: Apache-2.0
+---
+# Worktree Lifecycle
+
+Use for branch/worktree-backed task execution.
+
+- Capture the originating branch before creating task state.
+- Prefer one issue/task branch per isolated workspace.
+- Never reuse a dirty worktree for an unrelated task.
+- Do not force-push, amend, rebase or reset shared history as recovery.
+- Keep sealed contracts/spec artifacts available read-only to workers.
+- Reuse the same Paseo workspace for implementation, review and repair of one task.
+- Archive/remove the workspace only after delivery state is durable.
+
+Report branch, base, workspace id/path and any lifecycle blocker.

package/templates/AGENTS.md

@@ -0,0 +1,37 @@
+# Engineering Agent Contract
+
+## Lead agent
+
+The lead agent owns requirements interpretation, architecture, SDD artifacts, decomposition, review and final semantic acceptance. Prefer Codex for this role.
+
+Before delegating implementation:
+
+1. Inspect current repository state and relevant structural context.
+2. Recover historical memory only as advisory context.
+3. Produce/update proposal, specification, design and executable acceptance criteria.
+4. Create a TaskContract with explicit scope, invariants and deterministic validators.
+5. Freeze the TaskContract before implementation begins.
+
+After the worker finishes, inspect the actual diff and deterministic validation report. Never accept work solely from a worker summary.
+
+## Worker agent
+
+The worker implements an assigned frozen task. Prefer OpenCode with the configured workhorse model.
+
+The worker must not:
+
+- redefine requirements;
+- expand scope silently;
+- modify frozen TaskContracts;
+- weaken acceptance criteria or validators to make a task pass;
+- introduce new dependencies, schema changes or breaking APIs unless the TaskContract permits them.
+
+If the plan conflicts with reality, report the blocker to the lead agent instead of silently redesigning the system.
+
+## Source-of-truth order
+
+1. Current Git-versioned code and schemas.
+2. Frozen TaskContract and current SDD artifacts.
+3. ADRs and project policy.
+4. Executable acceptance criteria.
+5. Memory backend as historical/advisory context only.

package/templates/agents.source.jsonc

@@ -0,0 +1,39 @@
+{
+  "version": 1,
+  "extends": ["aeh:default"],
+  "activeProfile": "balanced",
+
+  // Override a built-in model alias once and every agent using it follows.
+  // "models": {
+  //   "workhorse": { "provider": "opencode-go", "model": "deepseek-v4-flash" },
+  //   "brain": { "provider": "openai", "model": "gpt-5.6-luna", "variant": "max" }
+  // },
+  "models": {},
+
+  // Add a new agent or partially override a built-in agent by name.
+  // "agents": {
+  //   "backend-implementer": { "temperature": 0.05 },
+  //   "domain-specialist": {
+  //     "role": "implementer",
+  //     "domains": ["my-domain"],
+  //     "execution": { "model": "@workhorse" },
+  //     "permissions": { "read": "allow", "write": "allow", "shell": "allow" },
+  //     "outputContract": "implementer"
+  //   }
+  // },
+  "agents": {},
+
+  // Rules with an existing id replace the built-in rule; new ids are appended.
+  "routing": [],
+
+  // Removal supports minimatch patterns and cascades agent references out of routing/recovery/councils.
+  // Example: remove every mobile agent from a non-mobile repository.
+  "remove": {
+    "agents": [],
+    "models": [],
+    "runtimes": [],
+    "profiles": [],
+    "routing": [],
+    "councils": []
+  }
+}

package/templates/otel-collector.yaml

@@ -0,0 +1,21 @@
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+      http:
+        endpoint: 0.0.0.0:4318
+
+processors:
+  batch: {}
+
+exporters:
+  debug:
+    verbosity: basic
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [debug]

package/templates/project.yaml

@@ -0,0 +1,196 @@
+version: 1
+
+project:
+  name: change-me
+
+agents:
+  configPath: .harness/agents.source.jsonc
+  generatedPath: .harness/generated/agents.json
+  activeProfile: balanced
+  required: true
+  findingsDir: .harness/findings
+
+workflow:
+  quick:
+    maxFiles: 5
+    disallowedDomains:
+      - security
+      - authentication
+      - authorization
+      - architecture
+      - database
+      - schema
+      - migration
+      - api-contract
+      - multi-tenancy
+  issueIntake:
+    enabled: true
+    snapshotDir: .harness/issues
+    verifyDriftOnRun: true
+    requireOpen: true
+    plannerAgent: planner
+    autoHandoff: true
+  reviews:
+    enabled: true
+    reviewQuick: false
+    leadAcceptance: true
+    leadAcceptanceQuick: false
+    quality:
+      severityPoints:
+        critical: 300
+        high: 75
+        medium: 24
+        low: 3
+        note: 1
+    convergence:
+      minimumDebtPointImprovement: 3
+      stagnationWindow: 2
+      cycleDetection: true
+      regressionDetection: true
+    finalQualityGate:
+      maxBySeverity:
+        critical: 0
+        high: 0
+        medium: 0
+        low: 3
+      maxDebtPoints: 9
+    escalation:
+      criticalStartStage: 2
+      replanResumeStage: 2
+      stages:
+        - name: normal
+          action: remediate
+        - name: quality
+          action: remediate
+          agent: quality-implementer
+        - name: senior
+          action: remediate
+          agent: senior-implementer
+          model: "@brain"
+        - name: diagnosis
+          action: diagnose
+          agent: oracle
+          model: "@brain"
+        - name: replan
+          action: replan
+          agent: planner
+          model: "@brain"
+
+orchestration:
+  provider: paseo
+  required: false
+  worker:
+    provider: opencode
+    maxRepairAttempts: 2
+
+toolchain:
+  configPath: .harness/toolchain.yaml
+  lockPath: .harness/toolchain.lock.json
+  statePath: .harness/toolchain.state.json
+  generatedMisePath: .config/mise/conf.d/aeh.toml
+
+mcp:
+  servers:
+    context7:
+      description: Current library/framework documentation lookup.
+      type: remote
+      url: https://mcp.context7.com/mcp
+      oauth: false
+      enabled: true
+    playwright:
+      description: Browser exploration and stateful UI validation; prefer deterministic Playwright tests when they are sufficient.
+      type: local
+      command: [npx, -y, "@playwright/mcp@0.0.78"]
+      enabled: true
+      timeoutMs: 30000
+    github:
+      description: Official GitHub MCP server in read-only mode for repository/issue/PR/action triage. Deterministic Harness delivery owns writes.
+      type: local
+      command: [podman, run, -i, --rm, -e, GITHUB_PERSONAL_ACCESS_TOKEN, -e, GITHUB_TOOLSETS, -e, GITHUB_READ_ONLY, ghcr.io/github/github-mcp-server]
+      environment:
+        GITHUB_PERSONAL_ACCESS_TOKEN: "{env:GITHUB_TOKEN}"
+        GITHUB_TOOLSETS: repos,issues,pull_requests,actions
+        GITHUB_READ_ONLY: "1"
+      enabled: true
+      timeoutMs: 30000
+    sentry:
+      description: Optional production-error and trace investigation via Sentry's remote MCP.
+      type: remote
+      url: https://mcp.sentry.dev/mcp
+      enabled: false
+      timeoutMs: 10000
+
+delivery:
+  stateDir: .harness/delivery
+  github:
+    enabled: false
+    tokenEnv: GH_TOKEN
+    assignTokenOwner: true
+    labels: []
+    branchPattern: feature/gh-{issue}-{slug}
+    finalizeOnAcceptance: true
+    pullRequestDraft: true
+  paseo:
+    enabled: false
+    createWorkspace: true
+    autoUseWorkspace: true
+    worktreeSlugPattern: gh-{issue}-{slug}
+
+memory:
+  provider: engram
+  required: false
+  benchmark:
+    casesDir: memory-benchmarks
+    resultsDir: .harness/memory-benchmarks
+    providers: []
+
+codeIntelligence:
+  provider: graphify
+  required: false
+  graphPath: graphify-out/graph.json
+  snapshotDir: .harness/graphify
+
+sdd:
+  specsDir: specs
+  contractsDir: .harness/contracts
+  reportsDir: .harness/reports
+  repairsDir: .harness/repairs
+  runsDir: .harness/runs
+
+validation:
+  baseRef: main
+  requireSeal: true
+  frozenPaths:
+    - .harness/contracts/**
+    - .harness/seals/**
+    - tests/acceptance/frozen/**
+  commands: []
+  validators: []
+  opa:
+    enabled: false
+    policyDirs:
+      - .harness/policies/core
+
+security:
+  sandbox:
+    provider: podman
+    required: false
+  tools:
+    - opengrep
+    - trivy
+
+telemetry:
+  enabled: true
+  required: false
+  localEventsFile: .harness/telemetry/events.ndjson
+  exporter: none
+  serviceName: engineering-harness-consumer
+
+evals:
+  corpusDir: evals/corpus
+  resultsDir: .harness/evals/results
+  workspacesDir: .harness/evals/workspaces
+
+provenance:
+  outputDir: .harness/provenance
+  buildType: https://github.com/JamesMorales04/agentic-engineering-harness/v0.4

package/templates/toolchain.yaml

@@ -0,0 +1,127 @@
+version: 1
+
+manager:
+  provider: mise
+  generatedConfig: .config/mise/conf.d/aeh.toml
+  lockFile: .harness/toolchain.lock.json
+  stateFile: .harness/toolchain.state.json
+  minimumVersion: "2026.7.0"
+
+strategy:
+  validators: local # local | prefer-container
+  containerEngine: podman
+
+profiles:
+  core:
+    tools: [git, node]
+  agents:
+    extends: [core]
+    tools: [codex, opencode, paseo]
+  intelligence:
+    extends: [core]
+    tools: [uv, graphify]
+  validation:
+    extends: [core]
+    tools: [opa, opengrep, trivy]
+  full:
+    extends: [agents, intelligence, validation]
+    tools: [podman, dotnet, bun]
+
+tools:
+  git:
+    kind: system
+    command: git
+    required: true
+    activateWhen: [always]
+
+  node:
+    kind: mise
+    command: node
+    source: node
+    version: "22"
+    required: true
+    activateWhen: [always, project:node, project:pnpm, project:yarn]
+
+  bun:
+    kind: mise
+    command: bun
+    source: bun
+    version: latest
+    activateWhen: [project:bun]
+
+  dotnet:
+    kind: mise
+    command: dotnet
+    source: dotnet
+    version: latest
+    activateWhen: [project:dotnet]
+
+  codex:
+    kind: mise
+    command: codex
+    source: "npm:@openai/codex"
+    version: latest
+    activateWhen: [runtime:codex]
+
+  opencode:
+    kind: mise
+    command: opencode
+    source: "aqua:anomalyco/opencode"
+    version: latest
+    activateWhen: [runtime:opencode]
+
+  paseo:
+    kind: mise
+    command: paseo
+    source: "npm:@getpaseo/cli"
+    version: latest
+    activateWhen: [orchestration:paseo, delivery:paseo]
+
+  uv:
+    kind: mise
+    command: uv
+    source: uv
+    version: latest
+    activateWhen: [code-intelligence:graphify, project:python]
+
+  graphify:
+    kind: mise
+    command: graphify
+    source: "pipx:graphifyy"
+    version: latest
+    dependsOn: [uv]
+    activateWhen: [code-intelligence:graphify]
+
+  opa:
+    kind: mise
+    command: opa
+    source: "aqua:open-policy-agent/opa"
+    version: latest
+    activateWhen: [validation:opa]
+    container:
+      image: docker.io/openpolicyagent/opa:latest-static
+
+  opengrep:
+    kind: mise
+    command: opengrep
+    source: "aqua:opengrep/opengrep"
+    version: latest
+    activateWhen: [security-tool:opengrep, validator:opengrep]
+
+  trivy:
+    kind: mise
+    command: trivy
+    source: "aqua:aquasecurity/trivy"
+    version: latest
+    activateWhen: [security-tool:trivy, validator:trivy]
+    container:
+      image: ghcr.io/aquasecurity/trivy:latest
+
+  podman:
+    kind: system
+    command: podman
+    activateWhen: [orchestration:podman, sandbox:podman]
+
+projectDependencies:
+  autoDetect: true
+  commands: []