# Codebase Structure

**Analysis Date:** 2026-03-12

## Directory Layout

```
/root/tckuiyo/
├── THE_IDEA.md              # Project concept documentation
├── .gitignore               # Git ignore rules
├── .bg-shell/               # Background shell config (manifest.json)
├── .gsd/                    # GSD project data
│   └── milestones/          # Milestone definitions (empty)
├── .opencode/               # GSD Framework (main project code)
│   ├── package.json         # Dependencies (OpenCode plugin)
│   ├── bun.lock             # Dependency lockfile
│   ├── opencode.db          # OpenCode database
│   ├── commands/            # User-facing commands
│   ├── agents/              # AI agent definitions
│   ├── get-shit-done/       # Workflows
│   │   └── workflows/       # Execution logic
│   ├── skills/              # Specialized skills
│   ├── rules/               # Behavior rules
│   ├── node_modules/        # Dependencies
│   └── .gitignore           # OpenCode-specific ignores
├── .planning/               # Project planning output
│   └── codebase/            # Codebase analysis docs (where mappers write)
└── (empty directories for future use)
```

## Directory Purposes

**`.opencode/`:**
- Purpose: Core GSD framework configuration
- Contains: Commands, agents, workflows, skills, rules
- Key files: All 33 command files, 12 agent files, 36 workflow files

**`.opencode/commands/gsd/`:**
- Purpose: User-invokable GSD commands
- Contains: Markdown command definitions with YAML frontmatter
- Key files: `gsd-new-project.md`, `gsd-map-codebase.md`, `gsd-plan-phase.md`, `gsd-execute-phase.md`

**`.opencode/agents/`:**
- Purpose: AI agent role definitions
- Contains: Agent configurations with tools and skills
- Key files: `gsd-codebase-mapper.md`, `gsd-planner.md`, `gsd-executor.md`, `gsd-verifier.md`

**`.opencode/get-shit-done/workflows/`:**
- Purpose: Execution logic for commands
- Contains: Step-by-step workflow instructions
- Key files: `map-codebase.md`, `new-project.md`, `plan-phase.md`, `execute-phase.md`

**`.opencode/skills/`:**
- Purpose: Specialized capability modules
- Contains: Skill definitions with scripts
- Key files: `gsd-oc-select-model/` (model selection skill)

**`.opencode/rules/`:**
- Purpose: Global behavior rules
- Contains: Rule definitions for agent behavior
- Key files: `gsd-oc-work-hard.md`

**`.planning/codebase/`:**
- Purpose: Output location for codebase mapper agents
- Contains: Analysis documents written by mapper agents
- Target files: STACK.md, INTEGRATIONS.md, ARCHITECTURE.md, STRUCTURE.md, CONVENTIONS.md, TESTING.md, CONCERNS.md

**`.gsd/milestones/`:**
- Purpose: Milestone definitions for projects
- Contains: Milestone JSON files (currently empty)
- Used by: new-milestone, complete-milestone commands

## Key File Locations

**Entry Points:**
- `.opencode/commands/gsd/gsd-*.md`: Command definitions invoked via `/gsd-*`

**Configuration:**
- `.opencode/package.json`: Dependencies - `@opencode-ai/plugin: 1.2.24`
- `.opencode/bun.lock`: Dependency lockfile
- `.gitignore`: Excludes node_modules, .opencode/, .gsd/, .planning/, *.swp

**Core Logic:**
- All logic in `.opencode/` - this IS the application (OpenCode configuration)

**Testing:**
- No separate test directory - OpenCode handles testing via verify-work workflow

## Naming Conventions

**Files:**
- Commands: `gsd-{command-name}.md` (kebab-case)
- Agents: `gsd-{agent-name}.md` (kebab-case)
- Workflows: `{workflow-name}.md` (kebab-case)
- Skills: `{skill-name}/` directory with SKILL.md inside

**Directories:**
- `.opencode/commands/gsd/`: GSD commands group
- `.opencode/agents/`: Agent definitions
- `.opencode/get-shit-done/workflows/`: Workflow definitions
- `.opencode/skills/`: Skill packages
- `.opencode/node_modules/`: npm dependencies
- `.planning/codebase/`: Codebase analysis outputs

## Where to Add New Code

**New Command:**
- Implementation: `.opencode/commands/gsd/gsd-{name}.md`
- Workflow: Add corresponding `.opencode/get-shit-done/workflows/{name}.md`

**New Agent:**
- Implementation: `.opencode/agents/gsd-{name}.md`

**New Workflow:**
- Implementation: `.opencode/get-shit-done/workflows/{name}.md`
- Referenced by: Command's `<execution_context>` tag

**New Skill:**
- Implementation: `.opencode/skills/{skill-name}/SKILL.md`

**Codebase Analysis Output:**
- Location: `.planning/codebase/` (written by gsd-codebase-mapper agents)

## Special Directories

**`.opencode/`:**
- Purpose: OpenCode project root - contains all project code
- Generated: No - this IS the codebase
- Committed: Yes - core project files

**`.opencode/node_modules/`:**
- Purpose: Dependencies for OpenCode plugin
- Generated: Yes (via bun install)
- Committed: No (in .gitignore)

**`.planning/`:**
- Purpose: Planning output and project state
- Generated: Yes (by GSD commands)
- Committed: Yes (project state is versioned)

**`.gsd/`:**
- Purpose: Project milestone and tracking data
- Generated: Yes (by GSD commands)
- Committed: Yes (project progress is versioned)

---

*Structure analysis: 2026-03-12*