check-project

name	check-project
description	Validate project structure against scaffold conventions -- check for required files, CI consistency, documentation completeness, sub-package/workspace members, and optional directory usage, reporting PASS/WARN/FAIL with fix suggestions. Use to audit an existing project or verify a scaffold was applied correctly. Do NOT use to create or modify project files; this is a read-only auditor (use the scaffold-* skills to generate structure).
allowed-tools	Read, Grep, Glob, Bash(git *), Bash(gh *)
user-invocable	true
metadata	{"title":"Check Project","category":"development","order":5}

Check Project

Audit a project against the conventions defined in scaffold-project, write-readme, and the language-specific scaffold skills. Report PASS/WARN/FAIL per check with actionable fix suggestions.

Required Files

Every project must have these. Report FAIL if missing:

File	What to Check
README.md	Exists; has centered header block
AGENTS.md	Exists
LICENSE	Exists; contains "Apache"
CONTRIBUTING.md	Exists
CODE_OF_CONDUCT.md	Exists; Contributor Covenant 2.1 (see community-health)
SECURITY.md	Exists; has vulnerability reporting instructions; no unrendered {REPO} or {CURRENT_MAJOR} placeholders; contact matches $PROJECT_CONTACT or git config user.email
.github/pull_request_template.md	Exists; has Summary, Changes, Verification sections; no unrendered {CHECK_COMMAND} placeholder (see community-health)
.github/ISSUE_TEMPLATE/bug_report.yml	Exists; YAML issue form (see community-health)
.github/ISSUE_TEMPLATE/feature_request.yml	Exists; YAML issue form (see community-health)
.github/ISSUE_TEMPLATE/config.yml	Exists; blank_issues_enabled: false; contact links for security + discussions (see community-health)
sr.yaml	Exists; has git.tag_prefix: "v" and git.floating_tag: true
.envrc	Exists (direnv config: layout, dotenv, env vars, etc.)
llms.txt	Exists
skills/*/SKILL.md	At least one skill exists
.github/workflows/ci.yml	Exists (or terraform.yml for Terraform projects)
.github/workflows/release.yml	Exists (or terraform.yml for Terraform projects)

Documentation Completeness

Report WARN if missing:

File	Condition
docs/	Directory should exist in every non-trivial project
CHANGELOG.md	Should exist after first release (auto-generated by sr)
CODEOWNERS	Should exist for team projects with multiple contributors

CI Consistency

Check workflow files for convention compliance. Report FAIL if violated:

Check	Expected
ci.yml permissions	contents: read at workflow level
ci.yml workflow_call	Present in on: triggers
ci.yml concurrency	cancel-in-progress: true
release.yml concurrency	cancel-in-progress: false
release.yml CI gate	uses: ./.github/workflows/ci.yml
release.yml bot skip	github.actor != 'sr[bot]'
release.yml force dispatch	workflow_dispatch with force boolean input

Optional Directory Checks

Report WARN (not FAIL) when conventions suggest a directory should exist:

Condition	Expected
teasr.toml exists	showcase/ directory should exist
Project is a library (has pkg/, exports in package.json, or [project.scripts] in pyproject.toml)	examples/ directory should exist
Project has API routes or consumes external APIs	spec/ directory should exist
examples/ exists	examples/basic/ (or equivalent simplest example) should exist

README Checks

Report WARN if:

Check	Expected
Demo image path	References showcase/ (not assets/)
Quick Start section	Exists with "Quick Start" heading
fsrc markers	Not stale (content between markers matches referenced files)
Section order	Features before Installation before Quick Start

Sub-Package Checks

For workspace projects (Cargo workspace, npm workspaces, etc.), audit each publishable member. Report FAIL if missing:

Check	Expected
LICENSE in each workspace member	Exists; matches root LICENSE
README.md in each workspace member	Exists; has crate name as heading

Skip examples/ workspace members -- they are not published independently.

How to Run

1. Detect the project language from manifest files (Cargo.toml, go.mod, pyproject.toml, package.json, main.tf)
2. Run all required file checks
3. Run documentation completeness checks
4. Run CI consistency checks
5. Run optional directory checks based on detected project type
6. If workspace detected, run sub-package checks on each publishable member
7. Run README checks
8. Report results grouped by severity: FAIL first, then WARN, then PASS

Output Format

## Project Audit: {project-name}

### FAIL (must fix)
- [ ] Missing SECURITY.md -- create with vulnerability reporting instructions
- [ ] ci.yml missing `permissions: contents: read` -- add at workflow level

### WARN (should fix)
- [ ] Missing docs/ directory -- create with at least architecture.md
- [ ] teasr.toml exists but no showcase/ directory -- run `teasr showme`
- [ ] Library project without examples/ -- add examples/basic/ with minimal usage
- [ ] Missing CHANGELOG.md -- will be created on first `sr release`

### PASS
- [x] README.md with centered header
- [x] sr.yaml with floating_tag and v prefix
- [x] CI gates release, bot skip present
- [x] CONTRIBUTING.md present
- [x] llms.txt present