Add repo-conventions skill and /create-repo command
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:
195
commands/create-repo.md
Normal file
195
commands/create-repo.md
Normal 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
196
skills/repo-conventions/SKILL.md
Normal 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
|
||||
Reference in New Issue
Block a user