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

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.