docs-workflow

Overview

• 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

/docs

/docs-init

/docs-update

/docs-claude

Quick Start

New Project

# In a new project directory
/docs-init

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 overview and tech stack
• Development setup commands
• Architecture overview
• Key file locations
• Common tasks and workflows

• 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

• Project name and description
• Installation/setup instructions
• Usage examples
• Configuration
• Contributing guidelines

docs/ Directory (Optional)

• docs/ARCHITECTURE.md

  - System architecture

• docs/API.md

  - API documentation

• docs/DATABASE.md

  - Database schema

Smart Maintenance

/docs-claude Features

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

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

wrangler.jsonc

wrangler.toml

next.config.js

next.config.ts

• 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

/docs-init

/docs-claude

/docs-update

/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/

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

• {{PROJECT_NAME}}

  - Detected from package.json or folder name

• {{DATE}}

  - Current date

• {{TECH_STACK}}

  - Detected technologies