This document is Router. It defines only the component work flow and gates; the actual content is in each Phase's reference file. When entering each Phase, read the corresponding reference at that time. Do not read them all in advance.
Core Flow
Platform Gate → Delivery Surface Gate → Phase 0 Pre (Brainstorm) → Phase 0 (Architecture) → Phase 1 (Implementation) → Phase 2 (Verification)
React/Lynx 결정 package/snippet 판단 사용자 합의 아키텍처 결정 레이어별 구현 자동·수동 검증
Between each Phase there is a gate. Do not proceed to the next Phase until the gate is passed. If the flow breaks, missing requirements, misaligned architecture, and bypassed verification accumulate and shake other components as well.
Storybook-only fast path
If the request is limited to docs/stories/*.stories.tsx, docs/.storybook/*authoring, refactoring, and verification only, and does not change the component API or behavior, do not apply the Platform/Delivery Surface/Phase 0 gate.
references/storybook.mdRead.docs/.storybook/preview.ts,docs/stories/utils/parameters.ts, check the nearest existing story.- Write using the CSF Next factory pattern and preserve the behavior scope per story.
references/storybook.mdverification command andreferences/visual-testing.mdStorybook entry.
If the component API, state, and recipe also change, stop the fast path and return to the general core flow.
Handling Blockers (common to all Phases)
If blocked during work, arbitrary workarounds, mocks,as any, skipping tests, and "let's fix it later" are prohibited. Write a pain memo → report to the user → retry after a decision.
Detailed rules and blocker classification table: references/sticking-policy.md
Platform Gate: Decide target platform
Read immediately upon entry → references/platform-gate.md
Before Phase 0 Pre, finalize the target platform as one of react / lynx / cross-platform . Once the platform is determined, the paths for Headless, Recipe, Styled UI, Snippet, Docs, Example, and Verification are determined.
🔒 Gate Platform → 0Pre
- Target platform finalized
cross-platformIf so, confirm the principle of separating shared Rootage/API and platform-specific implementations- 새
packages/lynx-react-headless/<component>If a package is needed, do not implement before user confirmation
Delivery Surface Gate: Determine public surface
Read immediately upon entry → references/api-design.md의 "Delivery Surface Gate"와 "Analog Parity Check"
Immediately after the Platform Gate, before implementation, finalize where among package export, registry snippet, 둘 다, docs-only to provide this component. If there is an equivalent React component, compare not only variant/interface but also docs Usage imports, registry presence, package exports, and example surfaces together.
Create a snippet only when the wrapper adds substantial value. Do not turn a presentational primitive that is sufficient as a single package import into a registry snippet merely because of a "full component flow".
🔒 Gate Delivery Surface → 0Pre
- Public surface finalized: package-only / snippet-only / package+snippet / docs-only
- Check docs Usage, registry, package export, and example surface of the equivalent React/Lynx component
- If a snippet is needed, explain the wrapper value in one sentence
- If a snippet is not needed, explicitly exclude registry/vendored example work
Phase 0 Pre: Requirements Brainstorming
Read immediately upon entry → references/brainstorming.md
Based on the Platform Gate results, agree with the user in a 1:1 conversation on 5 areas (Purpose / Relationship with existing / Edge cases / Token dependency / External reference priority). Ask one question at a time, multiple choice preferred. Do not fill in by guessing.
Deliverable: agreement summary (memo or PR description draft).
🔒 Gate 0Pre → 0
The user must explicitly confirm **"proceed as is"** after reviewing the agreement summary to enter Phase 0.
Phase 0: Architecture Analysis
Read on entry → references/architecture-decisions.md
Using the Phase 0 Pre agreement as input, determine the component category (A–E), whether it is a Headless layer, dependency stability, external references + accessibility, and pattern reference components.
Conditional additional reference:
- After category is finalized →
references/pattern-catalog.md(references by category + utility map) - When researching external libraries / deciding to borrow →
references/external-references.md(library priority + borrowing decision tree + ARIA/WCAG) - target platform이
lynxorcross-platformif so →references/lynx-patterns.md(Lynx runtime constraints + headless/styled responsibility separation)
🔒 Gate 0 → 1
- All items in the architecture-decisions.md checklist completed
- If dependency is BLOCKING, do not start implementation (sticking-policy로)
- Report the "Phase 0 result summary" to the user and get confirmation
Phase 1: Implementation
Read on entry → references/implementation-steps.md (full implementation procedure)
Auxiliary → references/guide.md (full flow overview, quick reference)
When entering each step, first read the AGENTS.mdof the target folder to modify, then read the corresponding file of the pattern reference component before implementing.
Step-by-step reference (read only when entering that step):
| Step | Reference to read |
|---|---|
| Recipe authoring | React는 references/recipe-patterns.md, Lynx는 references/lynx-patterns.md + packages/lynx-qvism-preset/AGENTS.md |
| Styled UI authoring | React는 references/react-patterns.md, Lynx는 references/lynx-patterns.md |
| Snippet layer design | references/api-design.md |
| Headless hook/primitive design (category C/D) | React는 references/external-references.md, Lynx는 references/lynx-patterns.md |
| Storybook authoring (React) | references/storybook.md |
🔒 Gate 1 → 2
All 4 automated verification commands must pass to enter Phase 2:
bun generate:all # 토큰/recipe 생성
bun test:all # 단위 테스트
bun packages:build # 패키지 빌드
bun docs:test # 문서 정합성
If any one fails, follow the sticking-policy.
Phase 2: Verification
Read on entry → references/verification-checklist.md + references/visual-testing.md
Required for React work:
- Storybook 4 themes/scales (Light / Dark / FontScaling ExtraSmall / ExtraExtraExtraLarge)
examples/stackflow-spaCheck for similar Activity (if none, consider creating one)- Component page rendering on the docs site
Required for Lynx work:
examples/lynx-spaCheck for a similar page or vendored snippetdocs/content/lynxSync with the public surface.docs/registry/lynx/uiCheck the vendored snippet only if the Delivery Surface Gate determined that a snippet is needed- Check the Lynx package build/test or the root Lynx verification script
Finally, create a changeset with the /changeset skill.
🔒 Gate 2 → Complete
- All items in the verification-checklist passed
- Report visual screenshot to the user + final confirmation
Reference file index
| Phase | File | When to read |
|---|---|---|
| Common | references/sticking-policy.md |
When blocked |
| Platform | references/platform-gate.md |
Immediately when starting component work |
| Delivery Surface | references/api-design.md |
When deciding the public surface right after the Platform Gate |
| 0 Pre | references/brainstorming.md |
Immediately upon entering Phase 0 Pre |
| 0 | references/architecture-decisions.md |
Immediately upon entering Phase 0 |
| 0 | references/pattern-catalog.md |
After the category is finalized |
| 0 | references/external-references.md |
When doing external research / deciding on borrowing (also when designing Headless hooks in Phase 1) |
| 0/1 | references/lynx-patterns.md |
target platform이 lynx or cross-platform일 때 |
| 1 | references/guide.md |
Auxiliary when entering Phase 1 |
| 1 | references/implementation-steps.md |
When entering Phase 1 |
| 1 | references/recipe-patterns.md |
Recipe authoring stage |
| 1 | references/react-patterns.md |
React Styled UI stage |
| 1 | references/api-design.md |
Snippet layer stage |
| 1 | references/storybook.md |
When authoring/refactoring React Storybook |
| 2 | references/verification-checklist.md |
When entering Phase 2 |
| 2 | references/visual-testing.md |
When entering Phase 2 |
| Maintenance | references/review-prompts.md |
When reviewing the documentation after modifying this skill itself |
Correction Retro: self-improvement after user adjustment
When the user makes an adjustment such as "Is this necessary?", "Why did you judge it this way?", or "I don't think this pattern is right," do not just fix the implementation—perform a short retro.
- Missing context: Which of repo/docs/analog did you not check, causing the judgment to waver?
- Incorrectly applied pattern: Where did you overgeneralize an existing success case or skill rule?
- Next judgment rule: In the same situation, what signals should be checked first and what work should be excluded?
- Skill update candidate: Propose which reference to add it to as a durable rule.
If the user wants to reinforce the skill or explicitly asks you to remember it, based on the above retro, SKILL.md or update the relevant reference as well.