# Architecture

**Analysis Date:** 2026-03-12

## Pattern Overview

**Overall:** Agent-based task automation framework built on OpenCode

**Key Characteristics:**
- Modular command/agent system with specialized agents for different phases
- Workflow-driven execution with named phases (discovery, research, plan, execute, verify)
- Direct file output pattern - agents write to `.planning/codebase/` directly
- Subagent spawning for parallel exploration tasks

## Layers

**Commands Layer:**
- Purpose: User-facing entry points for GSD operations
- Location: `.opencode/commands/gsd/`
- Contains: Markdown command definitions with YAML frontmatter
- Files: 33 command files (gsd-*.md)
- Used by: OpenCode CLI when user invokes `/gsd-*` commands

**Agents Layer:**
- Purpose: Specialized AI agents for focused tasks
- Location: `.opencode/agents/`
- Contains: Agent role definitions with tools and skills
- Files: 12 agent definitions (gsd-*.md)
- Used by: Commands that need parallel or complex task execution

**Workflows Layer:**
- Purpose: Execution logic connecting commands and agents
- Location: `.opencode/get-shit-done/workflows/`
- Contains: Step-by-step workflow definitions
- Files: 36 workflow files
- Depends on: Commands layer (referenced in command execution_context)
- Used by: Command execution context

**Supporting Layers:**
- Skills: `.opencode/skills/` - Specialized skills (e.g., model selection)
- Rules: `.opencode/rules/` - Behavior rules (e.g., work-hard rule)
- Configuration: `.opencode/package.json`, `bun.lock` - Dependencies and lockfile

## Data Flow

**Command Invocation Flow:**
1. User invokes `/gsd-*` command
2. Command definition loads execution_context (workflow)
3. Workflow orchestrates agent spawning and task execution
4. Agents write outputs directly to `.planning/` directories
5. Confirmation returned to orchestrator (not full content)

**Parallel Agent Pattern:**
- map-codebase spawns 4 parallel mapper agents (tech, arch, quality, concerns)
- Each agent explores focus area and writes specific documents
- Agents return confirmations only to minimize context load

## Key Abstractions

**Command Pattern:**
- Format: Markdown with YAML frontmatter
- Structure: name, description, argument-hint, permissions, objective, execution_context, context, when_to_use, process, success_criteria
- Location: `.opencode/commands/gsd/gsd-{name}.md`

**Agent Pattern:**
- Format: Markdown with YAML frontmatter
- Structure: name, description, mode, tools, color, skills
- Location: `.opencode/agents/gsd-{name}.md`
- Types: orchestrator agents (main), subagents (parallel workers)

**Workflow Pattern:**
- Format: Markdown with step-by-step instructions
- Location: `.opencode/get-shit-done/workflows/{name}.md`
- Called from: Command's `<execution_context>` directive

## Entry Points

**Primary Entry Point:**
- Location: `.opencode/commands/gsd/gsd-*.md` (33 commands)
- Triggers: OpenCode CLI `/gsd-*` invocation
- Responsibilities: Define command interface, load workflow, return success criteria

**Command Categories:**
- Project management: new-project, new-milestone, resume-work, pause-work
- Phase management: add-phase, remove-phase, insert-phase, list-phase-assumptions
- Execution: plan-phase, execute-phase, verify-phase, validate-phase
- Discovery: research-phase, map-codebase, discuss-phase, quick
- Verification: audit-milestone, complete-milestone, verify-work, health
- Debugging: debug, diagnose-issues, reapply-patches
- Utilities: add-todo, add-tests, set-profile, settings, help

## Error Handling

**Workflow Error Handling:**
- Phase failures trigger diagnosis workflows
- verify-work performs health checks on each phase
- audit-milestone catches incomplete work before completion

**Agent Error Patterns:**
- Subagent failures reported to orchestrator with error details
- Parallel agents - one failure doesn't cascade to others

## Cross-Cutting Concerns

**State Management:**
- Project state stored in `.planning/STATE.md`
- Milestone data in `.gsd/milestones/`
- Codebase docs in `.planning/codebase/`

**Permissions System:**
- Commands declare required permissions (read, bash, glob, grep, write, task)
- Agents declare tools they can use

---

*Architecture analysis: 2026-03-12*