Add self-hosted AI worker bootstrap

2026-05-24 03:44:23 +00:00
parent 6d7cc534c4
commit a7c50f651a
6 changed files with 276 additions and 0 deletions
@@ -0,0 +1,53 @@
+# Local AI Agent Guardrails
+
+These rules apply to any self-hosted AI coding assistant working on Agrarian.
+
+## Mandatory Behavior
+
+- Inspect existing project patterns before proposing changes.
+- Classify every task as `low`, `medium`, or `high` risk.
+- State evidence checked: files, docs, commands, logs, and build results.
+- Make the smallest useful change.
+- Do not refactor unrelated code.
+- Do not invent APIs or project conventions.
+- Do not merge directly to `main`.
+- Do not store secrets, private keys, wallet keys, passwords, or tokens in the
+  repo.
+- Passing tests/builds matter more than finishing the task.
+
+## Stop And Escalate
+
+Stop local work and prepare a Codex handoff when any of these are true:
+
+- confidence is below `0.65`,
+- tests fail twice,
+- build fails twice,
+- Unreal compile errors persist after one focused fix,
+- the task touches security, auth, payments, AGR wallet integration, save/load,
+  multiplayer, marketplace logic, migrations, or core engine architecture,
+- the diff touches more files than the brief allows,
+- local model context is overloaded,
+- the model cannot point to evidence for its recommendation.
+
+## Required Handoff Format
+
+```text
+Project:
+Branch:
+Goal:
+Risk:
+Confidence:
+Files inspected:
+Files changed:
+Commands run:
+Errors:
+What local AI tried:
+Why local AI stopped:
+Requested Codex action:
+```
+
+## Quality Bar
+
+Local AI is useful only when it is disciplined. It should be allowed to be
+uncertain, but it should not be allowed to be vague, overconfident, or
+unverified.
@@ -0,0 +1,74 @@
+# Agrarian Self-Hosted AI Development Stack
+
+This stack is meant to reduce pressure on Codex over time, not replace it
+immediately. The first production target is supervised local assistance:
+repository awareness, documentation, small safe edits, tests/builds, and clear
+Codex escalation when local tooling is over its head.
+
+## Current Services
+
+- Gitea:
+  `http://192.168.5.21:3000/nathan/agrarian-game.git`
+- Ollama:
+  `http://192.168.5.23:11434`
+- Open WebUI:
+  `http://192.168.5.26:8085`
+- Local AI worker VM:
+  `LinaAI / 192.168.5.27`
+- Primary Unreal/Linux development VM:
+  `unreal-engine / 192.168.5.20`
+
+## Current Local Model
+
+- `qwen2.5-coder:7b`
+- Role:
+  repo summaries, documentation, small patch suggestions, test generation,
+  straightforward scripts, and structured handoff preparation.
+- Not the role:
+  broad Unreal architecture changes, risky save/multiplayer/economy rewrites,
+  security-sensitive code, or autonomous merges.
+
+## Operating Model
+
+1. Local AI gathers context and proposes small changes.
+2. Work happens on a branch, not directly on `main`.
+3. The agent reports risk, files inspected, commands run, and confidence.
+4. Tests/builds decide whether a change is acceptable.
+5. After two failed local attempts, stop and escalate.
+6. Codex escalation uses the npm Codex CLI, not the API.
+7. Human review controls merges.
+
+## Codex Escalation
+
+Use `Scripts/ai_codex_escalate.sh` with a completed task status file. The
+script prefers a locally installed `codex` command and falls back to
+`npx -y @openai/codex exec`.
+
+Codex should be called for:
+
+- confidence below `0.65`,
+- two failed build/test attempts,
+- Unreal compile errors that persist,
+- tasks touching save systems, multiplayer, auth, payments, AGR wallet
+  integration, marketplace logic, migrations, or core architecture,
+- patches that grow beyond the intended small scope,
+- contradictions between local model output and official/project docs.
+
+## VM Boundaries
+
+- `LinaAI` owns local AI coding tools, Aider, Codex CLI escalation wrappers,
+  repo indexing, documentation generation, and small supervised branch work.
+- `unreal-engine` owns Unreal Engine source, editor builds, commandlets, and
+  game compile/package verification.
+- Keep these roles separated so AI tooling experiments do not destabilize the
+  Unreal build host.
+
+## Immediate Next Work
+
+- Verify Open WebUI model selection uses the Ollama backend at
+  `http://192.168.5.23:11434`.
+- Use Aider from `LinaAI`, not from `unreal-engine`.
+- Build project memory inside this repo under `Docs/` rather than creating a
+  separate documentation repository.
+- Add small local-agent tasks first: summarize systems, write docs, generate
+  tests, inspect logs, and prepare Codex handoffs.