Eliteforge Google Stitch Onboarding

EliteForge Google Stitch Onboarding

This skill expects the companion $eliteforge-task-progress-tracker skill to be available.

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/.

Google Stitch Onboarding Acceptance Manifest

Store this file as docs/tasks/google-stitch-onboarding/acceptance-manifest.md.

Route and navigation contract

• Root route /:
• Public/auth routes:
• Authenticated routes:
• Default post-login/authenticated route:
• Shell navigation targets:
• Primary cross-page action targets:
• Unknown-route/fallback behavior:
• Route guards/auth state model:
• Evidence and unresolved decisions:

Page implementation contract

Each row links source evidence to the product identity used in runtime implementation.

Prototype page acceptance

Repeat this block for every Stitch page directory containing code.html.

Page: <prototype-directory-name>

• Source identity:
• Product page:
• Route:
• Component/page module:
• Service/API boundary:
• Navigation label:
• Primary archetype:
• Shared shell evidence:
• Route/navigation evidence:
• Visual-structure evidence:
• Interaction smoke evidence:
• Accepted deviations:
• Blockers:

Critical journey smoke tests

Only include journeys that are visible in the prototypes or required by the PRD. Do not add global actions that a page does not actually expose.

Unresolved blockers

• none

Google Stitch Onboarding Integration Test Plan

Store this file as docs/tasks/google-stitch-onboarding/integration-test-plan.md.

Create this plan from design.md, PRD, and the scanned Stitch prototypes before full page implementation begins. Keep only scenarios that are visible in the prototypes or required by the PRD.

Source basis

• Design document:
• PRD:
• Prototype source:
• Page implementation contract source:
• Route/navigation contract source:
• Known exclusions approved by user:

Test environment

• Package manager:
• Frontend start command:
• Expected local URL:
• Browser/runtime tool:
• Required test data:

Integration scenarios

Execution evidence

Record results only after starting the real frontend app and interacting with the page in a browser runtime.

Unexecuted or failed scenarios

• none

Google Stitch Onboarding State

Store this file as docs/tasks/google-stitch-onboarding/state.md.

Stack

• Selected tech stack document path:
• Framework:
• Package manager:
• Build command:
• Lint/typecheck/test commands:

Repository

• Git repository detected:
• Git init command/result:

Stage 1 design-standard preview

• Design-standard route:
• Design-standard file(s):
• Standards rendered from design.md:
• Missing or ambiguous standards:

Prototype source

• Stitch source path:
• PRD path:
• Design path:

Prototype scan for shared layout

• Prototype page count:
• Shared shell contract:
• Page archetype summary:
• Shared component candidates:

Page implementation contract

Use source identity only for traceability and evidence. Use product identity for routes, components, modules, services, mocks, and navigation.

Shared shell evidence

Design/prototype conflicts

Route mapping

Route and navigation contract

• Root route /:
• Public/auth routes:
• Authenticated routes:
• Default post-login/authenticated route:
• Shell navigation targets:
• Primary cross-page action targets:
• Unknown-route/fallback behavior:
• Route guards/auth state model:
• Evidence and unresolved decisions:

Critical journey inventory

Integration test plan

• Plan file:
• Source basis:
• Frontend start command:
• Expected local URL:
• Browser/runtime tool:
• Scenario count:
• Execution status:
• Failed or unexecuted scenarios:

Runtime interaction smoke log

Validation log

Known gaps

-

eliteforge-google-stitch-onboarding

An Agent Skill for progressively implementing a frontend project from a Google Stitch prototype export. The executable entrypoint for agents is SKILL.md, Stage 1 includes a simple /design-standard preview page from design.md that must be preserved through later page implementation, route and navigation behavior must be validated through a design/PRD/prototype-derived integration test plan executed against the real running frontend app, and all workflow bookkeeping is constrained to docs/tasks/google-stitch-onboarding/.

