docs/templates/documentation_format_guide.md

metadata

title: KGraph-MCP Documentation Format Guide
type: meta_documentation
version: '1.0'
created_by: AI Development Assistant
last_updated: <DATE>

KGraph-MCP Documentation Format Guide

📋 Overview

This guide presents an optimal documentation format system for the KGraph-MCP project, designed specifically for AI-assisted development workflows. The system provides three interconnected PRD-style templates that create a comprehensive documentation hierarchy.

🏗️ Documentation Architecture

Three-Tier Documentation System

Project Level (Months)
    ↓
MVP Level (Days/Weeks)  
    ↓
Sprint Level (Hours/Days)
    ↓
Task Level (Individual Files)

Template Hierarchy

1. Project Description Format (project_description_format.md)

   • Purpose: High-level project charter and vision
   • Scope: Entire project lifecycle
   • Audience: Stakeholders, architects, project managers
   • Update Frequency: Quarterly or at major milestones

2. MVP Description Format (mvp_description_format.md)

   • Purpose: Epic/release planning for individual MVPs
   • Scope: Single MVP (typically 1-5 days for hackathons)
   • Audience: MVP owners, tech leads, development teams
   • Update Frequency: At MVP planning and completion

3. Sprint Description Format (sprint_description_format.md)

   • Purpose: Detailed sprint planning and execution
   • Scope: Individual sprints (typically 1-2 days for hackathons)
   • Audience: Sprint leads, developers, AI assistants
   • Update Frequency: At sprint start, daily standup, sprint end

🎯 Format Design Principles

AI-First Development Integration

• Claude/Cursor Optimized: Each template includes specific AI assistant guidance
• Context-Rich: Provides comprehensive context for AI-assisted coding
• Prompt Engineering: Built-in prompts for common development tasks
• Quality Gates: Automated checks integrate with AI workflows

GitHub Workflow Integration

• Issue/Project Sync: Metadata formats work with GitHub API
• Conventional Commits: Built-in commit message standards
• CI/CD Ready: Quality gates align with automated pipelines
• Task Tracking: Seamless integration with justfile recipes

Hackathon-Optimized Features

• Rapid Iteration: Templates support fast-paced development
• Demo-Focused: Emphasis on demonstrable outcomes
• Risk Mitigation: Built-in contingency planning
• Time-Boxing: Clear duration estimates and constraints

📝 Implementation Workflow

Phase 1: Project Initiation

Step 1: Create Project Description

# Copy project template
cp docs/templates/project_description_format.md docs/project_charter.md

# Customize for your project
# - Fill in project metadata
# - Define vision and problem statement
# - Set up MVP progression strategy
# - Establish development workflow

Step 2: Set Up Development Environment

# Create documentation structure
mkdir -p docs/{mvps,sprints,architecture,api,user}
mkdir -p docs/tasks/{mvp1,mvp2,mvp3,mvp4,mvp5}

