# Mcp Harness Repo Maintainer

> Maintains repo-local action contracts and harness repositories where product CLI and MCP adapters stay thin over core libraries. Use when adopting or improving steward.yaml actions, capability-level adoption evidence, cold-start proof loops, probes, benchmarks, CLI/MCP/core parity, adapter refactors, packages/core boundaries, or sibling harness layout; use repo-quality-system-lifecycle first for…

- **Type:** Skill
- **Install:** `agentstack add skill-arenukvern-skill-steward-mcp-harness-repo-maintainer`
- **Verified:** Pending review
- **Seller:** [Arenukvern](https://agentstack.voostack.com/s/arenukvern)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Arenukvern](https://github.com/Arenukvern)
- **Source:** https://github.com/Arenukvern/skill_steward/tree/main/skills/mcp-harness-repo-maintainer
- **Website:** https://docs.page/arenukvern/skill_steward

## Install

```sh
agentstack add skill-arenukvern-skill-steward-mcp-harness-repo-maintainer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Action Contract & Harness Repo Maintainer

Build and maintain repo-local action contracts and harnesses where agents execute and humans steer. The historical `mcp-` name remains because many adopters arrive through MCP work, but this skill is not MCP-only. For general app, library, tool, plugin, or meta-repo stewardship baselines, use `repo-quality-system-lifecycle` first; use this skill only when typed actions, probes, benchmarks, or CLI/MCP parity are in scope.

## Core principle (action-contract and harness repos)

**MCP and CLI are thin interfaces—APIs for agents and CI.** **Core** contains the real logic, schemas, and registries. Adapters parse wire format (argv, MCP JSON-RPC); they delegate immediately.

```text
Agents / CI  →  CLI ──┐
                      ├──► Core (logic, contracts, tests)
Agents / chat →  MCP ──┘
```

Full layering: [core-and-interfaces.md](references/core-and-interfaces.md). **Parity:** every MCP tool must call the same core entrypoint as its CLI twin.

**Progressive Automation (Agent-Driven Workflows):** Harnesses should let agents turn repeated friction into reviewed, durable capability. If an agent discovers a complex fix or command sequence, it should capture an unknown case or typed action candidate with owner, risk class, inputs, outputs, effects, provenance, and verification. Permanent `steward.yaml` changes must go through reviewable diffs and validation; do not teach agents to save raw bash permanently from MCP.

**Goal-first adoption:** The original user goal remains the acceptance check. Tool repair, install work, wrappers, action candidates, evals, and refactors are detours unless they directly solve that goal or preserve a reusable lesson. After two failed repair/setup attempts, stop tool restoration, use a type-native command or portable fallback when possible, record the friction, return to the task, and do not promote from that same detour.

**Product experiment ownership:** When the goal is visual quality, shader
behavior, loader correctness, renderer throughput, or performance, the product
repo owns the high-throughput experiment runner and oracle. Steward can validate
or summarize an `experiment-campaign-summary/v1` artifact after the product loop
has produced captures/metrics. Do not promote a Steward action, benchmark, or
MCP tool as product acceleration unless the product campaign names what surface
changed or was directly proven.

**Skeptic before promotion:** A missing capability is a harness gap only after smaller layers fail. First ask whether the fix belongs in a native command, error message, FAQ, docs map, public API, schema/codegen, or deletion/collapse. Promote a Steward action, MCP tool, or benchmark only when it improves a real proof path and carries a falsifier.

**Evolutionary simplicity for interfaces:** Split core entrypoints when ownership, proof, effects, cadence, or audience diverge. Compress CLI/MCP/help surfaces when one user or CI intent remains, but preserve structured child outcomes so wrappers do not flatten proof, effects, or non-claims.

## Core Beliefs & Culture

1. **Missing capability → possible harness gap** — When an agent fails, ask what is not *legible* or *enforceable*, then choose the smallest useful layer: native command, error message, docs/FAQ, schema, linter, skill, action, or deletion. For interface shape, apply evolutionary simplicity: split internals when proof, effects, or owners diverge; compress CLI/MCP/help wrappers when user intent remains one thing and child outcomes stay structured.
2. **Ambiguous design → decision checkpoint** — Before coding a fork, use `repository-governance-lifecycle`; record an accepted ADR after agreement.
3. **Mechanical enforcement** — Linters, validate commands, schema validation at boundaries—error messages teach the agent how to fix. Use structured parsing (YAML, JSON, or AST).
4. **Progressive disclosure** — Router → ADR / DESIGN_FAQ (why) → DX_FAQ (how) → skills (procedures) → code (behavior SSOT).

## Harness Layers to Build

```text
Human intent (prompt, plan, review)
        │
        ▼
┌───────────────────┐
│ Skills + AGENTS   │  Map & procedures (when to do what)
└─────────┬─────────┘
          ▼
┌───────────────────┐
│ CLI               │  doctor, exec, validate, contracts (deterministic)
└─────────┬─────────┘
          ▼
┌───────────────────┐
│ MCP server        │  fmt_* / tools for chat agents (same schemas)
└─────────┬─────────┘
          ▼
┌───────────────────┐
│ App / runtime     │  Legible UI, logs, metrics per worktree (optional)
└───────────────────┘
```

## Mixture of experts (pick one lead)

Route by **primary artifact** when the repo is harness or action-contract shaped. For the broader app/library/tool taxonomy, use `repo-quality-system-lifecycle`.

| Expert lens | Repo examples | Owns | Does not own |
|-------------|---------------|------|----------------|
| **Plugin/MCP** | `` | `plugin/mcp.json`, tool prefixing, init utility | Harness scripts, visual comparisons |
| **Library** | `` | Platform packages/modules, adapters | Shippable plugin tree, dogfood apps |
| **Harness/CLI** | `` | Harness engine, app registry, fixture lint | MCP server binary, marketplace manifests |
| **D — Visual sidecar** | `` | Profile configs, compare/deconstruct CLI | VM/MCP, dynamic registry |
| **Meta/governance** | `skill_steward` | `skills/`, `plugins/`, validator CLI, docs | Product MCP, domain tools |
| **F — Security/Ops** | all remotes | OAuth gateway, token brokering | Feature code |

## Universal maintainer spine (every archetype)

1. **Charter & Archetype** — `docs/NORTH_STAR.mdx` (or root pointer); `AGENTS.md` = map only.
2. **Behavior SSOT** — code + schemas; docs hold **why** and **how**.
3. **Thin adapters, thick core** — implement once in core; CLI + MCP are wrappers.
4. **Mechanical gates** — contract checks / validate commands / unit tests before merge.
5. **Plan hygiene** — extract to ADR/FAQ/code/skill then **delete** plan files.
6. **Version honesty** — single `VERSION` or release-please manifest.
7. **Distribution & Universal Translation** — Document per channel (`npx skills`, git marketplace). Avoid proprietary ecosystem lock-in. Ensure CLI tools natively compile governance to upstream IDE formats (e.g., `steward bundle` generating `.cursor/rules` and `.clinerules`).

## Workflow: Add Agent-First Capability

1. **Specify intent** — One sentence outcome + acceptance check.
2. **Run the Skeptic/generational check** — Is this repeated? Can a lower layer solve it? Would deleting or collapsing code reduce maintenance? What falsifier prevents tool-loop drift?
3. **Choose surface**
   - CI / script / gate → **CLI** first
   - Conversational debug loop → **MCP tool** (reuse CLI core)
   - One-off guidance → **skill** in `skills/`
   - Event enforcement → **plugin** hook
4. **Make legible** — JSON schema, `--json` output, stable error codes, action effects, limits, and redaction policy; document in DX_FAQ.
5. **Document why** — ADR or DESIGN_FAQ Q&A.
6. **Wire map** — `AGENTS.md` / `docs_map` row.
7. **Validate** — `pnpm run validate` or project contract tests.
8. **Human collab** — PR describes harness change.

## Cold-start local harness proof loop

Use this loop before claiming a repo is harness-ready or diagnosing repo-specific symptoms. A fresh repo has no meaningful symptom catalog yet; first prove that agents can discover and safely execute declared contracts.

### Portable Steward invocation

Use `steward ` only after installing the released CLI or activating a local clone as a global command. Do not teach absolute local paths, private SDK paths, or sibling checkout paths as adoption instructions.

Preferred order:

1. Released adopter or CI path: `curl -fsSL https://raw.githubusercontent.com/Arenukvern/skill_steward/main/install.sh | bash`, then `steward `.
2. Dart maintainer path from the Skill Steward clone: `cd packages/steward_cli && dart run :steward `.
3. Local clone global activation: `dart pub global activate --source path packages/steward_cli`, then `steward `.

Raw `dart --packages=... bin/steward.dart` commands are local provenance only. If evidence needs them, pair them with a portable command block and label the machine-specific path as non-copyable.

1. **Declare a small contract** — Add or update `steward.yaml` with one quick-safe action. The first action should inspect state, not mutate it.
2. **Expose the action** — Put the action under `probes.quick.actions` only when it passes quick policy: `default_policy: auto`, no confirmation, no shell, no network/secrets/destructive effects, no repo mutation, no `fs_write`.
3. **Add a scenario manifest** — Put committed scenarios under `steward/scenarios/*.yaml`; use a precise name such as `contract-status-smoke` until the scenario proves navigation or diagnosis.
4. **Run the proof loop**:

   ```bash
   steward doctor --json
   steward schema check-outputs --json
   steward schema drift --json
   steward actions list --json
   steward action inspect  --json
   steward probe --profile quick --json
   steward benchmark --scenario  --strict --output .steward/benchmark-summaries/.json --json
   ```

5. **Interpret honestly** — `doctor`/`actions list` prove discovery, `schema check-outputs` catches machine-readable output drift, `schema drift` catches generated contract/schema drift, `action inspect` proves the executable boundary, `probe` proves the safe first observation, and `benchmark` proves durable execution only when it returns `result: "pass"`. `durability_blocked` is truthful blocked evidence when strict benchmark inputs are modified or untracked; it is not H2 proof.
   - If fresh console JSON is blocked, pipe it to `steward blocked explain --stdin --json` to choose config repair, unknown-case capture, or same-benchmark rerun. Use `steward blocked explain --input  --json` only for an existing persisted summary.
   - Treat persisted benchmark summaries as machine evidence for the commit and inputs they name. Treat console-only JSON as session evidence unless rerun with `--output`. A current ledger or rerun route decides whether historical summaries are still current proof.
   - Treat benchmark passes as local or repo-owned proof for the named inputs first. They become public reproducibility proof only when the source is fetchable, the subject commit is a resolved SHA, the command is portable, and the retained artifact has a CI artifact name or hash.
   - Address invalid `steward.yaml`, dirty declared inputs, schema/output drift, or native launch failures through the owning surface before adding a new action, benchmark scenario, PDSA note, or evidence packet from the same detour.
6. **Protect local state** — Strict benchmark inputs must be tracked and clean before execution: `steward.yaml`, file-backed scenario manifests, and any declared action inputs the benchmark reads. Local run outputs such as `.steward/benchmark-summaries/*.json`, observations, unknown cases, and action candidates stay local unless a review intentionally promotes a redacted artifact. If the repo has temporary dirty files that must remain in place, write a do-not-touch exception and keep those files out of action inputs. Protected local state is not a benchmark blocker unless it is declared as a contract or scenario input.
7. **Grow from evidence** — If the probe exposes an unknown failure, capture an unknown case first. Promote a typed action candidate only after owner, effects, limits, redaction, validation command, and benchmark evidence exist. Do not promote diagnostics from the same run that discovered them.
   - When evidence is promoted into docs, use the `status`, `evidence_type`, `claim_tested`, `proof_level`, `limitations`, `non_claims`, `next_disposition`, and `current_status_pointer` envelope from [docs/core/evidence-artifacts.mdx](../../docs/core/evidence-artifacts.mdx). Do not preserve raw logs, secrets, or private relational memory as evidence.

### Native deterministic gate promotion

Prefer useful native gates over Steward-only scorekeeping. A repo may promote an existing deterministic script, test, or validation command into a Steward action when it has:

- positive proof on the current state
- a falsifier test or fixture that catches the regression class
- owner, risk class, effects, limits, and redaction policy
- a strict benchmark or eval that makes the capability discoverable
- a held-out benchmark or future-agent repeat that proves transfer
- explicit non-claims for product runtime correctness and broad H5 maturity

For visual/performance campaign work, a native gate must be able to run variants
without rebuild-per-hypothesis when the product stack allows it, keep warm
browser/server state for runtime sweeps, and emit the winning evidence rather
than raw screenshot piles. If two harness loops do not move the product oracle or
metric, stop harness work and return to product-native experimentation.

This is the path for turning evidence into a tool improvement packet. If the result cannot teach a later agent how to maintain or improve the repo's real tool surface, keep it as an observation or unknown case instead of promoting it.

### Adoption run classification

Use the adoption-run/v2 evidence shape before making S/H claims. Record:

- `user_goal`: original prompt, requested outcome, acceptance check, status, and evidence.
- `capability`: id, class, scope, user value, and native owner.
- `direct_problem_path`: declared surfaces and native gates used before raw shell exploration.
- `tool_detour`: reason, attempts, artifacts, stop rule, and return-to-goal step.
- `generational_architecture_check`: repeated pattern, smaller layer considered, deletion/collapse option, selected pattern layer, maintenance delta, and promotion guard.
- `outcome`: continue, refactor, stop, abandon, or promote.
- `hot_path_claim`: problem class, created surface, falsifier, positive proof, observed effect, held-out or future task, and non-claims.

Do not use "fully adopted repo" language for one polished proof. Say "capability-level H5" or "capability-level S5/H5" and name the capability. Repo maturity remains a separate, broader claim.

## Adoption maturity ladder

Do not call a repository harness-ready until the proof stage matches the claim.

| Stage | Name | Proof |
|-------|------|-------|
| **H0** | Skills installed | Agent can discover the relevant Skill Steward skills. |
| **H1** | Local contract declared | `steward.yaml` exists with one quick-safe action and docs point to it. |
| **H2** | Smoke loop proven | Cold-start proof loop produces a durable benchmark summary with `result: "pass"`; `durability_blocked` keeps the repo below H2 until rerun cleanly. |
| **H3** | Repo feedback loop | Benchmark summaries, unknown cases, and action candidates accumulate from real work. |
| **H4** | Fresh-agent workflow | A fresh agent completes one repo workflow without raw shell spelunking. |
| **H5** | Promoted harness capability | Repeated evidence, including at least one held-out benchmark or future-agent repeat, promotes a diagnostic, action, eval, or local harness feature. |

## Archetypes Details

- **Archetype A (Product MCP):** `plugin/` is SSOT. Ship a **custom** server, do not patch community servers for product logic.
- **Archetype B (Platform Libs):** Core modules + wire protocol adapters only; no domain forks.
- **Archetype C (CLI Harness):** No MCP. Depends on product MCP core modules.
- **Archetype D (Visual sidecar):** No MCP. SSOT: `profiles/*.yaml`.
- **Archetype E (Meta Steward):** Core validators, thin CLI check. No `mcp.json`.
- **Archetype F (Production MCP):** Resources for read-only; tools for mutation. Return job IDs for long tasks. Use OAuth.

## Sibling layout

```text
/
  /               # toolkit + MCP/plugin init
  /              # SDK platform/library packages
  /              # CLI/harness runner
  /            # D — comparison sidecar
  /      # meta skills & validation
```

## Checklist be

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Arenukvern](https://github.com/Arenukvern)
- **Source:** [Arenukvern/skill_steward](https://github.com/Arenukvern/skill_steward)
- **License:** MIT
- **Homepage:** https://docs.page/arenukvern/skill_steward

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-arenukvern-skill-steward-mcp-harness-repo-maintainer
- Seller: https://agentstack.voostack.com/s/arenukvern
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.