Skill: Validate Repo

Description

Runs a comprehensive health check against a generated project or any repo that follows the Foundry structure. Verifies folder expectations, required files, template completeness, broken internal links, and stack-specific tooling (lint, test, build commands). Produces a pass/fail checklist with actionable remediation for every finding. This skill works on any project regardless of stack because it adapts its checks based on the composition spec.

Trigger

•Invoked by the /validate-repo slash command.
•Can be run at any point during a project's lifecycle as a health check.
•Useful as a pre-export gate before sharing a generated project.

Inputs

Input	Type	Required	Description
project_dir	Directory path	Yes	Root of the project to validate
composition_spec	YAML file path	No	Composition spec; defaults to `ai/team/composition.yml` in the project
check_level	Enum: `structure`, `content`, `full`	No	Depth of validation; defaults to `full`

Process

•Locate composition spec -- Find and parse ai/team/composition.yml from the project directory. If missing, run structural checks only.
•Validate folder structure -- Confirm all expected directories exist: .claude/agents/, ai/context/, ai/generated/members/, ai/team/, ai/tasks/, ai/outputs/.
•Check required files -- Verify CLAUDE.md, README.md, ai/team/composition.yml exist and are non-empty.
•Validate agent completeness -- For each persona in the composition, confirm .claude/agents/{id}.md and ai/generated/members/{id}.md exist.
•Check output directories -- Verify ai/outputs/{id}/ exists for each persona.
•Scan for broken internal links -- Parse all markdown files for relative links and verify targets exist on disk.
•
Run stack-specific checks -- Based on the stacks in the composition:
- •python: Check for pyproject.toml or setup.py; verify pytest or test command is runnable.
- •node/react/typescript: Check for package.json; verify npm test or equivalent exists.
- •java: Check for pom.xml or build.gradle.
- •dotnet: Check for *.csproj or *.sln.
- •Other stacks: Check for common entry points.
•Check for secrets exposure -- Scan for .env files, hardcoded API keys, or credentials patterns in tracked files.
•Verify manifest consistency -- If ai/generated/manifest.json exists, confirm the files it lists still exist on disk.
•Produce validation report -- Generate a checklist with pass/fail/warn per check and remediation guidance for failures.

Outputs

Output	Type	Description
validation_report	Markdown file	Structured checklist with status per check and remediation steps
exit_code	Integer	0 if all checks pass, 1 if any errors, 2 if warnings only

Quality Criteria

•Every check produces a clear pass, fail, or warn verdict with no ambiguous states.
•Failed checks include specific remediation: what file to create, what command to run, what to fix.
•Stack-specific checks only run for stacks listed in the composition; missing stacks do not produce false failures.
•The report is sorted by severity: errors first, then warnings, then passes.
•Running validation on a freshly-generated project produces zero errors and zero warnings.

Error Conditions

Error	Cause	Resolution
`ProjectDirNotFound`	The specified directory does not exist	Check the path
`NotAFoundryProject`	No `CLAUDE.md` or `ai/` directory found	Verify this is a Foundry-generated project
`CompositionParseError`	The composition spec is malformed	Fix the YAML in `ai/team/composition.yml`
`StackCheckUnavailable`	A stack-specific tool is not installed	Install the required tool or skip stack checks with `--check-level structure`

Dependencies

•foundry_app/services/validator.py -- existing validation logic for composition and library checks
•foundry_app/services/export.py -- validate_generated_project() for structural checks
•Access to the project directory's filesystem
•Stack-specific tooling (pytest, npm, etc.) for full validation