blueprints-organization

# Organizing Technical Blueprints

## Directory Structure

```
blueprints/
├── README.md              # Index and overview
├── {system-name}.md       # One file per system
├── {feature-name}.md      # One file per feature
└── {integration-name}.md  # One file per integration
```

### Flat vs Nested

**Prefer flat structure** for most projects:

- Easier to navigate
- Simpler cross-references
- Less organizational overhead

**Use subdirectories** only for very large projects:

```
blueprints/
├── README.md
├── core/
│   ├── README.md
│   └── *.md
├── features/
│   └── *.md
└── integrations/
    └── *.md
```

## Naming Conventions

### File Names

- Use kebab-case: `user-authentication.md`
- Match system/feature names in code
- Be specific: `api-rate-limiting.md` not `api.md`
- Avoid generic names: `utils.md`, `helpers.md`

### Good Names

- `mcp-server.md` - Specific system
- `settings-merge.md` - Specific feature
- `github-integration.md` - Specific integration

### Bad Names

- `overview.md` - Too generic (use README.md)
- `misc.md` - Catch-all is a smell
- `new-feature.md` - Not descriptive

## The blueprints/README.md Index

Every blueprints/ directory needs an index:

```markdown
# Technical Blueprints

Implementation documentation for {Project Name}.

## Overview

Brief description of what this project does and how blueprints are organized.

## Systems

Core systems and their documentation:

### Core

- [Settings Management](./settings-management.md) - How configuration is loaded and merged
- [Plugin System](./plugin-system.md) - Plugin discovery and loading

### Features

- [MCP Server](./mcp-server.md) - Model Context Protocol implementation
- [Hook Dispatch](./hook-dispatch.md) - How hooks are executed

### Integrations

- [GitHub Integration](./github-integration.md) - GitHub API integration

## Contributing

When adding new blueprints:
1. Check for existing related documentation
2. Use consistent naming and structure
3. Update this index
```

## Avoiding D