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/tools/	Custom functions	spawn_issues implements multiple issues in parallel
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/tools/ → .opencode/tools/
• ~/.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)
│   ├── tools/                  # Custom tools (TypeScript/JS)
│   └── 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

Create .opencode/tools/<name>.ts:

import { tool } from "@opencode-ai/plugin"

export default tool({
  description: "What this tool does",
  args: {
    param: tool.schema.string().describe("Parameter description"),
  },
  async execute(args) {
    // Your implementation
    return "result"
  },
})

Tools are auto-discovered and 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