gpd-health

Run project health checks and auto-fix detected issues via the GPD CLI.

Updated Mar 18, 2026
One-click install
npx skills add https://github.com/MichaelsEngineering/sentinel-multiscale-field-dynamics --skill gpd-health-michaelsengineering
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: gpd-health
Source: https://github.com/MichaelsEngineering/sentinel-multiscale-field-dynamics/tree/main/.agents/skills/gpd-health
Command: npx skills add https://github.com/MichaelsEngineering/sentinel-multiscale-field-dynamics --skill gpd-health-michaelsengineering

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Project workspaces accumulate configuration drift, orphaned directories, invalid state files, and broken conventions over time, and manually auditing each of these is slow and error-prone. This Skill runs a comprehensive health check across the project and can automatically repair detected issues. ## Core Features & Use Cases - Comprehensive Health Checks: Validates environment, project structure, storage-path policy, state validity, compaction, roadmap consistency, orphaned phase directories, convention lock integrity, plan frontmatter, return envelopes, config.json validity, checkpoint tags, and git status. - Optional Auto-Fix: Pass the --fix flag to automatically repair fixable issues instead of only reporting them. - Structured Reporting: Presents results as a status table with pass/warn/fail per check plus a summary of totals, warnings, failures, and fixes. - Use Case: Before starting a new work phase, run the health check to confirm state files and configuration are valid, then rerun with --fix to clean up orphaned phase directories and repair frontmatter. ## Quick Start Ask the AI to run a project health check, or to run it with the fix flag to automatically repair detected issues.

Frequently Asked Questions about gpd-health

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run a project health check with auto-fix?▼

Invoke the skill with the --fix flag, for example $gpd-health --fix. The skill detects the flag in the arguments and calls the GPD CLI health command with --fix, which repairs fixable issues and reports how many were auto-fixed.

What does the GPD health check actually validate?▼

The health check validates environment, project structure, storage-path policy, state validity, compaction, roadmap consistency, orphaned phase directories, convention lock integrity, plan frontmatter, the latest return envelope, config.json validity, checkpoint tags, and git status.

Why does the skill use a pinned Python path instead of the gpd command?▼

The ambient gpd on PATH may not match the Codex runtime, so the skill calls /home/qol/.gpd/venv/bin/python -m gpd.runtime_cli with explicit runtime, config-dir, and install-scope arguments. This keeps the CLI invocation consistent with the Codex environment.

What happens if the health check command fails to execute?▼

If the CLI exits with a non-zero status, the skill prints an error message containing the command output and stops with exit code 1. No report table is rendered in that case, so you should resolve the CLI failure first.

Can I see which issues are fixable before running auto-fix?▼

Yes. Run the health check without --fix first; the output lists each check with pass, warn, or fail status and tells you how many issues can be auto-repaired. You can then decide whether to rerun with --fix.