agentleFS
lalulalilalulali/vespyr/.agents/skills/maintenance-plan/SKILL.md

maintenance-plan

Skill11 starsChanged 11 days agoMITView on GitHub

Create a source-linked, revision-bound plan for one approved maintenance run. Use when the user invokes `/maintenance-plan`, asks to plan an approved maintenance run, or requests bounded closeout tasks from that run's maintenance brief, spec, and work items. Do not use for product planning or code execution.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 3 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read each linked step file fully and follow Steps 0–3 in order.

    line 38
  2. Very specific:

    Read and write maintenance artifacts only beneath the exact artifacts/output/maintenance/<run-id>/ root returned by the maintenance state …

    line 39
  3. Very specific:

    Never read or write product artifacts/output/pipeline-state.json, artifacts/output/sprint-status.yaml, artifacts/memory/project-context.md, …

    line 41
  4. Very specific:

    Never use product /plan or /design, orchestrator_state.js, step_tracker.js, product memory, product phase state, or shared session/worktree …

    line 42
  5. Distinctive:

    All four steps have been completed or stopped at a clearly recorded blocker.

    line 68
  6. Distinctive:

    No code changes, product-state changes, or product-phase transitions were made.

    line 76

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Maintenance Plan — Draft bounded maintenance work

<!-- router-skill -->

Create one source-linked maintenance plan and keep it a draft until separate technical review and repository-owner execution authorization are recorded. Read and write maintenance artifacts only under the exact run-specific maintenance artifact root; read and write session/run state only under the caller-supplied external state root. Step 1 permits narrow, read-only inspection of exact repository source references after input reconciliation.

Non-goal: this skill creates the closeout plan only; it does not execute code changes. The separate /maintenance-execute workflow owns execution, and only for a plan that the repository owner has separately authorized.

When to invoke

  • The user invokes /maintenance-plan or asks for a plan from one approved maintenance run.
  • The work is defined by the run's maintenance brief, spec, and work items, not product-phase artifacts.
  • A caller can supply the existing runId, an absolute external state root, and the exact plan scope.

When NOT to invoke

  • The request is to implement, test, or otherwise execute planned code changes; this router never executes them.
  • The request is ordinary product planning, product design, or a product-phase transition.
  • The user wants a gate-green verdict. This skill creates a plan and records claims; it cannot establish gate-green.

Prerequisites

  • The caller supplies an absolute external --state-root and an existing approved runId. Pass --state-root explicitly on every command: the helper reads no environment variable, so VESPYR_MAINTENANCE_STATE_ROOT is not a fallback and a missing flag fails closed. Do not substitute an environment variable, generate a run ID, or fall back to product state.
  • The maintenance startup and state scripts are available. Step 0 must confirm the state root is canonical, outside the repository, and bound to the supplied run ID.
  • The returned artifact root contains maintenance-bootstrap-plan.md, maintenance-brief.md, maintenance-spec.md, maintenance-work-items.md, and maintenance-plan-contract.md. The external state must contain a recorded T005 completion claim. Treat all state events and approval entries as unverified claims, not authenticated facts.
  • The caller or an external run-state record supplies the exact base revision. After Step 1 reconciles the inputs, record working-tree identity from repository metadata and, for a dirty tree, a sorted content-hash manifest of only the relevant files inspected or required by the plan. Do not hash the whole checkout or read product runtime state to build it. If the base revision or relevant-file identity cannot be established within this boundary, stop.
  • The plan carries a dirtyManifest identity field: one single-line JSON object with schema dirty-manifest-v1 and a files array of per-file fingerprints. It is generated by the documented manifest command, never hand-written. A dirty relevant set must be declared; a clean relevant set is an empty files array.
  • The maintenance plan checker exists and documents two read-only commands. maintenance_plan_check.js manifest computes the dirty-manifest fingerprint for the plan's relevant paths; maintenance_plan_check.js check validates one draft plan. Both require --scope maintenance, --repo-root, --state-root, --run-id, --plan, and --json, both write nothing, and both emit executionAuthorized: false. Use the exact command shapes in Step 2 and Step 3. Do not guess a command shape, rename a flag, or substitute another checker.

