architecture/old/skills/repo-conventions/SKILL.md

name, model, description, user-invocable

name	model	description	user-invocable
repo-conventions	haiku	Standard structure and conventions for Flowmade repositories. Use when creating new repos, reviewing repo structure, or setting up projects.	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
│   ├── skills/             # User-invocable and background skills
│   └── 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.

# 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 for detailed guidance.

# [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.

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