Architecture & Job Description
How AI agents work here — the system that orients every Claude session, enforces the rules deterministically, and gets smarter with use. This is the document a new developer or employee reads to understand the whole board before touching a file.
The principle
This is a brand-new build. One GitHub repository is the spine and the backup — if everything else is lost, an agent re-orients itself by pulling the repo. The architecture deliberately uses Anthropic's native Claude Code primitives to do the jobs that custom servers and databases used to do. Infrastructure is added only when a concrete bottleneck proves it is needed — never on faith, never "just in case."
The payoff: less to maintain, fewer things that break at 2 a.m., a smaller security surface, and a system any new machine can install in one step. Each piece of the brain goes to the primitive that matches how it should load and how much authority it carries. Facts that are always true → CLAUDE.md. Procedures invoked on demand → skills. Things that must never happen → hooks.
Section 1
Two divisions, three employees. Each division has its own prompt; each employee has their own folder and prompt that layers on top.
Design, build, and deploy software. The engineering arm — the plan → build → review → ship → reflect discipline lives here.
Run a website and social-media company. Content, SEO, publishing, and the social cadence — the marketing and operations arm.
Every Dev project starts from a template build. No project begins on a blank page — it begins from the standard scaffold, so structure, conventions, and guardrails are consistent from the first commit. The work is configuration on a known base, not greenfield each time.
Every failure is logged, and every attempt must be a DIFFERENT method class — a different kind, not a retry of the same thing (running the same command ten times is not ten attempts). A failure is not surfaced before attempt 10 — except destructive or irreversible operations, which stop at attempt 1 and surface immediately. The escalation runs: direct method → MCP equivalent → alternative endpoint → auth refresh → shell/Python workaround → browser automation → system automation → fresh-context subagent → different model. An Intelligence Surge fires at the attempt-9 failure: an Opus-class model acts as analyst only (never executor), reviews the full attempt log, names the root-cause pattern, and proposes exactly one untried approach for attempt 10.
The destructive-op carve-out (stop at attempt 1) is the same set of actions locked by the Iron Clad hooks in the Hooks section — the 10-Attempt Rule and the hooks agree: destructive actions never get retried; they stop and surface.
Each person gets their own folder under /employees/. On a person's first session, an onboarding skill interviews them once and writes their prompt — calibrating how the agent shows up for them (directness, pushback, reasoning depth, what they own, what needs sign-off). After that, the questions never fire again.
Section 2
Anthropic's vocabulary, used precisely. For each: what loads when, what it costs, and what job it does.
Identity and stable facts: who the org is, the two divisions, the three employees, and brand and infra facts. Kept deliberately tight — it is read on every turn, so every line is a recurring tax. It holds only what must be true in all sessions; everything else lives in a primitive that loads on demand.
Instructions that load only when a matching file is touched — WordPress conventions load when you're in WordPress files, auth conventions when you're in auth files. They cost nothing the rest of the time. The global always/never rules also live here as the baseline that applies regardless of path.
The know-how layer. Only a skill's name and description load at startup; its full body loads only when the skill is invoked. That means many skills can exist at near-zero standing cost. The skills layer here is rebuilt as our own — modeled on proven patterns, but native to this system, not cloned or installed:
Rebuilt as our own, this skill lets the agent consult external models when a second opinion is useful. But every call to an external model is gated behind an explicit permission prompt each time — the agent asks before any external-AI call and proceeds only on a yes. That keeps the flexibility while honoring the "no external-AI calls without permission" rule. The gate is enforced as a hook, not merely stated.
A subagent does a job in its own fresh context window and returns only a summary to the main session. This is how code exploration and parallel work happen without polluting the main context: a codebase can be explored in depth, and the Council of 5 (Section 3) runs each of its five lenses in its own context — only the verdict or the relevant finding comes back clean.
The guidance is explicit: a "never do this" instruction is the wrong tool. Under pressure, in a long session, or because of a prompt injection in a file accessed as part of the task, the model can fail to follow a prompted rule. A real guardrail must be deterministic — and the enforcement methods are hooks and permissions. A PreToolUse hook can inspect a call and exit with code 2 to deny it. For the org-wide locks, managed settings are admin-deployed, cannot be overridden by a user's local config, and are the only way to enforce a deterministic, organization-wide guardrail. This is the difference between a sign that says "don't" and a lock.
The five hook-enforced rules: never move money; never run destructive commands on live data without confirmation; never hardcode a credential into a file; never publish or send without confirmation; never call an external AI without permission.
Learnings are written to files, committed to GitHub, and loaded at session start via a SessionStart hook — the closed loop that makes the brain compound instead of just persist. Each entry is tagged by how it is known, so future sessions can weigh it honestly:
Never write a secret into memory. If a learning needs a credential to be useful, name the secret's location (which vault), never its value.
A plugin bundles CLAUDE.md, rules, skills, subagents, and hooks into one installable unit, distributed from a GitHub marketplace. The sequence matters: build the pieces first, prove they work, then bundle them into a plugin. Building plugin-first means debugging packaging and content at the same time. The repo stays the spine throughout — the plugin is the delivery wrapper that lands every piece in the right slot on a new machine in one step.
Section 3
The decision layer. Whenever there is more than one viable path on anything consequential, the Council votes — five independent lenses, each running as its own subagent in isolated context, returning only a structured vote. It exists to prevent solo calls on consequential decisions, and it cannot be reasoned around.
Real isolation is the point: five subagents in separate contexts can genuinely disagree; one model voicing five roles in a single context cannot truly argue with itself. Each seat holds one lens and resists the others.
Every seat returns exactly one vote and nothing else — no essays. A seat that errors degrades to flag / 5, never a silent pass.
One-sentence rationale, forced — the value is five sharp independent reads, not volume. All seats run on a fast, cheap model (claude-haiku-4-5) on purpose, so a non-negotiable law actually gets used under time pressure.
Any single seat votes block → full stop. Surface to the operator with the complete vote table. Do not proceed.
Any seat votes flag, none block → revise to address the flag(s), then proceed.
All five seats pass → execute with confidence.
The Council advises; it does not act. Any action that follows still passes through the normal rules and confirmation gates. Seats return only their vote — never secrets, raw file contents, or credentials.
Section 4
What happens, in order, from the moment a session opens to the moment it closes.
SessionStart hook fetches the latest from GitHub so the agent begins on current truth — the spine is always the source.CLAUDE.md → rules → memory. Identity, always/never rules, and tagged learnings load before any work.node-solutions-dev.md or node-solutions-ops.md).PROMPT.md. If no profile exists yet, the onboarding skill runs once, writes it, commits it, and never fires again.EYES CONFIRM —Method: what was used to verifyEvidence: the actual observed value, not "looks good"Status: VERIFIED / PROXY (direct not possible) / FAILED — retrying/health returns 200 + non-empty body), file (exists and non-empty), cron (pattern found in crontab -l), api (GET returns any 2xx). When direct verification is impossible, use the strongest proxy (API response, log entry, status endpoint) and say so explicitly — never silently skip.SessionEnd hook reviews the session, appends tagged learnings to memory, prunes what became false, then commits and pushes — the backup and the compounding step in one.Section 5
The always/never rules — and, critically, which "never" rules are enforced as hooks rather than merely written down.
HOOK = enforced deterministically by a PreToolUse hook that inspects the call and exits with code 2 to deny it. These are not instructions the model is asked to follow — they are locks it cannot pass. The org-wide set is deployed via managed settings so a local config cannot override them.
Section 6
The external systems each division reaches into — the "hands." Two sets, one per division. The standing rule holds across both: anything that changes the outside world — a deploy, a push, a publish, a send — requires confirmation, unless a property is explicitly set to auto.
These are deploy and build targets the Dev agents reach into — distinct from the brain itself, which still runs no persistent server of its own.
Claude has no built-in vault by design: an AI agent should never be the system of record for secrets, since it is the most injectable surface in the stack. So credentials live in an external secrets manager and are referenced at runtime — never stored in the repository, a file, or the chat. This system supports two: Infisical (self-hosted) and 1Password. The agent reads a secret only when a task needs it, and the actual values never leave the vault. This is enforced, not just stated — the "no hardcoded credential" guardrail runs as a PreToolUse hook that blocks any command writing a key, token, or password into a file.