redongreen/uspec/create-component-md

Create Component Markdown (Orchestrator)

This skill consumes a _base.json produced by the uSpec Extract Figma plugin (figma-plugin/), runs four read-only interpretation skills (extract-api, extract-structure, extract-color, extract-voice), and writes two sibling artifacts: a canonical .json contract and a polished implementation .md. Figma is only the source of extraction. Exhaustive .audit.md is an opt-in diagnostic view, not a default artifact.

Do not call the `create-*` skills from here. They render Figma frames that overlap and do not compose into a single file.

Why this orchestrator exists

The four create-* skills each cost ~100k tokens per run because the majority of their weight is Figma rendering (setProperties, createInstance, loadFontAsync, layout math). The extract-* skills strip all rendering. Because the Figma plugin produces a single shared _base.json, the four interpretation skills also stop calling Figma — they read that file from disk. This removes most of the Figma-side work and keeps the orchestrator's parent context small by discarding each phase's detail after its one-line summary lands.

Token model (approximate):

extract-api runs first in the parent so its dictionary can steer the three downstream specialists. After the dictionary lands, the parent dispatches extract-structure, extract-color, and extract-voice as three parallel subagents (subagent_type=generalPurpose, single batch). Each subagent holds its own _base.json + dictionary context; the parent keeps only the returned one-line summaries and cache-file paths.

Inputs Expected

• `baseJsonPath` (required): absolute or workspace-relative path to the _base.json file produced by the uSpec Extract Figma plugin. Must validate against figma-plugin/docs/base-json-schema.md. If this is not provided, abort and instruct the user to run the uSpec Extract plugin (see figma-plugin/README.md).
• `figmaLink` (optional): URL to the component set or standalone component. Accept figma.com/design/:fileKey/... and branch URLs (/branch/:branchKey/). Only consulted if an interpretation skill needs a Step 3-delta MCP call.
• `optionalContext` (optional): free-form guidance (e.g., "this is a compact variant only", "skip error states"). If the plugin already captured it in _meta.optionalContext, that wins; otherwise the value passed here is used. Forwarded verbatim to every sub-skill.

No output path is required — the defaults are ./components/{componentSlug}.md and ./components/{componentSlug}.json in the current working directory.

Workflow

Copy this checklist and update as you progress:

Task Progress:
- [ ] Step 1: Preflight — read config, run `uspec-skills component-md prepare`, load manifest
- [ ] Step 2: Resolve componentSlug and output path (from manifest)
- [ ] Step 3: Announce the plan
- [ ] Step 3.5: Composition classification (reasoning gate — internalize before Step 4.5 review)
- [ ] Step 4: Stage _base.json into cachePath (handled by CLI prepare — verify manifest only)
- [ ] Step 4.5: Post-extract review — confirm _childComposition (user-selected classifications skip override pass)
- [ ] Step 5: Run extract-api (reads _base.json, no Figma), flush, verify cache + api-dictionary.json
- [ ] Step 6: Parallel fan-out — dispatch extract-structure, extract-color, extract-voice as three subagents in a single batch; join on all three summaries
- [ ] Step 8.5: Reconciliation — typed disagreement handling with bounded serial retries
- [ ] Step 9: Build the canonical JSON contract, then render the implementation Markdown
- [ ] Step 9.5: Integrity check — validate all cache files and reconciliation artifact before rendering
- [ ] Step 10: Audit output and return a one-line summary
- [ ] Step 10.5: Emit recursion manifest (constitutive children only)

Step 1: Preflight (CLI prepare)

Read uspecs.config.json at the project root. Extract:

• mcpProvider (figma-console or figma-mcp). Only used if figmaLink is also provided AND an interpretation skill's Step 3-delta triggers.
• environment (cursor | claude-code | codex) — used to resolve the skills directory for subagent dispatch (see Step 6).

`baseJsonPath` is required. If it is missing, abort with a one-line diagnostic: "run the uSpec Extract plugin in Figma and rerun with baseJsonPath=<path> — see figma-plugin/README.md."

Run the deterministic prepare stage first. Resolve the CLI executable before shelling out — do not assume npx uspec-skills is new enough to expose component-md prepare.

CLI resolution order (try each; stop at the first that works):

1. Local dev checkout — when packages/cli/dist/index.js exists in the project root:

``bash node packages/cli/dist/index.js component-md prepare --base "<baseJsonPath>" --json ` If missing but packages/cli/ exists, run npm run build:cli` from the project root once, then retry step 1.

1. Published npm — when step 1 is unavailable:

