C3 Component Design

C3 Component Level Exploration

⛔ CRITICAL GATE: Load Parent Container + Context First

STOP - Before ANY component-level work, execute:

# Load grandparent Context
cat .c3/README.md 2>/dev/null || echo "NO_CONTEXT"

# Load parent Container (REQUIRED - components inherit from here)
cat .c3/c3-{N}-*/README.md 2>/dev/null || echo "NO_CONTAINER"

# Check if component is listed in Container
grep "c3-{N}{NN}" .c3/c3-{N}-*/README.md 2>/dev/null || echo "COMPONENT_NOT_IN_CONTAINER"

# Load existing component doc (if exists)
cat .c3/c3-{N}-*/c3-{N}{NN}-*.md 2>/dev/null || echo "NO_COMPONENT_DOC"

Based on output:

• If "NO_CONTAINER" → STOP. Container must exist first. Escalate to c3-container-design.
• If "COMPONENT_NOT_IN_CONTAINER" → STOP. Add component to Container first.
• If component doc exists → Read it completely before proposing changes

⚠️ DO NOT read ADRs unless user specifically asks:

• Component work focuses on HOW, not historical WHY
• ADRs add unnecessary context → hallucination risk
• Only read: Context, parent Container, sibling Components (if dependencies)

Why this gate exists: Components INHERIT from Container (and transitively from Context). A component cannot exist without being listed in its parent Container.

Self-check before proceeding:

• I executed the commands above
• I read parent Container doc
• This component IS listed in Container's component inventory
• I know what contract/responsibility this component has (from Container)
• I read existing component doc (if exists)

Overview

Component is the leaf layer - it inherits all constraints from above and implements actual behavior.

Position: LEAF (c3-{N}{NN}) | Parent: Container (c3-{N}) | Grandparent: Context (c3-0)

📁 File Location: Component is .c3/c3-{N}-{slug}/c3-{N}{NN}-{slug}.md - INSIDE the container folder.

Announce: "I'm using the c3-component-design skill to explore Component-level impact."

The Principle

Upper layer defines WHAT. Lower layer implements HOW.

At Component level:

• Container defines WHAT I am (my existence, my responsibility)
• I define HOW I implement that responsibility
• Code implements my documentation (in the codebase, not in C3)
• I do NOT invent my responsibility - that's Container's job

Integrity rules:

• I must be listed in Container before I can exist
• My "Contract" section must reference what Container says about me
• If Container doesn't mention me, I don't exist as a C3 document

Include/Exclude

Litmus test: "Is this about HOW this component implements its contract?"

Diagram-First Principle

Components are documented visually. The diagram tells the story, text supports it.

Every component explains:

• Its boundary - what it's responsible for (and what it's not)
• Hand-off points - where information exchanges happen with other components
• Internal processing - what happens inside (self-contained)

Interface Diagram (Required)

Shows the boundary and hand-offs:

flowchart LR
    subgraph IN["Receives"]
        I1[From Component A]
        I2[From External]
    end

    subgraph SELF["Owns"]
        S1[Processing]
        S2[Transformation]
    end

    subgraph OUT["Provides"]
        O1[To Component B]
        O2[To Caller]
    end

    IN --> SELF --> OUT

Additional Diagrams (Where Applicable)

Use multiple diagrams when needed - just enough to explain:

Foundation vs Business components:

• Foundation (e.g., Hono): Shows the transition point - where framework ends and business begins. What it provides TO business components.
• Business (e.g., User Handler): Shows the flow - receives from foundation, processes, hands off results.

⛔ NO CODE ENFORCEMENT (MANDATORY)

Component docs describe HOW things work, NOT the actual implementation.

What Counts as Code (PROHIBITED)

Why Mermaid is Allowed but JSON is Not

• Mermaid = visual flow/state diagrams (architectural)
• JSON/YAML = data structure syntax (implementation)
• Rule: If it could be parsed by JSON/YAML parser → use table instead

Exploration Process

Phase 1: Verify Integrity

From loaded Container, extract:

• Component's responsibility (from Container's component table)
• Related components (siblings)
• Technology constraints
• Pattern constraints

If component not in Container: STOP. Escalate to c3-container-design.

Phase 2: Analyze Change Impact

Phase 3: Socratic Discovery

By container archetype:

• Service: Processing steps? Dependencies? Error paths?
• Data: Structure? Queries? Migrations?
• Boundary: External API? Mapping? Failures?
• Platform: Process? Triggers? Recovery?

Template

See component-template.md for complete structure with frontmatter, diagrams, and examples.

Required sections:

1. Contract (from parent Container)
2. Interface (diagram showing boundary - REQUIRED)
3. Hand-offs table
4. Conventions table
5. Edge Cases & Errors table

