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.
In this repository44 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- analyze-dataSkill
- brainstormingSkill
- craft-lessonSkill
- create-agentSkill
- create-skillSkill
- customize-agentSkill
- customize-skillSkill
- designSkill
- deslopSkill
- developSkill
- discovery-reportSkill
- elicitationSkill
- empathy-mapSkill
- explore-ideaSkill
- grill-meSkill
- help-meSkill
- humanizeSkill
- incidentSkill
- iterateSkill
- journey-mapSkill
- jtbdSkill
- kanbanSkill
- launchSkill
- legal-safety-auditSkill
- maintenance-executeSkill
- memorySkill
- motionSkill
- phaseSkill
- planSkill
- research-planSkill
- retroSkill
- reviewSkill
- root-causeSkill
- round-tableSkill
- shape-upSkill
- shut-upSkill
- statusSkill
- teach-meSkill
- testSkill
- unpack-problemSkill
- validate-ideaSkill
- validation-patternsSkill
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
- Distinctive: line 38
Read each linked step file fully and follow Steps 0–3 in order.
- Very specific: line 39
Read and write maintenance artifacts only beneath the exact artifacts/output/maintenance/<run-id>/ root returned by the maintenance state …
- Very specific: line 41
Never read or write product artifacts/output/pipeline-state.json, artifacts/output/sprint-status.yaml, artifacts/memory/project-context.md, …
- Very specific: line 42
Never use product /plan or /design, orchestrator_state.js, step_tracker.js, product memory, product phase state, or shared session/worktree …
- Distinctive: line 68
All four steps have been completed or stopped at a clearly recorded blocker.
- Distinctive: line 76
No code changes, product-state changes, or product-phase transitions were made.
≈ “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.
Files
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-planor 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-rootand an existing approvedrunId. Pass--state-rootexplicitly on every command: the helper reads no environment variable, soVESPYR_MAINTENANCE_STATE_ROOTis 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, andmaintenance-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
dirtyManifestidentity field: one single-line JSON object with schemadirty-manifest-v1and afilesarray 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 emptyfilesarray. - The maintenance plan checker exists and documents two read-only commands.
maintenance_plan_check.js manifestcomputes the dirty-manifest fingerprint for the plan's relevant paths;maintenance_plan_check.js checkvalidates one draft plan. Both require--scope maintenance,--repo-root,--state-root,--run-id,--plan, and--json, both write nothing, and both emitexecutionAuthorized: 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.mdor 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-relativepath:lineor 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
/planor/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
- Run and scope (non-skippable gate) → Step 0 — establish a fresh maintenance session, verify the run and artifact root, and lock the allowlist.
- Load and reconcile inputs → Step 1 — check required artifacts, IDs, internal links, source references, and open decisions.
- Write the plan → Step 2 — create a revision-bound draft with bounded tasks, evidence, dependencies, parallelism, risks, and a generated dirty manifest.
- 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
DRAFTand not review-ready. A checker result is a recorded claim about one revision; it is never authorization. - The plan's
dirtyManifestis 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
dirtyManifestfield 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'sRepository-owner execution authorizationrow 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
recordStatusstaysDRAFTfor 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.jsfirst, then checksnode .agents/scripts/maintenance_state.js statusandartifact-root. - After writing a plan, record a
plan_draftedevent whose details carry the plan ID, the revision, the digest, the artifact path, and theDRAFTstatus; then recheck status. The state store reads the identity from the detail keysplanId,planRevision, andplanHash. UseplanHashfor the digest — it is the plan'splanDigestvalue verbatim — andplanRevisionfor the plan's revision string. A detail set that omits one of those three keys is recorded as an invalid plan event. - A
verificationevent records@tech-leadtechnical review only. Aplan_approvedevent 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.
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
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.

