cc-os/plugins/cc-architect/references/layout/reference.md

What Makes a Good reference.md

reference.md is the routing file required in every references/ subdirectory (see ${CLAUDE_PLUGIN_ROOT}/references/layout/skill-structure.md). It exists so a model can decide what to read next without opening every knowledge doc.

This file is a pointer to the full pattern, kept here so references/layout/ stays a complete map of the layout — the actual authoring detail lives in progressive-disclosure:

→ ${CLAUDE_PLUGIN_ROOT}/references/progressive-disclosure/reference-md-pattern.md (required sections: what's here table, when to use this module, model guidance; anti-patterns like duplicating child content or exceeding ~50 lines)

When to split a reference doc out

A reference.md should point to a separate knowledge doc — rather than inline the knowledge itself — whenever the content stops being "what's here and when to read it" and becomes the knowledge itself. Concretely:

• The explanation would push reference.md past ~50 lines
• The content is only needed for a subset of workflows, not every reader of this directory
• The doc covers a distinct concept that could stand alone under a different topic subdirectory

Full splitting criteria (the "always needed together?" test, size guidelines, how to split, depth limits) are in: → ${CLAUDE_PLUGIN_ROOT}/references/progressive-disclosure/splitting-knowledge.md

Quick checklist

1. Table of files/subdirs with purpose + "when to read"
2. "When to use this module" section
3. "Model guidance" (cheap vs. stronger model)
4. No duplication of child file content
5. <=50 lines total