The capstone: all 10 roles, 3 sprints, from architecture to production
⏱ ~120 min · 3 Sprints · Advanced+
This is the capstone. Every command and role you've learned comes together. Multi-tenant SaaS has the highest complexity: tenant isolation, data security, PDF generation, email delivery, payment tracking. You'll use the full framework — security threat modeling upfront, story splitting for complex features, performance tuning, architecture audits, and a complete release pipeline.
Projects 01-06 each introduced a few commands at a time. This project uses nearly every command and ALL 10 roles in a single, realistic build. Multi-tenant means every query must be tenant-scoped, every endpoint must enforce isolation, and every security gap could expose one customer's data to another. This is the complexity level where the framework proves its value.
This is the only project where every role makes a meaningful contribution:
| Role | What they do in this project | When |
|---|---|---|
📋 @po | Writes tenant-scoped stories, validates multi-tenant acceptance criteria | Story creation, sprint reviews, acceptance |
🔄 @sm | Manages 3 sprints, tracks velocity trend across sprints, facilitates 3 retros | All sprint ceremonies |
🏗️ @arch | Designs multi-tenant architecture (shared DB vs separate schemas), records ADRs | Sprint 0, architecture audit |
👨💻 @lead | Reviews tenant isolation code, ensures no cross-tenant data leaks in PRs | Every code review |
⌨️ @dev | Implements with TDD, handles complex PDF generation and payment logic | All implementation |
🧪 @qa | Tests tenant isolation (can tenant A see tenant B's data?), validates coverage | DoD checks, isolation testing |
🗄️ @dba | Designs schema with tenant_id foreign keys, indexes for tenant-scoped queries, migration safety | Schema design, Sprint 2 payments |
🛡️ @sec | STRIDE threat model upfront, OWASP audit on payment/invoice code, dependency CVE scan | Sprint 0, Sprint 3 |
🎨 @ux | Invoice creation form, PDF preview, responsive dashboard, WCAG AA accessibility | Sprint 3 UI work |
🚀 @devops | CI/CD pipeline, staging + production environments, deployment with rollback plan | CI, releases, deploy |
"I want to build a multi-tenant invoicing SaaS. Tenants are businesses that create invoices for their clients. Each tenant's data must be completely isolated. Features: tenant registration, user management within tenants, invoice CRUD with line items, PDF generation, email delivery, and payment tracking."
/agile-explore-brainstorm/agile-explore-brainstorm Multi-tenant invoicing SaaS. Key concern: tenant data isolation. Evaluate shared DB with tenant_id column vs separate schemas vs separate databases. Must be cost-effective for MVP with path to scale.
🏗️ @arch evaluates multi-tenant isolation strategies:
🏗️ @arch responds:
## /agile-explore-brainstorm — Results
### Problem Statement
Multi-tenant data isolation for invoicing SaaS.
Constraints: cost-effective MVP, path to scale, strong isolation.
### Scoring Matrix
| Approach | Feasibility | Isolation | Cost | Scale Path | Total |
|------------------------|------------|-----------|---------|------------|-------|
| Shared DB + tenant_id | 9/10 | 7/10 | 10/10 | 7/10 | 33 |
| Separate schemas | 7/10 | 9/10 | 7/10 | 8/10 | 31 |
| Separate databases | 5/10 | 10/10 | 4/10 | 9/10 | 28 |
### Recommendation
Shared DB with tenant_id — highest feasibility, lowest cost.
Isolation enforced at application layer via middleware.
### What Would Change This
- If regulated industry (healthcare, finance) → separate schemas
- If >1000 tenants with heavy data → separate databases
- If compliance requires physical isolation → separate databases"Let's go with shared DB with tenant_id. Simplest for MVP, and we'll enforce isolation in middleware."
Record the decision so the framework remembers it across sprints:
💬 /agile-memory-remember Architecture decision: shared DB with tenant_id column
for multi-tenant isolation. Enforced via middleware, not DB-level.
🔄 @sm: Saved to .memory/semantic/architecture.md/agile-security-threat-modelMulti-tenant systems have a high security bar. Before writing a single line of code, @sec identifies threats that will drive Sprint 3's security stories.
/agile-security-threat-model Analyze the multi-tenant invoicing system for security threats. Key concerns: tenant data isolation, payment data, PII in invoices.
🛡️ @sec responds with STRIDE analysis:
## /agile-security-threat-model — STRIDE Analysis
### System: Multi-Tenant Invoicing SaaS
| Threat Category | Threat | Impact | Mitigation |
|--------------------|-------------------------------------------|--------|---------------------------------------|
| Spoofing | Attacker forges tenant context in JWT | 🔴 High | Sign JWTs server-side, validate |
| | | | tenant_id claim on every request |
| Tampering | User modifies invoice_id in URL to access | 🔴 High | Scope all queries by tenant_id, |
| | another tenant's invoice (IDOR) | | never trust client-supplied IDs alone |
| Repudiation | Tenant disputes invoice was sent/paid | 🟡 Med | Audit log for all invoice state |
| | | | changes and email deliveries |
| Info Disclosure | Cross-tenant data leak via API response | 🔴 High | Tenant isolation middleware on ALL |
| | or error messages | | endpoints, sanitize error responses |
| Denial of Service | Large PDF generation blocks server | 🟡 Med | Queue PDF generation, set timeouts, |
| | | | rate limit per tenant |
| Elevation of Priv | Regular user accesses admin endpoints | 🔴 High | RBAC per tenant, separate admin |
| | or another tenant's admin panel | | middleware, validate role + tenant |
### Key Finding
3 of 6 threat categories are 🔴 High — all related to tenant isolation.
This confirms: tenant isolation middleware is the single most critical component.The STRIDE analysis identified that tenant isolation failures appear in three separate threat categories. This isn't a nice-to-have — it's the architectural foundation. Sprint 3 will address these findings with targeted security stories.
🗄️ @dba designs the initial schema with tenant isolation baked into the data model:
🗄️ @dba: Initial Schema Design
### Tables
tenants (id PK, name, slug, created_at)
users (id PK, tenant_id FK → tenants, email UNIQUE per tenant, role, password_hash)
invoices (id PK, tenant_id FK → tenants, client_name, client_email,
status, due_date, created_at, updated_at)
invoice_items (id PK, invoice_id FK → invoices, tenant_id FK → tenants,
description, quantity, unit_price DECIMAL(10,2), line_total DECIMAL(10,2))
payments (id PK, invoice_id FK → invoices, tenant_id FK → tenants,
amount DECIMAL(10,2), payment_date, method)
### Key Constraints
- Every table has tenant_id (except tenants itself)
- Composite unique index on users(tenant_id, email)
- All FK cascades scoped to tenant
- DECIMAL(10,2) for ALL money fields — never FLOAT
### Indexes
- idx_invoices_tenant_status ON invoices(tenant_id, status)
- idx_invoice_items_invoice ON invoice_items(invoice_id)
- idx_payments_invoice ON payments(invoice_id)💬 "Set up the project with Express, PostgreSQL, and Jest. Then initialize."
⌨️ @dev: Scaffolds project structure
/agile-setup-init → All memory files populated ✅
/agile-setup-onboard → Coding rules generated ✅
/agile-setup-health → All checks green ✅Phase 1 complete. You have a multi-tenant architecture decision, a STRIDE threat model driving future security work, a schema design with tenant isolation at the data level, and a fully initialized project. Zero features built yet — Sprint 0 is about foundations.
/agile-story-create Tenants can register their business and get a unique workspace with a slug URL
📋 @po responds:
## /agile-story-create — Story Created
### Story US-001 (3 pts)
**As a** business owner,
**I want** to register my business as a tenant with a unique slug,
**so that** I get an isolated workspace for my invoicing.
### Acceptance Criteria
AC-1: POST /tenants with {name: "Acme Corp"} → 201, returns tenant with slug "acme-corp"
AC-2: Duplicate slug → 409 Conflict
AC-3: Missing name → 400 with error message/agile-story-create Users within a tenant can register, log in, and only see their tenant's data
📋 @po creates US-002 — but @dev estimates it at 13 points. Too large for one story.
/agile-story-split/agile-story-split US-002 --strategy business-rules
📋 @po splits by business rules:
## /agile-story-split — US-002 Split Into 3 Stories
| Story | Title | Points | Rationale |
|---------|--------------------------------|--------|------------------------------|
| US-002a | User registration within tenant | 3 | Signup + tenant_id FK |
| US-002b | Login + JWT with tenant claim | 3 | Auth + tenant in token |
| US-002c | Tenant isolation middleware | 5 | Core security — scopes ALL |
| | | | queries by tenant_id |
Original 13 pts → 3 stories totaling 11 pts (reduced uncertainty)
### INVEST Check: All 3 stories pass independently ✅Create the final foundation story:
💬 /agile-story-create Create and manage invoices: add line items,
calculate totals, set due dates
→ 📋 @po creates US-003: Invoice CRUD (5 pts)/agile-sprint-planning🔄 @sm facilitates:
## Sprint 1 Planning
### Sprint Goal
"Deliver tenant registration, user auth with isolation, and invoice CRUD"
### Sprint Backlog
| Story | Title | Points | Priority |
|---------|--------------------------------|--------|----------|
| US-001 | Tenant registration | 3 | P1 |
| US-002a | User registration within tenant | 3 | P1 |
| US-002b | Login + JWT with tenant claim | 3 | P1 |
| US-002c | Tenant isolation middleware | 5 | P1 |
| US-003 | Invoice CRUD | 5 | P1 |
### Capacity
- Committed: 19 points (aggressive for Sprint 1)
- Risk: No historical velocity — may need to carry US-003 to Sprint 2/agile-code-branch feature US-001 tenant-registration
/agile-story-plan US-001
/agile-code-tdd US-001
🔴 Test: POST /tenants creates tenant with slug → ❌
🟢 Implement tenant creation + slug generation → ✅
🔴 Test: duplicate slug returns 409 → ❌
🟢 Add unique constraint check → ✅
🔴 Test: missing name returns 400 → ❌
🟢 Add validation → ✅
/agile-code-ci → ✅ All green
/agile-code-commit → feat(tenants): add tenant registration with slug
/agile-code-pr → PR created
/agile-code-pr-review → ✅ Approved (8/10)
/agile-code-merge → Squash merged to develop
/agile-story-dod → ✅ DONE
/agile-story-accept → ✅ ACCEPTED (3 points)/agile-code-branch feature US-002a user-registration
/agile-story-plan US-002a → @lead: Create user with tenant_id FK, validate
email unique within tenant
/agile-code-tdd US-002a
🔴 Test: POST /tenants/:tenantId/users creates user → ❌
🟢 Implement with tenant_id FK → ✅
🔴 Test: duplicate email within same tenant → 409 → ❌
🟢 Add composite unique check → ✅
🔴 Test: same email in different tenant → 201 (allowed) → ❌
🟢 Scope uniqueness to tenant → ✅
/agile-code-ci → commit → PR → review → merge → DoD → accept ✅ (3 pts)/agile-code-branch feature US-002b tenant-jwt
/agile-code-tdd US-002b
🔴 Test: POST /login returns JWT with tenant_id in payload → ❌
🟢 Add tenant_id claim to JWT → ✅
🔴 Test: invalid credentials → 401 → ❌
🟢 Add credential validation → ✅
/agile-code-ci → commit → PR → review → merge → DoD → accept ✅ (3 pts)/agile-code-branch feature US-002c tenant-isolation
/agile-story-plan US-002c → @lead: Middleware extracts tenant_id from JWT,
injects into every DB query. No endpoint should work without valid tenant context.
/agile-code-tdd US-002c
🔴 Test: request without JWT → 401 → ❌
🟢 Add auth middleware → ✅
🔴 Test: request with valid JWT → tenant_id injected into req → ❌
🟢 Extract tenant_id from JWT claims → ✅
🔴 Test: GET /invoices only returns current tenant's data → ❌
🟢 Scope all queries with WHERE tenant_id = ? → ✅
🔴 Test: GET /invoices/:id for another tenant's invoice → 404 (not 403!) → ❌
🟢 Tenant-scoped lookup returns null → 404 → ✅
/agile-code-ci → ✅ All green🗄️ @dba reviews the migration for the users table:
🗄️ @dba: Migration Review
✅ tenant_id FK with ON DELETE CASCADE — correct
✅ Composite unique index (tenant_id, email) — correct
⚠️ Missing index on users(tenant_id) for tenant-scoped lookups — add it
→ @dev adds index, tests still pass ✅🧪 @qa runs the critical isolation test:
🧪 @qa: Tenant Isolation Verification
Test: Can tenant A see tenant B's invoices?
1. Create tenant A, create invoice for tenant A
2. Create tenant B, authenticate as tenant B
3. GET /invoices → returns [] (not tenant A's invoice) ✅
4. GET /invoices/:tenantA-invoiceId → 404 (not 200) ✅
5. Direct DB query confirms data exists but middleware blocks it ✅
Verdict: ✅ Isolation verified — no cross-tenant data leakage/agile-code-commit → feat(auth): add tenant isolation middleware
/agile-code-pr → PR created
/agile-code-pr-review
👨💻 @lead: PR Review — US-002c (CRITICAL component)
| # | Severity | Finding | Fix |
|---|----------|--------------------------------------------|------------------------------|
| 1 | 🟡 S2 | Middleware doesn't handle expired JWTs | Add expiry check |
| | | differently from missing JWTs | with distinct error message |
| 2 | 🔵 S3 | Magic string "tenant_id" repeated | Extract to constant |
Score: 8/10
Verdict: ✅ APPROVED — isolation logic is solid
/agile-code-merge → Squash merged to develop
/agile-story-dod → ✅ DONE
/agile-story-accept → ✅ ACCEPTED (5 pts)/agile-code-branch feature US-003 invoice-crud
/agile-code-tdd US-003
🔴 Test: POST /invoices creates invoice with line items → ❌
🟢 Implement with tenant-scoped insert → ✅
🔴 Test: GET /invoices returns only current tenant's invoices → ❌
🟢 Query scoped by tenant_id from middleware → ✅
🔴 Test: line item totals auto-calculated → ❌
🟢 Calculate line_total = quantity * unit_price, sum for invoice total → ✅
🔴 Test: invoice with zero items → 400 → ❌
🟢 Validate at least one line item required → ✅
/agile-code-ci → commit → PR → review → merge → DoD → accept ✅ (5 pts)/agile-sprint-review
Sprint Goal Met: ✅ Yes
Completed: 19/19 points (100%)
Velocity baseline: 19 points
/agile-sprint-retro
What went well: Story splitting reduced US-002 risk significantly
What went well: Tenant isolation tested thoroughly — high confidence
To improve: Sprint was aggressive — 19 pts may not be sustainable
Action items:
| Action | Owner | Due |
|-------------------------------------|-------|----------|
| Target 15-16 pts next sprint | @sm | Sprint 2 |
| Add tenant isolation to test template| @qa | Sprint 2 |
/agile-memory-learn → Sprint 1 velocity: 19 pts, story splitting effective/agile-sprint-refine/agile-sprint-refine
📋 @po: Backlog refined
US-004: Generate PDF invoices — Ready ✅ (ACs updated with logo, line items, totals)
US-005: Send invoice by email — Ready ✅ (ACs include retry on failure)
US-006: Track payments — Ready ✅ (ACs include partial payment, overdue status)💬 /agile-story-create Generate PDF invoices from invoice data.
The PDF should include company logo, line items, totals, payment terms.
→ 📋 @po creates US-004 (5 pts)
💬 /agile-story-create Send invoice by email to the client
with the PDF attached
→ 📋 @po creates US-005 (3 pts)
💬 /agile-story-create Track payments against invoices:
mark as paid, partially paid, or overdue
→ 📋 @po creates US-006 (5 pts)/agile-sprint-planning
Sprint Goal: "Add PDF generation, email delivery, and payment tracking"
Committed: 13 points (down from 19 — learning from retro ✅)/agile-explore-spikePDF generation has unknowns. Before committing to an implementation, @dev runs a time-boxed spike:
/agile-explore-spike Evaluate PDF generation libraries for Node.js. Need: company logo, styled table of line items, totals, payment terms. Time-box: 2 hours.
⌨️ @dev runs a time-boxed spike:
## /agile-explore-spike — PDF Library Evaluation (2h time-box)
### Libraries Tested
| Library | Logo Support | Table Layout | File Size | Render Speed | Verdict |
|-------------|-------------|--------------|-----------|-------------|------------|
| PDFKit | ✅ Images | Manual layout| 180KB | 120ms | ✅ Winner |
| Puppeteer | ✅ HTML/CSS | Full CSS | 850KB | 2.1s | Too heavy |
### Recommendation
PDFKit — fast rendering, small output, manual layout is acceptable
for structured invoice format.
### What We Learned
Puppeteer renders HTML to PDF (flexible) but requires a headless browser
(heavy dependency, slow). PDFKit is code-driven (less flexible) but
10x faster and no external dependencies.
### Decision
Use PDFKit for MVP. If layout needs become complex, revisit Puppeteer.
> 💬 /agile-memory-remember PDF generation: PDFKit chosen over Puppeteer.
> Reason: 10x faster, no headless browser dependency.
> Revisit if layout complexity increases./agile-code-branch feature US-004 pdf-generation
/agile-story-plan US-004
/agile-code-tdd US-004
🔴 Test: POST /invoices/:id/pdf returns a PDF buffer → ❌
🟢 Implement PDFKit rendering → ✅
🔴 Test: PDF contains company name, line items, totals → ❌
🟢 Add structured layout: header, items table, total → ✅
🔴 Test: PDF for another tenant's invoice → 404 → ❌
🟢 Tenant-scoped lookup (middleware handles it) → ✅
/agile-code-ci → commit → PR → review → merge → DoD → accept ✅ (5 pts)/agile-code-perfAfter implementation, PDF generation is slow for large invoices. Time to profile:
/agile-code-perf Profile PDF generation. It takes 3 seconds for a 50-line invoice. Target: under 500ms.
⌨️ @dev profiles and optimizes:
## /agile-code-perf — PDF Generation Profiling
### Bottleneck Analysis
| Operation | Time | % of Total |
|---------------------|---------|------------|
| DB query (invoice) | 45ms | 1.5% |
| DB query (items) | 62ms | 2.1% |
| Font loading | 2,400ms | 80.0% ← 🔴 |
| PDF rendering | 320ms | 10.7% |
| Buffer finalization | 173ms | 5.8% |
### Root Cause
Font files loaded from disk on EVERY PDF generation.
PDFKit re-reads and re-parses .ttf files per request.
### Fix
Cache font objects at module load time — load once, reuse forever.
### Results
| Metric | Before | After | Improvement |
|----------------|---------|--------|-------------|
| 50-line invoice | 3,000ms | 380ms | 87% faster |
| Memory per PDF | 12MB | 4MB | 67% less |
✅ Target met: 380ms < 500ms/agile-code-branch feature US-005 email-delivery
/agile-code-tdd US-005
🔴 Test: POST /invoices/:id/send triggers email with PDF attachment → ❌
🟢 Implement email sending via nodemailer → ✅
🔴 Test: email failure returns 502 with retry guidance → ❌
🟢 Add error handling with status tracking → ✅
🔴 Test: resending already-sent invoice updates sent_at → ❌
🟢 Track email delivery attempts → ✅
/agile-code-ci → commit → PR👨💻 @lead catches an important issue in review:
👨💻 @lead: PR Review — US-005
| # | Severity | Finding | Fix |
|---|----------|--------------------------------------------|-----------------------------|
| 1 | 🟡 S2 | Email failure silently swallowed — caller | Return 502 with error, |
| | | gets 200 even when email fails | log failure, mark invoice |
| | | | send_status as "failed" |
→ @dev fixes, re-runs CI ✅
/agile-code-merge → DoD → accept ✅ (3 pts)🗄️ @dba designs the payment tracking schema before implementation:
🗄️ @dba: Payment Schema Design
payments (
id SERIAL PRIMARY KEY,
invoice_id INTEGER REFERENCES invoices(id),
tenant_id INTEGER REFERENCES tenants(id),
amount DECIMAL(10,2) NOT NULL, -- ⚠️ DECIMAL, not FLOAT!
payment_date TIMESTAMP DEFAULT NOW(),
method VARCHAR(20) CHECK (method IN ('bank_transfer','card','cash'))
)
### Why DECIMAL, not FLOAT?
FLOAT: 0.1 + 0.2 = 0.30000000000000004 → rounding errors in financial totals
DECIMAL: 0.1 + 0.2 = 0.3 → exact arithmetic, required for money
### Invoice Status Logic
- paid: SUM(payments.amount) >= invoice.total
- partially_paid: SUM(payments.amount) > 0 AND < invoice.total
- overdue: due_date < NOW() AND status != 'paid'/agile-code-branch feature US-006 payment-tracking
/agile-code-tdd US-006
🔴 Test: POST /invoices/:id/payments records payment → ❌
🟢 Implement payment creation with DECIMAL arithmetic → ✅
🔴 Test: payment exceeding remaining balance → 400 → ❌
🟢 Add overpayment validation → ✅
🔴 Test: partial payment updates status to "partially_paid" → ❌
🟢 Recalculate invoice status after each payment → ✅
🔴 Test: full payment updates status to "paid" → ❌
🟢 SUM check against invoice total → ✅
/agile-code-ci → commit → PR → review → merge → DoD → accept ✅ (5 pts)/agile-sprint-status/agile-sprint-status
🔄 @sm: Sprint 2 Status
| Story | Status | Points |
|--------|------------|--------|
| US-004 | ✅ Done | 5 |
| US-005 | ✅ Done | 3 |
| US-006 | ✅ Done | 5 |
Progress: 13/13 points (100%)
Sprint Goal: ✅ On track
Velocity trend: Sprint 1 = 19, Sprint 2 = 13 (stabilizing)/agile-sprint-review
Sprint Goal Met: ✅ Yes
Velocity: 13/13 points (100%)
Cumulative: Sprint 1 (19) + Sprint 2 (13) = 32 points
/agile-sprint-retro
What went well: Spike prevented wrong PDF library choice
What went well: @lead caught silent email failure — would have been a production bug
What went well: DECIMAL for money — correct from day one
To improve: Should profile performance earlier, not after implementation
Action items:
| Action | Owner | Due |
|--------------------------------------|-------|----------|
| Add perf benchmarks to CI | @dev | Sprint 3 |
| Run OWASP audit before release | @sec | Sprint 3 |
/agile-memory-learn → Sprint 2 velocity: 13 pts, spike ROI validatedSprint 3 addresses the STRIDE findings from Sprint 0 and prepares for production release.
/agile-security-audit/agile-security-audit Scan invoice and payment code against OWASP Top 10
🛡️ @sec responds:
## /agile-security-audit — OWASP Top 10 Scan
### Findings
| # | Severity | Category | Finding | Location |
|---|----------|-----------------------|---------------------------------------|-----------------------|
| 1 | 🔴 S0 | A01: Broken Access | Tenant isolation bypass via IDOR — | GET /invoices/:id |
| | | Control | direct ID guessing bypasses middleware | (missing tenant check |
| | | | on direct-ID lookups | in findById query) |
| 2 | 🟠 S1 | A03: Injection | Invoice amounts accepted from client | POST /invoices |
| | | | without server-side validation — | (line item prices) |
| | | | negative prices allowed | |
| 3 | 🟡 S2 | A03: Injection | PDF generation doesn't sanitize HTML | PDF template |
| | | | in client_name field — XSS in PDF | rendering |
### Required Actions
Fix #1 (S0) and #2 (S1) — mandatory before release.
Fix #3 (S2) — recommended before release.The findById query fetches invoices by ID without scoping to the current tenant. An attacker who guesses an invoice ID from another tenant can access it directly. This is exactly the IDOR threat identified in the STRIDE analysis during Sprint 0.
/agile-code-tdd Fix S0: scope findById queries by tenant_id
🔴 RED:
test('GET /invoices/:id from another tenant returns 404', async () => {
// Create invoice as tenant A
const invoice = await createInvoice(tenantA);
// Request as tenant B
const res = await request(app)
.get(`/invoices/${invoice.id}`)
.set('Authorization', `Bearer ${tenantBToken}`);
expect(res.status).toBe(404); // NOT 200!
});
// ❌ FAIL — returns 200 with tenant A's invoice data
🟢 GREEN:
// Fix: Add tenant_id to ALL findById queries
findById(id, tenantId) {
return db.query(
'SELECT * FROM invoices WHERE id = $1 AND tenant_id = $2',
[id, tenantId]
);
}
// ✅ PASS — returns 404 for cross-tenant access/agile-code-tdd Fix S1: validate invoice amounts server-side
🔴 RED:
test('negative unit_price rejected with 400', async () => {
const res = await request(app)
.post('/invoices')
.set('Authorization', `Bearer ${token}`)
.send({ items: [{ description: 'Item', quantity: 1,
unit_price: -50.00 }] });
expect(res.status).toBe(400);
});
// ❌ FAIL — returns 201 with negative amount
🟢 GREEN:
// Add validation: quantity > 0, unit_price >= 0
if (item.unit_price < 0 || item.quantity <= 0) {
return res.status(400).json({
error: 'unit_price must be >= 0, quantity must be > 0'
});
}
// ✅ PASS💬 /agile-security-audit --recheck
🛡️ @sec: Re-audit results
#1 IDOR: ✅ Fixed — all findById queries now tenant-scoped
#2 Amounts: ✅ Fixed — server-side validation on all numeric fields
#3 PDF XSS: ✅ Fixed — HTML entities escaped in PDF text fields/agile-security-scan/agile-security-scan
🛡️ @sec: Dependency CVE Scan
Packages scanned: 147
Vulnerabilities found: 1
🟡 CVE-2025-XXXX in nodemailer < 6.9.8 (ReDoS in email parsing)
Fix: npm update nodemailer → 6.9.9 ✅
Post-fix scan: ✅ 0 vulnerabilities/agile-security-review/agile-security-review Review auth middleware, tenant isolation, and payment handling
🛡️ @sec: Security Review
Auth middleware: ✅ JWT validated, expiry checked, tenant_id extracted
Tenant isolation: ✅ All queries scoped (verified after S0 fix)
Payment handling: ✅ DECIMAL arithmetic, overpayment prevented
Password storage: ✅ bcrypt with cost factor 12
Overall: ✅ PASS — ready for production🎨 @ux builds the invoice creation form and verifies accessibility:
🎨 @ux: Invoice Form + Dashboard
### WCAG AA Accessibility Checklist
| Criterion | Status |
|----------------------------------|--------|
| Color contrast ratio ≥ 4.5:1 | ✅ |
| All form inputs have labels | ✅ |
| Keyboard navigation works | ✅ |
| Screen reader announces errors | ✅ |
| Focus management on add/remove | ✅ |
| Responsive: mobile invoice form | ✅ |
### Responsive Verification
- Desktop (1200px+): full table layout ✅
- Tablet (768px): stacked cards ✅
- Mobile (375px): single-column, touch-friendly ✅/agile-code-refactor/agile-code-refactor Analyze the codebase after 3 sprints. Focus on duplication, complexity, and consistency.
## /agile-code-refactor — Analysis + Refactoring
### Before
| Metric | Value |
|---------------------|----------|
| Code duplication | 14% |
| Avg cyclomatic complexity | 8.2 |
| Inconsistent error handling | 6 locations |
### Changes Made
1. Extracted tenant-scoped query builder (eliminated 8 duplicate WHERE clauses)
2. Unified error response format across all endpoints
3. Extracted validation middleware (DRY)
### After
| Metric | Before | After | Change |
|---------------------|--------|--------|--------|
| Code duplication | 14% | 3% | -79% |
| Avg cyclomatic complexity | 8.2 | 4.1 | -50% |
| Inconsistent errors | 6 | 0 | -100% |
Tests: ✅ All 47 tests still pass/agile-explore-audit/agile-explore-audit
🏗️ @arch: Architecture Health After 3 Sprints
### Health Score: 8.5/10
| Dimension | Score | Notes |
|--------------------|-------|------------------------------------------|
| Separation of concerns | 9/10 | Clean layers: routes → services → repos |
| Dependency management | 8/10 | No circular deps, clean imports |
| Testability | 9/10 | All services injectable, 94% coverage |
| Security posture | 8/10 | STRIDE mitigations implemented |
| Scalability path | 8/10 | Tenant isolation ready for schema split |
### Recommendation
Architecture is healthy. When tenant count exceeds ~500,
consider migrating to separate schemas (the #2 option from Sprint 0).
The tenant_id abstraction makes this migration straightforward./agile-sprint-review
Sprint Goal Met: ✅ Yes — security hardened, UI accessible, code refactored
Velocity: 7 points (security + refactoring stories)
Cumulative: 19 + 13 + 7 = 39 points across 3 sprints
/agile-sprint-retro
What went well: STRIDE analysis in Sprint 0 predicted exact security findings
What went well: Refactoring after 3 sprints brought duplication from 14% to 3%
What went well: All 10 roles contributed meaningfully
To improve: Should run /agile-security-audit after each sprint, not just Sprint 3
Action items:
| Action | Owner | Due |
|-------------------------------------------|-------|---------|
| Add security audit to sprint checklist | @sm | Future |
| Monitor tenant count for schema migration | @arch | Ongoing |
/agile-memory-learn → Final sprint learnings saved
→ Velocity trend: 19 → 13 → 7 (stabilized, security sprints are lower velocity)
→ STRIDE ROI: 100% of predicted threats were found and fixed/agile-ship-changelog## Changelog: v1.0.0 — Multi-Tenant Invoicing SaaS
### Sprint 1 — Foundation
- Tenant registration with unique slugs (US-001)
- User registration scoped to tenant (US-002a)
- JWT authentication with tenant claims (US-002b)
- Tenant isolation middleware — all queries tenant-scoped (US-002c)
- Invoice CRUD with line items and auto-calculated totals (US-003)
### Sprint 2 — Business Logic
- PDF invoice generation via PDFKit (US-004)
- Email delivery with PDF attachment and retry tracking (US-005)
- Payment tracking: paid, partially paid, overdue statuses (US-006)
### Sprint 3 — Security & Quality
- Fixed IDOR vulnerability in invoice lookup (S0)
- Added server-side validation for invoice amounts (S1)
- Sanitized HTML in PDF generation (S2)
- Updated nodemailer to patch CVE
- WCAG AA accessible invoice form and dashboard
- Codebase refactored: duplication 14% → 3%/agile-ship-release/agile-ship-release v1.0.0
🚀 @devops: Release v1.0.0
Branch: release/v1.0.0 from develop
CI: ✅ Green (47 tests, 0 vulnerabilities)
Merged to main ✅
Tagged: v1.0.0 ✅
Back-merged to develop ✅/agile-ship-deploy/agile-ship-deploy v1.0.0 --env production
🚀 @devops: Deployed v1.0.0 to production
Smoke tests:
✅ Tenant registration
✅ User login + JWT
✅ Invoice CRUD (tenant-scoped)
✅ PDF generation (380ms avg)
✅ Payment recording
Health check: ✅
Monitoring: 30-minute observation window started
Rollback plan: /agile-ship-rollback v0.0.0 (empty state)
→ Safety net ready if issues emerge during observation| Metric | Value |
|---|---|
| Sprints completed | 3 |
| Stories completed | 10 (including split stories) |
| Story points delivered | 39 (19 + 13 + 7) |
| Sprint goals met | ✅ All 3 |
| Security findings fixed | 3 (1 S0, 1 S1, 1 S2) |
| Release version | v1.0.0 |
| Test coverage | 94% (47 tests) |
| Roles involved | All 10: @po, @sm, @arch, @lead, @dev, @qa, @dba, @sec, @ux, @devops |
This project used nearly every command in the framework. Here's the full checklist:
| Category | Command | Used? | Where |
|---|---|---|---|
| Setup | /agile-setup-init | ✅ | Sprint 0 — project initialization |
/agile-setup-onboard | ✅ | Sprint 0 — coding rules | |
/agile-setup-health | ✅ | Sprint 0 — verify setup | |
/agile-setup-doctor | ➖ | Not needed (no config issues) | |
| Story | /agile-story-create | ✅ | All sprints — 6 stories created |
/agile-story-estimate | ✅ | Sprint planning | |
/agile-story-plan | ✅ | Every story implementation | |
/agile-story-implement | ✅ | Execution of implementation plans | |
/agile-story-split | ✅ | US-002 split into 3 stories | |
/agile-story-dod | ✅ | Every story completion | |
/agile-story-accept | ✅ | Every story acceptance | |
/agile-story-reject | ➖ | Not needed (all stories passed) | |
| Sprint | /agile-sprint-planning | ✅ | All 3 sprint starts |
/agile-sprint-status | ✅ | Sprint 2 mid-sprint check | |
/agile-sprint-refine | ✅ | Before Sprint 2 planning | |
/agile-sprint-review | ✅ | All 3 sprint ends | |
/agile-sprint-retro | ✅ | All 3 sprint ends | |
/agile-sprint-cancel | ➖ | Not needed (no cancelled sprints) | |
| Code | /agile-code-branch | ✅ | Every story branch |
/agile-code-tdd | ✅ | Every story + security fixes | |
/agile-code-ci | ✅ | Every story CI check | |
/agile-code-commit | ✅ | Every story commit | |
/agile-code-pr | ✅ | Every story PR | |
/agile-code-pr-review | ✅ | Every story review | |
/agile-code-merge | ✅ | Every story merge | |
/agile-code-refactor | ✅ | Sprint 3 — codebase cleanup | |
| Code (cont.) | /agile-code-perf | ✅ | Sprint 2 — PDF optimization |
/agile-code-debug | ➖ | Not needed (no runtime bugs) | |
| Explore | /agile-explore-brainstorm | ✅ | Sprint 0 — multi-tenant strategy |
/agile-explore-spike | ✅ | Sprint 2 — PDF library evaluation | |
/agile-explore-poc | ➖ | Not needed (spike was sufficient) | |
/agile-explore-audit | ✅ | Sprint 3 — architecture health | |
| Security | /agile-security-threat-model | ✅ | Sprint 0 — STRIDE analysis |
/agile-security-audit | ✅ | Sprint 3 — OWASP Top 10 scan | |
/agile-security-scan | ✅ | Sprint 3 — dependency CVE check | |
/agile-security-review | ✅ | Sprint 3 — auth + payment review | |
| Ship | /agile-ship-changelog | ✅ | Release — 3-sprint changelog |
/agile-ship-release | ✅ | Release — v1.0.0 | |
/agile-ship-deploy | ✅ | Release — production deploy | |
/agile-ship-hotfix | ➖ | Not needed (no production incidents) | |
/agile-ship-rollback | ➖ | Mentioned as safety net | |
| Memory | /agile-memory-remember | ✅ | Sprint 0 — architecture decision, Sprint 2 — PDF choice |
/agile-memory-recall | ✅ | Referenced across sprints | |
/agile-memory-learn | ✅ | All 3 sprint retros |
| Role | Key Contribution |
|---|---|
📋 @po | Created 6 stories with tenant-scoped acceptance criteria, split US-002, accepted all stories |
🔄 @sm | Managed 3 sprints, tracked velocity trend (19 → 13 → 7), facilitated 3 retros with actionable items |
🏗️ @arch | Evaluated multi-tenant strategies, recorded ADR, validated architecture health after 3 sprints |
👨💻 @lead | Caught silent email failure, reviewed tenant isolation code for cross-tenant leaks |
⌨️ @dev | TDD on all stories, PDF performance optimization (3s → 380ms), security fixes |
🧪 @qa | Verified tenant isolation ("can tenant A see tenant B's data?"), 94% coverage |
🗄️ @dba | Designed schema with tenant_id FKs, DECIMAL for money, composite indexes, migration review |
🛡️ @sec | STRIDE analysis predicted exact vulnerabilities, OWASP audit found IDOR, CVE scan cleared deps |
🎨 @ux | Accessible invoice form (WCAG AA), responsive dashboard, mobile-friendly layout |
🚀 @devops | CI pipeline on every story, production deploy with smoke tests + 30-min monitoring window |
You've delivered a production SaaS using the complete framework. From STRIDE threat modeling to PDF performance tuning, from tenant isolation testing to accessible invoice forms — every role contributed. This is how professional teams ship complex software: structured process, specialized roles, relentless quality gates.
The framework scales from a simple todo API (Project 01) to a multi-tenant SaaS (this project). The core loop never changes — create stories → plan sprint → branch → TDD → CI → PR → review → merge → accept → release — but the roles and commands you activate grow with the complexity of what you're building.
Why do STRIDE analysis before Sprint 1, not after?
Why use DECIMAL and not FLOAT for money in the database?
What does the tenant isolation middleware do?