wuxie888/dianjing

dianjing 是做什么的？

Complete the visual style design and polish for a codebase that is already complete or near release, transforming the repository from 'a place to put code' into a beautiful, trustworthy, understandable, installable, and shareable product storefront.

Turn a finished product into a public repository that others can understand, trust, install, use, and are willing to share. Deliver beauty, motion effects, and credibility as a single product, not just by tweaking the README copy or piling on decorative images.

Non-Negotiable Rules

1. Verify the product first, then package it. Confirm the actual repository boundaries, current commit, running state, functionality, license, distribution channels, and existing assets. Do not invent features, metrics, user testimonials, compatibility, or release status.
2. Audit first, then modify. First run scripts/audit_repository.py, then read the source code entry points, product documentation, existing README, assets, and Git status. Preserve the user's existing changes; do not overwrite unrelated work.
3. Product value before installation instructions. The README should first answer 'What is this, who is it for, what problem does it solve, and what is its real status?', and then proceed to installation, first success, upgrades, and troubleshooting.
4. Prioritize real assets. Prioritize reusing real logos, product screenshots, interface recordings, and output results. Newly generated visuals can only explain the real product; they cannot fake non-existent interfaces or capabilities.
5. Motion opportunity assessment is mandatory. Always evaluate dynamic Heroes, real-operation GIFs, demo videos, and Release media. Only evaluate a showcase website when the key experience cannot be conveyed by the README alone. Do not default to delivering only a static README, nor default to building a website just to appear advanced. If motion doesn't improve understanding, trust, or brand, record the reason for not adopting it.
6. Platform capabilities must be layered. The README, Social Preview, Release media, and GitHub Pages are different surfaces. Do not treat the README as a web page that can arbitrarily run JavaScript, CSS, or animated SVGs.
7. Beauty must be usable. Motion effects must not delay critical information. Provide a static first frame and respect prefers-reduced-motion. Check mobile view, light/dark backgrounds, file size, loop pacing, and license.
8. Separate the capability core from the distribution layer. Write product source code, Skills, plugins, installers, websites, and marketplace configurations only when they genuinely exist. Avoid creating a second copy of a core implementation that will drift.
9. Express release status based on evidence. Separate local completion, remote push, Tags, Releases, installability, first use, verified real behavior, and official directory/marketplace status.
10. Remote actions are not automatically authorized. A local polish request allows modifying relevant files within the target repository. Actions like pushing, creating Releases, modifying repository Settings, uploading Social Previews, enabling Pages, or deploying still require explicit user requests.

Workflow

1. Define Deliverable and Permissions

Confirm the target repository and the endpoint for this round:

• Only deliver a styling proposal
• Complete local repository polish
• Add a dynamic README
• Assess and, if needed, build a showcase website
• Prepare release without pushing
• Complete remote release and public acceptance

If the user says 'Polish it' or 'Just do it', default to completing a safe local implementation and verification; do not push or modify remote settings as a result.

2. Audit the Real Repository

Run:

python3 <skill-dir>/scripts/audit_repository.py <repo-path>

Then read audit-and-positioning.md to verify:

• Git root directory, remote, current branch/commit, working tree changes
• Real product entry points, runnable status, license, version, and distribution channels
• README, docs, governance files, tests, and release records
• Logos, screenshots, screen recordings, GIFs, videos, social images, and existing websites
• Absolute local paths, placeholder text, broken relative links, and potentially sensitive files

Do not diagnose not a git repository directly as a release failure; first locate the actual checkout. Do not modify product logic without user authorization.

3. Establish Product Polish Brief

Distill from real materials:

• What the user gives to the product
• What the product accomplishes
• What the user ultimately gets
• Who it's best for and who it's not for
• One strongest differentiator
• Current real status and critical boundaries
• The desired conveyed personality
• Definition of first success

When persistence is needed, copy and fill out repository-brief-template.md. When there's no brand direction, make a definitive choice based on the product itself, avoiding pushing all design decisions back to the user.

4. Choose Mandatory Foundation and Conditional Modules

First, complete the foundation required by any public repository, then select modules based on the product task. Do not equate module count with completeness or sophistication.

Mandatory Foundation:

• Product positioning and factual boundaries
• README information architecture
• Installation and first success
• Real visual assets
• License, version, and release status
• Basic governance and public acceptance

Conditional Modules:

