Development Workflow Overview
OmelasAI runs all software development through Claude Code AI instances. Each developer has a dedicated LXC container on the Contabo Singapore server (62.72.47.64) with a persistent Claude Code session running inside tmux. Every container shares the same set of slash-command skills and the same project map, ensuring a consistent workflow regardless of which developer or machine is active.
The Big Picture
Developer (laptop / phone / browser)
|
+-- SSH or Mosh or Web Terminal (term.ipnoelp.io)
|
+-- Contabo Singapore (62.72.47.64)
|
+-- LXC Container (chasclaude / infoclaude / seanclaude / jazclaude / managerclaude)
|
+-- tmux session "claude"
|
+-- Claude Code instance (running 24/7)
|
+-- 18 skills in ~/.claude/commands/
+-- projects.yaml (project map)
+-- CLAUDE.md per project (rules)
+-- Claude Net MCP (inter-instance messaging)
Each container is a full Ubuntu 24.04 development environment with Node.js 22, Docker, git, and GitHub CLI. Claude Code has auto-approved permissions for all file and shell operations, removing friction from the development loop.
The Development Cycle
A typical development session follows this pattern:
| Step | Skill | What Happens |
|---|---|---|
| 1. Start | /start-session |
Reads HANDOVER.md, loads project context from projects.yaml, reviews recent git log and OPS-LOG.md |
| 2. Work | (no skill) | Normal development – writing code, debugging, testing |
| 3. Checkpoint | /commit |
Stages changes, writes a commit message, commits |
| 4. Share | /push |
Pushes to GitHub remote |
| 5. End | /end-session |
Writes HANDOVER.md with current state, pending tasks, blockers |
The /start-session and /end-session pair creates continuity between sessions. When Claude Code restarts (or a new conversation begins), /start-session reads the handover from the previous session so context is not lost.
Key Files in Every Project
Every OmelasAI project repository contains these standard files:
| File | Purpose | Who Writes It |
|---|---|---|
CLAUDE.md |
Project-specific rules and architecture for Claude Code | Developer (manual) |
HANDOVER.md |
State snapshot from the last session – what was done, what’s next, any blockers | /end-session skill |
OPS-LOG.md |
Incident log – production issues, outages, recovery steps | /incident skill |
CHANGELOG.md |
Human-readable change history | Developer or /commit |
CLAUDE.md
The most important file. Claude Code reads this automatically when entering a project directory. It contains:
- What the project is and what it does
- Tech stack and architecture
- Critical rules (what NOT to do)
- Database schemas, API endpoints, file paths
- Deployment instructions
Every project’s CLAUDE.md inherits baseline rules from CLAUDE-BASE.md (propagated to all containers). Project-specific CLAUDE.md files add rules on top of the baseline.
HANDOVER.md
Written by /end-session, read by /start-session. Contains:
- Summary of what was accomplished in the session
- Current state of the codebase (what’s working, what’s broken)
- Pending tasks with priority
- Blockers or decisions needed
- Any context the next session needs to know
This file is the primary mechanism for session continuity. Without it, each new Claude Code conversation starts from zero.
Standard Project Structure
From CLAUDE-BASE.md, every project follows this layout:
project-root/
CLAUDE.md # Project rules (Claude reads automatically)
HANDOVER.md # Session state (written by /end-session)
OPS-LOG.md # Incident log
CHANGELOG.md # Change history
docs/ # Project documentation
.env # Secrets (never committed)
The exact contents under docs/ vary by project, but the root-level files are mandatory.
Session Persistence
Claude Code runs 24/7 inside tmux in each container. This architecture provides:
| Feature | Mechanism |
|---|---|
| Survive disconnects | tmux keeps the session alive when SSH drops |
| Survive network changes | Mosh (UDP) handles roaming and brief outages |
| Survive brownouts | tmux + systemd auto-restart ensures the session returns |
| Multi-device access | Multiple clients attach to the same tmux session simultaneously |
| Browser access | Web terminals (ttyd) at term.ipnoelp.io provide access from any device |
A developer can start work on their laptop, continue from their phone via the web terminal, and pick up again on the laptop – all seeing the same live session.
When Claude Code does restart (model updates, crashes, long idle), the /start-session skill reconstructs context from HANDOVER.md, CLAUDE.md, and recent git history.
Three Places Documentation Lives
OmelasAI maintains documentation in three distinct locations, each serving a different purpose:
| Location | What Goes There | Audience |
|---|---|---|
| Git repository | CLAUDE.md, HANDOVER.md, OPS-LOG.md, docs/ folder |
Claude Code instances working on that project |
| DocHub (docs.ipnoelp.com) | Tier 2 structured documentation – architecture, APIs, deployment | Humans and Claude instances needing cross-project reference |
Claude memory (~/.claude/ files) |
MEMORY.md, project-specific memory files | The Claude Code instance on that specific machine |
Git repo docs are the source of truth for individual projects. DocHub aggregates and structures documentation across all projects. Claude memory captures operational knowledge that does not belong in a repo (server IPs, SSH aliases, cross-project domain maps, lessons learned).
These three layers ensure that no matter how a developer (human or AI) enters the system – via a specific project, via DocHub search, or via a fresh Claude Code session – the relevant documentation is accessible.