173 lines
4.6 KiB
Markdown
173 lines
4.6 KiB
Markdown
# 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 |