@hegemonart/get-design-done 1.19.6 → 1.21.0

package/reference/error-recovery.md

@@ -0,0 +1,58 @@
+# Error recovery
+
+This is the recovery-action protocol for low-level errors inside the GDD pipeline. It sits on top of `scripts/lib/error-classifier.cjs` (Plan 20-14) and references the rate-guard, jittered-backoff, and iteration-budget primitives.
+
+## Recovery protocol
+
+On `status=413` or `context_overflow`, re-emit with compressed context (drop oldest non-system turns, target 50% reduction, retry once).
+
+On `status=429`, consult `scripts/lib/rate-guard.cjs` → `blockUntilReady(provider)` before retry.
+
+On network-transient (5xx, ECONNRESET), use jittered backoff (`scripts/lib/jittered-backoff.cjs`); max 3 retries.
+
+On auth-error, surface to user — do not retry.
+
+## Recovery-action table
+
+The `FailoverReason` enum in `scripts/lib/error-classifier.cjs` has eight values. Each row below is the canonical recovery action for one of those values. The classifier's `suggestedAction` field returns a one-liner drawn from this table; this doc is the authoritative long form.
+
+| FailoverReason      | Retryable | Action                                                                                                                                                     |
+| ------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rate_limited`      | yes       | Call `rate-guard.ingestHeaders(provider, response.headers)` to record the rate-limit signal, then `rate-guard.blockUntilReady(provider)` before retrying. The blocker waits until `resetAt` on disk — synchronized siblings (watch-authorities + update-check) therefore share the backoff boundary. After the block returns, retry with jittered backoff at attempt 0. |
+| `context_overflow`  | yes       | Compress context — drop the oldest non-system turns (or the oldest attachments) targeting roughly 50 % token reduction. Retry **once** with the compressed payload. If the retry also raises `context_overflow`, escalate to the user as an unrecoverable block — further compression destroys information. |
+| `auth_error`        | no        | Surface the error to the user with actionable text: which credential, which provider, and the renewal path (OAuth re-auth URL, API-key environment variable, etc.). Do not retry automatically — a loop would just multiply the failure. |
+| `network_transient` | yes       | Retry with `scripts/lib/jittered-backoff.cjs` — `await sleep(attempt)` inside a bounded loop. Cap at 3 attempts before giving up. When retries exhaust, reclassify as `network_permanent` and surface to the user. |
+| `network_permanent` | no        | Surface to user. The endpoint is wrong, DNS is broken, or the resource was removed. A retry without operator action will just re-fail. |
+| `tool_not_found`    | no        | Surface to user. Either the tool name drifted (common for MCP servers whose prefixes change across sessions) or the MCP is not registered. Reprobe via the connection's probe sequence before retrying anything. |
+| `validation`        | no        | Surface the validation detail to the caller. Do not retry the same input — 4xx is the server saying "your payload is wrong". Fixing the payload is caller work. |
+| `unknown`           | no        | Surface the raw error to the user. Do not retry — we can't tell whether it's safe. Add a telemetry row so we can tighten the classifier over time. |
+
+## Integration points
+
+| Caller                    | When to classify                             | What to do with `reason`                                                                                           |
+| ------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `hooks/budget-enforcer.ts` | pre-spawn rate-guard check (Plan 20-14)      | If upstream state already shows `rate_limited`, emit `decision: 'rate-limited'` and short-circuit before any spawn. |
+| Figma MCP probe           | live `get_metadata` call errors              | `network_transient` → jittered-backoff retry. `auth_error` → STOP with a reauth note. `rate_limited` → block then retry. |
+| Watch-authorities fetcher | per-feed HTTP fetch                          | Same policy as Figma probe; `validation` also possible on ETag stalemate (304). |
+| Update-check HTTP curl    | GitHub `releases/latest` fetch               | Silent failure by D-04 of Plan 13.3 — classify but don't surface; log and exit 0. |
+| MCP transport             | tool-call errors (gdd-state, figma, 21st-dev)| Map `tool_not_found` to a probe-reissue; map `auth_error` to STOP; retry transient classes via the caller's own loop. |
+
+## Fix-loop iteration interaction
+
+Retries consume iteration budget when paired with the Layer-B cache:
+
+1. On cache hit, `iteration-budget.refund(1)` preserves the iteration that would otherwise have been spent.
+2. On each actual retry that does real work (no cache hit), the caller `iteration-budget.consume(1)` before the spawn.
+3. When the budget's `remaining === 0`, further retries throw `IterationBudgetExhaustedError` and the caller must surface to user — a retry cycle has become pathological.
+
+This protects the "infinite fix loop" case — a blocker that regenerates after every fix — from burning unbounded context.
+
+## Telemetry
+
+Every classification result that leads to a retry or a surfaced error should append an event to `.design/telemetry/events.jsonl`:
+
+```json
+{ "type": "error.classified", "timestamp": "…", "sessionId": "…", "payload": { "reason": "rate_limited", "retryable": true, "caller": "figma-probe" } }
+```
+
+The event subtype is defined in `scripts/lib/event-stream/types.ts`. Consumers (`gdd-reflector`, dashboard) aggregate by `reason` to detect classifier drift — if `unknown` spikes, the classifier needs tightening.

package/reference/gemini-tools.md

@@ -0,0 +1,53 @@
+# Gemini CLI Tool Map
+
+Last verified: 2026-04-24
+
+When a GDD skill references a Claude Code tool name, the Gemini runtime
+translates to the equivalent below. Skills do NOT need to branch — the tool
+name in prose is authoritative; Gemini resolves via this map.
+
+## Tool-name mapping
+
+| CC name | Gemini name | Notes |
+| --- | --- | --- |
+| `Read` | `read_file` | Takes `absolute_path`. |
+| `Write` | `write_file` | Takes `path`, `content`; overwrites. |
+| `Edit` | `replace` | Takes `file_path`, `old_string`, `new_string`. Semantics match CC. |
+| `Bash` | `run_shell_command` | Takes `{command: string, directory?}`. |
+| `Grep` | `search_file_content` | Native grep wrapper. |
+| `Glob` | `glob` | Native glob wrapper. |
+| `Task` | Sub-invocation via nested gemini CLI | Same gap as Codex. |
+| `WebSearch` | `google_web_search` | Built-in. |
+| `WebFetch` | `web_fetch` | Built-in. |
+
+## MCP server `gdd-state`
+
+The gdd-state MCP server works unchanged on Gemini. Configure Gemini to load
+it by adding to `~/.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "gdd-state": {
+      "command": "node",
+      "args": ["--experimental-strip-types", "<pkg-root>/scripts/mcp-servers/gdd-state/server.ts"]
+    }
+  }
+}
+```
+
+All 11 tools exposed by the server appear as `mcp__gdd_state__*` in Gemini.
+
+## Known gaps
+
+- `Task` spawning: same as Codex — prefer `run_shell_command("npx gdd-sdk stage ...")`.
+  See GEMINI.md for invocation details.
+- Gemini's `replace` has stricter uniqueness requirements than CC's Edit;
+  when `old_string` appears more than once, Gemini requires context lines.
+  Skill prose that calls Edit should include surrounding context in
+  `old_string` to satisfy both harnesses.
+
+---
+
+Last verified: 2026-04-24 — tool surface re-checked against Gemini CLI docs
+current to this date. Revisit whenever Gemini ships a tool-vocabulary change.

package/reference/registry.json

@@ -3,6 +3,27 @@
   "version": 1,
   "generated_at": "2026-04-24T00:00:00.000Z",
   "entries": [
+    {
+      "name": "codex-tools",
+      "path": "reference/codex-tools.md",
+      "type": "meta-rules",
+      "phase": 21,
+      "description": "Phase 21 cross-harness tool map — Claude Code → OpenAI Codex CLI tool-name equivalents for the gdd-sdk runner (Read→read_file, Write/Edit→apply_patch, Bash→shell, etc.)"
+    },
+    {
+      "name": "gemini-tools",
+      "path": "reference/gemini-tools.md",
+      "type": "meta-rules",
+      "phase": 21,
+      "description": "Phase 21 cross-harness tool map — Claude Code → Gemini CLI tool-name equivalents for the gdd-sdk runner"
+    },
+    {
+      "name": "error-recovery",
+      "path": "reference/error-recovery.md",
+      "type": "meta-rules",
+      "phase": 20,
+      "description": "Phase 20 resilience recovery protocol — rate-limit + 429 + context-overflow retry guidance for the SDK runner (jittered-backoff / rate-guard / error-classifier / iteration-budget integration)"
+    },
     {
       "name": "component-authoring",
       "path": "reference/component-authoring.md",

package/reference/schemas/budget.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://get-design-done.example/schemas/budget.schema.json",
+  "title": ".design/budget.json",
+  "description": "Shape of .design/budget.json — the Phase 10.1 optimization-layer budget governance file. Consumed by hooks/budget-enforcer.ts on every PreToolUse:Agent spawn. Bootstrap writes the Default Config from reference/config-schema.md if the file is missing.",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "per_task_cap_usd": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Hard ceiling per agent spawn (USD). Breach under enforcement_mode=enforce triggers D-02 block."
+    },
+    "per_phase_cap_usd": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Cumulative ceiling across all spawns within the current phase (USD). Read from .design/STATE.md frontmatter `phase:` field."
+    },
+    "tier_overrides": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string",
+        "enum": ["haiku", "sonnet", "opus"]
+      },
+      "description": "Per-agent tier override map (agent-name -> tier). Wins over agent frontmatter default-tier per D-04."
+    },
+    "auto_downgrade_on_cap": {
+      "type": "boolean",
+      "description": "When true, hook silently rewrites tier -> haiku at 80% of per_task_cap_usd per D-03; logged as tier_downgraded: true in telemetry."
+    },
+    "cache_ttl_seconds": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "TTL (seconds) driving .design/cache-manifest.json entry expiry per D-08 Layer B. Default 3600."
+    },
+    "enforcement_mode": {
+      "type": "string",
+      "enum": ["enforce", "warn", "log"],
+      "description": "D-11 enforcement policy. enforce = block + auto-downgrade; warn = print warnings but allow spawn; log = advisory-only telemetry without gating."
+    }
+  }
+}

package/reference/schemas/events.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/hegemonart/get-design-done/main/reference/schemas/events.schema.json",
+  "title": "Event",
+  "description": "One line of .design/telemetry/events.jsonl — the append-only telemetry stream produced by Plan 20-06. Each event is a single JSON object followed by a newline. See .planning/phases/20-gdd-sdk-foundation/20-06-PLAN.md.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["type", "timestamp", "sessionId", "payload"],
+  "properties": {
+    "type": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Free-form event type identifier. Pre-registered seeds: state.mutation, state.transition, stage.entered, stage.exited, hook.fired, error."
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 timestamp of event emission."
+    },
+    "sessionId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Stable identifier per GDD pipeline run; correlates events across stages."
+    },
+    "stage": {
+      "type": "string",
+      "enum": ["brief", "explore", "plan", "design", "verify"],
+      "description": "Optional — present when the event is scoped to a pipeline stage."
+    },
+    "cycle": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Optional — present when the event is scoped to a cycle identifier."
+    },
+    "payload": {
+      "type": "object",
+      "description": "Event-type-specific payload. Opaque at the envelope level."
+    },
+    "_meta": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["pid", "host", "source"],
+      "properties": {
+        "pid": { "type": "integer", "minimum": 0 },
+        "host": { "type": "string" },
+        "source": { "type": "string" }
+      },
+      "description": "Writer-injected provenance. Never set by callers."
+    },
+    "_truncated": {
+      "type": "boolean",
+      "description": "Writer-set flag indicating the payload exceeded maxLineBytes and has been replaced by a placeholder."
+    }
+  }
+}

package/reference/schemas/generated.d.ts

@@ -0,0 +1,419 @@
+// AUTO-GENERATED from reference/schemas/*.schema.json — DO NOT EDIT.
+// Regenerate: npm run codegen:schemas
+/* eslint-disable */
+// ---- authority-snapshot.schema.json ----
+/**
+ * Structure of .design/authority-snapshot.json produced by agents/design-authority-watcher.md. See .planning/phases/13.2-external-authority-watcher/13.2-CONTEXT.md §D-12.
+ */
+export interface AuthoritySnapshot {
+  version: 1;
+  generated_at: string;
+  feeds: {
+    [k: string]: FeedState;
+  };
+}
+export interface FeedState {
+  last_fetched_at: string;
+  etag?: string;
+  /**
+   * @maxItems 200
+   */
+  entries: Entry[];
+}
+export interface Entry {
+  id: string;
+  hash: string;
+}
+
+export type AuthoritySnapshotSchema = AuthoritySnapshot;
+
+// ---- budget.schema.json ----
+/**
+ * Shape of .design/budget.json — the Phase 10.1 optimization-layer budget governance file. Consumed by hooks/budget-enforcer.ts on every PreToolUse:Agent spawn. Bootstrap writes the Default Config from reference/config-schema.md if the file is missing.
+ */
+export interface DesignBudgetJson {
+  /**
+   * Hard ceiling per agent spawn (USD). Breach under enforcement_mode=enforce triggers D-02 block.
+   */
+  per_task_cap_usd?: number;
+  /**
+   * Cumulative ceiling across all spawns within the current phase (USD). Read from .design/STATE.md frontmatter `phase:` field.
+   */
+  per_phase_cap_usd?: number;
+  /**
+   * Per-agent tier override map (agent-name -> tier). Wins over agent frontmatter default-tier per D-04.
+   */
+  tier_overrides?: {
+    [k: string]: 'haiku' | 'sonnet' | 'opus';
+  };
+  /**
+   * When true, hook silently rewrites tier -> haiku at 80% of per_task_cap_usd per D-03; logged as tier_downgraded: true in telemetry.
+   */
+  auto_downgrade_on_cap?: boolean;
+  /**
+   * TTL (seconds) driving .design/cache-manifest.json entry expiry per D-08 Layer B. Default 3600.
+   */
+  cache_ttl_seconds?: number;
+  /**
+   * D-11 enforcement policy. enforce = block + auto-downgrade; warn = print warnings but allow spawn; log = advisory-only telemetry without gating.
+   */
+  enforcement_mode?: 'enforce' | 'warn' | 'log';
+  [k: string]: unknown;
+}
+
+export type BudgetSchema = DesignBudgetJson;
+
+// ---- config.schema.json ----
+/**
+ * Shape of .design/config.json — model profile and parallelism settings per reference/config-schema.md.
+ */
+export interface DesignConfigJson {
+  model_profile?: 'quality' | 'balanced' | 'budget';
+  parallelism?: {
+    enabled?: boolean;
+    max_parallel_agents?: number;
+    min_tasks_to_parallelize?: number;
+    min_estimated_savings_seconds?: number;
+    require_disjoint_touches?: boolean;
+    worktree_isolation?: boolean;
+    per_stage_override?: {
+      [k: string]: {
+        enabled?: boolean;
+        max_parallel_agents?: number;
+        min_tasks_to_parallelize?: number;
+        min_estimated_savings_seconds?: number;
+        require_disjoint_touches?: boolean;
+        worktree_isolation?: boolean;
+        [k: string]: unknown;
+      };
+    };
+    [k: string]: unknown;
+  };
+  /**
+   * 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;
+  [k: string]: unknown;
+}
+
+export type ConfigSchema = DesignConfigJson;
+
+// ---- events.schema.json ----
+/**
+ * One line of .design/telemetry/events.jsonl — the append-only telemetry stream produced by Plan 20-06. Each event is a single JSON object followed by a newline. See .planning/phases/20-gdd-sdk-foundation/20-06-PLAN.md.
+ */
+export interface Event {
+  /**
+   * Free-form event type identifier. Pre-registered seeds: state.mutation, state.transition, stage.entered, stage.exited, hook.fired, error.
+   */
+  type: string;
+  /**
+   * ISO-8601 timestamp of event emission.
+   */
+  timestamp: string;
+  /**
+   * Stable identifier per GDD pipeline run; correlates events across stages.
+   */
+  sessionId: string;
+  /**
+   * Optional — present when the event is scoped to a pipeline stage.
+   */
+  stage?: 'brief' | 'explore' | 'plan' | 'design' | 'verify';
+  /**
+   * Optional — present when the event is scoped to a cycle identifier.
+   */
+  cycle?: string;
+  /**
+   * Event-type-specific payload. Opaque at the envelope level.
+   */
+  payload: {};
+  /**
+   * Writer-injected provenance. Never set by callers.
+   */
+  _meta?: {
+    pid: number;
+    host: string;
+    source: string;
+  };
+  /**
+   * Writer-set flag indicating the payload exceeded maxLineBytes and has been replaced by a placeholder.
+   */
+  _truncated?: boolean;
+}
+
+export type EventsSchema = Event;
+
+// ---- hooks.schema.json ----
+/**
+ * Shape of hooks/hooks.json — event-triggered commands registered by the plugin.
+ */
+export interface ClaudeHooksJson {
+  hooks: {
+    SessionStart?: HookGroup[];
+    SessionEnd?: HookGroup[];
+    PreToolUse?: HookGroup[];
+    PostToolUse?: HookGroup[];
+    [k: string]: unknown;
+  };
+  [k: string]: unknown;
+}
+export interface HookGroup {
+  matcher?: string;
+  hooks: {
+    type: 'command';
+    command: string;
+    [k: string]: unknown;
+  }[];
+  [k: string]: unknown;
+}
+
+export type HooksSchema = ClaudeHooksJson;
+
+// ---- intel.schema.json ----
+/**
+ * Shape of intel-store slice files per reference/intel-schema.md. Each slice has a generated timestamp and one array-valued payload key matching the slice name.
+ */
+export interface DesignIntelJson {
+  generated: string;
+  git_hash?: string;
+  files?: {
+    path: string;
+    type: 'skill' | 'agent' | 'reference' | 'connection' | 'script' | 'hook' | 'config' | 'test' | 'other';
+    mtime?: string;
+    size_bytes?: number;
+    git_hash?: string;
+    [k: string]: unknown;
+  }[];
+  exports?: {
+    file: string;
+    kind: 'skill' | 'agent' | 'reference' | 'other';
+    name: string;
+    command?: string;
+    [k: string]: unknown;
+  }[];
+  symbols?: {
+    file: string;
+    heading: string;
+    level?: number;
+    anchor?: string;
+    line?: number;
+    [k: string]: unknown;
+  }[];
+  tokens?: {
+    file: string;
+    token: string;
+    category?: 'color' | 'spacing' | 'typography' | 'radius' | 'shadow' | 'motion' | 'other';
+    line?: number;
+    context?: string;
+    [k: string]: unknown;
+  }[];
+  components?: {
+    file: string;
+    component: string;
+    role?: 'definition' | 'reference' | 'example';
+    line?: number;
+    [k: string]: unknown;
+  }[];
+  patterns?: {
+    name: string;
+    category?:
+      | 'color-system'
+      | 'spacing-system'
+      | 'typography-system'
+      | 'component-styling'
+      | 'layout'
+      | 'interaction'
+      | 'other';
+    source_file?: string;
+    description?: string;
+    [k: string]: unknown;
+  }[];
+  dependencies?: {
+    from: string;
+    to: string;
+    kind?: 'at-reference' | 'reads-from' | 'skill-calls-agent' | 'agent-calls-agent';
+    line?: number;
+    [k: string]: unknown;
+  }[];
+  decisions?: {
+    id: string;
+    summary: string;
+    source_file?: string;
+    line?: number;
+    date?: string;
+    [k: string]: unknown;
+  }[];
+  debt?: {
+    id: string;
+    summary: string;
+    severity?: 'high' | 'medium' | 'low';
+    source_file?: string;
+    line?: number;
+    [k: string]: unknown;
+  }[];
+  nodes?: {
+    id: string;
+    type?: string;
+    name?: string;
+    [k: string]: unknown;
+  }[];
+  edges?: {
+    from: string;
+    to: string;
+    kind?: string;
+    [k: string]: unknown;
+  }[];
+  [k: string]: unknown;
+}
+
+export type IntelSchema = DesignIntelJson;
+
+// ---- iteration-budget.schema.json ----
+/**
+ * Shape of .design/iteration-budget.json produced by scripts/lib/iteration-budget.cjs. Caps the number of fix-loop iterations that can consume context before the pipeline halts for user input. All mutations are coordinated by scripts/lib/lockfile.cjs and written via temp+rename. See .planning/phases/20-gdd-sdk-foundation/20-14-PLAN.md §Task 4.
+ */
+export interface IterationBudget {
+  /**
+   * The configured ceiling. Initialized by reset(). `remaining` never exceeds this value after refund().
+   */
+  budget: number;
+  /**
+   * Iterations still available for consume() calls. Starts at `budget`, drops on consume, climbs (capped at `budget`) on refund.
+   */
+  remaining: number;
+  /**
+   * Running total of successful consume() calls since last reset().
+   */
+  consumed: number;
+  /**
+   * Running total of refund amount since last reset() (useful for auditing the cache-hit refund path from budget-enforcer.ts).
+   */
+  refunded: number;
+  /**
+   * ISO-8601 timestamp of the last mutation.
+   */
+  updatedAt: string;
+}
+
+export type IterationBudgetSchema = IterationBudget;
+
+// ---- marketplace.schema.json ----
+/**
+ * Shape of .claude-plugin/marketplace.json — the plugin marketplace descriptor.
+ */
+export interface ClaudeMarketplaceJson {
+  name: string;
+  owner: {
+    name: string;
+    [k: string]: unknown;
+  };
+  metadata: {
+    description: string;
+    version: string;
+    [k: string]: unknown;
+  };
+  plugins: {
+    name: string;
+    source: string;
+    description: string;
+    version: string;
+    author: {
+      name: string;
+      [k: string]: unknown;
+    };
+    homepage?: string;
+    repository: string;
+    license: string;
+    category: string;
+    keywords: string[];
+    [k: string]: unknown;
+  }[];
+  [k: string]: unknown;
+}
+
+export type MarketplaceSchema = ClaudeMarketplaceJson;
+
+// ---- mcp-gdd-state-tools.schema.json ----
+/**
+ * Combined manifest of all 11 gdd-state MCP tool input+output schemas (Plan 20-05). Individual tool schemas live under scripts/mcp-servers/gdd-state/schemas/ and the tool handlers reference them; this combined schema exists so downstream validators and codegen can compile a single surface.
+ */
+export interface McpGddStateTools {
+  tools: {
+    gdd_state__get: ToolSchemaEntry;
+    gdd_state__update_progress: ToolSchemaEntry;
+    gdd_state__transition_stage: ToolSchemaEntry;
+    gdd_state__add_blocker: ToolSchemaEntry;
+    gdd_state__resolve_blocker: ToolSchemaEntry;
+    gdd_state__add_decision: ToolSchemaEntry;
+    gdd_state__add_must_have: ToolSchemaEntry;
+    gdd_state__set_status: ToolSchemaEntry;
+    gdd_state__checkpoint: ToolSchemaEntry;
+    gdd_state__probe_connections: ToolSchemaEntry;
+    gdd_state__frontmatter_update: ToolSchemaEntry;
+  };
+}
+export interface ToolSchemaEntry {
+  /**
+   * JSON Schema fragment describing the tool's input parameters.
+   */
+  input: {};
+  /**
+   * JSON Schema fragment describing the tool's response envelope.
+   */
+  output: {
+    type: 'object';
+  };
+}
+
+export type McpGddStateToolsSchema = McpGddStateTools;
+
+// ---- plugin.schema.json ----
+/**
+ * Shape of .claude-plugin/plugin.json — the plugin manifest consumed by Claude Code.
+ */
+export interface ClaudePluginJson {
+  name: string;
+  short_name: string;
+  version: string;
+  description: string;
+  author: {
+    name: string;
+    url?: string;
+    [k: string]: unknown;
+  };
+  homepage?: string;
+  repository: string;
+  license: string;
+  keywords: string[];
+  skills: string[];
+  hooks?: string;
+  [k: string]: unknown;
+}
+
+export type PluginSchema = ClaudePluginJson;
+
+// ---- rate-limits.schema.json ----
+/**
+ * Shape of .design/rate-limits/<provider>.json produced by scripts/lib/rate-guard.cjs. One file per provider (anthropic, openai, figma, ...) — header ingestion overwrites atomically via tmp+rename under scripts/lib/lockfile.cjs protection. See .planning/phases/20-gdd-sdk-foundation/20-14-PLAN.md §Task 2.
+ */
+export interface RateLimits {
+  /**
+   * Provider identifier (e.g. 'anthropic', 'openai', 'figma'). Matches the state file basename.
+   */
+  provider: string;
+  /**
+   * Number of API calls the provider says are still allowed before the next reset. When ingestion sees both requests-remaining and tokens-remaining, the lower value wins (most-restrictive).
+   */
+  remaining: number;
+  /**
+   * ISO-8601 timestamp when the rate-limit window resets. Synthesized from whichever header is present: retry-after (seconds or HTTP date), x-ratelimit-reset-requests / -tokens (Unix seconds), anthropic-ratelimit-requests-reset (ISO string). When multiple candidates are present, the latest resetAt wins.
+   */
+  resetAt: string;
+  /**
+   * ISO-8601 timestamp when this state file was last written (ingestHeaders call time).
+   */
+  updatedAt: string;
+}
+
+export type RateLimitsSchema = RateLimits;
+