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

User Intent	Mode	Next Step
"What's the architecture?"	Exploration	Load TOC → Present overview
"How does X work?"	Exploration	Load relevant docs → Explain
"I need to add/change..."	Design	Full workflow with ADR
"Why did we choose X?"	Exploration	Search ADRs → Present

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

Step	Action
Hypothesize	"This change affects [layers/docs]"
Explore	Use layer skills to investigate (invoke them, don't describe)
Discover	Find actual impacts, adjust hypothesis

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:

Impact	Action
Container inventory changes	Use Skill tool → c3-context-design
Component organization	Use Skill tool → c3-container-design
Implementation details	Use Skill tool → c3-component-design

---

⛔ Enforcement Harnesses

Harness 1: Skill Delegation (No Hallucination)

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

Anti-Pattern	Correct Action
"c3-container-design would create..."	Use Skill tool → c3-container-design
"Following c3-component-design patterns..."	Invoke the skill first
Summarizing skill output without invoking	Invoke, get real output

🚩 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.

Anti-Pattern	Correct Action
"Let me fix this quickly first"	Create ADR first
"I'll create ADR after fixing"	ADR before any edit
Making code changes in Phase 1-2	Only read code, don't modify

🚩 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