docs-workflow

# docs-workflow

**Last Updated**: 2026-01-11
**Purpose**: Manage project documentation throughout its lifecycle

---

## Overview

This skill helps you:
- **Initialize** documentation for new projects (CLAUDE.md, README.md, docs/)
- **Maintain** CLAUDE.md to match actual project state
- **Audit** all docs for staleness, broken links, outdated versions

## Commands

| Command | Purpose |
|---------|---------|
| /docs | Main entry - shows available subcommands |
| /docs-init | Create CLAUDE.md + README.md + docs/ structure |
| /docs-update | Audit and maintain all documentation |
| /docs-claude | Smart CLAUDE.md maintenance only |

## Quick Start

### New Project

# In a new project directory
/docs-init

This will:
1. Detect project type (Cloudflare Workers, Next.js, generic)
2. Create CLAUDE.md from appropriate template
3. Create README.md if missing
4. Optionally scaffold docs/ directory

### Existing Project

# Audit all documentation
/docs-update

# Or just maintain CLAUDE.md
/docs-claude

---

## What Gets Created

### CLAUDE.md

Project-specific context for Claude Code, including:
- Project overview and tech stack
- Development setup commands
- Architecture overview
- Key file locations
- Common tasks and workflows

**Templates available:**
- CLAUDE-cloudflare.md - Cloudflare Workers + Vite + D1 projects
- CLAUDE-nextjs.md - Next.js App Router projects
- CLAUDE-generic.md - Any other project type

### README.md

Standard README with:
- Project name and description
- Installation/setup instructions
- Usage examples
- Configuration
- Contributing guidelines

### docs/ Directory (Optional)

Scaffolded documentation structure:
- docs/ARCHITECTURE.md - System architecture
- docs/API.md - API documentation
- docs/DATABASE.md - Database schema

---

## Smart Maintenance

### /docs-claude Features

The CLAUDE.md maintenance command checks:

1. **Tech Stack Match**
- Does CLAUDE.md list technologies that match package.json?
- Are versions mentioned still accurate?

2. **Referenced Files**
- Do paths mentioned in CLAUDE.md still exist?
- Are there new important files not mentioned?

3. **Section Freshness**
- Is "Last Updated" date recent?
- Are there outdated patterns or commands?

4. **Critical Rules**
- For detected tech stack, are important rules present?
- E.g., Cloudflare project should mention wrangler.jsonc patterns

### /docs-update Features

Full documentation audit including:

1. **Date Freshness**
- Compare doc dates against git history
- Flag docs not updated in >30 days

2. **Version References**
- Check npm package versions mentioned
- Suggest updates for outdated versions

3. **Broken Links**
- Verify internal markdown links
- Check that referenced files exist

4. **Redundancy**
- Identify duplicate content across files
- Suggest consolidation

5. **Orphaned Files**
- Find docs not referenced anywhere
- Suggest archiving or deletion

---

## Project Type Detection

The skill auto-detects project type by looking for:

| Indicator | Project Type |
|-----------|-------------|
| wrangler.jsonc or wrangler.toml | Cloudflare Workers |
| next.config.js or next.config.ts | Next.js |
| Neither | Generic |

Additional indicators influence template content:
- package.json dependencies (React, Vite, etc.)
- Database config files (drizzle.config.ts, prisma/schema.prisma)
- Auth config (clerk, better-auth)

---

## Integration with Other Skills

- **project-workflow**: Use /docs-init after /plan-project to add documentation
- **project-planning**: Generated IMPLEMENTATION_PHASES.md referenced in CLAUDE.md
- **cloudflare-worker-base**: Cloudflare template includes Workers-specific patterns

---

## Best Practices

### When to Run Each Command

| Situation | Command |
|-----------|---------|
| New project | /docs-init |
| After major changes | /docs-claude |
| Before release | /docs-update |
| Monthly maintenance | /docs-update |

### CLAUDE.md Guidelines

1. **Keep it current** - Update "Last Updated" when making changes
2. **Focus on project-specific** - Don't duplicate generic tech docs
3. **Include common tasks** - Commands you run frequently
4. **Reference, don't duplicate** - Link to docs/ for detailed content

---

## Templates

Templates are located in templates/ within this skill:

templates/
├── CLAUDE-cloudflare.md    # Cloudflare Workers projects
├── CLAUDE-nextjs.md        # Next.js projects
├── CLAUDE-generic.md       # Generic projects
└── README-template.md      # Standard README

Templates use placeholders:
- {{PROJECT_NAME}} - Detected from package.json or folder name
- {{DATE}} - Current date
- {{TECH_STACK}} - Detected technologies


---

# CLAUDE.md Documentation Patterns

Common mistakes and best practices for CLAUDE.md files.

## Corrections

| If Claude suggests... | Use instead... |
|----------------------|----------------|
| Copying full framework docs into CLAUDE.md | Link to official docs, only include project-specific patterns |
| Generic tech tutorials | Project-specific workflows and commands |
| Outdated "Last Updated" date | Current date when making changes |
| Hardcoded paths that may change | Use relative paths or explain file discovery patterns |

## Structure Best Practices

### Required Sections

Every CLAUDE.md should have:

1. **Project Overview** - What it is, tech stack
2. **Quick Start** - Essential commands to get running
3. **Project Structure** - Key directories and their purposes
4. **Common Tasks** - Frequent operations with commands

### Optional but Recommended

- **Environment Variables** - Required vars and where to set them
- **Key Files** - Important files and their purposes
- **Troubleshooting** - Common issues and solutions

## Anti-Patterns

### Don't Include

- Full API references (link to docs instead)
- Generic programming tutorials
- Information that changes frequently without automated updates
- Secrets or credentials
- User-specific configuration

### Keep Focused

CLAUDE.md is for project-specific context:
- ✅ "Run pnpm db:push to sync schema"
- ❌ "Drizzle ORM is a TypeScript ORM that..."

## Maintenance

### Update Triggers

Update CLAUDE.md when:
- Adding new major dependencies
- Changing project structure
- Adding new workflows/commands
- Fixing common developer issues

### Don't Update For

- Minor dependency patches
- Small code changes
- Bug fixes (unless pattern-breaking)

## Size Guidelines

| Project Size | CLAUDE.md Lines | Notes |
|--------------|-----------------|-------|
| Small/Simple | 100-200 | Just essentials |
| Medium | 200-500 | Include troubleshooting |
| Large/Complex | 500-1000 | Multiple workflows, detailed structure |
| Enterprise | 1000+ | Consider splitting into docs/ |

**Note**: Size isn't the metric - clarity and usefulness are. A well-organized 800-line CLAUDE.md is better than a cramped 200-line one.