generate-component

generate-component

A skill that takes a component request specification produced by clarify-component and generates a working custom UI component file together with a Storybook story file. The spec at docs/gyre/specs/components/<kebab-name>.md is the contract: the skill consumes it and emits code without reopening the clarification dimensions. If the spec is wrong, the user is directed back to clarify-component — the skill does not re-interpret, amend, or extend the spec's decisions on its own. The skill's purpose: "When the user runs a skill in a host project against an existing component request specification produced by the clarify-component skill, the AI generates a working custom UI component from that spec, which the user can see on screen."

Invocation

/generate-component <kebab-name>

<kebab-name> identifies the spec at docs/gyre/specs/components/<kebab-name>.md. If the argument is omitted, the skill lists every .md file under docs/gyre/specs/components/ and asks the user to pick one. The skill operates on the current working directory, which is treated as the host project root. Like setup, it requires a package.json to be present there.

Output

After a successful run, the host project contains:

<components-alias>/<kebab-name>.tsx          # component source
<components-alias>/<kebab-name>.stories.tsx  # Storybook story

<components-alias> is the host project's component output directory. A divisible component (one whose spec carries a ## Composition section — a molecule or organism) is written to the component output directory at Composed/ catalog altitude. An atomic Compose whose resolved Reference is a primitive is written to the primitives directory at Primitives/ altitude. The directory is resolved by host discovery per references/host-discovery.md; the catalog altitude is set per references/output-format.md → Story catalog hierarchy; the stack-specific configuration files consulted are owned by the relevant stack skill.

If a file already exists at either target path, the skill does not overwrite silently. It pauses, tells the user the path is taken, and asks whether to overwrite or pick a different name before proceeding. Collision handling is specified in references/output-format.md.

The run may additionally cause:

• New npm dependencies added to the host package.json — only when the spec requires a package the host does not yet have, and only after the user approves the Plan that lists them (npm-install items).
• A Reference primitive installed by the shadcn skill — only when the AI's Compose decision names a primitive the host does not have, and only after Plan approval (shadcn-install items).

Both kinds of host mutation are explicit items on the Plan; neither occurs without user approval.

Language

