dev-workflows.md

Dev Workflows

Engineering workflows for this repo.

New Feature

• Read AGENTS.md and ARCHITECTURE.md
• Read the relevant feature doc in docs/features/
• For non-trivial changes, create a plan in docs/exec-plans/active/
• Implement the smallest coherent change
• Add or update tests
• Run: pnpm lint && pnpm lint:api && pnpm test:api && pnpm check:structure
• Update docs in the same PR (see AGENTS.md §8)
• Move plan to docs/exec-plans/completed/ after validation

Bugfix

• Add a failing test that reproduces the bug
• Confirm the test fails
• Implement the fix
• Rerun tests until green
• Update docs if behavior changed

Refactor

• Read ARCHITECTURE.md — respect layering rules
• Ensure structural tests still pass: pnpm check:structure
• No behavior changes without updating feature docs

Documentation Update

• Update only the canonical location (see AGENTS.md §8 doc update mapping)
• Never duplicate content — link instead
• Update <!-- last_verified: YYYY-MM-DD --> header

Pull Request

• One coherent change per PR
• Run full lint + test suite before submitting
• Docs updated in the same PR as code changes
• Only change files relevant to the task — no drive-by improvements

Testing

Test types

• Unit: pure logic (service layer)
• Integration: HTTP handlers, B2 connectivity (tests/)
• Structural: layering rules, import boundaries (tests/test_structure.py)
• E2E: Playwright browser-driven smoke tests

Test placement

• Backend: services/api/tests/
• E2E: project root (Playwright)

Commands

• Quick (backend): pnpm test:api
• Structure: pnpm check:structure
• Frontend lint: pnpm lint
• Backend lint: pnpm lint:api
• Full suite: pnpm lint && pnpm lint:api && pnpm test:api && pnpm check:structure
• E2E: pnpm test:e2e

When to run

• After behavior change: run relevant subset
• Before PR: run full suite

Frontend Conventions

• Tailwind v4: config via CSS @theme blocks, NOT tailwind.config.ts
• Colors: OKLch format
• Dark mode: next-themes with @custom-variant dark (&:is(.dark *))
• Animations: tw-animate-css (not tailwindcss-animate)
• shadcn/ui components in src/components/ui/ are generated — never modify them