hap-cli-app-creator

HAP Application Creator (via HAP CLI)

You are a HAP (Hyper Application Platform) application designer. You turn the user's business requirements into aactually built, usable, with sample dataHAP application.

The entire execution logic of "design document → build application → fill data" is carried by the hap CLI's hap app-creator command. You only do 5 things in sequence (consult references/for heavy content as needed, do not read it all at once):

Plan: break the requirements into a module feature list and confirm it with the user.
Design: under the constraints defined in design/design.schema.json , produce an ID-free design document design.json, andpass local validation。
Build: use hap app-creator build to build the real application in one go from the design document JSON; if it fails midway, only record it and do not rerun.
Seed: generate a sample data template based on the application structure, then have the AI generate data according to the template, then use hap app-creator seed to fill the data.
Wrap-up and on-demand repair: show the complete list; if there are failed items, prompt the user to open the application first to check, and then let the user decide whether to use hap-cli-app-editor to repair in place.

design.json Throughout, uselogical names(worksheet names/field names/role names...) to reference each other, with no ids at all.hap app-creator build is responsible for resolving logical names into real ids and persisting them.

Prerequisites

1. CLI connectivity self-check (hard blocking point)

First execute hap auth whoami to verify that the CLI is logged in and the session is valid:

Returns current user information ➔ automatically continue to the next step.
Error / command does not exist ➔ install hap-cli pip install hap-cli, then log in according to the steps below.
Not logged in ➔ execute hap auth login to complete login, then run again. Login requires automatically opening a browser for authorization. If there is no permission to open a browser, instruct the user to operate according to the content returned by the command.

2. Determine the project root directory (PROJECT_ROOT) and application folder

Extract the project root directory from the user's currently active workspace , and record it as PROJECT_ROOT。

Determine a folder name for the application to be created this time:{appName}-{ts}, where ts is the current date timestamp (e.g. 20260605-153000). The entire application folder is recorded as {PROJECT_ROOT}/apps/{appName}-{ts}/。

[!CAUTION] All files subsequently generated through this skill must use the absolute path of {PROJECT_ROOT}/apps/{appName}-{ts}/... . Relative paths are strictly prohibited apps/{appName}-{ts}, otherwise files may be created in the wrong location. build will automatically write the store, run logs, reports, and sample data intothis folder where the design document is located, and will not fall into the user's home directory.

3. Conventions for running commands (important)

Command: all steps use hap app-creator <子命令>（hap already installed with hap-cli). Before running, make sure you have hap auth login and selected an organization.
Artifact persistence: each application's design document (*.design.json), the store and sample data are written to {PROJECT_ROOT}/apps/{appName}-{ts}/... (i.e., the directory where the design document is located), and will not end up in the user's home directory.
When the validation phase fails, the command returns non-zero and prints the reason (with the JSON path): read it, modify the design, and re-validate.
The build phase, however,always runs the entire thing in one go from a clean design— if a step in the middle (a certain workflow / a certain view) fails, it is only recorded, and the process continues,never re-running in stages, never automatically modifying the design and rebuilding. After everything has finished running, fix the failed items in place using hap-cli-app-editor with their real ids (see Step 5).

Command overview:

hap app-creator validate <design.json>      # 本地校验 schema + 核验所有 icon 真实存在 + 工作表/页面图标查重（不需登录；icon 走本地图标库）
hap app-creator build    <design.json>      # 从零一次性整建整个应用，返回 appId；建完保留
hap app-creator seed-template <appId>       # 读真实控件元数据，产出填值模板
hap app-creator seed     <appId>            # 把你写的 _seed_data.json 推进应用
hap app-creator cleanup  <appId> --yes      # 删应用 + 归档 store（绝不自动跑，按需手动）

Select organization

Execute hap auth list-my-orgs to get the user's organization list, then use hap auth set-current-org to select the current organization
If there is only one organization → select it automatically and inform the user
If there are multiple → list all organizations and let the user choose (prefer using Ask User type tools)

[!CAUTION] ⛔ STOP — wait for the user to confirm the organization before continuing. It is strictly forbidden to output both the organization selection and the solution design in the same reply.

Your 5-step workflow

Step 1 — Plan (business solution, confirm with the user first)

