# tedivm/opencode-config architecture

> Architecture diagram of the GitHub repository tedivm/opencode-config, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tedivm/opencode-config
- Repository: https://github.com/tedivm/opencode-config

## Overview

#### Purpose and Runtime

This is a personal `opencode` CLI configuration repository, intended to populate `~/.config/opencode`. It defines agent behavior, model/provider integration, reusable instruction skills, and custom prompt commands rather than an application service. The primary runtime is the OpenCode CLI, configured by `opencode.jsonc`, with persisted conversation state in `dcp.jsonc`.

#### Core Configuration Boundary

`opencode.jsonc` is the central integration point for the local vLLM OpenAI-compatible provider, the `qwen3.6-27b` model, LSP/formatting capabilities, Context7 MCP documentation lookup, and the `@tarquinen/opencode-dcp` plugin. `AGENTS.md` establishes global agent operating rules. Secrets and endpoint settings are deliberately external environment files rather than repository configuration.

Paths: `opencode.jsonc`, `dcp.jsonc`, `AGENTS.md`.

#### Agent Specialization

Role-specific agent prompts define delegated work patterns and boundaries: architecture design, repository research, and review. These are reusable subagent personas invoked by the OpenCode workflow, rather than executable processes.

Paths: `agents/architect.md`, `agents/researcher.md`, `agents/reviewer.md`.

#### Command Layer

Custom commands package recurring, user-invoked workflows: repository critique, OpenSpec proposal/spec drift analysis, GitHub Action upgrades, response compression, and architecture/design review. Commands orchestrate configured agents and skills through prompt instructions; they are the main interactive entry points beyond the base CLI.

Paths: `commands/repo-critique.md`, `commands/openspec-review.md`, `commands/document-architecture.md`.

#### Skill Library

Each `skills/*/SKILL.md` is a domain workflow contract that supplies procedural instructions, conventions, and sometimes supporting assets or reference material. Major domains include project bootstrapping, code exploration, command/skill authoring, Python scaffolding, OpenSpec setup, PR creation, GitHub operations, JSON processing, quality validation, and design-system work.

Paths: `skills/bootstrapping-plan/SKILL.md`, `skills/exploring-code/SKILL.md`, `skills/robs-design/SKILL.md`.

#### Skill Assets and Reference Knowledge

Some skills carry executable or static supporting material. Markdown conversion invokes a Python integration with Microsoft MarkItDown; the Rob’s theme skill supplies CSS tokens/layout/component assets; architecture/design skills include reference patterns for FastAPI, Celery, SQLAlchemy, Pydantic, and Typer. These resources constrain generated output but are not a shared application runtime.

Paths: `skills/converting-to-markdown/scripts/markitdown-llm.py`, `skills/robs-theme/assets/variables.css`, `skills/robs-design/references/fastapi-routes.md`.

#### Installation and Validation

`make install` installs `snip`, an output-compression dependency used by the configuration/workflows. Repository validation is implemented in Node.js and invoked by the Makefile and CI. GitHub Actions enforce formatting and validation on changes.

Paths: `Makefile`, `scripts/validate.js`, `.github/workflows/validate.yml`.

#### External Services

The configuration depends on a locally hosted vLLM server through an OpenAI-compatible API, Context7 via MCP for documentation retrieval, GitHub through `gh`-oriented skills/commands, and the DCP plugin for conversation persistence. Credentials and host data are expected from untracked files such as `.llm_host`, `.openai_api_key`, and `.context7-api-key`.

