@pdlc-os/pdlc 0.1.0

package/templates/CONSTITUTION.md

@@ -0,0 +1,254 @@
+# Constitution
+<!-- This file is the single source of truth for how this project is built.
+     PDLC reads it before every phase. Strong defaults are already set.
+     Override only what your team explicitly agrees to change.
+     Changing this file is a Tier 2 safety event — PDLC will pause and confirm. -->
+
+**Version:** 1.0.0
+**Last updated:** <!-- YYYY-MM-DD — update whenever this file changes -->
+**Project:** <!-- Your project name -->
+
+---
+
+## 1. Tech Stack Decisions
+
+<!-- Lock in your chosen technologies here. Once set, PDLC treats these as constraints
+     and will flag any agent output that deviates from them.
+     Format: Technology — chosen option — brief rationale.
+     Example:
+       - Language: TypeScript (strict mode) — team familiarity, type safety
+       - Runtime: Node.js 22 LTS — long-term support, performance
+       - Frontend framework: Next.js 14 App Router — SSR, file-based routing
+       - Database: PostgreSQL 16 — relational, battle-tested
+       - ORM: Drizzle — lightweight, type-safe
+       - Styling: Tailwind CSS v4 — utility-first, no runtime overhead
+       - Auth: Supabase Auth — managed, supports OAuth flows
+       - Hosting: Fly.io — simple deploy, affordable egress
+-->
+
+| Layer | Technology | Rationale |
+|-------|-----------|-----------|
+| Language | <!-- e.g. TypeScript 5, strict mode --> | <!-- why --> |
+| Runtime / Framework | <!-- e.g. Node.js 22 LTS, Next.js 14 --> | <!-- why --> |
+| Database | <!-- e.g. PostgreSQL 16 --> | <!-- why --> |
+| ORM / Query layer | <!-- e.g. Drizzle ORM --> | <!-- why --> |
+| Styling | <!-- e.g. Tailwind CSS v4 --> | <!-- why --> |
+| Auth | <!-- e.g. Supabase Auth --> | <!-- why --> |
+| Testing | <!-- e.g. Vitest + Playwright --> | <!-- why --> |
+| Hosting / Deploy | <!-- e.g. Fly.io, Vercel, AWS --> | <!-- why --> |
+| CI/CD | <!-- e.g. GitHub Actions --> | <!-- why --> |
+
+---
+
+## 2. Coding Standards & Style
+
+<!-- Define the rules that all code in this project must follow.
+     Claude will apply these during Build and flag violations during Review. -->
+
+### Linting & Formatting
+
+<!-- Specify your linter/formatter and the configuration file location.
+     Example:
+       - Linter: ESLint with config at .eslintrc.json
+       - Formatter: Prettier with config at .prettierrc
+       - Pre-commit: lint-staged via .lintstagedrc
+-->
+
+- Linter: <!-- tool + config file path -->
+- Formatter: <!-- tool + config file path -->
+- Pre-commit hook: <!-- lint-staged / husky / none -->
+
+### Naming Conventions
+
+<!-- Fill in your agreed conventions. Examples shown.
+     Delete rows that don't apply to your stack. -->
+
+| Construct | Convention | Example |
+|-----------|-----------|---------|
+| Files (components) | <!-- e.g. PascalCase --> | <!-- UserCard.tsx --> |
+| Files (utilities) | <!-- e.g. kebab-case --> | <!-- format-date.ts --> |
+| Variables / functions | <!-- e.g. camelCase --> | <!-- getUserById --> |
+| Constants | <!-- e.g. SCREAMING_SNAKE_CASE --> | <!-- MAX_RETRY_COUNT --> |
+| Types / Interfaces | <!-- e.g. PascalCase, no I-prefix --> | <!-- UserProfile --> |
+| Database tables | <!-- e.g. snake_case, plural --> | <!-- user_profiles --> |
+| Database columns | <!-- e.g. snake_case --> | <!-- created_at --> |
+| CSS classes | <!-- e.g. Tailwind utilities only --> | <!-- n/a --> |
+| Environment variables | <!-- e.g. SCREAMING_SNAKE_CASE --> | <!-- DATABASE_URL --> |
+| Branch names | <!-- e.g. feature/[slug] --> | <!-- feature/user-auth --> |
+
+### General Rules
+
+<!-- Add any project-wide coding rules here. Examples:
+       - No `any` in TypeScript without explicit justification comment
+       - All functions must have JSDoc comments
+       - Max file length: 300 lines
+       - No magic numbers — use named constants
+       - No commented-out code in committed files
+       - All async operations must have error handling
+-->
+
+-
+-
+-
+
+---
+
+## 3. Architectural Constraints
+
+<!-- Document design decisions that shape the system structure.
+     These are guardrails — not just preferences. Claude will flag deviations.
+     Examples:
+       - All business logic lives in service layer, never in route handlers or components
+       - Database access only through the repository pattern — no raw SQL in services
+       - No shared mutable state between modules
+       - All external API calls must go through a dedicated adapter/client module
+       - Feature flags managed via environment variables only
+       - No circular dependencies between modules
+-->
+
+-
+-
+-
+
+---
+
+## 4. Security & Compliance Requirements
+
+<!-- List security standards and compliance obligations.
+     Phantom will verify these during every Review sub-phase.
+     Examples:
+       - OWASP Top 10 must be checked before any feature ships
+       - All user input must be validated and sanitized at the service boundary
+       - Secrets must never appear in source code or logs — use environment variables
+       - All API endpoints require authentication unless explicitly marked public
+       - PII must not be written to application logs
+       - HTTPS enforced in all environments
+       - Dependencies audited via `npm audit` before each release
+       - GDPR: user data deletion must be supported
+-->
+
+-
+-
+-
+
+---
+
+## 5. Definition of Done
+
+<!-- A task is not complete until ALL of the following are true.
+     PDLC checks this list before allowing Construction to transition to Operation.
+     Adjust to match your team's standards. -->
+
+- [ ] Code is committed on the feature branch with a conventional commit message
+- [ ] All unit tests pass (`npm test` or equivalent)
+- [ ] All integration tests pass
+- [ ] Code has been reviewed by Neo, Echo, Phantom, and Jarvis
+- [ ] Review file (`docs/pdlc/reviews/REVIEW_*.md`) exists and is human-approved
+- [ ] No `console.log` / debug statements left in committed code
+- [ ] All public functions/methods have inline documentation
+- [ ] No TypeScript errors (`tsc --noEmit` passes)
+- [ ] Linter passes with zero errors
+- [ ] PR description is complete and references the Beads task ID
+- [ ] Episode file drafted and human-approved
+<!-- Add project-specific requirements below: -->
+-
+-
+
+---
+
+## 6. Git Workflow Rules
+
+<!-- Define your branch strategy and commit message format.
+     PDLC enforces these during Build and Ship sub-phases. -->
+
+### Branch Strategy
+
+<!-- Choose one and delete the others, or define your own: -->
+
+- **Feature branch model (default)**: One branch per feature (`feature/[feature-name]`), single PR to `main` at end of Construction.
+- <!-- Alternative: Gitflow (main + develop + feature branches) -->
+- <!-- Alternative: Trunk-based (short-lived branches, merge to main daily) -->
+
+**Default branch:** `main`
+**Feature branch naming:** `feature/[kebab-case-feature-name]`
+**Merge strategy:** Merge commit (preserves full branch history)
+
+### Commit Message Format
+
+<!-- PDLC defaults to Conventional Commits. Change only if your team prefers otherwise. -->
+
+Format: `<type>(<scope>): <description>`
+
+Types: `feat` | `fix` | `chore` | `docs` | `test` | `refactor` | `perf` | `ci`
+
+Examples:
+- `feat(auth): add OAuth2 login with GitHub`
+- `fix(api): handle null user ID in profile endpoint`
+- `test(billing): add integration tests for Stripe webhook`
+
+**Breaking changes:** append `!` after type, e.g. `feat(api)!: rename /users endpoint to /accounts`
+
+### Protected Branches
+
+<!-- List branches that require PR review before merging.
+     Force-pushing to these is a Tier 1 hard block. -->
+
+- `main` — requires PR + human approval
+<!-- - `develop` — requires PR + human approval -->
+
+---
+
+## 7. Test Gates
+
+<!-- Check the boxes for test layers that MUST pass before Operation phase can begin.
+     Unchecked layers are still run and reported — they just don't hard-block the ship.
+     You can also skip a layer entirely via human instruction during Test sub-phase
+     (this is a Tier 3 logged warning). -->
+
+- [x] Unit tests
+- [x] Integration tests
+- [ ] E2E tests (real Chromium)
+- [ ] Performance / load tests
+- [ ] Accessibility checks
+- [ ] Visual regression tests
+
+<!-- Notes on gates: e.g. "E2E gate required for all features touching auth or checkout" -->
+
+---
+
+## 8. Safety Guardrail Overrides
+
+<!-- Tier 2 items that your team has deliberately downgraded to Tier 3 (logged, not blocking).
+     For each override: state the item, the reason, and the date agreed.
+     LEAVE THIS TABLE EMPTY unless your team has explicitly agreed to downgrade an item.
+
+     Default Tier 2 items (do NOT move here without team agreement):
+       - Any `rm -rf` or bulk delete
+       - `git reset --hard`
+       - Running DB migrations in production
+       - Changing CONSTITUTION.md
+       - Closing all open Beads tasks at once
+       - Any external API call that writes/posts/sends (Slack, email, webhooks)
+-->
+
+| Tier 2 Item | Downgraded Reason | Date Agreed | Agreed By |
+|-------------|-------------------|-------------|-----------|
+| <!-- item --> | <!-- reason --> | <!-- YYYY-MM-DD --> | <!-- initials --> |
+
+<!-- If no overrides, leave the table with the placeholder row above or delete the row entirely. -->
+
+---
+
+## 9. Additional Rules
+
+<!-- Anything that doesn't fit the sections above. Examples:
+       - Feature flags must be cleaned up within 2 sprints of full rollout
+       - All database migrations must be reversible (include down migration)
+       - Third-party packages require team discussion before adding
+       - Max bundle size: 200kb gzipped for initial page load
+       - All API responses follow the { data, error, meta } envelope format
+-->
+
+-
+-
+-

