urmzd/dotfiles / dot_agents/skills/check-project
check-project
UnverifiedValidate 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).
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/ | Should exist in every non-trivial project, laid out per scaffold-docs (run its check-docs-layout.sh) |
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 |
Node Supply-Chain Checks
Run when package.json exists. Report FAIL if violated:
| Check | Expected |
|---|---|
| Lockfile | pnpm-lock.yaml only; no package-lock.json, yarn.lock, bun.lock |
packageManager | pnpm@11.x pinned in package.json |
pnpm-workspace.yaml | Exists and sets minimumReleaseAge: 1440 or higher |
allowBuilds | Every entry is true or false; no set this to true or false placeholder |
| Overrides | In pnpm-workspace.yaml, not a pnpm field in package.json |
| CI install | pnpm install --frozen-lockfile; no npm ci, npm install, cache: npm |
| Framework checks | astro check scripts have @astrojs/check in devDependencies |
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
- Detect the project language from manifest files (Cargo.toml, go.mod, pyproject.toml, package.json, main.tf)
- Run all required file checks
- Run documentation completeness checks
- Run CI consistency checks
- Run optional directory checks based on detected project type
- If workspace detected, run sub-package checks on each publishable member
- Run README checks
- 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 `docs/README.md` and `docs/architecture/overview.md` per `scaffold-docs`
- [ ] Docs outside the `scaffold-docs` layout (stray root docs, loose files in docs/) -- move them per `scaffold-docs`
- [ ] 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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |