add c4 documentation workflow and agents (#129)

* add c4 documentation workflow and agents

* update the c4-code agent to use proper mermaid diagram types

docs/agents.md

@@ -1,6 +1,6 @@
 # Agent Reference
 
-Complete reference for all **86 specialized AI agents** organized by category with model assignments.
+Complete reference for all **91 specialized AI agents** organized by category with model assignments.
 
 ## Agent Categories
 
@@ -152,6 +152,10 @@ Complete reference for all **86 specialized AI agents** organized by category wi
 | [reference-builder](../plugins/documentation-generation/agents/reference-builder.md) | haiku | Technical references and API documentation |
 | [tutorial-engineer](../plugins/code-documentation/agents/tutorial-engineer.md) | sonnet | Step-by-step tutorials and educational content |
 | [mermaid-expert](../plugins/documentation-generation/agents/mermaid-expert.md) | sonnet | Diagram creation (flowcharts, sequences, ERDs) |
+| [c4-code](../plugins/c4-architecture/agents/c4-code.md) | haiku | C4 Code-level documentation with function signatures and dependencies |
+| [c4-component](../plugins/c4-architecture/agents/c4-component.md) | sonnet | C4 Component-level architecture synthesis and documentation |
+| [c4-container](../plugins/c4-architecture/agents/c4-container.md) | sonnet | C4 Container-level architecture with API documentation |
+| [c4-context](../plugins/c4-architecture/agents/c4-context.md) | sonnet | C4 Context-level system documentation with personas and user journeys |
 
 ### Business & Operations
 
@@ -211,8 +215,8 @@ Agents are assigned to specific Claude models based on task complexity and compu
 
 | Model | Agent Count | Use Case |
 |-------|-------------|----------|
-| Haiku | 47 | Fast execution tasks: testing, documentation, ops, database optimization, business |
-| Sonnet | 97 | Complex reasoning, architecture, language expertise, orchestration, security |
+| Haiku | 48 | Fast execution tasks: testing, documentation, ops, database optimization, business |
+| Sonnet | 100 | Complex reasoning, architecture, language expertise, orchestration, security |
 
 ### Model Selection Criteria
 

docs/architecture.md

@@ -36,7 +36,7 @@ This marketplace follows industry best practices with a focus on granularity, co
 
 ### Plugin Distribution
 
-- **63 focused plugins** optimized for specific use cases
+- **65 focused plugins** optimized for specific use cases
 - **23 clear categories** with 1-6 plugins each for easy discovery
 - Organized by domain:
   - **Development**: 4 plugins (debugging, backend, frontend, multi-platform)
@@ -48,10 +48,10 @@ This marketplace follows industry best practices with a focus on granularity, co
 
 ### Component Breakdown
 
-**85 Specialized Agents**
+**91 Specialized Agents**
 - Domain experts with deep knowledge
 - Organized across architecture, languages, infrastructure, quality, data/AI, documentation, business, and SEO
-- Model-optimized (47 Haiku, 97 Sonnet) for performance and cost
+- Model-optimized (48 Haiku, 100 Sonnet) for performance and cost
 
 **15 Workflow Orchestrators**
 - Multi-agent coordination systems
@@ -77,7 +77,7 @@ This marketplace follows industry best practices with a focus on granularity, co
 ```
 claude-agents/
 ├── .claude-plugin/
-│   └── marketplace.json          # Marketplace catalog (63 plugins)
+│   └── marketplace.json          # Marketplace catalog (65 plugins)
 ├── plugins/                       # Isolated plugin directories
 │   ├── python-development/
 │   │   ├── agents/               # Python language agents
@@ -112,6 +112,14 @@ claude-agents/
 │   │   │   └── security-dependencies.md
 │   │   └── skills/               # Security skills (1 total)
 │   │       └── sast-configuration/
+│   ├── c4-architecture/
+│   │   ├── agents/               # C4 architecture agents
+│   │   │   ├── c4-code.md
+│   │   │   ├── c4-component.md
+│   │   │   ├── c4-container.md
+│   │   │   └── c4-context.md
+│   │   └── commands/
+│   │       └── c4-architecture.md
 │   └── ... (60 more isolated plugins)
 ├── docs/                          # Documentation
 │   ├── agent-skills.md           # Agent Skills guide
@@ -193,8 +201,8 @@ The system uses Claude Opus and Sonnet models strategically:
 
 | Model | Count | Use Case |
 |-------|-------|----------|
-| Haiku | 47 agents | Fast execution, deterministic tasks |
-| Sonnet | 97 agents | Complex reasoning, architecture decisions |
+| Haiku | 48 agents | Fast execution, deterministic tasks |
+| Sonnet | 100 agents | Complex reasoning, architecture decisions |
 
 ### Selection Criteria
 
@@ -247,7 +255,7 @@ code-reviewer (Sonnet) validates architecture
 ### Component Coverage
 
 - **100% agent coverage** - all plugins include at least one agent
-- **100% component availability** - all 85 agents accessible across plugins
+- **100% component availability** - all 91 agents accessible across plugins
 - **Efficient distribution** - 3.4 components per plugin average
 
 ### Discoverability
@@ -375,5 +383,5 @@ Feature Development Workflow:
 
 - [Agent Skills](./agent-skills.md) - Modular knowledge packages
 - [Agent Reference](./agents.md) - Complete agent catalog
-- [Plugin Reference](./plugins.md) - All 63 plugins
+- [Plugin Reference](./plugins.md) - All 65 plugins
 - [Usage Guide](./usage.md) - Commands and workflows

docs/plugins.md

@@ -1,6 +1,6 @@
 # Complete Plugin Reference
 
-Browse all **63 focused, single-purpose plugins** organized by category.
+Browse all **65 focused, single-purpose plugins** organized by category.
 
 ## Quick Start - Essential Plugins
 
@@ -125,12 +125,13 @@ Next.js, React + Vite, and Node.js project setup with pnpm and TypeScript best p
 | **frontend-mobile-development** | Frontend UI and mobile development | `/plugin install frontend-mobile-development` |
 | **multi-platform-apps** | Cross-platform app coordination (web/iOS/Android) | `/plugin install multi-platform-apps` |
 
-### 📚 Documentation (2 plugins)
+### 📚 Documentation (3 plugins)
 
 | Plugin | Description | Install |
 |--------|-------------|---------|
 | **code-documentation** | Documentation generation and code explanation | `/plugin install code-documentation` |
 | **documentation-generation** | OpenAPI specs, Mermaid diagrams, tutorials | `/plugin install documentation-generation` |
+| **c4-architecture** | Comprehensive C4 architecture documentation workflow with bottom-up code analysis, component synthesis, container mapping, and context diagrams | `/plugin install c4-architecture` |
 
 ### 🔄 Workflows (3 plugins)
 
@@ -328,7 +329,7 @@ plugins/python-development/
 /plugin marketplace add wshobson/agents
 ```
 
-This makes all 63 plugins available for installation, but **does not load any agents or tools** into your context.
+This makes all 65 plugins available for installation, but **does not load any agents or tools** into your context.
 
 ### Step 2: Install Specific Plugins
 

docs/usage.md

@@ -120,6 +120,7 @@ Claude Code automatically selects and coordinates the appropriate agents based o
 | `/code-documentation:doc-generate` | Generate comprehensive documentation |
 | `/code-documentation:code-explain` | Explain code functionality |
 | `/documentation-generation:doc-generate` | OpenAPI specs, diagrams, tutorials |
+| `/c4-architecture:c4-architecture` | Generate comprehensive C4 architecture documentation (Context, Container, Component, Code) |
 
 ### Refactoring & Maintenance
 
@@ -262,6 +263,27 @@ Plugins provide pre-configured multi-agent workflows accessible via slash comman
 
 **Orchestration:** incident-responder → devops-troubleshooter → debugger → error-detective → observability-engineer
 
+### C4 Architecture Documentation
+
+```bash
+# Generate comprehensive C4 architecture documentation
+/c4-architecture:c4-architecture
+
+# Natural language alternative
+"Create C4 architecture documentation for this codebase"
+```
+
+**Orchestration:** c4-code → c4-component → c4-container → c4-context
+
+**What happens:**
+
+1. **Code Level**: Bottom-up analysis of all subdirectories, creating code-level documentation with function signatures and dependencies
+2. **Component Level**: Synthesizes code documentation into logical components with interfaces and relationships
+3. **Container Level**: Maps components to deployment containers with OpenAPI/Swagger API specifications
+4. **Context Level**: Creates high-level system context with personas, user journeys, and external dependencies
+
+**Output:** Complete C4 documentation in `C4-Documentation/` directory with Mermaid diagrams at all levels (Context, Container, Component, Code)
+
 ## Command Arguments and Options
 
 Many slash commands support arguments for precise control:
@@ -289,6 +311,9 @@ Many slash commands support arguments for precise control:
 
 # Python project scaffolding
 /python-development:python-scaffold fastapi-microservice
+
+# C4 architecture documentation generation
+/c4-architecture:c4-architecture
 ```
 
 ## Combining Natural Language and Commands
@@ -367,5 +392,5 @@ See [Agent Skills](./agent-skills.md) for details on the 47 specialized skills.
 
 - [Agent Skills](./agent-skills.md) - Specialized knowledge packages
 - [Agent Reference](./agents.md) - Complete agent catalog
-- [Plugin Reference](./plugins.md) - All 63 plugins
+- [Plugin Reference](./plugins.md) - All 65 plugins
 - [Architecture](./architecture.md) - Design principles