Odoo Capability Atlas (odoo-atlas) — how to use and test odoo2specs + generate

USAGE_AND_TESTING.md

Odoo Capability Atlas — how to use and test

Repo: https://github.com/litnimax/odoo-atlas
Branch: main

Two products in one monorepo:

Product	Role
odoo2specs	Authoring harness: read Odoo addons RO → extract → candidates → independent review → export capabilities.db
generate	Separate SaaS (Hono SSR): reads Atlas RO, adaptive interview → minimal Sphere spec (MD + JSON)

Odoo is a knowledge corpus, not a module catalog and not the Sphere architecture.

---

Requirements

• Node.js >=22.19 <26 (24 LTS recommended)
• pnpm 10.x (corepack enable is fine)
• Optional for live agents: ANTHROPIC_API_KEY or OPENAI_API_KEY

git clone https://github.com/litnimax/odoo-atlas.git
cd odoo-atlas
pnpm install
pnpm check    # typecheck + lint + tests — must be green

---

1) Fastest path: demo Atlas + generate UI

No Odoo sources needed.

# Build a small Atlas through the real candidate → review → export path
pnpm seed:demo

# Start generate (loopback no-auth demo only)
ATLAS_DB=./data/capabilities.db \
APP_DB=./data/application.db \
pnpm generate

Open: http://127.0.0.1:8787

Manual smoke in the browser

1. New project → name + free-text business description
2. Confirm domains
3. Interview — answer questions
4. Answer “Do you need a separate lead intake…” → No
   • Lead-qualification should move to excluded
   • Follow-up lead conversion question should not appear
5. Scope — force include/exclude if you want
6. Specification — download Markdown + JSON
7. Check the spec has:
   • selected scope + explicit non-scope
   • odu_ / odu_base doctrine notes
   • no “install crm/sale” recipes

Security headers smoke

curl -sI http://127.0.0.1:8787/ | rg -i 'x-content-type|x-frame|content-security'
# expect: nosniff, DENY, CSP default-src 'self'

Auth boundary

# Must fail (no-auth off loopback without docker demo flag)
GENERATE_HOST=0.0.0.0 GENERATE_NO_AUTH=true pnpm generate
# → error: Refusing no-auth mode on non-loopback host

---

2) Automated tests

pnpm test          # vitest
pnpm typecheck
pnpm lint
pnpm check         # all three

What is covered (high level):

• public schema + decision-rule DSL
• candidate → accept / merge / reject lifecycle
• sanitised export (no candidates/source tables; sentinel leak test)
• extractors + path sandbox + bounded source search
• role-gated Pi tools (analyzer ≠ reviewer)
• orchestrator dry-run + stale task recovery
• generate adaptive interview + doctrine-safe spec + CSP headers
• package boundaries (generate must not depend on authoring/Pi)

---

3) Authoring harness (odoo2specs) with a real Odoo tree

Point at any local addons directory. Module names are not hardcoded.

pnpm odoo2specs -- init

pnpm odoo2specs -- source add /path/to/odoo/addons \
  --label community --version 19.0

pnpm odoo2specs -- scan
pnpm odoo2specs -- doctor

# Mechanical extract only
pnpm odoo2specs -- extract --module <module_name>

# Mechanical extract + per-layer agent tasks
# Without API keys → dry-run (wires tools/skills, no LLM calls)
pnpm odoo2specs -- analyze --module <module_name>

# Live Pi sessions (needs API key). Still in-memory transcripts, custom tools only.
export ANTHROPIC_API_KEY=...   # or OPENAI_API_KEY
pnpm odoo2specs -- analyze --module <module_name> --live

Human review loop

pnpm odoo2specs -- review-queue
pnpm odoo2specs -- candidates --status proposed
pnpm odoo2specs -- show --revision <revision-id>

pnpm odoo2specs -- accept --revision <id> --hash <sha> --reviewer review-alice
# or
pnpm odoo2specs -- merge  --revision <id> --hash <sha> --reviewer review-alice --target <capability-id>
pnpm odoo2specs -- revise --revision <id> --hash <sha> --reviewer review-alice --note "Need clearer non-scope"
pnpm odoo2specs -- reject --revision <id> --hash <sha> --reviewer review-alice --reason not_a_business_capability

pnpm odoo2specs -- changelog
pnpm odoo2specs -- export
# → data/capabilities.db + data/capabilities.manifest.json

Then point generate at the export (same as demo).

Hard guarantees to verify manually

Check	How
Analyzer cannot create canonical	Only submit_candidate_revision; no accept tools for analyzer
Reviewer session ≠ analyzer session	Same session id on accept → error
Rejected never in public DB	Reject, export, open capabilities.db — no rejected slug
No source bodies in DB	Working DB has coordinates only; public has no source tables
No Atlas network API	generate opens SQLite file RO locally

---

4) Pi agent rules (production posture)

Live sessions use @earendil-works/pi-coding-agent:

• SessionManager.inMemory() — no durable source transcripts
• noTools: "builtin" — no default bash/edit/write/read
• allowlist = custom tools only
• mutation tools: executionMode: "sequential"

Role	Tools
common	read_source_file, search_source, get_analysis_context, search_atlas
analyzer	+ submit_candidate_revision
reviewer	+ review_candidate_revision

Skills: apps/odoo2specs/skills/{analyze-capability-layer,synthesize-module,review-candidate}/

---

5) Docker (optional)

# generate (after seed:demo; published on localhost only)
docker compose up --build generate
# http://127.0.0.1:8787

# odoo2specs image
docker build -f apps/odoo2specs/Dockerfile -t odoo2specs .
docker run --rm \
  -v "$PWD":/workspace \
  -v /path/to/addons:/sources/community:ro \
  odoo2specs help

---

6) Architecture (one screen)

Odoo addons (RO mounts)
        │
        ▼
odoo2specs  →  odoo2specs.db (working)
  extract → analyzer candidates → independent review → canonical
        │
        │  positive-allowlist export
        ▼
capabilities.db + capabilities.manifest.json
        │
        ▼
generate (RO Atlas + RW application.db)
  interview → scope → Sphere MD/JSON

Packages:

apps/odoo2specs  →  packages/atlas-authoring  →  packages/atlas-public
apps/generate    ────────────────────────────→  packages/atlas-public

generate must never import authoring or Pi.

---

7) Useful paths

Path	Purpose
specs/	ADRs / contracts
data/	Local DBs (gitignored except .gitkeep)
scripts/seed-demo-atlas.ts	Demo seed
apps/odoo2specs/src/cli.ts	Harness CLI
apps/generate/src/main.tsx	Discovery app

---

8) Troubleshooting

Symptom	Fix
Config not found	pnpm odoo2specs -- init
Atlas DB not found	pnpm seed:demo or odoo2specs export
better-sqlite3 native errors	pnpm rebuild better-sqlite3
analyze does nothing “smart”	No API key → dry-run by design; set key + --live
accept fails “same session”	Use a different --reviewer id than analyzer session
generate refuses host	Bind 127.0.0.1 or set GENERATE_DOCKER_DEMO=true only for local docker publish

---

9) Definition of done checklist (MVP)

• pnpm check green
• pnpm seed:demo + generate interview “no leads” path works
• Spec downloads include non-scope + odu_* doctrine
• Optional: analyze --module <x> on a real addon tree
• Optional: accept one candidate via review-queue → export → generate

---

Generated for https://github.com/litnimax/odoo-atlas — Odoo Capability Atlas / OduSphere discovery stack.