My personal starter template for new private projects. Clone it, rename placeholders, and start building — the full agent-driven workflow, CI pipelines, and Kubernetes deploy chain come ready out of the box.
Takes you from product design to a production-ready full-stack app, all driven by specialized AI agents. Covers the entire lifecycle: product vision, UI design, feature specs, architecture, implementation, QA, and release.
Stack: Python FastAPI + SQLModel backend · React 19 + TypeScript + Tailwind frontend · GitHub Copilot agents · GitHub Actions CI → ghcr.io → ArgoCD (homelab)
- Clone this repo for a new project and replace placeholders (see Customization).
- Design — optionally use Design OS agents to plan the product and prototype UI screens.
- Implement — use specialized agents (Requirements Engineer → Solution Architect → Backend/Frontend Developer → QA Engineer) to spec, architect, and build features.
- Release — tag services, CI builds container images, then update Kubernetes manifests in
~/code/homelabso ArgoCD deploys automatically.
Each project gets two independently versioned services (frontend, backend), each with its own GitHub Actions workflow, container image, and Kubernetes deployment.
make setup # Install deps (backend + frontend + design), create .env
make dev # Start PostgreSQL + backend + frontend
make dev-design # Start Design OS preview app- Frontend: http://localhost:5173
- Backend API: http://localhost:8000
- API Docs: http://localhost:8000/docs
- Design OS: http://localhost:5174
After cloning, replace these placeholders throughout the codebase:
| Placeholder | Replace With | Example |
|---|---|---|
{PROJECT_NAME} |
Your project name | "My Awesome App" |
{PREFIX} |
Feature ID prefix (3-5 chars) | "APP", "PROJ", "MY" |
starter-backend |
Your backend package name | "my-app-backend" |
starter-frontend |
Your frontend package name | "my-app-frontend" |
starter-db-dev |
Your Docker container name | "my-app-db-dev" |
backend/pyproject.toml— package namefrontend/package.json— package namefrontend/index.html— page titledocker-compose.yml— container nameMakefile— container name indb-shell- All
.github/files — project name and feature prefix
├── .github/
│ ├── copilot-instructions.md # Main Copilot config
│ ├── agents/ # 16 specialized agents
│ ├── instructions/ # Auto-applied coding rules
│ ├── skills/ # /help, /frontend-design, /product-hub, /release
│ └── workflows/ # CI: build & push container images on tag
│ ├── frontend.yml # triggers on frontend/v* tags
│ └── backend.yml # triggers on backend/v* tags
├── docs/
│ └── ARCHITECTURE.md # System architecture
├── design/ # Design OS app (standalone Vite on :5174)
│ ├── product/ # Product planning files
│ ├── export/ # Design export artifacts (generated)
│ └── src/ # Screen designs & preview app
├── backend/ # FastAPI backend
│ ├── app/ # Application code
│ ├── tests/ # Pytest tests
│ └── alembic/ # DB migrations
├── frontend/ # React frontend
│ ├── src/ # Application code
│ └── e2e/ # Playwright tests
├── Makefile # Dev commands
└── docker-compose.yml # PostgreSQL (dev)
This template uses a structured agent-driven workflow with two phases:
Design: Product Vision → Product Roadmap → Data Shape → Design System → Shell
→ per section: Shape Section → Sample Data → Screen → Screenshot
→ Clickdummy → Export
Use Design OS agents to plan your product, design UI screens, and export artifacts before writing code. Start with @Design: Product Vision.
Requirements Engineer → Solution Architect → Backend/Frontend Developer → QA Engineer
- New project? Switch to Requirements Engineer to create PRD and initial features (or use Design: Export output)
- New feature? Switch to Requirements Engineer to create a spec
- Ready to design? Switch to Solution Architect for tech design + plan
- Ready to build? Switch to Backend Developer or Frontend Developer
- Ready to test? Switch to QA Engineer
Use /help skill anytime to see project status and recommended next steps.
Services are independently versioned via git tags (<service>/v<semver>). The /release skill handles the full lifecycle:
- Changelog — collects commits since the last tag, appends to
CHANGELOG.md - Tagging — creates git tags that trigger GitHub Actions CI → builds multi-arch images → pushes to
ghcr.io - Deploy — updates Kubernetes manifests in
~/code/homelab→ ArgoCD syncs automatically
# Example: the /release skill handles all of this via Copilot chat
# "ship it" → full flow for all changed services
# "bump frontend" → changelog + tag for frontend only
# "deploy to preview" → update preview manifests in homelab
# "what's deployed?" → show status tableEach project gets two environments in homelab:
- Production —
apps/<project-name>/(stable tags likev1.2.3) - Preview —
apps/<project-name>-preview/(preview tags likev1.2.3-preview.1)
Preview → stable promotion retags the existing image instead of rebuilding.
| Command | Description |
|---|---|
make setup |
Install all dependencies, create .env |
make dev |
Start PostgreSQL + backend + frontend |
make dev-design |
Start Design OS preview app (5174) |
make dev-stop |
Stop PostgreSQL |
make kill |
Kill all dev processes |
make test-backend |
Run pytest |
make test-frontend |
Run Playwright E2E |
make db-migrate |
Run Alembic migrations |
make db-reset |
Reset database |
make clean |
Remove venv, node_modules, dist |
# Backend
cd backend && uv run pytest
cd backend && uv run pytest -k test_name
# Frontend E2E
cd frontend && npx playwright test
cd frontend && npx playwright test --ui- Design OS — Created by Brian Casel @ Builder Methods. This template integrates a community adaptation of Design OS for GitHub Copilot. All credit and intellectual property for Design OS belong to Brian Casel.
- Original repo: github.com/caselabs/design-os
- Website: buildermethods.com/design-os
MIT