@zenuml/core 3.32.6 → 3.33.0

package/.claude/commands/README.md

@@ -0,0 +1,162 @@
+# 🔧 Command Templates
+
+Orchestration templates that enable Claude Code to coordinate multi-agent workflows for different development tasks.
+
+## Overview
+
+After reading the [main kit documentation](../README.md), you'll understand how these commands fit into the integrated system. Each command:
+
+- **Auto-loads** the appropriate documentation tier for its task
+- **Spawns specialized agents** based on complexity 
+- **Integrates MCP servers** when external expertise helps
+- **Maintains documentation** to keep AI context current
+
+### 🚀 Automatic Context Injection
+
+All commands benefit from automatic context injection via the `subagent-context-injector.sh` hook:
+
+- **Core documentation auto-loaded**: Every command and sub-agent automatically receives `@/docs/CLAUDE.md`, `@/docs/ai-context/project-structure.md`, and `@/docs/ai-context/docs-overview.md`
+- **No manual context loading**: Sub-agents spawned by commands automatically have access to essential project documentation
+- **Consistent knowledge**: All agents start with the same foundational understanding
+
+## Available Commands
+
+### 📊 `/full-context`
+**Purpose**: Comprehensive context gathering and analysis when you need deep understanding or plan to execute code changes.
+
+**When to use**:
+- Starting work on a new feature or bug
+- Need to understand how systems interconnect
+- Planning architectural changes
+- Any task requiring thorough analysis before implementation
+
+**How it works**: Adaptively scales from direct analysis to multi-agent orchestration based on request complexity. Agents read documentation, analyze code, map dependencies, and consult MCP servers as needed.
+
+### 🔍 `/code-review` 
+**Purpose**: Get multiple expert perspectives on code quality, focusing on high-impact findings rather than nitpicks.
+
+**When to use**:
+- After implementing new features
+- Before merging important changes
+- When you want security, performance, and architecture insights
+- Need confidence in code quality
+
+**How it works**: Spawns specialized agents (security, performance, architecture) that analyze in parallel. Each agent focuses on critical issues that matter for production code.
+
+### 🧠 `/gemini-consult` *(Requires Gemini MCP Server)*
+**Purpose**: Engage in deep, iterative conversations with Gemini for complex problem-solving and architectural guidance.
+
+**When to use**:
+- Tackling complex architectural decisions
+- Need expert guidance on implementation approaches
+- Debugging intricate issues across multiple files
+- Exploring optimization strategies
+- When you need a thinking partner for difficult problems
+
+**How it works**: Creates persistent conversation sessions with Gemini, automatically attaching project context and MCP-ASSISTANT-RULES.md. Supports iterative refinement through follow-up questions and implementation feedback.
+
+**Key features**:
+- Context-aware problem detection when no arguments provided
+- Persistent sessions maintained throughout problem lifecycle
+- Automatic attachment of foundational project documentation
+- Support for follow-up questions with session continuity
+
+### 📝 `/update-docs`
+**Purpose**: Keep documentation synchronized with code changes, ensuring AI context remains current.
+
+**When to use**:
+- After modifying code
+- After adding new features
+- When project structure changes
+- Following any significant implementation
+
+**How it works**: Analyzes what changed and updates the appropriate CLAUDE.md files across all tiers. Maintains the context that future AI sessions will rely on.
+
+### 📄 `/create-docs`
+**Purpose**: Generate initial documentation structure for existing projects that lack AI-optimized documentation.
+
+**When to use**:
+- Adopting the framework in an existing project
+- Starting documentation from scratch
+- Need to document legacy code
+- Setting up the 3-tier structure
+
+**How it works**: Analyzes your project structure and creates appropriate CLAUDE.md files at each tier, establishing the foundation for AI-assisted development.
+
+### ♻️ `/refactor`
+**Purpose**: Intelligently restructure code while maintaining functionality and updating all dependencies.
+
+**When to use**:
+- Breaking up large files
+- Improving code organization
+- Extracting reusable components
+- Cleaning up technical debt
+
+**How it works**: Analyzes file structure, maps dependencies, identifies logical split points, and handles all import/export updates across the codebase.
+
+### 🤝 `/handoff`
+**Purpose**: Preserve context when ending a session or when the conversation becomes too long.
+
+**When to use**:
+- Ending a work session
+- Context limit approaching
+- Switching between major tasks
+- Supplementing `/compact` with permanent storage
+
+**How it works**: Updates the handoff documentation with session achievements, current state, and next steps. Ensures smooth continuation in future sessions.
+
+## Integration Patterns
+
+### Typical Workflow
+```bash
+/full-context "implement user notifications"    # Understand
+# ... implement the feature ...
+/code-review "review notification system"       # Validate  
+/update-docs "document notification feature"    # Synchronize
+/handoff "completed notification system"        # Preserve
+```
+
+### Quick Analysis
+```bash
+/full-context "why is the API slow?"           # Investigate
+# ... apply fixes ...
+/update-docs "document performance fixes"       # Update context
+```
+
+### Major Refactoring
+```bash
+/full-context "analyze authentication module"   # Understand current state
+/refactor "@auth/large-auth-file.ts"          # Restructure
+/code-review "review refactored auth"          # Verify quality
+/update-docs "document new auth structure"     # Keep docs current
+```
+
+### Complex Problem Solving
+```bash
+/gemini-consult "optimize real-time data pipeline" # Start consultation
+# ... implement suggested approach ...
+/gemini-consult                                    # Follow up with results
+/update-docs "document optimization approach"      # Capture insights
+```
+
+## Customization
+
+Each command template can be adapted:
+
+- **Adjust agent strategies** - Modify how many agents spawn and their specializations
+- **Change context loading** - Customize which documentation tiers load
+- **Tune MCP integration** - Adjust when to consult external services
+- **Modify output formats** - Tailor results to your preferences
+
+Commands are stored in `.claude/commands/` and can be edited directly.
+
+## Key Principles
+
+1. **Commands work together** - Each command builds on others' outputs
+2. **Documentation stays current** - Commands maintain their own context
+3. **Complexity scales naturally** - Simple tasks stay simple, complex tasks get sophisticated analysis
+4. **Context is continuous** - Information flows between sessions through documentation
+
+---
+
+*For detailed implementation of each command, see the individual command files in this directory.*

