project-health-diagnostics
Skill4 starsChanged 3 months agoMITView on GitHub
Autonomous project health audit engine that computes a Token Adherence Index (TAI) score (0–100), maps quality gaps to specific Agentway skills, and generates a structured Health Report Card with a prioritized prescription queue. Use when: health check, diagnose project, TAI score, what skills do I need, agentway doctor, project quality audit, skill recommender.
In this repository46 other files it gives its agents.
- accessibility-reviewSkill
- accessibility-runtime-auditSkill
- adaptive-component-behaviorSkill
- ai-feature-ux-patternsSkill
- behavioral-pricing-psychologySkill
- business-model-readingSkill
- business-model-thinkingSkill
- cognitive-load-heatmap-predictionSkill
- component-style-guideSkill
- cross-functional-reviewSkill
- dark-mode-theming-systemSkill
- dashboard-layout-patternsSkill
- dashboard-scaffolding-contractSkill
- design-drift-detectorSkill
- design-system-builderSkill
- design-to-code-handoffSkill
- design-tokensSkill
- error-boundary-resilience-designSkill
- flow-based-functional-testingSkill
- growth-impact-reviewSkill
- i18n-localization-strategySkill
- information-architectureSkill
- interactive-element-auditSkill
- kinematic-motion-choreographySkill
- micro-interaction-motion-designSkill
- module-registry-syncSkill
- mvp-scopingSkill
- perceived-performance-loadingSkill
- prd-traceability-matrixSkill
- product-discoverySkill
- product-strategySkill
- qa-feedback-loop-orchestratorSkill
- responsive-breakpoint-strategySkill
- responsive-qa-auditSkill
- route-integrity-checkerSkill
- security-privacy-reviewSkill
- stakeholder-requirement-mappingSkill
- touch-gesture-interactionSkill
- typography-systemSkill
- usability-heuristics-checkSkill
- user-flow-mappingSkill
- user-research-synthesisSkill
- ux-chaos-monkeySkill
- visual-hierarchy-reviewSkill
- visual-responsive-regression-testingSkill
- visual-style-extractorSkill
The file
Files
🩺 Skill: Project Health Diagnostics
Purpose
After months of AI-assisted development, codebases silently drift. Components bypass design tokens. Accessibility gaps accumulate. Error states get skipped. This skill gives agents the ability to run a structured diagnostic and prescribe exactly what's missing — turning "something feels off" into an actionable, scored health report.
Trigger Phrases
| Phrase | Activation |
| "health check" / "health report" | ✅ |
| "diagnose my project" / "audit this codebase" | ✅ |
| "TAI score" / "token adherence" | ✅ |
| "what skills do I need?" | ✅ |
| "agentway doctor" | ✅ |
| "what's missing from my design system?" | ✅ |
| "project quality audit" | ✅ |
Protocol: 5-Step Diagnostic Engine
STEP 1 — Scan (2–3 turns)
Detect the project's current state across 5 signal categories:
SIGNAL A: Token Architecture
- Are CSS custom properties used? (var(--color-*), var(--space-*))
- Is there a token file? (tokens.css, design-tokens.json, theme.ts)
- Token coverage estimate: % of color/spacing/type using tokens vs hardcoded
SIGNAL B: WCAG Compliance
- Presence of aria-*, role=*, alt="", tabindex
- Color contrast annotations in component comments
- Focus state styles (:focus-visible)
- Skip navigation links
SIGNAL C: Resilience Coverage
- Are empty/loading/error/offline/partial states handled in components?
- Is there an Error Boundary component?
- Are network failure states covered (offline queue, timeout fallback)?
SIGNAL D: Responsive Architecture
- Breakpoint system defined? (@media, container queries)
- Mobile-first CSS cascade?
- Touch target minimum sizes (44×44px)?
- Adaptive component transformations (sidebar → bottom-nav)?
SIGNAL E: AI Drift Indicators
- Frequency of hardcoded hex colors, px values, magic numbers
- Ratio of var(--token) vs literal values in stylesheets
- Presence of z-index: 9999 or !important flagsSTEP 2 — Score: Token Adherence Index (TAI)
Compute the TAI score using the weighted formula:
TAI = (token_coverage × 0.40) +
(wcag_score × 0.25) +
(resilience_cover × 0.20) +
(responsive_score × 0.15)
Each sub-score: 0–100 based on signal presence and coverage
Grade Thresholds:
90–100 → 🟢 Excellent (production-ready, autonomous AI-safe)
70–89 → 🟡 Good (minor gaps, advisory remediation)
50–69 → 🟠 Needs Work (significant gaps, blocking issues)
0–49 → 🔴 Critical (design system not enforced, high drift risk)STEP 3 — Identify: Gap Mapping
For each sub-score below threshold, map to the responsible Agentway skill:
| Sub-Score Low | Root Cause | Prescribe |
| Token Coverage < 80% | No token architecture | design-tokens (P0) |
| WCAG Score < 75% | Accessibility gaps | accessibility-review (P0) |
| Resilience Coverage < 70% | Missing state contracts | error-boundary-resilience-design (P1) |
| Responsive Score < 70% | No breakpoint system | responsive-breakpoint-strategy (P1) |
| Any hardcoded values > 10% | AI drift detected | design-drift-detector (P0) |
| No motion tokens | Animation inconsistency | micro-interaction-motion-design (P2) |
| No dark mode tokens | Theme system absent | dark-mode-theming-system (P2) |
STEP 4 — Prescribe: Skill Activation Queue
Output a prioritized prescription using this priority model:
P0 — CRITICAL: Run immediately. Blocks production quality.
P1 — HIGH: Run in current sprint. Significant UX impact.
P2 — MEDIUM: Run in next sprint. Polish and consistency.
P3 — LOW: Run when capacity allows. Nice-to-have improvement.STEP 5 — Report: Generate Health Report Card
Produce two artifacts:
health-report.md — Human-readable with:
- TAI Score badge (0–100 with grade emoji)
- Radar breakdown (token / WCAG / resilience / responsive)
- Top 3 critical gaps with 1-line explanations
- Prioritized prescription table
health-report.json — Machine-readable for CI integration:
{
"version": "1.6.0",
"scannedAt": "ISO8601",
"tai": { "score": 74, "grade": "Good",
"breakdown": { "tokenCoverage": 82, "wcagScore": 78,
"resilienceCoverage": 65, "responsiveScore": 71 }},
"drift": { "critical": 3, "high": 7, "medium": 12, "low": 4 },
"prescription": [
{ "skill": "design-tokens", "priority": "P0",
"reason": "Token coverage 63% — below 80% threshold" }
]
}Diagnostic Reference Thresholds
| Sub-Metric | Green (≥) | Yellow (≥) | Red (<) |
| Token Coverage | 85% | 70% | 70% |
| WCAG Score | 80% | 65% | 65% |
| Resilience Coverage | 75% | 55% | 55% |
| Responsive Score | 75% | 60% | 60% |
| AI Drift Rate | < 5% | < 15% | ≥ 15% |
CI Integration Pattern
# .github/workflows/quality-gate.yml
- name: Run Agentway Health Check
run: agentway doctor ./ --json > health-report.json
continue-on-error: true # Advisory in v1.6.0
- name: Check TAI Threshold
run: |
TAI=$(node -e "console.log(require('./health-report.json').tai.score)")
echo "TAI Score: $TAI"
if [ "$TAI" -lt 60 ]; then
echo "⚠️ TAI score below 60 — review health-report.json"
fiCompanion Skills
| Skill | Relationship |
design-drift-detector | Runs automatically as part of TAI scan (Signal E) |
design-tokens | Most commonly prescribed for token_coverage gaps |
accessibility-review | Prescribed when WCAG score is red |
error-boundary-resilience-design | Prescribed when resilience coverage is low |
responsive-breakpoint-strategy | Prescribed when responsive score is low |
ux-chaos-monkey | Prescribed when drift rate is high (AI hallucination risk) |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

