116 lines
4.2 KiB
Markdown
116 lines
4.2 KiB
Markdown
# 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* |