Session 0003.0 — Transcript

App: dev-claude-plugin Date: 2026-06-03 (PST) · ~17:00–18:27 Goal: Add deploy/flotilla context to the coding-session skill; from there, establish the team's docs-first / deterministic-first build philosophy and a natural-language handbook Q&A skill; ship it all. Outcome: Shipped. Handbook gained §4.1 + §4.2; tier-1 agent-context.md now tracked; new wgl-dev-handbook skill; stale handbook banner refreshed. 3 PRs merged (engineering #5, #8; plugin #1).

Note on this transcript: wgl-coding-session-init was not run at the start of this session, so no ID was claimed up front. This transcript was claimed retroactively at finalize (protocol §"end-of-session", case 3). The 17:00 start is an estimate; the work is recorded honestly regardless.

Plan

The session had no single launch plan — it grew turn by turn as the operator pulled a thread from a concrete edit up to a stated principle:

Add deployment/flotilla context to wgl-coding-session-init.
Solidify the underlying pattern (docs first; automation references docs).
Codify that pattern in the engineering handbook.
Build a natural-language handbook Q&A skill; codify the deterministic-vs-NL division as a second principle.
Commit/push/merge everything; then finalize.

Pre-session state

wgl-coding-session-init (plugin) covered only session-claim mechanics; no deploy/infra context.
Engineering handbook (wiggleverse/engineering/README.md) had §4 but no §4.1/§4.2. Its tier-1 digest agent-context.md existed only as an untracked working-tree file (never git added) — the ~/.claude/wiggleverse.md symlink target was not in git.
engineering checkout was on branch slice3-provision-vm-scaffold-gitea (2 commits ahead of main, touching README §5.3).
A parallel session was active in the plugin repo the whole time (it committed the session-init roadmap/baseline feature + resolve-app.py roadmap resolution, and bumped the plugin version repeatedly).

Turn-by-turn arc

Add deploy/flotilla to wgl-coding-session-init. Surveyed the sources of truth (handbook §8, OHM flotilla CLAUDE.md, scaffold-gcp-project). Asked the operator two structure questions → chose a reference file kept thin. Created DEPLOY-FLOTILLA.md (a pointer card: stack one-liner, the three load-bearing rules — per-process gcloud config pinning, never-ask-for-secret- bytes, deployment-shape-stays-out-of-framework — and pointers to §8 + the deployment's operator guide). Added a short section + ${CLAUDE_PLUGIN_ROOT} pointer in SKILL.md. Written app-neutral. (Minor stumble: first AskUserQuestion call errored — missing questions param — re-issued.)
"Solidify the pattern: docs first, automation references docs." Reframed the init skill as an index: added a "shape of this skill" section stating the docs-first principle and a pointer table (task → authoritative doc).
"Add it to the engineering docs as a principle." Added handbook §4.1 Documentation leads its automation (+ TOC), a one-line digest in agent-context.md, and converted the skill's prose into a pointer to §4.1 (dogfooding the principle). Placed §4.1 as a subsection so no downstream section numbers shifted (the digest cites §5.2/§8.4/etc.).
"Create wgl-dev-handbook" + the framing "deterministic things = CLI, natural-language things = skills." Built the read-only Q&A skill (reads the canonical docs live, answers with §-citations, routes operational asks to the owning CLI/skill). Registered it in agent-context.md's on-demand list.
"Put that in the handbook too — we build deterministic software wherever we see opportunity; skills are for context-injection, doc-pointers, and human↔LLM Q&A." Added handbook §4.2 Build deterministic software; skills are the natural-language layer (+ TOC + digest), and pointed the dev-handbook skill at §4.2 as its "third seam."
"I'm ready — do it all. I don't want to do anything." Treated this as an explicit override of push-before-pr-review (which normally leaves the merge to the operator) — so I opened and merged. Discoveries mid-flight:
- engineering was on slice3, so I lifted only my §4-area edits onto a fresh branch off main via a saved patch (leaving slice3 untouched), committed, and also started tracking agent-context.md → PR #5 merged.
- The plugin's working-tree changes had already been committed and pushed by the parallel session (e4b3226, which folded in my deploy card + docs- first section + its own roadmap work + a 0.2.0 bump). So only the brand-new wgl-dev-handbook/ remained → branched, bumped 0.2.0 → 0.3.0 (per the plugin CLAUDE.md "bump on ship" rule), committed → PR #1 merged.
- PRs were opened/merged via the Gitea API helper (gitea-api.sh); the token never entered the transcript. (Minor: a python3 parse of the PR-create response errored on display, but the PR was in fact created — confirmed via the PR list.)
- Deliberately did not bundle the parallel session's in-progress resolve-app.py / init-description work into my commits.
Finalize (wgl-coding-session-finalize). Surveyed: both repos clean, both PRs merged. Updated memory (project_wgl_session_framework.md — fixed its stale "agent-context UNCOMMITTED" note + recorded §4.1/§4.2 and the new skill; MEMORY.md index line). On approval, did the optional banner fix: the handbook's top banner + §12 still said "local draft, not yet committed" — fixed both (in an isolated worktree, to avoid disturbing the active slice3 checkout) → PR #8 merged. Then claimed this transcript (#0003) and published.

Cut state (end of session)

All work landed on main. Commit SHAs (cross-repo coherence):

Repo	Change	Feature SHA	Merge / PR
engineering	§4.1 + §4.2 + `agent-context.md` tracked w/ digests	`1aac9d5`	`57a6f29` · PR #5
engineering	refresh stale status banner + §12	`2452587`	`6b860b8` · PR #8
plugin	`wgl-dev-handbook` skill + 0.2.0→0.3.0	`f760f3c`	`30d226a` · PR #1
plugin	(parallel session) deploy card + docs-first section + roadmap work + 0.2.0	`e4b3226`	already on main

Both repos clean and in sync with origin. engineering left on slice3 (the operator's active branch), untouched by this session's merges.
Plugin version was bumped further to 0.4.0 by the parallel session after this session's 0.3.0 — so the live manifest is 0.4.0.

What lands on the operator's plate

Install the new plugin version to make wgl-dev-handbook live in running sessions: /plugin marketplace update then /plugin install wiggleverse-dev-claude-plugin (now v0.4.0). Installed copies are downstream by design (plugin CLAUDE.md) — this step is deliberately the operator's.
Optional: roll the @~/.claude/wiggleverse.md import into more repos' CLAUDE.md (one-time sweep), per project_wgl_session_framework.md.
Separate, bigger blocker (unchanged): OHM /docs/sessions deploy (gcloud auth login + flotilla deploy ohm-rfc-app).

Prompt the operator can paste into the next session

Make the new plugin skill live and verify it. First: /plugin marketplace update
then /plugin install wiggleverse-dev-claude-plugin (brings v0.4.0 + the new
wgl-dev-handbook skill into running sessions). Then sanity-check wgl-dev-handbook
by asking it a handbook question (e.g. "what's our rule on inline CLI comments?"
or "why do we prefer deterministic software?") — it should answer with a
§-citation, reading engineering/README.md live (§4.2 is the relevant new section).
Optional cleanup: a one-time sweep adding the `@~/.claude/wiggleverse.md` import
to repos' CLAUDE.md that lack it. Read memory project_wgl_session_framework.md +
project_dev_claude_plugin.md first. (Bigger separate blocker: OHM /docs/sessions
deploy.)

8.0 KiB Raw Permalink Blame History Unescape Escape