Google Stitch Prototype Implementation Guide

Prototype interpretation

A typical Google Stitch export contains multiple page directories. Each page directory usually has:

• code.html: generated static HTML with styling hints and semantic text.
• screen.png or another image: rendered visual target.

Treat the HTML and image as complementary:

• HTML is best for structure, labels, icon names, table columns, form fields, and approximate class semantics.
• Image is best for visual hierarchy, spacing, placement, density, and what is actually visible.
• PRD is authoritative for feature intent and naming.
• Design doc is authoritative for global theme, typography, spacing, radius, and shell consistency.

Component extraction rules

Extract shared components when they appear in two or more pages or are part of the platform shell:

• App shell.
• Sidebar and sidebar section groups.
• Top navigation/header bar.
• Workspace selector and global search.
• Page title block and actions area.
• Data table with toolbar/filter/pagination.
• Card, metric card, status badge, tag, avatar, empty state.
• Form field, select, switch, tab, segmented control.
• Modal/drawer/dialog if present.
• Floating agent/help button if present.

Avoid translating every HTML page into one monolithic component. The first pass should produce maintainable frontend structure, not static screenshots.

Do not treat a shared generic renderer as page implementation unless it preserves the prototype's primary layout archetype and required interactions. A generic renderer may reduce duplication, but it cannot erase page-specific structures such as kanban columns, split panes, detail inspectors, toggles, tabs, drawers, or form flows.

Shared shell contract

The shared shell is project-specific and must be derived from design.md plus the current Stitch prototype, not from a default dashboard template. During Step 2, record the shell contract before implementing product pages:

• Visible shell regions and their relative placement.
• Viewport-space ownership by shell regions and content regions.
• Fixed, sticky, scrollable, or responsive behavior visible in the prototype.
• Shell controls and their required observable behavior from design docs or prototypes.
• Pages that use the shell and pages that intentionally do not.
• Evidence source: design.md section names, page names, and whether the page evidence came from code.html, screen.png, or both.
• Conflicts between design docs and prototypes, recorded as blockers or explicit normalization decisions.

Visible layout is primarily verified against the prototype image, while design.md may define shell interaction, responsive behavior, naming, and consistency rules that are not fully visible in one screenshot. If design docs and prototype evidence conflict materially, stop and record the decision instead of silently choosing a generic shell.

During Step 3 and Step 4, a page using the shared shell cannot pass if the rendered shell violates this contract. HTTP 200, screenshot size, component existence, or source-code shape can support validation, but none of them replaces visual shell parity against the design/prototype evidence.

Page implementation contract

Build product pages from a contract, not directly from source directory names.

Identity separation:

• Source identity: Stitch page directory, code.html, rendered image, and inventory number. Use it for traceability, coverage, and evidence.
• Product identity: real product page name, route, component/page module, service/API boundary, mock data module, and navigation label. Use it for implementation.

Derive product identity in this order:

1. PRD information architecture, feature modules, or named workflows. 2. Design document page titles, navigation labels, or screen taxonomy. 3. Visible prototype titles, menus, breadcrumbs, table headings, or form headings. 4. Semantic text and accessible labels in code.html. 5. Source directory names only as derivation clues, never as unreviewed implementation names.

Before Step 3 begins, record the page implementation contract in docs/tasks/google-stitch-onboarding/state.md. If a source page cannot be mapped to a product identity with evidence, stop for a human decision instead of creating a source-shaped page/module name.

The contract should be the only input for runtime naming. Source identity may remain in source inventories, ledgers, acceptance evidence, and explicit prototype viewer or evidence tooling, but not as the default namespace for product routes, pages, components, mocks, services, or navigation.

Routing

Routing is product behavior, not just file naming. Before page implementation, record the entry route, public/auth route exceptions, authenticated route guard behavior, default post-login route, shell navigation targets, cross-page action destinations, and unknown-route fallback. If the prototype or PRD contains a login/auth flow, / should render that entry experience unless the user explicitly accepts a different first route.

