Working Agreement

How new work starts, and who is recorded against it. Read this with ACCESS_POLICY.md (what may be written where) and CONVENTIONS.md (how entries are written).

1. Always ask before building a new project

Never start building a new project, integration or automation without asking first.

This applies to an AI agent and to a person. Documenting something, reviewing something, or answering a question about it is not permission to build it. If the conversation drifts from "explain this" to "so we'd need a service that…", stop and ask.

Ask before you build when the work would:

• create a new repository, service, Lambda, scheduled job or integration;
• add a new system to the stack, or a new dependency between two existing systems;
• write to a production system that the work did not previously write to;
• start something that will need to be owned and maintained after it ships.

You do not need to ask to:

• document, review or diagram something that already exists;
• answer questions, investigate a defect, or reproduce a finding;
• make a change that was already scoped and agreed — that is the work, not a new project.

What to establish before anything is built. These are exactly the fields every registry entry carries (§2), so asking them up front means the entry can be written the day the work lands:

If the answer to any of them is "not sure yet", that is itself the reason to ask rather than build.

Why. Something built without a named owner becomes nobody's, and the registry ends up documenting a system no one will maintain. Asking costs a message; an unowned production job costs far more.

2. Who is recorded on an entry

Every entry carries three ownership fields. All three name real people or a real team — there are no role placeholders.

Ask for all three. Every time, on every new entry. None of them can be derived from the code, and all three are the kind of thing that looks obvious and turns out to be wrong. Ask them in the same message as everything else the entry cannot answer for itself — §5 — rather than as a question of their own:

• project_owner — propose Kim Hoang Nguyen and have it confirmed. Kim is the default across this registry, but a default is not an answer; asking costs one line and stops an entry quietly naming the wrong person as accountable.
• developers — ask who built it and who maintains it now. Corroborate against GitHub or Celigo authorship (§3), then put the names to a person and confirm them.
• for_department — ask which team feels it when it breaks. Offer the suggested list in CONVENTIONS.md §6 rather than an open question; it is far easier to correct a suggestion than to answer from nothing.

If an answer does not come back, leave the field blank rather than guessing. A blank renders as needs confirming, which is honest and actionable — §4 applies to people exactly as it applies to field labels.

Names beat role labels here: "Backend PM" tells a reader nothing they can act on, while a name tells them exactly who to message. The cost is that names go stale — which is what §3 is for. An entry whose people have all moved on needs its owner reassigned, not a role title papered over the gap.

Names are for attribution and contact only. Nothing in this registry should be read as assigning blame for a defect — the defect findings in an entry describe code, not people.

3. Amending the developer list from GitHub

developers is expected to drift, and it is meant to be corrected without ceremony.

When adding or creating any new feature, if you see a name in GitHub that is not on the entry — add it. The signal is authorship of real work in the source repository:

• the author of a commit or pull request that adds or changes the documented behaviour;
• a reviewer who is clearly maintaining the integration, not passing through.

How to amend:

1. Take the person's real name where GitHub shows it, not the handle — Julian-Ayoub is recorded as Julian Ayoub. If only a handle is available, record the handle and correct it later.
2. Add, don't replace. Someone who wrote a feature stays on the list after they move on; that is the record of who knows the system. Remove a name only when asked.
3. Add a change-history row and bump documented_updated, as with any other entry change. There is no version field — see CONVENTIONS.md §6.
4. last_reviewed stays where it is — an attribution change verifies nothing about behaviour (CONVENTIONS §10).

Do not infer a project_owner from GitHub. Whoever commits most is not thereby accountable for the project. That field changes only when someone says so.

A merge does not need a separate approval to update this list. Correcting attribution is maintenance, not a new project, so §1 does not apply.

4. Where field information comes from

The field registry (CONVENTIONS §8) needs three different kinds of information, and they come from three different places. Knowing which is which is what stops this becoming a questionnaire.

So the answer to "should I be asked every time?" is no, and not per field either:

1. Never ask for anything the code already answers. If the code reads a field to decide something, the entry can say what it changes without anyone being asked.
2. Read the label from the system, not from a person. NetSuite is the source of truth for what a field is called. Where a connector or a metadata endpoint is available, use it — the integration repositories already fetch field metadata this way rather than hard-coding it.
3. Ask once per entry, in one batch, for what is genuinely left — usually just the meanings. Not per field, not on every run, and never as a blocking question. That batch is not a field-registry batch: it is the single confirmation pass in §5, and the meanings go into it alongside the owner, the developers and the department.

A new field found in code is added immediately, flagged, and never blocks. When work adds or changes a field that drives a documented rule, the row goes into fields: straight away with everything the code knows and confirmed: false. It renders as needs confirming rather than as a guess. npm run check warns; it does not fail. An entry that is correct about behaviour should not be held up because a label is unconfirmed.

Never invent a label or a meaning. A plausible-sounding field description that turns out to be wrong is worse than a visible gap, because nobody goes back to check the ones that look finished.

This mirrors §3. Attribution is corrected from GitHub; field labels are corrected from the system. Both are maintenance, not new projects, so §1 does not apply to either.

5. One confirmation pass, before the entry is published

Everything an entry cannot answer for itself is asked in a single message, before the entry lands — not discovered afterwards. project_owner is the familiar case, but it was never the only one. The failure this exists to stop is the common one: the entry is written and published, someone reads it, they hit needs confirming in six places, and now there is a second round of questions against a page that already looks finished.

Two rounds is one too many. The information was always going to be needed; asking for it while the entry is being written costs one message, and asking for it afterwards costs a message plus a re-read plus an edit — and usually never happens at all, which is how a page fills up with permanent blanks.

How to run it. Write the entry as far as the code and the systems take you. Then, before it is published, run npm run build && npm run check and read the warnings: they are a generated list of exactly what is unconfirmed. Strike out everything you can answer yourself, and put the remainder into one message with the ownership questions.

Rules for the ask itself:

1. Propose, never interrogate. A list of blanks is work for the reader; a list of proposals is a two-minute correction. Every row above is phrased as something to confirm or correct.
2. One message, not a thread. Batch them even when they are for different people — it is far easier to forward one message than to answer seven.
3. Say what happens if there is no answer, so silence is a decision rather than an oversight: the field stays blank, renders as needs confirming, and the entry publishes anyway.
4. It is still never blocking (§4). Asking first and publishing anyway are not in tension: the point is that the question has already been asked by the time anyone reads the gap, so a blank means nobody knew yet, not nobody was asked.
5. Never fill a blank with the answer you expected. §4's last line holds everywhere: a plausible guess is worse than a visible gap, because nobody re-checks the ones that look finished.

Read this together with §1. That section asks three questions before anything is built; this one asks the rest before anything is published. Same principle, two moments — establish it while someone still has the answer in their head.