eliteforge-google-stitch-onboarding

name	eliteforge-google-stitch-onboarding
description	Guides agents through the first frontend implementation pass from a Google Stitch prototype bundle. Use when the user asks to initialize a frontend project from tech-stack.md, convert design.md/prd.md and Stitch HTML/image prototypes into consistent pages, create mock-data-backed screens with reserved backend API calls, and coordinate every phase with $eliteforge-task-progress-tracker and user confirmations. Activation gate - use this skill only when the user explicitly states that the current project follows `璀璨工坊规范` or `eliteforge specification`.
compatibility	expects the companion $eliteforge-task-progress-tracker skill to be available.
metadata	{"author":"eliteforge","version":"1.0.0"}

EliteForge Google Stitch 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 implementation pass from a Google Stitch export. Keep it incremental, auditable, and confirmation-gated.

Mandatory orchestration rule

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

Use docs/tasks/google-stitch-onboarding/ as the task-root override. Do not write google-stitch-onboarding bookkeeping under .eliteforge/google-stitch-onboarding/ or repository-root tasks/google-stitch-onboarding/.

• Top-level tracker task file: docs/tasks/google-stitch-onboarding/google-stitch-onboarding.md.
• Child tracker task files, if the tracker stores child tasks as separate files: docs/tasks/google-stitch-onboarding/google-stitch-onboarding-N.md.
• State file: docs/tasks/google-stitch-onboarding/state.md.
• Implementation ledger: docs/tasks/google-stitch-onboarding/implemented-pages.txt.
• Acceptance manifest: docs/tasks/google-stitch-onboarding/acceptance-manifest.md.
• Integration test plan: docs/tasks/google-stitch-onboarding/integration-test-plan.md.

During tracker setup, check whether the current directory is already inside a Git repository. If not, run git init in the current directory before recording tracker files, then record the command/result in the tracker and docs/tasks/google-stitch-onboarding/state.md.

Create top-level task google-stitch-onboarding and child tasks google-stitch-onboarding-1 through google-stitch-onboarding-4.

Every top-level step row under ## Steps must start with the exact relative Markdown link to its child task:

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

Step scope:

• Step 1: initialize from tech stack plus design docs and create /design-standard.
• Step 2: read product/design docs, scan every prototype page, and establish shared layout plus common components.
• Step 3: traverse all Stitch pages, implement them with mock data plus API boundaries, and record page acceptance evidence.
• Step 4: perform final quality acceptance across coverage, visual structure, interactions, and deviations.

Gate every step through waiting_human_decision. If a required decision is unclear, stop before guessing and record the exact question in both the top-level step and active child task. After a step's work and validation finish, set both rows to waiting_human_decision, ask for acceptance, and do not continue until the user confirms.

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, Google Stitch 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 inputs: tech stack doc, design doc, PRD, and a Google Stitch export or ZIP whose page directories contain code.html and usually screen.png. Accept canonical names such as tech-stack.md, docs/tech-stack.md, design.md, DESIGN.md, prd.md, and *_prd.md, plus clearly named nested equivalents. Record any non-canonical mapping in the tracker and state file. Missing tech stack or design input is a Step 1 blocker 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.
• scripts/acceptance_check.sh verifies source coverage, the page implementation contract, ledger entries, acceptance-manifest page entries, the integration test plan, runtime naming boundaries, and required route/critical-journey acceptance sections.
• assets/acceptance-manifest-template.md provides the required acceptance manifest structure.
• assets/integration-test-plan-template.md provides the required integration test plan structure.

