4.2 KiB
4.2 KiB
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:
- User invokes
/gsd-*command - Command definition loads execution_context (workflow)
- Workflow orchestrates agent spawning and task execution
- Agents write outputs directly to
.planning/directories - 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