Agent Skills: bbl-senior-architect

Use this skill when THB-BBL design choices have long-term impact.

When to use

1. Multiple viable architecture options with meaningful tradeoffs.
2. Boundary, dependency, or layering decisions across src/app/api/**/route.ts, src/server/services/**, prisma/schema.prisma, and backend/**.
3. Migration and compatibility planning for request-analysis, team-builder, exports, scheduling, or agent runtime flows.

When not to use

1. Routine implementation where architecture is already fixed.
2. UI-only or endpoint-only edits with no boundary impact.
3. Pure code review or pure test execution.

Preflight

1. Capture constraints, non-goals, and success criteria.
2. Map current THB-BBL boundaries: UI (src/app/**, src/components/**), API (src/app/api/**/route.ts), services (src/server/services/**), schema (prisma/schema.prisma), legacy backend (backend/**).
3. Identify stakeholder concerns: reliability, auditability, privacy boundaries, migration complexity, operator usability.

Stop condition: if success criteria or boundary ownership are ambiguous, pause and define them.

Execution checklist

1. Compare options using explicit criteria and a decision matrix.
2. Include required matrix dimensions: reliability, auditability, privacy boundaries, migration complexity, operator usability.
3. Surface operational, migration, and compatibility risks.
4. Select a preferred path and explain why alternatives are weaker.
5. Define implementation sequencing and rollback posture.
6. Produce ADR-ready summary with assumptions and deferred decisions.

Fallbacks

1. If the choice is already fixed, provide implementation guardrails only.
2. If uncertainty remains high, recommend a spike/prototype scope with exit criteria.
3. If evaluation is mostly vendor/tool choice, coordinate with tech-stack-evaluator.

Completion contract

Return:

1. scope_statement
2. options_considered
3. decision_matrix
4. recommended_option
5. migration_risks
6. compatibility_notes
7. rollback_posture
8. adr_summary
9. validation_hints (npm run lint, npm run typecheck, npm run test, python3 -m pytest backend/tests when backend/** is touched)