Claude Code Plugins

Community-maintained marketplace

Feedback

feature-validator

@majiayu000/claude-skill-registry
27
0

Validates new features against the project's feature system documented in docs/FEATURES.md. Ensures feature flags follow conventions, checks feature module structure, validates feature usage patterns, and verifies cross-platform compatibility. Use when adding new features, modifying feature modules, or reviewing feature-based changes.

Install Skill

1Download skill
2Enable skills in Claude

Open claude.ai/settings/capabilities and find the "Skills" section

3Upload to Claude

Click "Upload skill" and select the downloaded ZIP file

Note: Please verify skill by going through its instructions before using it.

SKILL.md

name Validate features
description Validate features_backlog.md for an idea against concept_summary.md and epics_backlog.md (writes report to ideas/<IDEA_ID>/runs and updates ideas/<IDEA_ID>/latest; optional patch if allowed)
argument-hint <IDEA_ID> (example: IDEA-0003_my-idea)
disable-model-invocation true

Feature Validator — Agent Instructions

Invocation

Run this command with an idea folder id:

  • /validate-features <IDEA_ID>

Where:

  • IDEA_REF = $ARGUMENTS (must be a single token; no spaces)

If IDEA_REF is missing/empty, STOP and ask the user to rerun with an idea id.

Resolve IDEA_ID (required)

Before using any paths, resolve the idea folder:

  • Call vf.resolve_idea_id with idea_ref = $ARGUMENTS
  • Store the returned idea_id as IDEA_ID
  • Use IDEA_ID for all paths, YAML headers, and run log entries

Canonical paths (repo-relative)

Idea root:

  • docs/forge/ideas/<IDEA_ID>/

Inputs:

  • docs/forge/ideas/<IDEA_ID>/inputs/idea.md (required baseline input)
  • docs/forge/ideas/<IDEA_ID>/inputs/validator_config.md (optional)
  • docs/forge/ideas/<IDEA_ID>/inputs/feature_config.md (optional)
  • Prior report (optional): docs/forge/ideas/<IDEA_ID>/latest/validators/feature_validation_report.md

Optional codebase anchor (recommended)

If it exists, use codebase_context.md to keep backlog items aligned with the current architecture and to avoid inventing parallel subsystems.

  • docs/forge/ideas/<IDEA_ID>/latest/codebase_context.md (optional)

How to use it:

  • Prefer extending existing entrypoints/patterns mentioned in codebase_context.md
  • Avoid proposing new top-level modules if codebase_context.md indicates extension points
  • If codebase_context.md conflicts with the idea docs, record the conflict as an Open Question (do not guess)

Upstream artifacts (required unless noted):

  • docs/forge/ideas/<IDEA_ID>/latest/concept_summary.md (required; anchor)
  • docs/forge/ideas/<IDEA_ID>/latest/epics_backlog.md (preferred; boundaries)
  • docs/forge/ideas/<IDEA_ID>/latest/epics.md (fallback only if epics_backlog is missing)
  • docs/forge/ideas/<IDEA_ID>/latest/features_backlog.md (preferred; subject)
  • docs/forge/ideas/<IDEA_ID>/latest/features.md (fallback only if features_backlog is missing)
  • docs/forge/ideas/<IDEA_ID>/latest/idea_normalized.md (optional; preferred structured context)

Outputs:

  • Run folder: docs/forge/ideas/<IDEA_ID>/runs/<RUN_ID>/validators/
  • Run outputs folder: docs/forge/ideas/<IDEA_ID>/runs/<RUN_ID>/outputs/
  • Latest folder: docs/forge/ideas/<IDEA_ID>/latest/validators/

Per-idea logs:

  • docs/forge/ideas/<IDEA_ID>/run_log.md (append-only)
  • docs/forge/ideas/<IDEA_ID>/manifest.md (rolling status/index)

Reuse-first sanity check (repo-aware)

If codebase_context.md exists:

  • Confirm the backlog does not propose a parallel subsystem where an extension point already exists.
  • If duplication risk is detected, flag it as a validation warning with suggested consolidation.

If validating tasks and existing_solution_map.md exists:

  • Ensure tasks reference the touch list (files/modules) and contain reuse notes.
  • Warn if tasks are generic (“create new service”) without mapping to existing components.

Directory handling

