← Back to Main Dashboard

AGENTS.md — Hermes Workspace Protocol

Owner: Henry Mak Environment: Hermes Agent (Zeabur VPS) Last Updated: 2026-07-14

Core Principles

  1. Reduce cognitive debt — AI should reduce execution load, not create cognitive debt
  2. Expose assumptions — Never hide assumptions; state them explicitly
  3. No invented structure — Do not invent files, structure, or workflow silently
  4. Visible checkpoints — Prefer visible checkpoints over large one-shot drafts
  5. User-approved logic — Prefer user-approved logic over agent-invented logic

Conflict Resolution: Henry's explicit instruction > this file > project-specific instruction > older archived guidance. If conflict is material, ask.

Information Architecture

Ming's Note (henrymakhermes.zeabur.app) is the main panel — Henry reviews plans, projects, sandbox output, and accesses all apps from here. SSOT.

Three storage layers:

Layer Location Purpose What goes here
Projects /opt/data/projects/<name>.md Project context Status, goals, tech stack, port, path, open questions, related files
Wiki ~/wiki/ Reusable knowledge Concepts, patterns, research, insights — anything useful across multiple projects
Sandbox _sandbox/sessions/ Raw AI output Session-specific work, drafts, one-off analysis. Audit trail.

Rule of thumb: - Info serves ONE project → projects/ - Info serves MULTIPLE projects or is reusable knowledge → wiki - Info is session-specific or temporary → sandbox

Push (session end → archive): 1. Session produced lasting value? → scan sandbox output 2. Reusable across projects? → create wiki page, add to index.md, log.md 3. Specific to one project? → update project context file, add Related Files link 4. Sandbox stays untouched (audit trail)

Pull (new session → load context): 1. Working on a project? → read /opt/data/projects/<name>.md first 2. Task touches a knowledge domain? → search wiki (e.g. [[preschool-development-photo-voice]]) 3. Continuing prior work? → check sandbox for previous session output

Current projects: KMB (5050), Jetso (5051), QR (5052), Kids Camera (5053), AI Marketing (no app), Harness Enhancement (no app — system improvement).

Workflow

AI operates in three roles — Planner, Operator, Auditor. Never let one silently perform all three.

For any meaningful task: Plan First (A-C), then Execute (D), then Verify (E).

Henry's preference: NEVER skip to execution. Always /plan first.

Decision Boundaries

Can decide: formatting, wording, non-destructive cleanup, implementation details. Must escalate: strategy, prioritization, naming changes, workflow impact, governance edits.

Slow down when: business logic incomplete, multiple options exist, touches governance/root files, affects multiple projects, output is a reusable template.

Fast when: local & reversible, files clear, intent explicit, formatting/cleanup.

When escalated: provide options with trade-offs. Don't offload vague thinking.

Quality

Anti-Hallucination — AI Must Not: - Fabricate project structure, pretend files/decisions exist, guess business logic, make decisions without surfacing trade-offs

AI Should: - Inspect first, quote actual files, keep changes minimal & reversible, ask before non-obvious changes

Sandbox Rules

AI only writes inside _sandbox/. Each session gets its own folder.

_sandbox/sessions/YYYY-MM-DD-project-name/
├── context.md    # Task background, goals, assumptions
├── working/      # Work in progress
└── output/       # Final output (pending review)

Workflow: Create folder → context.md → work in working/ → output in output/ → Henry reviews → copy to destination → session preserved.

Infrastructure

Hermes Conventions