Skip to content

Latest commit

 

History

History
666 lines (584 loc) · 39.5 KB

CHANGELOG.md

File metadata and controls

666 lines (584 loc) · 39.5 KB

Changelog

All notable changes to this project are documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

3.1.1 - 2026-08-31

Security

  • figma.mcp.url is now screened before it reaches the MCP probe. The value was read from the committed figma.projects.config.json without validation and handed to curl in URL position, so a value starting with - was parsed as an OPTION instead: -K<path> loads an arbitrary curl config file, which an attacker could commit beside it to obtain output (arbitrary file write with attacker-chosen content, i.e. code execution on the next run) or upload-file. The probe path is automatic — the mandatory before_specify / before_plan hooks reach it through figma-ensure-context → figma-introspect → figma_resolve_context_source — so a hostile config in a cloned or PR-modified repository needed no user action beyond an ordinary SpecKit run. mcp.url must now carry an http(s):// scheme (new figma_mcp_url_allowed / Test-FigmaMcpUrlAllowed guard, enforced at the probe and by figma-validate-config, plus a pattern in the JSON schema), and the probe passes it after a -- separator. This closes the same class of hole apiBaseUrl was already protected against.

    The host stays unrestricted, unlike apiBaseUrl: no credential travels with the probe, so a self-hosted MCP server (devcontainer, tunnel, alternate port) keeps working. Figma links pasted into a prompt are unaffected — they are parsed for their file/node ids and never used as a request target.

    The one legitimate config this can reject is a scheme-less mcp.url (e.g. 127.0.0.1:3845/mcp), which curl used to accept by assuming http. Prefix it with http:// and it works as before.

3.1.0 - 2026-08-25

Added

  • Cross-file source-component resolution. figma-introspect used to resolve an INSTANCE's source component only against the file of the pinned link — a component published from another file (a Design System library, another project, another team) silently degraded to instance-only data. It now falls back to Figma's own component registry (GET /v1/components/{key}), which answers with the file that actually owns a published component regardless of where that is — no config has to name it up front, and the same lookup covers the Design System and any other library uniformly. Resolved components are recorded in a new sources.externalFiles map; the rendered "Source components" table now shows a File column (same file or `<fileKey>` (external)). designSystem also gains optional figmaProjectId / figmaTeamId / figmaTeamIds fields, for enumerating a Design System spread across several files when browsing its reuse inventory.
  • Content-aware component locator inside a broad/oversized link. When the developer names or describes a specific component inside a page-sized link instead of asking "what's on this page?", the agent now searches the already-fetched subtree (node names, TEXT node content) for a match and presents that single match for confirmation, instead of the raw list of top-level children. Documentation-only change (/speckit.figma.ensure section 3b, /speckit.figma.introspect section 3) — no new script.

Fixed

  • A component whose source could not be resolved at all (neither in the linked file nor in another one) no longer shows up as a blank, misleading row in the "Source components" table — it is dropped instead of looking like a resolved component with no name.

3.0.0 - 2026-08-24

Changed

  • BREAKING (prerequisite) — the extension now requires SpecKit >=0.11.2, up from >=0.1.0. /speckit.converge is the only reason: its command template, and therefore the before_converge / after_converge hook points, first ship in that release. Every other hook this extension registers has existed since at least v0.9.5. An install on an older SpecKit that worked before is now refused, so this is a real prerequisite tightening, not a silent minor — upgrade SpecKit (uv tool upgrade specify-cli) before updating the extension.

