# 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