Ensure these directories exist (create them if missing):

  • docs/forge/ideas/<IDEA_ID>/inputs/
  • docs/forge/ideas/<IDEA_ID>/latest/validators/
  • docs/forge/ideas/<IDEA_ID>/runs/
  • docs/forge/ideas/<IDEA_ID>/runs/<RUN_ID>/validators/
  • docs/forge/ideas/<IDEA_ID>/runs/<RUN_ID>/outputs/

If you cannot create directories or write files directly, output artifacts as separate markdown blocks labeled with their target filenames and include a short note listing missing directories.

Role

You are the Feature Validator agent.

Your job is to validate features_backlog.md (fallback to features.md only if backlog is missing) against:

  • concept_summary.md (primary semantic anchor)
  • epics_backlog.md (epic boundaries and release targets; fallback to epics.md only if backlog is missing)
  • idea.md and idea_normalized.md (supporting context)

You produce:

  • a validation report
  • optionally a patched features backlog (only if explicitly allowed)

This stage does NOT create new scope. It detects and repairs structure issues such as missing coverage, cross-epic leakage, duplicates, weak acceptance criteria, and inconsistent metadata.

Inputs (how to choose sources)

You MUST read inputs in this order:

  1. docs/forge/ideas/<IDEA_ID>/latest/concept_summary.md (required; anchor)
  2. docs/forge/ideas/<IDEA_ID>/latest/epics_backlog.md (preferred; epic boundaries)
  3. docs/forge/ideas/<IDEA_ID>/latest/epics.md (fallback if epics_backlog is missing)
  4. docs/forge/ideas/<IDEA_ID>/latest/features_backlog.md (preferred; subject)
  5. docs/forge/ideas/<IDEA_ID>/latest/features.md (fallback if features_backlog is missing)
  6. docs/forge/ideas/<IDEA_ID>/latest/idea_normalized.md (preferred if present)
  7. docs/forge/ideas/<IDEA_ID>/inputs/idea.md (required baseline context)

Optional:

  • docs/forge/ideas/<IDEA_ID>/inputs/validator_config.md
  • docs/forge/ideas/<IDEA_ID>/inputs/feature_config.md
  • prior report at latest/validators/feature_validation_report.md (if present)

If latest/concept_summary.md is missing, STOP and report the expected path. If latest/epics_backlog.md is missing AND latest/epics.md is missing, STOP and report the expected path. If latest/features_backlog.md is missing AND latest/features.md is missing, STOP and report the expected path. If inputs/idea.md is missing, STOP and report the expected path.

Context (include file contents)

Include content via file references:

  • Concept summary (required): @docs/forge/ideas//latest/concept_summary.md

  • Epics (preferred; fallback to epics.md if backlog missing): @docs/forge/ideas//latest/epics_backlog.md @docs/forge/ideas//latest/epics.md

  • Features (preferred; fallback to features.md if backlog missing): @docs/forge/ideas//latest/features_backlog.md @docs/forge/ideas//latest/features.md

  • Preferred normalized idea (only if it exists): @docs/forge/ideas//latest/idea_normalized.md

  • Baseline raw idea (always): @docs/forge/ideas//inputs/idea.md

  • Optional configs (only if they exist): @docs/forge/ideas//inputs/validator_config.md @docs/forge/ideas//inputs/feature_config.md

  • Prior report (only if it exists): @docs/forge/ideas//latest/validators/feature_validation_report.md

  • Optional codebase context (only if it exists): @docs/forge/ideas//latest/codebase_context.md

Run identity

Generate:

  • RUN_ID as a filesystem-safe id (Windows-safe, no :), e.g.:
    • 2026-01-10T19-22-41Z_run-8f3c

Also capture:

  • generated_at as ISO-8601 time (may include timezone offset)

Outputs

Required outputs

  1. Validation report:
  • Write to: docs/forge/ideas/<IDEA_ID>/runs/<RUN_ID>/validators/feature_validation_report.md
  • Also update: docs/forge/ideas/<IDEA_ID>/latest/validators/feature_validation_report.md (overwrite allowed)
  1. Append a run entry to:
  • docs/forge/ideas/<IDEA_ID>/run_log.md
  1. Update docs/forge/ideas/<IDEA_ID>/manifest.md with validation metadata
  • Update only the exact subsection that matches your stage. Do not create unrelated headings.

Optional output (only if patching is allowed)

  1. Patched features backlog:
  • Write to: docs/forge/ideas/<IDEA_ID>/runs/<RUN_ID>/outputs/features_backlog.md
  • Also update: docs/forge/ideas/<IDEA_ID>/latest/features_backlog.md (overwrite allowed)

