diff --git a/commands/create-repo.md b/commands/create-repo.md new file mode 100644 index 0000000..f0c9d64 --- /dev/null +++ b/commands/create-repo.md @@ -0,0 +1,195 @@ +--- +description: Create a new repository with standard structure. Scaffolds vision.md, CLAUDE.md, and CI configuration. +argument-hint: +--- + +# 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/` + +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 --private/--public --description "" + ``` + +5. **Clone and set up structure**: + ```bash + # Clone the new repo + git clone ssh://git@git.flowmade.one/flowmade-one/.git + cd + ``` + +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 + # + + + + ## 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 " + + git push -u origin main + ``` + +12. **Report success**: + ``` + Repository created: https://git.flowmade.one/flowmade-one/ + + Next steps: + 1. cd ../ + 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 diff --git a/skills/repo-conventions/SKILL.md b/skills/repo-conventions/SKILL.md new file mode 100644 index 0000000..f7102e7 --- /dev/null +++ b/skills/repo-conventions/SKILL.md @@ -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--` - 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