mattrguerra.comHouston area
Matt Guerra
  1. 01AI & Automation
  2. 02Photography
  3. 03Design
  4. 04About
  5. 05Notes
  6. 06Contact
Back to the systems

mattrguerra/meridian-skillsmainPrivate on GitHub, published here in full

builder-api.md

Markdown6.9 KB163 lines

skills/sop-author/references/builder-api.md

  1. # build_sop.py: API reference
  3. The helper script `scripts/build_sop.py` takes a Python dict and produces a styled Meridian SOP .docx. Use it as the default path; only drop down to raw python-docx when the content needs layout the builder doesn't cover.
  5. ## Top-level dict
  7. ```python
  8. {
  9. "title": "Mockup File Naming Convention", # required, str
  10. "owner": "Matt Guerra", # required, str: full name
  11. "initials": "MG", # required, str: 2 or 3 letters
  12. "category": "Operations", # required, str
  13. "effective_date": "04/2026", # required, str: MM/YYYY with slash
  14. "folder_context": "07 - Mockup Artwork Files", # optional, str: appears on line 2 of title bar
  15. "draft": False, # optional, bool: prepends DRAFT_
  16. "template": False, # optional, bool: inserts _TEMPLATE before date
  17. "output_path": "/path/to/output_dir", # optional, str: directory or full path
  18. "sections": [ ... ], # required, list[dict]: see below
  19. }
  20. ```
  22. If `output_path` is a directory, the file is saved inside it using the canonical filename. If it's a full path with a different filename, the builder overrides with the canonical filename (`force_filename: False` to disable).
  24. ## Section types
  26. Each section in `sections` is a dict with a `type` and content fields.
  28. ### Required content sections
  30. ```python
  31. {"type": "purpose", "text": "This SOP defines ..."}
  32. # Renders Heading 1 "Purpose" + body paragraph
  34. {"type": "scope", "text": "This SOP applies to all team members who ..."}
  35. # Renders Heading 1 "Scope & Responsibility" + body paragraph
  36. ```
  38. ### Heading sections
  40. ```python
  41. {"type": "h1", "text": "Folder Structure"}
  42. {"type": "h2", "text": "1.1 Folder Creation & Numbering"}
  43. {"type": "h3", "text": "Components"}
  44. ```
  46. ### Body content
  48. ```python
  49. {"type": "body", "text": "All mockup design files must follow this format..."}
  50. # Arial 11pt black, normal paragraph
  52. {"type": "accent_subhead", "text": "Versioning"}
  53. # Arial Bold 12pt Meridian navy, for in-section topic labels
  55. {"type": "bullet", "text": "Start at v1 for every new job."}
  56. # Bulleted list item, Arial 11pt
  58. {"type": "numbered", "text": "Open the Shared Drive in your browser."}
  59. # Numbered list item, Arial 11pt
  61. {"type": "code", "text": "07 - Mockup Artwork Files\n├── [COMPANY-ID]_[COMPANY NAME]\n└── ..."}
  62. # Multi-line monospace blue code/path block
  64. {"type": "warning", "text": "Do not use 00 for functional folders; it's for SOPs & How-To's only."}
  65. # Bold red callout
  67. {"type": "blank"}
  68. # Inserts a blank paragraph for spacing
  69. ```
  71. ### Tables
  73. ```python
  74. {"type": "format_spec", "text": "Mockup_v[#]_[MM/YYYY]_[Initials]"}
  75. # 1-cell light-blue table with the format pattern in monospace blue bold
  77. {"type": "components_table", "rows": [
  78. ["Component", "Value", "Description"],
  79. ["Mockup", "Always \"Mockup\"", "Fixed document type prefix."],
  80. ["v[#]", "v1, v2, v3...", "Version number."],
  81. ["[MM/YYYY]", "04/2026", "Month and year of creation."],
  82. ["[Initials]", "MG, MI, RM, etc.", "Initials of the team member."],
  83. ]}
  84. # 3-col table. First row is the header. Second column rendered in code style.
  86. {"type": "examples_table", "rows": [
  87. ["Folder", "Sub DIR", "File Name(s)"],
  88. ["NORTHWIND ACADEMY", "H4A", "Mockup_v1_04/2026_RG"],
  89. ["NORTHWIND ACADEMY", "", "Mockup_v2_04/2026_RG"],
  90. ]}
  91. # 3-col table. First row is the header. Last column rendered in code style.
  93. {"type": "note", "text": "Note: This naming convention applies to files inside the 07 - Mockup Artwork Files folder only."}
  94. # 1-cell light-yellow note box, italic gray text
  96. {"type": "quick_ref", "text": "Mockup Format:\nMockup_v[#]_[MM/YYYY]_[Initials]\nFirst version: Mockup_v1_04/2026_RG\nRevision: Mockup_v2_04/2026_RG\nApproved final: Mockup_v3_FINAL_04/2026_RG"}
  97. # 1-cell light-blue reference card, multi-line monospace blue
  98. ```
  100. ## Driver example
  102. A complete driver script the model would write to use the builder:
  104. ```python
  105. import sys
  106. sys.path.insert(0, "/path/to/sop-author/scripts")
  107. from build_sop import build_sop
  109. spec = {
  110. "title": "Mockup Handoff",
  111. "owner": "Matt Guerra",
  112. "initials": "MG",
  113. "category": "Operations",
  114. "effective_date": "05/2026",
  115. "folder_context": "02 - Operations Client Facing > Mockup Handoffs",
  116. "output_path": "/path/to/output_dir",
  117. "sections": [
  118. {"type": "purpose", "text": "This SOP defines the procedure for handing off approved client mockups from the Design team to Client Success."},
  119. {"type": "scope", "text": "Applies to all Display Consultants and CS Associates handling client mockup approvals."},
  121. {"type": "h1", "text": "Process"},
  122. {"type": "h2", "text": "1. Mockup Finalization (Design)"},
  123. {"type": "numbered", "text": "Move the approved mockup file to the client's order folder under 03 - Orders Artwork Files."},
  124. {"type": "numbered", "text": "Rename the file to include _FINAL before the date."},
  125. {"type": "numbered", "text": "Add a comment in the client's CRM record noting the file is ready."},
  127. {"type": "h2", "text": "2. Handoff Notification (Design → CS)"},
  128. {"type": "numbered", "text": "Post in #handoffs with the order number, client name, and the file path."},
  129. {"type": "numbered", "text": "Tag the CS Associate assigned to the order."},
  131. {"type": "h2", "text": "3. CS Confirmation"},
  132. {"type": "numbered", "text": "CS opens the file, spot-checks against the approval thread."},
  133. {"type": "numbered", "text": "If clean: send to the client via the standard delivery email."},
  134. {"type": "numbered", "text": "If issues: return to Design with specifics. Do not edit Design's file."},
  136. {"type": "h1", "text": "Best Practices"},
  137. {"type": "accent_subhead", "text": "Speed vs. Accuracy"},
  138. {"type": "bullet", "text": "Same-day handoff is the goal, but CS confirmation can take up to 24h on high-volume days."},
  139. {"type": "bullet", "text": "Never skip the CS spot-check. The CS Associate is the last set of eyes before the client."},
  141. {"type": "h1", "text": "Quick Reference Card"},
  142. {"type": "quick_ref", "text": "1. Design finalizes file → renames _FINAL → moves to order folder.\n2. Design posts in #handoffs, tags CS.\n3. CS spot-checks.\n4. CS sends to client (or returns to Design)."},
  143. ],
  144. }
  146. out = build_sop(spec)
  147. print(f"Saved: {out}")
  148. ```
  150. ## Validating an existing SOP
  152. ```bash
  153. python3 scripts/build_sop.py --validate /path/to/some_sop.docx
  154. ```
  156. Prints a PASS/FAIL/WARN for each check. Exits 0 if no FAILs.
  158. ## Things the builder does NOT do
  160. - It does not infer SOP type from the content; you must pick the type and pass the right section list.
  161. - It does not edit an existing SOP in place; it always builds from scratch (using the template asset for style inheritance).
  162. - It does not check that the user's content is good. Garbage in → formatted garbage out.
  163. - It does not upload to Drive.