family/AgenticCode
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4ef27598a06f9d354e550b778f82e5377d8d6659
AgenticCode/.planning/codebase/ARCHITECTURE.md
local d963902a28 docs: map existing codebase
2026-03-27 00:21:00 +00:00

8.0 KiB
Raw Blame History

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 View Git Blame Copy Permalink