diagnose-substrate

name	diagnose-substrate
description	Audit an existing Claude Code workspace for canon-substrate gaps — the failure mode where users build sophisticated agent stacks without a CORPUS_MAP / SCHEMA / decisions/ layer underneath, leaving every agent's "consult on demand" reference list resolving to nothing. Reports ship-blocking issues, fragile-but-working issues, and noise. Use when invited into someone's `.claude/agents/` directory to do an audit-and-recommend pass.
disable-model-invocation	true
allowed-tools	Bash(node *)
argument-hint	<path to workspace root containing .claude/agents/>

Liminal Agents — Substrate Diagnostic

You are auditing a Claude Code workspace for canon-substrate gaps. The workspace may have an existing agent layer (subagents in .claude/agents/) that runs on prompt-only context with no canonical substrate underneath. This audit identifies what's broken, fragile, or noisy — and proposes the foundation pack shape that would fix it.

The audit is read-only. It does NOT modify the workspace. It produces a structured report.

When to invoke

• User has a working .claude/agents/ directory and asks "is my setup right?"
• User shares a snapshot zip of their Claude config and wants a review
• User reports "Claude doesn't remember things between sessions" — high-probability symptom of memory-path mismatch or empty memory dir
• Before offering canon-substrate templates from liminal-agents/templates/canon-substrate/, run this diagnostic first so the templates are tuned to actual gaps

Flow

1. Validate input

User provides a workspace root path. Verify:

• Path exists and is a directory
• .claude/agents/ exists under it (or .claude/ somewhere reachable)
• If neither, abort with "no agent layer found at /.claude/agents/"

2. Run the diagnostic

Invoke:

node ~/liminal/liminal-agents/skills/diagnose-substrate/diagnose.js <workspace-path>

The script produces a JSON report with sections:

• broken[] — ship-blocking issues (memory-path mismatch, missing CLAUDE.md, no CORPUS_MAP)
• fragile[] — works but risky (quarantine model relies only on system-prompt-only declarations, settings flags that disable safety prompts, agent overlap)
• noise[] — cosmetic issues (inert JSON-comment-string entries in allow arrays, etc.)
• agent_summary — count of agents, average lines, models used, tools granted
• recommended_foundation_pack — which template files would address each broken/fragile issue

3. Present the report

Render the report in this order:

1. Headline — one line summarizing severity (e.g. "3 ship-blocking, 4 fragile, 1 noise")
2. Broken issues — for each, name the issue + the canonical fix
3. Fragile issues — for each, name the issue + the risk vector
4. Noise — flagged but not blocking
5. Foundation-pack recommendation — link to liminal-agents/templates/canon-substrate/ with which template files address which gaps

4. Offer next step

Ask the user: would they like the foundation pack deployed to their workspace? If yes, do NOT auto-deploy — produce a paste-into-Claude landing prompt (similar to the one Shruti shipped to Sam on 2026-05-19) that lands the templates without disturbing the existing agent layer.

Output principles

• Read-only. Never modify the workspace.
• Honest severity. Don't soften broken-→-fragile. Memory-path mismatch is broken, even if "the agents still respond." They respond on empty context.
• No upsell. The diagnostic is the deliverable. Foundation-pack deployment is a separate action, surfaced only if the user asks.
• Specific, not generic. "Your memory dir resolves to ; the agents reference ; the difference is the project-name mismatch from a prior CWD" — not "your memory might not work."

Related canon

• Architectural rationale: liminal-agents/SPEC.md §14 "Canon Substrate as Agent-Layer Prerequisite"
• Foundation pack templates: liminal-agents/templates/canon-substrate/
• Reference instance (Shruti's own canon): ~/liminal/founder-brain/CLAUDE.md + ~/liminal/founder-brain/meta/CORPUS_MAP.md
• Original live audit that produced this skill: ~/liminal/founder-brain/retros/2026-05-19-helping-sam-shape-of-help.md