ollie/CONTRIBUTING.md

Contributing to Ollie

Development Workflow

1. Make changes in the source directory (~/src/ollie/).
2. Build and test: make (runs build + test + install).
3. Verify: Run olliesrv and test your changes.

Code Style

• Go: gofmt, short variable names, error returns (no panics), table-driven tests.
• Tool scripts: Emit structured output (STATUS=ok, STATUS=error).
• Prompts: Markdown, concise, example-driven.

Match the existing code style: naming conventions, error handling patterns, indentation, imports.

Testing

make test          # all tests
make test-core     # cmd/olliesrv, cmd/toolsrv, shared packages
make test-9p       # lib9p tests

Run tests before committing. If you add a feature, add tests.

Commits

• Keep commits atomic and focused.
• Write clear commit messages explaining what and why.
• Prefer new commits over --amend unless incorporating pre-commit hook changes.

Package Documentation

Each package should have a doc.go file with a package-level comment explaining:

• What the package does
• Key types and their relationships
• Usage patterns

File Organization

Split large files by concern:

• One primary type per file when it has significant logic
• Group related functions in the same file
• Keep files under ~500 lines when practical

Adding Tools

Script-based (Python/Bash)

1. Create executable in data/tools/<name>
2. Create data/tools/<name>.meta with JSON metadata
3. Run make install-data

Compiled (Go)

1. Create package under tools/<family>/cmd/<name>/main.go
2. Create <name>.meta alongside main.go
3. Add build target in Makefile
4. Run make

Adding Prompts

1. Write markdown in data/prompts/
2. Reference in agent config if needed
3. Run make install-data

Key Conventions

• Edit source files here, not ~/.config/ollie/ (that's the install target)
• 9P namespace is the API — every capability is a file
• No pointless indirection — call the real thing directly
• Subtraction > addition — look for what to remove first