cc-os/plugins/cc-architect/references/progressive-disclosure/reference-md-pattern.md

The reference.md Pattern

Every directory in references/ must have a reference.md file. It's the routing layer that tells the AI what's here and when to go deeper.

Purpose

The reference.md file answers three questions:

1. What knowledge lives in this directory?
2. When should I read each file?
3. Do I need to go deeper into subdirectories?

Required sections

What's here

A table listing each file/subdirectory with:

• Name
• Purpose (one line)
• When to read it

## What's here

| File | Purpose | When to read |
|------|---------|--------------|
| `foo.md` | Explains X | When doing Y |
| `bar/` | Details about Z | When you need deep Z knowledge |

When to use this module

Brief description of the scenarios where this directory's knowledge applies.

Model guidance

Hints about whether cheap or stronger models should handle this content.

Optional sections

• Prerequisites: What the AI should know/have before reading this
• Child topics: If subdirectories exist, brief descriptions of when to descend

Anti-patterns

• Don't duplicate knowledge from child files in reference.md
• Don't make reference.md longer than ~50 lines
• Don't skip the "when to read" column - it's the whole point

Example

# Authentication References

## What's here

| File | Purpose | When to read |
|------|---------|--------------|
| `oauth-flow.md` | OAuth 2.0 implementation details | When the API uses OAuth |
| `api-keys.md` | API key authentication patterns | When the API uses simple API keys |
| `rate-limiting.md` | How to handle rate limits | After auth is working, before production |

## When to use this module

You're implementing authentication for an API wrapper and need to understand the auth mechanism.

## Model guidance

Factual/procedural content. Cheap model is fine.