v1.0.8 — 4 Skill-doc fixes from v1.0.7 runtime-smoke retro

Doc-only Snapshot hot-fix wave addressing 4 of 15 items surfaced in the v1.0.7 runtime-smoke retro. 11 items deferred to v1.8.0 Item 3 (Synthesis-as-Code wave).

No @formtrieb/cdf-core / @formtrieb/cdf-mcp version bumps. .mcp.json caret-pin unchanged (^1.7.2).

R1 pre-ship probe corrected the plan's namespace assumption

Plan-as-drafted proposed mcp__cdf-mcp__<tool> for Bucket A's batch-ToolSearch tip. R1 ToolSearch probe in implementor session revealed that namespace does NOT exist for either install path — plugin-installed users see mcp__plugin_cdf_cdf-mcp__<tool> (where plugin_cdf derives from plugin-name cdf per Claude Code's mcp__plugin_<plugin>_<server>__<tool> convention), and direct-.mcp.json users see whatever local server-name they configured. Plan was updated in-flight to plugin-form before any Skill edits — preserves retro audit-trail honesty. Without R1, v1.0.8 would have shipped a still-broken selector and re-fired retro item 8.

Buckets

• A (retro item 8) — cdf-profile-snapshot/SKILL.md §0 + cdf-profile-scaffold/SKILL.md §0 batch-ToolSearch tip: replaced bare-slug select:cdf_fetch_figma_file,… v1.0.7-shipped string with plugin-namespaced select:mcp__plugin_cdf_cdf-mcp__cdf_fetch_figma_file,… (8 selectors: 4× cdf-mcp + 2× figma + AskUserQuestion + TodoWrite). Explanatory paragraph covers (a) why namespace prefix is mandatory, (b) lazy-discovery first-MCP-call caveat, (c) substitution rule for direct-.mcp.json users (mcp__<your-server-name>__<tool>).
• B (retro item 7) — synthesis.md Contract 4 Path 3 refined into Sub-Path 3a (preferred — Desktop bridge reachable, single figma_get_variables(format=summary) call) and Sub-Path 3b (fallback — Desktop bridge unreachable, sparse figma__get_variable_defs(nodeId) sampling, 3–5 calls). 3b mandates tool_survey: honesty annotation + explicit blind-spot naming partial-coverage estimate.
• C (retro item 10) — cdf-profile-snapshot/SKILL.md §1 wall-time replaced unqualified "5–10 min" promise with DS-size scaling table (<50 / 50-100 / 100-200 / >200 sets → 5 / 10 / 15 / 20+ min). >200-set DSes redirected to cdf-profile-scaffold directly.
• D (retro item 12) — shared/cdf-source-discovery/source-discovery.md §6 added "Filename prefix normalization" rule: metadata.ds_name lowercased + ASCII-only, non-alphanumeric → _. Examples: Material 3 → material_3, MyCo-Brand → myco_brand, acme.io → acme_io.

Deferred to v1.8.0 Item 3

Eleven retro items (1, 2, 3, 4, 5, 6, 9, 11, 13, 14, 15) cover larger architectural changes (walker-drift bridges merge, token_regime field, libraries.linked B5, vocab-collisions MCP, polymorphic-detect MCP, --lint mode, synthesis cheatsheet/restructure, inventory.pages info-loss, tool-discovery latency, axis_count semantic, config schema-drift validator).

Install / Update

claude plugin update cdf@cdf

Plan: docs/plans/done/2026-04-28-v1.0.8-hot-fix.md (private monorepo)
Source retro: docs/plans/done/2026-04-28-v1.0.7-runtime-smoke-retro.md (private monorepo)

cdf plugin v1.0.7 — Snapshot doc hot-fix

Post-v1.0.6 runtime-smoke hot-fix wave: 6 Skill-doc-only fixes from
the Material 3 fresh-install retro against v1.0.6 (12 frictions
surfaced; 6 absorbed here, 5 deferred to v1.8.0 Item 3, 1 to v1.9.0+).

Doc-only release — no @formtrieb/cdf-core / @formtrieb/cdf-mcp
version bumps; .mcp.json caret-pin unchanged.

Fixed

shared/cdf-source-discovery/source-discovery.md

