diff --git a/get-shit-done/templates/codebase/architecture.md b/get-shit-done/templates/codebase/architecture.md index 184409170..3e64b5360 100644 --- a/get-shit-done/templates/codebase/architecture.md +++ b/get-shit-done/templates/codebase/architecture.md @@ -124,18 +124,21 @@ Template for `.planning/codebase/ARCHITECTURE.md` - captures conceptual code org **Command Layer:** - Purpose: Parse user input and route to appropriate handler - Contains: Command definitions, argument parsing, help text +- Location: `src/commands/*.ts` - Depends on: Service layer for business logic -- Used by: CLI entry point (src/index.ts) +- Used by: CLI entry point (`src/index.ts`) **Service Layer:** - Purpose: Core business logic - Contains: FileService, TemplateService, InstallService +- Location: `src/services/*.ts` - Depends on: File system utilities, external tools - Used by: Command handlers **Utility Layer:** - Purpose: Shared helpers and abstractions - Contains: File I/O wrappers, path resolution, string formatting +- Location: `src/utils/*.ts` - Depends on: Node.js built-ins only - Used by: Service layer @@ -145,8 +148,8 @@ Template for `.planning/codebase/ARCHITECTURE.md` - captures conceptual code org 1. User runs: `gsd new-project` 2. Commander parses args and flags -3. Command handler invoked (commands/new-project.ts) -4. Handler calls service methods (e.g., ProjectService.create()) +3. Command handler invoked (`src/commands/new-project.ts`) +4. Handler calls service methods (`src/services/project.ts` → `create()`) 5. Service reads templates, processes files, writes output 6. Results logged to console 7. Process exits with status code @@ -160,12 +163,12 @@ Template for `.planning/codebase/ARCHITECTURE.md` - captures conceptual code org **Service:** - Purpose: Encapsulate business logic for a domain -- Examples: FileService, TemplateService, ProjectService +- Examples: `src/services/file.ts`, `src/services/template.ts`, `src/services/project.ts` - Pattern: Singleton-like (imported as modules, not instantiated) **Command:** - Purpose: CLI command definition -- Examples: new-project, plan-phase, execute-plan +- Examples: `src/commands/new-project.ts`, `src/commands/plan-phase.ts` - Pattern: Commander.js command registration **Template:** @@ -176,12 +179,12 @@ Template for `.planning/codebase/ARCHITECTURE.md` - captures conceptual code org ## Entry Points **CLI Entry:** -- Location: src/index.ts +- Location: `src/index.ts` - Triggers: User runs `gsd ` - Responsibilities: Register commands, parse args, display help **Commands:** -- Location: src/commands/*.ts +- Location: `src/commands/*.ts` - Triggers: Matched command from CLI - Responsibilities: Validate input, call services, format output @@ -229,11 +232,14 @@ Template for `.planning/codebase/ARCHITECTURE.md` - captures conceptual code org - Cross-cutting concerns (logging, auth, validation) **What does NOT belong here:** -- Specific file paths (that's STRUCTURE.md) +- Exhaustive file listings (that's STRUCTURE.md) - Technology choices (that's STACK.md) - Line-by-line code walkthrough (defer to code reading) - Implementation details of specific features +**File paths ARE welcome:** +Include file paths as concrete examples of abstractions. Use backtick formatting: `src/services/user.ts`. This makes the architecture document actionable for Claude when planning. + **When filling this template:** - Read main entry points (index, server, main) - Identify layers by reading imports/dependencies diff --git a/get-shit-done/templates/codebase/concerns.md b/get-shit-done/templates/codebase/concerns.md index cfbe28629..c1ffcb420 100644 --- a/get-shit-done/templates/codebase/concerns.md +++ b/get-shit-done/templates/codebase/concerns.md @@ -129,70 +129,80 @@ Template for `.planning/codebase/CONCERNS.md` - captures known issues and areas **Database queries in React components:** - Issue: Direct Supabase queries in 15+ page components instead of server actions +- Files: `app/dashboard/page.tsx`, `app/profile/page.tsx`, `app/courses/[id]/page.tsx`, `app/settings/page.tsx` (and 11 more in `app/`) - Why: Rapid prototyping during MVP phase - Impact: Can't implement RLS properly, exposes DB structure to client -- Fix approach: Move all queries to server actions in app/actions/, add proper RLS policies +- Fix approach: Move all queries to server actions in `app/actions/`, add proper RLS policies **Manual webhook signature validation:** - Issue: Copy-pasted Stripe webhook verification code in 3 different endpoints +- Files: `app/api/webhooks/stripe/route.ts`, `app/api/webhooks/checkout/route.ts`, `app/api/webhooks/subscription/route.ts` - Why: Each webhook added ad-hoc without abstraction - Impact: Easy to miss verification in new webhooks (security risk) -- Fix approach: Create shared validateStripeWebhook middleware +- Fix approach: Create shared `lib/stripe/validate-webhook.ts` middleware ## Known Bugs **Race condition in subscription updates:** - Symptoms: User shows as "free" tier for 5-10 seconds after successful payment - Trigger: Fast navigation after Stripe checkout redirect, before webhook processes +- Files: `app/checkout/success/page.tsx` (redirect handler), `app/api/webhooks/stripe/route.ts` (webhook) - Workaround: Stripe webhook eventually updates status (self-heals) - Root cause: Webhook processing slower than user navigation, no optimistic UI update -- Fix: Poll subscription status after checkout redirect, don't rely solely on webhook +- Fix: Add polling in `app/checkout/success/page.tsx` after redirect **Inconsistent session state after logout:** - Symptoms: User redirected to /dashboard after logout instead of /login - Trigger: Logout via button in mobile nav (desktop works fine) +- File: `components/MobileNav.tsx` (line ~45, logout handler) - Workaround: Manual URL navigation to /login works - Root cause: Mobile nav component not awaiting supabase.auth.signOut() -- Fix: Add await to logout handler in MobileNav.tsx +- Fix: Add await to logout handler in `components/MobileNav.tsx` ## Security Considerations **Admin role check client-side only:** - Risk: Admin dashboard pages check isAdmin from Supabase client, no server verification +- Files: `app/admin/page.tsx`, `app/admin/users/page.tsx`, `components/AdminGuard.tsx` - Current mitigation: None (relying on UI hiding) -- Recommendations: Add middleware to admin routes, verify role server-side in Server Components +- Recommendations: Add middleware to admin routes in `middleware.ts`, verify role server-side **Unvalidated file uploads:** - Risk: Users can upload any file type to avatar bucket (no size/type validation) +- File: `components/AvatarUpload.tsx` (upload handler) - Current mitigation: Supabase bucket limits to 2MB (configured in dashboard) -- Recommendations: Add file type validation (image/* only), virus scanning for larger scale +- Recommendations: Add file type validation (image/* only) in `lib/storage/validate.ts` ## Performance Bottlenecks **/api/courses endpoint:** - Problem: Fetching all courses with nested lessons and authors +- File: `app/api/courses/route.ts` - Measurement: 1.2s p95 response time with 50+ courses - Cause: N+1 query pattern (separate query per course for lessons) -- Improvement path: Use Prisma include to eager-load lessons, add Redis caching +- Improvement path: Use Prisma include to eager-load lessons in `lib/db/courses.ts`, add Redis caching **Dashboard initial load:** - Problem: Waterfall of 5 serial API calls on mount +- File: `app/dashboard/page.tsx` - Measurement: 3.5s until interactive on slow 3G - Cause: Each component fetches own data independently -- Improvement path: Server Component with single parallel fetch, or React Server Components +- Improvement path: Convert to Server Component with single parallel fetch ## Fragile Areas **Authentication middleware chain:** +- File: `middleware.ts` - Why fragile: 4 different middleware functions run in specific order (auth -> role -> subscription -> logging) - Common failures: Middleware order change breaks everything, hard to debug - Safe modification: Add tests before changing order, document dependencies in comments - Test coverage: No integration tests for middleware chain (only unit tests) **Stripe webhook event handling:** +- File: `app/api/webhooks/stripe/route.ts` - Why fragile: Giant switch statement with 12 event types, shared transaction logic - Common failures: New event type added without handling, partial DB updates on error -- Safe modification: Extract each event handler to separate function, add comprehensive error handling +- Safe modification: Extract each event handler to `lib/stripe/handlers/*.ts` - Test coverage: Only 3 of 12 event types have tests ## Scaling Limits @@ -272,6 +282,7 @@ Template for `.planning/codebase/CONCERNS.md` - captures known issues and areas - Minor code style issues **When filling this template:** +- **Always include file paths** - Concerns without locations are not actionable. Use backticks: `src/file.ts` - Be specific with measurements ("500ms p95" not "slow") - Include reproduction steps for bugs - Suggest fix approaches, not just problems diff --git a/get-shit-done/templates/codebase/stack.md b/get-shit-done/templates/codebase/stack.md index f57f7f10c..2006c5714 100644 --- a/get-shit-done/templates/codebase/stack.md +++ b/get-shit-done/templates/codebase/stack.md @@ -103,7 +103,7 @@ Template for `.planning/codebase/STACK.md` - captures the technology foundation. **Package Manager:** - npm 10.x -- Lockfile: package-lock.json present +- Lockfile: `package-lock.json` present ## Frameworks @@ -135,8 +135,8 @@ Template for `.planning/codebase/STACK.md` - captures the technology foundation. - Configuration via CLI flags only **Build:** -- tsconfig.json - TypeScript compiler options -- vitest.config.ts - Test runner configuration +- `tsconfig.json` - TypeScript compiler options +- `vitest.config.ts` - Test runner configuration ## Platform Requirements diff --git a/get-shit-done/templates/codebase/structure.md b/get-shit-done/templates/codebase/structure.md index 33e3e22ff..6c11db6e4 100644 --- a/get-shit-done/templates/codebase/structure.md +++ b/get-shit-done/templates/codebase/structure.md @@ -172,21 +172,21 @@ get-shit-done/ ## Key File Locations **Entry Points:** -- bin/install.js: Installation script (npx entry) +- `bin/install.js` - Installation script (npx entry) **Configuration:** -- package.json: Project metadata, dependencies, bin entry -- .gitignore: Excluded files +- `package.json` - Project metadata, dependencies, bin entry +- `.gitignore` - Excluded files **Core Logic:** -- bin/install.js: All installation logic (file copying, path replacement) +- `bin/install.js` - All installation logic (file copying, path replacement) **Testing:** -- tests/: Test files (if present) +- `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 +- `README.md` - User-facing installation and usage guide +- `CLAUDE.md` - Instructions for Claude Code when working in this repo ## Naming Conventions @@ -206,25 +206,25 @@ get-shit-done/ ## 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 +- 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: get-shit-done/templates/{name}.md +- Implementation: `get-shit-done/templates/{name}.md` - Documentation: Template is self-documenting (includes guidelines) **New Workflow:** -- Implementation: get-shit-done/workflows/{name}.md -- Usage: Reference from command with @~/.claude/get-shit-done/workflows/{name}.md +- Implementation: `get-shit-done/workflows/{name}.md` +- Usage: Reference from command with `@~/.claude/get-shit-done/workflows/{name}.md` **New Reference Document:** -- Implementation: get-shit-done/references/{name}.md +- Implementation: `get-shit-done/references/{name}.md` - Usage: Reference from commands/workflows as needed **Utilities:** -- No utilities yet (install.js is monolithic) -- If extracted: src/utils/ +- No utilities yet (`install.js` is monolithic) +- If extracted: `src/utils/` ## Special Directories diff --git a/get-shit-done/workflows/map-codebase.md b/get-shit-done/workflows/map-codebase.md index d9ee9a3cb..7e22858af 100644 --- a/get-shit-done/workflows/map-codebase.md +++ b/get-shit-done/workflows/map-codebase.md @@ -13,6 +13,9 @@ Each agent has fresh context and focuses on specific aspects. Output is concise **Document quality over length:** Include enough detail to be useful as reference. Prioritize practical examples (especially code patterns) over arbitrary brevity. A 200-line TESTING.md with real patterns is more valuable than a 74-line summary. + +**Always include file paths:** +Documents are reference material for Claude when planning/executing. Vague descriptions like "UserService handles users" are not actionable. Always include actual file paths formatted with backticks: `src/services/user.ts`. This allows Claude to navigate directly to relevant code without re-searching. Do NOT include line numbers (they go stale), just file paths. @@ -83,6 +86,8 @@ Prompt: ``` Analyze this codebase for technology stack and external integrations. +IMPORTANT: Always include actual file paths in your findings. Use backtick formatting like `src/config/database.ts`. This makes the output actionable for planning. + Focus areas: 1. Languages (check file extensions, package manifests) 2. Runtime environment (Node.js, Python, etc. - check .nvmrc, .python-version, engines field) @@ -104,6 +109,11 @@ Output findings for populating these sections: - STACK.md: Languages, Runtime, Frameworks, Dependencies, Configuration - INTEGRATIONS.md: External APIs, Services, Third-party tools +For each finding, include the file path where you found it. Example: +- "TypeScript 5.3 - `package.json`" +- "Supabase client - `src/lib/supabase.ts`" +- "Stripe integration - `src/services/stripe.ts`, `src/webhooks/stripe.ts`" + If something is not found, note "Not detected" for that category. ``` @@ -120,6 +130,8 @@ Prompt: ``` Analyze this codebase architecture and directory structure. +IMPORTANT: Always include actual file paths in your findings. Use backtick formatting like `src/index.ts`. This makes the output actionable for planning. + Focus areas: 1. Overall architectural pattern (monolith, microservices, layered, etc.) 2. Conceptual layers (API, service, data, utility) @@ -140,6 +152,11 @@ Output findings for populating these sections: - ARCHITECTURE.md: Pattern, Layers, Data Flow, Abstractions, Entry Points - STRUCTURE.md: Directory layout, Organization, Key locations +For each finding, include the file path. Examples: +- "CLI entry point: `bin/install.js`" +- "Service layer: `src/services/*.ts` (UserService, ProjectService)" +- "API routes: `src/routes/api/*.ts`" + If something is not clear, provide best-guess interpretation based on code structure. ``` @@ -156,6 +173,8 @@ Prompt: ``` Analyze this codebase for coding conventions and testing practices. +IMPORTANT: Always include actual file paths in your findings. Use backtick formatting like `vitest.config.ts`. This makes the output actionable for planning. + Focus areas: 1. Code style (indentation, quotes, semicolons, formatting) 2. File naming conventions (kebab-case, PascalCase, etc.) @@ -177,6 +196,11 @@ Output findings for populating these sections: - CONVENTIONS.md: Code Style, Naming, Patterns, Documentation - TESTING.md: Framework, Structure, Coverage, Tools +For each finding, include file paths. Examples: +- "Prettier config: `.prettierrc`" +- "Test pattern: `src/**/*.test.ts` (co-located with source)" +- "Example of naming convention: `src/services/user-service.ts`" + Look at actual code files to infer conventions if config files are missing. ``` @@ -193,6 +217,8 @@ Prompt: ``` Analyze this codebase for technical debt, known issues, and areas of concern. +CRITICAL: Always include actual file paths in your findings. Use backtick formatting like `src/auth/login.ts`. Concerns without file paths are not actionable. For each issue found, specify exactly where it is. + Focus areas: 1. TODO and FIXME comments 2. Complex or hard-to-understand code @@ -215,6 +241,11 @@ Search for: Output findings for populating: - CONCERNS.md: Technical Debt, Issues, Security, Performance, Documentation +For EVERY concern, include file paths. Examples: +- "Direct DB queries in components: `src/pages/Dashboard.tsx`, `src/pages/Profile.tsx`" +- "Missing error handling: `src/api/webhook.ts` (Stripe webhook has no try/catch)" +- "TODO: 'fix race condition' in `src/services/subscription.ts`" + Be constructive - focus on actionable concerns, not nitpicks. If codebase is clean, note that rather than inventing problems. ```