Update to Plugin Autopilot

{
  "description": "Use when converting an agentic repository into a ChatGPT/Codex Plugin or when building, repairing, validating, packaging, submitting, publishing, or auditing an existing Plugin.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 364
    },
    {
      "relative_path": "references/architectures.md",
      "size_in_bytes": 5852
    },
    {
      "relative_path": "references/branding-and-listing.md",
      "size_in_bytes": 3891
    },
    {
      "relative_path": "references/conformance-matrix.md",
      "size_in_bytes": 10915
    },
    {
      "relative_path": "references/conversion-pipeline.md",
      "size_in_bytes": 6443
    },
    {
      "relative_path": "references/host-python-sandbox.md",
      "size_in_bytes": 3168
    },
    {
      "relative_path": "references/host-workspace-capabilities.md",
      "size_in_bytes": 4661
    },
    {
      "relative_path": "references/official-contract.md",
      "size_in_bytes": 13323
    },
    {
      "relative_path": "references/release-playbook.md",
      "size_in_bytes": 4494
    },
    {
      "relative_path": "references/submission-checklist.md",
      "size_in_bytes": 5314
    },
    {
      "relative_path": "references/submission-errors.md",
      "size_in_bytes": 9091
    },
    {
      "relative_path": "scripts/analyze_repo.py",
      "size_in_bytes": 10617
    },
    {
      "relative_path": "scripts/build_directory_pack.py",
      "size_in_bytes": 14058
    },
    {
      "relative_path": "scripts/install_host_workspace_skill.py",
      "size_in_bytes": 2065
    },
    {
      "relative_path": "scripts/package_plugin.py",
      "size_in_bytes": 5973
    },
    {
      "relative_path": "scripts/validate_plugin.py",
      "size_in_bytes": 73417
    }
  ],
  "name": "chatgpt-codex-plugin-autopilot",
  "skill_md_contents": "---\nname: chatgpt-codex-plugin-autopilot\ndescription: Use when converting an agentic repository into a ChatGPT/Codex Plugin or when building, repairing, validating, packaging, submitting, publishing, or auditing an existing Plugin.\n---\n\n# ChatGPT/Codex Plugin Autopilot\n\nTake an arbitrary repository from agentic-workflow discovery to a verified ChatGPT/Codex Plugin artifact and, when explicitly authorized, through release/submission. This repository is itself a ChatGPT/Codex Plugin and must remain capable of validating and packaging its own installed surface.\n\nTreat the target repository as authoritative for product behavior and release channels. Never require Riqor, Bun, Node, or a project-specific layout unless the target already requires it.\n\n## Operating contract\n\n1. Verify the current **official OpenAI Plugin** and Skill documentation before editing public configuration. Current official docs override remembered schema, examples, limits, and tool availability. Read `references/official-contract.md`, `references/branding-and-listing.md`, `references/host-python-sandbox.md`, and `references/host-workspace-capabilities.md`.\n2. Inspect repository instructions, package metadata, manifests, Skills, agents, workflows, MCP/app configuration, hooks, assets, legal/support pages, CI, release scripts, tags, and public-distribution constraints before changing anything.\n3. When the repository is not already a coherent Plugin, run Repo-to-Plugin conversion first. Use `scripts/analyze_repo.py` plus `agentic-repo-discovery` to identify candidate workflows and set the public boundary.\n4. Classify the target as `skills-only`, `MCP-backed`, or `hybrid` from declared active components and actual user behavior, not from stray `.app.json` or `.mcp.json` files.\n5. Run the **public-distribution safety** review before mirroring internal capabilities into public Skills.\n6. Compile selected workflows with `workflow-to-skill-compiler`. Preserve decisions, approvals, tests, evidence, and stop conditions.\n7. Build the host-workspace capability profile with `plugin-experience-architect`. Decide whether the Plugin needs read, list, search, grep, write, patch, shell, and Python. Keep read-only discovery separate from mutation operations.\n8. For Plugins that interact with files, repositories, generated artifacts, or workspace state, install the canonical `host-workspace-operator` Skill with `scripts/install_host_workspace_skill.py`. Do not overwrite a customized existing copy without review.\n9. When deterministic computation, parsing, hashing, archive inspection, or Python-based verification is useful, include and invoke `sandbox-python-executor`. In ChatGPT, explicitly use the **python tool** when it is available. Do not claim execution without execution evidence.\n10. Build or repair `.codex-plugin/plugin.json`, focused Skills, optional `agents/openai.yaml`, optional MCP/app configuration, optional hooks, square branding, and accurate public URLs.\n11. For public preparation, require the product-specific SVG brand pack from `plugin-brand-identity-designer`: `assets/logo-light.svg`, `assets/logo-dark.svg`, and a compact square icon.\n12. Build truthful public metadata through `plugin-directory-listing-writer`: Name, Subtitle, Description, Category, verified Developer name, Website, Customer support, Privacy policy, Terms, Version, Package name, Capabilities, starter prompts, and reviewer material.\n13. Enforce package shape before copy polish. Only `plugin.json` belongs inside `.codex-plugin/`; every intended Skill is an immediate real child directory of `skills/` containing `SKILL.md`.\n14. Validate declared paths and assets. Reject outer whitespace, control characters, absolute paths, drive paths, `..` traversal, package escapes, missing files, invalid square branding, secret-shaped files, transient bytecode, and symlinks.\n15. Validate `agents/openai.yaml` when present as fail-closed YAML with the documented mapping/string/boolean/list types. Do not invent dependencies for host-native read/write/search/grep/shell/patch/Python capabilities. Documented Skill dependencies remain limited to the current official contract.\n16. Treat `.app.json` and `.mcp.json` as active only when the manifest declares the matching component.\n17. Run repository-native tests plus `scripts/validate_plugin.py` and fail closed on blocking errors. When the host provides execution tools, **execute the checks**; do not merely print commands and describe them as verified.\n18. Build the ZIP twice with `scripts/package_plugin.py` and require deterministic byte identity or matching SHA256. Extract a fresh copy and validate it again.\n19. Inspect archive contents, excluded capabilities, secret/privacy boundaries, package-relative paths, installation behavior, and generated workspace Skills.\n20. Smoke a fresh install on every available ChatGPT/Codex surface. Do not claim unavailable surfaces were tested.\n21. Run the separate submission-readiness gate. A valid ZIP, logo, listing, or successful local install is not OpenAI approval.\n22. Diagnose uploader/review failures from the current official docs and `references/submission-errors.md`; fix root causes and rerun the entire gate.\n23. Under **Full Autopilot Publish**, commit, tag, push, publish, and create releases without another routine confirmation only after all gates pass and only within the user's authorized release scope.\n24. Report exact commit, tag, version, hashes, executed tests, skipped checks, remote status, and residual warnings.\n\n## Repo-to-Plugin conversion mode\n\n### Stage A: discover\n\nRun:\n\n```bash\npython3 <autopilot-skill>/scripts/analyze_repo.py <target-repo> --json\n```\n\nUse `agentic-repo-discovery` to assign each candidate one disposition:\n\n```text\npreserve_skill\ncompile_skill\nreference_only\nruntime_dependency\ninternal_only\ndiscard\n```\n\nDo not treat discovery as automatic publication.\n\n### Stage B: compile workflows\n\nUse `workflow-to-skill-compiler`. One source file does not have to become one Skill. Merge fragments serving one job, split mixed workflows, and keep private or unsafe capabilities out of the public package.\n\nWhen a workflow touches local files or code, express its operations using host capabilities rather than one hard-coded tool implementation.\n\n### Stage C: design the Plugin experience\n\nUse `plugin-experience-architect` to define:\n\n- primary user and recurring job\n- public Skill set and exclusions\n- required/optional app dependencies\n- capability language and starter prompts\n- invocation boundaries\n- host-workspace capability profile\n- mutation boundary\n- whether `host-workspace-operator` should be installed\n- whether `sandbox-python-executor` is needed\n\n### Stage D: install the host workspace baseline\n\nFor repository/file-oriented Plugins, run:\n\n```bash\npython3 <autopilot-skill>/scripts/install_host_workspace_skill.py <target-plugin>\n```\n\nThe generated Plugin receives a portable Skill covering:\n\n```text\nread\nlist\nsearch\ngrep\nwrite\npatch\nshell\npython\n```\n\nThese are host-native capabilities, not permissions granted by the Plugin. The Skill maps intent to whichever compatible tools the current ChatGPT/Codex host exposes.\n\nDefault behavior:\n\n- read/list/search/grep first for discovery\n- patch before broad rewrite when available\n- write only for authorized mutation\n- shell for repository commands when narrower tools are insufficient\n- Python for deterministic computation and verification\n- no fabricated tool use when a capability is unavailable\n\nThe installer is idempotent and refuses to overwrite a customized existing `host-workspace-operator`.\n\n### Stage E: execute in the host sandbox\n\nUse `sandbox-python-executor` when a claim depends on real local computation, package inspection, hashing, file transformation, or the bundled Python validators/packagers.\n\nIn ChatGPT, when the **python tool** is available, use it. In Codex, use the safe host execution environment available to the session. Preserve execution evidence such as status, important output, generated file paths, and hashes.\n\nIf the required tool is unavailable, state that limitation and keep execution-dependent claims unverified.\n\n### Stage F: design the brand identity\n\nUse `plugin-brand-identity-designer` after the product boundary is stable. Create product-specific light/dark SVG variants sharing one geometry plus a small icon. Do not invent unsupported manifest fields for extra variants.\n\n### Stage G: build the Plugin Directory listing\n\nUse `plugin-directory-listing-writer`, then run:\n\n```bash\npython3 <autopilot-skill>/scripts/build_directory_pack.py <target-plugin> --json\n```\n\nMissing verified publisher/legal information is a blocker, not a copywriting opportunity.\n\n### Stage H: prove and prepare submission\n\nRun package preflight, deterministic packaging, clean extraction validation, reviewer tests, and discovery checks. Only then use `submission-pack-builder`.\n\nKeep these states separate:\n\n```text\nanalyzed\nconversion planned\nworkspace ready\nbrand ready\nlisting ready\nlocally validated\nsubmission ready\nsubmitted\napproved\npublished\n```\n\n## Host workspace operations rule\n\n`host-workspace-operator` is the shared execution policy for local workspace work.\n\nUse the narrowest available capability:\n\n- `read`: known file/range\n- `list`: directory/workspace shape\n- `search`: broad or semantic discovery\n- `grep`: exact text, regex, symbol, or field lookup\n- `patch`: focused existing-file edit\n- `write`: create/replace content when authorized\n- `shell`: tests, git, archive, or repository commands\n- `python`: deterministic parsing, transformations, hashes, and validation\n\nRead-only operations should establish the current state before mutations. Write, patch, delete, move, rename, formatting changes, and mutating shell commands are state changes and must respect the user's authorization and repository instructions.\n\nA generated Skill must never say it searched, read, wrote, patched, ran shell, or executed Python unless the current host actually produced evidence of that action.\n\nSee `references/host-workspace-capabilities.md`.\n\n## Host-native Python rule\n\n`sandbox-python-executor` is an execution policy around host capabilities supplied by ChatGPT/Codex. It is not an MCP server and does not grant a Python tool.\n\nWhen Python is available and materially improves correctness:\n\n- execute deterministic work instead of mental simulation\n- prefer bundled reviewed scripts when they already implement the check\n- keep target-repository access read-only by default\n- inspect untrusted target scripts before running them\n- do not assume sandbox internet access\n- return execution evidence\n\nWhen unavailable, do not claim tests, validation, packaging, hashes, or generated files were executed.\n\nSee `references/host-python-sandbox.md`.\n\n## Package preflight\n\nCheck at minimum:\n\n- `.codex-plugin/plugin.json` is present and alone in its manifest directory\n- declared component paths are safe and point to documented root locations\n- required logo and composer icon are valid square images\n- public Autopilot-produced Plugins contain committed light/dark SVG variants\n- every direct child under `skills/` is a valid Skill directory\n- `host-workspace-operator` is present when the Plugin's conversion plan requires local workspace operations\n- Skill frontmatter is valid YAML (mapping with non-empty string `name` and `description`), body/identity are valid, and names are unique\n- optional `agents/openai.yaml` is valid\n- declared app/MCP files are structurally valid; undeclared `.app.json` / `.mcp.json` do not alter architecture and fail Skills-only public preflight\n- package contains no secrets, bytecode, symlinks, excluded capabilities, normalization collisions, or local absolute user paths\n- deterministic packager produces the same bytes from the same source\n\n## Submission readiness\n\nUse `references/submission-checklist.md` plus current official documentation. Verify publisher identity, listing fields, brand assets, public Skill inventory, host-capability claims, starter prompts, required reviewer cases, and MCP review material when applicable.\n\nNever collapse `locally validated`, `submitted`, `approved`, and `published` into one status.\n\n## Public-distribution safety gate\n\nReview every public Skill name, description, instruction, reference, generated copy, capability label, and packaged executable behavior. Never blindly mirror all internal agents into a public Plugin.\n\nWhen a capability must stay internal, remove every public replica, registration, generated Skill, runtime mirror, reference, index entry, and archive entry. Regeneration must not restore it.\n\nPass excluded slugs to the validator:\n\n```bash\npython3 <autopilot-skill>/scripts/validate_plugin.py <plugin-root> --exclude <slug> --json\n```\n\n## Strict generic preflight\n\nWhen execution is available, actually run:\n\n```bash\npython3 <autopilot-skill>/scripts/validate_plugin.py <plugin-root> --json\npython3 <autopilot-skill>/scripts/build_directory_pack.py <plugin-root> --json\npython3 <autopilot-skill>/scripts/package_plugin.py <plugin-root> /tmp/plugin-a.zip --json\npython3 <autopilot-skill>/scripts/package_plugin.py <plugin-root> /tmp/plugin-b.zip --json\ncmp /tmp/plugin-a.zip /tmp/plugin-b.zip\nunzip -Z1 /tmp/plugin-a.zip\n```\n\nThen extract to a clean directory and rerun `validate_plugin.py` against the extraction.\n\nRepository-native quality, security, domain acceptance, and smoke checks remain additional gates.\n\n## Learned failure patterns that must stay covered\n\n- a loose `skills/registry.json` can be ignored by Skill import; move intended metadata under a valid owner and migrate consumers\n- missing `interface.logo` or `interface.composerIcon` blocks directory branding validation\n- a path such as `./assets/../assets/icon.svg` is unsafe even if it resolves inside the package\n- extra files inside `.codex-plugin/` are misplaced\n- undeclared `.app.json` / `.mcp.json` do not activate app/MCP capability and cannot remain in a Skills-only ZIP\n- Skills-only packages cannot include `interface.screenshots`; MCP screenshots need one PNG/JPEG per starter prompt at 706x400–860\n- Skill metadata `name` and directory slug are separate contracts\n- `agents/openai.yaml` must be validated when bundled\n- host-native read/write/search/grep/shell/patch/Python capabilities must not be represented as invented manifest dependencies\n- a local install is evidence, not public directory approval\n- GitHub/package authorship is not proof of verified OpenAI developer identity\n- a good-looking logo or complete listing is not proof of technical validity\n- a Plugin Skill can require execution behavior but cannot fabricate host tool availability\n\n## Stop conditions\n\nStop before irreversible publication when required OpenAI rules cannot be verified, repository identity is ambiguous, credentials are unavailable, tests/validation fail, a target immutable version already exists, package identity is nondeterministic when determinism is promised, public copy contradicts behavior, publisher/legal listing facts are missing, reviewer evidence cannot be produced honestly, or the requested action exceeds authorization.\n\nDo not weaken tests, hide uploader failures, rewrite released tags, inject registry credentials into CI, force-push unrelated history, overwrite customized workspace Skills without review, claim tool execution that did not occur, or claim Plugin Directory publication when only a local artifact was prepared.\n"
}