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:

Load .c3/TOC.md
Present overview based on intent
Navigate on demand
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:

Phase 1: Surface Understanding
Phase 2: Iterative Scoping
Phase 3: ADR Creation (MANDATORY)
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):

Summarize changes to user
List next actions
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

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