architecture/README.md

Architecture

The organizational source of truth for how we build software with OpenCode.

This repository contains the structure for our OpenCode configuration: skills, tools, and agents that make AI-assisted development predictable and effective.

Core Concepts

OpenCode uses three component types:

Component	Location	Purpose	Example
Skills	.opencode/skills/	Reference knowledge	issue-writing knows how to structure good issues
Tools	.opencode/plugins/	Custom functions, provided by plugins	tools registers the tea-* Gitea CLI tools
Agents	.opencode/agents/	Specialized subagents	code-reviewer handles PR reviews

Quick Start

Installation

# Clone the repository
git clone ssh://git@code.flowmade.one/flowmade-one/architecture.git
cd architecture

# Install symlinks to ~/.config/opencode/
make install

This creates symlinks at:

• ~/.config/opencode/skills/ → .opencode/skills/
• ~/.config/opencode/plugins/ → .opencode/plugins/
• ~/.config/opencode/agents/ → .opencode/agents/

Uninstallation

make uninstall

Status

make status

Shows current symlink state for each component.

Restart LLMs

make restart-llm

Restarts all local LLM services (atlas, forge, swift).

Project Structure

architecture/
├── legacy/                     # Historical Claude Code content
│   ├── old/                    # Early Claude Code structure
│   ├── old2/                   # Most recent Claude Code structure
│   ├── docs/                   # Documentation
│   ├── learnings/              # Governance learnings
│   └── scripts/                # Bash scripts
│
├── .opencode/                  # OpenCode configuration
│   ├── skills/                 # Reference knowledge (SKILL.md files)
│   ├── plugins/                # Plugins registering custom tools (TypeScript)
│   └── agents/                 # Specialized subagents (AGENT.md files)
│
├── Makefile                    # Symlink management
├── settings.json               # Historical reference (Claude Code)
└── README.md                   # This file

Adding Components

Skills

Create .opencode/skills/<name>/SKILL.md:

---
name: skill-name
description: What this skill does and when to use it
---

# Skill Title

Content goes here...

Skills are auto-discovered by OpenCode and available via the skill tool.

Tools

Tools are registered by plugins under .opencode/plugins/. Create .opencode/plugins/<name>/index.ts:

import { Plugin } from "@opencode/plugin"

import type { Info } from "@opencode/plugin/promise/tool"

const example: Info = {
  name: "example",
  description: "What this tool does",
  input: {
    type: "object",
    properties: {
      param: { type: "string", description: "Parameter description" },
    },
    required: ["param"],
    additionalProperties: false,
  },
  async execute(input) {
    const { param } = input as { param: string }
    // Your implementation
    return { content: `result for ${param}` }
  },
}

export default Plugin.define({
  id: "example",
  async setup(ctx) {
    await ctx.tool.transform((editor) => {
      editor.add(example)
    })
  },
})

Tool input schemas are plain JSON Schema, and execution returns structured content. Plugins under .opencode/plugins/ are auto-discovered and their tools are available to the LLM.

Agents

Create .opencode/agents/<name>.md:

---
description: What this agent does and when to use it
mode: subagent
permission:
  edit: deny
  bash: deny
---

You are an agent that specializes in...

Agents can be invoked with @agent-name or automatically by primary agents.

Referencing Legacy Content

The legacy/ folder contains the original Claude Code structure for reference:

• legacy/old2/ - Most recent Claude Code structure with skills, agents, commands
• legacy/old2/manifesto.md - Organization vision and beliefs
• legacy/old2/software-architecture.md - Architectural patterns and principles
• legacy/old2/learnings/ - Historical learnings (if any)

These are preserved for historical reference but not actively used by OpenCode.

Existing OpenCode Configuration

Your global OpenCode configuration is at ~/.config/opencode/opencode.json. This repository does not manage that file.

The settings.json in this repository is kept for historical reference (it was used with Claude Code).

License

MIT