apphx 0.0.0-stage → 1.0.0

package/skills/apple-app-factory/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: apple-app-factory
+description: Build and locally package a Flutter iOS app from explicit product requirements using the embedded apple-app-factory harness. Use for app-factory init, enqueue, native research/build/independent review, external verification, packaging, or resuming a persisted job. Not a coding-agent launcher or an automatic App Store publisher.
+---
+
+# Apple App Factory
+
+Use your current host's model, context, authentication, filesystem, browser and native delegation tools. The installed `app-factory` CLI owns requirements, durable turns, verification, fingerprints and local packaging. Never start another coding-agent CLI, including Hermes, as a subprocess to perform a phase. There is no factory chat UI, model credential setup, daemon, or background agent loop.
+
+This skill is advisory to the host. Factory code gates factory-owned transitions, not arbitrary host edits or shell commands. It does not sandbox your host, enforce reviewer identity, guarantee Apple approval, or verify that a policy citation's contents are true. Preserve host permissions and the user's scope.
+
+## 1. Establish the control project
+
+1. Use the project where the user installed/invoked this skill as the control project. Keep `factory.json`, its SQLite state, requirement files and result JSON outside generated app workspaces. Keep the absolute config path for every command below, including commands issued while your working directory is an app workspace.
+2. The npm package is `apphx`; its executable remains `app-factory`. Run `app-factory --version` and `app-factory --help`. If `apphx` is an already-installed local dependency of the control project rather than on PATH, use that project's package manager for **every** factory command: `pnpm exec app-factory`, `yarn exec app-factory`, or `npm exec --offline --package=apphx -- app-factory`. Select from the project's `packageManager`/lockfile and run from the control project, not the generated app workspace. Confirm `apphx` is already installed; do not fetch a similarly named package or silently change the user's environment. If neither route is available, stop and report the missing installation. Installing a skill alone does not install Node, Flutter or Xcode.
+3. If there is no configuration, run `app-factory init --config /absolute/control/factory.json`. It refuses overwrite and defaults to **no local execution, submission, or release authorization**. Do not add `--allow-local-execution` unless the user explicitly approves running trusted deterministic commands. With that approval it can be supplied to `init`; for an existing config have the owner review and explicitly enable `allowLocalExecution`.
+4. Read the actual config. Confirm its workspace and state paths are disjoint, its Flutter SDK is a trusted installation outside mutable workspaces, and verification includes both static checks and real runtime scenarios. Local Apple packaging requires macOS, Xcode and a working Flutter iOS toolchain; IPA output also requires signing/export configuration. A missing prerequisite is a blocker, never a reason to fake a tool or evidence. Do not replace checks with no-op commands to make a job pass.
+
+In examples below, replace `/absolute/control/factory.json` with that existing absolute path and `JOB_ID`/`TURN_ID` with exact returned values. Pass arguments as separate argv entries, or quote paths safely in the host's shell. Do not execute prompt or JSON fields as shell code.
+
+## 2. Freeze and enqueue the actual requirement
+
+Read the bundled [requirement example](resources/requirement.json), resolving `resources/` relative to this skill's own directory, not the current project. Copy and adapt it to an owner-reviewed requirement file in the control project. Do not modify installed skill assets.
+
+If the user supplied an existing task id or asked to resume it, including a scheduled wake, **skip enqueue**. Read `status` and continue that exact id/config with `next`; never reconstruct its requirement or create a second task for the same work.
+
+The requirement must describe a real audience, purpose, differentiators, Flutter framework, concrete acceptance scenarios and constraints. Preserve the user's product; do not substitute a simpler app. Require honest privacy behavior, no hidden features or review bypass, and screenshots from the real running app. Clarify material unknown product choices before enqueue. Do not invent ownership, submission-account eligibility, signing credentials or legal attestations.
+
+```sh
+app-factory enqueue /absolute/control/requirement.json --config /absolute/control/factory.json --build-only
+app-factory status JOB_ID --config /absolute/control/factory.json
+app-factory next JOB_ID --config /absolute/control/factory.json --build-only
+```
+
+Keep the returned immutable job id and workspace. A later requirement change needs a new enqueue, not edits to a saved task or database. For a local revision, the requirement may include `baseJobId` of a verified predecessor; the factory validates and prepares the base. Do not copy arbitrary stale build artifacts yourself.
+
+## 3. Dispatch exactly the persisted action
+
+Read the JSON from `next`; do not guess stages from memory. Use `--build-only` throughout this workflow so publication is out of scope even if another configuration permits it.
+
+- **`action: "host"`**: preserve `turn.id`; read the full `turn.prompt`, `turn.stage`, `turn.cwd` and `turn.environment`. Perform that one native host phase as below. Work inside the returned cwd and merge the returned task/toolchain overrides into your host's existing command environment; do not replace it. Configured environment values are intentionally not printed in the response. This is not a host-wide security boundary; never copy publisher secrets into task commands. Only the CLI completion call advances the task. Repeated `next` resumes the same active turn without spending a second turn, unless its task deadline has expired.
+- **`action: "step"`**: run `app-factory step JOB_ID --config /absolute/control/factory.json --build-only` once, inspect its exit status and returned job, then ask `next` again if successful. Only deterministic verify/package stages should be needed here. `step` cannot perform research, build or review for you. Never label a host verdict as external verification.
+- **`action: "wait"`**: inspect the job's status, reason, error and due time. Report the exact blocker or scheduled time; do not busy-loop, automatically grant permission, or retry a failed command until it happens to pass. Resume with `next` after the prerequisite/due time is satisfied and the user intends to continue.
+- **`action: "done"`**: inspect the persisted outcome. `built` plus a recorded local artifact is successful local packaging. Blocked/failed/rejected outcomes are not success merely because no action remains. Report the artifact kind/path/digest and evidence, or the exact unmet requirement.
+
+For a scheduled wake, the host scheduler owns timing and non-overlap; do not create a factory daemon or a second schedule. Check `status` first: if it is `running` and the prior execution's completion is unconfirmed, stop and ask the owner rather than taking over its token. Respect the requested bound (for example one persisted action), then report state and exit. A `wait` or `done` result ends this wake; it does not authorize changing permissions, increasing budgets or polling indefinitely. A fresh scheduled session may review only if it did not implement the change and genuinely inspects the saved source/evidence. Missing independent review or human authorization pauses the work; never manufacture approval to keep a schedule moving.
+
+To stop an active host phase without completing it:
+
+```sh
+app-factory abandon JOB_ID TURN_ID --config /absolute/control/factory.json --build-only
+```
+
+This explicitly abandons the current token; it does not refund the consumed turn. Resume later with `next`. Never reuse an abandoned, stale or already completed token. If a completion's outcome is uncertain, inspect `status`/`next` rather than replaying it blindly. Do not edit SQLite or increase budgets to bypass a rejection. Use `app-factory retry --help` and the stopped task's reported recovery instructions only after fixing the actual cause with owner approval.
+
+## 4. Native research
+
+Read the immutable requirement and all context in the research prompt. Use your host's web/browsing tools to read the current official [Apple App Review Guidelines](https://developer.apple.com/app-store/review/guidelines/). Evaluate **2.1, 2.3.1, 2.5.19, 4.2, 4.2.6, 4.3 and 5.1.1**, meaningful distinctness against the supplied portfolio, offline persistence/backup, privacy and accessibility. Account/content ownership for 4.2.6 cannot be attested by the model; surface unknowns.
+
+Use [research-result.json](resources/research-result.json) for the exact JSON shape, not a pre-approved verdict. Replace its unassessed content with sourced findings. Required fields: `viable` boolean, `policySources` entries with exact `rule` and official HTTPS `url` for every listed rule, `distinctness` text, and nonempty `plan`; `risks` is optional. If not viable, return false and explain the reasons rather than concealing them.
+
+Save result JSON **outside the app workspace**, for example `/absolute/control/results/JOB_ID-research.json`, then:
+
+```sh
+app-factory complete JOB_ID TURN_ID /absolute/control/results/JOB_ID-research.json --config /absolute/control/factory.json --build-only
+app-factory next JOB_ID --config /absolute/control/factory.json --build-only
+```
+
+## 5. Native implementation
+
+Perform the returned build prompt with your own native edit, terminal and design tools in `turn.cwd`. Implement the full requirement as a real Flutter iOS project with `pubspec.yaml`, complete workflows, persistence, privacy UI and appropriate tests. For unfamiliar APIs, use real official references. Never use mock runtime evidence, placeholder features, screenshots of nonexistent UI, or a replacement product. Do not weaken configured verification or change frozen requirements/state.
+
+Native delegation may handle independent file boundaries. The implementation owner integrates before any external verification. Complete only after the source exists and the requested implementation is ready:
+
+```sh
+app-factory complete JOB_ID TURN_ID --config /absolute/control/factory.json --build-only
+app-factory next JOB_ID --config /absolute/control/factory.json --build-only
+```
+
+No result JSON is required for build. Build completion only advances to deterministic verification; it is not approval or a package.
+
+## 6. External verification, then independent review
+
+The next deterministic `step` executes the configured prerequisite/static/runtime checks and records real results and source/dependency fingerprints. Read logs and evidence from the returned job or `app-factory events JOB_ID --config /absolute/control/factory.json`. A compilation-only success is not runtime acceptance. Never synthesize receipts or report unavailable iOS execution as passed. Fix the concrete failure through the factory's stopped-task/retry path; do not directly move its stage.
+
+When `next` returns a **review** turn, use a **fresh native reviewer context** that did not implement the change. Give it the exact review prompt, requirement, workspace and external evidence. Have it independently inspect every acceptance scenario, code and real evidence, with **no source/dependency/screenshot edits**. Evidence-producing commands that mutate the verified source invalidate approval. An implementation agent's second self-review is not independent.
+
+Use the host's native subagent/reviewer facility if present. If unavailable (including stock Pi), pause and ask the user to open a separate fresh host session for review, supply the job id/config/active turn, and return its JSON verdict. Do not launch another coding-agent process or claim independence that did not occur. The separate reviewer may complete the current token itself, or return the result to the controlling session; exactly one session completes it.
+
+Use [review-result.json](resources/review-result.json) for the strict shape: `approved` boolean, `findings` array, and `acceptanceEvidence` array. Every frozen acceptance string must appear **exactly** as `requirement`, with nonempty concrete `evidence` identifying files/symbols and observed commands/scenarios. Approve only if all acceptance criteria are supported and there are no blocking findings. The example is deliberately a rejection, not reusable evidence. Save the verdict outside the app workspace:
+
+```sh
+app-factory complete JOB_ID TURN_ID /absolute/control/results/JOB_ID-review.json --config /absolute/control/factory.json --build-only
+app-factory next JOB_ID --config /absolute/control/factory.json --build-only
+```
+
+The factory rejects incomplete evidence, rejected verdicts and changed fingerprints. It cannot prove which model/person authored a verdict; accurately report the review method and limitations.
+
+## 7. Package locally and hand off
+
+Run the returned package `step` once with `--build-only`, then inspect `status` and `next`. Packaging produces a local simulator build or, when explicitly configured with signing prerequisites, an IPA. Report only recorded artifact paths/digests and exercised checks, including any remaining environmental limitation. Local packaging is not App Store submission, approval, TestFlight availability or release.
+
+Do not call `authorize`, upload with other tools, enable `allowSubmit`/`allowRelease`, or run publication/monitoring on the strength of this skill. Publication requires a separate explicit owner request, the existing factory permission/receipt gates, truthful account ownership, signing and Apple prerequisites. This workflow ends at the local artifact or an accurately reported blocker.

