51 lines
8.3 KiB
Markdown
51 lines
8.3 KiB
Markdown
# Page collaboration
|
|
|
|
Use one coordinator and one active writer per page. The coordinator owns narrative and integration; workers own explicitly assigned page directories. Humans and Agents use the same source handoff. This is a recommended workflow on `ppt-project/v1`, not a scheduler or another ownership/history database.
|
|
|
|
## Freeze and assign
|
|
|
|
Consume the agreed audience, deck argument, page order and review cadence through [content handoff](content-handoff.md). Define stable IDs and a brief per page: its task, intended understanding, evidence, data/units, necessary premises and key steps, progression, conclusion-to-evidence associations, capacity, transition and content/notes/appendix allocation. Express these in the existing brief as relevant to the task; no new compiler schema or mandatory page-by-page time budget is needed. Report structure may come from the optional `report-structure` Skill or the user's own plan. Assign only pages authorized to proceed. Under `interactive-page`, review gates still apply; parallel workers do not authorize future pages or a batch.
|
|
|
|
Receive the current editable page source and any accompanying explanation PDF, confirmed content scope and [execution choices](execution-and-review.md). Reuse page-by-page or block-parallel selection, review assignments and budget, ImageGen scope/alternative and confirmed layout preferences; confirm only consequential pending choices. Time pressure alone does not authorize parallel work. A refusal of parallel Agents does not choose serial Agents or main-Agent replacement.
|
|
|
|
Freeze one template/version/theme, content-source revision, manifest and style input hashes, roster, fonts, glossary, shared data/assets. Use the project tools for the template snapshot and builder. Give each worker the same baseline, actual selected-template visual when a layout draft needs it, page brief, scoped confirmed preferences and write allowlist. Read library examples from the selected template. Route shared changes to the coordinator before implementation.
|
|
|
|
Freeze shared container renderers/recipes, named text roles and supported variants as part of that baseline. Workers instantiate them with content and whole-container bounds; they cannot hand-position child text/icons or create private offsets. Include the [text/container constraints](text-and-containers.md) in page review. Any necessary paragraph fragments retain one logical text source/frame and a documented layout implementation; route shared recipe changes to the coordinator.
|
|
|
|
Adapt [plan.example.json](../assets/collaboration/plan.example.json) into `collaboration/plan.json` and [page-packet.example.json](../assets/collaboration/page-packet.example.json) into `pages/<id>/packet.json`. These are handoff examples, not files interpreted automatically by the compiler. Replace every placeholder with real inputs and project-relative paths. Include the plan in `build.inputs` and packets in each page's `data` list when they must travel in the source lock/package. Do not create a second event store.
|
|
|
|
## Write ownership
|
|
|
|
| Surface | Writer | Rule |
|
|
|---|---|---|
|
|
| `pages/<id>/source.svg`, `content.json`, `notes.md`, `assets/`, `packet.json` | Assigned worker | Other pages/shared files read-only |
|
|
| `project.json`, order, selection, environment, builder, shared data/assets | Coordinator | Issue a new baseline after changes |
|
|
| Locks, final exports and receipts | Coordinator | Serial integration/build writer |
|
|
| Worker preview/test output | Corresponding worker | Separate scratch output, never shared final deck |
|
|
|
|
For separate worktrees/devices, return an assigned source diff or directory archive; merge by stable ID and preserve others' changes. Shared directories use the same allowlist. Reassign only after the old writer stops. A peer proposal or writable path does not grant authority. Contact other tasks only when messaging is authorized.
|
|
|
|
## Page delivery
|
|
|
|
Deliver source/content/notes, private assets and a packet recording ID, owner, revision, baseline hashes, layout, purpose, origin, source/asset hashes, preview renderer/hash, native objects, picture exceptions and unresolved issues. State source/static, native structure, SVG render, actual PowerPoint render, editing and projection individually; unavailable checks stay `not-run` with a reason. A PNG does not prove editability. Ready means ready for integration review.
|
|
|
|
Source, content and notes must agree. Update table/chart metadata with data; preserve evidence labels, numbers, units, necessary premises and key steps. Check actual reading order and the visual association between conclusions and evidence. Match fonts, grid, fixed body area and palette; remove placeholders/example text. Keep resources within the assigned page directory.
|
|
|
|
## Integrate and revise
|
|
|
|
1. Compare template/theme/style baseline and incoming hashes. Reject stale baselines and duplicate writers; preserve the worker version for repair. Never silently accept a different theme.
|
|
2. Check ID/layout, paths, content revision, evidence fidelity, notes, preview and object claims. Return precise issues to that page's worker; a coordinator may fix locally after explicitly taking over the page. Verify cross-block dependencies and transitions from actual source, rather than assuming an earlier block supplied them.
|
|
3. Integrate accepted source/assets. The coordinator updates `project.json` order/declarations and shared inputs, then runs `ppt_project.py lock`, `check`, and one `build`. A common roster/theme preserves common Master/Layout identities. Do not merge finished PPTX files as source integration.
|
|
4. Review the integrated deck for narrative, terminology, units, title rhythm, density, figure scale, repeated icons and navigation state. Render it: per-page static checks cannot establish visual consistency. Shared-style changes require affected pages to rebase and rerender.
|
|
5. Keep the agreed user acceptance granularity. Record accepted/revision-needed with evidence, then proceed to the next authorized pages. Pack after locks/integration pass. Another device supplies declared dependencies/fonts and runs its own application checks.
|
|
|
|
Reauthor or repair only affected pages; integrated export still compiles the completed SVG set together. If content allocation or order changes, synchronize stable IDs and destinations, page numbers, references and notes with the plan, including links across split arguments. Reuse unchanged page content and valid prior checks. For shared changes identify affected pages before repeating checks. Author completion, integrated render and user acceptance remain separate states.
|
|
|
|
Use the confirmed review-after-revision assignment; its default is an independent fresh-context reviewer who did not edit that portion. Supply current source and necessary criteria/evidence without author self-assessment, expected verdicts or leading summaries, and let the reviewer judge before seeing old resolution conclusions. Main-Agent checks or skipped reviews retain their actual labels. See [review inputs and affected scope](execution-and-review.md#review-after-revision). This uses the existing page ownership and handoff rather than a new scheduler or fixed Agent count. Save new reference implementations only from actual received or produced material, with source, method and the scope of acceptance. Template geometry feedback stays with the template maintainer; report-logic examples and rule learning stay with the structure maintainer.
|
|
|
|
## Research basis
|
|
|
|
Microsoft documents that [PresentationML](https://learn.microsoft.com/en-us/office/open-xml/presentation/structure-of-a-presentationml-document) relates slides, layouts, masters and themes, and [slide masters](https://learn.microsoft.com/en-us/office/open-xml/presentation/working-with-slide-masters) hold common design/layout relationships. Unified source compilation is our design recommendation based on this structure and this Skill's builder; Microsoft does not prescribe this Agent workflow.
|
|
|
|
[PowerPoint co-authoring](https://support.microsoft.com/en-us/powerpoint/work-together-on-powerpoint-presentations) supports human collaboration on shared OneDrive/SharePoint files with suitable access. It may complement review, but does not replace source packets, provenance or rebuild locks. Use only a user-chosen, authorized storage/sharing route; this workflow creates no cloud shares. Local source division also works with the user's chosen version control.
|