[codex] Add have-config agent resolver and Hermes profile

README.md

@@ -3,27 +3,36 @@
 HappyVertical shared cross-repo configuration for agent-assisted development.
 
 This repo is the umbrella for configuration that ≥2 HappyVertical projects
-consume. Today that's Claude Code command adapters and Codex workflow skills. Other
-shared config (MCP servers, agent hooks, lint/format/tsconfig bases) will
-land here as second consumers appear.
+consume. Today that's organization standards, service registry docs, agent
+instruction snippets, profile-specific commands/skills, and shared
+lint/format/tsconfig bases. Runtime agent behavior is installed as local files;
+Context Forge is consumed as an install-time snapshot by the have-config
+resolver.
 
 ## What lives here
 
 **In scope:**
 
-- Claude Code command adapters and Codex-visible workflow skills (`claude/`, `codex/`)
+- HappyVertical service registry and infrastructure docs (`docs/`, `services/`)
+- Organization agent instruction snippets (`agent-doc-snippets/`)
+- Profile-specific commands and skills, such as Hermes `check-setup`
+  (`profiles/`)
+- Agent manifests consumed by the have-config resolver (`hv/manifest.json`,
+  `profiles/*/manifest.json`)
 - Shared lint / format / tsconfig configs as published npm packages
   (`packages/eslint-config`, `packages/prettier-config`,
   `packages/tsconfig-base`)
 - MCP server configs consumed by ≥2 projects (planned — `TODO.md`)
 - Agent hook scripts (planned — `TODO.md`)
 - CLAUDE.md / AGENTS.md template sections that should be identical across
