# 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

```bash
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