``bash npx uspec-skills component-md prepare --base "<baseJsonPath>" --json ` When this fails with unknown command: component-md, retry once with an explicit version pin: `bash npx uspec-skills@0.3.3 component-md prepare --base "<baseJsonPath>" --json ``

1. Abort — when both paths fail, stop with:

> component-md prepare is unavailable. In the uSpec repo run npm run build:cli, then rerun create-component-md. Else run npx uspec-skills update after upgrading to uspec-skills ≥ 0.3.3.

Append --context "<optionalContext>" when the orchestrator received non-empty optionalContext. Append --output "<outputPath>" when the user passed an explicit output path.

• Any non-zero exit from a working CLI → abort with stderr (validation/staging failure). Do not fall back to manual validation or staging once a CLI with component-md prepare is available.
• Parse the JSON manifest from stdout. Keep: componentSlug, cachePath, stagedBasePath, outputPath, baseSourceHash, readiness, summaries, paths.contractPath, paths.evidence, and the one-line summaryLine.

Read the effective Figma target from manifest source.{fileKey,nodeId,figmaUrl}. The prepare command derives these fields from _base.json._meta; figmaUrl falls back to a URL constructed from the required fileKey + nodeId. Read the staged base only when an older manifest lacks source.

The MCP connection check is deferred — it is not needed unless a sub-skill triggers a delta.

If figmaLink is also passed alongside baseJsonPath, parse it for comparison — but trust manifest / _meta as the source of truth when they disagree and log a META_DISAGREES_WITH_LINK warning for the final summary.

Set deltaAvailable = true whenever manifest source.fileKey and source.nodeId are non-empty. A separately-passed figmaLink is not required. If a targeted delta later fails because the configured MCP cannot connect, record unavailable: "mcp-unavailable"; never mislabel an embedded target as no-figma-link.

Skills directory for downstream dispatch (from environment):

Step 2: Resolve componentSlug and output path

Use the manifest from Step 1 — do not re-derive paths:

1. componentSlug = manifest componentSlug
2. outputPath = manifest outputPath
3. cachePath = manifest cachePath
4. stagedBasePath = manifest stagedBasePath
5. baseSourceHash = manifest baseSourceHash
6. evidencePaths = manifest paths.evidence
7. contractPath = manifest paths.contractPath (or replace the final .md suffix

of outputPath with .json for an older manifest)

Do not proceed until all of the above are resolved. Every subsequent step reads from them.

Surface manifest readiness.warnings and any readiness.layoutTreeHasNodeIds === false flag before continuing (same framing as the legacy Step 4 render-meta freshness check).

Step 3: Announce the plan (non-blocking)

Print a single informational message to the user and then immediately continue to Step 4. Do not call AskQuestion. Do not wait for input. The chain runs start-to-finish without interruption.

Generating Markdown source of truth for {ComponentName} ({nodeId}).

Running 4 interpretation passes (API → Structure → Color → Voice) against the provided _base.json. Cache: {cachePath}. Output: {outputPath}.

No phase touches Figma unless an interpretation skill's Step 3-delta fires (read-only). Every pass flushes to disk to stay under token budget.

If the user wants to correct the target node or the extraction context, they must cancel this run and start a new one with different inputs. There is no mid-chain correction point.

Step 3.5: Composition classification (reasoning gate)

Before you interpret any of the extracted data, you must internalize how to classify every top-level child instance of the component being spec'd. This classification decides how each child appears in the final .md and whether a follow-up create-component-md run is needed. The mechanics of reading _childComposition happen at Step 4.5 (after _base.json lands). This step is the reasoning model you carry into that review.

Ask this question, in order, for each identity in the full cross-variant _childComposition.children[] union. Use presentInVariants, defaultVariantPresent, and placementsByVariant; never limit classification to the default tree.

Q1. If I removed this child, would the component still be the thing the user is asking me to spec?

• No → constitutive (part-of). It is part of what this component is. Spec it.
• Yes → continue to Q2.

Q2. Does this child have a name/identity that a different consumer would recognize and use independently in a different context?

• Yes → referenced (uses-a). It is a self-contained component this one happens to embed. Name it and document the configuration passed to it; do not re-spec it.
• No → decorative (has-no-identity). A vector, glyph, or layout frame. Fold into structure or color inline.

Patterns to match against, with one illustration each

The column you should pattern-match on is Pattern — the shape of the relationship. The Illustration column is one concrete example so you can anchor the shape; the agreement is with the pattern, not the specific names. When you spec any component, ask: which of these patterns does each child match?