Recommended product-identity normalization:

• dashboard_light -> dashboard route.
• task_management_light -> task management route.
• create_task_full_width_console_layout -> create task route.
• Duplicated variants such as _1 and _2 should become distinct states or variants only if the prototype visibly differs; otherwise document them as aliases.

Record all route decisions with their product identity and source evidence in docs/tasks/google-stitch-onboarding/state.md.

Runtime interaction smoke

Build an interaction inventory from what is visible in the prototype and required by the PRD. Do not invent controls that are not present, and do not require every page to support the same actions. Each visible enabled control must either have an observable runtime behavior or be recorded as a blocker.

Turn that inventory into docs/tasks/google-stitch-onboarding/integration-test-plan.md before final implementation/acceptance. The plan must be based on design docs, PRD, and prototype evidence, and it must be executable against the real frontend app after starting the normal dev or preview server.

Minimum observable behavior means one of these outcomes after a browser-driven action:

• Route changes to the expected page.
• Auth/session state changes and the authenticated shell appears.
• Modal, drawer, popover, menu, or file picker opens or closes.
• Form validation, submission state, or created/updated mock data becomes visible.
• Search, filter, sort, tab, pagination, or selection state changes visible content.
• A disabled/unavailable action is visibly disabled with a reason that matches the PRD/prototype.

Hard failures:

• Login/auth submit remains on the same static page with no auth state, route, or visible shell transition.
• An enabled link or button has no click/submit handler and no route target.
• Navigation items render labels but do not route or update active state.
• A page is represented by a generic fallback that drops its prototype-specific main archetype or expected interactions.

Record interaction smoke evidence in docs/tasks/google-stitch-onboarding/acceptance-manifest.md as a critical journey matrix with starting route, action sequence, expected result, actual route/state/UI result, evidence method, and pass/fail result.

Final acceptance requires executing the integration plan in a browser runtime. Record the frontend start command, local URL, browser/runtime tool, scenario results, and console/runtime errors. A page cannot pass final acceptance if its relevant scenario was not actually clicked through in the running app.

Mock data and API boundary

Every page should read data through a replaceable boundary:

• Service function or repository module.
• Typed DTOs/interfaces if the stack supports types.
• Mock adapter or fixture module.
• Clear placeholder endpoint name and parameters.

Example conceptual shape:

page/component -> hook/store/controller -> service/repository -> mock adapter for now

Do not bind page components directly to inline arrays when a backend call is expected later.

Visual consistency checklist

For each implemented page, check:

• Same shared shell contract where the prototype uses the shared shell.
• Same navigation region dimensions, selected states, section order, and icon style where the design/prototype defines navigation regions.
• Same header/topbar/workspace/user controls and global actions where the design/prototype defines them.
• Same content max width or full-width behavior for dense console pages.
• Same typography scale and tabular number treatment.
• Same spacing increments from design doc.
• Same card/table/form radius and border/shadow treatment.
• Same semantic badge color logic.
• Same loading, empty, and error state conventions.

Handling inconsistent prototypes

Google Stitch may generate inconsistent shell markup across pages. Normalize shared elements instead of reproducing inconsistency. Record material normalization decisions in the tracker and state file.

Coverage ledger

Use docs/tasks/google-stitch-onboarding/implemented-pages.txt as a simple source-of-truth ledger. It must contain exact prototype directory names, one per line, for pages that have been implemented.

Do not add a page to the ledger until the route/page/component exists and compiles, the API-ready service boundary exists, and visual-structure plus interaction smoke evidence has been recorded in docs/tasks/google-stitch-onboarding/acceptance-manifest.md.

Google Stitch Onboarding Workflow

0. Start and task tracker setup

