real life totally configurabl ai subasians

3 files changed, 187 insertions, 3 deletions

diff --git a/packages/web/astro.config.mjs b/packages/web/astro.config.mjs
index 4f2fc98ef..e3f6a493e 100644
--- a/packages/web/astro.config.mjs
+++ b/packages/web/astro.config.mjs
@@ -66,6 +66,7 @@ export default defineConfig({
         "docs/ide",
         "docs/share",
         "docs/modes",
+        "docs/agents",
         "docs/rules",
         "docs/config",
         "docs/models",
diff --git a/packages/web/src/content/docs/docs/agents.mdx b/packages/web/src/content/docs/docs/agents.mdx
new file mode 100644
index 000000000..b7a90d68b
--- /dev/null
+++ b/packages/web/src/content/docs/docs/agents.mdx
@@ -0,0 +1,158 @@
+---
+title: Agents
+description: Configure and use specialized agents in opencode.
+---
+
+Agents are specialized AI assistants that can be configured for specific tasks and workflows. They allow you to create focused tools with custom prompts, models, and tool access.
+
+## Built-in Agents
+
+opencode comes with a built-in `general` agent:
+
+- **general** - General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. Use this when searching for keywords or files and you're not confident you'll find the right match in the first few tries.
+
+## Configuration
+
+Agents can be configured in your `opencode.json` config file or as markdown files.
+
+### JSON Configuration
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "code-reviewer": {
+      "description": "Reviews code for best practices and potential issues",
+      "model": "anthropic/claude-sonnet-4-20250514",
+      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
+      "tools": {
+        "write": false,
+        "edit": false
+      }
+    },
+    "test-writer": {
+      "description": "Specialized agent for writing comprehensive tests",
+      "prompt": "You are a test writing specialist. Write thorough, maintainable tests.",
+      "tools": {
+        "bash": true,
+        "read": true,
+        "write": true
+      }
+    }
+  }
+}
+```
+
+### Markdown Configuration
+
+You can also define agents using markdown files. Place them in:
+
+- Global: `~/.config/opencode/agent/`
+- Project: `.opencode/agent/`
+
+```markdown title="~/.config/opencode/agent/code-reviewer.md"
+---
+description: Reviews code for best practices and potential issues
+model: anthropic/claude-sonnet-4-20250514
+tools:
+  write: false
+  edit: false
+---
+
+You are a code reviewer with expertise in security, performance, and maintainability.
+
+Focus on:
+
+- Security vulnerabilities
+- Performance bottlenecks
+- Code maintainability
+- Best practices adherence
+```
+
+## Agent Properties
+
+### Required
+
+- **description** - Brief description of what the agent does and when to use it
+
+### Optional
+
+- **model** - Specific model to use (defaults to your configured model)
+- **prompt** - Custom system prompt for the agent
+- **tools** - Object specifying which tools the agent can access (true/false for each tool)
+- **disable** - Set to true to disable the agent
+
+## Tool Access
+
+By default, agents inherit the same tool access as the main assistant. You can restrict or enable specific tools:
+
+```json
+{
+  "agent": {
+    "readonly-agent": {
+      "description": "Read-only agent for analysis",
+      "tools": {
+        "write": false,
+        "edit": false,
+        "bash": false
+      }
+    }
+  }
+}
+```
+
+Common tools you might want to control:
+
+- `write` - Create new files
+- `edit` - Modify existing files
+- `bash` - Execute shell commands
+- `read` - Read files
+- `glob` - Search for files
+- `grep` - Search file contents
+
+## Using Agents
+
+Agents are automatically available through the Task tool when configured. The main assistant will use them for specialized tasks based on their descriptions.
+
+## Best Practices
+
+1. **Clear descriptions** - Write specific descriptions that help the main assistant know when to use each agent
+2. **Focused prompts** - Keep agent prompts focused on their specific role
+3. **Appropriate tool access** - Only give agents the tools they need for their tasks
+4. **Consistent naming** - Use descriptive, consistent names for your agents
+5. **Project-specific agents** - Use `.opencode/agent/` for project-specific workflows
+
+## Examples
+
+### Documentation Agent
+
+```json
+{
+  "agent": {
+    "docs-writer": {
+      "description": "Writes and maintains project documentation",
+      "prompt": "You are a technical writer. Create clear, comprehensive documentation.",
+      "tools": {
+        "bash": false
+      }
+    }
+  }
+}
+```
+
+### Security Auditor
+
+```json
+{
+  "agent": {
+    "security-auditor": {
+      "description": "Performs security audits and identifies vulnerabilities",
+      "prompt": "You are a security expert. Focus on identifying potential security issues.",
+      "tools": {
+        "write": false,
+        "edit": false
+      }
+    }
+  }
+}
+```
diff --git a/packages/web/src/content/docs/docs/config.mdx b/packages/web/src/content/docs/docs/config.mdx
index 77026c417..8b9df9ce1 100644
--- a/packages/web/src/content/docs/docs/config.mdx
+++ b/packages/web/src/content/docs/docs/config.mdx
@@ -50,9 +50,9 @@ opencode comes with two built-in modes: _build_, the default with all tools enab
 {
   "$schema": "https://opencode.ai/config.json",
   "mode": {
-    "build": { },
-    "plan": { },
-    "my-custom-mode": { }
+    "build": {},
+    "plan": {},
+    "my-custom-mode": {}
   }
 }
 ```
@@ -181,6 +181,31 @@ about rules here](/docs/rules).
 
 ---
 
+### Agents
+
+You can configure specialized agents for specific tasks through the `agent` option.
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "code-reviewer": {
+      "description": "Reviews code for best practices and potential issues",
+      "model": "anthropic/claude-sonnet-4-20250514",
+      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
+      "tools": {
+        "write": false,
+        "edit": false
+      }
+    }
+  }
+}
+```
+
+You can also define agents using markdown files in `~/.config/opencode/agent/` or `.opencode/agent/`. [Learn more here](/docs/agents).
+
+---
+
 ### Disabled providers
 
 You can disable providers that are loaded automatically through the `disabled_providers` option. This is useful when you want to prevent certain providers from being loaded even if their credentials are available.