Project Workspace

IDENTITY: Architect.ConventionEnforcer. Establish and enforce one shared workspace layout so multiple Hermes profiles can work on the same projects without path confusion, duplicated clones, or sandbox isolation. Law: UniversalConventionFirst — apply pattern to ALL profiles immediately, never leave user to retroactively fill gaps. WHENUSE: SettingUpNewProfile|MultiAgentProject|Debugging"CantFindRepo"|OnboardingNewAgent. ESPECIALLY:ProfilesHaveSandboxedHome|SharedKnowledgeNeeded|NewAgentNeedsScratchFolder. NoSkip:OnboardingFullSetup{sixSteps}. REDFLAGS: GHRepoCloneWithoutAbsTarget->SandboxClone|GitCloneWithRelativePath->VerifyPWD|npmStartLaunchesGUI->DocumentHeadlessCmdInAGENTS.md|SymlinkBetweenSandboxAndRealHome->FragileProfileCleanupBreaksIt. RATIONALIZATIONS: CloneToSandboxAndMoveLater->CloneCorrectlyFirstTime|ProfileHomeIsFineForProjects->SandboxedPathInvisibleToUser|JustTellAgentWhereRepoIs->AGENTS.mdIsSingleSourceOfTruth. QUICKREF: Diagnose{CheckRealProjectsDir->CheckAllSandboxes->MoveToCanonical->UpdateRemoteURL}->Onboard{CreateScratchFolder->UpdateSCHEMA.md->UpdateIndex.md->AppendLog.md->NoteInSOUL.md->DocumentDomain}.

Project Workspace

Core Principle: Universal Convention First

When you establish a pattern for one profile (scratch folder, config path, credential sync), apply it to ALL existing and future profiles immediately — never leave the user to retroactively fill gaps. The user's instinct is "do this for all profiles to mitigate this in the future." Trust and follow that instinct proactively.

Conventions for organizing project files so that multiple Hermes profiles (Senna, Coder, Foreman, Reviewer, etc.) can work on the same projects without path confusion, duplicated clones, or "I can't find the repo" problems.

The Core Problem

Hermes profiles remap $HOME to a sandboxed directory:

Real home:         /Users/<you>/
Senna's home:      ~/.hermes/profiles/senna/home/
Coder's home:      ~/.hermes/profiles/coder/home/
Foreman's home:    ~/.hermes/profiles/foreman/home/

When any profile uses ~/path or relative paths for git clone, the repo lands in its own sandbox — invisible to the user and to other profiles.

Knowledge Store Conventions

Hermes profiles also need to share a knowledge base across sessions. The same "one shared copy" principle applies.

Canonical knowledge stores

The knowledge base is a unified wiki inside the Obsidian vault. Both "knowledge" (concepts, research, entities) and "operations" (protocols, conventions, agent scratch spaces, decisions) live in llm-wiki/:

llm-wiki/                    # Second brain (Karpathy pattern) — unified wiki
├── SCHEMA.md               # Conventions, tag taxonomy, page types
├── index.md                # Content catalog with one-line summaries
├── log.md                  # Append-only action log
├── raw/                    # Immutable source material (articles, papers, transcripts)
├── entities/               # Entity pages (people, orgs, products, models)
├── concepts/               # Concept/topic pages
├── comparisons/            # Side-by-side analyses
├── queries/                # Filed query results
├── alloys/                 # Synthesized pages combining 2+ existing pages
└── operational/            # Agent operations — how we do things, not what we know
    ├── agents/             # Per-agent scratch spaces (senna, foreman, coder, ...)
    ├── protocols/          # Handoff rules, inter-agent contracts, kanban workflow
    ├── conventions/        # Standards, style guides, commit patterns
    └── decisions/          # Architectural decision records with rationale

Team-Wiki is archived. Team-Wiki/ was merged into llm-wiki/operational/ in May 2026. If you encounter references to Team-Wiki/ in older memory or files, the canonical path is now the operational/ directory above.

Obsidian vault: /Users/<you>/Hermes Vault/Hermes/ (PARA structure: 0-Inbox/ through 4-Archive/ plus icarus/, Memory/, Daily Notes/).

Rules:

• Durable knowledge (entities, concepts, comparisons) goes to the shared folders, tagged appropriately in frontmatter.
• Scratch notes stay in operational/agents/<name>/ — transient unless promoted.
• Operational pages (protocols, conventions, decisions) document how the agent system works, not domain knowledge.
• Promotion path: when scratch notes mature, the agent promotes to concepts/, entities/, or operational/decisions/ with proper frontmatter, wikilinks, and index entry.

Why not separate vaults: Cross-pollination. The researcher finding a paper and the coder finding a related implementation pattern should connect in the same graph. Separate vaults would never discover those links.

Onboarding a new profile

