Documentation Generator MCP Server

================================================================================ CLAUDE.MD AND /GATHER-CONTEXT WORKFLOW RELATIONSHIP ================================================================================ PURPOSE: Clarify how claude.md files (narrative context) work alongside context.json (structured data) in the feature implementation workflow. ================================================================================ FEATURE STARTUP WORKFLOW ================================================================================ NEW FEATURE INITIATED: ↓ ┌─────────────────────────────────┐ │ Use /gather-context │ ← Structured data collection │ Creates: context.json │ └─────────────────────────────────┘ ↓ ┌─────────────────────────────────┐ │ Create claude.md files │ ← Narrative context documentation │ Creates: claude.md (project) │ │ Creates: claude.md (phase-1) │ └─────────────────────────────────┘ ↓ ┌─────────────────────────────────┐ │ Use /analyze-for-planning │ ← Project analysis │ Creates: analysis.json │ └─────────────────────────────────┘ ↓ ┌─────────────────────────────────┐ │ Use /create-plan │ ← Implementation plan │ Creates: plan.json │ └─────────────────────────────────┘ ================================================================================ WORKING FOLDER STRUCTURE (AFTER NEW FEATURE SETUP) ================================================================================ /working/{feature-name}/ ├── claude.md ← Project-level narrative context ├── context.json ← From /gather-context (structured requirements) ├── analysis.json ← From /analyze-for-planning (project analysis) ├── plan.json ← From /create-plan (implementation plan) ├── phase-1/ │ ├── claude.md ← Phase-level narrative context │ └── [implementation files] ├── phase-2/ │ ├── claude.md │ └── [implementation files] └── phase-3/ ├── claude.md └── [implementation files] ================================================================================ DOCUMENT PURPOSES (WHAT GOES WHERE) ================================================================================ CONTEXT.JSON (From /gather-context): ├── Structured JSON format ├── Machine-readable ├── Specific requirements and goals ├── User stories or acceptance criteria └── Used by: /analyze-for-planning and /create-plan tools CLAUDE.MD - Project Level (Manual Creation): ├── Narrative markdown format ├── Human/Agent-readable ├── Project overview and architecture ├── Technology stack and key decisions ├── Overall project blockers and dependencies └── Used by: Agents joining mid-project for rapid context CLAUDE.MD - Phase Level (Manual Creation): ├── Narrative markdown format ├── Human/Agent-readable ├── Current phase status and objectives ├── Completed tasks and next steps ├── Code hot spots and gotchas └── Used by: Agents working on current phase ANALYSIS.JSON (From /analyze-for-planning): ├── Structured JSON format ├── Machine-readable ├── Project structure and tech stack ├── Foundation docs and standards ├── Identified gaps and risks └── Used by: /create-plan to inform planning PLAN.JSON (From /create-plan): ├── Structured JSON format ├── Machine-readable ├── 10-section implementation plan ├── Tasks, milestones, success criteria ├── Testing strategy and risk assessment └── Used by: /validate-plan for quality scoring ================================================================================ WORKFLOW: NEW FEATURE START-TO-PLAN ================================================================================ STEP 1: FEATURE BEGINS Time: T+0 Agent: Product or feature lead Action: Decide to build new feature "X" Creates: Nothing yet, just decision --- STEP 2: GATHER REQUIREMENTS (/gather-context) Time: T+15min Agent: Requirements gatherer or product team Command: /gather-context Input: Feature questions answered interactively Output: context.json saved to coderef/working/{feature-name}/context.json Contains: - Feature goals and user stories - Success criteria - Dependencies and constraints - Out-of-scope items Example context.json: { "feature_name": "dark-mode-toggle", "goals": ["Allow users to switch themes", "Persist preference"], "user_stories": [ "As a user, I want to toggle dark mode from settings", "As a user, my theme choice should persist across sessions" ], "acceptance_criteria": ["...", "..."], "dependencies": ["Theme library", "localStorage"], "constraints": ["Must work on mobile"] } --- STEP 3: CREATE INITIAL CLAUDE.MD FILES (Manual) Time: T+30min Agent: Project lead or new agent Action: Create two claude.md files from templates: 1. claude.md in /working/{feature-name}/ (project overview) 2. claude.md in /working/{feature-name}/phase-1/ (phase context) Populate with: - Feature goals (can reference context.json) - Architecture overview (what you know so far) - Initial tech stack decision - Phase 1 objectives Contains: - Human-readable project summary - Quick reference for context - Phase-specific next steps Example project claude.md summary: --- # Project: Dark Mode Toggle **Status:** Planning **Created:** 2025-10-15 ## Quick Summary Add dark mode toggle to app settings with persistent user preference. ## Phase 1 Objective Implement theme provider and context system. --- --- STEP 4: ANALYZE PROJECT (/analyze-for-planning) Time: T+45min Agent: Planning agent Command: /analyze-for-planning --feature-name dark-mode-toggle Output: analysis.json saved to coderef/working/{feature-name}/analysis.json Contains: - Current tech stack - Existing patterns - Foundation docs available - Coding standards - Project structure - Identified risks/gaps Example analysis.json: { "technology_stack": { "framework": "React", "styling": "styled-components", "state": "Context API" }, "existing_patterns": ["Custom hooks", "Provider patterns"], "foundation_docs": ["README.md", "ARCHITECTURE.md"], "gaps": ["Theme documentation"] } --- STEP 5: CREATE IMPLEMENTATION PLAN (/create-plan) Time: T+60min (automatic, uses context.json + analysis.json) Agent: Planning AI Command: /create-plan --feature-name dark-mode-toggle Inputs: - context.json (from Step 2) - analysis.json (from Step 4) - Planning template (AI-optimized) Output: plan.json saved to coderef/working/{feature-name}/plan.json Contains: - 10 sections (preparation through implementation checklist) - Tasks broken down by phase - Testing strategy - Success criteria - Risk assessment --- STEP 6: VALIDATE PLAN (/validate-plan) Time: T+75min Agent: Validation agent Command: /validate-plan Score: 0-100 (typically 75-95 on first pass) If score >= 90: Ready for implementation If score < 90: Refine and re-validate (review loop) --- STEP 7: GENERATE REVIEW REPORT (/generate-plan-review) Time: T+90min (optional, for documentation) Agent: Planning AI Command: /generate-plan-review Output: Markdown review report with: - Approval status - Issues by severity - Recommendations ================================================================================ PRACTICAL EXAMPLE: DARK MODE FEATURE ================================================================================ FOLDER STRUCTURE AFTER SETUP: /working/dark-mode-toggle/ ├── claude.md ← Project overview (manual) ├── context.json ← From /gather-context ├── analysis.json ← From /analyze-for-planning ├── plan.json ← From /create-plan ├── phase-1/ │ ├── claude.md ← Phase context (manual) │ └── ... ├── phase-2/ │ ├── claude.md │ └── ... └── phase-3/ ├── claude.md └── ... --- NEW AGENT JOINING PHASE 2 (Mid-Project): Agent reads in this order: 1. /working/dark-mode-toggle/claude.md (2 min) → "Oh, we're building a dark mode toggle with React + styled-components" 2. /working/dark-mode-toggle/phase-1/claude.md (2 min) → "Phase 1 created theme provider, that's done" 3. /working/dark-mode-toggle/phase-2/claude.md (5 min) → "Phase 2: Add theme toggle to UI, currently blocked on color palette" 4. /working/dark-mode-toggle/plan.json (5 min) → Full implementation details and task breakdown 5. /working/dark-mode-toggle/context.json (3 min) → Requirements and acceptance criteria Total ramp-up time: ~15-20 minutes instead of 1-2 hours --- CURRENT PHASE TASK LIST (From phase-2/claude.md): ## What's Been Completed ✓ - [x] Theme provider implemented - [x] Context API setup - [x] Testing harness ready ## What's In Progress 🔄 - [ ] Theme toggle UI component - 50% complete Blocker: Awaiting color palette from design team ## What's Next 1. [ ] Add theme toggle to header 2. [ ] Implement theme persistence 3. [ ] Write component tests ================================================================================ KEY RELATIONSHIPS ================================================================================ /gather-context creates: context.json (structured feature requirements) claude.md files created: - Narrative project context - Complement context.json (structured requirements) - Provide "why" and "what we know" in human terms /analyze-for-planning creates: analysis.json (project structure analysis) /create-plan reads: - context.json (feature requirements) - analysis.json (project structure) - Planning template (structure) And creates: - plan.json (implementation plan) claude.md files are READ by: - New agents joining mid-project - Team members reviewing progress - Documentation systems NOT used as input to /gather-context or /create-plan (Those use structured .json files) ================================================================================ WHEN TO UPDATE CLAUDE.MD FILES ================================================================================ PROJECT-LEVEL CLAUDE.MD: - At feature start (initial setup) - After phase transitions (update current phase) - When blockers change (update known blockers) - When major architectural decisions change PHASE-LEVEL CLAUDE.MD: - At phase start (setup from template) - Daily or after milestones (update progress) - When blockers emerge (add to blockers section) - When agent changes (add "notes from last agent") - Before phase completion (mark complete, note lessons learned) ================================================================================ SUMMARY ================================================================================ /gather-context: ↓ Creates structured JSON ↓ context.json (machine-readable requirements) ↓ claude.md files (narratives): ↓ Provide rapid human/agent context ↓ "Big picture" understanding ↓ /analyze-for-planning: ↓ Creates structured JSON ↓ analysis.json (project structure) ↓ /create-plan: ↓ Uses context.json + analysis.json as input ↓ Creates plan.json (10-section implementation plan) ↓ Project execution: ↓ Agents use claude.md for narrative context ↓ Use plan.json for task breakdown ↓ Update phase claude.md files as work progresses ↓ Archive when complete: ↓ All files (claude.md, context.json, analysis.json, plan.json) → /archived/ ================================================================================