Repo Quality System Lifecycle

Repo Quality System Lifecycle

Use this skill to make a repository legible, safe, and improvable for humans and agents. It is broader than Agent Skill authoring and narrower than product implementation.

When to use

• Setting up Engineering Stewardship in an app, library, CLI/tool, plugin, harness, or meta repo.
• Auditing whether a repo has enough charter, docs, decisions, validation, evidence, and safety metadata for agents to work without hidden local context.
• Designing a repo quality contract before adding harness actions, diagnostics, or automation.
• Separating repo stewardship proof from product runtime correctness.
• Auditing a multi-repo integration chain where one repo must publish, tag, or stabilize before a consumer repo can truthfully cut over.
• Deciding whether repeated repo friction should stay native, become docs/FAQ, become an API/schema/generator, become harness proof, or be deleted/collapsed.
• Auditing broad product claims such as platform support, compatibility, maturity, or "works everywhere" language against live evidence and owner boundaries.
• Running a repository ecology review over plans, specs, docs, skills, schemas, tools, evidence, and validation surfaces to choose explicit dispositions.

When not to use

• Writing product/domain features directly; use the repo's native stack and product skills.
• Creating or packaging an Agent Skill; use skill-authoring-lifecycle.
• Maintaining a steward.yaml action contract, probes, benchmarks, or CLI/MCP parity after the baseline exists; use mcp-harness-repo-maintainer.
• Generalizing a proven harness across producer/consumer repos; use harness-engineering-lifecycle.

Workflow

1. Classify the repo

Pick one primary archetype. Do not let every repo become a harness repo.

2. Establish the stewardship baseline

A baseline is not a giant docs rewrite. It is the minimum map a fresh agent needs.

• Charter or North Star: what the repo is, is not, and optimizes for.
• Agent map: where an agent starts and what it must not bloat.
• Claims and evidence router: ADR for decisions, FAQ/docs for standing guidance, checks/tools/tests for deterministic drift, current ledger for weakest true status, evidence for real proof or blocked proof, delete completed plans after extraction.
• Docs map: canonical owner for why, how, specs, decisions, behavior, and procedures.
• Behavior SSOT: code, schemas, tests, or generated artifacts that docs link to.
• Validation command: one native command or truthful blocked state.
• Release path: changelog/version/artifact provenance, even if immature.

If the repo is not ready for Steward CLI, bootstrap manually: add the claim/evidence router and north_star_impact prompt to AGENTS.md, name the native validation command, and create docs/evidence/current-status.mdx only when a current claim or blocker needs a durable pointer. If the repo has Steward CLI, steward adopt creates the local agent map with that North Star impact habit, and steward evidence init --minimal creates that ledger without adding harness machinery.

3. Define the quality contract

Write the smallest contract that can be checked.

For multi-repo roadmaps, also record dependency order, source-of-truth repo, consumer gate, dirty-state policy, and do-not-touch exceptions. Do not claim a downstream consumer is ready from local path dependency success when the upstream package or binary still lacks publish evidence. The producer repo owns architecture, public contract, release provenance, and compatibility claims; consumer repos own adoption proof, local deltas, blocked state, and cutover commands.

Use docs/repo-quality-contracts.mdx as the normative spec.

For product repos, do not count Steward activity as product acceleration unless it lands in the owner checkout as either a source-owned product delta or a product-native proof. Examples: a changed Flutter interaction, a public API or adapter contract, a CLI output/failure mode, a plugin install path, a real visual screenshot, a performance metric, or a release/publish preflight. If the only result is a cleaner ledger, eval, action contract, or proof tool, the honest claim is stewardship maintenance, orientation, or harness candidate, not product progress. For visual/performance-heavy repos, tests are support evidence; the claim ceiling stays low until a human-inspectable capture or metric proves the product surface moved.

For visual, shader, renderer, loader, or performance tasks, route to the product-native experiment loop before Steward work. The product repo owns the variant runner, browser/server orchestration, image oracle, screenshots, videos, and performance metrics. Steward may summarize the winning campaign through an experiment-campaign-summary/v1 artifact, block false claims, and record non-claims. It must not become the inner loop. If two Steward detours fail to improve the product metric, stop Steward work and return to native experiments. Parallel lanes should test independent product hypotheses, not evidence paperwork.

