Language
YOUR AGENTIC ENVIRONMENT / A Field Guide / Companion to the setup doc ORIENT·01

Your Agentic Environment — A Field Guide

A personal team of AI experts for your homelab, code, and ideas

Before your AI walks you through building it, here's the shape of the thing: what it is, why it's built this way, and how the pieces fit. This is the what & why — not the how. Read it like a map.

1

What this is

The elevator pitch — one idea, two states.

Instead of
One general AI chat that forgets, doesn't know your rules, and answers from a blank slate every time.
You get
A versioned, personal team of specialized AI agents that share memory, follow your rules, and get sharper over time.

Not a chatbot — a small, governed, self-improving AI org that's yours.

It lives in a git repo

Versioned and backed up from day one — you can read it, diff it, and roll it back.

It plugs into Claude Code

Built on familiar primitives — subagents, slash commands, hooks. No new app.

It adapts to YOUR stack

Nothing here is prescribed — your AI interviews you and tailors every specific.

2

The five pillars

Five ideas hold the whole thing up. Everything else is detail.

Pillar 01

Expert subagents

Narrow, role-scoped specialists instead of one do-everything prompt. The infra agent thinks like an ops engineer; the security auditor thinks like an adversary. Each is good at its lane and stays in it.

scoped rolesno jack-of-all-trades
Pillar 02

Layered memory

Semantic (facts that are true now) + episodic (a decision journal) + procedural (skills & checklists) — with time-awareness so it doesn't silently go stale and start lying to you.

semanticepisodicprocedural+ time-aware
Pillar 03

Governance

Always-on rules: no silent behaviour changes, strict secret hygiene, and human approval for anything risky.

your rulessecrets stay safe
Pillar 04

Self-improving loop

Agents flag friction → you run a periodic review → they get coached and improve. Compounding, human-triggered, no always-on daemon.

compoundsyou trigger it
Pillar 05

Grounding

Agents look at reality — your repos, optionally live systems — instead of guessing. You choose the blast radius.

see, don't guessyou set the limits
3

The roster

Who's on the team — and what each one is trusted to touch.

Infra / Ops expert

RO → RW

Knows your homelab. Starts read-only; you decide if it earns write access.

Dev expert(s)

RW

Writes and refactors code in your repos, following your conventions.

UI / UX designer

RW

Designs and builds interfaces with a committed point of view, not templates.

Security auditor

READ-ONLY

Hunts for risks and leaks. Reports them — never edits anything itself.

Devil's advocate

READ-ONLY

Argues the other side and pokes holes in plans before you commit to them.

Product / Idea partner

READ-ONLY

Helps you turn raw ideas into shaped specs. Thinks with you, doesn't ship.

Remediation planner

READ-ONLY

Turns audit findings into an ordered fix plan. Plans the work; doesn't do it.

Engineering-manager

PROPOSES

Runs the review and coaches the roster. Proposes changes — you approve them.

› runs the self-improving loop
The principle to remember
Read-only by default; write is a privilege — and the agent that decides what to change never applies it unattended. The reviewer is never the applier.
4

The self-improving loop

The heart of it. A closed cycle with one explicit human-approval gate.

1

Capture friction

While you work, agents flag what got in the way — a missing fact, a gotcha, a correction you had to make.

2

Journal — local & private

Those notes accrue into a local, private decision journal. It's read only at review time, so it never bloats your day-to-day startup.

3

You run /eng-review

Periodically — and only when you choose, never on a timer — you kick off the review.

4

Engineering-manager proposes coaching

It reads the journal, finds patterns, and proposes concrete improvements to memory, skills, and agent instructions.

★

You approve the diffs human gate

Nothing changes until you say yes. Then the agents improve — and the loop returns to Capture, a little sharper.

It compounds — but only if you actually run the review. A start-of-session nudge reminds you when retros are piling up.

5

Memory architecture

Three layers, each with a different job. Together they make it remember.

It stores the non-derivable — not what's already in your code.

Memory captures gotchas and decisions: the things you'd otherwise re-explain every time. It deliberately doesn't duplicate what an agent can just read from your repo.

⏱ Time-aware on purpose

Each layer knows roughly how fresh it is — because staleness is silent. Old facts get flagged and pruned at review, so the system never quietly lies to you.

6

How setup works

You don't build it all at once. You grow it as real friction tells you to.

  1. Interview

    Your AI interviews you

    It asks about your domains, stack, conventions, guardrails, and risk posture — so everything that follows fits you, not a template.

  2. Scaffold

    It scaffolds a clean git repo

    A tidy structure, committed and backed up from day one — so your knowledge is never sitting in a single fragile local folder.

  3. Start small

    Begin with 2–3 agents you'll actually use

    Not the whole roster. The two or three roles that match what you do today, so the thing is useful in week one.

  4. Add the loop

    Add the self-improving loop

    Once you have agents worth coaching, wire up the journal and /eng-review. Now the system starts getting sharper on its own cadence.

  5. Expand

    Grow as real friction tells you to

    Add domains and agents when you actually hit a wall — never speculatively. The journal will show you where the friction is.

Build the smallest useful thing, use it, and let friction guide what's next.

Start here

Get started

This page is the what & why. This guide ships with a companion setup doc for your Claude Code — a single Markdown file, agentic-setup-bootstrap.md, that it reads and executes to scaffold the repo, interview you, and stand up your first agents.

Get the setup doc agentic-setup-bootstrap.md →
  1. Save it where your Claude Code can read it — your project folder, or your home directory (~/).
  2. Give Claude Code this instruction and let it take it from there: Read agentic-setup-bootstrap.md and set up my agentic environment.
7

Principles & anti-patterns

Keep these on the left. Watch for the ones on the right.

✓ Do

The habits that compound

  • ✓Commit + back up from day one — the repo is your source of truth.
  • ✓Generate your self-description from the live tree, so it never lies about itself.
  • ✓Read-only by default — grant write deliberately, role by role.
  • ✓Capture the human's corrections — your fixes are the highest-signal memory there is.
  • ✓Prune stale memory at review, so old facts don't quietly mislead.
  • ✓Human approves every change — the gate is the point, not a speed bump.
✗ Avoid

The traps that rot the system

  • ✗A source-of-truth repo with no backup — one disk failure from gone.
  • ✗Hand-maintained docs that rot — they drift out of sync and start lying.
  • ✗Dead / unused agents cluttering the roster with config that never fires.
  • ✗Capture with no review — a journal nobody reads is just noise.
  • ✗Agents grading their own work — "all went great" is noise, not signal.
  • ✗Always-on agents with broad access — the largest blast radius for the least gain.