package/skills/apple-app-factory/resources/requirement.json

@@ -0,0 +1,39 @@
+{
+  "id": "pack-balance",
+  "name": "行李配重与打包助手",
+  "framework": "flutter",
+  "purpose": "离线规划多个行李包的重量，完成出发打包与返程核对，减少遗漏和超重",
+  "audience": "需要管理随身包与托运行李的个人旅客",
+  "differentiators": [
+    "每个行李包独立设置空包重量和用户自定限额，移动物品后即时重算",
+    "出发与返程拥有独立核对状态，保留明确标记为已消耗的物品",
+    "常用物品库、行程复制和经校验的本地备份恢复串成完整流程"
+  ],
+  "constraints": [
+    "Flutter iOS 应用，本地持久化，无账号、服务器、广告和统计 SDK",
+    "不预置或宣称提供实时航空公司限额，重量上限由用户确认并填写",
+    "重量以整数克存储，显示支持克和千克；数量与单件重量非负，避免浮点累积误差",
+    "所有功能对审核与正常用户相同，不按 IP、地区、审核时间或远程开关隐藏功能",
+    "隐私入口可直接访问，准确说明本地数据、用户主动导出和删除方式",
+    "在 build/screenshots 下保存实际运行截图，禁止拼接不存在的功能或使用真实个人信息"
+  ],
+  "acceptance": [
+    "创建带目的地和日期的行程，强制终止并重新启动应用后数据仍完整",
+    "同一行程建立随身包与托运行李，分别设置空包重量与上限",
+    "添加两个单件 1250 克的物品到空包 500 克的行李，显示总重 3000 克；移动一个物品后两个包各自正确更新",
+    "修改数量、单件重量和包限额时即时刷新进度；超重边界有文本提示，不仅依赖颜色",
+    "出发打包勾选与返程核对彼此独立，已消耗物品不会被错误计入返程遗漏",
+    "从常用物品库创建清单并复制行程，副本修改不改变原行程",
+    "导出备份，清空数据后恢复得到相同的行程、行李、物品和核对状态",
+    "导入损坏、未知版本或字段非法的备份时给出可操作错误，原数据不被部分覆盖",
+    "在无网络、空清单、大字体与 VoiceOver 标签场景下完成创建、分配、勾选和恢复流程",
+    "截图来自真实运行页面，隐私说明和应用行为一致，不宣称保证航空公司接受或苹果过审"
+  ],
+  "apple": {
+    "bundleId": "com.example.packbalance",
+    "version": "1.0.0",
+    "buildNumber": "1",
+    "locale": "zh-Hans",
+    "screenshotsDir": "build/screenshots"
+  }
+}