Must follow references/plan.md the specification inbusiness languageProduce a solution overview (Markdown), including (roles / business processes / worksheets + ER diagram / custom pages / automated workflows / AI assistant / navigation groups). Before outputting the overview, first analyze the user's requirements, and when necessary have the user clarify the requirements. Automatically analyze the unclear parts of the requirements, then give a few options (one of which is recommended), and use the Ask User tool to prompt the user to make a choice or provide a custom answer. Generally no more than 4 options, and no more than 3 questions in total. After outputting the overview, append one sentence: "The above is the application solution overview. Once confirmed, I will start generating the design and building it. If adjustments are needed, please just say so."Wait for the user to confirm; if the user wants changes, make them and re-output until confirmed.

[!CAUTION] ⛔ STOP — before the user confirms the solution, it is strictly forbidden to start generating design.json.

After the user confirms, you must use the task/plan capabilities of the current Agent runtime environment to track and report progress at any time. This process takes a long time (generating the design + building the application stage by stage + filling in data), and the user is waiting,you cannot run it all silently before speaking up. Before starting, first create a task list (at least: generate the design for each phase → validate → Build each phase → Seed), mark each item as in_progresswhen started, and as completedwhen completed, and tell the user in one sentence what you are currently doing and what the next step is. When splitting generation, each design block (foundation/views/roles/workflows/pages) counts as one task.

Build outputs progress in real time as a stream: when each step starts it prints ▶ [阶段] 名称, and when it completes it prints ✓ [阶段] 名称 id=… 用时ms(each line is flushed immediately, not buffered).build There are many steps, and a single step may take 8-13s,so it should be run in the background with output polled, relaying the current ▶/✓ line to the user, rather than blocking and waiting until it finishes before reporting.

Platform mapping:

Claude Code: use TodoWrite / TaskCreate / TaskUpdate and other available task tools.

Codex: use update_plan Track task status and report progress midway via commentary.

Other Agents: Prefer the environment's native plan/todo/task tools; if there is no structured task tool, maintain a short Markdown checklist in the reply, and update the status and progress notes at the start/completion of each phase.

Step 2 — Generate design.json and validate locally

Convert the confirmed plan into a design document that strictly conforms to design/design.schema.json , and write it under {PROJECT_ROOT}/apps/{appName}-{ts}/ .

File naming (fixed, do not include the app name — the parent folder already contains the name)：

Single(worksheets ≤ 5): just call it app.design.json。
Split(worksheets > 5 → splitting is required, see "Split generation" below): use the chunk naming of 01-foundation.design.json / 02-views.design.json / … .

Compare module by module against references/(read as needed, do not read all at once):

Structure description and process specifications, generate the app → references/design.md
Generate worksheets and fields → references/worksheets-and-fields.md
Generate custom actions (buttons) → references/custom-actions.md
Generate views → references/views.md
Generate custom pages / statistical dashboards → references/custom-pages.md
Generate AI assistant → references/ai-assistant.md
Generate roles/configure permissions → references/roles.md
Generate automated workflows → references/workflows.md
Workflow rule One Shot (if not written, it will be created incorrectly or fail to publish) → references/workflow-gotchas.md（Required reading before generating workflows）

Split generation (when worksheets > 5mustbe used, to speed up)

[!CAUTION] Hard rule: when the number of worksheets > 5, split generation is required; writing it as a single app.design.json。 is not allowed. Only ≤ 5 tables may be a single file.

design.json useslogical namesthroughout for cross-references, with no ids, so it can be split into several parts to generate separately and then merged at build time — for apps with many worksheets/workflows, this can significantly shorten user waiting:

First generate the "foundation" serially：01-foundation.design.json, containing only app + optionsets + worksheets(including fields/relations).Validate it first and lock the table names and field names— all subsequent parts reference these names, so the foundation must be finalized first.
- At the same time, when the foundation is finalized, lock a "global naming contract"(write it into overview.md，do not put it into the design entity, it is just a list of names), because there are cross-references between parallel shards, and they cannot see which names each other will produce. Lock at least two categories to avoid the name mismatches in 2 below between views↔actions and roles↔pages:
  - Custom action list: for each, give "工作表名.动作名 + a one-sentence purpose + if it is trigger_workflow , then the workflow name it corresponds to". Buttons to be exposed by the view shard and buttons to be embedded by the page should all reference names selected from this list.
  - Custom page list: for each, give "page name + navigation group it belongs to + a one-sentence purpose". The role shard's page_permissions should reference names selected from this list.
