Development Flow

Standard flow

1. Start from roadmap task IDs and status.
2. Create a branch with codex/ prefix.
3. Implement a vertical slice:
   • contract/schema in libs/contracts
   • backend implementation in module application/infrastructure/interface
   • frontend features/*/api.ts + hooks + presentational components
4. Update docs and roadmap in the same slice.
5. Run local checks and open PR.

Vertical slice checklist

• Contracts first:
  • add or update Zod schemas in libs/contracts
  • wire oRPC contract in libs/contracts/src/orpc/athas-orpc.contract.ts
• Backend:
  • implement procedure/router binding in adapter layer
  • keep provider SDK calls in infrastructure providers
• Frontend:
  • keep screens orchestration-only
  • keep query/mutation logic in feature-local api.ts
• Docs:
  • update canonical page under apps/docs/content/docs
  • sync docs/roadmap.md task status in the same PR

Guardrails

• Contract-first checks must pass.
• Projection policy checks must pass.
• Dependency boundaries must pass for backend and frontend.

Core commands

bun run typecheck
bun run depcruise:backend
bun run depcruise:frontend
bun run check:contract-first
bun run check:projection-policy
bun run check:module-profiles

Scaffolding entry points

bun run scaffold:feature --app admin-console --feature reports --audience admin
bun run scaffold:providers-billing --app admin-console --slice integrations
bun run profiles:resolve --profiles core,commerce --format env
bun run scaffold:profile --profiles core,commerce --name commerce-starter

Documentation policy

• docs/roadmap.md is execution source of truth.
• ADRs record durable decisions.
• This Fumadocs app is the canonical surface for architecture and workflow docs.