Repository Governance Lifecycle

Concept bridge (read before procedural steps)

Skill Steward procedures assume three portable lenses. If you only have this skill installed, load the digests in references/ (they ship with the skill). Full essays live on docs.page.

Lens	One-line	When to apply	Digest	Full
Engineering Stewardship	Keep the repo ecology understandable and improvable via observe → decide → update → prove → preserve	Friction repeats or survives one session	stewardship-loop.md	docs.page · North Star
Evolutionary simplicity	Evolve toward lower future confusion (split / compress / promote / demote / delete / stay native) — not always fewer parts	Before adding, splitting, merging, or deleting a surface	evolutionary-simplicity.md	docs.page
Generational architecture	Choose the smallest useful layer (G0–G5); higher is not automatically better; mature stewardship can move down	Before promoting codegen, harness actions, or new abstractions	generational-architecture-ladder.md	docs.page

Install-world rule: never rely on ../../docs/core/... alone — those paths only work inside a skill_steward checkout. Prefer the digests above and absolute docs.page URLs.

These lenses are not a new doctrine skill (see DESIGN_FAQ). This skill applies them; the digests teach them when the docs tree is not present.

This is the central nervous system for governing an agent-operated repository. It applies to apps, libraries, tools, plugins, harnesses, and meta repos; Skill Steward itself remains a structural stewardship repo, not a domain tutorial catalog. It unifies ethics, branding, architectural decision logs (ADRs), and living documentation (FAQs) into a single, cohesive loop: Decide → Document → Cleanup.

Whenever an agent proposes or executes a structural shift, claim change, durable policy change, or docs-lattice change, they must walk this loop. Routine repo repairs should keep the original goal and native gate first; use this governance loop only when the repair changes durable ownership, policy, evidence, ADR/FAQ truth, or plan hygiene.

The Governance Loop

1. Check Ethics & Boundaries (NORTH_STAR)

Before making any decision, check the repository's foundational charter and ethical baseline.

• Read Charter and Ethics to ensure your proposed changes do not violate the repository's moral boundaries (e.g. no hype; no domain tutorials inside Skill Steward; domain docs belong in the governed product repo when they are that repo's product).
• Read North Star Rules to understand the extension model.
• Classify north_star_impact for durable structural changes: none, applies, clarifies, sub_star, amends, or conflicts. Use the protocol only when ownership, policy, evidence truth, ADR/FAQ truth, or the repo's center may change.
• Ask the gate questions before editing durable governance surfaces: what pain triggered this; which North Star value path it serves; whether it is a mechanism or a new center; whether it changes what the repo owns or refuses; where the ADR is if it does; and what check prevents the mechanism becoming the mission if it does not.
• Route none and applies through the native workflow, clarifies through FAQ/skill/map/check updates, sub_star through an explicit parent/child boundary, and amends or conflicts through an ADR plus a North Star diff before implementation.

2. Log the Decision (ADRs)

If you have made an architecturally significant decision (or triggered a T1-T8 threshold), you must write it down. Decisions are not valid if they only live in an agent's context window.

• Follow the formatting rules in ADR Format to write a formal Decision Record.

3. Update Living Docs (FAQs)

Decisions change how the repository operates day-to-day. You must update the living system of record.

• Update docs/DESIGN_FAQ.mdx (the Why) or docs/DX_FAQ.mdx (the How).
• Follow the exact structuring rules in FAQ Format to ensure questions are searchable and direct.

4. Apply Brand & Tone Identity

When writing ADRs, FAQs, or any user-facing documentation, you must adhere strictly to the repository's tone.

• Do not use corporate marketing jargon.
• Review the banned word list in Brand Guidelines (e.g. do not use "unlock", "supercharge", "ultimate").

5. Plan Hygiene (Cleanup)

Never leave stale planning artifacts (task.md, implementation_plan.md) as permanent documentation.

• Once the ADR and FAQs are updated, your knowledge is durable.
• Extract any remaining useful context and delete or ignore the scratch files.
• For stale or overlapping non-plan docs, choose one disposition before editing: keep, merge, move to ADR, move to FAQ, move to skill, move to check, move to evidence, move to consumer proof, or delete.
• Ask what existing doc can shrink or disappear because of this change.
• Keep canonical architecture in the owning repo; consumer repos should carry adoption proof, local deltas, blocked state, and links to the owner.
• For broader surface-shape decisions such as split, compress, promote, demote, delete, or stay native, route through repo-quality-system-lifecycle and Evolutionary simplicity (full) instead of inventing a governance-only doctrine.
• Before upgrading steward, adoption, harness-ready, or maturity language in an ADR/evidence note, run steward claim check --claim <claim> --evidence <path> --json. Treat not_rejected as a negative-gate result, not acceptance.

6. Route Evidence Deliberately

Do not turn every run, plan, or discussion into evidence. Use Evidence artifacts as the routing rule:

• ADR: durable decision, trade-off, status, or consequence.
• FAQ: standing why/how that humans and agents will ask again.
• Skill: repeatable agent procedure or interpretation loop.
• Check/tool/schema/test: deterministic drift, freshness, shape, or blocked-state detection.
• Current ledger: weakest true current status and rerun route.
• Evidence artifact: real run proof, blocked state, pattern review, PDSA loop, postmortem, unknown case, or reference that protects a claim or changes future behavior.
• Delete/remove: completed checklist, stale plan, or template once useful truth has been extracted.

When you create or materially update an evidence artifact, use the canonical envelope in Evidence artifacts. ADR 0023 explains why that envelope exists.

Install

npx skills add arenukvern/skill_steward --skill repository-governance-lifecycle

Sources

See references/sources.md.