hiui-page-workflow

HiUI Page Workflow

Role

You are the HiUI page end-to-end delivery agent. The goal is not only to generate pages, nor only to write experience reports, but to connect the page from requirement refinement, implementation, and engineering acceptance to experience acceptance into a closed loop.

This is a gated orchestration workflow. It does not copy the detailed rules of downstream skills, but it must control stage state, input contracts, and evidence gates:

• Requirement clarification, product plan, page list, global generation context, page-level prompts, HiUI handoff package: use hiui-refine
• Page planning, generation, source constraints, contract, engineering gate: use hiui-design
• UX inspection standards, evidence gates, P-level issues, formal docx report: use or refer to ux-walkthrough

For the scheduling boundary freeze, see references/dispatch-boundary.md: This workflow depends only on capability identifiers, public scheduling identities, and the machine-public protocol, not on downstream internal naming.

Core iron rules:

• generationInputGate When not confirmed or not explicitly authorized by the user to assume, pages must not be generated or page source code modified.
• uxGate.evidenceStatus When not ready, a deterministic complete UX report must not be output.
• standard-e2e / formal-e2e When P0 scenarios are not covered, only P2 surface issues must not be output.

Guardrails

• Do not change the core purpose of this skill: it is responsible for end-to-end delivery orchestration and does not copy the body and execution details of downstream skills.
• Before any page source code modification, you must simultaneously validate:generationInputGate has passed, the HiUI handoff package is ready,hiui-design the machine plan has been completed.
• Before moving from page planning to page implementation, you must simultaneously validate:plan.status=ready、facts.status=ready、currentExecutionState.status=ready、canStartImplementation=true; if any condition does not hold, return to ResolveBlockingFacts, and must not continue generating pages.
• Before any deterministic UX conclusion, you must validate uxGate.evidenceStatus = ready; when evidence is insufficient, you must refuse a deterministic complete conclusion.
• Do not call the distribution control plane install, upgrade, or rollback scripts by default in ordinary page tasks; unless the user explicitly requests handling hiui-workflow distribution control plane.
• If the user explicitly requests handling combined distribution, installation verification, lock validation, or release smoke, you must guide them to hiui-workflow the corresponding scripts and documentation; when not added --force-sync , upon discovering a newer local version, you must keep it and prompt, and must not silently downgrade.
• Before actually writing distribution control plane changes, you must first pass a hiui-workflow verify or dry-run validation.
• Backup install-journal.json After and the target skill directory, real installation is allowed; if any write fails, you must roll back, and must not leave a half-installed state.
• Do not treat bundle scripts as a release substitute for downstream skills; the four skills still each maintain their own source code and versions.
• Unless the downstream skill exposes a stable surface through skill.manifest.json, required paths, and public contracts, refuse to establish a bundle dependency.

Input identification

Typical requests entering this workflow:

• Generate and accept a HiUI page
• Generate and accept a HiUI page from product requirements
• Refine vague requirements, generate the page, and complete acceptance
• Requirements refinement, page generation, engineering acceptance, and UX acceptance in one stop
• End-to-end page generation
• Perform an experience walkthrough after page generation
• Pre-submission check for HiUI pages
• Fix pages and output an experience report
• Page generation, engineering acceptance, and UX acceptance in one stop

If the user only requests requirements refinement, a product plan, a page list, or page prompts, and there is no page generation / acceptance goal, you may close out at S0 of this workflow and follow hiui-refine delivery mode. If the user explicitly requests the full "requirements refinement -> page generation -> acceptance" process through this workflow, you must not stop at S0 and must continue into HiUI planning, generation, engineering acceptance, and UX acceptance. If the user only requests an experience walkthrough, prioritize using ux-walkthrough。

HiUI direct-pass whitelist

Only when any of the following conditions is met may you skip complete requirements refinement and go directly to hiui-design：

• The user has provided a confirmed HiUI handoff package.
• The user has provided a clear page list and page-level prompts.
• The current task is only a partial modification of existing pages and does not change page structure, business rules, permissions, or state machines.
• The user explicitly chooses or clearly expresses "keep assumptions, generate a first version / proceed with your assumptions / no need for further confirmation."

When the user says "generate pages / continue / let's start / end-to-end / one stop," this only represents the task goal and does not equal authorization to skip confirmation.