# Set up templates directory
mkdir -p docs/templates
cp docs/templates/*.md docs/templates/

Phase 2: MVP Planning

Step 1: Create MVP Description

# For each MVP (e.g., MVP3)
cp docs/templates/mvp_description_format.md docs/mvps/mvp3_description.md

# Customize MVP-specific content
# - Define MVP goal and value proposition
# - Plan sprint breakdown
# - Set success criteria
# - Define integration points

Step 2: Generate Sprint Plans

# For each sprint in the MVP (e.g., MVP3 Sprint2)
cp docs/templates/sprint_description_format.md docs/sprints/mvp3_sprint2_plan.md

# Use justfile integration
just mvp-task-create 3 2 "UI_Enhancement" "Enhance Gradio UI for PlannedStep display"

Phase 3: Sprint Execution

Step 1: Daily Development Workflow

# Morning: Review sprint plan
cat docs/sprints/mvp3_sprint2_plan.md

# During development: Reference AI assistant guidance
# Use task-specific Claude/Cursor prompts from sprint plan

# Evening: Update progress metrics
# Update task status in sprint document

Step 2: Quality Gates Integration

# Built into justfile recipes
just lint     # ruff check
just format   # black formatting  
just type-check  # mypy validation
just test     # pytest with coverage

🛠️ Customization Guidelines

Project-Specific Adaptations

For Hackathon Projects:

• Reduce planning overhead in templates
• Focus on demo-ready deliverables
• Emphasize rapid iteration cycles
• Include sponsor technology integration

For Production Projects:

• Add security and compliance sections
• Include more detailed architecture reviews
• Expand testing and quality requirements
• Add deployment and maintenance planning

For Research Projects:

• Include hypothesis and experimentation sections
• Add literature review and reference sections
• Include data collection and analysis plans
• Add publication and presentation planning

AI Assistant Integration Patterns

Claude/Cursor Prompt Templates:

## AI Assistant Guidance for Task <TASK_ID>

### Context Setting

You are helping develop the KGraph-MCP project, specifically working on .

Key context:

• Current MVP: ()
• Current Sprint: ()
• Task Type: <FOUNDATION|FEATURE|INTEGRATION|TESTING>
• Dependencies:

### Development Focus
- Primary files to modify: <FILE_LIST>
- Key patterns to follow: <PATTERN_LIST>
- Testing approach: <TESTING_STRATEGY>
- Integration requirements: <INTEGRATION_POINTS>

### Quality Standards
- Code style: Ruff + Black + MyPy
- Test coverage: >=80%
- Commit format: Conventional Commits
- Documentation: Docstrings + type hints

GitHub Integration Patterns:

# In project_description_format.md metadata
github_integration:
  project_id: 11
  issue_template: "docs/templates/task_template.md"
  commit_convention: "conventional_commits"
  ci_pipeline: ".github/workflows/ci.yml"
  
# In mvp_description_format.md
mvp_tracking:
  milestone: "MVP<N>"
  epic_label: "epic:mvp<N>"
  sprint_labels: ["sprint:1", "sprint:2", "sprint:3"]
  
# In sprint_description_format.md  
sprint_automation:
  task_creation: "just mvp-task-create <MVP> <SPRINT> <NAME>"
  progress_tracking: "just tasks-status-update"
  completion_check: "just sprint-validate <MVP> <SPRINT>"

📊 Usage Examples

Example 1: Starting MVP3

Step 1: Create MVP3 Description

# Copy template and customize
cp docs/templates/mvp_description_format.md docs/mvps/mvp3_interactive_execution.md

# Key customizations:
# - mvp_id: "3"
# - mvp_name: "Interactive Prompt Filling & Simulated Execution"  
# - duration_estimate: "3_days"
# - total_sprints: 5
# - primary_track: "Track 3: Agentic Demo"

Step 2: Plan Sprint Breakdown

# In mvp3_interactive_execution.md
sprint_roadmap:
  - sprint: 1
    name: "Dynamic UI Foundation"
    duration: "6_hours"
    primary_goal: "Generate dynamic input fields"
    key_deliverables: ["Dynamic field generation", "Input collection"]
  
  - sprint: 2  
    name: "User Input Integration"
    duration: "8_hours"
    primary_goal: "Collect and validate user inputs"
    key_deliverables: ["Input validation", "Executor integration"]

Example 2: Executing Sprint Planning

Step 1: Create Sprint Plan

cp docs/templates/sprint_description_format.md docs/sprints/mvp3_sprint1_dynamic_ui.md

Step 2: Customize Sprint Details

# In mvp3_sprint1_dynamic_ui.md
sprint_metadata:
  sprint_id: "3_S1"
  sprint_name: "Dynamic UI Foundation"
  mvp_parent: "MVP3: Interactive Prompt Filling & Simulated Execution"
  duration_estimate: "6_hours"
  
technical_approach:
  implementation_strategy: "TDD with Gradio component generation"
  design_patterns: ["Factory Pattern", "Observer Pattern"]
  
task_organization:
  total_tasks: 3
  task_methodology: "tdd_with_ai_assistance"
  parallel_workstreams: 1

Step 3: Define Tasks with AI Guidance

# Task example in sprint plan
task_3_1:
  objective: "Implement dynamic Gradio input field generation"
  files_to_modify: ["app.py", "agents/planner.py"]
  ai_assistant_guidance: |
    For Claude/Cursor IDE:
    - Focus areas: Gradio component factory pattern
    - Key patterns: Dynamic UI generation based on MCPPrompt.input_variables
    - Testing approach: Mock MCPPrompt objects with various input_variables
    - Integration points: Connect with existing handle_find_tools function

🔄 Maintenance and Evolution

Template Updates

• Version Control: Track template versions in frontmatter
• Backward Compatibility: Maintain compatibility with existing documents
• Regular Review: Quarterly review of template effectiveness
• Community Feedback: Incorporate lessons learned from usage

Process Improvement

• Metrics Collection: Track documentation quality and usage
• Automation Enhancement: Improve justfile recipe integration
• AI Assistant Optimization: Refine AI guidance patterns
• Tool Integration: Enhance GitHub and CI/CD integration

Scaling Considerations

• Team Growth: Adapt templates for larger development teams
• Project Complexity: Scale templates for more complex projects
• Multi-Project Use: Abstract common patterns for reuse
• Enterprise Features: Add compliance and governance sections

📚 Best Practices

Documentation Quality

1. Completeness: Fill all template sections thoroughly
2. Specificity: Use concrete, measurable criteria
3. Consistency: Follow naming and formatting conventions
4. Timeliness: Update documents promptly as work progresses

AI Assistant Optimization

1. Context Richness: Provide comprehensive context in AI guidance sections
2. Pattern Consistency: Use consistent prompt engineering patterns
3. Quality Standards: Include quality gates in all AI interactions
4. Feedback Loops: Capture and improve AI assistance effectiveness

Team Collaboration

1. Shared Understanding: Ensure all team members understand template structure
2. Review Process: Establish document review and approval workflows
3. Communication: Use templates as basis for team communication
4. Knowledge Transfer: Use templates for onboarding and handoffs

🔗 Integration Points

Existing KGraph-MCP Tools

• Justfile Recipes: Templates integrate with existing just commands
• GitHub Projects: Metadata aligns with project management workflow
• CI/CD Pipeline: Quality gates sync with automated validation
• Task Management: Links to docs/tasks/ directory structure

Development Workflow

• Planning: Templates support sprint and MVP planning
• Execution: AI guidance improves development velocity
• Quality: Built-in quality gates ensure code standards
• Retrospectives: Templates capture lessons learned

---

🚀 Getting Started

Quick Start Checklist

• Copy all three templates to your docs/templates/ directory
• Create initial project description document
• Set up documentation directory structure
• Configure justfile integration for task creation
• Train team on template usage and customization
• Start with first MVP description and sprint plan

Success Metrics

• Documentation Coverage: All projects, MVPs, and sprints documented
• AI Assistance Quality: Improved development velocity with AI
• Team Satisfaction: Positive feedback on documentation usefulness
• Delivery Success: On-time, quality deliverables aligned with plans

---

Next Steps: Choose your first project and begin with the Project Description Format template. Customize it for your specific needs and establish the foundation for systematic, AI-assisted development documentation.