platform-project-skill

Platform Project Skill

Two routes, both non-destructive:

If the user gives a path, run scripts/inspect-project.sh <path> before deciding the route — do not assume a project is new just because it lacks documentation.

Hard Constraints

• •New project creation MUST copy from assets/templates/omni-platform/ via scripts/create-platform-project.sh. Do not reconstruct from memory.
• •Existing project upgrade MUST go through scripts/upgrade-existing-project.sh, which is inspect-first, .gitignore-aware, and language-aware. It will NOT touch assets/, docs/, or business code by default.
• •Final visual assets MUST be generated by image_gen. Mermaid / SVG / HTML / Pillow are NOT substitutes for final images unless the user explicitly asks for editable diagrams.
• •GitHub social preview PNG files MUST stay under 1 MiB (1048576 bytes). If assets/social-preview.png is larger, compress or regenerate it before registration, validation, commit, or GitHub upload.
• •New projects MUST generate two localized copies of every required README image: zh-CN for the default Chinese README.md, and en for docs/README_en.md. Keep equivalent image types and information architecture across both locales.
• •English documentation MUST NOT be a short summary. docs/README_en.md must be structurally equivalent to the root Chinese README.md, with translated hero, badges, main visual, comparison, workflow, quick start, architecture, FAQ, contribution, version, Star History, license, and author sections.
• •Public GitHub publishing MUST configure repository metadata after push: About description, Topics, and Homepage URL. The Homepage URL should normally be https://github.com/<owner>/<repo> so the About sidebar shows a clickable repository link.
• •Public GitHub publishing MUST use a two-phase Star History flow when the repository does not exist yet: first publish the validated project and configure repository metadata, then run scripts/add-star-history.sh <project-path> <owner>/<repo>, re-run README/baseline validation, and create a second docs: add Star History commit. Never invent a Star History URL before the public repository exists.
• •After every image is generated, MUST call scripts/register-asset.sh to record it in assets/asset-manifest.json. Unregistered images will FAIL verify-assets.sh.
• •README display images MUST use direct Markdown syntax (![label](path)), never fenced code blocks.
• •README rewrite / open-source README tasks MUST load references/readme-rules.md and references/readme-open-source-style.md; the canonical exemplar is this repository's README.md, including social preview image, hero, nav, badges, main visual, comparison, workflow, quick start, architecture, FAQ, contribution, version, acknowledgements, Star History, license, and author sections.

State Model (HARD RULE)

scaffold_done < asset_done < validation_done < initialization_done. See references/state-model.md. 禁止跨越 — 在用户面前用"完成"措辞，必须等到 initialization_done。

Completion Gate

Run in order before reporting done:

scripts/create-platform-project.sh ...     # → STATE=scaffold_done
# for each localized image in assets/.asset-todo.json (7 types × 2 locales):
#   image_gen → scripts/register-asset.sh <project> <image-path>
scripts/verify-assets.sh <project-path>    # → STATE=asset_done
scripts/check-project-baseline.sh <path>   # → STATE=validation_done (含 verify-assets 子检查)

老项目：scripts/check-project-baseline.sh --existing <project-path>（manifest 可缺失，降级为 WARN）。

Reporting Gate

最终回复 必须 按 references/completion-report-template.md 的格式输出。 任何 STATE=*_failed 或孤儿图警告，不允许使用"完成 / 已就绪"措辞，必须用 STATE=partial_done 或具体阻塞描述。

For full rule details, asset rules, naming rules, hybrid path, and upgrade report template, load references/INDEX.md — it lists each rule file and when to load it.