Hugo Nijhuis
d980a0d0bc
Update documentation and apply new frontmatter capabilities: Documentation: - Add user-invocable, context, agent, hooks fields to writing-skills.md - Add disallowedTools, permissionMode, hooks fields to writing-agents.md - Add model, context, hooks, allowed-tools fields to writing-commands.md - Document skill hot-reload, built-in agents, background execution Skills: - Add user-invocable: false to gitea (CLI reference) - Add user-invocable: false to repo-conventions (standards reference) Commands: - Add context: fork to heavy exploration commands (improve, plan-issues, create-repo, update-claude-md) - Add missing argument-hint to roadmap, manifesto, improve Agents: - Add disallowedTools: [Edit, Write] to code-reviewer for safety Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
205 lines
4.7 KiB
Markdown
205 lines
4.7 KiB
Markdown
---
|
|
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
|