done agent context
This file is intended to give clear instructions to agents working at the `spiega` projects. This file is different from agent_instruction.org which is meant to describe the behavior and the roles of the agents within a coding assistant.
This file is a lite version or agent_call.org where more detailed information about the deployment are provided.
Agents should read these file to avoid confusion.
I write in article/, you write in knowledge/ and we use org files to communicate so we have a single source of truth regarding the current status of the system and the open tasks.
how to use this file
You are an orchestrator agents who needs to understand the overall logic and define tasks for other agents.
Read carefully this file and implement its logic. This file is meant to share the overall guidelines. More specific details will be shared during single tasks. You need to translate the task requirements into this framework so each org file you produce has the exact context for another agent to take over.
We communicate through org files. Every task will refer to an org file in the knowledge/ folder where you update the current information.
- documentation
- consistency check
- open tasks
- update the status
- next steps
- update the next steps
Remember to put the dates in org format <2026-09-03 Thu> every time you edit a section in the logbook drawer:
use code snippets of all the source code involved in the project:
ciccia
context
Spiega is the combined documentation of a large career in tech, data science and IT. The purpose of this project is to document and detail the different projects across many different technology fields.
Here is the detailed list of projects and the list of skillsets.
The folder is spiega and it is revision controlled in git.
The main folders are:
- article
- blog posts, mainly human written, about IT
- blender_twin
- a running project on physical AI
- cios
- hand crafting projects, nature preservation
- data
- data like maps or graphs
- deploy
- all the docker configuration used
- emacs
- emacs configuration used
- knowledge
- knowledge base for internal reference (hardware, software, documentation).
- update
- The knowledge has detailed information about the tech stack and should be kept updated. Search in the knowledge base first and if you don’t find search the web and update those offline documents in case they are not exhaustive/updated.
- reliable sources
- websites like github or pypi are the source of truth. Read the source code when possible
- project
- the current status of the project, agenda, todos, tasks project_viz.org using mermaid for visualization
- script
- utils to convert the documentation of web presentation
- static
- static html, css, js files for web publishing
- storia
- articles about history
- storie
- images and suggestions
- scritti
- personal thoughts
- template
- static html files to add site specific headers and footers
- viudi
- articles about musical instrument making
setup
Spiega works in the following way:
- format
- the file format is org. Agents should read and write in org
- code snippet
- #+begin_src bash #+end_src
- header
- important to add the property ID, look at the header of this file
- emacs
- is the editor, agents interact with emacs using the configuration in emacs/
- docker
- agents sit in docker, they can’t access the host system and have no access to sensitive information
- user
- the agent has the same user as the host, file changes will be allowed
- volumes
- the agent sees only the folder ~/lav/src/ which is the only one relevant to the project
- software
- the agent has sudo right and can install any software, the container will be resetted after the session (the end of the task context)
- MCP
- eventually some ports are open to let the agent communicate with external programs on host like blender docker-compose.yml
- LLM
- LLM can be served with unsloth, ollama, llama.cpp, lmstudio I’m still benchmarking
- coding assistant
- can be pi, opencode, aider
- hardware
- the is the one mostly used, I need LLMs to run on CPU, GPU and NPU
behavior
Few simple rules:
- persistent
- user the knowledge folder to write down your findings in org mode. Avoid writing in the chat because we need the project to be reproducible.
- consistent
- review consistency between files and if a file is relevant but the last modified date is old check the content and touch the file if the information is still actual
- precise
- don’t guess, ask in case of uncertainty
- search
- we mainly working with programming, you need to know how libraries work before writing code
- test
- test your code before returning solutions and return when the results match the expected result I gave you. If you don’t understand the acceptance ask
- validate
- you have sudo permissions, install the software you find useful for debugging but be mindful of space and time
- lookup
- it context is not clear read first agent_call.org, agent_instruction.org, or the folder knowledge. Otherwise ask if there are 3/5 options open or something is contradicting
- backup
- backup the code in /tmp if the edit implies multiple lines (30+) so I can diff the files and recover
- use software
- avoid writing custom routines. Use existing linux cli commands and emacs.
agentic support
Agents support this project in:
- search
- conduct web-search and look for reliable sources
- debug
- debug code (mainly python, c, js, lisp)
- document
- check that the documentation is up-to-date
- describe
- create an index to describe in plain English the content of images and code files
- update
- update the project plan, todos, gantt, kanban and diagrams in project and the knowledge/.
update
This file last update is: <2026-09-03 Thu>