diff --git a/.opencode/README.md b/.opencode/README.md
new file mode 100644
index 00000000..77231544
--- /dev/null
+++ b/.opencode/README.md
@@ -0,0 +1,823 @@
+
+
+
+
+# OpenAgents Control (OAC)
+
+### Control your AI patterns. Get repeatable results.
+
+**AI agents that learn YOUR coding patterns and generate matching code every time.**
+
+π― **Pattern Control** - Define your patterns once, AI uses them forever
+β **Approval Gates** - Review and approve before execution
+π **Repeatable Results** - Same patterns = Same quality code
+π **Editable Agents** - Full control over AI behavior
+π₯ **Team-Ready** - Everyone uses the same patterns
+
+**Multi-language:** TypeScript β’ Python β’ Go β’ Rust β’ C# β’ Any language*
+**Model Agnostic:** Claude β’ GPT β’ Gemini β’ MiniMax β’ Local models
+
+
+[](https://github.com/darrenhinde/OpenAgentsControl/stargazers)
+[](https://x.com/DarrenBuildsAI)
+[](https://opensource.org/licenses/MIT)
+[](https://github.com/darrenhinde/OpenAgentsControl/commits/main)
+
+[π Quick Start](#-quick-start) β’ [π» Show Me Code](#-example-workflow) β’ [πΊοΈ Roadmap](https://github.com/darrenhinde/OpenAgentsControl/projects) β’ [π¬ Community](https://nextsystems.ai)
+
+
+
+---
+
+> **Built on [OpenCode](https://opencode.ai)** - An open-source AI coding framework. OAC extends OpenCode with specialized agents, context management, and team workflows.
+
+---
+
+## The Problem
+
+Most AI agents are like hiring a developer who doesn't know your codebase. They write generic code. You spend hours rewriting, refactoring, and fixing inconsistencies. Tokens burned. Time wasted. No actual work done.
+
+**Example:**
+```typescript
+// What AI gives you (generic)
+export async function POST(request: Request) {
+ const data = await request.json();
+ return Response.json({ success: true });
+}
+
+// What you actually need (your patterns)
+export async function POST(request: Request) {
+ const body = await request.json();
+ const validated = UserSchema.parse(body); // Your Zod validation
+ const result = await db.users.create(validated); // Your Drizzle ORM
+ return Response.json(result, { status: 201 }); // Your response format
+}
+```
+
+## The Solution
+
+**OpenAgentsControl teaches agents your patterns upfront.** They understand your coding standards, your architecture, your security requirements. They propose plans before implementing. They execute incrementally with validation.
+
+**The result:** Production-ready code that ships without heavy rework.
+
+### What Makes OAC Different
+
+**π― Context-Aware (Your Secret Weapon)**
+Agents load YOUR patterns before generating code. Code matches your project from the start. No refactoring needed.
+
+**π Editable Agents (Not Baked-In Plugins)**
+Full control over agent behavior. Edit markdown files directlyβno compilation, no vendor lock-in. Change workflows, add constraints, customize for your team.
+
+**β Approval Gates (Human-Guided AI)**
+Agents ALWAYS request approval before execution. Propose β Approve β Execute. You stay in control. No "oh no, what did the AI just do?" moments.
+
+**β‘ Token Efficient (MVI Principle)**
+Minimal Viable Information design. Only load what's needed, when it's needed. Context files <200 lines, lazy loading, faster responses.
+
+**π₯ Team-Ready (Repeatable Patterns)**
+Store YOUR coding patterns once. Entire team uses same standards. Commit context to repo. New developers inherit team patterns automatically.
+
+**π Model Agnostic**
+Use any AI model (Claude, GPT, Gemini, local). No vendor lock-in.
+
+**Full-stack development:** OAC handles both frontend and backend work. The agents coordinate to build complete features from UI to database.
+
+---
+
+## π Quick Comparison
+
+| Feature | OpenAgentsControl | Cursor/Copilot | Aider | Oh My OpenCode |
+|---------|-------------------|----------------|-------|----------------|
+| **Learn Your Patterns** | β
Built-in context system | β No pattern learning | β No pattern learning | β οΈ Manual setup |
+| **Approval Gates** | β
Always required | β οΈ Optional (default off) | β Auto-executes | β Fully autonomous |
+| **Token Efficiency** | β
MVI principle (80% reduction) | β Full context loaded | β Full context loaded | β High token usage |
+| **Team Standards** | β
Shared context files | β Per-user settings | β No team support | β οΈ Manual config per user |
+| **Edit Agent Behavior** | β
Markdown files you edit | β Proprietary/baked-in | β οΈ Limited prompts | β
Config files |
+| **Model Choice** | β
Any model, any provider | β οΈ Limited options | β οΈ OpenAI/Claude only | β
Multiple models |
+| **Execution Speed** | β οΈ Sequential with approval | Fast | Fast | β
Parallel agents |
+| **Error Recovery** | β
Human-guided validation | β οΈ Auto-retry (can loop) | β οΈ Auto-retry | β
Self-correcting |
+| **Best For** | Production code, teams | Quick prototypes | Solo developers | Power users, complex projects |
+
+**Use OAC when:**
+- β
You have established coding patterns
+- β
You want code that ships without refactoring
+- β
You need approval gates for quality control
+- β
You care about token efficiency and costs
+
+**Use others when:**
+- **Cursor/Copilot:** Quick prototypes, don't care about patterns
+- **Aider:** Simple file edits, no team coordination
+- **Oh My OpenCode:** Need autonomous execution with parallel agents (speed over control)
+
+> **Full comparison:** [Read detailed analysis β](https://github.com/darrenhinde/OpenAgentsControl/discussions/116)
+
+---
+
+## π Quick Start
+
+**Prerequisites:** [OpenCode CLI](https://opencode.ai/docs) (free, open-source) β’ Bash 3.2+ β’ Git
+
+### Step 1: Install
+
+**One command:**
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s developer
+```
+
+The installer will set up OpenCode CLI if you don't have it yet.
+
+**Or interactive:**
+```bash
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh -o install.sh
+bash install.sh
+```
+
+### Keep Updated
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/update.sh | bash
+```
+
+> Use `--install-dir PATH` if you installed to a custom location (e.g. `~/.config/opencode`).
+
+### Step 2: Start Building
+
+```bash
+opencode --agent OpenAgent
+> "Create a user authentication system"
+```
+
+### Step 3: Approve & Ship
+
+**What happens:**
+1. Agent analyzes your request
+2. Proposes a plan (you approve)
+3. Executes step-by-step with validation
+4. Delegates to specialists when needed
+5. Ships production-ready code
+
+**That's it.** Works immediately with your default model. No configuration required.
+
+---
+
+### Alternative: Claude Code Plugin (BETA)
+
+**Prefer Claude Code?** OpenAgents Control is also available as a Claude Code plugin!
+
+**Installation:**
+
+1. Register the marketplace:
+```bash
+/plugin marketplace add darrenhinde/OpenAgentsControl
+```
+
+2. Install the plugin:
+```bash
+/plugin install oac
+```
+
+3. Download context files:
+```bash
+/oac:setup --core
+```
+
+4. Start building:
+```
+Add a login endpoint
+```
+
+**Features:**
+- β
6-stage workflow with approval gates
+- β
Context-aware code generation
+- β
7 specialized subagents (task-manager, context-scout, context-manager, coder-agent, test-engineer, code-reviewer, external-scout)
+- β
9 workflow skills + 6 user commands
+- β
Flexible context discovery (.oac config, .claude/context, context, .opencode/context)
+- β
Add context from GitHub, worktrees, local files, or URLs
+- β
Easy feature planning with `/oac:plan`
+
+**Documentation:**
+- [Plugin README](./plugins/claude-code/README.md) - Complete plugin documentation
+- [First-Time Setup](./plugins/claude-code/FIRST-TIME-SETUP.md) - Step-by-step guide
+- [Quick Start](./plugins/claude-code/QUICK-START.md) - Quick reference
+
+**Status:** BETA - Actively tested and ready for early adopters
+
+---
+
+## π‘ The Context System: Your Secret Weapon
+
+**The problem with AI code:** It doesn't match your patterns. You spend hours refactoring.
+
+**The OAC solution:** Teach your patterns once. Agents load them automatically. Code matches from the start.
+
+### How It Works
+
+```
+Your Request
+ β
+ContextScout discovers relevant patterns
+ β
+Agent loads YOUR standards
+ β
+Code generated using YOUR patterns
+ β
+Ships without refactoring β
+```
+
+### Add Your Patterns (10-15 Minutes)
+
+```bash
+/add-context
+```
+
+**Answer 6 simple questions:**
+1. What's your tech stack? (Next.js + TypeScript + PostgreSQL + Tailwind)
+2. Show an API endpoint example (paste your code)
+3. Show a component example (paste your code)
+4. What naming conventions? (kebab-case, PascalCase, camelCase)
+5. Any code standards? (TypeScript strict, Zod validation, etc.)
+6. Any security requirements? (validate input, parameterized queries, etc.)
+
+**Result:** Agents now generate code matching your exact patterns. No refactoring needed.
+
+### The MVI Advantage: Token Efficiency
+
+**MVI (Minimal Viable Information)** = Only load what's needed, when it's needed.
+
+**Traditional approach:**
+- Loads entire codebase context
+- Large token overhead per request
+- Slow responses, high costs
+
+**OAC approach:**
+- Loads only relevant patterns
+- Context files <200 lines (quick to load)
+- Lazy loading (agents load what they need)
+- 80% of tasks use isolation context (minimal overhead)
+
+**Real benefits:**
+- **Efficiency:** Lower token usage vs loading entire codebase
+- **Speed:** Faster responses with smaller context
+- **Quality:** Code matches your patterns (no refactoring)
+
+### For Teams: Repeatable Patterns
+
+**The team problem:** Every developer writes code differently. Inconsistent patterns. Hard to maintain.
+
+**The OAC solution:** Store team patterns in `.opencode/context/project/`. Commit to repo. Everyone uses same standards.
+
+**Example workflow:**
+```bash
+# Team lead adds patterns once
+/add-context
+# Answers questions with team standards
+
+# Commit to repo
+git add .opencode/context/
+git commit -m "Add team coding standards"
+git push
+
+# All team members now use same patterns automatically
+# New developers inherit standards on day 1
+```
+
+**Result:** Consistent code across entire team. No style debates. No refactoring PRs.
+
+---
+
+## π How It Works
+
+### The Core Idea
+
+**Most AI tools:** Generic code β You refactor
+**OpenAgentsControl:** Your patterns β AI generates matching code
+
+### The Workflow
+
+```
+1. Add Your Context (one time)
+ β
+2. ContextScout discovers relevant patterns
+ β
+3. Agent loads YOUR standards
+ β
+4. Agent proposes plan (using your patterns)
+ β
+5. You approve
+ β
+6. Agent implements (matches your project)
+ β
+7. Code ships (no refactoring needed)
+```
+
+### Key Benefits
+
+**π― Context-Aware**
+ContextScout discovers relevant patterns. Agents load YOUR standards before generating code. Code matches your project from the start.
+
+**π Repeatable**
+Same patterns β Same results. Configure once, use forever. Perfect for teams.
+
+**β‘ Token Efficient (80% Reduction)**
+MVI principle: Only load what's needed. 8,000 tokens β 750 tokens. Massive cost savings.
+
+**β Human-Guided**
+Agents propose plans, you approve before execution. Quality gates prevent mistakes. No auto-execution surprises.
+
+**π Transparent & Editable**
+Agents are markdown files you can edit. Change workflows, add constraints, customize behavior. No vendor lock-in.
+
+### What Makes This Special
+
+**1. ContextScout - Smart Pattern Discovery**
+Before generating code, ContextScout discovers relevant patterns from your context files. Ranks by priority (Critical β High β Medium). Prevents wasted work.
+
+**2. Editable Agents - Full Control**
+Unlike Cursor/Copilot where behavior is baked into plugins, OAC agents are markdown files. Edit them directly:
+```bash
+nano .opencode/agent/core/opencoder.md # local project install
+# Or: nano ~/.config/opencode/agent/core/opencoder.md # global install
+# Add project rules, change workflows, customize behavior
+```
+
+**3. ExternalScout - Live Documentation** π
+Working with external libraries? ExternalScout fetches current documentation:
+- Gets live docs from official sources (npm, GitHub, docs sites)
+- No outdated training data - always current
+- Automatically triggered when agents detect external dependencies
+- Supports frameworks, APIs, libraries, and more
+
+**4. Approval Gates - No Surprises**
+Agents ALWAYS request approval before:
+- Writing/editing files
+- Running bash commands
+- Delegating to subagents
+- Making any changes
+
+You stay in control. Review plans before execution.
+
+**5. MVI Principle - Token Efficiency**
+Files designed for quick loading:
+- Concepts: <100 lines
+- Guides: <150 lines
+- Examples: <80 lines
+
+Result: Lower token usage vs loading entire codebase.
+
+**6. Team Patterns - Repeatable Results**
+Store patterns in `.opencode/context/project/`. Commit to repo. Entire team uses same standards. New developers inherit patterns automatically.
+
+---
+
+## π― Which Agent Should I Use?
+
+### OpenAgent (Start Here)
+
+**Best for:** Learning the system, general tasks, quick implementations
+
+```bash
+opencode --agent OpenAgent
+> "Create a user authentication system" # Building features
+> "How do I implement authentication in Next.js?" # Questions
+> "Create a README for this project" # Documentation
+> "Explain the architecture of this codebase" # Analysis
+```
+
+**What it does:**
+- Loads your patterns via ContextScout
+- Proposes plan (you approve)
+- Executes with validation
+- Delegates to specialists when needed
+
+**Perfect for:** First-time users, simple features, learning the workflow
+
+### OpenCoder (Production Development)
+
+**Best for:** Complex features, multi-file refactoring, production systems
+
+```bash
+opencode --agent OpenCoder
+> "Create a user authentication system" # Full-stack features
+> "Refactor this codebase to use dependency injection" # Multi-file refactoring
+> "Add real-time notifications with WebSockets" # Complex implementations
+```
+
+**What it does:**
+- **Discover:** ContextScout finds relevant patterns
+- **Propose:** Detailed implementation plan
+- **Approve:** You review and approve
+- **Execute:** Incremental implementation with validation
+- **Validate:** Tests, type checking, code review
+- **Ship:** Production-ready code
+
+**Perfect for:** Production code, complex features, team development
+
+### SystemBuilder (Custom AI Systems)
+
+**Best for:** Building complete custom AI systems tailored to your domain
+
+```bash
+opencode --agent SystemBuilder
+> "Create a customer support AI system"
+```
+
+Interactive wizard generates orchestrators, subagents, context files, workflows, and commands.
+
+**Perfect for:** Creating domain-specific AI systems
+
+---
+
+## π οΈ What's Included
+
+### π€ Main Agents
+- **OpenAgent** - General tasks, questions, learning (start here)
+- **OpenCoder** - Production development, complex features
+- **SystemBuilder** - Generate custom AI systems
+
+### π§ Specialized Subagents (Auto-delegated)
+- **ContextScout** - Smart pattern discovery (your secret weapon)
+- **TaskManager** - Breaks complex features into atomic subtasks
+- **CoderAgent** - Focused code implementations
+- **TestEngineer** - Test authoring and TDD
+- **CodeReviewer** - Code review and security analysis
+- **BuildAgent** - Type checking and build validation
+- **DocWriter** - Documentation generation
+- **ExternalScout** - Fetches live docs for external libraries (no outdated training data) **NEW!**
+- Plus category specialists: frontend, devops, copywriter, technical-writer, data-analyst
+
+### β‘ Productivity Commands
+- `/add-context` - Interactive wizard to add your patterns
+- `/commit` - Smart git commits with conventional format
+- `/test` - Testing workflows
+- `/optimize` - Code optimization
+- `/context` - Context management
+- And 7+ more productivity commands
+
+### π Context System (MVI Principle)
+Your coding standards automatically loaded by agents:
+- **Code quality** - Your patterns, security, standards
+- **UI/design** - Design system, component patterns
+- **Task management** - Workflow definitions
+- **External libraries** - Integration guides (18+ libraries supported)
+- **Project-specific** - Your team's patterns
+
+**Key features:**
+- 80% token reduction via MVI
+- Smart discovery via ContextScout
+- Lazy loading (only what's needed)
+- Team-ready (commit to repo)
+- Version controlled (track changes)
+
+### How Context Resolution Works
+
+ContextScout discovers context files using a **local-first** approach:
+
+```
+1. Check local: .opencode/context/core/navigation.md
+ β Found? β Use local for everything. Done.
+ β Not found?
+2. Check global: ~/.config/opencode/context/core/navigation.md
+ β Found? β Use global for core/ files only.
+ β Not found? β Proceed without core context.
+```
+
+**Key rules:**
+- **Local always wins** β if you installed locally, global is never checked
+- **Global fallback is only for `core/`** (standards, workflows, guides) β universal files that are the same across projects
+- **Project intelligence is always local** β your tech stack, patterns, and naming conventions live in `.opencode/context/project-intelligence/` and are never loaded from global
+- **One-time check** β ContextScout resolves the core location once at startup (max 2 glob checks), not per-file
+
+**Common setups:**
+
+| Setup | Core files from | Project intelligence from |
+|-------|----------------|--------------------------|
+| Local install (`bash install.sh developer`) | `.opencode/context/core/` | `.opencode/context/project-intelligence/` |
+| Global install + `/add-context` | `~/.config/opencode/context/core/` | `.opencode/context/project-intelligence/` |
+| Both local and global | `.opencode/context/core/` (local wins) | `.opencode/context/project-intelligence/` |
+
+---
+
+
+
+## π» Example Workflow
+
+```bash
+opencode --agent OpenCoder
+> "Create a user dashboard with authentication and profile settings"
+```
+
+**What happens:**
+
+**1. Discover (~1-2 min)** - ContextScout finds relevant patterns
+- Your tech stack (Next.js + TypeScript + PostgreSQL)
+- Your API pattern (Zod validation, error handling)
+- Your component pattern (functional, TypeScript, Tailwind)
+- Your naming conventions (kebab-case files, PascalCase components)
+
+**2. Propose (~2-3 min)** - Agent creates detailed implementation plan
+```
+## Proposed Implementation
+
+**Components:**
+- user-dashboard.tsx (main page)
+- profile-settings.tsx (settings component)
+- auth-guard.tsx (authentication wrapper)
+
+**API Endpoints:**
+- /api/user/profile (GET, POST)
+- /api/auth/session (GET)
+
+**Database:**
+- users table (Drizzle schema)
+- sessions table (Drizzle schema)
+
+All code will follow YOUR patterns from context.
+
+Approve? [y/n]
+```
+
+**3. Approve** - You review and approve the plan (human-guided)
+
+**4. Execute (~10-15 min)** - Incremental implementation with validation
+- Implements one component at a time
+- Uses YOUR patterns for every file
+- Validates after each step (type check, lint)
+- *This is the longest step - generating quality code takes time*
+
+**5. Validate (~2-3 min)** - Tests, type checking, code review
+- Delegates to TestEngineer for tests
+- Delegates to CodeReviewer for security check
+- Ensures production quality
+
+**6. Ship** - Production-ready code
+- Code matches your project exactly
+- No refactoring needed
+- Ready to commit and deploy
+
+**Total time: ~15-25 minutes** for a complete feature (guided, with approval gates)
+
+### π‘ Pro Tips
+
+**After finishing a feature:**
+- Run `/add-context --update` to add new patterns you discovered
+- Update your context with new libraries, conventions, or standards
+- Keep your patterns fresh as your project evolves
+
+**Working with external libraries?**
+- **ExternalScout** automatically fetches current documentation
+- No more outdated training data - gets live docs from official sources
+- Works with npm packages, APIs, frameworks, and more
+
+---
+
+## βοΈ Advanced Configuration
+
+### Model Configuration (Optional)
+
+**By default, all agents use your OpenCode default model.** Configure models per agent only if you want different agents to use different models.
+
+**When to configure:**
+- You want faster agents to use cheaper models (e.g., Haiku/Flash)
+- You want complex agents to use smarter models (e.g., Opus/GPT-5)
+- You want to test different models for different tasks
+
+**How to configure:**
+
+Edit agent files directly:
+```bash
+nano .opencode/agent/core/opencoder.md # local project install
+# Or: nano ~/.config/opencode/agent/core/opencoder.md # global install
+```
+
+Change the model in the frontmatter:
+```yaml
+---
+description: "Development specialist"
+model: anthropic/claude-sonnet-4-5 # Change this line
+---
+```
+
+Browse available models at [models.dev](https://models.dev/?search=open) or run `opencode models`.
+
+### Update Context as You Go
+
+Your project evolves. Your context should too.
+
+```bash
+/add-context --update
+```
+
+**What gets updated:**
+- Tech stack, patterns, standards
+- Version incremented (1.0 β 1.1)
+- Updated date refreshed
+
+**Example updates:**
+- Add new library (Stripe, Twilio, etc.)
+- Change patterns (new API format, component structure)
+- Migrate tech stack (Prisma β Drizzle)
+- Update security requirements
+
+Agents automatically use updated patterns.
+
+---
+
+
+
+## π― Is This For You?
+
+### β
Use OAC if you:
+- Build production code that ships without heavy rework
+- Work in a team with established coding standards
+- Want control over agent behavior (not black-box plugins)
+- Care about token efficiency and cost savings
+- Need approval gates for quality assurance
+- Want repeatable, consistent results
+- Use multiple AI models (no vendor lock-in)
+
+### β οΈ Skip OAC if you:
+- Want fully autonomous execution without approval gates
+- Prefer "just do it" mode over human-guided workflows
+- Don't have established coding patterns yet
+- Need multi-agent parallelization (use Oh My OpenCode instead)
+- Want plug-and-play with zero configuration
+
+### π€ Not Sure?
+
+**Try this test:**
+1. Ask your current AI tool to generate an API endpoint
+2. Count how many minutes you spend refactoring it to match your patterns
+3. If you're spending time on refactoring, OAC will save you that time
+
+**Or ask yourself:**
+- Do you have coding standards your team follows?
+- Do you spend time refactoring AI-generated code?
+- Do you want AI to follow YOUR patterns, not generic ones?
+
+If you answered "yes" to any of these, OAC is for you.
+
+---
+
+## π Advanced Features
+
+### Frontend Design Workflow
+The **OpenFrontendSpecialist** follows a structured 4-stage design workflow:
+1. **Layout** - ASCII wireframe, responsive structure planning
+2. **Theme** - Design system selection, OKLCH colors, typography
+3. **Animation** - Micro-interactions, timing, accessibility
+4. **Implementation** - Single HTML file, semantic markup
+
+### Task Management & Breakdown
+The **TaskManager** breaks complex features into atomic, verifiable subtasks with smart agent suggestions and parallel execution support.
+
+### System Builder
+Build complete custom AI systems tailored to your domain in minutes. Interactive wizard generates orchestrators, subagents, context files, workflows, and commands.
+
+---
+
+## β FAQ
+
+### Getting Started
+
+**Q: Does this work on Windows?**
+A: Yes! Use Git Bash (recommended) or WSL.
+
+**Q: What languages are supported?**
+A: Agents are language-agnostic and adapt based on your project files. Primarily tested with TypeScript/Node.js. C# / .NET is now supported with dedicated context files. Python, Go, Rust, and other languages are supported but less battle-tested. The context system works with any language.
+
+**Q: Do I need to add context?**
+A: No, but it's highly recommended. Without context, agents write generic code. With context, they write YOUR code.
+
+**Q: Can I use this without customization?**
+A: Yes, it works out of the box. But you'll get the most value after adding your patterns (10-15 minutes with `/add-context`).
+
+**Q: What models are supported?**
+A: Any model from any provider (Claude, GPT, Gemini, MiniMax, local models). No vendor lock-in.
+
+### For Teams
+
+**Q: How do I share context with my team?**
+A: Commit `.opencode/context/project/` to your repo. Team members automatically use same patterns.
+
+**Q: How do we ensure everyone follows the same standards?**
+A: Add team patterns to context once. All agents load them automatically. Consistent code across entire team.
+
+**Q: Can different projects have different patterns?**
+A: Yes! Use project-specific context (`.opencode/` in project root) to override global patterns.
+
+### Technical
+
+**Q: How does token efficiency work?**
+A: MVI principle: Only load what's needed, when it's needed. Context files <200 lines (scannable in 30s). ContextScout discovers relevant patterns. Lazy loading prevents context bloat. 80% of tasks use isolation context (minimal overhead).
+
+**Q: What's ContextScout?**
+A: Smart pattern discovery agent. Finds relevant context files before code generation. Ranks by priority. Prevents wasted work.
+
+**Q: Can I edit agent behavior?**
+A: Yes! Agents are markdown files. Edit them directly: `nano .opencode/agent/core/opencoder.md` (local) or `nano ~/.config/opencode/agent/core/opencoder.md` (global)
+
+**Q: How do approval gates work?**
+A: Agents ALWAYS request approval before execution (write/edit/bash). You review plans before implementation. No surprises.
+
+**Q: How do I update my context?**
+A: Run `/add-context --update` anytime your patterns change. Agents automatically use updated patterns.
+
+### Comparison
+
+**Q: How is this different from Cursor/Copilot?**
+A: OAC has editable agents (not baked-in), approval gates (not auto-execute), context system (YOUR patterns), and MVI token efficiency.
+
+**Q: How is this different from Aider?**
+A: OAC has team patterns, context system, approval workflow, and smart pattern discovery. Aider is file-based only.
+
+**Q: How does this compare to Oh My OpenCode?**
+A: Both are built on OpenCode. OAC focuses on **control & repeatability** (approval gates, pattern control, team standards). Oh My OpenCode focuses on **autonomy & speed** (parallel agents, auto-execution). [Read detailed comparison β](https://github.com/darrenhinde/OpenAgentsControl/discussions/116)
+
+**Q: When should I NOT use OAC?**
+A: If you want fully autonomous execution without approval gates, or if you don't have established coding patterns yet.
+
+### Setup
+
+**Q: What bash version do I need?**
+A: Bash 3.2+ (macOS default works). Run `bash scripts/tests/test-compatibility.sh` to check.
+
+**Q: Do I need to install plugins/tools?**
+A: No, they're optional. Only install if you want Telegram notifications or Gemini AI features.
+
+**Q: Where should I install - globally or per-project?**
+A: Local (`.opencode/` in your project) is recommended β patterns are committed to git and shared with your team. Global (`~/.config/opencode/`) is good for personal defaults across all projects. The installer asks you to choose. See [OpenCode Config Docs](https://opencode.ai/docs/config/) for how configs merge.
+
+---
+
+## πΊοΈ Roadmap & What's Coming
+
+**This is only the beginning!** We're actively developing new features and improvements every day.
+
+### π See What's Coming Next
+
+Check out our [**Project Board**](https://github.com/darrenhinde/OpenAgentsControl/projects) to see:
+- π¨ **In Progress** - Features being built right now
+- π **Planned** - What's coming soon
+- π‘ **Ideas** - Future enhancements under consideration
+- β
**Recently Shipped** - Latest improvements
+
+### π― Current Focus Areas
+
+- **Plugin System** - npm-based plugin architecture for easy distribution
+- **Performance Improvements** - Faster agent execution and context loading
+- **Enhanced Context Discovery** - Smarter pattern recognition
+- **Multi-language Support** - Better Python, Go, Rust, C# / .NET support
+- **Team Collaboration** - Shared context and team workflows
+- **Documentation** - More examples, tutorials, and guides
+
+### π¬ Have Ideas?
+
+We'd love to hear from you!
+- π‘ [**Submit Feature Requests**](https://github.com/darrenhinde/OpenAgentsControl/issues/new?labels=enhancement)
+- π [**Report Bugs**](https://github.com/darrenhinde/OpenAgentsControl/issues/new?labels=bug)
+- π¬ [**Join Discussions**](https://github.com/darrenhinde/OpenAgentsControl/discussions)
+
+**Star the repo** β to stay updated with new releases!
+
+---
+
+## π€ Contributing
+
+We welcome contributions!
+
+1. Follow the established naming conventions and coding standards
+2. Write comprehensive tests for new features
+3. Update documentation for any changes
+4. Ensure security best practices are followed
+
+See: [Contributing Guide](docs/contributing/CONTRIBUTING.md) β’ [Code of Conduct](docs/contributing/CODE_OF_CONDUCT.md)
+
+---
+
+## π¬ Community & Support
+
+
+
+**Join the community and stay updated with the latest AI development workflows!**
+
+[](https://youtube.com/@DarrenBuildsAI)
+[](https://nextsystems.ai)
+[](https://x.com/DarrenBuildsAI)
+[](https://buymeacoffee.com/darrenhinde)
+
+**πΊ Tutorials & Demos** β’ **π¬ Join Waitlist** β’ **π¦ Latest Updates** β’ **β Support Development**
+
+*Your support helps keep this project free and open-source!*
+
+
+
+---
+
+## License
+
+This project is licensed under the MIT License.
+
+---
+
+**Made with β€οΈ by developers, for developers. Star the repo if this saves you refactoring time!**
diff --git a/.opencode/agent/content/copywriter.md b/.opencode/agent/content/copywriter.md
index 8f36fc2d..6c50760d 100644
--- a/.opencode/agent/content/copywriter.md
+++ b/.opencode/agent/content/copywriter.md
@@ -6,7 +6,9 @@
name: OpenCopywriter
description: "Expert in persuasive writing, marketing copy, and brand messaging"
mode: primary
-temperature: 0.3
+temperature: 0.2
+model: anthropic/claude-sonnet-4-20250514
+top_p: 0.9
---
# Copywriter
diff --git a/.opencode/agent/content/technical-writer.md b/.opencode/agent/content/technical-writer.md
index 5c61bf3b..231abbe5 100644
--- a/.opencode/agent/content/technical-writer.md
+++ b/.opencode/agent/content/technical-writer.md
@@ -7,6 +7,8 @@ name: OpenTechnicalWriter
description: "Expert in documentation, API docs, and technical communication"
mode: primary
temperature: 0.2
+model: anthropic/claude-sonnet-4-20250514
+top_p: 0.9
---
# Technical Writer
diff --git a/.opencode/agent/core/openagent.md b/.opencode/agent/core/openagent.md
index 7055915c..8736c8a4 100644
--- a/.opencode/agent/core/openagent.md
+++ b/.opencode/agent/core/openagent.md
@@ -3,6 +3,8 @@ name: OpenAgent
description: "Universal agent for answering queries, executing tasks, and coordinating workflows across any domain"
mode: primary
temperature: 0.2
+model: anthropic/claude-sonnet-4-20250514
+top_p: 0.9
permission:
bash:
"*": "ask"
@@ -58,6 +60,9 @@ CONSEQUENCE OF SKIPPING: Work that doesn't match project standards = wasted effo
Request approval before ANY execution (bash, write, edit, task). Read/list ops don't require approval.
+
+ β MANDATORY: You MUST read (using the Read tool) ANY file you will write or edit BEFORE writing or editing it. If the file does not yet exist, read the parent directory. This is separate from loading context standards β it means reading the ACTUAL TARGET FILE. Skipping this causes "must read before write" errors.
+
STOP on test fail/errors - NEVER auto-fix
@@ -117,14 +122,15 @@ task(
```
-
- - @critical_context_requirement
+
+ - @critical_context_requirement (load standards)
+ - Stage 2.5 ReadTargetFiles (read source files before edit)
- @critical_rules (all 4 rules)
- Permission checks
- User confirmation reqs
- - Stage progression: AnalyzeβApproveβExecuteβValidateβSummarize
+ - Stage progression: AnalyzeβApproveβReadTargetFilesβLoadContextβExecuteβValidateβSummarize
- Delegation routing
@@ -239,6 +245,41 @@ task(
User approval received (Stage 2 complete)
+
+ β STOP. Before ANY write/edit, you MUST read the target file(s).
+
+ **CRITICAL**: This is DIFFERENT from loading context standards!
+ - Stage 3.0 loads standards and workflows (code-quality.md, etc.)
+ - This step reads the ACTUAL SOURCE FILE you will modify
+
+
+ 1. Identify target file(s) from user request
+ 2. Use Read tool to read each file:
+ ```javascript
+ Read tool: path/to/file/you/will/edit.ts
+ // For new files, read parent directory structure
+ Read tool: path/to/parent/
+ ```
+ 3. Understand current structure, patterns, code style
+ 4. THEN proceed to Stage 3.0 (load context standards)
+
+
+
+ Edit tool requires file content loaded in context first.
+ Without reading, you get "must read before write" errors.
+ This wastes time and breaks workflow.
+
+
+
+ β
"Add logging to authStore" β Read apps/BowChat/src/stores/authStore.ts FIRST
+ β
"Create new component" β Read parent directory structure FIRST
+ β
"Fix bug in utils" β Read src/utils/file.ts FIRST
+ β Attempting edit without Read β ERROR: "must read before write"
+
+
+ All target files read, structure understood
+
+
β STOP. Before executing, check task type:
@@ -667,11 +708,19 @@ task(
These constraints override all other considerations:
1. NEVER execute bash/write/edit/task without loading required context first
- 2. NEVER skip step 3.1 (LoadContext) for efficiency or speed
- 3. NEVER assume a task is "too simple" to need context
- 4. ALWAYS use Read tool to load context files before execution
- 5. ALWAYS tell subagents which context file to load when delegating
+ 2. NEVER write or edit ANY file without reading it first β use Read tool before write/edit
+ 3. NEVER skip step 2.5 (ReadTargetFiles) - MUST read target files before ANY write/edit
+ 4. NEVER skip step 3.0 (LoadContext) for efficiency or speed
+ 4. NEVER assume a task is "too simple" to need context
+ 5. ALWAYS use Read tool to load context files before execution
+ 6. ALWAYS tell subagents which context file to load when delegating
+
+ CRITICAL DISTINCTION:
+ - Step 2.5 (ReadTargetFiles): Reads the ACTUAL SOURCE FILES you will edit
+ - Step 3.0 (LoadContext): Reads the STANDARDS/WORKFLOWS (code-quality.md, etc.)
+ - BOTH are mandatory. Skipping either causes failures.
- If you find yourself executing without loading context, you are violating critical rules.
+ If you find yourself violating these rules, you are violating critical rules.
Context loading is MANDATORY, not optional.
+ File reading is MANDATORY, not optional.
diff --git a/.opencode/agent/core/opencoder.md b/.opencode/agent/core/opencoder.md
index 7e2be799..18075fa7 100644
--- a/.opencode/agent/core/opencoder.md
+++ b/.opencode/agent/core/opencoder.md
@@ -2,7 +2,9 @@
name: OpenCoder
description: "Orchestration agent for complex coding, architecture, and multi-file refactoring"
mode: primary
-temperature: 0.1
+temperature: 0.2
+model: anthropic/claude-sonnet-4-20250514
+top_p: 0.9
permission:
bash:
"rm -rf *": "ask"
@@ -49,6 +51,9 @@ CONSEQUENCE OF SKIPPING: Work that doesn't match project standards = wasted effo
+
+ β MANDATORY: You MUST read (using the Read tool) ANY file you will write or edit BEFORE writing or editing it. If the file does not yet exist, read the parent directory. This is separate from loading context standards β it means reading the ACTUAL TARGET FILE. Skipping this causes "must read before write" errors.
+
Request approval before ANY implementation (write, edit, bash). Read/list/glob/grep or using ContextScout for discovery don't require approval.
ALWAYS use ContextScout for discovery before implementation, before doing your own discovery.
@@ -170,6 +175,31 @@ Code Standards
If user approves β continue to Stage 3.
+
+
+
+
+ Goal: Read all files that will be modified or created BEFORE any execution.
+
+
+ 1. **Identify target files** from user request and Stage 1 discovery
+ 2. **Read existing files** to understand structure:
+ - Use Read tool for each file to be edited
+ - For new files, read parent directory structure
+ 3. **Understand patterns**: Current naming, structure, style
+ 4. **Verify location**: Ensure correct paths before proceeding
+
+
+
+ - Edit tool requires file content loaded in context
+ - Without reading: "must read before write" errors
+ - Reading first = smooth execution, no interruptions
+ - Understand existing patterns = consistent changes
+
+
+ All target files read, structure understood, ready for implementation
+
+
@@ -463,20 +493,28 @@ Code Standards
- 1. Run full system integration tests.
- 2. Suggest `TestEngineer` or `CodeReviewer` if not already run.
+ 1. **TDD Verification (MANDATORY)**: Verify CoderAgent followed TDD workflow:
+ - [ ] All deliverables have corresponding test files
+ - [ ] Tests follow REDβGREEN pattern (failing before impl, passing after)
+ - [ ] Both positive and negative test cases exist
+ - [ ] Arrange-Act-Assert pattern used in all tests
+ - [ ] All external dependencies mocked in tests
+ - If ANY TDD checks fail β REJECT implementation, return to CoderAgent for correction
+ 2. Run full system integration tests.
+ 3. Suggest `TestEngineer` or `CodeReviewer` if not already run.
- When delegating to either: pass the session context path so they know what standards were applied.
- 3. Summarize what was built.
- 4. Ask user to clean up `.tmp` session and task files.
+ 4. Summarize what was built.
+ 5. Ask user to clean up `.tmp` session and task files.
Development specialist with strict quality gates, context awareness, and parallel execution optimization.
- **Approach**: Discover β Propose β Approve β Init Session β Plan β Execute (Parallel Batches) β Validate β Handoff
+ **Approach**: Discover β Propose β Approve β Init Session β Plan β Execute (Parallel Batches) β Validate (TDD Check) β Handoff
**Mindset**: Nothing written until approved. Context persisted once, shared by all downstream agents. Parallel tasks execute simultaneously for efficiency.
**Safety**: Context loading, approval gates, stop on failure, incremental execution within batches
+ **TDD Enforcement**: OpenCoder validates REDβGREEN pattern before handoff. CoderAgent writes tests first, implements second. No exceptions.
**Parallel Execution**: Tasks marked `parallel: true` with no dependencies run simultaneously. Sequential batches wait for previous batches to complete.
**BatchExecutor Usage**:
- 1-4 parallel tasks: OpenCoder delegates directly to CoderAgents (simpler, faster setup)
@@ -490,10 +528,17 @@ Code Standards
These constraints override all other considerations:
1. NEVER execute write/edit without loading required context first
- 2. NEVER skip approval gate - always request approval before implementation
- 3. NEVER auto-fix errors - always report first and request approval
- 4. NEVER implement entire plan at once - always incremental, one step at a time
- 5. ALWAYS validate after each step (type check, lint, test)
+ 2. NEVER write or edit ANY file without reading it first β use Read tool before write/edit
+ 3. NEVER skip Stage 2.5 (ReadTargetFiles) - MUST read target files before ANY write/edit
+ 3. NEVER skip approval gate - always request approval before implementation
+ 4. NEVER auto-fix errors - always report first and request approval
+ 5. NEVER implement entire plan at once - always incremental, one step at a time
+ 6. ALWAYS validate after each step (type check, lint, test)
+
+ CRITICAL DISTINCTION:
+ - Stage 2.5 (ReadTargetFiles): Reads the ACTUAL SOURCE FILES you will edit
+ - Stage 3+ context loading: Reads the STANDARDS/WORKFLOWS (code-quality.md, etc.)
+ - BOTH are mandatory. Skipping either causes "must read before write" errors.
If you find yourself violating these rules, STOP and correct course.
diff --git a/.opencode/agent/data/data-analyst.md b/.opencode/agent/data/data-analyst.md
index 827b6e22..9ad03f08 100644
--- a/.opencode/agent/data/data-analyst.md
+++ b/.opencode/agent/data/data-analyst.md
@@ -3,6 +3,8 @@ name: OpenDataAnalyst
description: "Expert in data analysis, visualization, and statistical insights"
mode: primary
temperature: 0.1
+model: lmstudio/qwen3-coder-30b
+top_p: 0.8
---
# Data Analyst
diff --git a/.opencode/agent/eval-runner.md b/.opencode/agent/eval-runner.md
index ec926258..620ad2b4 100644
--- a/.opencode/agent/eval-runner.md
+++ b/.opencode/agent/eval-runner.md
@@ -8,7 +8,9 @@ type: utility
version: 1.0.0
author: opencode
mode: subagent
-temperature: 0.2
+temperature: 0.4
+model: lmstudio/gpt-oss-20b
+top_p: 0.9
---
# Eval Runner - Test Harness
diff --git a/.opencode/agent/meta/repo-manager.md b/.opencode/agent/meta/repo-manager.md
index 122b622e..eadfbbdd 100644
--- a/.opencode/agent/meta/repo-manager.md
+++ b/.opencode/agent/meta/repo-manager.md
@@ -3,6 +3,8 @@ name: OpenRepoManager
description: "Meta agent for managing OpenAgents Control repository development with lazy context loading, smart delegation, and automatic documentation"
mode: primary
temperature: 0.2
+model: anthropic/claude-sonnet-4-20250514
+top_p: 0.9
permission:
bash:
"rm -rf *": "ask"
diff --git a/.opencode/agent/meta/system-builder.md b/.opencode/agent/meta/system-builder.md
index 6d18f063..2c64e3c1 100644
--- a/.opencode/agent/meta/system-builder.md
+++ b/.opencode/agent/meta/system-builder.md
@@ -7,6 +7,8 @@ name: OpenSystemBuilder
description: "Main orchestrator for building complete context-aware AI systems from user requirements"
mode: primary
temperature: 0.2
+model: anthropic/claude-sonnet-4-20250514
+top_p: 0.9
---
# System Builder Orchestrator
diff --git a/.opencode/agent/subagents/code/build-agent.md b/.opencode/agent/subagents/code/build-agent.md
index 8850da21..0bac0622 100644
--- a/.opencode/agent/subagents/code/build-agent.md
+++ b/.opencode/agent/subagents/code/build-agent.md
@@ -3,6 +3,8 @@ name: BuildAgent
description: Type check and build validation agent
mode: subagent
temperature: 0.1
+model: lmstudio/qwen3-coder-30b
+top_p: 0.8
permission:
bash:
"tsc": "allow"
diff --git a/.opencode/agent/subagents/code/coder-agent.md b/.opencode/agent/subagents/code/coder-agent.md
index 61aaf5f0..cb99932e 100644
--- a/.opencode/agent/subagents/code/coder-agent.md
+++ b/.opencode/agent/subagents/code/coder-agent.md
@@ -2,7 +2,9 @@
name: CoderAgent
description: Executes coding subtasks in sequence, ensuring completion as specified
mode: subagent
-temperature: 0
+temperature: 0.1
+model: lmstudio/qwen3-coder-30b
+top_p: 0.8
permission:
bash:
"*": "deny"
@@ -24,6 +26,9 @@ permission:
> **Mission**: Execute coding subtasks precisely, one at a time, with full context awareness and self-review before handoff.
+
+ β MANDATORY: You MUST read (using the Read tool) ANY file you will write or edit BEFORE writing or editing it. If the file does not yet exist, read the parent directory. Skipping this will cause "must read before write" errors and break your workflow.
+
ALWAYS call ContextScout BEFORE writing any code. Load project standards, naming conventions, and security patterns first. This is not optional β it's how you produce code that fits the project.
@@ -41,10 +46,13 @@ permission:
Implement atomic subtasks from JSON definitions, following project standards discovered via ContextScout
Limited bash access for task status updates only. Sequential execution. Self-review mandatory before handoff.
+ - @read_before_write: MUST read any file before writing/editing it
- @context_first: ContextScout ALWAYS before coding
- @external_scout_mandatory: ExternalScout for any external package
- @self_review_required: Self-Review Loop before signaling done
- @task_order: Sequential, no skipping
+ - @test_first: Write failing test BEFORE implementation (mandatory TDD)
+ - @test_never_skip: Never mark complete if tests missing or failing
- Read subtask JSON and understand requirements
@@ -125,6 +133,41 @@ task(subagent_type="ContextScout", description="Find context for [subtask title]
Load every file ContextScout recommends. Apply those standards.
+### Step 3.5: Verify Test Exists (TDD Mandate)
+
+**CRITICAL β TDD enforcement. Do NOT skip this step.**
+
+For each deliverable in `deliverables`:
+1. **Check if test file exists**
+ - Use `glob` to find matching test file (e.g., `src/utils/foo.test.ts` for `src/utils/foo.ts`)
+ - For components: check `src/**/*.test.tsx`
+ - For stores: check `src/stores/*.test.ts`
+
+2. **If test MISSING:**
+ - Write a MINIMAL failing test FIRST before any implementation
+ - Test should assert the expected behavior (will fail until implementation exists)
+ - This is the RED phase of TDD
+
+3. **If test EXISTS but PASSES:**
+ - Review the test assertions
+ - Fix the test to expect the CORRECT behavior (should fail)
+ - This ensures test is validating actual requirements
+
+4. **Run the test β confirm it FAILS**
+ ```bash
+ npx vitest run {test-file-path}
+ ```
+ - Test must be in RED state before proceeding
+ - If test passes incorrectly β fix test
+ - If test fails as expected β proceed to Step 4
+
+5. **Document exceptions:**
+ - If deliverable has NO testable behavior (config, types, static asset):
+ - Note this explicitly in completion summary
+ - All code deliverables require tests. Document why exception.
+
+**DO NOT proceed to Step 4 (Implement) until all tests are in RED state.**
+
### Step 4: Check for External Packages
Scan your subtask requirements. If ANY external library is involved:
@@ -146,14 +189,24 @@ Find `"status": "pending"` and replace with:
**NEVER use `write` here** β it would overwrite the entire subtask definition.
-### Step 6: Implement Deliverables
+### Step 6: Implement Deliverables (TDD: Green Phase)
+
+**Follow Red-Green-Refactor:**
For each item in `deliverables`:
+- **β READ FIRST**: Use Read tool to read the target file before writing/editing. If new file, read parent directory.
- Create or modify the specified file
- Follow acceptance criteria exactly
- Apply all standards from ContextScout
- Use API patterns from ExternalScout (if applicable)
-- Write tests if specified in acceptance criteria
+- **TDD Green Phase**: Write ONLY enough implementation to make failing test pass
+ - No over-engineering
+ - No future-proofing
+ - Minimal code that satisfies the test
+
+After implementation:
+- Run test again: should now PASS (GREEN phase complete)
+- If test still fails β continue implementing until pass
### Step 7: Self-Review Loop (MANDATORY)
@@ -182,10 +235,18 @@ Use `grep` on your deliverables to catch:
- If you used any external library: confirm your usage matches the documented API
- Never rely on training-data assumptions for external packages
+#### Check 5: TDD Verification (MANDATORY)
+- [ ] All tests written BEFORE implementation (RED phase completed)
+- [ ] All tests now PASSING (GREEN phase completed)
+- [ ] Tests follow Arrange-Act-Assert pattern
+- [ ] Both positive AND negative test cases exist
+- [ ] All external dependencies are mocked
+- [ ] No test skippage or exception undocumented
+
#### Self-Review Report
Include this in your completion summary:
```
-Self-Review: β
Types clean | β
Imports verified | β
No debug artifacts | β
All acceptance criteria met | β
External libs verified
+Self-Review: β
Types clean | β
Imports verified | β
No debug artifacts | β
All acceptance criteria met | β
Tests REDβGREEN | β
External libs verified
```
If ANY check fails β fix the issue. Do not signal completion until all checks pass.
diff --git a/.opencode/agent/subagents/code/reviewer.md b/.opencode/agent/subagents/code/reviewer.md
index 71da8c0f..ffc5eb96 100644
--- a/.opencode/agent/subagents/code/reviewer.md
+++ b/.opencode/agent/subagents/code/reviewer.md
@@ -3,6 +3,8 @@ name: CodeReviewer
description: Code review, security, and quality assurance agent
mode: subagent
temperature: 0.1
+model: lmstudio/qwen3-coder-30b
+top_p: 0.8
permission:
bash:
"*": "deny"
@@ -36,11 +38,13 @@ permission:
Read-only. No code modifications. Suggested diffs only.
- @context_first: ContextScout ALWAYS before reviewing
+ - @read_code_files: ALWAYS read all code files to review (Stage 2.5)
- @read_only: Never modify code β suggest only
- @security_priority: Security findings first, always
- @output_format: Structured output with severity ratings
+ - Stage 2.5: Read all code files to be reviewed
- Load project standards and review guidelines
- Analyze code for security vulnerabilities
- Check correctness and logic
@@ -55,6 +59,41 @@ permission:
Tier 1 always overrides Tier 2/3. Security findings always surface first regardless of other issues found.
---
+## π Stage 2.5: Read Code Files (BEFORE Reviewing)
+
+**CRITICAL: Read ALL code files you will review BEFORE analyzing.**
+
+This is DIFFERENT from loading context standards!
+- **ContextScout** loads review standards and quality patterns
+- **Stage 2.5** reads the ACTUAL SOURCE CODE you will review
+
+### Process
+1. **Identify files to review** from task requirements
+2. **Read each file completely**:
+ ```javascript
+ Read tool: src/path/to/file.ts
+ Read tool: src/path/to/module.ts
+ ```
+3. **Understand the code**:
+ - What does this code do?
+ - What are the inputs/outputs?
+ - What dependencies exist?
+ - Are there obvious issues?
+4. **THEN call ContextScout** for review criteria
+
+### Why This Matters
+- Cannot review what you haven't read
+- Understanding context reveals subtle issues
+- Prevents superficial feedback
+- Ensures review depth and relevance
+
+### Examples
+β
Reviewing PR β Read ALL changed files FIRST
+β
Security audit β Read ALL security-sensitive code FIRST
+β Reviewing without reading β Generic, useless feedback
+
+---
+
## π ContextScout β Your First Move
**ALWAYS call ContextScout before reviewing any code.** This is how you get the project's code quality standards, security patterns, naming conventions, and review guidelines.
@@ -89,6 +128,7 @@ task(subagent_type="ContextScout", description="Find code review standards", pro
## What NOT to Do
+- β **Don't skip Stage 2.5** β NEVER review code without reading files first
- β **Don't skip ContextScout** β reviewing without project standards = generic feedback that misses project-specific issues
- β **Don't apply changes** β suggest diffs only, never modify files
- β **Don't bury security issues** β they always surface first regardless of severity mix
diff --git a/.opencode/agent/subagents/code/test-engineer.md b/.opencode/agent/subagents/code/test-engineer.md
index d29b35c9..844b9d6f 100644
--- a/.opencode/agent/subagents/code/test-engineer.md
+++ b/.opencode/agent/subagents/code/test-engineer.md
@@ -3,6 +3,8 @@ name: TestEngineer
description: Test authoring and TDD agent
mode: subagent
temperature: 0.1
+model: lmstudio/qwen3-coder-30b
+top_p: 0.8
permission:
bash:
"npx vitest *": "allow"
@@ -31,6 +33,9 @@ permission:
> **Mission**: Author comprehensive tests following TDD principles β always grounded in project testing standards discovered via ContextScout.
+
+ β MANDATORY: You MUST read (using the Read tool) ANY file you will write or edit BEFORE writing or editing it. If the file does not yet exist, read the parent directory. Skipping this will cause "must read before write" errors and break your workflow.
+
ALWAYS call ContextScout BEFORE writing any tests. Load testing standards, coverage requirements, and TDD patterns first. Tests without standards = tests that don't match project conventions.
@@ -48,12 +53,15 @@ permission:
Write comprehensive tests that verify behavior against acceptance criteria, following project testing conventions
Deterministic tests only. No real network calls. Positive + negative required. Run tests before handoff.
+ - @read_before_write: MUST read any file before writing/editing it
- @context_first: ContextScout ALWAYS before writing tests
+ - @read_source_files: ALWAYS read source files before writing tests (Stage 2.5)
- @positive_and_negative: Both test types required for every behavior
- @arrange_act_assert: AAA pattern in every test
- @mock_externals: All external deps mocked β deterministic only
+ - Stage 2.5: Read target source files to understand behavior
- Propose test plan with behaviors to test
- Request approval before implementation
- Implement tests following AAA pattern
@@ -68,6 +76,42 @@ permission:
Tier 1 always overrides Tier 2/3. If test speed conflicts with positive+negative requirement β write both. If a test would use real network β mock it.
---
+## π Stage 2.5: Read Target Files (BEFORE Writing Tests)
+
+**CRITICAL: Read the source files you will test BEFORE writing any tests.**
+
+This is DIFFERENT from loading context standards!
+- **ContextScout** loads testing standards and conventions
+- **Stage 2.5** reads the ACTUAL SOURCE CODE you will test
+
+### Process
+1. **Identify files to test** from task requirements
+2. **Read each source file**:
+ ```javascript
+ Read tool: src/path/to/file.ts
+ // For new files, read parent directory
+ Read tool: src/path/to/parent/
+ ```
+3. **Understand the behavior**:
+ - What functions/classes exist?
+ - What are the inputs/outputs?
+ - What edge cases are apparent?
+ - What dependencies need mocking?
+4. **THEN call ContextScout** for testing standards
+
+### Why This Matters
+- Cannot test what you don't understand
+- Reading source reveals edge cases and dependencies
+- Prevents writing irrelevant tests
+- Ensures tests match actual implementation
+
+### Examples
+β
Testing authStore β Read `src/stores/authStore.ts` FIRST
+β
Testing utils β Read `src/utils/helper.ts` FIRST
+β Writing tests without reading source β Irrelevant tests
+
+---
+
## π ContextScout β Your First Move
**ALWAYS call ContextScout before writing any tests.** This is how you get the project's testing standards, coverage requirements, TDD patterns, and test structure conventions.
@@ -106,6 +150,8 @@ task(subagent_type="ContextScout", description="Find testing standards", prompt=
## What NOT to Do
+- β **Don't skip Stage 2.5** β NEVER write tests without reading source files first
+- β **Don't skip read-before-write** β ALWAYS read any file before writing or editing it
- β **Don't skip ContextScout** β testing without project conventions = tests that don't fit
- β **Don't skip negative tests** β every behavior needs both positive and negative coverage
- β **Don't use real network calls** β mock everything external, tests must be deterministic
diff --git a/.opencode/agent/subagents/core/batch-executor.md b/.opencode/agent/subagents/core/batch-executor.md
index fda5744b..e10d93dd 100644
--- a/.opencode/agent/subagents/core/batch-executor.md
+++ b/.opencode/agent/subagents/core/batch-executor.md
@@ -26,6 +26,12 @@ permission:
> **Mission**: Execute task batches in parallel, managing multiple simultaneous CoderAgent delegations and ensuring complete batch completion before returning.
+
+
+ β MANDATORY: You MUST read (using the Read tool) ANY file you will write or edit BEFORE writing or editing it. If the file does not yet exist, read the parent directory. Skipping this will cause "must read before write" errors and break your workflow.
+
+
+
Parallel execution coordinator within the OpenAgents task management pipeline
Batch task execution β parallel delegation, completion tracking, dependency management
Execute groups of tasks simultaneously, wait for all to complete, report batch status
diff --git a/.opencode/agent/subagents/core/context-manager.md b/.opencode/agent/subagents/core/context-manager.md
index 41c738d9..f48dcdc7 100644
--- a/.opencode/agent/subagents/core/context-manager.md
+++ b/.opencode/agent/subagents/core/context-manager.md
@@ -2,7 +2,9 @@
name: ContextManager
description: Context organization and lifecycle management specialist - discovers, catalogs, validates, and maintains project context structure with dependency tracking
mode: subagent
-temperature: 0.1
+temperature: 0.4
+model: lmstudio/gpt-oss-20b
+top_p: 0.9
permission:
read:
"*": "allow"
@@ -37,6 +39,9 @@ permission:
> **Mission**: Discover, catalog, validate, and maintain project context structure with dependency tracking and lifecycle management.
+
+ β MANDATORY: You MUST read (using the Read tool) ANY file you will write or edit BEFORE writing or editing it. If the file does not yet exist, read the parent directory. Skipping this will cause "must read before write" errors and break your workflow.
+
The ONLY entry point is `.opencode/context/`. All operations start from navigation.md files. Never hardcode paths β follow navigation dynamically.
@@ -62,6 +67,7 @@ permission:
- Deprecations or archival
+ - @read_before_write: MUST read any file before writing/editing it
- @context_root: Navigation-driven discovery only
- @navigation_driven: Read navigation.md before any changes
- @verify_before_modify: Confirm structure before modifying
diff --git a/.opencode/agent/subagents/core/context-retriever.md b/.opencode/agent/subagents/core/context-retriever.md
index 49d00162..ea36f821 100644
--- a/.opencode/agent/subagents/core/context-retriever.md
+++ b/.opencode/agent/subagents/core/context-retriever.md
@@ -2,7 +2,9 @@
name: Context Retriever
description: Generic context search and retrieval specialist for finding relevant context files, standards, and guides in any repository
mode: subagent
-temperature: 0.1
+temperature: 0.4
+model: lmstudio/gpt-oss-20b
+top_p: 0.9
permission:
bash:
"*": "deny"
diff --git a/.opencode/agent/subagents/core/contextscout.md b/.opencode/agent/subagents/core/contextscout.md
index 667b1928..32fcbc9e 100644
--- a/.opencode/agent/subagents/core/contextscout.md
+++ b/.opencode/agent/subagents/core/contextscout.md
@@ -2,6 +2,9 @@
name: ContextScout
description: Discovers and recommends context files from .opencode/context/ ranked by priority. Suggests ExternalScout when a framework/library is mentioned but not found internally.
mode: subagent
+model: lmstudio/gpt-oss-20b
+temperature: 0.4
+top_p: 0.9
permission:
read:
"*": "allow"
diff --git a/.opencode/agent/subagents/core/documentation.md b/.opencode/agent/subagents/core/documentation.md
index f6a265e4..b38a9929 100644
--- a/.opencode/agent/subagents/core/documentation.md
+++ b/.opencode/agent/subagents/core/documentation.md
@@ -3,6 +3,8 @@ name: DocWriter
description: Documentation authoring agent
mode: subagent
temperature: 0.2
+model: anthropic/claude-sonnet-4-20250514
+top_p: 0.9
permission:
bash:
"*": "deny"
@@ -21,6 +23,9 @@ permission:
> **Mission**: Create and update documentation that is concise, example-driven, and consistent with project conventions β always grounded in doc standards discovered via ContextScout.
+
+ β MANDATORY: You MUST read (using the Read tool) ANY file you will write or edit BEFORE writing or editing it. If the file does not yet exist, read the parent directory. Skipping this will cause "must read before write" errors and break your workflow.
+
ALWAYS call ContextScout BEFORE writing any documentation. Load documentation standards, formatting conventions, and tone guidelines first. Docs without standards = inconsistent documentation.
@@ -38,12 +43,15 @@ permission:
Write documentation that is consistent, concise, and example-rich following project conventions
Markdown only. Propose before writing. Concise + examples mandatory.
+ - @read_before_write: MUST read any file before writing/editing it
- @context_first: ContextScout ALWAYS before writing docs
+ - @read_existing_docs: ALWAYS read existing docs before writing (Stage 2.5)
- @markdown_only: Only .md files β never touch code or config
- @concise_and_examples: Short + examples, not verbose prose
- @propose_first: Propose before writing, get confirmation
+ - Stage 2.5: Read existing documentation files
- Load documentation standards via ContextScout
- Analyze what needs documenting
- Propose documentation plan
@@ -57,6 +65,45 @@ permission:
Tier 1 always overrides Tier 2/3. If writing speed conflicts with conciseness requirement β be concise. If a doc would be verbose without examples β add examples or cut content.
---
+## π Stage 2.5: Read Existing Docs (BEFORE Writing)
+
+**CRITICAL: Read existing documentation BEFORE writing or updating docs.**
+
+This is DIFFERENT from loading context standards!
+- **ContextScout** loads documentation standards and conventions
+- **Stage 2.5** reads the ACTUAL EXISTING DOCS to maintain consistency
+
+### Process
+1. **Identify docs to read**:
+ - Existing docs on same topic
+ - Parent/sibling documentation files
+ - Related feature documentation
+2. **Read each file**:
+ ```javascript
+ Read tool: docs/existing-feature.md
+ Read tool: docs/navigation.md
+ ```
+3. **Analyze patterns**:
+ - Heading structure and hierarchy
+ - Tone and writing style
+ - Code example format
+ - Section organization
+ - Link/reference patterns
+4. **THEN call ContextScout** for formal standards
+
+### Why This Matters
+- Maintains consistency across documentation
+- Understands existing structure before adding
+- Prevents duplicate content
+- Ensures new docs fit established patterns
+
+### Examples
+β
Documenting auth feature β Read `docs/authentication.md` FIRST
+β
Updating README β Read existing `README.md` sections FIRST
+β Writing docs without reading β Inconsistent style and structure
+
+---
+
## π ContextScout β Your First Move
**ALWAYS call ContextScout before writing any documentation.** This is how you get the project's documentation standards, formatting conventions, tone guidelines, and structure requirements.
@@ -91,6 +138,8 @@ task(subagent_type="ContextScout", description="Find documentation standards", p
## What NOT to Do
+- β **Don't skip Stage 2.5** β NEVER write docs without reading existing docs first
+- β **Don't skip read-before-write** β ALWAYS read any file before writing or editing it
- β **Don't skip ContextScout** β writing docs without standards = inconsistent documentation
- β **Don't write without proposing first** β always get confirmation before making changes
- β **Don't be verbose** β concise + examples, not walls of text
diff --git a/.opencode/agent/subagents/core/externalscout.md b/.opencode/agent/subagents/core/externalscout.md
index 7da8710d..fa3d9bc5 100644
--- a/.opencode/agent/subagents/core/externalscout.md
+++ b/.opencode/agent/subagents/core/externalscout.md
@@ -2,7 +2,9 @@
name: ExternalScout
description: Fetches live, version-specific documentation for external libraries and frameworks using Context7 and other sources. Filters, sorts, and returns relevant documentation.
mode: subagent
-temperature: 0.1
+temperature: 0.4
+model: lmstudio/gpt-oss-20b
+top_p: 0.9
permission:
read:
"**/*": "deny"
@@ -28,6 +30,9 @@ permission:
+
+ β MANDATORY: You MUST read (using the Read tool) ANY file you will write or edit BEFORE writing or editing it. If the file does not yet exist, read the parent directory. Skipping this will cause "must read before write" errors and break your workflow.
+
ALLOWED:
- read: ONLY .opencode/skills/context7/** and .tmp/external-context/**
diff --git a/.opencode/agent/subagents/core/stage-orchestrator.md b/.opencode/agent/subagents/core/stage-orchestrator.md
index 7e67dbcc..923bf011 100644
--- a/.opencode/agent/subagents/core/stage-orchestrator.md
+++ b/.opencode/agent/subagents/core/stage-orchestrator.md
@@ -27,6 +27,12 @@ permission:
> **Mission**: Coordinate multi-stage feature development workflows with systematic stage transitions, validation gates, and rollback capabilities.
+
+
+ β MANDATORY: You MUST read (using the Read tool) ANY file you will write or edit BEFORE writing or editing it. If the file does not yet exist, read the parent directory. Skipping this will cause "must read before write" errors and break your workflow.
+
+
+
Multi-stage workflow coordinator within the OpenAgents orchestration pipeline
Complex feature orchestration β stage management, gating, validation, integration
Execute 8-stage workflow from architecture to release with validation and rollback
diff --git a/.opencode/agent/subagents/core/task-manager.md b/.opencode/agent/subagents/core/task-manager.md
index 46249962..3ccd7d38 100644
--- a/.opencode/agent/subagents/core/task-manager.md
+++ b/.opencode/agent/subagents/core/task-manager.md
@@ -2,7 +2,9 @@
name: TaskManager
description: JSON-driven task breakdown specialist transforming complex features into atomic, verifiable subtasks with dependency tracking and CLI integration
mode: subagent
-temperature: 0.1
+temperature: 0.2
+model: anthropic/claude-sonnet-4-20250514
+top_p: 0.9
permission:
bash:
"*": "deny"
@@ -24,6 +26,12 @@ permission:
"task-management": "allow"
---
+
+
+ β MANDATORY: You MUST read (using the Read tool) ANY file you will write or edit BEFORE writing or editing it. If the file does not yet exist, read the parent directory. Skipping this will cause "must read before write" errors and break your workflow.
+
+
+
JSON-driven task breakdown and management subagent
Software development task management with atomic task decomposition
diff --git a/.opencode/agent/subagents/development/devops-specialist.md b/.opencode/agent/subagents/development/devops-specialist.md
index 5d9aef55..43127353 100644
--- a/.opencode/agent/subagents/development/devops-specialist.md
+++ b/.opencode/agent/subagents/development/devops-specialist.md
@@ -3,6 +3,8 @@ name: OpenDevopsSpecialist
description: DevOps specialist subagent - CI/CD, infrastructure as code, deployment automation
mode: subagent
temperature: 0.1
+model: lmstudio/qwen3-coder-30b
+top_p: 0.8
permission:
task:
"*": "deny"
@@ -48,11 +50,13 @@ permission:
- @context_first: ContextScout ALWAYS before infrastructure work
+ - @read_existing_configs: ALWAYS read existing configs before modifying (Stage 2.5)
- @approval_gates: Get approval after Plan before Implement
- @subagent_mode: Execute delegated tasks only
- @security_first: No hardcoded secrets, least privilege, security scanning
+ - Stage 2.5: Read existing infrastructure configs
- Analyze: Understand infrastructure requirements
- Plan: Design deployment architecture
- Implement: Build pipelines + infrastructure
@@ -66,6 +70,45 @@ permission:
Tier 1 always overrides Tier 2/3 β safety, approval gates, and security are non-negotiable
---
+## π Stage 2.5: Read Existing Configs (BEFORE Modifying)
+
+**CRITICAL: Read existing infrastructure files BEFORE making any changes.**
+
+This is DIFFERENT from loading context standards!
+- **ContextScout** loads DevOps standards and security patterns
+- **Stage 2.5** reads the ACTUAL CONFIG FILES you will modify
+
+### Process
+1. **Identify configs to read**:
+ - CI/CD pipeline files (`.github/workflows/`, `.gitlab-ci.yml`)
+ - Infrastructure as code (`terraform/`, `k8s/`, `docker-compose.yml`)
+ - Deployment scripts (`scripts/deploy/`, `bin/deploy`)
+ - Environment configs (`.env.example`, config maps)
+2. **Read each file**:
+ ```javascript
+ Read tool: .github/workflows/ci.yml
+ Read tool: terraform/main.tf
+ ```
+3. **Understand current setup**:
+ - What providers/services are used?
+ - What's the deployment flow?
+ - What security measures exist?
+ - What dependencies between components?
+4. **THEN call ContextScout** for best practices
+
+### Why This Matters
+- Infrastructure changes can break deployments
+- Must understand dependencies before modifying
+- Prevents configuration conflicts
+- Ensures backwards compatibility
+
+### Examples
+β
Adding CI stage β Read existing `.github/workflows/ci.yml` FIRST
+β
Modifying Terraform β Read `terraform/*.tf` files FIRST
+β Changing configs without reading β Broken deployments
+
+---
+
## π ContextScout β Your First Move
**ALWAYS call ContextScout before starting any infrastructure or pipeline work.** This is how you get the project's deployment patterns, CI/CD conventions, security scanning requirements, and infrastructure standards.
@@ -100,6 +143,7 @@ task(subagent_type="ContextScout", description="Find DevOps standards", prompt="
## What NOT to Do
+- β **Don't skip Stage 2.5** β NEVER modify infrastructure without reading configs first
- β **Don't skip ContextScout** β infrastructure without project standards = security gaps and inconsistency
- β **Don't implement without approval** β Plan stage requires sign-off before Implement
- β **Don't hardcode secrets** β use secrets management (Vault, AWS Secrets Manager, env vars)
diff --git a/.opencode/agent/subagents/development/frontend-specialist.md b/.opencode/agent/subagents/development/frontend-specialist.md
index d52bbc35..55c75396 100644
--- a/.opencode/agent/subagents/development/frontend-specialist.md
+++ b/.opencode/agent/subagents/development/frontend-specialist.md
@@ -2,7 +2,9 @@
name: OpenFrontendSpecialist
description: Frontend UI design specialist - subagent for design systems, themes, animations
mode: subagent
-temperature: 0.2
+temperature: 0.1
+model: lmstudio/qwen3-coder-30b
+top_p: 0.8
permission:
task:
"*": "deny"
diff --git a/.opencode/agent/subagents/planning/architecture-analyzer.md b/.opencode/agent/subagents/planning/architecture-analyzer.md
index 7af845fa..a951afa7 100644
--- a/.opencode/agent/subagents/planning/architecture-analyzer.md
+++ b/.opencode/agent/subagents/planning/architecture-analyzer.md
@@ -26,6 +26,12 @@ permission:
> **Mission**: Analyze feature requirements through a Domain-Driven Design lens, identifying bounded contexts, module boundaries, aggregates, and domain relationships to inform multi-stage task orchestration.
+
+
+ β MANDATORY: You MUST read (using the Read tool) ANY file you will write or edit BEFORE writing or editing it. If the file does not yet exist, read the parent directory. Skipping this will cause "must read before write" errors and break your workflow.
+
+
+
DDD-driven architecture analysis subagent
Domain modeling, bounded context identification, module boundary definition
diff --git a/.opencode/agent/subagents/planning/contract-manager.md b/.opencode/agent/subagents/planning/contract-manager.md
index 653716ed..6d393ccb 100644
--- a/.opencode/agent/subagents/planning/contract-manager.md
+++ b/.opencode/agent/subagents/planning/contract-manager.md
@@ -36,6 +36,9 @@ permission:
> **Mission**: Enable parallel development through contract-first design β define clear API contracts that allow frontend and backend teams to work independently while ensuring integration success.
+
+ β MANDATORY: You MUST read (using the Read tool) ANY file you will write or edit BEFORE writing or editing it. If the file does not yet exist, read the parent directory. Skipping this will cause "must read before write" errors and break your workflow.
+
ALWAYS call ContextScout BEFORE defining any contracts. You need to understand existing API patterns, bounded contexts, and contract standards before creating new contracts.
@@ -56,6 +59,7 @@ permission:
Create contract.json files with OpenAPI specs that enable parallel development
OpenAPI 3.0+ required. Bounded context alignment mandatory. Versioning strategy explicit.
+ - @read_before_write: MUST read any file before writing/editing it
- @context_first: ContextScout ALWAYS before contract definition
- @openapi_standard: OpenAPI 3.0+ specification format
- @bounded_context_alignment: Align with domain boundaries
diff --git a/.opencode/agent/subagents/system-builder/agent-generator.md b/.opencode/agent/subagents/system-builder/agent-generator.md
index b4b370e9..6a9e6871 100644
--- a/.opencode/agent/subagents/system-builder/agent-generator.md
+++ b/.opencode/agent/subagents/system-builder/agent-generator.md
@@ -6,11 +6,19 @@
name: AgentGenerator
description: "Generates XML-optimized agent files (orchestrator and subagents) following research-backed patterns"
mode: subagent
-temperature: 0.1
+temperature: 0.2
+model: anthropic/claude-sonnet-4-20250514
+top_p: 0.9
---
# Agent Generator
+
+
+ β MANDATORY: You MUST read (using the Read tool) ANY file you will write or edit BEFORE writing or editing it. If the file does not yet exist, read the parent directory. Skipping this will cause "must read before write" errors and break your workflow.
+
+
+
AI agent prompt engineering with XML optimization
Generate complete agent files following Stanford/Anthropic research patterns
diff --git a/.opencode/agent/subagents/system-builder/command-creator.md b/.opencode/agent/subagents/system-builder/command-creator.md
index 08f83dbb..84e67f49 100644
--- a/.opencode/agent/subagents/system-builder/command-creator.md
+++ b/.opencode/agent/subagents/system-builder/command-creator.md
@@ -6,11 +6,19 @@
name: CommandCreator
description: "Creates custom slash commands that route to appropriate agents with clear syntax and examples"
mode: subagent
-temperature: 0.1
+temperature: 0.2
+model: anthropic/claude-sonnet-4-20250514
+top_p: 0.9
---
# Command Creator
+
+
+ β MANDATORY: You MUST read (using the Read tool) ANY file you will write or edit BEFORE writing or editing it. If the file does not yet exist, read the parent directory. Skipping this will cause "must read before write" errors and break your workflow.
+
+
+
Command interface design and user experience
Create custom slash commands with clear syntax, routing, and documentation
diff --git a/.opencode/agent/subagents/system-builder/context-organizer.md b/.opencode/agent/subagents/system-builder/context-organizer.md
index 311c0db0..a5d6bcd6 100644
--- a/.opencode/agent/subagents/system-builder/context-organizer.md
+++ b/.opencode/agent/subagents/system-builder/context-organizer.md
@@ -2,7 +2,9 @@
name: ContextOrganizer
description: Organizes and generates context files (domain, processes, standards, templates) for optimal knowledge management
mode: subagent
-temperature: 0.1
+temperature: 0.2
+model: anthropic/claude-sonnet-4-20250514
+top_p: 0.9
permission:
task:
contextscout: "allow"
@@ -17,6 +19,9 @@ permission:
> **Mission**: Generate well-organized, MVI-compliant context files that provide domain knowledge, process documentation, quality standards, and reusable templates.
+
+ β MANDATORY: You MUST read (using the Read tool) ANY file you will write or edit BEFORE writing or editing it. If the file does not yet exist, read the parent directory. Skipping this will cause "must read before write" errors and break your workflow.
+
ALWAYS call ContextScout BEFORE generating any context files. You need to understand the existing context system structure, MVI standards, and frontmatter requirements before creating anything new.
@@ -34,6 +39,7 @@ permission:
Generate modular context files following centralized standards discovered via ContextScout
Function-based structure only. MVI format mandatory. No duplication. Size limits enforced.
+ - @read_before_write: MUST read any file before writing/editing it
- @context_first: ContextScout ALWAYS before generating files
- @standards_before_generation: Load MVI, frontmatter, structure standards first
- @no_duplication: Check existing context, never duplicate
diff --git a/.opencode/agent/subagents/system-builder/domain-analyzer.md b/.opencode/agent/subagents/system-builder/domain-analyzer.md
index b9bd449d..59adb59d 100644
--- a/.opencode/agent/subagents/system-builder/domain-analyzer.md
+++ b/.opencode/agent/subagents/system-builder/domain-analyzer.md
@@ -6,7 +6,9 @@
name: DomainAnalyzer
description: "Analyzes user domains to identify core concepts, recommended agents, and context structure"
mode: subagent
-temperature: 0.1
+temperature: 0.2
+model: anthropic/claude-sonnet-4-20250514
+top_p: 0.9
---
# Domain Analyzer
diff --git a/.opencode/agent/subagents/system-builder/workflow-designer.md b/.opencode/agent/subagents/system-builder/workflow-designer.md
index f664e373..0b871ce3 100644
--- a/.opencode/agent/subagents/system-builder/workflow-designer.md
+++ b/.opencode/agent/subagents/system-builder/workflow-designer.md
@@ -2,7 +2,9 @@
name: WorkflowDesigner
description: Designs complete workflow definitions with context dependencies and success criteria
mode: subagent
-temperature: 0.1
+temperature: 0.2
+model: anthropic/claude-sonnet-4-20250514
+top_p: 0.9
permission:
task:
contextscout: "allow"
@@ -17,6 +19,9 @@ permission:
> **Mission**: Design complete, executable workflow definitions that map use cases to agent coordination patterns β always grounded in existing workflow standards discovered via ContextScout.
+
+ β MANDATORY: You MUST read (using the Read tool) ANY file you will write or edit BEFORE writing or editing it. If the file does not yet exist, read the parent directory. Skipping this will cause "must read before write" errors and break your workflow.
+
ALWAYS call ContextScout BEFORE designing any workflow. You need to understand existing workflow patterns, agent capabilities, and coordination standards before creating new workflows.
@@ -34,6 +39,7 @@ permission:
Design executable workflows with clear stages, context dependencies, and success criteria
Validation gates mandatory. Context dependencies documented per stage. Success criteria measurable.
+ - @read_before_write: MUST read any file before writing/editing it
- @context_first: ContextScout ALWAYS before designing workflows
- @validation_gates_required: Every workflow needs checkpoints between stages
- @context_dependencies_mandatory: Every stage documents what context it needs
diff --git a/.opencode/agent/subagents/test/simple-responder.md b/.opencode/agent/subagents/test/simple-responder.md
index 73a4e95f..a5b0c78d 100644
--- a/.opencode/agent/subagents/test/simple-responder.md
+++ b/.opencode/agent/subagents/test/simple-responder.md
@@ -6,7 +6,9 @@
name: Simple Responder
description: "Test agent that responds with 'AWESOME TESTING' - for eval framework testing"
mode: subagent
-temperature: 0.0
+temperature: 0.4
+model: lmstudio/gpt-oss-20b
+top_p: 0.9
---
# Simple Responder - Test Agent
diff --git a/.opencode/agent/subagents/utils/image-specialist.md b/.opencode/agent/subagents/utils/image-specialist.md
index c7576dba..206b7a5a 100644
--- a/.opencode/agent/subagents/utils/image-specialist.md
+++ b/.opencode/agent/subagents/utils/image-specialist.md
@@ -6,7 +6,9 @@
name: Image Specialist
description: "Specialized agent for image editing and analysis using Gemini AI tools"
mode: subagent
-temperature: 0.2
+temperature: 0.4
+model: lmstudio/gpt-oss-20b
+top_p: 0.9
---
You are an image processing specialist powered by Gemini AI's Nano Banana model. Your capabilities include:
diff --git a/.opencode/command/model-router.md b/.opencode/command/model-router.md
new file mode 100644
index 00000000..b0981d0e
--- /dev/null
+++ b/.opencode/command/model-router.md
@@ -0,0 +1,87 @@
+---
+description: Configure per-agent model routing β view, apply, and manage tier-based model assignments
+tags:
+ - models
+ - routing
+ - configuration
+ - agents
+dependencies:
+ - skill:model-router
+---
+
+# Model Router
+
+**Arguments**: `$ARGUMENTS`
+
+---
+
+## Default Behavior (No Arguments)
+
+When invoked without arguments: `/model-router`
+
+Runs `status` β shows current agentβmodel assignments and any drift.
+
+---
+
+## Commands
+
+### `/model-router status`
+
+Show all agentβmodel assignments grouped by tier. Highlights drift (when agent frontmatter doesn't match tier config).
+
+### `/model-router apply`
+
+Sync `model-tiers.json` to all agent markdown frontmatter. Writes `model`, `temperature`, and `top_p` to each agent's frontmatter based on its tier assignment.
+
+**Always preview first**:
+```bash
+bash .opencode/skills/model-router/router.sh apply --dry-run
+```
+
+Then apply:
+```bash
+bash .opencode/skills/model-router/router.sh apply
+```
+
+### `/model-router tier `
+
+Change a tier's model. Example:
+```bash
+bash .opencode/skills/model-router/router.sh tier fast lmstudio/phi-4-mini
+```
+
+After changing a tier, run `apply` to propagate.
+
+### `/model-router assign `
+
+Move an agent to a different tier. Example:
+```bash
+bash .opencode/skills/model-router/router.sh assign contextscout medium
+```
+
+After changing an assignment, run `apply` to propagate.
+
+### `/model-router tiers`
+
+List all tier definitions with their model, temperature, and top_p settings.
+
+### `/model-router unassigned`
+
+Show agents in the registry that aren't in `model-tiers.json` assignments yet.
+
+---
+
+## Config Location
+
+`.opencode/skills/model-router/config/model-tiers.json`
+
+Edit this file directly to add new tiers, change defaults, or bulk-edit assignments.
+
+---
+
+## Workflow
+
+1. **View**: `/model-router status` β see current state
+2. **Edit**: Change tier or assignment via CLI commands, or edit `model-tiers.json` directly
+3. **Preview**: `bash .opencode/skills/model-router/router.sh apply --dry-run`
+4. **Apply**: `bash .opencode/skills/model-router/router.sh apply`
diff --git a/.opencode/context/core/standards/tdd.md b/.opencode/context/core/standards/tdd.md
new file mode 100644
index 00000000..6d8f8f6f
--- /dev/null
+++ b/.opencode/context/core/standards/tdd.md
@@ -0,0 +1,160 @@
+# TDD Standards
+
+> **Purpose**: Mandate test-first development for all coding tasks. No implementation without tests.
+
+## TDD Definition
+
+Test-Driven Development (TDD) is a **mandatory** development practice, not optional.
+
+### Red-Green-Refactor Sequence
+
+```
+1. RED: Write a failing test that defines expected behavior
+2. GREEN: Write minimal implementation to make test pass
+3. REFACTOR: Clean up code while maintaining test coverage
+```
+
+**Critical**: Steps must occur in order. You cannot skip to GREEN without RED.
+
+---
+
+## Critical Rules
+
+
+ BEFORE writing implementation code for ANY deliverable, verify test exists and is failing.
+ If no test exists β write minimal failing test first (Red phase).
+ If test exists but passes β fix test to expect correct behavior.
+
+
+
+ If a deliverable has NO testable behavior (e.g., config file, static asset), explicitly document why in the subtask completion notes.
+ All code deliverables require tests. Document exceptions.
+
+
+
+ Implement ONLY what makes the test pass. No over-engineering, no future-proofing.
+ Write the simplest solution that satisfies the test.
+
+
+
+ Refactor ONLY after test is green. Never refactor failing tests.
+ Maintain all existing test coverage during refactor.
+
+
+
+ NEVER mark a subtask complete if tests are missing, failing, or not yet written.
+ Completion requires: tests written + tests passing.
+
+
+---
+
+## Test Type Matrix
+
+| Deliverable Type | Required Test(s) | Test Location |
+|-----------------|------------------|---------------|
+| Utility function | Unit test (Vitest) | `src/utils/*.test.ts` |
+| React component | Component test + E2E if interactive | `src/**/*.test.tsx` + `e2e/*.spec.ts` |
+| API endpoint | Unit test + E2E | `src/**/*.test.ts` + `e2e/*.spec.ts` |
+| Zustand store | Unit test | `src/stores/*.test.ts` |
+| Custom hook | Unit test | `src/hooks/*.test.ts` |
+| Type definition | No test required | N/A |
+| Config file | No test required | N/A |
+| Static asset | No test required | N/A |
+
+---
+
+## Test Quality Requirements
+
+### Positive and Negative Tests
+
+Every testable behavior MUST have:
+- **Positive test**: Expected success case
+- **Negative test**: Expected failure/edge case
+
+```
+Example:
+- Positive: should return user data when valid ID provided
+- Negative: should throw error when invalid ID provided
+```
+
+### Arrange-Act-Assert Pattern
+
+ALL tests must follow AAA structure:
+
+```typescript
+// ARRANGE: Set up test data and conditions
+const input = { id: '123', name: 'Test' };
+
+// ACT: Execute the behavior being tested
+const result = processUser(input);
+
+// ASSERT: Verify the expected outcome
+expect(result).toEqual({ id: '123', name: 'Test' });
+```
+
+### Mock External Dependencies
+
+All external dependencies MUST be mocked:
+- API calls (fetch, axios)
+- localStorage/sessionStorage
+- Browser APIs (window, document)
+- Third-party libraries
+
+Tests must be **deterministic** β no network flakiness, no time-dependent assertions.
+
+---
+
+## TDD Workflow in Subtasks
+
+### For Each Deliverable:
+
+1. **Check if test exists**
+ - Scan for existing test file matching deliverable name
+ - If missing β create new test file with failing test
+
+2. **Verify test is in RED state**
+ - Run test: it should FAIL
+ - If test passes β fix assertion to expect correct behavior
+
+3. **Write minimal implementation**
+ - Only enough code to make test pass
+ - No extra features, no future-proofing
+
+4. **Run test β should be GREEN**
+ - If fails β continue implementing until pass
+
+5. **Refactor if needed**
+ - Clean up while maintaining test coverage
+ - Re-run tests to confirm still green
+
+6. **Verify all tests pass**
+ - Run full test suite
+ - Confirm no regressions
+
+---
+
+## Blocking Rules for CoderAgent
+
+CoderAgent MUST NOT mark subtask complete if ANY of these conditions exist:
+
+- [ ] Test file missing for deliverable
+- [ ] Test exists but not yet run
+- [ ] Tests failing (not in GREEN state)
+- [ ] No documentation for why deliverable has no test
+
+**Self-Review must include test verification:**
+
+```
+Self-Review: β
Types clean | β
Imports verified | β
No debug artifacts | β
All acceptance criteria met | β
Tests REDβGREEN | β
External libs verified
+```
+
+---
+
+## Context Discovery
+
+When ContextScout loads context for a task:
+1. Load `standards/tdd.md` (this file) β MANDATORY
+2. Load `standards/code-quality.md` β for code style
+3. Load project-specific test patterns from `context/`
+
+All agents must acknowledge TDD standards before implementing.
diff --git a/.opencode/env.example b/.opencode/env.example
new file mode 100644
index 00000000..ace3b220
--- /dev/null
+++ b/.opencode/env.example
@@ -0,0 +1,28 @@
+# Telegram Bot Configuration
+# Copy this file to .env and fill in your actual values
+
+# Your Telegram bot token (get from @BotFather)
+TELEGRAM_BOT_TOKEN=your_bot_token_here
+
+# Your chat ID (get by messaging your bot and checking the API)
+TELEGRAM_CHAT_ID=your_chat_id_here
+
+# Your bot username (optional, defaults to @OpenCode)
+TELEGRAM_BOT_USERNAME=@YourBotUsername
+
+# Idle timeout in milliseconds (default: 5 minutes = 300000ms)
+TELEGRAM_IDLE_TIMEOUT=300000
+
+# Check interval in milliseconds (default: 30 seconds = 30000ms)
+TELEGRAM_CHECK_INTERVAL=30000
+
+# Enable/disable the plugin (true/false)
+TELEGRAM_ENABLED=true
+
+# Gemini API Configuration
+# Get your API key from https://makersuite.google.com/app/apikey
+GEMINI_API_KEY=your_gemini_api_key_here
+
+# MiniMax API Configuration
+# Get your API key from https://platform.minimax.io
+MINIMAX_API_KEY=your_minimax_api_key_here
diff --git a/.opencode/package-lock.json b/.opencode/package-lock.json
new file mode 100644
index 00000000..f1aab8d7
--- /dev/null
+++ b/.opencode/package-lock.json
@@ -0,0 +1,376 @@
+{
+ "name": ".opencode",
+ "lockfileVersion": 3,
+ "requires": true,
+ "packages": {
+ "": {
+ "dependencies": {
+ "@opencode-ai/plugin": "1.14.20"
+ }
+ },
+ "node_modules/@msgpackr-extract/msgpackr-extract-darwin-arm64": {
+ "version": "3.0.3",
+ "resolved": "https://registry.npmjs.org/@msgpackr-extract/msgpackr-extract-darwin-arm64/-/msgpackr-extract-darwin-arm64-3.0.3.tgz",
+ "integrity": "sha512-QZHtlVgbAdy2zAqNA9Gu1UpIuI8Xvsd1v8ic6B2pZmeFnFcMWiPLfWXh7TVw4eGEZ/C9TH281KwhVoeQUKbyjw==",
+ "cpu": [
+ "arm64"
+ ],
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "darwin"
+ ]
+ },
+ "node_modules/@msgpackr-extract/msgpackr-extract-darwin-x64": {
+ "version": "3.0.3",
+ "resolved": "https://registry.npmjs.org/@msgpackr-extract/msgpackr-extract-darwin-x64/-/msgpackr-extract-darwin-x64-3.0.3.tgz",
+ "integrity": "sha512-mdzd3AVzYKuUmiWOQ8GNhl64/IoFGol569zNRdkLReh6LRLHOXxU4U8eq0JwaD8iFHdVGqSy4IjFL4reoWCDFw==",
+ "cpu": [
+ "x64"
+ ],
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "darwin"
+ ]
+ },
+ "node_modules/@msgpackr-extract/msgpackr-extract-linux-arm": {
+ "version": "3.0.3",
+ "resolved": "https://registry.npmjs.org/@msgpackr-extract/msgpackr-extract-linux-arm/-/msgpackr-extract-linux-arm-3.0.3.tgz",
+ "integrity": "sha512-fg0uy/dG/nZEXfYilKoRe7yALaNmHoYeIoJuJ7KJ+YyU2bvY8vPv27f7UKhGRpY6euFYqEVhxCFZgAUNQBM3nw==",
+ "cpu": [
+ "arm"
+ ],
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ]
+ },
+ "node_modules/@msgpackr-extract/msgpackr-extract-linux-arm64": {
+ "version": "3.0.3",
+ "resolved": "https://registry.npmjs.org/@msgpackr-extract/msgpackr-extract-linux-arm64/-/msgpackr-extract-linux-arm64-3.0.3.tgz",
+ "integrity": "sha512-YxQL+ax0XqBJDZiKimS2XQaf+2wDGVa1enVRGzEvLLVFeqa5kx2bWbtcSXgsxjQB7nRqqIGFIcLteF/sHeVtQg==",
+ "cpu": [
+ "arm64"
+ ],
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ]
+ },
+ "node_modules/@msgpackr-extract/msgpackr-extract-linux-x64": {
+ "version": "3.0.3",
+ "resolved": "https://registry.npmjs.org/@msgpackr-extract/msgpackr-extract-linux-x64/-/msgpackr-extract-linux-x64-3.0.3.tgz",
+ "integrity": "sha512-cvwNfbP07pKUfq1uH+S6KJ7dT9K8WOE4ZiAcsrSes+UY55E/0jLYc+vq+DO7jlmqRb5zAggExKm0H7O/CBaesg==",
+ "cpu": [
+ "x64"
+ ],
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ]
+ },
+ "node_modules/@msgpackr-extract/msgpackr-extract-win32-x64": {
+ "version": "3.0.3",
+ "resolved": "https://registry.npmjs.org/@msgpackr-extract/msgpackr-extract-win32-x64/-/msgpackr-extract-win32-x64-3.0.3.tgz",
+ "integrity": "sha512-x0fWaQtYp4E6sktbsdAqnehxDgEc/VwM7uLsRCYWaiGu0ykYdZPiS8zCWdnjHwyiumousxfBm4SO31eXqwEZhQ==",
+ "cpu": [
+ "x64"
+ ],
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "win32"
+ ]
+ },
+ "node_modules/@opencode-ai/plugin": {
+ "version": "1.14.20",
+ "resolved": "https://registry.npmjs.org/@opencode-ai/plugin/-/plugin-1.14.20.tgz",
+ "integrity": "sha512-txRfm6Y2DBqFxJtgo63vj5//d7TJS7/angWELUEQcsSK0llfvmVp60gox4e8zIwpGjDcDP9A4qO6oNe++pockg==",
+ "license": "MIT",
+ "dependencies": {
+ "@opencode-ai/sdk": "1.14.20",
+ "effect": "4.0.0-beta.48",
+ "zod": "4.1.8"
+ },
+ "peerDependencies": {
+ "@opentui/core": ">=0.1.99",
+ "@opentui/solid": ">=0.1.99"
+ },
+ "peerDependenciesMeta": {
+ "@opentui/core": {
+ "optional": true
+ },
+ "@opentui/solid": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/@opencode-ai/sdk": {
+ "version": "1.14.20",
+ "resolved": "https://registry.npmjs.org/@opencode-ai/sdk/-/sdk-1.14.20.tgz",
+ "integrity": "sha512-kPZP1An1ZdWOfLfDYhNjh665HX4RcI8au6Lzjn0FktoQ3RpWHq1WXRLHrJO8rJqwWvQDOzS48cXt9jbr+uwQiA==",
+ "license": "MIT",
+ "dependencies": {
+ "cross-spawn": "7.0.6"
+ }
+ },
+ "node_modules/@standard-schema/spec": {
+ "version": "1.1.0",
+ "resolved": "https://registry.npmjs.org/@standard-schema/spec/-/spec-1.1.0.tgz",
+ "integrity": "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==",
+ "license": "MIT"
+ },
+ "node_modules/cross-spawn": {
+ "version": "7.0.6",
+ "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
+ "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
+ "license": "MIT",
+ "dependencies": {
+ "path-key": "^3.1.0",
+ "shebang-command": "^2.0.0",
+ "which": "^2.0.1"
+ },
+ "engines": {
+ "node": ">= 8"
+ }
+ },
+ "node_modules/detect-libc": {
+ "version": "2.1.2",
+ "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
+ "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
+ "license": "Apache-2.0",
+ "optional": true,
+ "engines": {
+ "node": ">=8"
+ }
+ },
+ "node_modules/effect": {
+ "version": "4.0.0-beta.48",
+ "resolved": "https://registry.npmjs.org/effect/-/effect-4.0.0-beta.48.tgz",
+ "integrity": "sha512-MMAM/ZabuNdNmgXiin+BAanQXK7qM8mlt7nfXDoJ/Gn9V8i89JlCq+2N0AiWmqFLXjGLA0u3FjiOjSOYQk5uMw==",
+ "license": "MIT",
+ "dependencies": {
+ "@standard-schema/spec": "^1.1.0",
+ "fast-check": "^4.6.0",
+ "find-my-way-ts": "^0.1.6",
+ "ini": "^6.0.0",
+ "kubernetes-types": "^1.30.0",
+ "msgpackr": "^1.11.9",
+ "multipasta": "^0.2.7",
+ "toml": "^4.1.1",
+ "uuid": "^13.0.0",
+ "yaml": "^2.8.3"
+ }
+ },
+ "node_modules/fast-check": {
+ "version": "4.7.0",
+ "resolved": "https://registry.npmjs.org/fast-check/-/fast-check-4.7.0.tgz",
+ "integrity": "sha512-NsZRtqvSSoCP0HbNjUD+r1JH8zqZalyp6gLY9e7OYs7NK9b6AHOs2baBFeBG7bVNsuoukh89x2Yg3rPsul8ziQ==",
+ "funding": [
+ {
+ "type": "individual",
+ "url": "https://github.com/sponsors/dubzzz"
+ },
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/fast-check"
+ }
+ ],
+ "license": "MIT",
+ "dependencies": {
+ "pure-rand": "^8.0.0"
+ },
+ "engines": {
+ "node": ">=12.17.0"
+ }
+ },
+ "node_modules/find-my-way-ts": {
+ "version": "0.1.6",
+ "resolved": "https://registry.npmjs.org/find-my-way-ts/-/find-my-way-ts-0.1.6.tgz",
+ "integrity": "sha512-a85L9ZoXtNAey3Y6Z+eBWW658kO/MwR7zIafkIUPUMf3isZG0NCs2pjW2wtjxAKuJPxMAsHUIP4ZPGv0o5gyTA==",
+ "license": "MIT"
+ },
+ "node_modules/ini": {
+ "version": "6.0.0",
+ "resolved": "https://registry.npmjs.org/ini/-/ini-6.0.0.tgz",
+ "integrity": "sha512-IBTdIkzZNOpqm7q3dRqJvMaldXjDHWkEDfrwGEQTs5eaQMWV+djAhR+wahyNNMAa+qpbDUhBMVt4ZKNwpPm7xQ==",
+ "license": "ISC",
+ "engines": {
+ "node": "^20.17.0 || >=22.9.0"
+ }
+ },
+ "node_modules/isexe": {
+ "version": "2.0.0",
+ "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
+ "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==",
+ "license": "ISC"
+ },
+ "node_modules/kubernetes-types": {
+ "version": "1.30.0",
+ "resolved": "https://registry.npmjs.org/kubernetes-types/-/kubernetes-types-1.30.0.tgz",
+ "integrity": "sha512-Dew1okvhM/SQcIa2rcgujNndZwU8VnSapDgdxlYoB84ZlpAD43U6KLAFqYo17ykSFGHNPrg0qry0bP+GJd9v7Q==",
+ "license": "Apache-2.0"
+ },
+ "node_modules/msgpackr": {
+ "version": "1.11.10",
+ "resolved": "https://registry.npmjs.org/msgpackr/-/msgpackr-1.11.10.tgz",
+ "integrity": "sha512-iCZNq+HszvF+fC3anCm4nBmWEnbeIAfpDs6IStAEKhQ2YSgkjzVG2FF9XJqwwQh5bH3N9OUTUt4QwVN6MLMLtA==",
+ "license": "MIT",
+ "optionalDependencies": {
+ "msgpackr-extract": "^3.0.2"
+ }
+ },
+ "node_modules/msgpackr-extract": {
+ "version": "3.0.3",
+ "resolved": "https://registry.npmjs.org/msgpackr-extract/-/msgpackr-extract-3.0.3.tgz",
+ "integrity": "sha512-P0efT1C9jIdVRefqjzOQ9Xml57zpOXnIuS+csaB4MdZbTdmGDLo8XhzBG1N7aO11gKDDkJvBLULeFTo46wwreA==",
+ "hasInstallScript": true,
+ "license": "MIT",
+ "optional": true,
+ "dependencies": {
+ "node-gyp-build-optional-packages": "5.2.2"
+ },
+ "bin": {
+ "download-msgpackr-prebuilds": "bin/download-prebuilds.js"
+ },
+ "optionalDependencies": {
+ "@msgpackr-extract/msgpackr-extract-darwin-arm64": "3.0.3",
+ "@msgpackr-extract/msgpackr-extract-darwin-x64": "3.0.3",
+ "@msgpackr-extract/msgpackr-extract-linux-arm": "3.0.3",
+ "@msgpackr-extract/msgpackr-extract-linux-arm64": "3.0.3",
+ "@msgpackr-extract/msgpackr-extract-linux-x64": "3.0.3",
+ "@msgpackr-extract/msgpackr-extract-win32-x64": "3.0.3"
+ }
+ },
+ "node_modules/multipasta": {
+ "version": "0.2.7",
+ "resolved": "https://registry.npmjs.org/multipasta/-/multipasta-0.2.7.tgz",
+ "integrity": "sha512-KPA58d68KgGil15oDqXjkUBEBYc00XvbPj5/X+dyzeo/lWm9Nc25pQRlf1D+gv4OpK7NM0J1odrbu9JNNGvynA==",
+ "license": "MIT"
+ },
+ "node_modules/node-gyp-build-optional-packages": {
+ "version": "5.2.2",
+ "resolved": "https://registry.npmjs.org/node-gyp-build-optional-packages/-/node-gyp-build-optional-packages-5.2.2.tgz",
+ "integrity": "sha512-s+w+rBWnpTMwSFbaE0UXsRlg7hU4FjekKU4eyAih5T8nJuNZT1nNsskXpxmeqSK9UzkBl6UgRlnKc8hz8IEqOw==",
+ "license": "MIT",
+ "optional": true,
+ "dependencies": {
+ "detect-libc": "^2.0.1"
+ },
+ "bin": {
+ "node-gyp-build-optional-packages": "bin.js",
+ "node-gyp-build-optional-packages-optional": "optional.js",
+ "node-gyp-build-optional-packages-test": "build-test.js"
+ }
+ },
+ "node_modules/path-key": {
+ "version": "3.1.1",
+ "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz",
+ "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=8"
+ }
+ },
+ "node_modules/pure-rand": {
+ "version": "8.4.0",
+ "resolved": "https://registry.npmjs.org/pure-rand/-/pure-rand-8.4.0.tgz",
+ "integrity": "sha512-IoM8YF/jY0hiugFo/wOWqfmarlE6J0wc6fDK1PhftMk7MGhVZl88sZimmqBBFomLOCSmcCCpsfj7wXASCpvK9A==",
+ "funding": [
+ {
+ "type": "individual",
+ "url": "https://github.com/sponsors/dubzzz"
+ },
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/fast-check"
+ }
+ ],
+ "license": "MIT"
+ },
+ "node_modules/shebang-command": {
+ "version": "2.0.0",
+ "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz",
+ "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==",
+ "license": "MIT",
+ "dependencies": {
+ "shebang-regex": "^3.0.0"
+ },
+ "engines": {
+ "node": ">=8"
+ }
+ },
+ "node_modules/shebang-regex": {
+ "version": "3.0.0",
+ "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz",
+ "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=8"
+ }
+ },
+ "node_modules/toml": {
+ "version": "4.1.1",
+ "resolved": "https://registry.npmjs.org/toml/-/toml-4.1.1.tgz",
+ "integrity": "sha512-EBJnVBr3dTXdA89WVFoAIPUqkBjxPMwRqsfuo1r240tKFHXv3zgca4+NJib/h6TyvGF7vOawz0jGuryJCdNHrw==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=20"
+ }
+ },
+ "node_modules/uuid": {
+ "version": "13.0.0",
+ "resolved": "https://registry.npmjs.org/uuid/-/uuid-13.0.0.tgz",
+ "integrity": "sha512-XQegIaBTVUjSHliKqcnFqYypAd4S+WCYt5NIeRs6w/UAry7z8Y9j5ZwRRL4kzq9U3sD6v+85er9FvkEaBpji2w==",
+ "funding": [
+ "https://github.com/sponsors/broofa",
+ "https://github.com/sponsors/ctavan"
+ ],
+ "license": "MIT",
+ "bin": {
+ "uuid": "dist-node/bin/uuid"
+ }
+ },
+ "node_modules/which": {
+ "version": "2.0.2",
+ "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
+ "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==",
+ "license": "ISC",
+ "dependencies": {
+ "isexe": "^2.0.0"
+ },
+ "bin": {
+ "node-which": "bin/node-which"
+ },
+ "engines": {
+ "node": ">= 8"
+ }
+ },
+ "node_modules/yaml": {
+ "version": "2.8.3",
+ "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.3.tgz",
+ "integrity": "sha512-AvbaCLOO2Otw/lW5bmh9d/WEdcDFdQp2Z2ZUH3pX9U2ihyUY0nvLv7J6TrWowklRGPYbB/IuIMfYgxaCPg5Bpg==",
+ "license": "ISC",
+ "bin": {
+ "yaml": "bin.mjs"
+ },
+ "engines": {
+ "node": ">= 14.6"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/eemeli"
+ }
+ },
+ "node_modules/zod": {
+ "version": "4.1.8",
+ "license": "MIT",
+ "funding": {
+ "url": "https://github.com/sponsors/colinhacks"
+ }
+ }
+ }
+}
diff --git a/.opencode/skills/model-router/SKILL.md b/.opencode/skills/model-router/SKILL.md
new file mode 100644
index 00000000..4faead81
--- /dev/null
+++ b/.opencode/skills/model-router/SKILL.md
@@ -0,0 +1,265 @@
+---
+name: model-router
+description: Per-agent model routing with tier-based configuration β assign models to agents by role, reconfigure from one place
+version: 1.0.0
+author: opencode
+type: skill
+category: configuration
+tags:
+ - models
+ - routing
+ - configuration
+ - agents
+ - tiers
+---
+
+# Model Router Skill
+
+> **Purpose**: Configure which AI model each agent and subagent uses β from a single config file. Change a tier, re-apply, and all agents in that tier update instantly.
+
+---
+
+## What I Do
+
+I provide tier-based model routing for all agents and subagents:
+
+- **Define tiers** β Group models by capability (fast, medium, powerful)
+- **Assign agents to tiers** β Map each agent to the right model tier
+- **Apply in one command** β Sync model settings to all agent frontmatter
+- **Detect drift** β Spot when an agent's frontmatter doesn't match its tier
+- **Reconfigure instantly** β Change a tier's model, then apply
+
+---
+
+## Why This Exists
+
+OpenCode supports per-agent `model` configuration in agent markdown frontmatter and `opencode.json`. But with 30+ agents, manually editing each one is tedious and error-prone. This skill gives you a **single source of truth** (`model-tiers.json`) and a command to propagate changes.
+
+---
+
+## Quick Start
+
+```bash
+# See current assignments and any drift
+bash .opencode/skills/model-router/router.sh status
+
+# Apply tier config to all agent frontmatter
+bash .opencode/skills/model-router/router.sh apply
+
+# Preview changes without writing
+bash .opencode/skills/model-router/router.sh apply --dry-run
+```
+
+---
+
+## Command Reference
+
+| Command | Description |
+|---------|-------------|
+| `status` | Show current agentβmodel assignments and drift from config |
+| `apply [--dry-run]` | Sync model-tiers.json β agent markdown frontmatter |
+| `tier ` | Change a tier's model (e.g., `tier fast lmstudio/phi-4-mini`) |
+| `assign ` | Move an agent to a different tier (e.g., `assign contextscout medium`) |
+| `tiers` | List all tier definitions with models and settings |
+| `unassigned` | Show agents in registry not yet in assignments |
+| `help` | Show help message |
+
+---
+
+## Architecture
+
+```
+.opencode/skills/model-router/
+βββ SKILL.md # This file
+βββ router.sh # CLI router (entry point)
+βββ config/
+β βββ model-tiers.json # Central model routing config (source of truth)
+βββ scripts/
+ βββ model-router.ts # Apply/status/tier/assign automation
+```
+
+---
+
+## Config File: model-tiers.json
+
+The single source of truth for model routing. Located at:
+`.opencode/skills/model-router/config/model-tiers.json`
+
+### Schema
+
+```json
+{
+ "version": "1.0.0",
+ "tiers": {
+ "": {
+ "description": "What this tier is for",
+ "model": "provider/model-id",
+ "temperature": 0.2,
+ "top_p": 0.9
+ }
+ },
+ "defaults": {
+ "primary_agents": "tier-name",
+ "subagents": "tier-name"
+ },
+ "assignments": {
+ "": ""
+ }
+}
+```
+
+### Default Tiers
+
+| Tier | Purpose | Example Model |
+|------|---------|---------------|
+| **fast** | Simple tasks: web fetch, context scout, search | `lmstudio/gpt-oss-20b` |
+| **medium** | Coding, testing, medium-complexity tasks | `lmstudio/qwen3-coder-30b` |
+| **powerful** | Planning, orchestration, doc writing, architecture | `anthropic/claude-sonnet-4-20250514` |
+
+### Default Assignments
+
+| Tier | Agents |
+|------|--------|
+| **powerful** | openagent, opencoder, task-manager, documentation, domain-analyzer, agent-generator, context-organizer, workflow-designer, command-creator, architecture-analyzer, contract-manager, adr-manager, prioritization-engine, story-mapper, stage-orchestrator |
+| **medium** | coder-agent, tester, build-agent, reviewer, batch-executor, frontend-specialist, devops-specialist |
+| **fast** | contextscout, externalscout, context-retriever, context-manager, image-specialist, simple-responder |
+
+---
+
+## How Apply Works
+
+1. Reads `model-tiers.json` to get tierβmodel mappings
+2. Reads `registry.json` to resolve agent-id β file path
+3. For each agent in `assignments`, resolves its tier to `model`, `temperature`, `top_p`
+4. Updates the agent's markdown frontmatter in-place (only `model`, `temperature`, `top_p` fields)
+5. Preserves all other frontmatter fields (name, description, mode, permission, etc.)
+6. Reports what changed
+
+---
+
+## Common Workflows
+
+### 1. Check Current State
+
+```bash
+bash .opencode/skills/model-router/router.sh status
+```
+
+Shows all agentβmodel assignments, grouped by tier. Highlights any drift (agent frontmatter doesn't match its tier).
+
+### 2. Switch All "fast" Agents to a New Model
+
+```bash
+# Step 1: Update the tier definition
+bash .opencode/skills/model-router/router.sh tier fast lmstudio/phi-4-mini
+
+# Step 2: Preview the changes
+bash .opencode/skills/model-router/router.sh apply --dry-run
+
+# Step 3: Apply
+bash .opencode/skills/model-router/router.sh apply
+```
+
+### 3. Move a Single Agent to a Different Tier
+
+```bash
+# Move contextscout from "fast" to "medium"
+bash .opencode/skills/model-router/router.sh assign contextscout medium
+
+# Apply the change
+bash .opencode/skills/model-router/router.sh apply
+```
+
+### 4. Add a New Tier
+
+Edit `model-tiers.json` directly to add a new tier:
+
+```json
+{
+ "tiers": {
+ "fast": { ... },
+ "medium": { ... },
+ "powerful": { ... },
+ "reasoning": {
+ "description": "Deep reasoning for complex analysis",
+ "model": "openai/o3-mini",
+ "temperature": 1.0,
+ "top_p": 0.95
+ }
+ }
+}
+```
+
+Then assign agents to it and apply:
+
+```bash
+bash .opencode/skills/model-router/router.sh assign task-manager reasoning
+bash .opencode/skills/model-router/router.sh apply
+```
+
+### 5. Find Unassigned Agents
+
+```bash
+bash .opencode/skills/model-router/router.sh unassigned
+```
+
+Shows agents in the registry that aren't in `assignments` yet, so you can add them.
+
+---
+
+## Key Concepts
+
+### Tiers
+
+A tier groups model settings (model ID, temperature, top_p) under a name. All agents assigned to a tier share the same model configuration. This means you can switch 10 agents from one model to another by changing a single tier definition.
+
+### Assignments
+
+The `assignments` map links each agent-id to a tier name. This is the routing table. When you run `apply`, the script resolves each agent's tier to its model settings and writes those to the agent's frontmatter.
+
+### Drift
+
+Drift occurs when an agent's frontmatter `model` field doesn't match what its tier defines. This can happen if someone manually edits an agent file, or if you change a tier but forget to apply. The `status` command detects and reports drift.
+
+### Apply Target
+
+The `apply` command writes `model`, `temperature`, and `top_p` into each agent's markdown frontmatter. This is where OpenCode natively reads model configuration. Provider settings (API keys, base URLs) remain in `opencode.json` β this skill only manages the agentβmodel assignment.
+
+---
+
+## Integration
+
+### With OpenCode
+
+OpenCode natively reads `model`, `temperature`, and `top_p` from agent frontmatter. After running `apply`, the next time an agent is invoked, it will use the new model.
+
+### With Profiles
+
+Profiles (`.opencode/profiles/`) determine which agents are **included** in a setup. Model routing determines which **model** each included agent uses. They are orthogonal β you can use both together.
+
+### With Registry
+
+The `registry.json` provides the agent-id β file-path mapping. The model router reads this to find each agent's markdown file when applying.
+
+---
+
+## Troubleshooting
+
+### "Config not found"
+Make sure `.opencode/skills/model-router/config/model-tiers.json` exists.
+
+### "Registry not found"
+Make sure `registry.json` exists at the project root.
+
+### "No frontmatter found in file"
+The agent's markdown file may not have a YAML frontmatter block. Add one with `---` delimiters.
+
+### "Drift detected"
+Run `bash .opencode/skills/model-router/router.sh apply` to sync all agents with their tier definitions.
+
+### Model not showing up after apply
+Restart OpenCode to pick up the frontmatter changes, or switch agents and switch back.
+
+---
+
+**Model Router Skill** β Configure per-agent models from a single file!
diff --git a/.opencode/skills/model-router/config/model-tiers.json b/.opencode/skills/model-router/config/model-tiers.json
new file mode 100644
index 00000000..20a81b88
--- /dev/null
+++ b/.opencode/skills/model-router/config/model-tiers.json
@@ -0,0 +1,65 @@
+{
+ "$schema": "https://opencode.ai/config.json",
+ "version": "1.0.0",
+ "description": "Centralized model routing: define tiers, assign agents to tiers, reconfigure from one place.",
+ "tiers": {
+ "fast": {
+ "description": "Fast, cheap model for simple tasks β web fetch, context scout, search, simple lookups",
+ "model": "lmstudio/gpt-oss-20b",
+ "temperature": 0.4,
+ "top_p": 0.9
+ },
+ "medium": {
+ "description": "Balanced model for coding, testing, and medium-complexity tasks",
+ "model": "lmstudio/qwen3-coder-30b",
+ "temperature": 0.1,
+ "top_p": 0.8
+ },
+ "powerful": {
+ "description": "Most capable model for planning, orchestration, architecture, and complex reasoning",
+ "model": "anthropic/claude-sonnet-4-20250514",
+ "temperature": 0.2,
+ "top_p": 0.9
+ }
+ },
+ "defaults": {
+ "primary_agents": "powerful",
+ "subagents": "medium"
+ },
+ "assignments": {
+ "openagent": "powerful",
+ "opencoder": "powerful",
+ "coder-agent": "medium",
+ "tester": "medium",
+ "build-agent": "medium",
+ "reviewer": "medium",
+ "task-manager": "powerful",
+ "batch-executor": "medium",
+ "documentation": "powerful",
+ "contextscout": "fast",
+ "externalscout": "fast",
+ "context-retriever": "fast",
+ "context-manager": "fast",
+ "domain-analyzer": "powerful",
+ "agent-generator": "powerful",
+ "context-organizer": "powerful",
+ "workflow-designer": "powerful",
+ "command-creator": "powerful",
+ "frontend-specialist": "medium",
+ "devops-specialist": "medium",
+ "image-specialist": "fast",
+ "stage-orchestrator": "powerful",
+ "architecture-analyzer": "powerful",
+ "contract-manager": "powerful",
+ "adr-manager": "powerful",
+ "prioritization-engine": "powerful",
+ "story-mapper": "powerful",
+ "simple-responder": "fast",
+ "system-builder": "powerful",
+ "repo-manager": "powerful",
+ "technical-writer": "powerful",
+ "copywriter": "powerful",
+ "data-analyst": "medium",
+ "eval-runner": "fast"
+ }
+}
diff --git a/.opencode/skills/model-router/router.sh b/.opencode/skills/model-router/router.sh
new file mode 100644
index 00000000..6d76ca08
--- /dev/null
+++ b/.opencode/skills/model-router/router.sh
@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+#############################################################################
+# Model Router Skill Router
+# Routes to model-router.js with proper path resolution and command handling
+#############################################################################
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLI_SCRIPT="$SCRIPT_DIR/scripts/model-router.js"
+
+# Show help
+show_help() {
+ cat << 'HELP'
+π― Model Router Skill
+ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+Usage: router.sh [COMMAND] [OPTIONS]
+
+COMMANDS:
+ status Show current agentβmodel assignments and drift
+ apply [--dry-run] Sync model-tiers.json β agent frontmatter
+ tier Change a tier's model
+ assign Move an agent to a different tier
+ tiers List all tier definitions
+ unassigned Show agents not in assignments
+ help Show this help message
+
+EXAMPLES:
+ ./router.sh status
+ ./router.sh apply
+ ./router.sh apply --dry-run
+ ./router.sh tier fast lmstudio/phi-4-mini
+ ./router.sh assign contextscout medium
+ ./router.sh tiers
+ ./router.sh unassigned
+
+FEATURES:
+ β Tier-based model routing (fast/medium/powerful)
+ β Centralized config in model-tiers.json
+ β Apply model settings to agent frontmatter
+ β Drift detection between config and actual files
+ β One-command reconfiguration
+
+CONFIG FILE:
+ .opencode/skills/model-router/config/model-tiers.json
+
+For more info, see: .opencode/skills/model-router/SKILL.md
+HELP
+}
+
+# Check if CLI script exists
+if [ ! -f "$CLI_SCRIPT" ]; then
+ echo "β Error: model-router.js not found at $CLI_SCRIPT"
+ exit 1
+fi
+
+# Find project root
+find_project_root() {
+ local dir
+ dir="$(pwd)"
+ while [ "$dir" != "/" ]; do
+ if [ -d "$dir/.git" ] || [ -f "$dir/package.json" ]; then
+ echo "$dir"
+ return 0
+ fi
+ dir="$(dirname "$dir")"
+ done
+ pwd
+ return 1
+}
+
+# Handle help
+if [ "$1" = "help" ] || [ "$1" = "-h" ] || [ "$1" = "--help" ]; then
+ show_help
+ exit 0
+fi
+
+# If no arguments, show help
+if [ $# -eq 0 ]; then
+ show_help
+ exit 0
+fi
+
+PROJECT_ROOT="$(find_project_root)"
+
+# Run the model router CLI with all arguments
+cd "$PROJECT_ROOT" && node "$CLI_SCRIPT" "$@"
diff --git a/.opencode/skills/model-router/scripts/model-router.js b/.opencode/skills/model-router/scripts/model-router.js
new file mode 100644
index 00000000..2b884d57
--- /dev/null
+++ b/.opencode/skills/model-router/scripts/model-router.js
@@ -0,0 +1,445 @@
+#!/usr/bin/env node
+/**
+ * Model Router CLI
+ *
+ * Manages per-agent model assignments via tier-based configuration.
+ * Reads model-tiers.json, resolves agent paths from registry.json,
+ * and applies model/temperature/top_p to agent markdown frontmatter.
+ *
+ * Usage: node model-router.js [args...]
+ *
+ * Commands:
+ * status Show current agentβmodel assignments and drift
+ * apply Sync model-tiers.json β agent frontmatter
+ * tier Change a tier's model
+ * assign Move an agent to a different tier
+ * tiers List all tier definitions
+ * unassigned Show agents in registry not in assignments
+ * help Show help message
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// --- Path resolution ---
+
+function findProjectRoot() {
+ let dir = process.cwd();
+ while (dir !== path.dirname(dir)) {
+ if (fs.existsSync(path.join(dir, '.git')) || fs.existsSync(path.join(dir, 'package.json'))) {
+ return dir;
+ }
+ dir = path.dirname(dir);
+ }
+ return process.cwd();
+}
+
+const PROJECT_ROOT = findProjectRoot();
+const CONFIG_PATH = path.join(__dirname, '..', 'config', 'model-tiers.json');
+const REGISTRY_PATH = path.join(PROJECT_ROOT, 'registry.json');
+
+// --- Core functions ---
+
+function loadConfig() {
+ if (!fs.existsSync(CONFIG_PATH)) {
+ console.error(`β Config not found: ${CONFIG_PATH}`);
+ process.exit(1);
+ }
+ return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+}
+
+function saveConfig(config) {
+ fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n');
+}
+
+function loadRegistry() {
+ if (!fs.existsSync(REGISTRY_PATH)) {
+ console.error(`β Registry not found: ${REGISTRY_PATH}`);
+ process.exit(1);
+ }
+ return JSON.parse(fs.readFileSync(REGISTRY_PATH, 'utf-8'));
+}
+
+/** Build a map of agent-id β absolute-path from registry */
+function buildAgentPathMap(registry) {
+ const map = {};
+ for (const category of Object.keys(registry.components)) {
+ for (const comp of registry.components[category]) {
+ if (comp.type === 'agent' || comp.type === 'subagent') {
+ map[comp.id] = path.join(PROJECT_ROOT, comp.path);
+ }
+ }
+ }
+ return map;
+}
+
+/** Parse YAML frontmatter from a markdown file, return { frontmatter, body } */
+function parseFrontmatter(filePath) {
+ if (!fs.existsSync(filePath)) return null;
+ const content = fs.readFileSync(filePath, 'utf-8');
+ const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+ if (!match) return { frontmatter: {}, body: content };
+ const raw = match[1];
+ const body = match[2];
+ const frontmatter = {};
+ for (const line of raw.split('\n')) {
+ const kv = line.match(/^(\w[\w-]*):\s*(.*)$/);
+ if (kv) {
+ const key = kv[1];
+ let value = kv[2].trim();
+ // Parse simple YAML values
+ if (value === 'true') value = true;
+ else if (value === 'false') value = false;
+ else if (value === 'null') value = null;
+ else if (/^-?\d+(\.\d+)?$/.test(value)) value = parseFloat(value);
+ frontmatter[key] = value;
+ }
+ }
+ return { frontmatter, body };
+}
+
+/** Write frontmatter updates back to a markdown file, preserving complex YAML */
+function writeFrontmatter(filePath, updates) {
+ const content = fs.readFileSync(filePath, 'utf-8');
+ const match = content.match(/^(---\n)([\s\S]*?)(\n---\n)([\s\S]*)$/);
+ if (!match) {
+ console.error(` β οΈ No frontmatter found in ${filePath}, skipping`);
+ return false;
+ }
+
+ const prefix = match[1];
+ let rawYaml = match[2];
+ const suffix = match[3];
+ const fileBody = match[4];
+
+ // Apply updates to the raw YAML by targeting specific keys
+ for (const [key, value] of Object.entries(updates)) {
+ const valueStr = typeof value === 'string' ? value : String(value);
+
+ // Try to replace existing key
+ const regex = new RegExp(`^(${key}:\\s*)(.*)$`, 'm');
+ if (regex.test(rawYaml)) {
+ rawYaml = rawYaml.replace(regex, `$1${valueStr}`);
+ } else {
+ // Add new key after the last simple key (before nested blocks)
+ const lines = rawYaml.split('\n');
+ let insertIdx = lines.length;
+ // Find the last line that's a simple key-value (not indented)
+ for (let i = lines.length - 1; i >= 0; i--) {
+ if (/^\w[\w-]*:\s*.+/.test(lines[i])) {
+ insertIdx = i + 1;
+ break;
+ }
+ }
+ lines.splice(insertIdx, 0, `${key}: ${valueStr}`);
+ rawYaml = lines.join('\n');
+ }
+ }
+
+ fs.writeFileSync(filePath, prefix + rawYaml + suffix + fileBody);
+ return true;
+}
+
+// --- Commands ---
+
+function cmdStatus() {
+ const config = loadConfig();
+ const registry = loadRegistry();
+ const agentPaths = buildAgentPathMap(registry);
+
+ console.log('β'.repeat(72));
+ console.log('π― Model Router β Current Assignments');
+ console.log('β'.repeat(72));
+
+ // Tier summary
+ console.log('\nπ¦ Tier Definitions:');
+ for (const [tierName, tier] of Object.entries(config.tiers)) {
+ const agentCount = Object.entries(config.assignments).filter(([, t]) => t === tierName).length;
+ console.log(` ${tierName.padEnd(12)} β ${tier.model.padEnd(40)} (${agentCount} agents)`);
+ console.log(` temp: ${tier.temperature}, top_p: ${tier.top_p}`);
+ }
+
+ // Per-agent assignments with drift detection
+ console.log('\nπ Agent Assignments:');
+ const driftFound = [];
+
+ const sortedAssignments = Object.entries(config.assignments).sort(([, a], [, b]) => a.localeCompare(b));
+ let currentTier = '';
+
+ for (const [agentId, tierName] of sortedAssignments) {
+ if (tierName !== currentTier) {
+ currentTier = tierName;
+ const tier = config.tiers[tierName];
+ if (tier) {
+ console.log(`\n ββ ${tierName.toUpperCase()} (${tier.model}) ββ`);
+ }
+ }
+
+ const filePath = agentPaths[agentId];
+ let currentModel = '(not found)';
+ let drift = false;
+
+ if (filePath) {
+ const parsed = parseFrontmatter(filePath);
+ if (parsed && parsed.frontmatter.model) {
+ currentModel = parsed.frontmatter.model;
+ const expectedModel = config.tiers[tierName]?.model;
+ if (expectedModel && currentModel !== expectedModel) {
+ drift = true;
+ driftFound.push(agentId);
+ }
+ } else if (parsed) {
+ currentModel = '(inherited/default)';
+ }
+ }
+
+ const driftMarker = drift ? ' β οΈ DRIFT' : '';
+ const okMarker = !drift && currentModel !== '(not found)' && currentModel !== '(inherited/default)' ? ' β
' : '';
+ console.log(` ${agentId.padEnd(24)} ${currentModel.padEnd(42)}${driftMarker}${okMarker}`);
+ }
+
+ if (driftFound.length > 0) {
+ console.log(`\nβ οΈ Drift detected for ${driftFound.length} agent(s). Run 'apply' to sync.`);
+ } else {
+ console.log('\nβ
All agents in sync with tier definitions.');
+ }
+}
+
+function cmdApply(dryRun) {
+ const config = loadConfig();
+ const registry = loadRegistry();
+ const agentPaths = buildAgentPathMap(registry);
+
+ console.log('β'.repeat(72));
+ if (dryRun) {
+ console.log('π Model Router β DRY RUN (no files will be modified)');
+ } else {
+ console.log('π Model Router β Applying tier assignments to agent files');
+ }
+ console.log('β'.repeat(72));
+
+ let applied = 0;
+ let skipped = 0;
+ let errors = 0;
+
+ for (const [agentId, tierName] of Object.entries(config.assignments)) {
+ const tier = config.tiers[tierName];
+ if (!tier) {
+ console.log(` β ${agentId}: Unknown tier '${tierName}'`);
+ errors++;
+ continue;
+ }
+
+ const filePath = agentPaths[agentId];
+ if (!filePath) {
+ console.log(` βοΈ ${agentId}: Not found in registry, skipping`);
+ skipped++;
+ continue;
+ }
+
+ if (!fs.existsSync(filePath)) {
+ console.log(` β ${agentId}: File not found at ${filePath}`);
+ errors++;
+ continue;
+ }
+
+ const updates = {
+ model: tier.model,
+ temperature: tier.temperature,
+ top_p: tier.top_p,
+ };
+
+ if (dryRun) {
+ const parsed = parseFrontmatter(filePath);
+ const currentModel = parsed?.frontmatter.model || '(none)';
+ const changed = currentModel !== tier.model;
+ console.log(` ${changed ? 'π' : ' '} ${agentId}: ${currentModel} β ${tier.model} (temp: ${tier.temperature}, top_p: ${tier.top_p})`);
+ applied++;
+ } else {
+ const success = writeFrontmatter(filePath, updates);
+ if (success) {
+ console.log(` β
${agentId}: model=${tier.model}, temperature=${tier.temperature}, top_p=${tier.top_p}`);
+ applied++;
+ } else {
+ console.log(` β ${agentId}: Failed to update frontmatter`);
+ errors++;
+ }
+ }
+ }
+
+ console.log('\n' + 'β'.repeat(72));
+ if (dryRun) {
+ console.log(`Preview: ${applied} would be updated, ${skipped} skipped, ${errors} errors`);
+ } else {
+ console.log(`Applied: ${applied} updated, ${skipped} skipped, ${errors} errors`);
+ }
+}
+
+function cmdTier(tierName, modelId) {
+ const config = loadConfig();
+
+ if (!config.tiers[tierName]) {
+ console.error(`β Unknown tier: '${tierName}'`);
+ console.log(`Available tiers: ${Object.keys(config.tiers).join(', ')}`);
+ process.exit(1);
+ }
+
+ const oldModel = config.tiers[tierName].model;
+ config.tiers[tierName].model = modelId;
+ saveConfig(config);
+
+ console.log(`β
Updated tier '${tierName}': ${oldModel} β ${modelId}`);
+ console.log(`\nRun 'apply' to propagate this change to all agents in the '${tierName}' tier.`);
+}
+
+function cmdAssign(agentId, tierName) {
+ const config = loadConfig();
+
+ if (!config.tiers[tierName]) {
+ console.error(`β Unknown tier: '${tierName}'`);
+ console.log(`Available tiers: ${Object.keys(config.tiers).join(', ')}`);
+ process.exit(1);
+ }
+
+ const oldTier = config.assignments[agentId] || '(unassigned)';
+ config.assignments[agentId] = tierName;
+ saveConfig(config);
+
+ console.log(`β
Assigned '${agentId}' to tier '${tierName}': ${oldTier} β ${tierName}`);
+ console.log(`\nRun 'apply' to propagate this change to the agent's frontmatter.`);
+}
+
+function cmdTiers() {
+ const config = loadConfig();
+
+ console.log('β'.repeat(72));
+ console.log('π¦ Model Tier Definitions');
+ console.log('β'.repeat(72));
+
+ for (const [tierName, tier] of Object.entries(config.tiers)) {
+ const agentCount = Object.entries(config.assignments).filter(([, t]) => t === tierName).length;
+ console.log(`\n ${tierName.toUpperCase()}`);
+ console.log(` Model: ${tier.model}`);
+ console.log(` Temperature: ${tier.temperature}`);
+ console.log(` Top-P: ${tier.top_p}`);
+ console.log(` Description: ${tier.description}`);
+ console.log(` Agents: ${agentCount}`);
+ }
+
+ console.log('\n' + 'β'.repeat(72));
+ console.log(`Defaults: primary_agents β '${config.defaults.primary_agents}', subagents β '${config.defaults.subagents}'`);
+}
+
+function cmdUnassigned() {
+ const config = loadConfig();
+ const registry = loadRegistry();
+ const agentPaths = buildAgentPathMap(registry);
+
+ const assignedIds = new Set(Object.keys(config.assignments));
+ const unassigned = [];
+
+ for (const [id, filePath] of Object.entries(agentPaths)) {
+ if (!assignedIds.has(id)) {
+ const parsed = parseFrontmatter(filePath);
+ unassigned.push({
+ id,
+ name: parsed?.frontmatter.name || id,
+ type: parsed?.frontmatter.mode || 'unknown',
+ });
+ }
+ }
+
+ console.log('β'.repeat(72));
+ console.log('π Agents Not in model-tiers.json Assignments');
+ console.log('β'.repeat(72));
+
+ if (unassigned.length === 0) {
+ console.log('\nβ
All agents in registry are assigned to a tier.');
+ return;
+ }
+
+ for (const agent of unassigned) {
+ console.log(` ${agent.id.padEnd(24)} (${agent.type}) ${agent.name}`);
+ }
+
+ console.log(`\n${unassigned.length} unassigned agent(s). Add them to 'assignments' in model-tiers.json.`);
+}
+
+// --- Main router ---
+
+function main() {
+ const args = process.argv.slice(2);
+
+ if (args.length === 0 || args[0] === 'help' || args[0] === '-h' || args[0] === '--help') {
+ console.log(`
+π― Model Router CLI
+ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+Usage: model-router.js [args...]
+
+COMMANDS:
+ status Show current agentβmodel assignments and drift
+ apply [--dry-run] Sync model-tiers.json β agent frontmatter
+ tier Change a tier's model
+ assign Move an agent to a different tier
+ tiers List all tier definitions
+ unassigned Show agents not in assignments
+ help Show this help message
+
+EXAMPLES:
+ node model-router.js status
+ node model-router.js apply
+ node model-router.js apply --dry-run
+ node model-router.js tier fast lmstudio/phi-4-mini
+ node model-router.js assign contextscout medium
+ node model-router.js tiers
+ node model-router.js unassigned
+
+CONFIG FILE: .opencode/skills/model-router/config/model-tiers.json
+`);
+ return;
+ }
+
+ const command = args[0];
+
+ switch (command) {
+ case 'status':
+ cmdStatus();
+ break;
+
+ case 'apply':
+ cmdApply(args.includes('--dry-run'));
+ break;
+
+ case 'tier':
+ if (args.length < 3) {
+ console.error('β Usage: model-router.js tier ');
+ process.exit(1);
+ }
+ cmdTier(args[1], args[2]);
+ break;
+
+ case 'assign':
+ if (args.length < 3) {
+ console.error('β Usage: model-router.js assign ');
+ process.exit(1);
+ }
+ cmdAssign(args[1], args[2]);
+ break;
+
+ case 'tiers':
+ cmdTiers();
+ break;
+
+ case 'unassigned':
+ cmdUnassigned();
+ break;
+
+ default:
+ console.error(`β Unknown command: ${command}`);
+ console.log("Run 'help' for available commands.");
+ process.exit(1);
+ }
+}
+
+main();
diff --git a/README.md b/README.md
index 77231544..86cfea7f 100644
--- a/README.md
+++ b/README.md
@@ -582,9 +582,53 @@ Approve? [y/n]
- You want complex agents to use smarter models (e.g., Opus/GPT-5)
- You want to test different models for different tasks
-**How to configure:**
+#### Option 1: Model Router (Recommended)
-Edit agent files directly:
+The **Model Router** skill lets you configure per-agent models from a single file β change a tier, re-apply, and all agents in that tier update instantly.
+
+**Quick start:**
+
+```bash
+# See all current assignments
+node .opencode/skills/model-router/scripts/model-router.js status
+
+# Preview changes (no files modified)
+node .opencode/skills/model-router/scripts/model-router.js apply --dry-run
+
+# Apply model settings to all agent frontmatter
+node .opencode/skills/model-router/scripts/model-router.js apply
+```
+
+**How it works:**
+
+Agents are grouped into **tiers** β each tier defines a model, temperature, and top_p. You assign agents to tiers, then `apply` writes the settings to each agent's frontmatter.
+
+| Tier | Purpose | Example Model | Agents |
+|------|---------|---------------|--------|
+| **fast** | Simple tasks: search, context lookup | `lmstudio/gpt-oss-20b` | ContextScout, ExternalScout, etc. |
+| **medium** | Coding, testing, medium tasks | `lmstudio/qwen3-coder-30b` | CoderAgent, TestEngineer, etc. |
+| **powerful** | Planning, orchestration, architecture | `anthropic/claude-sonnet-4-20250514` | OpenAgent, OpenCoder, etc. |
+
+**Reconfigure in one command:**
+
+```bash
+# Change the "fast" tier to a new model
+node .opencode/skills/model-router/scripts/model-router.js tier fast lmstudio/phi-4-mini
+
+# Move a single agent to a different tier
+node .opencode/skills/model-router/scripts/model-router.js assign contextscout medium
+
+# Apply the changes
+node .opencode/skills/model-router/scripts/model-router.js apply
+```
+
+**Config file:** `.opencode/skills/model-router/config/model-tiers.json` β edit directly to add new tiers, change defaults, or bulk-edit assignments.
+
+**Slash command:** `/model-router` in OpenCode β runs `status` by default.
+
+#### Option 2: Edit Agent Files Directly
+
+Edit individual agent files:
```bash
nano .opencode/agent/core/opencoder.md # local project install
# Or: nano ~/.config/opencode/agent/core/opencoder.md # global install
diff --git a/registry.json b/registry.json
index f56c2012..c861dccd 100644
--- a/registry.json
+++ b/registry.json
@@ -651,6 +651,23 @@
"refactoring"
],
"category": "standard"
+ },
+ {
+ "id": "model-router",
+ "name": "Model Router",
+ "type": "command",
+ "path": ".opencode/command/model-router.md",
+ "description": "Configure per-agent model routing β view, apply, and manage tier-based model assignments",
+ "tags": [
+ "models",
+ "routing",
+ "configuration",
+ "agents"
+ ],
+ "dependencies": [
+ "skill:model-router"
+ ],
+ "category": "standard"
}
],
"tools": [
@@ -786,6 +803,28 @@
".opencode/skills/context-manager/SKILL.md",
".opencode/skills/context-manager/router.sh"
]
+ },
+ {
+ "id": "model-router",
+ "name": "Model Router",
+ "type": "skill",
+ "path": ".opencode/skills/model-router/SKILL.md",
+ "description": "Per-agent model routing with tier-based configuration β assign models to agents by role, reconfigure from one place",
+ "tags": [
+ "models",
+ "routing",
+ "configuration",
+ "agents",
+ "tiers"
+ ],
+ "dependencies": [],
+ "category": "essential",
+ "files": [
+ ".opencode/skills/model-router/SKILL.md",
+ ".opencode/skills/model-router/router.sh",
+ ".opencode/skills/model-router/config/model-tiers.json",
+ ".opencode/skills/model-router/scripts/model-router.js"
+ ]
}
],
"contexts": [