From 1f1d9961fc4343635765d7928926f9290d286e14 Mon Sep 17 00:00:00 2001
From: Hugo Nijhuis <hugo@flowmade.one>
Date: Thu, 8 Jan 2026 10:26:10 +0100
Subject: [PATCH] Add /update-claude-md command
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Updates or creates CLAUDE.md with:
- Organization context section (links to manifesto, repos.md, vision)
- Current project structure from filesystem scan
- Architecture patterns inferred or asked

Preserves existing custom content, shows diff before writing.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 commands/update-claude-md.md | 165 +++++++++++++++++++++++++++++++++++
 1 file changed, 165 insertions(+)
 create mode 100644 commands/update-claude-md.md

diff --git a/commands/update-claude-md.md b/commands/update-claude-md.md
new file mode 100644
index 0000000..fee645f
--- /dev/null
+++ b/commands/update-claude-md.md
@@ -0,0 +1,165 @@
+---
+description: Update or create CLAUDE.md with current project context. Explores the project and ensures organization context is present.
+argument-hint:
+---
+
+# 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