Hugo Nijhuis
cc72ad68ed
- Move legacy content to legacy/ folder (old, old2, docs, learnings, scripts) - Create new .opencode/ structure with skills/, tools/, agents/ folders - Update Makefile to symlink to ~/.config/opencode/ instead of ~/.claude/ - Update Makefile to manage skills, tools, and agents (remove settings.json) - Simplify install/uninstall (no backup logic) - Add README.md documenting the new structure - Keep settings.json as historical reference
155 lines
3.9 KiB
Markdown
155 lines
3.9 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/tools/` | Custom functions | `spawn_issues` implements multiple issues in parallel |
|
|
| **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/tools/` → `.opencode/tools/`
|
|
- `~/.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)
|
|
│ ├── 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`:
|
|
|
|
```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
|
|
|
|
Create `.opencode/tools/<name>.ts`:
|
|
|
|
```typescript
|
|
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`:
|
|
|
|
```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 |