From 426def40f1cdd8aefb61674c663e9ee8f89ae8d5 Mon Sep 17 00:00:00 2001
From: bendtherules <abhasbhattacharya2@gmail.com>
Date: Mon, 23 Mar 2026 12:17:29 +0530
Subject: [PATCH] docs: enhance AGENTS.md

---
 AGENTS.md | 56 +++++++++++++++++++++++++++----------------------------
 1 file changed, 27 insertions(+), 29 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index e0322dc..7ad192e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,14 +2,14 @@
 
 ## Project Overview
 
-opencode-multi-model is a Bun/TypeScript project that provides multi-model tmux session management for AI coding assistants. Works as an OpenCode plugin, standalone CLI, and project tool.
+opencode-multi-model is a Bun/TypeScript project that provides multi-model tmux session management for AI coding assistants. It allows running multiple AI models simultaneously in isolated tmux windows with separate git worktrees.
 
-Key features:
-- Launch multiple AI models in isolated tmux sessions
-- Git worktree management for each model session
-- Archive tag creation for session state preservation
-- Supports both OpenCode and Kilo binaries
-- Available as CLI tool, OpenCode plugin, or project-level import
+Available as three integration modes:
+- **OpenCode Plugin**: Loaded via `opencode.json` plugin array
+- **Standalone CLI**: Install globally and run `opencode-multi-model open <session> -m <models...>`
+- **Project Tool**: Import core functions from `"opencode-multi-model/core"` for project-level commands (used during development).
+
+Requires: tmux, git, opencode or kilo binary, Bun runtime.
 
 ## Build, Lint, and Test Commands
 
@@ -20,6 +20,9 @@ bun install
 # Build for production
 bun run build
 
+# Run tests
+bun test
+
 # Run tests with coverage (HTML report in ./coverage)
 bun run coverage
 # Run a specific test by name
@@ -76,13 +79,7 @@ bun run typecheck && bun run lint
 
 - Use `import type` for type-only imports
 - Group imports: external packages, internal modules, types
-- Example:
-  ```typescript
-  import * as fs from "node:fs";
-  import chalk from "chalk";
-  import type { MultiModelOptions } from "../types";
-  import { runCommand } from "./utils";
-  ```
+- Biome automatically organizes imports
 
 ### JSDoc Comments
 
@@ -92,17 +89,17 @@ bun run typecheck && bun run lint
 
 ### Error Handling
 
-- Return result objects (e.g., `MultiModelResult`, `CommandResult`) with `success: boolean`
+- Return result objects (e.g., `MultiModelResult`, `CloseSessionResult`, `CleanupResult`) with `success: boolean`
 - Include descriptive error messages prefixed with `Error:`
-- Provide actionable error messages (e.g., suggest valid models on failure)
+- Provide actionable error messages (e.g., suggest valid models on invalid model name)
 - Use `chalk` for colored terminal output (red for errors, dim for secondary info, bold for primary info)
 
 ### Shell Commands
 
 - Use `Bun.$` template tag for shell commands
-- Always use `quiet().nothrow()` to capture output
-- Wrap command execution in `runCommand()` utility
-- Never use single-character variable names
+- Always use `quiet().nothrow()` to capture output without throwing
+- Wrap command execution in `runCommand()` utility from `core/utils.ts`
+- Use `shellQuote()` for user-provided values in shell commands
 
 ### Testing
 
@@ -112,30 +109,30 @@ bun run typecheck && bun run lint
 - Group tests with `describe()` blocks
 - Test file naming: `*.test.ts` in `tests/` directory
 
-### Project Structure
+## Project Structure
 
 ```
 src/
 ├── index.ts          # Plugin entry point (default export)
-├── cli.ts            # CLI entry point
+├── cli.ts            # CLI entry point (commander setup)
 ├── types.ts          # All TypeScript interfaces/types
 ├── core/
 │   ├── index.ts      # Core exports
 │   ├── open.ts       # Session launch logic
 │   ├── close.ts      # Session close logic
 │   ├── cleanup.ts    # Archive tag cleanup logic
-│   └── utils.ts      # Shared utilities
+│   └── utils.ts      # Shared utilities (runCommand, shellQuote, etc.)
 └── tools/
     ├── open.ts       # OpenCode tool definition
     ├── close.ts      # CloseCode tool definition
     └── cleanup.ts    # Cleanup tool definition
 tests/
-├── open.test.ts
-├── close.test.ts
-├── cleanup.test.ts
-├── open_error.test.ts
-├── close_error.test.ts
-└── utils.test.ts
+├── open.test.ts         # Open command tests
+├── close.test.ts        # Close command tests
+├── cleanup.test.ts      # Cleanup command tests
+├── open_error.test.ts   # Open error handling tests
+├── close_error.test.ts  # Close error handling tests
+└── utils.test.ts        # Utility function tests
 ```
 
 ### Git Branch and Tag Naming
@@ -149,4 +146,5 @@ tests/
 - Tmux session names use raw input; git branches/paths use sanitized names
 - Window names must be unique; collisions get numeric suffixes (e.g., `gpt-5-2`, `gpt-5-2-2`)
 - Window names are truncated to 24 characters to fit tmux limits
-- Worktree paths are checked for existence before creation to avoid conflicts
\ No newline at end of file
+- Worktree paths are checked for existence before creation to avoid conflicts
+- Archive tags preserve branch state before deletion for recovery
\ No newline at end of file