docs: map existing codebase
This commit is contained in:
local
217
.planning/codebase/STRUCTURE.md
Normal file
217
.planning/codebase/STRUCTURE.md
Normal file
@@ -0,0 +1,217 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user