@hegemonart/get-design-done 1.40.0 → 1.40.5

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "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).",
-    "version": "1.40.0"
+    "version": "1.40.5"
   },
   "plugins": [
     {
       "name": "get-design-done",
       "source": "./",
       "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.",
-      "version": "1.40.0",
+      "version": "1.40.5",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.40.0",
+  "version": "1.40.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).",
   "author": {
     "name": "hegemonart",

package/CHANGELOG.md

@@ -4,6 +4,36 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.40.5] - 2026-06-01
+
+### Phase 40.5 — GDD CLI Localization
+
+GDD's README is multilingual, but the CLI talked English. 40.5 adds locale resolution + per-locale
+message tables for the highest-traffic surface — `--help`, common error messages, and skill prompt
+headers. English is always the final fallback, so a partial locale never breaks the CLI. **No new
+runtime dependency, no new egress.**
+
+### Added
+
+- **`scripts/lib/i18n/index.cjs`** — locale resolver: `resolveLocale` (`config.locale` > env `LANG`/`LC_ALL` > `en`), `fallbackChain` (`locale → base → en`), `translate` (chain walk; a missing key returns the key, never throws), `descriptionFor` (`description_i18n` || English). Pure functions + a thin `loadTable` reader.
+- **`scripts/lib/i18n/messages/{en,ru,uk,de,fr,zh,ja}.json`** — flat message tables. `en` is the complete source (24 keys: `help.*`/`error.*`/`prompt.*`/`status.*`), `ru` a full translation, `uk`/`de`/`fr`/`zh`/`ja` placeholders (a `_meta` marker + a starter subset) that fall back to English.
+- **`skills/locale/SKILL.md`** (`/gdd:locale [<code>]`) — inspect the resolved locale + per-locale coverage, or set `.design/config.json#locale`.
+- **`reference/cli-localization.md`** — the resolver contract + the add-a-locale contribution path (translate the table, add a `NOTICE` translator credit, open a PR; warn-only completeness). Registered. Distinct from `reference/i18n.md` (which covers *user-design* i18n).
+
+### Changed
+
+- **`reference/schemas/config.schema.json`** — + `locale` (enum en/ru/uk/de/fr/zh/ja); `generated.d.ts` regenerated.
+- **`agents/README.md`** — document the opt-in `description_i18n` frontmatter field (falls back to the English `description`; backward-compatible — the 28.5 contract validates it only when present).
+
+### Notes
+
+- **No new runtime dependency, no new egress.** Pure resolver + JSON tables + docs.
+- The completeness gate is **warn-only** — only `en` + `ru` are full; the five placeholder locales rely on the English fallback and are never required to be 100%.
+- 6-manifest lockstep at **v1.40.5** + `OFF_CADENCE_VERSIONS.add('1.40.5')` + the 34 live-pinned `manifests-version.txt` baselines forward-propagated 1.40.0 → 1.40.5.
+- Inventory relock: registry-diff 159 → 160 (+`cli-localization`), skill-list 82 → 83 (+`locale`), skill-length-distribution relocked, tarball golden 721 → 731 (+10). No agent/event deltas. Root `SKILL.md` command table += `locale`.
+
+---
+
 ## [1.40.0] - 2026-06-01
 
 ### Phase 40 — Team Collaboration Mode

package/README.md

@@ -194,6 +194,10 @@ GDD migrates *your* design systems (above) — now it migrates **itself**. When
 
 GDD's single-operator baseline now extends to **teams** — git-native + advisory, no server. Two developers working a cycle on parallel branches merge their `.design/STATE.md` **per section** ([`section-merge`](scripts/lib/collab/section-merge.cjs) unions decisions by `D-id`; a real conflict is only a same-id divergence, which [`conflict-resolver`](agents/conflict-resolver.md) reconciles with human confirmation — never auto-picking or dropping a decision). Decisions carry optional `[author= co-author=]` attribution, move through an async review queue (`proposed → reviewing → approved → locked`) with **hard locks** (the only escape is an audited [`/gdd:unlock-decision`](skills/unlock-decision/SKILL.md)), and [`/gdd:review-decisions`](skills/review-decisions/SKILL.md) surfaces what's pending. [`decision-journal-exporter`](agents/decision-journal-exporter.md) publishes a **pseudonymized, read-only** Notion/Confluence journal for stakeholders who don't run GDD. `gdd_cycle_mode` (designer/dev/full) partitions a cycle by role, a `permissions` model gates per-section writes, and `collab.multi_writer_enabled` switches the advisory lock to a team-mode backoff. The full contract: [`reference/multi-author-model.md`](reference/multi-author-model.md). **Everything is off by default** — a single-operator project is unaffected. **No new runtime dependency.**
 
+### CLI localization (v1.40.5)
+
+GDD's README is multilingual — now its **CLI** is too. [`/gdd:locale <code>`](skills/locale/SKILL.md) sets the language of `--help`, common error messages, and skill prompt headers, resolved by [`scripts/lib/i18n`](scripts/lib/i18n/index.cjs) (precedence: `config.locale` > env `LANG` > `en`; fallback chain `locale → base → en`). Flat-JSON message tables ship for **en** (complete source), **ru** (full), and **uk/de/fr/zh/ja** placeholders — a missing key always falls back to English, so a partial locale never breaks the CLI. Skills + agents can carry an opt-in `description_i18n` map. Adding a locale is a PR: translate the table, add a `NOTICE` credit (the contribution path is in [`reference/cli-localization.md`](reference/cli-localization.md)). Completeness is **warn-only**. **No new runtime dependency.**
+
 ### Previous releases
 
 - **v1.26.0** — Headless Model Resolver (per-runtime tier→model map, `resolved_models` router field, per-runtime price tables, `reasoning-class` runtime-neutral alias).

package/SKILL.md

@@ -107,6 +107,7 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `migrate [--yes] [--dry-run]` | `get-design-done:gdd-migrate` | Phase 39.5 — migrate a project off GDD's own deprecated paths after an upgrade; reads `reference/DEPRECATIONS.md` via `deprecation-registry.cjs`, previews a diff, applies on confirm. Preview-first; never edits silently |
 | `review-decisions [<id>] [--pending]` | `get-design-done:gdd-review-decisions` | Phase 40 — surface the async decision-review queue (`proposed → reviewing → approved → locked`); `--pending` shows decisions still awaiting action. Read-only |
 | `unlock-decision <id> --approver <who> [--reason <text>] [--dry-run]` | `get-design-done:gdd-unlock-decision` | Phase 40 — reopen a LOCKED decision (the only escape hatch); requires an approver + writes an audit entry; previews before writing |
+| `locale [<code>]` | `get-design-done:gdd-locale` | Phase 40.5 — inspect or set the GDD CLI locale (en/ru/uk/de/fr/zh/ja) for `--help`, errors, and skill prompt headers; missing keys fall back to English. No arg reports the resolved locale + coverage |
 
 ## Handoff Routing
 

package/agents/README.md

@@ -39,6 +39,7 @@ Every agent file begins with a YAML frontmatter block. All fields except `model`
 |-------|------|-----------------|---------|
 | `name` | kebab-case string | unique within plugin | Identifier passed to the `Task` tool — must match the filename without `.md` |
 | `description` | string | free-form | One sentence: what the agent does + when it is spawned |
+| `description_i18n` | object | `{ <locale>: "<description>" }` | **Phase 40.5, opt-in.** Localized descriptions keyed by locale (en/ru/uk/de/fr/zh/ja). `scripts/lib/i18n/index.cjs` `descriptionFor(frontmatter, locale)` resolves it via the fallback chain and falls back to the English `description` when a locale is absent. Backward-compatible — omit it and nothing changes. |
 | `tools` | comma-separated list | `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`, `Task`, `WebFetch`, `TodoWrite`, `mcp__*` | Claude tools the agent may use — list only what is needed |
 | `color` | enum | `yellow`, `green`, `blue`, `red` | Terminal display color for the agent's output |
 | `model` | enum (optional) | `inherit`, `sonnet`, `haiku` | Omit to use the project's configured profile default. Use `inherit` to bypass the profile and use the highest available model (quality-tier work) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.40.0",
+  "version": "1.40.5",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",

package/reference/cli-localization.md

@@ -0,0 +1,61 @@
+# CLI Localization — GDD's Own Surface
+
+Phase 40.5 contract. `reference/i18n.md` covers internationalizing *user designs*; this file covers
+**GDD's own CLI** — `--help`, the common error messages, and skill prompt headers. The goal is the
+lowest-effort, highest-impact subset; full skill-body translation is deferred (per-locale demand).
+
+## Resolution
+
+`scripts/lib/i18n/index.cjs` resolves the active locale with this precedence:
+
+1. **`.design/config.json#locale`** — an explicit per-project override (set via `/gdd:locale <code>`).
+2. **`process.env`** — `LC_ALL` / `LC_MESSAGES` / `LANG` / `LANGUAGE` (normalized: `ru_RU.UTF-8` → `ru`).
+3. **`en`** — the default.
+
+A `C` / `POSIX` env locale resolves to `en`. The resolved code then drives a **fallback chain**
+`locale → base → en` (e.g. `de-DE → de → en`), so a regional locale degrades to its base and finally
+to English — the complete source table.
+
+## Message tables
+
+Flat-JSON tables live at `scripts/lib/i18n/messages/<locale>.json` (chosen over ICU MessageFormat for
+simplicity). Each is `{ "_meta": { locale, coverage, fallback }, "<key>": "<string>", ... }`. Keys are
+namespaced: `help.*` (usage + section headers), `error.*` (the common CLI errors), `prompt.*` (skill
+prompt headers), `status.*`.
+
+- **`en.json`** — the **complete source of truth**; every key lives here.
+- **`ru.json`** — a complete second-locale translation (covers every `en` key).
+- **`uk.json` / `de.json` / `fr.json` / `zh.json` / `ja.json`** — **placeholders**: a `_meta` marker
+  (`coverage: "placeholder"`) plus a starter subset. Any missing key falls back to `en` per the chain.
+
+`translate(tables, key, locale)` walks the chain and returns the first hit, or the key itself if no
+table has it (a missing key is always visible, never a crash).
+
+## Frontmatter `description_i18n`
+
+Skills and agents may carry an **opt-in** `description_i18n: { <locale>: "<description>" }` map.
+`descriptionFor(frontmatter, locale)` returns the localized description via the fallback chain, or the
+plain English `description` when the locale is absent. The field is fully backward-compatible — a
+skill/agent without it is unaffected, and the Phase 28.5 contract only validates it (as an object of
+locale→string) when present.
+
+## Completeness policy
+
+The completeness gate is **warn-only**. Only `en` (source) and `ru` (full) are expected to be 100%; the
+five placeholder locales are intentionally partial and rely on the English fallback. A locale is never
+required to be complete to ship — partial is better than English-only, and fallback guarantees no key
+is ever missing at runtime.
+
+## Adding or completing a locale (contribution path)
+
+1. Edit `scripts/lib/i18n/messages/<locale>.json` — add the keys you can translate (any `en` key is
+   fair game; you do not need 100%).
+2. Set `_meta.coverage` to `"complete"` once every `en` key is present, else leave `"placeholder"`.
+3. Add a translator-credit line to `NOTICE` under the attributions section (name/handle + locale).
+4. Open a PR. The warn-only gate reports coverage; it does not block on partial locales.
+
+## Boundaries
+
+`--help` + common errors + skill prompt headers only — not full skill bodies (deferred per demand),
+not RTL terminal rendering (a terminal concern), not voice/conversational localization. English is
+always the final fallback, so the CLI is never broken by a partial translation.

package/reference/config-schema.md

@@ -395,3 +395,11 @@ single-operator projects are unaffected. Full contract: `reference/multi-author-
   team-mode policy (`scripts/lib/collab/lock-policy.cjs` — 30 s wait + 100 ms backoff);
   `sync_backend` selects the cross-machine `.design/` backend (`scripts/lib/collab/sync-backend.cjs`,
   default `git`; `s3`/`git-lfs` are opt-in declarations — a live client is not bundled this phase).
+
+## CLI localization (Phase 40.5)
+
+- **`locale`** (`en`|`ru`|`uk`|`de`|`fr`|`zh`|`ja`) — overrides the language of GDD's own `--help`,
+  common error messages, and skill prompt headers. Set via `/gdd:locale <code>`. Precedence: this key >
+  env `LANG`/`LC_ALL` > `en`. Missing message keys fall back to English (`scripts/lib/i18n/index.cjs`,
+  chain `locale → base → en`); `en` + `ru` are complete, the other five are placeholders. Full
+  contract: `reference/cli-localization.md`.

package/reference/registry.json

@@ -1035,6 +1035,13 @@
       "type": "meta-rules",
       "phase": 40,
       "description": "Phase 40 team-collaboration contract: multi-writer STATE.md via a git-merge-driver with per-section semantic merge (scripts/lib/collab/section-merge.cjs — union by D-id, conflict only on same-id divergence); decision attribution line-suffix [author= co-author=] (attribution.cjs); the async review queue proposed->reviewing->approved->locked with hard locks + audited /gdd:unlock-decision (review-queue.cjs); the multi-writer advisory-lock policy (lock-policy.cjs, 30s/100ms backoff in team mode); sectional handoff gdd_cycle_mode designer|dev|full (cycle-mode.cjs); the permission model (permissions.cjs) + CI gate; decision-journal-exporter (pseudonymized, write-only Notion) + pr-commenter D-XX threading; opt-in cross-machine sync (sync-backend.cjs, defaults to git). Agents conflict-resolver + decision-journal-exporter; skills /gdd:review-decisions + /gdd:unlock-decision."
+    },
+    {
+      "name": "cli-localization",
+      "path": "reference/cli-localization.md",
+      "type": "meta-rules",
+      "phase": 40.5,
+      "description": "Phase 40.5 CLI-localization contract: locale resolution (config.locale > env LANG > en) + fallback chain locale->base->en + flat-JSON message tables via scripts/lib/i18n/index.cjs; tables at scripts/lib/i18n/messages/{en,ru,uk,de,fr,zh,ja}.json (en source-complete, ru full, 5 placeholders with en fallback); the opt-in description_i18n frontmatter (descriptionFor falls back to English); /gdd:locale skill; warn-only completeness; the add-a-locale contribution path (translate table + NOTICE credit + PR). Distinct from reference/i18n.md (which covers USER-design i18n)."
     }
   ]
 }

package/reference/schemas/config.schema.json

@@ -41,6 +41,11 @@
       "type": "string",
       "description": "Latest plugin tag (e.g. \"v1.0.7.3\") whose update nudge the user has dismissed. Set by /gdd:check-update --dismiss and by hooks/update-check.sh on the --dismiss code path. When a newer tag ships, the nudge reappears."
     },
+    "locale": {
+      "type": "string",
+      "enum": ["en", "ru", "uk", "de", "fr", "zh", "ja"],
+      "description": "Phase 40.5 CLI locale override for GDD's own --help, error messages, and skill prompt headers. Set via /gdd:locale <code>. Precedence: this key > env LANG/LC_ALL > en. Missing message keys fall back to English per scripts/lib/i18n/index.cjs (locale -> base -> en). en + ru are complete; uk/de/fr/zh/ja are placeholders that fall back to English."
+    },
     "gdd_cycle_mode": {
       "type": "string",
       "enum": ["designer", "dev", "full"],

package/reference/schemas/generated.d.ts

@@ -101,6 +101,10 @@ export interface DesignConfigJson {
    * Latest plugin tag (e.g. "v1.0.7.3") whose update nudge the user has dismissed. Set by /gdd:check-update --dismiss and by hooks/update-check.sh on the --dismiss code path. When a newer tag ships, the nudge reappears.
    */
   update_dismissed?: string;
+  /**
+   * Phase 40.5 CLI locale override for GDD's own --help, error messages, and skill prompt headers. Set via /gdd:locale <code>. Precedence: this key > env LANG/LC_ALL > en. Missing message keys fall back to English per scripts/lib/i18n/index.cjs (locale -> base -> en). en + ru are complete; uk/de/fr/zh/ja are placeholders that fall back to English.
+   */
+  locale?: 'en' | 'ru' | 'uk' | 'de' | 'fr' | 'zh' | 'ja';
   /**
    * Phase 40 sectional handoff. designer = Brief + Explore only; dev = Plan + Design + Verify; full = all stages (default). scripts/lib/collab/cycle-mode.cjs gates STATE writes by stage so a designer and a dev can hand a cycle back and forth without overwriting each other's sections.
    */

package/scripts/lib/i18n/index.cjs

@@ -0,0 +1,95 @@
+'use strict';
+// Phase 40.5 — i18n/index.cjs — GDD CLI localization resolver.
+//
+// Resolves a locale (config override > env LANG > English), a fallback chain (locale → base → en),
+// and translates a message key against per-locale flat-JSON tables. The pure functions (baseLocale,
+// fallbackChain, resolveLocale, translate, descriptionFor) take their data as arguments and touch
+// neither fs nor env directly — so they are trivially unit-testable. `loadTable` is the only fs reader.
+//
+// Contract: reference/cli-localization.md. Fallback is always to `en` (the complete source table).
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const KNOWN_LOCALES = Object.freeze(['en', 'ru', 'uk', 'de', 'fr', 'zh', 'ja']);
+const DEFAULT_LOCALE = 'en';
+const MESSAGES_DIR = path.join(__dirname, 'messages');
+
+/** Normalize a raw locale token: lowercase, `_`→`-`, strip an encoding suffix (`ru_RU.UTF-8` → `ru-ru`). */
+function normalizeLocale(code) {
+  if (!code) return '';
+  return String(code).split('.')[0].split(':')[0].trim().toLowerCase().replace(/_/g, '-');
+}
+
+/** The base of a locale (`de-de` → `de`; `en` → `en`). */
+function baseLocale(code) {
+  return normalizeLocale(code).split('-')[0];
+}
+
+/** Resolution chain: [normalized, base, 'en'] with duplicates removed. */
+function fallbackChain(code) {
+  const norm = normalizeLocale(code);
+  const chain = [];
+  for (const c of [norm, baseLocale(norm), DEFAULT_LOCALE]) {
+    if (c && !chain.includes(c)) chain.push(c);
+  }
+  return chain.length ? chain : [DEFAULT_LOCALE];
+}
+
+/**
+ * Resolve the active locale. Precedence: explicit config.locale > env.LANG/LC_ALL > 'en'.
+ * @param {{env?: object, configLocale?: string}} [opts]
+ */
+function resolveLocale(opts) {
+  const o = opts || {};
+  const fromConfig = normalizeLocale(o.configLocale);
+  if (fromConfig) return fromConfig;
+  const env = o.env || {};
+  const fromEnv = normalizeLocale(env.LC_ALL || env.LC_MESSAGES || env.LANG || env.LANGUAGE);
+  if (fromEnv && fromEnv !== 'c' && fromEnv !== 'posix') return fromEnv;
+  return DEFAULT_LOCALE;
+}
+
+/**
+ * Translate `key` for `locale` against the supplied `tables` map ({ <locale>: {<key>: <string>} }).
+ * Walks the fallback chain; returns the first hit, else the key itself (so a missing key is visible,
+ * never throws).
+ */
+function translate(tables, key, locale) {
+  const map = tables || {};
+  for (const loc of fallbackChain(locale)) {
+    const t = map[loc];
+    if (t && Object.prototype.hasOwnProperty.call(t, key) && typeof t[key] === 'string') return t[key];
+  }
+  return key;
+}
+
+/**
+ * Resolve a skill/agent description for `locale`: frontmatter.description_i18n[<chain>] || .description.
+ * Opt-in + backward-compatible — absent description_i18n falls straight back to the English description.
+ */
+function descriptionFor(frontmatter, locale) {
+  const fm = frontmatter || {};
+  const i18n = fm.description_i18n;
+  if (i18n && typeof i18n === 'object') {
+    for (const loc of fallbackChain(locale)) {
+      if (typeof i18n[loc] === 'string' && i18n[loc].trim()) return i18n[loc];
+    }
+  }
+  return fm.description || '';
+}
+
+/** Read a locale's flat-JSON table from disk. Returns {} on missing/parse error (fail-safe → fallback). */
+function loadTable(locale, dir) {
+  const file = path.join(dir || MESSAGES_DIR, `${normalizeLocale(locale) || DEFAULT_LOCALE}.json`);
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+module.exports = {
+  KNOWN_LOCALES, DEFAULT_LOCALE, MESSAGES_DIR,
+  normalizeLocale, baseLocale, fallbackChain, resolveLocale, translate, descriptionFor, loadTable,
+};

package/scripts/lib/i18n/messages/de.json

@@ -0,0 +1,7 @@
+{
+  "_meta": { "locale": "de", "coverage": "placeholder", "fallback": "en" },
+  "help.tagline": "Eine Design-Qualitäts-Pipeline für KI-Coding-Agenten.",
+  "status.complete": "Fertig.",
+  "status.in_progress": "In Bearbeitung.",
+  "status.blocked": "Blockiert."
+}

package/scripts/lib/i18n/messages/en.json

@@ -0,0 +1,27 @@
+{
+  "_meta": { "locale": "en", "coverage": "complete", "fallback": null },
+  "help.usage": "Usage: gdd <command> [options]",
+  "help.tagline": "A design-quality pipeline for AI coding agents.",
+  "help.commands_header": "Commands",
+  "help.options_header": "Options",
+  "help.more": "Run `gdd help <command>` for details on a command.",
+  "help.pipeline": "Pipeline: brief -> explore -> plan -> design -> verify",
+  "error.no_state": "No .design/STATE.md found. Run /gdd:start to initialize a cycle.",
+  "error.no_config": "No .design/config.json found; using defaults.",
+  "error.stage_locked": "This stage is locked under the current cycle mode.",
+  "error.permission_denied": "Permission denied: your role cannot perform this action on this section.",
+  "error.budget_cap": "Budget cap reached. Raise the cap in .design/budget.json or wait for the next task.",
+  "error.connection_unavailable": "Connection unavailable. Configure it via /gdd:connections.",
+  "error.invalid_locale": "Unknown locale. Known locales: en, ru, uk, de, fr, zh, ja.",
+  "error.merge_conflict": "STATE.md has a merge conflict. Run the conflict-resolver to reconcile per section.",
+  "error.decision_locked": "This decision is locked. Use /gdd:unlock-decision <id> --approver <who> to reopen it.",
+  "error.no_telemetry": "No cost telemetry yet. Run a cycle first.",
+  "prompt.brief_header": "Stage 1 of 5 - Brief: capture the problem, audience, constraints, and metrics.",
+  "prompt.explore_header": "Stage 2 of 5 - Explore: inventory the design surface and interview for intent.",
+  "prompt.plan_header": "Stage 3 of 5 - Plan: decompose the work into tasks.",
+  "prompt.design_header": "Stage 4 of 5 - Design: execute the plan.",
+  "prompt.verify_header": "Stage 5 of 5 - Verify: score and audit against the design system.",
+  "status.complete": "Complete.",
+  "status.in_progress": "In progress.",
+  "status.blocked": "Blocked."
+}

package/scripts/lib/i18n/messages/fr.json

@@ -0,0 +1,7 @@
+{
+  "_meta": { "locale": "fr", "coverage": "placeholder", "fallback": "en" },
+  "help.tagline": "Un pipeline de qualité de conception pour les agents de codage IA.",
+  "status.complete": "Terminé.",
+  "status.in_progress": "En cours.",
+  "status.blocked": "Bloqué."
+}

package/scripts/lib/i18n/messages/ja.json

@@ -0,0 +1,7 @@
+{
+  "_meta": { "locale": "ja", "coverage": "placeholder", "fallback": "en" },
+  "help.tagline": "AI コーディングエージェントのためのデザイン品質パイプライン。",
+  "status.complete": "完了。",
+  "status.in_progress": "進行中。",
+  "status.blocked": "ブロック中。"
+}

package/scripts/lib/i18n/messages/ru.json

@@ -0,0 +1,27 @@
+{
+  "_meta": { "locale": "ru", "coverage": "complete", "fallback": "en" },
+  "help.usage": "Использование: gdd <команда> [параметры]",
+  "help.tagline": "Конвейер качества дизайна для ИИ-агентов программирования.",
+  "help.commands_header": "Команды",
+  "help.options_header": "Параметры",
+  "help.more": "Выполните `gdd help <команда>` для подробностей о команде.",
+  "help.pipeline": "Конвейер: brief -> explore -> plan -> design -> verify",
+  "error.no_state": "Файл .design/STATE.md не найден. Выполните /gdd:start, чтобы инициализировать цикл.",
+  "error.no_config": "Файл .design/config.json не найден; используются значения по умолчанию.",
+  "error.stage_locked": "Этот этап заблокирован в текущем режиме цикла.",
+  "error.permission_denied": "Доступ запрещён: ваша роль не может выполнить это действие в этом разделе.",
+  "error.budget_cap": "Достигнут лимит бюджета. Увеличьте лимит в .design/budget.json или дождитесь следующей задачи.",
+  "error.connection_unavailable": "Подключение недоступно. Настройте его через /gdd:connections.",
+  "error.invalid_locale": "Неизвестная локаль. Доступные локали: en, ru, uk, de, fr, zh, ja.",
+  "error.merge_conflict": "В STATE.md конфликт слияния. Запустите conflict-resolver для согласования по разделам.",
+  "error.decision_locked": "Это решение заблокировано. Используйте /gdd:unlock-decision <id> --approver <кто>, чтобы открыть его повторно.",
+  "error.no_telemetry": "Телеметрия затрат пока отсутствует. Сначала выполните цикл.",
+  "prompt.brief_header": "Этап 1 из 5 - Brief: зафиксируйте задачу, аудиторию, ограничения и метрики.",
+  "prompt.explore_header": "Этап 2 из 5 - Explore: исследуйте поверхность дизайна и уточните намерение.",
+  "prompt.plan_header": "Этап 3 из 5 - Plan: разбейте работу на задачи.",
+  "prompt.design_header": "Этап 4 из 5 - Design: выполните план.",
+  "prompt.verify_header": "Этап 5 из 5 - Verify: оцените и проверьте по дизайн-системе.",
+  "status.complete": "Готово.",
+  "status.in_progress": "В процессе.",
+  "status.blocked": "Заблокировано."
+}

package/scripts/lib/i18n/messages/uk.json

@@ -0,0 +1,7 @@
+{
+  "_meta": { "locale": "uk", "coverage": "placeholder", "fallback": "en" },
+  "help.tagline": "Конвеєр якості дизайну для ШІ-агентів програмування.",
+  "status.complete": "Готово.",
+  "status.in_progress": "У процесі.",
+  "status.blocked": "Заблоковано."
+}

package/scripts/lib/i18n/messages/zh.json

@@ -0,0 +1,7 @@
+{
+  "_meta": { "locale": "zh", "coverage": "placeholder", "fallback": "en" },
+  "help.tagline": "面向 AI 编码代理的设计质量流水线。",
+  "status.complete": "完成。",
+  "status.in_progress": "进行中。",
+  "status.blocked": "已阻塞。"
+}

package/skills/locale/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: gdd-locale
+description: "Inspects or sets the GDD CLI locale for this project. With no argument, reports the resolved locale (config.locale > env LANG > en), the fallback chain, and per-locale coverage (which message tables are complete vs placeholder). With a <code> (en/ru/uk/de/fr/zh/ja), sets .design/config.json#locale after previewing the change. Localizes --help, common error messages, and skill prompt headers via scripts/lib/i18n/; missing keys fall back to English, so a partial locale never breaks the CLI. Use to switch GDD's own output language."
+argument-hint: "[<code>]"
+user-invocable: true
+tools: Read, Write, Bash, Grep, Glob
+---
+
+# /gdd:locale
+
+Closes the English-only CLI gap: GDD's README is multilingual, but `--help`, errors, and skill prompt
+headers spoke English until now. This skill inspects or sets the project's locale. Contract:
+`../../reference/cli-localization.md`.
+
+## Invocation
+
+| Command | Behavior |
+|---|---|
+| `/gdd:locale` | Report the resolved locale, the fallback chain, and per-locale coverage. |
+| `/gdd:locale <code>` | Set `.design/config.json#locale` to `<code>` (en/ru/uk/de/fr/zh/ja), after preview. |
+
+## Steps
+
+1. **Resolve current.** Read `.design/config.json#locale` (if any) and the environment, then call the
+   resolver to report the active locale + chain:
+
+   ```bash
+   node -e '
+     const i = require("./scripts/lib/i18n/index.cjs");
+     let cfg = {}; try { cfg = JSON.parse(require("fs").readFileSync(".design/config.json","utf8")); } catch {}
+     const loc = i.resolveLocale({ env: process.env, configLocale: cfg.locale });
+     const cov = i.KNOWN_LOCALES.map((l) => `${l}:${(i.loadTable(l)._meta||{}).coverage||"?"}`).join("  ");
+     console.log(JSON.stringify({ resolved: loc, chain: i.fallbackChain(loc), coverage: cov }));
+   '
+   ```
+
+2. **No argument** → print the resolved locale, the fallback chain, and the coverage line (which
+   tables are `complete` vs `placeholder`). Stop.
+3. **`<code>` argument** → validate it is in `KNOWN_LOCALES` (en/ru/uk/de/fr/zh/ja). Unknown → print the
+   `error.invalid_locale` message + the known list, change nothing.
+4. **Preview + set.** Show `locale: <old> -> <code>`, then write `locale` into `.design/config.json`
+   (create the file if absent, preserving any existing keys). Confirm, and note that missing keys in a
+   placeholder locale fall back to English.
+
+## Output
+
+End with:
+
+```
+## LOCALE COMPLETE
+```