Main entry points: [`opencode.jsonc`](https://github.com/tedivm/opencode-config/blob/main/opencode.jsonc) (OpenCode configuration), [`skills/robs-design/SKILL.md`](https://github.com/tedivm/opencode-config/blob/main/skills/robs-design/SKILL.md) (Rob's design skill), [`Makefile`](https://github.com/tedivm/opencode-config/blob/main/Makefile) (Make targets), [`scripts/validate.js`](https://github.com/tedivm/opencode-config/blob/main/scripts/validate.js) (Configuration validator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["OpenCode Runtime"]
  node_opencode{{"OpenCode CLI<br/>CLI runtime"}}
  node_config["OpenCode configuration<br/>[opencode.jsonc]"]
  node_agent_rules["Global agent rules<br/>agent policy<br/>[AGENTS.md]"]
  node_conversation_state[("Conversation state<br/>DCP state<br/>[dcp.jsonc]")]
  node_dcp_plugin{{"DCP plugin<br/>OpenCode plugin"}}
end

subgraph group_prompts["Workflow Library"]
  node_agents["Specialist agents<br/>prompt personas"]
  node_architect_agent["Architect persona<br/>agent prompt<br/>[architect.md]"]
  node_researcher_agent["Researcher persona<br/>agent prompt<br/>[researcher.md]"]
  node_reviewer_agent["Reviewer persona<br/>agent prompt<br/>[reviewer.md]"]
  node_commands["Custom commands<br/>interactive workflows"]
  node_repo_critique["Repository critique<br/>command prompt<br/>[repo-critique.md]"]
  node_openspec_review["OpenSpec review<br/>command prompt<br/>[openspec-review.md]"]
  node_architecture_command["Architecture review<br/>command prompt"]
  node_skills["Skill library<br/>workflow contracts"]
  node_bootstrapping_skill["Bootstrapping skill<br/>[SKILL.md]"]
  node_exploration_skill["Code exploration skill<br/>[SKILL.md]"]
  node_design_skill["Rob's design skill<br/>[SKILL.md]"]
end

subgraph group_assets["Skill Assets"]
  node_markdown_converter["MarkItDown integration<br/>Python script<br/>[markitdown-llm.py]"]
  node_theme_tokens["Theme CSS tokens<br/>design assets<br/>[variables.css]"]
  node_architecture_reference["FastAPI route patterns<br/>reference knowledge<br/>[fastapi-routes.md]"]
end

subgraph group_delivery["Installation &amp; Validation"]
  node_makefile["Make targets<br/>task runner"]
  node_validator["Configuration validator<br/>Node.js validation<br/>[validate.js]"]
  node_ci["Validation workflow<br/>GitHub Actions<br/>[validate.yml]"]
end

subgraph group_external["External Integrations"]
  node_vllm{{"Local vLLM server<br/>OpenAI-compatible API"}}
  node_context7{{"Context7<br/>MCP documentation service"}}
  node_github{{"GitHub<br/>external platform"}}
  node_environment["Untracked environment files<br/>credentials and endpoints"]
end

node_opencode -->|"loads"| node_config
node_opencode -->|"follows"| node_agent_rules
node_config -->|"configures provider"| node_vllm
node_environment -.->|"supplies credentials"| node_config
node_config -->|"configures MCP"| node_context7
node_config -->|"enables"| node_dcp_plugin
node_dcp_plugin -->|"persists"| node_conversation_state
node_opencode -->|"invokes"| node_commands
node_commands -->|"includes"| node_repo_critique
node_commands -->|"includes"| node_openspec_review
node_commands -->|"includes"| node_architecture_command
node_commands -->|"delegates to"| node_agents
node_agents -->|"includes"| node_architect_agent
node_agents -->|"includes"| node_researcher_agent
node_agents -->|"includes"| node_reviewer_agent
node_commands -->|"uses"| node_skills
node_skills -->|"includes"| node_bootstrapping_skill
node_skills -->|"includes"| node_exploration_skill
node_skills -->|"includes"| node_design_skill
node_design_skill -->|"uses"| node_theme_tokens
node_design_skill -->|"consults"| node_architecture_reference
node_skills -->|"uses"| node_markdown_converter
node_commands -->|"operates through gh"| node_github
node_makefile -->|"runs"| node_validator
node_ci -->|"runs"| node_validator
node_makefile -.->|"installs configuration dependencies"| node_opencode

click node_config "https://github.com/tedivm/opencode-config/blob/main/opencode.jsonc"
click node_agent_rules "https://github.com/tedivm/opencode-config/blob/main/AGENTS.md"
click node_conversation_state "https://github.com/tedivm/opencode-config/blob/main/dcp.jsonc"
click node_architect_agent "https://github.com/tedivm/opencode-config/blob/main/agents/architect.md"
click node_researcher_agent "https://github.com/tedivm/opencode-config/blob/main/agents/researcher.md"
click node_reviewer_agent "https://github.com/tedivm/opencode-config/blob/main/agents/reviewer.md"
click node_repo_critique "https://github.com/tedivm/opencode-config/blob/main/commands/repo-critique.md"
click node_openspec_review "https://github.com/tedivm/opencode-config/blob/main/commands/openspec-review.md"
click node_architecture_command "https://github.com/tedivm/opencode-config/blob/main/commands/document-architecture.md"
click node_bootstrapping_skill "https://github.com/tedivm/opencode-config/blob/main/skills/bootstrapping-plan/SKILL.md"
click node_exploration_skill "https://github.com/tedivm/opencode-config/blob/main/skills/exploring-code/SKILL.md"
click node_design_skill "https://github.com/tedivm/opencode-config/blob/main/skills/robs-design/SKILL.md"
click node_markdown_converter "https://github.com/tedivm/opencode-config/blob/main/skills/converting-to-markdown/scripts/markitdown-llm.py"
click node_theme_tokens "https://github.com/tedivm/opencode-config/blob/main/skills/robs-theme/assets/variables.css"
click node_architecture_reference "https://github.com/tedivm/opencode-config/blob/main/skills/robs-design/references/fastapi-routes.md"
click node_makefile "https://github.com/tedivm/opencode-config/blob/main/Makefile"
click node_validator "https://github.com/tedivm/opencode-config/blob/main/scripts/validate.js"
click node_ci "https://github.com/tedivm/opencode-config/blob/main/.github/workflows/validate.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_opencode,node_config,node_agent_rules,node_conversation_state,node_dcp_plugin toneBlue
class node_agents,node_architect_agent,node_researcher_agent,node_reviewer_agent,node_commands,node_repo_critique,node_openspec_review,node_architecture_command,node_skills,node_bootstrapping_skill,node_exploration_skill,node_design_skill toneAmber
class node_markdown_converter,node_theme_tokens,node_architecture_reference toneMint
class node_makefile,node_validator,node_ci toneRose
class node_vllm,node_context7,node_github,node_environment toneIndigo
```

## Components

### OpenCode Runtime

- **OpenCode CLI**: CLI runtime · Loads this repository as the user configuration.
- [OpenCode configuration](https://github.com/tedivm/opencode-config/blob/main/opencode.jsonc): configuration · Central provider, capability, MCP, and plugin integration point. · `opencode.jsonc`
- [Global agent rules](https://github.com/tedivm/opencode-config/blob/main/AGENTS.md): agent policy · `AGENTS.md`
- [Conversation state](https://github.com/tedivm/opencode-config/blob/main/dcp.jsonc): DCP state · `dcp.jsonc`
- **DCP plugin**: OpenCode plugin · Persists conversation state through the configured plugin.

### Workflow Library

- **Specialist agents**: prompt personas · Architecture, research, and review delegation roles.
- [Architect persona](https://github.com/tedivm/opencode-config/blob/main/agents/architect.md): agent prompt · `agents/architect.md`
- [Researcher persona](https://github.com/tedivm/opencode-config/blob/main/agents/researcher.md): agent prompt · `agents/researcher.md`
- [Reviewer persona](https://github.com/tedivm/opencode-config/blob/main/agents/reviewer.md): agent prompt · `agents/reviewer.md`
- **Custom commands**: interactive workflows · User-invoked prompts that orchestrate agents and skills.
- [Repository critique](https://github.com/tedivm/opencode-config/blob/main/commands/repo-critique.md): command prompt · `commands/repo-critique.md`
- [OpenSpec review](https://github.com/tedivm/opencode-config/blob/main/commands/openspec-review.md): command prompt · `commands/openspec-review.md`
- [Architecture review](https://github.com/tedivm/opencode-config/blob/main/commands/document-architecture.md): command prompt · `commands/document-architecture.md`
- **Skill library**: workflow contracts · Reusable procedural guidance for generation and operations.
- [Bootstrapping skill](https://github.com/tedivm/opencode-config/blob/main/skills/bootstrapping-plan/SKILL.md): skill · `skills/bootstrapping-plan/SKILL.md`
- [Code exploration skill](https://github.com/tedivm/opencode-config/blob/main/skills/exploring-code/SKILL.md): skill · `skills/exploring-code/SKILL.md`
- [Rob's design skill](https://github.com/tedivm/opencode-config/blob/main/skills/robs-design/SKILL.md): skill · `skills/robs-design/SKILL.md`

### Skill Assets

- [MarkItDown integration](https://github.com/tedivm/opencode-config/blob/main/skills/converting-to-markdown/scripts/markitdown-llm.py): Python script · Converts content to Markdown using Microsoft MarkItDown. · `skills/converting-to-markdown/scripts/markitdown-llm.py`
- [Theme CSS tokens](https://github.com/tedivm/opencode-config/blob/main/skills/robs-theme/assets/variables.css): design assets · `skills/robs-theme/assets/variables.css`
- [FastAPI route patterns](https://github.com/tedivm/opencode-config/blob/main/skills/robs-design/references/fastapi-routes.md): reference knowledge · `skills/robs-design/references/fastapi-routes.md`

### Installation & Validation

- [Make targets](https://github.com/tedivm/opencode-config/blob/main/Makefile): task runner · Installs dependencies and invokes validation. · `Makefile`
- [Configuration validator](https://github.com/tedivm/opencode-config/blob/main/scripts/validate.js): Node.js validation · `scripts/validate.js`
- [Validation workflow](https://github.com/tedivm/opencode-config/blob/main/.github/workflows/validate.yml): GitHub Actions · Enforces formatting and validation on changes. · `.github/workflows/validate.yml`

### External Integrations

- **Local vLLM server**: OpenAI-compatible API
- **Context7**: MCP documentation service
- **GitHub**: external platform · Accessed by gh-oriented workflows.
- **Untracked environment files**: credentials and endpoints · Provides host and API credentials outside repository configuration.

## Connections

- OpenCode CLI → OpenCode configuration: loads
- OpenCode CLI → Global agent rules: follows
- OpenCode configuration → Local vLLM server: configures provider
- Untracked environment files → OpenCode configuration: supplies credentials
- OpenCode configuration → Context7: configures MCP
- OpenCode configuration → DCP plugin: enables
- DCP plugin → Conversation state: persists
- OpenCode CLI → Custom commands: invokes
- Custom commands → Repository critique: includes
- Custom commands → OpenSpec review: includes
- Custom commands → Architecture review: includes
- Custom commands → Specialist agents: delegates to
- Specialist agents → Architect persona: includes
- Specialist agents → Researcher persona: includes
- Specialist agents → Reviewer persona: includes
- Custom commands → Skill library: uses
- Skill library → Bootstrapping skill: includes
- Skill library → Code exploration skill: includes
- Skill library → Rob's design skill: includes
- Rob's design skill → Theme CSS tokens: uses
- Rob's design skill → FastAPI route patterns: consults
- Skill library → MarkItDown integration: uses
- Custom commands → GitHub: operates through gh
- Make targets → Configuration validator: runs
- Validation workflow → Configuration validator: runs
- Make targets → OpenCode CLI: installs configuration dependencies