C3 Architecture Design

C3 Architecture Design

⛔ CRITICAL GATE: Load Existing Documentation First

STOP - Before ANY exploration or design work, execute:

cat .c3/​README.md 2>/​dev/​null || echo "NO_CONTEXT"
cat .c3/​TOC.md 2>/​dev/​null || echo "NO_TOC"
ls -d .c3/​c3-*/  2>/​dev/​null || echo "NO_CONTAINERS"

Based on output:

• If docs exist → READ THEM before forming any hypothesis
• If "NO_CONTEXT" → Fresh project, proceed to Mode Detection

⚠️ DO NOT read completed ADRs unless user specifically asks:

• ADRs are historical records, not active guidance
• Reading them adds unnecessary context → hallucination risk
• Only read: Context (README.md), Containers, Components

Why this gate exists: Agents that skip existing documentation propose conflicting changes, miss established patterns, and waste user time.

Self-check before proceeding:

• I executed the commands above
• I read existing .c3/ docs (if they exist)
• My understanding comes from DOCS, not code exploration

---

Overview

Transform requirements into C3 documentation through iterative scoping. Also supports exploration-only mode.

Core principle: Hypothesis → Explore → Discover → Iterate until stable.

Announce: "I'm using the c3-design skill to guide architecture design."

---

Mode Detection

Exploration Mode

Quick read-only navigation:

1. Load .c3/​TOC.md
2. Present overview based on intent
3. Navigate on demand
4. If user wants changes → Switch to Design Mode

Design Mode

Full workflow with mandatory ADR creation.

⛔ DESIGN MODE GATE: Load References

# Load skill references (from plugin directory)
cat references/​design-guardrails.md
cat references/​adr-template.md

Self-check before proceeding:

• I read design-guardrails.md (common mistakes, red flags)
• I read adr-template.md (ADR structure, required sections)
• I understand ADR+Plan are inseparable (no ADR without Plan)

---

Design Mode Workflow

IMMEDIATELY create TodoWrite items:

1. Phase 1: Surface Understanding
2. Phase 2: Iterative Scoping
3. Phase 3: ADR Creation (MANDATORY)
4. Phase 4: Handoff

Phase 1: Surface Understanding

Form hypothesis about which layers are affected.

Input: User's request + loaded .c3/ docs Output: Written hypothesis statement Gate: Hypothesis formed referencing specific C3 docs

Example hypothesis:
"Based on c3-1 (Backend), this change affects Container level.
The user wants to add caching, which impacts c3-102 (Data Layer component)."

Phase 2: Iterative Scoping

Loop until stable: HYPOTHESIZE → EXPLORE → DISCOVER

Gate: No new discoveries in last iteration → Declare "Scope stable"

Phase 3: ADR Creation (MANDATORY)

⛔ NO code changes until ADR file exists.

Create ADR in .c3/​adr/​adr-YYYYMMDD-slug.md:

# Determine today's date and create ADR
today=$(date +%Y%m%d)
cat > .c3/​adr/​adr-${today}-{slug}.md << 'EOF'
---
id: adr-YYYYMMDD-{slug}
title: [Decision Title]
status: proposed
date: YYYY-MM-DD
---

# [Decision Title]

## Status
**Proposed** - YYYY-MM-DD

## Problem/​Requirement
[What triggered this decision]

## Exploration Journey
**Initial hypothesis:** [What we first thought]
**Explored:** [What we found at each direction]
**Discovered:** [Key insights]

## Solution
[The approach and why]

## Changes Across Layers
### Context Level
- [c3-0]: [What changes, why]

### Container Level  
- [c3-N-slug]: [What changes, why]

### Component Level
- [c3-NNN-slug]: [What changes, why]

## Verification
- [ ] [Check derived from exploration]

## Implementation Plan

### Code Changes
| Layer Change | Code Location | Action | Details |
|--------------|---------------|--------|---------|

### Acceptance Criteria
| Verification Item | Criterion | How to Test |
|-------------------|-----------|-------------|

## Related
- [Links to affected docs]
EOF

Gate: ADR file exists on disk

# Verify ADR was created
ls .c3/​adr/​adr-*.md

Phase 4: Handoff

Execute handoff steps (from .c3/​settings.yaml or defaults):

1. Summarize changes to user
2. List next actions
3. Confirm completion

Gate: All steps executed with evidence

---

Layer Skill Delegation

When you identify which layer is affected, INVOKE the layer skill:

---

⛔ Enforcement Harnesses

Harness 1: Skill Delegation (No Hallucination)

Rule: When work requires a layer skill, INVOKE it. Never describe what it "would do."

🚩 Red Flag: Using layer skill name without Skill tool invocation in conversation

Harness 2: ADR-Before-Code

Rule: NO code changes until ADR file exists in Design Mode.

🚩 Red Flag: Edit/​Write tool used before ADR file created

---

Verification Checklist

Before claiming completion, verify:

# If Design Mode: Verify ADR exists
ls .c3/​adr/​adr-*.md 2>/​dev/​null | tail -1

# Verify no orphaned changes (ADR lists them)
cat .c3/​adr/​adr-*.md | grep -A20 "Changes Across Layers"

• Critical gate executed (existing docs loaded)
• Mode detected correctly
• If Design Mode: All 4 phases completed with gates
• If Design Mode: ADR file exists with all sections
• Layer skills invoked (not described)
• Handoff executed

---

📚 Reading Chain Output

At the end of your work, output a contextual reading chain based on what you discovered.

Format:

## 📚 To Go Deeper

Based on this work affecting [layer/​component], relevant reading:

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

**Siblings (coordinate changes):**
├─ c3-NMM - [why relevant]
└─ c3-NKK - [why relevant]

**Downstream (propagate changes):**
└─ c3-NNNX - [affected by this change]

*Reading chain generated from actual doc relationships.*

Rules:

• Only include docs you actually read or identified during exploration
• Explain WHY each doc is relevant (not generic)
• Never include ADRs unless user asked about decisions

---

Related

• references/​design-guardrails.md - Key principles, common mistakes
• references/​design-phases.md - Phase details
• references/​adr-template.md - Full ADR template with examples
• references/​design-exploration-mode.md - Exploration workflow