AgenticCode/.planning/codebase/STRUCTURE.md

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 <command>

.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: <purpose>, <process> 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