Added

  • /speckit.figma.export — Figma nodes to image files, in two modes. One endpoint, two needs whose lifecycles are opposite, so they are separate modes rather than one flag that would put throwaway files under version control (or leave deliverables in a git-ignored cache).

    preview (default) renders the candidate frames to PNG under specs/<feature>/assets/, so design rule 5 can be answered by looking at the creative instead of reading a list of node ids. Those files are committed on purpose: .figma/cache/ is git-ignored, so a preview written there is invisible to a reviewer on GitHub and spec.md renders a broken image — a few tens of KB costs less than that.

    asset pulls what the implementation ships — a logo as .svg, a mock as .png. --out is mandatory: where a shipped asset belongs (Design System vs app) is a placement decision like any other, and the script refuses to guess it. A .figma-assets.json manifest beside the files records what was written and its checksum, so a re-run reports unchanged instead of re-downloading and refuses to overwrite a file a human edited since (skipped-modified); --force is how a developer says they meant it.

    Mechanics worth knowing: the endpoint renders asynchronously — it returns temporary URLs that must then be downloaded, two steps — ids are requested in batches (--batch-size, default 10) because a large request times out on a big file, scale is dropped for vector formats instead of being sent and rejected, and the rendered URL is a signed CDN link that is downloaded without the PAT, since attaching it would leak the credential to a third-party host. Export needs no scope beyond file_content:read. The command is deliberately not hooked: it writes into the repository.

  • Source components are resolved automatically — "right-click > show source". A linked node is almost always an INSTANCE, and an instance is the flattened rendering of a main component: overrides applied, variant fixed. Reading it is how a spec ends up describing one particular appearance of a component rather than the component, which is what forced a developer to redo a feature in a second session, manually pasting the main component's node id into the spec.

    Introspection now collects the componentId of every INSTANCE in the fetched subtrees and deep-fetches those definitions into a new sources slot on the snapshot. The rendered section lists them and tags every extracted value row instance or source, so a difference between the two stays visible as an override to expose as a prop instead of being silently merged into one number. Components living in another library file are out of reach (that would need the library's file key) and the resolution is non-fatal: a missing source degrades the context, it does not invalidate it.

  • New oversized link scope — a pinned node id is not automatically a creative. linkScope was binary: broad (a file/page link) or frame (anything with a node id). A link copied from a full-page desktop frame pins a FRAME like any other, so it was classified frame — a confirmed creative — and the confirmation checkpoint never fired. The agent then reasoned over 12 000 px of page as if it were the component, which is the single most expensive failure this extension has produced.

    A pinned node past FIGMA_OVERSIZED_HEIGHT (3000px) or FIGMA_OVERSIZED_DESCENDANTS (150) is now oversized and handled exactly like broad — enumerate and confirm — except the candidates are the node's own children: the developer linked the right page, they only have to say which block of it. Both thresholds are env-overridable, because "page-sized" is a property of the design system in use, not a universal constant.

  • Deterministic design values in the rendered section. The renderer's stated goal is a section produced "REGARDLESS of the agent model" — but that was only ever true of its structure. The values were not: the snapshot is a raw dump of the Figma node tree (megabytes for a full-page frame) and the spacing/typography tables were left for the model to mine out of it. Weaker models do not mine megabytes of JSON; they guess, which is why a faithful-looking spec produced an implementation whose padding, alignment and type matched nothing in the mockup.

    A new figma-extract-values helper walks the deep-fetched nodes and emits the facts as a compact digest — layoutMode, the four paddings, itemSpacing, both axis alignments, corner radius, box size, and per text node the family, weight, size, line height, letter spacing and alignment, plus the styles ids that bridge to the Design System. figma-render-section now pastes those as two tables inside the section, so the agent copies numbers instead of inventing them. Nodes carrying no design value contribute no row, and a padding Figma never sent is absent rather than fabricated as 0px — a fabricated zero reads as a deliberate design decision the mockup never made.

  • Units are always explicit, and the conversion contract is the project's. Every length is emitted as 70px, never as a bare 70. A bare number is what lets a length be re-read as something else downstream: handed to a scale-indexed helper — Tailwind's mt-70, or MUI's theme.spacing(70) on a theme built with spacing: 4 — a 70px margin silently becomes 280px, wrong by the scale factor, with nothing failing.

    The extension deliberately stops at "this is 70 absolute CSS px at 1x". It does not convert, and there is no units block in the config: no schema could cover MUI useStyles with a custom pxToRem, Tailwind, CSS variables, styled-components and vanilla-extract at once, and a half-covering one is worse than none. New base rule 6b states the invariant and the prohibition, and defers the conversion contract to the project overlay (.figma/figma-design-rules.custom.md) — the same pattern rule 4 already uses for the responsive policy. config/figma-design-rules.custom.example.md ships a ready-to-uncomment example that names the trap with the actual number.

  • autoIntrospect — opt-in autonomous introspection, per target. 2.0.0 made a Figma link the sole trigger, which removed the agent's ability to fetch design context when it judges the feature to need it. A target can now re-open the config-derived path in figma.projects.config.json:

    "repo": { "autoIntrospect": { "mode": "on-request", "maxFrames": 60 } }

    off is the default, so nothing changes for a workspace that says nothing and the 2.0.0 contract is preserved. on-request (recommended) has the committed config authorise and the agent trigger, by passing the new --assume-design flag when the feature plainly describes UI work; on a target left at off the flag is ignored with a warning, so an agent can never grant itself design context. always restores the pre-2.0.0 behaviour for the targets that want it.

    Three properties keep this from re-creating the regression 2.0.0 removed:

    • The autonomous path introspects the mapped file and nothing wider. A project or team id would crawl an organisation — that is /speckit.figma.introspect's job, never an automatic pre-generation hook's. A target with no figmaFileId reports the new reason auto-unavailable, and the schema refuses the combination outright.
    • maxFrames (default 60) is a hard, measured budget. Over it, the run stops at too-large-for-auto with nothing rendered and asks for a node id, because context that wide is too diluted to implement faithfully. It is checked at all three points that reach a usable snapshot — the fresh slot, the restored per-file copy and a fresh introspection — and never applies to a link-driven run, whose node id already pins the creative.
    • The rule-5 confirmation checkpoint fires by construction. An autonomous run contributes no node id, so the scope computation classifies it broad and the candidate frames are enumerated for confirmation — the existing safety net, reused rather than rebuilt. confirmFrames: false opts out, for a file holding one unambiguous creative.

    The status object gains trigger (link | auto | none) and confirmFrames, rather than duplicating every reason into an auto-* variant, plus the terminal reasons auto-declined, auto-unavailable and too-large-for-auto.

  • /speckit.converge is hooked as a task-generating phase. Converge assesses the codebase against spec/plan/tasks and appends the remaining unbuilt work to tasks.md, which puts it in the same class as /speckit.tasks — already hooked. Converging without design context means the unbuilt UI work is re-derived from prose alone: the appended tasks carry no Figma value at all, and /speckit.implement then builds from those. It is also the phase most likely to run on a PR resumed later by someone else, which is exactly the scenario the analyze/implement fix above addresses.

    before_converge invokes /speckit.figma.ensure, and after_converge runs the same --phase tasks verification as after_tasks: converge rewrites a document that already carries the section, and a rewrite is where a section — and the marker every later phase keys on — gets dropped. The agent instructions add one converge-specific rule: keep the existing tasks section and its marker, add the newly derived design tasks into it, never paste a second copy.

  • /speckit.figma.drift — design-drift reporting after /speckit.analyze. Analyze cross-checks spec.md, plan.md and tasks.md against each other, and all three can agree perfectly while being faithful to a creative the designer has since changed. On a PR open for two weeks that is what yields an implementation faithful to an obsolete design. The new after_analyze hook compares the Figma lastModified recorded when the document was generated against the snapshot before_analyze just refreshed, and reports — it never edits a document, because whether a moved creative invalidates work already done is the developer's call. --strict (or figma.verifyStrict) makes a real drift exit non-zero for CI; being unable to check still exits 0, so the gate fires on evidence and never on its absence.

  • The rendered section marker now carries the two facts drift detection needs: <!-- speckit-figma:section phase=spec file=<key> lastModified=<ts> -->. Reading them back from the marker rather than from the rendered prose keeps the check working the first time a heading is reworded or translated. Backward compatible by construction — every existing reader greps the fixed speckit-figma:section phase=<phase> prefix, which still matches. A snapshot with no lastModified renders lastModified=unknown, which reads as "cannot compare", never as a timestamp.

Fixed

  • The extension now runs on /speckit.analyze and /speckit.implement. extension.yml declared hooks for specify, plan and tasks only, and the --prompt-hooks fallback stopped at the same three (install.sh), so on the two remaining phases the extension was entirely absent: no snapshot, no link recovery, and .figma/figma-design-rules.md never loaded — during the one phase that actually writes code. The hole predates 2.0.0; v1.6.0 shipped the identical hook set.

    What that produced in the field: a developer picking up an existing PR re-ran analyze and implement, had no cache at all (.figma/cache/ is git-ignored, so nothing travels with a branch, and the recovery of the link from the committed spec.md lives inside ensure), and their agent improvised — a direct Figma MCP call with a node id re-extracted from the URL, which is the usual source of "the provided node ID was not found in the file". That path bypasses node-id canonicalisation, the engine resolution and its REST fallback, the design rules, and the deterministic section.

    before_analyze and before_implement now invoke /speckit.figma.ensure. Both phases generate no document, so nothing is pasted and mustInject does not apply to them: what the hook provides there is the context — the effective ruleset (base plus the project overlay) and a current snapshot. The agent instructions say so explicitly, in the command and in the injected managed block. SpecKit has exposed these hook points since at least v0.9.5, so no minimum-version change is needed.

  • Features orphaned by the 2.0.0 trigger change are now detected. Before 2.0.0 a mapped pageToPackageMapping was enough to trigger design context, so a spec generated by 1.6.x can carry a full design section that records no url — it reads "None — context derived from page mapping." Under 2.0.0 the link is the trigger and the recovery path parses urls out of the committed spec.md; with none to find, the run falls through to no-figma-link, under which the agent is instructed to say nothing about Figma at all.

    The result was the extension's only failure mode that produced no signal: /speckit.plan and /speckit.tasks silently stopped adding the design context that spec.md still displays, permanently, for that feature. The 2.0.0 CHANGELOG did not cover it.

    /speckit.figma.update now runs figma-check-orphans and lists the affected features with the two ways out — paste the link of the frame each one targets into its spec.md, or enable autoIntrospect on the target so the mapping is a legitimate trigger again. It never edits a spec: which frame a feature targeted is precisely what those specs failed to record, and guessing it is how the wrong creative gets implemented. --strict makes it a CI gate.

2.0.0 - 2026-08-11

Changed

  • BREAKING — the helpers and templates now run from the tree SpecKit installs, .specify/extensions/figma/, and are no longer copied into the workspace. specify extension add already installs scripts/, templates/ and the commands there; the installer copied both into .specify/scripts/ and .specify/templates/ on top of that, so every workspace carried two versions of the same file. The copy has no owner — SpecKit records the version of the tree, not of the duplicate — so it silently drifts, and the stale one is the one a developer reads. Everything now invokes ./.specify/extensions/figma/scripts/{bash,powershell}/…, and figma-render-section resolves its templates next to itself (the workspace path remains as a fallback for un-migrated installs, but no longer takes precedence: a leftover can no longer shadow the shipped template).

    Consequences, all of them user-visible:

    • specify extension add is now a prerequisite, not one of two options. install.sh / install.ps1 check the tree is present and stop with the exact command to run when it is not — before writing anything, since wiring a project around helpers that are absent produces a workspace that looks installed and fails on every hook. Run them from the installed tree (./.specify/extensions/figma/install.sh), which is what /speckit.figma.update and /speckit.figma.config now do.
    • The installers delete the duplicated figma-* helpers and section templates earlier versions left in .specify/scripts/ and .specify/templates/. Only the figma-* entries: both directories are SpecKit's and keep its own files, and an emptied directory is removed only when it is genuinely empty.
  • BREAKING — a Figma link in the feature input is now what triggers the extension. figma-ensure-context used to treat a valid config with a mapped, enabled target as enough: it introspected and forced the design section into every spec.md, plan.md and tasks.md, so a feature like "add a Redis cache on the billing endpoint" came back carrying a Figma section it had no business carrying. The mapping in figma.projects.config.json says where a creative would live, not whether a feature has one — only the link answers that. With no link the run now ends at the new no-figma-link reason: no introspection, no rendered section, mustInject: false, and the after_* verify hooks report not-applicable.

  • Workspaces that relied on pageToPackageMapping alone to obtain design context without pasting a link must now paste the Figma link in the feature description, or run /speckit.figma.introspect by hand.

  • BREAKING — /speckit.figma.setup is renamed /speckit.figma.config. The command never installed anything (install.sh / install.ps1 do that): it detects the topology, writes figma.projects.config.json, and validates connectivity. config says what it does, and matches the sibling extension spec-kit-charter, which already exposes /speckit.charter.config. Re-run specify extension add to register the new name; no alias is kept, because two names for one command is the confusion the rename removes.

  • role is no longer required on a target. Validation rejected a config without it, yet no helper branched on it: figma-detect-target copies it into its JSON output and nothing reads it back. It stays enum-validated when present — a value outside the enum is a typo, not a choice — and stays documented, because it tells a human what a target is. Existing configs are unaffected.

  • Rendered sections moved to .figma/cache/sections/<feature>/<phase>.md, from the flat .figma/cache/section.<phase>.md. Both installers drop the old flat files. Nothing needs to reference these paths by hand — the orchestrator reports them in specSection / planSection / tasksSection — but a workspace that hardcoded them somewhere must follow.

  • As a consequence, figma-ensure-context no longer derives an introspection scope from the config (--team / --project / --file); that path was unreachable once a link became mandatory. /speckit.figma.introspect remains the way to introspect a mapped team or project.

Added

  • Figma links detected in the feature input are remembered per feature (.figma/cache/links/<feature>.json, already covered by the .figma/cache/ gitignore entry), so the link is pasted once at /speckit.specify and /speckit.plan / /speckit.tasks inherit it. Scoping is per feature so the next, design-less feature never inherits the previous one's link. The feature identity follows SpecKit's own resolution: SPECIFY_FEATURE, then .specify/feature.json, then the git branch.
  • When that per-feature memory is absent, the link is recovered from the committed spec.md. .figma/cache/ is git-ignored, so the memory does not travel with the branch: a fresh clone, a CI job or a teammate who just pulled reached /speckit.plan with no link and fell through to no-figma-link — under which the agent is told to add nothing about Figma, so plan.md silently lost the design section spec.md carries. The recovery is gated on the speckit-figma:section phase=spec marker: a figma.com URL merely mentioned in the prose of a spec is not a design section and must not become a trigger. The document must also be one the current feature positively owns (identified-only): with nothing identifying the feature, "the only spec around" belongs to another one, and inheriting its creative would re-create the very regression this release removes. A recovered link re-warms the cache.
  • Prototype links keep their flow starting point. A /proto/ URL names two frames — node-id, whatever the designer was viewing when they copied the link, and starting-point-node-id, the entry point of the parcours — and only the first was introspected. Both are now deep-fetched (same batched request, so no extra API cost), which also pins a prototype link whose node-id is missing instead of degrading it to a broad link. Parsed links carry a new startNodeId field.
  • The no-figma-link outcome is now surfaced conversationally, without touching the document. Nothing distinguishes a front-end feature whose author simply forgot to paste the link from a back-end one that legitimately has none, and the document is deliberately silent — so a forgotten link produced a spec with no design context and no signal at all, through plan.md and tasks.md too. The console line now names the remedy, and the agent instructions separate the two surfaces: nothing in the generated document, one plain sentence in the chat reply. It stays a statement, not a question: the agent still never asks for a link, blocks, or goes looking for one with an MCP tool.
  • Snapshots are cached per Figma file under .figma/cache/snapshots/, on top of the single context-snapshot.json slot. That slot is the snapshot of the current run — the well-known path every command prompt hands to the agent — and one slot is enough to publish a snapshot but not to cache one: two features targeting different Figma files evicted each other, so the fresh path never hit and every phase re-paid a full file fetch plus a nodes fetch for a snapshot that had been valid minutes earlier. A run whose link is already covered by a stored snapshot now restores it instead of re-introspecting.
  • docs/ARCHITECTURE.md maps the subsystems with Mermaid diagrams: the decision flow and every skip reason, link resolution and its guards, the introspection pipeline, engine selection, credential resolution, the section lifecycle, and which parts of the config are executable versus written for human readers. Installed into workspaces alongside the other guides.
  • The README now states that figma.contextSource: "mcp" does not replace the PAT. The deterministic introspection always goes through the REST API, whatever the configured engine; MCP improves how the agent renders the design, not how the snapshot is collected. A local Dev Mode server alone, with no PAT, fails with "reason": "introspect-failed" and "code": "AUTH".
  • The schema now says what pageToPackageMapping is: guidance in the /speckit.figma.introspect prompt, not a mapping any helper parses. Same for role.
  • Cache housekeeping. .figma/cache/ only ever grew: a links/<key>.json and a sections/<key>/ per branch that ever ran a phase, a snapshots/<fileId>.json per Figma file ever linked. Disk was not the problem — key reuse was: a key derives from a branch name, so a new feature on a recycled name inherited the remembered links of whatever used the name before it, and came back carrying a design section for someone else's mockup. Every real (non-dry) run now sweeps the cache at most once a day, on an ownership-first policy: an entry survives as long as specs/<key>/ exists — the signal is committed, so it outlives the branch — and is collected only when it is both orphaned and untouched for FIGMA_CACHE_RETENTION_DAYS (7). Stored snapshots have no owner to consult and go on age alone, never below the freshness window a caller configured. The feature of the run doing the sweep is exempt unconditionally, and a live feature's renders are never collected — figma-verify-section reads "Figma applied to this run" from their existence, so collecting them would turn a --strict gate fail-open. FIGMA_CACHE_GC=off disables the sweep, =force ignores the daily throttle.
  • figma_gc_cache / figma_gc_key_is_live (bash) and Invoke-FigmaCacheGc / Test-FigmaGcKeyIsLive (PowerShell).
  • figma_snapshot_store_path (bash) / Get-FigmaSnapshotStorePath (PowerShell).
  • figma_feature_key / figma_feature_links_path / figma_resolve_phase_doc (bash) and Get-FigmaFeatureKey / Get-FigmaFeatureLinksPath / Get-FigmaPhaseDoc (PowerShell). figma-verify-section now shares the document resolver instead of carrying its own copy, and the resolver honours the feature identity (SPECIFY_FEATURE, .specify/feature.json) before falling back to the branch.

Fixed

  • A design-less feature could make a --strict CI gate pass for a document genuinely missing its design section. figma-verify-section decides "Figma applied to this run" from the existence of the rendered section, while resolving a per-feature document — but the section lived in a single global slot. Running a feature without a mockup deleted the renders of a feature with one, whose after_* hook then reported not-applicable: fail-open, precisely what the gate exists to prevent. Sections are now scoped per feature, resolved through the same feature identity as the remembered links, so ensure and verify always agree and a wipe only ever touches the current feature.
  • A Windows PAT stored in a default PowerShell SecretStore vault was reported as missing. Such a vault is in password mode: the first Get-Secret of a session opens an interactive prompt, which an agent hook can never answer. The token loaders discarded the command's stderr (2>$null / 2>/dev/null) and fell through to "FIGMA_PAT not found", sending the user back to re-storing a PAT that was already stored correctly. Both loaders now capture the command's own error and print it with the warning, and a SecretStore lookup that fails additionally names the remedy — Set-SecretStoreConfiguration -Authentication None -Interaction None -Confirm:$false, which keeps the secrets encrypted at rest under the Windows user profile (DPAPI) — reporting the vault's observed Authentication/Interaction when it can be read, and staying silent when the vault is already in no-password mode. The bash hint also covers Git Bash/WSL, where Get-Secret is a cmdlet the tokenized exec cannot run at all without a pwsh -NoProfile -NonInteractive -Command wrapper. The one-time Set-SecretStoreConfiguration step is now part of the documented Windows setup (docs/CREDENTIALS.md, README, both installers, /speckit.figma.config, the README block template).
  • The PowerShell port accepted any remembered-links file that parsed, including a JSON object root, where bash requires an array. A hand-edited .figma/cache/links/<feature>.json holding a single object instead of a one-element array was honoured on Windows and ignored everywhere else. The check now reads the JSON root off the text, because ConvertFrom-Json unrolls a one-element array into a bare object and the deserialized shape cannot tell the two apart.

1.7.0 - 2026-08-10

Fixed

  • Node ids are now canonicalized at a single chokepoint (figma_normalize_node_id / ConvertTo-FigmaNodeId), so the URL form Figma puts in deep links can no longer reach a server as-is. Previously figma-parse-links converted only the first separator and required the id to start with a digit, which left nested-instance links (node-id=I123-456%3B789-012) unresolved and could forward a partially normalized id — both surface as "The provided node ID was not found in the file". The extractor now takes the whole node-id value (the &t=… tracking suffix can no longer leak in), normalizes every separator, and reports an unrecognized value as null (broad link → the agent asks which frame) instead of forwarding a bogus id.
  • figma-introspect --node validates and canonicalizes its input before any network call: 12-345 is accepted and queried as 12:345, and a malformed value fails with an explicit error instead of an empty node set.
  • A missing jq no longer breaks the auto-context hook's contract. It used to abort with a bare "'jq' is required but not installed" before emitting any status object, leaving the agent with nothing and pushing it to improvise — typically direct Figma MCP calls with a hand-extracted node id, the very failure above. figma-ensure-context.sh now answers with a jq-free {"ran":false,"reason":"missing-dependency","dependency":"jq",…} on stdout and exits 0, and every figma_require failure prints an install path that works without sudo or a writable Homebrew Cellar.

Added

  • MCP node-id contract in the command prompts (/speckit.figma.introspect section 1b-bis, /speckit.figma.ensure section 2). Passing ids to MCP tools was previously left to the model's own judgement, which made the step model-dependent: agents must now reuse the fileId/nodeId pair produced by parse verbatim, never re-derive an id from a URL, and treat a null nodeId as a broad link.
  • A missing-dependency degraded-mode protocol in /speckit.figma.ensure (section 4) and /speckit.figma.introspect (section 1b-bis): when the helpers cannot run, the agent must apply the node-id normalization steps literally (cut at &/#, decode %3A/%3B, replace every -, validate the shape, pair with the file key of the same URL) and relay the install instructions instead of silently staying degraded.
  • MCP installation instructions for Claude Code and VS Code in the managed README block written by the installer, and a dedicated section in docs/INSTALL.md covering the hosted server, the local Dev Mode server, and a troubleshooting table for "The provided node ID was not found in the file" (including the fact that MCP authenticates separately from the PAT).
  • A jq prerequisite callout — with the admin-free static-binary install — in docs/INSTALL.md, the README requirements and the managed README block.

1.6.0 - 2026-07-07

Added

  • .extensionignore so specify extension add installs a clean copy: the test suites (bats/Pester), CI configuration and repo-only dotfiles are excluded from the installed extension (#9).
  • CHANGELOG.md (this file) and the homepage field in extension.yml, aligning the extension with the Spec Kit extension catalog publishing requirements.

Changed

  • extension.yml: the manifest description was shortened to meet the catalog limit (under 100 characters); the full feature description lives in the README.
  • README: the recommended specify extension add --from URL now points to the latest tagged release archive instead of the main branch, so installs are reproducible and match the published catalog entry.

1.5.0 - 2026-07-03

Changed

  • Updates are standardized as "fetch from the official repository": the /speckit.figma.update flow performs a fresh shallow clone of the official repo (#7).
  • Added an "Updating" section to the managed README block pointing to /speckit.figma.update and the official repository.
  • Install/update documentation revised accordingly.

1.4.0 - 2026-07-02

Added

  • Windows support: PowerShell 7+ ports of every bash helper (scripts/powershell/, 9 scripts) with the same flags, JSON output and exit codes — commands, hooks and CI gates behave identically on macOS, Linux and Windows (#6). Windows needs only pwsh and git (built-in HTTP/JSON: no curl, no jq).
  • New install.ps1: full port of install.sh (managed README/hook blocks, version-coherence check, command-drift detection).
  • New Pester suite (tests/powershell/, 108 tests) plus CI jobs on windows-latest and ubuntu-latest, and PSScriptAnalyzer lint.

Changed

  • Both installers now copy both script families into the workspace (.specify/scripts/bash/ and .specify/scripts/powershell/), so a mixed macOS/Linux/Windows team shares one committed setup.
  • extension.yml tool requirements: git stays required; bash/curl/jq become POSIX-only; pwsh is the Windows alternative.

1.3.0 - 2026-07-02

Added

  • install.sh now copies the user-facing guides (CREDENTIALS.md, INSTALL.md, MONOREPO.md) into the workspace at .figma/docs/, refreshed on every update so they match the installed version (#5).
  • Managed figma section appended to the workspace README.md (created if missing): extension version + layout mode, the read-only Figma PAT setup and links to the local guides. Refreshed in place on re-runs; opt out with --no-readme.

1.2.0 - 2026-07-02

Added

  • Persistent user overlay .figma/figma-design-rules.custom.md: per-project design-rule customizations that survive updates, with local-wins precedence over the extension-owned base (#4).
  • Graceful no-Design-System support: component resolution collapses to reuse → app/lib and token gaps are not raised.

Changed

  • Snapshot/render state moved under a dedicated cache directory (.figma/cache/); the design-rules concept renamed from "memory" to constitution (#3).
  • The shipped base constitution is now universal: mobile-first, Storybook and the CI token-gap trigger moved to the overlay as opt-in defaults.

1.1.0 - 2026-07-02

Added

  • figma-render-section.sh: renders the spec/plan/tasks design sections with every deterministic placeholder pre-filled, so the agent integrates the section regardless of model (#2).
  • before_plan hook and plan-figma-section.template.md.
  • Post-generation verification gate (figma-verify-section.sh, /speckit.figma.verify, after_* hooks) with --strict CI mode.
  • Broad Figma links (file/page-level) detected as linkScope: "broad" with candidateFrames listed for selection.
  • First-class idempotent update flow (/speckit.figma.update).
  • Proxy-vs-auth failure diagnostics and native MCP recommendations for Claude Code / VS Code.

Fixed

  • Documented that project/team introspection requires the projects:read PAT scope, with a scope matrix in docs/CREDENTIALS.md and an actionable 403/404 hint (figma_scope_hint).

1.0.0 - 2026-06-17

Added

  • Initial release: agent-agnostic SpecKit extension grounding spec/plan/tasks generation in Figma design context (#1).
  • Portable REST engine (curl + jq) with optional MCP engine and automatic REST fallback.
  • Single-repo, mono-repo and multi-repo layouts driven by figma.projects.config.json.
  • 3-level component resolution (reuse → create-in-DS → create-in-app) with a purely presentational Design System.
  • bats test suite and shellcheck lint, run in CI.