@hegemonart/get-design-done 1.34.1 → 1.34.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +6 -3
- package/.claude-plugin/plugin.json +5 -2
- package/CHANGELOG.md +44 -0
- package/README.md +16 -0
- package/agents/design-context-builder.md +9 -5
- package/agents/design-verifier.md +8 -5
- package/agents/email-executor.md +148 -0
- package/agents/pdf-executor.md +144 -0
- package/connections/connections.md +4 -0
- package/connections/litmus.md +134 -0
- package/connections/print-renderer.md +113 -0
- package/package.json +1 -1
- package/reference/email-design.md +219 -0
- package/reference/print-design.md +223 -0
- package/reference/registry.json +14 -0
- package/scripts/lib/email/validate-email-html.cjs +157 -0
- package/scripts/lib/print/validate-print-css.cjs +155 -0
|
@@ -5,14 +5,14 @@
|
|
|
5
5
|
},
|
|
6
6
|
"metadata": {
|
|
7
7
|
"description": "Get Design Done — 5-stage agent-orchestrated design pipeline with 9 connections, handoff-first workflow, bidirectional Figma write-back, 22+ specialized agents, queryable knowledge layer (intel store, dependency analysis, learnings extraction), and a self-improvement loop (reflector, frontmatter + budget feedback, global-skills layer). v1.20.0 ships the SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream, and resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) for rate-limit + 429 + context-overflow recovery. Full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
|
|
8
|
-
"version": "1.34.
|
|
8
|
+
"version": "1.34.3"
|
|
9
9
|
},
|
|
10
10
|
"plugins": [
|
|
11
11
|
{
|
|
12
12
|
"name": "get-design-done",
|
|
13
13
|
"source": "./",
|
|
14
14
|
"description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), Claude Design handoff, bidirectional Figma write-back, and a queryable intel store (.design/intel/) for dependency and learnings queries. Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation. Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain.",
|
|
15
|
-
"version": "1.34.
|
|
15
|
+
"version": "1.34.3",
|
|
16
16
|
"author": {
|
|
17
17
|
"name": "hegemonart"
|
|
18
18
|
},
|
|
@@ -74,7 +74,10 @@
|
|
|
74
74
|
"design-system-sync",
|
|
75
75
|
"swift",
|
|
76
76
|
"compose",
|
|
77
|
-
"flutter"
|
|
77
|
+
"flutter",
|
|
78
|
+
"email",
|
|
79
|
+
"print",
|
|
80
|
+
"pdf"
|
|
78
81
|
]
|
|
79
82
|
}
|
|
80
83
|
]
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "get-design-done",
|
|
3
3
|
"short_name": "gdd",
|
|
4
|
-
"version": "1.34.
|
|
4
|
+
"version": "1.34.3",
|
|
5
5
|
"description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain. v1.27.7 ships gdd-mcp (Phase 27.7): 12 read-only MCP tools for sub-3s priming. v1.28.0 (Phase 28): Foundational References Tier 2 — 5 new reference files (color-theory, composition, proportion-systems, i18n, contrast-advanced), 2 verifier i18n probes + 1 explore i18n-readiness probe, 12 additive cross-link insertions across 10 existing references, 2 orthogonal audit-scoring lens-tags (composition_alignment + i18n_readiness).",
|
|
6
6
|
"author": {
|
|
7
7
|
"name": "hegemonart",
|
|
@@ -68,7 +68,10 @@
|
|
|
68
68
|
"design-system-sync",
|
|
69
69
|
"swift",
|
|
70
70
|
"compose",
|
|
71
|
-
"flutter"
|
|
71
|
+
"flutter",
|
|
72
|
+
"email",
|
|
73
|
+
"print",
|
|
74
|
+
"pdf"
|
|
72
75
|
],
|
|
73
76
|
"skills": [
|
|
74
77
|
"./skills/"
|
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,50 @@ All notable changes to get-design-done are documented here. Versions follow [sem
|
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
+
## [1.34.3] - 2026-05-31
|
|
8
|
+
|
|
9
|
+
### Phase 34.3 — Non-Web Output Layer: Print/PDF
|
|
10
|
+
|
|
11
|
+
Third and **FINAL** sub-phase of the split Phase 34 (Non-Web Output Layer) — **completing it completes the parent Phase 34** (native 34.1 + email 34.2 + print 34.3 all shipped). Adds **print/PDF output** — a dedicated executor that generates print-ready HTML/CSS honoring the real production constraints (`@page` box model, bleed + crop marks, CMYK color-space awareness, font embedding, 300dpi raster fallback) that screen-RGB web HTML ignores — behind the same project-type detector that routes native (34.1) and email (34.2). Print generation is **opt-in via project-type detection — web remains the default**. A decimal release on the v1.34.x arc (CHANGELOG-only, D-01); **no new runtime dependency** — the executor generates the print HTML/CSS as an agent-prompt and the plugin checks it with a deterministic static validator, no `pdfkit`/`paged`/`puppeteer`/`playwright` runtime (D-02/D-10). Print is the final Phase-34 output type — the project-type seam is now **closed**. 4 plans across Waves A–C.
|
|
12
|
+
|
|
13
|
+
### Added
|
|
14
|
+
|
|
15
|
+
- **Print-constraint catalogue + static validator (no `pdfkit`/`paged` dependency, D-02/D-03).** `reference/print-design.md` — the authoritative print-constraint catalogue (`@page` size/margin/marks — the print box model, bleed box + crop/registration marks, CMYK color-space awareness, font embedding/outlining, 300dpi raster fallback, and the on-press guidance the render-test verifies), registered in `reference/registry.json`. `scripts/lib/print/validate-print-css.cjs` — a pure, deterministic static checker (zero `require`, no fs/network/pdfkit/paged) that flags the statically-verifiable subset: `PR-PAGE-01` (an `@page` rule present), `PR-BLEED-01` (a bleed box / crop-marks signal), `PR-CMYK-01` (a CMYK-awareness signal), `PR-FONT-01` (a font-embed signal), `PR-DPI-01` (a 300dpi raster-fallback signal) — returning `{ ok, violations:[{ rule, detail }] }`.
|
|
16
|
+
- **`pdf-executor` agent (Paged.js-compatible HTML/CSS + PDFKit fallback, D-02/D-04).** `agents/pdf-executor.md` — generates **print-ready output per task**: Paged.js-compatible print HTML/CSS (`@page` size/margin/marks, bleed, CMYK-aware color notes, font embedding, 300dpi raster fallback) against the `reference/print-design.md` catalogue, with PDFKit-fallback notes for Chrome-less runtimes, run through the static validator as its own self-check. It is an agent-prompt (like `design-executor`/`email-executor`), **not** a compiler — no running headless Chrome, no PDFKit, no network is required to produce the print HTML/CSS. Carries a `## Record` section from the start (the record-contract lesson) and an honest `size_budget`.
|
|
17
|
+
- **`print-renderer` connection (optional render-test, degrade-to-static-validator, D-03).** `connections/print-renderer.md` — Paged.js-via-headless-Chrome (or PDFKit on Chrome-less runtimes) rendered PDF/page evidence for the verify stage when present, mirroring `connections/preview.md`. **Never hard-required**: when absent the verify stage degrades to the static print-CSS validator / code-only structural audit. Added to the `connections/connections.md` index + Capability Matrix in this closeout.
|
|
18
|
+
- **`design-context-builder` `print` project-type route (seam CLOSED) + `design-verifier` consolidated non-web verify (D-06/D-07).** The context-builder appends the `print` enum + the `pdf-executor` route at the 34.1/34.2 seam and **closes the seam** — print is the final Phase-34 output type. The verifier gains the print-verify branch by **consolidating** the native + email + print non-web verify branches into ONE delegated "Non-Web Verify" section (routing by `<project_type>` to native-platforms.md / email-design.md / print-design.md + the matching validator) — a net line-reduction that keeps the verifier within its ≤700-line budget.
|
|
19
|
+
- **Regression baseline.** `test/fixtures/baselines/phase-34-3/` freezes the print surface — a valid print fixture (`print-good.css`), a validator golden (`validator-golden.json`, the recorded `validatePrintCss` output for a passing + a failing fixture, proving the rule-output shape is frozen), and `manifests-version.txt`=1.34.3 — pinned by `test/suite/phase-34-3-baseline.test.cjs` so a future change cannot silently break the validator or its verdict shape.
|
|
20
|
+
|
|
21
|
+
### Notes
|
|
22
|
+
|
|
23
|
+
- All Phase 34.3 tests are hermetic (D-10): the static print-CSS validator is a pure string→verdict function (fixture CSS → constraint checks, no network/headless-Chrome/PDFKit), the pdf-executor is validated **structurally** (frontmatter + catalogue reference + validator reference + presence), and the default `npm test` invokes **no** headless Chrome / PDFKit and pulls in **no** `pdfkit`/`paged`/`puppeteer`/`playwright` runtime. Rendered PDF/page verification is the opt-in degraded-mode path (D-03).
|
|
24
|
+
- The 31.5 tarball golden (`test/fixtures/baselines/phase-31-5/tarball-manifest.txt`) was regenerated as a reviewed delta: **+4** newly-shipped files (`agents/pdf-executor.md`, `connections/print-renderer.md`, `reference/print-design.md`, `scripts/lib/print/validate-print-css.cjs`), zero removals. Tests are not shipped.
|
|
25
|
+
- 6-manifest lockstep at **v1.34.3** (`package.json` + `package-lock.json` (root + `packages.""`) + `.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json` (metadata.version + plugins[0].version) + `.cursor-plugin/plugin.json` + `.codex-plugin/plugin.json`); marketplace `plugins[0].keywords` + plugin keywords gain `print`/`pdf`. Version-sync hygiene done upfront (D-09): `OFF_CADENCE_VERSIONS.add('1.34.3')` + the 17 live-pinned `manifests-version.txt` baselines forward-propagated 1.34.2 → 1.34.3 (phase-34-2, the prior closeout's own baseline, joined the set). **This completes the parent Phase 34 (Non-Web Output Layer — native + email + print).**
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## [1.34.2] - 2026-05-31
|
|
30
|
+
|
|
31
|
+
### Phase 34.2 — Non-Web Output Layer: Email
|
|
32
|
+
|
|
33
|
+
Second sub-phase of the split Phase 34 (Non-Web Output Layer). Adds **email-template output** — a dedicated executor that generates email honoring the real client constraints (table-based layout, inline styles, MSO conditional comments for Outlook's Word engine, dark-mode `color-scheme` handling, and the top-20-client quirks) that modern web HTML/CSS breaks on — behind the same project-type detector that routes native (34.1). Email generation is **opt-in via project-type detection — web remains the default**. A decimal release on the v1.34.x arc (CHANGELOG-only, D-01); **no new runtime dependency** — the executor generates the email as an agent-prompt and the plugin checks it with a deterministic static validator, no `mjml` runtime (D-02/D-10). Native (Phase 34.1) shipped; Print/PDF (Phase 34.3) is the next sub-phase, out of 34.2 (D-07). 4 plans across Waves A–C.
|
|
34
|
+
|
|
35
|
+
### Added
|
|
36
|
+
|
|
37
|
+
- **Email-constraint catalogue + static validator (no `mjml` dependency, D-02/D-03).** `reference/email-design.md` — the authoritative email-constraint catalogue (~30 catalogued constraints: table-based layout, inline styles, MSO conditional comments, dark-mode `color-scheme`, ~600px width, image/alt rules, and the top-20-client quirks), registered in `reference/registry.json`. `scripts/lib/email/validate-email-html.cjs` — a pure, deterministic static checker (zero `require`, no fs/network/mjml) that flags the statically-verifiable subset: `EM-LAYOUT-01` (no flexbox/grid/`position`), `EM-STYLE-01` (no `<style>` as the primary styling mechanism; a small `@media`-only block is tolerated), `EM-MSO-01` (an MSO conditional comment in a full email), `EM-DARK-01` (a `color-scheme` signal present) — returning `{ ok, violations:[{ rule, detail }] }`.
|
|
38
|
+
- **`email-executor` agent (MJML canonical + derived HTML, D-02/D-04).** `agents/email-executor.md` — generates **one email template per task**: an MJML source (the canonical artifact) plus the equivalent derived HTML, generated against the `reference/email-design.md` catalogue and run through the static validator as its own self-check. It is an agent-prompt (like `design-executor`/`flutter-executor`), **not** a compiler — no running `mjml`, no Litmus account, no network is required to produce the email. Carries a `## Record` section from the start (the record-contract lesson) and an honest `size_budget`.
|
|
39
|
+
- **`litmus` connection (optional render-test, degrade-to-static-validator, D-03).** `connections/litmus.md` — cross-client rendered screenshots (Email-on-Acid is the documented alternative) for the verify stage when present, mirroring `connections/chromatic.md`. **Never hard-required**: when absent the verify stage degrades to the static email-HTML validator / code-only structural audit. Added to the `connections/connections.md` index + Capability Matrix in this closeout.
|
|
40
|
+
- **`design-context-builder` `email` project-type route + `design-verifier` email-verify branch (delegated, D-06/D-09).** The context-builder appends the `email` enum + the `email-executor` route at the 34.1 seam (the seam is left open for 34.3/print). The verifier gains an email-verify branch by **delegation** to `reference/email-design.md` (the verifier stayed within its ≤700-line budget).
|
|
41
|
+
- **Regression baseline.** `test/fixtures/baselines/phase-34-2/` freezes the email surface — a valid email fixture (`email-good.html`), a validator golden (`validator-golden.json`, the recorded `validateEmailHtml` output for a passing + a failing fixture, proving the rule-output shape is frozen), and `manifests-version.txt`=1.34.2 — pinned by `test/suite/phase-34-2-baseline.test.cjs` so a future change cannot silently break the validator or its verdict shape.
|
|
42
|
+
|
|
43
|
+
### Notes
|
|
44
|
+
|
|
45
|
+
- All Phase 34.2 tests are hermetic (D-10): the static email-HTML validator is a pure string→verdict function (fixture HTML → constraint checks, no network/mjml), the email-executor is validated **structurally** (frontmatter + catalogue reference + validator reference + presence), and the default `npm test` invokes **no** Litmus/Email-on-Acid and pulls in **no** `mjml` runtime. Rendered cross-client verification is the opt-in degraded-mode path (D-03).
|
|
46
|
+
- The 31.5 tarball golden (`test/fixtures/baselines/phase-31-5/tarball-manifest.txt`) was regenerated as a reviewed delta: **+2** newly-shipped files (`agents/email-executor.md`, `connections/litmus.md`), zero removals (641 paths). The other two new email files (`reference/email-design.md`, `scripts/lib/email/validate-email-html.cjs`) were already in the golden from their Wave-A (34.2-01) commit — so the four new shipped files net to a +2 line-delta on the golden.
|
|
47
|
+
- 6-manifest lockstep at **v1.34.2** (`package.json` + `package-lock.json` (root + `packages.""`) + `.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json` (metadata.version + plugins[0].version) + `.cursor-plugin/plugin.json` + `.codex-plugin/plugin.json`); marketplace `plugins[0].keywords` + plugin keywords gain `email`. Version-sync hygiene done upfront (D-08): `OFF_CADENCE_VERSIONS.add('1.34.2')` + the 16 live-pinned `manifests-version.txt` baselines forward-propagated 1.34.1 → 1.34.2 (phase-34-1, the prior closeout's own baseline, joined the set).
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
7
51
|
## [1.34.1] - 2026-05-31
|
|
8
52
|
|
|
9
53
|
### Phase 34.1 — Non-Web Output Layer: Native Mobile
|
package/README.md
CHANGED
|
@@ -114,6 +114,22 @@ GDD now generates **native mobile** UI, not just web. A project-type detector ro
|
|
|
114
114
|
|
|
115
115
|
All three are fed by a shared **token-bridge** ([`reference/native-platforms.md`](reference/native-platforms.md)) that extends the Phase-23 token engine with `swift`/`compose`/`flutter` emitters — mapping your canonical tokens (`#3B82F6`, `16px`, `Inter`) deterministically onto each platform's theme primitives (`Color`/`Font`, `MaterialTheme`, `ThemeData`) with a documented, round-trippable precision contract, so the executors never hand-author colour or dimension math. Rendered verification via the iOS Simulator / Android emulator is **optional** — when no simulator is present the verify stage degrades to a code-only structural audit (the simulator only *adds* rendered confirmation).
|
|
116
116
|
|
|
117
|
+
### Email output (v1.34.2)
|
|
118
|
+
|
|
119
|
+
GDD also generates **email templates** — the project-type detector routes an `email` brief to a dedicated executor that honors the real client constraints web HTML/CSS breaks on:
|
|
120
|
+
|
|
121
|
+
- **[`email-executor`](agents/email-executor.md)** — generates one email per task as **MJML source (canonical) + the derived HTML**, against the constraint catalogue, with the static validator as its own self-check. It is an agent-prompt, not a compiler — **no `mjml` runtime, no Litmus account, no network** is needed to produce the email.
|
|
122
|
+
|
|
123
|
+
The constraints live in [`reference/email-design.md`](reference/email-design.md) — table-based layout (no flexbox/grid/`position`), inline styles (no `<style>` sheet in Gmail), MSO conditional comments for Outlook's Word engine, dark-mode `color-scheme` handling, ~600px width, and the top-20-client quirks. A deterministic static checker ([`scripts/lib/email/validate-email-html.cjs`](scripts/lib/email/validate-email-html.cjs)) flags the statically-verifiable subset (`EM-LAYOUT`/`EM-STYLE`/`EM-MSO`/`EM-DARK`). Cross-client rendered verification via [`Litmus`](connections/litmus.md) (or Email-on-Acid) is **optional** — when absent the verify stage degrades to the static validator. Email generation is opt-in; **web stays the default**.
|
|
124
|
+
|
|
125
|
+
### Print/PDF output (v1.34.3)
|
|
126
|
+
|
|
127
|
+
GDD also generates **print/PDF** output — the project-type detector routes a `print` brief to a dedicated executor that honors the production constraints screen-RGB web HTML ignores. This **completes the Non-Web Output Layer** (native + email + print all shipped):
|
|
128
|
+
|
|
129
|
+
- **[`pdf-executor`](agents/pdf-executor.md)** — generates **Paged.js-compatible print HTML/CSS** (with PDFKit-fallback notes for Chrome-less runtimes) against the constraint catalogue, with the static validator as its own self-check. It is an agent-prompt, not a compiler — **no headless Chrome, no PDFKit, no network** is needed to produce the print HTML/CSS.
|
|
130
|
+
|
|
131
|
+
The constraints live in [`reference/print-design.md`](reference/print-design.md) — the `@page` box model (size/margin/marks), bleed box + crop/registration marks, CMYK color-space awareness (print is subtractive CMYK, not screen RGB), font embedding/outlining (print RIPs have no web fonts), and a 300dpi raster fallback. A deterministic static checker ([`scripts/lib/print/validate-print-css.cjs`](scripts/lib/print/validate-print-css.cjs)) flags the statically-verifiable subset (`PR-PAGE`/`PR-BLEED`/`PR-CMYK`/`PR-FONT`/`PR-DPI`). Rendered PDF/page verification via the optional [`print-renderer`](connections/print-renderer.md) connection (Paged.js/headless-Chrome or PDFKit) is **optional** — when absent the verify stage degrades to the static validator. Print generation is opt-in; **web stays the default**.
|
|
132
|
+
|
|
117
133
|
### Previous releases
|
|
118
134
|
|
|
119
135
|
- **v1.26.0** — Headless Model Resolver (per-runtime tier→model map, `resolved_models` router field, per-runtime price tables, `reasoning-class` runtime-neutral alias).
|
|
@@ -218,18 +218,20 @@ Proceed to Step 0E regardless of whether Step 0D ran or was skipped.
|
|
|
218
218
|
|
|
219
219
|
Detect the **project type** so the pipeline routes the brief to the correct executor. Reuse the Step 0C / Step 1 grep/glob idiom (file reads only, < 1 second, no skip condition).
|
|
220
220
|
|
|
221
|
-
**Enum (
|
|
221
|
+
**Enum (6 values — D-06, the full set):** `web` (DEFAULT) · `native-ios` · `native-android` · `flutter` · `email` · `print`.
|
|
222
222
|
|
|
223
|
-
**Detection signals + precedence** (first match wins; brief overrides — if the user explicitly says "iOS app" / "Android app" / "Flutter app", honor that):
|
|
223
|
+
**Detection signals + precedence** (first match wins; brief overrides — if the user explicitly says "iOS app" / "Android app" / "Flutter app" / "email" / "newsletter" / "email template" / "print" / "PDF" / "print-ready" / "brochure" / "flyer" / "poster", honor that):
|
|
224
224
|
|
|
225
225
|
```bash
|
|
226
226
|
ls pubspec.yaml 2>/dev/null # → flutter
|
|
227
227
|
ls *.xcodeproj Package.swift 2>/dev/null # → native-ios (when no pubspec)
|
|
228
228
|
ls build.gradle build.gradle.kts settings.gradle 2>/dev/null # → native-android (when no pubspec)
|
|
229
|
+
ls **/*.mjml email/ emails/ templates/email 2>/dev/null # → email (email-template signals)
|
|
230
|
+
ls **/*.print.css print/ templates/print 2>/dev/null # → print (print-output signals: a print stylesheet / print-template dir)
|
|
229
231
|
ls package.json 2>/dev/null # → web (default; also the fallback when none match)
|
|
230
232
|
```
|
|
231
233
|
|
|
232
|
-
Precedence: `pubspec.yaml` (flutter) > `*.xcodeproj`/`Package.swift` (native-ios) > `build.gradle*`/`settings.gradle` (native-android) > `package.json` / none (web — DEFAULT).
|
|
234
|
+
Precedence: an explicit brief override (the user says "email" / "newsletter" / "email template", or "print" / "PDF" / "print-ready" / "brochure" / "flyer" / "poster") wins like the other brief-overrides; otherwise `pubspec.yaml` (flutter) > `*.xcodeproj`/`Package.swift` (native-ios) > `build.gradle*`/`settings.gradle` (native-android) > `.mjml` files / an `email/` templates directory (email) > a print stylesheet (`*.print.css`) / a `print/` templates directory (print) > `package.json` / none (web — DEFAULT).
|
|
233
235
|
|
|
234
236
|
**Routing table** (project type → executor — one row per type, trivially appendable):
|
|
235
237
|
|
|
@@ -239,10 +241,12 @@ Precedence: `pubspec.yaml` (flutter) > `*.xcodeproj`/`Package.swift` (native-ios
|
|
|
239
241
|
| native-ios | swift-executor |
|
|
240
242
|
| native-android | compose-executor |
|
|
241
243
|
| flutter | flutter-executor |
|
|
244
|
+
| email | email-executor |
|
|
245
|
+
| print | pdf-executor |
|
|
242
246
|
|
|
243
|
-
<!-- 34.
|
|
247
|
+
<!-- Phase 34 output types complete: native (34.1: native-ios/native-android/flutter) + email (34.2) + print (34.3). Print is the FINAL Phase-34 output type — no further Phase-34 output types; the enum + routing table above are the full set. (34.1/34.2 kept this seam OPEN for the next type; 34.3 ties it off.) -->
|
|
244
248
|
|
|
245
|
-
Record the detected type in DESIGN-CONTEXT.md as a `<project_type>` line (e.g. `<project_type>native-ios</project_type>`) so downstream stages route correctly. The native specifics (token→theme bridge) live in `reference/native-platforms.md` — do not inline them here.
|
|
249
|
+
Record the detected type in DESIGN-CONTEXT.md as a `<project_type>` line (e.g. `<project_type>native-ios</project_type>`) so downstream stages route correctly. The native specifics (token→theme bridge) live in `reference/native-platforms.md`; the email specifics (table layout, inline styles, MSO/dark-mode constraints) live in `reference/email-design.md`; the print specifics (the `@page` box model, bleed/crop marks, CMYK awareness, font embedding, 300dpi raster) live in `reference/print-design.md` — do not inline any of them here.
|
|
246
250
|
|
|
247
251
|
Proceed to Step 1 regardless of outcome.
|
|
248
252
|
|
|
@@ -354,14 +354,17 @@ In DESIGN-VERIFICATION.md, add a `## Phase 4B — Screenshot Evidence` section l
|
|
|
354
354
|
|
|
355
355
|
---
|
|
356
356
|
|
|
357
|
-
## Phase 4D —
|
|
357
|
+
## Phase 4D — Non-Web Verify (no-DOM targets)
|
|
358
358
|
|
|
359
|
-
When `<project_type>`
|
|
359
|
+
When `<project_type>` is a **no-DOM target** — `native-ios`/`native-android`/`flutter`, `email`, or `print` — the Phase-1 web DOM grep + the Phase-4B Preview loop do not apply as-is. Route by `<project_type>` to the matching constraint/structural audit **by delegation** (the per-type rules live in the reference, never inlined here), with the optional render-connection as a degrade-able enhancement — the Phase-4B precedent:
|
|
360
360
|
|
|
361
|
-
|
|
362
|
-
|
|
361
|
+
| `<project_type>` | reference (authority) + static audit | optional render-connection (degrade if absent) |
|
|
362
|
+
|---|---|---|
|
|
363
|
+
| `native-ios` / `native-android` / `flutter` | `reference/native-platforms.md` — **code-only structural audit**: expected SwiftUI views / Compose composables / Flutter widgets present + token-bridge usage (a snapshot audit when a screenshot is supplied) | `xcode-simulator` / `android-emulator` / Preview (Flutter-web) → degrade to the code-only structural audit |
|
|
364
|
+
| `email` | `reference/email-design.md` + `scripts/lib/email/validate-email-html.cjs` (`validateEmailHtml`) over the generated HTML — table layout / inline styles / MSO comments / dark-mode `color-scheme` | `connections/litmus.md` cross-client screenshots → degrade to the static validator / code-only |
|
|
365
|
+
| `print` | `reference/print-design.md` + `scripts/lib/print/validate-print-css.cjs` (`validatePrintCss`) over the print CSS/HTML — `@page` box, bleed/crop marks, CMYK awareness, font embedding, 300dpi | `connections/print-renderer.md` (Paged.js-headless / PDFKit render) → degrade to the static validator / code-only |
|
|
363
366
|
|
|
364
|
-
|
|
367
|
+
**Degrade posture (D-03, the Phase-4B precedent — applies to every row):** the render-connection (simulator/emulator/Litmus/print-render) is an **enhancement, NEVER hard-required**. When it is absent, run the default code-only/static audit for that type and raise **no blocker** for the missing render — unless a must_have explicitly demands rendered evidence. Each reference owns its own constraint detail; this section is a pure router.
|
|
365
368
|
|
|
366
369
|
---
|
|
367
370
|
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: email-executor
|
|
3
|
+
description: Executes one plan task by generating an email template — MJML source (canonical) + the derived HTML — honoring reference/email-design.md constraints, validated by the static email-HTML checker. Single-shot; mirrors design-executor.
|
|
4
|
+
tools: Read, Write, Edit, Bash, Grep, Glob
|
|
5
|
+
color: magenta
|
|
6
|
+
default-tier: sonnet
|
|
7
|
+
tier-rationale: "Follows an Opus-authored plan; executes email codegen rather than plans it"
|
|
8
|
+
size_budget: M
|
|
9
|
+
size_budget_rationale: "Honest tier sized to the actual ~148-line body (M cap 300), NOT inflated to the design-family XXL default. Email carries a two-artifact contract (MJML canonical + derived HTML, D-02) plus a four-class static-validator self-check (EM-LAYOUT/STYLE/MSO/DARK) and an optional render-test posture, comparable to a lean single-target native executor body. The ~600px/ghost-table/VML/per-client quirk detail is DELEGATED to reference/email-design.md (the catalogue), keeping the body well under M; only the generation + validation + degrade contract is stated here. Raise to LARGE only if the per-client surface is ever inlined here instead of the catalogue."
|
|
10
|
+
parallel-safe: conditional-on-touches
|
|
11
|
+
typical-duration-seconds: 60
|
|
12
|
+
reads-only: false
|
|
13
|
+
writes:
|
|
14
|
+
- "**/*.mjml"
|
|
15
|
+
- "**/*.html"
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
@reference/shared-preamble.md
|
|
19
|
+
|
|
20
|
+
# email-executor
|
|
21
|
+
|
|
22
|
+
## Role
|
|
23
|
+
|
|
24
|
+
You execute **exactly one task** from the plan: you generate **one email template** — an **MJML source** file (the canonical artifact) and the **equivalent derived HTML** — honoring the email-client constraints. Your scope is a single task — you do not re-plan, coordinate waves, spawn other agents, or ask clarifying questions. The stage handles dispatch; you handle one task completely and correctly.
|
|
25
|
+
|
|
26
|
+
You are a single-shot agent: receive context, read the references, generate the MJML + HTML, write the file(s), run the static validator, commit, emit the completion marker, done.
|
|
27
|
+
|
|
28
|
+
You are an **agent-prompt**, not a compiler (D-04): GDD generates the email when an LLM (you) invokes this prompt, consistent with `design-executor.md` / `flutter-executor.md`. You do **not** require a running `mjml` compiler, a Litmus account, or any network to produce the email — rendered cross-client verification is the verify stage's degraded-mode concern, never a precondition here (D-03/D-10).
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## Required Reading
|
|
33
|
+
|
|
34
|
+
Read every file the stage lists in its `<required_reading>` block before taking any action. At minimum:
|
|
35
|
+
|
|
36
|
+
- `.design/STATE.md` — pipeline state (decisions, blockers, must-haves)
|
|
37
|
+
- `.design/DESIGN-PLAN.md` — your task is identified by `task_id`
|
|
38
|
+
- `.design/DESIGN-CONTEXT.md` — brand decisions, constraints, locked choices
|
|
39
|
+
- **`reference/email-design.md`** — the **authoritative** email-constraint catalogue: table-based layout (no flexbox/grid/`position`), inline styles (no `<style>` sheet), MSO conditional comments for Outlook's Word engine, dark-mode `color-scheme`, ~600px max-width, image/alt rules, and the top-20-client quirks. This is how you pick the correct email idiom — you **generate against the catalogue**, you do **not** re-derive these rules (the `flutter-executor`→`reference/native-platforms.md` precedent).
|
|
40
|
+
|
|
41
|
+
**Invariant:** read all listed files FIRST, before making any changes.
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## MJML canonical + HTML derived (the D-02 two-artifact contract)
|
|
46
|
+
|
|
47
|
+
Per **D-02** the executor emits **two artifacts**, and **you (the LLM) perform the MJML→HTML expansion as your contract** — there is **NO `mjml` build step / runtime dependency** (an opt-in real `mjml` compile is out of scope, like the simulator connections):
|
|
48
|
+
|
|
49
|
+
| Artifact | Role | Notes |
|
|
50
|
+
| --- | --- | --- |
|
|
51
|
+
| **`*.mjml`** | **CANONICAL** — the source of truth | Semantic MJML the maintainer edits |
|
|
52
|
+
| **`*.html`** | **DERIVED** — generated by you from the MJML | The shippable email; what the static validator checks |
|
|
53
|
+
|
|
54
|
+
- Emit **both**: write the MJML source, then write the equivalent table-based HTML you expand from it (inline styles, ghost tables, MSO comments, color-scheme — per the catalogue).
|
|
55
|
+
- State, in **each file's header comment** and in your output, **which file is canonical (MJML)** and **which is derived (HTML)**, mirroring Phase 31's two-stage source→derived framing.
|
|
56
|
+
- Do **not** add `mjml` to `package.json` or shell out to an `mjml` binary — the expansion is your job.
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## Token Consumption — the canonical token form
|
|
61
|
+
|
|
62
|
+
Where the task themes the email (colors, spacing, type), consume the **canonical design tokens** (the css-vars token form) for those values rather than inventing ad-hoc hex/px — consistent with the design-family executors. Email cannot use CSS custom properties reliably across clients, so **resolve** the token values to literals **inline** at generation time (the token is the source; the email carries the resolved value). Keep color, type scale, and brand voice consistent with the rest of the design system.
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## Self-check via the static validator (the deterministic gate)
|
|
67
|
+
|
|
68
|
+
Before completing, **run the static email-HTML validator** on your **derived HTML**:
|
|
69
|
+
|
|
70
|
+
```js
|
|
71
|
+
const { validateEmailHtml } = require('scripts/lib/email/validate-email-html.cjs');
|
|
72
|
+
const { ok, violations } = validateEmailHtml(htmlString);
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
`validateEmailHtml` (Phase 34.2-01) deterministically checks the four statically-verifiable constraint classes — **EM-LAYOUT-01** (no flexbox/grid/`position`), **EM-STYLE-01** (no `<style>` block as the primary styling mechanism), **EM-MSO-01** (an MSO conditional comment in a full email), **EM-DARK-01** (a `color-scheme` signal present). **Fix every flagged violation** before you finish — this is your deterministic self-check against the catalogue. The remaining catalogue rules (~600px width, ghost tables/VML, image width/height/alt, per-client quirks) are render-tested guidance, not statically asserted — honor them from the catalogue.
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## Optional Litmus render-test (degraded / not a precondition)
|
|
80
|
+
|
|
81
|
+
Code generation needs **no** render service (D-04/D-10). Cross-client **rendered** verification is the **verify stage's** degraded-mode concern (D-03): point it at the `connections/litmus.md` render-test connection **as an enhancement**, **never** a precondition.
|
|
82
|
+
|
|
83
|
+
- When **Litmus** (or **Email-on-Acid**, the documented alternative) is available → the verify stage captures cross-client screenshots.
|
|
84
|
+
- When **absent** → verification **degrades** to the static validator above, then a code-only structural audit. Never hard-require Litmus.
|
|
85
|
+
|
|
86
|
+
Email ships its render-test connection at `connections/litmus.md`; you only **name** it — you never run it to generate.
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## Execution Principles
|
|
91
|
+
|
|
92
|
+
1. **Honor DESIGN-CONTEXT.md decisions as locked.** `D-XX:` decisions are non-negotiable.
|
|
93
|
+
2. **`reference/email-design.md` is authoritative** for the email constraints. Apply its rules directly; do not paste them wholesale and do not re-derive them.
|
|
94
|
+
3. **Observable outcomes only.** Acceptance criteria describe observable states ("the HTML uses `role="presentation"` tables", "an MSO conditional comment is present", "validateEmailHtml returns `ok: true`").
|
|
95
|
+
4. **Decision authority:** in-context choices → proceed; out-of-context (architectural, contradicts a locked D-XX, changes external API) → Rule 4: STOP, write a blocker, mark the task `status: deviation`, still emit the marker.
|
|
96
|
+
5. **Single-task scope.** Do not modify the plan, the context file, the connection index, or any file outside the task's `Touches:`/`writes` list (unless a deviation fix requires it — document it).
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
## Deviation Rules
|
|
101
|
+
|
|
102
|
+
Apply automatically; track each in the task output `## Deviations` section.
|
|
103
|
+
|
|
104
|
+
- **Rule 1 — Bug:** broken HTML/MJML, a flagged `validateEmailHtml` violation, wrong token resolution in files you author → fix inline.
|
|
105
|
+
- **Rule 2 — Missing Critical:** missing MSO comment, missing `color-scheme` signal, a flexbox/grid/`position` style, a missing `alt`/`width`/`height` on an `<img>` → add it (the catalogue requires it).
|
|
106
|
+
- **Rule 3 — Blocking:** a referenced file/import missing, the validator not resolvable → fix (resolve import, create stub) and note it.
|
|
107
|
+
- **Rule 4 — Architectural:** switching the email framework, restructuring the template system, a schema-level change, or anything contradicting a locked D-XX → STOP, write a `<blocker>`, mark `status: deviation`, still emit the marker.
|
|
108
|
+
|
|
109
|
+
**Scope boundary:** only fix issues directly caused by this task's changes. **Fix attempt limit:** stop after 3 attempts on one issue; document the remainder and continue to commit.
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
## Output
|
|
114
|
+
|
|
115
|
+
Emit the **MJML source** + the **derived HTML** to the path(s) the task declares. In your final response, state: the file(s) written, **which is canonical (MJML)** and **which is derived (HTML)**, how tokens were resolved, and the `validateEmailHtml` result (`ok: true` / the violations you fixed). Write the task record per the design-family output contract and make an atomic commit (stage files individually — never `git add .`/`-A`; never run `git clean`).
|
|
116
|
+
|
|
117
|
+
Terminate with exactly this line, on its own line:
|
|
118
|
+
|
|
119
|
+
```
|
|
120
|
+
## EXECUTION COMPLETE
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## Constraints
|
|
126
|
+
|
|
127
|
+
This agent MUST NOT:
|
|
128
|
+
|
|
129
|
+
- Run `git clean` (any flags) — absolute prohibition.
|
|
130
|
+
- Require a running `mjml` compiler, a Litmus/Email-on-Acid account, or any network to generate the email (D-04/D-10).
|
|
131
|
+
- Add a `mjml` dependency to `package.json` or shell out to an `mjml` binary — the MJML→HTML expansion is the agent's contract (D-02).
|
|
132
|
+
- Re-derive the email constraints — consume `reference/email-design.md` (the catalogue).
|
|
133
|
+
- Emit only HTML or only MJML — both artifacts are the contract (MJML canonical, HTML derived).
|
|
134
|
+
- Create or edit the connection index, or modify the plan or context file, re-plan, spawn other agents, ask clarifying questions, or `git add .`/`-A`.
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
## Record
|
|
139
|
+
|
|
140
|
+
At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
|
|
141
|
+
|
|
142
|
+
```json
|
|
143
|
+
{"ts":"<ISO-8601>","agent":"email-executor","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<which email template (MJML+HTML) was generated + the validateEmailHtml result>","artifacts_written":["<files written>"]}
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Schema: `reference/schemas/insight-line.schema.json`.
|
|
147
|
+
|
|
148
|
+
## EXECUTION COMPLETE
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pdf-executor
|
|
3
|
+
description: Executes one plan task by generating print-ready output — Paged.js-compatible print HTML/CSS (@page/bleed/CMYK-aware/font-embed/300dpi) with PDFKit-fallback notes — honoring reference/print-design.md constraints, validated by the static print-CSS checker. Single-shot; mirrors design-executor.
|
|
4
|
+
tools: Read, Write, Edit, Bash, Grep, Glob
|
|
5
|
+
color: pink
|
|
6
|
+
default-tier: sonnet
|
|
7
|
+
tier-rationale: "Follows an Opus-authored plan; executes print codegen rather than plans it"
|
|
8
|
+
size_budget: M
|
|
9
|
+
size_budget_rationale: "Honest tier sized to the actual ~150-line body (M cap 300), NOT inflated to the design-family XXL default. Print carries a single-artifact generation contract (Paged.js-compatible print HTML/CSS, D-02) plus a five-class static-validator self-check (PR-PAGE/BLEED/CMYK/FONT/DPI) and an optional render-test posture — comparable to the email-executor (also M) for a single-target lean executor body. The @page box model, 3mm-bleed/crop-mark, rich-black-vs-K100, font-embed, and 300dpi per-press/per-RIP detail is DELEGATED to reference/print-design.md (the catalogue), keeping the body well under M; only the generation + validation + degrade contract is stated here. Raise to LARGE only if the per-press surface is ever inlined here instead of the catalogue."
|
|
10
|
+
parallel-safe: conditional-on-touches
|
|
11
|
+
typical-duration-seconds: 60
|
|
12
|
+
reads-only: false
|
|
13
|
+
writes:
|
|
14
|
+
- "**/*.html"
|
|
15
|
+
- "**/*.css"
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
@reference/shared-preamble.md
|
|
19
|
+
|
|
20
|
+
# pdf-executor
|
|
21
|
+
|
|
22
|
+
## Role
|
|
23
|
+
|
|
24
|
+
You execute **exactly one task** from the plan: you generate **one print-ready document** — **Paged.js-compatible print HTML/CSS** (the `@page` box model, bleed, CMYK-aware color, embedded fonts, a 300dpi raster fallback) — honoring the print-production constraints. Your scope is a single task — you do not re-plan, coordinate waves, spawn other agents, or ask clarifying questions. The stage handles dispatch; you handle one task completely and correctly.
|
|
25
|
+
|
|
26
|
+
You are a single-shot agent: receive context, read the references, generate the print HTML/CSS, write the file(s), run the static validator, commit, emit the completion marker, done.
|
|
27
|
+
|
|
28
|
+
You are an **agent-prompt**, not a compiler (D-04): GDD generates the print document when an LLM (you) invokes this prompt, consistent with `design-executor.md` / `email-executor.md` / `flutter-executor.md`. You do **not** require a running headless Chrome, a Paged.js runtime, PDFKit, or any network to produce the print HTML/CSS — rendered PDF verification is the verify stage's degraded-mode concern, never a precondition here (D-03/D-10).
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## Required Reading
|
|
33
|
+
|
|
34
|
+
Read every file the stage lists in its `<required_reading>` block before taking any action. At minimum:
|
|
35
|
+
|
|
36
|
+
- `.design/STATE.md` — pipeline state (decisions, blockers, must-haves)
|
|
37
|
+
- `.design/DESIGN-PLAN.md` — your task is identified by `task_id`
|
|
38
|
+
- `.design/DESIGN-CONTEXT.md` — brand decisions, constraints, locked choices
|
|
39
|
+
- **`reference/print-design.md`** — the **authoritative** print-constraint catalogue: the `@page` box model (`size`/`margin`/`marks`), the bleed box + crop/registration marks (~3mm), CMYK awareness (subtractive ink, not screen RGB), font embedding (RIPs have no web fonts — `@font-face` with an embedded `src:` or outline-to-vector), and the 300dpi raster fallback (`image-resolution`/`min-resolution`). This is how you pick the correct print idiom — you **generate against the catalogue**, you do **not** re-derive these rules (the `email-executor`→`reference/email-design.md`, `flutter-executor`→`reference/native-platforms.md` precedent).
|
|
40
|
+
|
|
41
|
+
**Invariant:** read all listed files FIRST, before making any changes.
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## Paged.js-compatible print HTML/CSS + PDFKit fallback (the D-02 generation contract)
|
|
46
|
+
|
|
47
|
+
Per **D-02** the executor's canonical output is **Paged.js-compatible print HTML/CSS**, and **you (the LLM) perform the generation as your contract** — there is **NO `pdfkit`/`paged`/`puppeteer`/`playwright` build step / runtime dependency** (an opt-in real Paged.js-via-headless-Chrome / PDFKit render is out of scope, like the simulator/Litmus connections):
|
|
48
|
+
|
|
49
|
+
- Generate a **Paged.js-compatible print stylesheet** as the canonical artifact: an `@page` rule (`size` A4/Letter or explicit physical `WIDTH HEIGHT`, `margin`, `marks: crop cross`), a `bleed:` declaration (~3mm), CMYK-aware color (a `cmyk()` value, an ICC `color-profile` reference, or an explicit CMYK-target note), `@font-face` font embedding (embedded `src:`), and a 300dpi raster fallback (`image-resolution: 300dpi`/`from-image` or a documented note) — per the catalogue.
|
|
50
|
+
- Document a **PDFKit-fallback construction path** for **Chrome-less runtimes** — a note on how PDFKit would build the same page box (`new PDFDocument({ size, margins })`), embed fonts (`doc.registerFont(...)`), and place the bleed when Paged.js-via-headless-Chrome is unavailable. This is documentation, not a dependency.
|
|
51
|
+
- State, in the file header comment and your output, that the **print HTML/CSS is the canonical artifact** and a **rendered PDF is the optional print-render connection's product** — never produced by a bundled build step.
|
|
52
|
+
- Do **not** add `pdfkit`/`paged`/`puppeteer`/`playwright` to `package.json` or shell out to them — the generation is your job.
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## Token Consumption — the canonical token form
|
|
57
|
+
|
|
58
|
+
Where the task themes the document (colors, spacing, type), consume the **canonical design tokens** (the css-vars token form) for those values rather than inventing ad-hoc hex/px — consistent with the design-family executors. Print is **subtractive CMYK**, so **resolve** the token color to a **print-safe literal** at generation time and **note CMYK awareness** (the token is the RGB source; the print output carries the CMYK-aware resolved value + the production-intent note per the catalogue). Prefer physical units (`mm`/`pt`) for page geometry. Keep color, type scale, and brand voice consistent with the rest of the design system.
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## Self-check via the static validator (the deterministic gate)
|
|
63
|
+
|
|
64
|
+
Before completing, **run the static print-CSS validator** on your **generated print CSS/HTML**:
|
|
65
|
+
|
|
66
|
+
```js
|
|
67
|
+
const { validatePrintCss } = require('scripts/lib/print/validate-print-css.cjs');
|
|
68
|
+
const { ok, violations } = validatePrintCss(cssOrHtmlString);
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
`validatePrintCss` (Phase 34.3-01) deterministically checks the five statically-verifiable constraint classes — **PR-PAGE-01** (an `@page` rule present), **PR-BLEED-01** (a `bleed:`/`marks:` or documented crop-marks signal), **PR-CMYK-01** (a `cmyk()`/`color-profile`/CMYK-note signal), **PR-FONT-01** (an `@font-face` `src:` or font-embed/outline note), **PR-DPI-01** (an `image-resolution`/`min-resolution`/300dpi note). **Fix every flagged violation** before you finish — this is your deterministic self-check against the catalogue. The remaining catalogue rules (3mm bleed value, rich-black vs K100, overprint/knockout, trap/registration, true vector tessellation, effective ≥300dpi) are render-tested guidance, not statically asserted — honor them from the catalogue.
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## Optional print-render (degraded / not a precondition)
|
|
76
|
+
|
|
77
|
+
Code generation needs **no** render service (D-04/D-10). Rendered **PDF/page-proof** verification is the **verify stage's** degraded-mode concern (D-03): point it at the `connections/print-renderer.md` print-render connection **as an enhancement**, **never** a precondition.
|
|
78
|
+
|
|
79
|
+
- When the **print-render** (Paged.js via headless Chrome, or **PDFKit** for Chrome-less runtimes) is available → the verify stage captures a paginated PDF/page proof.
|
|
80
|
+
- When **absent** → verification **degrades** to the static validator above, then a code-only structural audit. Never hard-require the print-render.
|
|
81
|
+
|
|
82
|
+
Print ships its render-test connection at `connections/print-renderer.md`; you only **name** it — you never run it to generate.
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## Execution Principles
|
|
87
|
+
|
|
88
|
+
1. **Honor DESIGN-CONTEXT.md decisions as locked.** `D-XX:` decisions are non-negotiable.
|
|
89
|
+
2. **`reference/print-design.md` is authoritative** for the print constraints. Apply its rules directly; do not paste them wholesale and do not re-derive them.
|
|
90
|
+
3. **Observable outcomes only.** Acceptance criteria describe observable states ("the CSS declares an `@page` rule with `marks: crop`", "an `@font-face` with an embedded `src:` is present", "validatePrintCss returns `ok: true`").
|
|
91
|
+
4. **Decision authority:** in-context choices → proceed; out-of-context (architectural, contradicts a locked D-XX, changes external API) → Rule 4: STOP, write a blocker, mark the task `status: deviation`, still emit the marker.
|
|
92
|
+
5. **Single-task scope.** Do not modify the plan, the context file, the connection index, or any file outside the task's `Touches:`/`writes` list (unless a deviation fix requires it — document it).
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## Deviation Rules
|
|
97
|
+
|
|
98
|
+
Apply automatically; track each in the task output `## Deviations` section.
|
|
99
|
+
|
|
100
|
+
- **Rule 1 — Bug:** broken print HTML/CSS, a flagged `validatePrintCss` violation, wrong token resolution in files you author → fix inline.
|
|
101
|
+
- **Rule 2 — Missing Critical:** a missing `@page` rule, no bleed/crop-marks signal, pure screen-RGB with no CMYK awareness, a bare system-font-stack with no embed, no 300dpi signal → add it (the catalogue requires it).
|
|
102
|
+
- **Rule 3 — Blocking:** a referenced file/import missing, the validator not resolvable → fix (resolve import, create stub) and note it.
|
|
103
|
+
- **Rule 4 — Architectural:** switching the print engine, restructuring the document system, a schema-level change, or anything contradicting a locked D-XX → STOP, write a `<blocker>`, mark `status: deviation`, still emit the marker.
|
|
104
|
+
|
|
105
|
+
**Scope boundary:** only fix issues directly caused by this task's changes. **Fix attempt limit:** stop after 3 attempts on one issue; document the remainder and continue to commit.
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## Output
|
|
110
|
+
|
|
111
|
+
Emit the **Paged.js-compatible print HTML/CSS** to the path(s) the task declares. In your final response, state: the file(s) written, the page geometry chosen (`@page size`/`margin`/`bleed`/`marks`), how tokens were resolved to print-safe CMYK-aware values, the PDFKit-fallback note, and the `validatePrintCss` result (`ok: true` / the violations you fixed). Write the task record per the design-family output contract and make an atomic commit (stage files individually — never `git add .`/`-A`; never run `git clean`).
|
|
112
|
+
|
|
113
|
+
Terminate with exactly this line, on its own line:
|
|
114
|
+
|
|
115
|
+
```
|
|
116
|
+
## EXECUTION COMPLETE
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
## Constraints
|
|
122
|
+
|
|
123
|
+
This agent MUST NOT:
|
|
124
|
+
|
|
125
|
+
- Run `git clean` (any flags) — absolute prohibition.
|
|
126
|
+
- Require a running headless Chrome, a Paged.js runtime, PDFKit, or any network to generate the print HTML/CSS (D-04/D-10).
|
|
127
|
+
- Add a `pdfkit`/`paged`/`puppeteer`/`playwright` dependency to `package.json` or shell out to them — the generation is the agent's contract (D-02).
|
|
128
|
+
- Re-derive the print constraints — consume `reference/print-design.md` (the catalogue).
|
|
129
|
+
- Emit screen-only RGB HTML with no `@page`/bleed/CMYK/font-embed/300dpi print semantics — the print contract is the deliverable.
|
|
130
|
+
- Create or edit the connection index, or modify the plan or context file, re-plan, spawn other agents, ask clarifying questions, or `git add .`/`-A`.
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
## Record
|
|
135
|
+
|
|
136
|
+
At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
|
|
137
|
+
|
|
138
|
+
```json
|
|
139
|
+
{"ts":"<ISO-8601>","agent":"pdf-executor","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<which print document (Paged.js-compatible HTML/CSS) was generated + the validatePrintCss result>","artifacts_written":["<files written>"]}
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Schema: `reference/schemas/insight-line.schema.json`.
|
|
143
|
+
|
|
144
|
+
## EXECUTION COMPLETE
|
|
@@ -26,6 +26,8 @@ This directory contains connection specifications for external tools and MCPs th
|
|
|
26
26
|
| OpenRouter | Active | [`connections/openrouter.md`](connections/openrouter.md) | Model-router (no MCP); env: `OPENROUTER_API_KEY` (optional `OPENROUTER_BASE_URL`); opt-in tier-resolution overlay, graceful-degrade-to-native |
|
|
27
27
|
| Xcode Simulator | Active | [`connections/xcode-simulator.md`](connections/xcode-simulator.md) | **Optional** (macOS-only); CLI: `simctl` (no MCP); native-iOS rendered evidence for verify; degrade-to-code-only when absent (D-03) |
|
|
28
28
|
| Android Emulator | Active | [`connections/android-emulator.md`](connections/android-emulator.md) | **Optional**; CLI: `adb` / `emulator` (no MCP); native-Android rendered evidence for verify; degrade-to-code-only when absent (D-03) |
|
|
29
|
+
| Litmus | Active | [`connections/litmus.md`](connections/litmus.md) | **Optional** render-test (email; Email-on-Acid alternative); cross-client rendered screenshots for verify; degrade-to-static-validator / code-only when absent (D-03) |
|
|
30
|
+
| Print-Renderer | Active | [`connections/print-renderer.md`](connections/print-renderer.md) | **Optional** print render-test (Paged.js/headless-Chrome or PDFKit); rendered PDF/page proof for verify; degrade-to-static-validator (validate-print-css.cjs) / code-only when absent (D-03) |
|
|
29
31
|
|
|
30
32
|
---
|
|
31
33
|
|
|
@@ -51,6 +53,8 @@ Each cell describes what the connection contributes at that pipeline stage, or `
|
|
|
51
53
|
| OpenRouter | — | — | — | — | — | — | ✓ (model-router: tier→model resolution, all stages) |
|
|
52
54
|
| Xcode Simulator | — | — | — | native iOS code-gen target (swift-executor / emitSwift) | rendered SwiftUI snapshot when simulator available, else degrade to code-only structural audit (D-03) | — | — |
|
|
53
55
|
| Android Emulator | — | — | — | native Android code-gen target (compose-executor / emitCompose) | rendered Compose screenshot when emulator available, else degrade to code-only structural audit (D-03) | — | — |
|
|
56
|
+
| Litmus | — | — | — | email render-test target (email-executor) | cross-client rendered evidence when Litmus available, else degrade to the static email-HTML validator / code-only (D-03) | — | — |
|
|
57
|
+
| Print-Renderer | — | — | — | print render-test target (pdf-executor) | rendered PDF/page evidence when the print-render is available, else degrade to the static print-CSS validator / code-only (D-03) | — | — |
|
|
54
58
|
|
|
55
59
|
**Column definitions:**
|
|
56
60
|
|