Module	Adoption Criteria
Dynamic Expression	A dynamic Hero, real-operation GIF, or video significantly improves understanding, trust, or brand recognition.
Showcase Website	The README cannot convey key interactions, visual experiences, non-developer conversions, or live demos, and no reusable official website exists.
Release & Distribution	The product has entered a phase of versioned releases, external sharing, or sustained distribution, requiring Social Previews, Release media, bilingual entries, or upgrade/troubleshooting guides.
Advanced Documentation	Installation, API, configuration, or maintenance is complex enough that the README alone is no longer a suitable single source of documentation.

A showcase website is a conditional deliverable, not a higher polish tier. Agent Skills, CLIs, SDKs, and small libraries typically use the README as their home page; UI products, games, creative coding, interactive demos, or products targeting non-developers are more likely to need a showcase website. When the product already has an official website, prioritize connecting and reusing it; do not create a duplicate GitHub Pages.

5. Design README and Documentation

Read readme-and-documentation.md. Organize according to the user's understanding path:

Understand the product
→ Build motivation to use
→ See real evidence
→ Understand capabilities and boundaries
→ Install
→ Achieve first success
→ Troubleshoot and upgrade
→ Learn about testing, maintenance, and license

Do not mechanically apply a template. CLIs, libraries, apps, websites, Skills/plugins, and research projects should choose different demonstration, installation, and first-success paths. When a skeleton is needed, copy readme-outline-template.md and then adapt it to the product.

6. Design Visual and Motion System

Read visual-and-motion.md. First, inventory real assets, then define a product-specific language for color, typography, layout, icons, and motion.

If motion-anything-design is available, you must first:

1. Read the current bundle.
2. Search for design systems that match the product personality.
3. Search for real motion effects with implementation_status: ready.
4. Read the avoid_when, restraint, reduced_motion, dependencies, and license for the selected effects.
5. Get the real implementation files before adapting; do not rewrite an existing implementation from memory.
6. Search for and obtain accurate icon SVGs.

If a new Logo, Hero image, or illustration is needed, first reuse existing brand assets; if generation is truly necessary, use available image generation capabilities, based on real product screenshots and interfaces.

Perform at least one motion opportunity audit per repository:

• Could a dynamic brand Hero explain the product faster?
• Could a real-operation GIF be more effective than multiple screenshots?
• Does a Release need a short video?
• Can the README no longer support the key experience? If so, is the existing website or showcase website worthy of hosting interactions, flows, and CTAs?
• Is the static first frame, non-animated state, and light/dark background all valid?

7. Implement Repository Storefront

Work within the target repository's existing tech stack and conventions:

• Modify the README and necessary documentation
• Reuse or create real visual media
• Add docs/, getting started, troubleshooting, maintenance, and release notes as needed
• Only after passing the showcase website conditional gate, add Pages source code and deployment configuration as needed
• Keep the product core source code singular; do not copy implementations for display
• Use relative links; avoid local paths
• Do not commit keys, cookies, private links, unauthorized assets, or incompatible licenses

Motion selection follows the principle 'one motion effect carries one narrative task.' Default to at most one ambient background effect, one primary text animation, and one celebratory/highlight effect per screen; keep body text and critical operations stable.

8. Verify Local Results

Re-run the audit script and check the Git diff. Then:

• Render the README, check the reading order on desktop and narrow screens
• Actually open all images, GIFs, and videos
• Check GIF first frame, loop seams, subtitles, and file size
• If the Showcase Website module was adopted, perform browser acceptance for Pages or the existing website: responsiveness, light/dark mode, interactions, console, performance, 404s
• Enable reduced motion preference and confirm content is immediately visible and functionality is not lost
• Check all relative links, installation commands, versions, licenses, and real status
• Confirm no unrelated user modifications were overwritten

9. Verify Public Artifacts

After the user authorizes a release, read release-and-acceptance.md. Perform a fresh checkout from the public repository or Tag, then re-verify the README, media, adopted showcase website, installation, first success, and upgrade path.

Report separately on:

• Local polish complete
• Remote source code visible
• Tag / Release published
• Adopted Social Preview / Showcase website is live
• User's first success verified
• Items not yet completed or only verbally confirmed by the user

When formal recording is needed, copy acceptance-report-template.md.

Stop Conditions

• The product's real status cannot be confirmed: First report evidence gaps; do not cover problems with visuals.
• Lack of real product images: Brand and structural assets can be created, but do not fake product screenshots.
• Motion effects incompatible with the README: Prioritize converting to GIF or video; only move to Pages after passing the Showcase Website conditional gate; do not claim the README will run unsupported scripts.
• Existing workspace changes conflict with polish files: Preserve user changes and explain the conflict; request direction if necessary.
• Pushing, deploying, using paid assets, or modifying remote settings is required but not authorized: Stop after completing locally deliverable parts.