When creating a new Hermes profile, before first use, run the full setup:

1. Create its scratch folder: mkdir -p /Users/<you>/Hermes\\ Vault/Hermes/Team-Wiki/profiles/<name>/
2. Update SCHEMA.md — add a row to the agent table in the "Agent Scratch Spaces" section
3. Update index.md — add the new agent to the Scratch Spaces table
4. Append to log.md — record the new agent with "[YYYY-MM-DD] create | Added agent to scratch spaces"
5. Note the scratch path in the profile's SOUL.md or Mnemosyne memory so the agent knows where to write
6. If the profile has a specific domain (e.g. researcher → raw/ ingest), document that in SCHEMA.md

This ensures every future profile inherits the knowledge architecture without retrofitting. If you forget a step, catch it during team-wiki/maintain which will flag missing profile folders.

The Standard

One shared copy, absolute paths, project-level metadata.

1. Canonical location

/Users/<you>/projects/<project-name>/

All profiles use this absolute path. No ~/ ambiguity. The user sees it in Finder. All agents can cd there regardless of which profile is active.

2. Project-level metadata: AGENTS.md

Each project root can contain an AGENTS.md file that any agent reads when it starts working on that project. This replaces fragmented conventions spread across memory or chat history.

# AGENTS.md

## Project
HermesMirror — fork of MagicMirror² (https://github.com/MagicMirrorOrg/MagicMirror)

- `references/agents-md-conventions.md` — AGENTS.md patterns: roadmap, DO NOT launch GUI, worker recovery, HelixMirror example
## Conventions
- npm installs must be vetted before running
- Upstream remote: `upstream` → MagicMirrorOrg/MagicMirror
- Test runner: vitest (not plain jest)
- Lint: ESLint with project config

## Filesystem layout
- ~/projects/HermesMirror/
- Modules: ./modules/
- Config: ./config/

See templates/AGENTS.md for a starter template. The template has placeholder variables ({{PROJECT_NAME}}, {{USER}}, etc.) — replace those when creating a real AGENTS.md for a project.

See references/hermesmirror-agents.md for a concrete real-world example (the HermesMirror AGENTS.md written during a live session). It shows all sections in practice — tech stack table, key commands, conventions, and the path/sandbox caveat.

See references/agent-topology.md for the multi-profile fleet topology map, the current communication model (delegate_task), and how the A2A protocol plugin would enable peer-to-peer communication between profiles — including the single-profile constraint, the multi-gateway workaround, and which profiles benefit most from running as persistent A2A gateways.

3. Git remotes

• origin → your fork on GitHub
• upstream → the original repo (for forks)

Agents always work on origin. Push/pull via gh credential helper (see github-auth skill).

4. Shared auth

All profiles use the same gh credential, which writes to ~/.hermes/profiles/<name>/home/.config/gh/hosts.yml. After gh auth login --with-token from one profile, sync the config:

cp ~/.hermes/profiles/senna/home/.config/gh/hosts.yml ~/.config/gh/hosts.yml

Each profile's gh reads its own sandboxed copy — sync to real home makes it available for manual user terminal use.

Diagnosing "I can't find the repo"

If the user says a project isn't visible:

# 1. Check real projects directory
ls /Users/<you>/projects/ 2>/dev/null

# 2. Check all Hermes profile sandboxes
for p in ~/.hermes/profiles/*/; do
  sandbox="${p}home/projects"
  if [ -d "$sandbox" ]; then
    echo "--- ${p##*/} sandbox ---"
    ls "$sandbox"
  fi
done

# 3. If found in a sandbox, move it to canonical location
mv ~/.hermes/profiles/<name>/home/projects/<repo> /Users/<you>/projects/<repo>

After moving, update the remote URL if it has an embedded token:

cd /Users/<you>/projects/<repo>
git remote -v  # check for @github.com patterns
# If embedded token found:
git remote set-url origin https://github.com/<owner>/<repo>.git

Pitfalls

• Electron / desktop GUI projects: npm start launches a full-screen window. Many projects (Electron, Tauri, etc.) map npm start to launching the desktop GUI. When dispatching fix tasks to such projects, workers must verify changes with headless alternatives: npm run server, npm test, or npm run config:check — never npm start. Document the headless command in the project's AGENTS.md under Key Commands. Example: HermesMirror uses npm run server for headless mode.
• gh repo clone always uses sandboxed HOME. Never run it bare — always append an absolute target: gh repo clone owner/repo /Users/<you>/projects/repo
• Relative paths in git clone resolve against $PWD, which may also be sandboxed. Verify with pwd before cloning.
• Moving a repo that was ahead of origin — check git status first. An unpushed commit needs to be pushed before (or after) the move.
• Symlinks between sandbox and real home can work but are fragile — profile directory cleanup or reinstallation can break them. Prefer a single canonical copy.