1. Activate $eliteforge-task-progress-tracker. 2. Set the tracker task root to docs/tasks/google-stitch-onboarding/; do not create .eliteforge/google-stitch-onboarding/ or repository-root tasks/google-stitch-onboarding/ for this workflow. 3. Check whether the current directory is inside a Git repository before recording tracker files. If not, run git init in the current directory. Record the command/result in the tracker setup log and docs/tasks/google-stitch-onboarding/state.md; a missing Git repository is not a blocker. 4. Create top-level task google-stitch-onboarding with four ordered steps. Each step description must begin with the exact relative Markdown-link prefix for its child task file:

• Step 1 prefix: [google-stitch-onboarding-1](google-stitch-onboarding-1.md) - followed by locating and reading the project tech stack document plus design.md, initializing the frontend project with the design color scheme, and creating a simple /design-standard page that previews the standards from design.md without occupying the root route /.
• Step 2 prefix: [google-stitch-onboarding-2](google-stitch-onboarding-2.md) - followed by reading product docs, reusing design docs, scanning every prototype page, deriving the page implementation contract, and implementing shared layout plus common components.
• Step 3 prefix: [google-stitch-onboarding-3](google-stitch-onboarding-3.md) - followed by implementing every contracted product page from its Stitch source evidence with mock data, API boundaries, route wiring, and observable interactions.
• Step 4 prefix: [google-stitch-onboarding-4](google-stitch-onboarding-4.md) - followed by final quality acceptance for all prototype pages, route wiring, and critical user journeys.

5. Store the top-level tracker file at docs/tasks/google-stitch-onboarding/google-stitch-onboarding.md. 6. Create child task google-stitch-onboarding-1 and mark it in progress. If child tasks are separate tracker files, store them as docs/tasks/google-stitch-onboarding/google-stitch-onboarding-N.md. 7. Use docs/tasks/google-stitch-onboarding/ for tracker files, state files, and coverage ledgers. 8. Whenever creating or updating child tasks, keep the parent task's step links pointing to the matching child task files.

Do not perform project setup before this tracker setup, including Git repository initialization status, is recorded.

Common gate

If any important requirement, source mapping, stack choice, route decision, visual interpretation, or implementation tradeoff is unclear during any step, stop before guessing. Update both the top-level task's active step row and the active child task's current step to waiting_human_decision, record the exact decision needed in each task's step note and update log, ask the user, and do not continue until the user decides.

Do not treat "page exists" as equivalent to "flow works". A route, auth transition, navigation item, or enabled control that does not produce the expected observable page/state change is unfinished work. Record it as a blocker and keep the active step incomplete.

When a step's required actions and validation are complete, do not immediately mark that step finished. Update both the matching top-level step row and active child task step to waiting_human_decision, record deliverables, touched files, validation results, gaps, and pending decisions, ask for user acceptance, and stop. Only after the user confirms should the agent mark that child task completed, mark the matching top-level step finished, and start the next child task. For Step 4, final user confirmation completes both google-stitch-onboarding-4 and the top-level task.

Mandatory worker delegation

Automation prompt constraint: this is an explicit delegation requirement. When the current action is execute_current_step and the page batch count is greater than 2, the lead agent must use worker subagents to split non-overlapping page batches. The lead agent is responsible only for shared contracts, integration, ledger/manifest/state updates, validation, and tracker updates.

Apply this to Step 2 full prototype scans, Step 3 page implementation, and any similar large page-batch work. Before spawning workers, the lead agent must define the source inventory, page implementation contract, stable ordering, batch boundaries, shared shell/component contract, service/mock contract, and expected worker output. Workers must implement only the product identities assigned by the contract and must not edit global shell, design tokens, shared components, or another worker's page files unless explicitly assigned.

If worker subagents are unavailable when this rule applies, set the active top-level and child task rows to waiting_human_decision, record the blocker, and stop. Do not fall back to serial lead-agent execution.

1. Step google-stitch-onboarding-1: initialize project from the tech stack document and design.md