4. Run the generational architecture check

Before adding automation, splitting a surface, compressing navigation, or creating a new abstraction, apply evolutionary simplicity. Decide whether this surface should split, compress, promote, demote, delete, or stay native.

Then ask the Skeptic questions:

• Is the friction repeated across agents or workflows, or only from this run?
• Can a language/framework feature, native command, FAQ, validation message, or docs-map row solve it?
• Would deleting, merging, or demoting a layer reduce maintenance without losing proof?
• Did ownership, proof, effects, cadence, or audience diverge enough to split the surface?
• Did user intent, CI flow, or navigation converge enough to compress the surface while keeping child truths inspectable?
• If codegen is proposed, is the schema smaller and more stable than the generated code?
• If a harness action is proposed, does it help the original task or a named future problem class?
• What falsifier or held-out task will show the promoted layer is stale, wrong, or not useful?

Use docs/core/evolutionary-simplicity.mdx for the parent movement rule and docs/core/generational-architecture-ladder.mdx for the architecture stage model. Higher layers are not automatically better; mature stewardship can move down the ladder.

If the check rejects a proposed abstraction, promotes a new layer, updates an existing skill/tool, or changes durable repo policy, record a Pattern Promotion Review under docs/evidence/pattern-promotion-review-YYYY-MM-DD-topic.mdx. Keep it as evidence for a real run, not as a new skill or scorecard.

5. Prove the claim honestly

Use the weakest true claim, not the strongest desired one.

Before using machine-readable CLI output as evidence, run steward schema check-outputs --json in the owning repo when available. This catches schema/JSON drift; it does not prove runtime behavior or maturity by itself.

For broad compatibility or maturity claims, record a compact claim audit:

Skipped validation, blocked generators, blocked benchmarks, and manually synced generated files are useful notes, not readiness proof.

6. Promote repeated learning

If an agent discovers friction, do not immediately create permanent automation. First decide the durable artifact.

7. Run a repository ecology review

Use this when the user asks what should be compressed, changed, merged, removed, updated, created, retired, or moved into checks. Dogfood or benchmark evidence may be relevant, but it is not required for every ecology pass.

Inspect the repo ecology surfaces that matter for the request:

• Plans and specs: in-flight, implemented, stale, or extracted.
• Docs and maps: canonical owner, duplicated truth, stale proof, or missing links.
• ADRs and FAQs: durable decisions versus standing why/how.
• Skills and evals: activation clarity, overlap, missing cases, or bloat.
• Schemas and generated artifacts: machine-readable drift and behavior SSOT.
• CLI/MCP/tools: deterministic checks, JSON shape, and bounded effects.
• Evidence: current proof, historical proof, superseded proof, templates, blocked evidence, current-status pointers, next disposition, and non-claims.

Loop smells to name before creating another artifact: a third evidence note or packet for the same blocker, repeated blocker proof, a tool tunnel, stale proof loop, repair replacing the original goal, or status artifacts multiplying faster than fixes.

Prefer a single disposition table over a new doctrine page:

Use these disposition meanings:

• keep: current canonical owner is still right.
• compress: reduce duplicated prose while preserving the owner.
• merge: move remaining truth into another live surface.
• update: current owner is right but stale.
• remove: content is implemented, stale, duplicated, or no longer useful after extraction.
• create: a missing surface is justified by repeated friction or proof needs.
• defer: the signal is real but not ready for a durable surface.
• move to ADR: the durable value is a decision or trade-off.
• move to FAQ: the durable value is standing why/how guidance.
• move to skill: the durable value is repeatable agent procedure.
• move to check: deterministic drift or freshness should fail mechanically.
• move to evidence: a real run should be preserved with proof and non-claims.
• move to consumer proof: this repo owns local adoption proof, not producer architecture.
• leave native: the repo's language, framework, or product command is the right layer.

When steward ecology snapshot --json is available, use it as inventory only. The snapshot can reduce tedious state gathering, but it does not award maturity, adoption, H2/H5, or steward status.

