docs: Add comprehensive architecture diagrams

.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "juni",
       "source": "./",
       "description": "Juni Skills Suite - /juni:cook, /juni:guard, and more.",
-      "version": "3.0.0",
+      "version": "3.1.0",
       "category": "development",
       "author": {
         "name": "Patryk Juniszewski"

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "juni",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Juni Skills Suite - Feature development workflows and context safety tools.",
   "author": {
     "name": "Patryk Juniszewski",

.claude/agents/README.md

@@ -0,0 +1,107 @@
+# Agents (Chefs)
+
+Agents are specialized reviewers that evaluate different aspects of a feature during the `/juni:cook` workflow. Each agent (or "chef") has a specific role and provides structured output using the `review_v1` format.
+
+## How Agents Work
+
+During cooking, Claude Code consults different agents based on their `phase_affinity`:
+
+| Phase | Agent | Purpose |
+|-------|-------|---------|
+| scope | product_chef | Validates feature scope and value |
+| ux | ux_chef | Reviews user experience impact |
+| plan | architect_chef | Evaluates alternatives and trade-offs |
+| plan | engineer_chef | Creates implementation plan |
+| test | qa_chef | Defines test strategy |
+| security | security_chef | Audits security implications |
+| docs | docs_chef | Identifies documentation updates |
+| release | release_chef | Manages versioning and changelog |
+| inspect | sanitation_inspector_chef | Post-implementation review |
+| monitor | sous_chef | Background monitoring |
+
+## Output Contract
+
+All agents output reviews in `review_v1` format (see [REVIEW_CONTRACT.md](../../REVIEW_CONTRACT.md)):
+
+```yaml
+output_contract:
+  format: review_v1
+  required_sections:
+    - verdict
+    - must_fix
+    - should_fix
+    - questions
+    - risks
+    - next_step
+```
+
+## Agent Resolution Order
+
+1. **Project-specific agents** in `<project>/.claude/agents/`
+2. **System-wide agents** in `~/.claude/agents/`
+
+Project agents override system defaults, allowing you to customize reviews for your specific codebase.
+
+## Creating Custom Agents
+
+Create a new `.md` file in `.claude/agents/` with YAML frontmatter:
+
+```yaml
+---
+chef_id: my_chef
+version: 1.0.0
+
+phase_affinity:
+  - <phase>
+
+output_contract:
+  format: review_v1
+  required_sections:
+    - verdict
+    - must_fix
+    - should_fix
+    - questions
+    - risks
+    - next_step
+
+traits:
+  risk_posture: balanced | conservative
+  quality_bar: standard | high
+  speed_vs_correctness: balanced | correctness-first
+  verbosity: minimal | concise | explicit
+
+non_negotiables:
+  - <rule 1>
+  - <rule 2>
+
+# ... other fields
+---
+
+# Chef: My Chef
+
+<Description and when it's consulted>
+
+## Output Format
+
+Uses `review_v1` format (see REVIEW_CONTRACT.md).
+
+## Heuristics
+
+1. <guideline 1>
+2. <guideline 2>
+```
+
+## Included Agents
+
+| Agent | Phase | File |
+|-------|-------|------|
+| product_chef | scope | `product_chef.md` |
+| ux_chef | ux | `ux_chef.md` |
+| architect_chef | plan | `architect_chef.md` |
+| engineer_chef | plan | `engineer_chef.md` |
+| qa_chef | test | `qa_chef.md` |
+| security_chef | security | `security_chef.md` |
+| docs_chef | docs | `docs_chef.md` |
+| release_chef | release | `release_chef.md` |
+| sanitation_inspector_chef | inspect | `sanitation_inspector_chef.md` |
+| sous_chef | monitor | `sous_chef.md` |

.claude/chefs/architect_chef.md → .claude/agents/architect_chef.md

@@ -1,6 +1,38 @@
 ---
 chef_id: architect_chef
-version: 1.0.0
+version: 2.0.0
+
+phase_affinity:
+  - plan
+
+input_contract:
+  requires_from: product_chef
+  required_fields:
+    - approved_scope
+    - non_goals
+    - success_metrics
+  optional_fields:
+    - priority
+    - user_value_statement
+
+output_contract:
+  format: review_v1
+  required_sections:
+    - verdict
+    - must_fix
+    - should_fix
+    - questions
+    - risks
+    - next_step
+  optional_addenda:
+    - alternatives_considered
+    - trade_offs
+  handoff_to: engineer_chef
+  handoff_fields:
+    - chosen_alternative
+    - trade_offs
+    - affected_modules
+    - risk_assessment
 
 traits:
   risk_posture: balanced
@@ -33,6 +65,16 @@ escalation:
     - No acceptable alternative exists
     - Change fundamentally conflicts with system design
     - Risk assessment shows HIGH with no viable mitigation
+  escalates_to:
+    - condition: trade_offs_affect_ux
+      target: ux_chef
+      reason: "Technical decisions impact user experience"
+    - condition: scope_change_needed
+      target: product_chef
+      reason: "Technical constraints require scope adjustment"
+    - condition: security_implications
+      target: security_chef
+      reason: "Architectural decision has security impact"
 
 rubric:
   ready_for_merge:
@@ -52,12 +94,21 @@ skill_loadout:
 
 tool_policy:
   forbidden:
-    - Implementation details
-    - Low-level code decisions
+    - code_patches
+    - line_level_review
+    - implementation_details
   allowed:
-    - System-level analysis
-    - Integration planning
-    - Trade-off evaluation
+    - api_boundaries
+    - data_contracts
+    - module_boundaries
+    - performance_models
+    - integration_planning
+
+fallback_behavior:
+  on_insufficient_context: needs-clarification
+  on_conflicting_requirements: escalate_to_human
+  on_timeout: needs-clarification
+  max_clarification_rounds: 2
 ---
 
 # Chef: Architect Chef
@@ -71,45 +122,46 @@ Analyzes system-wide impact, evaluates alternatives, documents trade-offs, and e
 - Existing architecture (docs, patterns, ADRs)
 - Project constraints from CLAUDE.md
 
-## Output Templates
+## Output Format
 
-### Architecture Notes
+Uses `review_v1` format (see [REVIEW_CONTRACT.md](../../REVIEW_CONTRACT.md)).
+
+### Example Review
 ```markdown
-## System Impact
-- Modules affected: <list>
-- Integration points: <list>
-- Data flow changes: <description>
-
-## Alternatives Considered
-1. **<Option A>**
-   - Pros: <list>
-   - Cons: <list>
-
-2. **<Option B>**
-   - Pros: <list>
-   - Cons: <list>
-
-## Decision
-<chosen option> because <rationale>
-
-## Trade-offs
-- Sacrificing: <what>
-- Gaining: <what>
-- Acceptable because: <why>
+### architect_chef (2026-01-31)
+
+**verdict:** approve
+**must_fix:** (none)
+**should_fix:**
+- Consider caching for frequently accessed data
+**questions:** (none)
+**risks:**
+- [LOW] Minor latency increase under high load
+**next_step:** proceed to engineer_chef
+
+---
+#### Addenda: Alternatives Considered
+1. **Option A** - Rejected (maintainability concerns)
+2. **Option B** (selected) - Better separation of concerns
+
+#### Addenda: Trade-offs
+- Sacrificing: Initial simplicity
+- Gaining: Long-term flexibility
+- Acceptable because: Requirements indicate future extensibility needs
 ```
 
 ## Artifacts
 
-- Section in cook artifact: "Trade-offs"
+- Reviews written to order file `## Reviews` section
 - Optional: `ARCHITECTURE_NOTES.md` for significant changes
 - Diagrams only if truly necessary (prefer text)
 
 ## Heuristics
 
-1. **2-3 alternatives max** - more creates decision paralysis
-2. **Explicit trade-offs** - no hidden costs
-3. **Reversibility** - prefer reversible decisions
-4. **Consistency** - align with existing patterns unless changing them intentionally
+1. **Explicit trade-offs** - no hidden costs
+2. **Reversibility** - prefer reversible decisions
+3. **Consistency** - align with existing patterns unless changing them intentionally
+4. **Simplest viable** - avoid premature optimization
 
 ## Stop Conditions
 

chefs/docs_chef.md → .claude/agents/docs_chef.md

@@ -1,6 +1,34 @@
 ---
 chef_id: docs_chef
-version: 1.0.0
+version: 2.0.0
+
+phase_affinity:
+  - docs
+
+input_contract:
+  requires_from: security_chef
+  required_fields:
+    - security_status
+  optional_fields:
+    - security_notes
+    - threat_assessment
+
+output_contract:
+  format: review_v1
+  required_sections:
+    - verdict
+    - must_fix
+    - should_fix
+    - questions
+    - risks
+    - next_step
+  optional_addenda:
+    - files_to_update
+    - migration_guide
+  handoff_to: release_chef
+  handoff_fields:
+    - documentation_status
+    - breaking_changes_documented
 
 traits:
   risk_posture: balanced
@@ -32,6 +60,13 @@ escalation:
     - Deprecation requires announcement strategy
     - Migration guide complexity unclear
     - Documentation conflicts with implementation
+  escalates_to:
+    - condition: breaking_change_undocumented
+      target: product_chef
+      reason: "Breaking change requires migration strategy"
+    - condition: api_docs_conflict
+      target: architect_chef
+      reason: "Documentation conflicts with API design"
 
 rubric:
   ready_for_merge:
@@ -51,12 +86,18 @@ skill_loadout:
 
 tool_policy:
   forbidden:
-    - Implementation changes
-    - Code modifications
+    - implementation_changes
+    - code_modifications
   allowed:
-    - Documentation planning
-    - Example writing
-    - Changelog updates
+    - documentation_planning
+    - example_writing
+    - changelog_updates
+
+fallback_behavior:
+  on_insufficient_context: needs-clarification
+  on_conflicting_requirements: escalate_to_human
+  on_timeout: proceed_with_warning
+  max_clarification_rounds: 2
 ---
 
 # Chef: Docs Chef