Add CLAUDE.md guidance and repository map

- Create claude-md-writing skill with best practices for CLAUDE.md files
- Create repos.md registry of all repos with status (Active/Planned/Splitting)
- Update /create-repo to include organization context section
- Update repo-conventions to reference new skill

Each repo's CLAUDE.md now links to manifesto, repos.md, and vision.md
so Claude always understands the bigger picture.

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

skills/claude-md-writing/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: claude-md-writing
+description: Write effective CLAUDE.md files that give AI assistants the context they need. Use when creating new repos, improving existing CLAUDE.md files, or setting up projects.
+---
+
+# Writing Effective CLAUDE.md Files
+
+CLAUDE.md is the project's context file for AI assistants. A good CLAUDE.md means Claude understands your project immediately without needing to explore.
+
+## Purpose
+
+CLAUDE.md answers: "What does Claude need to know to work effectively in this repo?"
+
+- **Not a README** - README is for humans discovering the project
+- **Not documentation** - Docs explain how to use the product
+- **Context for AI** - What Claude needs to make good decisions
+
+## Required Sections
+
+### 1. One-Line Description
+
+Start with what this repo is in one sentence.
+
+```markdown
+# Project Name
+
+Brief description of what this project does.
+```
+
+### 2. Organization Context
+
+Link to the bigger picture so Claude understands where this fits.
+
+```markdown
+## 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
+```
+
+### 3. Setup
+
+How to get the project running locally.
+
+```markdown
+## Setup
+
+\`\`\`bash
+# Clone and install
+git clone <url>
+cd <project>
+make install  # or npm install, etc.
+\`\`\`
+```
+
+### 4. Project Structure
+
+Key directories and what they contain. Focus on what's non-obvious.
+
+```markdown
+## Project Structure
+
+\`\`\`
+project/
+├── cmd/           # Entry points
+├── pkg/           # Shared packages
+│   ├── domain/    # Business logic
+│   └── infra/     # Infrastructure adapters
+├── internal/      # Private packages
+└── api/           # API definitions
+\`\`\`
+```
+
+### 5. Development Commands
+
+The commands Claude will need to build, test, and run.
+
+```markdown
+## Development
+
+\`\`\`bash
+make build    # Build the project
+make test     # Run tests
+make lint     # Run linters
+make run      # Run locally
+\`\`\`
+```
+
+### 6. Architecture Decisions
+
+Key patterns and conventions specific to this repo.
+
+```markdown
+## Architecture
+
+### Patterns Used
+- Event sourcing for state management
+- CQRS for read/write separation
+- Hexagonal architecture
+
+### Conventions
+- All commands go through the command bus
+- Events are immutable value objects
+- Projections rebuild from events
+```
+
+## What Makes a Good CLAUDE.md
+
+### Do Include
+
+- **Enough context to skip exploration** - Claude shouldn't need to grep around
+- **Key architectural patterns** - How the code is organized and why
+- **Non-obvious conventions** - Things that aren't standard
+- **Important dependencies** - External services, APIs, databases
+- **Common tasks** - How to do things Claude will be asked to do
+
+### Don't Include
+
+- **Duplicated manifesto content** - Link to it instead
+- **Duplicated vision content** - Link to vision.md
+- **API documentation** - That belongs elsewhere
+- **User guides** - CLAUDE.md is for the AI, not end users
+- **Obvious things** - Don't explain what `go build` does
+
+## Template
+
+```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
+
+\`\`\`bash
+# TODO: Add setup instructions
+\`\`\`
+
+## Project Structure
+
+\`\`\`
+project/
+├── ...
+\`\`\`
+
+## Development
+
+\`\`\`bash
+make build    # Build the project
+make test     # Run tests
+make lint     # Run linters
+\`\`\`
+
+## Architecture
+
+### Patterns
+- [List key patterns]
+
+### Conventions
+- [List important conventions]
+
+### Key Components
+- [Describe main components and their responsibilities]
+```
+
+## Examples
+
+### Good: Enough Context
+
+```markdown
+## Architecture
+
+This service uses event sourcing. State is rebuilt from events, not stored directly.
+
+### Key Types
+- `Aggregate` - Domain object that emits events
+- `Event` - Immutable fact that something happened
+- `Projection` - Read model built from events
+
+### Adding a New Aggregate
+1. Create type in `pkg/domain/`
+2. Implement `HandleCommand()` and `ApplyEvent()`
+3. Register in `cmd/main.go`
+```
+
+Claude can now work with aggregates without exploring the codebase.
+
+### Bad: Too Vague
+
+```markdown
+## Architecture
+
+Uses standard Go patterns. See the code for details.
+```
+
+Claude has to explore to understand anything.
+
+## Maintenance
+
+Update CLAUDE.md when:
+- Adding new architectural patterns
+- Changing project structure
+- Adding important dependencies
+- Discovering conventions that aren't documented
+
+Don't update for:
+- Every code change
+- Bug fixes
+- Minor refactors

skills/repo-conventions/SKILL.md

@@ -75,13 +75,20 @@ This product vision builds on the [organization manifesto](../architecture/manif
 
 ### CLAUDE.md
 
-Project-specific instructions for Claude Code.
+Project-specific context for AI assistants. See [claude-md-writing skill](../claude-md-writing/SKILL.md) for detailed guidance.
 
 ```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
 
 [How to get the project running locally]