Documentation Generator MCP Server

{ "_AI_INSTRUCTIONS": { "purpose": "Generate implementation plans following this structure", "core_principles": { "no_time_factors": "Plans are agentic - focus on complexity and completeness, not deadlines", "no_business_considerations": "Pure technical focus - what needs to be built and how", "complete_autonomous_execution": "AI must implement without asking clarifying questions - zero ambiguity", "architecture_compliance": "Follow existing project patterns and standards" }, "workflow": "Read context.json + analysis data → Fill all 10 sections → Validate completeness" }, "REQUIRED_SECTIONS": { "0_preparation": { "purpose": "Gather project documentation and coding standards BEFORE writing sections 1-9", "required_fields": { "foundation_docs": { "available": ["List discovered docs: API.md, ARCHITECTURE.md, etc."], "missing": ["List missing docs"] }, "coding_standards": { "available": ["List discovered standards: BEHAVIOR-STANDARDS.md, etc."], "missing": ["List missing standards"] }, "reference_components": { "primary": "Most similar component to reference", "secondary": ["Other relevant components"] }, "key_patterns_identified": ["Pattern 1", "Pattern 2"], "technology_stack": { "languages": ["Python", "TypeScript", "etc."], "frameworks": ["React", "FastAPI", "etc."], "key_libraries": ["library@version"] }, "gaps_and_risks": ["Gap/risk 1", "Gap/risk 2"] }, "example": { "foundation_docs": {"available": ["API.md", "ARCHITECTURE.md"], "missing": ["User guide"]}, "coding_standards": {"available": ["BEHAVIOR-STANDARDS.md"], "missing": []}, "reference_components": {"primary": "handle_audit_codebase - Similar handler pattern", "secondary": ["StandardsGenerator"]}, "key_patterns_identified": ["All handlers: log → validate → work → return → catch errors", "All types named [Feature]ResultDict"], "technology_stack": {"languages": ["Python 3.11+"], "frameworks": ["MCP SDK"], "key_libraries": ["mcp@1.0.0"]}, "gaps_and_risks": ["No testing standards doc (will infer from existing tests)"] } }, "1_executive_summary": { "required_fields": { "purpose": "What problem does this solve? Template: Enable [users/system] to [capability] by [approach]", "value_proposition": "Why important? List 2-3 concrete benefits", "real_world_analogy": "Explain to non-technical person using everyday analogy", "use_case": "When/how used? Format: [Trigger] → [Steps] → [Outcome]", "output": "Tangible artifacts: files, endpoints, tables, UI screens" }, "example": { "purpose": "Enable AI assistants to create implementation plans autonomously by providing guided workflow and optimized template", "value_proposition": "Reduces planning time by 60%, ensures consistency across plans, eliminates workflow gap between analysis and validation", "real_world_analogy": "Like a GPS giving turn-by-turn directions - provides structure and guidance without controlling how you drive", "use_case": "User requests feature → AI runs /gather-context → /analyze-for-planning → /create-plan → plan.json created → ready for /validate-plan", "output": "plan.json file, planning-template-for-ai.json, /create-plan slash command, PlanningGenerator class" }, "bad_example": {"purpose": "Improve system", "value_proposition": "Makes things better"} }, "2_risk_assessment": { "required_fields": { "overall_risk": "low | medium | high", "complexity": "low | medium | high | very_high (with file count estimate)", "scope": "[Small/Medium/Large] - [X] files, [Y] components affected", "file_system_risk": "low | medium | high (if reads/writes files)", "dependencies": ["Library@version or 'None'"], "performance_concerns": ["Concern 1", "None"], "security_considerations": ["Security item 1", "None"], "breaking_changes": "none | minor | major | migration_needed" }, "guidelines": { "low_complexity": "< 5 files, < 200 lines, follows existing patterns exactly", "medium_complexity": "5-15 files, 200-1000 lines, adapts existing patterns", "high_complexity": "15-50 files, 1000-3000 lines, new patterns, multiple subsystems", "very_high_complexity": "> 50 files, > 3000 lines, major architectural changes" }, "example": { "overall_risk": "medium", "complexity": "high (10-12 files affected, ~800 lines new code, introduces new generator pattern)", "scope": "Medium - 10 files, affects generators/ and tool system", "file_system_risk": "medium (reads context.json, analysis, writes plan.json)", "dependencies": ["No new external dependencies"], "performance_concerns": ["Template parsing may be slow for large templates", "Plan generation should complete <5s"], "security_considerations": ["Must validate feature_name to prevent path traversal", "Must handle malformed JSON in context/analysis files"], "breaking_changes": "none" } }, "3_current_state_analysis": { "required_fields": { "affected_files": [ "NEW: path/to/file.ext - Purpose", "MODIFIED: path/to/file.ext - What changes", "MODIFIED: path/to/file.ext:42-58 - Specific section" ], "dependencies": { "existing_internal": ["Module - How used"], "existing_external": ["library@version - How used"], "new_external": ["library@version - Why needed"], "new_internal": ["Module - Purpose"] }, "architecture_context": "Layer (presentation/logic/data), patterns to follow, integration points" }, "example": { "affected_files": [ "NEW: generators/planning_generator.py - Generates implementation plans from template + context", "NEW: context/planning-template-for-ai.json - AI-optimized planning template (~450 lines)", "NEW: .claude/commands/create-plan.md - Slash command for plan creation", "MODIFIED: server.py - Add create_plan tool definition", "MODIFIED: tool_handlers.py - Add handle_create_plan handler", "MODIFIED: constants.py - Add PLANNING_TEMPLATE_AI path constant", "MODIFIED: type_defs.py - Add PlanResultDict TypedDict", "MODIFIED: validation.py - Add validate_feature_name_input()" ], "dependencies": { "existing_internal": [ "generators/base_generator.py - Inherit BaseGenerator pattern", "error_responses.py - Use ErrorResponse factory", "validation.py - Use existing validation patterns", "logger_config.py - Use structured logging" ], "existing_external": ["No new external dependencies"], "new_external": [], "new_internal": ["generators/planning_generator.py - New PlanningGenerator class"] }, "architecture_context": "Operates at business logic layer. Follows existing generator pattern (BaseGenerator → ChangelogGenerator, StandardsGenerator). Must use handler registry pattern. All errors via ErrorResponse factory. Input validation at MCP boundaries." } }, "4_key_features": { "required_fields": { "primary_features": ["3-5 core user-facing capabilities"], "secondary_features": ["2-3 supporting capabilities"], "edge_case_handling": ["2-3 special scenarios"], "configuration_options": ["1-2 configurable aspects or 'None'"] }, "guidelines": { "write_from_user_perspective": "What users experience, not how implemented", "be_concrete": "Specific testable features, not vague goals", "typical_count": "6-10 features total" }, "example": { "primary_features": [ "Load context.json and analysis data to gather planning inputs", "Generate complete 10-section implementation plan in batch mode", "Save plans to coderef/working/<feature-name>/plan.json" ], "secondary_features": [ "Detect missing prerequisites (context/analysis) and prompt user", "Print terminal summary showing sections completed and next steps" ], "edge_case_handling": [ "Save partial plan with TODOs if generation fails mid-way", "Auto-retry once for transient errors before saving partial", "Handle malformed or missing context.json/analysis gracefully" ], "configuration_options": ["None"] }, "bad_example": ["Better planning", "Improved workflow"] }, "5_task_id_system": { "prefixes": { "SETUP": "Initial setup, dependencies, configuration (typical: 3-6 tasks)", "DB": "Database schema, migrations, queries (typical: 2-5 tasks)", "API": "HTTP endpoints, request/response (typical: 3-8 tasks)", "LOGIC": "Business logic, algorithms, validation (typical: 4-10 tasks)", "UI": "User interface components, forms, styling (typical: 5-15 tasks)", "TEST": "Unit, integration, E2E tests (typical: 5-10 tasks)", "SEC": "Security, input validation, access control (typical: 2-5 tasks)", "DOC": "Documentation, API specs, guides (typical: 3-5 tasks)", "DEPLOY": "Deployment scripts, CI/CD, env config (typical: 2-4 tasks)", "REFACTOR": "Code cleanup, restructuring (varies)" }, "format": "PREFIX-NNN (e.g., SETUP-001, API-002)", "task_description_rules": { "start_with_imperative_verb": "Create, Add, Implement, Update, Fix, Write", "be_specific": "Include file name or component", "be_testable": "Clear completion criteria", "minimum_length": "20 words for quality" }, "example_good": "LOGIC-003: Implement generate_plan() method in PlanningGenerator that loads template, context, and analysis, then synthesizes all 10 sections into plan.json using batch mode approach", "example_bad": "LOGIC-003: Do planning stuff" }, "6_implementation_phases": { "standard_structure": { "phase_1_foundation": { "purpose": "Setup before writing logic", "typical_tasks": ["SETUP tasks", "DB tasks", "Scaffolding"], "completion_criteria": "All files exist, dependencies installed, code compiles", "complexity": "low", "effort_percentage": "15-25%" }, "phase_2_core_implementation": { "purpose": "Implement primary features and business logic", "typical_tasks": ["LOGIC tasks", "API tasks", "UI tasks"], "completion_criteria": "Happy path works end-to-end", "complexity": "high", "effort_percentage": "40-50%" }, "phase_3_edge_cases_security": { "purpose": "Handle errors, validation, security", "typical_tasks": ["Error handling", "SEC tasks", "Performance optimizations"], "completion_criteria": "All edge cases handled, security requirements met", "complexity": "medium", "effort_percentage": "20-25%" }, "phase_4_testing": { "purpose": "Comprehensive testing at all levels", "typical_tasks": ["TEST tasks", "Manual testing"], "completion_criteria": "All tests pass, coverage meets requirements", "complexity": "medium", "effort_percentage": "15-20%" }, "phase_5_documentation_deployment": { "purpose": "Finalize docs and prepare for release", "typical_tasks": ["DOC tasks", "DEPLOY tasks"], "completion_criteria": "All documentation complete, ready to deploy", "complexity": "low", "effort_percentage": "5-10%" } }, "required_fields_per_phase": { "title": "Descriptive phase name", "purpose": "Why this phase exists", "complexity": "low | medium | high | very_high", "effort_level": "1-5 scale (1=trivial, 5=major)", "tasks": ["TASK-ID: Description"], "completion_criteria": "How to know phase is done" }, "guidelines": { "phase_count": "4-6 phases typical; >8 suggests feature should be split", "sequential_execution": "No circular dependencies", "all_tasks_assigned": "Every task ID appears in exactly one phase" } }, "7_testing_strategy": { "required_fields": { "unit_tests": { "scope": "Individual functions/methods in isolation", "coverage_target": "80-90% for business logic", "tests": ["test_function_name() - What it verifies"] }, "integration_tests": { "scope": "Multiple components working together", "focus": "Database transactions, API contracts, inter-service communication", "tests": ["test_workflow_name() - What workflow it verifies"] }, "end_to_end_tests": { "scope": "Complete user workflows through UI (if applicable)", "when_needed": "For features with UI or complex user workflows", "tests": ["User journey description"] }, "edge_case_scenarios": { "minimum_count": "5-10 scenarios", "categories": [ "Empty/Null Input", "Invalid Input", "Boundary Conditions", "Concurrent Access", "Resource Exhaustion", "External Dependency Failure", "Security", "State" ], "format": { "scenario": "Description", "setup": "How to create scenario", "expected_behavior": "What should happen", "verification": "How to verify", "error_handling": "Expected error type or 'No error'" } } }, "example": { "unit_tests": [ "test_load_template() - Verify template loads and parses correctly", "test_extract_ai_template() - Verify META/USAGE sections removed", "test_validate_feature_name() - Verify path traversal prevention" ], "integration_tests": [ "test_create_plan_full_workflow() - Load context + analysis → generate plan → verify 10 sections created", "test_create_plan_missing_context() - Generate plan without context.json → verify warning but continues", "test_save_partial_on_failure() - Simulate section failure → verify partial plan saved with TODOs" ], "end_to_end_tests": ["Not applicable - no UI"], "edge_case_scenarios": [ { "scenario": "context.json missing", "setup": "Call create_plan without running gather-context first", "expected_behavior": "Prints warning, continues with plan generation using only analysis data", "verification": "Check terminal output for warning message", "error_handling": "No error (warning only)" }, { "scenario": "Invalid feature name with path traversal", "setup": "Call create_plan with feature_name='../../etc/passwd'", "expected_behavior": "Rejects with validation error", "verification": "Check error message contains 'invalid feature name'", "error_handling": "ValueError" }, { "scenario": "Malformed analysis JSON", "setup": "Corrupt analysis file with invalid JSON", "expected_behavior": "Returns error, does not crash", "verification": "Check error response contains 'malformed JSON'", "error_handling": "JSONDecodeError" }, { "scenario": "Section generation fails mid-way", "setup": "Simulate error during section 5 generation", "expected_behavior": "Saves partial plan (sections 0-4 complete, 5 marked TODO, 6-9 null)", "verification": "Load plan.json, verify sections 0-4 populated, section 5 has status='INCOMPLETE'", "error_handling": "Partial save, no exception raised" }, { "scenario": "Empty template file", "setup": "Replace template with empty file", "expected_behavior": "Returns error 'template is empty or malformed'", "verification": "Check error message", "error_handling": "ValueError" } ] } }, "8_success_criteria": { "categories": { "functional_requirements": { "format": { "requirement": "Name", "metric": "What to measure", "target": "Measurable target", "validation": "How to validate" }, "must_be_measurable": "Numbers, percentages, time units - not 'fast' or 'good'" }, "quality_requirements": { "universal_criteria": [ "Code style compliance (linter passes)", "Test coverage (>80% for new code)", "Type safety (type checker passes)", "Documentation completeness (all public APIs documented)" ] }, "performance_requirements": { "when_needed": "For features processing significant data or handling concurrent users", "examples": ["API response time <200ms P95", "Database query <50ms", "Memory usage <500MB"] }, "security_requirements": { "when_needed": "For features handling sensitive data, authentication, or user input", "examples": ["Password hashing with bcrypt cost>=10", "Parameterized queries (no SQL injection)", "Input validation prevents XSS"] } }, "example": { "functional_requirements": [ { "requirement": "Plan generation", "metric": "Complete 10-section plan created", "target": "All sections 0-9 present with required fields populated", "validation": "Run integration test, verify plan.json contains all sections" }, { "requirement": "Partial plan on failure", "metric": "Failed sections marked with TODO", "target": "Incomplete sections have status='INCOMPLETE' and error message", "validation": "Simulate failure, verify partial plan structure" } ], "quality_requirements": [ { "requirement": "Code style", "metric": "Linter passes", "target": "pylint returns exit code 0", "validation": "Run: pylint generators/planning_generator.py" }, { "requirement": "Test coverage", "metric": "Line coverage percentage", "target": ">80% coverage for planning_generator.py", "validation": "Run: pytest --cov=generators.planning_generator" } ], "performance_requirements": [ { "requirement": "Plan generation speed", "metric": "Time to generate plan", "target": "<5 seconds for typical feature plan", "validation": "Time test_create_plan_full_workflow() execution" } ], "security_requirements": [ { "requirement": "Feature name validation", "metric": "Path traversal prevention", "target": "Feature names with '../' or absolute paths rejected", "validation": "Unit test with malicious inputs, verify ValueError raised" } ] } }, "9_implementation_checklist": { "structure": { "pre_implementation": [ "☐ Review complete plan for gaps or ambiguities", "☐ Get stakeholder approval (if required)", "☐ Set up development environment" ], "phase_sections": "One section per phase, containing all task IDs with checkboxes", "finalization": [ "☐ All tests passing", "☐ Code review completed and approved", "☐ Documentation updated", "☐ Changelog entry created", "☐ Deploy to staging (if applicable)", "☐ Smoke tests on staging" ] }, "checkbox_format": { "unchecked": "☐ TASK-ID: Description", "completed": "☑ TASK-ID: Description" }, "requirements": [ "Every task ID from section 6 must appear in checklist", "Tasks listed in logical execution order", "Checklist is flat (no nested checkboxes)" ] } }, "QUALITY_CHECKLIST": { "completeness": [ "☐ All 10 sections (0-9) present with required fields", "☐ No placeholder text like '[TBD]', '[TODO]', '[figure out later]'", "☐ All task IDs follow PREFIX-NNN format", "☐ All tasks have imperative verb + specific description ≥20 words", "☐ Success criteria are measurable (numbers, not subjective)", "☐ Edge cases cover: empty input, invalid input, boundaries, errors", "☐ Every task ID appears exactly once in implementation checklist" ], "quality": [ "☐ Task descriptions ≥20 words (specific enough to implement)", "☐ 5-10 edge case scenarios documented", "☐ Complexity and effort assessments realistic", "☐ Dependencies clearly specified", "☐ Security considerations if handling sensitive data", "☐ Performance targets if processing significant data" ], "autonomy": [ "☐ Zero ambiguity - every decision made upfront", "☐ AI could implement without asking clarifying questions", "☐ Edge cases have defined expected behavior", "☐ Success criteria clear enough to know when 'done'" ] }, "COMMON_MISTAKES": [ { "mistake": "Vague task descriptions", "bad": "SETUP-001: Set up authentication", "good": "SETUP-001: Install pyjwt==2.8.0 and bcrypt==4.0.1 in requirements.txt for JWT token generation and password hashing" }, { "mistake": "Missing edge cases", "bad": "Only testing happy path", "good": "Testing: happy path + 7 edge cases (empty input, invalid tokens, concurrent access, etc.)" }, { "mistake": "Subjective success criteria", "bad": "System is fast and secure", "good": "Login endpoint <200ms P95, passwords hashed with bcrypt cost>=10" }, { "mistake": "Forgetting dependencies", "bad": "Using library without listing it", "good": "NEW EXTERNAL: pyjwt==2.8.0 (add to requirements.txt)" }, { "mistake": "No error handling plan", "bad": "Implement feature (no mention of errors)", "good": "Edge case: invalid JWT → return 401 with {error: 'Invalid token'} → log to stderr" }, { "mistake": "Circular phase dependencies", "bad": "Phase 1 depends on Phase 3 which depends on Phase 1", "good": "Phase 1 (DB) → Phase 2 (API) → Phase 3 (UI) → Phase 4 (Tests)" }, { "mistake": "Underestimating complexity", "bad": "Authentication system: low complexity, effort 1", "good": "Authentication system: high complexity (security, API, DB layers), effort 4" } ] }