# Codebase Structure **Analysis Date:** 2026-03-27 ## Directory Layout ``` /home/ys/family-repo/AgenticCode/ ├── .agent/ # Anthropic Agent-specific GSD setup │ ├── agents/ # Agent definitions (symlinks or copies) │ ├── get-shit-done/ # Workflows, templates, references │ ├── hooks/ # Post-tool integration hooks │ ├── skills/ # Project skills (agent instructions) │ └── package.json # CommonJS marker ├── .claude/ # Claude Code / Claude Web setup │ ├── agents/ # 18 agent definition files (master) │ ├── get-shit-done/ # Master workflows, references, commands │ │ ├── bin/ # gsd-tools.cjs CLI (~1000 lines) │ │ ├── commands/gsd/ # Command metadata (workstreams.md) │ │ ├── references/ # Documentation and config specs │ │ ├── templates/ # Scaffold templates for PLAN.md, SUMMARY.md │ │ └── workflows/ # 56 orchestration workflows │ ├── commands/gsd/ # Claude Code command overrides │ ├── hooks/ # Post-tool hooks for linting/formatting │ ├── package.json # CommonJS marker │ └── settings.json # Per-runtime settings ├── .codex/ # Codeium Codex setup (mirrors .claude/) ├── .cursor/ # Cursor IDE setup (mirrors .claude/) ├── .gemini/ # Google Gemini setup (mirrors .claude/) ├── .opencode/ # OpenCode setup (mirrors .claude/) ├── .windsurf/ # Codeium Windsurf setup (mirrors .claude/) ├── .github/ # GitHub integration │ ├── gsd-file-manifest.json # File integrity checksums │ └── get-shit-done/ # GitHub action templates ├── .planning/ # Project state and planning documents │ ├── codebase/ # Analysis documents (STACK.md, ARCHITECTURE.md, etc.) │ ├── config.json # Project configuration (branching, model profiles) │ ├── STATE.md # Global project state (current phase, milestone, blockers) │ ├── ROADMAP.md # Full scope and phase definitions │ ├── REQUIREMENTS.md # Traceability for feature requirements │ └── phases/ # Phase execution directories │ ├── 1/ # Phase 1 │ │ ├── CONTEXT.md # User decisions for this phase │ │ ├── PLAN-01.md # Task breakdown (plan 1 of N) │ │ ├── PLAN-02.md # Task breakdown (plan 2 of N) │ │ ├── SUMMARY-01.md # Execution results (for PLAN-01) │ │ ├── VERIFICATION.md # Success criteria and quality gates │ │ └── WAITING.json # Optional: pause signal for checkpoints │ ├── 1.1/ # Sub-phase 1.1 │ └── 2/ # Phase 2 ├── .git/ # Git repository ├── .gitignore # Standard: excludes node_modules, .env, .planning (optional) ├── README.md # Project descriptor └── .gsd-file-manifest.json # Root-level file integrity tracking ``` ## Directory Purposes **`.claude/` (Master Directory):** - Purpose: Contains the canonical GSD system — agents, workflows, CLI tool, references - Contains: Agent role definitions (18 files), 56 workflows, gsd-tools.cjs, documentation - Key files: `agents/gsd-planner.md`, `agents/gsd-executor.md`, `agents/gsd-codebase-mapper.md`, `get-shit-done/bin/gsd-tools.cjs` **`.claude/agents/`:** - Purpose: Agent role definitions — instructions, tool access, execution patterns - Contains: 18 agent files (one per agent type) - File pattern: `gsd-{role-name}.md` (e.g., `gsd-planner.md`) - Size: Large files (10KB-45KB), front-loaded with role definition, process steps **`.claude/get-shit-done/workflows/`:** - Purpose: Orchestration logic — multi-step processes coordinating agents and user input - Contains: 56 markdown workflow files - Naming: workflow names map to commands (e.g., `execute-phase.md` → `/gsd:execute-phase`) - Pattern: Each workflow defines steps with conditional branching, gsd-tools.cjs calls, agent spawning **`.claude/get-shit-done/bin/`:** - Purpose: CLI tool providing centralized state/git operations - Contains: `gsd-tools.cjs` (main tool, ~1000 lines), `lib/` (supporting utilities) - Commands: 100+ subcommands for state, phases, roadmaps, validation, commits - Called from: Every workflow and agent via `node gsd-tools.cjs ` **`.claude/get-shit-done/references/`:** - Purpose: Documentation and configuration specifications - Contains: 15 reference files (model-profiles.md, planning-config.md, checkpoints.md, etc.) - Usage: Read by agents to understand patterns, by implementers to understand system **`.claude/get-shit-done/templates/`:** - Purpose: Scaffold templates for plan and summary generation - Contains: PLAN.md template, SUMMARY.md template, CONTEXT.md template - Usage: Developers fill templates when creating new phases **`.agent/`, `.gemini/`, `.codex/`, `.cursor/`, `.windsurf/`, `.opencode/`:** - Purpose: Per-IDE setup directories (mirrors of `.claude/`) - Contains: Symlinks or copies of agents/, workflows/, hooks/, settings.json - Why separate: Each IDE has own credential storage, hook integration points, settings **`.planning/`:** - Purpose: Global project state and phase-local planning documents - Contains: STATE.md (global), ROADMAP.md (full scope), config.json, phases/ directory tree - Key files: `STATE.md` (current position), `ROADMAP.md` (phase definitions), `config.json` (branching strategy, model profiles) **`.planning/phases/N/`:** - Purpose: Per-phase execution directory — holds decisions, plans, summaries - Contains: CONTEXT.md (user decisions), PLAN-*.md (task breakdowns), SUMMARY-*.md (results), VERIFICATION.md (success gates) - Naming: Phase directories use number (1, 1.1, 1.2, 2) corresponding to ROADMAP.md phases ## Key File Locations **Entry Points:** - `.claude/get-shit-done/workflows/*.md` - User command entry points - `.claude/agents/*.md` - Agent entry points (invoked by workflows) - `.claude/get-shit-done/bin/gsd-tools.cjs` - CLI tool entry point **Configuration:** - `.planning/config.json` - Project-wide configuration (branching, model profiles, search behavior) - `.claude/settings.json` - Per-runtime agent settings (model overrides, parallelization) - `~/.gsd/defaults.json` - User-global GSD defaults (read-only in repo) **Core Logic:** - `.claude/agents/gsd-planner.md` - Phase planning logic (45KB, ~700 lines) - `.claude/agents/gsd-executor.md` - Plan execution logic (21KB, ~450 lines) - `.claude/agents/gsd-codebase-mapper.md` - Project analysis for architecture/tech docs - `.claude/get-shit-done/bin/gsd-tools.cjs` - Centralized state/git operations **State & Decisions:** - `.planning/STATE.md` - Global state (current phase, milestone, workstream, blockers) - `.planning/ROADMAP.md` - Master scope (phase numbers, descriptions, order) - `.planning/phases/N/CONTEXT.md` - User decisions for phase N - `.planning/phases/N/PLAN-*.md` - Task breakdowns (executable prompts) **Execution & Verification:** - `.planning/phases/N/SUMMARY-*.md` - Execution results, commit hashes, artifacts - `.planning/phases/N/VERIFICATION.md` - Success criteria, quality gates, test requirements - `.planning/REQUIREMENTS.md` - Requirement IDs (REQ-01, etc.) for traceability **Documentation & References:** - `.claude/get-shit-done/references/model-profiles.md` - Agent model selection strategies - `.claude/get-shit-done/references/planning-config.md` - Configuration options spec - `.claude/get-shit-done/references/checkpoints.md` - Pause point definition and usage ## Naming Conventions **Files:** - Workflows: kebab-case (e.g., `execute-phase.md`, `plan-phase.md`) - Agents: kebab-case with gsd- prefix (e.g., `gsd-planner.md`, `gsd-executor.md`) - Phase documents: UPPERCASE with phase number (e.g., `PLAN-01.md`, `SUMMARY-02.md`) - Config files: lowercase (e.g., `config.json`, `settings.json`) - State files: UPPERCASE (e.g., `STATE.md`, `ROADMAP.md`) **Directories:** - Hidden IDE-specific: dot-prefixed (`.claude`, `.agent`, `.gemini`) - Planning: `.planning` with phase structure (phases/1/, phases/1.1/, etc.) - Tools/resources: lowercase (agents, workflows, bin, lib, references, templates) **Phase Numbering:** - Integer phases: 1, 2, 3 (major phases) - Decimal sub-phases: 1.1, 1.2, 1.3 (sub-divisions of phase 1) - Directory structure mirrors numbering: `.planning/phases/1/`, `.planning/phases/1.1/` ## Where to Add New Code **New Agent:** 1. Create ``.claude/agents/gsd-{agent-name}.md`` with role definition, process steps, tools 2. Size: Keep under 50KB (agents are consumed whole as context) 3. Register: List in agent registry within workflow files and orchestrator 4. Mirror: Copy to `.agent/agents/`, `.gemini/agents/`, etc. after validation **New Workflow:** 1. Create `.claude/get-shit-done/workflows/{workflow-name}.md` 2. Define: ``, `` with numbered steps, subprocess calls to gsd-tools.cjs 3. Commands: If user-facing, add metadata entry in `.claude/commands/gsd/` 4. Routing: Document how workflow invokes agents (inline vs spawned via Task()) **New Reference Documentation:** 1. Create `.claude/get-shit-done/references/{topic}.md` 2. Purpose: Explain system patterns, configuration options, validation rules 3. Read by: Agents when implementing features, developers understanding system 4. Update: Link from agent files or workflow documentation **New Phase (during project execution):** 1. Create phase directory: `.planning/phases/{N}/` (where N is next phase number) 2. Create CONTEXT.md (template in references/) 3. Planner creates PLAN-*.md files 4. Add phase to ROADMAP.md with description 5. Update STATE.md current_phase field **Phase Documents (during planning):** - PLAN.md: Created by gsd-planner agent (follows template in templates/) - VERIFICATION.md: User creates to define success criteria (template available) - CONTEXT.md: Created by gsd-discuss-phase agent from user decisions ## Special Directories **`.planning/codebase/`:** - Purpose: Analysis documents for executor reference (STACK.md, ARCHITECTURE.md, CONVENTIONS.md, TESTING.md, CONCERNS.md) - Generated: By gsd-codebase-mapper agent via `/gsd:map-codebase` - Committed: Yes, documents tracked in git for future reference **`.planning/phases/N/`:** - Purpose: Execution workspace for phase N (isolated state) - Generated: Directories created by gsd-tools.cjs during phase setup - Committed: Yes, all planning docs committed (unless .planning/ in .gitignore) **`.claude/get-shit-done/bin/lib/`:** - Purpose: Supporting utilities for gsd-tools.cjs - Contents: Shared functions for JSON parsing, git operations, file I/O - Generated: No, part of GSD system - Committed: Yes, part of codebase **`node_modules/`:** - Purpose: NPM dependencies (if any) - Generated: Yes, by `npm install` - Committed: No, excluded via .gitignore --- *Structure analysis: 2026-03-27*