From aisa
Manage .claude/cache/ snapshots for incremental scanning — supports rebuild, status, and invalidate sub-commands. Reduces token consumption by 60-80% by skipping unchanged content. Run after any sync cycle or manually to refresh.
How this skill is triggered — by the user, by Claude, or both
Slash command
/aisa:aisa-cache [rebuild|status|invalidate][rebuild|status|invalidate]The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Maintain `.claude/cache/` so that `aisa-sync`, `aisa-inspect`, and `aisa-lint` can
Maintain .claude/cache/ so that aisa-sync, aisa-inspect, and aisa-lint can
skip unchanged files and focus tokens only on what actually changed since the last audit.
.claude/cache/
├── snapshot.json # inventory + file hashes — WHO exists and WHAT they contain
└── drift-report.json # last audit results per file — WHAT was their status
{
"generated_at": "2025-02-23T14:30:00Z",
"generated_by": "aisa-sync v8.0",
"project_root_hash": "<sha256 of sorted ls -la on project root>",
"skills": {
"identity-coding-standards": {
"path": ".claude/skills/identity-coding-standards.md",
"sha256": "<hash of file content>",
"lines": 142,
"mtime": "2025-02-20T10:15:00Z",
"has_quality_gates": true,
"has_learning_capture": true,
"has_pcidci_workflow": true,
"exempt_from_gates": false
}
},
"agents": {
"code-reviewer": {
"path": ".claude/agents/code-reviewer.md",
"sha256": "<hash>",
"lines": 85,
"mtime": "2025-02-19T08:00:00Z",
"frontmatter_valid": true,
"tools_valid": true,
"has_self_review": true,
"has_learning_capture": true
}
},
"claude_md": {
"sha256": "<hash>",
"mtime": "2025-02-21T09:00:00Z"
},
"learnings_log": {
"total_entries": 24,
"active": 8,
"promoted": 12,
"stale": 4,
"sha256": "<hash>"
},
"project_indicators": {
"go_mod_hash": "<hash of go.mod if exists>",
"package_json_hash": "<hash of package.json if exists>",
"spec_dir_hash": "<hash of sorted ls on specs/ or openspec/>",
"src_dir_listing_hash": "<hash of sorted find on src/ top 2 levels>"
}
}
{
"generated_at": "2025-02-23T14:35:00Z",
"generated_by": "aisa-inspect",
"overall_status": "NEEDS_ATTENTION",
"results": {
"identity-coding-standards": {
"status": "CURRENT",
"passes": { "A": "PASS", "B": "PASS", "C": "PASS", "D": "N/A", "E": "PASS" },
"notes": null
},
"identity-error-handling": {
"status": "OUTDATED",
"passes": { "A": "PASS", "B": "FAIL", "C": "PASS", "D": "N/A", "E": "PASS" },
"notes": "Pass B: ErrorResponseFactory signature changed in v2.3"
}
}
}
$ARGUMENTS = rebuild (or empty)Full rebuild of snapshot.json. Use after a complete aisa-sync cycle or when cache is suspected stale.
Locate the script with Glob for **/cache-snapshot.js, then run from the project root:
node <plugin-path>/scripts/cache-snapshot.js rebuild --project-root .
The script discovers all skill and agent .md files, hashes each with SHA-256, evaluates
principle compliance flags via content pattern matching, counts learnings log entries, hashes
project indicators, and writes the complete snapshot.json in a single invocation.
The script lives at plugins/ai-setup-automation/scripts/cache-snapshot.js relative to the
marketplace root, or can be located with Glob pattern **/cache-snapshot.js.
Principle compliance flags — populated automatically by the script:
/aisa-lint runs explicitlyWrite to .claude/cache/snapshot.json.
$ARGUMENTS = statusReport cache freshness without rebuilding:
node <plugin-path>/scripts/cache-snapshot.js status --project-root .
The script compares current file hashes against the cached snapshot and prints a markdown report to stdout:
## Cache Status
- snapshot.json: [EXISTS / MISSING] — age: {time since generated_at}
- drift-report.json: [EXISTS / MISSING] — age: {time since generated_at}
- Skills cached: {N} / {N actual on disk} — {N} stale (hash mismatch)
- Agents cached: {N} / {N actual on disk} — {N} stale (hash mismatch)
- Project indicators: {N changed since snapshot}
### Recommendation
{FRESH — no rebuild needed / PARTIALLY STALE — incremental scan sufficient / STALE — full rebuild recommended}
After presenting the cache status report, always close with:
## Learnings
{If cache analysis reveals patterns (e.g., "skills always drift together", "spec changes correlate with domain drift"), note them here. Otherwise: "No new patterns detected."}
This section is mandatory — it is the evidence that P1 learning capture ran.
Before delivering the status report, perform an internal critique:
$ARGUMENTS = invalidateDelete the cache files, forcing a full scan on the next aisa-sync run:
node <plugin-path>/scripts/cache-snapshot.js invalidate --project-root .
When any aisa-* skill starts, it should:
.claude/cache/snapshot.json existsgo.mod, package.json, spec dirs, or src dirs changed → flag related skills for re-audit even if the skill file itself didn't change| Setup size | Full scan tokens | Incremental (20% changed) | Savings |
|---|---|---|---|
| 10 items | ~30K | ~10K | ~67% |
| 20 items | ~60K | ~16K | ~73% |
| 33 items | ~100K | ~25K | ~75% |
The cache should be fully rebuilt when:
aisa-sync completes a full cycle (it rebuilds automatically)aisa-init generates a new setup/aisa-cache rebuildThe cache should be partially invalidated when:
aisa-update updates specific skills (update only those entries)aisa-harvest promotes learnings to skills (update promoted targets)aisa-postmortem modifies skills (update modified entries)Every aisa-sync full cycle should, as its final step, rebuild the cache:
Phase 7 — Execute → apply approved changes
Phase 7.5 — Cache Rebuild → update .claude/cache/snapshot.json with new state
This ensures the NEXT evolution run starts with a fresh baseline.
Before writing snapshot.json:
If cache analysis reveals patterns (e.g., "skills in domain X always drift together",
"agents drift faster than skills", "spec changes correlate with domain skill drift"),
append as learning entries to .claude/learnings/log.md.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub rnagrodzki/ai-setup-automation --plugin aisa