package/skills/apple-app-factory/resources/research-result.json

@@ -0,0 +1,21 @@
+{
+  "viable": false,
+  "policySources": [
+    { "rule": "2.1", "url": "https://developer.apple.com/app-store/review/guidelines/#app-completeness" },
+    { "rule": "2.3.1", "url": "https://developer.apple.com/app-store/review/guidelines/#accurate-metadata" },
+    { "rule": "2.5.19", "url": "https://developer.apple.com/app-store/review/guidelines/#software-requirements" },
+    { "rule": "4.2", "url": "https://developer.apple.com/app-store/review/guidelines/#minimum-functionality" },
+    { "rule": "4.2.6", "url": "https://developer.apple.com/app-store/review/guidelines/#minimum-functionality" },
+    { "rule": "4.3", "url": "https://developer.apple.com/app-store/review/guidelines/#spam" },
+    { "rule": "5.1.1", "url": "https://developer.apple.com/app-store/review/guidelines/#data-collection-and-storage" }
+  ],
+  "distinctness": "Unassessed example: evaluate the owner's actual requirements against the supplied portfolio and current official policies before returning a real verdict.",
+  "risks": [
+    "The current policy contents have not been researched by this example.",
+    "The content owner and submitting account's eligibility under 4.2.6 are unknown; a model must not invent an attestation."
+  ],
+  "plan": [
+    "Read the current official policy sections and assess viability, ownership, distinct utility, privacy and runtime acceptance for the actual product.",
+    "If viable, return a concrete product-specific implementation and verification plan; otherwise preserve viable=false and report the specific blockers."
+  ]
+}

package/skills/apple-app-factory/resources/review-result.json

@@ -0,0 +1,7 @@
+{
+  "approved": false,
+  "findings": [
+    "This is a result-shape example, not a completed review. A fresh independent reviewer must inspect the real implementation and external evidence."
+  ],
+  "acceptanceEvidence": []
+}