package/.claude/commands/code-review.md

@@ -0,0 +1,322 @@
+# /code-review
+
+*Performs focused multi-agent code review that surfaces only critical, high-impact findings for solo developers using AI tools.*
+
+## Core Philosophy
+
+This command prioritizes **needle-moving discoveries** over exhaustive lists. Every finding must demonstrate significant impact on:
+- System reliability & stability
+- Security vulnerabilities with real exploitation risk
+- Performance bottlenecks affecting user experience
+- Architectural decisions blocking future scalability
+- Critical technical debt threatening maintainability
+
+### 🚨 Critical Findings Only
+Issues that could cause production failures, security breaches, or severe user impact within 48 hours.
+
+### 🔥 High-Value Improvements
+Changes that unlock new capabilities, remove significant constraints, or improve metrics by >25%.
+
+### ❌ Excluded from Reports
+Minor style issues, micro-optimizations (<10%), theoretical best practices, edge cases affecting <1% of users.
+
+
+## Auto-Loaded Project Context:
+@/CLAUDE.md
+@/docs/ai-context/project-structure.md
+@/docs/ai-context/docs-overview.md
+
+
+## Command Execution
+
+User provided context: "$ARGUMENTS"
+
+### Step 1: Understand User Intent & Gather Context
+
+#### Parse the Request
+Analyze the natural language input to determine:
+1. **What to review**: Parse file paths, component names, feature descriptions, or commit references
+2. **Review focus**: Identify any specific concerns mentioned (security, performance, etc.)
+3. **Scope inference**: Intelligently determine the breadth of review needed
+
+Examples of intent parsing:
+- "the authentication flow" → Find all files related to auth across the codebase
+- "voice pipeline implementation" → Locate voice processing components
+- "recent changes" → Parse git history for relevant commits
+- "the API routes" → Identify all API endpoint files
+
+#### Read Relevant Documentation
+Before allocating agents, **read the documentation** to understand:
+1. Use `/docs/ai-context/docs-overview.md` to identify relevant docs
+2. Read documentation related to the code being reviewed:
+   - Architecture docs for subsystem understanding
+   - API documentation for integration points
+   - Security guidelines for sensitive areas
+   - Performance considerations for critical paths
+3. Build a mental model of risks, constraints, and priorities
+
+This context ensures intelligent agent allocation based on actual project knowledge.
+
+### Step 2: Define Mandatory Coverage Areas
+
+Every code review MUST analyze these core areas, with depth determined by scope:
+
+#### 🎯 Mandatory Coverage Areas:
+
+1. **Critical Path Analysis**
+   - User-facing functionality that could break
+   - Data integrity and state management
+   - Error handling and recovery mechanisms
+
+2. **Security Surface**
+   - Input validation and sanitization
+   - Authentication/authorization flows
+   - Data exposure and API security
+
+3. **Performance Impact**
+   - Real-time processing bottlenecks
+   - Resource consumption (memory, CPU)
+   - Scalability constraints
+
+4. **Integration Points**
+   - API contracts and boundaries
+   - Service dependencies
+   - External system interactions
+
+#### 📊 Dynamic Agent Allocation:
+
+Based on review scope, allocate agents proportionally:
+
+**Small to medium Scope (small set of files or small feature)**
+- 2-3 agents covering mandatory areas
+- Each agent handles 1-2 coverage areas
+- Focus on highest-risk aspects
+
+**Large Scope (many files, major feature or subsystem)**
+- 4-6 agents with specialized focus
+- Each mandatory area gets dedicated coverage
+- Additional agents for cross-cutting concerns
+
+### Step 3: Dynamic Agent Generation
+
+Based on scope analysis and mandatory coverage areas, dynamically create specialized agents:
+
+#### Agent Generation Strategy:
+
+**With your documentation knowledge from Step 1, think deeply** about optimal agent allocation:
+- Leverage your understanding of the project architecture and risks
+- Consider the specific documentation you read about this subsystem
+- Apply insights about critical paths and security considerations
+- Use documented boundaries and integration points to partition work
+- Factor in any performance or scalability concerns from the docs
+
+Use your understanding of the project to intuitively determine:
+1. **How many agents are needed** - Let the code's complexity and criticality guide you
+2. **How to partition the work** - Follow natural architectural boundaries
+3. **Which specializations matter most** - Focus agents where risk is highest
+
+**Generate Specialized Agents**
+
+   For each allocated agent, create a focused role:
+
+   **Example for 6-agent allocation:**
+   - Agent 1: Critical_Path_Validator (user flows + error handling)
+   - Agent 2: Security_Scanner (input validation + auth)
+   - Agent 3: API_Security_Auditor (data exposure + boundaries)
+   - Agent 4: Performance_Profiler (bottlenecks + resource usage)
+   - Agent 5: Scalability_Analyst (constraints + growth paths)
+   - Agent 6: Integration_Verifier (dependencies + contracts)
+
+   **Example for 3-agent allocation:**
+   - Agent 1: Security_Performance_Analyst (security + performance areas)
+   - Agent 2: Critical_Path_Guardian (functionality + integrations)
+   - Agent 3: Risk_Quality_Assessor (technical debt + code quality)
+
+#### Dynamic Focus Areas:
+
+Each agent receives specialized instructions based on:
+- **File characteristics**: API endpoints → security focus
+- **Code patterns**: Loops/algorithms → performance focus
+- **Dependencies**: External services → integration focus
+- **User touchpoints**: UI/voice → critical path focus
+
+### Step 4: Execute Dynamic Multi-Agent Review
+
+**Before launching agents, pause and think deeply:**
+- What are the real risks in this code?
+- Which areas could cause the most damage if they fail?
+- Where would a solo developer need the most help?
+
+Generate and launch agents based on your thoughtful analysis:
+
+```
+For each dynamically generated agent:
+  Task: "As [Agent_Role], analyze [assigned_coverage_areas] in [target_scope].
+
+  MANDATORY COVERAGE CHECKLIST:
+  ☐ Critical Path: [assigned aspects]
+  ☐ Security: [assigned aspects]
+  ☐ Performance: [assigned aspects]
+  ☐ Integration: [assigned aspects]
+
+  HIGH-IMPACT REVIEW MANDATE:
+  Focus ONLY on findings that significantly move the needle for a solo developer.
+
+  Review workflow:
+  1. Review auto-loaded project context (CLAUDE.md, project-structure.md, docs-overview.md)
+  2. Analyze your assigned coverage areas with deep focus
+  3. For complex issues, use:
+     - mcp__gemini__consult_gemini for architectural analysis
+     - mcp__context7__get-library-docs for framework best practices
+  4. Cross-reference with other coverage areas for systemic issues
+  5. Document ONLY high-impact findings:
+
+     ## [Coverage_Area] Analysis by [Agent_Role]
+
+     ### 🚨 Critical Issues (Production Risk)
+     - Issue: [description]
+     - Location: [file:line_number]
+     - Impact: [quantified - downtime hours, users affected, data at risk]
+     - Fix: [specific code snippet]
+     - Consequence if ignored: [what happens in 48 hours]
+
+     ### 🎯 Strategic Improvements (Capability Unlocks)
+     - Limitation: [what's currently blocked]
+     - Solution: [architectural change or implementation]
+     - Unlocks: [new capability or scale]
+     - ROI: [effort hours vs benefit quantified]
+
+     ### ⚡ Quick Wins (Optional)
+     - Only include if <2 hours for >20% improvement
+     - Must show measurable impact
+
+  REMEMBER: Every finding must pass the 'so what?' test for a solo developer."
+```
+
+#### Parallel Execution Strategy:
+
+**Launch all agents simultaneously** for maximum efficiency
+
+
+### Step 5: Synthesize Findings with Maximum Analysis Power
+
+After all sub-agents complete their analysis:
+
+**ultrathink**
+
+Activate maximum cognitive capabilities to:
+
+1. **Filter for Impact**
+   - Discard all low-priority findings
+   - Quantify real-world impact of each issue
+   - Focus on production risks and capability unlocks
+
+2. **Deep Pattern Analysis**
+   - Identify systemic issues vs isolated problems
+   - Find root causes across agent reports
+   - Detect subtle security vulnerabilities
+
+3. **Strategic Prioritization**
+   - Calculate ROI for each improvement
+   - Consider solo developer constraints
+   - Create actionable fix sequence
+   ```markdown
+   # Code Review Summary
+
+   **Reviewed**: [scope description]
+   **Date**: [current date]
+   **Overall Quality Score**: [A-F grade with justification]
+
+   ## Key Metrics
+   - Security Risk Level: [Critical/High/Medium/Low]
+   - Performance Impact: [description]
+   - Technical Debt: [assessment]
+   - Test Coverage: [if applicable]
+   ```
+
+### Step 6: Present Comprehensive Review
+
+Structure the final output as:
+
+```markdown
+# 🔍 Code Review Report
+
+## Executive Summary
+[High-level findings and overall assessment]
+
+## 🚨 Production Risks (Fix Within 48 Hours)
+[Only issues that could cause downtime, data loss, or security breaches]
+
+## 🎯 Strategic Improvements (High ROI)
+[Only changes that unlock capabilities or improve metrics >25%]
+
+## ⚡ Quick Wins (Optional)
+[Only if <2 hours effort for significant improvement]
+
+## Detailed Analysis
+
+### Security Assessment
+[Detailed security findings from Security_Auditor]
+
+### Performance Analysis
+[Detailed performance findings from Performance_Analyzer]
+
+### Architecture Review
+[Detailed architecture findings from Architecture_Validator]
+
+### Code Quality Evaluation
+[Detailed quality findings from Quality_Inspector]
+
+[Additional sections based on sub-agents used]
+
+## Action Plan
+1. Critical fixes preventing production failures
+2. High-ROI improvements unlocking capabilities
+
+## Impact Matrix
+| Issue | User Impact | Effort | ROI |
+|-------|-------------|--------|-----|
+| [Only high-impact issues with quantified metrics] |
+```
+
+### Step 7: Interactive Follow-up
+
+After presenting the review, offer interactive follow-ups. For example:
+- "Would you like me to fix any of the critical issues?"
+- "Should I create a detailed refactoring plan for any component?"
+- "Do you want me to generate tests for uncovered code?"
+- "Should I create GitHub issues for tracking these improvements?"
+
+## Implementation Notes
+
+1. **Use parallel Task execution** for all sub-agents to minimize review time
+2. **Include file:line_number references** for easy navigation
+3. **Balance criticism with recognition** of good practices
+4. **Provide actionable fixes**, not just problem identification
+5. **Consider project phase** and priorities when recommending changes
+6. **Use MCP servers** for specialized analysis when beneficial
+7. **Keep security findings sensitive** - don't expose vulnerabilities publicly
+
+## Error Handling
+
+### Coverage Verification
+
+Before presenting results, verify complete coverage:
+
+```
+☑ Critical Path Analysis: [Covered by agents X, Y]
+☑ Security Surface: [Covered by agents Y, Z]
+☑ Performance Impact: [Covered by agents X, Z]
+☑ Integration Points: [Covered by agents W, X]
+```
+
+If any area lacks coverage, deploy additional focused agents.
+
+## Error Handling
+
+If issues occur during review:
+- **Ambiguous input**: Use search tools to find relevant files before asking for clarification
+- **File not found**: Search for similar names or components across the codebase
+- **Large scope detected**: Dynamically scale agents based on calculated complexity
+- **No files found**: Provide helpful suggestions based on project structure
+- **Coverage gaps**: Deploy supplementary agents for missed areas