project-docs

name	project-docs
description	Generate comprehensive, professional project documentation structures including README, ARCHITECTURE, USER_GUIDE, DEVELOPER_GUIDE, and CONTRIBUTING files. Use when the user requests project documentation creation, asks to "document a project", needs standard documentation files, or wants to set up docs for a new repository. Adapts to Python/Go projects and OpenSource/internal contexts.
license	MIT
compatibility	opencode
metadata	{"version":"1.0.0"}

Project Documentation Generator

Generate complete, professional documentation structures for software projects. Automatically adapts content and structure based on project language (Python/Go), context (OpenSource/internal), and existing files.

Core Documentation Files

Always generate these five core files:

1. README.md - Project overview, quick start, badges
2. ARCHITECTURE.md - System design, components, data flow
3. USER_GUIDE.md - Usage examples, configuration, troubleshooting
4. DEVELOPER_GUIDE.md - Development setup, testing, contribution workflow
5. CONTRIBUTING.md - Contribution guidelines, code standards, PR process

Workflow

1. Context Detection

Before generating docs, detect:

• Language: Scan for go.mod, pyproject.toml, requirements.txt, setup.py
• Project type: Check for Dockerfile, terraform/, k8s/, AI/ML indicators
• Existing docs: Identify what already exists to avoid duplication
• License: Detect from LICENSE file or ask user
• Context: Determine if OpenSource or internal based on repo structure

2. Ask Clarifying Questions

Ask user ONE question at a time to fill gaps:

• "What's the primary purpose of this project in one sentence?"
• "Who's the main audience? (developers, ops, end-users, all)"
• "Is this OpenSource or internal? (affects badges, contact info)"
• "Any company-specific tooling to mention? (Jira, Slack channels, etc.)"

3. Content Adaptation

Read references/templates.md to select appropriate template variants based on detected context.

Language-specific elements:

• Python: Package managers (uv, pip, poetry), testing (pytest), linting (ruff, mypy)
• Go: Build commands, testing, golangci-lint, module structure

Context-specific elements:

• OpenSource: Badges, CODE_OF_CONDUCT, security policy, community guidelines
• Internal: Slack channels, internal tools, compliance requirements, team contacts

Project type adjustments:

• AI Agents: MCP architecture, prompt patterns, example interactions
• Infrastructure: Terraform/K8s setup, deployment procedures, DR plans
• Microservices: API schemas, service mesh, health checks
• CLI Tools: Installation methods, command examples, flags

4. File Generation

Generate files in this order:

1. README.md first (most visible, sets tone)
2. ARCHITECTURE.md (technical foundation)
3. DEVELOPER_GUIDE.md (setup and contribution)
4. USER_GUIDE.md (end-user focused)
5. CONTRIBUTING.md (community guidelines)

Each file must:

• Use clear headers and structure from templates
• Include concrete, runnable examples
• Reference other docs when needed (avoid duplication)
• Match project's actual structure and commands

5. Template Application

For each file:

1. Select template variant from references/templates.md
2. Fill in project-specific details
3. Add context-appropriate sections
4. Ensure consistency across all files

6. Quality Checks

Before finalizing, verify:

• All code examples are runnable and accurate
• Commands match detected language/tooling
• Cross-references between docs are correct
• No placeholder text remains
• Tone is consistent (technical/friendly/formal based on context)

7. Output

Place all files in docs/ and use present_files to share with user.

Resources

references/templates.md

Contains complete documentation templates for all five core files with variants for:

• Python vs Go projects
• OpenSource vs internal contexts
• Different project types (agent, service, CLI, infra)
• Different complexity levels

Claude should read this file to select appropriate templates before generating docs.

Special Considerations

For AI Agent projects:

• Explain MCP server architecture
• Document tool integrations
• Show example prompts and interactions
• Include LLM configuration details

For Infrastructure/DevOps:

• Environment requirements (cloud providers, versions)
• Deployment runbooks
• Monitoring setup
• Disaster recovery procedures

For Microservices:

• API endpoint documentation
• Service dependency diagrams
• Inter-service communication patterns
• Health check and metrics endpoints

Quality Standards

Every documentation file must:

• Have table of contents for files >200 lines
• Use proper code fences with language tags
• Include "Quick Start" section at top
• Show real, tested examples
• Explain "why" decisions were made
• Use consistent terminology throughout

Avoid

• Generic placeholder text like "TODO" or "Coming soon"
• Outdated technology references
• Overly complex explanations without examples
• Duplicating content across multiple files
• Missing concrete code examples