diff --git a/commands/create-repo.md b/commands/create-repo.md index f0c9d64..47478ac 100644 --- a/commands/create-repo.md +++ b/commands/create-repo.md @@ -7,6 +7,7 @@ argument-hint: @~/.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 # + ## 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): diff --git a/repos.md b/repos.md new file mode 100644 index 0000000..e9d386d --- /dev/null +++ b/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 diff --git a/skills/claude-md-writing/SKILL.md b/skills/claude-md-writing/SKILL.md new file mode 100644 index 0000000..db5ada6 --- /dev/null +++ b/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 +cd +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 diff --git a/skills/repo-conventions/SKILL.md b/skills/repo-conventions/SKILL.md index f7102e7..e1441d6 100644 --- a/skills/repo-conventions/SKILL.md +++ b/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]