AGENTS.md: update build system references from justfile to Makefile
This commit is contained in:
Levi Neely
parent
8b71b34fdf
commit
2e6ec53dec
65
AGENTS.md
65
AGENTS.md
|
|
@ -3,8 +3,8 @@ Project-level context for AI agents working in this repository.
|
|||
|
||||
> **⚠️ IMPORTANT: All work must be done in THIS source directory (`~/src/ollie/`).**
|
||||
> Never edit files under `~/.config/ollie/` — that is an install target.
|
||||
> Changes made there are overwritten on the next `just install-data`.
|
||||
> Edit source files here, then run `just` to build and install.
|
||||
> Changes made there are overwritten on the next `make install-data`.
|
||||
> Edit source files here, then run `make` to build and install.
|
||||
|
||||
## Project Overview
|
||||
Ollie is an AI agent runtime inspired by Plan 9: agent state and behaviors are exposed as files in a 9P namespace. Orchestration, scheduling, and UIs are external — shell scripts, editors, web apps. The core is minimal; capabilities come from composing scripts.
|
||||
|
|
@ -53,41 +53,34 @@ ollie/ ← you are here
|
|||
|
||||
### Canonical source for prompts, tools, and skills
|
||||
|
||||
Do not edit `~/.config/ollie/` directly. It is an install target. Runtime data is copied from `data/` by `just install-data`; compiled tools are built into the same runtime tools directory by their build targets. The installed configuration also contains `backends.conf`, `sandbox.yaml`, agents, prompts, skills, scripts, and tools.
|
||||
Do not edit `~/.config/ollie/` directly. It is an install target. Runtime data is copied from `data/` by `make install-data`; compiled tools are built into the same runtime tools directory by their build targets. The installed configuration also contains `backends.conf`, `sandbox.yaml`, agents, prompts, skills, scripts, and tools.
|
||||
## Build System
|
||||
The default `just` target builds and installs the KF6 variant. Build and install are separate phases.
|
||||
The default `make` target builds, tests, and installs. Build and install are separate phases.
|
||||
```bash
|
||||
just # build + test + install (KF6)
|
||||
just kf5 # build + install the KF5/Qt5 variant
|
||||
just build # build core, 9P, lib9p, tools, and KDE
|
||||
just core # go build ./...
|
||||
just ninep # olliesrv and ollie-9p
|
||||
just lib9p # native lib9p shared library and header
|
||||
just toolsrv # toolsrv binary
|
||||
just code-tools # Tree-sitter code-intelligence tools
|
||||
just file-tools # Go file tools
|
||||
just lsp-tools # LSP tools
|
||||
just tools-web # web_fetch
|
||||
just kde # KDE KF6 integration
|
||||
just kde-kf5 # KDE KF5 integration
|
||||
just install-data # runtime configuration, prompts, skills, scripts, and tools
|
||||
just install-el # Emacs frontend
|
||||
just test # core and lib9p tests
|
||||
just test-core # cmd/olliesrv, cmd/toolsrv, shared packages, and toolsrv tests
|
||||
just test-9p # lib9p tests
|
||||
just test-remote # build-check toolsrv (`go build ./cmd/toolsrv/...`)
|
||||
just clean # remove build artifacts
|
||||
make # build + test + install
|
||||
make build # build core, 9P, client, tools, and KDE
|
||||
make core # go build ./...
|
||||
make ninep # olliesrv and ollie-9p
|
||||
make client # native lib9p shared library and header
|
||||
make tools # compiled tools (code-intel, file, LSP, web)
|
||||
make kde # KDE KF6 integration
|
||||
make kde-kf5 # KDE KF5 integration
|
||||
make install-data # runtime configuration, prompts, skills, scripts, and tools
|
||||
make test # core and lib9p tests
|
||||
make test-core # cmd/olliesrv, cmd/toolsrv, shared packages
|
||||
make test-9p # lib9p tests
|
||||
make clean # remove build artifacts
|
||||
```
|
||||
Requires [just](https://github.com/casey/just): `cargo install just`.
|
||||
Requires GNU Make.
|
||||
|
||||
## Testing
|
||||
The supported test entry points are:
|
||||
```bash
|
||||
just test
|
||||
just test-core
|
||||
just test-9p
|
||||
make test
|
||||
make test-core
|
||||
make test-9p
|
||||
```
|
||||
For direct Go testing, use the packages covered by `just test-core` and `just test-9p`. The current repository does not contain the former `cmd/ollie-remote` package; remote tool execution is implemented by `toolclient.SpawnRemote` and the remote toolsrv deployment path.
|
||||
For direct Go testing, use the packages covered by `make test-core` and `make test-9p`.
|
||||
## Language & Conventions
|
||||
|
||||
- **Go** (root module): Go 1.25+, standard library preferred, minimal dependencies.
|
||||
|
|
@ -136,7 +129,7 @@ Runtime configuration is read from `~/.config/ollie/` (or `$XDG_CONFIG_HOME/olli
|
|||
- `OLLIE_BACKEND` is a fallback when no configured backend or session backend is selected.
|
||||
- `OLLIE_MODEL` is a legacy/environment model fallback; configured backend sections can set `model = ...`.
|
||||
- The runtime path helpers honor `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, and `XDG_RUNTIME_DIR`.
|
||||
- The current `justfile` install targets use `~/.config/ollie`, `~/.local/share/ollie`, and `~/.local/bin` directly; non-default XDG locations therefore require adjusting the install targets or copying the installed files manually.
|
||||
- The Makefile install targets use `~/.config/ollie`, `~/.local/share/ollie`, and `~/.local/bin` directly; non-default XDG locations require adjusting the install targets or copying the installed files manually.
|
||||
- Runtime tools are discovered from `$XDG_CONFIG_HOME/ollie/tools` (default: `~/.config/ollie/tools`).
|
||||
- OptMem runtime data is under `$XDG_DATA_HOME/ollie/optmem` (default: `~/.local/share/ollie/optmem`).
|
||||
## Adding a new tool
|
||||
|
|
@ -147,26 +140,26 @@ Runtime configuration is read from `~/.config/ollie/` (or `$XDG_CONFIG_HOME/olli
|
|||
```json
|
||||
{"description":"...","prompt":"...","args":{...},"tier":"hot","readOnly":false}
|
||||
```
|
||||
3. Run `just install-data` to install
|
||||
3. Run `make install-data` to install
|
||||
|
||||
### Compiled tool (Go)
|
||||
1. Create a package under `tools/<family>/cmd/<name>/main.go`
|
||||
- Read JSON args from stdin, write result to stdout, exit 0/1
|
||||
- Share library code in `tools/<family>/` (e.g. `tools/lsp/`)
|
||||
2. Create `<name>.meta` alongside `main.go` in the same `cmd/<name>/` directory (same format as above)
|
||||
3. Add a build target in the justfile that compiles to `{{cfg}}/tools/<name>` **and** installs the `.meta` file alongside it
|
||||
4. Run `just` to build and install
|
||||
3. Add a build target in the Makefile that compiles to `$(CFG)/tools/<name>` **and** installs the `.meta` file alongside it
|
||||
4. Run `make` to build and install
|
||||
|
||||
The `.meta` file lives with the code that produces the tool, not in `data/tools/`. See the `lsp-tools` just target for the canonical pattern.
|
||||
The `.meta` file lives with the code that produces the tool, not in `data/tools/`. See the `tools` target in the Makefile for the canonical pattern.
|
||||
|
||||
Both paths produce the same result: an executable + `.meta` in `$XDG_CONFIG_HOME/ollie/tools`.
|
||||
The registry doesn't distinguish between scripts and binaries.
|
||||
## Adding a new prompt
|
||||
1. Write the markdown file in `data/prompts/`
|
||||
2. If it should be loaded by default, reference it in `data/agents/default.json`
|
||||
3. Run `just install-data` to install
|
||||
3. Run `make install-data` to install
|
||||
## KDE development
|
||||
KDE integration is part of this repository under `kde/`. Build and install it through the root `justfile` targets. The component has its own `kde/justfile` for focused KDE builds.
|
||||
KDE integration is part of this repository under `kde/`. Build and install it through the root Makefile targets (`make kde` or `make kde-kf5`).
|
||||
|
||||
## Key Lessons (Aug 14–17 session)
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue