@roki-h5/create-roki-app 0.1.3 → 0.1.5

package/templates/h5/.agents/skills/writing-plans/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: writing-plans
+description: Use when you have a spec or requirements for a multi-step task, before touching code
+---
+
+# Writing Plans
+
+## Overview
+
+Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
+
+Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
+
+**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
+
+**Context:** If working in an isolated worktree, it should have been created via the `superpowers:using-git-worktrees` skill at execution time.
+
+**Save plans to:** `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
+- (User preferences for plan location override this default)
+
+## Scope Check
+
+If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.
+
+## File Structure
+
+Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.
+
+- Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.
+- You reason best about code you can hold in context at once, and your edits are more reliable when files are focused. Prefer smaller, focused files over large ones that do too much.
+- Files that change together should live together. Split by responsibility, not by technical layer.
+- In existing codebases, follow established patterns. If the codebase uses large files, don't unilaterally restructure - but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable.
+
+This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.
+
+## Task Right-Sizing
+
+A task is the smallest unit that carries its own test cycle and is worth a
+fresh reviewer's gate. When drawing task boundaries: fold setup,
+configuration, scaffolding, and documentation steps into the task whose
+deliverable needs them; split only where a reviewer could meaningfully
+reject one task while approving its neighbor. Each task ends with an
+independently testable deliverable.
+
+## Bite-Sized Task Granularity
+
+**Each step is one action (2-5 minutes):**
+- "Write the failing test" - step
+- "Run it to make sure it fails" - step
+- "Implement the minimal code to make the test pass" - step
+- "Run the tests and make sure they pass" - step
+- "Commit" - step
+
+## Plan Document Header
+
+**Every plan MUST start with this header:**
+
+```markdown
+# [Feature Name] Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** [One sentence describing what this builds]
+
+**Architecture:** [2-3 sentences about approach]
+
+**Tech Stack:** [Key technologies/libraries]
+
+## Global Constraints
+
+[The spec's project-wide requirements — version floors, dependency limits,
+naming and copy rules, platform requirements — one line each, with exact
+values copied verbatim from the spec. Every task's requirements implicitly
+include this section.]
+
+---
+```
+
+## Task Structure
+
+````markdown
+### Task N: [Component Name]
+
+**Files:**
+- Create: `exact/path/to/file.py`
+- Modify: `exact/path/to/existing.py:123-145`
+- Test: `tests/exact/path/to/test.py`
+
+**Interfaces:**
+- Consumes: [what this task uses from earlier tasks — exact signatures]
+- Produces: [what later tasks rely on — exact function names, parameter
+  and return types. A task's implementer sees only their own task; this
+  block is how they learn the names and types neighboring tasks use.]
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+def test_specific_behavior():
+    result = function(input)
+    assert result == expected
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pytest tests/path/test.py::test_name -v`
+Expected: FAIL with "function not defined"
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+def function(input):
+    return expected
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pytest tests/path/test.py::test_name -v`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tests/path/test.py src/path/file.py
+git commit -m "feat: add specific feature"
+```
+````
+
+## No Placeholders
+
+Every step must contain the actual content an engineer needs. These are **plan failures** — never write them:
+- "TBD", "TODO", "implement later", "fill in details"
+- "Add appropriate error handling" / "add validation" / "handle edge cases"
+- "Write tests for the above" (without actual test code)
+- "Similar to Task N" (repeat the code — the engineer may be reading tasks out of order)
+- Steps that describe what to do without showing how (code blocks required for code steps)
+- References to types, functions, or methods not defined in any task
+
+## Remember
+- Exact file paths always
+- Complete code in every step — if a step changes code, show the code
+- Exact commands with expected output
+- DRY, YAGNI, TDD, frequent commits
+
+## Self-Review
+
+After writing the complete plan, look at the spec with fresh eyes and check the plan against it. This is a checklist you run yourself — not a subagent dispatch.
+
+**1. Spec coverage:** Skim each section/requirement in the spec. Can you point to a task that implements it? List any gaps.
+
+**2. Placeholder scan:** Search your plan for red flags — any of the patterns from the "No Placeholders" section above. Fix them.
+
+**3. Type consistency:** Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks? A function called `clearLayers()` in Task 3 but `clearFullLayers()` in Task 7 is a bug.
+
+If you find issues, fix them inline. No need to re-review — just fix and move on. If you find a spec requirement with no task, add the task.
+
+## Execution Handoff
+
+After saving the plan, offer execution choice:
+
+**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Two execution options:**
+
+**1. Subagent-Driven (recommended)** - I dispatch a fresh subagent per task, review between tasks, fast iteration
+
+**2. Inline Execution** - Execute tasks in this session using executing-plans, batch execution with checkpoints
+
+**Which approach?"**
+
+**If Subagent-Driven chosen:**
+- **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development
+- Fresh subagent per task + two-stage review
+
+**If Inline Execution chosen:**
+- **REQUIRED SUB-SKILL:** Use superpowers:executing-plans
+- Batch execution with checkpoints for review

package/templates/h5/.agents/skills/writing-plans/plan-document-reviewer-prompt.md

@@ -0,0 +1,49 @@
+# Plan Document Reviewer Prompt Template
+
+Use this template when dispatching a plan document reviewer subagent.
+
+**Purpose:** Verify the plan is complete, matches the spec, and has proper task decomposition.
+
+**Dispatch after:** The complete plan is written.
+
+```
+Subagent (general-purpose):
+  description: "Review plan document"
+  prompt: |
+    You are a plan document reviewer. Verify this plan is complete and ready for implementation.
+
+    **Plan to review:** [PLAN_FILE_PATH]
+    **Spec for reference:** [SPEC_FILE_PATH]
+
+    ## What to Check
+
+    | Category | What to Look For |
+    |----------|------------------|
+    | Completeness | TODOs, placeholders, incomplete tasks, missing steps |
+    | Spec Alignment | Plan covers spec requirements, no major scope creep |
+    | Task Decomposition | Tasks have clear boundaries, steps are actionable |
+    | Buildability | Could an engineer follow this plan without getting stuck? |
+
+    ## Calibration
+
+    **Only flag issues that would cause real problems during implementation.**
+    An implementer building the wrong thing or getting stuck is an issue.
+    Minor wording, stylistic preferences, and "nice to have" suggestions are not.
+
+    Approve unless there are serious gaps — missing requirements from the spec,
+    contradictory steps, placeholder content, or tasks so vague they can't be acted on.
+
+    ## Output Format
+
+    ## Plan Review
+
+    **Status:** Approved | Issues Found
+
+    **Issues (if any):**
+    - [Task X, Step Y]: [specific issue] - [why it matters for implementation]
+
+    **Recommendations (advisory, do not block approval):**
+    - [suggestions for improvement]
+```
+
+**Reviewer returns:** Status, Issues (if any), Recommendations

package/templates/h5/docs/agent-skills.md

