check-project git:20261029.73191d5A

Immutable. This exact content never changes and is served at /api/v1/blob/780418786491558e.

---
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/` | 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 |

## 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

```text
## 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
```