From 110d0f0950b0a9a0299caa91e1a7dcbbed84eda7 Mon Sep 17 00:00:00 2001 From: yifu zuo Date: Thu, 29 Oct 2026 12:33:42 -0500 Subject: [PATCH] feat(maintain-verification-skill): add maintain-verification-skill plugin Upkeep loop for a project's verification skill and feature map: source coverage per feature, a live pass over every feature, and at most one PR of proven corrections. Adapted from the pstack skills (MIT, (c) Lauren Tan, https://github.com/cursor/plugins), project-skill paths updated for Droid (.factory/skills). --- .factory-plugin/marketplace.json | 6 +++ README.md | 8 ++++ .../.factory-plugin/plugin.json | 8 ++++ plugins/maintain-verification-skill/README.md | 11 ++++++ .../maintain-verification-skill/SKILL.md | 38 +++++++++++++++++++ skills/maintain-verification-skill | 1 + 6 files changed, 72 insertions(+) create mode 100644 plugins/maintain-verification-skill/.factory-plugin/plugin.json create mode 100644 plugins/maintain-verification-skill/README.md create mode 100644 plugins/maintain-verification-skill/skills/maintain-verification-skill/SKILL.md create mode 120000 skills/maintain-verification-skill diff --git a/.factory-plugin/marketplace.json b/.factory-plugin/marketplace.json index 4282159..b8076e5 100644 --- a/.factory-plugin/marketplace.json +++ b/.factory-plugin/marketplace.json @@ -53,6 +53,12 @@ "description": "Pull request lifecycle skills: create PRs with consistent conventions and follow up on them until merge-ready", "source": "./plugins/code-review", "category": "productivity" + }, + { + "name": "maintain-verification-skill", + "description": "Keep a project's verification skill and feature map honest as the app changes: source coverage, live pass, one PR of proven corrections", + "source": "./plugins/maintain-verification-skill", + "category": "automation" } ] } diff --git a/README.md b/README.md index 9793470..6fb359b 100644 --- a/README.md +++ b/README.md @@ -96,6 +96,14 @@ Skills for continuous learning and improvement. Autonomous experiment loop for optimization research. Try an idea, measure it, keep what works, discard what doesn't, repeat. Works standalone or as a mission worker. +### maintain-verification-skill + +Keep a project's verification skill and feature map honest as the app changes. + +**Skills:** + +- `maintain-verification-skill` - Source wave per feature, live pass over every feature, at most one PR of proven corrections + ## Plugin Structure Each plugin follows the Factory plugin format: diff --git a/plugins/maintain-verification-skill/.factory-plugin/plugin.json b/plugins/maintain-verification-skill/.factory-plugin/plugin.json new file mode 100644 index 0000000..c92b527 --- /dev/null +++ b/plugins/maintain-verification-skill/.factory-plugin/plugin.json @@ -0,0 +1,8 @@ +{ + "name": "maintain-verification-skill", + "description": "Keep a project's verification skill and feature map honest as the app changes: source coverage, live pass, one PR of proven corrections", + "author": { + "name": "yifu zuo", + "email": "yzuo.2019@gmail.com" + } +} diff --git a/plugins/maintain-verification-skill/README.md b/plugins/maintain-verification-skill/README.md new file mode 100644 index 0000000..9bb6534 --- /dev/null +++ b/plugins/maintain-verification-skill/README.md @@ -0,0 +1,11 @@ +# maintain-verification-skill + +Keep a project's verification skill and feature map honest as the app changes. + +**Skills:** + +- `maintain-verification-skill` - Source wave per feature, live pass over every feature, and at most one PR of proven corrections; reports clean, changed, or blocked + +Companion to the `create-verification-skill` plugin, which generates the verification skill this pass maintains. + +Adapted from the pstack skills by Lauren Tan ([cursor/plugins](https://github.com/cursor/plugins), MIT License), with project-skill paths updated for Droid (`.factory/skills/`). diff --git a/plugins/maintain-verification-skill/skills/maintain-verification-skill/SKILL.md b/plugins/maintain-verification-skill/skills/maintain-verification-skill/SKILL.md new file mode 100644 index 0000000..31ae4a4 --- /dev/null +++ b/plugins/maintain-verification-skill/skills/maintain-verification-skill/SKILL.md @@ -0,0 +1,38 @@ +--- +name: maintain-verification-skill +description: "Periodic pass that keeps a project's verification skill and feature map honest: parallel source readers per feature, one live session driving every feature, at most one PR of proven corrections. Use for \"audit the verify skill\" or on a cadence after generating one." +--- + +# Maintain a verification skill + +A feature map rots the moment the app changes. This skill is the upkeep loop for a skill generated by create-verification-skill (or any project-local verification skill with a feature map). The unit of rigor is the feature, not every sentence: cover every feature file from source and exercise every feature live, without terminalising every bullet. + +## Outcomes + +Pick one, and say which: + +- **clean** — every feature got source and live coverage; nothing worth shipping. No branch, no PR. +- **changed** — one PR ships proven doc, harness, or map corrections. +- **blocked** — coverage could not finish or a proven fix could not ship safely. Say exactly what blocked it. + +## Edit scope + +Only edit the verification skill's own directory (its SKILL.md, features/, and any harness scripts it owns). Never edit product code during a run: a behavior the map describes that the app no longer does is either doc drift (fix the map) or a product regression (report it, don't paper over it in docs). + +## Pass + +0. **Locate the target.** Find the verification skill to maintain: the project-local skill whose body has launch/drive sections and a feature map (usually `.factory/skills/verify-*/`). Several candidates → ask which one; none → stop and point at create-verification-skill instead of inventing a target. + +1. **Index hygiene.** Read the feature map README and glob its sibling files. Fix missing, extra, duplicate, or dead entries. Lightweight; no generated inventory. + +2. **Source wave.** One read-only subagent per feature file, launched concurrently. Each explains "how does this user-facing feature work?" from source, flags likely doc drift with citations, and returns one concise live-verification recipe. Children never drive the app and never edit files. Return shape: feature summary / source entry points / likely drift or none / one recipe. + +3. **Reconcile.** Every feature file has a returned summary. Merge overlapping recipes into as few app states as practical. Spot-check cited drift; don't re-prove clean claims. Sweep recent churn for user-facing surfaces missing from the map — require a concrete source path before calling one missing. + +4. **Live pass.** Required even when source looks clean. The coordinator owns all driving; follow the verification skill's own launch model — one long-lived instance driven serially for servers and UIs, or a fresh isolated session per drive for short-lived CLIs (the skill's Launch section decides, not this one). Exercise every feature at least once, and hold three invariants the whole pass, whatever the failure: (1) never drive an instance you haven't health-checked since it last did something surprising — doctor before first drive, doctor on each fresh session where sessions are the unit, doctor again after any failed drive, and where doctor can't see the failure (a wedged UI state on a healthy process), reset to a known state or relaunch rather than hoping; (2) evidence captured so far survives every cleanup, checked at its named location, not assumed; (3) nothing a drive started outlives that drive's usefulness — failed-iteration residue is cleaned whether the session is stuck, exited, or shared (for a shared instance, clean the residue, not the instance). A doctor failure caused by skill drift is drift: fix it under edit scope and retry once — restart whatever the fix invalidated, nothing more — before calling the pass `blocked`. A feature that can't be reached is `verified-unreachable` only with the concrete prerequisite (auth, entitlement, OS, external state) and the route attempted; if the map omits that prerequisite, that's drift. Any harness fix from triage gets re-driven live before it ships. Final teardown happens after the last drive of the run — including those re-proofs — so nothing outlives the run (evidence stays, per the skill). + +5. **Triage.** Wrong or missing user-POV description → doc drift, fix it. Working behavior the harness can't drive → harness gap, fix it; a harness fix follows the same helpers rule as generation (scripts executable, invocation documented in the skill body). App behavior that's actually broken → product gap; record it for the user, keep it out of this PR. + +6. **Ship or stop.** For changed: one PR of proven corrections, re-read every changed file first. For clean or blocked: no PR, report the outcome and the coverage honestly. + +Keep concise run notes (features covered, unreachable prerequisites, confirmed drift, outcome) in a scratch location; don't commit them. diff --git a/skills/maintain-verification-skill b/skills/maintain-verification-skill new file mode 120000 index 0000000..0e779b2 --- /dev/null +++ b/skills/maintain-verification-skill @@ -0,0 +1 @@ +../plugins/maintain-verification-skill/skills/maintain-verification-skill \ No newline at end of file