# 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

```bash
# 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

```bash
make uninstall
```

### Status

```bash
make status
```

Shows current symlink state for each component.

### Restart LLMs

```bash
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`:

```markdown
---
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`:

```typescript
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`:

```markdown
---
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