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 <path>/.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 <path>; the agents reference <other path>; 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`