Required actions:

1. Locate and read the project tech stack document. Prefer ./tech-stack.md, then ./docs/tech-stack.md, then a clearly named nested equivalent such as **/tech-stack.md or **/*tech-stack*.md. Record the selected path. Do not fail only because the file is under docs/. 2. Locate and read design.md or a reasonable equivalent such as DESIGN.md or a nested design markdown file. 3. Extract the required framework, package manager, build tool, language, CSS/UI approach, lint/test requirements, directory conventions, and runtime constraints. 4. Extract the baseline visual system from the design doc: color palette, theme tokens, typography, spacing scale, surface/background rules, and brand tone. 5. Inspect the current directory:

• If empty, initialize the project in place.
• If not empty, identify existing project files and merge without destructive cleanup.

6. Install or configure only what the selected tech stack document supports. 7. Create the baseline app, routing, theme/design-token setup, style entrypoint, environment files, and project conventions required by the stack. 8. Create a simple design-standard preview page at /design-standard that lets the user preview the standards extracted from design.md before prototype implementation starts. Do not place this preview at the root route / unless the user explicitly overrides the route.

• Show color swatches with token names and values.
• Show typography examples for headings, body text, captions, and tabular or numeric text when specified.
• Show spacing, radius, surface, border, and shadow examples when specified.
• Show representative primitive samples such as buttons, inputs, selects, cards, tables, tags, badges, tabs, or empty states when those standards are described.
• Show missing or ambiguous standards without inventing values.
• Keep it implementation-oriented and preserve it in later steps.

9. Add or update docs/tasks/google-stitch-onboarding/state.md with:

• Selected tech stack document path.
• Detected stack.
• Design document path and extracted color/theme tokens.
• Initialization command(s).
• Package manager used.
• Design-standard preview route and key file path(s).
• Validation commands.
• Any blockers.

Validation:

• Run install/build/lint/typecheck/test commands that are appropriate for the stack and feasible in the current environment.
• Verify that the Stage 1 /design-standard route compiles or renders according to the stack's available tooling.
• If a command cannot run, document why and what the user should run manually.

Gate payload: include the /design-standard route, touched files, extracted design standards, validation, and missing or ambiguous design inputs.

2. Step google-stitch-onboarding-2: establish shared layout from docs and full prototype scan

Required actions:

1. After user confirmation, mark google-stitch-onboarding-1 completed and create google-stitch-onboarding-2. 2. Locate and read product docs, and reuse or refresh design docs from step 1:

• Prefer prd.md, plus the design.md already used during initialization.
• Accept equivalents such as *_prd.md, DESIGN.md, or nested design files.

3. Build a prototype inventory from Stitch page directories containing code.html and optional image files.

• If this inventory creates more than two page batches for scanning, follow the mandatory worker delegation rule before scanning page batches.

4. Scan every prototype page directory in the inventory:

• Read code.html.
• Inspect screen.png or the available rendered image when present.
• Record the page archetype and repeated layout/component patterns in docs/tasks/google-stitch-onboarding/state.md.

5. Derive the page implementation contract before any product page implementation:

• Treat Stitch directory names, code.html, rendered images, and inventory numbers as source identity for traceability only.
• Derive product identity from, in 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.
• Record each source page's product page name, route, component/page module, service/API boundary, navigation label, evidence, and blocker status in docs/tasks/google-stitch-onboarding/state.md.
• If a real product identity cannot be derived, set the active task rows to waiting_human_decision, record the ambiguous source page and evidence gap, and stop. Do not create implementation placeholders from source-only names.

6. Identify common shell elements: navigation regions such as sidebar or top navigation when present, page title area, breadcrumbs, workspace selector, action buttons, floating agent entry, density/spacing, cards, tables, forms, tabs, and badges. 7. Identify page-specific archetypes that must be preserved in Step 3, such as kanban, split-pane, data table, form, chat, graph, dashboard, detail page, and auth page. 8. Derive the project-specific shared shell contract from design docs plus the prototypes. Record:

• Shell regions and their spatial relationships.
• Which regions own which viewport space.
• Which pages use the shared shell and which pages are exceptions.
• Required shell interactions from design.md or visible in the prototype.
• Evidence for each decision, using design.md section names, page names, code.html, or image observations.
• Any conflict between design docs and prototypes as a blocker or explicit normalization decision; do not guess.

9. Derive the route and navigation contract from the product identities in the page implementation contract. Record:

• Root route / behavior.
• Public/auth routes and authenticated routes.
• Default route after successful login or authenticated entry.
• Sidebar, topnav, breadcrumb, row-action, and primary action destinations.
• Fallback and unknown-route behavior.
• Prototype/PRD evidence for every route decision.
• Blockers for any route or navigation target that is ambiguous.

10. Derive a critical user journey list from the PRD and prototypes. Use product page names in scenario titles and keep source pages only as evidence. Include auth/login when present, primary shell navigation, and every visible page-level primary action such as import, create/new, edit, detail, submit/cancel, search, filter, tab switching, pagination, upload, modal, or drawer interactions. 11. Create docs/tasks/google-stitch-onboarding/integration-test-plan.md from assets/integration-test-plan-template.md and fill it from design docs, PRD, prototype scan, page implementation contract, route/navigation contract, and critical journey list. The plan must specify:

• Source evidence for each scenario.
• Product page or flow under test.
• Start route and preconditions.
• Browser interaction steps.
• Expected route, auth/session state, visible UI state, and data changes.
• Required mock data.
• Priority and acceptance status.

12. Implement shared layout and primitive components according to the shell, route/navigation, and product identity contracts and the stack. 13. Do not count the Step 2 scan as page implementation, and do not append to docs/tasks/google-stitch-onboarding/implemented-pages.txt unless a prototype page already satisfies the full Step 3 ledger and acceptance-manifest rules.

Expected outputs: full source inventory, page implementation contract, project-specific shared shell contract, route/navigation contract, integration test plan, critical journey list, page archetype/component-pattern summary, shell/navigation/header components, design tokens, and common table/card/form primitives.

Validation:

• Run build/typecheck/lint where available.
• Confirm the scan covers every prototype directory containing code.html.
• Confirm every source page has a product identity, route, component/page module, service/API boundary, navigation label when applicable, and evidence.
• Confirm runtime page/module/service names are derived from product identity, not source-only inventory names.
• Confirm the shared shell contract is backed by design/prototype evidence, not a generic template assumption.
• Confirm the route/navigation contract identifies /, auth/public routes, authenticated entry routes, login transition target when applicable, and all visible primary action destinations.
• Confirm the critical journey list includes at least one runtime-verifiable expected result for each login/auth flow, navigation flow, and primary page action visible in the prototypes.
• Confirm the integration test plan maps each design/PRD/prototype-backed scenario to concrete browser steps and expected route/state/UI results.
• Confirm shared components compile or render through the stack's available tooling.
• Record archetype-specific risks and inconsistencies that must be handled during full traversal.

Gate payload: include scanned page count, page implementation contract summary, shared shell contract summary, route/navigation contract summary, integration test plan summary, critical journey list, archetype summary, created shared components, validation result, and known gaps.

3. Step google-stitch-onboarding-3: implement all Stitch pages

Required actions:

1. After user confirmation, mark google-stitch-onboarding-2 completed and create google-stitch-onboarding-3. 2. Load the Step 2 page implementation contract and confirm it covers every prototype directory containing code.html. 3. Implement product pages in contract order, usually PRD order or the stable ordering recorded in Step 2.

• If the implementation plan creates more than two page batches, follow the mandatory worker delegation rule before implementing page batches.

4. Create or update docs/tasks/google-stitch-onboarding/acceptance-manifest.md using assets/acceptance-manifest-template.md as the required structure. 5. Update docs/tasks/google-stitch-onboarding/integration-test-plan.md when implemented route names, controls, or expected results differ from the Step 2 draft. Do not remove a scenario only because it is not implemented; mark it blocked or unexecuted. 6. For each page:

• Read the source identity evidence: code.html, screen.png, and inventory notes.
• Identify the page archetype: kanban, split-pane, data table, form, chat, graph, dashboard, detail page, auth page, or another explicit archetype.
• Use the contract's product identity for the page name, route, component/page module, service/API boundary, mock data module, and navigation label.
• If the contract is missing or ambiguous for this source page, stop at waiting_human_decision; do not invent a source-shaped implementation name.
• Implement the route using the shared shell, but preserve the prototype's main-content archetype.
• If the page uses the shared shell, verify its rendered shell against the Step 2 shared shell contract. Mismatches in shell structure, viewport-space ownership, or required shell interactions are hard failures.
• If the page has a unique layout, create page-specific component composition instead of forcing it into a generic template.
• Create mock data in a dedicated product-domain module.
• Create or extend an API service function named from the product domain for future backend integration.
• Wire the page route into the real router, shell navigation, and any route guards/auth state required by the Step 2 route/navigation contract.
• Implement visible controls with minimum stateful behavior. If a required interaction cannot be implemented or verified, record it as a blocker and do not count the page as passed.
• Treat an enabled button, link, menu item, table row action, tab, filter, search field, pagination control, upload/import entry, create/new action, submit action, or cancel action with no route/state/UI effect as a hard failure.
• For auth pages, the login action must change auth state and navigate to the configured default authenticated route or shell. Do not accept a no-op login button or a static login mock as complete.
• For any page where the prototype or PRD exposes an import action, the action must open an import dialog/drawer/file input or navigate to an import flow. For any page where the prototype or PRD exposes a create/new action, the action must open the expected form/drawer or navigate to the expected create route. Do not require these actions on pages where they are not visible or specified.
• Add one line to docs/tasks/google-stitch-onboarding/implemented-pages.txt using the exact prototype directory name only after the component, route, service boundary, shell contract check, route/navigation check, visual structure check, and interaction smoke check pass.
• Add the page to docs/tasks/google-stitch-onboarding/acceptance-manifest.md with source identity, product identity, shell, route/navigation, visual, structural, and interaction evidence.

7. Preserve consistency across pages. Where prototypes differ in shared navigation or shell details, normalize them to the design/PRD-approved shell. 8. Preserve the Stage 1 /design-standard route and page files while adding product routes. Do not remove or replace the design-standard preview during full Stitch traversal.

Worker batch contract: assign exact source identities, product page names, routes, component/page modules, service/API boundaries, and expected files from the page implementation contract. Subagents must reuse shared primitives unless explicitly assigned otherwise, must not revert edits by others, and must report repeated UI candidates. The lead agent owns integration, shared contract updates, ledger order, validation, tracker updates, and confirmation.

Backend reservation pattern:

• Page components should not hard-code business data inline.
• Use a page-level hook/composable/store/controller that calls a service function.
• The service function may return mock data now, but its signature should match the future backend contract.
• Keep endpoint placeholders, DTO/type definitions, and query parameters explicit.

Validation:

• Run build/typecheck/lint periodically and at the end.
• Confirm every implemented route renders or compiles.
• Confirm every implemented runtime file path, route, navigation label, component/page module, mock data module, and service/API boundary comes from product identity in the contract.
• Start the app with the normal dev or preview server when the stack supports it, then perform browser-driven smoke checks for the root route, auth/login transition when present, shell navigation, and every critical journey assigned to implemented pages. Use Playwright, the in-app browser, or an equivalent runtime browser tool. Source-code inspection alone is not enough.
• Confirm every visible enabled primary action changes route, opens/closes a modal/drawer/file picker, updates state, filters/sorts/paginates visible data, validates/submits a form, or records a blocker.
• Confirm docs/tasks/google-stitch-onboarding/acceptance-manifest.md contains shared shell contract evidence, visual-structure evidence, and interaction smoke evidence for every ledger page.
• Confirm docs/tasks/google-stitch-onboarding/integration-test-plan.md stays synchronized with the implemented routes and controls, and clearly marks blocked or not-yet-executed scenarios.
• Confirm the acceptance manifest contains a critical journey smoke matrix with start route, steps, expected result, actual route/state/UI result, evidence, and pass/fail result.
• Do not accept Step 3 based only on HTTP 200, screenshot dimensions, source-structure checks, static screenshots, or ledger coverage.
• Record pages with partial fidelity or unresolved interactions.

Gate payload: include page count, page implementation contract result, route mapping, route/navigation contract result, critical journey smoke result, shell contract result, acceptance-manifest status, validation result, and gaps.

4. Step google-stitch-onboarding-4: quality acceptance

Required actions:

1. After user confirmation, mark google-stitch-onboarding-3 completed and create google-stitch-onboarding-4. 2. Re-scan the Stitch source inventory for all directories containing code.html. 3. Compare source page names against docs/tasks/google-stitch-onboarding/implemented-pages.txt and docs/tasks/google-stitch-onboarding/acceptance-manifest.md. 4. Verify source inventory coverage. 5. Verify page implementation contract coverage and route/component/service/mock boundary coverage. 6. Verify shared shell contract parity for every page that uses the shared shell. 7. Verify visual structure parity for every page. 8. Verify route and navigation contract parity:

• / renders the configured entry page.
• Login/auth flow transitions to the configured authenticated route when auth exists.
• Sidebar/topnav links navigate to real pages and selected states update.
• Primary cross-page actions navigate to the expected route or open the expected flow.
• Unknown-route and guard behavior matches the contract.

9. Verify interaction smoke test evidence for every interactive control category present in the prototype. 10. Execute the integration test plan against the real running frontend app:

• Start or restart the frontend with the normal project dev or preview command; do not rely on an unknown pre-existing server as acceptance evidence.
• Record the start command, local URL, and readiness check.
• Use Playwright, the in-app browser, or an equivalent browser runtime to interact with the page.
• Execute every scenario in docs/tasks/google-stitch-onboarding/integration-test-plan.md that is not explicitly blocked by an approved unresolved decision.
• Record the actual route/state/UI result, console/runtime errors, evidence method, and pass/fail status in the plan and acceptance manifest.

11. Re-run browser-driven smoke checks for all critical user journeys. The evidence must show the action sequence and actual visible route/state/UI result, not only a screenshot before the click. 12. Verify there is no generic fallback rendering for pages whose prototype has a distinct archetype. 13. Verify product runtime paths, routes, navigation labels, component/page modules, mock data modules, and service/API boundaries use product identity from the contract. Source identity may appear in evidence and explicit prototype viewer tooling only. 14. Verify all deviations are either non-material or explicitly accepted by the user. 15. Run final build/typecheck/lint/test commands supported by the project. 16. Run scripts/coverage_check.sh and scripts/acceptance_check.sh when their inputs are available. 17. Update docs/tasks/google-stitch-onboarding/state.md with final quality acceptance results.

If any page lacks shared shell, route/navigation, visual, or interaction evidence, Step 4 is incomplete. If any integration scenario or critical journey fails, is skipped, is unexecuted without an approved blocker, or is only source-inspected, Step 4 is incomplete.

Gate payload: if quality acceptance is complete, ask the user to accept final quality acceptance. If incomplete, list missing pages, route/navigation failures, integration test failures, shell contract mismatches, missing evidence, generic-renderer violations, unresolved interactions, and unaccepted deviations; do not claim completion.