Optional sections (include based on component nature):

• Additional diagrams (Sequence, State, Organization)
• Configuration, Dependencies, Invariants, Performance

Keep it lean: Simple component = 5 sections. Complex framework = multiple diagrams + optional sections.

⛔ Enforcement Harnesses

Harness 1: No Code

Rule: No code blocks except Mermaid diagrams.

# Check for non-mermaid code blocks
grep -E '```[a-z]+' .c3/c3-{N}-*/c3-{N}{NN}-*.md | grep -v mermaid
# Should return nothing

🚩 Red Flags:

• function, class, interface, type keywords
• import, require, export statements
• File extensions like .ts, .js, .py
• JSON/YAML blocks (even for "schemas")
• "Example payload" in code blocks

Harness 2: Diagram-First

Rule: Interface diagram (IN → Processing → OUT) is REQUIRED.

Required sections:

1. Frontmatter (id, c3-version, title, type, parent, summary)
2. Contract (from parent Container)
3. Interface (Mermaid diagram REQUIRED - boundary and hand-offs)
4. Hand-offs (table - what exchanges with whom)
5. Conventions (table of rules)
6. Edge Cases & Errors (table)

Optional sections (include based on component nature):

• Additional diagrams (Sequence, State, Organization) - where needed
• Configuration - significant config surface
• Dependencies - external dependencies matter
• Invariants - key guarantees to verify
• Performance - throughput/latency matters

🚩 Red Flags:

• Missing Interface diagram
• No IN/OUT structure in diagram
• Text-heavy without diagrams
• Code blocks present

Verification Checklist

Before claiming completion, execute:

# Verify component doc exists in correct location
ls .c3/c3-{N}-*/c3-{N}{NN}-*.md

# Verify frontmatter
grep -E "^id:|^type:|^parent:" .c3/c3-{N}-*/c3-{N}{NN}-*.md

# Verify Interface diagram exists with IN/OUT structure
grep -c '```mermaid' .c3/c3-{N}-*/c3-{N}{NN}-*.md  # Should be >= 1
grep -E "subgraph.*(IN|OUT)" .c3/c3-{N}-*/c3-{N}{NN}-*.md  # Should find IN/OUT

# Verify NO non-mermaid code blocks
non_mermaid=$(grep -E '```[a-z]+' .c3/c3-{N}-*/c3-{N}{NN}-*.md | grep -v mermaid | wc -l)
echo "Non-mermaid code blocks: $non_mermaid (should be 0)"

• Critical gate executed (Container + Context loaded)
• Component IS listed in parent Container's inventory
• "Contract" section references Container's description
• Interface diagram present (boundary and hand-offs)
• Hand-offs table present (what exchanges with whom)
• Conventions table present (rules for consistency)
• Edge Cases & Errors table present
• NO code blocks (except Mermaid)
• Additional diagrams justified - only if Sequence/State/Organization needed
• Optional sections justified - only included if relevant to this component

📚 Reading Chain Output

At the end of component work, output a reading chain for related docs.

Format:

## 📚 To Go Deeper

This component (c3-NNN) is part of:

**Ancestors (understand constraints):**
└─ c3-0 (Context) → c3-N (Container) → c3-NNN (this)

**Sibling components (if dependencies):**
├─ c3-NMM - [why this sibling matters]
└─ c3-NKK - [dependency relationship]

**Parent container (for context):**
└─ c3-N-{slug} - [what contract this component fulfills]

*Reading chain generated from component's dependencies and parent.*

Rules:

• List siblings only if this component depends on or affects them
• Always include parent Container for contract reference
• Include Context only if cross-cutting concerns are relevant
• Never include ADRs unless user asked

When NOT to Use

Escalate to c3-container-design if:

• Change affects component relationships (not just one component's internals)
• New technology/pattern needed
• Component not yet listed in parent Container

Escalate to c3-context-design if:

• Cross-cutting concern (affects multiple containers)
• New protocol or boundary needed

Wrong layer symptoms:

• Describing WHAT component does → Container's job
• Documenting WHY component exists → Container's job
• Including cross-container flows → Context's job

Change Impact Decision

flowchart TD
    A[Analyze Change] --> B{Breaks interface<br/>or patterns?}
    B -->|yes| C[Escalate to<br/>c3-container-design]
    B -->|no| D{Needs new<br/>technology?}
    D -->|yes| C
    D -->|no| E[Document at<br/>Component level]

Common Rationalizations

Common Mistakes

Related

• references/core-principle.md - The C3 principle
• defaults.md - Component layer rules
• references/container-archetypes.md - How archetype shapes component docs
• references/diagram-patterns.md - Diagram guidance