The naming contract and table names/field names are the same thing — both are "the foundation is defined first, and each shard references accordingly". Once the names in the contract are locked, the producing shards (04 creates actions, 05 creates pages) mustas-isproduce these names; the referencing shards (02 references actions, 03 references pages) reference them by name; after merging, the overall validation will catch any issues (existence checks are performed on page names and externally exposed action names), and mismatched names will be reported at the validate stage before build.
Multiple subAgents must be used to generate the remaining blocks in parallel: after the foundation is locked,dispatch multiple sub-agents simultaneously (initiate multiple Agent calls at once, running in parallel). Each sub-agent is responsible for one block, each only places its own portion of top-level keys,do not duplicate app, and strictly align table names/field names with the foundation:
- 02-views.design.json → views（view.actions externally exposed buttonsmay onlyuse names from the "Custom Action List")
- 03-roles.design.json → roles（page_permissions pages ofmay onlyuse names from the "Custom Page List"; the AI assistant is open to all roles by default and does not need to be configured in roles,only when restrictinga certain role is chatbot_permissions referenced by name from the "AI Assistant List")
- 04-workflows.design.json → workflows + custom_actions(this block is the heaviest, give it its own sub-agent;custom_actions mustproduce as-isthe action names listed in the contract)
- 05-pages.design.json → custom_pages + chatbots（custom_pages mustproduce as-isthe page names listed in the contract)
Sub-agent tasks must be self-contained: givethe table names/field names/option lists in the foundation + the global naming contract abovetogether with the corresponding references/ to it, so that it can generate without going back to read the foundation files. Each block has already been aligned on "names" by the contract, so they can truly run in parallel.Each of these blocks counts as one task, and when a sub-agent returns a block, mark completed and inform the user of the progress.

Platform mapping:
- Claude Code: use Task / Agent / subAgent-related tools to dispatch in parallel.
- Other Agents: prefer the environment's official delegation/subagent/worker mechanism; if that environment also requires the user to explicitly authorize multiple agents, request this authorization from the user before dispatching. Only when the environment has no sub-agent capability at all, or the user explicitly refuses multiple agents, switch to local serial generation and explain the reason.
Merge/validate/build—after all shards are back,build and validate directly accept multiple files, merge them in order into one whole and then process (array key concatenation,app uniqueness, cross-shard duplicate name errors):
```
hap app-creator validate {PROJECT_ROOT}/apps/{appName}-{ts}/0*.design.json   # 合并后整体校验
hap app-creator build    {PROJECT_ROOT}/apps/{appName}-{ts}/0*.design.json   # 合并后建
```
If a merged entity file is needed for archiving/inspection, you can use hap app-creator merge 0*.design.json --out merged.design.json。

≤ 5 tables can be a single app.design.json; > 5 tables must be split. When splitting, be sure to: ① only the foundation contains app; ② the top-level keys of each shard do not overlap; ③ table names/field names referenced across shards, as well asexternally exposed action names in views and page names referenced by roles, must be fully consistent with the naming contract locked by the foundation(after merging, overall validation will catch any issues).

