Validate Cc

validate-cc -- CC Configuration Quality Validation

Corresponding rules: docs/specs/rule-writing.md, docs/specs/skill-design.md, docs/specs/agent-design.md, docs/specs/settings-design.md

Purpose

Validates only the items that exist in the project. Categories that do not exist are automatically omitted from the report. For categories that do exist, provides PASS/FAIL results and statistics per category.

Input

• Target directory: current project root (auto-detected)
• No additional input required

Verification criteria

Categories whose target directory does not exist (e.g., .claude/agents/ missing) are automatically omitted from the report.

1. CLAUDE.md

• EXISTS: CC automatically loads CLAUDE.md into context at session start (CC_OFFICIAL)
• STRUCTURE: Tech Stack/Architecture sections prevent Claude from guessing the tech stack (EMPIRICAL)
• DEPTH: 3 or more sections provide sufficient project orientation (EMPIRICAL)

2. Rules

• DIR: CC auto-loads .md files from the rules/ directory (CC_OFFICIAL)
• FILES: a meaningful rule system requires at least 2 files (EMPIRICAL)
• META: WHY/CONSTRAINT enable rule-priority judgment and awareness of violation severity (EMPIRICAL)
• SCOPING: explicit scope prevents indiscriminate rule application (EMPIRICAL)

3. Skills

• DIR: CC recognizes SKILL.md in the skills/ directory (CC_OFFICIAL)
• FRONTMATTER: without frontmatter, CC cannot recognize the skill (CC_OFFICIAL)
• RULE_SKILL_RATIO: Rules without a Skill cannot be automatically validated (EMPIRICAL)
• GATE: skills without execution gates allow the AI to skip verification depth (EMPIRICAL)
• Methodology rule exception: Rules marked [M] (methodology rules such as c-suite-analysis, question-principles, research) are excluded from the Rule-Skill ratio calculation. These rules define analysis/research methodologies consumed by skills like /discovery, not CC behavior constraints requiring a dedicated validation skill.

4. Agents

• DIR: CC recognizes agent definitions in the agents/ directory (CC_OFFICIAL)
• FILES: at least 1 agent is required for automated code review/analysis (EMPIRICAL)
• ALLOWED_TOOLS: allowed_tools restricts the agent's tool scope (CC_OFFICIAL)

5. Settings

• EXISTS: settings.json controls tool permissions and hooks (CC_OFFICIAL)
• DENY: deny takes precedence over allow, reliably blocking dangerous operations (CC_OFFICIAL)
• HOOK: PreToolUse/PostToolUse hooks automate verification before and after tool execution (CC_OFFICIAL)

6. README.md

• EXISTS: README.md is the project entry point providing installation/run guidance (INDUSTRY_STD)
• CONTENT: at least 3 sections are required to cover basic guidance such as install, run, and test (INDUSTRY_STD)

7. Commands

• DIR: CC recognizes commands in the commands/ directory (CC_OFFICIAL)
• NAMING: the action should be immediately inferable from the name alone (EMPIRICAL)
• SINGLE_ACTION: with branching/looping present, conversion to a skill is recommended (EMPIRICAL)

Mandatory output: Category verification matrix

Output the following matrix before grade calculation. Every cell must be filled. If any cell is empty, do not proceed to grading.

Status values: PASS (verified clean), NOT_APPLICABLE (category directory not found -- omitted from report), SKIPPED (plugin issue), SHALLOW (partial check)

Grade criteria

Execution logic

1. Detect current project root (search for CLAUDE.md or .claude/ via Glob)
2. Discover existing categories (omit categories that do not exist)
3. Verify category-specific items using Read/Glob/Grep:
   • Glob to confirm file/directory existence
   • Read to read file contents
   • Grep for pattern matching (WHY, CONSTRAINT, paths:, etc.)
4. PASS/WARN/FAIL determination and statistics aggregation per item
5. Determine grade
6. Generate improvement suggestions

Output

Produce the validation report in the user's conversation language.

Output the validation results in the following format:

CC Configuration Quality Report
==================================================

[PASS] CLAUDE.md (3/3)
  [v] Existence
  [v] Structure
  [v] Technical depth

[WARN] Rules (3/4)
  [v] Directory
  [v] File count
  [!] WHY/CONSTRAINT -- 50% coverage
  [v] Scoping

[PASS] Skills (3/3)
  [v] Directory
  [v] Frontmatter
  [v] Rule-Skill ratio

[PASS] Settings (3/3)
  [v] Existence
  [v] Deny
  [v] Hook

[PASS] README.md (2/2)
  [v] Existence
  [v] Content

--------------------------------------------------
Total: 14/15 passed | 1 warning | 0 failures
Grade: Good

Improvement suggestions: 1
  - Add WHY metadata to rules

In the example above, the Agents category is automatically omitted because the .claude/agents/ directory does not exist.

Icon convention

Pre-output checklist (required before final output)

Verify every item before drafting the report. If any item is unchecked, go back and complete it.

• Every category has a Status value assigned (no empty Status cells)
• Every category whose Status != NOT_APPLICABLE has an Evidence value
• Categories that do not exist have Status NOT_APPLICABLE
• Grade calculation matches the grade criteria table
• Report language matches the user's conversation language

Schema compliance check (required before persisting to .ww-w-ai/standards/)

Verify the JSON output before writing to .ww-w-ai/standards/validate-cc/:

• All "required" fields in schema.json are present and non-empty
• categories[] array length matches the number of categories checked
• summary.total == summary.passed + summary.warnings + summary.failures

Output persistence

After generating the validation report, persist results to .ww-w-ai/standards/validate-cc/:

1. Create the .ww-w-ai/standards/validate-cc/ directory if it does not exist
2. Write latest.json -- structured result following templates/schema.json
3. Write latest.md -- human-readable report following templates/report.template.md
4. Archive to history/ -- copy latest.json to .ww-w-ai/standards/validate-cc/history/{timestamp}.json

latest.md is produced in the user's conversation language. JSON field names remain in English regardless of language. The JSON output enables machine-parseable history tracking and cross-run comparison. The history/ directory preserves prior runs for trend analysis.

Permission rationale

• Write: restricted to .ww-w-ai/standards/ output persistence. No modification of project source.
• Bash: restricted to read-only git/system queries. No file modification.

Notes

• Bash is permitted for directory creation (mkdir -p .ww-w-ai/standards/validate-cc/history) and Grep pattern matching.
• Detailed improvement guidance is provided by the /audit skill.

Spec references

Detailed verification criteria, evidence tables, examples:

• Corresponding rule specs: ../../docs/specs/rule-writing.md, ../../docs/specs/skill-design.md, ../../docs/specs/agent-design.md, ../../docs/specs/settings-design.md, ../../docs/specs/claude-md-design.md, ../../docs/specs/readme-design.md, ../../docs/specs/commands-design.md
• Evidence index: ../../docs/evidence/evidence-registry.md