agentleFS
devexpert-iodevexpert-io/harness-starter/.agents/skills/feature-validator/SKILL.md

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.

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
  1. Distinctive:

    All paths in this skill are relative to the repository root.

    line 10
  2. Distinctive:

    Do inspect the spec, diff, harness state, and verification evidence.

    line 16
  3. Distinctive:

    Do rerun checks when feasible and useful.

    line 17
  4. Distinctive:

    Do review architecture, security, maintainability, documentation, and scope.

    line 18
  5. Very specific:

    Do produce a clear verdict: accept, revise, or block.

    line 19
  6. Distinctive:

    Do give concrete, executable repair instructions for every finding that prevents acceptance.

    line 20
  7. Distinctive:

    Do not implement broad fixes during validation unless the user explicitly asks for fixes.

    line 21
  8. Distinctive:

    Do not accept based only on the implementer's confidence or summary.

    line 22
  9. Very specific:

    Treat passing in feature_list.json as "ready for validation", not as already accepted.

    line 23
  10. Very specific:

    If no feature id is provided, choose the feature currently in_progress.

    line 39
  11. Distinctive:

    If there is no spec, stop: validation needs a contract.

    line 60
  12. Distinctive:

    Run the repo standard gate and focused checks when practical.

    line 75
  13. Very specific:

    Use references/validation-rubric.md to evaluate:

    line 90
  14. Very specific:

    If the verdict is revise, also include an Implementation Repair Brief that can be handed directly to the implementer.

    line 132

≈ “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.

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

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, or block.
  • 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 passing in feature_list.json as "ready for validation", not as already accepted. Treat accepted as already independently accepted unless the user explicitly asks for revalidation.

Inputs To Read First

  1. AGENTS.md
  2. PROGRESS.md
  3. feature_list.json
  4. Selected feature spec: docs/specs/<feature-id>.md
  5. Current git status and diff
  6. Durable docs if present:
    • ARCHITECTURE.md
    • CONSTRAINTS.md
    • DESIGN.md when the spec or implementation has UI or visual behavior
    • related docs under docs/
  7. 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.json and PROGRESS.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 in feature_list.json.
  • validator accept: independent acceptance verdict; it becomes status accepted only 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:

  1. static/syntax checks,
  2. tests and runtime/startup checks,
  3. persistent E2E checks such as pnpm test:e2e when available and relevant,
  4. 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.md stayed short and router-like,
  • ARCHITECTURE.md captures durable boundaries without becoming a file inventory,
  • CONSTRAINTS.md uses operational MUST/MUST NOT rules rather than vague preferences,
  • docs do not contradict the implemented behavior.
  • UI or visual changes follow DESIGN.md when 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 revise or block,
  • 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.

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.