Skip to content

Session Protocol

This page is canonical. The ESG Screening project runs across two distinct kinds of Claude session, plus Slack as the event log. This page is the operating manual.

The same content has historically lived in three places: the project instructions on claude.ai, .claude/CLAUDE.md in the repo, and pinned Slack notes. Those still exist, but they now defer here.

The three surfaces

Surface What it is Authoring Persistence
Chat session (claude.ai) Interpretive work, design, framing, drafting Browser-based, one Rob, one Claude Per-chat (project memory between chats)
CC-on-VM (Claude Code on the Azure VM) Build, commit, deploy work SSH'd into the VM as azureuser Per-session terminal; state lives in the repo
Slack #esg-screening Event log Manual handoff at session end Permanent, searchable

Chat sessions — what they're for

Use a chat session for:

  • Interpretive work on spec documents (the v0.4 workbook, an ADR draft)
  • Producing complete artefacts to hand to CC-on-VM (SQL, JSON, design notes, scraper specs, seed files)
  • Decisions, naming, framing, planning
  • Drafting Slack handoffs
  • Writing or updating this ops site's content

Don't use a chat session for:

  • Stack health checks (PM2, /health, DB state) — VM-only
  • Reading .claude/CLAUDE.md — lives on the VM
  • Any file write, migration, commit, or push to the repo

Chat session opener (canonical):

Picking up the ESG screening project — please follow session start ritual.

This triggers Claude to read the latest Slack handoff in #esg-screening, acknowledge what was read, and proceed. The project instructions on claude.ai handle the rest.

Chat session closer (canonical): Claude drafts a Slack handoff to #esg-screening (the manual sender being Rob — Claude drafts, Rob reviews and sends). The handoff format is in handoff-template.md.

CC-on-VM — what it's for

Use CC-on-VM for:

  • Schema migrations
  • Building scrapers, scoring modules, UI templates
  • Committing and pushing to the main repo
  • Anything that touches the running stack (PM2 restarts, log inspection, DB inspection)
  • Running npm run scrape, npm run score, etc.

CC-on-VM opens via:

esgc

The esgc PowerShell function opens an SSH session into the VM and launches Claude Code in bypass-permissions mode (--dangerously-skip-permissions). This mirrors the Vextor vex pattern. No tool prompts during the session.

CC-on-VM session opener (canonical): Claude reads .claude/CLAUDE.md first, then the latest Slack handoff in #esg-screening, then proceeds with whatever the handoff specifies.

CC-on-VM session closer (canonical): Claude posts its own technical handoff to #esg-screening covering what landed (commits, migrations, verification results, surprises, anything next-Rob needs to know). Followed by a manual session-wrap handoff from Rob if the cycle was multi-step.

Slack #esg-screening — what it's for

The event log. Searchable, permanent, append-only by convention.

Three kinds of message belong here:

  1. Session handoff — at the end of every chat or CC-on-VM session. Format in handoff-template.md.
  2. Pinned canonical notes — short notes that override or clarify project state. Currently one pinned: the canonical hierarchy note.
  3. In-session updates — when something surprising or blocking happens mid-session.

This is NOT for:

  • Standing reference content (architecture, methodology, glossary). Those belong on this ops site. If you find yourself re-explaining the same thing in handoffs, put it on the ops site and reference it.

The flow, end to end

┌─────────────────────────────────────────────────────────────────┐
│                                                                  │
│   Chat session (interpretive)                                    │
│   ────────────                                                   │
│   • Read latest Slack handoff                                    │
│   • Do the interpretive work                                     │
│   • Produce artefacts (in /mnt/user-data/outputs/)               │
│   • Draft Slack handoff for review and send                      │
│                                                                  │
│              │                                                   │
│              ▼ (Slack handoff)                                   │
│                                                                  │
│   CC-on-VM session (build)                                       │
│   ──────────                                                     │
│   • Read .claude/CLAUDE.md                                       │
│   • Read latest Slack handoff                                    │
│   • Execute the build (migration / scraper / commit / push)      │
│   • Verify against expected outcomes                             │
│   • Post own handoff to Slack covering what landed               │
│                                                                  │
│              │                                                   │
│              ▼ (next session, possibly weeks later)              │
│                                                                  │
│   Next chat session — picks up from Slack handoff                │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

The patterns that took a while to settle

Some patterns are now established that weren't obvious from the start. Recording them here so they aren't re-derived.

CC self-drives from a complete handoff

CC-on-VM reads the Slack handoff, treats it as a full spec, and executes without needing a "do the work" follow-up. Chat-session handoffs should be end-to-end actionable, not "design now, ask CC to plan later."

CC writes code; chat writes spec

Code-writing belongs to CC, which can see the live schema and module signatures. Chat hands over functional spec + irreducible artefacts (seed data, design notes) and lets CC write code against live state.

Recorded after cycle C (12 May) had 8 categories of column-name reconciliation because chat drafted SQL against assumed schema. Cycle A (13 May) delegated code-writing to CC and had two LEI corrections and one migration-number correction — smaller surface for surprises.

Chat-side LEIs cannot be trusted

Any LEI or GLEIF-verifiable identifier in a chat-drafted artefact should be either looked up live during chat (via search results) or left blank with CC: populate via GLEIF. Never trust a chat-side LEI guess. Two LEI errors in the PRB seed (NatWest, HSBC) confirmed this on 13 May.

"Permissions off" means "bypass mode"

In operator shorthand "permissions off" means "no prompts" = --dangerously-skip-permissions mode, not "deny everything." Vextor and ESG Screening both run CC-on-VM in this mode.

When CC-on-VM hits a no-credentials wall, gh auth login

Pattern from 12 May. When CC-on-VM cannot push because there's no PAT or credential helper, gh auth login (browser device-code flow) is the resolution path. gh manages the token at rest; no PAT dropped to /root.

Anti-patterns

These have been tried and don't work. Recording so they aren't tried again.

  • Re-pasting full chat history into the next chat. Feels safe, costs tokens, and the Slack handoff + project instructions already carry the load. Trust the handoff.
  • Slack handoffs that re-explain methodology. They get long and next-Rob still doesn't read them. Methodology belongs on this site; handoffs reference it.
  • Chat session writing code against assumed schema. See "CC writes code; chat writes spec" above.
  • Hand-classified GICS codes without verification. IKEA's GICS in migration 005 was hand-classified and later flagged as probably wrong. When the catalogue is licensed or formally verified, revisit.