@@ -0,0 +1,136 @@
+# Agent Skills 使用说明
+
+本脚手架预置了来自 [obra/superpowers](https://github.com/obra/superpowers) 的 4 个 Cursor Agent Skills，位于：
+
+```
+.agents/skills/
+├── brainstorming/
+├── systematic-debugging/
+├── test-driven-development/
+└── writing-plans/
+```
+
+`skills-lock.json` 记录安装来源与版本哈希，便于团队用 `npx skills experimental_install` 恢复或更新。
+
+## Skills 不会每次对话都执行
+
+开启新对话时，Agent **不会**把 4 个 skill 全文跑一遍，只会看到一份 **技能目录**（名称 + `description` 摘要）。
+
+只有当任务与某个 skill 的 `description` 匹配，或你 **主动点名**（`@brainstorming`、在对话里说「按 TDD 做」等）时，Agent 才会读取对应 `SKILL.md` 并按其中流程执行。
+
+## 推荐工作流
+
+典型功能开发顺序：
+
+```
+brainstorming → writing-plans → test-driven-development
+         ↑
+systematic-debugging（遇 bug / 测试失败时插入）
+```
+
+| 顺序 | Skill | 作用 |
+|------|-------|------|
+| 1 | `brainstorming` | 动手写代码前，澄清需求、对比方案、产出设计并获你确认 |
+| 2 | `writing-plans` | 设计通过后，拆成可执行的多步实现计划 |
+| 3 | `test-driven-development` | 按计划实现时，先写测试再写实现 |
+| — | `systematic-debugging` | 出现 bug、测试失败、异常行为时，先根因分析再改代码 |
+
+## 各 Skill 何时会被 Agent 调用
+
+### 1. brainstorming
+
+**自动触发场景**（Agent 根据 description 判断）：
+
+- 新建功能、页面、组件
+- 修改现有行为或交互
+- 需求不清晰、有多种实现路径
+- 任何「创造性」开发任务
+
+**核心约束**：在呈现设计并获得你批准之前，**不得**直接写实现代码（skill 内 HARD-GATE）。
+
+**你可主动说**：
+
+- 「先 brainstorm 一下登录页方案」
+- `@brainstorming 帮我设计设备列表页`
+
+---
+
+### 2. writing-plans
+
+**自动触发场景**：
+
+- 已有需求说明或设计文档
+- 多文件、多步骤的中大型任务
+- brainstorming 结束、准备开工前
+
+**产出**：分步骤的实现计划（改哪些文件、如何验证、提交粒度等）。
+
+**你可主动说**：
+
+- 「根据刚才的设计写实现计划」
+- `@writing-plans`
+
+---
+
+### 3. test-driven-development
+
+**自动触发场景**：
+
+- 开始实现某个功能或 bugfix
+- 对话中提到 TDD、先写测试
+- writing-plans 进入编码阶段
+
+**核心约束**：先写失败测试 → 写最少实现让测试通过 → 重构。
+
+**你可主动说**：
+
+- 「用 TDD 实现这个 API 封装」
+- `@test-driven-development`
+
+---
+
+### 4. systematic-debugging
+
+**自动触发场景**：
+
+- 运行报错、测试失败
+- 线上/本地行为与预期不符
+- 准备「试一把修复」之前
+
+**核心约束**：先定位根因、复现路径，再提出修复；避免无依据地改代码。
+
+**你可主动说**：
+
+- 「系统排查一下 welcome 接口 401」
+- `@systematic-debugging`
+
+## 如何手动指定 Skill
+
+| 方式 | 示例 |
+|------|------|
+| `@` 引用 | 在 Cursor 输入 `@brainstorming` |
+| 自然语言 | 「按 superpowers 的 brainstorming 流程来」 |
+| 明确阶段 | 「先不要写代码，走 brainstorming」 |
+
+## 安装与更新（维护者）
+
+在**已生成项目**或**本模板目录**中：
+
+```bash
+# 安装单个 skill
+npx skills add https://github.com/obra/superpowers --skill brainstorming --agent cursor -y --copy
+
+# 从 lock 恢复
+npx skills experimental_install
+
+# 查看已安装
+npx skills ls
+```
+
+脚手架生成项目时会复制 `.agents/skills/` 与 `skills-lock.json`，团队成员打开项目即可使用，无需每人重新安装。
+
+## 注意事项
+
+1. **不是每个小改动都要走全套**：改 typo、调样式等可直接说明；复杂功能建议走 brainstorming → plans → TDD。
+2. **Skills 会占用上下文**：被选中时才会加载完整 `SKILL.md`；目录摘要常驻，但开销很小。
+3. **来源与许可**：Skills 来自第三方仓库 [obra/superpowers](https://github.com/obra/superpowers)，升级前请阅读其变更说明。

package/templates/h5/index.html

@@ -10,6 +10,8 @@
     <meta name="mobile-web-app-capable" content="yes" />
     <meta name="format-detection" content="telephone=no" />
     <meta name="apple-touch-fullscreen" content="yes" />
+    <link rel="icon" type="image/png" href="/favicon.png" />
+    <link rel="icon" href="/favicon.ico" sizes="any" />
     <title>%VITE_APP_TITLE%</title>
   </head>
   <body>

package/templates/h5/scripts/version.js

@@ -5,7 +5,7 @@ import { fileURLToPath } from 'node:url'
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
 const packagePath = path.resolve(__dirname, '../package.json')
-const pkg = JSON.parse(fs.readFileSync(packagePath, 'utf8')) as { version: string }
+const pkg = JSON.parse(fs.readFileSync(packagePath, 'utf8'))
 
 const [major, minor, patch] = pkg.version.split('.').map(Number)
 

package/templates/h5/skills-lock.json

@@ -0,0 +1,29 @@
+{
+  "version": 1,
+  "skills": {
+    "brainstorming": {
+      "source": "obra/superpowers",
+      "sourceType": "github",
+      "skillPath": "skills/brainstorming/SKILL.md",
+      "computedHash": "26a8eb33d548f0c4ead9e7bc13a90c3853398d30345c651245a61a12b869f130"
+    },
+    "systematic-debugging": {
+      "source": "obra/superpowers",
+      "sourceType": "github",
+      "skillPath": "skills/systematic-debugging/SKILL.md",
+      "computedHash": "792a368e074981d7e3138edb439e138489b2ac247cd1e5739fab52af680fb17b"
+    },
+    "test-driven-development": {
+      "source": "obra/superpowers",
+      "sourceType": "github",
+      "skillPath": "skills/test-driven-development/SKILL.md",
+      "computedHash": "eee144aea35d783296d178017e9fe843c6d16cc8b240e106f5e50910f6caf329"
+    },
+    "writing-plans": {
+      "source": "obra/superpowers",
+      "sourceType": "github",
+      "skillPath": "skills/writing-plans/SKILL.md",
+      "computedHash": "b73b59d43c34c3fc225bfae419c458bb216af80df25fc0c545dfa7fd2a161722"
+    }
+  }
+}

package/templates/h5/src/assets/styles/atomic/flex.css

@@ -0,0 +1,60 @@
+.flex {
+  display: flex;
+}
+
+.inline-flex {
+  display: inline-flex;
+}
+
+.flex-col {
+  flex-direction: column;
+}
+
+.flex-row {
+  flex-direction: row;
+}
+
+.flex-wrap {
+  flex-wrap: wrap;
+}
+
+.flex-1 {
+  flex: 1 1 0%;
+}
+
+.flex-shrink-0 {
+  flex-shrink: 0;
+}
+
+.flex-center {
+  align-items: center;
+  justify-content: center;
+}
+
+.items-center {
+  align-items: center;
+}
+
+.items-start {
+  align-items: flex-start;
+}
+
+.items-end {
+  align-items: flex-end;
+}
+
+.justify-center {
+  justify-content: center;
+}
+
+.justify-between {
+  justify-content: space-between;
+}
+
+.justify-end {
+  justify-content: flex-end;
+}
+
+.justify-start {
+  justify-content: flex-start;
+}

package/templates/h5/src/assets/styles/atomic/index.css

@@ -0,0 +1,4 @@
+@import './flex.css';
+@import './spacing.css';
+@import './text.css';
+@import './layout.css';

package/templates/h5/src/assets/styles/atomic/layout.css

@@ -0,0 +1,64 @@
+.block {
+  display: block;
+}
+
+.inline-block {
+  display: inline-block;
+}
+
+.hidden {
+  display: none !important;
+}
+
+.w-full {
+  width: 100%;
+}
+
+.h-full {
+  height: 100%;
+}
+
+.min-h-full {
+  min-height: 100%;
+}
+
+.relative {
+  position: relative;
+}
+
+.absolute {
+  position: absolute;
+}
+
+.fixed {
+  position: fixed;
+}
+
+.overflow-hidden {
+  overflow: hidden;
+}
+
+.overflow-auto {
+  overflow: auto;
+}
+
+.rounded-8 {
+  border-radius: 8px;
+}
+
+.rounded-12 {
+  border-radius: 12px;
+}
+
+.border {
+  border: 1px solid var(--color-border);
+}
+
+.border-t {
+  border-top: 1px solid var(--color-divider);
+}
+
+.safe-bottom {
+  padding-bottom: constant(safe-area-inset-bottom);
+  padding-bottom: env(safe-area-inset-bottom);
+}

package/templates/h5/src/assets/styles/atomic/spacing.css

@@ -0,0 +1,97 @@
+.m-0 {
+  margin: 0;
+}
+
+.m-8 {
+  margin: 8px;
+}
+
+.m-12 {
+  margin: 12px;
+}
+
+.m-16 {
+  margin: 16px;
+}
+
+.m-24 {
+  margin: 24px;
+}
+
+.m-t-8 {
+  margin-top: 8px;
+}
+
+.m-t-12 {
+  margin-top: 12px;
+}
+
+.m-t-16 {
+  margin-top: 16px;
+}
+
+.m-t-24 {
+  margin-top: 24px;
+}
+
+.m-b-8 {
+  margin-bottom: 8px;
+}
+
+.m-b-12 {
+  margin-bottom: 12px;
+}
+
+.m-b-16 {
+  margin-bottom: 16px;
+}
+
+.m-b-24 {
+  margin-bottom: 24px;
+}
+
+.m-l-8 {
+  margin-left: 8px;
+}
+
+.m-l-12 {
+  margin-left: 12px;
+}
+
+.m-r-8 {
+  margin-right: 8px;
+}
+
+.m-r-12 {
+  margin-right: 12px;
+}
+
+.p-0 {
+  padding: 0;
+}
+
+.p-8 {
+  padding: 8px;
+}
+
+.p-12 {
+  padding: 12px;
+}
+
+.p-16 {
+  padding: 16px;
+}
+
+.p-24 {
+  padding: 24px;
+}
+
+.p-x-16 {
+  padding-left: 16px;
+  padding-right: 16px;
+}
+
+.p-y-12 {
+  padding-top: 12px;
+  padding-bottom: 12px;
+}