This appendix is written so that an artificial intelligence agent can follow it step by step and set up a minimal business factory on a computer, with ordinary files and commands. Whoever reads it can hand it to their agent as is. The code blocks are copied as they are; whatever goes between < and > is replaced, and the uppercase variables at the top of each script are adjusted once.
The guide builds the essentials: folders, rules, sessions, permissions, each role's work in git, the approvals ledger, the data store, an outfitted connection and a routine. What requires a provider (a cloud machine, a cloud browser, a secrets vault) can be added later; for each one, an open option is given first, when one exists, and then a commercial example.
What it takes
- A computer with
git(2.28 or later, forinit -b) andpython3. - An agent harness: a program that runs an artificial intelligence agent in a folder, that reads the
AGENTS.mdfiles in that folder and in the ones above it, and that accepts a permission list per session (what it can read, write and run). If it can also run sessions in the background and send messages between them, all the better. For example, OpenCode (open) or Claude Code. - A git server for each role's work. To start, bare repositories on the same computer are enough; later, a git server that can be self-hosted (for example, Forgejo or Gitea).
- Optional, for the data store: DuckDB, with the DuckLake extension.
Nothing in this guide requires spending money or connecting to an outside service.
Step 1. The folders
Create one folder per business. Inside it, a dot folder for what belongs to the business factory and one folder per role for what belongs to the business. Each role's work/ folder is not created here: it comes from cloning its repository in step 5.
NEGOCIO=horizonte
ROLES="owner ventas"
mkdir -p "$NEGOCIO/.factory"
for r in $ROLES; do
mkdir -p "$NEGOCIO/$r/.assets" "$NEGOCIO/$r/.sessions/as-routine" "$NEGOCIO/$r/.sessions/at-task"
done
mkdir -p "$NEGOCIO/owner/.sessions/with-person"
The resulting tree, once steps 2 to 7 are complete:
horizonte/
AGENTS.md # the business: who is who, what each person decides
.factory/ # how every business factory works: nobody in the business writes it
AGENTS.md # common rules (step 2)
settings.json # base permissions (step 3)
launch.sh # starts a session (step 4)
ok-check.sh # checks an approval (step 6)
owner/ # the coordinating role
AGENTS.md
work/ # clone of its repository (step 5)
approvals/ # the approvals ledger
board/ # one file per request in progress
inbox/ # what the roles send it, if the harness has no messages
state/resume.md
.assets/
.sessions/
with-person/<person>/ # each person's owner conversation
as-routine/ at-task/
ventas/ # a leader (Sales)
AGENTS.md
work/ # clone of its repository
routines/ outbox/ state/resume.md
.assets/
.warehouse/ # its data store, outside git (step 7)
.sessions/
as-routine/<routine>/ at-task/<task>/
The rules of the structure:
- a name with a dot belongs to the business factory; one without a dot, to the business;
- each role writes only in its own
work/(and in its.warehouse/); what it needs from another role, it asks for; - inside
work/, at the root, there are only folders, and one file per thing; .sessions/is not written by hand:launch.shfills it in;- to clone a business factory, the repositories of each role are enough (plus its data store); everything else is generated again.
To verify it: find horizonte -maxdepth 2 -type d shows .factory, one directory per role and their .assets and .sessions.
Step 2. The common rules
horizonte/AGENTS.md describes the business: who each person is, which roles they have access to and what they decide. .factory/AGENTS.md is what every session reads in addition to the business's file and its role's. It should be short (chapter 5). A template:
# How this business factory works
## Sessions
- Main: one per role. Does the role's work and saves it in work/. Belongs to no person.
- Owner: each person's conversation with the coordinating role. It is the only one that asks a person anything.
- Routine: one per routine. Talks only with its role's main session.
- Task: a piece of work with an end, opened by a main session. It closes when its work is in work/.
## Who talks to whom
- Routines and tasks: only with their role's main session.
- Leaders' main sessions: with owner; with each other, only for a question or its answer.
- A new request for another area goes through owner, which decides whose it is.
- Whatever passes from one person to another stays in the role's work/.
- Channel: the harness's messages between sessions. If the harness has none, the sender writes a file
in its own work/outbox/<date>-<topic>.md and the receiver reads it (owner reads every outbox/).
## How to talk (first line of every message)
TELL · nobody owes anything
ALERT · it matters now
ASK · the receiver owes an answer (with a recommended option and what happens with each one)
NEED · the receiver owes an answer now (say what is blocked)
PROMISE · due <time or event> · the sender owes the delivery
Closings: DONE · <evidence> | CAN'T · <reason> | RENEGOTIATE · <new deadline> | REDIRECT · <to whom> | CANCEL
Before starting on a request: «I understood: … ; it is done when …».
Before asserting a cause: verify it, or say it is a hypothesis.
## Autonomy
1. It can be undone without anyone noticing: do it and report it.
2. Real but bounded, with an automatic check: do it if the check approves it.
3. It cannot be undone or it is seen from outside (secrets, access, deleting, people, money, publishing): only with an approval from the ledger.
## Approvals
- A role that needs an approval sends owner a NEED with the exact action.
- Owner asks the person, writes the entry in approvals/ in its work/, pushes it and replies DONE · approvals/<id>.
- Before acting, the role runs .factory/ok-check.sh <id> and acts only on what «Covers» says. It cites the id in what it leaves done.
- When finished, the role sends owner DONE · approvals/<id> · <evidence>, and owner records the use in the entry.
## Saving
- Pull the latest before starting (pull --rebase); commit and push as soon as the work is done, in small changes.
- Every commit ends with the line «Side: <side>» given in your session's startup rules.
- Never force a push. If two changes collide and cannot be combined, push your own to a branch
conflict/<session>/<date> and alert the role's main session.
- Before stopping: write state/resume.md (doing, next step, open, waiting, due, not verified).
Only the main session writes state/resume.md; a routine writes only in its output folder.
And a role's AGENTS.md:
# <role> («<title>»)
What it does: <one or two lines, in the business's words>.
People with access: <who>.
## Its work
work/
<folder>/<one thing per file>.md
routines/<routine>.md
state/resume.md
## What it decides alone and what it asks
- Alone: <list of level 1 and 2 actions specific to the role>.
- Always with approval: <list of level 3 actions specific to the role>.
## Never
- <what the role does not do, even if asked>
To verify it: find horizonte -maxdepth 2 -name AGENTS.md lists four files (the business's, the one in .factory/ and one per role), and each role says what it does, who has access and what it asks.
Step 3. The permissions per session
What cannot fail is not written down: it is configured (chapter 10). .factory/settings.json holds the base list, with {root} and {role} as markers that launch.sh fills in. The paths are absolute, because not every session starts in the role's folder. The exact format depends on the harness; the idea is this:
{
"permissions": {
"allow": [
"Read", "Grep", "Glob",
"Edit(/{root}/{role}/work/**)", "Write(/{root}/{role}/work/**)",
"Edit(/{root}/{role}/.warehouse/**)", "Write(/{root}/{role}/.warehouse/**)",
"Bash(git -C /{root}/{role}/work status*)", "Bash(git -C /{root}/{role}/work diff*)",
"Bash(git -C /{root}/{role}/work log*)", "Bash(git -C /{root}/{role}/work pull --rebase*)",
"Bash(git -C /{root}/{role}/work add *)", "Bash(git -C /{root}/{role}/work commit *)",
"Bash(git -C /{root}/{role}/work push)", "Bash(git -C /{root}/{role}/work push -u origin main)",
"Bash(/{root}/.factory/ok-check.sh *)"
],
"deny": [
"Edit(/{root}/.factory/**)", "Write(/{root}/.factory/**)",
"Edit(/{root}/AGENTS.md)", "Write(/{root}/AGENTS.md)",
"Edit(/{root}/{role}/AGENTS.md)", "Write(/{root}/{role}/AGENTS.md)",
"Bash(env)", "Bash(printenv:*)", "Bash(ps:*)", "Bash(set)", "Bash(export)",
"Bash(echo *TOKEN*)", "Bash(echo *SECRET*)", "Bash(echo *KEY*)", "Bash(echo *PASSWORD*)",
"Bash(git push --force*)", "Bash(git -C * push --force*)", "Bash(git -C * push -f*)"
]
}
}
When each session starts, launch.sh adds to the deny list writing to the work/ of every other role, and it removes the harness tool for asking a person something from every session that is not a person's owner conversation. Reading stays open on purpose (owner and the roles read what they need); that is why no secret lives in the tree: secrets go to a vault (step 8).
To verify it: in the configuration generated for the main session of ventas (Sales), Write(/<root>/owner/work/**) and Write(/<root>/.factory/**) appear in deny.
Step 4. Starting a session
.factory/launch.sh gives each session its name, its folder, its rules, its permissions and its signature in git:
#!/bin/bash
# Usage: .factory/launch.sh <role> [with-person <person> | routine <routine> | task <task>] [harness args...]
set -euo pipefail
NEGOCIO=horizonte # the business's short name
HARNESS="${HARNESS:-echo}" # the harness command; echo for testing
ASK_TOOL="${ASK_TOOL:-AskUserQuestion}" # the harness tool for asking a person something
LADO="${LADO:-local}" # where this business factory runs (its side)
root="$(cd "$(dirname "$0")/.." && pwd)"
role="${1:?role}"; shift
kind=main; inst=""
case "${1:-}" in with-person|routine|task) kind="$1"; inst="${2:?name}"; shift 2 ;; esac
[ -f "$root/$role/AGENTS.md" ] || { echo "no such role $role" >&2; exit 2; }
[ "$kind" != with-person ] || [ "$role" = owner ] || { echo "with-person is only for owner" >&2; exit 2; }
case "$kind" in
main) cwd="$root/$role"; name="$NEGOCIO--$role" ;;
with-person) cwd="$root/owner/.sessions/with-person/$inst"; name="$NEGOCIO--owner--with-person.$inst" ;;
routine) cwd="$root/$role/.sessions/as-routine/$inst"; name="$NEGOCIO--$role--as-routine.$inst" ;;
task) cwd="$root/$role/.sessions/at-task/$inst"; name="$NEGOCIO--$role--at-task.$inst" ;;
esac
mkdir -p "$cwd"
out="${TMPDIR:-/tmp}/$NEGOCIO-factory"; mkdir -p "$out"
# The rules: who the session is, the common rules, the role and, for a routine, its definition.
{ echo "You are the session \`$name\`, of the role \`$role\`. Your work is in $root/$role/work."
echo "Every commit of yours ends with the line: Side: $LADO"; echo
cat "$root/.factory/AGENTS.md"; echo; cat "$root/$role/AGENTS.md"
if [ "$kind" = routine ]; then echo; cat "$root/$role/work/routines/$inst.md"; fi
} > "$out/$name.rules.md"
# The permissions: the base list, filled in for this session.
python3 -I - "$root" "$role" "$kind" "$ASK_TOOL" "$out/$name.settings.json" <<'PY'
import json, os, sys
root, role, kind, ask, dst = sys.argv[1:6]
s = json.load(open(f"{root}/.factory/settings.json"))
p = s["permissions"]
r = root.lstrip("/")
fill = lambda x: x.replace("{root}", r).replace("{role}", role)
p["allow"] = [fill(x) for x in p["allow"]]
p["deny"] = [fill(x) for x in p["deny"]]
others = [d for d in os.listdir(root) if d != role and not d.startswith(".") and os.path.isdir(f"{root}/{d}/.sessions")]
p["deny"] += [f"{t}(/{r}/{d}/work/**)" for d in others for t in ("Edit", "Write")]
if kind != "with-person":
p["deny"].append(ask)
json.dump(s, open(dst, "w"), indent=2)
PY
# The signature on each commit: the session's name.
export GIT_AUTHOR_NAME="$name" GIT_COMMITTER_NAME="$name"
export GIT_AUTHOR_EMAIL="$name@$NEGOCIO.local" GIT_COMMITTER_EMAIL="$name@$NEGOCIO.local"
cd "$cwd"
# The exact command depends on the harness (see the table «The same startup in three harnesses», below):
# it must receive the name, the rules file and the permissions file.
exec "$HARNESS" --name "$name" --rules "$out/$name.rules.md" --settings "$out/$name.settings.json" "$@"
The same startup in three harnesses
Each harness solves, under its own names, the same things launch.sh asks for. The table summarizes three, according to their official documentation as consulted on November 19, 2026; anything marked «(not verified)» does not appear as such in that documentation, and should be checked against the version installed.
| Claude Code | OpenCode | Codex | |
|---|---|---|---|
| Rules | reads the AGENTS.md files in the folder and in the ones above it only if there is no CLAUDE.md; a session's extra rules go with --append-system-prompt-file <file> |
reads the global AGENTS.md and the ones it finds going up from the folder; extra rules go in the instructions key of opencode.json |
reads AGENTS.override.md or AGENTS.md from the repository root down to the folder; extra rules, in developer_instructions in config.toml (with -c per session, not verified) |
| Permissions | settings.json, keys permissions.allow and permissions.deny (for example, Bash(git push *)); per session, --settings <file> |
opencode.json, a permissions list of {action, resource, effect} rules; per session, no documented option |
prefix_rule rules in .codex/rules/*.rules, plus sandbox_mode and approval_policy in config.toml; per session, -c or --profile |
| Removing the tool for asking | AskUserQuestion, in permissions.deny or with --disallowedTools AskUserQuestion |
question, with a rule {action: "question", effect: "deny"} (not verified) |
request_user_input (not verified: it does not appear in the official documentation, nor does a way to remove it) |
| Messages between sessions | SendMessage and ListAgents; regulated with crossSessionInbound |
none; use outbox/ and inbox/ (step 2) |
none between sessions; use outbox/ and inbox/ (step 2) |
| Headless start | claude -p "<request>" for one turn; claude --bg "<request>" for a background session |
opencode run "<request>"; background, no documented option |
codex exec "<request>"; background, no documented option |
With Claude Code, for example, the last line of launch.sh becomes this (the session's names go in the rules file, which already includes them):
exec claude --bg --append-system-prompt-file "$out/$name.rules.md" --settings "$out/$name.settings.json" "$@"
And there must be no CLAUDE.md anywhere in the business factory's folder, so that it reads the AGENTS.md files.
Sessions are started each day from their note (work/state/resume.md), not by continuing yesterday's conversation, and only those of the roles with something pending.
To verify it: HARNESS=echo .factory/launch.sh ventas prints the name and the two paths, and both files exist; launch.sh none ends with «no such role none».
Step 5. Each role's work in git
Each work/ is a git repository of its own. To start, on the same computer:
SRV="$HOME/git-srv/horizonte" # or the git server's address
mkdir -p "$SRV"
for r in owner ventas; do
git init -q --bare -b main "$SRV/$r.git"
git clone -q "$SRV/$r.git" "horizonte/$r/work"
done
# the folders of each work/ and the first commit (made by whoever sets up the business factory)
mkdir -p horizonte/owner/work/{approvals,board,inbox,state} horizonte/ventas/work/{routines,outbox,state}
for r in owner ventas; do
printf '# Where it left off\n\nJust set up.\n' > "horizonte/$r/work/state/resume.md"
touch horizonte/$r/work/{approvals,board,inbox,routines,outbox}/.keep 2>/dev/null || true
git -C "horizonte/$r/work" add -A
git -C "horizonte/$r/work" -c user.name=setup -c user.email=setup@horizonte.local commit -qm "Initial setup"
git -C "horizonte/$r/work" push -q -u origin main
done
The rules:
- each role has its own credential, with write access only to its repository; every role has read access to owner's repository (to read the approvals), and owner has read access to all of them;
- each session signs its changes with its name (
launch.shexports it) and ends each commit message withSide: <side>; - work is saved on
main, with no branches or reviews for the business roles; - the latest is pulled before starting and pushed as soon as the work is done;
- a push is never forced; a conflict that cannot be combined goes to a
conflict/<session>/<date>branch.
What is saved, and when:
| When | What |
|---|---|
| on finishing each piece of work | what was produced, in its file |
| on receiving a decision | the decision, quoted, in the file of the thing it decides |
| before a long piece of work | where things stand, in state/resume.md |
| before stopping | state/resume.md, up to date |
To verify it, after a session has committed: git -C horizonte/ventas/work log -1 --format='%an%n%B' shows the session's name and the Side: line.
Step 6. The approvals ledger
One entry per approval, in the approvals/ folder of owner's repository, named <date>-<nn>-<topic>.md:
# 2026-11-19-01-lens-promo
- Decided by: <person>
- When: <date and time>, in <owner session>
- Requested by: <session>, NEED of <time> («<action>»)
- Question: «<the question as it was asked, with its recommendation>»
- Answer, verbatim: «<what the person wrote, or the option they chose>»
- Covers (only this):
1. <the exact action: the command, the file, the service>
- Type: single-use | standing (class: <one line>)
- Valid until: used once | <event> | revoked
- Revokes: —
## Uses
The rules: what is not in «Covers» is not covered; one entry per decision, even when a batch holds several; only owner writes to the ledger, including the line for each use, when the role tells it DONE.
The role that acts checks the entry against the central repository, never against a copy that someone could have changed. .factory/ok-check.sh:
#!/bin/bash
# Usage: .factory/ok-check.sh <id> → prints the entry and VALID, or the reason; exits with 0 only if it is valid.
set -euo pipefail
id="${1:?id}"
OWNER_REPO="${OWNER_REPO:-$HOME/git-srv/horizonte/owner.git}"
cache="${TMPDIR:-/tmp}/ok-check-owner"
[ -d "$cache" ] || git clone -q --bare "$OWNER_REPO" "$cache"
git -C "$cache" fetch -q origin '+refs/heads/main:refs/heads/main'
entry="$(git -C "$cache" show "main:approvals/$id.md" 2>/dev/null)" || { echo "INVALID: approvals/$id.md does not exist"; exit 1; }
echo "$entry"
if git -C "$cache" grep -q "Revokes: .*$id" main -- approvals/; then echo "REVOKED"; exit 1; fi
if echo "$entry" | grep -q "Type: single-use" && echo "$entry" | sed -n '/^## Uses/,$p' | grep -q '^- '; then echo "USED"; exit 1; fi
echo "VALID"
To verify it: with a test entry pushed, the script says VALID; after owner records a use and pushes it, it says USED; with an id that does not exist, INVALID.
Step 7. Each role's data store
For data in table form, each role has a local database in <role>/.warehouse/ (outside git, because data files cannot be merged) and a central copy. With DuckDB and DuckLake, the central copy can be a catalog in SQLite or Postgres with the data in a folder or in object storage; a catalog on a DuckDB file does not accept several writers at once. The contract:
clone brings the full central copy into the local database
pull brings only the rows that changed since the last pull
push pushes only the rows that changed; each row is rejected if another session changed it since the last pull,
and the rejection stays in a conflicts table for whoever came second to review
The rules: each table declares its key (what identifies each row); each table has a single owning role, the only one that runs push on it; the other roles only read, and owner reads everything. «Whoever writes last» never wins.
To verify it: with two local databases of the same table, change the same row in both and check that the second push ends up in conflicts instead of overwriting the first.
Step 8. Outfitting a connection
Before a role is given an important system, the system is tested thoroughly and its loadout is put together (chapter 7). A template, in the role's work/connections/<system>/LOADOUT.md:
# <system> loadout for <role>
Test: <date> · what was covered · what failed
## Reads (validated)
| Tool | What it returns | Validated (correct runs / runs) |
## Writes (proposed, until a real case)
| Tool | What it changes | Autonomy level | Real case that would enable it |
## Skills
- How <system> is used (map, entry point, common tasks, pitfalls)
- How this business uses it
## Routines
- <routine>: what it reads, how often, what change deserves an alert
The system's credentials go in no file: a secrets vault keeps them (for example, OpenBao, which is open and can be self-hosted, or a cloud provider's secrets manager), and the session receives them only to call the service, ideally through an MCP gateway that reads them at the moment of the call. If the system is used through a browser, the person logs in, by hand, in a live view, and the login is saved in a browser profile (with Playwright and a browser of one's own, or with a cloud browser provider such as Browserbase); the agent then works with an instance of that profile that saves no changes.
Step 9. A routine
A routine is defined in the role's work, in work/routines/<routine>.md:
# <routine>
- Role: <role>
- Wakes on: schedule «<every business day at 9>» (time zone <zone>) | event «<exact type>»
- Purpose: <what it aims to achieve, in one line>
- Steps:
1. <…>
- Done when: <the signal that it is finished>
- Writes to: work/<output folder>/
- Alerts the main session only if: <condition>
A person creates it. It runs in its own session (launch.sh <role> routine <routine>), which receives the definition in its rules, with the role's connections, and writes only to its output folder. Whatever wakes it (a task scheduler such as cron, a board, a queue) needs a bridge that turns each event into a session start (chapter 19); without one, the routine never finds out.
A version for a single person
For an independent professional, the same guide builds a smaller business factory:
- the roles are their areas: for example,
owner,clientes(Clients),liquidaciones(Payroll and Taxes) andvencimientos(Deadlines) for an independent accountant; - a single owner conversation:
launch.sh owner with-person <their name>; - in the business's
AGENTS.md, the person appears with admin access to every role; - the approvals ledger stays in
owner/work/approvals/, even though the one who decides is always the same person: it serves to know, later, what was approved and in what words; - the data store (step 7) and the outfitted connections (step 8) are added when an area needs them.
NEGOCIO=estudio
ROLES="owner clientes liquidaciones vencimientos"
# the rest of steps 1 to 10, the same
Step 10. The first day
| # | Step | How it is verified |
|---|---|---|
| 1 | create the folders from step 1, with owner and one leader | find -maxdepth 2 -type d shows .factory, the roles, their .assets and .sessions |
| 2 | write the business's AGENTS.md, the common rules and the roles' files |
find -maxdepth 2 -name AGENTS.md lists four files |
| 3 | create the repositories, clone them and make the first commit | git -C <role>/work status -sb shows main...origin/main |
| 4 | write settings.json, launch.sh and ok-check.sh |
HARNESS=echo launch.sh ventas generates the right name, rules and permissions |
| 5 | start owner's main session and write its first note | owner/work/state/resume.md pushed, signed by the session |
| 6 | start a leader's main session, ask it for something and have it save it | the change appears in its repository, signed and with Side: |
| 7 | test the flow: have the leader send owner a NEED | owner receives it, asks, writes the entry in approvals/, and ok-check.sh reports it as valid |
| 8 | test a refusal: have the leader try to write to owner/work/ |
the harness refuses it by configuration, not by instruction |
| 9 | define a routine and run it once by hand | what it produces appears in its output folder |
| 10 | stop everything and start again from the notes | each session resumes from state/resume.md |
| 11 | optional: create a table in the data store and test the conflict from step 7 | the second push ends up in conflicts |
| 12 | optional: outfit a connection with the template from step 8 | the LOADOUT.md has validated reads and proposed writes |
In short, a minimal business factory is folders with short rules, sessions with their own name, signature and permissions, one git repository per role, an approvals ledger checked against the central repository, a data store with an owner per table, outfitted connections and routines defined in the work. Everything else is added on top of that base without changing it: an isolated machine that goes to sleep (with Firecracker, which is open, or with a sandbox provider such as E2B, Daytona or Modal), a cloud browser and a secrets vault.