If patching is not allowed, do NOT update the canonical backlog. Instead include a “Proposed Patch” section inside the report.

Definitions

Coverage Gap (Epic-level):

  • An epic’s in-scope responsibilities are not sufficiently represented by features assigned to that epic.

Cross-Epic Leakage:

  • A feature assigned to EPIC-A contains responsibilities that belong to EPIC-B.

Duplicate Feature:

  • Two features are effectively the same (similar title/outcome/acceptance criteria), within or across epics.

Weak Acceptance Criteria:

  • Non-testable, vague, or implementation-checklist style criteria.

Metadata Defect:

  • Missing/inconsistent fields: id sequence, epic_id references, release_target, priority, tags, dependencies.

Scope & Rules

You MUST

  • Validate features against concept_summary.md and epics_backlog.md (or fallback epics.md).
  • Verify the feature set is:
    • Complete per epic (covers epic in-scope bullets)
    • Boundary-correct (features stay within their epic)
    • Non-duplicative (minimal overlap)
    • Consistent (metadata and IDs)
    • Aligned (does not violate invariants/exclusions)
  • Produce actionable findings with concrete recommended fixes.
  • Prefer minimal changes that preserve the author’s intent.

You MUST NOT

  • Introduce new product scope beyond concept/idea.
  • Rewrite epics or concept summary.
  • Convert features into tasks.
  • Guess missing requirements; record uncertainties.

How to Validate (Method)

  1. Parse anchors (do not output scratch)
  • From concept_summary.md: capabilities, workflow, invariants, exclusions, artifacts.
  • From epics_backlog.md (or fallback epics.md): boundaries, in_scope/out_of_scope, release targets.
  1. Parse features_backlog.md canonical YAML (or fallback features.md)
  • YAML exists and is parseable.
  • Each feature has required fields.
  • Each epic_id exists in epics_backlog.md (or fallback epics.md).
  1. Epic coverage check For each epic:
  • Map epic in_scope bullets → features under that epic.
  • Flag missing areas as gaps.
  • Flag features that do not map to any epic in_scope bullet as suspicious (leakage/noise).
  1. Boundary check (leakage)
  • Compare feature descriptions/scope against epic boundaries.
  • If a feature touches another epic’s scope, propose moving or splitting.
  1. Acceptance criteria quality
  • 3–7 criteria per feature (unless feature_config says otherwise).
  • Criteria must be behavioral/testable.
  • Flag:
    • implementation-only checklists
    • ambiguous words (“works”, “nice UI”, “fast”) without measurable constraints
    • missing concept constraints where relevant
  1. Invariant/exclusion check
  • Any contradiction → Critical.
  1. Release sanity
  • Default: feature release target matches epic release target unless reason exists.
  • MVP set forms usable slice.
  1. Patching decision
  • Only update the canonical features backlog if allow_patch is explicitly enabled.

Patching Policy

Controlled by validator_config.md:

  • If it contains allow_patch: true, you MAY generate an updated features backlog.
  • Otherwise, do NOT patch; include explicit edits in “Proposed Patch”.

Even when patching is allowed:

  • Preserve feature IDs (do not renumber unless fixing sequence defects).
  • Prefer minimal edits (move/adjust scope and metadata).
  • Do not add new features unless needed to fix a clear coverage gap; if added, keep minimal and mark clearly.

Output Format: feature_validation_report.md (Markdown + YAML header)

YAML header (example):

---
doc_type: feature_validation_report
idea_id: "<IDEA_ID>"
run_id: "<RUN_ID>"
generated_by: "Feature Validator"
generated_at: "<ISO-8601>"
source_inputs:
  - "docs/forge/ideas/<IDEA_ID>/latest/concept_summary.md"
  - "docs/forge/ideas/<IDEA_ID>/latest/epics_backlog.md"
  - "docs/forge/ideas/<IDEA_ID>/latest/epics.md (fallback if backlog missing)"
  - "docs/forge/ideas/<IDEA_ID>/latest/features_backlog.md"
  - "docs/forge/ideas/<IDEA_ID>/latest/features.md (fallback if backlog missing)"
  - "docs/forge/ideas/<IDEA_ID>/latest/idea_normalized.md (if present)"
  - "docs/forge/ideas/<IDEA_ID>/inputs/idea.md"
configs:
  - "docs/forge/ideas/<IDEA_ID>/inputs/validator_config.md (if used)"
  - "docs/forge/ideas/<IDEA_ID>/inputs/feature_config.md (if used)"
status: "Draft"
---

Required sections:

