nano-opencode-agents/README.md

# Nano - OpenCode Agents Project

A minimal project structure for creating and managing custom OpenCode agents.

## Project Structure

```
nano/
├── opencode.json           # Main agent configuration
├── .opencode/agent/        # Custom agents (markdown format)
│   └── docs-writer.md     # Documentation writer agent
├── prompts/               # Agent prompt files
│   ├── build.txt          # Build agent prompt
│   ├── cleanup.txt        # Cleanup agent prompt
│   ├── security.txt       # Security auditor prompt
│   └── review.txt        # Code review prompt
└── README.md             # This file
```

## Available Agents

### Primary Agents
- **build**: Full development agent with all tools enabled
- **plan**: Analysis and planning agent (read-only)

### Subagents
- **@cleanup**: Repository cleanup and maintenance
- **@security**: Security auditing and vulnerability assessment
- **@docs-writer**: Technical writing and documentation
- **@review**: Code review and quality assessment

## Usage

### Switching Between Primary Agents
Use `Tab` key to cycle between `build` and `plan` agents.

### Using Subagents
Mention subagents with `@` in your messages:
```
@cleanup help me clean up this repository
@security audit this code for vulnerabilities
@docs-writer create documentation for this API
@review review my recent changes
```

## Configuration

### Adding New Agents

1. **JSON Configuration**: Edit `opencode.json`
2. **Markdown Files**: Add new `.md` files to `.opencode/agent/`
3. **Prompt Files**: Add corresponding prompts to `prompts/`

### Agent Types
- **Primary**: Main agents you interact with directly
- **Subagent**: Specialized agents invoked for specific tasks

## Customization

### Models
Each agent can use different models optimized for their tasks:
- Fast models for planning and analysis
- Capable models for implementation
- Specialized models for specific domains

### Tools & Permissions
Configure which tools each agent can access:
- File operations (read, write, edit)
- System commands (bash)
- Web access (webfetch)
- Custom permissions and restrictions

### Temperature
Control creativity vs. determinism:
- 0.0-0.2: Focused, analytical tasks
- 0.3-0.5: Balanced development work
- 0.6-1.0: Creative and exploratory tasks

## Examples

### Repository Cleanup
```bash
@cleanup analyze this repository and suggest cleanup
```

### Security Audit
```bash
@security check for security vulnerabilities in this code
```

### Documentation Generation
```bash
@docs-writer create API documentation for this module
```

### Code Review
```bash
@review review my recent commits for best practices
```

## Development

### Creating New Agents
Use OpenCode CLI to create new agents:
```bash
opencode agent create
```

### Testing Agents
Test agents in isolation before integrating:
```bash
@new-agent test this functionality
```

### Agent Configuration Examples

#### JSON Configuration
```json
{
  "agent": {
    "my-agent": {
      "description": "Custom agent for specific task",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.3,
      "prompt": "{file:./prompts/my-agent.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": false
      }
    }
  }
}
```

#### Markdown Configuration
```markdown
---
description: Custom agent for specific task
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.3
tools:
  write: true
  edit: true
  bash: false
---

You are a specialized agent for...
```

## Agent Permissions

### Permission Levels
- **allow**: Grant unrestricted access
- **ask**: Prompt for confirmation before action
- **deny**: Completely disable the tool

### Example Permissions
```json
{
  "permission": {
    "bash": {
      "git push": "ask",
      "git status": "allow",
      "*": "deny"
    },
    "edit": "ask",
    "webfetch": "allow"
  }
}
```

## Best Practices

### Agent Design
- Keep agents focused on specific tasks
- Use appropriate temperature settings
- Configure minimal necessary permissions
- Write clear, specific prompts

### Security
- Restrict dangerous operations with permissions
- Use `ask` for potentially destructive actions
- Review agent configurations regularly

### Performance
- Use faster models for simple tasks
- Reserve powerful models for complex work
- Consider token usage and costs

## Resources

