feature-validator
Skill4 starsChanged 51 days agoMITView on GitHub
Independently validate one implemented feature against a feature spec file under docs/specs, feature_list.json, PROGRESS.md, and the current diff. Use when the user asks to validate, review, QA, evaluate, or accept/reject a feature after implementation. The skill checks behavior, verification evidence, scope discipline, architecture, security, durable documentation, and handoff readiness, then returns accept/revise/block.
In this repository3 other files it gives its agents.
- build-briefSkill
- feature-specSkill
- harness-starterSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. About 0 are common, 9 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 10
All paths in this skill are relative to the repository root.
- Distinctive: line 16
Do inspect the spec, diff, harness state, and verification evidence.
- Distinctive: line 17
Do rerun checks when feasible and useful.
- Distinctive: line 18
Do review architecture, security, maintainability, documentation, and scope.
- Very specific: line 19
Do produce a clear verdict: accept, revise, or block.
- Distinctive: line 20
Do give concrete, executable repair instructions for every finding that prevents acceptance.
- Distinctive: line 21
Do not implement broad fixes during validation unless the user explicitly asks for fixes.
- Distinctive: line 22
Do not accept based only on the implementer's confidence or summary.
- Very specific: line 23
Treat passing in feature_list.json as "ready for validation", not as already accepted.
- Very specific: line 39
If no feature id is provided, choose the feature currently in_progress.
- Distinctive: line 60
If there is no spec, stop: validation needs a contract.
- Distinctive: line 75
Run the repo standard gate and focused checks when practical.
- Very specific: line 90
Use references/validation-rubric.md to evaluate:
- Very specific: line 132
If the verdict is revise, also include an Implementation Repair Brief that can be handed directly to the implementer.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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
Feature Validator
Use this skill after an implementation session. The validator is independent from the implementer: it does not trust self-reported completion and judges the work against repo artifacts and runtime evidence. Run it in a fresh session or subagent that did not write the code, so it does not inherit the implementer's assumptions.
All paths in this skill are relative to the repository root.
Role Boundary
You are the validator/evaluator, not the planner and not the implementer.
- Do inspect the spec, diff, harness state, and verification evidence.
- Do rerun checks when feasible and useful.
- Do review architecture, security, maintainability, documentation, and scope.
- Do produce a clear verdict:
accept,revise, orblock. - Do give concrete, executable repair instructions for every finding that prevents acceptance.
- Do not implement broad fixes during validation unless the user explicitly asks for fixes.
- Do not accept based only on the implementer's confidence or summary.
- Treat
passinginfeature_list.jsonas "ready for validation", not as already accepted. Treatacceptedas already independently accepted unless the user explicitly asks for revalidation.
Inputs To Read First
AGENTS.mdPROGRESS.mdfeature_list.json- Selected feature spec:
docs/specs/<feature-id>.md - Current git status and diff
- Durable docs if present:
ARCHITECTURE.mdCONSTRAINTS.mdDESIGN.mdwhen the spec or implementation has UI or visual behavior- related docs under
docs/
- Files changed by the implementation.
If no feature id is provided, choose the feature currently in_progress. If none exists, choose the most recently evidenced passing feature. Do not choose features whose status is accepted unless the user explicitly asks to revalidate them. If ambiguous, ask for the feature id.
Workflow
1. Establish Review Target
Identify:
- selected feature id,
- spec path,
- implementation diff,
- claimed status in
feature_list.json, - evidence recorded in
feature_list.jsonandPROGRESS.md.
Status convention:
in_progress: implementation may still be underway; validate only if the user asks for interim review.passing: implementer self-verification passed; this is the normal state to validate.accepted: independent validator acceptance has already been persisted infeature_list.json.- validator
accept: independent acceptance verdict; it becomes statusacceptedonly after it is persisted (see Produce Verdict).
If there is no spec, stop: validation needs a contract.
2. Validate Against The Spec
Check:
- goal satisfied,
- non-goals respected,
- acceptance scenarios pass or have convincing evidence,
- expected file changes are present or deviations are justified,
- implementation tasks were completed or explicitly deferred,
- verification plan was followed.
3. Rerun Or Inspect Verification
Run the repo standard gate and focused checks when practical. If checks are expensive, unavailable, or require external services, inspect recorded evidence and state what was not rerun.
If init.sh exists after a runnable baseline has been created, treat it as the standard non-blocking startup/verification gate. It should execute the relevant checks and fail on errors. If it only prints commands while the repo is already bootstrapped, raise a revise finding with a concrete repair brief. It must not start long-running processes such as a dev server.
Use this hierarchy:
- static/syntax checks,
- tests and runtime/startup checks,
- persistent E2E checks such as
pnpm test:e2ewhen available and relevant, - user-flow or manual smoke checks when persistent E2E is not yet available or cannot cover the case.
If the repo has a persistent E2E command and the feature changes user-visible behavior, authentication, authorization, routing, or API flows, verify that focused E2E coverage was added/updated or that the spec/implementation gives a credible reason it was not needed. Missing relevant E2E coverage is normally a revise finding once the E2E harness exists.
4. Review Quality And Risk
Use references/validation-rubric.md to evaluate:
- correctness,
- verification evidence,
- scope discipline,
- architecture compliance,
- security/privacy/access-control risk,
- maintainability,
- durable documentation,
- handoff readiness.
Also read and apply references/security-checklist.md for a portable feature-scoped security review. Security review should be scoped to the feature, current diff, and directly supporting files, not a full repository audit unless requested.
5. Check Durable Documentation
Validate the spec's Durable Documentation Impact section:
- required docs were created/updated,
- unnecessary docs were not created,
AGENTS.mdstayed short and router-like,ARCHITECTURE.mdcaptures durable boundaries without becoming a file inventory,CONSTRAINTS.mduses operational MUST/MUST NOT rules rather than vague preferences,- docs do not contradict the implemented behavior.
- UI or visual changes follow
DESIGN.mdwhen the feature involves product screens, public verification pages, or generated design assets.
6. Produce Verdict
Return one of:
accept: feature satisfies the spec, verification evidence is adequate, and harness/docs are consistent.revise: feature is close but needs specific fixes; list required changes.block: validation cannot continue or the implementation is fundamentally unsafe/wrong; list blocker and required next action.
For each finding that leads to revise or block, include:
- severity,
- evidence,
- why it matters,
- required change,
- suggested implementation steps,
- verification after fix.
If the verdict is revise, also include an Implementation Repair Brief that can be handed directly to the implementer. It should be ordered, scoped, and executable without this chat.
Do not mark final acceptance in files unless the user explicitly asks. By default, return the verdict and the recommended state update. When the user confirms an accept verdict, set the feature status to accepted in feature_list.json, record concise evidence, and add a short entry to PROGRESS.md. If a separate orchestrator runs this validator, it is responsible for persisting the verdict instead.
Output Summary
Report:
- verdict,
- feature id and spec path,
- checks rerun and results,
- findings by severity,
- implementation repair brief when the verdict is
reviseorblock, - security assessment summary, including whether the security checklist found no relevant issues, notes, or blocking findings,
- documentation/harness state assessment,
- required follow-up if any.
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.