package/templates/INTENT.md

@@ -0,0 +1,120 @@
+# Intent
+<!-- This file defines the core purpose of the product.
+     It is set during /pdlc init and should rarely change.
+     If the fundamental problem or user changes, update this file and record why in docs/pdlc/memory/DECISIONS.md.
+     Claude reads this at the start of every Inception phase to anchor the Discover conversation. -->
+
+**Project:** <!-- Your project name -->
+**Created:** <!-- YYYY-MM-DD -->
+**Last updated:** <!-- YYYY-MM-DD -->
+
+---
+
+## Project Name
+
+<!-- Full name of the product or service. Include tagline if you have one.
+     Example: "Folia — the personal finance tracker that doesn't judge you" -->
+
+<!-- Your project name and tagline here -->
+
+---
+
+## Problem Statement
+
+<!-- Describe the core problem this product solves. Be concrete — who is suffering, what is the pain,
+     and why existing solutions fall short.
+     Keep this to 3–5 sentences. Avoid solution language.
+     Example:
+       Small business owners spend 4–6 hours per week manually reconciling expenses
+       in spreadsheets. Existing tools like QuickBooks are powerful but intimidating —
+       they require accounting knowledge most owners don't have. The gap between
+       "too simple" (a spreadsheet) and "too complex" (full accounting software) is
+       where most small businesses live and struggle. -->
+
+<!-- Your problem statement here -->
+
+---
+
+## Target User (Persona)
+
+<!-- Describe your primary user in enough detail that Claude can make product decisions on their behalf.
+     Include: who they are, what they know, what they want, and what frustrates them.
+     Example:
+       **Primary: The Bootstrapped Founder**
+       - Solo founder or 2-person team at an early-stage B2B SaaS startup
+       - Technical enough to read code but not their day job
+       - Using multiple tools (Stripe, Linear, Notion) with no unified view
+       - Frustrated by context-switching; wants answers fast, not dashboards
+       - Will pay for something that saves 30 min/day; will churn if onboarding is > 5 min -->
+
+<!-- Your target user persona here -->
+
+**Secondary users (if any):**
+<!-- Describe secondary users or leave this section blank -->
+
+---
+
+## Core Value Proposition
+
+<!-- One or two sentences that capture why your target user would choose this over alternatives.
+     Should complete the sentence: "Only [product] lets [target user] [achieve outcome] by [unique mechanism]."
+     Example:
+       "Only Folia lets bootstrapped founders see their true runway in under 30 seconds,
+       by connecting directly to their bank and Stripe — with zero manual entry." -->
+
+<!-- Your value proposition here -->
+
+---
+
+## What Success Looks Like
+
+<!-- Define concrete, measurable outcomes for the first meaningful milestone (e.g. private beta, v1.0).
+     Use specific metrics where possible.
+     Example:
+       - 50 active users in the first 30 days after launch
+       - Average session time > 8 minutes (users are exploring, not bouncing)
+       - 70% of users return within 7 days (sticky core loop working)
+       - Time-to-value < 5 minutes (user sees their data on first visit)
+       - NPS ≥ 40 from first 20 respondents
+       - Zero Sev-1 bugs in the first 14 days post-launch -->
+
+| Metric | Target | Timeframe |
+|--------|--------|-----------|
+| <!-- metric --> | <!-- target --> | <!-- e.g. 30 days post-launch --> |
+| <!-- metric --> | <!-- target --> | <!-- timeframe --> |
+| <!-- metric --> | <!-- target --> | <!-- timeframe --> |
+
+---
+
+## Out of Scope
+
+<!-- List things this product explicitly will NOT do — at least for v1.
+     This is as important as what it does. Being clear here prevents scope creep and
+     helps Claude make tighter decisions during Discover.
+     Example:
+       - No mobile app in v1 (web only, mobile-responsive)
+       - No multi-user/team support until v2
+       - No custom reporting or data exports in v1
+       - No integrations with accounting software (QuickBooks, Xero) in v1
+       - No white-labelling -->
+
+-
+-
+-
+
+---
+
+## Key Constraints
+
+<!-- Real-world constraints that Claude must respect.
+     Examples: budget, timeline, regulatory, technical, team size.
+     Example:
+       - Timeline: MVP must be shippable in 8 weeks with a 2-person team
+       - Budget: No paid infrastructure over $200/month until first revenue
+       - Regulatory: Cannot store raw bank credentials (must use OAuth / Plaid)
+       - Team: Two engineers, no dedicated designer — UI must use a component library
+       - Existing codebase: Must integrate with existing Rails API (not a greenfield) -->
+
+-
+-
+-

