Summary

Ceremonies silently stop working when ceremonies.md exceeds the file-view size threshold (~20KB). The coordinator's view tool rejects the file with "File too large to read at once," and instead of falling back to alternative read strategies, the coordinator drops the entire ceremony system and misroutes ceremony requests as general work tasks.

This is a cliff failure — below the threshold ceremonies work 100%, above it they work 0%. Every new ceremony definition added to the monolithic file makes the problem worse with no graceful degradation.

Steps to Reproduce

1. Create a squad with several ceremonies defined in .squad/ceremonies.md
2. Continue adding ceremony definitions until the file exceeds ~20KB (roughly 8-12 detailed ceremonies depending on complexity)
3. Request a ceremony by name (e.g., "bug bash", "run a retro", "design review")
4. Expected: Coordinator matches the request to the ceremony definition, spawns the facilitator, and runs the structured ceremony
5. Actual: Coordinator fails to read ceremonies.md, pattern-matches the request against the routing table's "general work request" row, and fans out agents to do ad-hoc work — completely bypassing the ceremony system

Root Cause Chain

1. Coordinator calls view on ceremonies.md → tool returns "File too large to read at once"
2. No fallback logic exists (no view_range, no grep, no chunked read)
3. With zero ceremony definitions in context, the user's request (e.g., "bug bash") doesn't match the "ceremony request" routing signal
4. Request falls through to "general work request" and gets decomposed as a multi-agent task

Implementation Guide: Ceremonies as Skills

Migrate ceremony definitions from the monolithic ceremonies.md into individual skill files, reducing ceremonies.md to a lightweight dispatch table that will never hit the size threshold.

Architecture Change

Before (current):

• ceremonies.md = monolithic file containing every ceremony's full definition (triggers, participants, flow steps, facilitator templates)
• Grows linearly with each new ceremony
• Single point of failure at the file-size cliff

After (proposed):

• ceremonies.md = small dispatch table (~2-4KB max, scales to 50+ ceremonies without issue)
• Each ceremony lives in .squad/skills/ceremony-{name}/SKILL.md with its full definition
• Coordinator reads the tiny table, matches the trigger, reads just that one skill file

New ceremonies.md Format

`markdown

Ceremonies

Ceremony definitions live in individual skill files. This table is the dispatch index.

Ceremony Skill File Structure

Each .squad/skills/ceremony-{name}/SKILL.md contains the full ceremony definition currently embedded in ceremonies.md:

• Facilitator (who runs it)
• Participants (who's involved)
• Flow steps (the structured meeting format)
• Facilitator spawn template
• Output format and expected artifacts

Coordinator Instruction Changes (squad.agent.md)

The Ceremonies section changes from:

"read ceremonies.md for ceremony definitions"

To:

1. Read ceremonies.md (always small — just a dispatch table)
2. Match the user's request against the Name/Trigger/Condition columns
3. If matched, read the referenced skill file at the path in the Skill column
4. Spawn the facilitator with the ceremony skill content inlined

The auto-trigger logic (before/after checks) also reads only the dispatch table to find matching conditions, then loads only the matched ceremony's skill file.

Why This Approach Works

• The dispatch table never hits the size cliff. Even with 50+ ceremonies, a markdown table is ~3-4KB.
• Skill-aware routing already exists. The coordinator already knows how to discover, read, and pass skills to agents. Zero new infrastructure needed.
• Each ceremony skill is self-contained and small — typically 1-2KB. Always readable by any tool.
• Skills inherit the confidence lifecycle — ceremonies that get used and refined naturally gain confidence levels (low → medium → high).
• Better discoverability. Each ceremony is a separate file that can be searched, versioned, and reviewed independently.

Migration Steps

1. Parse existing ceremonies.md to extract each ceremony definition
2. Create .squad/skills/ceremony-{name}/SKILL.md for each ceremony, following the existing skill template format
3. Replace ceremonies.md content with the dispatch table (keeping the # Ceremonies header)
4. Update the Ceremonies section in squad.agent.md with the new dispatch-then-read logic
5. Update ceremony-reference.md template to document the new structure
6. Update Init Mode Phase 2 so new squads create the dispatch table format (not the monolithic format)

Files Affected

• squad.agent.md — Ceremonies section (coordinator instructions for lookup and execution)
• .squad/ceremonies.md — file format changes from monolith to dispatch table
• .squad/skills/ceremony-*/SKILL.md — new files (one per ceremony)
• .squad/templates/ceremony-reference.md — updated format guide
• Init Mode Phase 2 — ceremony file creation during team setup

What Does NOT Change

• How ceremonies execute (facilitator spawning, participant sub-tasks, sync mode)
• Ceremony cooldown logic
• Auto-triggered before/after matching semantics (just reads from the table instead of the monolith)
• The ## Ceremonies entry in the Source of Truth Hierarchy