Developer Conventions
Day-to-day conventions for working in the PPP monorepo. This is the "how we actually ship things here" page — the rules that don't show up in lint errors but do show up in PR reviews.
For non-negotiable technical rules (type safety, no-console.log, migration discipline), see Code Standards.
Git Workflow
Branches
uatis the integration branch. All feature work merges intouatfirst and is deployed to the UAT environment.maintracks what's in production. It only receives commits via controlleduat → mainrelease PRs (typically with-s oursmerges to bridge divergence).- Feature/fix/chore branches are created from
origin/uat, named by type and issue number, e.g.feature/issue-1234,fix/issue-4895-cv-upload,chore/issue-5143-delete-deploy-marketing.
Git worktrees — the main workspace stays on uat
PPP uses git worktrees for all feature work. The main workspace (C:\Git\ppp / /workspaces/ppp) stays on uat at all times — never switch branches there unless the user explicitly requests it.
# Create a worktree for a new issue
git worktree add .worktrees/issue-<N> -b feature/issue-<N> origin/uat
# Work in the worktree
cd .worktrees/issue-<N>
# … make changes, commit, push …
# Return to the main workspace
cd /workspaces/ppp
# Clean up after the PR merges
git worktree remove .worktrees/issue-<N>Worktrees let multiple parallel feature branches coexist without blowing away node_modules or forcing a stash-juggling ritual when you jump between issues.
Pre-commit hooks
Husky runs lint-staged on every commit. Lint-staged runs Prettier against staged files and fails the commit if formatting is off. The hook also runs any type/lint checks scoped to the changed paths.
If a hook fails, fix the underlying issue — do not bypass with --no-verify unless the user has explicitly asked for it. When a hook fails, the commit did not happen, so never use git commit --amend to retry; create a fresh commit instead.
Conventional commits
PPP uses Conventional Commits with Commitizen. The prefix determines the release-note section and must match the type of change:
| Prefix | Use for |
|---|---|
feat(scope): ... | New feature or user-visible enhancement |
fix(scope): ... | Bug fix |
chore(scope): ... | Tooling, deps, refactors that aren't user-visible |
refactor(scope): ... | Internal restructuring with no behaviour change |
docs(scope): ... | Documentation-only change |
test(scope): ... | Test-only change |
ops(scope): ... | Operational/runtime config |
deploy(scope): ... | Deployment pipeline or release mechanics |
Run pnpm commit from the repo root to get an interactive Commitizen prompt that builds a valid message.
Pull Requests
Title convention
The PR title is the squash-merge commit message, so it must follow the Conventional Commits format and include a - fixes #<N> suffix where possible so the issue auto-closes when the PR merges.
fix(signup): auto-mount PaymentIntent and default billing country to registration country - fixes #5151
feat(pricing): bump CPD Home to $299 AUD / £159 GBP — fixes #5111
chore(mobile): delete redundant deploy-marketing.yml — fixes #5143Closing keywords
GitHub auto-closes issues when the merged PR's title OR body contains one of the closing keywords: fixes #N, closes #N, resolves #N. The keywords are strict — Fix #N (capital, missing plural) and fixes: #N (with colon) both fail to auto-close.
Body structure
A typical PR body looks like:
## Summary
- 1-3 bullets describing what changed and why
## Test Plan
- [ ] Manual verification steps
- [ ] Any CI gates that need attention
fixes #<N>Issue Labelling
Every open issue must carry exactly one of bug or enhancement as a top-level tag. This makes the weekly triage ritual fast — a reviewer can filter the board by bug and triage everything critical in one pass.
| Label | Use for |
|---|---|
bug | Something is broken, regressing, or behaving against spec |
enhancement | Everything else: new features, tech debt, refactors, ops tasks, research spikes, deploy tasks |
question | Exempt from the bug/enhancement rule — questions aren't trackable work |
When you create an issue via gh issue create or a workflow, always pass bug or enhancement in the labels array. The issue-auto-label workflow is a safety net that defaults new issues to enhancement, but don't rely on it — tag at creation.
Secondary labels to consider:
for-discussion— items that need Matt's specific review or feedback before closing (e.g. UX decisions, clinical workflow, pricing/billing)on-hold— parked items with open questions; typically need a product decision before implementation can proceedepic— umbrella issues that track multiple children- Module labels like
mobile,docs,devops,marketing— help scoping
BDD-First Rule
Every issue that touches instances/ppp/ or api/backend-ppp/ must include a corresponding BDD scenario change. If a PR has no .feature file change and touches those paths, the PR description must include an explicit justification.
The order is always: scenario first, implementation second. The scenario is the acceptance criteria. If you can't write a scenario, the issue isn't well-defined enough to implement.
| Issue type | Required tag | Location |
|---|---|---|
| Bug fix | @regression | Matching .feature file — a scenario that would have caught the bug |
| New feature | @smoke | Matching .feature file — 1-2 critical path scenarios |
| New journey | @smoke + @regression | @smoke for the happy path, @regression for the failure path |
Tag every new scenario with @issue-<N> so the trace from scenario → issue → PR is automatic.
Step definitions grow organically — if your scenario needs a step that doesn't exist, add it to the matching steps/*.steps.ts file. Reuse existing steps wherever possible; the step library compounds with each closed issue.
Feature Specifications
Before modifying any named feature, read its spec file in docs/features/. If your change causes the implementation to diverge from the acceptance criteria, you must update the spec with the reason in the Change Log at the bottom of the spec file. Never silently remove functionality that appears in a spec.
See docs/features/README.md for the full index. Related BDD scenarios live in instances/ppp/e2e/bdd/features/ and are executable via playwright-bdd.
Plan Before Building
- Enter plan mode for any task with 3+ steps or architectural decisions.
- If an approach fails or goes sideways, stop and re-plan rather than pushing through.
- Every plan should include verification steps, not just build steps.
- Write specs upfront to reduce ambiguity — "we'll figure it out as we go" is a sign of scope creep.
Verify Before Done
Never mark work as done without running the CI-equivalent gates locally. The table below maps changed areas to the commands you need to run; CI enforces exactly the same commands as Tier 1 gates.
| Changed area | Commands |
|---|---|
api/backend-ppp/ | pnpm tsc && pnpm lint && pnpm lint:no-console |
instances/ppp/ | npx tsc --noEmit -p tsconfig-lint.json && pnpm lint && pnpm lint:no-console |
packages-shared/ppp/ | pnpm tsc (from root) |
| Any of the above | node .github/scripts/check-no-any.mjs |
| Backend test files | npx tsc --noEmit -p tsconfig.test.json |
Diff your changes against the base branch before requesting review. Ask yourself: "Would a senior engineer approve this PR?"
Autonomous Problem Solving
- When given a bug report or failing CI, investigate and fix it. Don't ask for hand-holding.
- Point at logs, errors, and failing tests, then resolve them.
- Zero context-switching required from the requester.
- Fix failing CI tests without being told how.
Development Environment
Prerequisites
- Node.js ≥ 22.14.0
- pnpm ≥ 9
- Docker (for backend integration tests against a local Postgres)
Initial setup
pnpm install # install all dependencies
pnpm build # build all packages — required before running apps
pnpm build:force # force rebuild, ignoring turbo cacheRunning the stack
# Frontend (from instances/ppp/)
pnpm start # http://localhost:3000
# Backend (from api/backend-ppp/)
pnpm start # http://localhost:4000
# Storybook
pnpm storybook # http://localhost:6006Common commands
pnpm format-lint # check formatting
pnpm format-fix # auto-fix formatting
pnpm lint # lint all workspaces
pnpm tsc # type-check all workspaces
pnpm test # run all tests
pnpm clean # remove node_modules and build artifactsStyle Highlights
- Comments in PPP code start with 🤗 for visual consistency.
- Variable names should be clear and descriptive — prefer
monthlyActivityCountovercnt. - Single-line
ifstatements don't need brackets when the body is a single statement. - Prefer early returns over deep nesting.
- Extract functions when a block grows beyond ~40 lines; name them after what they do, not how they do it.
Where to Go Next
- Local Setup — get the stack running locally
- Code Standards — non-negotiable type safety and linting rules
- Backend Testing — backend test patterns
- Frontend Testing — Storybook, play tests, RTL