flowmade-one/architecture
3
0
Fork 0
Code Issues 15 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Add repo-conventions skill and /create-repo command

Browse Source 
Skill documents standard repo structure, naming conventions,
open vs proprietary guidance, and CI/CD patterns.

Command scaffolds new repos with vision.md, CLAUDE.md, Makefile,
CI workflow, and .gitignore - all linked to the architecture repo.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Hugo Nijhuis
2026-01-07 23:58:16 +01:00
parent 305e4b8927
commit 0e1a65f0e3
2 changed files with 391 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

195
commands/create-repo.md Normal file
View File

@@ -0,0 +1,195 @@
---
description: Create a new repository with standard structure. Scaffolds vision.md, CLAUDE.md, and CI configuration.
argument-hint: <repo-name>
---
# Create Repository
@~/.claude/skills/repo-conventions/SKILL.md
@~/.claude/skills/vision-management/SKILL.md
@~/.claude/skills/gitea/SKILL.md
Create a new repository with Flowmade's standard structure.
## Process
1. **Get repository name**: Use `$1` or ask the user
- Validate: lowercase, hyphens only, no `flowmade-` prefix
- Check it doesn't already exist: `tea repos flowmade-one/<name>`
2. **Determine visibility**:
- Ask: "Should this repo be public (open source) or private (proprietary)?"
- Refer to repo-conventions skill for guidance on open vs proprietary
3. **Gather vision context**:
- Read the organization manifesto: `../architecture/manifesto.md`
- Ask: "What does this product do? (one sentence)"
- Ask: "Which manifesto personas does it serve?"
- Ask: "What problem does it solve?"
4. **Create the repository on Gitea**:
```bash
tea repos create --name <repo-name> --private/--public --description "<description>"
```
5. **Clone and set up structure**:
```bash
# Clone the new repo
git clone ssh://git@git.flowmade.one/flowmade-one/<repo-name>.git
cd <repo-name>
```
6. **Create vision.md**:
- Use the vision structure template from vision-management skill
- Link to `../architecture/manifesto.md`
- Fill in based on user's answers
7. **Create CLAUDE.md**:
```markdown
# <Repo Name>
<One-line description from step 3>
## Setup
```bash
# TODO: Add setup instructions
```
## Project Structure
TODO: Document key directories once code exists.
## Development
```bash
make build # Build the project
make test # Run tests
make lint # Run linters
```
```
8. **Create Makefile** (basic template):
```makefile
.PHONY: build test lint
build:
@echo "TODO: Add build command"
test:
@echo "TODO: Add test command"
lint:
@echo "TODO: Add lint command"
```
9. **Create CI workflow**:
```bash
mkdir -p .gitea/workflows
```
Create `.gitea/workflows/ci.yaml`:
```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
```
10. **Create .gitignore** (basic, expand based on language):
```
# IDE
.idea/
.vscode/
*.swp
# OS
.DS_Store
Thumbs.db
# Build artifacts
/dist/
/build/
/bin/
# Dependencies (language-specific, add as needed)
/node_modules/
/vendor/
```
11. **Initial commit and push**:
```bash
git add .
git commit -m "Initial repository structure
- vision.md linking to organization manifesto
- CLAUDE.md with project instructions
- CI workflow template
- Basic Makefile
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>"
git push -u origin main
```
12. **Report success**:
```
Repository created: https://git.flowmade.one/flowmade-one/<repo-name>
Next steps:
1. cd ../<repo-name>
2. Update CLAUDE.md with actual setup instructions
3. Update Makefile with real build commands
4. Start building!
```
## Output Example
```
## Creating Repository: my-service
Visibility: Private (proprietary)
Description: Internal service for processing events
### Files Created
- vision.md (linked to manifesto)
- CLAUDE.md (project instructions)
- Makefile (build template)
- .gitea/workflows/ci.yaml (CI pipeline)
- .gitignore (standard ignores)
### Repository URL
https://git.flowmade.one/flowmade-one/my-service
### Next Steps
1. cd ../my-service
2. Update CLAUDE.md with setup instructions
3. Update Makefile with build commands
4. Start coding!
```
## Guidelines
- Always link vision.md to the sibling architecture repo
- Keep initial structure minimal - add complexity as needed
- CI should pass on empty repo (use placeholder commands)
- Default to private unless explicitly open-sourcing

196
skills/repo-conventions/SKILL.md Normal file
View File

@@ -0,0 +1,196 @@
---
name: repo-conventions
description: Standard structure and conventions for Flowmade repositories. Use when creating new repos, reviewing repo structure, or setting up projects.
---
# 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 instructions for Claude Code.
```markdown
# [Project Name]
[One-line description]
## 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