lossless-group/astro-knots

The Lossless Group's Astro Knots conventions — vision, tech hierarchy, approved frameworks, and hard prohibitions for the family of ~10+ Astro sites and the Lossless Flavored Markdown ecosystem. Use whenever working on an Astro project in the lossless-monorepo (or any sibling repo), scaffolding new sites, choosing dependencies, building components, integrating LFM, or when the user mentions "Astro Knots", "LFM", "Lossless Flavored Markdown", or "pseudomonorepo". Hard prohibitions on React, JSX, Angular, and unnecessary dependencies.

How to help someone find the look of a new site or brand before anything is designed, by building a mood board of 2 to 4 reference "worlds" with real images, each linked to its source and credited. Use after a site's narrative is agreed and before the brand kit, theme or any UI; whenever someone says "mood board", "moodboard", "inspiration", "what should it look like", "I don't know what style I want", "show me some directions", or is new to design and needs help ideating; and when a brand kit is being started from nothing. Encodes the cluster shape (name, how it reads, what to steal, 10 to 16 pins), where to find usable images, how to check every image loads, the single-file HTML template with its JSON board data, and the hand-off from board to brand kit.

How The Lossless Group writes and structures changelog/ entries across all repos (projects, true monorepos, pseudomonorepos). Use whenever shipping or pushing a coherent chunk of work, when scaffolding a new repo's changelog/ directory, when authoring a product release message, when the user says "log this", "write a changelog", or "ship note", or when reviewing a changelog/ file. Also fires when the user drops screenshots for an entry or the work being logged is visual — composes with prep-images-for-embed so images get CDN-hosted with real alt text without the user naming both skills. Encodes the strict frontmatter (publish, lede, ISO dates), filename pattern, "it exists" priority, the never-use-relative-image-paths rule (entries get rolled up into parent sites, so relative paths break), and the show-don't-enforce ethos.

How to generate share-imagery (OpenGraph banners, portraits, squares, tall WhatsApp/iMessage cards) for any Lossless site or splash page so the resulting images form a coherent visual family — via two coexisting techniques: Ideogram illustration, or rasterizing the project's own hero/specimen component with macOS's qlmanage+sips (or a Playwright screenshot for higher fidelity). Use whenever a site, splash, plugin page, or fundraise deck needs an OG image generated or refreshed; whenever the user says "make an og image", "generate a banner", "we need a share image", "regenerate banners across formats", "the unfurl looks stale", "screenshot the hero for the share image", "turn this component into an OG image"; whenever scaffolding a new Astro Knots site that doesn't yet have an og:image or a DESIGN.md; whenever per-page or per-component custom illustrative imagery is needed even if it deliberately departs from the OG-image canon; whenever an existing OG image (of either technique) might already be live and a decision is needed about replacing vs. keeping it. Encodes the pattern of (1) choose Ideogram illustration vs. hero rasterization per the Strategy Choice section, (2) check / create a DESIGN.md following the Google Stitch open spec, (3) check / add an imagery: recipe block to that DESIGN.md, (4) call Ideogram v3 generate with every field locked except prompt and aspect_ratio (or rasterize the hero via qlmanage+sips), (5) save with the canonical naming convention, (6) treat WhatsApp + iMessage chat-preview as the primary share surface and other socials as secondary, (7) run the Case Protocol before wiring anything into a live og:image tag. The skill never sees an API key in source — IDEOGRAM_API_KEY lives in ~/.secrets and is inherited from the shell, same pattern as the crawl-fetch-ingest skill.

The Lossless Group's git commit message conventions — structured headers with action verbs and effort groupings, paragraph-spaced bodies that explain impact before implementation, and "Also included" riders for minor changes. Use when writing commit messages, reviewing commits, or when the user mentions "commit message format", "git conventions", or asks how to structure a commit.

Check an Astro site against the Astro Knots guardrails (no React or JSX patterns, LFM, Vitest, share images, canonical URLs, sitemap, robots.txt) and fix what fails. Use before committing, before deploying, after a big change, when a share preview looks wrong, or when someone asks "does this follow our patterns?"

The Lossless Group's extended-markdown flavor — what LFM is, when to use it, how its directives normalize across syntaxes (CommonMark, GFM, Obsidian callouts, remark-directive, Markdoc), how citations and link previews work, and how sites extend it via trigger maps and theme tokens. Use whenever authoring or rendering content in any Astro Knots site, integrating the @lossless-group/lfm package, building or registering custom components for markdown, debugging callouts/embeds/citations, or when the user mentions "LFM", "Lossless Flavored Markdown", "extended markdown", "directive syntax", "wikilink", "trigger map", "callout", or "hex-code citation".