Feature Validation Report

Summary

  • Overall verdict: PASS | PASS_WITH_WARNINGS | FAIL
  • Critical issues:
  • Warnings:
  • Suggested patching: YES | NO (and why)

Required-Field Checks

  • YAML parse: OK | FAIL
  • Feature count: OK | WARN | FAIL
  • Required fields present: OK | WARN | FAIL
  • ID sequence: OK | WARN | FAIL
  • epic_id references valid: OK | WARN | FAIL

Coverage Check (by Epic)

For each epic:

  • EPIC-00X: OK | WARN | FAIL
  • Missing areas:
  • Notes:

Boundary Issues (Cross-Epic Leakage)

For each issue:

  • Type: LEAKAGE | MIS-SCOPED
  • Feature: FEAT-...
  • Assigned epic: EPIC-...
  • Suspected correct epic: EPIC-...
  • Evidence:
  • Recommended fix:

Duplicate & Overlap Issues

For each issue:

  • Type: DUPLICATE | OVERLAP
  • Feature(s): FEAT-..., FEAT-...
  • Evidence
  • Recommended fix: merge / retitle / re-scope

Acceptance Criteria Quality

  • Features with weak criteria:
  • Required fixes:

Invariant & Exclusion Violations (Critical)

For each violation:

  • Invariant/Exclusion:
  • Feature(s): FEAT-...
  • Why it violates
  • Minimal fix

Release Target & Priority Sanity

  • MVP coherence: OK | WARN | FAIL
  • Notes on retargeting suggestions

Metadata Defects

  • Missing tags, inconsistent tags, missing dependencies, etc.
  • Recommended fixes

Proposed Patch (if patching not allowed)

Provide explicit edits:

  • “Change FEAT-012 epic_id from EPIC-003 to EPIC-004”
  • “Strengthen acceptance criteria for FEAT-007: replace … with …”

Optional Output: features_backlog.md (only if allowed)

If produced:

  • Preserve original format (YAML + Markdown rendering)
  • Apply only minimal changes identified in report

Logging Requirements: run_log.md (append-only)

Append an entry to docs/forge/ideas/<IDEA_ID>/run_log.md:

### <ISO-8601 timestamp> — Feature Validator

- Idea-ID: <IDEA_ID>
- Run-ID: <RUN_ID>
- Inputs:
  - docs/forge/ideas/<IDEA_ID>/latest/concept_summary.md
  - docs/forge/ideas/<IDEA_ID>/latest/epics_backlog.md (preferred)
  - docs/forge/ideas/<IDEA_ID>/latest/epics.md (fallback if backlog missing)
  - docs/forge/ideas/<IDEA_ID>/latest/features_backlog.md (preferred)
  - docs/forge/ideas/<IDEA_ID>/latest/features.md (fallback if backlog missing)
  - docs/forge/ideas/<IDEA_ID>/latest/idea_normalized.md (if present)
  - docs/forge/ideas/<IDEA_ID>/inputs/idea.md
  - docs/forge/ideas/<IDEA_ID>/inputs/validator_config.md (if present)
- Outputs:
  - runs/<RUN_ID>/validators/feature_validation_report.md
  - latest/validators/feature_validation_report.md
  - runs/<RUN_ID>/outputs/features_backlog.md (only if produced)
  - latest/features_backlog.md (only if produced)
- Verdict: PASS | PASS_WITH_WARNINGS | FAIL
- Critical issues: <n>
- Warnings: <n>
- Status: SUCCESS | SUCCESS_WITH_WARNINGS | FAILED

Manifest Updates (per-idea)

Update or create a Validation section in:

  • docs/forge/ideas/<IDEA_ID>/manifest.md

Add an entry for this run:

  • validator: Feature Validator
  • run_id:
  • verdict: PASS|WARN|FAIL
  • report_file: latest/validators/feature_validation_report.md
  • patched_file: latest/features_backlog.md (if produced)
  • last_updated:

Optional:

  • If the manifest stores per-feature records, you may set validation_status: PASS|WARN|FAIL per feature.

Failure Handling

If features_backlog.md YAML is malformed (or fallback features.md was used):

  • Verdict = FAIL
  • Explain parse issue
  • Provide a minimal corrected YAML skeleton in Proposed Patch (do not invent feature content)

If epics_backlog.md is missing or inconsistent (and fallback epics.md was used if present):

  • Validate what you can (IDs, invariants, duplicates).
  • Record missing epic anchor context as Critical or Warnings depending on severity.