package/templates/OVERVIEW.md

@@ -0,0 +1,93 @@
+# Overview
+<!-- This file is the living, aggregated record of everything this product does and has shipped.
+     It is updated automatically by PDLC after every successful merge to main (during Reflect sub-phase).
+     Use it to orient yourself after time away, onboard a new teammate, or brief Claude in a fresh session.
+     Do not edit manually — let PDLC maintain it. If you need to correct something, update and note the reason. -->
+
+**Project:** <!-- Project name — set during /pdlc init -->
+**Last updated:** <!-- YYYY-MM-DDTHH:MM:SSZ — set automatically after each merge -->
+
+---
+
+## Project Summary
+
+<!-- 1–2 sentences describing what this product is and who it is for.
+     Derived from INTENT.md and updated only if the product's core purpose changes.
+     Example:
+       Folia is a personal finance tracker for bootstrapped founders that connects to Stripe and bank
+       accounts to show true runway in under 30 seconds — with zero manual entry. -->
+
+<!-- Auto-populated from INTENT.md on first run. Human-editable thereafter. -->
+
+---
+
+## Active Functionality
+
+<!-- A plain-language bullet list of everything the product currently does — as of last merge.
+     Claude updates this list after every Reflect sub-phase to reflect the current shipped state.
+     Think of it as the "what can a user actually do right now?" list.
+     Example:
+       - Users can sign up and log in via email/password or GitHub OAuth
+       - Users can connect a Stripe account and see live MRR and churn
+       - Users can set a monthly runway target and see a countdown
+       - Admins can view all users and impersonate accounts
+       - Automated weekly email digest of key metrics -->
+
+<!-- None yet — update after first feature ships. -->
+
+---
+
+## Shipped Features
+
+<!-- Auto-populated by PDLC after each successful merge to main.
+     Each row added during the Reflect sub-phase.
+     Do not delete rows — this is the permanent shipping record. -->
+
+| # | Feature | Date Shipped | Episode | PR |
+|---|---------|-------------|---------|-----|
+| <!-- 001 --> | <!-- Feature name --> | <!-- YYYY-MM-DD --> | <!-- [ep-001](../memory/episodes/001_*.md) --> | <!-- [#1](https://github.com/org/repo/pull/1) --> |
+
+---
+
+## Architecture Summary
+
+<!-- A concise description of the system architecture.
+     Updated when the architecture changes significantly (e.g. new service added, DB migration, infra change).
+     Include: tech stack layers, data flow, key integrations, and anything non-obvious.
+     Aim for 3–6 bullet points or a short paragraph. Mermaid diagrams welcome.
+     Example:
+       - Next.js 14 App Router frontend served from Vercel; API routes handle all server-side logic
+       - PostgreSQL database on Supabase; accessed via Drizzle ORM
+       - Supabase Auth handles all authentication; JWTs passed in Authorization header to API routes
+       - Stripe webhooks received at /api/webhooks/stripe, verified and queued for async processing
+       - GitHub Actions CI runs lint → test → deploy on every merge to main
+-->
+
+<!-- Auto-populated during /pdlc init from CONSTITUTION.md and updated as architecture evolves. -->
+
+---
+
+## Known Tech Debt
+
+<!-- A running list of technical debt acknowledged by the team.
+     Each item is added during Reflect when a tradeoff was consciously accepted.
+     Items are removed when resolved (with a note of when and in which episode).
+     Format: - [Added YYYY-MM-DD] [Description] — [why it was accepted] — [episode ref]
+     Example:
+       - [2026-04-10] Auth tokens stored in localStorage instead of httpOnly cookies —
+         accepted to ship faster; should move to cookies before public launch — ep-001
+       - [2026-04-17] No pagination on /api/users — table is small now; add before 1k users — ep-002
+-->
+
+<!-- None yet. -->
+
+---
+
+## Decision Log Summary
+
+<!-- A short summary of the most consequential decisions made across all episodes.
+     Full ADR-style decisions live in docs/pdlc/memory/DECISIONS.md.
+     This section highlights the 3–5 decisions most likely to affect future work.
+     Updated by Claude during Reflect. -->
+
+<!-- None yet — see docs/pdlc/memory/DECISIONS.md for the full log. -->

package/templates/PRD.md

@@ -0,0 +1,212 @@
+# PRD: [Feature Name]
+<!-- Replace [Feature Name] with the full name of the feature.
+     File naming convention: PRD_[feature-name]_[YYYY-MM-DD].md
+     This file lives at: docs/pdlc/prds/PRD_[feature-name]_[YYYY-MM-DD].md
+     Claude auto-generates a draft of this file at the end of the Discover sub-phase.
+     Human reviews and approves the draft before Design begins. -->
+
+**Date:** <!-- YYYY-MM-DD -->
+**Status:** Draft <!-- Change to "Approved" after human sign-off; do not proceed to Design until Approved -->
+**Feature slug:** <!-- kebab-case-feature-name — used in file paths and branch names -->
+**Episode:** <!-- Will be assigned after delivery, e.g. ep-003 -->
+
+---
+
+## Overview
+
+<!-- 2–4 sentences summarising what this feature is and why it is being built now.
+     Should connect directly to a goal in INTENT.md.
+     Example:
+       This feature adds GitHub OAuth login as an alternative to email/password sign-up.
+       It reduces friction for technical users who already have a GitHub account and
+       eliminates the need to remember yet another password. Shipped before the public launch
+       to ensure the primary target audience (developers) can onboard in under 60 seconds. -->
+
+<!-- Auto-generated by Claude from Discover conversation. Review and edit as needed. -->
+
+---
+
+## Problem Statement
+
+<!-- The specific problem this feature solves. More granular than the product-level problem in INTENT.md.
+     Be concrete: what is the user unable to do today, and what is the cost of that gap?
+     Example:
+       Currently users must create a new email/password account to use the product.
+       40% of our target users (developers) use "Sign in with GitHub" as their preferred
+       auth method. Forcing a password creates friction, increases drop-off, and introduces
+       a support burden (password resets). -->
+
+<!-- Auto-generated by Claude from Discover conversation. Review and edit as needed. -->
+
+---
+
+## Target User
+
+<!-- Who specifically benefits from this feature? Reference the persona(s) from INTENT.md.
+     If this feature is for a subset of users (e.g. admins only), say so explicitly. -->
+
+<!-- Auto-generated by Claude from Discover conversation. Review and edit as needed. -->
+
+---
+
+## Requirements
+
+<!-- Numbered list of functional requirements.
+     Each requirement should be specific and testable — it will become acceptance criteria and BDD stories.
+     Use "must", "should", "may" for priority signalling (RFC 2119 style).
+     Example:
+       1. The system MUST provide a "Sign in with GitHub" button on the login page.
+       2. The system MUST redirect users to GitHub's OAuth authorization page when the button is clicked.
+       3. The system MUST create a new user account if the GitHub email is not already registered.
+       4. The system MUST link the GitHub identity to an existing account if the email matches.
+       5. The system SHOULD display the user's GitHub avatar as their profile photo after login.
+       6. The system MAY allow users to unlink their GitHub account from settings. -->
+
+1.
+2.
+3.
+
+---
+
+## Assumptions
+
+<!-- Things believed to be true that, if wrong, would change the requirements.
+     Surfaced during the Discover Socratic session.
+     Example:
+       - GitHub OAuth app credentials (client ID + secret) will be provisioned before Build begins
+       - Users who sign up via GitHub implicitly accept the terms of service (no separate checkbox needed)
+       - Email is always available from the GitHub OAuth response (some GitHub accounts hide it — needs handling)
+       - This feature does not need to support GitHub Enterprise -->
+
+-
+-
+-
+
+---
+
+## Acceptance Criteria
+
+<!-- Numbered list of conditions that must be true for this feature to be considered done.
+     These are binary — pass or fail. Echo uses these to verify test coverage during Review.
+     Example:
+       1. A user with a valid GitHub account can log in and land on their dashboard in under 5 seconds.
+       2. A new account is created on first login with the correct email, name, and avatar pulled from GitHub.
+       3. Logging in with GitHub on an email that already has a local account links the accounts without
+          creating a duplicate.
+       4. If GitHub OAuth fails or is denied, the user sees a human-readable error and is not logged in.
+       5. The "Sign in with GitHub" button is visible and accessible (keyboard-navigable, ARIA-labelled). -->
+
+1.
+2.
+3.
+
+---
+
+## User Stories
+
+<!-- BDD-format stories using Given / When / Then.
+     Each story maps to one or more acceptance criteria above (cross-reference by number).
+     Label each story with an ID for reference in Beads tasks.
+     Example:
+       **US-001: Happy path GitHub login**
+       *Acceptance criteria: 1, 2*
+       Given a user is on the login page
+       When they click "Sign in with GitHub" and authorize the app on GitHub
+       Then they are redirected back to the dashboard, logged in as themselves
+
+       **US-002: Duplicate email — account linking**
+       *Acceptance criteria: 3*
+       Given a user already has an account with email alice@example.com
+       When they click "Sign in with GitHub" using an account with the same email
+       Then their GitHub identity is linked to the existing account and they are logged in
+       And no duplicate account is created
+
+       **US-003: OAuth failure**
+       *Acceptance criteria: 4*
+       Given a user is on the login page
+       When they click "Sign in with GitHub" but deny authorization on the GitHub page
+       Then they are returned to the login page
+       And they see the message "GitHub login was cancelled. Please try again or use email."
+       And they remain logged out -->
+
+**US-001: [Story title]**
+*Acceptance criteria: <!-- reference AC numbers -->*
+Given <!-- starting context -->
+When <!-- action taken -->
+Then <!-- expected outcome -->
+
+**US-002: [Story title]**
+*Acceptance criteria: <!-- reference AC numbers -->*
+Given <!-- starting context -->
+When <!-- action taken -->
+Then <!-- expected outcome -->
+
+---
+
+## Non-Functional Requirements
+
+<!-- Performance, security, accessibility, and operational requirements.
+     These become test criteria for Echo (tests), Phantom (security), and the Test sub-phase.
+     Example:
+       - OAuth redirect round-trip MUST complete in under 3 seconds on a standard broadband connection
+       - No GitHub access tokens may be stored in the database or logged
+       - The login flow MUST be keyboard-accessible and meet WCAG 2.1 AA
+       - The feature MUST degrade gracefully if the GitHub OAuth service is unavailable
+         (fallback to email/password, not a blank screen)
+       - Rate limiting: no more than 10 OAuth attempts per IP per minute -->
+
+-
+-
+-
+
+---
+
+## Out of Scope
+
+<!-- Explicitly list what this PRD does NOT cover.
+     Prevents scope creep and sets clear expectations for what comes later.
+     Example:
+       - Google / Apple / other OAuth providers (separate feature)
+       - GitHub Enterprise support
+       - Two-factor authentication (2FA) via GitHub
+       - Unlinking GitHub from an existing account (follow-up feature)
+       - Account merging when two separate accounts have the same email via different providers -->
+
+-
+-
+-
+
+---
+
+## Design Docs
+
+<!-- Links to design documents produced during the Design sub-phase.
+     These are auto-populated by PDLC after Design is complete. Do not fill in during Define. -->
+
+- Architecture: <!-- [ARCHITECTURE.md](../../design/[feature-name]/ARCHITECTURE.md) -->
+- Data model: <!-- [data-model.md](../../design/[feature-name]/data-model.md) -->
+- API contracts: <!-- [api-contracts.md](../../design/[feature-name]/api-contracts.md) -->
+- Additional: <!-- links to any other design files, UI direction, sequence diagrams, etc. -->
+
+---
+
+## Related Episodes
+
+<!-- Links to episodic memory files for prior features that this feature builds on or is affected by.
+     Auto-populated by PDLC when relevant episodes are detected. Review and supplement as needed.
+     Example:
+       - [ep-001: User Auth foundation](../memory/episodes/001_user_auth_2026-04-03.md)
+         — GitHub OAuth builds on the auth session infrastructure introduced here -->
+
+<!-- None yet. -->
+
+---
+
+## Approval
+
+<!-- Do not proceed to Design until a human has approved this PRD.
+     Record the approver's name/initials and date. -->
+
+**Approved by:** <!-- Name / initials -->
+**Date approved:** <!-- YYYY-MM-DD -->
+**Notes:** <!-- Any conditions or caveats attached to approval -->