- [OpenCode Documentation](https://opencode.ai/docs/)
- [Agent Configuration Guide](https://opencode.ai/docs/agents/)
- [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 ~/.config/opencode/prompts
cp /path/to/nano-opencode-agents/.opencode/agent/* ~/.config/opencode/agent/
cp /path/to/nano-opencode-agents/prompts/* ~/.config/opencode/prompts/
```

#### Step 2: Create Global config.json
```bash
# Create global config file with all agents
cat > ~/.config/opencode/config.json << 'EOF'
{
  "agents": {
    "build": {
      "type": "prompt",
      "path": "prompts/build.txt"
    },
    "cleanup": {
      "type": "prompt", 
      "path": "prompts/cleanup.txt"
    },
    "security": {
      "type": "prompt",
      "path": "prompts/security.txt"
    },
    "review": {
      "type": "prompt",
      "path": "prompts/review.txt"
    },
    "docs-writer": {
      "type": "markdown",
      "path": "agent/docs-writer.md"
    },
    "plan": {
      "type": "json",
      "path": "agent/plan.json"
    }
  }
}
EOF
```

#### Step 3: Verify Global Setup
```bash
# Check global configuration
ls -la ~/.config/opencode/
cat ~/.config/opencode/config.json

# Test from any directory
cd /tmp
opencode  # Will load global agents
```

#### Global Structure
```
~/.config/opencode/
├── config.json          # Main configuration
├── agent/              # Markdown/JSON agents
│   └── docs-writer.md  # Documentation writer
└── prompts/            # Text-based prompts
    ├── build.txt       # Build automation
    ├── cleanup.txt     # Repository cleanup
    ├── review.txt      # Code review
    └── security.txt    # Security analysis
```

## Updating Global Configuration

After making changes to the nano project agents, you need to sync them with the global configuration:

### When to Update
- Edited agent prompts
- Added new agents
- Removed existing agents
- Modified agent configurations
- Changed opencode.json settings

### Update Steps

#### 1. Copy Changes to Global Location
```bash
# Navigate to nano project directory
cd /path/to/nano-opencode-agents

# Copy updated agent files
cp .opencode/agent/* ~/.config/opencode/agent/
cp prompts/* ~/.config/opencode/prompts/

# Update global config if needed
cp opencode.json ~/.config/opencode/config.json
```

#### 2. Verify the Update
```bash
# Check that files are current
ls -la ~/.config/opencode/agent/
ls -la ~/.config/opencode/prompts/
cat ~/.config/opencode/config.json
```

#### 3. Test Global Agents
```bash
# Test from any directory
cd /tmp
opencode  # Should load updated agents
```

### Specific Update Scenarios

#### Prompt Edits
```bash
# Single prompt update
cp prompts/cleanup.txt ~/.config/opencode/prompts/
```

#### New Agent Added
```bash
# Copy new agent and update config
cp .opencode/agent/new-agent.md ~/.config/opencode/agent/
cp prompts/new-agent.txt ~/.config/opencode/prompts/
# Update ~/.config/opencode/config.json with new agent entry
```

#### Agent Removal
```bash
# Remove from global location
rm ~/.config/opencode/agent/removed-agent.md
rm ~/.config/opencode/prompts/removed-agent.txt
# Remove from ~/.config/opencode/config.json
```

#### Configuration Changes
```bash
# Update global config completely
cp opencode.json ~/.config/opencode/config.json
```

### Workflow Recommendation

1. **Make changes** in nano project (version controlled)
2. **Test locally** in nano project directory
3. **Commit changes** to git repository
4. **Sync to global** using the steps above
5. **Verify globally** by testing from another directory

This workflow ensures:
- Version control of all changes
- Clean separation between development and deployment
- Easy rollback if needed
- Shareable configuration for team members

### 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:

1. Fork the project
2. Create a new branch
3. Add your agent configuration
4. Test thoroughly
5. Submit a pull request

## License

This project is provided as a template for OpenCode agent development. Feel free to adapt and modify for your specific needs.