muzu-organization/skills

1. What this repository is

This is not an application codebase; it is a skills corpus for Claude Code / Claude.ai that standardizes how Odoo consulting tasks are executed. The repo packages four specialized skills, shared guidance, validation scripts, and read-only “anchor” agents that audit outputs before completion.

2. Top-level architecture

The repository splits into three main layers:

- _shared/: cross-cutting principles, role checklists, anchors, and shared linting.

- odoo-*/: four independently invokable skills, each with its own SKILL.md, reference material, scripts, and reports.

- roadmaps/: non-committal backlog material for future skills and corpus improvements.

3. Shared governance layer

_shared/principles.md and _shared/role_checklists/ define the common decision framework used across multiple skills. These files are the canonical source for “how we reason” about Odoo work: interview discipline, validation discipline, security, UX, architecture, troubleshooting, etc. They are designed to be consumed by several skills rather than copied into each one.

4. Anchor subsystem

_shared/anchors/ contains 17 read-only subagents that act as drift detectors. Most anchors audit shared doctrine or role checklists; a few are skill-specific structure/fidelity checks. They run in parallel near the end of a workflow to compare the current artifact against the relevant source of truth and return structured findings that must be reconciled before finish.

5. Skill boundaries

Each skill is a self-contained workflow with its own output contract:

- odoo-plan-development: build a verified-installable Odoo addon.

- odoo-spreadsheet-report: produce and validate an Odoo Spreadsheet .osheet.json.

- odoo-write-specifications: generate a .docx functional spec.

- odoo-mock-design: generate a self-contained HTML mock of Odoo screens.

These are staged handoff points in a typical Odoo delivery chain, not overlapping implementations.

6. Skill-specific reference material

Under each skill’s reference/ folder are the canonical inputs that the skill reads at runtime or during validation. Examples include architecture branches, content outlines, style guides, sample outputs, troubleshooting indexes, and documentation caches. This is where the repo stores the “source of truth” for each skill’s structure and accepted output shape.

7. Validation and tooling

Each skill includes scripts that support its pipeline:

- odoo-plan-development/reference/scripts/ handles environment detection, instance creation, addon install, linting, and smoke tests.

- odoo-spreadsheet-report/reference/scripts/_sync_o_spreadsheet_source.py refreshes cached upstream spreadsheet source.

- odoo-write-specifications/reference/scripts/ builds and lints the document.

- odoo-mock-design/reference/scripts/ lints mock packages and renders the baked catalog.

There is also a shared troubleshooting linter in _shared/scripts/_lint_troubleshooting.py used by multiple skills.

8. Data and artifact flow

The repo’s data flow is mostly “instruction → generated artifact → validation → audit”:

- Interview/plan mode produces a plan or spec.

- Builder scripts create the target artifact: addon scaffold, .osheet.json, .docx, or mock HTML package.

- Validation stages test installability, importability, visual fidelity, or self-containment.

- Anchors then re-check the artifact against principles, role checklists, and skill-specific contracts before completion.

9. Outputs and handoffs

The skills intentionally produce different final artifacts and hand off to each other:

- Spec creation can optionally hand off to mock design.

- Mock design can be run standalone or from spec finish-line.

- Plan development turns a scoped request into a verified Odoo addon under an instance-specific path.

- Spreadsheet report generation yields a loadable report file that is validated in an Odoo database.

This makes the repository an orchestration layer for Odoo delivery, not a single-purpose generator.

10. Operational constraints and environment awareness

The architecture is explicitly environment-sensitive: Odoo.sh, Docker, bare-metal, and local setups are treated as different branches of execution. The skills detect the environment before proceeding and route accordingly. There are also strict process constraints baked into the corpus, such as one-question-at-a-time interviews, confirm-before-destructive actions, and three-stage validation.

11. Documentation vs runtime boundaries

A key boundary in the repo is reference/ versus reports/:

- reference/ is canonical and read at runtime by the skill or its lints.

- reports/ is audit/snapshot material used for calibration and future improvement, but not as a runtime dependency.

This separation is important for diagramming because only reference/ content participates directly in the skill execution path.

12. Maintenance and discovery layer

The repo is designed for Claude’s skill/agent discovery model: SKILL.md files are the skill entry points, while agents/*.yaml are Claude.ai/Claude Desktop exports. The README also defines how the repo is installed into Claude Code via symlinks, and how anchors are discovered flatly. The roadmaps/ folder holds future work and corpus improvements, which sit outside the operational path.

13. Notable external dependencies

There are only a few material external dependencies:

- python-docx for building the specification document.

- Pillow only when BPMN diagrams are requested in a spec.

- Odoo itself as the target runtime for addon install/smoke tests and spreadsheet import validation.

These dependencies matter because they affect whether a given skill can fully execute or falls back to placeholder behavior.

14. How to draw the architecture

A good diagram would show:

- A shared governance/anchor core feeding all skills.

- Four independent skill pipelines, each with its own reference corpus, scripts, and final artifact.

- A validation loop inside each pipeline.

- Optional handoffs between spec → mock → plan → report.

- A separate maintenance/backlog lane for reports and roadmaps.

That captures the repo’s real shape: a multi-skill Odoo delivery framework with shared doctrine and parallel audit checks.