| name | developing-leaf |
| description | Develops Leaf from the current checkout by previewing examples, comparing runtimes, refreshing catalog stills, and testing page changes in the browser. |
Develop Leaf from this checkout
Resolve the repository root three directories above this SKILL.md, then resolve
<root>/bin/leaf to an absolute path. Run that launcher with --version and
continue only when it prints the same repository root. Use the absolute launcher
throughout; a bare leaf command may resolve to the installed plugin instead.
Use the visible-change handoff in <root>/CLAUDE.md to choose a workflow. When a
visual or content artifact would help the developer judge the work, put a draft
in front of them during exploration or at handoff rather than relying on a
description alone. Preview a shipped example when the request names one or that
handoff requires interactive proof. Otherwise author or revise a page.
Before presenting a served page or visible runtime change as finished, inspect
the exact served URL. When the subject is Leaf's own interface, the demonstrated
surface must come from its owning runtime and theme through a shipped example or
fixture; page-local HTML and CSS may frame it, but must not imitate it. Call an
unimplemented imitation a sketch, not a preview. Confirm the expected content,
review the changed surface at a representative viewport, and check the browser
console. Navigate to the semantic block that owns the changed surface and hand off
the exact URL including its fragment. A titled section uses the section's stable id,
so its eyebrow and heading arrive together. Add an id to the tight semantic container
when it has none. Keep the process alive.
Preview a shipped example
From the repository root, start scripts/preview.py <example> in a long-running
command or terminal session. Keep it alive and retain the exact served URL. The
script watches source and runtime edits and preserves feedback at
.tmp/previews/<example>. Repeating the command reuses that preview; use
--slot <name> for another copy. A refused update appears in the terminal or the
background log named at startup. Fix the input and the watcher retries.
Browser automation runs scripts/preview.py <example> --automation in a
long-running process. The command uses the browser suite's temporary server: the
real HTTP and event log, with no task claim or durable service. Its default page
is .tmp/previews/<example>-automation; use the reader preview's distinct page
when presenting a URL for feedback. An explicit slot cannot change interaction
mode.
When finished with a preview, run the matching preview command with --stop (and
--automation for its automation slot); it waits for the watcher and server to
stop. Ctrl-C stops a foreground preview. A slot refuses a different source or seeded
history so it keeps the existing page and feedback. Use --reset to discard the
selected slot and rebuild it from the current fixture.
In Codex
- Call
mcp__codex_app__open_in_codex with the destination's fragment URL as a
browser target and placement: "right".
- Run
<root>/bin/leaf codex start <root>/.tmp/previews/<example> so Leaf
comments return to the current task.
- Tell the user to select page text or use Leaf's comment affordance for a Leaf
thread. Codex Annotation mode creates visual comments that the user sends with
their next chat message. Use the Codex review pane when feedback belongs to a
source line.
Refresh the public catalog stills
When a change adds or removes a worked example, or changes its first viewport, run
wt refresh-previews from the repository root on macOS. Run wt setup first in a
new checkout. If Worktrunk requests approval for the project commands, ask the user
to run wt config approvals add. The refresh command captures every worked example,
validates the rebuilt site, pushes the complete JPEG set to
max-sixty/leaf-assets, and updates example-previews.json and the catalog links in
this checkout. Because it pushes the asset repository immediately, run it only when
the user has authorized that publication. The generator checks the required Charter
and San Francisco fonts and fails rather than publishing images rendered with
fallback fonts.
Compare runtime versions
Choose one authored source and serve it through two named preview slots:
scripts/preview.py --source <source.html> --runtime <baseline-root> \
--slot baseline --background
scripts/preview.py --source <source.html> --runtime <candidate-root> \
--slot candidate --background
Each command verifies the checkout launcher, prepares or resumes its independent
page, watches that runtime and source, and prints its exact URL. Exercise the
same journey and viewport at both URLs, check both browser consoles, then
navigate both to the same authored destination id. Hand off the labeled URL pair
and the action that reveals the difference; in Codex, open those exact fragment
URLs as browser targets.
Author or revise a page
Read <root>/skills/leaf/SKILL.md completely and follow its authoring,
validation, handoff, and conversation-loop routes. Use the checkout launcher's
absolute path for every command written there as leaf, and resolve its
references from <root>/skills/leaf/.
page init vendors the checkout's runtime, theme, registry, widgets, and assets
into the page. For an existing page that must exercise the current checkout,
read <root>/skills/leaf/references/serving-pages.md and re-vendor it with the
checkout launcher. A served page follows that reference's stop, init, start
sequence. Fix or report a compatibility refusal without falling back to the
installed plugin.
