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 renders their combined output into one self-contained Markdown file. The `.md` is the artifact; Figma is only the source of extraction.

**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):**

| Phase | Peak context in parent |
|---|---|
| extract-api (runs first, inline) | instruction + `_base.json` read + interpretation |
| parallel fan-out (structure + color + voice, subagent each) | three one-line summaries (subagents hold their own context) |
| reconciliation (Step 8.5) | mismatch lists + api dictionary (small) |
| rendering | 4 JSON cache files + template + instruction |

`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]({{repo: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 default is `./components/{componentSlug}.md` 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: Render the .md (follow {{ref:component-md/agent-component-md-instruction.md}})
- [ ] 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.

2. **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.2 component-md prepare --base "<baseJsonPath>" --json
   ```

3. **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.2.

Append `--context "<optionalContext>"` when the orchestrator received non-empty `optio