Migrate from Claude Code to OpenCode structure

- 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

Makefile

@@ -1,55 +1,48 @@
 .PHONY: install uninstall status
 
-CLAUDE_DIR := $(HOME)/.claude
+OPENCODE_DIR := $(HOME)/.config/opencode
 REPO_DIR := $(shell pwd)
 
 # Items to symlink
-ITEMS := scripts skills agents settings.json
+ITEMS := skills tools agents
 
 # LLM services to manage
-LLM_SERVICES := atlas forge swift sage
+LLM_SERVICES := atlas forge swift
 
 install:
-	@echo "Installing Claude Code config symlinks..."
-	@mkdir -p $(CLAUDE_DIR)
+	@echo "Installing OpenCode config symlinks..."
+	@mkdir -p $(OPENCODE_DIR)
 	@for item in $(ITEMS); do \
-		if [ -e "$(REPO_DIR)/$$item" ]; then \
-			if [ -L "$(CLAUDE_DIR)/$$item" ]; then \
+		if [ -e "$(REPO_DIR)/.opencode/$$item" ]; then \
+			if [ -L "$(OPENCODE_DIR)/$$item" ]; then \
 				echo "  $$item: already symlinked"; \
-			elif [ -e "$(CLAUDE_DIR)/$$item" ]; then \
-				echo "  $$item: backing up existing to $$item.bak"; \
-				mv "$(CLAUDE_DIR)/$$item" "$(CLAUDE_DIR)/$$item.bak"; \
-				ln -s "$(REPO_DIR)/$$item" "$(CLAUDE_DIR)/$$item"; \
-				echo "  $$item: symlinked"; \
 			else \
-				ln -s "$(REPO_DIR)/$$item" "$(CLAUDE_DIR)/$$item"; \
+				ln -s "$(REPO_DIR)/.opencode/$$item" "$(OPENCODE_DIR)/$$item"; \
 				echo "  $$item: symlinked"; \
 			fi \
+		else \
+			echo "  $$item: skipped (not found)"; \
 		fi \
 	done
-	@echo "Done! Restart Claude Code to apply changes."
+	@echo "Done!"
 
 uninstall:
-	@echo "Removing Claude Code config symlinks..."
+	@echo "Removing OpenCode config symlinks..."
 	@for item in $(ITEMS); do \
-		if [ -L "$(CLAUDE_DIR)/$$item" ]; then \
-			rm "$(CLAUDE_DIR)/$$item"; \
+		if [ -L "$(OPENCODE_DIR)/$$item" ]; then \
+			rm "$(OPENCODE_DIR)/$$item"; \
 			echo "  $$item: removed symlink"; \
-			if [ -e "$(CLAUDE_DIR)/$$item.bak" ]; then \
-				mv "$(CLAUDE_DIR)/$$item.bak" "$(CLAUDE_DIR)/$$item"; \
-				echo "  $$item: restored backup"; \
-			fi \
 		fi \
 	done
 	@echo "Done!"
 
 status:
-	@echo "Claude Code config status:"
+	@echo "OpenCode config status:"
 	@for item in $(ITEMS); do \
-		if [ -L "$(CLAUDE_DIR)/$$item" ]; then \
-			target=$$(readlink "$(CLAUDE_DIR)/$$item"); \
+		if [ -L "$(OPENCODE_DIR)/$$item" ]; then \
+			target=$$(readlink "$(OPENCODE_DIR)/$$item"); \
 			echo "  $$item: symlink -> $$target"; \
-		elif [ -e "$(CLAUDE_DIR)/$$item" ]; then \
+		elif [ -e "$(OPENCODE_DIR)/$$item" ]; then \
 			echo "  $$item: exists (not symlinked)"; \
 		else \
 			echo "  $$item: not found"; \
@@ -58,7 +51,7 @@ status:
 
 restart-llm-%:
 	@echo "Restarting com.vllm-mlx-$*..."
-	@launchctl bootout gui/$$(id -u) ~/Library/LaunchAgents/com.vllm-mlx-$*.plist || true
-	@launchctl bootstrap gui/$$(id -u) ~/Library/LaunchAgents/com.vllm-mlx-$*.plist
+	@launchctl bootout gui/$$(id -u) ~/Library/LaunchAgents/com.vllm-mlx.$*.plist || true
+	@launchctl bootstrap gui/$$(id -u) ~/Library/LaunchAgents/com.vllm-mlx.$*.plist
 
-restart-llm: $(patsubst %,restart-llm-%,$(LLM_SERVICES))
+restart-llm: $(patsubst %,restart-llm-%,$(LLM_SERVICES))

README.md

@@ -0,0 +1,155 @@
+# 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