docs: map existing codebase
This commit is contained in:
local
170
.planning/codebase/ARCHITECTURE.md
Normal file
170
.planning/codebase/ARCHITECTURE.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# Architecture
|
||||
|
||||
**Analysis Date:** 2026-03-27
|
||||
|
||||
## Pattern Overview
|
||||
|
||||
**Overall:** Agent-orchestrated agentic code framework (GSD - Get Shit Done)
|
||||
|
||||
**Key Characteristics:**
|
||||
- Multi-agent cooperative system: 18 specialized agents working in coordinated workflows
|
||||
- Document-driven state management: All decisions and progress stored as Markdown files
|
||||
- Workflow-based orchestration: 56 workflows guide agent interactions and user engagement
|
||||
- Agentic code execution: Plans are executable prompts for Claude model execution
|
||||
- Extensible per-runtime: Same architecture replicated across 7 IDE/agent providers (.claude, .agent, .gemini, .codex, .cursor, .windsurf, .opencode)
|
||||
|
||||
## Layers
|
||||
|
||||
**Orchestration Layer:**
|
||||
- Purpose: Coordinate user commands, route to agents, manage phase/milestone progression
|
||||
- Location: `.claude/get-shit-done/workflows/`
|
||||
- Contains: 56 workflow definitions (markdown files), each defining a multi-step process
|
||||
- Depends on: gsd-tools.cjs CLI for state management, git operations, config parsing
|
||||
- Used by: All commands (user entry points)
|
||||
|
||||
**Agent Layer:**
|
||||
- Purpose: Specialized reasoning for different task types (planning, execution, research, verification, mapping)
|
||||
- Location: `.claude/agents/` (18 agents)
|
||||
- Contains: Agent role definitions, instructions, tool access lists
|
||||
- Agents: gsd-planner, gsd-executor, gsd-phase-researcher, gsd-verifier, gsd-debugger, gsd-codebase-mapper, gsd-integration-checker, gsd-ui-auditor, gsd-plan-checker, and 9 others
|
||||
- Depends on: Workflow coordination, tools (Read, Write, Bash, Grep, Glob, WebFetch)
|
||||
- Used by: Orchestration workflows, invoked via `@agent-name` or Task() calls
|
||||
|
||||
**State Management Layer:**
|
||||
- Purpose: Persistent tracking of project progress, decisions, and configuration
|
||||
- Location: `.planning/` (global state), phase directories (phase-local state)
|
||||
- Contains: STATE.md (global), CONTEXT.md (decisions), ROADMAP.md (scope), PLAN.md (task breakdown), SUMMARY.md (execution results), VERIFICATION.md (quality gates)
|
||||
- Depends on: gsd-tools.cjs for parsing, git for history
|
||||
- Used by: All agents and orchestration layer
|
||||
|
||||
**Tool Layer:**
|
||||
- Purpose: Provide execution capabilities for agents
|
||||
- Location: Various (bash, file I/O, git, web)
|
||||
- Tools: Read, Write, Edit, Bash, Grep, Glob, WebFetch, mcp__context7__*
|
||||
- Depends on: Agent invocations
|
||||
- Used by: Agents during execution
|
||||
|
||||
**CLI Tool Layer:**
|
||||
- Purpose: Centralized state/config operations shared across 50+ workflow/agent files
|
||||
- Location: `.claude/get-shit-done/bin/gsd-tools.cjs` (~1000 lines)
|
||||
- Contains: 100+ commands for state management, phase operations, validation, progress tracking
|
||||
- Depends on: Node.js built-ins, git, file system
|
||||
- Used by: Every workflow and agent (called via bash subprocess)
|
||||
|
||||
## Data Flow
|
||||
|
||||
**Phase Planning Flow:**
|
||||
|
||||
1. User invokes `/gsd:plan-phase PHASE_NUMBER`
|
||||
2. Orchestrator (plan-phase workflow) loads PHASE state via gsd-tools.cjs
|
||||
3. Planner agent (gsd-planner) reads CONTEXT.md (user decisions), codebase structure, creates PLAN.md
|
||||
4. Plan Checker agent validates PLAN.md structure and quality
|
||||
5. PLAN.md written to phase directory
|
||||
6. User reviews, optionally discusses via `/gsd:discuss-phase` → updates CONTEXT.md
|
||||
7. Flow loops if plan changes needed
|
||||
|
||||
**Phase Execution Flow:**
|
||||
|
||||
1. User invokes `/gsd:execute-phase PHASE_NUMBER`
|
||||
2. Executor orchestrator loads phase plans (multiple per phase)
|
||||
3. Plans grouped by wave (dependency-aware parallelization)
|
||||
4. For each wave:
|
||||
- Executor agent loads PLAN.md
|
||||
- Executes tasks sequentially (each task → code change → test verification)
|
||||
- Commits per-task (atomic commits for rollback safety)
|
||||
- Writes SUMMARY.md with results
|
||||
5. Orchestrator collects all SUMMARY.md files
|
||||
6. Verifier agent checks phase completion against VERIFICATION.md
|
||||
7. STATE.md updated with completion status
|
||||
8. Planning docs committed to git (if commit_docs: true)
|
||||
|
||||
**Verification Flow:**
|
||||
|
||||
1. Phase execution completes, SUMMARY.md produced
|
||||
2. Verifier agent compares output against VERIFICATION.md (user-defined success criteria)
|
||||
3. If gaps detected: Trigger `/gsd:plan-phase --gaps` for remedial planning
|
||||
4. Remedial PLAN.md created with gap-closure tasks
|
||||
5. Execute → Verify loop continues until no gaps
|
||||
|
||||
**State Management Flow:**
|
||||
|
||||
1. STATE.md maintains global position: current_phase, current_milestone, workstream, blockers
|
||||
2. Phase directories contain CONTEXT.md (decisions), PLAN.md (tasks), SUMMARY.md (results), VERIFICATION.md (success gates)
|
||||
3. ROADMAP.md holds master scope: all phases with descriptions
|
||||
4. .planning/config.json: branching strategy, model profiles, search behavior
|
||||
5. Each operation updates relevant state file, committed atomically
|
||||
|
||||
## Key Abstractions
|
||||
|
||||
**Phase:**
|
||||
- Purpose: Logical unit of work scoped by user, contains multiple Plans
|
||||
- Examples: `1`, `1.1`, `1.2` (decimal numbering for sub-phases)
|
||||
- Pattern: Each phase has directory `.planning/phases/N/` with CONTEXT.md, PLAN.md, SUMMARY.md, VERIFICATION.md
|
||||
|
||||
**Plan:**
|
||||
- Purpose: Executable task breakdown derived from phase scope (typically 2-3 tasks per plan)
|
||||
- Examples: `PLAN-01.md`, `PLAN-02.md` within a phase directory
|
||||
- Pattern: PLAN.md contains frontmatter (metadata), objective, context references, tasks array, success criteria
|
||||
|
||||
**Task:**
|
||||
- Purpose: Atomic unit of work within a plan (code change, test, commit)
|
||||
- Types: `type="auto"` (fully autonomous), `type="checkpoint"` (pause before), `type="review"` (requires human sign-off)
|
||||
- Pattern: Task has action (what to do), verification criteria, expected artifacts
|
||||
|
||||
**Workflow:**
|
||||
- Purpose: Multi-step process coordinating user input and agent actions
|
||||
- Examples: `plan-phase.md`, `execute-phase.md`, `discuss-phase.md`
|
||||
- Pattern: Workflows define steps with conditional branching, agent spawning, state updates
|
||||
|
||||
**Agent Profiles:**
|
||||
- Purpose: Model selection strategy for agent execution (quality vs cost)
|
||||
- Profiles: `quality` (Opus for all), `balanced` (Opus planning, Sonnet execution), `budget` (minimal Opus)
|
||||
- Pattern: Resolved via gsd-tools.cjs based on `.planning/config.json` model_profile setting
|
||||
|
||||
## Entry Points
|
||||
|
||||
**Command Entry Point:**
|
||||
- Location: `.claude/get-shit-done/workflows/` (any `.md` file)
|
||||
- Triggers: User invokes `/gsd:WORKFLOW_NAME [args]`
|
||||
- Responsibilities: Parse arguments, call gsd-tools.cjs init command, route to agents or inline execution
|
||||
|
||||
**Agent Entry Point:**
|
||||
- Location: `.claude/agents/AGENT_NAME.md`
|
||||
- Triggers: Spawned by orchestrator via `@AGENT_NAME` mention or Task() call
|
||||
- Responsibilities: Load context, read mandatory files, execute role-specific logic, return results
|
||||
|
||||
**Tool Entry Point:**
|
||||
- Location: `.claude/get-shit-done/bin/gsd-tools.cjs`
|
||||
- Triggers: `node gsd-tools.cjs <command> [args]`
|
||||
- Responsibilities: Parse subcommands, perform atomic state/git operations, output JSON
|
||||
|
||||
## Error Handling
|
||||
|
||||
**Strategy:** Graceful degradation with checkpoint pauses
|
||||
|
||||
**Patterns:**
|
||||
- **Auth Errors:** Executor pauses at checkpoint, waits for user to provide credentials
|
||||
- **Verification Failures:** Verifier identifies gaps, planner creates remedial PLAN.md, executor runs gap-closure phase
|
||||
- **Invalid State:** gsd-tools.cjs validate commands detect inconsistencies, suggest repairs
|
||||
- **Parse Failures:** Frontmatter validation catches schema violations early
|
||||
- **Git Conflicts:** Executor respects branching strategy, creates feature branches per config
|
||||
|
||||
## Cross-Cutting Concerns
|
||||
|
||||
**Logging:** Shell output captured from gsd-tools.cjs, bash task execution. Errors logged to console, summary tracked in SUMMARY.md.
|
||||
|
||||
**Validation:** gsd-tools.cjs provides `validate` commands for:
|
||||
- Phase numbering consistency
|
||||
- Plan structure (required fields, task arrays)
|
||||
- References (@ paths resolve to existing files)
|
||||
- Artifacts (must_haves tracked in PLAN.md)
|
||||
|
||||
**Authentication:** Config stored in `~/.gsd/` (outside repo), environment variable overrides for CI. Secrets never committed to git.
|
||||
|
||||
**Atomicity:** gsd-tools.cjs commit command handles commit_docs check and .gitignore detection. Each task commits separately for rollback safety.
|
||||
|
||||
**Determinism:** Model profiles ensure same agent type always gets same model (unless inherit mode). Frontmatter schema validation prevents parsing ambiguity.
|
||||
|
||||
---
|
||||
|
||||
*Architecture analysis: 2026-03-27*
|
||||
Reference in New Issue
Block a user