---
name: repo-conventions
description: Standard structure and conventions for Flowmade repositories. Use when creating new repos, reviewing repo structure, or setting up projects.
user-invocable: false
---

# Repository Conventions

Standard structure and conventions for Flowmade repositories.

## Repository Layout

All product repos should follow this structure relative to the architecture repo:

```
org/
├── architecture/           # Organizational source of truth
│   ├── manifesto.md        # Organization identity and beliefs
│   ├── commands/           # Claude Code workflows
│   ├── skills/             # Knowledge modules
│   └── agents/             # Subtask handlers
├── product-a/              # Product repository
│   ├── vision.md           # Product vision (extends manifesto)
│   ├── CLAUDE.md           # AI assistant instructions
│   ├── .gitea/workflows/   # CI/CD pipelines
│   └── ...
└── product-b/
    └── ...
```

## Required Files

### vision.md

Every product repo needs a vision that extends the organization manifesto.

```markdown
# Vision

This product vision builds on the [organization manifesto](../architecture/manifesto.md).

## Who This Product Serves

### [Persona Name]

[Product-specific description]

*Extends: [Org persona] (from manifesto)*

## What They're Trying to Achieve

| Product Job | Enables Org Job |
|-------------|-----------------|
| "[Product job]" | "[Org job from manifesto]" |

## The Problem

[Pain points this product addresses]

## The Solution

[How this product solves those problems]

## Product Principles

### [Principle Name]

[Description]

*Extends: "[Org principle]"*

## Non-Goals

- **[Non-goal].** [Explanation]
```

### CLAUDE.md

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]

## Project Structure

[Key directories and their purposes]

## Development

[How to build, test, run]

## Architecture

[Key architectural decisions and patterns]
```

### .gitea/workflows/ci.yaml

Standard CI pipeline. Adapt based on language/framework.

```yaml
name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: make build
      - name: Test
        run: make test
      - name: Lint
        run: make lint
```

## Naming Conventions

### Repository Names

- Lowercase with hyphens: `product-name`, `service-name`
- Descriptive but concise
- No prefixes like `flowmade-` (the org already provides context)

### Branch Names

- `main` - default branch, always deployable
- `issue-<number>-<short-description>` - feature branches
- No `develop` or `staging` branches - use main + feature flags

### Commit Messages

- Imperative mood: "Add feature" not "Added feature"
- First line: summary (50 chars)
- Body: explain why, not what (the diff shows what)
- Reference issues: "Fixes #42" or "Closes #42"

## Open vs Proprietary

Decisions about what to open-source are guided by the manifesto:

| Type | Open Source? | Reason |
|------|--------------|--------|
| Infrastructure tooling | Yes | Builds community, low competitive risk |
| Generic libraries | Yes | Ecosystem benefits, adoption |
| Core platform IP | No | Differentiator, revenue source |
| Domain-specific features | No | Product value |

When uncertain, default to proprietary. Opening later is easier than closing.

## CI/CD Conventions

### Runners

- Use self-hosted ARM64 runners where possible (resource efficiency)
- KEDA-scaled runners for burst capacity
- Cache dependencies aggressively

### Deployments

- Main branch auto-deploys to staging
- Production requires manual approval or tag
- Use GitOps (ArgoCD) for Kubernetes deployments

## Dependencies

### Go Projects

- Use Go modules
- Vendor dependencies for reproducibility
- Pin major versions, allow minor updates

### General

- Prefer fewer, well-maintained dependencies
- Audit transitive dependencies
- Update regularly, don't let them rot

## Documentation

Following the manifesto principle "Encode, don't document":

- CLAUDE.md: How to work with this repo (for AI and humans)
- vision.md: Why this product exists
- Code comments: Only for non-obvious "why"
- No separate docs folder unless user-facing documentation