From 1a162a2447c2e22cd5a3f7b1a1223ee356abfb6d Mon Sep 17 00:00:00 2001
From: ditus <ditus@kapuscinski.pl>
Date: Mon, 10 Nov 2025 12:48:11 +0100
Subject: [PATCH] Add comprehensive guide for using agents with different
 projects

- Added 4 integration methods (copy, global, project-specific, selective)
- Included step-by-step instructions for each method
- Added project-specific customization ideas
- Included troubleshooting and best practices
- Added examples for web development, data science, and DevOps projects
---
 README.md | 191 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 191 insertions(+)

diff --git a/README.md b/README.md
index a004430..4f226b0 100644
--- a/README.md
+++ b/README.md
@@ -197,6 +197,197 @@ You are a specialized agent for...
 - [Available Models](https://opencode.ai/docs/models/)
 - [Permissions Documentation](https://opencode.ai/docs/permissions/)
 
+## Using with Different Projects
+
+This OpenCode agents project can be used with any existing project. Here are several methods to integrate the agents:
+
+### Method 1: Copy Configuration to Existing Project
+
+#### Step 1: Copy Agent Files
+```bash
+# Navigate to your existing project
+cd /path/to/your/project
+
+# Copy OpenCode configuration
+cp -r /path/to/nano-opencode-agents/.opencode ./
+cp /path/to/nano-opencode-agents/opencode.json ./
+cp -r /path/to/nano-opencode-agents/prompts ./
+```
+
+#### Step 2: Verify Structure
+Your project should now have:
+```
+your-project/
+├── .opencode/
+│   └── agent/
+│       └── docs-writer.md
+├── prompts/
+│   ├── build.txt
+│   ├── cleanup.txt
+│   ├── security.txt
+│   └── review.txt
+├── opencode.json
+└── (your existing project files)
+```
+
+#### Step 3: Start OpenCode
+```bash
+# Navigate to your project
+cd /path/to/your/project
+
+# Start OpenCode
+opencode
+```
+
+### Method 2: Global Configuration
+
+#### Step 1: Install Globally
+```bash
+# Copy to global OpenCode config directory
+mkdir -p ~/.config/opencode/agent
+cp /path/to/nano-opencode-agents/.opencode/agent/* ~/.config/opencode/agent/
+```
+
+#### Step 2: Create Global opencode.json
+```bash
+# Create global config file
+cat > ~/.config/opencode/config.json << 'EOF'
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "cleanup": {
+      "description": "Repository cleanup and maintenance",
+      "mode": "subagent",
+      "prompt": "{file:~/.config/opencode/prompts/cleanup.txt}",
+      "tools": { "write": true, "bash": true }
+    }
+    // ... add other agents as needed
+  }
+}
+EOF
+```
+
+#### Step 3: Use in Any Project
+```bash
+cd /path/to/any/project
+opencode  # Will load global agents
+```
+
+### Method 3: Project-Specific Customization
+
+#### Step 1: Initialize Project
+```bash
+cd /path/to/your/project
+
+# Create OpenCode structure
+mkdir -p .opencode/agent prompts
+```
+
+#### Step 2: Copy Base Configuration
+```bash
+# Copy agent configurations
+cp /path/to/nano-opencode-agents/opencode.json ./
+cp -r /path/to/nano-opencode-agents/.opencode/agent/* .opencode/agent/
+cp -r /path/to/nano-opencode-agents/prompts/* prompts/
+```
+
+#### Step 3: Customize for Your Project
+Edit `opencode.json` to match your project needs:
+- Adjust models based on your preferences
+- Modify permissions for your workflow
+- Add project-specific agents
+
+### Method 4: Selective Agent Installation
+
+#### Step 1: Choose Specific Agents
+```bash
+# Only copy cleanup agent
+cp /path/to/nano-opencode-agents/.opencode/agent/docs-writer.md .opencode/agent/
+cp /path/to/nano-opencode-agents/prompts/cleanup.txt prompts/
+```
+
+#### Step 2: Create Minimal opencode.json
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "cleanup": {
+      "description": "Repository cleanup and maintenance",
+      "mode": "subagent",
+      "prompt": "{file:./prompts/cleanup.txt}",
+      "tools": { "write": true, "bash": true }
+    }
+  }
+}
+```
+
+### Usage Examples
+
+#### Once Configured, Use Agents Like This:
+```bash
+# Start OpenCode in your project
+opencode
+
+# Switch between primary agents with Tab
+# Use subagents with @ mentions
+
+@cleanup help me organize this project
+@security audit my authentication code
+@docs-writer create API documentation
+@review review my recent changes
+```
+
+### Project-Specific Customization Ideas
+
+#### For Web Development Projects:
+- Add `frontend` agent for UI/UX work
+- Add `backend` agent for server-side logic
+- Add `testing` agent for test automation
+
+#### For Data Science Projects:
+- Add `analysis` agent for data exploration
+- Add `visualization` agent for charts/plots
+- Add `ml` agent for machine learning tasks
+
+#### For DevOps Projects:
+- Add `deployment` agent for CI/CD
+- Add `monitoring` agent for observability
+- Add `infrastructure` agent for cloud resources
+
+### Best Practices for Integration
+
+#### Configuration Management:
+1. **Start small** - add agents as needed
+2. **Test locally** before committing
+3. **Version control** your agent configurations
+4. **Document customizations** for your team
+
+#### Permission Management:
+1. **Restrict dangerous operations** with `ask` permissions
+2. **Allow read operations** freely
+3. **Customize per project type**
+4. **Review regularly** for security
+
+#### Performance Optimization:
+1. **Use fast models** for simple tasks
+2. **Reserve powerful models** for complex work
+3. **Consider token costs** and usage
+4. **Cache frequently used prompts**
+
+### Troubleshooting
+
+#### Common Issues:
+- **Agents not showing**: Check file paths in opencode.json
+- **Permission errors**: Verify tool configurations
+- **Model not found**: Check model names and availability
+- **Prompt not loading**: Verify file paths exist
+
+#### Debug Steps:
+1. Check OpenCode logs for errors
+2. Validate JSON syntax
+3. Test with minimal configuration
+4. Verify file permissions
+
 ## Contributing
 
 To contribute new agents or improvements: