# muzu-organization/skills architecture

> Architecture diagram of the GitHub repository muzu-organization/skills, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/muzu-organization/skills
- Repository: https://github.com/muzu-organization/skills

## Overview

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.

Main entry points: [`_shared/anchors`](https://github.com/muzu-organization/skills/tree/master/_shared/anchors) (Anchors), [`odoo-write-specifications/SKILL.md`](https://github.com/muzu-organization/skills/blob/master/odoo-write-specifications/SKILL.md) (Spec writer), [`odoo-mock-design/SKILL.md`](https://github.com/muzu-organization/skills/blob/master/odoo-mock-design/SKILL.md) (Mock design), [`odoo-plan-development/SKILL.md`](https://github.com/muzu-organization/skills/blob/master/odoo-plan-development/SKILL.md) (Plan dev)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shared["Shared core"]
  node_readme["README<br/>entry guide<br/>[README.md]"]
  node_principles["Principles<br/>governance<br/>[principles.md]"]
  node_role_checklists["Role checklists<br/>guidance set"]
  node_anchors{{"Anchors<br/>audit agents"}}
  node_shared_lint["Shared lint<br/>utility script"]
end

subgraph group_skills["Skill pipelines"]
  node_plan_skill["Plan dev<br/>Odoo addon skill<br/>[SKILL.md]"]
  node_plan_ref["Plan refs<br/>reference corpus"]
  node_plan_scripts["Plan scripts<br/>validation pipeline"]
  node_spreadsheet_skill["Spreadsheet<br/>report skill<br/>[SKILL.md]"]
  node_spreadsheet_ref["Sheet refs<br/>reference corpus"]
  node_spreadsheet_scripts["Sheet scripts<br/>validation pipeline"]
  node_spec_skill["Spec writer<br/>documentation skill<br/>[SKILL.md]"]
  node_spec_ref["Spec refs<br/>reference corpus"]
  node_spec_scripts["Spec scripts<br/>build pipeline"]
  node_mock_skill["Mock design<br/>UI mock skill<br/>[SKILL.md]"]
  node_mock_ref["Mock refs<br/>reference corpus"]
  node_mock_scripts["Mock scripts<br/>render pipeline"]
end

subgraph group_backlog["Backlog"]
  node_roadmaps["Roadmaps<br/>backlog"]
end

node_readme -->|"explains"| node_principles
node_readme -->|"describes"| node_anchors
node_principles -->|"frames"| node_role_checklists
node_anchors -.->|"audits"| node_principles
node_anchors -.->|"audits"| node_role_checklists
node_shared_lint -->|"supports"| node_anchors
node_plan_skill -->|"reads"| node_plan_ref
node_plan_skill -->|"invokes"| node_plan_scripts
node_plan_scripts -->|"uses"| node_shared_lint
node_plan_skill -.->|"reviewed by"| node_anchors
node_spreadsheet_skill -->|"reads"| node_spreadsheet_ref
node_spreadsheet_skill -->|"invokes"| node_spreadsheet_scripts
node_spreadsheet_skill -.->|"reviewed by"| node_anchors
node_spec_skill -->|"reads"| node_spec_ref
node_spec_skill -->|"invokes"| node_spec_scripts
node_spec_skill -.->|"handoff"| node_mock_skill
node_spec_skill -.->|"reviewed by"| node_anchors
node_mock_skill -->|"reads"| node_mock_ref
node_mock_skill -->|"invokes"| node_mock_scripts
node_mock_skill -.->|"reviewed by"| node_anchors
node_roadmaps -.->|"tracks"| node_readme

click node_readme "https://github.com/muzu-organization/skills/blob/master/README.md"
click node_principles "https://github.com/muzu-organization/skills/blob/master/_shared/principles.md"
click node_role_checklists "https://github.com/muzu-organization/skills/tree/master/_shared/role_checklists"
click node_anchors "https://github.com/muzu-organization/skills/tree/master/_shared/anchors"
click node_shared_lint "https://github.com/muzu-organization/skills/blob/master/_shared/scripts/_lint_troubleshooting.py"
click node_plan_skill "https://github.com/muzu-organization/skills/blob/master/odoo-plan-development/SKILL.md"
click node_plan_ref "https://github.com/muzu-organization/skills/tree/master/odoo-plan-development/reference"
click node_plan_scripts "https://github.com/muzu-organization/skills/tree/master/odoo-plan-development/reference/scripts"
click node_spreadsheet_skill "https://github.com/muzu-organization/skills/blob/master/odoo-spreadsheet-report/SKILL.md"
click node_spreadsheet_ref "https://github.com/muzu-organization/skills/tree/master/odoo-spreadsheet-report/reference"
click node_spreadsheet_scripts "https://github.com/muzu-organization/skills/tree/master/odoo-spreadsheet-report/reference/scripts"
click node_spec_skill "https://github.com/muzu-organization/skills/blob/master/odoo-write-specifications/SKILL.md"
click node_spec_ref "https://github.com/muzu-organization/skills/tree/master/odoo-write-specifications/reference"
click node_spec_scripts "https://github.com/muzu-organization/skills/tree/master/odoo-write-specifications/reference/scripts"
click node_mock_skill "https://github.com/muzu-organization/skills/blob/master/odoo-mock-design/SKILL.md"
click node_mock_ref "https://github.com/muzu-organization/skills/tree/master/odoo-mock-design/reference"
click node_mock_scripts "https://github.com/muzu-organization/skills/tree/master/odoo-mock-design/reference/scripts"
click node_roadmaps "https://github.com/muzu-organization/skills/tree/master/roadmaps"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme,node_principles,node_role_checklists,node_anchors,node_shared_lint toneBlue
class node_plan_skill,node_plan_ref,node_plan_scripts,node_spreadsheet_skill,node_spreadsheet_ref,node_spreadsheet_scripts,node_spec_skill,node_spec_ref,node_spec_scripts,node_mock_skill,node_mock_ref,node_mock_scripts toneAmber
class node_roadmaps toneMint
```

## Components

### Shared core

Cross-skill doctrine, anchors, and shared linting.

- [README](https://github.com/muzu-organization/skills/blob/master/README.md): entry guide · Repo-level setup and discovery guidance for Claude skills and anchors. · `README.md`
- [Principles](https://github.com/muzu-organization/skills/blob/master/_shared/principles.md): governance · Canonical shared decision framework used across multiple skills. · `_shared/principles.md`
- [Role checklists](https://github.com/muzu-organization/skills/tree/master/_shared/role_checklists): guidance set · Shared checklists for consultant, QA, security, architecture, UX, and related roles. · `_shared/role_checklists`
- [Anchors](https://github.com/muzu-organization/skills/tree/master/_shared/anchors): audit agents · Read-only drift detectors that compare outputs against shared doctrine and skill contracts. · `_shared/anchors`
- [Shared lint](https://github.com/muzu-organization/skills/blob/master/_shared/scripts/_lint_troubleshooting.py): utility script · Common troubleshooting linter reused by multiple skills. · `_shared/scripts/_lint_troubleshooting.py`

### Skill pipelines

Independent Odoo delivery skills with their own references, scripts, and artifacts.

- [Plan dev](https://github.com/muzu-organization/skills/blob/master/odoo-plan-development/SKILL.md): Odoo addon skill · Builds a verified-installable Odoo addon from a scoped request. · `odoo-plan-development/SKILL.md`
- [Plan refs](https://github.com/muzu-organization/skills/tree/master/odoo-plan-development/reference): reference corpus · Environment detection, addon architecture, install flow, and troubleshooting references. · `odoo-plan-development/reference`
- [Plan scripts](https://github.com/muzu-organization/skills/tree/master/odoo-plan-development/reference/scripts): validation pipeline · Creates instances, installs modules, lints add-ons, and runs smoke tests. · `odoo-plan-development/reference/scripts`
- [Spreadsheet](https://github.com/muzu-organization/skills/blob/master/odoo-spreadsheet-report/SKILL.md): report skill · Produces and validates Odoo Spreadsheet .osheet.json artifacts. · `odoo-spreadsheet-report/SKILL.md`
- [Sheet refs](https://github.com/muzu-organization/skills/tree/master/odoo-spreadsheet-report/reference): reference corpus · Spreadsheet architecture, design system, examples, and troubleshooting references. · `odoo-spreadsheet-report/reference`
- [Sheet scripts](https://github.com/muzu-organization/skills/tree/master/odoo-spreadsheet-report/reference/scripts): validation pipeline · Refreshes upstream spreadsheet source and supports report validation. · `odoo-spreadsheet-report/reference/scripts`
- [Spec writer](https://github.com/muzu-organization/skills/blob/master/odoo-write-specifications/SKILL.md): documentation skill · Generates a functional specification as a .docx document. · `odoo-write-specifications/SKILL.md`
- [Spec refs](https://github.com/muzu-organization/skills/tree/master/odoo-write-specifications/reference): reference corpus · Content outline, DOCX styling, and sample structure for specification generation. · `odoo-write-specifications/reference`
- [Spec scripts](https://github.com/muzu-organization/skills/tree/master/odoo-write-specifications/reference/scripts): build pipeline · Builds and lints the DOCX specification output. · `odoo-write-specifications/reference/scripts`
- [Mock design](https://github.com/muzu-organization/skills/blob/master/odoo-mock-design/SKILL.md): UI mock skill · Generates self-contained HTML mockups of Odoo screens. · `odoo-mock-design/SKILL.md`
- [Mock refs](https://github.com/muzu-organization/skills/tree/master/odoo-mock-design/reference): reference corpus · Catalog components, view patterns, interactions, and style guidance for mock generation. · `odoo-mock-design/reference`
- [Mock scripts](https://github.com/muzu-organization/skills/tree/master/odoo-mock-design/reference/scripts): render pipeline · Lints mock packages and renders the catalog used by the skill. · `odoo-mock-design/reference/scripts`

### Backlog

Non-operational improvement and future-skill notes.

- [Roadmaps](https://github.com/muzu-organization/skills/tree/master/roadmaps): backlog · Future skills and corpus improvements kept outside the operational path. · `roadmaps`

## Connections

- README → Principles: explains · Repo guidance points to shared doctrine and operating norms.
- README → Anchors: describes · Repository discovery and anchor usage are documented at the top level.
- Principles → Role checklists: frames · Shared principles are operationalized through role-specific checklists.
- Anchors → Principles: audits · Anchors compare artifacts against the canonical principles.
- Anchors → Role checklists: audits · Several anchors check outputs against role checklist expectations.
- Shared lint → Anchors: supports · Shared linting backs troubleshooting and audit consistency.
- Plan dev → Plan refs: reads · The skill consults its canonical reference corpus at runtime.
- Plan dev → Plan scripts: invokes · Plan development uses its script pipeline for environment setup and validation.
- Plan scripts → Shared lint: uses · Skill validation can reuse shared troubleshooting linting.
- Plan dev → Anchors: reviewed by · Anchors audit plan outputs before completion.
- Spreadsheet → Sheet refs: reads · Spreadsheet generation is driven by its reference corpus.
- Spreadsheet → Sheet scripts: invokes · The skill refreshes and validates spreadsheet sources through scripts.
- Spreadsheet → Anchors: reviewed by · Anchors validate spreadsheet outputs against shared and skill-specific contracts.
- Spec writer → Spec refs: reads · Specification generation uses outline, style, and sample references.
- Spec writer → Spec scripts: invokes · The DOCX build and lint pipeline produces the final spec artifact.
- Spec writer → Mock design: handoff · Specification work can hand off to mock design when needed.
- Spec writer → Anchors: reviewed by · Anchors re-check specification outputs before finish.
- Mock design → Mock refs: reads · Mock generation is grounded in catalog and interaction references.
- Mock design → Mock scripts: invokes · Mock packages are linted and rendered through the catalog pipeline.
- Mock design → Anchors: reviewed by · Anchors verify fidelity and coverage of mock outputs.
- Roadmaps → README: tracks · Roadmap material sits alongside, but outside, the operational skill path.