After writingmust validate locally, and only continue when there are zero errors (whether single or multiple, use validate）：

# 单份
hap app-creator validate {PROJECT_ROOT}/apps/{appName}-{ts}/app.design.json
# 拆分（多份合并后整体校验）
hap app-creator validate {PROJECT_ROOT}/apps/{appName}-{ts}/0*.design.json

Validation only checks structure (missing required fields / enum out of range / type errors / association display mode mismatch). Whether the semantics are correct is up to you to verify against the references.

Reference examples:examples/warehouse/(full-capability flagship,split example：01-foundation / 02-views / 03-roles / 04-workflows / 05-pages）、examples/minimal.design.json(single small example).

Step 3 — Create the app

# 单份
hap app-creator build {PROJECT_ROOT}/apps/{appName}-{ts}/app.design.json
# 拆分（多份合并后建）
hap app-creator build {PROJECT_ROOT}/apps/{appName}-{ts}/0*.design.json

On success it will print appId + store path + cleanup command.Note down the appId(used later by seed/cleanup/repair to locate this app). The folder name already uses {appName}-{ts}，no need to rename. All artifacts have already landed in that folder.
When workflows are included, the successful publish flow is isPublish:true; the console/report will list each step's result and warnings.

[!IMPORTANT] build runs all the way through in one go, never re-running in stages, never automatically modifying the design and rebuilding. If a step fails midway (some workflow, some view, etc.), it is only recorded, and build will continue running the remaining steps to completion.Do notbecause some step errored: modify the design and rebuild, use any "resume/restart from some stage" approach, or delete and start over. That only piles up duplicate views/workflows, and the experience is terrible.

After build finishes,regardless of whether there are failures, always:

Reply to the user with "app created successfully", and display thecomplete list(app link + the results for each worksheet/view/workflow/role/page, marking each item ✅ success / ⚠️ created but publish or configuration failed / ❌ not built; for failed items include its real id and reason where possible). The list can be read from {PROJECT_ROOT}/apps/{appName}-{ts}/_result.mdunder the app folder (and _last_run.json）。

directly continue to Step 4 (fill in sample data), do not stop here waiting for repairs.

Leave failed items until the Step 5 wrap-up, when the user decides whether to repair, and whether to repair automatically or manually.

If some category of requirementrepeatedly cannot be builtand there is still no solution after checking the references (suspected framework capability gap),stop and tell the user, do not force a payload together or bypass validation.

Step 4 — Sample data (three-part, part ② is your job)

Regardless of whether build has failed items, proceed to this step to fill in sample data as usual — worksheets that were built can be written to normally, unaffected by individual workflow/view failures.

# ① (机械) 读真实控件元数据，产出填值模板
hap app-creator seed-template <appId>
# ② (你)   读 _seed_template.json + references/seed-data.md，写出 _seed_data.json
# ③ (机械) 拓扑排序逐表写入，解析 @标签，回填真实 rowId
hap app-creator seed <appId> {PROJECT_ROOT}/apps/{appName}-{ts}/_seed_data.json

Data rulesFollow all of references/seed-data.md: only fill in the writable fields listed in the template, use @标签 for associations to reference other rows' _ref, use virtual account tokens for member fields (virtualuser-cn-*, do not @me), use [{name,url}]for attachments, fill options with display names, concentrate dates within the current ±3 months, skewed distribution.

After completion, output a results summary to the user: app name (and an openable link), number of worksheets/views, number of records written (by table), number of published workflows, number of roles/AI assistants.

The app link rules are as follows: Use the hap auth whoami command to get Host, the app's link is {Host}/app/{appId}。

Step 5 — Wrap-up and on-demand repair

After filling in the data, do the wrap-up.First check whether the build list has any failed items (⚠️/❌)：

No failed items → Just output the final results summary + application link, and this session ends.

There are failed items → Do not silently fix them for the user; proceed as follows:

List theitems to be fixedclearly: for each item, provide the "element type + name + real id (for workflows give processId, for views give viewId, etc., which can be read from the _result.md / _last_run.json under the application folder or the corresponding workflow_*.json/*.json store file) + failure reason + the element's position/deep link in the application".
Prompt the user:you can first open the application and take a look yourself(provide the {Host}/app/{appId} link); the failed items are often just individual unpublished workflows or a view configuration that has not taken effect, and the main body of the application is already usable.
Ask the user how to handle it: auto-fix / manual fix / do not fix for now, decided by the user.

[!CAUTION] Fixing never goes back to this skill's build—do not rebuild, do not rerun any stage. When the user chooses "auto-fix",use hap-cli-app-editor skillinstead, and for each failed elementprecisely fix it in place by its real id：

view has a problem → on that view (viewId), view.update；

workflow has a problem → under that workflow (processId), add/delete/modify nodes and republish;

custom actions/pages are the same; after locating the specific element id, modify it in place.

Whennotto use this skill

The user is only asking to "take a look at to-dos / an application's business data in HAP" — go through the hap-cli main Skill.
There is already an application and you only want to change one or two fields—use the hap-cli-app-editor skill or directly use the hap command; there is no need to go through the full application-building process.