OmelasAI — CLAUDE.md Base Template

This is the mandatory foundation for every CLAUDE.md across all OmelasAI containers and projects. Every container’s CLAUDE.md MUST include all rules from this base. Container-specific and project-specific details are added AFTER this foundation.

Source of truth: OmelasAI/claude-skills repo → CLAUDE-BASE.md Last updated: 2026-03-08

1. ABSOLUTE RULES — NEVER VIOLATE

These rules apply to every Claude Code instance in the OmelasAI organization. They are not suggestions. They are hard constraints.

1.1 Claude Net — FIRST CHOICE for Messaging

When anyone says “send a message to [person/container]”, use Claude Net FIRST. This is the primary communication channel between all OmelasAI containers and team members.

Machines: chasclaude, infoclaude, seanclaude, jazclaude, managerclaude, laptopclaude, serclaude

Rules:

• Claude Net is internal inter-container coordination — it is safe to send directly, no draft needed
• If user says “message Sean” → claude_net_send("seanclaude", "...")
• If user says “tell Jaz” → claude_net_send("jazclaude", "...")
• If user says “notify all” → send to each container individually
• Check claude_net_machines() if unsure who is online
• Check claude_net_inbox() periodically or when asked about messages

1.2 External Communications — DRAFT ONLY, NEVER SEND

• NEVER use send_email — ALWAYS use draft_email. No exceptions, no edge cases.
• You do NOT send emails on behalf of anyone. You ONLY create drafts for the user to review and send manually.
• This applies to ALL external communication tools: email, Slack, webhooks, SMS, push notifications, API calls to messaging services.
• If a user says “send an email to X”, you interpret that as “draft an email to X”. Always draft. Never send.
• Exception: Claude Net (Section 1.1) is internal — direct sending is allowed and expected.

1.3 External Actions — Confirm Before Executing

Any action visible to people or systems outside this container requires explicit user confirmation:

• Emails: DRAFT only. Never send.
• GitHub PRs, issues, comments: Confirm before creating or posting.
• Webhooks, external API calls: Confirm before executing.
• Production deployments: Use /deploy skill which requires confirmation. Never deploy silently.
• Anything irreversible: Ask first.

General rule: If it leaves this container and reaches a human or external service, it must be a draft or require explicit confirmation before execution.

1.4 Session Persistence — NEVER Exit Claude

• Claude Code runs inside a persistent tmux session. It stays alive 24/7.
• You NEVER exit Claude. Not at end of day. Not when switching projects. Not for any reason.
• /end-session pauses project work (commits, pushes, writes handover). Claude stays running.
• If the user disconnects (brownout, device switch), the session persists. They reconnect via mosh/ssh and resume.
• There is no “exit” or “quit” or “close” command. The session is always alive.

1.5 Servers — Do NOT Access Without Permission

• You do NOT SSH to any server unless the user explicitly asks.
• You do NOT modify files on any machine other than your own container.
• Even if a task seems obvious (“deploy to production”), confirm the target server before connecting.
• When working on a remote server, state what you’re doing: “I’m now connected to [server], running [command].”

1.6 Secrets and Credentials

• NEVER commit .env files, API keys, passwords, or credentials to git.
• NEVER log actual secret values in OPS-LOG.md — log THAT credentials changed and WHERE, not the values.
• NEVER display secrets in output unless the user explicitly asks.
• If you notice credentials in a staged file, warn immediately and unstage.

2. STANDARD PROJECT STRUCTURE

Every OmelasAI project MUST have these files. If they don’t exist, create them.

project-root/
├── CLAUDE.md        # AI context — architecture, rules, deployment, key files
├── HANDOVER.md      # Last session state — auto-generated by /end-session
├── CHANGELOG.md     # Significant changes log
├── OPS-LOG.md       # Operational incidents — append-only, never delete entries
├── docs/
│   ├── architecture.md   # System design, components, data flow
│   └── deployment.md     # How to deploy, server details, commands
└── .gitignore       # Must exclude: .env, node_modules/, dist/, credentials

File Purposes

OPS-LOG.md Format

## YYYY-MM-DD — Brief descriptive title
**Problem:** What went wrong or what needed to change
**Cause:** Root cause if known
**Fix:** Exactly what was done to resolve it
**Files changed:** List of files/configs/services affected
**Prevention:** How to avoid this in future, or "N/A"

3. STANDARD WORKFLOW

Starting Work

/start-session

This loads CLAUDE.md, HANDOVER.md, OPS-LOG.md, pulls latest, shows summary. Run it FIRST.

During Work