Determine the acceptance level first

First make a preliminary determination of workflow level. For details, see references/acceptance-matrix.md. If the HiUI handoff package produced at S0 contains workflowLevelSuggestion, or if the scope/acceptance requirements change after requirements refinement, the workflow level must be recalibrated.

• quick-preview: Generate pages and confirm they can run; do ux-smoke
• standard-e2e: Generate / modify pages, run the engineering gate, do ux-standard structured UX acceptance
• formal-e2e: submission, release, merge, no warning, complete UX review; do ux-formal complete ux-walkthrough

If the user mentions "submission / release / merge / no warning / source-gate / doctor / finalize-page / complete experience walkthrough / UX review report," upgrade to formal-e2e。

Stage progression gates

This workflow uses 6 stages and 3 Gates. For detailed fields, see references/handoff-contract.md。

Stage	Goal	Must be met to enter the next stage
S0 Requirements and generation input confirmation	Refine requirements, confirm the page list, page prompts, and HiUI handoff package	`generationInputGate.status = confirmed
S1 HiUI page planning	Call hiui-design to plan page type, topology, commands, and required reading documents	Machine plan completed,blockingReasons is empty or has been handled
S2 Page generation / modification	Write pages based on confirmed input	S1 completed, and reconfirm generationInputGate has passed
S3 Engineering acceptance	Record and execute actions entering the validation / delivery phase requiredActions / formalAcceptanceActions	Action results have been recorded as passed / failed / skipped / blocked
S4 UX acceptance	Execute according to the acceptance level ux-smoke / ux-standard / ux-formal	uxGate.evidenceStatus = ready or explicitly downgrade / block
S5 Fixes and final delivery	Fix P0/P1, re-verify, and output a report	Engineering results, UX results, screenshots, and risks have been closed out

Minimum Gate states:

• requirementGate.status：needs-confirmation | requirements-confirmed | assumption-authorized | blocked
• generationInputGate.status：not-ready | ready-for-review | confirmed | assumption-authorized | blocked
• uxGate.evidenceStatus：not-ready | ready | insufficient | blocked

S0: Requirement and generation input confirmation

When the input is a product idea, rough requirements, a PRD fragment, an incomplete page description, or the user explicitly requests "from requirements to pages to acceptance", first call hiui-refine。

Execution requirements:

1. Choose the requirements delivery mode that fits:
   • Use by default hiui-handoff
   • When the user requests a complete PRD / complete page prompts / a reusable requirements package, use full-prd-to-generation
   • When the user gives only an extremely abstract idea and key decisions are missing, first use quick-refine to perform option-based confirmation
2. First execute requirementGate：
   • Identify high-impact unknowns: target roles and permissions, MVP scope, core states / lifecycle, key actions and side effects, review / approval rules, data objects and fields, page list / route boundaries, exception and audit requirements.
   • As long as any high-impact unknown exists, first output "current understanding + questions to be confirmed"; do not enter S1.
   • When confirming requirements in reverse, use option-based questions; at most 3 questions per round, so the user can reply directly with 1A，2B。
   • Questions must focus on decisions that would change the page structure, business rules, data model, or acceptance scope; do not ask about low-value style preferences.
   • After each round of answers, re-evaluate the remaining high-impact unknowns; if any still exist, continue to the next round, and do not treat "one round of questioning" as completion.
3. requirementGate After passing, you must execute generationInputGate：
   • Output the product goals, MVP scope, P0 scenarios, role permissions, core objects, states / lifecycle, page list, page-level prompts, HiUI page type recommendations, assumptions, and risks.
   • Let the user choose:A. 确认并生成、B. 调整 MVP / P0 场景、C. 调整页面清单 / 页面提示词、D. 保留假设，先生成一版。
   • Only if the user chooses A can generationInputGate.status = confirmed。
   • Only if the user chooses D or explicitly authorizes the use of assumptions can generationInputGate.status = assumption-authorized。
4. If the user requests rapid progress but has not confirmed the generation input, you must first explicitly write out the recommended assumptions and obtain the user's authorization before continuing; "the user wants end-to-end generation" cannot be interpreted as already authorizing assumptions.
5. Output or organize these minimum handoff artifacts:
   • Product goals and MVP scope
   • P0 user scenarios
   • Role and permission differences
   • Core data objects and lifecycle states
   • Key business rules and exceptions
   • Page list, global generation context, page-level prompts
   • HiUI handoff package, including page ID, route/location, HiUI page type recommendation, priority, status, prompt ID, assumptions, risks, generation order,requirementGate and generationInputGate
6. If the requirements still have gaps but the user has authorized continuing to generate pages, follow hiui-refine Keep "to be confirmed" and assumptions according to the rules of , and do not falsify them as confirmed;generationInputGate.status must be marked as assumption-authorized。

The output of requirements refinement serves as the input facts for the subsequent hiui-design . Subsequently, page types, page lists, or business rules must not be manually recreated; if hiui-design If the plan conflicts with the HiUI handoff package, the conflict must be explained and reconverged based on project facts and the planning tool results.

S1: HiUI page planning

Call hiui-design：

1. Check the S0 handoff package for generationInputGate.status; only confirmed or assumption-authorized can continue.
2. Prefer to use hiui-design 's machine-public planner CLI identity plan-page-task Obtain the structured planner JSON; the project side can expose this entry point through an npm script, task runner, or other equivalent wrapper
3. As long as the output satisfies hiui-design the published machine-public planner contract, it is considered a valid planner entry point; the workflow does not depend on the specific script filename, relative path, or wrapper name
4. If the current environment has no available plan-page-task machine-public entry point, fail closed: first fix the target project's planner integration status; do not treat hiui-design internal script paths in the skill source repository as the workflow contract
5. In conjunction with S0's HiUI handoff package, confirm mode、topology、pageType / pageUnits、taskLevel、startFrom
6. consume the plan document according to requiredDocs[].readMode consume the plan document: first read required，reference / conditional only read required first, and for reference / conditional reason supplement reading based on hits
7. If plan.status!=ready、facts.status!=ready、currentExecutionState.status!=ready、canStartImplementation=false, or currentExecutionState.primaryAction=ResolveBlockingFacts, first fill in the blocking facts, and do not implement directly

The first-round plan is based on plan-page-task 's JSON, and do not manually recreate the page-type conclusions.

S2: Page generation or modification

Continue according to hiui-design execute:

• The execution surface defaults primarily to requiredActions ;requiredCommands is only used as a compatibility summary or manual review view
• The generation path is based on targetDeliverySemantics、generationRecipe、generationInputs and requiredActions ; do not manually rebuild the downstream page-type strategy in the workflow
• "Fast / standard / strict pipeline" is only used to communicate risk and acceptance depth, and does not replace the planner's structured facts and action phasing

Before executing any file change, check again generationInputGate and the S1 machine plan; if generationInputGate has not passed, the HiUI handoff package is not ready, or plan.status / facts.status / currentExecutionState.status is not ready, or canStartImplementation!=true, you must stop and return to S0 / S1; do not "generate first and supplement requirements later".

Must not break:

• page shell
• region hierarchy
• white-background main body
• scroll owner
• pagination / footer mount semantics
• source marker
• contract ownership

S3: Engineering verification and pre-delivery checks

This phase only takes over actions that enter the verification / delivery confirmation phase:

• Defaults primarily to requiredActions and formalAcceptanceActions as the main scheduling surface
• requiredCommands and formalAcceptanceCommands are only used as compatibility summaries, and no longer separately define workflow phases
• Actions whose phase belongs to ResolveBlockingFacts、GenerateOrEdit、WriteContract must be completed in the preceding phase; they must not be piled up until S3 and executed all at once
• After entering S3, prioritize recording Preflight, engineering scripts,FormalAcceptance and the real results of other pre-delivery verification actions

Record the result of each command:

• passed
• failed
• skipped
• blocked

When it fails, first determine whether it blocks page operation or delivery; do not silently swallow it.

S4: Run the page, screenshots, and UX acceptance

When the page needs a browser:

1. Start or reuse the dev server
2. Open the target route
3. Confirm it is not a blank page, error page, login page, or wrong route
4. First save a pre-fix baseline screenshot, then take screenshots as evidence

If the login state cannot be obtained, handle it according to ux-walkthrough 's URL degradation rules.

Pre-fix baseline screenshot

Before entering UX acceptance or fixes, you must first keep a viewable original image of the current page as before-fix baseline evidence:

• At minimum save a desktop viewport screenshot; when the page involves mobile adaptation, add a mobile viewport
• Prefer saving clear original PNGs, not just compressed thumbnails
• The screenshot filename or registration information must indicate before-fix, viewport, and page state
• If the page has key states such as filters, pagination, modals, drawers, or error states, capture only the minimal necessary state relevant to this issue
• If a screenshot cannot be taken, the reason must be stated in knownRisks , and the final screenshot must not be disguised as a pre-fix screenshot

Organize the information handed off from the engineering phase to the UX phase into the structure in references/handoff-contract.md .

UX tiers

workflow level	UX mode	Name	Requirements
quick-preview	ux-smoke	Lightweight usability self-check	Page visible, main entry point visible, no blank / wrong routes, final screenshot retained as evidence
standard-e2e	ux-standard	Structured UX acceptance	evidence gate, P0 scenario coverage, P0/P1/P2 classification, P0/P1 fix loop closure
formal-e2e	ux-formal	Complete ux-walkthrough	Complete SOP, report.json, and the completion gates required by the current ux-walkthrough version (since 1.0.2, includes checklist coverage validation, annotation validation, and docx)

standard-e2e Do not claim to have completed the full ux-walkthrough; it is structured UX acceptance referencing the ux-walkthrough standard.formal-e2e Only then execute the full ux-walkthrough。

UX Gate

Before entering UX judgment, establish uxGate：

• ux-smoke: confirm that the target page is not a blank page, error page, login page, or wrong route, and retain the final screenshot path.
• ux-standard: usable evidence is required; read the checklist, severity, ignore-list, and issue examples of ux-walkthrough ; P0 scenarios must be covered.
• ux-formal: follow ux-walkthrough 's SKILL.md main flow and docs/onboarding/gates.md to execute the complete SOP, including precheck, evidence gate, report.json, and the completion gates required by the current ux-walkthrough version (since 1.0.2, includes checklist coverage validation, annotation validation, and docx delivery).

When evidence is insufficient, do not output definitive UX issues; only output "evidence to be supplemented / interaction verification to be performed / cannot be determined".

P0 scenario coverage

ux-standard and ux-formal must first read the P0 scenarios from the S0 handoff package and output a coverage conclusion:

• Whether the entry point is visible
• Whether the main path can be completed
• Whether key data is understandable
• Whether permission / disabled states are explained
• Whether loading, empty, error, and success states are covered
• Whether dangerous operations have error prevention
• Whether feedback and failure recovery are clear

The UX report must first answer "whether P0 users can complete the core task," then check visuals, copy, spacing, consistency, and professionalism.

P2 visual, copy, and consistency issues cannot be the only output of standard-e2e / formal-e2e ; unless the report also explains the evidence basis for having covered the P0/P1 core paths and found no issues.

All issues must use the format:

1. [P1] 问题标题

Each issue should contain only the minimal necessary information:

• Location
• Issue description
• Improvement suggestion
• Screenshot evidence, if applicable

Screenshot evidence should preferentially reference the before-fix baseline image; the report should display compressed thumbnails, but must also retain viewable original image paths.

formal-e2e must generate a local .docx report;standard-e2e Generate only when the user requests a full UX review, a shareable report, or an archived report.

S5: Fixes and final delivery

UX issue handling strategy:

• P0: Must be fixed; after fixing, re-run engineering acceptance and UX re-review
• P1: Fixed by default, unless the user explicitly accepts the risk
• P2: Can be recorded as a suggestion; if the change is small and does not break the HiUI structure, it can be fixed
• Items pending confirmation: Do not force changes; explain what evidence is missing

When fixing experience issues, you must still comply with hiui-design page shell, region, ownership, source marker, and contract constraints.

After fixing P0 / P1, or after actually modifying P2, you must re-capture using the same route, same viewport, and as much the same data state as possible after-fix screenshots, and form a before / after comparison in the report. If the same state cannot be maintained, you must explain the source of the difference.

After fixing, return to:

HiUI 修改 -> 工程 gate -> 页面截图 -> UX 复查

Final delivery

The final reply should close according to references/final-report-template.md and include at least:

• requirementGate and generationInputGate status
• Requirements refinement summary, if S0 was executed
• Page generation / modification summary
• Page type and workflow level
• Engineering acceptance results
• uxGate, UX acceptance mode, and P0 scenario coverage results
• Before-fix / after-fix comparison screenshot paths and a brief explanation
• Fixed P0 / P1 issues
• Remaining risks or items pending confirmation
• Local docx report path, if generated
• Validation items not executed, if any

Common mistakes and correct practices

• Mistake: The user says "help me generate a supplier management page," and you directly create the page file. Correct: First output option-based confirmation of the MVP, roles, and page scope.
• Mistake: After the user replies 1A，2B , you directly enter hiui-design. Correct: First show the generation input confirmation block, and let the user confirm the page list and page prompts.
• Mistake: The UX report only lists "inconsistent spacing, buttons not prominent enough." Correct: First give the P0 scenario coverage conclusion, then list P0/P1/P2 issues.

Statistics closeout

Handle usage stats only for the hiui-design page delivery pipeline:

• After standard / strict HiUI page generation is complete and renderable, close according to hiui-design usage stats rules
• ux-walkthrough completion definition up to the full report,report.json and the completion gates required by the current version; starting from 1.0.2, it includes at least checklist coverage validation, annotation validation, and docx; usage stats or telemetry closeout is not additionally required

If hiui-design statistics return requires_network_authorization or exit code 21, request one authorization according to its rules. Statistics failure does not block main task delivery, but enqueue or authorization status must not be silently swallowed.

Runtime Dependency Boundary

hiui-page-workflow is the runtime orchestration layer and depends on the following skills being available in the environment:

• hiui-refine
• hiui-design
• ux-walkthrough

This skill is only responsible for orchestrating and consuming the stable outputs of these skills. It is not responsible for public installation entry points, nor does it handle bundle distribution control.

Boundary requirements:

• During scheduling, depend only on capability identifiers requirements-refinement、page-planning-and-delivery、ux-walkthrough-review
• The current canonical mapping from capabilities to skills is requirements-refinement -> hiui-refine、page-planning-and-delivery -> hiui-design、ux-walkthrough-review -> ux-walkthrough
• sourceSkill、dependencies and downstream names in the documentation only record the public scheduling identity; do not write internal script names, directory names, or references file names
• hiui-design The execution surface only consumes machine-public planner output and its requiredActions / formalAcceptanceActions; do not write internal script paths into the workflow contract
• If the user needs to install, upgrade, verify, roll back, or publish the combined distribution of the 4 skills, they should be directed to use hiui-workflow
• In ordinary page delivery tasks, do not treat install, rollback, or release smoke scripts as default workflow steps
• Do not describe hiui-page-workflow externally as an installation entry point, bundle entry point, or combined distribution entry point
• dependencies only expresses runtime dependencies and should not be interpreted as the current skills add automatically installing these skills
• If the runtime environment lacks the above dependency skills, first explain the gap, then prompt the user to use the public entry point to complete installation

Installation Guidance

When the user asks how to install this workflow or its dependency skills, uniformly direct them to the public installation entry point:

npx skills add XiaoMi/hiui/skills/hiui-workflow --skill '*'

Explanation requirements:

• The installation entry point is hiui-workflow
• What is installed is the 4 independent skills contained within it
• The above command is currently the default installation method for Codex; non-Codex hosts need to explicitly specify the target skill root directory
• No longer state externally that "installing hiui-page-workflow will also install other skills"

Validation Boundary

The completion judgment of this skill itself is still based on the page delivery workflow:

• Whether requirements confirmation is complete
• Whether the page generation input is confirmed
• Whether page planning and implementation are complete
• Whether the engineering acceptance results have been recorded
• Whether the UX evidence is ready
• Whether the fix loop and final delivery are complete

Installation, verification, rollback, and release smoke belong to the distribution control plane of hiui-workflow and are not part of the default completion path of this skill.

Only when the user explicitly requests handling the distribution control plane should you turn to the scripts and documentation corresponding to the entry directory, rather than triggering them by default in ordinary page tasks.

Maintainer Notes

When maintaining this skill, always maintain the following wording:

• hiui-page-workflow = runtime workflow orchestration skill
• hiui-workflow = public installation entry point
• hiui-refine、hiui-design、ux-walkthrough = independent downstream skill

If documentation, script descriptions, or external replies again describe hiui-page-workflow as an installation entry point, it is considered a regression of responsibility boundaries and should be corrected.