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