| name | animated-readme-logo |
| description | Create, transform, or review animated logo asset pipelines for GitHub READMEs, including starter asset creation when no logo exists, transparent-background transformations, SVG/Lottie source choices, README-safe picture markup, reduced-motion fallbacks, GitHub Pages demos, and asset validation. Use when working on README logos, profile README hero images, animated repository branding, or README image compatibility. |
| license | Apache-2.0 |
| metadata | {"author":"stark-ai-de","category":"engineering-workflows","version":"0.4.0"} |
Animated README Logo
Goal
Create a portable, validated SVG logo master and a deterministic motion plan, then export only the artifacts the available tools can verify.
When to use
- Create, redesign, transform, animate, export, or review a repository or profile-README logo.
- Audit GitHub README logo compatibility, transparency, reduced motion, or local asset references.
- Turn an existing SVG or raster mark into a validated README asset pipeline.
When not to use
- Ordinary README prose editing with no logo or image concern.
- App/site motion unrelated to repository branding delivery.
- Generic image generation with no README or repository-logo target.
Inputs to inspect
- Repository identity, public brand copy, target surface, and requested task.
- README markup and root-bounded local asset references.
- Existing logo sources, reference-media fidelity needs, transparency, themes, dimensions, accessibility, and export constraints.
- Live provider, authoring, validator, exporter, and inspector capabilities without assuming availability.
Workflow
- Inspect repository identity, README markup, referenced assets, brand constraints, target surface, and available local or connected capabilities.
- Select exactly one current task mode:
review: assess existing README logo assets without redesigning them.create: design a new mark or intentionally redesign an existing one.transform: faithfully recreate or clean an existing mark.animate-export: define motion or export an already acceptable source.
- Select the source route before creating anything. Read
references/provider-routing.md for every create task and whenever external generation is proposed. Recraft is ineligible for review, a clean existing SVG, a faithful transformation, or any task that needs reference-media fidelity.
- Preserve originals. Create deterministic derived filenames under the repository's established asset folder, or
docs/assets/ when none exists.
- Produce a self-contained SVG locally at the static first-frame state. A provider result is design input, not proof that the SVG is ready. Use
drawio-diagrams only when geometric, editable construction materially helps; it is not a dependency.
- Strictly validate the SVG. Do not report completion until it passes the bundled validator. Read
references/asset-transformation.md for the authoring and validation contract.
- Write a deterministic motion specification with named layers, explicit keyframes, easing, duration, loop point, and a static reduced-motion state. Read
references/motion-rubric.md.
- Choose README and optional web-demo delivery from
references/github-readme-compatibility.md and references/asset-pipeline.md. For static PNG plus animated GIF delivery, keep brand behavior in a trusted repository recipe and use the bundled exporter contract in references/export-recipe.md; do not recreate its rasterization and encoding plumbing in the product repository. Read references/local-tooling.md before declaring an exporter, inspector runtime, or browser unavailable. When a requested export or inspection needs a missing local command, immediately present the minimal installation preflight and ask for explicit approval; stop before installing. Export animated raster formats only when a detected or approved-and-verified tool can produce them and the result can be inspected. Never invent an artifact or successful export.
- For an existing README, run the read-only audit with an explicit repository root. Treat every local reference as untrusted and root-bounded. Read
references/readme-audit-safety.md.
- Report the public status fields below and the exact files, checks, fallbacks, and remaining blockers.
For a multi-stage request, finish and report one mode before moving to the next mode.
Provider boundary
- Detect live Higgsfield MCP capability, exact
recraft_v4_1 availability, and the exact current cost before offering a provider route. Documentation is not availability evidence, and cost must never be hardcoded.
- Present the sanitized brief, live cost, and fixed generation settings before asking for approval.
- Make no credit-consuming call until the user explicitly approves that exact batch after the preflight.
- On unavailable or indeterminate capability, unavailable model/cost data, or explicit refusal, use the direct local SVG fallback.
Safety rules
- Do not install tools, overwrite brand assets, spend credits, publish, or change remote state without the required approval.
- Keep provider approval and local-tool installation approval as separate checkpoints. Approval of one never authorizes the other.
- Do not expose secrets, private paths, internal hostnames, hidden metadata, or customer data in a prompt, asset, snippet, or report.
- Do not send reference media to Recraft or claim it preserves an existing identity.
- Reject absolute, UNC, root-escaping traversal, and symlink-escaping README asset references.
- Do not promise animated SVG, Lottie, or a raster format will work in GitHub README rendering without a compatible fallback and manual GitHub preview.
- Preserve transparency unless the user explicitly requests a background.
References
Read only what the task needs:
references/provider-routing.md: live Recraft eligibility, cost preflight, approval, fixed settings, and fallback.references/output-contract.md: exact public fields and status values.references/asset-transformation.md: direct SVG authoring, transformation, validation, and mutation boundaries.references/asset-pipeline.md: canonical assets, export capability gates, and transparency checks.references/export-recipe.md: trusted repository recipe boundary and reusable static-PNG/animated-GIF exporter contract.references/local-tooling.md: minimal exporter selection, installation approval, verification, and browser-preview fallback routing.references/motion-rubric.md: deterministic motion specification and reduced-motion requirements.references/github-readme-compatibility.md: README versus web delivery and renderer fallbacks.references/readme-audit-safety.md: root-bounded README asset inspection.references/readme-snippets.md: accessible README and demo markup.
Scripts
scripts/validate_logo_svg.py <svg> strictly validates the canonical SVG.scripts/inspect-animated-image.mjs <asset> verifies a generated, metadata-clean GIF, APNG, or animated WebP without modifying it.scripts/export-readme-logo-animation.mjs --root <repo> --recipe <relative.mjs> [--check] [--replace] validates a trusted repository recipe, then exports a static PNG and animated GIF through approved local tools with validate-before-commit and commit-time no-clobber checks. The exporter modifies only absent declared outputs unless --replace is explicit; --check performs no exporter-controlled writes, but the trusted recipe still executes.scripts/audit-readme-logo-assets.mjs --root <repo-root> --readme <root-relative-readme> audits bounded, root-contained README references and fallback roles without modifying files.scripts/generate-readme-logo-snippet.mjs --fallback <path> --alt <text> --width <px> --height <px> [options] prints markup to stdout.
Run a script with --help before relying on optional flags.
Output format
Always report these fields for an activated task:
Task mode: review | create | transform | animate-export
Source route: <route>
Provider state: <state>
Approval state: <state>
SVG readiness: <state>
Export status: <state>
Then report the asset stack, motion specification, README delivery, validation evidence, and remaining blockers. Use the exact meanings in references/output-contract.md.
Completion criteria
- A complete creation, transformation, or animation path has a self-contained SVG that passes strict validation and a deterministic motion specification.
- A review may finish with a non-ready SVG status only when it reports concrete remediation; it must not claim the asset pipeline is complete.
- Every paid generation is traceable to a live preflight and explicit approval of that exact batch.
- Every claimed raster export exists and passes the relevant inspector.
- Every README-local path stays within the declared repository root after symlink resolution.
- README animation has a meaningful static fallback, reduced-motion delivery, explicit dimensions and alt text, and a required manual GitHub preview.
Runtime portability
Keep one host-neutral workflow. Do not branch on Codex, Cursor, Claude, or another agent name and do not emit agent-specific commands. Tailoring has no present benefit because source, approval, validation, motion, and output contracts are shared. Reconsider a split only if a host later requires a materially different tool or output contract.
Failure modes
- If live provider capability, exact model availability, or current cost cannot be confirmed, report the limitation and author the SVG locally.
- If provider approval is pending, stop before generation. If it is declined, record that once and continue locally.
- If strict SVG validation fails, correct the source and rerun validation; do not claim readiness.
- If a required exporter or inspector runtime is missing and installation has not been declined or forbidden, present the exact minimal tool preflight and ask for approval immediately. Use
Export status: blocked while approval is pending; install nothing yet.
- If installation is declined, forbidden, or unavailable, keep the validated SVG and motion spec, report
Export status: capability-unavailable, and create no placeholder.
- If Playwright cannot find its expected browser, do not classify the raster exporter as unavailable. Reuse an existing configured Chrome or Chromium executable, then an existing
agent-browser; request approval before any CLI or browser download.
- If a README asset reference fails root containment, reject it before reading and report the path class.
