# Project Health

> >

- **Type:** Skill
- **Install:** `agentstack add skill-mdproctor-cc-praxis-project-health`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mdproctor](https://agentstack.voostack.com/s/mdproctor)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [mdproctor](https://github.com/mdproctor)
- **Source:** https://github.com/mdproctor/cc-praxis/tree/main/project-health

## Install

```sh
agentstack add skill-mdproctor-cc-praxis-project-health
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Project Health

Answer the question: **is this project correct, complete, and consistent?**

Runs universal quality checks that apply to every project type, then runs
type-specific health checks inline based on the project type declared in CLAUDE.md.

---

## Step 0 — Read Project Type

Before any checks run, read the project type:

```bash
python3 ~/.claude/skills/project-init/ctx.py
```

Read `PROJECT_TYPE` from the output.

Extract the type: `skills` | `java` | `blog` | `custom` | `generic`

If `PROJECT_TYPE` is empty, treat as `generic` and note it as a `config` finding.

Store the type — type-aware checks (`primary-doc`, `artifacts`, `conventions`,
`framework`) use it throughout this skill.

---

## Step 1 — Determine Tier

Parse flags from the invocation:

| Flag | Tier | What runs |
|------|------|-----------|
| `--commit` | 1 | `validate_all.py --tier commit` only |
| `--standard` | 2 | Universal quality checks |
| `--prerelease` | 3 | Universal + type-specific quality checks |
| `--deep` | 4 | All of tier 3 + refinement questions |
| `--tier N` | N | Explicit tier (1–4) |

If no tier flag is given, prompt:

> **How thorough should this check be?**
>
> 1 — **Quick** — validators only (~30s)
> 2 — **Standard** — universal quality checks (~5 min)
> 3 — **Full** — universal + type-specific quality (~15 min)
> 4 — **Deep** — everything + refinement questions (~30 min)
>
> Enter 1–4 (default: 2):

Wait for response. If no response, use tier 2.

Also parse:
- `--save` → write report to `YYYY-MM-DD-health-report.md` after output
- Category names (e.g. `docs-sync consistency`) → run only those categories
- If categories specified without `--tier`, run at tier 2

---

## Step 2 — Tier 1: Run Automated Validators

**Always run first** (all tiers include this):

```bash
python scripts/validate_all.py --tier commit
```

If this script doesn't exist, note it as a `config` finding and skip.

Report output. If CRITICAL findings from validators → flag them.

For tier 1, **stop here**. Present findings and exit.

---

## Step 3 — Build Document Scan List

For tier 2+, build the scan scope before running checks.

**Always included:**
- All `.md` files (recursive) under `doc/`, `docs/`, `documentation/` (case-insensitive)
- Root-level `.md` files matching: `readme`, `overview`, `summary`, `index`, `contributing`,
  `governance`, `code_of_conduct`, `changelog`, `history`, `release`, `architecture`,
  `design`, `decisions`, `vision`, `philosophy`, `principles`, `api`, `schema`, `glossary`,
  `security`, `deployment`, `install`, `usage`, `troubleshooting`, `roadmap`, `spec`,
  `requirements`, `quality` (case-insensitive match on filename stem)
- Any root `.md` not on the list is still scanned
- Any `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, `ARCHITECTURE.md` anywhere in the tree

**Type-specific additions (use detected type from Step 0):**
- `skills` → all `SKILL.md` files in direct subdirectories
- `java` → `pom.xml`, `build.gradle`, Javadoc comments in `src/`
- `blog` → `_config.yml`, `_posts/`, `_layouts/`, `_includes/`
- `custom` → primary document path declared in CLAUDE.md

**User-configured additions:**
Read `## Health Check Configuration` from CLAUDE.md:
```
Additional doc paths: wiki/, design/
```
Add any listed paths to the scan scope.

---

## Step 4 — Read CLAUDE.md Health Configuration

```bash
grep -A 10 "## Health Check Configuration" CLAUDE.md 2>/dev/null
```

Parse:
- `Default checks:` → limit to these categories if no categories specified on invocation
- `Skip:` → exclude these categories even if requested
- `Additional doc paths:` → already applied in Step 3

If no configuration section, use built-in defaults: run all universal categories.

---

## Step 5 — Run Universal Checks

Run the applicable check categories at the requested tier. Skip categories listed
in `Skip:` from CLAUDE.md. If specific categories were requested, run only those.

For **tier 2**: quality items only (pass/fail checks).
For **tier 4**: quality items + refinement questions (judgment items).

**Read [check-categories.md](check-categories.md)** for the full quality and
refinement checklists for all 12 universal categories before running checks:
`docs-sync`, `consistency`, `logic`, `config`, `security`, `release`,
`user-journey`, `git`, `primary-doc`, `artifacts`, `conventions`, `framework`.

---

## Step 6 — Run Type-Specific Checks (Tier 3+)

At tier 3 and 4, after universal checks complete, read the type-specific content file
and execute the checks it describes. Type-specific findings are prefixed with `[type]`
(e.g. `[java]`).

| Project type | File to read |
|---|---|
| `skills` | `~/.claude/skills/project-health/skills-repo.md` |
| `java` | `~/.claude/skills/project-health/java.md` |
| `blog` | `~/.claude/skills/project-health/blog.md` |
| `custom` | `~/.claude/skills/project-health/custom.md` |
| `python` | `~/.claude/skills/project-health/python.md` |
| `ts` / TypeScript detected | `~/.claude/skills/project-health/typescript.md` |
| `generic` | Skip — universal checks only |

Read the file, then execute the checks described in it.

If the project type is `generic` but TypeScript or Python files are found, suggest
running the relevant section manually.

---

## Step 7 — Present Report

```
## project-health report — [categories run] — tier [N]

### CRITICAL (must fix)
- [category] finding description

### HIGH (should fix)
- [category] finding description

### MEDIUM (worth fixing)
- [category] finding description

### LOW (nice to fix)
- [category] finding description

### PASS
✅ category1, category2, ...
```

Universal findings have no extra prefix. Type-specific findings are prefixed
with `[type]` (e.g. `[java]`). If no findings in a severity level, omit that section.

---

## Step 8 — Offer Auto-Fix (Mechanical Issues Only)

For mechanical findings (wrong count in README, stale version number, missing
`commands/.md`), offer:

> **Auto-fixable findings detected.**
>
> Would you like me to apply mechanical fixes now?
> - [list of specific fixes]
>
> **(YES / NO — judgment calls are never auto-applied)**

Wait for response. Apply only on YES. Never auto-apply.

---

## Step 9 — Save Report (if --save)

If `--save` was passed, write findings to a date-prefixed file:

```bash
# Format: YYYY-MM-DD-health-report.md
```

Tell user:
> Report saved to `YYYY-MM-DD-health-report.md`. This file is gitignored by default.

Verify `.gitignore` includes `*-health-report.md` or similar. If not, suggest adding it.

---

## Common Pitfalls

| Mistake | Why It's Wrong | Fix |
|---------|----------------|-----|
| Running type-specific checks before reading project type | Checks have no context | Always read project type in Step 0 first |
| Reporting "plans to implement" as bugs | Intentional design language | Distinguish docs describing intent vs. describing current state |
| Auto-fixing judgment findings | Judgment calls require human decision | Only auto-fix mechanical findings, always with YES confirmation |
| Skipping type-specific section at tier 3+ | Incomplete health picture | Run the type-specific section — it's mandatory at tier 3+ unless type is generic |
| Treating all findings as equal | CRITICAL blocks release, LOW does not | Use severity consistently |
| Running `docs-sync` without reading the actual source files | Can't verify claims without reading | Read code and docs together |

---

## Success Criteria

Health check is complete when:

- ✅ Project type read from CLAUDE.md before any checks ran
- ✅ Tier confirmed (via flag or prompt)
- ✅ All applicable universal categories checked at the requested tier
- ✅ Type-specific section run at tier 3+ (or skipped for generic)
- ✅ Report presented with findings grouped by severity
- ✅ Mechanical auto-fix offered (not applied without YES)
- ✅ Report saved if `--save` was passed

**Not complete until** all applicable categories checked and report presented.

---

## Skill Chaining

**Invoked by:**
- User says "health check", "is the project healthy", "pre-release check", or invokes `/project-health`
- Other skills (e.g. `git-commit`) can suggest `/project-health --commit` after significant changes

**Companion skill:**
- [`project-refine`] — once health is green, use project-refine for improvement opportunities (bloat, structure, deduplication). They share the same CLAUDE.md Health Check Configuration section.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [mdproctor](https://github.com/mdproctor)
- **Source:** [mdproctor/cc-praxis](https://github.com/mdproctor/cc-praxis)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-mdproctor-cc-praxis-project-health
- Seller: https://agentstack.voostack.com/s/mdproctor
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.