Documentation Generator MCP Server

{ "META_DOCUMENTATION": { "title": "Feature Implementation Planning Standard - Universal Meta-Template", "purpose": "Universal planning framework for ANY feature implementation or refactoring project in ANY codebase", "version": "1.1.0", "created": "2025-10-10", "last_updated": "2025-10-10", "audience": "AI assistants and developers planning features, refactors, or architectural changes", "applicability": "Any programming language, any framework, any project size, any domain", "what_is_this": { "description": "A meta-template that defines a standardized planning methodology for software implementation", "not_code": "This is NOT code - it's documentation about HOW to create implementation plans", "universal": "Applies to web apps, mobile apps, backend services, libraries, CLI tools, APIs, databases, infrastructure - anything", "structure": "Explains what each section means, why it exists, and how to fill it out properly", "v1_1_0_enhancement": "Added section 0 (Preparation) - guides AI to leverage existing foundation docs and coding standards BEFORE writing plan, reducing implementation time by 60-70% through copy-paste patterns", "context_gathering": "Optional: Use /gather-context to create <feature-name>-context.json BEFORE planning to clarify requirements and scope" }, "core_principles": { "principle_1": { "name": "No Time Factors - All Agentic", "description": "Plans must be executable by AI autonomously without human intervention during implementation", "rationale": "AI doesn't work on deadlines; it works on completeness and complexity understanding", "implications": [ "Every decision must be made upfront in the plan", "No 'TBD' or 'we'll figure this out later'", "Complexity and effort levels guide planning, not time estimates", "AI executes at its own pace without time pressure", "Quality over speed - no shortcuts due to complexity constraints" ], "example": "Instead of 'We'll decide on the database schema during implementation', plan says 'User table: id (UUID), email (string, unique), created_at (timestamp)'" }, "principle_2": { "name": "No Business Considerations", "description": "Plans focus purely on technical implementation, not business value or market concerns", "rationale": "Separates technical planning from product/business decisions", "implications": [ "No cost-benefit analysis", "No market research or user surveys", "No prioritization based on business impact or ROI", "Pure technical focus: what needs to be built and how", "Assume business requirements are already defined and approved" ], "example": "Don't include 'This feature will increase revenue by 20%' - instead focus on 'Implements OAuth2 authentication flow with refresh tokens'" }, "principle_3": { "name": "Complete Autonomous Execution", "description": "AI must be able to implement the plan start-to-finish without asking clarifying questions", "rationale": "Eliminates back-and-forth; AI has everything it needs upfront", "implications": [ "Complete specifications - zero ambiguity", "All edge cases identified and resolution defined", "Clear success criteria - AI knows when it's done", "Built-in review gates - AI knows when to pause for approval", "All dependencies explicitly stated", "All architectural decisions documented with rationale" ], "example": "Instead of 'Handle errors appropriately', specify 'Catch PermissionError, log to stderr with error level, return HTTP 403 with JSON body {error: message}'" }, "principle_4": { "name": "Architecture Compliance", "description": "All implementations must follow existing project patterns and standards", "rationale": "Maintains consistency and prevents architectural drift", "implications": [ "Document existing patterns that must be followed", "Reference architectural decision records (ADRs)", "Specify coding standards and style guides", "Identify design patterns in use (factory, singleton, repository, etc.)", "List required testing patterns (unit, integration, E2E)", "Define error handling conventions" ], "example": "For a React project: 'Use functional components with hooks (not class components), PropTypes for type checking, React Query for data fetching, CSS Modules for styling'" } } }, "UNIVERSAL_PLANNING_STRUCTURE": { "0_preparation": { "purpose": "Gather project documentation and coding standards BEFORE writing implementation plan sections 1-9", "why_critical": "Leveraging existing patterns, standards, and documentation accelerates planning, ensures consistency, and reduces implementation time by 60-70%", "when_to_do_this": "FIRST step after reading META_DOCUMENTATION, before writing executive summary", "output": "Reference inventory to use throughout plan writing", "overview": { "what_youre_looking_for": [ "Foundation docs - Project-level documentation (architecture, APIs, components, schemas)", "Coding standards - Language/framework-specific patterns and conventions", "Similar components - Existing implementations to reference or extend", "Test patterns - How tests are structured and organized" ], "where_to_look": { "common_locations": [ "docs/, documentation/, coderef/, .docs/", "coderef/foundation-docs/", "coderef/standards/", "README.md, ARCHITECTURE.md, API.md, COMPONENTS.md", "CONTRIBUTING.md, STYLE_GUIDE.md" ], "note": "Location varies by project - use find/grep to locate if not in standard places" }, "effort_investment": "Moderate preparation effort - significantly reduces implementation complexity and effort" }, "step_1_inventory_foundation_docs": { "purpose": "Identify what project-level documentation exists", "what_to_find": { "API_documentation": { "common_names": ["API.md", "api-reference.md", "endpoints.md"], "contains": ["API endpoint definitions", "Request/response schemas", "Error codes", "Authentication requirements"], "use_in_planning": ["Section 3 (Current State) - Understanding existing API contracts", "Section 4 (Key Features) - Ensuring new APIs match existing patterns", "Task breakdown - Knowing exact parameter types"] }, "ARCHITECTURE_documentation": { "common_names": ["ARCHITECTURE.md", "architecture.md", "system-design.md"], "contains": ["System topology", "Module dependencies", "Design patterns in use", "Data flow"], "use_in_planning": ["Section 2 (Risk Assessment) - Understanding system complexity", "Section 3 (Current State) - Identifying which modules are affected", "Task breakdown - Knowing which modules to import/extend"] }, "COMPONENTS_documentation": { "common_names": ["COMPONENTS.md", "components.md", "class-diagram.md"], "contains": ["Component inventory", "Component interfaces", "Component relationships", "Usage examples"], "use_in_planning": ["Section 3 (Current State) - Finding similar components to reference", "Task breakdown - Identifying which components to extend vs create new", "Code templates - Copying structure from similar components"] }, "SCHEMA_documentation": { "common_names": ["SCHEMA.md", "schema.md", "data-models.md", "types.md"], "contains": ["Data models and type definitions", "Database schemas", "Validation rules", "Type definition patterns"], "use_in_planning": ["Section 3 (Current State) - Understanding existing data models", "Task breakdown - Creating new types following existing patterns", "Section 7 (Testing) - Understanding validation requirements"] } }, "how_to_inventory": { "step_1": "Run: ls -la docs/ coderef/ documentation/ (find doc directories)", "step_2": "Run: find . -name '*.md' | grep -iE '(api|architecture|component|schema)'", "step_3": "Open each document and scan table of contents", "step_4": "Create reference map in your planning notes", "complexity": "Simple - straightforward file discovery and cataloging" }, "documentation_not_found": { "what_to_do": "Document this gap in section 2 (Risk Assessment) as 'Missing documentation' risk", "fallback_strategy": ["Review existing code directly", "Look for inline documentation", "Check version control history", "Consider creating minimal documentation as part of this feature"] } }, "step_2_inventory_coding_standards": { "purpose": "Identify project-specific coding patterns and conventions", "what_to_find": { "BEHAVIOR_STANDARDS": { "common_names": ["BEHAVIOR-STANDARDS.md", "coding-conventions.md"], "contains": ["Error handling patterns", "Logging conventions", "State management patterns", "Validation approaches"], "use_in_planning": ["Task breakdown - Error handling structure", "Section 7 (Testing) - Edge case scenarios", "Section 8 (Success Criteria) - Code follows standards"] }, "COMPONENT_PATTERN": { "common_names": ["COMPONENT-PATTERN.md", "handler-template.md"], "contains": ["Standard component/class/handler structure template", "Required methods", "Naming conventions", "Documentation requirements"], "use_in_planning": ["Task breakdown - COPY template structure, fill in placeholders", "Section 8 (Success Criteria) - Structure compliance", "Implementation time reduction - 60-70% is copy-paste"] }, "SCHEMA_STANDARDS": { "common_names": ["SCHEMA-STANDARDS.md", "type-conventions.md"], "contains": ["Type definition conventions", "Naming patterns", "Required fields", "Validation function patterns"], "use_in_planning": ["Task breakdown - Creating new types", "Section 3 (Current State) - Type definitions needed", "Section 8 (Success Criteria) - Type safety validation"] } }, "how_to_inventory": { "step_1": "Run: ls -la coderef/standards/", "step_2": "Run: find . -name '*STANDARDS*.md' -o -name '*-pattern*.md'", "step_3": "Check project root for: STYLE_GUIDE.md, CONTRIBUTING.md", "step_4": "Review each document and note key patterns", "complexity": "Simple - document discovery and pattern identification" }, "standards_not_found": { "what_to_do": "Create minimal standards as FIRST phase of implementation", "approach": ["Analyze existing code to identify patterns", "Document patterns you observe", "Include 'SETUP-001: Document coding patterns' as first task"], "note": "If standards don't exist, you're creating them - this increases Phase 1 complexity and effort significantly" } }, "step_3_find_reference_components": { "purpose": "Identify existing components similar to what you're building", "why_important": "Copy proven patterns instead of inventing new ones; reduces bugs and implementation time", "what_to_look_for": { "similar_functionality": { "question": "What existing component does something similar?", "examples": ["Building authentication? → Look for authorization or session management", "Building new API endpoint? → Look for existing endpoints in same domain", "Building UI component? → Look for similar components"] }, "same_layer": { "question": "What components operate at the same architectural layer?", "layers": {"presentation": "UI components, API routes", "business_logic": "Services, use cases", "data_access": "Repositories, database queries"} } }, "how_to_find": { "method_1_use_components_doc": "Open COMPONENTS.md and search for keywords related to your feature", "method_2_grep_codebase": "Use grep to find relevant code (grep -r 'class.*Repository' src/)", "method_3_analyze_file_structure": "Browse directory structure to understand organization", "complexity": "Medium - requires understanding codebase structure and identifying patterns" }, "what_to_extract": { "structure_template": { "copy": ["Class/function signature", "Method names and order", "Import statements", "Error handling structure"], "dont_copy": "Business logic - that's feature-specific" } } }, "step_4_create_preparation_summary": { "purpose": "Consolidate all references into a single summary for quick lookup during planning", "format": { "preparation_summary": { "foundation_docs": {"available": ["API.md", "ARCHITECTURE.md"], "missing": ["User guide"]}, "coding_standards": {"available": ["BEHAVIOR-STANDARDS.md", "COMPONENT-PATTERN.md"], "missing": ["TESTING-STANDARDS.md"]}, "reference_components": {"primary": "handle_audit_codebase - Similar handler pattern", "secondary": ["StandardsGenerator"]}, "key_patterns_identified": ["All handlers follow: log → validate → work → return → catch 5 errors", "All result types named [Feature]ResultDict"], "gaps_and_risks": ["No testing standards doc (will infer from existing tests)"] } }, "where_to_include": "Add this summary to section 3 (Current State Analysis) → Architecture Context", "complexity": "Simple - consolidation and summarization task" }, "using_references_throughout_planning": { "section_1_executive_summary": {"reference": "README.md", "use_for": "Understanding project's purpose and value proposition style"}, "section_2_risk_assessment": {"reference": "ARCHITECTURE.md, COMPONENTS.md", "use_for": "Identifying dependencies and complexity"}, "section_3_current_state_analysis": {"reference": "ALL foundation docs and standards", "use_for": "Complete picture of what exists and what patterns to follow"}, "section_4_key_features": {"reference": "API.md, similar components", "use_for": "Understanding existing feature capabilities"}, "section_5_task_breakdown": {"reference": "COMPONENT-PATTERN.md, BEHAVIOR-STANDARDS.md", "use_for": "Writing specific tasks with exact structure to copy"}, "section_6_implementation_phases": {"reference": "ARCHITECTURE.md (dependencies)", "use_for": "Ordering phases based on dependency graph"}, "section_7_testing_strategy": {"reference": "TESTING-STANDARDS.md, existing tests", "use_for": "Test structure and organization"}, "section_8_success_criteria": {"reference": "API.md (contracts), BEHAVIOR-STANDARDS.md", "use_for": "Defining measurable validation criteria"}, "section_9_implementation_checklist": {"reference": "All previous sections", "use_for": "Ensuring all tasks reference appropriate templates/standards"} }, "quality_checklist": [ "☐ Inventoried all foundation docs (or documented they don't exist)", "☐ Inventoried all coding standards (or documented need to create them)", "☐ Found 1-3 similar components to reference (or documented none exist)", "☐ Created preparation summary with key patterns identified", "☐ Documented gaps (missing docs/standards) in risk assessment", "☐ Complexity and effort assessments account for any documentation gaps" ], "effort_breakdown": { "step_1_inventory_foundation_docs": {"effort_level": 1, "complexity": "simple"}, "step_2_inventory_coding_standards": {"effort_level": 2, "complexity": "simple"}, "step_3_find_reference_components": {"effort_level": 2, "complexity": "medium"}, "step_4_create_preparation_summary": {"effort_level": 1, "complexity": "simple"}, "overall_effort": "Low to moderate - high value preparation phase", "payback": "Significantly reduces implementation complexity and effort through pattern reuse" } }, "1_executive_summary": { "purpose": "High-level overview for stakeholders who won't read the full plan", "when_to_write": "First section to write - forces clarity on what you're building", "target_length": "5-7 sentences total across all fields", "fields": { "purpose": { "question_to_answer": "What problem does this solve? What gap does it fill?", "bad_example": "This feature improves the system", "good_example": "Add user authentication to allow personalized experiences and protect sensitive data", "guideline": "Focus on the problem being solved, not the solution details", "template": "Enable [users/system] to [capability] by [high-level approach]" }, "value_proposition": { "question_to_answer": "Why is this important? What value does it provide?", "bad_example": "Makes things better", "good_example": "Prevents unauthorized access to user data, enables personalization, meets compliance requirements", "guideline": "List 2-3 concrete benefits; avoid vague marketing language", "template": "[Benefit 1], [Benefit 2], [Benefit 3]" }, "real_world_analogy": { "question_to_answer": "How would you explain this to a non-technical person?", "bad_example": "It's like a database with authentication", "good_example": "Like a bouncer checking IDs at a club entrance - verifies who you are before letting you in", "guideline": "Use everyday analogies that anyone can understand; avoid technical jargon", "template": "Like [common real-world thing] that [action] to [outcome]" }, "use_case": { "question_to_answer": "When/how would someone use this?", "bad_example": "When needed", "good_example": "User signs up → receives verification email → clicks link → account activated → can log in", "guideline": "Describe primary user journey or trigger condition", "template": "[Trigger] → [Step 1] → [Step 2] → [Outcome]" }, "output": { "question_to_answer": "What tangible artifacts does this create?", "bad_example": "New code", "good_example": "3 new API endpoints (/register, /login, /refresh), JWT tokens, users table in database", "guideline": "List concrete deliverables - files, endpoints, database tables, UI screens", "template": "[Artifact 1], [Artifact 2], [Artifact 3]" } }, "quality_checklist": [ "☐ Can a non-developer understand what's being built?", "☐ Each field is 1-2 sentences max (concise)", "☐ No placeholder text like '[to be determined]'", "☐ Real-world analogy doesn't use technical terms", "☐ Output lists concrete deliverables (not vague goals)" ] }, "2_risk_assessment": { "purpose": "Identify potential problems before they occur", "when_to_write": "Early in planning - informs architecture decisions", "output": "Honest evaluation of risks with mitigation strategies", "risk_levels": { "overall_risk": { "low": "Well-understood problem, proven solutions, minimal dependencies, no security concerns", "medium": "Some complexity, moderate unknowns, standard security needs, manageable scope", "high": "Novel approach, many unknowns, critical security implications, large scope, external dependencies", "example_low": "Adding a new read-only API endpoint that returns cached data", "example_medium": "Implementing OAuth2 authentication using established libraries", "example_high": "Building a custom distributed consensus algorithm" }, "complexity": { "low": "< 5 files affected, < 200 lines of code, follows existing patterns exactly", "medium": "5-15 files, 200-1000 lines, uses existing patterns with minor adaptations", "high": "15-50 files, 1000-3000 lines, introduces new patterns, multiple subsystems", "very_high": "> 50 files, > 3000 lines, major architectural changes, system-wide impact", "guideline": "Count all files that will be created or modified; estimate net new lines (not just additions)" }, "scope": { "format": "[Small/Medium/Large] - [X] files, [Y] components/modules affected", "small": "1-3 files, single component or module", "medium": "4-15 files, 2-5 components or modules", "large": "> 15 files, 5+ components or modules or cross-cutting concerns", "example": "Medium - 8 files, affects authentication module and user profile module" } }, "risk_factors": { "file_system": { "assess": "Does this read/write files? Create directories? Handle uploads?", "low": "Read-only operations or no file I/O", "medium": "Writes to designated directories with error handling", "high": "User-provided paths, file uploads, permission-sensitive operations" }, "dependencies": { "assess": "What external libraries, services, or systems does this depend on?", "none": "Uses only standard library or existing dependencies", "low": "Well-established libraries with stable APIs (e.g., lodash, requests)", "medium": "Newer libraries or external services with SLAs (e.g., Stripe API)", "high": "Experimental libraries, third-party services without SLAs, multiple external dependencies" }, "performance": { "assess": "Will this process large amounts of data? Handle concurrent requests? Affect critical paths?", "concerns": [ "Database query performance (N+1 queries, missing indexes)", "Memory usage (loading large files into RAM)", "Network latency (external API calls)", "CPU-intensive operations (image processing, encryption)", "Concurrency issues (race conditions, deadlocks)" ], "mitigation_examples": [ "Add database indexes on frequently queried columns", "Stream large files instead of loading into memory", "Implement caching with TTL", "Use background jobs for heavy processing", "Add rate limiting to prevent abuse" ] }, "security": { "assess": "Does this handle sensitive data? Accept user input? Control access?", "threats": [ "Injection attacks (SQL, XSS, command injection)", "Authentication bypass", "Authorization flaws", "Data exposure", "CSRF/SSRF attacks" ], "mitigation_examples": [ "Input validation and sanitization", "Parameterized queries (prevent SQL injection)", "Content Security Policy headers", "Proper authentication tokens (JWT with expiration)", "Role-based access control", "Encryption at rest and in transit" ] }, "breaking_changes": { "assess": "Will this break existing functionality or APIs?", "none": "Purely additive - no changes to existing behavior", "minor": "Changes to internal APIs only, public APIs unchanged", "major": "Public API changes requiring consumer updates", "migration_needed": "Database schema changes, config changes, deployment procedure changes" } }, "quality_checklist": [ "☐ Honest assessment (don't downplay risks to look good)", "☐ Each high risk has a mitigation strategy", "☐ Dependencies are specific (library names and versions)", "☐ Security risks identified if handling user data", "☐ Breaking changes clearly documented" ] }, "3_current_state_analysis": { "purpose": "Document existing codebase state before making changes", "why_important": "Prevents surprises during implementation; ensures you understand what you're modifying", "affected_files": { "format": "List every file that will be created or modified", "include": [ "Source code files", "Test files", "Configuration files", "Database migration files", "Documentation files" ], "detail_level": { "new_files": "filename.ext - [Brief description of purpose]", "modified_files": "filename.ext - [What changes will be made]", "with_line_numbers": "filename.ext:42-58 - [Specific section being modified]" }, "example": [ "NEW: src/auth/jwt_handler.py - Handles JWT token creation and validation", "MODIFIED: src/api/routes.py - Add authentication middleware to existing routes", "MODIFIED: database/migrations/003_add_users_table.sql - Create users table schema", "MODIFIED: tests/test_auth.py - Add unit tests for authentication flow" ] }, "dependencies": { "categorize_as": { "existing_internal": "Code/modules already in the project that you'll use", "existing_external": "Third-party libraries already installed", "new_external": "New libraries to be added", "new_internal": "New modules/classes you'll create" }, "example": [ "EXISTING INTERNAL: src/database/connection.py - Database connection pool (will use for user queries)", "EXISTING EXTERNAL: bcrypt==4.0.1 - Password hashing (already installed)", "NEW EXTERNAL: pyjwt==2.8.0 - JWT token handling (must add to requirements.txt)", "NEW INTERNAL: src/auth/jwt_handler.py - JWT token utilities (to be created)" ], "why_important": "Ensures all imports will work; identifies version conflicts early" }, "architecture_context": { "questions_to_answer": [ "What layer of the architecture does this operate at? (presentation, business logic, data access)", "What existing patterns must this follow? (MVC, repository pattern, service layer, etc.)", "How does this integrate with existing systems?", "What design patterns are already in use that this must follow?", "What coding standards must be followed?" ], "example": "Operates at business logic and data access layers. Follows repository pattern for database access. Must use existing BaseRepository class. Authentication tokens are JWT format per existing API design. All async operations must use existing async/await patterns." }, "quality_checklist": [ "☐ Every file to be modified is listed", "☐ Line numbers provided for specific changes (when known)", "☐ All dependencies categorized (existing/new, internal/external)", "☐ New external dependencies include version numbers", "☐ Architecture context explains how this fits into existing system" ] }, "4_key_features": { "purpose": "List what this implementation does at feature level (not implementation details)", "format": "Flat list of feature descriptions from user perspective", "categorization": { "primary_features": { "definition": "Core functionality that defines this feature", "count": "3-5 primary features typical", "example": [ "User registration with email verification", "Login with username/password returning JWT token", "Token refresh to extend session without re-login" ] }, "secondary_features": { "definition": "Supporting capabilities that enhance primary features", "count": "2-3 secondary features typical", "example": [ "Password strength requirements enforced", "Rate limiting on login attempts to prevent brute force", "Logout endpoint to invalidate tokens" ] }, "edge_case_handling": { "definition": "How special scenarios are handled", "count": "2-3 edge cases typical", "example": [ "Graceful handling of expired tokens with clear error messages", "Account lockout after N failed login attempts", "Password reset flow for forgotten passwords" ] }, "configuration_options": { "definition": "User-configurable aspects of the feature", "count": "1-2 config options typical", "example": [ "Configurable token expiration time (default: 1 hour)", "Optional multi-factor authentication (2FA) support" ] } }, "writing_guidelines": { "user_perspective": "Describe what users experience, not how it's implemented", "bad_example": "Bcrypt password hashing with salt rounds=10", "good_example": "Passwords are securely hashed and cannot be recovered", "concrete": "Specific features, not vague goals", "bad_example": "Better security", "good_example": "Implements OAuth2 with refresh tokens for secure authentication" }, "quality_checklist": [ "☐ 6-10 features total (right level of granularity)", "☐ Each feature is user-facing (not implementation details)", "☐ Features are concrete and testable", "☐ Edge cases explicitly mentioned", "☐ No duplicate or overlapping features" ] }, "5_task_id_system": { "purpose": "Task IDs provide traceability, progress tracking, and clear references for implementation work", "format": "PREFIX-NNN (e.g., SETUP-001, API-002, TEST-003)", "universal_prefixes": { "SETUP": { "usage": "Initial setup, scaffolding, configuration, dependencies", "examples": [ "SETUP-001: Initialize project structure", "SETUP-002: Add dependencies to package.json / requirements.txt / pom.xml", "SETUP-003: Create configuration files", "SETUP-004: Set up development environment" ], "typical_count": "3-6 tasks" }, "DB": { "usage": "Database schema, migrations, seeds, queries", "examples": [ "DB-001: Create users table migration", "DB-002: Add indexes on email and username columns", "DB-003: Create seed data for testing", "DB-004: Write stored procedure for user lookup" ], "typical_count": "2-5 tasks for database-heavy features" }, "API": { "usage": "HTTP endpoints, request/response handling, API contracts", "examples": [ "API-001: Create POST /auth/register endpoint", "API-002: Create POST /auth/login endpoint", "API-003: Create POST /auth/refresh endpoint", "API-004: Add authentication middleware" ], "typical_count": "3-8 tasks depending on API surface area" }, "LOGIC": { "usage": "Business logic, algorithms, data processing, validation", "examples": [ "LOGIC-001: Implement password hashing with bcrypt", "LOGIC-002: Implement JWT token generation and validation", "LOGIC-003: Implement email verification token generation", "LOGIC-004: Implement rate limiting logic" ], "typical_count": "4-10 tasks for complex business logic" }, "UI": { "usage": "User interface components, screens, forms, styling", "examples": [ "UI-001: Create login form component", "UI-002: Create registration form component", "UI-003: Add form validation and error display", "UI-004: Style authentication pages to match design system" ], "typical_count": "5-15 tasks for frontend-heavy features" }, "TEST": { "usage": "Unit tests, integration tests, E2E tests, test data", "examples": [ "TEST-001: Unit tests for password hashing", "TEST-002: Unit tests for JWT token handling", "TEST-003: Integration tests for authentication flow", "TEST-004: E2E tests for registration and login", "TEST-005: Load tests for login endpoint" ], "typical_count": "5-10 tasks for comprehensive testing" }, "SEC": { "usage": "Security implementations, validations, access control", "examples": [ "SEC-001: Add input sanitization to prevent XSS", "SEC-002: Implement CSRF protection", "SEC-003: Add rate limiting to prevent brute force", "SEC-004: Set up secure cookie configuration" ], "typical_count": "2-5 tasks for security-critical features" }, "DOC": { "usage": "Documentation, API specs, user guides, inline comments", "examples": [ "DOC-001: Write API documentation for authentication endpoints", "DOC-002: Update README with authentication setup instructions", "DOC-003: Create user guide for password reset flow", "DOC-004: Add inline documentation to public APIs" ], "typical_count": "3-5 tasks" }, "DEPLOY": { "usage": "Deployment scripts, CI/CD, environment configuration", "examples": [ "DEPLOY-001: Add environment variables for JWT secret", "DEPLOY-002: Update deployment script to run migrations", "DEPLOY-003: Configure production database connection", "DEPLOY-004: Update CI/CD pipeline to run security tests" ], "typical_count": "2-4 tasks" }, "REFACTOR": { "usage": "For refactoring projects - code cleanup, restructuring", "examples": [ "REFACTOR-001: Extract authentication logic into separate service", "REFACTOR-002: Rename UserModel to User for consistency", "REFACTOR-003: Split large UserController into smaller controllers", "REFACTOR-004: Remove deprecated authentication methods" ], "typical_count": "Varies by refactor scope" } }, "numbering_conventions": { "sequential": "Number tasks sequentially: 001, 002, 003 (not 1, 2, 3)", "unique": "Each task ID must be unique within the plan", "execution_order": "Numbers roughly reflect execution order", "gaps_acceptable": "If tasks are removed, gaps in sequence are OK" }, "task_description_best_practices": { "imperative_verb": "Start with action verb (Create, Add, Implement, Update, Fix)", "specific": "Specific enough to know exactly what to do", "location": "Include file name or component", "testable": "Clear completion criteria", "example_good": "API-001: Create POST /auth/login endpoint in src/api/auth_routes.py returning JWT on success", "example_bad": "API-001: Do login stuff" }, "quality_checklist": [ "☐ Task IDs follow PREFIX-NNN format", "☐ Prefixes match the type of work (SETUP, API, TEST, etc.)", "☐ Each task has imperative verb (Create, Add, Implement)", "☐ Tasks are specific enough to implement without clarification", "☐ Tasks are appropriately scoped (single-focus, not overly broad)", "☐ All tasks are unique (no duplicate IDs)" ] }, "6_implementation_phases": { "purpose": "Break work into logical phases that can be executed sequentially", "why_phases": "Allows progress tracking, natural review points, dependency management", "standard_phase_structure": { "phase_1_foundation": { "purpose": "Set up infrastructure before writing logic", "typical_tasks": [ "Project setup and dependencies (SETUP tasks)", "Database schema and migrations (DB tasks)", "Configuration files and environment variables", "Scaffolding (empty classes/functions/components)" ], "completion_criteria": "All files exist, all dependencies installed, code compiles/builds (even if functionality is stubbed)", "complexity": "low", "effort_percentage": "15-25% of total implementation effort" }, "phase_2_core_implementation": { "purpose": "Implement primary features and business logic", "typical_tasks": [ "Core business logic (LOGIC tasks)", "API endpoints (API tasks)", "UI components (UI tasks)", "Integration between layers" ], "completion_criteria": "Happy path works end-to-end for primary features", "complexity": "high", "effort_percentage": "40-50% of total implementation effort" }, "phase_3_edge_cases_and_security": { "purpose": "Handle error cases, validation, security", "typical_tasks": [ "Error handling for all edge cases", "Input validation and sanitization (SEC tasks)", "Security implementations (rate limiting, CSRF protection)", "Performance optimizations" ], "completion_criteria": "All edge cases handled, security requirements met", "complexity": "medium", "effort_percentage": "20-25% of total implementation effort" }, "phase_4_testing": { "purpose": "Comprehensive testing at all levels", "typical_tasks": [ "Unit tests (TEST tasks)", "Integration tests", "E2E tests", "Manual testing", "Performance testing" ], "completion_criteria": "All tests pass, test coverage meets requirements", "complexity": "medium", "effort_percentage": "15-20% of total implementation effort" }, "phase_5_documentation_and_deployment": { "purpose": "Finalize documentation and prepare for release", "typical_tasks": [ "API documentation (DOC tasks)", "User guides", "Deployment configuration (DEPLOY tasks)", "Changelog entry" ], "completion_criteria": "All documentation complete, ready to deploy", "complexity": "low", "effort_percentage": "5-10% of total implementation effort" } }, "custom_phases": { "when_needed": "For features with unique workflows or complex dependencies", "examples": [ "phase_2_data_migration - For features requiring data transformation", "phase_3_backward_compatibility - For breaking changes requiring migration path", "phase_2_external_integration - For features heavily dependent on third-party APIs" ], "guideline": "4-6 phases typical; more than 8 suggests feature should be split" }, "phase_structure": { "required_fields": { "title": "Descriptive name of phase", "purpose": "Why this phase exists", "complexity": "Complexity rating (low | medium | high | very_high)", "effort_level": "Effort level (1-5 scale: 1=trivial, 5=major undertaking)", "tasks": "List of task IDs with descriptions", "completion_criteria": "How to know this phase is done" }, "optional_fields": { "dependencies": "What must be complete before starting this phase", "risks": "Phase-specific risks", "review_gate": "Whether approval is needed before next phase", "effort_percentage": "Optional percentage of total implementation effort (e.g., '20-25%')" } }, "quality_checklist": [ "☐ Phases can be executed sequentially (no circular dependencies)", "☐ Each phase has clear completion criteria", "☐ Phase complexity and effort levels are realistic and justified", "☐ All task IDs are assigned to a phase", "☐ No task appears in multiple phases", "☐ Dependencies between phases are explicit" ] }, "7_testing_strategy": { "purpose": "Define how to validate implementation correctness across all scenarios", "three_tier_approach": { "unit_tests": { "scope": "Individual functions/methods in isolation", "goal": "Verify each unit works correctly independently", "typical_count": "3-5 tests per public function/method", "tools": "Language-specific: pytest, Jest, JUnit, etc.", "example": [ "test_password_hashing() - Verify bcrypt produces different hashes for same input", "test_jwt_token_generation() - Verify token contains expected claims", "test_jwt_token_validation() - Verify expired tokens are rejected" ], "coverage_target": "80-90% code coverage for business logic" }, "integration_tests": { "scope": "Multiple components working together", "goal": "Verify components integrate correctly", "typical_count": "5-10 tests covering major workflows", "tools": "Language-specific: pytest with fixtures, Supertest, RestAssured, etc.", "example": [ "test_registration_flow() - POST /register → verify user in database → email sent", "test_login_flow() - POST /login → verify JWT returned → JWT contains user ID", "test_authenticated_request() - Login → use JWT → access protected endpoint" ], "focus": "Database transactions, API contracts, inter-service communication" }, "end_to_end_tests": { "scope": "Complete user workflows through UI (if applicable)", "goal": "Verify system works from user perspective", "typical_count": "3-5 critical user journeys", "tools": "Selenium, Cypress, Playwright, Puppeteer", "example": [ "User registration → email verification → login → access profile", "Forgotten password → reset email → set new password → login with new password" ], "when_needed": "For features with UI components or complex user workflows" } }, "edge_case_testing": { "purpose": "Ensure system handles unexpected or boundary conditions gracefully", "required": "5-10 edge case scenarios per feature", "scenario_structure": { "scenario": "Description of edge case", "setup": "How to create this scenario", "expected_behavior": "What should happen", "verification": "How to verify correct behavior", "error_handling": "Expected error type or 'No error'" }, "universal_edge_cases": [ { "category": "Empty/Null Input", "examples": [ "Empty string for required field", "Null value for optional field", "Array with zero elements", "File upload with 0 bytes" ] }, { "category": "Invalid Input", "examples": [ "Invalid email format", "Password too short", "Negative number where positive expected", "String where number expected" ] }, { "category": "Boundary Conditions", "examples": [ "Maximum allowed length + 1", "Exactly at maximum", "Integer overflow", "Date in past/future beyond allowed range" ] }, { "category": "Concurrent Access", "examples": [ "Two users editing same record simultaneously", "Race condition in token validation", "Deadlock scenario" ] }, { "category": "Resource Exhaustion", "examples": [ "Extremely large file upload", "Very long list (1M+ items)", "Deep recursion", "Database connection pool exhausted" ] }, { "category": "External Dependency Failure", "examples": [ "Database connection lost mid-operation", "Email service unavailable", "External API returns 500 error", "Network timeout" ] }, { "category": "Security", "examples": [ "SQL injection attempt", "XSS attack attempt", "Path traversal attempt", "Expired/tampered JWT token" ] }, { "category": "State", "examples": [ "Accessing resource that was deleted", "Re-using one-time token", "Account locked after failed logins", "Session expired" ] } ] }, "quality_checklist": [ "☐ Unit tests cover all public functions/methods", "☐ Integration tests cover major workflows", "☐ At least 5 edge case scenarios documented", "☐ Each edge case has expected behavior defined", "☐ Test coverage targets specified (e.g., 80% for unit tests)", "☐ Manual testing steps documented where automation isn't feasible" ] }, "8_success_criteria": { "purpose": "Define quantifiable metrics to validate implementation is complete and correct", "why_quantifiable": "AI needs objective pass/fail criteria, not subjective judgment", "four_categories": { "functional_requirements": { "definition": "Core functionality must work as specified", "format": { "requirement": "Name of functional requirement", "metric": "What to measure", "target": "Target value or condition (must be measurable)", "validation": "How to validate (test to run, command to execute, etc.)" }, "examples": [ { "requirement": "User registration", "metric": "Successful registration creates user in database", "target": "POST /register with valid data returns 201, user record exists in database", "validation": "Run integration test test_user_registration(), verify database query returns user" }, { "requirement": "JWT token generation", "metric": "Login returns valid JWT", "target": "POST /login returns 200 with token, token is valid for 1 hour", "validation": "Decode JWT and verify 'exp' claim is current_time + 3600 seconds" } ], "typical_count": "5-8 functional requirements" }, "quality_requirements": { "definition": "Code quality, maintainability, and standards compliance", "universal_criteria": [ { "requirement": "Code style compliance", "metric": "Linter passes with zero warnings", "target": "eslint / pylint / rubocop returns exit code 0", "validation": "Run linter on modified files" }, { "requirement": "Test coverage", "metric": "Percentage of lines covered by tests", "target": "> 80% line coverage for new code", "validation": "Run coverage tool (pytest-cov, jest --coverage, etc.)" }, { "requirement": "Type safety", "metric": "Type checker passes", "target": "TypeScript / mypy / Flow returns zero errors", "validation": "Run type checker on modified files" }, { "requirement": "Documentation completeness", "metric": "All public APIs documented", "target": "Every public function/method has docstring or JSDoc", "validation": "Run documentation coverage tool or manual inspection" }, { "requirement": "No code duplication", "metric": "Duplicate code percentage", "target": "< 5% duplicate code (per SonarQube or similar)", "validation": "Run code duplication detection tool" } ], "typical_count": "4-6 quality requirements" }, "performance_requirements": { "definition": "Speed, efficiency, scalability targets", "when_needed": "For features that process significant data or handle concurrent users", "examples": [ { "requirement": "API response time", "metric": "P95 latency for endpoints", "target": "< 200ms for login endpoint at 100 req/sec", "validation": "Run load test with Apache Bench / k6 / JMeter" }, { "requirement": "Database query performance", "metric": "Query execution time", "target": "< 50ms for user lookup query", "validation": "Use EXPLAIN ANALYZE (PostgreSQL) or similar" }, { "requirement": "Memory usage", "metric": "Peak memory consumption", "target": "< 500MB for typical workload", "validation": "Profile with memory profiler during load test" }, { "requirement": "Concurrent users", "metric": "Number of concurrent users supported", "target": "1000 concurrent users without degradation", "validation": "Run load test with 1000 virtual users" } ], "typical_count": "3-5 performance requirements (if applicable)" }, "security_requirements": { "definition": "Security validations and threat mitigations", "when_needed": "For any feature handling sensitive data, authentication, or user input", "examples": [ { "requirement": "Password security", "metric": "Password hashing strength", "target": "Bcrypt with cost factor >= 10, salted", "validation": "Inspect stored password hashes in database" }, { "requirement": "SQL injection prevention", "metric": "Parameterized queries used", "target": "Zero string concatenation in SQL queries", "validation": "Code review of all database operations + SQL injection test" }, { "requirement": "XSS prevention", "metric": "Output encoding applied", "target": "All user input encoded before rendering in HTML", "validation": "XSS vulnerability scan + manual testing" }, { "requirement": "Authentication token security", "metric": "Token storage and transmission", "target": "JWT stored in httpOnly cookie, HTTPS only", "validation": "Inspect network traffic and browser storage" } ], "typical_count": "3-5 security requirements" } }, "writing_guidelines": { "measurable": "Every target must be objectively measurable (not subjective)", "specific": "Use numbers, percentages, time units - not 'fast' or 'secure'", "bad_example": "System is performant", "good_example": "Login endpoint responds in < 200ms at P95 under 100 req/sec load", "testable": "Validation method must be clear and repeatable", "achievable": "Targets should be challenging but realistic" }, "quality_checklist": [ "☐ Every criterion has a measurable target (number, percentage, yes/no)", "☐ Validation method is specific (test name, command to run, tool to use)", "☐ Functional requirements cover all key features from section 4", "☐ Quality requirements include test coverage target", "☐ Performance requirements included if processing significant data", "☐ Security requirements included if handling sensitive data" ] }, "9_implementation_checklist": { "purpose": "Master checklist with all task IDs for tracking progress during implementation", "format": "Organized by phase with checkboxes", "structure": { "pre_implementation": [ "☐ Review complete plan for gaps or ambiguities", "☐ Get stakeholder approval (if required)", "☐ Commit finalized plan to main branch with message 'pre-{plan-name} execution commit' and push", "☐ Set up development environment" ], "phase_sections": "One section per phase from section 6, containing all task IDs", "finalization": [ "☐ All tests passing", "☐ Code review completed and approved", "☐ Documentation updated", "☐ Changelog entry created", "☐ Commit completed implementation to main branch with message 'post-{plan-name} execution commit' and push", "☐ Deploy to staging environment", "☐ Smoke tests on staging", "☐ Deploy to production (if applicable)" ] }, "checkbox_states": { "unchecked": "☐ TASK-ID: Description", "in_progress": "🔄 TASK-ID: Description (optional, if tool supports it)", "completed": "☑ TASK-ID: Description" }, "usage": { "during_planning": "Serves as final check that all tasks are covered", "during_implementation": "AI updates checkboxes as tasks complete", "progress_tracking": "Easy to see what % of work is done", "communication": "Share with stakeholders to show progress" }, "quality_checklist": [ "☐ Every task ID from phases appears in checklist", "☐ Tasks listed in logical execution order", "☐ Finalization steps included (tests, review, deploy)", "☐ Pre-implementation checks included", "☐ Checklist is flat (no nested checkboxes - hard to track)" ] } }, "QUALITY_CHECKLIST_FOR_PLANS": { "purpose": "Use this to validate your implementation plan before starting work", "completeness": [ "☐ Executive summary: All 5 fields filled with substantial content (not placeholders)", "☐ Risk assessment: Honest evaluation with all risk factors addressed", "☐ Current state: Every affected file listed with description of changes", "☐ Key features: 6-10 features covering primary, secondary, edge cases", "☐ Task IDs: All tasks have unique IDs following PREFIX-NNN format", "☐ Phases: 4-6 phases with clear completion criteria", "☐ Testing: Unit, integration, and 5+ edge case scenarios defined", "☐ Success criteria: Quantifiable metrics in all 4 categories", "☐ Implementation checklist: Every task ID appears with checkbox" ], "quality": [ "☐ No placeholder text like '[TBD]', '[to be determined]', '[figure out later]'", "☐ All task descriptions start with imperative verb (Create, Add, Implement)", "☐ Success criteria are measurable (numbers, not subjective judgments)", "☐ Edge cases cover: empty input, invalid input, boundaries, errors", "☐ Complexity and effort assessments are realistic (compare to similar past work)", "☐ Dependencies clearly specified (internal and external)", "☐ Security considerations addressed if handling sensitive data", "☐ Performance targets specified if processing significant data" ], "autonomy": [ "☐ Zero ambiguity - every decision has been made", "☐ AI could implement this without asking clarifying questions", "☐ Edge cases have defined expected behavior (not just 'handle somehow')", "☐ Success criteria are clear enough to know when 'done'", "☐ Review gates specified (when to pause for human approval)", "☐ All architectural decisions documented with rationale" ] }, "COMMON_MISTAKES_TO_AVOID": [ { "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 authentication", "why_bad": "Too broad; unclear what 'set up' means" }, { "mistake": "Missing edge cases", "bad": "Only testing happy path", "good": "Testing: happy path + 7 edge cases including empty input, invalid tokens, concurrent access", "why_bad": "Real-world usage will hit edge cases you didn't consider" }, { "mistake": "Subjective success criteria", "bad": "System is fast and secure", "good": "Login endpoint < 200ms P95 latency, passwords hashed with bcrypt cost>=10", "why_bad": "Can't objectively verify 'fast' or 'secure'" }, { "mistake": "Forgetting dependencies", "bad": "Using library without listing it in dependencies", "good": "NEW EXTERNAL: pyjwt==2.8.0 (add to requirements.txt)", "why_bad": "Code will fail at runtime with import errors" }, { "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", "why_bad": "Errors will crash the system or leak sensitive info" }, { "mistake": "Phases with circular 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)", "why_bad": "Can't execute phases sequentially" }, { "mistake": "Underestimating complexity and effort", "bad": "Authentication system marked as 'low complexity, effort level 1'", "good": "Authentication system: high complexity (multiple components), effort level 4 (significant implementation scope across security, API, database layers)", "why_bad": "Underestimating complexity leads to inadequate planning and missed edge cases" }, { "mistake": "Missing security considerations", "bad": "Store passwords as plain text", "good": "Hash passwords with bcrypt cost factor 10, store hash + salt in database", "why_bad": "Massive security vulnerability" } ], "USAGE_INSTRUCTIONS": { "when_to_create_plan": { "always_create_for": [ "New features (any significant new capability)", "Major refactoring (touching 5+ files)", "Architecture changes (new patterns, libraries, or paradigms)", "Performance optimizations (if they require code changes)", "Security enhancements (new authentication, authorization, encryption)", "Database schema changes (migrations, new tables)" ], "optional_for": [ "Bug fixes (unless complex - touching 3+ files)", "Minor refactoring (renaming, moving files)", "Documentation updates (unless restructuring entire docs)", "Configuration changes (unless they affect architecture)" ] }, "optional_pre_planning_step": { "action": "Gather feature context using /gather-context", "when_to_use": "Before creating implementation plan to clarify WHAT user wants", "purpose": "Create structured requirements briefing before planning HOW to implement", "output": "<feature-name>-context.json with requirements, constraints, and scope", "workflow": "See /gather-context slash command for interactive Q&A process", "benefit": "Provides clear goal and boundaries for implementation planning", "note": "This is optional but recommended for features where requirements are not yet fully defined" }, "how_to_use_this_meta_template": [ { "step": 1, "action": "Read this entire meta-template", "complexity": "simple", "effort_level": 2, "output": "Understanding of planning standard" }, { "step": 2, "action": "Create implementation plan file (feature-name-implementation-plan.json)", "complexity": "simple", "effort_level": 1, "output": "Empty plan file" }, { "step": 3, "action": "Complete preparation (section 0) - inventory docs and standards", "complexity": "medium", "effort_level": 3, "output": "Reference map of foundation docs, coding standards, and similar components" }, { "step": 4, "action": "Write executive summary (section 1)", "complexity": "simple", "effort_level": 2, "output": "Purpose, value proposition, analogy, use case, output" }, { "step": 5, "action": "Assess risks (section 2)", "complexity": "medium", "effort_level": 2, "output": "Risk levels and mitigation strategies" }, { "step": 6, "action": "Analyze current state (section 3)", "complexity": "medium", "effort_level": 3, "tips": "Actually review the codebase; don't guess which files are affected" }, { "step": 7, "action": "List key features (section 4)", "complexity": "simple", "effort_level": 2, "output": "6-10 features from user perspective" }, { "step": 8, "action": "Break work into tasks with IDs (section 5)", "complexity": "high", "effort_level": 4, "tips": "This is the core of the plan - be thorough; use appropriate prefixes" }, { "step": 9, "action": "Organize tasks into phases (section 6)", "complexity": "medium", "effort_level": 2, "output": "4-6 phases with completion criteria" }, { "step": 10, "action": "Define testing strategy (section 7)", "complexity": "medium", "effort_level": 3, "output": "Unit tests, integration tests, 5+ edge cases" }, { "step": 11, "action": "Set success criteria (section 8)", "complexity": "medium", "effort_level": 3, "output": "Quantifiable metrics across 4 categories" }, { "step": 12, "action": "Build implementation checklist (section 9)", "complexity": "simple", "effort_level": 2, "output": "Complete checklist with all task IDs" }, { "step": 13, "action": "Run quality checklist", "complexity": "medium", "effort_level": 2, "output": "Validated plan meeting all quality standards" }, { "step": 14, "action": "Get stakeholder approval", "complexity": "simple", "effort_level": 1, "tips": "Present executive summary + risk assessment + complexity/effort analysis" }, { "step": 15, "action": "Commit finalized plan and push to remote", "complexity": "simple", "effort_level": 1, "output": "Plan committed to main branch with 'pre-{plan-name} execution commit' message", "tips": "Creates audit trail showing approved plan before implementation begins. Commit directly to main: git add <plan-file> && git commit -m 'pre-{plan-name} execution commit' && git push origin main" } ], "overall_planning_effort": "Comprehensive planning requires moderate to high effort for complex features", "note": "Thorough upfront planning prevents rework and ensures successful autonomous implementation" } }