# ADR-001: Adopt Proven Patterns from agent-skills into Harness Engineering

**Date:** 2026-04-07
**Status:** Accepted
**Deciders:** cwarner (harness engineering lead)

## Context

A comparative architectural analysis of Addy Osmani's `agent-skills` (https://github.com/addyosmani/agent-skills) — a collection of 19 production-grade engineering skills for AI coding agents — revealed four patterns that harness engineering should adopt to close identified gaps.

Harness engineering significantly exceeds agent-skills in architectural sophistication: state management, skill composition, verification depth (EXISTS/SUBSTANTIVE/WIRED), cognitive modes, fan-out pipelines, rigor levels, and mechanical enforcement are all substantially more advanced. However, agent-skills demonstrates four patterns where it leads:

1. **Anti-rationalization tables** — mandatory per-skill, table format, systematically countering agent excuse-making
2. **MCP-independent operation** — pure Markdown skills that work on 6+ platforms without runtime dependencies
3. **Explicit context budgets** — 5-level hierarchy with <2,000 line target per task
4. **Protected code regions** — block-level annotations preventing agent modification of critical code

The analysis is documented in:

- `docs/architecture/agent-skills-comparative/discovery.md`
- `docs/architecture/agent-skills-comparative/analysis.md`
- `docs/architecture/agent-skills-comparative/proposal.md`

## Decision

Adopt the four patterns in a phased approach, prioritized by impact-to-effort ratio:

### Phase 1: Anti-Rationalization Tables (Immediate)

Make `## Common Rationalizations` a **required section** in the harness skill format specification (`harness-skill-authoring`). Standardize the format as:

```markdown
## Common Rationalizations

| Rationalization                       | Reality                        |
| ------------------------------------- | ------------------------------ |
| "Excuse agents use to skip this step" | Counter-argument with evidence |
```

Requirements:

- Minimum 3 entries per skill, maximum 8
- Each entry must be specific to the skill's domain (no generic filler)
- Table format (not prose) — easier for agents to pattern-match
- Skill validation should check for section presence

Backfill across all 77 user-facing skills. Internal skills (6) are exempt.

### Phase 2: Protected Code Regions (Near-term)

Introduce a `harness-ignore` annotation system for code-modifying skills:

```
/* harness-ignore-start: <reason> */
// protected code
/* harness-ignore-end */
```

Applicable to: `harness-refactoring`, `cleanup-dead-code`, `enforce-architecture`, `code-simplification`, and any future code-modifying skill. Implementation approach TBD — may use agent-skills' content-hashing hook pattern or integrate into MCP tool layer.

### Phase 3: Context Budget System (When skill count exceeds 100)

Add `context_budget` field to skill.yaml:

```yaml
context_budget:
  max_lines: 2000
  loading: progressive # or eager
```

Adopt the 5-level context hierarchy from agent-skills' `context-engineering` skill:

1. Rules files (always loaded)
2. Spec / architecture docs (per feature)
3. Relevant source files (per task)
4. Error output / test results (per iteration)
5. Conversation history (accumulates)

### Phase 4: Degraded Mode (If multi-platform becomes strategic)

Define `## Degraded Mode` section in SKILL.md spec documenting fallback behavior for each MCP call. Add `degraded_mode: true|false` to skill.yaml. Only pursue if expanding to Cursor/Gemini CLI/Windsurf becomes a priority.

## Alternatives Considered

### Adopt nothing — harness already exceeds agent-skills

Rejected because the four identified gaps are real and measurable:

- Without anti-rationalization, agents skip steps with plausible excuses
- Without protected regions, critical code is vulnerable during refactoring
- Without context budgets, quality will degrade as skill count grows
- Without degraded mode, harness skills are inert outside MCP environments

The fact that harness exceeds agent-skills overall doesn't mean there's nothing to learn.

### Adopt everything simultaneously

Rejected because Phase 4 (degraded mode) has high effort and medium risk (two code paths per skill), and Phase 3 (context budgets) is preventive — the problem isn't urgent yet. Phased adoption matches the actual urgency.

### Fork agent-skills and integrate wholesale

Rejected because the projects have fundamentally different architectures. agent-skills is stateless Markdown; harness is a runtime system with MCP, state management, and orchestration. The value is in the patterns, not the code.

## Consequences

### Positive

- Anti-rationalization tables directly improve agent compliance by preempting the most common failure mode
- Protected regions prevent accidental modification of performance-critical, compliance-required, or legally-sensitive code
- Context budgets will prevent quality degradation as the skill library scales
- The phased approach minimizes disruption to active development

### Negative

- Backfilling rationalizations across 77 skills requires domain expertise per skill — medium effort, mitigated by doing it incrementally as skills are touched
- Protected regions add a concept that skill authors and users must understand — mitigated by clear documentation and a simple annotation format
- Context budgets require runtime changes to skill loading — mitigated by deferring until the problem is measurable

### Neutral

- This analysis validates that harness engineering's core architecture (state, composition, verification, enforcement) is more advanced than the leading open-source alternative
- The gap areas (portability, anti-rationalization, context management, code protection) are all addressable without architectural changes

## Action Items

- [ ] Update `harness-skill-authoring` SKILL.md to require `## Common Rationalizations` section — owner: cwarner
- [ ] Add anti-rationalization table validation to skill authoring tooling — owner: cwarner
- [ ] Backfill rationalizations for top 20 most-used skills (tdd, execution, planning, debugging, code-review, verification, autopilot, refactoring, brainstorming, security-review, architecture-advisor, release-readiness, perf, observability, design, impact-analysis, parallel-agents, soundness-review, pre-commit-review, skill-authoring) — owner: cwarner
- [ ] Design `harness-ignore` annotation spec and prototype hook — owner: cwarner
- [ ] Monitor skill count; trigger Phase 3 when approaching 100 skills — owner: cwarner
- [ ] Evaluate multi-platform demand quarterly; trigger Phase 4 if strategic — owner: cwarner

## Appendix: What Harness Already Exceeds

For completeness, areas where harness engineering is definitively ahead:

| Capability             | Harness                                         | agent-skills           |
| ---------------------- | ----------------------------------------------- | ---------------------- |
| State management       | Two-tier + handoff + learnings + failure memory | Stateless              |
| Skill routing          | Signal-weighted auto-recommendation             | Manual flowchart       |
| Cognitive modes        | 8 distinct reasoning postures                   | 3 domain personas      |
| Parallel dispatch      | Fan-out with model tier selection               | Sequential only        |
| Verification           | EXISTS → SUBSTANTIVE → WIRED                    | Checklist              |
| Rigor adaptation       | fast / standard / thorough                      | One speed              |
| Pipeline composition   | Context-aware scope adaptation                  | Always full process    |
| Mechanical enforcement | harness.config.json + validate                  | Trust-based            |
| Dependency graph       | `depends_on` + `addresses` + `stack_signals`    | None                   |
| Orchestration          | Autopilot state machine with retry budgets      | Slash command dispatch |
