progettino/AGENTS.md

OpenCode Agent Instructions

Overview

This repository contains an OpenCode development environment setup. OpenCode is an AI-powered development assistant that helps you build, test, and deploy software. The environment is configured with the OpenCode plugin and runs in a Linux-based development container.

Project Context

• Project Type: AI Agent Development Environment
• Main Technology: Node.js with OpenCode plugin
• Target Audience: AI agents and developers working on code generation projects
• Development Server: Local development with Ollama for on-premise LLMs

Development Environment

System Setup

• OS: Debian Linux (running in Proxmox container)
• IP Address: 192.168.0.240
• Memory: Standard Linux environment with Node.js
• AI Models: Ollama server at http://192.168.0.50:11434 (gemma2:9b, nomic-embed-text)

Key Directories

• .opencode/ - OpenCode plugin and configuration
• .opencode/memory/ - Persistent memory storage
• .opencode/node_modules/ - Node.js dependencies

OpenCode Usage

Basic Commands

# Start OpenCode agent
opencode

# Run with specific tool
opencode --tool claude

# Check OpenCode version
opencode --version

Agent Workflow

1. Initialization: OpenCode loads the project context and available skills
2. Task Analysis: The agent analyzes the request and breaks it down into steps
3. Execution: Tasks are delegated to specialized subagents
4. Verification: Results are checked against requirements
5. Documentation: Progress is saved to memory and AGENTS.md

Important Development Commands

Node.js Management

# Install dependencies
npm install

# Run scripts (if defined in package.json)
npm run <script-name>

# Check for outdated packages
npm outdated

# Update packages
npm update

Git Operations

# Check status
git status

# Add changes
git add .

# Commit changes
git commit -m "message"

# Push to remote
git push

File Operations

# Search for files
find . -name "*.js" -type f

# Search content
grep -r "pattern" .

# List all files
ls -la

Testing and Debugging

Diagnostic Tools

• lsp_diagnostics: Check for errors and warnings in files
• grep: Search for patterns across the codebase
• ast_grep: Advanced code pattern matching
• read: Read file contents

Debugging Strategy

1. Use lsp_diagnostics to identify issues
2. Search for similar patterns with grep or ast_grep
3. Consult documentation for external libraries
4. Test changes in isolation
5. Verify with build/test commands

Conventions and Best Practices

Code Quality

• Type Safety: Never suppress type errors with as any or @ts-ignore
• Error Handling: Always handle errors properly; avoid empty catch blocks
• Testing: Write tests for new functionality; don't delete failing tests
• Refactoring: Refactor safely; use tools to ensure correctness

Workflow

• Atomic Commits: Each commit should represent a single logical change
• PRs: Keep pull requests focused and small
• Documentation: Update documentation as part of any significant change
• Memory: Use memory files to persist important information

Common Gotchas

Environment Issues

• Node.js Version: Ensure you're using a compatible Node.js version
• Dependencies: Install all dependencies before running commands
• Permissions: Check file permissions for read/write access

OpenCode Specific

• Context Window: Keep requests focused to avoid context overflow
• Skill Selection: Use appropriate skills for the task domain
• Background Tasks: Use run_in_background=true for parallel operations
• Task Continuation: Use task_id to continue previous agent sessions

External Resources

Documentation Links

• OpenCode Documentation
• Node.js Documentation
• Ollama Documentation

Local Servers

• Ollama: http://192.168.0.50:11434
• Development Server: (if applicable)

Project-Specific Notes

This is a minimal development environment primarily used for:

• Testing OpenCode agent capabilities
• Developing AI-assisted coding workflows
• Experimenting with on-premise LLM integration

The repository is intentionally simple to serve as a clean slate for various development tasks.

Updating This File

Keep AGENTS.md up to date with any new conventions, commands, or structural changes. Remove outdated information and add new insights as they're discovered.

(End of file)