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

See references/core-principle.md for full details.

Upper layer defines WHAT. Lower layer implements HOW.

At Container: Context defines WHAT I am. I define WHAT components exist. Component implements HOW. I must be listed in Context; components must be listed in me.

---

Container Archetypes

See references/container-archetypes.md for full component inventory by relationship type.

Quick reference: Service (processes), Data (stores), Boundary (interfaces), Platform (operates).

---

Include/Exclude

See defaults.md for full include/exclude rules and litmus test.

Quick check: "Is this about WHAT components do and HOW they relate?"

---

Components vs Tech Stack

Components have conventions for consumers. Tech Stack is just "we use X".

Component Types

Type	Purpose	Examples
Foundation	Cross-cutting, provides to business	Logger, Config, HTTP Framework
Business	Domain logic, processing	Renderer, Cache, Queue, Flows

Both Foundation and Business are valid components IF they have conventions consumers must follow.

When to List as Component

Has conventions for consumers?	Decision
Yes - consumers must follow rules	→ Component (Foundation or Business)
No - just "we use X library"	→ Tech Stack row only

Examples:

• Logger with structured field conventions → Foundation Component
• "We use pino" with no conventions → Tech Stack only
• Config with tag patterns consumers inject → Foundation Component
• "We use dotenv" → Tech Stack only

Foundation layer in diagrams: Show Foundation components in the Internal Structure diagram's Foundation layer, with arrows showing what they provide to Business components.

---

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: Foundation-First Discovery

Identify foundational aspects BEFORE business components.

Production-ready containers address common concerns. Discover what aspects apply, how they're addressed, and which establish conventions for business components.

Step 1: Identify relevant aspects

Based on container archetype, reason about which production-ready aspects apply:

Aspect	Question	If Conventions Exist → Foundation Component
Entry Point	How do requests/events enter?	Web Server, Event Handler, UI Framework
Request Pipeline	How are requests processed before business logic?	Middleware, Interceptors, Guards
Configuration	How are settings/secrets managed?	Config Provider (if injection patterns)
Logging	How is observability achieved?	Logger (if structured conventions)
Error Handling	How do errors propagate?	Error Handler (if error taxonomy)
Persistence	How do we talk to data stores?	DB Client, Connection Pool
External Integration	How do we call other services?	HTTP Client, SDK Wrappers
Operations	Health, metrics, graceful shutdown?	Health Provider, Metrics
State Management	How is application state managed?	State Store, Cache
Navigation/Routing	How do users/requests navigate?	Router (if route conventions)

Step 2: Ask how each relevant aspect is addressed

For each aspect that applies:

1. "How is [aspect] handled?" → Get the approach
2. "Are there conventions business components must follow?" → Determines if it's a Foundation component
3. "What patterns does it establish?" → Captures the conventions

Step 3: Then discover business components

Once foundation is understood, ask about domain logic:

• What are the core business operations?
• What services/handlers implement domain logic?
• What are the critical flows?

Phase 4: Archetype-Specific Questions

After foundation discovery, dive deeper by archetype:

• Service: Critical flows? Error scenarios? Integration points?
• Data: Schema patterns? Query conventions? Migration strategy?
• Boundary: Contract shape? Retry/fallback? Rate limiting?
• Platform: Deployment model? Scaling triggers? Recovery procedures?

---

Template

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

Required sections:

1. Inherited From Context
2. Overview
3. Technology Stack
4. Architecture - External Relationships (diagram + interface mapping table)
5. Architecture - Internal Structure (diagram with Foundation/Business layering)
6. Component Layering Rules
7. Components table (with Type column: Foundation/Business)
8. Key Flows

Components table format:

| ID | Name | Type | Responsibility |
|----|------|------|----------------|
| c3-N01 | Web Server | Foundation | Request entry, middleware pipeline |
| c3-N02 | Logger | Foundation | Structured logging conventions |
| c3-N03 | Auth Service | Business | User authentication, token management |
| c3-N04 | Order Service | Business | Order processing, validation |

Foundation components listed first, then Business components.

---

Diagram Requirements

Container level REQUIRES two diagrams:

1. External Relationships - Shows connections to other containers/external systems
2. 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):

1. Frontmatter (id, c3-version, title, type, parent, summary)
2. Inherited From Context
3. Overview
4. Technology Stack
5. Architecture - External Relationships (diagram REQUIRED)
6. Architecture - Internal Structure (diagram REQUIRED)
7. Components
8. 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)
• Foundation-first discovery completed - aspects identified before business components
• Components table has Type column - Foundation components listed first
• 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.
"Logger is just a tech choice"	If it has conventions for consumers (structured fields, levels), it's a Foundation component.
"Every atom/service needs a component"	Only if conventions exist. "We use X" → Tech Stack. Conventions for consumers → Component.

---

Common Mistakes

Mistake	Fix
Jumping to business components	Discover foundation aspects FIRST. Entry point, logging, config, etc.
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.
Confusing Foundation with Tech Stack	Foundation has conventions for consumers. Tech Stack is just "we use X".
Creating component for "we use X"	No conventions = no component. Only Tech Stack row.
Components table missing Type column	Always include Foundation/Business type for each component.

---

Related

• 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