mirror of
https://github.com/wshobson/agents.git
synced 2026-03-18 09:37:15 +00:00
feat: add Conductor plugin for Context-Driven Development
Add comprehensive Conductor plugin implementing Context-Driven Development methodology with tracks, specs, and phased implementation plans. Components: - 5 commands: setup, new-track, implement, status, revert - 1 agent: conductor-validator - 3 skills: context-driven-development, track-management, workflow-patterns - 18 templates for project artifacts Documentation updates: - README.md: Updated counts (68 plugins, 100 agents, 110 skills, 76 tools) - docs/plugins.md: Added Conductor to Workflows section - docs/agents.md: Added conductor-validator agent - docs/agent-skills.md: Added Conductor skills section Also includes Prettier formatting across all project files.
This commit is contained in:
Seth Hobson
@@ -7,7 +7,8 @@ Generate comprehensive C4 architecture documentation for an existing repository/
|
||||
## 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
|
||||
|
||||
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)
|
||||
@@ -19,27 +20,27 @@ All documentation is written to a new `C4-Documentation/` directory in the repos
|
||||
## 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
|
||||
@@ -50,17 +51,15 @@ For each directory, starting from the deepest:
|
||||
- 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
|
||||
@@ -70,12 +69,13 @@ For each directory, starting from the deepest:
|
||||
- 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.
|
||||
**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
|
||||
|
||||
- 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)
|
||||
@@ -83,83 +83,77 @@ For each directory, starting from the deepest:
|
||||
- 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
|
||||
- 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
|
||||
- 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:
|
||||
|
||||
|
||||
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
|
||||
- Context: All c4-component-\*.md files
|
||||
|
||||
## Phase 3: Container-Level Synthesis
|
||||
|
||||
### 3.1 Analyze Components and Deployment Definitions
|
||||
- Review all c4-component-*.md files
|
||||
|
||||
- Review all c4-component-\*.md files
|
||||
- Search for deployment/infrastructure definitions:
|
||||
- Dockerfiles
|
||||
- Kubernetes manifests (deployments, services, etc.)
|
||||
@@ -169,34 +163,31 @@ For each identified component:
|
||||
- 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
|
||||
@@ -204,7 +195,6 @@ For each identified component:
|
||||
- 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
|
||||
@@ -213,22 +203,19 @@ For each identified component:
|
||||
- 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
|
||||
@@ -237,6 +224,7 @@ For each identified component:
|
||||
## Phase 4: Context-Level Documentation
|
||||
|
||||
### 4.1 Analyze System Documentation
|
||||
|
||||
- Review container and component documentation
|
||||
- Search for system documentation:
|
||||
- README files
|
||||
@@ -248,21 +236,20 @@ For each identified component:
|
||||
- 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
|
||||
@@ -270,25 +257,22 @@ For each identified component:
|
||||
- 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
|
||||
@@ -296,7 +280,6 @@ For each identified component:
|
||||
- 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)
|
||||
@@ -304,13 +287,12 @@ For each identified component:
|
||||
- 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
|
||||
@@ -330,7 +312,7 @@ For each identified component:
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- ✅ Every subdirectory has a corresponding c4-code-*.md file
|
||||
- ✅ 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
|
||||
@@ -375,11 +357,11 @@ C4-Documentation/
|
||||
```
|
||||
|
||||
This will:
|
||||
|
||||
1. Walk through all subdirectories bottom-up
|
||||
2. Create c4-code-*.md for each directory
|
||||
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/
|
||||
|
||||
|
||||
Reference in New Issue
Block a user