feat(01-01): codebase map templates for stack, architecture, structure
- stack.md: captures languages, runtime, frameworks, key dependencies - architecture.md: captures patterns, layers, data flow, abstractions - structure.md: captures directory layout, file locations, conventions
This commit is contained in:
Lex Christopherson
249
get-shit-done/templates/codebase/architecture.md
Normal file
249
get-shit-done/templates/codebase/architecture.md
Normal file
@@ -0,0 +1,249 @@
|
||||
# Architecture Template
|
||||
|
||||
Template for `.planning/codebase/ARCHITECTURE.md` - captures conceptual code organization.
|
||||
|
||||
**Purpose:** Document how the code is organized at a conceptual level. Complements STRUCTURE.md (which shows physical file locations).
|
||||
|
||||
---
|
||||
|
||||
## File Template
|
||||
|
||||
```markdown
|
||||
# Architecture
|
||||
|
||||
**Analysis Date:** [YYYY-MM-DD]
|
||||
|
||||
## Pattern Overview
|
||||
|
||||
**Overall:** [Pattern name: e.g., "Monolithic CLI", "Serverless API", "Full-stack MVC"]
|
||||
|
||||
**Key Characteristics:**
|
||||
- [Characteristic 1: e.g., "Single executable"]
|
||||
- [Characteristic 2: e.g., "Stateless request handling"]
|
||||
- [Characteristic 3: e.g., "Event-driven"]
|
||||
|
||||
## Layers
|
||||
|
||||
[Describe the conceptual layers and their responsibilities]
|
||||
|
||||
**[Layer Name]:**
|
||||
- Purpose: [What this layer does]
|
||||
- Contains: [Types of code: e.g., "route handlers", "business logic"]
|
||||
- Depends on: [What it uses: e.g., "data layer only"]
|
||||
- Used by: [What uses it: e.g., "API routes"]
|
||||
|
||||
**[Layer Name]:**
|
||||
- Purpose: [What this layer does]
|
||||
- Contains: [Types of code]
|
||||
- Depends on: [What it uses]
|
||||
- Used by: [What uses it]
|
||||
|
||||
## Data Flow
|
||||
|
||||
[Describe the typical request/execution lifecycle]
|
||||
|
||||
**[Flow Name] (e.g., "HTTP Request", "CLI Command", "Event Processing"):**
|
||||
|
||||
1. [Entry point: e.g., "User runs command"]
|
||||
2. [Processing step: e.g., "Router matches path"]
|
||||
3. [Processing step: e.g., "Controller validates input"]
|
||||
4. [Processing step: e.g., "Service executes logic"]
|
||||
5. [Output: e.g., "Response returned"]
|
||||
|
||||
**State Management:**
|
||||
- [How state is handled: e.g., "Stateless - no persistent state", "Database per request", "In-memory cache"]
|
||||
|
||||
## Key Abstractions
|
||||
|
||||
[Core concepts/patterns used throughout the codebase]
|
||||
|
||||
**[Abstraction Name]:**
|
||||
- Purpose: [What it represents]
|
||||
- Examples: [e.g., "UserService, ProjectService"]
|
||||
- Pattern: [e.g., "Singleton", "Factory", "Repository"]
|
||||
|
||||
**[Abstraction Name]:**
|
||||
- Purpose: [What it represents]
|
||||
- Examples: [Concrete examples]
|
||||
- Pattern: [Pattern used]
|
||||
|
||||
## Entry Points
|
||||
|
||||
[Where execution begins]
|
||||
|
||||
**[Entry Point]:**
|
||||
- Location: [Brief: e.g., "src/index.ts", "API Gateway triggers"]
|
||||
- Triggers: [What invokes it: e.g., "CLI invocation", "HTTP request"]
|
||||
- Responsibilities: [What it does: e.g., "Parse args, route to command"]
|
||||
|
||||
## Error Handling
|
||||
|
||||
**Strategy:** [How errors are handled: e.g., "Exception bubbling to top-level handler", "Per-route error middleware"]
|
||||
|
||||
**Patterns:**
|
||||
- [Pattern: e.g., "try/catch at controller level"]
|
||||
- [Pattern: e.g., "Error codes returned to user"]
|
||||
|
||||
## Cross-Cutting Concerns
|
||||
|
||||
[Aspects that affect multiple layers]
|
||||
|
||||
**Logging:**
|
||||
- [Approach: e.g., "Winston logger, injected per-request"]
|
||||
|
||||
**Validation:**
|
||||
- [Approach: e.g., "Zod schemas at API boundary"]
|
||||
|
||||
**Authentication:**
|
||||
- [Approach: e.g., "JWT middleware on protected routes"]
|
||||
|
||||
---
|
||||
|
||||
*Architecture analysis: [date]*
|
||||
*Update when major patterns change*
|
||||
```
|
||||
|
||||
<good_examples>
|
||||
```markdown
|
||||
# Architecture
|
||||
|
||||
**Analysis Date:** 2025-01-20
|
||||
|
||||
## Pattern Overview
|
||||
|
||||
**Overall:** CLI Application with Plugin System
|
||||
|
||||
**Key Characteristics:**
|
||||
- Single executable with subcommands
|
||||
- Plugin-based extensibility
|
||||
- File-based state (no database)
|
||||
- Synchronous execution model
|
||||
|
||||
## Layers
|
||||
|
||||
**Command Layer:**
|
||||
- Purpose: Parse user input and route to appropriate handler
|
||||
- Contains: Command definitions, argument parsing, help text
|
||||
- Depends on: Service layer for business logic
|
||||
- Used by: CLI entry point (src/index.ts)
|
||||
|
||||
**Service Layer:**
|
||||
- Purpose: Core business logic
|
||||
- Contains: FileService, TemplateService, InstallService
|
||||
- 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
|
||||
- Depends on: Node.js built-ins only
|
||||
- Used by: Service layer
|
||||
|
||||
## Data Flow
|
||||
|
||||
**CLI Command Execution:**
|
||||
|
||||
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())
|
||||
5. Service reads templates, processes files, writes output
|
||||
6. Results logged to console
|
||||
7. Process exits with status code
|
||||
|
||||
**State Management:**
|
||||
- File-based: All state lives in `.planning/` directory
|
||||
- No persistent in-memory state
|
||||
- Each command execution is independent
|
||||
|
||||
## Key Abstractions
|
||||
|
||||
**Service:**
|
||||
- Purpose: Encapsulate business logic for a domain
|
||||
- Examples: FileService, TemplateService, ProjectService
|
||||
- Pattern: Singleton-like (imported as modules, not instantiated)
|
||||
|
||||
**Command:**
|
||||
- Purpose: CLI command definition
|
||||
- Examples: new-project, plan-phase, execute-plan
|
||||
- Pattern: Commander.js command registration
|
||||
|
||||
**Template:**
|
||||
- Purpose: Reusable document structures
|
||||
- Examples: PROJECT.md, PLAN.md templates
|
||||
- Pattern: Markdown files with substitution variables
|
||||
|
||||
## Entry Points
|
||||
|
||||
**CLI Entry:**
|
||||
- Location: src/index.ts
|
||||
- Triggers: User runs `gsd <command>`
|
||||
- Responsibilities: Register commands, parse args, display help
|
||||
|
||||
**Commands:**
|
||||
- Location: src/commands/*.ts
|
||||
- Triggers: Matched command from CLI
|
||||
- Responsibilities: Validate input, call services, format output
|
||||
|
||||
## Error Handling
|
||||
|
||||
**Strategy:** Throw exceptions, catch at command level, log and exit
|
||||
|
||||
**Patterns:**
|
||||
- Services throw Error with descriptive messages
|
||||
- Command handlers catch, log error to stderr, exit(1)
|
||||
- Validation errors shown before execution (fail fast)
|
||||
|
||||
## Cross-Cutting Concerns
|
||||
|
||||
**Logging:**
|
||||
- Console.log for normal output
|
||||
- Console.error for errors
|
||||
- Chalk for colored output
|
||||
|
||||
**Validation:**
|
||||
- Zod schemas for config file parsing
|
||||
- Manual validation in command handlers
|
||||
- Fail fast on invalid input
|
||||
|
||||
**File Operations:**
|
||||
- FileService abstraction over fs-extra
|
||||
- All paths validated before operations
|
||||
- Atomic writes (temp file + rename)
|
||||
|
||||
---
|
||||
|
||||
*Architecture analysis: 2025-01-20*
|
||||
*Update when major patterns change*
|
||||
```
|
||||
</good_examples>
|
||||
|
||||
<guidelines>
|
||||
**What belongs in ARCHITECTURE.md:**
|
||||
- Overall architectural pattern (monolith, microservices, layered, etc.)
|
||||
- Conceptual layers and their relationships
|
||||
- Data flow / request lifecycle
|
||||
- Key abstractions and patterns
|
||||
- Entry points
|
||||
- Error handling strategy
|
||||
- Cross-cutting concerns (logging, auth, validation)
|
||||
|
||||
**What does NOT belong here:**
|
||||
- Specific file paths (that's STRUCTURE.md)
|
||||
- Technology choices (that's STACK.md)
|
||||
- Line-by-line code walkthrough (defer to code reading)
|
||||
- Implementation details of specific features
|
||||
|
||||
**When filling this template:**
|
||||
- Read main entry points (index, server, main)
|
||||
- Identify layers by reading imports/dependencies
|
||||
- Trace a typical request/command execution
|
||||
- Note recurring patterns (services, controllers, repositories)
|
||||
- Keep descriptions conceptual, not mechanical
|
||||
|
||||
**Useful for phase planning when:**
|
||||
- Adding new features (where does it fit in the layers?)
|
||||
- Refactoring (understanding current patterns)
|
||||
- Identifying where to add code (which layer handles X?)
|
||||
- Understanding dependencies between components
|
||||
</guidelines>
|
||||
187
get-shit-done/templates/codebase/stack.md
Normal file
187
get-shit-done/templates/codebase/stack.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# Technology Stack Template
|
||||
|
||||
Template for `.planning/codebase/STACK.md` - captures the technology foundation.
|
||||
|
||||
**Purpose:** Document what technologies run this codebase. Focused on "what executes when you run the code."
|
||||
|
||||
---
|
||||
|
||||
## File Template
|
||||
|
||||
```markdown
|
||||
# Technology Stack
|
||||
|
||||
**Analysis Date:** [YYYY-MM-DD]
|
||||
|
||||
## Languages
|
||||
|
||||
**Primary:**
|
||||
- [Language] [Version] - [Where used: e.g., "all application code"]
|
||||
|
||||
**Secondary:**
|
||||
- [Language] [Version] - [Where used: e.g., "build scripts, tooling"]
|
||||
|
||||
## Runtime
|
||||
|
||||
**Environment:**
|
||||
- [Runtime] [Version] - [e.g., "Node.js 20.x"]
|
||||
- [Additional requirements if any]
|
||||
|
||||
**Package Manager:**
|
||||
- [Manager] [Version] - [e.g., "npm 10.x"]
|
||||
- Lockfile: [e.g., "package-lock.json present"]
|
||||
|
||||
## Frameworks
|
||||
|
||||
**Core:**
|
||||
- [Framework] [Version] - [Purpose: e.g., "web server", "UI framework"]
|
||||
|
||||
**Testing:**
|
||||
- [Framework] [Version] - [e.g., "Jest for unit tests"]
|
||||
- [Framework] [Version] - [e.g., "Playwright for E2E"]
|
||||
|
||||
**Build/Dev:**
|
||||
- [Tool] [Version] - [e.g., "Vite for bundling"]
|
||||
- [Tool] [Version] - [e.g., "TypeScript compiler"]
|
||||
|
||||
## Key Dependencies
|
||||
|
||||
[Only include dependencies critical to understanding the stack - limit to 5-10 most important]
|
||||
|
||||
**Critical:**
|
||||
- [Package] [Version] - [Why it matters: e.g., "authentication", "database access"]
|
||||
- [Package] [Version] - [Why it matters]
|
||||
|
||||
**Infrastructure:**
|
||||
- [Package] [Version] - [e.g., "Express for HTTP routing"]
|
||||
- [Package] [Version] - [e.g., "PostgreSQL client"]
|
||||
|
||||
## Configuration
|
||||
|
||||
**Environment:**
|
||||
- [How configured: e.g., ".env files", "environment variables"]
|
||||
- [Key configs: e.g., "DATABASE_URL, API_KEY required"]
|
||||
|
||||
**Build:**
|
||||
- [Build config files: e.g., "vite.config.ts, tsconfig.json"]
|
||||
|
||||
## Platform Requirements
|
||||
|
||||
**Development:**
|
||||
- [OS requirements or "any platform"]
|
||||
- [Additional tooling: e.g., "Docker for local DB"]
|
||||
|
||||
**Production:**
|
||||
- [Deployment target: e.g., "Vercel", "AWS Lambda", "Docker container"]
|
||||
- [Version requirements]
|
||||
|
||||
---
|
||||
|
||||
*Stack analysis: [date]*
|
||||
*Update after major dependency changes*
|
||||
```
|
||||
|
||||
<good_examples>
|
||||
```markdown
|
||||
# Technology Stack
|
||||
|
||||
**Analysis Date:** 2025-01-20
|
||||
|
||||
## Languages
|
||||
|
||||
**Primary:**
|
||||
- TypeScript 5.3 - All application code
|
||||
|
||||
**Secondary:**
|
||||
- JavaScript - Build scripts, config files
|
||||
|
||||
## Runtime
|
||||
|
||||
**Environment:**
|
||||
- Node.js 20.x (LTS)
|
||||
- No browser runtime (CLI tool only)
|
||||
|
||||
**Package Manager:**
|
||||
- npm 10.x
|
||||
- Lockfile: package-lock.json present
|
||||
|
||||
## Frameworks
|
||||
|
||||
**Core:**
|
||||
- None (vanilla Node.js CLI)
|
||||
|
||||
**Testing:**
|
||||
- Vitest 1.0 - Unit tests
|
||||
- tsx - TypeScript execution without build step
|
||||
|
||||
**Build/Dev:**
|
||||
- TypeScript 5.3 - Compilation to JavaScript
|
||||
- esbuild - Used by Vitest for fast transforms
|
||||
|
||||
## Key Dependencies
|
||||
|
||||
**Critical:**
|
||||
- commander 11.x - CLI argument parsing and command structure
|
||||
- chalk 5.x - Terminal output styling
|
||||
- fs-extra 11.x - Extended file system operations
|
||||
|
||||
**Infrastructure:**
|
||||
- Node.js built-ins - fs, path, child_process for file operations
|
||||
|
||||
## Configuration
|
||||
|
||||
**Environment:**
|
||||
- No environment variables required
|
||||
- Configuration via CLI flags only
|
||||
|
||||
**Build:**
|
||||
- tsconfig.json - TypeScript compiler options
|
||||
- vitest.config.ts - Test runner configuration
|
||||
|
||||
## Platform Requirements
|
||||
|
||||
**Development:**
|
||||
- macOS/Linux/Windows (any platform with Node.js)
|
||||
- No external dependencies
|
||||
|
||||
**Production:**
|
||||
- Distributed as npm package
|
||||
- Installed globally via npm install -g
|
||||
- Runs on user's Node.js installation
|
||||
|
||||
---
|
||||
|
||||
*Stack analysis: 2025-01-20*
|
||||
*Update after major dependency changes*
|
||||
```
|
||||
</good_examples>
|
||||
|
||||
<guidelines>
|
||||
**What belongs in STACK.md:**
|
||||
- Languages and versions
|
||||
- Runtime requirements (Node, Bun, Deno, browser)
|
||||
- Package manager and lockfile
|
||||
- Framework choices
|
||||
- Critical dependencies (limit to 5-10 most important)
|
||||
- Build tooling
|
||||
- Platform/deployment requirements
|
||||
|
||||
**What does NOT belong here:**
|
||||
- File structure (that's STRUCTURE.md)
|
||||
- Architectural patterns (that's ARCHITECTURE.md)
|
||||
- Every dependency in package.json (only critical ones)
|
||||
- Implementation details (defer to code)
|
||||
|
||||
**When filling this template:**
|
||||
- Check package.json for dependencies
|
||||
- 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)
|
||||
- Upgrading frameworks (know what's in use)
|
||||
- Choosing implementation approach (must work with existing stack)
|
||||
- Understanding build requirements
|
||||
</guidelines>
|
||||
285
get-shit-done/templates/codebase/structure.md
Normal file
285
get-shit-done/templates/codebase/structure.md
Normal file
@@ -0,0 +1,285 @@
|
||||
# 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 tree of top-level directories with purpose]
|
||||
|
||||
```
|
||||
[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
|
||||
|
||||
```
|
||||
get-shit-done/
|
||||
├── bin/ # Executable entry points
|
||||
├── commands/ # Slash command definitions
|
||||
│ └── gsd/ # GSD-specific commands
|
||||
├── get-shit-done/ # 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)
|
||||
|
||||
**get-shit-done/references/**
|
||||
- Purpose: Core philosophy and guidance documents
|
||||
- Contains: principles.md, questioning.md, plan-format.md
|
||||
- Key files: principles.md - system philosophy
|
||||
- Subdirectories: None
|
||||
|
||||
**get-shit-done/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)
|
||||
|
||||
**get-shit-done/workflows/**
|
||||
- Purpose: Reusable multi-step procedures
|
||||
- Contains: Workflow definitions called by commands
|
||||
- Key files: execute-phase.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: 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
|
||||
|
||||
**New Reference Document:**
|
||||
- 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/
|
||||
|
||||
## Special Directories
|
||||
|
||||
**get-shit-done/**
|
||||
- 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 tree)
|
||||
- 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)
|
||||
|
||||
**ASCII tree format:**
|
||||
```
|
||||
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>
|
||||
Reference in New Issue
Block a user