skill(project-instructions-health): Task #114 — instructions health checker
10-check validation suite that compares project instructions against live infrastructure: server connectivity + IPs, MCP connectors, Gitea repos + branches, Arbiter health, database access, subscription tiers, website deploy pipeline, policy page content, clone size (post-#101), and stale reference scan (Ghost, Paymenter, SSH blocked, Founder tier, sparse checkout). Designed to run at session start or after infrastructure changes. Reports as PASS/WARNING/FAIL with concrete action items. Chronicler #81
This commit is contained in:
Claude
225
docs/skills/project-instructions-health/SKILL.md
Normal file
225
docs/skills/project-instructions-health/SKILL.md
Normal file
@@ -0,0 +1,225 @@
|
||||
---
|
||||
name: project-instructions-health
|
||||
description: |
|
||||
Validate Claude Project instructions against live infrastructure state. Use this skill whenever:
|
||||
- Starting a new session and wanting to verify instructions are current
|
||||
- After deploying infrastructure changes (new servers, new services, changed IPs)
|
||||
- After adding or removing MCP connectors
|
||||
- After changing subscription tiers, policies, or branding
|
||||
- When a Chronicler suspects instructions reference something stale
|
||||
- Periodically as preventive maintenance (every ~10 sessions)
|
||||
This skill catches drift between what the project instructions say and what actually exists, preventing Chroniclers from operating on outdated assumptions.
|
||||
---
|
||||
|
||||
# Project Instructions Health Checker
|
||||
|
||||
Validates the Claude Project instructions against live Firefrost infrastructure. Catches stale references, missing capabilities, outdated IPs, wrong tier names, and other drift before it causes problems.
|
||||
|
||||
---
|
||||
|
||||
## WHEN TO RUN
|
||||
|
||||
- **Session start (optional):** Quick check after the Joining Protocol if you suspect instructions may be stale
|
||||
- **After infrastructure changes:** Any time a server is added/removed/moved, an IP changes, a service is deployed or decommissioned, or an MCP connector is added/removed
|
||||
- **After policy changes:** Tier pricing, branding updates, the "We Don't Kick People Out" policy, or any load-bearing policy documented in the instructions
|
||||
- **On request:** When Michael says "check the instructions" or "are the instructions up to date"
|
||||
|
||||
---
|
||||
|
||||
## HOW TO RUN
|
||||
|
||||
Execute these checks in order. Each check is independent — a failure in one doesn't block the others. Collect all results and report at the end.
|
||||
|
||||
### Check 1: Server Connectivity
|
||||
|
||||
Verify every server listed in the instructions is reachable via Trinity Core.
|
||||
|
||||
```bash
|
||||
# Call Trinity Core:list_servers and compare against the Infrastructure table
|
||||
# in the project instructions. Flag any server that:
|
||||
# - Is listed in instructions but NOT in Trinity Core's roster
|
||||
# - Is in Trinity Core's roster but NOT in the instructions
|
||||
# - Has a different IP than what the instructions say
|
||||
```
|
||||
|
||||
**How to verify IPs:**
|
||||
```bash
|
||||
# For each server in Trinity Core's roster:
|
||||
Trinity Core:run_command(server="<name>", command="hostname -I | awk '{print $1}'")
|
||||
# Compare the returned IP against the instructions table
|
||||
```
|
||||
|
||||
**Pass criteria:** All servers in instructions match Trinity Core roster AND IPs match.
|
||||
|
||||
### Check 2: MCP Connectors
|
||||
|
||||
Verify the connectors listed in the instructions match what's actually available.
|
||||
|
||||
```bash
|
||||
# Call tool_search with queries for each listed connector:
|
||||
# "Canva", "Cloudflare", "Stripe", "Google Calendar", "Gmail", "Mermaid Chart", "Trinity Core"
|
||||
# Flag any connector that:
|
||||
# - Is listed in instructions but fails to load
|
||||
# - Is available but NOT listed in instructions
|
||||
```
|
||||
|
||||
**Pass criteria:** Every listed connector loads, no unlisted connectors discovered.
|
||||
|
||||
### Check 3: Gitea Repos
|
||||
|
||||
Verify the repos listed in the instructions exist and the listed branches are correct.
|
||||
|
||||
```bash
|
||||
# For each repo in the Repo Reference table:
|
||||
curl -s -H "Authorization: token <TOKEN>" \
|
||||
"https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/<REPO>/branches" \
|
||||
| python3 -c "import sys,json; [print(b['name']) for b in json.load(sys.stdin)]"
|
||||
# Flag if the default branch doesn't match what the instructions say
|
||||
```
|
||||
|
||||
**Pass criteria:** All repos exist, default branches match.
|
||||
|
||||
### Check 4: Arbiter Health
|
||||
|
||||
Verify Arbiter is running and the documented endpoints respond.
|
||||
|
||||
```bash
|
||||
Trinity Core:run_command(server="command-center", command="systemctl is-active arbiter-3")
|
||||
Trinity Core:run_command(server="command-center", command="curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:3500/admin/")
|
||||
```
|
||||
|
||||
**Pass criteria:** Service active, admin endpoint returns 200 or 302 (redirect to login).
|
||||
|
||||
### Check 5: Database Access
|
||||
|
||||
Verify the documented database credentials work.
|
||||
|
||||
```bash
|
||||
Trinity Core:run_command(server="command-center", command="PGPASSWORD='FireFrost2026!Arbiter' psql -U arbiter -h 127.0.0.1 -d arbiter_db -c 'SELECT 1'")
|
||||
```
|
||||
|
||||
**Pass criteria:** Query returns `1` without error.
|
||||
|
||||
### Check 6: Subscription Tiers
|
||||
|
||||
Verify the tiers listed in the instructions match what's configured in Arbiter.
|
||||
|
||||
```bash
|
||||
Trinity Core:run_command(server="command-center", command="PGPASSWORD='FireFrost2026!Arbiter' psql -U arbiter -h 127.0.0.1 -d arbiter_db -tAc \"SELECT DISTINCT tier_level FROM subscriptions ORDER BY tier_level;\"")
|
||||
```
|
||||
|
||||
Also check `src/routes/admin/constants.js` in the services repo for the TIER_INFO definition:
|
||||
```bash
|
||||
grep -A 30 "TIER_INFO" /home/claude/firefrost-services/services/arbiter-3.0/src/routes/admin/constants.js
|
||||
```
|
||||
|
||||
**Pass criteria:** Tiers in the database and constants file match the instructions table. The top tier is SOVEREIGN (never "Founder").
|
||||
|
||||
### Check 7: Website Deploy Pipeline
|
||||
|
||||
Verify the website auto-deploy mechanism is intact.
|
||||
|
||||
```bash
|
||||
# Check that the website repo's main branch exists and has recent activity:
|
||||
curl -s -H "Authorization: token <TOKEN>" \
|
||||
"https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-website/branches/main" \
|
||||
| python3 -c "import sys,json; d=json.load(sys.stdin); print('last commit:', d['commit']['message'][:80])"
|
||||
|
||||
# Verify the live site responds:
|
||||
curl -s -o /dev/null -w "%{http_code}" https://firefrostgaming.com/
|
||||
```
|
||||
|
||||
**Pass criteria:** Repo branch exists, live site returns 200.
|
||||
|
||||
### Check 8: Policy Page
|
||||
|
||||
Verify the "We Don't Kick People Out" policy page is live and contains the expected content markers.
|
||||
|
||||
```bash
|
||||
curl -s https://firefrostgaming.com/cancellation-refund/ | grep -c "Awakened\|appealForm\|We Don't Kick"
|
||||
```
|
||||
|
||||
**Pass criteria:** At least 2 of the 3 markers found (confirms page is live and has the right content).
|
||||
|
||||
### Check 9: Clone Size
|
||||
|
||||
Verify the ops manual clone size is still healthy (post-Task #101 cleanup).
|
||||
|
||||
```bash
|
||||
# After the standard session-start clone:
|
||||
du -sh /home/claude/firefrost-operations-manual/.git
|
||||
```
|
||||
|
||||
**Pass criteria:** Under 150 MB. If over 300 MB, large binary files may have been re-committed — investigate with:
|
||||
```bash
|
||||
git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectsize) %(rest)' | awk '$1=="blob" && $2>1000000' | sort -k2 -rn | head -10
|
||||
```
|
||||
|
||||
### Check 10: Stale References
|
||||
|
||||
Scan the instructions text for references to things that no longer exist.
|
||||
|
||||
```bash
|
||||
# Check for references to decommissioned services:
|
||||
# - Ghost CMS (decommissioned April 2-3, 2026)
|
||||
# - Paymenter (decommissioned April 2-3, 2026)
|
||||
# - SSH blocked (no longer true since Trinity Core)
|
||||
# - "Founder" tier (correct name is SOVEREIGN)
|
||||
# - sparse checkout (no longer needed since Task #101)
|
||||
```
|
||||
|
||||
**How:** Read through the project instructions in context and flag any mention of:
|
||||
- `Ghost` or `ghost` (unless clearly historical)
|
||||
- `Paymenter` or `paymenter` (unless clearly historical)
|
||||
- `SSH is blocked` or `SSH.*cannot` or `port 22.*blocked`
|
||||
- `Founder` as a tier name (should be `Sovereign`)
|
||||
- `sparse checkout` as a recommendation (should say full clone)
|
||||
|
||||
**Pass criteria:** Zero stale references found.
|
||||
|
||||
---
|
||||
|
||||
## REPORTING FORMAT
|
||||
|
||||
After running all checks, report like this:
|
||||
|
||||
```
|
||||
📋 Project Instructions Health Check — [Date]
|
||||
|
||||
✅ Check 1: Server Connectivity — PASS (7/7 servers reachable, IPs match)
|
||||
✅ Check 2: MCP Connectors — PASS (7/7 connectors load)
|
||||
⚠️ Check 3: Gitea Repos — WARNING (firefrost-staff-wiki not in instructions but exists)
|
||||
✅ Check 4: Arbiter Health — PASS (active, admin returns 302)
|
||||
✅ Check 5: Database Access — PASS
|
||||
✅ Check 6: Subscription Tiers — PASS (6 tiers, top = Sovereign)
|
||||
✅ Check 7: Website Deploy — PASS (main branch active, site returns 200)
|
||||
✅ Check 8: Policy Page — PASS (3/3 markers found)
|
||||
✅ Check 9: Clone Size — PASS (62 MB)
|
||||
✅ Check 10: Stale References — PASS (0 found)
|
||||
|
||||
Result: 9/10 PASS, 1 WARNING
|
||||
Action needed: Add firefrost-staff-wiki to Repo Reference table
|
||||
```
|
||||
|
||||
Use ✅ for PASS, ⚠️ for WARNING (non-critical drift), ❌ for FAIL (instructions are actively wrong about something load-bearing).
|
||||
|
||||
---
|
||||
|
||||
## AFTER THE CHECK
|
||||
|
||||
- If all checks pass: note it in the session log and move on.
|
||||
- If warnings found: mention them to Michael, suggest the fix, apply if he approves.
|
||||
- If failures found: **stop and fix before doing other work.** A Chronicler operating with wrong instructions is worse than a Chronicler operating with no instructions. Fix the instructions text, generate the updated file, and have Michael paste it into the Project config.
|
||||
|
||||
---
|
||||
|
||||
## MAINTAINING THIS SKILL
|
||||
|
||||
When new infrastructure is added (servers, connectors, services, repos), add a corresponding check to this skill. The skill should grow alongside the infrastructure it validates.
|
||||
|
||||
When checks become obsolete (e.g., a service is permanently decommissioned and removed from instructions), remove the corresponding check so the skill doesn't accumulate dead weight.
|
||||
|
||||
---
|
||||
|
||||
*Created by Chronicler #81 — April 11, 2026*
|
||||
*"Trust but verify. Then verify the verifier."*
|
||||
Reference in New Issue
Block a user