143 lines
8.0 KiB
Markdown
143 lines
8.0 KiB
Markdown
# 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.)
|
||
```
|