---
name: platform-project-skill
description: This skill should be used when the user asks to "初始化平台项目", "创建 *-platform 项目", "基于 omni-platform 创建项目", "给老项目做 AI 能力升级", "老项目接手能力", "initialize platform project", "create *-platform project", "upgrade legacy project for AI handoff", or wants a reusable workflow for new platform projects and existing project AI enablement.
version: 0.3.0
---

# Platform Project Skill

Two routes, both non-destructive:

| Request | Route | Must read |
|---|---|---|
| Empty / new target | `new` | `references/workflow-new-project.md` + `references/state-model.md` |
| Existing production codebase | `existing` | `references/workflow-existing-project.md` + `references/non-invasive-upgrade.md` |
| Downloaded / cloned / copied public repo into a new named upgraded project | `open-source-fork` | `references/workflow-open-source-fork.md` + `references/readme-open-source-style.md` |
| README / assets / graphify only | `partial` | `references/INDEX.md` then the relevant rule file |

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.
- If the user asks to download/clone/copy a public GitHub repository into a new project name, rebrand it, productize it, upgrade its UI, or prepare it as a public/open-source project, treat it as `open-source-fork` rather than plain `existing`. In that route, preserve upstream attribution but rebuild the root README using the open-source README style: default Simplified Chinese, full English counterpart, social preview near the top, and bilingual README images.
- 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.
- Platform projects MUST prefer shared infrastructure first. Reuse existing PostgreSQL / Redis containers or managed services when reachable; create project-scoped database/schema/role/keyspace only. Generate or start standalone PostgreSQL / Redis containers only when no shared infrastructure exists or the user explicitly asks for isolated infrastructure.
- 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.
- Open-source fork README validation MUST run `scripts/check-open-source-readme.sh <project-path>` or `scripts/check-project-baseline.sh --existing --open-source <project-path>` before reporting completion.

## 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:

```bash
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.