hyper/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/)

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