loswfx ships native skill support

the shape now

over the last sweep, skills became a first-class layer in loswfx. the skills/ directory holds 26 markdown files. the .loswf/tools/ directory holds 7 python primitives. design.md §9 and §10 are machine-consumable brand briefs the tools read at call time. a new cardinal practice, illustrated-planning, scans planning artifacts and surfaces ones that ship without an inline diagram.

the kernel didn’t grow. the chain from operator to artifact did. an agent that needs a hero image invokes image-generate; the wrapper prepends design.md §9 voice before the api call; the receipt records every parameter. an agent that needs a four-second branded clip invokes remotion-render against a composition that imports tokens from a brand.ts file mirroring design.md §10. an agent authoring an engagement plan sees a prompt addendum that points to the right tool for the shape of its output.

this post is the first one a documenter agent will ship through bin/loswf-devlog. each section that follows names the part of the layer it describes and links to the file that proves it.

skills as code-blueprints, not docs

each skill is a markdown file with required yaml frontmatter — name, description, side, and an optional output_dir. the skill-frontmatter validator (internal/practices/skill_frontmatter.go, landed in 3e0d30b) refuses to register a skill missing those fields. the skill-name-coverage validator catches scenarios that reference skills that don’t ship.

the discipline matters because the kernel routes by frontmatter. side: client lands the deliverable in the engagement workspace; side: shadow lands it in loswf/shadow-<operator>. an agent doesn’t ask where its output goes; the side field decides. an engagement-plan posts to proposals/<client>/engagement-plan.md; a retrospective posts to engagements/<client>/<repo>/retros/<date>.md. the operator never wires the path manually.

---
name: engagement-plan
description: produce a multi-deliverable engagement plan...
side: client
output_dir: proposals/<client>
---

skills also carry the inputs/process/outputs/verification contract the icm research surfaced (docs/research/ICM-PAPER-NOTES.md). 14 of 26 skills now declare a verification block; this is the post-hoc “did the artifact land in the right shape” check the practices catalog can run against the shadow.

tool primitives behind skills

skills point at tools. the seven primitives that shipped or were vendored:

• generate_image.py — openai gpt-image-2 wrapper. --prompt mode for hero art; --mermaid mode renders a kroki baseline then polishes through gpt-image-2’s images.edit endpoint. brand voice from design.md §9 is auto-prepended to every prompt unless the caller passes --no-style. landed e69dff2; frontmatter fixed a6fa1ef.
• devlog_voice_gate.py / devlog_write.py / devlog_promote.py / devlog_trigger_body.py — the four-piece chain that publishes to log.loswf.com. voice gate enforces word caps + banned phrases + lowercase loswf without an llm call. mirrored from loswf2 in b91b2ca.
• render_remotion.py — wrapper around npx remotion render with tier presets (preview / default / max / prores-4444-xq), composition-id pre-validation, props-as-tempfile, structured receipt. landed in the 5aff778 cluster.
• lint_remotion_spec.py — beats-blueprint spec validator + a sister --check-tokens mode that warns when composition .tsx files carry hex literals outside the brand-tokens module.

every tool writes a receipt json next to its output. the receipt is the audit trail. when a render fails, the receipt names the failure mode; when a render succeeds, the receipt carries the prompt hash, the api parameters, and the cost estimate.

the eight-second clip below is a work item moving through the team workflow — intake → triage → plan → build → review → ship — authored as a remotion composition with svg primitives, rendered through the same bundled wrapper. the dashed amber arc above review → build is the rework loop; the token doesn’t traverse it on this happy-path run, but its presence in the graph is the point. the same clip is embedded in the loswfx readme and the architecture-map doc; the asset itself is reusable.

brand voice as machine-consumed

before this sweep, design.md was a human-only reference. authoring a hero image required an agent to read the doc and re-state the rules. that worked when one operator was driving; it didn’t scale.

now design.md §9 is the canonical machine-readable brand brief for images. the image_gen.style_brief block in .loswf/config.yaml points generate_image.py at the section; the wrapper reads it once per process and prepends the prompt suffix to every call. an agent that says “draw a server-rack blueprint” gets back something that reads as a sibling to the org chart, with no extra prompt engineering.

design.md §10 does the same job for remotion. the tokens module at examples/remotion-demo/src/brand.ts is the typescript mirror; compositions import from it instead of hardcoding hex. a --check-tokens linter pass catches drift when an agent slips a literal #0a0a0a into a .tsx file.

two demo compositions in the loswfx repo prove the chain end to end. the four-second story-card clip loads a brand-voiced still through staticFile() and animates it with a monospace caption and an amber underline. the eight-second workflow-traversal clip above is pure svg with the token-as-amber-dot moving along blue edges through six labeled nodes — no external image asset, all timing through useCurrentFrame + interpolate + spring. both clips inherit §10 brand voice via the tokens import; generate_image.py output inherits §9 brand voice via the style-brief prefix; both surfaces descend from design.md §1–§2, so the final video is brand-aligned in both the static and motion layers without a separate brand pass.

closing the loop: illustrate-doc + the cardinal practice

skills tell agents how to produce artifacts. the cardinal practice tells operators when the artifacts are missing something.

the new illustrated-planning validator (internal/practices/illustrated_planning.go, landed 3dfeeda) walks proposals/ and engagements/ for planning artifacts that match known filename patterns — engagement-plan.md, iteration-.md, product-brief.md, audit-.md, retro-*.md. for each, it strips yaml front-matter, counts body words, and checks for inline image syntax or a mermaid fence. an artifact ≥600 words with no visual surfaces as a violation. soft check — operators can skip a finding when the doc genuinely doesn’t carry geometry — but the nudge is real.

the prompt side is wired too. plan and build capabilities now include a documentvisualguidance promptsection gated by a heuristic that detects doc-shape work items (title or body matches engagement-plan, audit, brief, prd, etc.). when an agent is producing a documentation artifact, the system prompt picks up a paragraph that says: default to mermaid, escalate to image-generate only when brand voice matters, don’t add an image just because.

a methodology skill, illustrate-doc, holds the full decision tree. eight of the most diagram-friendly doc skills — engagement-plan, iteration-plan, repo-audit, product-brief, research-brief, retrospective, research-design-implications, triage-decomposition — cross-reference it so the rule lives in one place and the skills don’t drift apart.

what this enables

agents that draw their reasoning are more reviewable. a planning artifact that ships with a phase timeline is faster to read than one that buries the same geometry in prose. a video clip that inherits brand voice from §10 stops requiring a separate brand pass. a hero image that inherits §9 brand voice stops requiring a designer-in-the-loop.

the practical artifacts of this sweep: a working bin/loswf-devlog that ships posts like this one without a developer; a 90-frame brand intro and a 120-frame story-card composition rendered by the bundled wrapper; six architecture diagrams now embedded in the doc set; a methodology skill that any new doc-producing agent can read in three minutes and apply.

the kernel size didn’t change. what an agent can reach for did. the next agent that picks up an engagement plan sees an addendum in its prompt, has a mermaid fence at hand, knows that an image-generate escalation will inherit brand voice, and ships an artifact that the illustrated-planning validator passes without a manual nudge from the operator.