User-facing prompts (Plan presentation, approval dialogue, final reporting) are in the user's language, inferred from the user's messages. Spec content is required to be in English (enforced by clarify-component's Spec language rule; see ../clarify-component/references/output-format.md); generate preserves spec content verbatim into code (identifiers, string literals, the rare comment). Generate terminates at Step 2 (Load spec) if it finds any non-ASCII content in the spec body — see Step 2 for the termination message.

Scope

In scope:

• the component whose Where decision the AI resolves to New or Compose. Compose now spans both a composition over primitives (molecule) and a composition over catalog custom components (organism); the rung label is emergent (see Step 3). A Compose whose composition requires a custom component not yet in the catalog terminates with a must-build-first report (Step 3) rather than generating.
• Discovering the host catalog and deciding Reuse / Extend / Compose / New (Principle 4), then reporting the decision to the director.
• Discovering host context (component output alias, primitive source location, active design tokens, package dependencies, Storybook setup) by reading host files directly.
• Asking the shadcn skill to install the Reference primitive when a Compose decision names a primitive the host does not yet have.
• Writing one component file and one Storybook story file.
• Auditing the emitted files against the loaded stack skills' concrete rules (Step 8.5 self-review), with three-way classification of findings and auto-fix of the fixable-here class.
• Verifying the result via TypeScript typecheck, scoped ESLint, and Storybook build, with a bounded self-repair loop.

Out of scope (deferred or excluded):

• Code generation when the AI's Where decision is Extend or Reuse. The skill reports the decision and terminates with a clear message. Extend requires reading and modifying existing host source code in ways this skill does not commit to; Reuse has nothing to generate. Only the decision owner moved into this skill — generating Extend/Reuse remains deferred.
• Installing or scaffolding the host stack itself — components.json, Storybook, Tailwind, the host's package manager, the @workspace/ui monorepo wiring, etc. If a precondition is missing the skill explains and terminates.
• Re-opening clarification dialogue. The skill does not re-interpret the spec's decisions; ambiguity is treated as a spec defect and the user is pointed back to clarify-component.
• Generating demo routes, tests, or component documentation beyond the story file.
• Page and DESIGN.md generation — separate slices in future iterations.
• Running when required stack skills are not installed in the host. The skill terminates at Step 1.5 with a pointer to /setup instead of falling back to host conventions alone.

Process

The skill executes the following steps in order. Each step has an explicit termination branch on failure.

1. Confirm host project

Check that the current working directory contains a package.json file. If it does not, tell the user that generate-component must be run from a project root, and terminate without reading the spec or writing anything.

1.5. Precondition — stack skills installed

Read the manifest at ../setup/references/stack-skills.md. For each entry, evaluate the two detection signals as defined in ../setup/SKILL.md Step 4 (Detect install state):

• a skill directory carrying SKILL.md exists at EITHER .claude/skills/<name>/SKILL.md OR .agents/skills/<name>/SKILL.md, and
• skills-lock.json at the host project root contains the key <name> under its skills object.

Classify each entry as installed (both signals hold), incomplete (exactly one holds), or missing (neither holds) — the same classification used by setup Step 4.

If every entry is installed, proceed to Step 2.

Otherwise, terminate. In the user's language:

• name each non-installed entry and state which detection signal is missing (skill files / lock entry / both),
• instruct the user to run /setup from this host project root and then retry /generate-component,
• do not load the spec, do not perform host discovery, do not write any file.

A failed precondition is never reported as success — the same posture setup takes in its own Step 6 ("Verify and report").

2. Load spec

Read docs/gyre/specs/components/<kebab-name>.md. Parse both the YAML front matter and the body sections (Interaction model / What / Look / How / Data / Non-goals). If the file is absent, tell the user that no spec was found at that path and that they should run clarify-component <kebab-name> to create one, then terminate.

After parsing, scan every section's content for non-ASCII characters. The scan covers all body text and all front-matter values except the source field, which preserves the verbatim original natural-language request and is intentionally archival. If any non-ASCII characters are found in the scanned content, terminate with the message:

"The spec at docs/gyre/specs/components/<kebab-name>.md contains non-ASCII content in section <section name>. Spec content must be in English (enforced by clarify-component's Spec language rule). Re-run /gyre:clarify-component <kebab-name> or edit the spec to use English, then re-invoke /gyre:generate-component <kebab-name>."

Do not load stack skills, do not perform host discovery, do not write any file. This validation protects against manual spec edits that reintroduce user-language content and against legacy specs created before the language rule landed.

2.5. Invoke stack skills

Read the manifest at ../setup/references/stack-skills.md. For each row, in the table's row order:

• kind: always — invoke the row's name via Claude Code's Skill tool.
• kind: conditional — evaluate the row's condition predicate against the spec body loaded in Step 2. If the predicate is true, invoke the row's name via the Skill tool. If false, skip the row.
• kind: external — skip. The skill loads through its own auto-activation mechanism; the manifest row exists so that setup installs it.
• kind: deferred — skip. The manifest row exists so that setup installs it for parity with future iterations.

Run the invocations sequentially in row order so the resulting tool-call trace is deterministic for a given spec.

If a Skill invocation errors (skill not found, body load failure), report the failure to the user — naming the row and the error — and terminate without proceeding to Step 3. Step 1.5 should have caught uninstalled entries already, so reaching this branch indicates drift between the install state and the manifest.

Fetch-only skills carry no rules until fetched. When an invoked skill's body defers its entire ruleset to a URL fetched at review time (e.g., web-design-guidelines, whose SKILL.md names a guidelines URL and instructs the reader to fetch it), invocation brings the fetch instruction into context, not the rules. The fetch itself is performed by the Step 8.5 rule audit (references/self-review.md), which retrieves the URL with WebFetch and adds the fetched ruleset to what it checks. Loading such a skill at Step 2.5 alone contributes nothing checkable; do not treat its presence in context as having loaded its rules.

Loaded skill bodies remain available to all subsequent steps (Discovery in Step 4, Plan composition in Step 5, file Write in Step 8, the rule audit in Step 8.5, Verify in Step 9) without re-invocation.

3. Decide Where (discover + decide)

Discover the host catalog and decide the Where relationship for this component — the decision is the AI's, made from discovery, not read from the spec (the spec has no ## Where section). Apply Principle 4 (STRATEGY.md):

• Scan the host catalog — the component and primitive directories resolved by host discovery (per references/host-discovery.md) — for a same-role component and for base primitives the spec's intent implies.
• Decide, biased toward creating new: Reuse when an existing component already covers the intent end-to-end; Extend when only minor additions to an existing same-role component are needed (addition only — existing interfaces unchanged); Compose when a new identity is assembled from existing primitives (primitives are never modified — a needed variant is solved by composition); New when neither a same-role component nor a usable primitive exists.
• Record the decision and any Reference primitive(s) for downstream steps (the import map in Step 5 consumes them).

Composition mapping (divisible specs). When the spec carries a ## Composition section, resolve the Where decision by mapping each intent-level unit onto the catalog per references/host-discovery.md → Composition mapping. Each unit resolves to a primitive Reference, a custom-component Reference, a directly-rendered part, an installable primitive (shadcn-install), or an absent custom unit. The rung label is emergent — all-primitive References → molecule, any custom-component Reference → organism — and is informational only; both are Compose. If any unit is an absent custom unit, the must-build-first list is non-empty: report it and terminate (see the termination bullet below). Otherwise proceed to Step 4 with the resolved References.

Then branch:

• New or Compose → proceed with full host discovery (Step 4) and generation.
• Extend or Reuse → report the decision and its rationale to the director, state that code generation for Extend/Reuse is deferred to a future iteration, and terminate without writing any file. Do not point the director back to clarify to "fix" a Where decision — Where is no longer a clarify output.
• Compose with a non-empty must-build-first list → report the absent constituent units (direct dependencies only) and terminate without writing any file. For each absent unit, direct the director to build it first with /clarify-component <name> → /generate-component <name>, then re-run /generate-component <this-spec>. Do not expand a missing unit's own sub-units (they are not fixed until that unit is clarified) and do not point the director back to clarify to "fix" the composition — the decomposition is correct; the catalog is simply not yet populated. The recursion is well-founded: an absent custom unit is always a lower rung, ultimately Rung-1.

The catalog scan that feeds this decision is the new work in this step; it resolves the host's component and primitive directories on demand — the same directories Step 4's Plan slots reuse (component output alias, design tokens, dependencies, Storybook). Directory resolution thus happens when first needed (here) and is reused, rather than requiring Step 4 to run first.

4. Discover host context

Map host context into Plan slots per the slot policy in references/host-discovery.md. Six slot kinds feed the Plan (a seventh, the catalog scan, feeds the Step 3 Where decision and is not a Plan item):

• Component output directory — resolves the spec's output path; failure label user-needed.
• Reference location (Compose only) — resolves each identifier the AI's Where decision (Step 3) recorded as a Reference (a primitive or a catalog custom component). An absent primitive carries failure label shadcn-install; a custom-component Reference is located by the catalog scan (never shadcn-install) and an absent custom unit terminates the run via the must-build-first branch (Step 3) rather than reaching this slot.
• Active design tokens — surfaces conflicts with the spec's ## Look → Token overrides; conflict label attention (non-blocking).
• External dependencies — checks for the packages the spec requires (icon library, theme provider, animation library) and resolves the current export name to emit for each abstract symbol the spec names (by reading the package's installed type definitions); failure label npm-install.
• Consumer-implied preconditions — derives, per external symbol the component will import, the host-side conditions that must hold for the symbol to function, verifies each via a host signal; unmet preconditions are surfaced with label host-setup-required (non-blocking).
• Storybook precondition — checks the host's story framework is installed. Absence is not a Plan item: the skill terminates here and tells the user it must be installed first.

The concrete stack conventions used to perform each lookup (configuration file structure, path resolution, primitive file naming, installation-detection signals) are not duplicated here — they belong to the stack skills installed by setup (see ../setup/references/stack-skills.md for the current manifest).

5. Compose Plan

Assemble a single Plan document combining the spec and the discoveries from step 4. The Plan's structure is defined in references/plan-format.md. It includes the two output file paths, the import map, all prerequisite actions, story rows derived from the spec's ## How → States, ## How → Edge cases, and ## Data / Content → Edge data (subject to the Story coverage rule in references/output-format.md), and any user-needed, attention, or host-setup-required items. The eight source labels that may appear on Plan rows are: spec, host, inferred, user-needed, shadcn-install, npm-install, attention, and host-setup-required.

6. Plan approval

Present the Plan to the user in one message. Three outcomes are recognized:

• Approve as is → proceed to step 7.
• Fill in or amend any item, including user-needed items → return to step 5, recompose the Plan with the change applied, and re-present it. This loop continues until the user approves or rejects.
• Reject → terminate without writing or installing anything.

If the user requests a change that would contradict the spec — for example, renaming a prop that the spec fixes in ## What → Props, or changing the interaction-model variant the spec records — the skill must not silently follow. It stops, tells the user the requested change is a spec-level change, and directs the user to run clarify-component to update the spec and re-invoke /generate-component once the spec reflects the change. Exact phrasing rules for this termination branch are in references/plan-format.md. This preserves the spec-is-the-contract rule.

7. Realize prerequisites

For each shadcn-install item on the approved Plan: invoke the shadcn skill through Claude Code's Skill tool (not Bash). If a shadcn-install fails, report the CLI error and terminate without writing files.

For each npm-install item: run the host's package manager using the same runner-resolution logic the setup skill uses (see ../setup/SKILL.md Step 3). If an install fails, report the error and terminate.

Run all prerequisites before writing any files — failures here surface before the skill's own files are written.

8. Write files

Write the component file and the story file at the paths fixed in step 5. For each file, immediately before writing, check whether the path is already occupied. If it is, ask the user whether to overwrite or pick a different name, then act on the answer before writing either file. File contents follow references/output-format.md.

Consult the loaded rules at write time. This is the author-time half of the safety net (Step 8.5 is the audit half). Before emitting a piece of code that exhibits one of the traits in references/output-format.md → Pattern selection deference → Trait → rule lookup (client hooks / derived state, theme-or-SSR coupling, SVG animation, icon-only control, composition surface, styled transitions — read from the spec body, the Plan's import map, and the Step 3 Where decision), read the rule the table names from the loaded skill body and write to satisfy it. Do not rely on Step 8.5 to retrofit a pattern the consultation should have produced — the audit is a backstop, not the primary mechanism. The trait→rule table is the same applicability filter the Step 8.5 audit re-uses, so the same rules are checked once before emission and once after.

8.5. Rule audit (self-review)

After the files are written and before the verification gate, audit the emitted files against the concrete rules of the stack skills loaded at Step 2.5 — the discrete check that closes the gap between loading a skill and applying it (Principle 5: the AI self-verifies the artifact it produced). The full procedure is specified in references/self-review.md. In outline:

• Fetch the web-design-guidelines ruleset (a fetch-only skill; see Step 2.5) via WebFetch so its rules are actually in context.
• Enumerate the rules applicable to this component's traits (client hooks, theme/SSR coupling, SVG animation, icon-only control, composition surface, styled transitions — derived from the spec body, the resolved import map, and the Step 3 Where decision), using the trait→rule lookup in references/output-format.md as the applicability filter, and reading each rule from the loaded skill body (or fetched ruleset) rather than from memory.
• Check the emitted files against each applicable rule and classify every finding into exactly one of three classes — the classification is what keeps the audit from violating the spec-is-contract rule (Principle 1) and the primitives-are-never-modified rule (Principle 4):
  • fixable-here — resolvable within the generated file without contradicting the spec → auto-fix, then re-verify at Step 9.
  • spec-bounded — would require changing a spec-fixed decision → do not change; report with citation and a pointer to clarify-component.
  • primitive-inherited — originates in an unmodifiable Reference primitive → informational report only.

The audit modifies only the two generated files (never a primitive, a barrel file, a route, or the spec) and never blocks the run with a question — its spec-bounded / primitive-inherited findings are disclosure, carried into the Step 9 success report. If the web-design-guidelines fetch fails, the audit notes the reduced coverage and proceeds with the locally-loaded rules.

9. Verify and self-repair

Run the typecheck command, then the scoped lint command, then the Storybook-build command — each only when the previous one passes — treating their outputs as the truth. Command resolution (including the file-scoped eslint <files> --max-warnings 0 lint command and its --fix pre-pass), the bounded self-repair loop rules, error-normalization definitions (including the lint signature), the classification of residual lint findings, and the exact context given to the repair step are all specified in references/verification.md. The stack-standard form of each command (TypeScript's tsc, ESLint's eslint, Storybook's storybook build) is not pinned here — it follows the host's stack convention as already encoded by setup's runner-resolution. The scoped lint command re-checks, mechanically, the lint-visible subset of the rule classes the Step 8.5 audit reasons about; the two share one classification vocabulary.

The loop terminates on one of two outcomes:

• All three commands pass — report success, including the generated file paths, the host's recommended dev command (the script the host uses to launch the story framework in dev mode) so the user can launch it themselves to see the result on screen, and the Step 8.5 audit section (auto-fixed fixable-here findings, plus any spec-bounded / primitive-inherited findings with their citations). Termination: success.
• The most recent attempt produces the same normalized error signature as the previous attempt for the same command — the loop cannot make progress. Report the repeated error signature and the diagnosis, and leave the files in their last state for the user to inspect. Termination: failure with report.

The skill never runs storybook dev; it builds only.

Constraints

• The generated component file and story file must not reference paths or vocabulary outside the host project. The same constraint the spec format imposes carries through to the code.
• The skill does not generate JSDoc, banner comments, or "generated by" markers. Code is identified by its identifiers; provenance is recorded in the spec, not in the file.
• The skill does not modify host files other than:
  • the two new files it writes,
  • package.json (when an npm-install is approved on the Plan),
  • any files the shadcn skill writes during a shadcn-install. No other host file is touched, including no edits to barrel files, index files, or routes.
• The skill never re-enters the clarification dimensions. Spec ambiguity surfaces as a termination with a pointer to clarify-component.

Reference files

These files show spec → code mapping (and the host-discovery / Plan-composition / verification policies that surround it). They contain no stack convention details — React, Next.js, shadcn/ui, the type system, the story framework — those are delegated to the stack skills installed in the host by setup (see ../setup/references/stack-skills.md for the current manifest).

• references/host-discovery.md — slot policy (which kinds of host context the Plan needs, which Plan slot label is used on resolve failure) and the five resolve-failure labels.
• references/plan-format.md — the Plan's three-section structure, the eight source labels, story-set rendering, the approval mechanism, and the spec-contradiction termination phrasing rules.
• references/output-format.md — the spec → code mapping (which spec section becomes which piece of the emitted code), the imports rule, the no-comments-by-default rule with its single exception, the collision prompt, and Pattern selection deference with its trait→rule lookup table (the write-time consultation half).
• references/self-review.md — the Step 8.5 rule audit: how applicable rules are enumerated from the loaded skills (including the web-design-guidelines fetch), the three-way classification of findings (fixable-here / spec-bounded / primitive-inherited), auto-fix-and-re-verify, and the audit report shape.
• references/verification.md — command resolution policy for all three gate commands (typecheck, scoped lint, Storybook build), the self-repair loop rules, error-normalization definitions, the classification of residual lint findings, and the context provided to each repair invocation.

The AI reads these reference files at invocation time and uses them to drive host discovery, Plan composition, file generation, the rule audit, and verification. None of their contents are duplicated in this file.