Project Structure Documentation Generator

Generate PROJECT-STRUCTURE.md with comprehensive tree representation, meaningful comments, and utility dependency analysis.

Core Workflow

Important: All file operations should be relative to the git repository root. Always determine the git root first:

GIT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)

Then reference files as $GIT_ROOT/PROJECT-STRUCTURE.md, $GIT_ROOT/package.json, etc.

Generation Process

1. •

   Detect package manager and read production dependencies:

   bash

   # Check for package managers (use $GIT_ROOT for all paths)
   test -f "$GIT_ROOT/package.json" && echo "node_found"
   test -f "$GIT_ROOT/pyproject.toml" && echo "python_toml_found"
   test -f "$GIT_ROOT/requirements.txt" && echo "python_requirements_found"
   test -f "$GIT_ROOT/Cargo.toml" && echo "rust_found"
   test -f "$GIT_ROOT/go.mod" && echo "go_found"
   

   • •Read dependency files to identify production dependencies
   • •Store list for later analysis in Step 6
2. •

   Gather all files (respecting .gitignore):

   bash

   # Change to git root first, then gather files
   cd "$GIT_ROOT"
   
   # Get tracked files
   git ls-files
   
   # Get untracked files (respects .gitignore)
   git ls-files --others --exclude-standard
   

   • •Combine both lists for complete file inventory
   • •All paths will be relative to git root
3. •

   Build directory tree structure with root files:

   • •CRITICAL: Show ALL directories at ALL nesting levels, but ONLY files in the repository root
   • •Build complete directory hierarchy recursively
   • •Include all files at the repository root level
   • •Do NOT show individual files within subdirectories
   • •Use proper tree formatting:
     • •├── for items with siblings below
     • •└── for last item in directory
     • •│ for vertical continuation
     • •Indent 4 spaces per level
   • •Example structure:
     code

     package.json            # Node.js dependencies and scripts
     README.md              # Project overview and setup instructions
     src/                   # Source: React components (45), utilities (12). Entry App.tsx
     ├── components/        # UI components: Button, Card, Form. Design system, accessibility. 15 modules
     │   ├── Button/       # Button component: primary/secondary variants. Tests, Storybook stories
     │   └── Form/         # Form inputs: Input, Select, Checkbox. Validation, error handling
     └── utils/             # Utilities: formatting, validation, data transformation. 12 helpers
     

4. •

   Generate telegraphic comments for directories and root files:

   • •Read comment-guidelines.md
   • •CRITICAL: Every directory at every nesting level must have a keyword-dense comment
   • •For root-level files: ~8-12 words describing functionality and purpose
   • •For directories: ~14-23 words using telegraphic style:
     • •Format: Purpose: key items. Tech/patterns. Counts
     • •List key items by name (Button, Card, Form OR AuthService, UserService)
     • •Mention tech/patterns concisely (JWT, React hooks, Sequelize ORM)
     • •Include counts when relevant (15 modules, 8 files)
     • •Omit articles (the, a, an) and unnecessary verbs
   • •Describe WHAT content is about, not just restate names
   • •Use Read/Glob/Grep to understand directory contents and structure
   • •Examples:
     • •components/ → "UI components: Button, Card, Form, Modal. Design system, accessibility, tests, stories. 15 modules"
     • •components/Button/ → "Button component: primary/secondary/tertiary variants, loading states. ARIA accessibility, tests, Storybook stories"
5. •

   Analyze utility dependencies:

   • •Read dependency-analysis.md
   • •Categorize production dependencies
   • •Analyze actual usage patterns
   • •Document commonly used functions
   • •Only include meaningful utilities (3+ file usage)
6. •

   Write PROJECT-STRUCTURE.md:

   File Format:

   markdown

   # Project Structure
   
   *Generated on [current date and time] with the project-structure skill*
   
   [FULL RECURSIVE tree showing ALL directories and files at ALL nesting levels with inline comments]
   
   ## Utility Dependencies
   
   **Note:** Before implementing custom utilities, check if functionality exists in these libraries.
   
   [Dependency analysis by category - ONLY if meaningful production dependencies exist]
   

   File Location:

   • •File path: $GIT_ROOT/PROJECT-STRUCTURE.md
   • •Always write to git repository root
   • •File is standalone, dedicated to project structure documentation

   Use Write tool:

   • •Use Write to create or replace the entire file
   • •Since this is a dedicated file, simply write the complete content
   • •The file will be overwritten if it already exists

   CRITICAL Tree Requirements:

   • •Show complete recursive directory structure - expand ALL directories at ALL levels
   • •Show ONLY root-level files - do NOT show files within subdirectories
   • •Every directory at every level gets a telegraphic comment (e.g., components/ # UI components: Button, Card. Design system. 15 modules)
   • •Every root file gets a comment (e.g., package.json # Node.js dependencies and scripts)
   • •All comments are INLINE in the tree - NO separate sections
   • •Directory comments use telegraphic style - Format: Purpose: items. Tech. Counts (~14-23 words)
   • •Omit articles and unnecessary verbs - keyword-dense, information-rich
   • •NO extra sections beyond tree and dependencies
   • •Utility Dependencies section (##) only included if meaningful production dependencies found (3+ file usage or critical utilities)

Output Format

See examples.md for complete example outputs.

File Structure (PROJECT-STRUCTURE.md):

1. •# Project Structure header (level 1, since it's the main document title)
2. •Generation attribution line in italics: *Generated on [date and time] with the project-structure skill*
3. •Complete directory tree with root files and inline comments:
   • •All root-level files with comments
   • •All directories at all nesting levels with detailed comments
   • •NO files shown within subdirectories
4. •## Utility Dependencies section (level 2, ONLY if meaningful production dependencies exist)

File Notes:

• •The file is standalone and dedicated to project structure
• •Located at repository root: $GIT_ROOT/PROJECT-STRUCTURE.md
• •File is always generated fresh (simple and clean)
• •Keep the file simple and focused - no extra sections beyond Utility Dependencies

Performance Tips

• •Use Glob for efficient directory scanning
• •Use Grep to understand file purposes
• •Read representative files, not every file
• •Build tree incrementally
• •Leverage progressive disclosure (read reference docs as needed)

Key Principles

1. •Respect .gitignore - Only document relevant project files
2. •Directory-focused structure - Show all directories with telegraphic comments, only root-level files
3. •Telegraphic comments - Use keyword-dense style: Purpose: items. Tech. Counts (~14-23 words)
4. •Production focus - Only document production dependencies

Reference Materials

• •comment-guidelines.md - Telegraphic comment style guide with examples
• •dependency-analysis.md - Dependency documentation
• •examples.md - Real-world examples with telegraphic comments

Begin Execution

Read reference materials as needed using progressive disclosure and generate the project structure documentation.