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:

## 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/ — agent memory files with usage patterns
• Any harness eval output from /omcustomcodex:harness-eval

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

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 opus model for frequently failing tasks)
• Additional skills that may reduce failure rate

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)

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