jambonz-observability

Cross-repo design, schemas, and shared artifacts for the jambonz Session Observability feature.

What's in this repo

• DESIGN.md — the canonical design document for the feature. Read this first.
• HANDOFF.md — rolling shift-handoff log between developers. Most recent shift on top.
• schemas/ — JSON Schema for session.json (the artifact written to customer buckets at call end).
• bundle-viewer/ — standalone HTML viewer used in the downloadable-bundle endpoint.
• fixtures/ — sample session.json files (agent, s2s, verb-only) for testing.

Why a separate repo

The Session Observability feature spans four implementation repos: feature-server (writes session data), recorder / upload_recordings (uploads to bucket), api-server (serves data and bundles), and webapp (renders the UI). Putting the design doc, the shared schema, and the bundle viewer in one place avoids drift and gives both the doc and the schema a single source of truth.

Working with this repo alongside an implementation repo

When you start a Claude Code session in any of the implementation repos, include this directory so Claude has visibility into the design and schema:

cd /path/to/feature-server         # or api-server, webapp, etc.
claude --add-dir /path/to/jambonz-observability

Open Claude with the prompt:

Read jambonz-observability/HANDOFF.md (focus on the most recent entry) and jambonz-observability/DESIGN.md. I'm picking up the session observability work — let's continue from where the last shift ended.

Claude then has both the implementation code and the design context loaded.

Distributed development handoff procedure

This feature is co-developed by Dave (US) and Hoan (Asia) on a follow-the-sun rotation. Claude Code sessions are user-scoped and machine-local — there is no "shared conversation." The repo is the only durable handoff channel.

Core principle

The conversation is ephemeral. The repo state is permanent. Anything worth preserving must land in git before you close your Claude session.

End-of-shift ritual (~10 minutes)

1. Find a clean stopping point. Not necessarily a working state, but a coherent one. Don't leave the next person an incomprehensible half-state — stop at a file boundary if mid-refactor.

2. Ask Claude to summarize the session. Something like:

   "Summarize what we did this session, what's in progress, and what decisions we made. Format it as a HANDOFF.md update. Include file paths for anything in progress."

   Review the output — Claude sometimes overstates progress or undersells nuance. Edit it yourself.

3. Update HANDOFF.md with a new entry at the top (see template below).

4. Update DESIGN.md if you made any durable design decisions during the shift. The handoff note should reference them; the design doc is where they live permanently.

5. Commit and push everything.

   • Work-in-progress branches in each implementation repo touched (push WIP commits to feature/... branches, never to main).
   • HANDOFF.md and DESIGN.md updates in this repo.
   • If you have uncommitted work you're nervous about, commit it to a WIP branch with a clear wip: prefix in the commit message rather than leaving local stashes.

6. Close the Claude session. Done.

Start-of-shift ritual (~10 minutes)

1. Pull everything. git pull in this repo and in any implementation repo you'll touch.

2. Read HANDOFF.md first, in your editor or browser. Not in Claude — read it yourself, form your own understanding.

3. Read any DESIGN.md diffs since your last shift (git log -p --since="2 days ago" DESIGN.md). Understand any durable decisions before asking Claude to build on them.

4. Skim the prior shift's commits in the implementation repos (git log --oneline plus diffs of anything that looks surprising). The handoff doc says what the prior dev thinks they did. The code says what they actually did. These sometimes diverge.

5. Start Claude Code from the implementation repo, with this directory added:

   claude --add-dir /path/to/jambonz-observability

6. Open with an explicit instruction to read the handoff:

   "Read jambonz-observability/HANDOFF.md. The top entry is the most recent — focus there. Earlier entries are historical context, only consult if needed. Then read DESIGN.md for the feature spec. I'm picking up from [Dave/Hoan]'s last shift."

7. Work your shift. Any design decisions you make go into DESIGN.md as you make them, not saved for end-of-shift.

8. At the end of your day, do the end-of-shift ritual back to the other person.

HANDOFF.md entry template

Append a new entry at the top of HANDOFF.md with this structure:

## YYYY-MM-DD — <Name> (ending shift)

### Done
- <bullet list of completed work, with file paths>

### In progress
- <task that wasn't finished, with file path and line number / TODO marker>

### Next up
- <what the next shift should pick up first>
- <subsequent items, in order>

### Decisions made (also in DESIGN.md)
- <decision and brief rationale; pointer to DESIGN.md section if applicable>

### Blockers / questions for next shift
- <open questions; tag the recipient if directed>

### Branch state
- feature-server: <branch name>, HEAD <short sha>
- jambonz-observability: <branch name>, HEAD <short sha>
- <other repos as relevant>

---

Newest entry on top. Horizontal rule between entries. Don't wipe; keep the full history. When the file gets uncomfortably long (after several months), move the oldest entries to HANDOFF_ARCHIVE.md in one batch.

Practical tips

• Keep HANDOFF.md short. It's a baton, not a report. If a shift produces more than a page, real design content is leaking — push it to DESIGN.md.
• Use PR descriptions as a second handoff channel for changes scoped to a single repo. HANDOFF.md gives the cross-repo meta-view; PRs cover individual changes.
• Use overlap windows for synchronous clarification. A 15-minute live chat resolves more than a day of async on a confusing handoff.
• Don't have Claude write the handoff alone. Draft with Claude, then review and edit. Claude misses nuance like "this looked right but I'm nervous" or "this is urgent vs. nice-to-have."

Schema versioning

The session.json envelope carries a schema_version field. When making schema changes:

1. Update schemas/session.json and bump the version (semver).
2. Update fixtures to match.
3. Note the change in DESIGN.md and HANDOFF.md.
4. Update any consumers (feature-server, api-server, webapp, bundle-viewer) that read or write the affected fields.