When steward ecology route --json emits dispatch_lane_candidates, treat them as disposable advisory hints derived from the same route facts. They are not write authorization, action candidates, backlog items, parent lane contracts, maturity evidence, or scheduler state. Use them only to make repo-wide pain legible for a parent agent, then assign real work through multi-agent-handoff or delete the scaffolding after synthesis. Do not generate or trust lane candidates from leave_native.

For evidence surfaces, apply the envelope in docs/core/evidence-artifacts.mdx. Prefer move to check over move to evidence when the same deterministic drift will recur; prefer a current ledger over many historical notes when the reader only needs the present weakest true claim.

When proof includes maintainer-local paths, temp replays, or one workstation's setup, keep that context in the current ledger or historical evidence and label it as maintainer-local. Create or update a public reproducibility card only when a public reader needs to audit the claim from durable anchors: public repo URL, fetchable commit SHA, portable command, and artifact hash or CI artifact name.

Run ecology as a disposition loop, not an evidence treadmill or a tool tunnel. Ask: what is the boldest useful outcome, and what is the least machinery needed to prove it?

Keep the two vocabularies distinct:

• Prefer orient, compress, validate, tutor_pain, promote_tool, leave_native, or stop before creating any new artifact.
• When a proposed mechanism starts acting like the umbrella, classify north_star_impact. sub_star needs a parent/child boundary; amends or conflicts needs governance and an ADR before product direction changes.
• When the review finds invalid config, dirty declared inputs, schema/output drift, blocked payload routing, stale navigation, or a broken native gate, update the owning surface and rerun the same gate when that is the smallest safe disposition.
• For command, tool, docs, evidence, and skill surfaces, ask whether the boldest useful move is to split, compress, promote, demote, delete, or stay native.
• For tutor_pain, name the pain signal, owner, native gate, smallest disposition, rerun route, hot-path residue, and non-claim.
• Before adding a new doc, check, schema, skill, evidence artifact, command, or tool, apply the anti-bureaucracy gate: it must reduce future uncertainty, automate repeated judgment, prevent a demonstrated failure, enable an honest claim, or delete/compress an older surface.
• For product repos, name the product impact check before adding or trusting Steward proof. If no product-native behavior, API, UI/visual, performance, release, or workflow surface changed or was directly proven, downgrade the outcome to stewardship support and return to the product owner surface.
• For repeated skills/plugins/hooks/marketplace copy friction, prefer a documented skill pattern or product-owned local copy/init script before adding Steward CLI functionality. The owner repo should generate its host manifests, cache-refresh notes, rollback steps, and install proof. A Steward skill can teach the pattern; it should not turn one repo's installer into a new Steward command without a Pattern Promotion Review and repeated cross-repo evidence.
• For experiment campaigns, require a product-owned oracle/capture/metric before any product-acceleration claim. Summaries with only Steward docs, schemas, evals, or harness changes are support_only: true.
• After two learning loops on the same friction, stop PDSA and produce a disposition table. Extract the durable lesson into ADR, FAQ, skill, check, CLI diagnostic, or current ledger, then delete/retire duplicate plans or historical packets from active navigation.
• Do not add sub-stewards, new broad skills, new benchmark scenarios, or new evidence indices from the same blocked detour unless the repaired owner still cannot represent the repo honestly.

Output contract

When reporting an audit or adoption pass, include:

• Repo archetype and primary artifact.
• Current maturity stage (S0-S5) and evidence for audits, adoption claims, or readiness claims.
• Missing contract areas when they block the requested work or a claim.
• Pattern layer chosen, smaller layer considered, and expected maintenance delta.
• north_star_impact when the work could alter the repo center, ownership, or refusal boundaries.
• Boldest useful next improvement.
• Product impact check and product delta, or the explicit reason the work is stewardship support only.
• Ecology dispositions when the request is about compression, cleanup, or surface changes.
• What was not validated.
• Any skipped generators, blocked checks, or non-claims behind broad product language.

For normal implementation tasks, the shorter output is enough: original goal, chosen disposition, native gate, boldest useful change or reason to leave native/stop, validation result, and the hot-path residue left for future agents.

Install

npx skills add arenukvern/skill_steward --skill repo-quality-system-lifecycle

Sources

See references/sources.md.