Sprint 3 — AI Agent Layer¶
Dates: 20 Apr – 1 May 2026 Sprint Goal: Deliver a conversational AI layer that enables natural-language billing management, anomaly detection, and compliance queries — while completing email infrastructure and hardening PDF generation. Total Story Points: 43
Context¶
Sprints 0–2 established the core platform: entity CRUD, billing configurator with multi-entity AND/OR conditions, exception handling, discount stacking, billing run engine, cycle lifecycle, manual payments, transactions, auth (JWT/RBAC/RLS), audit logging, custom fields, admin UI, and PDF invoice generation.
Sprint 3 shifts focus from building billing mechanics to making them accessible through natural language. The AI agent layer wraps existing services — it reads and orchestrates, but the billing engine remains the source of truth. Alongside this, the sprint addresses two infrastructure gaps: email delivery (required for password reset and invoice distribution) and PDF pipeline stability.
What Changes After This Sprint¶
| Capability | Before Sprint 3 | After Sprint 3 |
|---|---|---|
| Billing cycle setup | Manual 9-tab configurator only | NL conversational setup + configurator |
| Anomaly detection | Manual review of billing outputs | AI-driven anomaly alerts with structured reports |
| Fee modelling | No what-if capability | NL scenario modelling (read-only, no execution) |
| Audit queries | Raw audit log tables | NL compliance queries with auto-generated Kysely |
| Tables exist, no provider or sending | Full send pipeline — password reset + invoice delivery | |
| PDF generation | Works but no CI coverage | Puppeteer in CI, visual regression tests |
| Tenant management | Basic multi-tenancy | Tier-based feature gating, logo upload, secure routes |
Stories¶
| # | Story | SP | Owner | Priority |
|---|---|---|---|---|
| 80 | Tenant Management — Tier-Based Feature Access, Secure Routes & Logo Upload | 8 | Ola | Carryover — finish first |
| 46 | Pymble Data Import and E2E Verification Test | 5 | Ola | Week 1–2 |
| 47 | AI Agent Foundation | 5 | Samawal | Week 1 — critical path |
| 48 | AI: Natural Language Billing Setup | 5 | Samawal | Week 2 (after #47) |
| 49 | AI: Anomaly Detection | 3 | Samawal | Week 2 (after #47) |
| 50 | AI: Fee Structure Modelling | 3 | Samawal | Week 2 (after #47) |
| 51 | AI: Audit and Compliance Queries | 3 | Samawal | Week 2 (after #47) |
| 81 | Email Notification System — Foundation, Password Reset & Invoice Delivery | 8 | Monther | Week 1–2 |
| 82 | PDF Engine CI and Hardening | 3 | Monther | Week 1 |
Dependencies¶
graph TD
S2["Sprint 2 Complete"] --> 80["#80 Tenant Management<br/>8 SP — Ola"]
S2 --> 46["#46 Pymble E2E<br/>5 SP — Ola"]
S2 --> 82["#82 PDF CI Hardening<br/>3 SP — Monther"]
S2 --> 81["#81 Email System<br/>8 SP — Monther"]
S2 --> 47["#47 AI Foundation<br/>5 SP — Samawal"]
47 --> 48["#48 NL Billing Setup<br/>5 SP — Samawal"]
47 --> 49["#49 Anomaly Detection<br/>3 SP — Samawal"]
47 --> 50["#50 Fee Modelling<br/>3 SP — Samawal"]
47 --> 51["#51 Audit & Compliance<br/>3 SP — Samawal"]
38["#38 PDF Invoice<br/>(Sprint 2)"] -.->|"attaches to emails"| 81
38 -.->|"hardens"| 82
style 47 fill:#e74c3c,color:#fff
style 80 fill:#f39c12,color:#fffCritical path: #47 → #48/#49/#50/#51. If the AI Foundation slips, four stories (14 SP) are blocked. Sarah pairs with Samawal on #47 to mitigate this risk.
No cross-developer dependencies — each developer's work stream is fully independent. Ola, Monther, and Samawal can work in parallel from day one.
Workload Distribution¶
pie title Story Points by Developer
"Samawal — AI (19 SP)" : 19
"Ola — Data & Tenant (13 SP)" : 13
"Monther — Email & PDF (11 SP)" : 11| Developer | Week 1 | Week 2 | Total SP | Notes |
|---|---|---|---|---|
| Samawal | #47 AI Foundation (5) | #48 (5), #49 (3), #50 (3), #51 (3) | 19 | Sarah pairs on #47. Scenarios are read-only wrappers over the foundation |
| Ola | #80 finish (~2 SP remaining), #46 start | #46 Pymble E2E cont. + bug fixes | 13 | #80 is a Sprint 2 carryover, nearly complete. #46 may surface billing engine bugs |
| Monther | #82 PDF Hardening (3), #81 Email start | #81 Email cont. | 11 | Independent from AI chain. #82 hardens his own Sprint 2 PDF work |
Risks and Mitigations¶
| Risk | Impact | Likelihood | Mitigation |
|---|---|---|---|
| AI Foundation (#47) delays block 4 stories | High — 14 SP idle | Medium | Sarah pairs with Samawal; #47 is week 1 only focus |
| Pymble E2E (#46) surfaces billing engine bugs | Medium — unplanned fix work | High | Ola has capacity buffer (~2 SP slack). Bugs are caught now vs production |
| Email provider decision not finalised | Medium — #81 architecture depends on it | Low | Decide SendGrid vs SES vs SMTP before sprint starts |
| Samawal at 19 SP (above team avg ~13) | Medium — potential incomplete stories | Medium | Four scenarios (14 SP) are structurally similar — each is a read-only AI wrapper |
Key Decisions Made During Planning¶
| Decision | Rationale |
|---|---|
| Moved #52 (Mid-Year Adjustment) to Sprint 6 | Depends on pro-ration (#36), RPS (#63), and refunds (#70) — all Sprint 5/6 |
| Merged #74 (Password Reset Email) into #81 | Both built email infrastructure. Single story avoids duplicate foundation work |
| Bumped #46 from 3 SP to 5 SP | Real-data import with Pymble will surface bugs requiring investigation and fixes |
| All AI scenarios are read-only | No AI story executes mutations directly — all changes go through existing service layer with user confirmation |
Sprint 2 Carryover¶
| # | Story | SP | State | Action |
|---|---|---|---|---|
| 80 | Tenant Management | 8 | Active | Carries into Sprint 3 — nearly complete, Ola finishes week 1 |
| 38 | PDF Invoice Generation | 5 | Resolved | Close in Sprint 2 retrospective |
Definition of Done¶
A story is complete when:
- Code merged to
developvia PR with at least one reviewer - Unit tests pass (Vitest) with relevant coverage
- No ESLint or TypeScript errors
- API endpoints documented (route + Zod schema)
- Manual smoke test on dev environment
- Story moved to Closed in Azure Boards, and discussions updated to include what was done.