333-333-333/local-dev-workflow
skills/local-dev-workflow/SKILL.md
Local development workflow: Makefiles, port conventions, running services, and environment setup. Trigger: When adding new services, updating Makefiles, configuring local ports, or setting up local development.
development
Updated Mar 25, 2026
$ install --global
skillsauthnpx skillsauth add 333-333-333/agents local-dev-workflowInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Error
VirusTotalMulti-engine malware detection
70%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Mar 25, 2026, 12:29 PM45.7s2 files scanned
SKILL.md
- name:
- local-dev-workflow
- description:
- >
- Local development workflow:
- Makefiles, port conventions, running services, and environment setup.
- Trigger:
- When adding new services, updating Makefiles, configuring local ports, or setting up local development.
- license:
- Apache-2.0
- author:
- 333-333-333
- version:
- 1.1
- type:
- project
- scope:
- [api]
When to Use
- Adding a new microservice to
api/ - Updating or creating Makefiles
- Changing port assignments
- Modifying docker-compose services
- Setting up a developer's local environment
Port Convention
Every service gets a unique local port. In Docker, all services use :8080 internally.
| Service | Local port | Docker internal | pg-{service} host port |
|---------|-----------|-----------------|--------------------------|
| gateway | 8080 | 8080 | — |
| auth | 8081 | 8080 | 5433 |
| booking | 8082 | 8080 | 5434 |
| caregiver | 8083 | 8080 | 5435 |
| payment | 8084 | 8080 | 5436 |
| notification | 8085 | 8080 | 5437 |
| pet | 8086 | 8080 | 5438 |
Rule: next service = next sequential port. Never reuse ports.
Environment Modes
| Mode | APP_ENV | DB_PROVIDER | How to run |
|------|-----------|---------------|------------|
| Local (no Docker) | local | memory | make run or make run-{service} |
| Local + PostgreSQL | development | postgres | make run-{service}-pg (needs Docker for DB) |
| Docker full stack | development | postgres | make up |
| Staging | staging | postgres | Cloud deployment |
| Production | production | postgres | Cloud deployment |
Root Makefile Commands
make run # Start ALL services in background (in-memory)
make stop # Stop all background services
make logs # Tail all service logs
make run-{service} # Start single service
make test # Run all tests
make test-{service} # Test single service
make build # Build all binaries
make up # docker-compose up -d
make down # docker-compose down -v
make sqlc # Regenerate sqlc code for all services
Per-Service Makefile Template
When creating a new service, its Makefile MUST follow the template in assets/service.Makefile.
Replace {name}, {assigned port from table}, {pg host port from table}, {service_name}, and {domain} with actual values.
Checklist: Adding a New Service
When adding a new service to the project:
- [ ] Assign next sequential port in the port table above
- [ ] Create
api/{service}/Makefilefollowing the template - [ ] Add
run-{service}andtest-{service}targets to rootMakefile - [ ] Add
pg-{service}container todocker-compose.yml - [ ] Add service container to
docker-compose.yml - [ ] Add service URL env var to gateway in
docker-compose.yml - [ ] Add proxy route in gateway's
main.go - [ ] Add
{SERVICE}_SERVICE_URLto gateway'sconfig.go - [ ] Update this skill's port table if needed
Docker-Compose: Database per Service Pattern
Each service gets its own PostgreSQL container following the template in assets/docker-compose.service.yml.
Replace {service} and {host port} with actual values from the port table.
Critical: dev passwords are service name (e.g. auth/auth). Production uses secrets management.
File Locations
api/Makefile # API orchestrator — runs all services
api/gateway/Makefile # Gateway service
api/auth/Makefile # Auth service
api/{service}/Makefile # Future services
api/docker-compose.yml # Docker full stack
api/logs/ # Local dev log files (gitignored)
api/.pids/ # Background process PIDs (gitignored)
Related Skills
333-333-333/ux-review
testing
VerifiedTrustedCommunity
Review Flutter components and screens for UX/UI compliance. Trigger: When user invokes /ux-review command or requests UX audit.
SKILL.mdUpdated Mar 25, 2026
333-333-333/typescript
development
VerifiedTrustedCommunity
TypeScript strict patterns and best practices. Trigger: When implementing or refactoring TypeScript in .ts/.tsx (types, interfaces, generics, const maps, type guards, removing any, tightening unknown).
SKILL.mdUpdated Mar 25, 2026
333-333-333/testing-strategy
testing
VerifiedTrustedCommunity
Testing philosophy and strategy for every feature: test pyramid, mandatory levels per change type, completion checklist, and skill delegation. Trigger: When planning tests for a feature, reviewing test coverage, defining acceptance criteria, or asking what tests a change needs.
SKILL.mdUpdated Mar 25, 2026
333-333-333/terraform-security
development
VerifiedTrustedCommunity
Terraform security practices: sensitive variables, secret management, state protection, .gitignore patterns, and CI/CD credential handling. Trigger: When handling secrets in Terraform, configuring state backends, reviewing .gitignore for Terraform, or setting up CI/CD pipelines for infrastructure.
SKILL.mdUpdated Mar 25, 2026