| 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.
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
- mgr-creator
- mgr-gitnerd
- mgr-sauron
- mgr-supplier
- mgr-updater
- mgr-claude-code-bible
inactive_agents:
- lang-golang-expert
- lang-rust-expert
usage_stats:
most_used_agents: []
failure_patterns: []
overrides:
rules: {}
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 foundconfidence: 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
