# 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:

1. Add deployment/flotilla context to `wgl-coding-session-init`.
2. Solidify the underlying pattern (docs first; automation references docs).
3. Codify that pattern in the engineering handbook.
4. Build a natural-language handbook Q&A skill; codify the deterministic-vs-NL
   division as a second principle.
5. 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 add`ed) — 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

1. **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.)*

2. **"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).

3. **"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.).

4. **"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.

5. **"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."

6. **"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.

7. **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.)
```