How to author and maintain a DESIGN.md file at the root of any Lossless project (site, splash page, plugin landing, fundraise deck) following Google Stitch's open spec. Use whenever a project is missing a DESIGN.md and an agent needs the project's visual identity in machine-readable form; whenever the user mentions "design tokens", "design system", "DESIGN.md", or "Stitch spec"; whenever theme/CSS-token work changes the runtime values (new CSS custom property in :root, renamed token, new mode, new component pattern, refreshed palette, refreshed typography scale) and the documented contract has drifted; whenever a sibling skill (generate-consistent-og-images, theme-system, astro-knots) needs to read locked design values; whenever the user says "the agent doesn't know what color we use" or "let's write down the design system." Encodes (1) the Stitch spec's frontmatter token groups (colors, typography, rounded, spacing, components) and the eight prose sections in canonical order, (2) the maintenance triggers — what kinds of code changes should bounce back into the document, (3) the "runtime CSS is source of truth, DESIGN.md is the contract" discipline, (4) the precedent for off-spec extensions like an imagery: block, (5) anti-patterns. The skill never sees an API key or makes network calls — it's a pure-document discipline.

How to build and keep current the /design-system page (the in-site component catalog) and its sibling /brand-kit page on any Astro Knots site — the replacement for Storybook. Use when a site has no /design-system page yet; whenever a component is created, changed, given a variant, or extracted from a spike; when refactoring a spike into components; when knot-check reports uncatalogued components; or when the user mentions "design system page", "component catalog", "brand kit", or "Storybook". Encodes the two pages' scopes, the required entry for each component, the theme and mode contract, noindex, the same-change rule, and how to catch up a catalog that has drifted.

How to make a page unfurl reliably in iMessage, WhatsApp, Slack, Discord, LinkedIn, and X; surface to search engines via sitemap.xml + robots.txt; and stay legible to generative engines (GEO), including the llms.txt standard for LLM corpus ingest. Use when adding or debugging OpenGraph / Twitter Card metadata, picking an OG image format, choosing where to host the image, fixing pages that "won't unfurl", auditing share previews, scaffolding /llms.txt and /llms-full.txt, or adding @astrojs/sitemap + robots.txt to a splash or marketing site. Encodes the JPEG-over-WebP rule, the ImageKit content-negotiation gotcha, the absolute-URL requirement, the og:image:type-must-match-bytes invariant, the cache-busting recipe for forcing a re-unfurl, the prose-in-markdown source-of-truth pattern for llms.txt, and the sitemap filter that keeps non-HTML routes (llms.txt, 404) out of the search-engine index.

The Lossless Group's rhythm for building UI with coding agents — spike new features, pages and redesigns freely without the design system (component library and theme), then refactor the approved spike back into components (Component-Driven Architecture) and back onto the theme's tokens, and catalog them on /design-system. Use when starting any new page, feature, section, redesign or design variant (to make the gametime decision whether to use the component library); when a spike has been approved and needs refactoring; when assigning an agent to refactor a spike; when someone asks "should I use the existing components?"; or when knot-check reports open spikes or uncatalogued components. Encodes the decision rule, the @spike marker, the behavior-locking refactor procedure, how to hand a refactor to a separate agent, and the anti-patterns.

Set someone up to build an Astro Knots website with their coding agent, from an empty folder to a deployed site that passes knot-check. Use when someone says "get started", "set me up", "start a new site", "make me a website", or connects Astro Knots for the first time. Covers agreeing the site's narrative (grilled one question at a time) and mood board before any code, the machine, the plugin, image generation, the site's stack, share images and SEO, and the first deploy.

The Lossless Group's theme and mode architecture — two-tier token system, three-mode contract (light/dark/vibrant), theme.css organization, and design system conventions. Use when setting up themes/modes for any Astro Knots site, debugging mode toggles, working with CSS tokens, or when the user mentions "vibrant mode", "two-tier tokens", "theme.css", or design system patterns.

How to agree on what a website says before building it, by grilling the person one question at a time (in the style of Matt Pocock's grill-me) until there is a shared story, writing it to context-v/narratives/, getting it signed off, and then developing the site's content from it. Use at the start of every new site or redesign, before the mood board, brand kit or any code; whenever someone says "narrative", "messaging", "positioning", "what should the site say", "help me figure out my website", "grill me", or is new and doesn't know where to start; and when content needs writing for pages that don't have any. Encodes the decision tree a site's story walks down, the one-question-with-a-recommendation interview, the narrative document shape, the sign-off gate, and the narrative-to-content step.