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

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

# 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*

```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
• AGENTS.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 @/Users/theogengineer/Projects/Multilingual-Absa/.opencode/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 /Users/theogengineer/Projects/Multilingual-Absa/.opencode/
• Source: Copied by bin/install.js during installation
• Committed: Yes (source of truth)

commands/

• Purpose: Slash commands installed to /Users/theogengineer/Projects/Multilingual-Absa/.opencode/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>