Repository navigation
docs(lookbook): true up the nine skills + plan doc; add root CLAUDE.md - #4
Merged
Merged
Conversation
The two capabilities that shipped after the v1 phases — the technical_quality scorer with curate_for_character / curate_for_environment, and the cross-image identity scorer with compare_to_reference — were absent from every skill and from the plan doc, so an agent reading the skills could not discover them. This is a truth pass over the docs, verified against source, plus two small code fixes. Skills: - lookbook-dev: new "shipped after the five phases" section; HTTP verb count 9 -> 10; py2mcp -> fastmcp in the layer diagram; meshed.DAG stated as not taken up (nothing imports meshed); frontmatter no longer names a local path. - lookbook-http: compare_to_reference added to the route table and to the mk_lookbook_app funcs list; new step for the MCP mirror; the async-task note no longer claims Phase 5 work that never happened. - lookbook-curate: documents both curate_for_* presets and compare_to_reference, including that "passed" is advisory and aggregation="max" means "any view". - lookbook-add-scorer: real registry contents as a table (registry name vs metric_id, tier, requires); the invented face-box sketch replaced by the two real worked examples — TechnicalQuality (derived) and IdentitySimilarity (cross-image, injected embedder); cost_tier text no longer promises a budget controller that does not exist. - lookbook-add-selector: quota is shipped, not "Phase 3" future work. - lookbook-profile: technical_quality as the no-face quality signal; the unshipped scorers marked as unshipped rather than "Phase 2.5+". - lookbook-recipe: technical_quality / identity_similarity tunables; points at the presets before hand-tuning. - lookbook-storage: manifest filename separator is "--", not "::" (Windows); images defaults to JsonFiles metadata records, not Files bytes. - lookbook-diagnose: compare_to_reference as a fourth diagnostic; the yaw bins have _left twins. Docs: plan doc status snapshot extended with the post-v1 rows and a post-v1 deliverables section; skill count 8 -> 9; everything below the fold marked as the original plan of record. README gains the two new sections, fixes py2mcp -> fastmcp, and lists the new modules. Code: - lookbook/__init__.py is now pure re-export: curate / score / curate_for_* moved to lookbook/facade.py, so Any/Mapping/Optional/Sequence/Union no longer leak into dir(lookbook). __all__ is unchanged and every name in it still resolves. _resolve became facade.resolve_plugin (used by interactive.py, so no underscore) and interactive.py's dead PluginSpec string alias is gone. - store.py docstrings corrected to the "--" separator and to what the images store actually holds. Tests: python -m pytest -q -> 152 passed, 3 skipped. ruff clean. Claude-Session: https://claude.ai/code/session_01EvKbcwUUanua9yu5aFsPK8
Review follow-up on the skills truth-up. lookbook-dev/SKILL.md was the one
file the sweep had not fully verified against source; it shipped claims the
same commit had already corrected elsewhere, plus three more that no file
had caught.
Contradicted by other files in the same commit:
- manifest filename separator was `::`; store.py's `_KEY_SEP` is `--`
(Windows disallows `:`). Now states the reason, matching lookbook-storage.
- `images` store values were "bytes / path / url payload"; the slot holds
metadata records (`{"path": ...}`) written by `ingest_to_store`.
Newly found, verified against source:
- Path defaults claimed `~/Library/Application Support` on macOS. config2py
is XDG on all POSIX, macOS included: `~/.local/share/lookbook`. Windows
goes to `%LOCALAPPDATA%`. Corrected in SKILL.md and README.
- Architecture diagram named `budget` as an orchestration module; there is
no `budget.py` — it was planned in the plan doc and never built. Added a
"Not taken up" row for it next to the `meshed.DAG` one.
- Backend layer listed `pyiqa` and `apricot` as wrapped; nothing imports
either (they are declared-only `[embed]` extras, and the same file says
FacilityLocation is pure-numpy "no apricot dep"). Now lists what is
actually wrapped, consistently across SKILL.md, CLAUDE.md and README.
- "four protocols" headed a list of five; base.py defines five Protocols,
four of which are the plugin layer.
- `Stores` was "three (and a half) MutableMappings" over a four-row table.
- "Every function and class named above is a top-level export" was false
for `TechnicalQuality`, which is registry-only.
Also:
- pipeline.py's docstring still sold the `meshed.DAG` swap as scheduled
"Phase 1+" work; it is not scheduled and nothing imports meshed.
- Exported `PluginSpec`, so `dir(lookbook)` really is `__all__` plus
submodules as CLAUDE.md and lookbook-dev both claim.
Claude-Session: https://claude.ai/code/session_01EvKbcwUUanua9yu5aFsPK8
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation truth pass: two merged PRs (#1 technical_quality scorer + curate_for_character/environment facades, #3 IdentitySimilarity/compare_to_reference) shipped real, federation-consumed capabilities that no skill and no plan doc mentioned. Federation agents could not discover them — which is exactly the failure the skills exist to prevent, and these are the capabilities nw and reelee lean on for character consistency.
What changed
lookbook-dev's "current state" stopped at Phase 5 and claimed HTTP exposes 9 verbs —mk_lookbook_appmounts 10.lookbook-http's route table was missingcompare_to_reference.lookbook-curatenow documents the two curate facades;lookbook-add-scoreruses the identity and technical-quality scorers as worked examples, since they are now the best ones in the registry.CLAUDE.mdadded (modelled on mixing's) — orientation, capability map, and a pointer to each of the nine skills.misc/docs/lookbook_development_plan.mdstatus table updated to shipped reality.lookbook-dev's frontmatter description — it hardcoded a developer's home directory in a tracked file of a public repo. Repo re-swept; no other path, home-dir or email leaks remain.Any, Mapping, Optional, Sequence, Unionno longer leak intodir(lookbook).Note for review
The namespace fix was done by extracting the facade implementations out of
__init__.pyinto a newlookbook/facade.py, leaving__init__.pyas a thin re-export. That is a larger structural change than the leak strictly required, so it deserves the closer look:__all__carried over unchanged at 27 names and every one still resolves. (The follow-up commit below adds one name,PluginSpec, bringing it to 28 — see below for why.)Follow-up commit: the truth pass was itself not fully true
An adversarial review of the first commit found that
lookbook-dev/SKILL.md— the file an agent reads first — had not actually been verified against source, so "all nine skills" above was overstated. It shipped two claims this very PR corrects elsewhere, and re-verifying every remaining claim in that file turned up three more. All are now fixed:Contradicted by another file in the same PR:
::;store.py's_KEY_SEPis--(Windows disallows:in filenames).lookbook-storageandstore.py's docstring already said--.imagesstore values were described as "bytes / path / url payload"; the slot holds metadata records ({"path": ...}), aslookbook-storageandstore.pyalready said.Not caught by anything until now:
~/Library/Application Supporton macOS.config2pyuses XDG on all POSIX platforms, macOS included →~/.local/share/lookbook; Windows goes to%LOCALAPPDATA%. Fixed in the skill and inREADME.md.budgetas an orchestration module. There is nobudget.py— it was planned and never built. Added a "Not taken up" row for it in the plan doc's status table, beside themeshed.DAGone.pyiqaandapricotas wrapped. Nothing imports either; they are declared-only[embed]extras, and the same file saysFacilityLocationis pure-numpy with "no apricot dep". The diagram now lists what is actually wrapped, identically in the skill,CLAUDE.mdandREADME.md.base.pydefines five Protocols, four of which form the plugin layer.Storeswas "three (and a half) MutableMappings" above a four-row table.TechnicalQuality, which is reachable only as thetechnical_qualityregistry name.Plus the two nits from the same review:
pipeline.py's module docstring still sold themeshed.DAGswap as scheduled "Phase 1+" work, which this PR's own plan-doc row calls "Not taken up".PluginSpecwas indir(lookbook)but not in__all__, so the "dir(lookbook)is the public API plus submodules" sentence inCLAUDE.mdandlookbook-devwas marginally loose. It is a genuine public type (it is the(name, kwargs)plugin-spec form the facade signatures use), so it is now exported —__all__is 28 names, and non-underscoredir(lookbook)is now exactly__all__plus submodules.Note for whoever lands this:
meshedis still a declared core dependency inpyproject.tomlalthough nothing imports it. Removing it is a packaging change with release consequences, so it was deliberately left alone here rather than folded into a docs PR.pytest -q→ 152 passed, 3 skipped (unchanged), with the import pinned to this checkout.https://claude.ai/code/session_01EvKbcwUUanua9yu5aFsPK8