Engineering Athena
Engineering intelligence on demand, in the form the work needs it:
Curated, kept current. Connect once — nothing is added to your repositories.
The problem
The standards exist — a 40-page PDF, a Notion space, a handful of ADRs. None of it is open in the editor at the moment the code actually gets written.
So the rules get copied into every repo. Eleven handbooks drift in eleven directions, and nobody can say which one is current anymore.
No owner, no review date, no way to tell a living standard from a fossil. Engineers stop trusting all of it — and they are right to.
Coding agents generate from their training data — the average of GitHub — not from your layering, your error contract, your migration policy. The output looks right, and is wrong in exactly the places your house style differs.
The usual answer is to install more: a skill per framework, a server per vendor, a rules file per repo. Each one eats context on every request, and each one needs an owner. The team ends up maintaining tooling instead of shipping.
All five have the same root cause. The knowledge lives somewhere that is not where the work happens, so it has to be carried there by a human who remembers. Under deadline, nobody remembers — which is exactly when the rules mattered.
A CLAUDE.md per repo fixes maybe 60% of this for free and you should do it today. Athena exists for the part that does not fit in 100 lines and must not be copied eleven times.
How it works
Athena serves what the task needs, in the shape the task needs it: graded rules, working guides, multi-step flows, or deep research. The agent asks for what it's trying to get done; the pillar decides what comes back.
Rules
06-api-design.md
MUSTplural, lowercase routes — /api/v1/orders
MUSTPATCH for partial updates, never PUT
SHOULDidentifiers opaque to the client
Guides
auth-in-django.md
one working recipe — steps + code that runs
01 install djoser + simplejwt
02 settings: auth classes · token lifetimes
03 urls: /auth/jwt/ create · refresh · verify
04 code: serializer snippet, ready to paste
Flows
Setup FullStack App
01 fastapi cookiecutter template
02 react vite template
03 gcp + pulumi cli
04 rules: terraform · guide: cloud run
05 rules: gh actions · guide: ci/cd
Knowledge
> SQS or Kafka for this queue?
> what does a checkout flow need?
> how to design multi-tenancy?
The mechanism
The agent describes its task. Athena tells it which pillar and which call, returns exactly what that step needs, and the agent comes back citing the standard it used — by name, so you can open it and argue with it. A small toolbox, not forty tools.
An agent cannot create or alter a rule. It can ask, and it can report that something was missing. It cannot promote its own opinion into the standard it will be judged against next week. The standards change through reviewed pull requests.
| Tool | Category | What it is for |
|---|---|---|
| athena_route | — | Describe the task; get told which pillar and which call |
| athena_rules | Rules | What binds the change being made |
| athena_guide | Guides | How to build one thing, with code |
| athena_flow | Flows | Multi-step work, and the instruction to fan out |
| athena_brief | Flows | One agent's payload, for one step |
| athena_knowledge | Knowledge | Deep research on a topic |
| athena_get | — | Redeem a reference the agent was already given |
| athena_feedback | — | Report what was missing — the one write |
Categories are the four pillars above. Route, get and feedback serve all of them.
Context economy
Context is the budget you are actually spending. A 200 KB handbook in every session is worse retrieval than three relevant pages, and it crowds out the code the agent is supposed to be reading.
So the rules are served separately from the prose. athena_rules("python") returns the graded assertions — about 2 KB — with no rationale, no examples, no diagrams. That is what an agent needs to enforce a standard. The why is still one athena_get away, for the human who wants to argue.
Same reason the toolbox is small instead of forty tools. Every tool schema is injected into context on every request. A large toolbox makes an agent worse, not better.
one 200,000-token context window
0 tokens
whole handbook pasted into CLAUDE.md
0%
room left for your code
Planning
Cursor, Claude Code and the other coding agents already ship strong planning. Athena doesn’t add another planning skill, and it doesn’t force a new workflow on top of them.
It hands those native tools the right engineering knowledge at the right moment — your architecture, standards, conventions, guardrails and proven practices — so the agent plans with your context instead of generic knowledge, or rediscovering how your codebase works one session at a time.
Breadth
Teams adopt AI at the point where code gets typed and wonder why throughput barely moves. The expensive parts are upstream and downstream: deciding what to build, breaking it down honestly, and finding out why it broke in production.
Athena carries the standard for every stage, and the gate between each one. Agents draft. Humans decide. The artifacts — a spec, a plan, a reviewed diff — are what make the next stage cheap.
07 · Scaffold
“Start a FastAPI service, our way”
the callathena_guide("start a fastapi service")
returnsthe generator + its answers, prompt by prompt
the post-generation delta · the day-zero checklist
Scaffolding
The agent reads the setup pages, asks you the four questions it is not allowed to decide, runs the generator, applies the post-generation delta, and then verifies the day-zero checklist item by item with evidence.
It does not create the repo, the cloud resources or the secrets. It writes the infrastructure and the commands; you run them. An agent that provisions unattended is an unreviewed deploy.
Step 1
Step 2
Step 3
Step 4
24 items on the full checklist. Two stay amber until a human signs them — deliberately.
Step 5
Time to live
What takes minutes: a service that builds, runs in a container, passes CI, reports errors to Sentry and reaches staging. Not because anything was skipped — because the generator, the multi-stage image, the compose files, the CI workflow and the error tracking are standards Athena hands the agent, not decisions you make at 16:40 on a Thursday.
What takes the rest of the 30 minutes: the day-zero checklist. Owner, tier, data ownership, branch protection, secrets, infrastructure, the layer contract, the runbook. We will not tell you that part is instant. We will tell you it gets done, item by item with evidence, instead of becoming a ticket nobody picks up.
one image, built once, promoted
drawn to scale
minutes — skeleton deployed, CI green, Sentry live
minute 30 — day-zero checklist done with evidence, first feature PR on prod
Measured: “minutes” from uvx cookiecutter to a green pipeline, a container in staging and Sentry receiving events. “Thirty minutes” from the same start to the first reviewed feature PR on prod with the checklist complete. Both are handbook pages, linked from this one — not marketing claims.
Four environments from the first commit — one image, built once and promoted. Parity is the shape the service starts in, not a later project. And the same shape three times: FastAPI, Django, React. One handbook, one layering, one delivery path.
Standards as code
A PR that breaks it does not merge. Exceptions need a waiver ADR.
“Every endpoint declares a response_model” — CI fails the build on a bare dict return.
The default. Deviating is allowed and must be justified in the PR description.
“Use httpx, not requests” — fine to deviate for a legacy SDK, if the PR says why.
Genuinely a choice, written down so you do not re-derive the trade-off.
“Celery or Cloud Tasks for background jobs” — both supported; the page holds the trade-off so you pick in minutes, not meetings.
The grade is not decoration. CI keys off it, code review keys off it, and so does the agent. A MUST costs an ADR to create and an ADR to change — rules that cannot be challenged get routed around instead.
Every page carries a status and a review date. Anything in draft for more than 90 days is deleted or finished. That is how you tell a live standard from a fossil.
The gate behind the grade: same rule, carried by the agent, the linter and the review.
Knowledge that writes itself
When Athena has no answer and you work the thing out manually — a setup, a fix, a piece of functionality — one call sends what you learned back: athena_feedback. It gets reviewed, graded and merged as working knowledge.
Next time, your agent gets it served in two kilobytes — and so does everyone else’s. One person’s afternoon becomes the community’s answer, globally.
Examples
What Athena is, where it sits next to your coding agent, and the full setup — connect once, and every rule, guide and flow your team has curated is on call. Nothing is added to your repositories.