context-generation

Context Generation Workflow

Generate hierarchical CLAUDE.md and README.md documentation structure with directed context loading for trusted-ai-development-workbench.

Purpose

This workflow analyzes your repository structure and creates:

• README.md files for human-readable documentation
• CLAUDE.md files with YAML front matter for directed context loading

Each file is tailored to the directory's actual contents, not generic templates.

Prerequisites

1. Repository initialized with trustable-ai init
2. Claude Code running in project root directory

Workflow Steps

Step 1: Analyze Repository Structure

Use Glob and Read tools to analyze the project:

from pathlib import Path
import os

# Project root
root = Path.cwd()

# Directories to skip
skip_dirs = {
    'node_modules', 'venv', '.venv', 'env', '.env',
    '__pycache__', '.git', '.svn', '.hg',
    'dist', 'build', 'out', 'target', 'bin', 'obj',
    '.idea', '.vscode', '.vs',
    'coverage', '.coverage', 'htmlcov',
    '.pytest_cache', '.mypy_cache', '.ruff_cache',
}

# Find significant directories (have source files)
def is_significant(directory):
    """Check if directory has source code files."""
    code_extensions = {'.py', '.js', '.ts', '.tsx', '.go', '.rs', '.java', '.cpp', '.c', '.rb'}
    files = list(directory.glob('*'))
    code_files = [f for f in files if f.is_file() and f.suffix in code_extensions]
    return len(code_files) >= 2  # At least 2 source files

def analyze_directory(dir_path):
    """Analyze a directory's contents."""
    files = []
    subdirs = []

    for item in dir_path.iterdir():
        if item.name.startswith('.') and item.name != '.claude':
            continue
        if item.name in skip_dirs:
            continue

        if item.is_dir():
            subdirs.append(item.name)
        elif item.is_file():
            files.append({
                'name': item.name,
                'extension': item.suffix,
                'size': item.stat().st_size
            })

    # Detect directory type
    dir_type = 'module'
    dir_name = dir_path.name.lower()

    type_patterns = {
        'src': 'source', 'lib': 'source', 'app': 'source', 'pkg': 'source',
        'tests': 'tests', 'test': 'tests', 'spec': 'tests', '__tests__': 'tests',
        'docs': 'documentation', 'documentation': 'documentation',
        'api': 'api', 'apis': 'api',
        'core': 'core',
        'config': 'configuration', 'configs': 'configuration',
        'scripts': 'scripts', 'bin': 'scripts',
        '.claude': 'claude_config',
    }

    dir_type = type_patterns.get(dir_name, 'module')

    # Count file types
    py_files = len([f for f in files if f['extension'] == '.py'])
    js_files = len([f for f in files if f['extension'] in ['.js', '.ts', '.tsx']])
    go_files = len([f for f in files if f['extension'] == '.go'])

    primary_lang = 'mixed'
    if py_files > js_files and py_files > go_files:
        primary_lang = 'python'
    elif js_files > py_files and js_files > go_files:
        primary_lang = 'javascript'
    elif go_files > 0:
        primary_lang = 'go'

    return {
        'path': str(dir_path),
        'relative_path': str(dir_path.relative_to(root)),
        'type': dir_type,
        'files': files,
        'subdirs': subdirs,
        'primary_language': primary_lang,
        'has_readme': (dir_path / 'README.md').exists(),
        'has_claude_md': (dir_path / 'CLAUDE.md').exists(),
    }

# Scan repository (max depth 3)
directories_to_document = []

# Always include root
directories_to_document.append(analyze_directory(root))

# Scan subdirectories
for item in root.rglob('*'):
    if not item.is_dir():
        continue

    relative = item.relative_to(root)

    # Check depth
    if len(relative.parts) > 3:
        continue

    # Skip ignored directories
    if any(skip in relative.parts for skip in skip_dirs):
        continue

    # Check if significant
    if is_significant(item):
        directories_to_document.append(analyze_directory(item))

print(f"📁 Found {len(directories_to_document)} directories to document:")
for d in directories_to_document:
    status = "✓ has docs" if d['has_claude_md'] else "○ needs docs"
    print(f"  {d['relative_path']:<30} {status} | {len(d['files'])} files | {d['type']}")