From f9c6d68ded2f9885751db669430ad5c35f41e086 Mon Sep 17 00:00:00 2001 From: Platon Mazarakis Date: Wed, 6 May 2026 09:27:36 -0700 Subject: [PATCH 1/3] Add Google Docs staging hygiene guidance --- plugins/google-drive/skills/google-docs/SKILL.md | 2 ++ .../skills/google-docs/agents/openai.yaml | 2 +- .../reference-import-docx-to-native-docs.md | 12 +++++++----- plugins/google-drive/skills/google-drive/SKILL.md | 2 +- 4 files changed, 11 insertions(+), 7 deletions(-) diff --git a/plugins/google-drive/skills/google-docs/SKILL.md b/plugins/google-drive/skills/google-docs/SKILL.md index af7f3f8e..6b614173 100644 --- a/plugins/google-drive/skills/google-docs/SKILL.md +++ b/plugins/google-drive/skills/google-docs/SKILL.md @@ -27,6 +27,8 @@ Use this routing: 3. If the Documents plugin is unavailable, do not create the net-new Google Doc directly. Report that the required local Documents authoring path is unavailable. 4. Existing Google Docs reads, summaries, edits, comments, and template-preserving modifications: use Google Docs connector or app tools directly. +Local DOCX staging hygiene is mandatory for net-new Google Docs. Put all builder scripts, generated `.docx` files, render outputs, QA PNG/PDF files, and scratch assets in one per-task scratch directory, not in the user-facing workspace root. After successful native import and connector readback, remove those local staging artifacts unless the user explicitly asked to keep local files. + Do not reference the local `.docx` in the final answer after successful native import. The final answer includes the Google Docs link only. ## Runtime Model diff --git a/plugins/google-drive/skills/google-docs/agents/openai.yaml b/plugins/google-drive/skills/google-docs/agents/openai.yaml index 9a2c7bae..c7288914 100644 --- a/plugins/google-drive/skills/google-docs/agents/openai.yaml +++ b/plugins/google-drive/skills/google-docs/agents/openai.yaml @@ -4,4 +4,4 @@ interface: icon_small: "./assets/google-docs-small.svg" icon_large: "./assets/google-docs.png" brand_color: "#1A73E8" - default_prompt: "Use $google-docs for Google Docs work. For net-new Google Docs, create a local DOCX with [@documents](plugin://documents@openai-primary-runtime) first, then upload and convert it to a native Google Doc. For existing Docs, read the target doc, find the right indexes, and apply precise batch updates with proper formatting." + default_prompt: "Use $google-docs for Google Docs work. For net-new Google Docs, create a local DOCX with [@documents](plugin://documents@openai-primary-runtime) first, keep all builder scripts and render artifacts in a per-task scratch directory, then upload and convert it to a native Google Doc and clean up local staging files after connector readback. For existing Docs, read the target doc, find the right indexes, and apply precise batch updates with proper formatting." diff --git a/plugins/google-drive/skills/google-docs/references/reference-import-docx-to-native-docs.md b/plugins/google-drive/skills/google-docs/references/reference-import-docx-to-native-docs.md index 625740d7..b054114a 100644 --- a/plugins/google-drive/skills/google-docs/references/reference-import-docx-to-native-docs.md +++ b/plugins/google-drive/skills/google-docs/references/reference-import-docx-to-native-docs.md @@ -17,7 +17,8 @@ For `.docx` inputs, the blessed path is the Google Drive upload tool with `mime_ Steps: 1. Confirm the local source path is an absolute path to a `.docx` file. -2. Upload the file with the Google Drive connector upload tool: +2. Confirm the local source path and any builder/helper scripts are inside a per-task scratch directory, not the user-facing workspace root. +3. Upload the file with the Google Drive connector upload tool: ```json { @@ -27,10 +28,11 @@ Steps: } ``` -3. Use the connector function exposed in the current runtime, for example `mcp__codex_apps__google_drive._upload_file(...)` or the equivalent Google Drive upload tool. -4. Verify the upload response reports native conversion with `mime_type: "application/vnd.google-apps.document"` and a Google Docs URL or document id. -5. If the desired Google Doc title should not include `.docx`, rename the native Google Doc with `mcp__codex_apps__google_drive._update_file(...)` or the equivalent Drive metadata update tool after upload. -6. Read the imported document with the Google Docs connector and verify that core headings, body text, tables, and other connector-visible content survived conversion. +4. Use the connector function exposed in the current runtime, for example `mcp__codex_apps__google_drive._upload_file(...)` or the equivalent Google Drive upload tool. +5. Verify the upload response reports native conversion with `mime_type: "application/vnd.google-apps.document"` and a Google Docs URL or document id. +6. If the desired Google Doc title should not include `.docx`, rename the native Google Doc with `mcp__codex_apps__google_drive._update_file(...)` or the equivalent Drive metadata update tool after upload. +7. Read the imported document with the Google Docs connector and verify that core headings, body text, tables, and other connector-visible content survived conversion. +8. After successful connector readback, clean up local staging artifacts: generated Python or JS builder scripts, render folders, QA PNG/PDF files, temporary assets, and the local `.docx` source. Keep local files only when the user explicitly asked to preserve them. ## Preservation Mode diff --git a/plugins/google-drive/skills/google-drive/SKILL.md b/plugins/google-drive/skills/google-drive/SKILL.md index a2558ae4..eae0d3aa 100644 --- a/plugins/google-drive/skills/google-drive/SKILL.md +++ b/plugins/google-drive/skills/google-drive/SKILL.md @@ -34,7 +34,7 @@ Start with Google Drive for file discovery and file lifecycle tasks, then route - Deck -> Slides skill - If the user wants to find a file and then edit it, do both in one flow: Drive for discovery, then the file-type skill for the edit. - If the user wants a Google Workspace outcome but has not named a file type yet, start with Drive discovery instead of asking them to choose among separate Google plugins. -- If the user asks to create a new Google Doc, route to the Docs skill. The Docs skill must use `[@documents](plugin://documents@openai-primary-runtime)` to create a local `.docx`, then upload and convert it as a native Google Doc. +- If the user asks to create a new Google Doc, route to the Docs skill. The Docs skill must use `[@documents](plugin://documents@openai-primary-runtime)` to create a local `.docx`, keep all local builder scripts and render artifacts in per-task scratch space, then upload and convert it as a native Google Doc and clean up local staging files after connector readback. - If the user asks to import a local `.docx` into Google Docs, route to the Docs skill and use native Google Docs conversion by default. Preserve the source file type only when the user explicitly asks for that. - If the user asks to create a new Google Sheet, route to the Sheets skill. The Sheets skill should prefer the `[@spreadsheets](plugin://spreadsheets@openai-primary-runtime)` plugin or `$Excel` skill to create a local `.xlsx`, then import it as native Google Sheets. - If the user asks to import a local `.xlsx`, `.xls`, `.ods`, `.csv`, or `.tsv` into Google Sheets, route to the Sheets skill and use native Google Sheets conversion by default. Preserve the source file type only when the user explicitly asks for that. From 867ee4b6d0ff929b6c252739c4f530afa9144e5a Mon Sep 17 00:00:00 2001 From: Platon Mazarakis Date: Wed, 6 May 2026 10:02:03 -0700 Subject: [PATCH 2/3] Drop Google Docs agent prompt change --- plugins/google-drive/skills/google-docs/agents/openai.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/google-drive/skills/google-docs/agents/openai.yaml b/plugins/google-drive/skills/google-docs/agents/openai.yaml index c7288914..9a2c7bae 100644 --- a/plugins/google-drive/skills/google-docs/agents/openai.yaml +++ b/plugins/google-drive/skills/google-docs/agents/openai.yaml @@ -4,4 +4,4 @@ interface: icon_small: "./assets/google-docs-small.svg" icon_large: "./assets/google-docs.png" brand_color: "#1A73E8" - default_prompt: "Use $google-docs for Google Docs work. For net-new Google Docs, create a local DOCX with [@documents](plugin://documents@openai-primary-runtime) first, keep all builder scripts and render artifacts in a per-task scratch directory, then upload and convert it to a native Google Doc and clean up local staging files after connector readback. For existing Docs, read the target doc, find the right indexes, and apply precise batch updates with proper formatting." + default_prompt: "Use $google-docs for Google Docs work. For net-new Google Docs, create a local DOCX with [@documents](plugin://documents@openai-primary-runtime) first, then upload and convert it to a native Google Doc. For existing Docs, read the target doc, find the right indexes, and apply precise batch updates with proper formatting." From 599407f87a5dded408e8515b33b50083db16b480 Mon Sep 17 00:00:00 2001 From: Platon Mazarakis Date: Wed, 6 May 2026 19:56:42 -0700 Subject: [PATCH 3/3] Port latest Google Docs import guidance --- .../google-drive/skills/google-docs/SKILL.md | 19 +++++++---- .../reference-import-docx-to-native-docs.md | 33 ++++++++++++++----- .../google-drive/skills/google-drive/SKILL.md | 2 +- 3 files changed, 39 insertions(+), 15 deletions(-) diff --git a/plugins/google-drive/skills/google-docs/SKILL.md b/plugins/google-drive/skills/google-docs/SKILL.md index 6b614173..3740edf1 100644 --- a/plugins/google-drive/skills/google-docs/SKILL.md +++ b/plugins/google-drive/skills/google-docs/SKILL.md @@ -6,7 +6,7 @@ description: Documents-first net-new Google Docs creation plus connector-first G # Google Docs Use this skill for Google Docs work in Codex local-plugin sessions where Browser Use and rendered visual inspection are unavailable. -Net-new Google Doc deliverables must be authored through `[@documents](plugin://documents@openai-primary-runtime)` as local `.docx` files first, then uploaded as native Google Docs. +Net-new Google Doc deliverables must be authored through `[@documents](plugin://documents@openai-primary-runtime)` as local `.docx` files first, using the `google_docs_default` design preset by default, then uploaded as native Google Docs. ## Purpose Of This File @@ -22,15 +22,21 @@ Latency is not a constraint for this skill, so always read the relevant referenc Use this routing: -1. Net-new Google Docs creation: use `[@documents](plugin://documents@openai-primary-runtime)` to create a local `.docx` first, including that skill's DOCX QA workflow. -2. Upload and convert the `.docx` into Drive as a native Google Docs document. Read `references/reference-import-docx-to-native-docs.md`. +1. Net-new Google Docs creation: use `[@documents](plugin://documents@openai-primary-runtime)` to create a local `.docx` first, explicitly selecting the `google_docs_default` design preset unless the user asked for a special, branded, or highly polished visual treatment. +2. Upload and convert the `.docx` into Drive as a native Google Docs document. Read `references/reference-import-docx-to-native-docs.md`, then run the repair-only post-import normalization pass described there. 3. If the Documents plugin is unavailable, do not create the net-new Google Doc directly. Report that the required local Documents authoring path is unavailable. 4. Existing Google Docs reads, summaries, edits, comments, and template-preserving modifications: use Google Docs connector or app tools directly. -Local DOCX staging hygiene is mandatory for net-new Google Docs. Put all builder scripts, generated `.docx` files, render outputs, QA PNG/PDF files, and scratch assets in one per-task scratch directory, not in the user-facing workspace root. After successful native import and connector readback, remove those local staging artifacts unless the user explicitly asked to keep local files. +Local DOCX staging hygiene is mandatory for net-new Google Docs. Staging must be non-user-visible and untracked from the start. Do not create DOCX builder or helper scripts with tracked file-edit tools such as `apply_patch`, and do not create helper source files in the workspace or any path surfaced by Changes Made. Prefer the Documents plugin's built-in authoring workflow or a one-shot runtime command that keeps generation code ephemeral and persists only the required `.docx`, render outputs, and scratch assets in a per-task scratch directory. After successful native import and connector readback, remove those local staging artifacts unless the user explicitly asked to keep local files. Cleanup is required as a backstop, not as the visibility control. Do not reference the local `.docx` in the final answer after successful native import. The final answer includes the Google Docs link only. +## Google Docs Default Preset + +For a net-new Google Doc, `google_docs_default` is the default visual contract. Do not let the Documents skill infer `standard_business_brief`, `compact_reference_guide`, or another Word-oriented preset from the content archetype alone. The expected result is a native-feeling Google Doc after import: Arial-based typography, black title/headings/body text, simple title block, restrained spacing, real lists, and no imported Word-template chrome such as blue headings, colored callouts, dense table borders, or running header/footer furniture. + +Use a different Documents preset only when the user explicitly asks for a special visual treatment, a branded document, or a more polished formal artifact than a normal Google Doc. + ## Runtime Model This plugin is for the local Codex plugin environment. @@ -66,7 +72,7 @@ For existing document editing tasks and follow-on edits after a DOCX import, pre 3. establish the heading and section skeleton 4. fill the core text or structured content 5. decide which content should stay prose, become a table, become a short card, or become a compact visual block -6. verify and normalize formatting +6. verify and normalize formatting, including the repair-only Google Docs post-import pass for imported DOCX files 7. add secondary elements such as tables, links, or connector-supported figures only after the core structure is stable 8. stop once the document is clean, complete, and scannable @@ -79,7 +85,7 @@ If a simple verified workflow is viable, use it. Do not drift into speculative a Before final handoff, explicitly verify these with connector readback: 1. every new or edited table has the intended rows, columns, cell text, table anchor, style requests, and column widths where the connector exposes them -2. every new or edited heading, label, and body block matches surrounding connector-visible style fields such as named style, font family, font size, bolding, links, and list state +2. every new or edited heading, label, and body block matches surrounding connector-visible style fields such as named style, font family, font size, bolding, links, and list state; imported net-new Docs should read back as Arial-based, black-text documents without obvious blue-heading or Word-template residue 3. every inserted figure or image uses a connector-supported insertion path and is present in connector readback; if rendered placement cannot be inspected, say so plainly 4. when available, export the document as `text/html` through Google Drive and use the generated markup/CSS as a rendered-structure proxy for heading tags, font families, font sizes, table cells, fills, widths, and paragraph ordering 5. the document is not relying on one repeated structure everywhere; for example, a long run of similar tables or identical header colors should be treated as a design smell unless the source template clearly calls for it @@ -96,6 +102,7 @@ If Default Routing uses `[@documents](plugin://documents@openai-primary-runtime) 1. Read the `[@documents](plugin://documents@openai-primary-runtime)` plugin skill. 2. Read `references/reference-import-docx-to-native-docs.md`. +3. For the post-import normalization pass, also read `references/reference-request-shapes-and-write-safety.md`, `references/reference-headings-and-question-format.md`, `references/reference-response-and-list-format.md`, and `references/reference-section-completeness-and-final-pass.md`. If Default Routing uses connector edit workflow: diff --git a/plugins/google-drive/skills/google-docs/references/reference-import-docx-to-native-docs.md b/plugins/google-drive/skills/google-docs/references/reference-import-docx-to-native-docs.md index b054114a..167be480 100644 --- a/plugins/google-drive/skills/google-docs/references/reference-import-docx-to-native-docs.md +++ b/plugins/google-drive/skills/google-docs/references/reference-import-docx-to-native-docs.md @@ -7,7 +7,7 @@ description: Import a local DOCX as a native Google Docs document. When to read: after creating or locating a local `.docx` file that should become a native Google Docs document. -For new Google Docs creation, create the local document with the `[@documents](plugin://documents@openai-primary-runtime)` plugin first, then follow this import path. +For new Google Docs creation, create the local document with the `[@documents](plugin://documents@openai-primary-runtime)` plugin first, explicitly selecting the `google_docs_default` design preset unless the user asked for a special, branded, or highly polished visual treatment, then follow this import path. ## Native Conversion @@ -17,8 +17,9 @@ For `.docx` inputs, the blessed path is the Google Drive upload tool with `mime_ Steps: 1. Confirm the local source path is an absolute path to a `.docx` file. -2. Confirm the local source path and any builder/helper scripts are inside a per-task scratch directory, not the user-facing workspace root. -3. Upload the file with the Google Drive connector upload tool: +2. Confirm the local staging path is a per-task scratch directory, not the user-facing workspace root. +3. Confirm no persistent DOCX builder or helper source file was created with tracked file-edit tools such as `apply_patch`, and no helper source file lives in a path surfaced by Changes Made. If generation logic is needed, use the Documents plugin's built-in tooling or a one-shot runtime command that keeps the code ephemeral and writes only the `.docx` and required QA outputs into scratch space. If a tracked helper file was already created, regenerate through untracked scratch before upload unless the user explicitly asked to keep that file. +4. Upload the file with the Google Drive connector upload tool: ```json { @@ -28,11 +29,27 @@ Steps: } ``` -4. Use the connector function exposed in the current runtime, for example `mcp__codex_apps__google_drive._upload_file(...)` or the equivalent Google Drive upload tool. -5. Verify the upload response reports native conversion with `mime_type: "application/vnd.google-apps.document"` and a Google Docs URL or document id. -6. If the desired Google Doc title should not include `.docx`, rename the native Google Doc with `mcp__codex_apps__google_drive._update_file(...)` or the equivalent Drive metadata update tool after upload. -7. Read the imported document with the Google Docs connector and verify that core headings, body text, tables, and other connector-visible content survived conversion. -8. After successful connector readback, clean up local staging artifacts: generated Python or JS builder scripts, render folders, QA PNG/PDF files, temporary assets, and the local `.docx` source. Keep local files only when the user explicitly asked to preserve them. +5. Use the connector function exposed in the current runtime, for example `mcp__codex_apps__google_drive._upload_file(...)` or the equivalent Google Drive upload tool. +6. Verify the upload response reports native conversion with `mime_type: "application/vnd.google-apps.document"` and a Google Docs URL or document id. +7. If the desired Google Doc title should not include `.docx`, rename the native Google Doc with `mcp__codex_apps__google_drive._update_file(...)` or the equivalent Drive metadata update tool after upload. +8. Read the imported document with the Google Docs connector and verify that core headings, body text, tables, and other connector-visible content survived conversion. +9. Run the repair-only post-import normalization pass below. +10. After successful connector readback and normalization, clean up local staging artifacts: generated render folders, QA PNG/PDF files, temporary assets, and the local `.docx` source. Keep local files only when the user explicitly asked to preserve them. Cleanup is a final backstop and does not replace the requirement to avoid tracked helper files before upload. + +## Post-Import Normalization + +Use this only for imported net-new Google Docs created from the Documents plugin. The goal is to repair conversion drift, not to create a second styling system. + +1. Re-read the imported document and sample the title, the first real section heading, one body paragraph, and the first list if present. +2. Verify the imported document still matches the `google_docs_default` intent: + - title/headings/body text use Arial or the closest connector-visible Arial family + - text color is black for title, headings, body, and lists + - section hierarchy is preserved with real Docs heading styles + - bullets and numbered items are real Docs lists, not typed markers + - no obvious Word-style residue survived import: blue heading colors, decorative running headers/footers, colored callout fills, dense table borders, or table-first packaging of normal prose +3. If any of those checks drifted during import, use the normal Google Docs connector write path to repair only the affected ranges. Prefer `updateParagraphStyle`, `updateTextStyle`, `createParagraphBullets`, `deleteParagraphBullets`, `updateTableCellStyle`, and other narrow native requests instead of broad rewrites. +4. Re-read the repaired ranges and, when available, export `text/html` as a structure/style proxy to confirm the imported document now reads like a native Google Doc. +5. Do not add smart chips, metadata pills, decorative mastheads, or new styling flourishes in this pass. Those are out of scope for v1. ## Preservation Mode diff --git a/plugins/google-drive/skills/google-drive/SKILL.md b/plugins/google-drive/skills/google-drive/SKILL.md index eae0d3aa..34ab3c90 100644 --- a/plugins/google-drive/skills/google-drive/SKILL.md +++ b/plugins/google-drive/skills/google-drive/SKILL.md @@ -34,7 +34,7 @@ Start with Google Drive for file discovery and file lifecycle tasks, then route - Deck -> Slides skill - If the user wants to find a file and then edit it, do both in one flow: Drive for discovery, then the file-type skill for the edit. - If the user wants a Google Workspace outcome but has not named a file type yet, start with Drive discovery instead of asking them to choose among separate Google plugins. -- If the user asks to create a new Google Doc, route to the Docs skill. The Docs skill must use `[@documents](plugin://documents@openai-primary-runtime)` to create a local `.docx`, keep all local builder scripts and render artifacts in per-task scratch space, then upload and convert it as a native Google Doc and clean up local staging files after connector readback. +- If the user asks to create a new Google Doc, route to the Docs skill. The Docs skill must use `[@documents](plugin://documents@openai-primary-runtime)` with the `google_docs_default` preset to create a local `.docx`, avoid tracked DOCX builder/helper scripts or files surfaced by Changes Made, stage only required outputs in per-task scratch space, then upload and convert it as a native Google Doc, run the narrow post-import normalization pass, and clean up local staging files after connector readback. - If the user asks to import a local `.docx` into Google Docs, route to the Docs skill and use native Google Docs conversion by default. Preserve the source file type only when the user explicitly asks for that. - If the user asks to create a new Google Sheet, route to the Sheets skill. The Sheets skill should prefer the `[@spreadsheets](plugin://spreadsheets@openai-primary-runtime)` plugin or `$Excel` skill to create a local `.xlsx`, then import it as native Google Sheets. - If the user asks to import a local `.xlsx`, `.xls`, `.ods`, `.csv`, or `.tsv` into Google Sheets, route to the Sheets skill and use native Google Sheets conversion by default. Preserve the source file type only when the user explicitly asks for that.