# cto (repo) · cto-planb (Hermes profile)

**Hermes classification:** profile distribution (C-suite, instance #3, Plan B-scoped)
*Inherits Karpathy 4 rules from `~/.claude/CLAUDE.md` — read them before coding.*

## What this is

CTO agent for Plan B — WebUI direct coding profile with Sandcastle background-job support. Decomposes JP/CEO tech goals, patches scoped Hermes-owned work directly when risk allows, delegates independent review/exploration, launches Sandcastle for broad/risky/background branches, requests JP approval for high-risk actions, and reports proof. Never deploys directly. Instance #3 of the C-suite profile distribution family.

**Naming:** the repo dir is `cto/` (generic). The deployed Hermes profile is `cto-planb` (Plan B-scoped, driven by `distribution.yaml → name`). Future orgs would clone this repo and set `name: cto-<org>` in their `distribution.yaml`.

**Status:** v2.0 migration — static direct-coder skills and eval expectations are present; full WebUI runtime parity still requires live eval evidence.

## Hard rules

- CTO may directly patch scoped Hermes-owned files for R1 work; use Sandcastle for broad/risky/background branch attempts
- CTO NEVER merges to main without JP `approve` (definition of "deploy" per CONTRACT.md §3)
- CTO NEVER touches infrastructure (DNS, certs, secrets, cron, cloud) — escalate always
- CTO NEVER edits `../sandcastle/` — read-only workspace hard rule (mattpocock/sandcastle pinned v0.5.11)
- `cto.db` never committed — created by `install.sh`, managed at runtime
- CTO uses a focused skill set only; do NOT add broad unrelated skill libraries here
- Structural changes follow `../sot/03-PROTOCOLS/PROFILE-DISTRIBUTION-PROTOCOL.md`

## Structure

```
cto/
├── manifest.yaml                    # profile: cto-planb, kind: profile-distribution
├── distribution.yaml                # Hermes native install contract
├── AGENT.md                         # CTO identity (role, mission, boundaries)
├── CONTRACT.md                      # CTO behavior contract — tier T1 (this file wins)
├── install.sh                       # idempotent installer → ~/.hermes/cto-planb symlink (skeleton)
├── credbridge.sh                    # secrets bridge (skeleton — github-pat only in v1)
├── schema.sql                       # cto.db schema (work_queue, agent_runtime, invocations)
├── skills/
│   ├── cto-agent/                   # supervisor and profile protocol
│   ├── cto-direct-coder/            # direct inspect-plan-patch-test-report loop
│   ├── cto-repo-contract/           # workspace contract
│   └── ...                          # focused reviewer/evals/sandbox/capsule/QA skills
└── cron/                            # empty for v1 (CEO precedent — on-demand only)
```

## Gotchas

- Sandcastle is at `../sandcastle/` (sibling). Read its `CONTEXT.md` before writing any sandcastle.run() invocation — the terminology (sandbox provider, branch strategy, agent provider) matters
- `cto/` does NOT inherit `cmo/`'s 40-skill complexity — keep the direct-coder skill set focused and PRD-bound
- Runtime promotion remains blocked until live WebUI evals and disclosure drift checks pass
- credbridge in v1 resolves only `github-pat`; other creds (deploy, cloud) deferred to v2 per CONTRACT.md §4
- When adding runtime code: write deterministic tests first, wire the smallest Hermes-native surface, then run the CTO PRD static gate and targeted WebUI tests

## When to update this CLAUDE.md vs other docs

- This file: gotchas, hard rules, structure overview — what a Claude session needs to navigate the repo
- `AGENT.md`: identity (role, mission, principal) — what CTO IS
- `CONTRACT.md`: behavior contract — what CTO DOES and does NOT do, decisions, anti-patterns (tier T1)
- `manifest.yaml`: machine-readable identity + install hooks
- `distribution.yaml`: Hermes native install contract (separate from manifest by design)
- `README.md`: human-facing intro + install instructions


## Site map — where to find anything in cortex-os

Read these in order to ground any session:

| What | Where |
|---|---|
| **Karpathy 4 rules** | `~/.claude/CLAUDE.md` (auto-inherited every session) |
| **Workspace contract + repo map** | `~/workspaces/hermes/CLAUDE.md` |
| **SOT library orientation** | `~/workspaces/hermes/sot/README.md` |
| **Curator-generated SOT index** | `~/workspaces/hermes/sot/INDEX.md` |
| **Profile catalog (5 profiles + tool disclosure + governance)** | `~/workspaces/hermes/sot/06-REGISTRY/PROFILE-CATALOG.md` |
| **Profile distribution protocol (T1)** | `~/workspaces/hermes/sot/03-PROTOCOLS/PROFILE-DISTRIBUTION-PROTOCOL.md` |
| **Frontmatter spec (T1)** | `~/workspaces/hermes/sot/04-STANDARDS/FRONTMATTER-SPEC.md` |
| **SOT enforcement (pre-commit + curator + pre-push)** | `~/workspaces/hermes/sot/04-STANDARDS/SOT-ENFORCEMENT.md` |
| **Living graph artifact** | `~/workspaces/hermes/graph/umbrella.json` (curator-maintained) |
| **Living graph UI panel (planned)** | `/umbrella` route in hermes-webui per `sot/03-PROTOCOLS/CORTEX-OS-UMBRELLA-VIZ-PRD.md` |
| **This repo's CONTRACT.md** | `./CONTRACT.md` if present (T1 — wins over everything in this repo) |

If you're new to a session: read the workspace contract first, then this file, then the SOT orientation. Don't guess about cortex-os structure — anchor to these.