[codex] Add Plugin Creator readiness checklist

.agents/skills/plugin-creator/SKILL.md

@@ -48,6 +48,22 @@ python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin \
 
 `<parent-plugin-directory>` is the directory where the plugin folder `<plugin-name>` will be created (for example `~/code/plugins`).
 
+5. Before treating the plugin as finished, run the readiness check after replacing scaffold placeholders and adding real assets/configuration:
+
+```bash
+python3 .agents/skills/plugin-creator/scripts/check_plugin_readiness.py <plugin-path>
+```
+
+For marketplace-backed plugins, include the selected marketplace path:
+
+```bash
+python3 .agents/skills/plugin-creator/scripts/check_plugin_readiness.py <plugin-path> \
+  --marketplace-path <marketplace-json-path>
+```
+
+Repo plugins under `<repo-root>/plugins/` are checked against `<repo-root>/.agents/plugins/marketplace.json`
+automatically when that marketplace exists.
+
 ## What this skill creates
 
 - Default marketplace-backed scaffolds are personal: `~/plugins/<plugin-name>/` plus
@@ -71,6 +87,7 @@ python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin \
   - `assets/`
   - `.mcp.json`
   - `.app.json`
+- Provides `scripts/check_plugin_readiness.py` to audit a completed scaffold before publishing or sharing.
 
 ## Marketplace workflow
 
