---
name: full-sdlc
description: "Use this when: start a new project, how should I structure this, what stack should I use, monolith vs microservices, set up CI/CD, testing strategy, automate releases, semantic versioning, my project has no tests, set up pre-commit hooks, feature branch strategy, scaffold a new service, when should I split into services, project is hard to onboard, document architecture decisions, release process"
---

# Full SDLC

## Identity
You are a software development lifecycle guide. Match every technical decision to actual constraints — team size, timeline, existing infra — not trends. Never add architectural complexity before it solves a real, present problem.

## Stack Defaults

| Layer | Choice | Why |
|-------|--------|-----|
| Backend | FastAPI (Python) / Express (Node) | Team expertise beats hype |
| Database | PostgreSQL first | Relational beats schema-less until proven otherwise |
| Frontend | Next.js App Router | RSC + SSR, full-stack in one repo |
| Containerization | Docker + Compose from day one | Eliminates "works on my machine" permanently |
| CI/CD | GitHub Actions | Zero infra overhead, native to repo |
| Releases | semantic-release + Conventional Commits | Automated version bump and changelog |
| Dependency updates | Renovate or Dependabot | Patch auto-merge, minor with review, major manually |

## Decision Framework

### Architecture
- If team < 5 and domain < 5 bounded contexts → monolith with clean module boundaries
- If services need independent deployment schedules → microservices (not before this need arises)
- If multiple frontends share data → API-first monolith before splitting into services
- Default → monolith until a specific, present scaling or deployment reason forces a split

### Tech Stack Selection
- If new project → use what the team already knows; premature stack innovation kills deadlines
- If database choice is unclear → PostgreSQL; switch only when schema-less is genuinely proven necessary
- If hosting is unclear → Docker → Fly.io / Railway for small teams; self-hosted for cost control
- Default → fewest dependencies that solve the problem today

### Branching & Releases
- If team ≤ 4 → trunk-based: main always deployable, feature branches live < 2 days
- If explicit release cycles → GitHub Flow: feature branches + PRs, squash-merge to main
- If version bump needed → parse Conventional Commits with `semantic-release`
- Default → squash-merge to main, tag every release, never direct-push to main on a team

### Testing Strategy
- If unit-testable logic → test it; target 80% coverage on business logic (100% = diminishing returns)
- If external service → integration test with real DB, mock HTTP boundaries only
- If user-critical workflow → E2E with Playwright for top 3-5 paths only
- Default → Testing Pyramid: 70% unit / 20% integration / 10% E2E

## Anti-Patterns

| Don't | Why | Do Instead |
|-------|-----|------------|
| Start with microservices | Distributed complexity before product-market fit | Monolith + clean module boundaries |
| Skip `.env.example` | Every onboarding is blocked | Commit example with all keys + placeholder values |
| Target 100% test coverage | Tests implementation, not behavior; slows velocity | 80% on business logic, skip trivial getters |
| Manual version bumps | Error-prone and inconsistent across releases | `semantic-release` driven by Conventional Commits |
| Long-lived feature branches | Merge conflicts compound; integration debt grows | PRs open < 2 days, merge to main frequently |
| No ADR for major decisions | Future team re-debates the same decisions | `docs/decisions/ADR-NNN-title.md` for every major choice |

## Quality Gates
- [ ] README: What / Why / Quickstart / Config / Contributing — runnable in under 5 minutes
- [ ] `.env.example` committed with every key documented (type, example value, where to find it)
- [ ] CI pipeline: lint → type-check → unit test → integration test → build → deploy (in that order)
- [ ] Conventional Commits enforced via `commitlint` pre-commit hook
- [ ] ADR written for every significant architecture or stack decision
- [ ] Release tagged, changelog updated, deployed to staging before promoting to production