ec1dfe59e4
Core plan: current-state, goal-state (layered architecture, OtOpcUa, Redpanda EventHub, SnowBridge, canonical model, UNS posture + naming hierarchy, digital twin use cases absorbed), roadmap (7 workstreams x 3 years), and status bookmark. Component detail files: legacy integrations inventory (3 integrations, pillar 3 denominator closed), equipment protocol survey template (dual mandate with UNS hierarchy snapshot), digital twin management brief (conversation complete, outcome recorded). Output generation pipeline: specs for 18-slide mixed-stakeholder PPTX and faithful-typeset PDF, with README, design doc, and implementation plan. No generated outputs yet — deferred until source data is stable.
276 lines
11 KiB
Markdown
276 lines
11 KiB
Markdown
# Output Generation Pipeline Implementation Plan
|
||
|
||
> **For Claude:** REQUIRED SUB-SKILL: Use `superpowers-extended-cc:executing-plans` to implement this plan task-by-task. Note: this repo is not a git project and the work is markdown authoring + skill invocation, not code. The standard writing-plans template (TDD, pytest, git commits) does not apply; use the **verification steps** per task as the equivalent of "run the tests."
|
||
|
||
**Goal:** Scaffold a repeatable PPTX + PDF generation pipeline over the plan markdown source, and produce the first pair of outputs.
|
||
|
||
**Architecture:** Spec files (`presentation-spec.md`, `longform-spec.md`) as structure anchors; hand-drawn Mermaid diagrams committed as `.mmd` + `.png`; `document-skills:pptx` and `document-skills:pdf` invoked per a fixed checklist in `outputs/README.md`; append-only `run-log.md` records every regeneration.
|
||
|
||
**Tech Stack:** Markdown, Mermaid (for diagrams), `document-skills:pptx`, `document-skills:pdf`, `document-skills:theme-factory` default theme.
|
||
|
||
**Design reference:** [`outputs/DESIGN.md`](DESIGN.md)
|
||
|
||
**Path note:** Writing-plans' default location is `docs/plans/YYYY-MM-DD-<name>.md`; this repo convention keeps documents in topical directories, so this plan lives alongside the pipeline it implements.
|
||
|
||
---
|
||
|
||
## Task 0: Directory scaffold
|
||
|
||
**Status:** Parent directory `outputs/` already exists (created when `DESIGN.md` was written). This task creates the remaining subdirectories.
|
||
|
||
**Files:**
|
||
- Create: `outputs/diagrams/` (directory)
|
||
- Create: `outputs/generated/` (directory)
|
||
|
||
**Step 1:** `mkdir -p outputs/diagrams outputs/generated`
|
||
|
||
**Step 2: Verify**
|
||
Run: `ls outputs/`
|
||
Expected: `DESIGN.md IMPLEMENTATION-PLAN.md diagrams generated` (README, specs, run-log not yet created)
|
||
|
||
---
|
||
|
||
## Task 1: outputs/README.md — trigger phrases + regeneration checklist
|
||
|
||
**Files:**
|
||
- Create: `outputs/README.md`
|
||
|
||
**Content requirements:**
|
||
- Purpose statement (what `outputs/` is and isn't)
|
||
- Trigger phrases section — `regenerate outputs`, `regenerate presentation`, `regenerate longform`
|
||
- Numbered regeneration procedure (the 5-step checklist from design section 2)
|
||
- Edit-this-not-that rules — when to edit specs vs. source vs. diagrams
|
||
- Pointers to `DESIGN.md`, `presentation-spec.md`, `longform-spec.md`, `run-log.md`
|
||
|
||
**Verification:**
|
||
- File exists at `outputs/README.md`
|
||
- Contains the three trigger phrases verbatim
|
||
- Contains the 5-step procedure numbered 1–5
|
||
- Links to the four companion files resolve to existing or soon-to-exist paths
|
||
|
||
---
|
||
|
||
## Task 2: outputs/presentation-spec.md — 18-slide PPTX structure anchor
|
||
|
||
**Files:**
|
||
- Create: `outputs/presentation-spec.md`
|
||
|
||
**Content requirements:**
|
||
- Meta header — audience (mixed-stakeholder), theme (theme-factory default), truncation rules (6 bullets, ~12 words each, overflow → footer pointer)
|
||
- 18 slide entries, one per slide. Each entry specifies:
|
||
- Slide number, title, layout type
|
||
- Source file + section anchor
|
||
- Population instructions (verbatim / N-bullet summary / diagram embed / table render)
|
||
- Optional: notes on layout fallbacks if the PPTX skill can't do the requested layout
|
||
- A closing "editing this spec" section explaining that structural changes go here, not in prompts
|
||
|
||
**Verification:**
|
||
- File exists
|
||
- Has exactly 18 slide entries
|
||
- Every slide cites a specific source file (or `—` for the title slide)
|
||
- Slides 8 and 9 reference `outputs/diagrams/architecture-layers.png` and `outputs/diagrams/end-to-end-flow.png` respectively
|
||
|
||
---
|
||
|
||
## Task 3: outputs/longform-spec.md — PDF chapter/appendix structure anchor
|
||
|
||
**Files:**
|
||
- Create: `outputs/longform-spec.md`
|
||
|
||
**Content requirements:**
|
||
- Meta header — audience (anyone reading the plan standalone), theme (theme-factory default serif), page setup (Letter, 1" margins, chapter header, page+date footer)
|
||
- File-to-chapter mapping:
|
||
- Cover page (title, subtitle, as-of date, abstract from `goal-state.md` → Vision)
|
||
- TOC (auto, two levels)
|
||
- Chapter 1: `current-state.md`
|
||
- Chapter 2: `goal-state.md`
|
||
- Chapter 3: `roadmap.md`
|
||
- Appendix A: `current-state/legacy-integrations.md`
|
||
- Appendix B: `current-state/equipment-protocol-survey.md`
|
||
- Transformation rules (numbered heading, link normalization, `_TBD_` highlight, ASCII diagram preservation, table handling)
|
||
- Exclusion list (`status.md`, `CLAUDE.md`, `goal-state/digital-twin-management-brief.md`, `outputs/*`)
|
||
|
||
**Verification:**
|
||
- File exists
|
||
- Lists 3 chapters + 2 appendices in the specified order
|
||
- Transformation rules section is present and enumerated
|
||
|
||
---
|
||
|
||
## Task 4: outputs/diagrams/architecture-layers.mmd — Mermaid source for the 4-layer stack
|
||
|
||
**Files:**
|
||
- Create: `outputs/diagrams/architecture-layers.mmd`
|
||
|
||
**Content requirements:**
|
||
- Mermaid `flowchart TB` (top-to-bottom)
|
||
- Nodes: Equipment (bottom) → OtOpcUa (L2, with two namespace sub-nodes) → System Platform + Ignition (L3) → ScadaBridge (L4) → Enterprise IT (Camstar, Delmia, Snowflake, Power BI)
|
||
- A visible IT↔OT boundary line between L4 and Enterprise IT (Mermaid supports this via subgraphs or styled edges)
|
||
- Labels use the exact vocabulary from `goal-state.md` → Layered Architecture
|
||
|
||
**Verification:**
|
||
- File exists
|
||
- Starts with `flowchart TB` or equivalent directive
|
||
- Contains node labels for `Equipment`, `OtOpcUa`, `System Platform`, `Ignition`, `ScadaBridge`, and `Enterprise IT`
|
||
- Passes basic Mermaid syntax sanity check (paste into mermaid.live renders without error — verify this step on first authoring)
|
||
|
||
---
|
||
|
||
## Task 5: outputs/diagrams/end-to-end-flow.mmd — Mermaid source for the data flow
|
||
|
||
**Files:**
|
||
- Create: `outputs/diagrams/end-to-end-flow.mmd`
|
||
|
||
**Content requirements:**
|
||
- Mermaid `flowchart LR` (left-to-right)
|
||
- Nodes match `goal-state.md` line 77 exactly: Equipment → OtOpcUa → System Platform/Ignition → ScadaBridge → Redpanda → SnowBridge → Snowflake → dbt → Power BI
|
||
- IT↔OT boundary marker between ScadaBridge and Redpanda (Redpanda is IT-adjacent from ScadaBridge's central crossing)
|
||
|
||
**Verification:**
|
||
- File exists
|
||
- Starts with `flowchart LR` or equivalent
|
||
- Has exactly the 9 nodes in the exact order from `goal-state.md` line 77
|
||
- Renders at mermaid.live without error
|
||
|
||
---
|
||
|
||
## Task 6: Render diagrams to PNG (or document manual fallback)
|
||
|
||
**Files:**
|
||
- Create: `outputs/diagrams/architecture-layers.png` (if rendering available)
|
||
- Create: `outputs/diagrams/end-to-end-flow.png` (if rendering available)
|
||
|
||
**Step 1:** Attempt to render Mermaid → PNG in the Claude Code environment. Options, in order of preference:
|
||
1. `document-skills:pptx` skill may expose a diagram embed path that handles Mermaid natively
|
||
2. Python with `mermaid-py` or `mermaid-cli` if available
|
||
3. A headless browser with mermaid.js
|
||
|
||
**Step 2 (if rendering succeeds):** Write the PNGs to `outputs/diagrams/`. Verify file size > 0 and file type is PNG.
|
||
|
||
**Step 3 (if rendering fails):** Do not block. Instead:
|
||
- Create placeholder empty PNGs or skip PNG creation entirely
|
||
- Record in the run log: *"Render `outputs/diagrams/architecture-layers.mmd` and `outputs/diagrams/end-to-end-flow.mmd` at https://mermaid.live and save the PNGs to `outputs/diagrams/`. Then re-run `regenerate presentation`."*
|
||
- Note in the human-facing summary that this is the one-time manual step
|
||
|
||
**Verification:**
|
||
- Either both PNG files exist with non-zero size, OR the run log contains the explicit manual-render instruction
|
||
|
||
---
|
||
|
||
## Task 7: Update CLAUDE.md index
|
||
|
||
**Files:**
|
||
- Modify: `CLAUDE.md`
|
||
|
||
**Change:** Add `outputs/` to the component detail files list with a one-line description, so future Claude sessions see the pipeline exists when loading the project.
|
||
|
||
**Verification:**
|
||
- `CLAUDE.md` mentions `outputs/` and points to `outputs/README.md` as the regeneration entry point
|
||
|
||
---
|
||
|
||
## Task 8: Execute first PPTX generation
|
||
|
||
**Files:**
|
||
- Create: `outputs/generated/plan-presentation.pptx`
|
||
|
||
**Step 1:** Read `outputs/presentation-spec.md` (the structure anchor).
|
||
|
||
**Step 2:** Read every source file named in the spec.
|
||
|
||
**Step 3:** For each of the 18 slides, populate content per the spec's rules.
|
||
|
||
**Step 4:** Invoke `document-skills:pptx` with:
|
||
- Theme: `document-skills:theme-factory` default professional
|
||
- Title: "Shopfloor IT/OT Transformation — 3-Year Plan"
|
||
- Output path: `outputs/generated/plan-presentation.pptx`
|
||
- Diagram images from `outputs/diagrams/`
|
||
|
||
**Step 5:** Append run log entry.
|
||
|
||
**Verification:**
|
||
- `outputs/generated/plan-presentation.pptx` exists, file size > 0
|
||
- Slide count is 18 (verify by re-reading the file's structure if possible)
|
||
- Run log has a new entry with timestamp and a "presentation regenerated" note
|
||
- If any source content was truncated, a warning appears in the run log entry
|
||
|
||
---
|
||
|
||
## Task 9: Execute first PDF generation
|
||
|
||
**Files:**
|
||
- Create: `outputs/generated/plan-longform.pdf`
|
||
|
||
**Step 1:** Read `outputs/longform-spec.md`.
|
||
|
||
**Step 2:** Read all 5 source files (current-state.md, goal-state.md, roadmap.md, legacy-integrations.md, equipment-protocol-survey.md).
|
||
|
||
**Step 3:** Apply the transformation rules from the spec — numbered headings, link normalization, `_TBD_` highlighting.
|
||
|
||
**Step 4:** Invoke `document-skills:pdf` with:
|
||
- Theme: theme-factory default
|
||
- Cover page with title, subtitle, as-of date, abstract
|
||
- TOC, 3 chapters, 2 appendices
|
||
- Output path: `outputs/generated/plan-longform.pdf`
|
||
|
||
**Step 5:** Append run log entry.
|
||
|
||
**Verification:**
|
||
- `outputs/generated/plan-longform.pdf` exists, file size > 0
|
||
- Basic sanity: first page is cover, second is TOC, chapters appear in the expected order
|
||
- Run log has a new entry for the PDF generation
|
||
- Broken/unresolvable inter-file links are logged as warnings, not silently dropped
|
||
|
||
---
|
||
|
||
## Task 10: Initial run log + human-facing summary
|
||
|
||
**Files:**
|
||
- Create: `outputs/run-log.md`
|
||
|
||
**Content:**
|
||
- Header explaining the run log's purpose (append-only audit trail, one entry per regeneration, newest at bottom)
|
||
- Inaugural entry:
|
||
- Timestamp (2026-04-15)
|
||
- What ran: first PPTX + PDF generation
|
||
- Source plan version: brief summary ("plan as of 2026-04-15 — 5 source files, 3 legacy integrations, 6 protocol survey placeholder rows")
|
||
- Warnings: any truncations, missing sections, broken links, or PNG rendering fallbacks from tasks 6, 8, 9
|
||
- Next actions for the human reviewer
|
||
|
||
**Verification:**
|
||
- File exists
|
||
- Contains the inaugural entry
|
||
- If Task 6 hit the manual-render fallback, the run log surfaces that prominently
|
||
|
||
---
|
||
|
||
## Dependencies
|
||
|
||
```
|
||
Task 0 (scaffold)
|
||
├── Task 1 (README)
|
||
├── Task 2 (presentation-spec)
|
||
├── Task 3 (longform-spec)
|
||
├── Task 4 (architecture-layers.mmd)
|
||
├── Task 5 (end-to-end-flow.mmd)
|
||
└── Task 7 (CLAUDE.md index) — can run in parallel
|
||
|
||
Tasks 4, 5 → Task 6 (render PNGs)
|
||
Tasks 1, 2, 6 → Task 8 (PPTX generation)
|
||
Tasks 1, 3 → Task 9 (PDF generation)
|
||
Tasks 8, 9 → Task 10 (run log)
|
||
```
|
||
|
||
Tasks 0–5 and 7 can run in parallel where sensible; tasks 6, 8, 9, 10 are sequentially dependent.
|
||
|
||
---
|
||
|
||
## Out of scope for this plan
|
||
|
||
- A second theme / branded version of the deck (first run uses theme-factory default; branding iteration is a follow-up)
|
||
- A third diagram (roadmap-timeline) — starter set is 2, per design
|
||
- A `.claude/commands/regenerate-outputs.md` slash command — plain English trigger + README checklist is enough for first pass
|
||
- A curated long-form narrative PDF (option b from earlier brainstorm) — first run is option (a) faithful typeset only
|
||
- Editing source plan files — regeneration is read-only on plan content
|
||
- Any git operations — this repo is not a git project
|