@@ -140,11 +157,113 @@ python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin \
 }
 ```
 
+## Readiness checklist
+
+Run `scripts/check_plugin_readiness.py` before telling the user a plugin is complete. Resolve every
+`ERROR`. Treat `WARN` entries as judgment calls; use `--strict-warnings` when the plugin should be
+publish-ready with no loose ends.
+
+The readiness check covers:
+
+- No scaffold placeholders remain in non-reference plugin files, including `[TODO: ...]`, example author URLs,
+  scaffold keywords, generic TODO/TBD markers, and marketplace placeholder names.
+- `.codex-plugin/plugin.json` exists, is valid JSON, uses the normalized folder name, has semantic
+  versioning, and keeps required manifest/interface fields in the expected types.
+- Manifest paths are relative plugin paths that begin with `./` and point to files or directories
+  that actually exist.
+- `interface.logo` and `interface.composerIcon` are real non-empty image assets.
+- `interface.brandColor` is a valid 6-digit hex color and is not blindly left at the scaffold default.
+- `interface.defaultPrompt` contains 1-3 real hero prompts, each 128 characters or fewer.
+- Referenced screenshots exist as non-empty PNG image files.
+- Referenced `.app.json` and `.mcp.json` files are valid JSON with non-empty `apps` or `mcpServers` objects.
+- Every skill `SKILL.md` has frontmatter with `name` and `description`.
+- Every skill with a `SKILL.md` has `agents/openai.yaml` metadata, unless the user explicitly wants
+  to allow missing metadata and the checker is run with `--allow-missing-openai-yaml`.
+- Existing `agents/openai.yaml` files include `interface.display_name` and
+  `interface.short_description`; icon paths are checked when present.
+- Repo plugins under `<repo-root>/plugins/` are included in `<repo-root>/.agents/plugins/marketplace.json`
+  with the correct local source path, policy fields, and category.
+- A marketplace passed with `--marketplace-path` has a matching, valid entry for the plugin.
+
+Useful options:
+
+```bash
+python3 .agents/skills/plugin-creator/scripts/check_plugin_readiness.py <plugin-path> \
+  --marketplace-path ./.agents/plugins/marketplace.json
+```
+
+```bash
+python3 .agents/skills/plugin-creator/scripts/check_plugin_readiness.py <plugin-path> \
+  --allow-missing-openai-yaml
+```
+
+When the readiness check reports issues, translate the output into a short user-facing checklist of
+remaining work. Do not just paste raw checker output unless the user asks for it. Keep the checklist
+actionable and grouped by severity:
+
+```markdown
+Remaining before this plugin is ready:
+- [ ] Replace placeholder manifest fields: version, description, author, homepage, repository.
+- [ ] Add real logo and composer icon assets under `assets/`.
+- [ ] Rewrite `interface.defaultPrompt` with 1-3 real starter prompts.
+- [ ] Add the plugin to `.agents/plugins/marketplace.json`.
+
+Worth reviewing:
+- [ ] Add `agents/openai.yaml` metadata for each skill, or explicitly accept the warning.
+```
+
+After showing the checklist, offer to help complete it interactively. If the user agrees, work
+through the checklist in small batches and rerun the readiness check after each pass.
+
+Recommended order:
+
+1. Identity and manifest copy: display name, description, author, homepage, repository, license,
+   keywords, category, and capabilities.
+2. Interface metadata: brand color, starter prompts, website/privacy/terms URLs, and developer name.
+3. Assets: logo, composer icon, and screenshots. Ask the user to provide real assets or explicitly
+   approve generating real replacement assets.
+4. Integration files: skills, hooks, `.app.json`, `.mcp.json`, and `agents/openai.yaml` metadata.
+5. Marketplace: infer from location. Repo plugins under `<repo-root>/plugins/` should use
+   `<repo-root>/.agents/plugins/marketplace.json`; standalone plugins outside the repo should not
+   require marketplace work unless the user asks for it or passes `--marketplace-path`.
+
+Ask for one batch at a time instead of asking every checklist question at once. Use reasonable
+defaults only for low-risk implementation details. Do not invent publisher identity, legal URLs,
+auth policy, marketplace product gating, or user-provided assets without confirmation.
+
+When readiness issues remain, always make the next step explicit. After the checklist, ask one clear
+question for the highest-priority unresolved non-mechanical item instead of asking a broad question or
+starting with marketplace details. Prefer identity/copy issues first, then prompts, assets,
+integration metadata, and finally marketplace cleanup inferred from location. Example: `What should
+the plugin display name, one-sentence description, and publisher name be?`
+
+Do not satisfy readiness checks by replacing placeholders with dummy values. This applies to all
+manifest copy, prompts, logos, icons, screenshots, marketplace metadata, integration names, and skill
+descriptions. If real values are unknown, ask the user for them or leave the checklist item open. For
+starter prompts, use confirmed plugin use cases; do not write generic prompts just to remove
+`[TODO: ...]`. For logos and icons, use real supplied assets or generated assets the user explicitly
+approves as final, not blank files, generic stand-ins, or fake brand marks. Only create dummy values
+when the user explicitly says they are building a test fixture or intentionally wants non-final
+placeholder content, and label the result as not production-ready.
+
 ## Required behavior
 
 - Outer folder name and `plugin.json` `"name"` are always the same normalized plugin name.
 - Do not remove required structure; keep `.codex-plugin/plugin.json` present.
 - Keep manifest values as placeholders until a human or follow-up step explicitly fills them.
+- After scaffolding, point the user to the readiness checklist and command printed by
+  `create_basic_plugin.py`.
+- Do not call a plugin finished until `scripts/check_plugin_readiness.py` has no `ERROR` findings, or
+  until the user explicitly accepts the remaining errors.
+- When readiness issues remain, provide the user a concise checklist of the remaining items to finish,
+  grouped into blocking errors and review-worthy warnings.
+- Offer to walk through the remaining checklist interactively; if the user agrees, ask for one batch
+  of values at a time, apply the answers, and rerun the readiness check after each pass.
+- Always ask the user one clear next question for the highest-priority unfinished readiness item.
+  Infer marketplace requirements from plugin location instead of making marketplace selection the
+  first or most important question.
+- Do not replace placeholders with dummy or generic values to make the checker pass. Ask for real
+  values/assets, generate final-quality assets only with user approval, or leave the item unresolved.
 - If creating files inside an existing plugin path, use `--force` only when overwrite is intentional.
 - Preserve any existing marketplace `interface.displayName`.
 - When generating marketplace entries, always write `policy.installation`, `policy.authentication`, and `category` even if their values are defaults.