omcustomcodex-adaptive-harness

name	omcustomcodex:adaptive-harness
description	Auto-detect project context and optimize harness — deactivate unused agents/skills, suggest missing experts, generate project profile
scope	harness
version	1.0.0
user-invocable	true
argument-hint	[--optimize|--scan|--learn|--export|--import|--dry-run] [target-dir]
effort	high

Adaptive Harness Self-Customization Skill

Automatically detects project context and optimizes the oh-my-customcodex harness (agents, skills, rules) to fit the project. Generates a persistent project profile that drives agent activation decisions and records learned patterns over time.

Usage

/omcustomcodex:adaptive-harness              # Full scan + optimize
/omcustomcodex:adaptive-harness --scan       # Scan only (generate/update project profile)
/omcustomcodex:adaptive-harness --optimize   # Deactivate unused, suggest missing
/omcustomcodex:adaptive-harness --learn      # Analyze failure patterns, update profile
/omcustomcodex:adaptive-harness --export     # Export profile as portable bundle
/omcustomcodex:adaptive-harness --import <path>  # Import profile from another project
/omcustomcodex:adaptive-harness --dry-run    # Show what would change without modifying

Default (no flag): runs --scan then --optimize in sequence.

Project Profile Format

The skill generates and maintains .codex/project-profile.yaml. Manual edits to this file are preserved across runs — the skill merges new detections with existing content rather than overwriting.

# Auto-generated by adaptive-harness. Manual edits will be preserved.
project:
  name: detected-project-name
  scanned_at: "2026-04-12T10:00:00Z"

tech_stack:
  languages: [python, typescript]
  frameworks: [fastapi, next.js]
  databases: [postgres, redis]
  infra: [docker, aws]

detection_evidence:
  - indicator: "requirements.txt found"
    confidence: high
    suggests: [lang-python-expert, be-fastapi-expert]
  - indicator: "package.json with next dependency"
    confidence: high
    suggests: [lang-typescript-expert, fe-vercel-agent]

active_agents:
  - lang-python-expert
  - be-fastapi-expert
  - lang-typescript-expert
  - fe-vercel-agent
  - db-postgres-expert
  - db-redis-expert
  - infra-docker-expert
  - infra-aws-expert
  # manager agents always active
  - mgr-creator
  - mgr-gitnerd
  - mgr-sauron
  - mgr-supplier
  - mgr-updater
  - mgr-claude-code-bible

inactive_agents:
  - lang-golang-expert    # no Go files detected
  - lang-rust-expert      # no Rust files detected

usage_stats:
  most_used_agents: []     # populated by --learn
  failure_patterns: []     # populated by --learn

overrides:
  rules: {}                # e.g., R009: { max_parallel: 5 }

last_optimized: "2026-04-12T10:00:00Z"

Workflow: --scan

Scans the TARGET project (the project using oh-my-customcodex, not the harness itself) and generates or updates the project profile. Uses Read, Glob, and Grep only — no side effects.

Step 1: Detect Tech Stack

Check for language manifest files and framework indicators:

