Day 1.5 of AEGIS — The Invisible Infrastructure
On persistent context injection, PostToolUse hooks, and configuring the agentic workflow surfaces before writing a line of application logic.
The day I wrote zero features
Day 1 shipped a 13-table PostgreSQL ontology. Every column earned its place. Every provenance FK carries RESTRICT cascade so a source document can never be deleted without the evidence rows citing it raising an error first. It was deliberate, load-bearing work.
Day 1.5 produced no tables. No extraction logic. No schema migration. What is produced was a CLAUDE.md file, three slash commands, and a working PostToolUse hook.
If you are building a production system with an agentic coding assistant, that is not procrastination. It is the leverage play. The assistant’s operating environment is part of your architecture. Configuring it before writing application logic means every subsequent session starts correctly — not approximately correctly, not usually correctly. Correctly, by construction.
That is what Day 1.5 was. And this is what I built.
The problem: conventions that live in your head
Every LLM-assisted project accumulates conventions. In AEGIS, those conventions include things like: every fact-bearing row carries inline provenance columns; provenance FKs use RESTRICT not CASCADE ; Python is 3.11+, snake_case, plural table names; the docs/adr/ directory is append-only. These decisions are documented. They exist in ADRs, in a project spec, in a reference guide.
But every Claude Code session starts cold. The model re-derives context from whatever it can see. If you do not explicitly surfaces your conventions at session start, you are relying on the agent to rediscover them from scratch — or on yourself to paste the relevant context manually every single time.
A convention a human has to remember to inject is a bug waiting to happen.
Claude Code offers three surfaces that turn “please remember to..” into infrastructure the system cannot forget: project memory (`CLAUDE.md`), slash commands ( .claude/commands/ ), and hooks ( .claude/settings/json ). Each one moves a responsibility off human memory and into the system. Together, they form the invisible layer that makes the rest of the build tractable.
Surface 1 — CLAUDE.md: persistent context injection
CLAUDE.md is a file at the repo root that Claude Code automatically injects into context at the start of every session. It is not README. It is not documentation for humans. It is an operator-defined context payload specifically for the model.
Every line in CLAUDE.md costs context budget on every single turn. That constraint forces a discipline that READMEs never impose: curation, not completeness. You cannot dump everything into it. You have to decide what the agent genuinely needs to know to behave correctly without being told, and what can live in the ADRs and reference docs it can read on demand.
For AEGIS, CLAUDE.md contains:
- A mandatory read rule: “ALWAYS read AGENT_PRIMER.md before reading anything else in this repo.” — the single most important instruction, placed first.
- A two-paragraph project summary covering the mission and the dual-purpose build structure.
- A file map — not full documentation, just enough to orient the agent to where things live.
- Conventions that apply everywhere: provenance column pattern, JSONB for evidence blobs, cascade rule.
- Model selection cross-reference: Opus for planning and architectural choices, Sonnet for execution after the plan is accepted.
- A “don’t touch” list:
docs/reference/is frozen, root-level.mdfiles are Cowork-maintained,docs/adr/entries are append-only.
## Don't touch
- `docs/reference/` — frozen reference material.
- Root-level `*.md` files — Cowork-maintained; Claude Code does not edit these without explicit instruction.
- `docs/adr/` entries — append-only; write a new ADR rather than editing an existing one.That last section prevents the class of failure where an agent helpfully “improves” a frozen document and the edit is not caught until it has been committed. The agent sees it at session start, before any tool call, before any user prompt. It is not a hint — it is a constraint baked into the operating context.
Surface 2 — Slash commands: reusable agentic workflows
Slash commands ( .claude/commands/<name>.md ) are operator-defined prompt expansions. When you type /aegis-plan day-02-credit-memo-template in a Claude Code session, the entire contents of aegis-plan.md become the prompt, with $ARGUMENTS replaced by the string you passed. One keystroke. No copy-pasting.
AEGIS ships three commands:
/aegis-plan <day-slug>— reads the AGENT_PRIMER.md practice protocol and the specified chunk prompt file, then enters plan mode. This is how every new day starts: one command, full context loaded, planning mode active./aegis-status— prints the active phases row from PHASES.md and lists any day-prompt/aegis-recap <day-slug>— It runsgit logandgit diffto infer what was actually built, derives most fields automatically.
---
description: Fill the Practice Recap at the bottom of docs/prompts/$ARGUMENTS using
the AGENT_PRIMER.md §4 template.
argument-hint: <day-slug>
---
You are filling the Practice Recap at the bottom of `docs/prompts/$ARGUMENTS.md`.
Step 1. Read `AGENT_PRIMER.md` §4 for the exact Recap template.
Step 2. Read `docs/prompts/$ARGUMENTS.md` in full.
Step 3. Run `git log --oneline` and `git diff HEAD~1..HEAD --stat` to see what changed.
Step 4. Derive Date, Intended primary topic, Actually exercised, Drift check, and Cross-ref by inference — do NOT ask the user about them.
Step 5. Ask the operator EXACTLY ONE question — phrased verbatim as:
"What's the single thing you didn't know at the start of this chunk that you do now?"
Step 6. Write the completed Recap into the file.Two commands I deliberately did not build:
Get Chirag Venkateshaiah’s stories in your inbox
Join Medium for free to get updates from this writer.
/aegis-extract and /aegis-recon . Both were listed in the early mappings as illustrative names. The extraction and reconciliation modules do not exist yet. A slash command that derives a module that does not exist is ergonomic debt, not ergonomic leverage. Build the command when you have something for it to do.
Surface 3 — PostToolUse hooks: event-driven guardrails (the technical payoff)
Hooks are the surfaces most developers reach for last and the one with the sharpest behavior gap in the current documentation. Understanding that gap is the most transferable thing in this post.
A PostToolUse hook fires after a specified tool completes. In AEGIS, the hook triggers whenever Claude Code’s Edit or Write tool touches a file matching data/schemas/*.sql or data/seeds/*.sql . The intended behavior: remind the agent to re-run make schema-verify against the running PostgreSQL container before declaring the edit done.
The hook lives at .claude/hooks/schema-modified.sh . Here is the part that matters.
The version that seems to work but does not:
if echo "$file_path" | grep -qE "data/(schemas|seeds)/.*\.sql$"; then
echo "Schema or seed modified. Re-run make schema-verify before declaring done."
fiThis output text to the session transcript. The human operator sees it. The model does not. The guardrail silently does nothing.
The version that actually works:
if echo "$file_path" | grep -qE "data/(schemas|seeds)/.*\.sql$"; then
printf '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"Schema or seed modified. Re-run make schema-verify against the aegis-pg container before declaring done."}}\n'
fiThe difference is the output format. PostToolUse stdout is logged to the session transcript, but it is only injected into Claude’s context if it is emitted as structured JSON containing.
hookSpecificOutput.additionalContext . A plain echo satisfies the human eye. The model never sees it.
This is not documented clearly in the current Claude Code docs. If your PostToolUse hook feels like it is doing nothing, this is why. The hook needs to speak JSON to reach the model, not human-readable text.
Once the hook outputs the correct JSON, the behavior changes materially. After editing a schema file, Claude autonomously ran make schema-verify , inspected the output, confirmed the container was healthy, and only then marked the task complete. That is the guardrail working as intended — not as a reminder to the human, but as a verified step in the agent’s own workflow.
The pattern underneath all three
Stand back and the three surfaces share the same instinct.
CLAUDE.md moves session context off human memory and into the system. Slash commands move repeated multi-step workflows off human memory and into reusable verbs. PostToolUse hooks move verification steps off human memory and into event-driven enforcement.
Each surface answers a different version of the same question: what does the agent need to know or do here that it cannot be trusted to remember?
That instinct not new to AEGIS. Day 1’s ontology applied the same reasoning to data: every fact-bearing row carries its own provenance — source_document_id , page_number , confidence , extractor_model — because the alternative is trusting the downstream pipeline to remember where the number came from. It never does.
The workflow layer is the same reliability design, one level up. The provenance columns make the data trustworthy. The agentic surfaces make the development process trustworthy.
Honest scope: What I deliberately did not build
Infrastructure work is where over-engineering hides.
The design bar for Day 1.5 was: minimum that enforces discipline without nagging. By that standard:
- Two hooks, not five. A pre-commit lint hook would block commits during rapid schema iteraiton — net negative in Week 1. A test coverage hook has no target until Phase 2 introduces real modules. An eval-log hook is Phase 5 work. Two hooks is correct for now.
- No MCP server registration yet. The
aegis-ontology-mcpserver is Phase 2 work, alongside the first module that needs it. No stub created. - No subagent-specific hooks. The reconciliation orchestrator and its parallel subagents are Phase 3. Hooks for them land then.
- No
.claude/agents/directory. No stubs. This directory appears in Phase 3 with its first agent definition.
Every deferred item has a phase and a reason. None are forgotten. They are not built because the module that needs them does not exist yet.
Forward hook -> Day 2
The invisible infrastructure is in place. Every new Claude Code session in this repo now inherits AEGIS conventions automatically. Chunk launches are one keystroke. Schema discipline is enforced by the toolchain, not by memory.
Day 2 is domain immersion: studying the OCC’s Comptroller’s Handbook guidance on credit memo structure. The ontology was designed contract-first — I decided what the data model should look like before reading the regulator’s template in detail. Day 2 is where I find out whether that bet was right.
The infrastructure was the setup.
AEGIS is being built in public. The repo is at github.com/ChiragVenkateshaiah/aegis. Day 1 post: “Reviving a Name, Rebuilding the Mission.”
