@opengsd/gsd-core 1.13.0 → 1.14.0

package/gsd-core/templates/codebase/integrations.md

@@ -1,280 +0,0 @@
-# External Integrations Template
-
-Template for `.planning/codebase/INTEGRATIONS.md` - captures external service dependencies.
-
-**Purpose:** Document what external systems this codebase communicates with. Focused on "what lives outside our code that we depend on."
-
----
-
-## File Template
-
-```markdown
-# External Integrations
-
-**Analysis Date:** [YYYY-MM-DD]
-
-## APIs & External Services
-
-**Payment Processing:**
-- [Service] - [What it's used for: e.g., "subscription billing, one-time payments"]
-  - SDK/Client: [e.g., "stripe npm package v14.x"]
-  - Auth: [e.g., "API key in STRIPE_SECRET_KEY env var"]
-  - Endpoints used: [e.g., "checkout sessions, webhooks"]
-
-**Email/SMS:**
-- [Service] - [What it's used for: e.g., "transactional emails"]
-  - SDK/Client: [e.g., "sendgrid/mail v8.x"]
-  - Auth: [e.g., "API key in SENDGRID_API_KEY env var"]
-  - Templates: [e.g., "managed in SendGrid dashboard"]
-
-**External APIs:**
-- [Service] - [What it's used for]
-  - Integration method: [e.g., "REST API via fetch", "GraphQL client"]
-  - Auth: [e.g., "OAuth2 token in AUTH_TOKEN env var"]
-  - Rate limits: [if applicable]
-
-## Data Storage
-
-**Databases:**
-- [Type/Provider] - [e.g., "PostgreSQL on Supabase"]
-  - Connection: [e.g., "via DATABASE_URL env var"]
-  - Client: [e.g., "Prisma ORM v5.x"]
-  - Migrations: [e.g., "prisma migrate in migrations/"]
-
-**File Storage:**
-- [Service] - [e.g., "AWS S3 for user uploads"]
-  - SDK/Client: [e.g., "@aws-sdk/client-s3"]
-  - Auth: [e.g., "IAM credentials in AWS_* env vars"]
-  - Buckets: [e.g., "prod-uploads, dev-uploads"]
-
-**Caching:**
-- [Service] - [e.g., "Redis for session storage"]
-  - Connection: [e.g., "REDIS_URL env var"]
-  - Client: [e.g., "ioredis v5.x"]
-
-## Authentication & Identity
-
-**Auth Provider:**
-- [Service] - [e.g., "Supabase Auth", "Auth0", "custom JWT"]
-  - Implementation: [e.g., "Supabase client SDK"]
-  - Token storage: [e.g., "httpOnly cookies", "localStorage"]
-  - Session management: [e.g., "JWT refresh tokens"]
-
-**OAuth Integrations:**
-- [Provider] - [e.g., "Google OAuth for sign-in"]
-  - Credentials: [e.g., "GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET"]
-  - Scopes: [e.g., "email, profile"]
-
-## Monitoring & Observability
-
-**Error Tracking:**
-- [Service] - [e.g., "Sentry"]
-  - DSN: [e.g., "SENTRY_DSN env var"]
-  - Release tracking: [e.g., "via SENTRY_RELEASE"]
-
-**Analytics:**
-- [Service] - [e.g., "Mixpanel for product analytics"]
-  - Token: [e.g., "MIXPANEL_TOKEN env var"]
-  - Events tracked: [e.g., "user actions, page views"]
-
-**Logs:**
-- [Service] - [e.g., "CloudWatch", "Datadog", "none (stdout only)"]
-  - Integration: [e.g., "AWS Lambda built-in"]
-
-## CI/CD & Deployment
-
-**Hosting:**
-- [Platform] - [e.g., "Vercel", "AWS Lambda", "Docker on ECS"]
-  - Deployment: [e.g., "automatic on main branch push"]
-  - Environment vars: [e.g., "configured in Vercel dashboard"]
-
-**CI Pipeline:**
-- [Service] - [e.g., "GitHub Actions"]
-  - Workflows: [e.g., "test.yml, deploy.yml"]
-  - Secrets: [e.g., "stored in GitHub repo secrets"]
-
-## Environment Configuration
-
-**Development:**
-- Required env vars: [List critical vars]
-- Secrets location: [e.g., ".env.local (gitignored)", "1Password vault"]
-- Mock/stub services: [e.g., "Stripe test mode", "local PostgreSQL"]
-
-**Staging:**
-- Environment-specific differences: [e.g., "uses staging Stripe account"]
-- Data: [e.g., "separate staging database"]
-
-**Production:**
-- Secrets management: [e.g., "Vercel environment variables"]
-- Failover/redundancy: [e.g., "multi-region DB replication"]
-
-## Webhooks & Callbacks
-
-**Incoming:**
-- [Service] - [Endpoint: e.g., "/api/webhooks/stripe"]
-  - Verification: [e.g., "signature validation via stripe.webhooks.constructEvent"]
-  - Events: [e.g., "payment_intent.succeeded, customer.subscription.updated"]
-
-**Outgoing:**
-- [Service] - [What triggers it]
-  - Endpoint: [e.g., "external CRM webhook on user signup"]
-  - Retry logic: [if applicable]
-
----
-
-*Integration audit: [date]*
-*Update when adding/removing external services*
-```
-
-<good_examples>
-```markdown
-# External Integrations
-
-**Analysis Date:** 2025-01-20
-
-## APIs & External Services
-
-**Payment Processing:**
-- Stripe - Subscription billing and one-time course payments
-  - SDK/Client: stripe npm package v14.8
-  - Auth: API key in STRIPE_SECRET_KEY env var
-  - Endpoints used: checkout sessions, customer portal, webhooks
-
-**Email/SMS:**
-- SendGrid - Transactional emails (receipts, password resets)
-  - SDK/Client: @sendgrid/mail v8.1
-  - Auth: API key in SENDGRID_API_KEY env var
-  - Templates: Managed in SendGrid dashboard (template IDs in code)
-
-**External APIs:**
-- OpenAI API - Course content generation
-  - Integration method: REST API via openai npm package v4.x
-  - Auth: Bearer token in OPENAI_API_KEY env var
-  - Rate limits: 3500 requests/min (tier 3)
-
-## Data Storage
-
-**Databases:**
-- PostgreSQL on Supabase - Primary data store
-  - Connection: via DATABASE_URL env var
-  - Client: Prisma ORM v5.8
-  - Migrations: prisma migrate in prisma/migrations/
-
-**File Storage:**
-- Supabase Storage - User uploads (profile images, course materials)
-  - SDK/Client: @supabase/supabase-js v2.x
-  - Auth: Service role key in SUPABASE_SERVICE_ROLE_KEY
-  - Buckets: avatars (public), course-materials (private)
-
-**Caching:**
-- None currently (all database queries, no Redis)
-
-## Authentication & Identity
-
-**Auth Provider:**
-- Supabase Auth - Email/password + OAuth
-  - Implementation: Supabase client SDK with server-side session management
-  - Token storage: httpOnly cookies via @supabase/ssr
-  - Session management: JWT refresh tokens handled by Supabase
-
-**OAuth Integrations:**
-- Google OAuth - Social sign-in
-  - Credentials: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET (Supabase dashboard)
-  - Scopes: email, profile
-
-## Monitoring & Observability
-
-**Error Tracking:**
-- Sentry - Server and client errors
-  - DSN: SENTRY_DSN env var
-  - Release tracking: Git commit SHA via SENTRY_RELEASE
-
-**Analytics:**
-- None (planned: Mixpanel)
-
-**Logs:**
-- Vercel logs - stdout/stderr only
-  - Retention: 7 days on Pro plan
-
-## CI/CD & Deployment
-
-**Hosting:**
-- Vercel - Next.js app hosting
-  - Deployment: Automatic on main branch push
-  - Environment vars: Configured in Vercel dashboard (synced to .env.example)
-
-**CI Pipeline:**
-- GitHub Actions - Tests and type checking
-  - Workflows: .github/workflows/ci.yml
-  - Secrets: None needed (public repo tests only)
-
-## Environment Configuration
-
-**Development:**
-- Required env vars: DATABASE_URL, NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY
-- Secrets location: .env.local (gitignored), team shared via 1Password vault
-- Mock/stub services: Stripe test mode, Supabase local dev project
-
-**Staging:**
-- Uses separate Supabase staging project
-- Stripe test mode
-- Same Vercel account, different environment
-
-**Production:**
-- Secrets management: Vercel environment variables
-- Database: Supabase production project with daily backups
-
-## Webhooks & Callbacks
-
-**Incoming:**
-- Stripe - /api/webhooks/stripe
-  - Verification: Signature validation via stripe.webhooks.constructEvent
-  - Events: payment_intent.succeeded, customer.subscription.updated, customer.subscription.deleted
-
-**Outgoing:**
-- None
-
----
-
-*Integration audit: 2025-01-20*
-*Update when adding/removing external services*
-```
-</good_examples>
-
-<guidelines>
-**What belongs in INTEGRATIONS.md:**
-- External services the code communicates with
-- Authentication patterns (where secrets live, not the secrets themselves)
-- SDKs and client libraries used
-- Environment variable names (not values)
-- Webhook endpoints and verification methods
-- Database connection patterns
-- File storage locations
-- Monitoring and logging services
-
-**What does NOT belong here:**
-- Actual API keys or secrets (NEVER write these)
-- Internal architecture (that's ARCHITECTURE.md)
-- Code patterns (that's PATTERNS.md)
-- Technology choices (that's STACK.md)
-- Performance issues (that's CONCERNS.md)
-
-**When filling this template:**
-- Check .env.example or .env.template for required env vars
-- Look for SDK imports (stripe, @sendgrid/mail, etc.)
-- Check for webhook handlers in routes/endpoints
-- Note where secrets are managed (not the secrets)
-- Document environment-specific differences (dev/staging/prod)
-- Include auth patterns for each service
-
-**Useful for phase planning when:**
-- Adding new external service integrations
-- Debugging authentication issues
-- Understanding data flow outside the application
-- Setting up new environments
-- Auditing third-party dependencies
-- Planning for service outages or migrations
-
-**Security note:**
-Document WHERE secrets live (env vars, Vercel dashboard, 1Password), never WHAT the secrets are.
-</guidelines>

package/gsd-core/templates/codebase/structure.md

@@ -1,285 +0,0 @@
-# Structure Template
-
-Template for `.planning/codebase/STRUCTURE.md` - captures physical file organization.
-
-**Purpose:** Document where things physically live in the codebase. Answers "where do I put X?"
-
----
-
-## File Template
-
-```markdown
-# Codebase Structure
-
-**Analysis Date:** [YYYY-MM-DD]
-
-## Directory Layout
-
-[ASCII box-drawing tree of top-level directories with purpose - use ├── └── │ characters for tree structure only]
-
-```
-[project-root]/
-├── [dir]/          # [Purpose]
-├── [dir]/          # [Purpose]
-├── [dir]/          # [Purpose]
-└── [file]          # [Purpose]
-```
-
-## Directory Purposes
-
-**[Directory Name]:**
-- Purpose: [What lives here]
-- Contains: [Types of files: e.g., "*.ts source files", "component directories"]
-- Key files: [Important files in this directory]
-- Subdirectories: [If nested, describe structure]
-
-**[Directory Name]:**
-- Purpose: [What lives here]
-- Contains: [Types of files]
-- Key files: [Important files]
-- Subdirectories: [Structure]
-
-## Key File Locations
-
-**Entry Points:**
-- [Path]: [Purpose: e.g., "CLI entry point"]
-- [Path]: [Purpose: e.g., "Server startup"]
-
-**Configuration:**
-- [Path]: [Purpose: e.g., "TypeScript config"]
-- [Path]: [Purpose: e.g., "Build configuration"]
-- [Path]: [Purpose: e.g., "Environment variables"]
-
-**Core Logic:**
-- [Path]: [Purpose: e.g., "Business services"]
-- [Path]: [Purpose: e.g., "Database models"]
-- [Path]: [Purpose: e.g., "API routes"]
-
-**Testing:**
-- [Path]: [Purpose: e.g., "Unit tests"]
-- [Path]: [Purpose: e.g., "Test fixtures"]
-
-**Documentation:**
-- [Path]: [Purpose: e.g., "User-facing docs"]
-- [Path]: [Purpose: e.g., "Developer guide"]
-
-## Naming Conventions
-
-**Files:**
-- [Pattern]: [Example: e.g., "kebab-case.ts for modules"]
-- [Pattern]: [Example: e.g., "PascalCase.tsx for React components"]
-- [Pattern]: [Example: e.g., "*.test.ts for test files"]
-
-**Directories:**
-- [Pattern]: [Example: e.g., "kebab-case for feature directories"]
-- [Pattern]: [Example: e.g., "plural names for collections"]
-
-**Special Patterns:**
-- [Pattern]: [Example: e.g., "index.ts for directory exports"]
-- [Pattern]: [Example: e.g., "__tests__ for test directories"]
-
-## Where to Add New Code
-
-**New Feature:**
-- Primary code: [Directory path]
-- Tests: [Directory path]
-- Config if needed: [Directory path]
-
-**New Component/Module:**
-- Implementation: [Directory path]
-- Types: [Directory path]
-- Tests: [Directory path]
-
-**New Route/Command:**
-- Definition: [Directory path]
-- Handler: [Directory path]
-- Tests: [Directory path]
-
-**Utilities:**
-- Shared helpers: [Directory path]
-- Type definitions: [Directory path]
-
-## Special Directories
-
-[Any directories with special meaning or generation]
-
-**[Directory]:**
-- Purpose: [e.g., "Generated code", "Build output"]
-- Source: [e.g., "Auto-generated by X", "Build artifacts"]
-- Committed: [Yes/No - in .gitignore?]
-
----
-
-*Structure analysis: [date]*
-*Update when directory structure changes*
-```
-
-<good_examples>
-```markdown
-# Codebase Structure
-
-**Analysis Date:** 2025-01-20
-
-## Directory Layout
-
-```
-gsd-core/
-├── bin/                # Executable entry points
-├── commands/           # Slash command definitions
-│   └── gsd/           # GSD-specific commands
-├── gsd-core/     # Skill resources
-│   ├── references/    # Principle documents
-│   ├── templates/     # File templates
-│   └── workflows/     # Multi-step procedures
-├── src/               # Source code (if applicable)
-├── tests/             # Test files
-├── package.json       # Project manifest
-└── README.md          # User documentation
-```
-
-## Directory Purposes
-
-**bin/**
-- Purpose: CLI entry points
-- Contains: install.js (installer script)
-- Key files: install.js - handles npx installation
-- Subdirectories: None
-
-**commands/gsd/**
-- Purpose: Slash command definitions for Claude Code
-- Contains: *.md files (one per command)
-- Key files: new-project.md, plan-phase.md, execute-plan.md
-- Subdirectories: None (flat structure)
-
-**gsd-core/references/**
-- Purpose: Core philosophy and guidance documents
-- Contains: principles.md, questioning.md, plan-format.md
-- Key files: principles.md - system philosophy
-- Subdirectories: None
-
-**gsd-core/templates/**
-- Purpose: Document templates for .planning/ files
-- Contains: Template definitions with frontmatter
-- Key files: project.md, roadmap.md, plan.md, summary.md
-- Subdirectories: codebase/ (new - for stack/architecture/structure templates)
-
-**gsd-core/workflows/**
-- Purpose: Reusable multi-step procedures
-- Contains: Workflow definitions called by commands
-- Key files: execute-plan.md, research-phase.md
-- Subdirectories: None
-
-## Key File Locations
-
-**Entry Points:**
-- `bin/install.js` - Installation script (npx entry)
-
-**Configuration:**
-- `package.json` - Project metadata, dependencies, bin entry
-- `.gitignore` - Excluded files
-
-**Core Logic:**
-- `bin/install.js` - All installation logic (file copying, path replacement)
-
-**Testing:**
-- `tests/` - Test files (if present)
-
-**Documentation:**
-- `README.md` - User-facing installation and usage guide
-- `CLAUDE.md` - Instructions for Claude Code when working in this repo
-
-## Naming Conventions
-
-**Files:**
-- kebab-case.md: Markdown documents
-- kebab-case.js: JavaScript source files
-- UPPERCASE.md: Important project files (README, CLAUDE, CHANGELOG)
-
-**Directories:**
-- kebab-case: All directories
-- Plural for collections: templates/, commands/, workflows/
-
-**Special Patterns:**
-- {command-name}.md: Slash command definition
-- *-template.md: Could be used but templates/ directory preferred
-
-## Where to Add New Code
-
-**New Slash Command:**
-- Primary code: `commands/gsd/{command-name}.md`
-- Tests: `tests/commands/{command-name}.test.js` (if testing implemented)
-- Documentation: Update `README.md` with new command
-
-**New Template:**
-- Implementation: `gsd-core/templates/{name}.md`
-- Documentation: Template is self-documenting (includes guidelines)
-
-**New Workflow:**
-- Implementation: `gsd-core/workflows/{name}.md`
-- Usage: Reference from command with `@~/.claude/gsd-core/workflows/{name}.md`
-
-**New Reference Document:**
-- Implementation: `gsd-core/references/{name}.md`
-- Usage: Reference from commands/workflows as needed
-
-**Utilities:**
-- No utilities yet (`install.js` is monolithic)
-- If extracted: `src/utils/`
-
-## Special Directories
-
-**gsd-core/**
-- Purpose: Resources installed to ~/.claude/
-- Source: Copied by bin/install.js during installation
-- Committed: Yes (source of truth)
-
-**commands/**
-- Purpose: Slash commands installed to ~/.claude/commands/
-- Source: Copied by bin/install.js during installation
-- Committed: Yes (source of truth)
-
----
-
-*Structure analysis: 2025-01-20*
-*Update when directory structure changes*
-```
-</good_examples>
-
-<guidelines>
-**What belongs in STRUCTURE.md:**
-- Directory layout (ASCII box-drawing tree for structure visualization)
-- Purpose of each directory
-- Key file locations (entry points, configs, core logic)
-- Naming conventions
-- Where to add new code (by type)
-- Special/generated directories
-
-**What does NOT belong here:**
-- Conceptual architecture (that's ARCHITECTURE.md)
-- Technology stack (that's STACK.md)
-- Code implementation details (defer to code reading)
-- Every single file (focus on directories and key files)
-
-**When filling this template:**
-- Use `tree -L 2` or similar to visualize structure
-- Identify top-level directories and their purposes
-- Note naming patterns by observing existing files
-- Locate entry points, configs, and main logic areas
-- Keep directory tree concise (max 2-3 levels)
-
-**Tree format (ASCII box-drawing characters for structure only):**
-```
-root/
-├── dir1/           # Purpose
-│   ├── subdir/    # Purpose
-│   └── file.ts    # Purpose
-├── dir2/          # Purpose
-└── file.ts        # Purpose
-```
-
-**Useful for phase planning when:**
-- Adding new features (where should files go?)
-- Understanding project organization
-- Finding where specific logic lives
-- Following existing conventions
-</guidelines>