validating-readmes

Validates that project structure documented in README.md accurately reflects the actual filesystem structure

Tool Paths: Commands in this skill use default Windows paths from {directories.config}/tools.json. See Configuration Guide to customize for your environment.

Purpose

Validates that the project structure documented in README.md accurately reflects the actual filesystem structure. This skill ensures documentation stays synchronized with the codebase as the project evolves.

Process

1. Review the task requirements.
2. Apply the skill's methodology.
3. Validate the output against the defined criteria.

Step 1: Run Validation Check

Execute the validation script to check if README matches actual structure:

C:\App\Anaconda\python.exe {directories.scripts}/validate_readme_structure.py --check

Expected output if valid:

✓ README project structure is up to date
  agents: 7
  skills: 18
  blueprints: 14
  patterns: 48
  knowledge: 42
  templates: 163

Expected output if invalid:

✗ README project structure is OUT OF DATE

Discrepancies found:
  - skills: README says 14, actual is 18
  - blueprints: README says 7, actual is 14

Step 2: Review Discrepancies

If discrepancies are found, review what changed:

# Generate current structure to see what's different
C:\App\Anaconda\python.exe {directories.scripts}/validate_readme_structure.py --generate

Step 3: Update README

If discrepancies are legitimate (new components added), update the README:

C:\App\Anaconda\python.exe {directories.scripts}/validate_readme_structure.py --update

This automatically updates the Project Structure section in README.md.

Step 4: Verify Update

Run validation again to confirm the update was successful:

C:\App\Anaconda\python.exe {directories.scripts}/validate_readme_structure.py --check

Integration Points

Pre-Commit Hook

Add to .git/hooks/pre-commit (or use pre-commit framework):

#!/bin/bash
python {directories.scripts}/validate_readme_structure.py --check
if [ $? -ne 0 ]; then
    echo "README structure validation failed. Run: python {directories.scripts}/validate_readme_structure.py --update"
    exit 1
fi

CI/CD Integration

The validation is integrated into .github/workflows/ci.yml:

- name: Validate README Structure
  run: python {directories.scripts}/validate_readme_structure.py --check

Manual Workflow

When extending the factory with new components:

1. Add your new agent/skill/blueprint/etc.
2. Run --check to see the discrepancy
3. Run --update to fix README
4. Commit both the new component AND the updated README

Command Reference

| Command | Description | ||-| | --check | Validate README against actual structure (default) | | --generate | Print the correct structure markdown | | --update | Update README.md in place | | --json | Output scan results as JSON (for tooling) | | --root PATH | Specify project root directory |

What Gets Scanned

| Component | Location | Counted | |--|-|| | Agents | {directories.agents}/*.md | Number of .md files | | Skills | {directories.skills}/*/SKILL.md | Directories with SKILL.md | | Blueprints | {directories.blueprints}/*/blueprint.json | Directories with blueprint.json | | Patterns | {directories.patterns}/**/*.json | All JSON files in subdirectories | | Knowledge | {directories.knowledge}/*.json | All JSON files | | Templates | {directories.templates}/**/*.tmpl | All .tmpl files |

Error Handling

• README not found: Script reports error and exits with code 1
• Structure section not found: Script warns and exits with code 1
• Permission errors: Standard Python permission error handling

Relationship to Factory Components

This skill supports the factory's documentation-first approach:

• Agents use this skill via the onboarding-architect when validating project state
• CI/CD runs this automatically on every pull request
• Developers run this before commits to catch documentation drift

Best Practices

• Run validation before every commit to catch drift early
• Integrate validation into pre-commit hooks for automated checks
• Keep README structure section as single source of truth
• Update README immediately when adding new components
• Use --check in CI to fail builds with outdated documentation
• Document any intentional discrepancies with comments
• Review structure changes during code review

References

• Script: {directories.scripts}/validate_readme_structure.py
• CI Config: .github/workflows/ci.yml
• README: README.md (Project Structure section)

When to Use

This skill should be used when strict adherence to the defined process is required.

Prerequisites

• Basic understanding of the agent factory context.
• Access to the necessary tools and resources.