/commit          — checkpoint (repeatable)
/push            — send to GitHub
/incident        — log operational issues
/deploy          — deploy to production (with confirmation)
/branch          — manage branches

Pausing Work

/end-session

This commits, pushes, writes HANDOVER.md, updates memory. Claude stays running.

Full Workflow

/start-session → work → /commit → /push → /end-session

When Picking Up Someone Else’s Project

1. cd to their project directory (or clone it)
2. /start-session — loads their handover, ops-log, CLAUDE.md
3. Work on the issue
4. /incident — if it was an operational problem
5. /end-session — leave your own handover for next person

4. ALL SKILLS (16 commands)

Session Lifecycle

Git Workflow

Operations

Documentation

Setup

5. GIT RULES

• All code changes MUST be committed and pushed to GitHub.
• All documentation and markdown files live in the git repo alongside the code.
• Use /commit and /push skills for git operations.
• NEVER force push (--force, --force-with-lease) unless the user explicitly asks.
• NEVER force push to main/master — refuse even if asked.
• NEVER skip hooks (--no-verify) unless the user explicitly asks.
• NEVER amend commits unless the user explicitly asks — always create new commits.
• Commit messages use imperative mood: “Add feature” not “Added feature”.
• End every commit with: Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

6. DOCUMENTATION EXPECTATIONS

During Development

• When /commit detects significant changes (new endpoints, architecture changes, config changes), it hints about updating docs.
• When /end-session runs, it writes HANDOVER.md automatically.
• When operational incidents occur, use /incident to log them immediately.

What Gets Documented

• Architecture decisions and why they were made
• Deployment procedures and server details
• Operational incidents (credential rotations, service outages, email bans, DNS changes)
• Integration points between projects
• Key technical constraints (“DOM-only rule”, “VITE_SAAS=1”, etc.)

Where Documentation Lives

1. In the git repo (CLAUDE.md, OPS-LOG.md, docs/) — travels with the code
2. In DocHub (https://docs.ipnoelp.com) — browsable, searchable, API-accessible
3. In Claude memory (~/.claude/projects/*/memory/) — persistent across sessions

DocHub Three-Tier System

• Tier 1: Visual HTML overviews for humans browsing
• Tier 2: Structured markdown for developers reading
• Tier 3: JSON manifests + API for Claude CLI integration

7. INTER-CONTAINER COLLABORATION

Claude Net — See Section 1.1 (Absolute Rule)

Claude Net is the primary communication tool between containers. Full reference in Section 1.1.

Quick reminder: claude_net_send(to, message) — send directly, no draft needed.

Handoff Protocol

When someone is unavailable and their project needs work:

1. Connect to their container (or clone the repo)
2. Run /start-session — loads their handover and context
3. Fix the issue
4. Run /incident if it was operational
5. Run /end-session — leave handover for next person
6. Use claude_net_send to notify them what was done

GitHub

• Organization: OmelasAI (private repos)
• All containers authenticate via gh CLI
• Every project has a repo in the OmelasAI org

8. REDUCING UNNECESSARY QUESTIONS

• Batch questions — ask ONE question with all needed info, not five sequential prompts.
• Don’t ask permission for routine operations — git add, git commit, file reads, grep searches.
• Do ask for decisions — architecture choices, deployment targets, destructive operations.
• Read CLAUDE.md as the authority — if it says how to deploy, just do it (with confirmation per Section 1.2).
• Don’t re-ask what’s already documented — check CLAUDE.md, HANDOVER.md, OPS-LOG.md first.

9. HOW TO USE THIS BASE TEMPLATE

Every container’s CLAUDE.md should be structured as:

# {Container/Project Name}

## Who You Are
{Container identity, owner, IP, purpose}

## CRITICAL: Operational Boundaries
{Include ALL rules from CLAUDE-BASE.md Section 1}
{Add container-specific boundaries}

## Projects
{What projects this container works on}

## Servers
{What servers this container can access}

## Container-Specific Rules
{Any additional rules unique to this container}

## {Project-specific sections as needed}

The base rules (Sections 1-8 above) are mandatory inclusions. Container-specific details are added on top.

When updating this base template, propagate changes to ALL containers:

• chasclaude (/home/dev/.claude/CLAUDE.md)
• infoclaude (/home/dev/.claude/CLAUDE.md)
• seanclaude (/home/dev/.claude/CLAUDE.md)
• jazclaude (/home/dev/.claude/CLAUDE.md)
• managerclaude (/home/dev/.claude/CLAUDE.md)

This base template is maintained in OmelasAI/claude-skills → CLAUDE-BASE.md and should be the single source of truth for all mandatory Claude Code behavior across the organization.