skilldeck: Instructions file for Claude Code

Skilldeck — Agent Project Bible

What This Project Is

Skilldeck is a desktop application for managing AI agent skill files (SKILL.md, CLAUDE.md, AGENTS.md) across projects and tools. It solves three problems:

1. Scatter — skill files live in different places, copies diverge, starting a new project means rebuilding behavioral infrastructure from scratch
2. Opacity — no way to know which skills are active in a project, at what version, or whether they've drifted
3. No verification — no feedback mechanism to know if a skill file is actually changing agent behavior

Skilldeck is also a harness engineering experiment. It is being built by AI agents following harness methodology. The build process itself is the proof of concept.

Rules Every Agent Must Follow

1. Read before touching. Before any coding session begins, read this file, claude-progress.txt, and feature_list.json. Do not skip this.

2. One feature at a time. One feature, one commit. Pick the highest-priority incomplete feature from feature_list.json. Complete it. Run the full verification sequence below. Commit. Then move to the next feature.

   Full verification sequence — every step must pass before committing:

   # Step 1 — feature test (must pass first)
   npx playwright test verify.spec.ts --grep F00X
   
   # Step 2 — invariant checks (always-true system properties)
   node check-invariants.js --always
   
   # Step 3 — regression gate (re-run affected passing tests)
   REGRESSION=$(node get-regression-tests.js F00X)
   npx playwright test verify.spec.ts --grep "$REGRESSION"
   
   # Step 4 — only if all three pass: mark passing, commit
   node -e "const fs=require('fs');const f=JSON.parse(fs.readFileSync('feature_list.json','utf8'));const x=f.features.find(x=>x.id==='F00X');x.passes=true;x.notes='Verified with Playwright + invariants + regression gate';fs.writeFileSync('feature_list.json',JSON.stringify(f,null,2));"
   git add .
   git commit -m "feat(F00X): short description of what was built"