Working with EILAID

What changes for engineers

Your job moves from writing every line to two things that matter more: deciding what gets built and deciding whether it is right. In practice, a day looks like this:

1. Morning: the gate queue. Review briefs that agents drafted overnight. Correct anything wrong, answer open questions, approve.
2. Questions inbox. Answer what the Oracle could not. Each answer becomes context, so the same question does not come back.
3. Accept changes. Review finished work for intent and design. CI and review agents have already checked tests, style and obvious bugs.
4. Deep work. Architecture, hard problems, pairing with an agent on something new. The loop keeps running while you do.
5. Learn. When an agent gets something wrong, ask once: what rule, test or context file would have prevented this? Add it.

Writing a brief agents can finish

The brief is the most important file in EILAID. The Shaper agent drafts it; you make it right. A good brief lets a fresh agent, with no memory of anything, finish the task.

---
id: PAY-412
track: feature
owner: "@sam"
footprint: [src/payments/**, src/api/refunds.ts, db/migrations/]
depends_on: [PAY-409]
---
# Partial refunds

## Goal
Support staff can refund part of a charge. Today a refund is all or
nothing, so returning one item of an order means refunding all of it.

## Acceptance criteria (each one tied to a check)
1. POST /refunds accepts 0 < amount <= remaining  -> refunds.spec.ts#limits
2. Refunds are idempotent on Idempotency-Key      -> refunds.spec.ts#idempotent
3. Ledger entry written in the same transaction   -> ledger.int.ts#refund

## Context
- Payments go through PaymentGateway (src/payments/gateway.ts)
- Copy the validation pattern from src/api/charges.ts
- Decision 0017: money is integer minor units, never floats
- In flight nearby: PAY-409 owns gateway.ts until it merges

## Out of scope
Refund UI; multi-currency.

## Open questions
- [x] Max refunds per charge? Unlimited until fully refunded (answered by @sam)

Checklist for Gate 1:

• Could someone new to the codebase finish this from the brief alone?
• Does every acceptance criterion name a check?
• Is the footprint realistic, and does it avoid other work in flight?
• Is anything out of scope that someone might assume is in?
• Are all open questions answered?

Files in the repo

EILAID lives in your repository as plain files. The tools read and write these. You can always open them yourself.

AGENTS.md                  repo-wide rules for every agent
docs/decisions/            numbered decision records
.eilaid/
  config.yaml              tracker, runtimes, models, budgets, gates
  personas/                shaper.md, builder.md, reviewer.md, ...
  tracks/                  patch.yaml, feature.yaml, epic.yaml
  templates/               brief, handoff, decision, question
  context/                 anything else the Oracle should know
  briefs/                  one file per work item

A persona is a short markdown file:

---
name: builder
tools: [read, edit, test, oracle, ledger]
budget: { minutes: 45 }
context: [AGENTS.md, brief, handoffs, situation report]
output: [commits, handoff, draft PR]
---
You implement exactly one approved brief. Work test-first: one failing
check per acceptance criterion, then code. Stay inside your footprint.
When unsure, ask the Oracle before guessing. If still unsure, raise a
blocker. Finish by writing the handoff and opening a draft PR.

Commands

The proposed CLI. Every command also has an equivalent in the web board.

Adopting it, one step at a time

1. Write the context (about two weeks). AGENTS.md, a short page per major module, and decision records for the five biggest past decisions. Index them and try eilaid ask to find the gaps.
2. One team, small work (four to six weeks). Patch and Feature tracks only. Agents shape briefs, engineers approve them, agents build them, engineers accept the result.
3. Coordination. Turn on leases, blockers, the questions inbox and parallel runs. Add the Steward for nightly maintenance.
4. Scale. The Epic track, the web board, tracker sync, more teams and more repos.

How to tell it is working