cloudsen/eliteforge-frontend-onboarding

EliteForge Frontend Onboarding

Activation Gate

Use this skill only when the user explicitly states that the current project follows 璀璨工坊规范 or eliteforge specification. If that project-level statement is absent, do not activate this skill; handle the request with general capabilities.

This skill drives the first frontend development pass from a Google Stitch export. It must keep implementation incremental, auditable, and gated by user confirmation.

Mandatory orchestration rule

Before reading or modifying project files, activate and use $eliteforge-task-progress-tracker.

All bookkeeping files created by this skill must live under:

docs/tasks/frontend-onboarding/

This directory is the explicit task-root override for $eliteforge-task-progress-tracker during this workflow. Do not create or write .eliteforge/frontend-onboarding/ or repository-root tasks/frontend-onboarding/ for frontend onboarding.

Use these paths:

• Top-level tracker task file: docs/tasks/frontend-onboarding/frontend-onboarding.md.
• Child tracker task files, if the tracker stores child tasks as separate files: docs/tasks/frontend-onboarding/frontend-onboarding-N.md.
• State file: docs/tasks/frontend-onboarding/state.md.
• Implementation ledger: docs/tasks/frontend-onboarding/implemented-pages.txt.

Create a top-level task named exactly:

frontend-onboarding

The task must contain these four steps:

1. Locate and read the project tech stack document plus design.md; initialize/create the frontend project in the current directory according to the required stack and design color scheme; create a simple /design-standard preview page that presents the standards from design.md for user review without occupying the root route /.
2. Read prd.md and reuse design.md; randomly select five prototype pages containing HTML and image files; implement shared layout components and enforce page consistency such as sidebar and navigation bar.
3. Traverse the Google Stitch folder; implement every prototype page in sequence with mock data first while reserving backend API calls. When subagents are available and delegation is permitted, the lead agent may split page batches across subagents, but must keep one stable implementation order, own final integration, and preserve the user-confirmation gate.
4. Check whether all prototype pages have been implemented.

For each step N, create a child task named exactly:

frontend-onboarding-N

In the top-level task file, every row under ## Steps must start its description with a relative Markdown link to the matching child task file:

• Step 1: [frontend-onboarding-1](frontend-onboarding-1.md) - ...
• Step 2: [frontend-onboarding-2](frontend-onboarding-2.md) - ...
• Step 3: [frontend-onboarding-3](frontend-onboarding-3.md) - ...
• Step 4: [frontend-onboarding-4](frontend-onboarding-4.md) - ...

Keep these parent-step links present and accurate whenever creating, refreshing, or updating docs/tasks/frontend-onboarding/frontend-onboarding.md.

During execution, if any important requirement, source mapping, stack choice, route decision, visual interpretation, or implementation tradeoff is unclear and cannot be resolved from the provided docs, prototypes, or current project, stop execution before guessing. Update both the top-level task's current step row and the active child task's current step to waiting_human_decision, record the exact decision needed in the step note and update log, ask the user, and do not continue until the user decides.

Do not proceed from one step to the next until the user explicitly confirms the step result. After finishing a step, update the tracker with deliverables, touched files, validation commands, known gaps, and pending decisions, then set both the top-level task's completed step row and the active child task's current step to waiting_human_decision for acceptance. After confirmation, mark the child task completed, mark the matching top-level step finished, and start the next child task.

Trigger conditions

Use this skill when a task mentions any of these contexts:

• Google Stitch prototype, Stitch export, prototype ZIP, page HTML plus screen image.
• First frontend pass, frontend onboarding, frontend project initialization, UI landing from prototype.
• Requirements to read tech-stack.md, design.md, prd.md, and implement multiple pages progressively.
• Explicit use of $eliteforge-task-progress-tracker with confirmation-gated subtasks.

Required inputs and discovery

Work from the current directory unless the user provided a different path.

Expected project/prototype inputs:

