molecule-dev-department/README.md

molecule-ai/molecule-dev-department

Importable engineering-tree subtree for Molecule AI org templates.

This repo is not a standalone org template. It is designed to be grafted into a parent template (e.g. molecule-ai-org-template-molecule-dev) via filesystem symlink at deploy time. The parent template owns the org identity, top-level workspaces (PM, Marketing, Research, …), and imports this repo's dev-lead/ subtree as its engineering org.

Why a separate repo

molecule-ai-org-template-molecule-dev had grown to ~60 workspace folders + 11 teams/*.yaml composition files + 17 orphaned folders that no !include chain reached. The orphan accumulation was a sign the structure had outgrown a single repo.

Splitting the dev tree out:

• Atomizes engineering as a self-contained unit that other org templates can reuse (one link to add the whole department).
• Makes orphan accumulation impossible — the validator (CI gate) walks the manifest → roots → children and fails on any folder not reachable.
• Lets the dev tree evolve on its own cadence without churning the parent template.
• Keeps the parent template's structure focused on org identity (PM, Marketing, Research) and removes the ~50% of mass that's dev-specific.

Full design rationale: internal#77 RFC

Subtree contract

This repo is consumed by parent templates via this convention:

1. Operator-side deploy layout clones both repos as siblings under /org-templates/:

   /org-templates/
     molecule-ai-org-template-molecule-dev/   ← parent template
     molecule-dev-department/                 ← THIS repo
   

2. Parent template has a relative directory symlink at its root (or under teams/):

   parent-template/
     org.yaml
     dev → ../molecule-dev-department/        ← symlink
   

3. Parent's org.yaml imports the subtree:

   workspaces:
     - !include teams/pm.yaml
     - !include teams/marketing.yaml
     - !include dev/dev-lead/workspace.yaml   ← into the symlinked subtree
   

4. Workspace files_dir: paths inside this repo use the symlink prefix (dev/<workspace-name>) so they resolve correctly when the subtree is imported via the parent. This means the subtree is not directly importable as a standalone org template — by design.

The platform's org importer (workspace-server/internal/handlers/org_include.go) follows symlinks at the OS layer (os.ReadFile is symlink-aware) while its security check (filepath.Abs / filepath.Rel) operates on path strings (passes for symlinked paths because the link's path is inside the parent root). The contract is pinned by tests in molecule-core PR #102.

Repo layout

.
├── dev-department.yaml         ← manifest: defaults + category_routing + roots
├── .molecule-ci/scripts/
│   └── validate-tree.py        ← orphan / reachability lint (CI gate)
├── .github/workflows/
│   └── validate.yml            ← runs validate-tree.py on every PR
├── README.md                   ← this file
├── LICENSE                     ← MIT
└── <workspace-folders>         ← scaffolded empty; populated by Phase 3c-2

After Phase 3c-2 (extract dev tree with git history) the repo will contain the dev-lead/ workspace tree with nested sub-teams. After Phase 3c-3 (move documentation-specialist + triage-operator into the tree per Hongming Q1+Q2) those workspaces will live under dev-lead/app-docs/documentation-specialist/ and dev-lead/triage-operator/ respectively.

Validating locally

.molecule-ci/scripts/validate-tree.py
# OK — tree is clean

# Or with explicit manifest:
.molecule-ci/scripts/validate-tree.py dev-department.yaml

The validator:

• Walks dev-department.yaml → roots → children recursively, including through !include directives.
• Lists every directory containing workspace.yaml.
• Reports orphans (filesystem dirs not reachable from manifest), cross-tree .. traversal in children: paths, duplicate parents, and missing workspace.yaml.
• Exits non-zero on any violation.

CI runs the same script via .github/workflows/validate.yml on every push and PR — orphan accumulation is caught at PR time, not at deploy time.

Phase status

Phase	Status	Where
1 — Investigate platform org importer	✓ done	internal#77 comment 1886
2 — Design (SSOT, alternatives, security, versioning)	✓ done	internal#77
3a — Platform external: ref support	parked (deferred)	task #222
3b — Validator + CI gate	✓ done	this commit
3c-1 — Scaffold this repo	✓ done	this commit
3c-2 — Extract dev tree with history	pending	task #224
3c-3 — Atomize structure + move doc-spec + triage-op	pending	task #224
3d — Slim parent template + wire symlink + delete orphans	pending	task #225
4 — End-to-end verify on staging	pending	task #226

Refs

• internal#77 — extraction RFC
• molecule-core#102 — symlink-resolution test
• Hongming GO 2026-05-08 ("you own this feature and repos, start")

License

MIT — see LICENSE