---
name: update-claude-md
description: >
  Update or create CLAUDE.md with current project context. Explores the project
  and ensures organization context is present. Use when updating project docs,
  adding CLAUDE.md, or when user says /update-claude-md.
model: haiku
context: fork
user-invocable: true
---

# Update CLAUDE.md

@~/.claude/skills/claude-md-writing/SKILL.md
@~/.claude/skills/repo-conventions/SKILL.md

Update or create CLAUDE.md for the current repository with proper organization context and current project state.

## Process

1. **Check for existing CLAUDE.md**: Look for `CLAUDE.md` in repo root

2. **If CLAUDE.md exists**:
   - Read current content
   - Identify which sections exist
   - Note any custom content to preserve

3. **Explore the project**:
   - Scan directory structure
   - Identify language/framework (go.mod, package.json, Cargo.toml, etc.)
   - Find key patterns (look for common directories, config files)
   - Check for Makefile or build scripts

4. **Check organization context**:
   - Does it have the "Organization Context" section?
   - Does it link to `../architecture/manifesto.md`?
   - Does it link to `../architecture/repos.md`?
   - Does it link to `./vision.md`?

5. **Gather missing information**:
   - If no one-line description: Ask user
   - If no architecture section: Infer from code or ask user

6. **Update CLAUDE.md**:

   **Always ensure these sections exist:**

   ```markdown
   # [Project Name]

   [One-line description]

   ## Organization Context

   This repo is part of Flowmade. See:
   - [Organization manifesto](../architecture/manifesto.md) - who we are, what we believe
   - [Repository map](../architecture/repos.md) - how this fits in the bigger picture
   - [Vision](./vision.md) - what this specific product does

   ## Setup

   [From existing or ask user]

   ## Project Structure

   [Generate from actual directory scan]

   ## Development

   [From Makefile or existing]

   ## Architecture

   [From existing or infer from code patterns]
   ```

7. **Preserve custom content**:
   - Keep any additional sections the user added
   - Don't remove information, only add/update
   - If unsure, ask before removing

8. **Show diff and confirm**:
   - Show what will change
   - Ask user to confirm before writing

## Section-Specific Guidance

### Project Structure

Generate from actual directory scan:
```bash
# Scan top-level and key subdirectories
ls -la
ls pkg/ cmd/ internal/ src/ (as applicable)
```

Format as tree showing purpose:
```markdown
## Project Structure

\`\`\`
project/
├── cmd/           # Entry points
├── pkg/           # Shared packages
│   ├── domain/    # Business logic
│   └── infra/     # Infrastructure
└── internal/      # Private packages
\`\`\`
```

### Development Commands

Extract from Makefile if present:
```bash
grep -E "^[a-zA-Z_-]+:" Makefile | head -10
```

Or from package.json scripts, Cargo.toml, etc.

### Architecture

Look for patterns:
- Event sourcing: Check for aggregates, events, projections
- Clean architecture: Check for domain, application, infrastructure layers
- API style: REST, gRPC, GraphQL

If unsure, ask: "What are the key architectural patterns in this project?"

## Output Example

```
## Updating CLAUDE.md

### Current State
- Has description: ✓
- Has org context: ✗ (will add)
- Has setup: ✓
- Has structure: Outdated (will update)
- Has development: ✓
- Has architecture: ✗ (will add)

### Changes

+ Adding Organization Context section
~ Updating Project Structure (new directories found)
+ Adding Architecture section

### New Project Structure

\`\`\`
arcadia/
├── cmd/
├── pkg/
│   ├── aether/      # Event sourcing runtime
│   ├── iris/        # WASM UI framework
│   ├── adl/         # Domain language
│   └── ...
└── internal/
\`\`\`

Proceed with update? [y/n]
```

## Guidelines

- Always add Organization Context if missing
- Preserve existing custom sections
- Update Project Structure from actual filesystem
- Don't guess at Architecture - ask if unclear
- Show changes before writing
- Reference claude-md-writing skill for best practices