Read references/google-stitch-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.
• Read the design document early enough to seed baseline color, typography, spacing, and tokens before creating styles or theme configuration.
• Stage 1 must create a runnable /design-standard preview using normal routing. Do not use / for this page unless explicitly requested; preserve it throughout later steps and never count it as a Stitch page.
• 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.
• Keep source identity separate from product identity. Source identity is the Stitch page directory, code.html, rendered image, and inventory number; use it only for traceability, coverage, and evidence. Product identity is the real product page name, route, component/page module, service/API boundary, and navigation label; use it for implementation.
• Step 2 must create a page implementation contract before product page implementation begins. Derive product identity in this order: PRD information architecture or feature modules, design document page titles or navigation, visible prototype title/menu text, semantic text from code.html, then source directory name only as a derivation clue. If product identity remains unclear, stop at waiting_human_decision; do not generate source-shaped implementation names.
• Runtime code must be named from product identity. Source identity terms such as prototype/stitch page names may remain in onboarding docs, ledgers, source inventories, and explicit prototype viewer or evidence tooling, but they must not become the default names for product pages, routes, components, service modules, mocks, or navigation entries.
• Step 2 must derive a project-specific shared shell contract from design.md plus the actual Stitch pages before building shared layout primitives. The contract must capture visible shell regions, spatial relationships, ownership of viewport space, responsive behavior when specified or visible, and required shell interactions from design docs or prototypes. Do not use a generic shell contract.
• Build shared layout primitives before duplicating page code: app shell, navigation regions, 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.
• Routing, entry state, and user journeys are part of the deliverable. Step 2 must define the route and navigation contract before Step 3 page implementation begins, including the root route /, auth/public route exceptions, default post-login route, sidebar/topnav destinations, cross-page action destinations, and fallback/redirect behavior.
• If the prototype or PRD contains an auth/login page, the unauthenticated first visit to / must render the login/auth experience unless the user explicitly approves a different entry route. The login action must visibly transition into the authenticated system route through the real router or state model; a button that does not change route, auth state, or visible shell state is a blocker.
• Any visible primary action such as import, create/new, edit, view detail, submit, cancel, tab, filter, search, pagination, upload, drawer, modal, or row action must have minimum observable behavior. A visible enabled control with no click/submit behavior is a hard failure, not a cosmetic gap.
• Step 2 must create an integration test plan from design.md, PRD, and the prototype scan before Step 3 implementation begins. The plan must enumerate realistic browser scenarios, expected route/state/UI results, test data, and acceptance evidence for all product flows that are visible in the prototype or specified by the PRD.
• Step 4 must start or restart the real frontend app with the project's normal dev or preview command and execute the integration test plan through actual browser interactions. Do not rely on an unknown pre-existing server as acceptance evidence. The agent must interact with the page itself using Playwright, the in-app browser, or an equivalent browser runtime. Static review, source inspection, screenshots before clicks, or HTTP 200 checks are not enough.
• This skill explicitly requires and authorizes multi-agent delegation for large page-batch actions. When the current action is execute_current_step and the active step contains page-batch work with more than two batches, use worker subagents for non-overlapping page batches. This applies to Step 2 full prototype scans, Step 3 page implementation, and any similar large batch of pages.
• The lead agent owns only shared contracts, integration, ledger/manifest/state updates, validation, tracker updates, and user confirmation for delegated page-batch work. It must not serially perform worker-owned page batches after the mandatory delegation condition is met.
• If worker subagents are unavailable when mandatory delegation is required, record a blocker in the tracker/state, set the active rows to waiting_human_decision, and stop instead of silently doing the batch work in the lead agent.
• Maintain a local implementation ledger at docs/tasks/google-stitch-onboarding/implemented-pages.txt. Append one source prototype page name per line only after its route/page/component, API-ready service boundary, visual-structure check, and interaction smoke check have passed.
• Maintain docs/tasks/google-stitch-onboarding/state.md with source paths, prototype inventory, page implementation contract, page archetype scan, route mapping, route/navigation contract, critical user journeys, validation commands, and decisions.
• Maintain docs/tasks/google-stitch-onboarding/acceptance-manifest.md once page implementation begins. Record each Stitch source page's product identity, route, component, service/API boundary, primary archetype, visual-structure evidence, interaction smoke evidence, route/navigation evidence, accepted deviations, and blockers.
• Maintain docs/tasks/google-stitch-onboarding/integration-test-plan.md once Step 2 has enough design/PRD/prototype evidence. Keep it synchronized as routes and flows are implemented.
• Maintain a critical journey smoke matrix in the acceptance manifest. At minimum include entry route and auth/login flow when present, main shell navigation, and every page-level primary action that is visible in the prototypes or required by the PRD. Examples are illustrative only: login -> default system page, an import action opening an import dialog/drawer/file input when such an action exists, or a create/new action opening the expected create route/form when such an action exists.

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 a full scan of every Stitch page.
• The page implementation contract maps every Stitch source page to a product identity before Step 3 begins; unresolved product identities are blockers, not implementation placeholders.
• Every Stitch page directory containing code.html has a corresponding route/page/component or documented equivalent, and each page passes visual-structure acceptance.
• Product page routes, components, modules, service boundaries, mocks, and navigation labels use product identity, while source identity remains limited to coverage and evidence artifacts.
• Every Stitch page preserves the prototype's primary main-content archetype; kanban boards, split panes, data tables, forms, chats, graphs, dashboards, detail inspectors, auth flows, and similar structures must not be replaced by a generic card template.
• Every page using the shared shell conforms to the project-specific shared shell contract extracted from design docs plus the prototype. Shared shell structural or interaction mismatch is a hard failure for every affected page.
• The root route, auth/public entry routes, default post-login route, and navigation/action destinations conform to the Step 2 route and navigation contract.
• Every interactive control category visible in the prototype has minimum observable behavior verified through a browser-driven or equivalent runtime smoke test. Blocked, unimplemented, or unverified control behavior cannot count as a pass.
• The acceptance manifest contains critical journey evidence that shows the starting route, action sequence, expected result, actual route/state change, and pass/fail result. Login flows, navigation links, and primary page actions cannot be accepted from source-code inspection alone.
• docs/tasks/google-stitch-onboarding/integration-test-plan.md exists, is derived from design docs/PRD/prototypes, and has been executed against the real running frontend app.
• Step 4 evidence records the frontend start command, local URL, browser/runtime tool used, scenario results, and any console/runtime errors encountered during testing.
• Each page uses mock data through an API-ready boundary.
• Coverage check shows no missing prototype pages.
• Acceptance check shows no missing implementation-contract rows, no missing manifest product identity entries, no source-identity leakage into runtime implementation paths, and no missing route/critical-journey sections.
• docs/tasks/google-stitch-onboarding/acceptance-manifest.md exists and is maintained with page-by-page visual, structural, and interaction acceptance evidence.
• /design-standard, route 200 checks, screenshot dimensions, build/typecheck success, source-structure checks, and implementation-ledger coverage are baseline gates only; they do not constitute final acceptance without visual-structure and interaction evidence in the acceptance manifest.
• The tracker contains completed child tasks google-stitch-onboarding-1 through google-stitch-onboarding-4.
• No Google Stitch onboarding bookkeeping files are written outside docs/tasks/google-stitch-onboarding/.