Adaptive Harness

---
name: omcustom: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-customcode 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

```
/omcustom:adaptive-harness              # Full scan + optimize
/omcustom:adaptive-harness --scan       # Scan only (generate/update project profile)
/omcustom:adaptive-harness --optimize   # Deactivate unused, suggest missing
/omcustom:adaptive-harness --learn      # Analyze failure patterns, update profile
/omcustom:adaptive-harness --export     # Export profile as portable bundle
/omcustom:adaptive-harness --import <path>  # Import profile from another project
/omcustom: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 `.claude/project-profile.yaml`. Manual edits to this file are preserved across runs — the skill merges new detections with existing content rather than overwriting.

```yaml
# 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-customcode, 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-java-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: .claude/project-profile.yaml
```

## Workflow: --optimize

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

### Step 1: Load Profile

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

### Step 2: Identify Inactive Agents

Compare all agent files in `.claude/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 `.claude/agents/.inactive/` directory if it does not exist
- Move inactive agent `.md` files to `.claude/agents/.inactive/`
- Update `inactive_agents` list in project profile

### Step 4: Detect Gaps

Check `active_agents` list against files actually present in `.claude/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 `.claude/outputs/harness-adaptations/YYYY-MM-DD.md`:

### Tool: Writing artifacts under .claude/outputs/

Under `mode: "bypassPermissions"`, direct Write/Edit/Bash on `.claude/**` paths is permitted (CC v2.1.121+, #1101) — no `/tmp/*.sh` wrapping is needed.

To write adaptive-harness results under `.claude/outputs/`:

1. Write the artifact body directly to `.claude/outputs/harness-adaptations/$(date +%Y-%m-%d).md` with the Write tool (every Agent tool call includes `mode: "bypassPermissions"`, R010)
2. Read-only Bash on `.claude/outputs/` (e.g., `cat`, `head`, `wc`) is allowed for verification

Reference: R006/R010 sensitive-path handling (CC v2.1.121+), #1101.


```markdown
## 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: .claude/project-profile.yaml
```

### Restore

Run `--optimize --restore` to move all files from `.claude/agents/.inactive/` back to `.claude/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      → .claude/agents/.inactive/
  - lang-rust-expert        → .claude/agents/.inactive/
  - de-airflow-expert       → .claude/agents/.inactive/
  ... (26 more)

Gaps detected: 0

Log: .claude/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

- `.claude/outputs/` — session artifacts and eval results
- `.claude/agent-memory/` — agent memory files with usage patterns
- Any harness eval output from `/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: .claude/project-profile.yaml
```

## Workflow: --export / --import

### Export

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

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

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

### Import

```
/omcustom:adaptive-harness --import .claude/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 `.claude/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 |
|-----------|-------------|
| `/omcustom: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 where Claude Code is running, not the omcustom harness directory

## Related Guide

- `guides/harness-engineering/` — 하네스 엔지니어링 통합 가이드 (Project Profile Learning 관점에서 adaptive-harness 위치)