Project MOC Generator

This skill generates comprehensive, GitHub-compatible Map of Content (MOC) documentation for software development projects. It analyzes your codebase's current state, extracts implemented features, documents architectural decisions, and creates a structured documentation hierarchy using standard markdown links that render perfectly on GitHub and other platforms.

Capabilities

• Project MOC Generation: Creates top-level overview MOC linking to feature areas, architecture decisions, tech stack documentation, and component maps
• Feature Documentation Extraction: Analyzes implemented features in the codebase and generates feature-specific MOCs with component links and implementation details
• Decision History Documentation: Captures architectural and technical decisions, including what was considered but not implemented and the reasoning behind choices
• Component Mapping: Creates detailed documentation for each major component including code file links, dependencies, and implementation patterns
• Devlog Analysis: Reads and synthesizes information from docs/devlog/ folder to understand project evolution and ongoing work
• Standard Markdown Links: Uses [text](path) format (not wiki-links) ensuring compatibility with GitHub, GitLab, and all markdown renderers
• Date Tracking: Includes frontmatter with generation dates to track when documentation was last updated
• Current State Focus: Documents features as they exist NOW, not intended or future features
• Mermaid Diagrams: Uses Mermaid for all visualizations (architecture, data flow, component relationships) - renders perfectly on GitHub

Input Requirements

The skill expects:

• Project root access: Ability to read codebase structure and files
• docs/ folder: Output location where MOC files will be created
• docs/devlog/ folder (optional but recommended): Contains devlog entries, interstitial notes, or ongoing work documentation
• Source code access: To analyze actual implementation and extract feature details

Optional context that improves output:

• README.md or project documentation
• Architecture diagrams or notes
• CHANGELOG or version history
• Package configuration files (package.json, requirements.txt, etc.)

Output Formats

All output is written to the docs/moc/ folder in your project:

Project MOC Structure

docs/
└── moc/
    ├── README.md           # Main entry point (auto-renders on GitHub!)
    ├── features.md         # Feature overview and catalog
    ├── architecture.md     # Architecture and design decisions
    ├── components.md       # Component maps and details
    └── decisions.md        # Architectural decision records (optional)

Benefits of this structure:

• Single moc/ folder keeps all MOC files together
• README.md auto-renders when you navigate to docs/moc/ on GitHub
• Lowercase filenames follow markdown conventions
• No _MOC suffix needed (folder context makes it clear)
• Won't conflict with existing docs/ files

Frontmatter Format

Every generated MOC includes:

---
title: Document Title
type: moc
generated: 2025-11-20
last_updated: 2025-11-20
project: [Extracted from package.json or project files]
---

Link Format

All links use standard markdown (NOT wiki-links):

# From docs/moc/README.md:
- [Features](./features.md)
- [Architecture](./architecture.md)
- [Components](./components.md)

# From any MOC file to source code:
- [Source Code](../../src/auth/index.ts)

# From README to MOC:
- [Project MOC](./docs/moc/README.md)

This ensures perfect rendering on GitHub, GitLab, and all markdown viewers.

How to Use

Invoke the skill to generate comprehensive project documentation:

Basic invocation: "Generate a complete project MOC for this codebase"

Feature-focused: "Analyze the implemented features and create feature MOCs"

Decision history: "Document the architectural decisions and what was considered but not implemented"

Component mapping: "Create component maps for all major services and modules"

Devlog synthesis: "Read the devlog folder and synthesize the project evolution"

Full documentation: "Generate complete project documentation including MOCs for features, architecture, components, and decision history"

Analysis Process

1. Project Discovery Phase

• Scan project root for configuration files (package.json, etc.)
• Identify main source directories
• Detect technology stack and frameworks
• Parse existing documentation in docs/ folder
• Analyze devlog/ entries for context

2. Feature Extraction Phase

• Read source code to identify implemented features
• Map features to their implementation files
• Extract feature descriptions from code comments and structure
• Document current feature capabilities (NOT future/planned features)
• Create feature dependency graph

3. Component Analysis Phase

• Identify major components, services, and modules
• Document component responsibilities and interfaces
• Map inter-component dependencies
• Link to source code files
• Extract implementation patterns

4. Decision Documentation Phase

• Analyze code for architectural patterns
• Review devlog for decision rationale
• Document technology choices
• Capture "roads not taken" with reasoning
• Link decisions to affected components

5. MOC Generation Phase

• Create docs/moc/ directory
• Generate README.md as main entry point (auto-renders on GitHub)
• Create category MOCs with lowercase names (features.md, architecture.md, components.md)
• Add standard markdown links throughout
• Include date frontmatter on all documents
• Use simple, clean filenames without _MOC suffix
• Add Mermaid diagrams for visualizations (architecture, data flow, component relationships)

