@aslomon/effectum 0.1.0

package/workshop/knowledge/04-examples.md

@@ -0,0 +1,435 @@
+# PRD Examples
+
+Three complete examples showing the progression from simple to complex, all agent-ready.
+
+---
+
+## Example A: Simple Feature (single PRD, ~20 iterations)
+
+````markdown
+# PRD: User Profile Avatar Upload
+
+## Problem
+
+Users cannot upload a profile picture. Profiles show a generic placeholder,
+making it harder for team members to identify each other in a multi-user workspace.
+
+## Goal
+
+Users can upload, preview, and change their profile picture. The avatar is displayed
+across the application wherever the user's identity appears.
+
+## User Stories
+
+- As a user, I want to upload a profile picture so that others can recognize me
+- As a user, I want to preview my image before confirming the upload so that I can ensure it looks right
+- As a user, I want to see a fallback avatar when no image is uploaded so that the UI remains consistent
+
+## Acceptance Criteria
+
+- [ ] AC1: Upload accepts JPG, PNG, and WebP files up to 5MB
+- [ ] AC2: Given a file larger than 5MB, When the user attempts upload, Then an error message is shown
+- [ ] AC3: Image is stored in Supabase Storage bucket "avatars"
+- [ ] AC4: Avatar URL is persisted in the user profile (profiles.avatar_url)
+- [ ] AC5: Preview is shown immediately after file selection, before upload confirmation
+- [ ] AC6: Fallback avatar displays user initials when no image is uploaded
+- [ ] AC7: Avatar is displayed in the header, team member list, and comment threads
+
+## Scope
+
+### In Scope
+
+- Upload component with drag-and-drop and file picker
+- Image preview before upload
+- Supabase Storage integration
+- Profile update (avatar_url field)
+- Fallback avatar component
+- Display in header, team list, and comments
+
+### Out of Scope
+
+- Image cropping or editing
+- Image filters or effects
+- Social media avatar import
+- Avatar history or versioning
+- Animated avatars (GIF support)
+
+## Data Model
+
+### profiles (existing table — add column)
+
+| Column     | Type | Constraints | Description                       |
+| ---------- | ---- | ----------- | --------------------------------- |
+| avatar_url | text | NULL        | URL to avatar in Supabase Storage |
+
+### Supabase Storage
+
+- Bucket: "avatars"
+- Path: `{org_id}/{user_id}/avatar.{ext}`
+- Max size: 5MB
+- Allowed MIME types: image/jpeg, image/png, image/webp
+- RLS: Users can only upload/delete their own avatar
+
+## API Design
+
+### POST /api/profile/avatar
+
+**Purpose:** Upload or replace profile avatar
+
+**Request:** multipart/form-data with "file" field
+
+**Response (200):**
+
+```json
+{
+  "data": {
+    "avatar_url": "https://[project].supabase.co/storage/v1/object/public/avatars/..."
+  }
+}
+```
+````
+
+**Errors:**
+
+- 400: File too large or invalid MIME type
+- 401: Not authenticated
+- 500: Storage upload failed
+
+### DELETE /api/profile/avatar
+
+**Purpose:** Remove profile avatar, revert to fallback
+
+**Response (200):**
+
+```json
+{
+  "data": { "avatar_url": null }
+}
+```
+
+## Quality Gates
+
+- Build: `pnpm build` — 0 errors
+- Types: `tsc --noEmit` — 0 errors
+- Tests: `pnpm vitest run` — all pass, 80%+ coverage on new code
+- Lint: `pnpm lint` — 0 errors
+
+## Autonomy Rules
+
+- Design: Follow DESIGN.md for avatar sizing, border radius, and colors
+- Libraries: Use existing project dependencies only
+- Architecture: Follow existing patterns in src/lib/ and src/components/
+- On ambiguity: Decide autonomously
+
+## Completion Promise
+
+"All acceptance criteria met, build passes, all tests pass, 0 lint errors, no console.log in production code"
+
+````
+
+---
+
+## Example B: Standard Feature (single PRD, ~30 iterations)
+
+```markdown
+# PRD: Team Invitation System
+
+## Problem
+
+New team members can only be added manually via direct database insertion.
+This is error-prone, unauditable, and requires developer involvement for
+every new hire or collaborator.
+
+## Goal
+
+Admins can send email invitations from the settings page. Invited users receive
+a magic link and are automatically assigned to the team with the correct role
+upon acceptance. Pending invitations are visible and revocable.
+
+## User Stories
+
+- As an admin, I want to invite team members via email so that onboarding is self-service
+- As an invitee, I want to join via a link without manual registration so that joining is frictionless
+- As an admin, I want to see pending invitations and their status so that I can track onboarding
+- As an admin, I want to revoke pending invitations so that I can correct mistakes
+
+## Acceptance Criteria
+
+- [ ] AC1: Admin can enter one or more email addresses and assign a role (member, admin)
+- [ ] AC2: Each invitation generates a single-use token valid for 24 hours
+- [ ] AC3: Given an expired token, When the invitee clicks the link, Then they see an expiration message
+- [ ] AC4: Email is sent via Supabase Edge Function with invitation link
+- [ ] AC5: Given a new user (no account), When they accept, Then they are redirected to onboarding
+- [ ] AC6: Given an existing user, When they accept, Then they are directly assigned to the team
+- [ ] AC7: Admin sees a list of pending invitations with email, role, status, and expiration
+- [ ] AC8: Admin can revoke any pending invitation (immediate invalidation)
+- [ ] AC9: Maximum 50 pending invitations per team
+- [ ] AC10: Rate limit: 10 invitations per hour per admin
+- [ ] AC11: Given a duplicate email (already invited or already a member), When the admin invites, Then an appropriate error message is shown
+
+## Scope
+
+### In Scope
+
+- Invitation CRUD (create, list, revoke)
+- Token generation and validation
+- Email sending via Edge Function
+- Invitation acceptance flow (new + existing users)
+- Admin UI in settings page
+- Rate limiting and invitation limits
+
+### Out of Scope
+
+- Bulk CSV import
+- Custom invitation email templates
+- Invitation analytics or reporting
+- Role management beyond member/admin
+- SSO-based invitations
+- Re-sending expired invitations (user must create new invitation)
+
+## Data Model
+
+### invitations
+
+| Column | Type | Constraints | Description |
+|--------|------|-------------|-------------|
+| id | uuid | PK, default gen_random_uuid() | |
+| org_id | uuid | FK → organizations.id, NOT NULL | Tenant isolation |
+| email | text | NOT NULL | Invitee email address |
+| role | text | NOT NULL, CHECK (role IN ('member', 'admin')) | Assigned role |
+| token | text | NOT NULL, UNIQUE | Single-use invitation token |
+| status | text | NOT NULL, default 'pending', CHECK (status IN ('pending', 'accepted', 'revoked', 'expired')) | |
+| invited_by | uuid | FK → profiles.id, NOT NULL | Admin who created |
+| expires_at | timestamptz | NOT NULL | Token expiration (created_at + 24h) |
+| accepted_at | timestamptz | NULL | When invitation was accepted |
+| created_at | timestamptz | NOT NULL, default now() | |
+
+### RLS Policies
+
+- SELECT: Users can view invitations where org_id matches their org
+- INSERT: Only admins of the same org can create invitations
+- UPDATE: Only admins of the same org can update status (revoke)
+- DELETE: Not allowed (use status = 'revoked' instead)
+
+### Indexes
+
+- UNIQUE on (org_id, email) WHERE status = 'pending' (prevent duplicate pending invitations)
+- INDEX on token (lookup during acceptance)
+- INDEX on (org_id, status) (admin list view)
+
+## API Design
+
+### POST /api/invitations
+
+Create one or more invitations.
+
+Request:
+```json
+{
+  "invitations": [
+    { "email": "user@example.com", "role": "member" },
+    { "email": "admin@example.com", "role": "admin" }
+  ]
+}
+````
+
+Response (201):
+
+```json
+{
+  "data": {
+    "created": 2,
+    "failed": 0,
+    "invitations": [{ "id": "...", "email": "...", "status": "pending" }]
+  }
+}
+```
+
+Errors:
+
+- 400: Invalid email format, invalid role, duplicate email
+- 403: Not an admin
+- 429: Rate limit exceeded (10/hour)
+
+### GET /api/invitations
+
+List invitations for current org. Query params: ?status=pending
+
+Response (200):
+
+```json
+{
+  "data": [
+    {
+      "id": "...",
+      "email": "...",
+      "role": "member",
+      "status": "pending",
+      "expires_at": "...",
+      "invited_by": { "name": "..." }
+    }
+  ]
+}
+```
+
+### DELETE /api/invitations/:id
+
+Revoke invitation (sets status to 'revoked').
+
+Response (200):
+
+```json
+{ "data": { "id": "...", "status": "revoked" } }
+```
+
+### POST /api/invitations/accept
+
+Redeem invitation token.
+
+Request:
+
+```json
+{ "token": "abc123..." }
+```
+
+Response (200): Redirect URL to dashboard or onboarding
+
+Errors:
+
+- 400: Invalid or expired token
+- 409: Already accepted
+
+## Constraints
+
+- Use Supabase Auth for magic links (no external email providers)
+- Edge Function for email sending (supabase/functions/send-invitation/)
+- Token format: 32 random bytes, hex-encoded
+- Rate limiting: Implemented via database count query, not in-memory
+
+## Quality Gates
+
+- Build: `pnpm build` — 0 errors
+- Types: `tsc --noEmit` — 0 errors
+- Tests: `pnpm vitest run` — all pass, 80%+ coverage
+- Lint: `pnpm lint` — 0 errors
+- E2E: `npx playwright test tests/e2e/invitations.spec.ts` — all pass
+- RLS: Supabase security advisor — no warnings
+
+## Autonomy Rules
+
+- Design: Follow DESIGN.md
+- Libraries: Use existing project dependencies
+- Architecture: Follow patterns in src/lib/billing/ for service layer
+- Edge Functions: Follow patterns in supabase/functions/
+- On ambiguity: Decide autonomously, document decisions in code comments
+
+## Completion Promise
+
+"All acceptance criteria met, migration applied, RLS policies active, all tests pass, build succeeds, 0 lint errors, types generated"
+
+````
+
+---
+
+## Example C: Large Project — Vision + Multiple PRDs
+
+### Project Vision Document
+
+```markdown
+# Project Vision: TaskFlow — AI-Powered Project Management
+
+## Problem
+
+Small teams (3-15 people) use spreadsheets and chat messages to manage projects.
+They lack visibility into progress, miss deadlines, and waste time in status meetings.
+Existing tools (Jira, Asana) are too complex and expensive for their needs.
+
+## Goal
+
+A lightweight project management tool where teams can organize work, track progress,
+and get AI-generated insights — without enterprise complexity. Launch MVP within 8 weeks.
+
+## Target Users
+
+- **Team Lead (primary):** Manages 3-15 people, needs progress visibility, assigns work
+- **Team Member:** Needs clear task list, updates status, logs time
+- **Stakeholder (secondary):** Needs high-level progress reports, no daily interaction
+
+## Tech Stack
+
+- Frontend: Next.js 16, App Router, TypeScript, Tailwind CSS v4, Shadcn UI
+- Backend: Supabase (DB, Auth, Storage, Edge Functions, Realtime)
+- AI: Claude API for insights and summaries
+- Hosting: Vercel
+- Auth: Supabase Auth (email + Google OAuth)
+
+## Constraints
+
+- Multi-tenant from day one (org_id on every table)
+- GDPR-compliant (EU data residency option in v2)
+- Mobile-responsive (not native app)
+- Budget: Supabase Pro plan, Vercel Pro plan
+
+## PRD Overview
+
+| PRD | Name | Description | Dependencies |
+|-----|------|-------------|--------------|
+| 001 | Auth & Org Setup | Registration, login, org creation, member management | None |
+| 002 | Projects & Tasks | Create projects, manage tasks, assign members, track status | 001 |
+| 003 | AI Insights | AI-generated project summaries, risk detection, suggestions | 001, 002 |
+| 004 | Notifications & Activity | Real-time notifications, activity feed, email digests | 001, 002 |
+
+## Dependency Graph
+
+001-Auth ──► 002-Projects & Tasks ──► 003-AI Insights
+    │              │
+    │              └──────────────► 004-Notifications
+    └──────────────────────────────►
+
+## Roadmap
+
+| Phase | PRDs | Milestone | Effort |
+|-------|------|-----------|--------|
+| 1 | 001 | Users can register, create org, invite members | Small (20 iter) |
+| 2 | 002 | Teams can create projects and manage tasks | Standard (30 iter) |
+| 3 | 003, 004 (parallel) | AI insights + notifications functional | Large (40 iter each) |
+````
+
+### Requirements Map (excerpt)
+
+```markdown
+## v1 (Must-Have)
+
+| ID    | Requirement                    | PRD |
+| ----- | ------------------------------ | --- |
+| R-001 | Email registration + login     | 001 |
+| R-002 | Google OAuth login             | 001 |
+| R-003 | Organization creation          | 001 |
+| R-004 | Member invitation (email)      | 001 |
+| R-005 | Project CRUD                   | 002 |
+| R-006 | Task CRUD with status workflow | 002 |
+| R-007 | Task assignment to members     | 002 |
+| R-008 | Kanban board view              | 002 |
+| R-009 | AI project summary             | 003 |
+| R-010 | In-app notifications           | 004 |
+
+## v2
+
+| ID    | Requirement            | PRD |
+| ----- | ---------------------- | --- |
+| R-011 | Time tracking          | 002 |
+| R-012 | AI risk detection      | 003 |
+| R-013 | Email digest           | 004 |
+| R-014 | Gantt chart view       | 002 |
+| R-015 | Custom fields on tasks | 002 |
+
+## Out of Scope
+
+- Native mobile apps
+- Custom workflows / automation builder
+- Integration marketplace (Slack, GitHub, etc.)
+- White-label / custom branding
+- On-premise deployment
+```
+
+Each individual PRD (001, 002, 003, 004) would then follow the full template from Example B, with complete data models, API designs, and quality gates.

package/workshop/knowledge/05-quality-checklist.md

@@ -0,0 +1,166 @@
+# PRD Quality Checklist
+
+Verification checklist to ensure a PRD is complete, consistent, and agent-ready before handoff.
+
+---
+
+## Completeness Check
+
+### Problem & Goal
+
+- [ ] Problem statement explains WHO is affected and WHY it matters
+- [ ] Goal is measurable (you can verify it was achieved)
+- [ ] Business context is provided (not just technical motivation)
+
+### User Stories
+
+- [ ] Each story follows "As a [role], I want to [action], so that [benefit]"
+- [ ] All identified user personas have at least one story
+- [ ] Stories cover the happy path AND error/edge cases
+
+### Acceptance Criteria
+
+- [ ] Each criterion is independently testable by an automated test
+- [ ] Complex criteria use Given/When/Then format
+- [ ] No vague terms ("user-friendly", "fast", "intuitive") — replaced with concrete metrics
+- [ ] Edge cases are covered (empty state, max limits, invalid input, concurrent access)
+- [ ] Error scenarios are specified (what happens when things go wrong)
+- [ ] Each criterion maps to exactly one behavior (no compound "X and Y" criteria)
+
+### Scope
+
+- [ ] In-scope list is exhaustive (everything being built is listed)
+- [ ] Out-of-scope list includes items someone might reasonably expect
+- [ ] No overlap between in-scope and out-of-scope
+- [ ] Non-Goals are explicitly stated
+
+### Data Model
+
+- [ ] All tables are defined with columns, types, and constraints
+- [ ] Primary keys, foreign keys, and indexes are specified
+- [ ] Multi-tenant isolation is addressed (org_id where needed)
+- [ ] RLS policies are defined for every table
+- [ ] Timestamps (created_at, updated_at) are included
+- [ ] Soft delete vs. hard delete strategy is documented
+- [ ] Relations between tables are documented
+
+### API Design
+
+- [ ] Every CRUD operation has a defined endpoint
+- [ ] Request and response shapes are specified with field types
+- [ ] Error responses are documented (400, 401, 403, 404, 429, 500)
+- [ ] Authentication requirements are stated per endpoint
+- [ ] Rate limiting is specified where applicable
+- [ ] Pagination strategy is defined for list endpoints
+
+---
+
+## Consistency Check
+
+- [ ] Acceptance criteria align with user stories (every story has criteria)
+- [ ] Data model supports all acceptance criteria (no missing fields/tables)
+- [ ] API endpoints cover all acceptance criteria (no missing operations)
+- [ ] Scope boundaries match acceptance criteria (nothing in AC that is out of scope)
+- [ ] Constraints are reflected in the data model and API design
+
+---
+
+## Agent-Ready Check
+
+### Quality Gates
+
+- [ ] Build command is specified (e.g., `pnpm build`)
+- [ ] Type check command is specified (e.g., `tsc --noEmit`)
+- [ ] Test command is specified (e.g., `pnpm vitest run`)
+- [ ] Lint command is specified (e.g., `pnpm lint`)
+- [ ] E2E test command is specified (if applicable)
+- [ ] Coverage threshold is defined (e.g., 80%+)
+- [ ] Project-specific checks are listed
+
+### Autonomy Rules
+
+- [ ] Design decision authority is clear (follow DESIGN.md / free to decide / ask)
+- [ ] Library choice authority is clear (existing only / free to add / predefined)
+- [ ] Architecture pattern references are provided (e.g., "follow src/lib/billing/")
+- [ ] Ambiguity handling is defined (decide autonomously / stop and ask)
+
+### Completion Promise
+
+- [ ] Promise is a single, verifiable statement
+- [ ] Promise covers ALL quality gates
+- [ ] Promise is specific enough that it cannot be true if any AC fails
+- [ ] Promise format works with the target system (Ralph Loop / GSD / manual)
+
+---
+
+## Architecture Compliance
+
+These checks ensure the PRD aligns with the autonomous workflow's architecture principles.
+
+- [ ] DB changes specify migration approach (`apply_migration`, not raw DDL)
+- [ ] TypeScript types will be generated from schema (not hand-written)
+- [ ] Type-safety chain is documented: DB schema → generated types → Zod schemas → API → frontend
+- [ ] Multi-tenancy is addressed: `org_id` on relevant tables with RLS
+- [ ] Service layer is separated from UI components (no business logic in components)
+- [ ] Server Components are the default; Client Components are justified with reason
+- [ ] All API inputs are validated with Zod
+- [ ] Result pattern `{ data, error }` is used for operations that can fail
+- [ ] API endpoints expose clean REST/RPC interfaces (agent-native principle)
+
+---
+
+## Red Flags — Issues That Will Cause Implementation Problems
+
+| Red Flag                     | Problem                      | Fix                                            |
+| ---------------------------- | ---------------------------- | ---------------------------------------------- |
+| "Should be fast"             | Not testable                 | Define: "API response < 200ms at p95"          |
+| "Nice UI"                    | Subjective                   | Reference DESIGN.md or provide wireframes      |
+| "Handle errors gracefully"   | Vague                        | Specify each error case with expected behavior |
+| No data model                | Agent must guess schema      | Define tables, fields, types, relations        |
+| No out-of-scope              | Scope creep guaranteed       | List 3-5 explicit exclusions                   |
+| Compound AC: "X and Y and Z" | Untestable as single unit    | Split into separate criteria                   |
+| "Similar to [product]"       | Ambiguous without specifics  | Describe exact behaviors to replicate          |
+| No API error responses       | Agent invents error handling | Define status codes and messages               |
+| Missing auth requirements    | Agent guesses access control | Specify per-endpoint authentication            |
+| No RLS policies              | Security gap                 | Define row-level security for every table      |
+
+---
+
+## Final Verification Questions
+
+Ask these before declaring the PRD complete:
+
+1. **Can a developer implement this without asking a single question?**
+   If not, what is missing?
+
+2. **Can every acceptance criterion be verified by running a command?**
+   If not, rewrite the criterion to be testable.
+
+3. **Is it clear what is NOT being built?**
+   If not, add explicit out-of-scope items.
+
+4. **Could two developers read this PRD and build the same thing?**
+   If not, add specificity where interpretations diverge.
+
+5. **Does the data model support every acceptance criterion?**
+   Trace each AC to the fields and tables it requires.
+
+6. **Are all [ASSUMPTION] and [NEEDS CLARIFICATION] tags resolved?**
+   If not, resolve them before handoff.
+
+---
+
+## PRD Readiness Scoring
+
+| Category                    | Weight | Score (0-3) | Notes                                                     |
+| --------------------------- | ------ | ----------- | --------------------------------------------------------- |
+| Problem clarity             | 10%    |             | 0=missing, 1=vague, 2=clear, 3=compelling                 |
+| Acceptance criteria quality | 20%    |             | 0=missing, 1=vague, 2=testable, 3=Given/When/Then         |
+| Scope definition            | 10%    |             | 0=missing, 1=in-scope only, 2=+out-of-scope, 3=+non-goals |
+| Data model completeness     | 20%    |             | 0=missing, 1=tables only, 2=+relations, 3=+RLS+indexes    |
+| API design                  | 15%    |             | 0=missing, 1=endpoints only, 2=+shapes, 3=+errors+auth    |
+| Agent-ready extension       | 15%    |             | 0=missing, 1=quality gates, 2=+autonomy, 3=+promise       |
+| Architecture compliance     | 10%    |             | 0=missing, 1=partial, 2=most checks, 3=all checks pass    |
+
+**Minimum for handoff: Average score >= 2.0**
+**Recommended for autonomous execution: Average score >= 2.5**