The agent harness that got out of hand.
Personal by design, public as a reference, and never quite finished.
Arnesto is the versioned operating layer behind my AI-assisted work. It brings together instructions, executable tools, agent contracts, routing policies, evaluations, and local wiring so that different coding agents can share one coherent way of working.
It is not a universal agent framework or a polished distribution. It is a working system shaped around my environment, published so other people can inspect it, borrow from it, and adapt the useful pieces to their own stack.
Read how I organise my agent environment for concrete examples of rules, skills, context and runtime boundaries. More writing lives in Notes on saski.com.
The active AI detects learning without a save request: how-to guidance and directives go to the fitting Arnesto rule, skill, workflow, command, or policy; explanations and opinions I identify with go to my personal knowledge vault. It presents the exact proposed content and destination for my validation before saving, checking, committing, and pushing to the corresponding repository. The shared learning capture rule defines this behavior for clients that load Arnesto.
For complex, ambiguous tasks, shared clarification guidance helps me specify Goal, Context, Output, and Boundaries. The AI uses the context already available and asks only about material gaps.
Repository review: 2026-10-18. This describes checked-in mechanisms and documented experiments; provider health and installed runtime state require their own live checks.
| Area | What exists today | What remains open |
|---|---|---|
| Portable core | Progressive rules, shared skills, commands, OpenSpec, setup contracts, and local/CI validation | Keep client wiring and imported material aligned as tools change |
| Agent execution | A frontier-owned handoff to a constrained OpenCode worker, with model admission, execution limits, structured results, and local validation | Complete the shared multi-entry contract, including Cursor, a portable Hermes profile, and final acceptance evidence |
| Runtime integration | Separate Codex/Orca runtimes, Hermes remote entry, OmniRoute configuration, and explicit free-model lanes | Recheck volatile routes; configuration and past probes do not establish current availability |
| Coding interview practice | Candidate-led seven-stage pairing template, vertical TDD slices, code diffs, and explicit RED/GREEN review checkpoints | Keep guided practice separate from independent assessment; load interview-specific evidence from its project |
| Behavioural evaluation | Truthfulness cases and a pinned Promptfoo evaluator; one recorded Promptfoo case passed | Broader model/client comparisons and representative quality, cost, and correction measurements |
| Optional tools | Ponytail reuse guidance, CodeGraph navigation, and a Headroom compression fixture | Real-task benefit and integration quality remain unproven; these do not change global routing |
| Experimental surfaces | A documented AI Studio Android build/install workflow and an Orca trial | Orca acceptance evidence; Grok Agent remains a planned evaluation |
The project status and
active routing tasks
record the remaining work. The reusable coordination mechanism is
run-free-worker;
the archived provisional coordinator
is reference material.
Arnesto takes its cue from the Spanish word arnés —harness—. The name fits what the repository became: no longer a collection of configuration files, but the harness connecting an increasingly unruly set of tools.
The repository started in Q3 2025 as a fork of a coding-agent configuration. Each generation of tools changed what the repository needed to hold:
flowchart LR
rules["Rules<br/>shared behaviour"]
skills["Skills<br/>on-demand workflows"]
context["Context engineering<br/>planning + compaction"]
specs["OpenSpec<br/>durable intent"]
harness["Arnesto<br/>multi-tool harness"]
lab["Specialised and experimental edges<br/>AI Studio · Orca · Grok Agent · next"]
rules --> skills --> context --> specs --> harness --> lab
classDef origin fill:#f3f4f6,stroke:#6b7280,color:#111827
classDef growth fill:#ede9fe,stroke:#7c3aed,color:#111827
classDef current fill:#dcfce7,stroke:#16a34a,color:#111827
classDef labStyle fill:#fef3c7,stroke:#d97706,color:#111827
class rules origin
class skills,context,specs growth
class harness current
class lab labStyle
That evolution is the point. Arnesto preserves the stable lessons while letting models, clients, and orchestration experiments change around them.
flowchart TB
human["User"]
subgraph surfaces["Entry surfaces"]
codexApp["Codex"]
cursor["Cursor"]
claude["Claude"]
gemini["Gemini"]
telegram["Telegram"]
end
subgraph arnesto["Arnesto · versioned core"]
rules["Rules"]
skills["Skills"]
planning["Context + OpenSpec"]
policies["Routing policies"]
adapters["Adapters + templates"]
checks["Contracts + guardrails + evals"]
end
subgraph execution["Execution and routing"]
frontier["Frontier agents"]
hermes["Hermes"]
opencode["OpenCode workers"]
omniroute["OmniRoute"]
end
subgraph workbenches["Specialised workbenches"]
aiStudio["AI Studio<br/>Android build + install"]
end
subgraph experiments["Evaluation lab"]
orca["Orca"]
grok["Grok Agent · next"]
end
local["Local runtime state<br/>credentials · sessions · caches"]
human --> surfaces
surfaces --> arnesto
arnesto --> execution
arnesto -.->|project repository contract| aiStudio
aiStudio -.->|build + device evidence| arnesto
experiments -.->|evaluated against the core| arnesto
execution -.->|owns| local
arnesto -.->|never stores| local
classDef core fill:#ede9fe,stroke:#7c3aed,color:#111827
classDef active fill:#dcfce7,stroke:#16a34a,color:#111827
classDef labStyle fill:#fef3c7,stroke:#d97706,color:#111827
class rules,skills,planning,policies,adapters,checks core
class frontier,hermes,opencode,omniroute,aiStudio active
class orca,grok labStyle
The repository owns portable intent and repeatable behaviour. Each tool keeps its credentials, sessions, databases, trust state, and mutable preferences in its own runtime. The diagram groups responsibilities; client availability does not mean every client has completed the shared entry contract. Arnesto is the versioned core, and the user remains the actor above it.
AI Studio is a specialised workbench rather than another control plane. The Health tracking project validated a narrow workflow in which Codex and OpenSpec owned requirements, source changes, tests, and review in a canonical GitHub repository, while AI Studio synchronised that repository, built the Android app, and installed it on the phone. This preserved an auditable source of truth without requiring a local Android Studio, SDK, or ADB setup.
| Stable core | Specialised and experimental edge |
|---|---|
| Compact rules loaded progressively | Model and provider availability |
| Skills selected only when relevant | Routing combinations |
| OpenSpec for durable requirements and decisions | New entry surfaces and agent clients |
| Canonical repositories and review boundaries | AI Studio as an Android build and install workbench |
| Explicit runtime and credential boundaries | Orca evaluation |
Behaviour-level contracts and make check |
Grok Agent as the next exploration |
An experiment is not promoted because it looks interesting. It must solve a real problem, respect the existing boundaries, and survive a useful task with observable evidence.
An artifact's category describes its job, not necessarily its directory. A skill can bundle a script, an agent prompt, fixtures, and references. A policy states what is permitted; a guardrail is the mechanism that checks or limits execution. An instruction alone does not provide that enforcement.
| Category | Purpose | Current examples and boundaries |
|---|---|---|
| Rules | Define baseline behaviour and when to load narrower instructions | .agents/rules/, exposed through client instruction files. Most are guidance interpreted by the agent; Codex's codex-default.rules is a separate client-specific command approval file. |
| Skills | Supply a reusable workflow only when the task needs it | .agents/skills/ is the shared library; Cursor-only skills have a separate inventory. The on-demand writing skills help remove AI writing patterns or revise a draft toward a natural ES/EN voice. Availability depends on client discovery and setup. |
| Commands and workflows | Provide explicit entry points and repeatable sequences | .agents/commands/ and .agents/workflows/. They describe procedures; they are not background jobs. |
| Specifications, plans, and research | Preserve requirements, decisions, tasks, and working context | docs/openspec/, the thoughts/ workspace, and its src/thoughts/ CLI. Active proposals, archived decisions, and accepted behaviour have different status. |
| Catalogs and provenance | Make capabilities discoverable and track ownership, source pins, and licenses | Domain routing, skill inventory, governance catalogs, skills-lock.json, and upstream locks. These describe inventory and origin, not measured effectiveness. |
| Category | Purpose | Current examples and boundaries |
|---|---|---|
| Scripts and CLIs | Perform deterministic operations | bin/, root setup/sync/validation scripts, and skill-local scripts/. A script performs work; its calling skill explains when and how to use it. |
| Agents and roles | Define an executor's responsibility, tools, limits, and handoff | The OpenCode worker profile and frontier/entry/worker contract are implemented. Skill-local worker/reviewer prompts also exist; there is no general agent registry or universal scheduler. |
| Adapters and tool connections | Translate a contract into a client or tool invocation | run-free-worker, codex-free, and MCP declarations. Shared MCP setup targets Cursor/Gemini; Codex owns its separate configuration. Declarations do not implement the external services. |
| Gateways | Provide messaging ingress or model/provider access | Hermes and OmniRoute run outside the repository. Arnesto versions overlays, wrappers, and operating procedures; each gateway owns its credentials and mutable service state. |
| Templates and wiring | Install portable defaults while preserving local configuration | templates/ and setup-symlinks.sh. Shared assets are linked; selected mutable configuration is seeded or merged, with local Codex model/effort choices preserved. |
| Hooks and operational automation | React to tool or repository events and maintain local services | The RTK hook, pre-commit hook, and Hermes watcher/update procedures. RTK reduces shell output; it does not enforce task privacy. |
| Category | Purpose | Current examples and boundaries |
|---|---|---|
| Policies and routing | Decide eligible work, models, privacy categories, and execution ceilings | Free-worker manifest, Codex routing guidance, and OmniRoute desired state. Advisory selection, adapter admission, and gateway fallback are separate decisions. |
| Contracts and schemas | Define valid inputs, outputs, roles, and failure semantics | Worker contracts, executable jq checks, OpenSpec specs, and Promptfoo's JSON Schema assertion. There is no central schema registry. |
| Guardrails | Apply checks and limits at specific execution boundaries | The adapter checks model admission and declared sensitivity, denies worker shell/delegation tools, applies limits, and checks newly dirty paths and validation results. allowed_files is a post-run check, not filesystem isolation; pre-existing dirty paths limit attribution. |
| Tests and evaluations | Verify mechanisms and sample agent behaviour | tests/, evals/, and make check. Local checks exercise contracts; live model evaluations run separately and consume provider quota. A passing fixture or one model case does not establish broad quality or safety. |
| Runbooks, execution evidence, and observability | Explain operation and preserve results that can be reviewed | docs/, structured worker results with usage/termination/validation fields, and project-owned coordination evidence. Raw run material stays in the project's ignored .lab/coordination/; Arnesto has no unified audit or telemetry service. |
Credentials, sessions, caches, trust databases, and personal memory are runtime-owned state rather than portable repository artifacts. Reusable task recipes and selected evidence belong to the project that owns the work.
These are candidate gaps to address when a real task justifies them, not implemented capabilities or commitments to build another platform.
| Area | Next useful step |
|---|---|
| Agent capability and handoff definitions | Complete the existing entry contract before deciding whether reusable role manifests need a registry. Make tools, ownership, escalation, and acceptance explicit. |
| Authorization and tool trust | Map each policy to its actual enforcement point. Evaluate coverage for untrusted tool/document content, sensitive data, and side effects; retain human approval where required. |
| Execution isolation and recovery | Improve attribution on already-dirty files, precise file permissions, interruption recovery, and rollback. Current post-run checks cannot prevent or undo every out-of-scope write. |
| Behavioural and routing evaluation | Expand representative cases across clients and models, including abstention and provider failures. Measure accepted outcomes, retries, correction effort, time, and consumption before automatic routing. |
| Observability and evidence lifecycle | Correlate task, policy decision, execution, review, and result with minimal metadata; define redaction, retention, and resumable evidence before adding dashboards. |
| Distribution and compatibility | Track client/plugin versions, provenance, upgrades, deprecation, and installation drift. Promote optional integrations only after a bounded, repeatable task demonstrates value. |
The full skill inventory deliberately stays out of this README. Discovery belongs to the active client and the domain routing catalog, not to a giant prompt loaded on every task.
For explicit Codex model, reasoning effort, Fast mode, or spending decisions, use codex-model-routing. It provides cost-conscious recommendations with acceptance checks and escalation criteria.
For Madrid municipal incidents, use madrid-avisos to prepare a report, submit it with authorization through an available browser, or check its status. See setup and validation notes for client availability.
For coding interview preparation, use ai-coding-interview and its reusable starting prompt. The candidate owns the contract, plan and accepted changes across seven stages: understand, define the contract, plan, RED, GREEN, select the next slice, and close with execution evidence. Reviews include the actual code diff and check results; revisions are followed by relevant checks. The candidate approves each transition and explicitly starts any timer.
Keep employer identities, recruiter evidence and interview-specific constraints in the preparation project. Shared templates remain employer-neutral. During a mock, implementation assistance applies only to designated AI tasks; guided practice does not establish independent readiness.
Start by reading the repository before installing anything. The setup script creates links under your home directory and seeds selected local templates.
git clone https://github.com/saski/arnesto.git
cd arnesto
make ci-checkIf the conventions fit your environment, install the managed links and run the complete local validation:
./setup-symlinks.sh setup
make checkMy local SSH remote uses the saski host alias:
git@github.com-saski:saski/arnesto.git
The setup recreates local shims such as ~/.agents/bin/openspec; mutable
runtime state remains outside the repository. Forking and removing the pieces
that do not match your tools is an expected way to use Arnesto.
The explicit Codex/Orca lane uses the tracked OmniRoute free-coding route
through codex-free. The OpenCode entry configuration selects
omniroute/combo/free-coding-v2, and the Hermes overlay defaults to
combo/free-coding-v2. The v2 combo's membership and selection policy are local
OmniRoute state. These entry aliases do not expand the bounded worker
adapter's separate model allowlist.
Fixed Laguna, MiMo, HY3, and Big Pickle pins remain available for Codex diagnosis.
See the
runtime-boundary guide for configuration
and the data-safety boundary. The older free-stack and free-deterministic
combos are retired and must not be recreated.
- Coordination artifacts — project-owned recipes and evidence, local execution logs, and a provisional launcher reference.
- Architecture snapshot — architectural boundaries recorded on 2026-08-19; use current templates and routing tasks for subsequent configuration and acceptance changes.
- Development guide — repository structure, skill governance, setup, and validation.
- Promptfoo evaluation — check that Arnesto reports unexecuted validation honestly.
- Promptfoo skill — choose and design behavioral evaluations for prompts, agent rules, and models.
- TypeSafe AI skill — design and build applications with TypeSafe's typed AI judgments using current vendor docs.
- Token-efficiency tools — existing RTK and Caveman coverage, scoped Ponytail guidance, and optional CodeGraph/Headroom integrations with bounded local verification.
- Hermes, OmniRoute, and Telegram operations — the current remote-entry runbook.
- Runtime boundaries — why Codex, Orca, Hermes, and OmniRoute keep separate mutable state.
- Project status — what is stable, under evaluation, and deliberately deferred now.
- Keep universal instructions small.
- Load specialised knowledge only when the task needs it.
- Preserve intent and decisions outside transient chat context.
- Prefer explicit routing and visible failure over magical fallback.
- Keep credentials and mutable runtime state with the tool that owns them.
- Promote experiments only after they earn a place in the stable core.
All agent configuration instructions belong in shared .agents rules or
skills, not in one client's memory or configuration. Client adapters implement
that common policy while credentials and mutable runtime state remain local.
Each authorized Arnesto update includes validation, a scoped commit, a push to
the Arnesto remote, and verification of the published commit. Failed checks
block publication; unrelated changes are preserved. The shared communication
default is concise, natural prose, with lists for scripts, meeting support, and
study material. Personal facts and reusable knowledge remain in the personal
knowledge vault.
Client-specific instructions such as Codex with Astra remain owned by Arnesto and load only for the matching client/model.
Arnesto grew from Eduardo Ferro's augmented-code configuration. The complete Git history preserves that origin. The former fork remains archived as a public migration and provenance record.
Unlicense — public domain.