-  repos (planned — `TODO.md`)
+  repos
 
 **Out of scope:**
 
 - Runnable tools — these get their own repos (see
   [`happyvertical/pr-review`](https://github.com/happyvertical/pr-review))
+- Generic personal workflows such as `ship` and `review-cycle`; those live in
+  dotfiles and are consumed here as the lowest-priority baseline
 - Per-repo specifics (e.g. anytown's
   `apps/dashboard/docs/ad-network.md`)
 - Anything used by exactly one project
@@ -40,32 +49,26 @@ have-config/
 ├── LICENSE
 ├── install.sh                       # one-line setup (agents)
 ├── TODO.md                          # planned additions, with consumer count
+├── hv/
+│   └── manifest.json                # organization source manifest
+├── profiles/
+│   └── hermes/
+│       ├── manifest.json            # Hermes-only commands and skills
+│       ├── commands/
+│       │   ├── claude/check-setup.md
+│       │   └── codex/check-setup.md
+│       └── skills/check-setup/
+│           └── SKILL.md
+├── agent-doc-snippets/              # cumulative AGENTS / CLAUDE sections
+├── docs/
+│   ├── agent-playbook.md            # what agents use each service for
+│   └── infrastructure.md            # HappyVertical service map
+├── services/
+│   └── services.json                # machine-readable service registry
 ├── package.json                     # pnpm workspace root
 ├── pnpm-workspace.yaml
 ├── .changeset/                      # versioning + publish manifests
 │   └── config.json
-├── claude/                          # Claude Code marketplace
-│   ├── .claude-plugin/
-│   │   └── marketplace.json
-│   └── have/                        # the `have` plugin
-│       ├── .claude-plugin/
-│       │   └── plugin.json
-│       └── commands/
-│           ├── ship.md              # /have:ship adapter
-│           └── review-cycle.md      # /have:review-cycle adapter
-├── codex/                           # Codex marketplace
-│   └── plugins/
-│       └── have/                    # the `have` plugin
-│           ├── .codex-plugin/
-│           │   └── plugin.json
-│           ├── commands/
-│           │   ├── ship.md          # /have:ship adapter
-│           │   └── review-cycle.md  # /have:review-cycle adapter
-│           └── skills/              # Codex adapters to ContextForge
-│               ├── ship/
-│               │   └── SKILL.md     # have:ship
-│               └── review-cycle/
-│                   └── SKILL.md     # have:review-cycle
 └── packages/                        # published npm configs
     ├── eslint-config/               # @happyvertical/eslint-config
     ├── prettier-config/             # @happyvertical/prettier-config
@@ -110,7 +113,7 @@ See each package's README for usage details:
 
 Configs are versioned via Changesets and published on merge to `main`.
 
-## Plugin install (agent workflows)
+## Agent Bootstrap
 
 ```bash
 git clone https://github.com/happyvertical/have-config.git ~/Work/happyvertical/repos/have-config
@@ -120,60 +123,68 @@ cd ~/Work/happyvertical/repos/have-config
 
 `install.sh` does:
 
-1. Clones [`happyvertical/pr-review`](https://github.com/happyvertical/pr-review)
-   if missing, adds `pr-review/bin` to a shell-rc snippet.
-2. Registers this repo as a marketplace for both Claude Code and Codex.
-3. Installs the `have` plugin in both agents.
-4. Optionally symlinks the cached plugin install back to the live repo
-   path for in-place editing (`./install.sh --live`).
+1. Clones or updates the configured dotfiles repo and runs its `install.sh`
+   unless `--skip-dotfiles` or `HAVE_CONFIG_SKIP_DOTFILES=1` is set.
+2. Clones [`happyvertical/pr-review`](https://github.com/happyvertical/pr-review)
+   if missing, adds `pr-review/bin` to the current install PATH.
+3. Resolves dotfiles, have-config, active profile, Context Forge snapshot, and
+   local overrides into local generated agent files.
 
-After install, Claude Code has:
+By default, have-config caches dotfiles under `~/.config/hv/dotfiles` for
+workstations and `~/.hermes/dotfiles` for Hermes agents. Set `DOTFILES_DIR` to
+use a personal checkout instead.
 
-- `/have:ship` — end-to-end shipping pipeline
-- `/have:review-cycle` — multi-tool review/fix/retest loop
+Dotfiles contributes generic baseline workflows such as `ship` and
+`review-cycle` through its `agent/manifest.json`. have-config contributes
+HappyVertical organization standards, service playbooks, service registry data,
+and profile-specific additions.
 
-Codex has equivalent skills:
+Hermes agents additionally get local generated commands/skills:
 
-- `have:ship` — end-to-end shipping pipeline
-- `have:review-cycle` — multi-tool review/fix/retest loop
+- `/check-setup` / `check-setup` — verifies agent access to HappyVertical
+  services
 
-## Editing
+## Agent resolution model
 
-ContextForge is the source of truth for workflow bodies:
+The have-config installer composes agent behavior in this order:
 
-| Workflow | Prompt | Resource |
-|---|---|---|
-| Ship | `have-ship` | `have://happyvertical/workflows/ship` |
-| Review cycle | `have-review-cycle` | `have://happyvertical/workflows/review-cycle` |
+1. dotfiles baseline workflows
+2. have-config organization standard
+3. active profile defaults, such as Hermes
+4. Context Forge install-time snapshot
+5. machine-local overrides
 
-The resources live in the **Happy Vertical** team at
-`context.happyvertical.com`. They store the workflow markdown as a base64
-payload because ContextForge's default content scanner rejects raw shell-heavy
-workflow markdown. The prompt loaders decode that payload and follow it as the
-authoritative workflow.
+For command and skill conflicts, later layers win. For AGENTS and CLAUDE
+behavior, sections are cumulative and assembled in layer order.
 
-Edits to workflow behavior should happen in ContextForge, not in this repo.
-This lets prompt/workflow changes go live without redeploying or reinstalling
-the agent plugins.
+Context Forge remains the dynamic organization policy source, but it is not a
+runtime dependency for normal agent behavior. Export it into
+`HV_CONTEXTFORGE_SNAPSHOT_DIR` and rerun `./install.sh` to materialize new
+local command/skill files and update `agent-lock.json`.
 
-Edits to the adapter files are picked up:
+Hermes profile detection uses explicit environment first:
 
-- **Live mode** (`install.sh --live`): edits are immediately visible to
-  running sessions via symlink. May need re-linking after
-  `claude plugin update` rewrites the cache.
-- **Standard mode**: edits require `claude plugin update have@have-config`
-  for Claude, or rerunning `./install.sh` to refresh the Codex plugin cache.
+- `HV_AGENT_PROFILE=hermes` or `AGENT_PROFILE=hermes`
+- `HERMES`, `HERMES_AGENT`, `HERMES_AGENT_ID`, or `HERMES_HOME`
+- `~/.hermes/profile.json` or `~/.hermes/.profile-hermes`
 
-The Claude command files and Codex `skills/` files must remain thin adapters.
-Do not put canonical workflow text back into this repo.
+When Hermes is active, generated files and reports default under `~/.hermes`.
+Local overrides default to `~/.config/hv/overrides` for workstations and
+`~/.hermes/overrides` for Hermes agents. The installer creates templates there
+but never deletes or rewrites existing override files. On first install,
+existing unmanaged global `AGENTS.md` / `CLAUDE.md` files are adopted into that
+override directory before generated docs are linked.
+
+Edits to dotfiles, have-config, profile files, Context Forge snapshots, or
+local overrides are picked up by rerunning `./install.sh`.
 
 ## Companion tool
 
-The shipping/review commands generate review prompts via
+The baseline shipping/review workflows can generate review prompts via
 [`pr-review`](https://github.com/happyvertical/pr-review). pr-review stays
 a standalone tool because it has a broader audience (anyone running
-pre-PR review with any LLM, regardless of harness). have-config wraps
-pr-review in opinionated workflow commands; pr-review itself is unopinionated.
+pre-PR review with any LLM, regardless of harness). have-config ensures the
+tool is available while organization standards remain in this repo.
 
 ## License
 

TODO.md

@@ -10,8 +10,13 @@ that needs it.
 
 ## Slash commands and agent surfaces
 
-- [x] `claude/` — Claude Code `have` plugin
-- [x] `codex/plugins/have/` — Codex `have` plugin
+- [x] `hv/manifest.json` — org-owned agent docs, env requirements, and service
+      metadata consumed by the resolver
+- [x] `profiles/hermes/` — Hermes-only commands and skills such as
+      `check-setup`
+- [ ] `claude/` / `codex/` packaged surfaces, only if a future second
+      consumer needs marketplace/plugin distribution instead of generated local
+      files
 - [ ] `cursor/` — Cursor commands, when there's a second project using
       Cursor as the primary IDE
 
@@ -51,16 +56,28 @@ Pick when the first consumer pair exists, not before.
 
 ## CLAUDE.md / AGENTS.md template sections
 
-- [ ] `agent-doc-snippets/` — durable policy text that should be
+- [x] `agent-doc-snippets/` — durable policy text that should be
       identical across repos:
-      - No Workarounds Policy
-      - No Private API Reach-Ins
-      - Git Workflow SOPs
-      - Git And PR SOP
-      - Review Readiness
-
-      Today every repo carries its own copy and drift is a recurring
-      problem. Lifting these into snippets would require a
-      consumption mechanism (probably a generator script that
-      assembles each repo's CLAUDE.md from snippets + repo-specific
-      sections).
+      - HappyVertical source layering
+      - runtime behavior
+      - identity and secrets
+      - service map
+
+      The have-config resolver assembles these snippets with active profiles,
+      Context Forge snapshots, and local overrides.
+
+## Service registry and infrastructure docs
+
+- [x] `docs/infrastructure.md` — HappyVertical service map for humans and agents
+- [x] `docs/agent-playbook.md` — agent-facing guide for which service to use
+      for identity, secrets, files, tasks, chat, gateway access, and memory
+- [x] `services/services.json` — machine-readable service registry consumed by
+      have-config reports
+
+## Context Forge snapshots
+
+- [x] `hv/manifest.json` — source manifest consumed by have-config
+- [x] `profiles/hermes/manifest.json` — Hermes-only defaults such as
+      `check-setup`
+- [ ] Publish an exporter from Context Forge into the manifest shape expected by
+      have-config (`manifest.json` with `skills`, `commands`, and `agent_docs`).

agent-doc-snippets/happyvertical-standards.md

@@ -0,0 +1,28 @@
+# HappyVertical Organization Standards
+
+## Source Layers
+- Treat `dotfiles` as the personal baseline for workstation and agent bootstrap.
+- Treat `have-config` as the HappyVertical organization standard for shared agent behavior, infrastructure docs, and reusable development config.
+- Treat Context Forge snapshots as dynamic organization policy materialized during install/update.
+- Treat machine-local overrides as explicit exceptions that must be visible in install reports.
+
+## Runtime Behavior
+- Agents must use local installed command, skill, and instruction files at runtime.
+- Agents should not depend on live Context Forge access during normal task execution.
+- When command or skill definitions conflict, use this order: local override, Context Forge snapshot, `have-config`, then `dotfiles`.
+- AGENTS and CLAUDE instructions are cumulative; do not discard lower-layer instructions unless a higher layer explicitly supersedes them.
+
+## Identity And Secrets
+- Account identity is per user or per agent. Do not commit account-specific addresses, tokens, or passwords.
+- Use `idp.happyvertical.com` for HappyVertical identity and SSO.
+- Use Warden for password sharing and retrieval.
+- Use SOPS only for machine-provided encrypted environment material and templates; do not place real user-specific values in this repo.
+
+## HappyVertical Services
+- Use `warden.happyvertical.com` for approved password and shared secret access.
+- Use `drive.happyvertical.com` for OxiCloud file sharing.
+- Use `todo.happyvertical.com` for Vikunja project management.
+- Use `stoat.happyvertical.com` for chat and collaboration.
+- Use `bifrost.happyvertical.com` as the gateway.
+- Use `context.happyvertical.com` for prompts, resources, and memory snapshots.
+- Hermes agents run `check-setup` after bootstrap or account changes to verify service access.