Harness adherence

  • Read each linked step file fully and follow Steps 0–3 in order. Step 0 is non-skippable and its startup command runs before reading any run artifact.
  • Read and write maintenance artifacts only beneath the exact artifacts/output/maintenance/<run-id>/** root returned by the maintenance state helper. Read and write session/run state only under the explicit external state root through maintenance-state tooling.
  • After Step 1 reconciles the run inputs, read-only inspection is allowed only for exact repository paths linked from maintenance-work-items.md or required to verify a named finding or estimate (source, tests, specs, baselines, or scripts). Read only relevant files and sections; do not broad-scan unrelated directories. Record the exact repository-relative path:line or test name and the full revision/tree identity checked. A citation is not verified until the source is actually opened. This exception does not allow edits or test/script execution.
  • Never read or write product artifacts/output/pipeline-state.json, artifacts/output/sprint-status.yaml, artifacts/memory/project-context.md, artifacts/memory/**, .agents/state/**, product session summaries, or unrelated product output. External/web sources not reopened remain inherited and unverified unless separately authorized.
  • Never use product /plan or /design, orchestrator_state.js, step_tracker.js, product memory, product phase state, or shared session/worktree helpers.
  • The body names capabilities, not harness-specific tools. If technical review or owner confirmation cannot be obtained in the current environment, record it as pending rather than simulating it.

Mode selection

There is one mode: create or revise a plan for the caller's existing maintenance run. Lock the mode from the explicit run ID and requested scope. If the user asks for execution, product planning, or a different run, stop and hand back the appropriate next step; do not silently switch workflows.

Step sequence

  1. Run and scope (non-skippable gate) → Step 0 — establish a fresh maintenance session, verify the run and artifact root, and lock the allowlist.
  2. Load and reconcile inputs → Step 1 — check required artifacts, IDs, internal links, source references, and open decisions.
  3. Write the plan → Step 2 — create a revision-bound draft with bounded tasks, evidence, dependencies, parallelism, risks, and a generated dirty manifest.
  4. Review and authorization → Step 3 — keep technical review separate from owner authorization and record only evidence-backed claims.

Halt conditions

  • The caller has not supplied an absolute external state root or existing run ID → ask for both and stop before repository reads or writes.
  • Startup, run status, or artifact-root output is missing, conflicting, outside the allowlist, or bound to another run → stop; do not retry in product mode.
  • Required maintenance inputs or the T005 completion record are absent, their IDs/internal links conflict, or any owner decision conflicts across the input artifacts and external state → preserve the conflict and stop for resolution.
  • A required plan identity, exact source link, 1–4 hour task bound, code revert-proof test, non-code evidence record, or matching dependency graph cannot be supplied → keep the affected work blocked; do not invent evidence or inflate an estimate.
  • The documented plan-check command has not actually run against this exact plan revision, or it reports invalid → keep the plan DRAFT and not review-ready. A checker result is a recorded claim about one revision; it is never authorization.
  • The plan's dirtyManifest is missing, malformed, stale, or mismatched against the computed fingerprint → fail closed. Regenerate it with the documented manifest command, recompute the digest, and re-run the check before any review.
  • Technical review, repository-owner authorization, or its exact evidence reference is missing → leave that record pending. Never infer owner authorization from technical review, an earlier bootstrap approval, silence, or a state transition.

Done when

  • All four steps have been completed or stopped at a clearly recorded blocker.
  • One plan revision exists only beneath the exact run artifact root and records its full identity, scope, source reconciliation, tasks, decision blockers, verification, parallelism, dependencies, and risks.
  • The dirtyManifest field holds the JSON the documented manifest command generated for this plan's relevant paths, and the digest was recomputed after that JSON was written into the plan.
  • B1, O-4, B10, and credential-residual stay [OPEN] unless the owner has ruled on them in their own evidence; the skill itself never chooses their policy. A decision stops blocking dependent work only when three artifacts agree: the plan's Repository-owner execution authorization row names that decision ID, the plan's decision row for that ID is no longer [OPEN], and external maintenance state holds a matching recorded disposition claim that the plan's decision row cites. The skill records those claims; it never fabricates them.
  • The plan file's recordStatus stays DRAFT for its whole life, including after the owner authorizes it. The checker validates draft plans only. Authorization is recorded in the plan's review/authorization rows and in external maintenance state, never by flipping the plan's status field.
  • Any review or authorization claim includes an exact evidence reference and is labelled unverified; neither a state event nor its status is authentication or gate-green.
  • The plan checker is reported as passed only after its documented command has actually run against this exact plan revision. Its result is a recorded claim about that revision, never owner authorization.
  • Any change to a reviewed plan creates a new revision with a new digest. The earlier technical review and owner authorization do not carry over: the new revision needs a fresh technical review and a fresh owner authorization bound to its own revision and digest.
  • No code changes, product-state changes, or product-phase transitions were made.

Maintenance-state integration

  • Step 0 runs node .agents/scripts/maintenance_session.js first, then checks node .agents/scripts/maintenance_state.js status and artifact-root.
  • After writing a plan, record a plan_drafted event whose details carry the plan ID, the revision, the digest, the artifact path, and the DRAFT status; then recheck status. The state store reads the identity from the detail keys planId, planRevision, and planHash. Use planHash for the digest — it is the plan's planDigest value verbatim — and planRevision for the plan's revision string. A detail set that omits one of those three keys is recorded as an invalid plan event.
  • A verification event records @tech-lead technical review only. A plan_approved event is reserved for explicit repository-owner execution authorization tied to the same plan revision and digest. Both are recorded claims with evidence references, not authenticated approvals.
  • Finish by checking maintenance_state.js status. Status records evidence; it never establishes gate-green.

Output artifacts

  • artifacts/output/maintenance/<run-id>/maintenance-plan-<plan-id>-r<revision>.md — the immutable plan revision. A change creates a new revision and digest; do not overwrite a reviewed revision.
  • External maintenance state events — session identity, draft, review, authorization claims, and status. Do not create machine state in the repository.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.