Execution Charter

---
name: execution-charter
description: How to turn a passed AIDD decision gate into a build — reading the contract, honouring APPLY/INFER/INNOVATE/DEFERRED, writing the charter, slicing the work, and handling contract drift. Load during the AIDD execution phase.
---

# Building under contract

The gate has passed. `.aidd/02-research/decisions.md` now outranks your defaults.

## Read it properly

Read the whole file, including the machine-readable block. Then restate it back to the user before writing code — every `APPLY`, `INFER`, `INNOVATE`, and `DEFERRED`. Misreading the contract is the cheapest mistake to catch here and the most expensive one to catch later.

## The four stances

**APPLY** — build exactly this. No latitude on the choice. If it turns out to be unworkable, stop and report; do not substitute. The user took this decision away from you deliberately.

**INFER** — read it, extract what's useful, then decide independently. The most misread stance: it does not mean "use it", it means "learn from it". If your implementation is indistinguishable from the referenced option, you inferred nothing. Say what you took and what you left.

**INNOVATE** — the named option marks ground already covered. Go elsewhere. Not a variation with different names; a genuinely different approach. State in the charter what you're doing instead and why it beats what was shown. If after real effort the shown option is simply correct, say that explicitly rather than pretending you invented something.

**DEFERRED** — your call. Pick what the research supports, record the pick and the reason, tag it `[claude-call]` so it is trivially findable later.

**LOCKED** — not a choice at all: a fact about the codebase, with the file that proves it. Build with it. Replacing it is a separate project and needs the user's explicit say-so. A user note on a locked segment ("fine for now, but I want this gone next quarter") is a constraint on *how* you build — design so the replacement is possible later — not permission to do it now.

## On an existing codebase

The contract's **What the existing codebase already fixes** section is binding, and its `must not break` list outranks everything else in the document. Breaking the revenue path is worse than shipping nothing.

- **Match the surrounding code** — naming, layering, error handling, test style — even where you would have done it differently. Mismatched style is how generated code announces itself.
- **No opportunistic refactors.** Spotted something worth fixing outside this change? Note it for the user. A diff that touches twice what it needed to is a diff nobody can review.
- **Extend the existing seams.** A second job runner, config system, or HTTP client beside the one already there is a defect, not an improvement.
- **Migrations and public contracts are one-way doors.** Additive first; anything destructive gets raised before it is written.
- **Run the existing test suite before and after.** "My new tests pass" is not evidence you left the other 1,900 alone.

## Notes outrank cards

The free-text notes carry the constraints the option cards could not express. If a note says "must run offline" and the `APPLY`ed choice needs a server, that is a live conflict — raise it before building. Never resolve it silently in either direction.

## charter.md

One page, written before any code, shown to the user:

```markdown
# Build charter — <project>

## Bound by the gate
- <segment>: APPLY <option> — <what this concretely means in the code>
- <segment>: INFER <option> — taking <X>, leaving <Y>, doing <Z> instead
- <segment>: INNOVATE past <option> — building <what>, because <why it's better>
- <segment>: LOCKED <option> — building with it; <how the design accommodates it>

## Inherited from the existing codebase   (brownfield only)
- Must not break: <the list, restated as things you will verify still work>
- Conventions I am matching: <naming, layering, test style — with a file to imitate>

## My calls
- [claude-call] <segment>: chose <X> because <reason from the research>

## Constraints from the user's notes
- <note> → <how the build satisfies it>

## Conflicts to resolve before building
- <conflict> — needs the user

## Architecture in five lines
<the shape, not a diagram>

## Visual approach   (anything with a surface — see the craft-bar skill)
- Direction: <what this should feel like, derived from the subject, in one line>
- Techniques: <the 2-3 you are actually building, and what each one is for>
- Generated, not sourced: <how each visual is produced — CSS, SVG, canvas, WebGL, procedural>
- Degradation: <what a no-WebGL, reduced-motion, narrow-viewport visitor gets>

## Contract drift
(empty until something breaks)
```

## Slicing

`tasks.md` is thin vertical slices, each leaving the project runnable. Not "set up the database" then "write the API" then "build the UI" — one narrow path through all three, then widen.

Parallelise with `aidd-executor` agents only where slices touch disjoint files. Launch them in one message so they actually run concurrently.

## Where your creative freedom lives

The contract names decisions, not the product. Module boundaries, naming, error handling, the shape of the data model, tests, developer ergonomics, the small touches that make it feel *made* — all yours, all unmentioned by the gate, and all of what separates a good build from a compliant one.

A project that satisfies every contract line and still feels like a checklist is a failed build. Use the room you were given.

## Verification

Run the thing. Execute the path you changed and look at the actual output before calling anything done. Quote it. A green type-check is not an observation of behaviour.

For rendered work, verification means **rendering it and looking**: both themes, `prefers-reduced-motion` on and off, a narrow viewport, and the no-WebGL path. Reading your own source is not observation. Profile the frame rate before describing anything as smooth.

Blockers, not progress: `TODO` placeholders, stubbed branches, skipped or `.only` tests, functions returning fake data. Implement them or report them as blockers.

Review is a separate pass — `code-reviewer` or `verifier`, never self-approval in the same breath as writing the code.

## Contract drift

When reality contradicts an `APPLY` — abandoned library, dead API, licence that forbids the use — stop. Report with evidence, offer the alternatives, let the user choose. Then log it:

```markdown
## Contract drift
- 2026-08-09 — APPLY <option> blocked: <what broke, with evidence>.
  Options offered: <A>, <B>. User chose: <X>.
```

The log is what makes the finished project explicable six months later.

## Closing the run

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/aidd.mjs" phase done
```

Report: what runs, what you verified and with which command, what is stubbed, every `[claude-call]`, and every drift.