Indicator Files	Tech	Suggests Agents
go.mod, *.go	Go	lang-golang-expert, be-go-backend-expert
Cargo.toml, *.rs	Rust	lang-rust-expert
requirements.txt, pyproject.toml, *.py	Python	lang-python-expert
fastapi in deps/imports	FastAPI	be-fastapi-expert
django in deps/imports	Django	be-django-expert
package.json, tsconfig.json, *.ts, *.tsx	TypeScript	lang-typescript-expert
next in package.json deps	Next.js	fe-vercel-agent
vue in package.json deps	Vue.js	fe-vuejs-agent
svelte.config.*, *.svelte	Svelte	fe-svelte-agent
pubspec.yaml, *.dart	Flutter	fe-flutter-agent
*.kt, build.gradle.kts	Kotlin	lang-kotlin-expert
*.java, pom.xml	Java	lang-java21-expert
spring-boot in deps	Spring Boot	be-springboot-expert
express in package.json deps	Express	be-express-expert
@nestjs in package.json deps	NestJS	be-nestjs-expert
Dockerfile, docker-compose.*	Docker	infra-docker-expert
cdk.json, template.yaml, .aws/	AWS	infra-aws-expert
terraform/, *.tf	Terraform	infra-aws-expert
.github/workflows/	CI/CD	mgr-gitnerd
*.sql, alembic/, pg in deps	PostgreSQL	db-postgres-expert
redis in deps/config	Redis	db-redis-expert
supabase in deps/config	Supabase	db-supabase-expert
prisma/, drizzle/	ORM	db-postgres-expert
dags/*.py, airflow in deps	Airflow	de-airflow-expert
dbt_project.yml	dbt	de-dbt-expert
kafka in deps/config	Kafka	de-kafka-expert
spark in deps/config	Spark	de-spark-expert
snowflake in deps/config	Snowflake	de-snowflake-expert

Step 2: Build Detection Evidence

For each indicator found, record:

• indicator: human-readable description of what was found
• confidence: high (direct manifest file) | medium (dependency reference) | low (indirect signal)
• suggests: list of agent names this indicator implies

Step 3: Write Project Profile

Delegate write to a subagent (R010). Merge with existing profile if present — preserve overrides, usage_stats, and any manual entries.

Output format:

[adaptive-harness --scan] Target: /path/to/project

Tech Stack Detected:
  - Python     (requirements.txt + pyproject.toml found)      [confidence: high]
  - FastAPI    ("fastapi" in requirements.txt)                [confidence: high]
  - TypeScript (tsconfig.json found)                          [confidence: high]
  - Next.js    ("next" in package.json deps)                  [confidence: high]
  - Docker     (Dockerfile found)                             [confidence: high]
  - PostgreSQL ("psycopg2" in requirements.txt)               [confidence: medium]
  - Redis      ("redis" in requirements.txt)                  [confidence: medium]
  - AWS        (cdk.json found)                               [confidence: high]

Active agents identified: 8
Profile written: .codex/project-profile.yaml

Workflow: --optimize

Reads the project profile and adjusts which agent files are active.

Step 1: Load Profile

Read .codex/project-profile.yaml. If the profile does not exist, run --scan first.

Step 2: Identify Inactive Agents

Compare all agent files in .codex/agents/*.md against active_agents list from the profile. Agents not in the active list (and not in the always-active set below) are candidates for deactivation.

Always-Active Agents (never deactivate)

mgr-creator, mgr-gitnerd, mgr-sauron, mgr-supplier, mgr-updater, mgr-claude-code-bible
sys-memory-keeper, sys-naggy
arch-documenter, arch-speckit-agent

Step 3: Move Inactive Agents

Delegate to subagent (R010):

• Create .codex/agents/.inactive/ directory if it does not exist
• Move inactive agent .md files to .codex/agents/.inactive/
• Update inactive_agents list in project profile

Step 4: Detect Gaps

Check active_agents list against files actually present in .codex/agents/. If an active agent file is missing, flag it as a gap and suggest mgr-creator to fill it.

Step 5: Log Adaptations

Append a record to .codex/outputs/harness-adaptations/YYYY-MM-DD.md:

Compatibility artifact protocol

Sensitive-path compatibility note: when delegated work touches .claude/outputs/, .claude/**, or templates/.claude/**, keep .codex/** artifacts on the normal file-write path. On Claude Code v2.1.121+ with bypassPermissions, direct compatibility writes are allowed for .claude/skills/, .claude/agents/, and .claude/commands/; on v2.1.126+ broader protected paths are covered. Use /tmp/<skill>-<timestamp>.md only as a legacy fallback when the runtime is older or still prompts.

## Optimization Run — 2026-04-12T10:00:00Z

Deactivated (moved to .inactive/):
  - lang-golang-expert
  - lang-rust-expert
  - de-airflow-expert

Gaps detected (agents needed but missing):
  - (none)

Profile: .codex/project-profile.yaml

Restore

Run --optimize --restore to move all files from .codex/agents/.inactive/ back to .codex/agents/. This reverses the last optimization.

Output format:

[adaptive-harness --optimize]

Always-active agents: 10 (protected)
Active per profile:   8
Candidates for deactivation: 29

Deactivated:
  - lang-golang-expert      → .codex/agents/.inactive/
  - lang-rust-expert        → .codex/agents/.inactive/
  - de-airflow-expert       → .codex/agents/.inactive/
  ... (26 more)

Gaps detected: 0

Log: .codex/outputs/harness-adaptations/2026-04-12.md
Summary: 29 deactivated, 18 active, 0 gaps

--dry-run mode outputs [would deactivate] / [would restore] without moving any files.

Workflow: --learn

Analyzes session history and eval-core data to populate usage_stats and failure_patterns in the project profile.

Step 1: Collect Data Sources

• .codex/outputs/ — session artifacts and eval results
• .codex/agent-memory-local/ — managed local agent memory files with usage patterns
• Any harness eval output from $harness-eval (Codex / OMX; /harness-eval on Claude Code)

Step 2: Extract Patterns

Most-used agents:   Count agent invocations across outputs
Failure patterns:   Identify agents that frequently retried or errored
Unused agents:      Active agents with zero invocations in recent N sessions
Passing evals:      Preserve newly passing cases as regression candidates
Loop signals:       Identify repeated errors, same-file edit loops, repeated tool-target calls

Step 3: Update Profile

Merge findings into usage_stats and failure_patterns sections of the project profile. Preserve existing entries; append new ones.

Step 4: Generate Suggestions

Based on failure patterns, suggest:

• Rule overrides (e.g., increase max_parallel if timeout patterns detected)
• Agent replacements (e.g., suggest escalation to frontier/high model for frequently failing tasks)
• Additional skills that may reduce failure rate
• Missing middleware guidance when loop signals recur
• Eval pruning when a case is saturated, obsolete, or ambiguous

Trace Analyzer Pattern

When --learn sees repeated failures, classify each pattern before suggesting changes:

Pattern	Suggested action
Same error repeats	Recommend loop-detection-middleware and systematic-debugging
Missing local context	Add project-profile evidence or guide references to spawned prompts
Completion claim without proof	Strengthen R020 checklist or skill output contract
Passing eval newly appears	Add to harness regression cache

Do not auto-edit rules from one trace. Require repeated evidence or an explicit user request before promoting a suggestion into a rule or skill change.

Output format:

[adaptive-harness --learn]

Sessions analyzed: 12
Agent invocations found: 847

Most-used agents (top 5):
  1. lang-python-expert    (312 invocations)
  2. be-fastapi-expert     (189 invocations)
  3. mgr-gitnerd           (97 invocations)
  4. db-postgres-expert    (84 invocations)
  5. lang-typescript-expert (71 invocations)

Failure patterns:
  - db-postgres-expert: 3 retries in session 2026-04-10 (timeout pattern)
  
Suggestions:
  - db-postgres-expert: consider effort: high for complex query generation
  - de-kafka-expert: 0 invocations — candidate for deactivation

Profile updated: .codex/project-profile.yaml

Workflow: --export / --import

Export

Bundles the project profile and active agent list for sharing with another project or team member.

Output: .codex/outputs/harness-bundle-YYYY-MM-DD.json

{
  "version": "1.0.0",
  "exported_at": "2026-04-12T10:00:00Z",
  "source_project": "detected-project-name",
  "profile": { ... },
  "active_agent_names": [ ... ]
}

Import

/omcustomcodex:adaptive-harness --import .codex/outputs/harness-bundle-2026-04-12.json

Reads the bundle and applies the active_agents list to the current project by running --optimize with the imported profile. Does not overwrite usage_stats or failure_patterns from the current project.

Execution Rules

• --scan uses Read, Glob, Grep only — no writes, safe to run anytime
• All file writes (profile, logs, agent moves) are delegated to subagents (R010)
• --dry-run suppresses all writes; outputs [would ...] for every action
• Profile changes are always logged to .codex/outputs/harness-adaptations/ for auditability
• When profile already exists, the skill merges new detections rather than overwriting
• Parallel Glob/Grep calls are used during --scan for performance (R009)

Integration

Component	Interaction
/omcustomcodex:analysis	Calls adaptive-harness --scan after initial tech stack detection to persist the profile
SessionStart hook	Lightweight profile existence check only — no full scan at startup
mgr-creator	Invoked when gaps are detected during --optimize to create missing agent files
R016 (Continuous Improvement)	Failure patterns from --learn may trigger rule updates
eval-core	Primary data source for --learn invocation and usage pattern extraction
mgr-sauron	Run after --optimize to verify structural integrity (R017)
loop-detection-middleware	Consumes repeated failure/edit/tool patterns found by --learn
harness-eval	Supplies optimization and holdout eval cases for hill-climbing

Notes

• Always run --dry-run first on a new project to preview deactivation scope
• --optimize --restore is the safe exit if deactivation causes unexpected routing failures
• The .inactive/ directory is git-tracked so deactivation decisions are visible in history
• Manager and system agents are unconditionally protected from deactivation
• Target directory defaults to the project root of the current GPT Codex + OMX session, not the child-package source directory