C3 Container Level Exploration

⛔ CRITICAL GATE: Load Parent Context + Current Container First

STOP - Before ANY container-level work, execute:

# Load parent Context (REQUIRED - containers inherit from here)
cat .c3/README.md 2>/dev/null || echo "NO_CONTEXT"

# Load current container (if exists)
cat .c3/c3-{N}-*/README.md 2>/dev/null || echo "NO_CONTAINER_DOC"

# Load settings
cat .c3/settings.yaml 2>/dev/null || echo "NO_SETTINGS"

Based on output:

If "NO_CONTEXT" → STOP. Context must exist first. Escalate to c3-context-design.
If container doc exists → Read it completely before proposing changes
Extract from Context: boundary, protocols, actors, cross-cutting concerns for this container

⚠️ DO NOT read ADRs unless user specifically asks:

Container work focuses on current structure, not historical decisions
ADRs add unnecessary context → hallucination risk
Only read: Context, this Container, sibling Containers (if coordination needed)

Why this gate exists: Containers INHERIT from Context. Proposing changes without understanding inherited constraints causes conflicts.

Self-check before proceeding:

[ ] I executed the commands above
[ ] I read parent Context doc
[ ] I know what constraints this container inherits
[ ] I read existing container doc (if exists)

Overview

The Container level is the architectural command center of C3:

Full context awareness from above (inherits from Context)
Complete control over component responsibilities below
Mediator for all interactions

Position: MIDDLE (c3-{N}) | Parent: Context (c3-0) | Children: Components (c3-{N}NN)

📁 File Location: Container is .c3/c3-{N}-{slug}/README.md - a folder with README inside.

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

The Principle

Upper layer defines WHAT. Lower layer implements HOW.

At Container level:

Context defines WHAT I am (my existence, my responsibility)
I define WHAT components exist and WHAT they do
Component implements my definitions (HOW it works)
I do NOT define how components work internally - that's Component's job

Integrity rules:

I must be listed in Context before I can exist
Components cannot exist without being listed in my inventory

Container Archetypes

| Archetype | Relationship | Typical Components | |-----------|--------------|-------------------| | Service | Creates/processes | Handlers, Services, Adapters | | Data | Stores/structures | Schema, Indexes, Migrations | | Boundary | Interface to external | Contract, Client, Fallback | | Platform | Operates on containers | CI/CD, Deployment, Networking |

Include/Exclude

| Include (Container Level) | Exclude (Push Up/Down) | |---------------------------|------------------------| | Component responsibilities | WHY container exists (Context) | | Component relationships | HOW components work internally (Component) | | Data flows between components | Code references | | Business flows | File paths | | Inner patterns | |

Litmus test: "Is this about WHAT components do and HOW they relate to each other?"

Exploration Process

Phase 1: Verify Inheritance

From loaded Context, extract for this container:

Boundary: What can/cannot access
Protocols: What we implement (provider/consumer)
Actors: Who we serve
Cross-cutting: Patterns we must follow (auth, logging, errors)

Phase 2: Analyze Change Impact

| Direction | Action | |-----------|--------| | Upstream | New protocol/boundary violation → Escalate to c3-context-design | | Isolated | Stack/pattern/API/org change → Document here | | Adjacent | Component-to-component impact → Coordinate | | Downstream | New/changed components → Delegate to c3-component-design |

Phase 3: Socratic Discovery

By archetype:

Service: Responsibility? Key components? Critical flows?
Data: Engine/version? Schema? Access patterns?
Boundary: Contract? Client? Fallback?
Platform: Processes? Affected containers?

Template

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

Required sections:

Inherited From Context
Overview
Technology Stack
Architecture - External Relationships (diagram + interface mapping table)
Architecture - Internal Structure (diagram with Foundation/Business layering)
Component Layering Rules
Components table
Key Flows

Diagram Requirements

Container level REQUIRES two diagrams:

External Relationships - Shows connections to other containers/external systems
Internal Structure - Shows how components relate to each other

Use Mermaid only - no ASCII art.

⛔ Enforcement Harnesses

Harness 1: Template Fidelity

Rule: Output MUST match template structure exactly.

Required sections (in order):

Frontmatter (id, c3-version, title, type, parent, summary)
Inherited From Context
Overview
Technology Stack
Architecture - External Relationships (diagram REQUIRED)
Architecture - Internal Structure (diagram REQUIRED)
Components
Key Flows

🚩 Red Flags:

Sections missing or reordered
Only one diagram (need BOTH)
Missing "Inherited From Context" section

Harness 2: Two Diagrams Required

Rule: Container docs MUST have both External and Internal diagrams.

# Verify both diagrams exist
grep -c '```mermaid' .c3/c3-{N}-*/README.md  # Should be >= 2

Verification Checklist

Before claiming completion, execute:

# Verify container doc exists in correct location
ls .c3/c3-*-*/README.md

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

# Verify BOTH mermaid diagrams exist
mermaid_count=$(grep -c '```mermaid' .c3/c3-{N}-*/README.md)
echo "Mermaid diagrams: $mermaid_count (need >= 2)"

[ ] Critical gate executed (Context + current container loaded)
[ ] Container is listed in Context's container inventory
[ ] "Inherited From Context" section populated from parent
[ ] Template sections present in correct order
[ ] BOTH diagrams included (External + Internal)
[ ] Components listed with responsibilities
[ ] Downstream delegation identified (c3-component-design)

📚 Reading Chain Output

At the end of container work, output a reading chain for components and related containers.

Format:

## 📚 To Go Deeper

This container (c3-N) contains:

**Components to explore:**
├─ c3-N01-{slug} - [responsibility, why it matters]
├─ c3-N02-{slug} - [responsibility, why it matters]
└─ ...

**Parent (inherited constraints):**
└─ c3-0 (Context) - [what this container inherits]

**Sibling containers (if coordination needed):**
└─ c3-M-{slug} - [why coordination matters]

*Reading chain generated from components listed in this Container.*

Rules:

List components from the Container's inventory
Highlight which components are affected by this change
Include parent Context for constraint reference
Never include ADRs unless user asked

Change Impact Decision

flowchart TD
    A[Analyze Change] --> B{New protocol or<br/>boundary violation?}
    B -->|yes| C[Escalate to<br/>c3-context-design]
    B -->|no| D{Component org<br/>change?}
    D -->|yes| E[Delegate to<br/>c3-component-design]
    D -->|no| F[Document at<br/>Container level]

Common Rationalizations

| Excuse | Reality | |--------|---------| | "One diagram is enough" | External + Internal are BOTH required. Different purposes. | | "I'll add diagrams later" | Diagrams drive understanding. Add during exploration, not after. | | "Template too rigid" | Template is minimum. Add sections if needed, but don't skip required ones. | | "This container is simple" | Simple containers still need both diagrams. Just smaller diagrams. | | "Inherited section is obvious" | Make inheritance explicit. What's obvious to you isn't to readers. | | "Layering doesn't apply here" | All containers have Foundation → Business layering. Show it. |

Common Mistakes

| Mistake | Fix | |---------|-----| | Missing External Relationships diagram | REQUIRED. Maps Context interfaces to owning components. | | Missing Internal Structure diagram | REQUIRED. Shows Foundation → Business layering. | | Not mapping interfaces to components | Add table: External Interface | Owning Component | Protocol | | Duplicating Context content | Reference Context, don't repeat. Show component ownership. | | Skipping layering rules | Always include Foundation/Business rules table. |

references/core-principle.md - The C3 principle
defaults.md - Container layer rules
references/container-archetypes.md - Container types
references/diagram-decision-framework.md - When to use which diagram