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>

commands/create-repo.md

@@ -7,6 +7,7 @@ argument-hint: <repo-name>
 
 @~/.claude/skills/repo-conventions/SKILL.md
 @~/.claude/skills/vision-management/SKILL.md
+@~/.claude/skills/claude-md-writing/SKILL.md
 @~/.claude/skills/gitea/SKILL.md
 
 Create a new repository with Flowmade's standard structure.
@@ -44,12 +45,19 @@ Create a new repository with Flowmade's standard structure.
    - Link to `../architecture/manifesto.md`
    - Fill in based on user's answers
 
-7. **Create CLAUDE.md**:
+7. **Create CLAUDE.md** (following claude-md-writing skill):
    ```markdown
    # <Repo Name>
 
    <One-line description from step 3>
 
+   ## 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
@@ -67,6 +75,10 @@ Create a new repository with Flowmade's standard structure.
    make test     # Run tests
    make lint     # Run linters
    ```
+
+   ## Architecture
+
+   TODO: Document key patterns and conventions once established.
    ```
 
 8. **Create Makefile** (basic template):

repos.md

@@ -0,0 +1,71 @@
+# Repository Map
+
+Central registry of all Flowmade repositories.
+
+## How to Use This
+
+Each repo's CLAUDE.md should reference this map for organization context. When working in any repo, Claude can check here to understand how it fits in the bigger picture.
+
+**Status markers:**
+- **Active** - Currently in use
+- **Splitting** - Being broken into smaller repos
+- **Planned** - Will be created (from split or new)
+
+## Repositories
+
+### Organization
+
+| Repo | Purpose | Status | Visibility |
+|------|---------|--------|------------|
+| architecture | Org source of truth: manifesto, Claude tooling, learnings | Active | Public |
+
+### Platform
+
+| Repo | Purpose | Status | Visibility |
+|------|---------|--------|------------|
+| arcadia | Monorepo containing platform code | Splitting | Private |
+| aether | Event sourcing runtime with bytecode VM | Planned (from Arcadia) | Private |
+| iris | WASM UI framework | Planned (from Arcadia) | Public |
+| eskit | ES primitives (aggregates, events, projections, NATS) | Planned (from Arcadia) | Public |
+| adl | Domain language compiler | Planned (from Arcadia) | Private |
+| studio | Visual process designer, EventStorming tools | Planned (from Arcadia) | Private |
+
+### Infrastructure
+
+| Repo | Purpose | Status | Visibility |
+|------|---------|--------|------------|
+| gitserver | K8s-native git server (proves ES/IRIS stack) | Planned | Public |
+
+## Relationships
+
+```
+arcadia (splitting into):
+├── eskit (standalone, foundational)
+├── iris (standalone)
+├── aether (imports eskit)
+├── adl (imports aether)
+└── studio (imports aether, iris, adl)
+
+gitserver (will use):
+├── eskit (event sourcing)
+└── iris (UI)
+```
+
+## Open Source Strategy
+
+See [repo-conventions skill](skills/repo-conventions/SKILL.md) for classification criteria.
+
+**Open source** (public):
+- Generic libraries that benefit from community (eskit, iris)
+- Infrastructure tooling that builds awareness (gitserver)
+- Organization practices and tooling (architecture)
+
+**Proprietary** (private):
+- Core platform IP (aether VM, adl compiler)
+- Product features (studio)
+
+## Related
+
+- [Manifesto](manifesto.md) - Organization identity and beliefs
+- [Issue #53](https://git.flowmade.one/flowmade-one/architecture/issues/53) - Git server proposal
+- [Issue #54](https://git.flowmade.one/flowmade-one/architecture/issues/54) - Arcadia split planning

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]