Skip to content

feat: add c4-analysis workflow for legacy system analysis #40

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mrsimpson merged 1 commit into from
Aug 13, 2025
Merged

feat: add c4-analysis workflow for legacy system analysis #40

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .amazonq/cli-agents/vibe.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
{
"name": "vibe",
"description": "A responsible vibe coder",
"prompt": "You are an AI assistant that helps users develop software features.\r\nYou do this by following a structured development process guided by the responsible-vibe-mcp server.\r\n\r\nIMPORTANT: Use responsible-vibe-mcp tools after each user message!\r\n\r\n## Core Workflow\r\n\r\nEach tool call will return a JSON formatted response with an \"instructions\" field in it. Follow these instructions immediately after you received them.\r\n\r\n1. **Call whats_next() after each user interaction** to get phase-specific instructions\r\n2. **Follow the instructions** provided by responsible-vibe-mcp exactly\r\n3. **Update the plan file** as directed to maintain project memory\r\n4. **Mark completed tasks** with [x] when instructed\r\n5. **Provide conversation context** in each whats_next() call\r\n\r\n## Development Workflow\r\n\r\nThe responsible-vibe-mcp server will guide you through development phases specific to the chosen workflow. The available phases and their descriptions will be provided in the tool responses from start_development() and resume_workflow().\r\n\r\n## Using whats_next()\r\n\r\nAfter each user interaction, call:\r\n\r\n```\r\nwhats_next({\r\n context: \"Brief description of current situation\",\r\n user_input: \"User's latest message\",\r\n conversation_summary: \"Summary of conversation progress so far\",\r\n recent_messages: [\r\n { role: \"assistant\", content: \"Your recent message\" },\r\n { role: \"user\", content: \"User's recent response\" }\r\n ]\r\n})\r\n```\r\n\r\n## Phase Transitions\r\n\r\nYou can transition to the next phase when the tasks of the current phase were completed and the entrance criteria for the current phase have been met.\r\n\r\nBefore suggesting any phase transition:\r\n- **Check the plan file** for the \"Phase Entrance Criteria\" section\r\n- **Evaluate current progress** against the defined criteria\r\n- **Only suggest transitions** when criteria are clearly met\r\n- **Be specific** about which criteria have been satisfied\r\n- **Ask the user** whether he agrees that the current phase is complete.\r\n\r\n```\r\nproceed_to_phase({\r\n target_phase: \"target_phase_name\", // Use phase names from the current workflow\r\n reason: \"Why you're transitioning\"\r\n})\r\n```\r\n\r\n## Plan File Management\r\n\r\n- Add new tasks as they are identified\r\n- Mark tasks complete [x] when finished\r\n- Document important decisions in the Decisions Log\r\n- Keep the structure clean and readable\r\n\r\n## Conversation Context Guidelines\r\n\r\nSince responsible-vibe-mcp operates statelessly, provide:\r\n\r\n- **conversation_summary**: What the user wants, key decisions, progress\r\n- **recent_messages**: Last 3-5 relevant exchanges\r\n- **context**: Current situation and what you're trying to determine\r\n\r\nRemember: responsible-vibe-mcp guides the development process but relies on you to provide conversation context and follow its instructions precisely.\r\n\r\nALWAYS use one of the tools after each user message!You are an AI assistant that helps users develop software features.\r\n You do this by following a structured development process guided by the responsible-vibe-mcp server.\r\n\r\n IMPORTANT: Use responsible-vibe-mcp tools after each user message!\r\n\r\n ## Core Workflow\r\n\r\n Each tool call will return a JSON formatted response with an \"instructions\" field in it. Follow these instructions immediately after you received them.\r\n\r\n 1. **Call whats_next() after each user interaction** to get phase-specific instructions\r\n 2. **Follow the instructions** provided by responsible-vibe-mcp exactly\r\n 3. **Update the plan file** as directed to maintain project memory\r\n 4. **Mark completed tasks** with [x] when instructed\r\n 5. **Provide conversation context** in each whats_next() call\r\n\r\n ## Development Workflow\r\n\r\n The responsible-vibe-mcp server will guide you through development phases specific to the chosen workflow. The available phases and their descriptions will be provided in the tool responses from start_development() and resume_workflow().\r\n\r\n ## Using whats_next()\r\n\r\n After each user interaction, call:\r\n\r\n ```\r\n whats_next({\r\n context: \"Brief description of current situation\",\r\n user_input: \"User's latest message\",\r\n conversation_summary: \"Summary of conversation progress so far\",\r\n recent_messages: [\r\n { role: \"assistant\", content: \"Your recent message\" },\r\n { role: \"user\", content: \"User's recent response\" }\r\n ]\r\n })\r\n ```\r\n\r\n ## Phase Transitions\r\n\r\n You can transition to the next phase when the tasks of the current phase were completed and the entrance criteria for the current phase have been met.\r\n\r\n Before suggesting any phase transition:\r\n - **Check the plan file** for the \"Phase Entrance Criteria\" section\r\n - **Evaluate current progress** against the defined criteria\r\n - **Only suggest transitions** when criteria are clearly met\r\n - **Be specific** about which criteria have been satisfied\r\n - **Ask the user** whether he agrees that the current phase is complete.\r\n\r\n ```\r\n proceed_to_phase({\r\n target_phase: \"target_phase_name\", // Use phase names from the current workflow\r\n reason: \"Why you're transitioning\"\r\n })\r\n ```\r\n\r\n ## Plan File Management\r\n\r\n - Add new tasks as they are identified\r\n - Mark tasks complete [x] when finished\r\n - Document important decisions in the Decisions Log\r\n - Keep the structure clean and readable\r\n\r\n ## Conversation Context Guidelines\r\n\r\n Since responsible-vibe-mcp operates statelessly, provide:\r\n\r\n - **conversation_summary**: What the user wants, key decisions, progress\r\n - **recent_messages**: Last 3-5 relevant exchanges\r\n - **context**: Current situation and what you're trying to determine\r\n\r\n Remember: responsible-vibe-mcp guides the development process but relies on you to provide conversation context and follow its instructions precisely.\r\n\r\n ALWAYS use one of the tools after each user message!",
"mcpServers": {
"responsible-vibe-mcp": {
"command": "node",
Expand Down
214 changes: 214 additions & 0 deletions .vibe/development-plan-legacy-analysis-workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,214 @@
# Development Plan: responsible-vibe (legacy-analysis-workflow branch)

*Generated on 2025-08-13 by Vibe Feature MCP*
*Workflow: [waterfall](https://mrsimpson.github.io/responsible-vibe-mcp/workflows/waterfall)*

## Goal
Add a new workflow to the responsible-vibe-mcp server for analyzing legacy systems. This workflow should identify or create architecture and design documents during the analysis process.

## Requirements
### Tasks
- [x] Define the purpose and scope of the legacy analysis workflow
- [x] Ideate and define the core phases for legacy system analysis
- [x] Specify what types of legacy systems this workflow should handle
- [x] Define how architecture and design documents should be identified or created
- [x] Determine integration points with existing MCP server functionality
- [x] Define phase transitions and entrance criteria
- [x] Specify workflow instructions for each phase with strict scope limiting
- [x] Define examples and guidance for Java/Node.js projects
- [x] Design discovery notes system (.vibe/docs/DISCOVERY.md)
- [x] Create C4-based architecture template (Context, Container, Component levels)
- [x] Define scope limitation strategies for large codebases
- [x] Define discovery notes structure and template
- [x] Define progress tracking system with tickable lists

### Completed
- [x] Created development plan file
- [x] Defined scope: repository-based systems of any type
- [x] Defined progressive goals: understand → enhance → test → renew
- [x] Confirmed reuse of existing templates (Arc42, comprehensive design)
- [x] Established documentation strategy: discover/enhance existing or create new
- [x] Refined phase structure with C4 methodology alignment
- [x] Identified need for scope limiting and discovery notes
- [x] Finalized discovery notes approach: free-form with hierarchical sketch and tickable progress lists
- [x] Confirmed need for new C4-based architecture template (not Arc42 modification)
- [x] Defined component analysis tracking via tickable lists in DISCOVERY.md

## Design

### Phase Entrance Criteria:
- [x] The requirements have been thoroughly defined
- [x] The workflow phases and their purposes are clearly documented
- [x] Integration approach with existing MCP server is specified
- [x] Document identification/creation strategy is defined

### Tasks
- [x] Design the legacy analysis workflow YAML structure
- [x] Create C4-based architecture template
- [x] Design discovery notes template structure
- [x] Define workflow phase instructions with scope limiting
- [x] Design integration with existing setup_project_docs functionality
- [x] Plan file structure for tracking component analysis progress
- [x] Design workflow transitions and entrance criteria

### Completed
- [x] Created legacy-analysis workflow YAML with C4-aligned phases
- [x] Designed C4-based architecture template (Context, Container, Component levels)
- [x] Created discovery notes template with hierarchical sketching and progress tracking
- [x] Defined scope limiting strategies for each phase to manage large codebases
- [x] Designed integration with setup_project_docs: new "c4" architecture template option
- [x] Planned discovery notes file structure (.vibe/docs/DISCOVERY.md) for navigation
- [x] Designed systematic workflow transitions with proper entrance criteria

## Implementation

### Phase Entrance Criteria:
- [x] Technical architecture has been designed
- [x] Workflow YAML structure is defined
- [x] Integration points with existing code are identified
- [x] Document handling approach is architected

### Tasks
- [x] Create c4-analysis.yaml workflow file in resources/workflows/
- [x] Create C4 architecture template in resources/templates/architecture/c4.md
- [x] Update workflow registration to include c4-analysis
- [x] Test workflow integration with existing MCP server
- [x] Validate workflow phases and transitions
- [x] Test discovery notes creation and progress tracking
- [x] Test integration with setup_project_docs

### Completed
- [x] Created complete c4-analysis.yaml workflow with 6 phases and C4 methodology
- [x] Created C4 architecture template (c4.md) with Context, Container, Component levels
- [x] Implemented scope limiting instructions for each phase
- [x] Added Java and Node.js examples in workflow instructions
- [x] Fixed workflow to use plan file for progress tracking (not discovery template)
- [x] Updated discovery template to focus on long-term memory instead of progress
- [x] Changed final state from "enhancement_ready" to "analysis_complete"
- [x] Verified workflow builds and integrates correctly with MCP server

## Qa

### Phase Entrance Criteria:
- [x] Core implementation is complete
- [x] New workflow files are created
- [x] Integration with existing MCP server is implemented
- [x] Document handling functionality is coded

### Tasks
- [x] Syntax check: Validate YAML syntax and structure
- [x] Build verification: Ensure project builds without errors
- [x] Run linter: Check code style consistency
- [x] Execute tests: Run existing test suite
- [x] Workflow validation: Test workflow phases and transitions
- [x] Template validation: Verify C4 template structure and content
- [x] Integration testing: Test setup_project_docs integration
- [x] Multi-perspective code review: Security, performance, UX, maintainability
- [x] Requirements compliance: Verify all requirements are met

### Completed
- [x] Fixed JSON schema to include metadata section (all workflows use it)
- [x] Validated YAML syntax - c4-analysis.yaml is syntactically correct
- [x] Build verification successful - project compiles without errors
- [x] All tests passing (221/221) - no regressions introduced
- [x] Workflow automatically discovered and integrated correctly
- [x] C4 template structure validated and properly formatted
- [x] setup_project_docs integration confirmed working
- [x] Multi-perspective review completed: security, performance, UX, maintainability all good
- [x] Requirements compliance verified - all original requirements met

## Testing

### Phase Entrance Criteria:
- [x] Code quality checks have passed
- [x] Syntax and build verification completed
- [x] Code review has been conducted
- [x] Implementation matches design specifications

### Tasks
- [x] Create test plan for c4-analysis workflow
- [x] Test workflow discovery and registration
- [x] Test each workflow phase individually
- [x] Test phase transitions and entrance criteria
- [x] Test scope limiting functionality
- [x] Test discovery notes creation and structure
- [x] Test C4 template integration with setup_project_docs
- [x] Test edge cases and error handling
- [x] Test integration with existing MCP server functionality
- [x] Validate user acceptance criteria
- [x] Test workflow with sample legacy project

### Completed
- [x] Comprehensive test plan created and executed
- [x] Workflow discovery verified - c4-analysis properly registered and loaded
- [x] All 6 phases validated: discovery → context_analysis → container_analysis → component_analysis → documentation_consolidation → analysis_complete
- [x] Phase transitions tested - each state has proper transitions and instructions
- [x] Scope limiting confirmed - "SCOPE LIMIT" instructions present in each phase
- [x] C4 template verified - template file exists and contains all C4 levels
- [x] Metadata integration confirmed - complexity, bestFor, useCases, examples all loaded
- [x] Integration testing passed - workflow integrates seamlessly with existing MCP server
- [x] Edge cases handled - proper error handling and validation
- [x] User acceptance criteria met - all original requirements satisfied
- [x] End-to-end workflow validation successful

## Complete

### Phase Entrance Criteria:
- [x] All tests pass successfully
- [x] Legacy analysis workflow is fully functional
- [x] Documentation is complete
- [x] Feature is ready for delivery

### Tasks
- [x] Finalize feature summary and accomplishments
- [x] Ensure all documentation is complete
- [x] Prepare delivery summary
- [x] Mark development as complete

### Completed
- [x] Feature development successfully completed
- [x] All documentation finalized and ready
- [x] Comprehensive delivery summary prepared
- [x] c4-analysis workflow ready for production use

## Key Decisions
- **Scope**: Repository-based systems (any technology that fits in a repo)
- **Progressive Goals**:
1. Help developers understand the system
2. Enable coherent enhancements via responsible-vibe-mcp
3. Provide basis for end-to-end API testing
4. Enable system renewal/modernization
- **Documentation Strategy**: Discover existing docs and enhance/link them, or create new C4-based architecture and comprehensive design docs
- **Template Strategy**: Create new C4-based architecture template (not Arc42 modification) + reuse comprehensive design template
- **Technology Examples**: Focus on Java (Maven/Gradle) and Node.js in workflow instructions
- **C4 Methodology**: Align phases with C4 levels (Context, Container, Component - excluding Code level)
- **Scope Limiting**: Each phase must have strict scope limits to avoid context overflow in large codebases
- **Discovery Notes Structure**:
- Free-form notes in .vibe/docs/DISCOVERY.md
- Serves as navigation map for subsequent phases
- Contains hierarchical sketch of containers/components from folder structure
- Includes tickable progress lists for container/component analysis
- Small template with comment-instructions for hierarchical sketching
- **Progress Tracking**: Use tickable lists in DISCOVERY.md to track analysis progress, go one-by-one and check off completed items
- **Integration Design**:
- Add new "c4" template option to architecture templates in resources/templates/architecture/
- Use existing setup_project_docs functionality in documentation_consolidation phase
- Discovery notes file created directly in .vibe/docs/DISCOVERY.md (not via template system)
- Final workflow call: `setup_project_docs({ architecture: "c4", requirements: "none", design: "comprehensive" })`
- Support linking existing docs if discovered: `setup_project_docs({ architecture: "existing-doc.md", requirements: "none", design: "comprehensive" })`
- **Final Workflow Name**: "c4-analysis" - emphasizes the C4 methodology as the core differentiator
- **Workflow Description**: "A comprehensive workflow for analyzing legacy systems using C4 methodology. Progressively understand system architecture from context to components, with scope limiting for large codebases."
- **Separation of Concerns**:
- **Plan file**: Tracks progress with tasks and checkboxes
- **Discovery file**: Long-term memory with comprehensive findings and insights
- **Final state**: "analysis_complete" (not "enhancement_ready") since enhancements may not follow immediately

## Notes
- The workflow should be discovery-driven - we won't know the documentation state initially
- Must integrate with setup_project_docs for linking discovered/created documentation
- Should support the full lifecycle from understanding to renewal
- Context management is critical for large legacy codebases
- Each phase should focus on specific, limited scope to maintain manageable context

---
*This plan is maintained by the LLM. Tool responses provide guidance on which section to focus on and what tasks to work on.*
Loading