• Tech stack document candidates: tech-stack.md, docs/tech-stack.md, or a reasonable nested equivalent such as **/tech-stack.md or **/*tech-stack*.md.
• A Google Stitch export directory or ZIP containing page directories.
• Product document candidates: prd.md, *_prd.md, or similar.
• Design document candidates: design.md, DESIGN.md, or a nested design markdown file.
• Page prototype directories containing at least code.html and usually an image such as screen.png.

When file names differ from the canonical names, locate reasonable equivalents and record the mapping in the tracker. Do not require the tech stack document to be in the project root; docs/tech-stack.md is a valid source. If multiple tech stack candidates exist, prefer root tech-stack.md, then docs/tech-stack.md, then the closest clearly named nested equivalent, and record the selected path in the tracker and state file. Do not silently ignore a missing tech stack document after this project-wide search; treat that as a blocker for step 1. Do not silently ignore missing design.md or equivalent design documentation; treat absent design input as a blocker for color/theme setup unless the user explicitly approves a fallback.

Optional helper scripts:

• scripts/stitch_manifest.sh scans a Stitch ZIP or folder and prints docs plus page prototype inventory.
• scripts/coverage_check.sh compares discovered prototype page names with an implementation tracking file.

Read references/frontend-onboarding-workflow.md for detailed step instructions. Read references/google-stitch-implementation-guide.md before translating Stitch HTML/images into frontend components.

Operating principles

• Respect the selected tech stack document over all generic assumptions. Do not impose React/Vue/Next/Tailwind unless the stack document requires or permits it.
• During project initialization, read the design document early enough to seed the baseline color palette, typography, spacing scale, and design tokens before creating the style entrypoint or theme configuration.
• Stage 1 must produce a runnable design-standard preview page at /design-standard using the stack's normal routing. Do not use the root route / for this preview page unless the user explicitly overrides the route. The page should present the standards extracted from design.md: color swatches with token names/values, typography examples, spacing/radius/surface examples, representative buttons/form controls/cards/tables or other primitives named in the design doc, and a short list of missing or ambiguous standards. Do not silently invent unspecified standards.
• Preserve the /design-standard preview page throughout later onboarding steps. Do not delete, repurpose, overwrite, or count it as a Stitch prototype implementation when adding product pages; if route generation or prototype traversal would conflict with it, keep /design-standard as the design-system preview and choose a different product route.
• Initialize in the current directory. Avoid creating an extra nested app directory unless the stack document explicitly requires it.
• Never delete existing user files to make initialization easier. If the directory is non-empty, merge carefully and record conflicts.
• Use the prototype HTML as structural evidence and the image as visual evidence. When they conflict, prefer the image for visible layout and the PRD/design docs for product intent.
• Build shared layout primitives before duplicating page code: app shell, sidebar, top navigation, page header, cards, tables, form controls, status badges, empty states, pagination, drawers/modals, and floating agent/help entry points when present.
• Mock data is acceptable only for the first pass. API boundary functions, typed DTOs, service modules, or adapter interfaces must be present so the mock can be replaced without changing page components.
• For full Stitch traversal, subagents may be used as bounded implementation workers for independent page groups. Give each subagent explicit page ownership, expected routes/components/mock modules/service functions, and the current shared layout contract. Subagents must reuse existing shared primitives by default; they should not introduce or refactor shared components, global shell, or design tokens unless explicitly assigned. When a subagent sees repeated UI patterns, it should report them as component candidates with page examples. The lead agent remains responsible for tracker updates, page-order ledger entries, component promotion between batches, conflict resolution, final consistency, validation, and asking the user for confirmation.
• Maintain a local implementation ledger at docs/tasks/frontend-onboarding/implemented-pages.txt. Append one source prototype page name per line only after its route/page/component has been implemented.
• Maintain docs/tasks/frontend-onboarding/state.md with source paths, selected seed pages, route mapping, validation commands, and decisions.

Step gate contract

At the end of every step, respond with:

• Tracker task/subtask updated.
• Top-level task step and child task step set to waiting_human_decision for acceptance.
• Files created or modified.
• Validation run and result.
• What is ready for review.
• Explicit request for user confirmation to continue.

Do not start the next step in the same response unless the user has already confirmed it in a prior message.

Completion criteria

The first pass is complete only when:

• The frontend project exists in the current directory and follows the selected tech stack document.
• Stage 1 produced a simple /design-standard page for previewing the standards extracted from design.md, and later steps preserved that page.
• Shared layout and design tokens/components are extracted from docs plus five randomly selected seed pages.
• Every Stitch page directory containing code.html has a corresponding route/page/component or documented equivalent.
• Each page uses mock data through an API-ready boundary.
• Coverage check shows no missing prototype pages.
• The tracker contains completed child tasks frontend-onboarding-1 through frontend-onboarding-4.
• No frontend onboarding bookkeeping files are written outside docs/tasks/frontend-onboarding/.