Claude-buildease-demo/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this repository is

This repo *is* a Claude Code skill, not an application. It contains no source code, tests, or build tooling — only prompt content:

- `SKILL.md` — the skill body (`name: buildease-demo`), loaded by Claude Code when the skill is invoked.
- `reference/buildease.md` — the BuildEase module map and pain→module routing table, read at Phase A.

Editing this repo means editing instructions that another Claude instance will follow. There is nothing to compile or lint; the only meaningful verification is running the skill end to end against a real Odoo instance.

### Installing / testing a change

```bash
ln -s "$PWD" ~/.claude/skills/buildease-demo
```

Or check the repo out at that path directly — either layout works. What matters is that
**exactly one copy exists**: a clone alongside a checkout means you edit one and Claude
loads the other, with nothing to signal the drift. The substrate is symlinked for that
reason.

Claude Code discovers skills from the `name:`/`description:` frontmatter in `SKILL.md`. Changing `name:` changes how the skill is invoked; changing `description:` changes when it triggers — both are the routing surface, so treat them as API.

## Architecture

`buildease-demo` is a **thin vertical overlay** on `callista-odoo-demo`. It does not own a pipeline. It supplies exactly five overlays, each applied at a *named* step of the substrate skill:

| Overlay | Applied at |
|---|---|
| Module routing (`reference/buildease.md`) | *Install modules*, Phase A `## Phase 1 scope` |
| Solution precedence — BuildEase → native Odoo 19 → custom | *Research native-vs-custom* |
| Demo data policy — never `buildease_demo_data` | *Load demo data* |
| Purge chain — take-off / progress-statement teardown order | *Purge test residue* |
| Follow-through framing | Phase C |

**The boundary is the point of this repo.** New *mechanism* needed — a step that doesn't exist, an override those five don't offer — is a gap in `callista-odoo-demo`: fix it *there*, so the next vertical inherits it. Do not work around it here, and never reimplement the substrate's `scripts/`, `templates/`, or `demo_config.json` handling.

Construction detail that merely hangs off an existing named step (settings that default off, what a plausible staged number looks like, which chain *Test heroes* exercises) is **not** a gap. It belongs here, under *Step-local notes*, tagged with the step it applies at.

This repo was previously a full three-phase skill. The generic two-thirds (discovery brief from any source, the two-agent parallel build, the follow-through doc set) moved into the substrate on 2026-07-31 because Callista runs it for plain Odoo implementations too, and that content was stranded behind a construction trigger.

### Substrate and upstream

| Repo | Role |
|---|---|
| `admin/callista-odoo-demo` (Gitea) | The pipeline this skill overlays. Hard dependency, installed as `~/.claude/skills/callista-odoo-demo/` |
| `github.com/Smetools/odoo-demo-architect` | What the substrate was forked from at `ada2751`. Callista has no commit rights; changes land in the fork. See its `UPSTREAM.md` |
| `git@github.com:callista-tools/mev.git` | BuildEase — 34 Odoo 19 modules, umbrella module `buildease`. Not vendored; `reference/buildease.md` is a distilled map |

**Never install the substrate under the name `odoo-demo-architect`.** Skills resolve by directory name, so a same-named fork silently shadows upstream depending on install order, and two people build different demos from the same brief.

### Editing rules that carry weight

- **Reference substrate steps by name** (*Test heroes*, *Purge test residue*), never by number. Numbered references are how an upstream renumbering silently misroutes this skill with nothing to detect it.
- **The purge ordering** (transient wizard rows → invoices → statements → timesheets → tasks → projects → sale orders → take-offs → partner last) is ordered because Odoo blocks deletion otherwise. Invoices go *before* statements — an `invoiced` `sale.progress` refuses `action_cancel` until its invoice is cancelled — so do not "helpfully" reorder them back. Do not reorder or summarise. The take-off-without-a-sale-order trap in particular is non-obvious and cost a debugging round.
- **Not installing `buildease_demo_data`** is the reason this overlay exists at all; the app-level dependencies that bundle used to drag in must still be routed from the pain table.
- `reference/buildease.md` drifts when mev changes. When updating it, keep the two things that make it useful: the pain→module table keyed on *the client's own words*, and the gotchas (missing `custom_product_*` deps, Odoo 19 only, settings that default off).

## Writing style for this repo

Match the existing prose: imperative, second person, no hedging, tables for anything enumerable. Rules state what to do *and* the failure that motivates them ("a fabricated quote read back to the client in the demo is not"). Avoid generic agent boilerplate — everything here should be specific to BuildEase or it belongs in the substrate.

## Related

The parent workspace `../CLAUDE.md` (Callista BV multi-customer workspace) covers Odoo module conventions — naming, manifests, version numbering — and applies when editing the mev modules themselves, not this repo.