This is [Andreas Sefzig](https://homepage.sefzig-net.workers.dev/)s tutorial "Local Agent": - Canonical Web URL: `https://homepage.sefzig-net.workers.dev/tutorial/local-agent`. - A copy of the Markdown: `https://homepage.sefzig-net.workers.dev/source/tutorials/local-agent/Content.md`. - The URL of this prompt `https://homepage.sefzig-net.workers.dev/source/tutorials/local-agent/Prompt.md`. As you read this, it might be a good idea to discuss with your user whether they want to walk through the Local Agent tutorial or whether they have questions. The following is the Markdown of the tutorial. --- # Local Agent _In this tutorial, we will set up a powerful local Agent._ The tutorial will walk you through setting up your Agent along a simple proven method, working in the Harness of your choice. What your [Agent(cxw tooltip click)]("An AI Agent is a program that uses Large Language Models to make decisions, pursue goals, and take actions on behalf of the user.") will work on is up to you! ![An agent lives in a computer that is connected to the cloud (full trans)](images/illustration.img) > [Hint] > Prerequisites: An active [Harness(cxw tooltip click)]("A Harness is a program that enables LLMs to operate as an Agent and users to provide that Agent with input. Examples are ChatGPT Work, Claude Code/Work, OpenCode."), being comfortable using [Markdown(cxw tooltip click)]("Markdown is a way to format long text with a simple, human-friendly syntax. With Markdown, you create text that is structurally sound, rich in terms of embedded content, and the preferred style of any AI.\n\nTake my [5-minute tutorial](https://homepage.sefzig-net.workers.dev/tutorial/markdown) first?"), and an afternoon's time. The tutorial is not technical at all. Once the basics are set up, I will guide you while you implement your own use case. ## Introduction _Please read first what you can expect from this tutorial._ The tutorial will take you aproximately 2 hours. This is for setting up and understanding your Agent; depending on what you want your new Agent to do, you will spend more time. Context [^] If you are new to agentic AI or need context, I recommend you read my related [Blog Post](https://homepage.sefzig-net.workers.dev/blog/local-agents) first. Or read the summary of my methods pros and cons: The pro's of my method [v] - One method that works across any use case - Isolate [domain expertise(cxw tooltip click)]("Your expertise is what the AIs don't have: Taste. You know how to turn data into information, how to apply that in your domain, and how to talk about it.") in portable files - Stay [Model(cxw tooltip click)]("A Large Language Model (short: LLM or Model) is a machine learning model capable of generating text that aims at completing the input of its user.")- and [Harness(cxw tooltip click)]("A Harness is a program that enables LLMs to operate as an Agent and users to provide that Agent with input. Examples are ChatGPT Work, Claude Code/Work, OpenCode.")-agnostic - Keep [Token(cxw tooltip click)]("Tokens are the atoms of AI inference and the currency Model providers use to price the usage of their Models.") cost at minimum - Stay somewhat low-tech to minimize dependencies - Be ready for the next developments The con's of my method [v] - You need to have the common administrative rights on your computer. - Providing others with your Agent requires either them to use a copy of your files (through [Git(cxw tooltip click)]("Git is a free software to maintain and update files across computers.") or manual copies), or you to host the filesystem together with a headless Harness as a [Container(cxw tooltip click)]("You can host the filesystem together with a headless Harness in the cloud (which is not trivial to set up). With such a solution, your Agent(s) become(s) an API you can connect to with systems such as Slack, n8n, or your website."), which is not trivial. The tutorial will walk you through the setup and explain the reasoning behind each step. You can follow along or [download](downloads/Local-Agent_Template.zip) the files directly. With that and my notes in the last section, you will set up your use case in a breeze! ## Set up the Structure _First, we will create the conventional filesystem._ As with any system, we need to think about the architecture first. Ours is a simple filesystem in a folder of your choice. Later, you will point your AI Harness at it to bring it to life. So, let us build the filesystem piece by piece: ### Root _We will create the Agent in a folder of your choosing._ Put a folder named `agents` anywhere on your computer: ```md [<] Filesystem agents/ └─ ... ``` Recommendations [v] I recommend to put `agents` into your common `documents` folder. You can choose a different name, but in this tutorial, we will assume you named that folder `agents`. In it, add your first Agent as a folder named `tba`: ```md Filesystem agents/ └─ tba/ ``` We will rename that folder once we implement your use case. Later, additional agents will also reside in `agents`. ### Governance _We create a folder for durable, canonical instructions._ Add the folder `gov` for all our Governance files: ```md [<] Filesystem agents/ └─ tba/ └─ gov/ ``` Permissions [v] You dont want your Agent to rewrite its own Governance, so we will later tell the Agent to not modify it's contents. So here is our first convention to remember: > [Hint] > _Convention_ > The folder `gov` contains all of the Governance. Next, we will distinguish between 3 types of Governance. [!Steps] #### Knowledge One type of Governance is Knowledge – background information that the Agent will regard as canonical. Add the sub-folder `knowledge`: ```md Filesystem agents/ └─ tba/ └─ gov/ └─ knowledge/ ``` This is where you will store your domain knowledge in the form of focussed, portable files. #### Rules Another type of Governance are Rules – actionable information that instructs the Agent on good decisions. Add the sub-folder `rules`: ```md Filesystem agents/ └─ tba/ └─ gov/ ├─ knowledge/ └─ rules/ ``` This is the behavioral layer making the Agent steer itself through your conversations. #### Workflows The third type of Governance are Workflows – procedural information that the Agent will use to produce certain results. Add the sub-folder `workflows`: ```md Filesystem agents/ ├─ ... └─ tba/ └─ gov/ ├─ knowledge/ ├─ rules/ └─ workflows/ ``` This is your domain knowledge on how to produce results that you expect to be deterministic. #### Summary Ok, now the Governance structure is set up: ```md Filesystem agents/ └─ tba/ └─ gov/ ├─ knowledge/ ├─ rules/ └─ workflows/ ``` And we have another convention: > [Hint] > _Convention_: > Governance is separated into `knowledge`, `rules`, and `workflows`. Let us move on: Tools are next. ### Tools _We create one folder for all the [tools(cxw tooltip click)]("Tools are what an Agent can use to actually do something:\n\n- Reading and writing files\n- Get data from an API\n- Execute a program\n\nHarnesses provide Agents with various tools. In our Agent, we will establish a way for us to extend those basic capabilities.") your Agent can use._ For a [variety of reasons(cxw tooltip click)]("You can rely on the tools your Harness provides, but then you are locked in!\n\nAlso, you will want your tools to be consistent and eventually confidential, for example\n- to request customer data from your CRM,\n- send data to an internal system, or\n- to add a monitoring later."), we will manage our own Tools from the start. Add the folder `tools`: ```md [<] Filesystem agents/ └─ tba/ └─ tools/ ``` File types [v] The tools in this folder will be one `.py` (Python) file each. These could be `.sh` (Shell on Mac) or `.ps1` (PowerShell on Windows) files too, but Python works on all systems and has almost no drawbacks. Let's stick to Python until a specific (yet somewhat improbable) need arises. Permissions [v] As with the `gov`, you don't want your Agent to freely change files in this folder. So we will later tell the Agent to modify it's Tools only with your explicit clearance. Next convention to remember: > [Hint] > _Convention_ > We keep all Tools as Python scripts in one place. ### Workbench _Your Agent works exclusively in a dedicated folder._ Create the folder `work`: ```md [<] Filesystem agents/ └─ tba/ └─ work/ ``` Contents [v] Which files and-or folder reside in `work` depends on your Agent's use case, which we have not yet defined. So let's keep that folder unstructured for now. Next convention to remember: > [Hint] > _Convention_ > The Agent will edit files only in the Workbench. Let's move on. ### Documentation _We create one folder for our (manually curated) docs._ > I like to have a documentation for everything. You too? Let's add one last main folder: ```md [<] Filesystem agents/ ├─ ... └─ tba/ ├─ docs/ └─ ... ``` Curation [v] - _Q_: Why manually curate the docs? - _A_: Surely your Agent could write it's own docs. But I have realized that one needs to write the docs oneself to make sure one really understands the Agent. Otherwise there will be #Robogeddon! So here is our last structural convention: > [Hint] > _Convention_ > We manually curate a documentation of the Agent. Next, we will revisit the structure we created. ### Summary _Before we proceed, a quick summary on where we stand._ We now have a very simple folder structure with a set of simple conventions to make sense of it: ```md [v] Filesystem agents/ ├─ ... └─ tba/ ├─ docs/ ├─ gov/ ├─ knowledge/ ├─ rules/ └─ workflows/ ├─ tools/ └─ work/ ``` Conventions [v] - The folder `gov` contains all of the Governance. - Governance is separated into Knowledge, Rules, and Workflows. - We keep all tools as Python scripts in one place. - The Agent will edit files only in the Workbench. - We manually curate a documentation of the Agent. Every file your Agent will ever need has a orderly place; except for the Workbench, in which your Agent's use case can grow. Let's move on to breath in some life! ## Add basic Behavior _Now let us tell the Agent how to use our filesystem._ * How is your Agent supposed to understand the structure? * And how do we prevent it from reading everything at once? This section covers the files that will make the Agent decide which files to read as per case: [Steps] We will go through these essential files one by one. ### AGENTS.md [entrypoint] _Harnesses expect one file as the Agent's entrypoint._ Most Harnesses recognize any file named `AGENTS.md` as the first file to read when a conversation is started in its root folder: ```md [<] Filesystem agents/ └─ tba/ └─ AGENTS.md ``` Of course, Google and Anthropic don't adhere to the standards because they are so special. But there is a workaround. > [Hint] > _Convention_ > We curate one entrypoint for all Harnesses. Let's set this up next. [!Steps] #### AGENTS.md [agents-md] Add the file `AGENTS.md` to your Agent's root folder: ```md [<] Filesystem agents/ └─ tba/ └─ AGENTS.md ``` Fill the main entrypoint with actual instructions: ```md [v nowrap] Template # Tba You, the Agent, are asked to do things on behalf of the User. To fulfil your duty, you need to know the following. ## Your role _TBA_ ## Your instructions To solve the Wish of the User, you need to have read and mandatorily respect these Governance files: - `gov/rules/_Index.md` - `gov/workflows/_Index.md` - `gov/knowledge/_Index.md` Also, you need to be aware of how to use the Tools that are available: - `tools/_Index.md` Follow these steps to make sure you work inline with the Governance: 1. Read `gov/rules/_Index.md` once per Session. 2. Read `gov/workflows/_Index.md` once per Session. 3. Read `gov/knowledge/_Index.md` once per Session. 4. Read `tools/_Index.md` once per Session. Also, understand `gov/rules/Tool-use.md`. 5. Before using an Engine-native capability, apply the capability resolution priority in `gov/rules/Tool-use.md`; when a matching registered Tool exists, invoke it through the Tool wrapper. 6. Read the Wish-relevant Platform Rules and Workflows. 7. Proceed only when the Wish is clear enough to do unambiguously. If it is not, invoke `gov/workflows/Requirements-first.md` ## Protected Artifacts Before writing protected artifacts, you must ask the User for explicit permission. Protected Platform artifacts include: - `docs/**` - `gov/**` - `tools/**` - `AGENTS.md` - `README.md` Usually, you should not find yourself in a situation of having to edit them. If the User allowed you to, take utmost care and involve in any decision. ``` What this does [v] - Make the Agent read the minimal mandatory rules - Make the Agent read the indices to know what else is there - Make the Agent prefer tools from `tools/` if available - Make the Agent understand which files not to touch uncleared What to do [v] - Replace `tba` with your Agents folder name - Replace `Tba` with your Agents human readable name - Replace `_TBA_` with prose describing your Agent Now we have provided the Agent with it's initial orientation. Note for Git users [v] *If* you want to include a Git sync, do that here. Add a section above the ordered list, describing how you want Git to be used. Add that step to the ordered list as #1. #### Symlinks [symlinks] Because not everybody adheres to the standard, we have to work around the Harnesses using `CLAUDE.md` and `GEMINI.md` as antrypoints. We will create [Symlinks(cxw tooltip click)]("Symlinks are files that appear to be regular files with their own filename, but simply point to the content of another file."), which will make most programs load your `AGENTS.md` instead: ```md [<] Filesystem agents/ └─ tba/ ├─ AGENTS.md ├─ CLAUDE.md └─ GEMINI.md ``` This is a bit tricky because we need your computer's [os:Apple]Terminal[/os:Apple][!os:Apple]Shell[/!os:Apple] application for this. [Skip the next step](#skip) if you are not comfortable with the console. Later, we can ask your Agent to do that for us. #### Symlinks [symlinking] _Ok, so you are comfortable with the console, you nerd._ [device:Desktop] This is what we need to do: Open the console app [^] Open your [os:Apple]Terminal[/os:Apple][!os:Apple]Shell[/!os:Apple] application. Navigate to the folder [v] Navigate to `tba` in your `agents` folder: ```bash cd /agents/tba ``` `` is a placeholder for the actual path. Set up the Symlinks [v] Enter these two lines: [os:Apple] ```bash ln -s AGENTS.md CLAUDE.md ln -s AGENTS.md GEMINI.md ``` [/os:Apple] [!os:Apple] ```shell New-Item -ItemType SymbolicLink -Path "CLAUDE.md" -Target "AGENTS.md" New-Item -ItemType SymbolicLink -Path "GEMINI.md" -Target "AGENTS.md" ``` [/!os:Apple] This will create the Symlinks we need. Check they are there [v] Look into your `agents/tba` folder: Are the Symlinks there? If not, we will ask your Agent later to do this for us. [/device:Desktop] [!device:Desktop] > [Error] > Your device does not allow for creating symlinks. > We will ask your Agent later to do this for us. [/!device:Desktop] Whether that worked or not: let's continue. ### _Index.md [indices] _We maintain a search index in any (potentially) crowded folder._ > [Error] > Tba. A simple yet robust way is to maintain an index file in every folder which contains discoverables like Governance files, Tools, or Workbench content. ```md [v] Filesystem agents/ └─ tba/ ├─ docs/ └─ _Index.md ├─ gov/ ├─ knowledge/ └─ _Index.md ├─ rules/ └─ _Index.md └─ workflows/ └─ _Index.md ├─ tools/ └─ _Index.md └─ work/ └─ reports/ └─ _Index.md ``` These indices contain a list of files each with a short summary of when to use it. This will allow us to drop the name of any folder and the Agent, knowing about this convention from `AGENTS.md`, can contextually infer what is relevant. Reasoning [v] One priority of ours is to not require the Agent to read everything preemptively, because that would - fill up the [Context Window(cxw tooltip click)]("The Context Window is the maximum number of Tokens a Model can ingest when generating a response. Models will simply miss excess information.") needlessly, - make [Inference(cxw tooltip click)]("Inference is the process in which a Model predicts the next Tokens based on the input it gets.") slower, and even - risk to confuse the Model with seemingly conflicting information. So we give the Agent an abstract of all available files, so that it can discover more information when it actually needs it. To make these indices stand out, both for the Agent and ourselves, we give the files a consistent filename that will lead any alphabetical sorting: `_Index.md`. > [Hint] > _Convention_ > Every folder with discoverable files gets an `_Index.md`. Let's set that up next. [!Steps] #### _Index.md [indices-template] _Here is a template for you to use._ ````md [< nowrap] Template # Index: __ ## Format files listed in this index are registered with this structure: ```md * `File-name.md`: Short description of the . ``` ## List * Tba ```` What this does [<] - Explain the purpose - Define the format - List the files Add the file `_Index.md` to all these folders: ```md Filesystem agents/ └─ tba/ ├─ docs/ └─ _Index.md ├─ gov/ ├─ knowledge/ └─ _Index.md ├─ rules/ └─ _Index.md └─ workflows/ └─ _Index.md └─ tools/ └─ _Index.md ``` What to do [<] In each copy: - replace `` with the human readable name of the folder - replace `` with the descriptions below Descriptions [<] - `/docs/`: This is the documentation of the Tba Agent. - `/gov/knowledge/`: This file lists canonical Knowledge you use. - `/gov/rules/`: This file lists the mandatory Rules you will use. - `/gov/workflows/`: This file lists Workflows you may use. - `/tools/`: This file lists tools which are available to you. All done? Then let's close the last gaps next. ### README.md [description] _We close the last gaps by describing the folders._ Sometimes, the Agent will not look for a folders content, but its purpose. For that, we will use the [classic(cxw tooltip click)]("A file commonly found in folders used by developers is the `README.md`, which describes the contents of a folder. It contains a brief description of the purpose of a folder.") `README.md` file. > [Hint] > _Convention_ > Every folder gets a `README.md` describing the folder's purpose. There are [reasons(cxw tooltip click)]("Reasons not to merge:\n- Depending on the context, the description or the exact content is not relevant for the Agent.\n- `_Index.md` will be sorted to the top by your file manager.\n- `README.md` will be sorted somewhere between files whose names start with 'Q' and 'S'.\nOur future selves will appreciate a place for folder-specific notes.") to not merge Indices and Descriptions. [!Steps] #### README.md [readme-md] _Here is a template for you to use._ Every folder gets a `README.md`: ```md [<] Filesystem agents/ └─ tba/ ├─ docs/ └─ README.md ├─ gov/ ├─ knowledge/ └─ README.md ├─ rules/ └─ README.md ├─ workflows/ └─ README.md └─ README.md ├─ tools/ └─ README.md └─ work/ └─ README.md ``` Use this as a template: ```md [< nowrap] README.md # _This is the folder._ ``` What this does [<] - Explain the purpose - Ready for you to take notes All copies must be adjusted: What to do [<] - Copy the template in every folder In each copy: - replace `` with the human readable name - replace `` with the descriptions below Descriptions [v] - `docs/`: This is the documentation of the Tba Agent. - `gov/`: This folder contains the Governance _Template adheres to. The Governance is split into binding Rules, procedural Workflows, and canonical Knowledge. - `gov/knowledge/`: This file lists canonical Knowledge you use. - `gov/rules/`: This file lists the mandatory Rules you will use. - `gov/workflows/`: This file lists Workflows you may use. - `tools/`: This folder contains Workspace tools. Tools in this folder are workspace tools that Colleagues may use when a User Wish matches the tool capability. Tool use is governed by the Rule `/gov/rules/Tool-use.md`. The registry for this folder is `/tools/_Index.md`. - `work/`: This folder is your Workbench. Only here you have my permission to edit files. Done? Then we can sum up the behavior. ### Summary _Before we proceed, a quick summary on where we stand._ We now have an Agent that traverses our filesystem to read our files only when they are relevant for the current task. We added the entrypoint `AGENTS.md` and registered all folders with `README.md` and all files with `_Index.md`: ```md Filesystem agents/ └─ tba/ ├─ docs/ ├─ _Index.md └─ README.md ├─ gov/ ├─ knowledge/ ├─ _Index.md └─ README.md ├─ rules/ ├─ _Index.md └─ README.md ├─ workflows/ ├─ _Index.md └─ README.md └─ README.md ├─ tools/ ├─ _Index.md └─ README.md ├─ work/ └─ README.md ├─ AGENTS.md ├─ CLAUDE.md └─ GEMINI.md ``` We have not yet written *any* instructions! That will be next. > [Gold] > Goal achieved: Finished the first boring part. ## Add basic Governance _Now we will integrate generally applicable Governance._ Still apart from your use case, let us add instructions that make any Agent well-behaved: [Steps] We will walk through these files one by one. ### Terminology [terminology] _First of, let us agree on a shared language._ Once you and your Agent established a shared vocabulary, communication becomes much easier. This Governance lists terms and their canonical meaning: ```md [<] Terminology.md # Terminology The terms below are to be used consistently: * `Agent`: The actual invocation of an LLM by the User in a Session of the Agent. * `Assumption`: A temporary understanding of how to go about working on the User's Wish. * `Filesystem`: The local folder with subfolders and files the Harness is working in. * `Governance`: The canonical information Agents use to know how to work as a Agent. * `Harness`: Agent harness tool to talk/work with Agents, currently OpenCode. * `Index`: A file listing the content of the folder it is in. * `Knowledge`: Informational governance that contains Agent-specific background info. * `Log`: An artifact written by the Agent whenever a task was accomplished. * `Model`: The LLM used for inference, chosen by Router based on the Alias the User chose. * `Platform`: The Filesystem plus Harness layer running on top of the Agent Workspaces. * `Protocol`: A certain chat behaviour of the Agent as governed by various Rules. * `Provider`: The llm platform the Model is consumed from. * `Reaction`: The final response of the Agent when working on a Users Wish. * `Result`: A change in the Filesystem that is invoked by the User's Wish. * `Rule`: Behavioral governance the Agent will adhere to, can be Agent-specific. * `Session`: A single conversation the User has with a Agent in the Harness. * `Tool`: A script for Agents to use (not to be confused with Harness' native tools). * `User`: The person actually talking to the Agent in the Harness right here. * `Wish`: The expressed need of the User when talking to the Agent. * `Workbench`: Agent-specific output folder, containing for example apps/ or posts/. * `Workflow`: Procedural governance that makes Agents take a certain sequence of steps. * `Workspace`: The folder of one Agent in the Filesystem. Related files: * Rule describing how to apply these terms: [Terminology to use](/gov/rules/Terminology-to-use.md) ``` Copy the file here: ```md [<] Filesystem agents/ └─ tba/ └─ gov/ └─ knowledge/ └─ Terminology.md ``` To make both you and the Agent recognize these terms in regular communication, we will write those terms in [Title case(cxw tooltip click)]("Title case writes the main word/s with an uppercase first letter, e.g. `Harness`. With this being unnatural in English, these terms stand out without annoying the reader."). > [Hint] > _Convention_ > We [curate(cxw tooltip click)]("I recommend you keep this dictionary up-to-date, as you encounter more terms that require a shared understanding.") terms that have a specific meaning in shared dictionary. > They appear in Title case. In the accompanying Rule (referenced in the last line), we will tell the Agent how to handle these terms. But first, we need to register the Knowledge in it's Index to make it discoverable. [!Steps] #### Terminology [terminology-knowledge] _We need to make the Knowledge discoverable._ Update this `_Index.md` file ... ```md [<] Filesystem agents/ └─ tba/ └─ gov/ └─ knowledge/ └─ _Index.md ``` ... by adding this list item: ```md [< wrap] Markdown * `Terminology.md`: A list of all terms that have a specific canonical meaning. ``` Now, the Agent can read those terms whenever it needs. Next, let us make sure the Agent sticks to them. #### Terminology [terminology-rule] In the `gov/rules/` folder ... ```md [<] Filesystem agents/ └─ tba/ └─ gov/ └─ rules/ └─ Terminology-to-use.md ``` ... add this file ... ```md [v copy nowrap] Terminology-to-use.md # Rule: Terminology to use _We use a controlled terminology so that Agents speak consistently in Sessions, Governance, Documentation, and Results._ ## Terms Read the Knowledge `/gov/knowledge/Terminology.md` first, once per Session. It is our canonical list of Terms. ## Usage Always apply the following rules. ### Capitalization Capitalize governed Terms when they refer to internal concepts. Examples: - `The Workflow writes a Log.` - `The User validated a decision.` - `This is governed Workbench material.` Do not capitalize ordinary language that only happens to use the same word. Examples: - `Apps should leave logs when integrating an n8n workflow.` - `This might look funny to the common user.` - `The synthesia workbench is very intuitive.` Plural and adjectival forms are capitalized when they still refer to governed Platform concepts, such as `Workflows` or `Rules`, or `Harness-native`. ### Literal casing File paths, slash commands, code identifiers, field names, and quoted source text keep their original casing even when they contain a Term. Examples: - `/gov/workflows/Example-workflow.md` - `/work/input/incoming/` - `/requirements-first` - `user_review_required` ## Controlled language Use clear and consistent language in all outputs. When writing in English, follow the main principles of ASD-STE100 Simplified Technical English: * Use short and complete sentences. * Express one main point or instruction per sentence. * Prefer active voice. * Use the same Term for the same concept. * Avoid unnecessary synonyms, idioms, metaphors, and vague references. * Put conditions before the actions that depend on them. * Use numbered steps for sequential instructions. * Explain abbreviations when they first occur. When writing in another language, apply equivalent principles naturally in that language. Do not copy English-specific grammar rules into other languages. The controlled Platform Terms in this Rule and in `/gov/knowledge/Terminology.md` take precedence over general ASD-STE100 vocabulary. Do not mention to the User that you are using this Controlled language, just apply it. ## Practical Rule When unsure, use the relevant definition from `/gov/knowledge/Terminology.md` and prefer the controlled Term over a near-synonym. ## Related files * Knowledge with the canonical list of Terms: [Terminology](/gov/knowledge/Terminology.md) ``` Register it in `_Index.md` ... ```md [<] Filesystem agents/ └─ tba/ └─ gov/ └─ rules/ └─ _Index.md ``` ... with this list item: ```md [< copy wrap] Markdown * `Terminology-to-use.md`: Shared terminology and usage guidance for the Terms used throughout the Filesystem and our communication. Read first once per Session to create a consistent language in Sessions and files. ``` Done? Then let's tackle the next Governance item. ### File handling [files] _We need to align how the Agent handles files and their paths._ Remember the goal we have to be Harness-agnostic? It is important, because we want our Agent to work on any platform with any Harness. Since the various Harnesses out there load files differently, we have to agree on how to link, use, and document files. [!Steps] #### File handling [files-rule] _We add a Rule that tells the Agent how to handle files._ In the `gov/rules/` folder ... ```md [<] Filesystem agents/ └─ tba/ └─ gov/ └─ rules/ └─ Session-file-handling.md ``` ... add this file: ```md [v copy nowrap] Session-file-handling.md # Session file handling _This Rule contains instructions you need to handle files in our Sessions._ ## File paths Governed paths are notation only. When passing a governed path to a Harness filesystem tool, shell command, or script, remove the leading slash and resolve it relative to the Engine working directory. The leading slash only indicates the Harness's working directory. Example: - governed path: `/gov/rules/_Index.md` - tool path: `gov/rules/_Index.md` - absolute path: `/gov/rules/_Index.md` Never pass governed paths like `/gov/...` or `/tools/...` directly to Harness filesystem tools. For file writes and file edits, also apply the active Harness-specific Rule when one exists. Harness-specific Rules may define a stricter or safer conversion from governed paths to Harness tool paths. When writing inside the active Workspace, prefer relative Workspace paths such as `work/reports/...`. Do not write machine-expanded paths such as `/Users//...` into the Governance, Reports, Logs, or any other Workbench artifacts. ## Read once A Governance file counts as read when its complete contents are available in the Agent's current Session context. This includes contents supplied automatically by the Harness through configured instructions as well as contents retrieved using a filesystem capability. When a Governance file has been read in the current Session, treat it as known for the rest of that Session. Do not retrieve it again merely to satisfy an instruction to read it. Re-read only when: - the file may have changed - the Session was compacted or pruned and exact content is needed again - exact wording or line references are needed - the User asks to re-check it - a new Session, subagent, or separate Harness context is started - the Agent has a concrete need to re-read, or a reason to doubt the retained content ``` Register the Rule in ... ```md [<] Filesystem agents/ └─ tba/ └─ gov/ └─ rules/ └─ _Index.md ``` ... with this list item: ```md [< copy wrap] Markdown * `Session-file-handling.md`: Handle files in our Sessions, specifically on how to interpret file paths in the Governance and on when to re-read files. ``` Let's move on to the next Governance item. ### Requirements [requirements] _We prevent the Agent from hallucinating what you might want by making it ask what you do want._ In case the Agent does not have all information it needs (through the Governance or your chat with it), we want the Agent to complete its understanding by asking you targeted questions first. [visit:Prompts/ask] > We will re-use the [Ask Protocol](https://homepage.sefzig-net.workers.dev/prompts/ask) prompt. [/visit:Prompts/ask] [!visit:Prompts/ask] > Hallucinate once, shame on you. > Hallucinate twice, shame on me. [/!visit:Prompts/ask] Let's set that up next. [!Steps] #### Requirements [requirements-first] _We add a Workflow that defines requirements engineering._ In the `gov/workflows/` folder ... ```md [<] Filesystem agents/ └─ tba/ └─ gov/ └─ workflows/ └─ Requirements-first.md ``` ... add this file: ````md [v copy nowrap] Requirements-first.md # Workflow: Requirements First ## Purpose Ensure a User's Wish is understood well enough before a Result is written or a Reaction is put out. ## Invocation Canonical Workflow name: `Requirements first`. Natural-language examples: * "Clarify the requirements before changing files." * "Let us harden our assumptions." * "Check whether this task is clear enough to implement." * "Have you understood what I want?" Required input: * The User's Wish * Session Context ## Procedure _This section describes the procedure you will apply to ambiguous User Wishes._ ### Trigger Apply this Workflow whenever the User expresses a Wish, but the information you need to unambiguously solve it is incomplete. ### Inputs These information needs to be available to run the procedure: * The User's Wish * Relevant Knowledge in `/gov/knowledge/` * Relevant Workbench information in `/work/` * Eventually better suited Workflows in `/gov/workflows/_Index.md` Read the relevant files only once per Session. ### Steps These are the mandatory steps you need to take to deliver the outcome of the procedure. 1. Review the User's Wish. Look up the relevant Workbench files in `/work/` (once per Session). Understand scope and gravity. Make Assumptions needed to reach the Result/Reaction. 2. Decide whether another Workflow in `/gov/workflows/` is suitable for delivering the Result/Reaction. Check `/gov/workflows/_Index.md` and look for a Workflow that is clearly better suited. If there is a better suited Workflow, stop this procedure and continue immediately with that Workflow. If there is no better suited Workflow, proceed here. 3. Decide whether the Wish is clear enough to proceed unambiguously (without Assumptions). If not, ask clarifying questions in the "Question" format below. Repeat until no Assumtions are left and the Wish is clear. 4. Decide whether you have all information necessary to produce the according Result/Reaction without guessing. If you haven't, read the relevant Knowledge in `/gov/knowledge/` (infer relevance from `/gov/knowledge/_Index.md`). If you still haven't, ask the User questions in the "Question" format below. Ask questions one by one, message for message. Repeat until you know all you need to know. 5. Review the User's Wish and the information is gathered: Do you know all you need to know to produce the Result/Reaction? If not, tell the User you still have Assumptions and ask the User questions in the "Question" format below. Ask questions one by one, message for message. If there are no gaps left, proceed. 6. Respond with your understanding of the User's Wish in the "Briefing" format below. ## Formats _These message templates are available for delivering the procedure._ ### Question This template is used to ask the User questions one by one, message for message. ```md **Question /**: 1. 2. ____ 3. ____ ``` Meaning of the : * `Resume`: If the question is not the first question, briefly re-iterate your understanding of the previous answer. * `NumberQuestion`: The amount of questions you have asked in this procedure, having started with 1. * `NumberQuestions`: Estimated total number of questions you will ask (allowed to change during the procedure). * `Question`: The question you need to have answered. * `Option1`: An option for the User to pick, in this case the option you recommend to pick. * `Option2`: An option for the User to pick, in this case the second-best option. * `Option3`: An option for the User to pick. * `Reasoning`: A brief rationale why you recommend to pick Option1 and how picking that option will advance the solution. The template aims at superior clarity for the User, guiding the Users expectation by showing the progress ("Question n/N: ..."), and simple answering by replying with the number of the chosen option. Allow the User to not answer with a number or to ask clarifying questions themselves, which you will answer before proceeding with the next question. ### Briefing This template is used to close the series of questions at the end of the procedure. ```md This is my understanding of your answers: This is my understanding of your Wish: > ``` Meaning of the : * `Response`: A sentence recognizing the completion of the procedure (thankful if there were more than 3 questions answered). * `List`: An unordered list of the choices the User made, with items rephrased to be brief and goal-oriented. * `Prose`: A short summary of how you now understand the Users Wish. * `NextStep`: A quick note on how this ties in with the further working on the Result or Reaction. * `Confirmation`: Ask the User for confirmation. The template aims at marking the completion of requirement gathering and restating the User's Wish in an intelligible, insightful way. Require the User to confirm your understanding before you proceed. Allow the User to request changes or add notes, in which case you will respond with an adapted Briefing message. ## Outcome Usually, the outcome of this Workflow should be a clear and aligned briefing for the next steps. Expected outcome: * A sufficiently clear re-briefing that is free of Assumptions, has a clear outcome, and is a stable basis for the next steps. * Confirmation of the User to proceed with the next steps. It may be the case that the ourcome of this Workflow is not clear enough to proceed unambiguously. Then: * Ask follow-up questions before proceeding to the next steps. * You may proceed with the next steps without follow-up questions only if the Result/Reaction scope is known, the requested outcome is clear, no conflicting guidance is known, and no missing detail would materially change the implementation; or if a better suited Workflow defines a clear path to deliver the User's Wish. ```` Register the Workflow in ... ```md [<] Filesystem agents/ └─ tba/ └─ gov/ └─ workflows/ └─ _Index.md ``` ... with this list item: ```md [< copy wrap] Markdown * `Requirements-first.md`: Apply when the User makes a Wish but it is ambiguous and-or information that is needed to proceed is incomplete, so that the Users requirements need to be clarified before proceeding. Use before any implementation of a User's Wish. ``` Let's move on to the next Governance item. ### Summary _Before we proceed, a quick summary on where we stand._ We now have an Agent that behaves well in general and behaves great in certain common situations. Specifically we have ... * added and registered the `Terminology.md` Knowledge and enforced it's use with the Rule `Terminology-to-use.md`. * added and registered the `Session-file-handling.md` Rule to make the Agent understand and use file paths properly. This is a milestone! > [Gold] > Goal achieved: Whitelabel Agent Next, we will implement your use case. ## Make it your Agent _Last, I will give you practical tips for your Agent._ Tba. ### Summary _To round up, a quick summary on what we achieved._ We now have an Agent that is set to behave well in general and behave great in certain common situations. > [Gold] > Goal achieved: Your first own Agent This is it!