• Bucket A (Friction 1) — §2 Tier-Detection algorithm gains an anti-shortcut callout above the T1-modern probe step. echo $FIGMA_PAT shell-probe is now explicitly forbidden as a proxy for cdf_fetch_figma_file({file_key}) MCP call. .mcp.json env injects only into the MCP-server process — shell-env is empty by design for designer-friendly setups. Sister to Rule B's feedback_capability_probe_before_default.

cdf-profile-snapshot/references/synthesis.md

• Bucket B (Friction 4) — §0 large-file fallback gains an explicit ❌/✅ yq inline-construction anti-pattern with the verbatim lexer-error message. V1+V3 retro item 1 reproduced in the v1.0.6 Material 3 run despite §0's positive recipe.
• Bucket C (Friction 4 ext) — §2.2 gains a sibling paste-ready aggregator for walker top-level metadata (schema_version, generated_at, generated_by, figma_file, libraries, theming_matrix, token_regime, token_source, seeded_findings).
• Bucket D (Friction 3) — §2.2 inventory: aggregator extends the (.indexed_count // .total) walker-drift bridge with a documentation_surfaces bridge for the v1.7.x walker's flat figma_component_descriptions + doc_frames_info shape. Consolidated "Walker-drift bridges" note replaces the prior single-bridge note.
• Bucket E (Friction 2) — §2.7 theming gains a parallel fallback block for regime: figma-variables alongside the existing tokens-studio fallback. Recovers theming-axes via Path 3 of Contract 4 — single figma_get_variables(format=summary) call enumerates collections + modes (budget shared with token-source enumeration).
• Bucket F (Friction 8) — Contract 4 (TOKEN-MCP) gains a consolidated probe-budget table immediately under the Path-applicability intro paragraph. Single source-of-truth across Contract 3-bis (Rule-A tool_survey:), Contract 4 (Path 1/2/3), and tool-leverage.md §4.1.

shared/cdf-source-discovery/tool-leverage.md

• Bucket B mirror — §4.2 (YAML extraction) mirrors synthesis.md §0's explicit ❌/✅ anti-pattern + verbatim lexer-error block.

Deferred to v1.8.0 Item 3

• Walker auto-fill theming_matrix.collections for regime: figma-variables (Friction 2 walker-side).
• New MCP tool cdf_validate_snapshot (Friction 6).
• New MCP tool cdf_query_phase1 (Friction 12).
• §Z-frame-named walker investigation (Friction 9).
• synthesis.md doc-restructure alongside Synthesis-as-Code rewrite (Friction 7).

Stop-condition assessment

V1+V3-baseline reproduction count: 1 (Friction 4 = V1+V3 item 1 yq lexer). Frictions 1, 2, 3, 5–12 are NEW (different DS, different regime, different PAT-state) or v1.0.6-coverage gaps, not V1+V3-baseline reproductions. Threshold not tripped (1/3); v1.8.0 path stays open.

Install / Update

Already-installed users: claude plugin update cdf@cdf picks up v1.0.7. New users: see README.

Plan: docs/plans/active/2026-04-27-v1.0.7-hot-fix.md (private monorepo).

cdf v1.0.6 — V1+V3 Skill-doc hot-fix

Post-V1+V3 doc hot-fix wave: seven Skill-doc-only fixes from the V1+V3 Material 3 retro. Ships in coordination with `@formtrieb/cdf-mcp` v1.7.3 (Renderer "What this snapshot surfaced" block — V1+V3 retro item 10); the plugin's `.mcp.json` caret-pin `^1.7.2` picks up 1.7.3 transparently on next `npx` resolution.

Sources:

• Retro: docs/plans/done/2026-04-27-v1-v3-material3-retro.md (private)
• Plan: docs/plans/done/2026-04-27-v1.0.6-hot-fix.md (private)

Fixed (cdf-profile-snapshot):

• Items 3 + 4 — synthesis.md §0 fallback threshold tightened from 2 MB to 100 KB OR 2000 lines (Read-tool 25k-token cap calibration); §2.2 inventory: gains a paste-ready canned aggregator query.
• Item 5 — synthesis.md Contract 4 (TOKEN-MCP) gains Path 3 (Figma-MCP Variables) for `regime: figma-variables` with no DS-MCP loaded.
• Item 1 — yq lexer recipe inlined in §0 directly.
• Item 7 — SKILL.md §1.4: Maximum 1 AskUserQuestion at session start; tier-probe is mechanically deterministic.
• Item 8 — synthesis.md §2.5 demotion rule for polymorphic per-component-role properties (Type / Style / Configuration / Layout / Variant) with ≥20 cross-cluster values.
• Item 9 — both SKILL.md files gain §0 batch ToolSearch tip.

Fixed (`shared/cdf-source-discovery`):

• Item 13 — source-discovery.md §6 `.gitignore` recommendation precondition-gated by `git rev-parse --is-inside-work-tree`.

Preserved (regression): probe-first tier-detection (Rule B), Contract 3-bis tool-survey discipline (Rule A), walker auto-seeding, `Phase1Output` source-of-truth contract, `cdf_render_snapshot` telemetry shape, hard 15-finding cap.

See `CHANGELOG.md` for the full entry.

v1.0.5 — Post-V2 doc hot-fix

Post-V2 doc hot-fix wave: six doc-only fixes from the V2 MoPla Snapshot
validation retro. Skill-content + plugin-manifest only release; no
@formtrieb/cdf-core / @formtrieb/cdf-mcp version bumps.

Fixed

• A1 — both SKILL.md files gain a §0.5 · Read-Path Resolution
  anchor clarifying that Read / yq / jq paths in the skill and
  its references/ + shared/ docs resolve relative to the
  SKILL.md base, not relative to the user's cwd. Eliminates the
  ls-discovery friction observed in V2 first-touch runs and gives a
  one-shot recovery instruction (find ~/.claude/plugins -name SKILL.md -path "*<skill-name>*") when the harness doesn't auto-
  resolve the relative path.
• A2-doc — synthesis.md §0 (Inputs) appends a Large-file
  fallback (>25k Read tokens) paragraph cross-referencing the yq+jq
  recipe in tool-leverage.md §4. Walker outputs exceeding the
  25,000-token Read limit (typical for DSes with ≥150
  component_sets) no longer block synthesis: the contract holds, only
  the read-strategy changes. Probe walker file size first
  (ls -lh .cdf-cache/phase-1-output.yaml); branch directly to
  fallback if >2 MB.
• A3 — tool-leverage.md §4 adds a §4.2 YAML extraction
  (mikefarah yq + jq) sub-section documenting the
  yq -o=json '...' file.yaml | jq '...' pipe pattern. Mikefarah yq
  rejects inline jq-style object construction (yq '.foo | {bar: .baz}'); the pipe pattern is the canonical fallback. Includes
  WRONG / RIGHT examples.
• A4 — walker-invocation.md §2 documents the
  total ↔ indexed_count field-name drift between what the walker
  emits (ds_inventory.component_sets.total) and what the snapshot
  schema expects (indexed_count). Both refer to the same metric
  (union of tree-resolved + remote-only sets); the alias-mapping is
  authoritative until the walker rename ships in v1.8.0.
• A5-doc — synthesis.md §2.7 (theming) appends a Fallback when
  theming_matrix.collections: [] is empty recipe. When the walker
  emits an empty collections list (typical when .cdf.config.yaml
  has no explicit resolver: block but regime: tokens-studio is
  set and tokens/$themes.json exists on disk), operators can derive
  theming-modifiers via a single jq -r 'group_by(.group) | …'
  invocation against tokens/$themes.json. Cross-validation note
  against component-side VARIANTS included.
• A6 — walker-invocation.md §2 adds an Output-Shape Examples
  block for jq/yq query construction. Several walker fields emit
  flat-string arrays (NOT object arrays) — standalone_components.*,
  pages.separators[], libraries.linked[], doc_frames_detected[].
  Documents the WRONG .utility[].name (returns null) vs RIGHT
  .utility[] query shapes.

Deferred to v1.8.0 (Synthesis-as-Code wave)

• A2-walker — cdf_extract_figma_file summary_only mode emitting
  phase-1-summary.yaml (drops inline propertyDefinitions for

  25k cases)

• A5-walker — walker auto-resolves theming_matrix.collections
  from tokens/$themes.json when regime: tokens-studio and no
  explicit resolver: is configured
• A7 — Renderer hyphen-line-break lint (cosmetic)
• B5 — libraries.linked walker output bug — under fresh-chat
  investigation in v1.8.0

Accepted as platform constant

• A8 — ToolSearch round-trip latency for first-time MCP tool
  invocation. Documented in v1.0.4's tool-leverage.md §1
  deferred-tool note; no further action.

No package version bumps in v1.0.5

• @formtrieb/cdf-core@1.0.x and @formtrieb/cdf-mcp@1.7.x unchanged
• .mcp.json still pins @formtrieb/cdf-mcp@^1.7.2
• Skill-content + plugin-manifest only release

Upgrade for existing installs

claude plugin marketplace update cdf
claude plugin update cdf@cdf
# Fully quit Claude Code (Cmd+Q) and relaunch — closing the window
# is not enough; the MCP launcher needs to reload .mcp.json env.

v1.0.4 — Snapshot stability

Snapshot stability bundle from two real-world Snapshot validation runs. Skill-content + plugin-manifest only release — no @formtrieb/cdf-core / @formtrieb/cdf-mcp version bumps.

8 fixes ship in this wave: 5 mechanical + 3 inhaltliche.

Fixed

• F6 (HIGH) — Tier-detection probe-order bug. Snapshot/scaffold no longer silently defaults to T0 when on-disk Figma caches are absent but FIGMA_PAT is set. New probe-first algorithm: T2 → T1-legacy-cache → T1-modern-probe (cdf_fetch_figma_file) → T0 → halt. Adds Rule B — Capability-Probe Before Default-Fallback as sister-rule to Rule A.

Improved

• F1 — Pre-reading β-strict refactor. SKILL.md §1 in both skills no longer requires upfront Read of the 3 shared/-refs. Each phase-doc / synthesis dispatch declares its requires: deps in YAML frontmatter, Read at point-of-need. Per-step Read budget drops from 3 (eager) to 0–2 (point-of-need).
• L8.5 — Rule-A literal-loophole closed. Paraphrased capability-gap claims ("only partial Variable surface", "REST cache lacks Variables data") now trigger the same tool-survey enforcement as the literal "X NOT enumerable". Rule is structural; positive-obligation trigger-word list provides self-check.
• F4 — Deferred-tool note in tool-leverage.md §1, documenting one-time ToolSearch round-trip per MCP-family per session.
• F8 — Host-tool prerequisites (yq mikefarah ≥4.x, jq, python3 stdlib only, bash 4+/zsh) declared in both SKILL.md §0. New scripts/check-host-deps.sh verifier (exits 0 + versions on success, 1 + MISSING:<tool> + install hint on first absent dep).
• F10 (inhaltliche) — Vocabulary-threshold loosened. Single-set semantically-evident vocabs (intent, density, progress, orientation, position) and Boolean-as-VARIANT recurring props (selected, open) elevate to top-level vocabularies alongside their interaction-pattern view. Icon-Set heuristic added.
• F11 (inhaltliche) — Token-grammar fallback-path depth. Contract 4's 1× browse_tokens cap binds DS-MCP path only. In the filesystem-walk fallback path (no DS-tokens MCP loaded, but DTCG / Tokens-Studio JSON files on disk), path-level jq paths enumeration is encouraged with depth-2 cap. New §4.1 "Token enumeration paths" precedence list + recipes + Components/* heuristic.
• F12 (inhaltliche) — T0/T1 walker inventory-counting semantic difference documented (T0 counts every variant-instance; T1 dedupes by COMPONENT id; on the same file these can differ by 5–10×). Snapshot synthesis emits a one-line note when both probes are available.

Deferred to v1.8.0 (companion roadmap)

• Walker summary_only mode (cdf_extract_figma_file option)
• Generic @formtrieb/tokens-mcp@2.0.0 (path-parameter, non-DS-specific) — supersedes the F11 jq-paths fallback recipe
• libraries.linked walker output bug fix
• Bash-script deletion (scripts/extract-to-yaml.sh retirement)
• Synthesis-as-Code (cdf_analyze_inventory) replacing the F10 LLM-policy bridge

No package version bumps in v1.0.4

• @formtrieb/cdf-core@1.0.x and @formtrieb/cdf-mcp@1.7.x unchanged
• .mcp.json still pins @formtrieb/cdf-mcp@^1.7.2
• Skill-content + plugin-manifest only release

Upgrade for existing installs

claude plugin marketplace update cdf
claude plugin update cdf@cdf
# Fully quit Claude Code (Cmd+Q) and relaunch — closing the window
# is not enough; the MCP launcher needs to reload .mcp.json env.

Full changelog

See CHANGELOG.md.

cdf v1.0.3 — Phase 4 MoPla validation fixes

Patch release surfacing two friction points caught during Phase 4 MoPla validation (2026-04-26 — first real-world snapshot run against a non-trivial DS, 152 component_sets, 9 min wall-time).

Fixed

FIGMA_PAT not reaching the MCP server

The plugin's .mcp.json did not explicitly forward FIGMA_PAT from the user's shell, so whether cdf-mcp received it depended on Claude Code's MCP-launcher inheritance behavior. Real run: export FIGMA_PAT=... was set in ~/.zshrc, but the first cdf_fetch_figma_file call still failed with the no-PAT error. The user had to read the value from .env and pass pat: inline.

Fix — .mcp.json now declares an explicit env passthrough:

"env": { "FIGMA_PAT": "${FIGMA_PAT}" }

The ${FIGMA_PAT} syntax interpolates at MCP launch time. Shell-set tokens now reach cdf-mcp on first call without per-call pat: arg. The arg-form fallback still works (and overrides env) for multi-account scenarios.

_quality: draft schema annotation invalid on findings_unclassified

snapshot.profile.schema.yaml documented _quality: draft as a top-level marker on every best-effort section, but findings_unclassified is a YAML list — a sibling _quality: draft key produces a mixed scalar+list shape that breaks parsers. The schema now omits the marker on the list section and adds an explicit note that draft-status there is implicit via the soft-boundary position. Mapping sections (vocabularies, token_grammar, theming, interaction_a11y) keep the inline marker — they're objects, where it's well-formed.

Upgrade

claude plugin marketplace update cdf
claude plugin update cdf@cdf
# Fully quit Claude Code (Cmd+Q) and relaunch — the MCP launcher
# needs to reload .mcp.json env passthrough.

Phase 4 status

The MoPla run produced a full, useful snapshot output (12 findings + 7 blind-spots, all under cap, vocabulary-collisions surfaced, Rule A tool-survey corrected the Variables blind-spot). Wall-time was 9 min — at the upper edge of the <10 min target. Three deferred friction points (pre-reading 6 files before drafting; walker output >25k tokens for 152 component_sets; deferred-tool ToolSearch overhead) are tracked in the upstream backlog under "Skill UX iteration from MoPla run."

No package version bumps — @formtrieb/cdf-mcp and @formtrieb/cdf-core are unchanged at v1.7.2 / v1.0.3. Only this plugin's manifest + schema doc changed.

cdf v1.0.2 — Fix bootstrap config crash

Patch release fixing the MCP server crash that occurred when .cdf.config.yaml referenced a not-yet-existing profile_path: — i.e. the default bootstrap state for any new plugin user following the Quickstart. The MCP server reported MCP error -32000: Connection closed and the plugin was unusable until the profile YAML existed (chicken-and-egg, since the profile is what the scaffold produces).

Root cause

@formtrieb/cdf-core@1.0.2's parseConfigFile eagerly loaded the profile YAML as soon as profile_path: was set in .cdf.config.yaml, throwing ENOENT if the file didn't exist. The MCP server crashed during initialization, before any tools could register.

Fix (three coordinated patch releases)

• @formtrieb/cdf-core@1.0.3 — parseConfigFile now existsSync-checks the profile path and, if missing, leaves ds_profile undefined while emitting one stderr warning line: [cdf-core] profile_path '...' set in ... but file does not exist (...); ds_profile not loaded. Diagnostic signal preserved for misconfigurations; bootstrap states now proceed cleanly. 4 new tests covering happy path, missing-file skip-and-warn, no-profile_path quiet path, relative-path resolution.
• @formtrieb/cdf-mcp@1.7.2 — pins ^1.0.3 (caret range that resolves to the fixed cdf-core); no behavioural changes in the MCP server itself.
• cdf plugin v1.0.2 — .mcp.json bumped to ^1.7.2 so npx re-resolves past stale ^1.7.1 cache entries; README Quickstart .cdf.config.yaml example now leaves profile_path: commented out on first run (uncomment after the scaffold writes the profile).

Upgrade for existing installs

claude plugin marketplace update cdf
claude plugin update cdf@cdf
# Fully quit Claude Code (Cmd+Q) and relaunch — closing the window is not enough.

If the MCP still doesn't connect after that, clear the npx cache so any stale ^1.7.1 resolution is dropped:

rm -rf ~/.npm/_cacache/_npx ~/.npm/_cacache/index-v5/_npx

…then restart Claude Code again.

Fresh install

Same two-step as v1.0.0:

claude plugin marketplace add formtrieb/cdf-plugin
claude plugin install cdf@cdf

Verify

claude mcp list | grep cdf-mcp
# Expect: plugin:cdf:cdf-mcp: npx -y @formtrieb/cdf-mcp@^1.7.2 - ✓ Connected

cdf v1.0.1 — Fix MCP launch via npx

Patch release fixing the MCP server launch path. v1.0.0 shipped with .mcp.json pinning @formtrieb/cdf-mcp@^1.7.0, but that version of the MCP server lacked a bin field — npx couldn't determine an executable, so Claude Code reported "plugin:cdf:cdf-mcp ✗ Failed to connect" on every session.

Fix

• .mcp.json bumped to @formtrieb/cdf-mcp@^1.7.1 (release notes)
• README install command corrected to the two-step pattern (marketplace add → install cdf@cdf); single-plugin repos package as one-entry marketplaces, the bare-URL install path expects an already-configured marketplace
• README troubleshooting expanded with both symptoms (MCP-launch failure and the marketplace-not-found error)

Upgrade for existing installs

claude plugin marketplace update cdf
claude plugin update cdf@cdf
# Restart Claude Code so the new MCP server config takes effect.

If the MCP still doesn't connect after that, clear the npx cache (rm -rf ~/.npm/_cacache/_npx ~/.npm/_cacache/index-v5/_npx) so any stale ^1.7.0 resolution gets dropped, then restart again.

Fresh install

Same two-step as v1.0.0:

claude plugin marketplace add formtrieb/cdf-plugin
claude plugin install cdf@cdf

cdf v1.0.0 — Initial plugin release

First public release of the cdf Claude Code plugin — bundles two complementary Component Description Format (CDF) skills.

Install

This is a single-plugin repo packaged as a one-entry marketplace — two-step install:

claude plugin marketplace add formtrieb/cdf-plugin
claude plugin install cdf@cdf

Verify with claude plugin list | grep cdf (expect cdf@cdf Version: 1.0.0 Status: ✔ enabled). Restart your Claude Code session after install so the slash-commands and MCP tools are discovered.

Why two steps: claude plugin install <owner>/<repo> expects an already-configured marketplace, not a bare GitHub URL. Even single-plugin repos need to be registered as a one-entry marketplace first. See README.md for the full pattern.

What's in the box

• /cdf:scaffold-profile — production-grade 7-phase Profile authoring (Orient → Vocabularies → Grammars → Theming → Interaction+A11y → Findings+Classify → Emit+Validate). Wall-time ~30–40 min per DS. Validator-checked output.
• /cdf:snapshot-profile — 5–10 min first-touch evaluation sketch with explicit blind-spots and an upgrade path to the Production Scaffold. Audience: evaluators asking "what would CDF say about my DS?"

Both skills:

• share a canonical source-discovery layer (shared/cdf-source-discovery/) — opening checklist, T0/T1/T2 tier detection, Survey-First (Rule A), walker invocation
• orchestrate @formtrieb/cdf-mcp@^1.7.0 (22 deterministic CDF tools) via the plugin's .mcp.json (npx-launched, no separate install)
• support T0 (runtime / no PAT), T1 (REST / PAT), T2 (Enterprise REST + Variables) Figma access paths

See README.md for the full prerequisite + Quickstart guide. .cdf.config.yaml schema is documented at github.com/formtrieb/cdf#quickstart--cdfconfigyaml.

Compatibility

• Claude Code or Claude Desktop with MCP support
• Node.js ≥ 20 (the plugin's .mcp.json uses npx)
• Optional: figma-console MCP for the T0 (no-PAT) path; DS-specific tokens MCP for richer regimes

Related projects

• formtrieb/cdf — CDF v1.0 spec
• @formtrieb/cdf-core — TypeScript library
• @formtrieb/cdf-mcp — MCP server (this plugin's bundled dependency)