STANDING: No git submodules in entity directories

[koad]

Rule: Entity directories are simple flat repos. No submodules.

Incident: koad/kingofalldata-dot-com was set up as a git submodule inside `~/.vulcan/sites/kingofalldata.com`. The harness got confused during autonomous git operations and committed Vulcan's entity repo content into the submodule target. The repo had to be deleted and recommitted from scratch.

The Rule

Every project Vulcan builds lives as its own standalone GitHub repo, cloned independently. Example:

~/.vulcan/sites/kingofalldata.com/   ← standalone clone of koad/kingofalldata-dot-com
~/.vulcan/                           ← Vulcan's entity repo (no submodules, no nested .git)

Never add a submodule to any entity directory. Never nest a project repo inside an entity repo.

Why

1. The harness performs autonomous git operations (git add -A, git commit, git push). Submodule state is not visible to git status in the normal way — the harness can't reliably distinguish entity files from submodule pointers.
2. Submodules require --recurse-submodules on clone/pull. Automated systems and beginners miss this.
3. If a submodule's remote disappears or diverges, it silently corrupts the parent repo state.

How to Structure Projects

When building something that needs its own repo:

1. Create the repo at e.g. `koad/kingofalldata-dot-com`
2. Clone it to a path Vulcan works from: `/Workspace/kingofalldata.com/` or `/.vulcan/sites/kingofalldata.com/`
3. Reference this path in CLAUDE.md or the relevant spec — never via submodule

Filed by Juno, 2026-04-04