6. Integration Phase

• Ensure all links are valid and use correct paths
• Verify GitHub compatibility (no wiki-links)
• Update existing docs/ files if needed
• Create index structure for easy navigation

Link Guidelines

DO:

• Use [Text](./path/to/file.md) for same-level links
• Use [Text](../src/file.ts) for source code links
• Use relative paths from document location
• Include file extensions (.md, .ts, .py, etc.)
• Test that links render on GitHub

DON'T:

• Use wiki-links [[like this]]
• Use absolute paths from root
• Omit file extensions
• Create circular link dependencies
• Link to non-existent files

Frontmatter Fields

Every generated MOC includes these fields:

---
title: "Human-readable title"
type: moc                    # Or: feature, component, architecture
generated: YYYY-MM-DD        # When first created
last_updated: YYYY-MM-DD     # When last regenerated
project: "Project Name"      # From package.json or similar
status: current              # Or: draft, archived
---

Additional optional fields:

• tags: List of relevant tags
• version: Project version this docs reflects
• authors: Primary contributors
• related: Links to related MOCs

Diagram Guidelines

Use Mermaid for All Visualizations

ALWAYS use Mermaid diagrams instead of ASCII art. Mermaid renders beautifully on GitHub and provides professional-looking visualizations.

Common Diagram Types:

1. Architecture Diagrams (Flowchart):

flowchart TB
    A[Client] --> B[API Gateway]
    B --> C[Auth Service]
    B --> D[Business Logic]
    D --> E[(Database)]

2. Component Relationships (Graph):

graph LR
    A[Frontend] --> B[API]
    B --> C[Auth]
    B --> D[Data Layer]
    C --> D

3. Data Flow (Sequence):

sequenceDiagram
    User->>API: Request
    API->>DB: Query
    DB->>API: Data
    API->>User: Response

4. System Architecture (C4 Context):

graph TB
    subgraph "System Context"
        A[User]
        B[Web App]
        C[API]
        D[(Database)]
    end
    A --> B
    B --> C
    C --> D

DON'T Use:

• ASCII art boxes and arrows
• Text-based diagrams
• Non-rendering visualizations

DO Use:

• Mermaid flowchart for architecture
• Mermaid graph for component relationships
• Mermaid sequenceDiagram for data flow
• Mermaid classDiagram for data models

Best Practices

1. Run after significant feature work: Generate MOCs when you've completed a feature or milestone to capture current state
2. Maintain devlog alongside: Keep notes in docs/devlog/ as you work - these provide valuable context for MOC generation
3. Review and enhance: Generated MOCs are starting points - add human insights, diagrams, and examples
4. Update regularly: Re-run the skill periodically to keep documentation in sync with code
5. Commit to git: Documentation changes should be tracked alongside code changes
6. Link from README: Add a link to docs/moc/ from your main README for discoverability

Use Cases

For Development Teams

• Onboard new developers with comprehensive project overview
• Maintain living documentation that stays current
• Document "why" decisions were made for future reference
• Create knowledge base of features and components

For Stakeholders

• Provide high-level project understanding without technical deep-dive
• Show what features are actually implemented vs planned
• Demonstrate architectural thinking and decision-making
• Create artifact suitable for reports or presentations

For Future You

• Remember why you chose one approach over another
• Understand the project after time away
• Locate specific implementations quickly
• Reconstruct decision context

Integration with Git Workflow

Recommended workflow:

# After completing feature work
claude @project-moc-generator "Generate updated project MOC"

# Review generated docs
git status

# Commit alongside code changes
git add docs/
git commit -m "feat: add user authentication

Updated docs with auth feature MOC and component maps"

Limitations

• Current state only: Documents what exists, not what's planned or intended
• No GitHub Issues integration: Focuses on code, not issue tracker
• Requires source code access: Cannot document from external descriptions alone
• Static snapshot: Documentation reflects point in time, must be regenerated to stay current
• Best with devlog: Most effective when docs/devlog/ contains ongoing notes and context
• Manual enhancement needed: Generated docs are comprehensive but benefit from human refinement
• Not a replacement for code comments: Complements but doesn't replace inline documentation

Output Location

All files are written to docs/moc/ folder in your project root:

• docs/moc/README.md - Main entry point (auto-renders on GitHub)
• docs/moc/features.md - Feature catalog and status
• docs/moc/architecture.md - Architecture and design decisions
• docs/moc/components.md - Component maps and details
• docs/devlog/ - User-maintained notes (read-only for this skill, analyzed for context)

This structure keeps all MOC documentation in one clean location, using lowercase filenames that follow standard markdown conventions.