Git & Documentation Strategy

Core Principle

Projects are the source of truth, not containers. Containers are disposable workstations. A project lives on GitHub as a private repo under the OmelasAI organisation. Any container can clone it, work on it, commit, push. Another container pulls and picks up where the last one left off.

Repository Structure

Every active project gets a private repo on OmelasAI GitHub:

Branching Convention

• main — stable, deployed code. Always works.
• dev — integration branch for work-in-progress (optional, per project)
• feature/description — feature branches for specific work
• fix/description — bug fix branches

Two-Layer Documentation

Documentation happens at two layers with different purposes and timing:

Layer 1: Git (continuous, project-level)

Code and project markdowns committed to GitHub. This is the working record — what changed, when, and why.

What gets committed:

• Source code changes
• Project markdowns (CHANGELOG.md, README.md, docs/)
• Configuration changes
• Updated .env.example (never .env itself)

Commit messages must be meaningful. Not “updated files” but “Added authentication middleware to gateway, updated CHANGELOG with new endpoint list.” Any Claude instance reading the git log should understand exactly what happened and be able to continue the work.

Layer 2: DocHub (periodic, polished)

Structured documentation pushed to DocHub via /dochub-add. This is the human-readable overview for cross-project visibility.

What goes to DocHub:

• Architecture documentation
• API references
• Deployment guides
• Visual overviews

When to Commit

Commits are developer-initiated, not automatic. The developer (or their Claude instance) knows when a chunk of work is complete enough to save. Specifically:

Primary trigger

When the developer says “document” / “update docs” / “commit” — they have reached a natural stopping point and want to save state.

Natural checkpoint moments

What happens at a checkpoint

1. Claude updates project markdowns (CHANGELOG, README, relevant docs)
2. Claude commits code + markdowns with a descriptive message
3. Claude pushes to GitHub
4. If end of session: developer runs /dochub-add for polished DocHub update

What does NOT trigger a commit

• Every tool call (creates garbage history)
• Every file edit (too granular)
• Automatic timers (meaningless commits)
• Mid-task saves (incomplete work with bad messages)

Markdown Update Discipline

During a work session, Claude updates project markdowns multiple times as work progresses. These are local file updates, not commits yet. The developer may update markdowns 3-4 times over a few hours, then commit once at a checkpoint.

Every project should maintain:

Container Takeover Process

When one container needs to take over another’s project:

1. git clone (or git pull if already cloned) the project repo
2. Read CHANGELOG.md — understand recent work
3. Read git log --oneline -20 — see commit history
4. Read project README.md — understand setup
5. npm install + docker compose up — get running
6. Check DocHub for architectural overview if needed
7. Continue work, following the same commit discipline

No special tooling needed. Just git and good documentation habits.

Secrets Management

.env files are never committed. Each project maintains:

• .env.example — template with all required keys (no values)
• Actual .env files distributed securely via Claude Net file transfer or stored on the host

When a new container clones a project, it gets the .env via:

# Secure channel (e.g., Claude Net message, or admin copies directly)

Then Chas provides the actual values via secure channel.

GitHub Access

All containers authenticate to GitHub via gh CLI (GitHub CLI). Each developer has their own GitHub account added to the OmelasAI organisation: