get-shit-done-cc 1.3.4 → 1.3.6

package/commands/gsd/map-codebase.md

@@ -13,7 +13,7 @@ allowed-tools:
 <objective>
 Analyze existing codebase using parallel Explore agents to produce structured codebase documents.
 
-This command spawns multiple Explore agents to analyze different aspects of the codebase in parallel, each with fresh context. Each agent produces focused documentation under 100 lines.
+This command spawns multiple Explore agents to analyze different aspects of the codebase in parallel, each with fresh context.
 
 Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
 </objective>
@@ -71,14 +71,12 @@ Check for .planning/STATE.md - loads context if project already initialized
    - TESTING.md - Test structure, coverage, practices
    - INTEGRATIONS.md - APIs, databases, external services
    - CONCERNS.md - Technical debt, risks, issues
-6. Verify each document is under 100 lines (summarize if needed)
-7. Offer next steps (typically: /gsd:new-project or /gsd:plan-phase)
+6. Offer next steps (typically: /gsd:new-project or /gsd:plan-phase)
 </process>
 
 <success_criteria>
 - [ ] .planning/codebase/ directory created
 - [ ] All 7 codebase documents written
-- [ ] Each document under 100 lines
 - [ ] Documents follow template structure
 - [ ] Parallel agents completed without errors
 - [ ] User knows next steps

package/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 <command>`
 - 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

package/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

package/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
 
@@ -177,7 +177,6 @@ Template for `.planning/codebase/STACK.md` - captures the technology foundation.
 - Note runtime version from .nvmrc or package.json engines
 - Include only dependencies that affect understanding (not every utility)
 - Specify versions only when version matters (breaking changes, compatibility)
-- Keep under ~100 lines total
 
 **Useful for phase planning when:**
 - Adding new dependencies (check compatibility)

package/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
 

package/get-shit-done/workflows/execute-phase.md

@@ -1177,7 +1177,6 @@ For each document needing update:
 1. Read current document
 2. Identify what changed (new entries, removed entries, modified sections)
 3. Apply minimal edits to reflect new state
-4. Keep document under 100 lines (summarize if needed)
 
 **Commit codebase updates:**
 ```bash

package/get-shit-done/workflows/map-codebase.md

@@ -1,7 +1,7 @@
 <purpose>
 Orchestrate parallel Explore agents to analyze codebase and produce structured documents in .planning/codebase/
 
-Each agent has fresh context and focuses on specific aspects. Output is concise (under 100 lines per document) and actionable for planning.
+Each agent has fresh context and focuses on specific aspects. Output is concise and actionable for planning.
 </purpose>
 
 <philosophy>
@@ -11,8 +11,11 @@ Each agent has fresh context and focuses on specific aspects. Output is concise
 - Each agent optimized for its domain (tech vs organization vs quality vs issues)
 - Faster execution (agents run simultaneously)
 
-**Why 100-line limit:**
-Codebase maps are reference material loaded frequently. Concise summaries are more useful than exhaustive inventories. If codebase is large, summarize patterns rather than listing every file.
+**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.
 </philosophy>
 
 <process>
@@ -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.
 ```
@@ -255,13 +286,6 @@ If an agent didn't find information for a section, use placeholder:
 - "Not applicable" (for patterns that don't apply to this codebase)
 - "No significant concerns" (for CONCERNS.md if codebase is clean)
 
-**Line count check:**
-
-Before writing, estimate total lines for each document. If any will exceed 100 lines:
-- Summarize patterns instead of listing all instances
-- Prioritize most important/frequent patterns
-- Reference "see code for full details" for exhaustive lists
-
 Continue to write_documents.
 </step>
 
@@ -281,11 +305,7 @@ For each document:
      - "Not detected" for optional infrastructure
      - "Not applicable" for patterns that don't fit this codebase
      - "No significant concerns" for clean codebase areas
-4. **Verify line count** - if filled template exceeds 100 lines, summarize:
-   - Keep most critical findings
-   - Summarize patterns instead of exhaustive lists
-   - Add "(see code for full details)" where appropriate
-5. **Write to .planning/codebase/{NAME}.md** (uppercase filename)
+4. **Write to .planning/codebase/{NAME}.md** (uppercase filename)
 
 **Example filling pattern:**
 
@@ -329,7 +349,6 @@ wc -l .planning/codebase/*.md
 
 **Verification checklist:**
 - All 7 documents exist
-- Each document under 100 lines
 - No empty documents
 - Templates populated with findings
 
@@ -377,7 +396,6 @@ Created .planning/codebase/:
 - INTEGRATIONS.md ([N] lines) - External services and APIs
 - CONCERNS.md ([N] lines) - Technical debt and issues
 
-[If any files >100 lines, add warning: "⚠ Some files exceed 100 lines - consider summarizing further"]
 
 ---
 
@@ -410,7 +428,6 @@ End workflow.
 - Agent prompts are specific and actionable
 - TaskOutput used to collect all agent results
 - All 7 codebase documents written using template filling
-- Each document under 100 lines (or warning shown)
 - Documents follow template structure with actual findings
 - Clear completion summary with line counts
 - User offered clear next steps in GSD style

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "get-shit-done-cc",
-  "version": "1.3.4",
+  "version": "1.3.6",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.",
   "bin": {
     "get-shit-done-cc": "bin/install.js"