codehava-agent-kit 1.0.1 → 3.0.0

package/templates/.agent/skills/c4-architecture-c4-architecture/SKILL.md

@@ -0,0 +1,392 @@
+---
+name: c4-architecture-c4-architecture
+description: "Generate comprehensive C4 architecture documentation for an existing repository/codebase using a bottom-up analysis approach."
+risk: unknown
+source: community
+date_added: "2026-02-27"
+---
+
+# C4 Architecture Documentation Workflow
+
+Generate comprehensive C4 architecture documentation for an existing repository/codebase using a bottom-up analysis approach.
+
+[Extended thinking: This workflow implements a complete C4 architecture documentation process following the C4 model (Context, Container, Component, Code). It uses a bottom-up approach, starting from the deepest code directories and working upward, ensuring every code element is documented before synthesizing into higher-level abstractions. The workflow coordinates four specialized C4 agents (Code, Component, Container, Context) to create a complete architectural documentation set that serves both technical and non-technical stakeholders.]
+
+## Use this skill when
+
+- Working on c4 architecture documentation workflow tasks or workflows
+- Needing guidance, best practices, or checklists for c4 architecture documentation workflow
+
+## Do not use this skill when
+
+- The task is unrelated to c4 architecture documentation workflow
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## Overview
+
+This workflow creates comprehensive C4 architecture documentation following the [official C4 model](https://c4model.com/diagrams) by:
+
+1. **Code Level**: Analyzing every subdirectory bottom-up to create code-level documentation
+2. **Component Level**: Synthesizing code documentation into logical components within containers
+3. **Container Level**: Mapping components to deployment containers with API documentation (shows high-level technology choices)
+4. **Context Level**: Creating high-level system context with personas and user journeys (focuses on people and software systems, not technologies)
+
+**Note**: According to the [C4 model](https://c4model.com/diagrams), you don't need to use all 4 levels of diagram - the system context and container diagrams are sufficient for most software development teams. This workflow generates all levels for completeness, but teams can choose which levels to use.
+
+All documentation is written to a new `C4-Documentation/` directory in the repository root.
+
+## Phase 1: Code-Level Documentation (Bottom-Up Analysis)
+
+### 1.1 Discover All Subdirectories
+
+- Use codebase search to identify all subdirectories in the repository
+- Sort directories by depth (deepest first) for bottom-up processing
+- Filter out common non-code directories (node_modules, .git, build, dist, etc.)
+- Create list of directories to process
+
+### 1.2 Process Each Directory (Bottom-Up)
+
+For each directory, starting from the deepest:
+
+- Use Task tool with subagent_type="c4-architecture::c4-code"
+- Prompt: |
+  Analyze the code in directory: [directory_path]
+
+  Create comprehensive C4 Code-level documentation following this structure:
+  1. **Overview Section**:
+     - Name: [Descriptive name for this code directory]
+     - Description: [Short description of what this code does]
+     - Location: [Link to actual directory path relative to repo root]
+     - Language: [Primary programming language(s) used]
+     - Purpose: [What this code accomplishes]
+  2. **Code Elements Section**:
+     - Document all functions/methods with complete signatures:
+       - Function name, parameters (with types), return type
+       - Description of what each function does
+       - Location (file path and line numbers)
+       - Dependencies (what this function depends on)
+     - Document all classes/modules:
+       - Class name, description, location
+       - Methods and their signatures
+       - Dependencies
+  3. **Dependencies Section**:
+     - Internal dependencies (other code in this repo)
+     - External dependencies (libraries, frameworks, services)
+  4. **Relationships Section**:
+     - Optional Mermaid diagram if relationships are complex
+
+  Save the output as: C4-Documentation/c4-code-[directory-name].md
+  Use a sanitized directory name (replace / with -, remove special chars) for the filename.
+
+  Ensure the documentation includes:
+  - Complete function signatures with all parameters and types
+  - Links to actual source code locations
+  - All dependencies (internal and external)
+  - Clear, descriptive names and descriptions
+
+- Expected output: c4-code-<directory-name>.md file in C4-Documentation/
+- Context: All files in the directory and its subdirectories
+
+**Repeat for every subdirectory** until all directories have corresponding c4-code-\*.md files.
+
+## Phase 2: Component-Level Synthesis
+
+### 2.1 Analyze All Code-Level Documentation
+
+- Collect all c4-code-\*.md files created in Phase 1
+- Analyze code structure, dependencies, and relationships
+- Identify logical component boundaries based on:
+  - Domain boundaries (related business functionality)
+  - Technical boundaries (shared frameworks, libraries)
+  - Organizational boundaries (team ownership, if evident)
+
+### 2.2 Create Component Documentation
+
+For each identified component:
+
+- Use Task tool with subagent_type="c4-architecture::c4-component"
+- Prompt: |
+  Synthesize the following C4 Code-level documentation files into a logical component:
+
+  Code files to analyze:
+  [List of c4-code-*.md file paths]
+
+  Create comprehensive C4 Component-level documentation following this structure:
+  1. **Overview Section**:
+     - Name: [Component name - descriptive and meaningful]
+     - Description: [Short description of component purpose]
+     - Type: [Application, Service, Library, etc.]
+     - Technology: [Primary technologies used]
+  2. **Purpose Section**:
+     - Detailed description of what this component does
+     - What problems it solves
+     - Its role in the system
+  3. **Software Features Section**:
+     - List all software features provided by this component
+     - Each feature with a brief description
+  4. **Code Elements Section**:
+     - List all c4-code-\*.md files contained in this component
+     - Link to each file with a brief description
+  5. **Interfaces Section**:
+     - Document all component interfaces:
+       - Interface name
+       - Protocol (REST, GraphQL, gRPC, Events, etc.)
+       - Description
+       - Operations (function signatures, endpoints, etc.)
+  6. **Dependencies Section**:
+     - Components used (other components this depends on)
+     - External systems (databases, APIs, services)
+  7. **Component Diagram**:
+     - Mermaid diagram showing this component and its relationships
+
+  Save the output as: C4-Documentation/c4-component-[component-name].md
+  Use a sanitized component name for the filename.
+
+- Expected output: c4-component-<name>.md file for each component
+- Context: All relevant c4-code-\*.md files for this component
+
+### 2.3 Create Master Component Index
+
+- Use Task tool with subagent_type="c4-architecture::c4-component"
+- Prompt: |
+  Create a master component index that lists all components in the system.
+
+  Based on all c4-component-\*.md files created, generate:
+  1. **System Components Section**:
+     - List all components with:
+       - Component name
+       - Short description
+       - Link to component documentation
+  2. **Component Relationships Diagram**:
+     - Mermaid diagram showing all components and their relationships
+     - Show dependencies between components
+     - Show external system dependencies
+
+  Save the output as: C4-Documentation/c4-component.md
+
+- Expected output: Master c4-component.md file
+- Context: All c4-component-\*.md files
+
+## Phase 3: Container-Level Synthesis
+
+### 3.1 Analyze Components and Deployment Definitions
+
+- Review all c4-component-\*.md files
+- Search for deployment/infrastructure definitions:
+  - Dockerfiles
+  - Kubernetes manifests (deployments, services, etc.)
+  - Docker Compose files
+  - Terraform/CloudFormation configs
+  - Cloud service definitions (AWS Lambda, Azure Functions, etc.)
+  - CI/CD pipeline definitions
+
+### 3.2 Map Components to Containers
+
+- Use Task tool with subagent_type="c4-architecture::c4-container"
+- Prompt: |
+  Synthesize components into containers based on deployment definitions.
+
+  Component documentation:
+  [List of all c4-component-*.md file paths]
+
+  Deployment definitions found:
+  [List of deployment config files: Dockerfiles, K8s manifests, etc.]
+
+  Create comprehensive C4 Container-level documentation following this structure:
+  1. **Containers Section** (for each container):
+     - Name: [Container name]
+     - Description: [Short description of container purpose and deployment]
+     - Type: [Web Application, API, Database, Message Queue, etc.]
+     - Technology: [Primary technologies: Node.js, Python, PostgreSQL, etc.]
+     - Deployment: [Docker, Kubernetes, Cloud Service, etc.]
+  2. **Purpose Section** (for each container):
+     - Detailed description of what this container does
+     - How it's deployed
+     - Its role in the system
+  3. **Components Section** (for each container):
+     - List all components deployed in this container
+     - Link to component documentation
+  4. **Interfaces Section** (for each container):
+     - Document all container APIs and interfaces:
+       - API/Interface name
+       - Protocol (REST, GraphQL, gRPC, Events, etc.)
+       - Description
+       - Link to OpenAPI/Swagger/API Spec file
+       - List of endpoints/operations
+  5. **API Specifications**:
+     - For each container API, create an OpenAPI 3.1+ specification
+     - Save as: C4-Documentation/apis/[container-name]-api.yaml
+     - Include:
+       - All endpoints with methods (GET, POST, etc.)
+       - Request/response schemas
+       - Authentication requirements
+       - Error responses
+  6. **Dependencies Section** (for each container):
+     - Containers used (other containers this depends on)
+     - External systems (databases, third-party APIs, etc.)
+     - Communication protocols
+  7. **Infrastructure Section** (for each container):
+     - Link to deployment config (Dockerfile, K8s manifest, etc.)
+     - Scaling strategy
+     - Resource requirements (CPU, memory, storage)
+  8. **Container Diagram**:
+     - Mermaid diagram showing all containers and their relationships
+     - Show communication protocols
+     - Show external system dependencies
+
+  Save the output as: C4-Documentation/c4-container.md
+
+- Expected output: c4-container.md with all containers and API specifications
+- Context: All component documentation and deployment definitions
+
+## Phase 4: Context-Level Documentation
+
+### 4.1 Analyze System Documentation
+
+- Review container and component documentation
+- Search for system documentation:
+  - README files
+  - Architecture documentation
+  - Requirements documents
+  - Design documents
+  - Test files (to understand system behavior)
+  - API documentation
+  - User documentation
+
+### 4.2 Create Context Documentation
+
+- Use Task tool with subagent_type="c4-architecture::c4-context"
+- Prompt: |
+  Create comprehensive C4 Context-level documentation for the system.
+
+  Container documentation: C4-Documentation/c4-container.md
+  Component documentation: C4-Documentation/c4-component.md
+  System documentation: [List of README, architecture docs, requirements, etc.]
+  Test files: [List of test files that show system behavior]
+
+  Create comprehensive C4 Context-level documentation following this structure:
+  1. **System Overview Section**:
+     - Short Description: [One-sentence description of what the system does]
+     - Long Description: [Detailed description of system purpose, capabilities, problems solved]
+  2. **Personas Section**:
+     - For each persona (human users and programmatic "users"):
+       - Persona name
+       - Type (Human User / Programmatic User / External System)
+       - Description (who they are, what they need)
+       - Goals (what they want to achieve)
+       - Key features used
+  3. **System Features Section**:
+     - For each high-level feature:
+       - Feature name
+       - Description (what this feature does)
+       - Users (which personas use this feature)
+       - Link to user journey map
+  4. **User Journeys Section**:
+     - For each key feature and persona:
+       - Journey name: [Feature Name] - [Persona Name] Journey
+       - Step-by-step journey:
+         1. [Step 1]: [Description]
+         2. [Step 2]: [Description]
+            ...
+       - Include all system touchpoints
+     - For programmatic users (external systems, APIs):
+       - Integration journey with step-by-step process
+  5. **External Systems and Dependencies Section**:
+     - For each external system:
+       - System name
+       - Type (Database, API, Service, Message Queue, etc.)
+       - Description (what it provides)
+       - Integration type (API, Events, File Transfer, etc.)
+       - Purpose (why the system depends on this)
+  6. **System Context Diagram**:
+     - Mermaid C4Context diagram showing:
+       - The system (as a box in the center)
+       - All personas (users) around it
+       - All external systems around it
+       - Relationships and data flows
+       - Use C4Context notation for proper C4 diagram
+  7. **Related Documentation Section**:
+     - Links to container documentation
+     - Links to component documentation
+
+  Save the output as: C4-Documentation/c4-context.md
+
+  Ensure the documentation is:
+  - Understandable by non-technical stakeholders
+  - Focuses on system purpose, users, and external relationships
+  - Includes comprehensive user journey maps
+  - Identifies all external systems and dependencies
+
+- Expected output: c4-context.md with complete system context
+- Context: All container, component, and system documentation
+
+## Configuration Options
+
+- `target_directory`: Root directory to analyze (default: current repository root)
+- `exclude_patterns`: Patterns to exclude (default: node_modules, .git, build, dist, etc.)
+- `output_directory`: Where to write C4 documentation (default: C4-Documentation/)
+- `include_tests`: Whether to analyze test files for context (default: true)
+- `api_format`: Format for API specs (default: openapi)
+
+## Success Criteria
+
+- ✅ Every subdirectory has a corresponding c4-code-\*.md file
+- ✅ All code-level documentation includes complete function signatures
+- ✅ Components are logically grouped with clear boundaries
+- ✅ All components have interface documentation
+- ✅ Master component index created with relationship diagram
+- ✅ Containers map to actual deployment units
+- ✅ All container APIs documented with OpenAPI/Swagger specs
+- ✅ Container diagram shows deployment architecture
+- ✅ System context includes all personas (human and programmatic)
+- ✅ User journeys documented for all key features
+- ✅ All external systems and dependencies identified
+- ✅ Context diagram shows system, users, and external systems
+- ✅ Documentation is organized in C4-Documentation/ directory
+
+## Output Structure
+
+```
+C4-Documentation/
+├── c4-code-*.md              # Code-level docs (one per directory)
+├── c4-component-*.md          # Component-level docs (one per component)
+├── c4-component.md            # Master component index
+├── c4-container.md            # Container-level docs
+├── c4-context.md              # Context-level docs
+└── apis/                      # API specifications
+    ├── [container]-api.yaml   # OpenAPI specs for each container
+    └── ...
+```
+
+## Coordination Notes
+
+- **Bottom-up processing**: Process directories from deepest to shallowest
+- **Incremental synthesis**: Each level builds on the previous level's documentation
+- **Complete coverage**: Every directory must have code-level documentation before synthesis
+- **Link consistency**: All documentation files link to each other appropriately
+- **API documentation**: Container APIs must have OpenAPI/Swagger specifications
+- **Stakeholder-friendly**: Context documentation should be understandable by non-technical stakeholders
+- **Mermaid diagrams**: Use proper C4 Mermaid notation for all diagrams
+
+## Example Usage
+
+```bash
+/c4-architecture:c4-architecture
+```
+
+This will:
+
+1. Walk through all subdirectories bottom-up
+2. Create c4-code-\*.md for each directory
+3. Synthesize into components
+4. Map to containers with API docs
+5. Create system context with personas and journeys
+
+All documentation written to: C4-Documentation/

package/templates/.agent/skills/canvas-design/LICENSE.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.