Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

docs: salvage HarmonyOS ArkTS guidance

Affaan Mustafaa8836d7bbd8b
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 947349fbf..ed300ff08 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -11,7 +11,7 @@
{
"name": "ecc",
"source": "./",
- "description": "The most comprehensive Claude Code plugin — 54 agents, 208 skills, 72 legacy command shims, selective install profiles, and production-ready hooks for TDD, security scanning, code review, and continuous learning",
+ "description": "The most comprehensive Claude Code plugin — 55 agents, 208 skills, 72 legacy command shims, selective install profiles, and production-ready hooks for TDD, security scanning, code review, and continuous learning",
"version": "2.0.0-rc.1",
"author": {
"name": "Affaan Mustafa",
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 443fc68a0..230f341d7 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ecc",
"version": "2.0.0-rc.1",
- "description": "Battle-tested Claude Code plugin for engineering teams — 54 agents, 208 skills, 72 legacy command shims, production-ready hooks, and selective install workflows evolved through continuous real-world use",
+ "description": "Battle-tested Claude Code plugin for engineering teams — 55 agents, 208 skills, 72 legacy command shims, production-ready hooks, and selective install workflows evolved through continuous real-world use",
"author": {
"name": "Affaan Mustafa",
"url": "https://x.com/affaanmustafa"
diff --git a/AGENTS.md b/AGENTS.md
index ffb243c7d..db3b3a83e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
# Everything Claude Code (ECC) — Agent Instructions
-This is a **production-ready AI coding plugin** providing 54 specialized agents, 208 skills, 72 commands, and automated hook workflows for software development.
+This is a **production-ready AI coding plugin** providing 55 specialized agents, 208 skills, 72 commands, and automated hook workflows for software development.
**Version:** 2.0.0-rc.1
@@ -146,7 +146,7 @@ Troubleshoot failures: check test isolation → verify mocks → fix implementat
## Project Structure
```
-agents/ — 54 specialized subagents
+agents/ — 55 specialized subagents
skills/ — 208 workflow skills and domain knowledge
commands/ — 72 slash commands
hooks/ — Trigger-based automations
diff --git a/README.md b/README.md
index 037651177..3da3755d5 100644
--- a/README.md
+++ b/README.md
@@ -89,7 +89,7 @@ This repo is the raw code only. The guides explain everything.
### v2.0.0-rc.1 — Surface Refresh, Operator Workflows, and ECC 2.0 Alpha (Apr 2026)
- **Dashboard GUI** — New Tkinter-based desktop application (`ecc_dashboard.py` or `npm run dashboard`) with dark/light theme toggle, font customization, and project logo in header and taskbar.
-- **Public surface synced to the live repo** — metadata, catalog counts, plugin manifests, and install-facing docs now match the actual OSS surface: 54 agents, 208 skills, and 72 legacy command shims.
+- **Public surface synced to the live repo** — metadata, catalog counts, plugin manifests, and install-facing docs now match the actual OSS surface: 55 agents, 208 skills, and 72 legacy command shims.
- **Operator and outbound workflow expansion** — `brand-voice`, `social-graph-ranker`, `connections-optimizer`, `customer-billing-ops`, `ecc-tools-cost-audit`, `google-workspace-ops`, `project-flow-ops`, and `workspace-surface-audit` round out the operator lane.
- **Media and launch tooling** — `manim-video`, `remotion-video-creation`, and upgraded social publishing surfaces make technical explainers and launch content part of the same system.
- **Framework and product surface growth** — `nestjs-patterns`, richer Codex/OpenCode install surfaces, and expanded cross-harness packaging keep the repo usable beyond Claude Code alone.
@@ -358,7 +358,7 @@ If you stacked methods, clean up in this order:
/plugin list ecc@ecc
```
-**That's it!** You now have access to 54 agents, 208 skills, and 72 legacy command shims.
+**That's it!** You now have access to 55 agents, 208 skills, and 72 legacy command shims.
### Dashboard GUI
@@ -456,7 +456,7 @@ everything-claude-code/
| |-- plugin.json # Plugin metadata and component paths
| |-- marketplace.json # Marketplace catalog for /plugin marketplace add
|
-|-- agents/ # 54 specialized subagents for delegation
+|-- agents/ # 55 specialized subagents for delegation
| |-- planner.md # Feature implementation planning
| |-- architect.md # System design decisions
| |-- tdd-guide.md # Test-driven development
@@ -481,6 +481,7 @@ everything-claude-code/
| |-- java-build-resolver.md # Java/Maven/Gradle build errors
| |-- kotlin-reviewer.md # Kotlin/Android/KMP code review
| |-- kotlin-build-resolver.md # Kotlin/Gradle build errors
+| |-- harmonyos-app-resolver.md # HarmonyOS/ArkTS app development
| |-- rust-reviewer.md # Rust code review
| |-- rust-build-resolver.md # Rust build error resolution
| |-- pytorch-build-resolver.md # PyTorch/CUDA training errors
@@ -606,6 +607,7 @@ everything-claude-code/
| |-- golang/ # Go specific
| |-- swift/ # Swift specific
| |-- php/ # PHP specific (NEW)
+| |-- arkts/ # HarmonyOS / ArkTS specific
|
|-- hooks/ # Trigger-based automations
| |-- README.md # Hook documentation, recipes, and customization guide
@@ -840,6 +842,7 @@ cp -r everything-claude-code/rules/typescript ~/.claude/rules/ecc/ # pick your
cp -r everything-claude-code/rules/python ~/.claude/rules/ecc/
cp -r everything-claude-code/rules/golang ~/.claude/rules/ecc/
cp -r everything-claude-code/rules/php ~/.claude/rules/ecc/
+cp -r everything-claude-code/rules/arkts ~/.claude/rules/ecc/
# Copy skills first (primary workflow surface)
# Recommended (new users): core/general skills only
@@ -959,6 +962,7 @@ rules/
golang/ # Go specific patterns and tools
swift/ # Swift specific patterns and tools
php/ # PHP specific patterns and tools
+ arkts/ # HarmonyOS / ArkTS patterns and constraints
```
See [`rules/README.md`](rules/README.md) for installation and structure details.
@@ -983,6 +987,7 @@ Not sure where to start? Use this quick reference. Skills are the canonical work
| Review Go code | `/go-review` | go-reviewer |
| Review Python code | `/python-review` | python-reviewer |
| Review TypeScript/JavaScript code | *(invoke `typescript-reviewer` directly)* | typescript-reviewer |
+| Develop HarmonyOS apps | *(invoke `harmonyos-app-resolver` directly)* | harmonyos-app-resolver |
| Audit database queries | *(auto-delegated)* | database-reviewer |
| Review production ML changes | `mle-workflow` skill + `mle-reviewer` agent | mle-reviewer |
@@ -1141,7 +1146,7 @@ Please contribute! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
### Ideas for Contributions
-- Language-specific skills (Rust, C#, Kotlin, Java) — Go, Python, Perl, Swift, and TypeScript already included
+- Language-specific skills (Rust, C#, Kotlin, Java) — Go, Python, Perl, Swift, TypeScript, and HarmonyOS/ArkTS already included
- Framework-specific configs (Rails, FastAPI) — Django, NestJS, Spring Boot, and Laravel already included
- DevOps agents (Kubernetes, Terraform, AWS, Docker)
- Testing strategies (different frameworks, visual regression)
@@ -1349,7 +1354,7 @@ The configuration is automatically detected from `.opencode/opencode.json`.
| Feature | Claude Code | OpenCode | Status |
|---------|-------------|----------|--------|
-| Agents | PASS: 54 agents | PASS: 12 agents | **Claude Code leads** |
+| Agents | PASS: 55 agents | PASS: 12 agents | **Claude Code leads** |
| Commands | PASS: 72 commands | PASS: 35 commands | **Claude Code leads** |
| Skills | PASS: 208 skills | PASS: 37 skills | **Claude Code leads** |
| Hooks | PASS: 8 event types | PASS: 11 events | **OpenCode has more!** |
@@ -1454,7 +1459,7 @@ ECC is the **first plugin to maximize every major AI coding tool**. Here's how e
| Feature | Claude Code | Cursor IDE | Codex CLI | OpenCode |
|---------|------------|------------|-----------|----------|
-| **Agents** | 54 | Shared (AGENTS.md) | Shared (AGENTS.md) | 12 |
+| **Agents** | 55 | Shared (AGENTS.md) | Shared (AGENTS.md) | 12 |
| **Commands** | 72 | Shared | Instruction-based | 35 |
| **Skills** | 208 | Shared | 10 (native format) | 37 |
| **Hook Events** | 8 types | 15 types | None yet | 11 types |
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 6b0e1c119..ed83c1677 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -160,7 +160,7 @@ Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/"
/plugin list ecc@ecc
```
-**完成!** 你现在可以使用 54 个代理、208 个技能和 72 个命令。
+**完成!** 你现在可以使用 55 个代理、208 个技能和 72 个命令。
### multi-* 命令需要额外配置
diff --git a/agents/harmonyos-app-resolver.md b/agents/harmonyos-app-resolver.md
new file mode 100644
index 000000000..8dc08c924
--- /dev/null
+++ b/agents/harmonyos-app-resolver.md
@@ -0,0 +1,173 @@
+---
+name: harmonyos-app-resolver
+description: HarmonyOS application development expert specializing in ArkTS and ArkUI. Reviews code for V2 state management compliance, Navigation routing patterns, API usage, and performance best practices. Use for HarmonyOS/OpenHarmony projects.
+tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
+model: sonnet
+---
+
+# HarmonyOS Application Development Expert
+
+You are a senior HarmonyOS application development expert specializing in ArkTS and ArkUI for building high-quality HarmonyOS native applications. You have deep understanding of HarmonyOS system components, APIs, and underlying mechanisms, and always apply industry best practices.
+
+## Core Tech Stack Constraints (Strictly Enforced)
+
+In all code generation, Q&A, and technical recommendations, you MUST strictly follow these technology choices - **no compromise**:
+
+### 1. State Management: V2 Only (ArkUI State Management V2)
+
+- **MUST use**: ArkUI State Management V2 decorators/patterns (use applicable decorators by context), including `@ComponentV2`, `@Local`, `@Param`, `@Event`, `@Provider`, `@Consumer`, `@Monitor`, `@Computed`; use `@ObservedV2` + `@Trace` for observable model classes/properties when needed.
+- **MUST NOT use**: V1 decorators (`@Component`, `@State`, `@Prop`, `@Link`, `@ObjectLink`, `@Observed`, `@Provide`, `@Consume`, `@Watch`)
+
+### 2. Routing: Navigation Only
+
+- **MUST use**: `Navigation` component with `NavPathStack` for route management; use `NavDestination` as root container for sub-pages
+- **MUST NOT use**: Legacy `router` module (`@ohos.router`) for page navigation
+
+## Your Role
+
+- **ArkTS & ArkUI mastery** - Write elegant, efficient, type-safe declarative UI code with deep understanding of V2 state management observation mechanisms and UI update logic
+- **Full-stack component & API expertise** - Proficient with UI components (List, Grid, Swiper, Tabs, etc.) and system APIs (network, media, file, preferences, etc.) to rapidly implement complex business requirements
+- **Best practice enforcement**:
+ - **Architecture**: Modular, layered architecture ensuring high cohesion and low coupling
+ - **Performance**: Use `LazyForEach`, component reuse, async processing for expensive tasks
+ - **Code standards**: Consistent style, rigorous logic, clear comments, compliant with HarmonyOS official guidelines
+
+## Workflow
+
+### Step 1: Understand Project Context
+
+- Read `CLAUDE.md`, `module.json5`, `oh-package.json5` for project conventions
+- Identify existing state management version (V1 vs V2) and routing approach
+- Check `build-profile.json5` for API level and device targets
+
+### Step 2: Review or Implement
+
+When reviewing code:
+- Flag any V1 state management usage - recommend V2 migration
+- Flag any `@ohos.router` usage - recommend Navigation migration
+- Check API level compatibility and permission declarations
+- Verify resource references use `$r()` instead of hardcoded literals
+- Check i18n completeness across all language directories
+
+When implementing features:
+- Use V2 state management exclusively
+- Use Navigation + NavPathStack for routing
+- Define UI constants in resources, reference via `$r()`
+- Add i18n strings to all language directories
+- Consider dark theme support for new color resources
+
+### Step 3: Validate
+
+```bash
+# Build HAP package (global hvigor environment)
+hvigorw assembleHap -p product=default
+```
+
+- Run build after every implementation to verify compilation
+- Check for ArkTS syntax constraint violations
+- Verify permission declarations in `module.json5`
+
+## ArkTS Syntax Constraints (Compilation Blockers)
+
+ArkTS is a strict subset of TypeScript. The following are NOT supported and will cause compilation failures:
+
+**Type System:**
+- No `any` or `unknown` types - use explicit types
+- No index access types - use type names
+- No conditional type aliases or `infer` keyword
+- No intersection types - use inheritance
+- No mapped types - use classes
+- No `typeof` for type annotations - use explicit type declarations
+- No `as const` assertions - use explicit type annotations
+- No structural typing - use inheritance, interfaces, or type aliases
+- No TypeScript utility types except `Partial`, `Required`, `Readonly`, `Record`
+
+**Functions & Classes:**
+- No function expressions - use arrow functions
+- No nested functions - use lambdas
+- No generator functions - use async/await
+- No `Function.apply`, `Function.call`, `Function.bind`
+- No constructor type expressions - use lambdas
+- No constructor signatures in interfaces or object types
+- No declaring class fields in constructors - declare in class body
+- No `this` in standalone functions or static methods
+- No `new.target`
+
+**Object & Property Access:**
+- No dynamic field declaration or `obj["field"]` access - use `obj.field`
+- No `delete` operator - use nullable type with `null`
+- No prototype assignment
+- No `in` operator - use `instanceof`
+- No `Symbol()` API (except `Symbol.iterator`)
+- No `globalThis` or global scope - use explicit module exports/imports
+
+**Destructuring & Spread:**
+- No destructuring assignments or variable declarations
+- No destructuring parameter declarations
+- Spread operator only for arrays into rest parameters or array literals
+
+**Modules & Imports:**
+- No `require()` imports - use regular `import`
+- No `export = ...` syntax - use normal export/import
+- No import assertions
+- No UMD modules
+- No wildcards in module names
+- All `import` statements must precede other statements
+
+**Other:**
+- No `var` keyword - use `let`
+- No `for...in` loops - use regular `for` loops for arrays
+- No `with` statements
+- No JSX expressions
+- No `#` private identifiers - use `private` keyword
+- No declaration merging
+- No index signatures - use arrays
+- No class literals - use named class types
+- Comma operator only in `for` loops
+- Unary operators `+`, `-`, `~` only for numeric types
+- Omit type annotations in `catch` clauses
+
+**Object Literals:**
+- Supported only when compiler can infer the corresponding class/interface
+- Not supported for: `any`/`Object`/`object` types, classes with methods, classes with parameterized constructors, classes with `readonly` fields
+
+## HarmonyOS API Usage Guidelines
+
+- Prefer official HarmonyOS APIs, UI components, animations, and code templates
+- Verify API parameters, return values, API level, and device support before use
+- When uncertain about syntax or API usage, search official Huawei developer documentation - never guess
+- Confirm `import` statements are added at file header before using APIs
+- Verify required permissions in `module.json5` before calling APIs
+- Verify dependency existence and version compatibility in `oh-package.json5`
+- Enforce `@ComponentV2` for all new or modified ArkUI components; when encountering legacy `@Component`, recommend migration to V2
+- Define UI display constants as resources, reference via `$r()` - avoid hardcoded literals
+- Add i18n resource strings to all language directories when creating new entries
+- Check if new color resources need dark theme support (recommended for new projects)
+
+## ArkUI Animation Guidelines
+
+- Prefer native HarmonyOS animation APIs and advanced templates
+- Use declarative UI with state-driven animations (change state variables to trigger animations)
+- Set `renderGroup(true)` for complex sub-component animations to reduce render batches
+- NEVER frequently change `width`, `height`, `padding`, `margin` during animations - severe performance impact
+
+## Behavior Guidelines
+
+- **Proactive refactoring**: If user code contains V1 state management or `router` routing, proactively flag it and refactor to V2 + Navigation
+- **Explain best practices**: Briefly explain why a solution is "best practice" (e.g., performance advantages of `@ComponentV2` over V1)
+- **Rigor**: Ensure code snippets are complete, runnable, and handle common edge cases (empty data, loading states, error handling)
+
+## Output Format
+
+```text
+[REVIEW] src/main/ets/pages/HomePage.ets:15
+Issue: Uses V1 @State decorator
+Fix: Migrate to @ComponentV2 with @Local for local state
+
+[IMPLEMENT] src/main/ets/viewmodel/UserViewModel.ets
+Created: ViewModel using @ObservedV2 with @Trace for observable properties, consumed via @ComponentV2 with @Local/@Param
+```
+
+Final: `Status: SUCCESS/NEEDS_WORK | Issues Found: N | Files Modified: list`
+
+For detailed HarmonyOS patterns and code examples, refer to rule files in `rules/arkts/`.
diff --git a/docs/zh-CN/AGENTS.md b/docs/zh-CN/AGENTS.md
index b6f15070f..63f6ba265 100644
--- a/docs/zh-CN/AGENTS.md
+++ b/docs/zh-CN/AGENTS.md
@@ -1,6 +1,6 @@
# Everything Claude Code (ECC) — 智能体指令
-这是一个**生产就绪的 AI 编码插件**,提供 54 个专业代理、208 项技能、72 条命令以及自动化钩子工作流,用于软件开发。
+这是一个**生产就绪的 AI 编码插件**,提供 55 个专业代理、208 项技能、72 条命令以及自动化钩子工作流,用于软件开发。
**版本:** 2.0.0-rc.1
@@ -146,7 +146,7 @@
## 项目结构
```
-agents/ — 54 个专业子代理
+agents/ — 55 个专业子代理
skills/ — 208 个工作流技能和领域知识
commands/ — 72 个斜杠命令
hooks/ — 基于触发的自动化
diff --git a/docs/zh-CN/README.md b/docs/zh-CN/README.md
index d1ec31d93..d48df9fa1 100644
--- a/docs/zh-CN/README.md
+++ b/docs/zh-CN/README.md
@@ -224,7 +224,7 @@ Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/"
/plugin list ecc@ecc
```
-**搞定!** 你现在可以使用 54 个智能体、208 项技能和 72 个命令了。
+**搞定!** 你现在可以使用 55 个智能体、208 项技能和 72 个命令了。
***
@@ -1132,7 +1132,7 @@ opencode
| 功能特性 | Claude Code | OpenCode | 状态 |
|---------|-------------|----------|--------|
-| 智能体 | PASS: 54 个 | PASS: 12 个 | **Claude Code 领先** |
+| 智能体 | PASS: 55 个 | PASS: 12 个 | **Claude Code 领先** |
| 命令 | PASS: 72 个 | PASS: 35 个 | **Claude Code 领先** |
| 技能 | PASS: 208 项 | PASS: 37 项 | **Claude Code 领先** |
| 钩子 | PASS: 8 种事件类型 | PASS: 11 种事件 | **OpenCode 更多!** |
@@ -1240,7 +1240,7 @@ ECC 是**第一个最大化利用每个主要 AI 编码工具的插件**。以
| 功能特性 | Claude Code | Cursor IDE | Codex CLI | OpenCode |
|---------|------------|------------|-----------|----------|
-| **智能体** | 54 | 共享 (AGENTS.md) | 共享 (AGENTS.md) | 12 |
+| **智能体** | 55 | 共享 (AGENTS.md) | 共享 (AGENTS.md) | 12 |
| **命令** | 72 | 共享 | 基于指令 | 35 |
| **技能** | 208 | 共享 | 10 (原生格式) | 37 |
| **钩子事件** | 8 种类型 | 15 种类型 | 暂无 | 11 种类型 |
diff --git a/examples/harmonyos-app-CLAUDE.md b/examples/harmonyos-app-CLAUDE.md
new file mode 100644
index 000000000..f5cb257ae
--- /dev/null
+++ b/examples/harmonyos-app-CLAUDE.md
@@ -0,0 +1,88 @@
+# HarmonyOS App Project CLAUDE.md
+
+This is a project-level CLAUDE.md example for HarmonyOS applications. Place it at your project root.
+
+## Project Overview
+
+[Briefly describe your app - features, target devices, API level]
+
+## Core Rules
+
+### 1. Tech Stack Constraints
+
+- Platform: HarmonyOS (ArkTS/TypeScript), prefer latest stable official APIs
+- State Management: **V2 only** (`@ComponentV2`, `@Local`, `@Param`, `@Event`, `@Provider`, `@Consumer`, `@Monitor`, `@Computed`)
+- Routing: **Navigation only** (`Navigation` + `NavPathStack` + `NavDestination`)
+- Architecture: MVVM with modular layers - View renders only, all business logic in ViewModel
+- Component priority: in-module reusable components > cross-module shared components > third-party libraries
+
+### 2. Code Organization
+
+- Prefer many small files over few large files
+- High cohesion, low coupling
+- Target 200-400 lines per file, max 800 lines
+- Organize by feature/domain, not by type
+
+### 3. Code Style
+
+- No emojis in code, comments, or documentation
+- Immutability - never mutate objects directly
+- Double quotes for strings; semicolons required
+- Never use `var` - prefer `const`, then `let`
+- No `any` type - complete type annotations for all methods, parameters, return values
+- Naming: `camelCase` for variables/functions, `PascalCase` for classes/interfaces, `UPPER_SNAKE_CASE` for constants
+- File header: `@file` + `@author`; all methods need JSDoc with `@param` and `@returns`
+
+### 4. Layout & Interaction
+
+- Use `layoutWeight(1)` for even distribution - avoid `SpaceAround`/`SpaceBetween`
+- Use percentages / layout weights / adaptive units - no hardcoded fixed dimensions (except icons)
+- Define UI constants as resources, reference via `$r()`
+- Support both light and dark themes for new color resources
+
+### 5. Build & Validation
+
+```bash
+# Build HAP package
+hvigorw assembleHap -p product=default
+```
+
+- Run build after every implementation to verify compilation
+- Refer to official Huawei developer docs for uncertain API usage - never guess
+
+### 6. Testing
+
+- TDD: write tests first
+- Unit tests for utility functions and ViewModels
+- UI tests for critical user flows
+- Minimum 80% coverage for business logic
+
+### 7. Security
+
+- No hardcoded secrets
+- Verify permissions in `module.json5` before using system APIs
+- Validate all user input
+- Use HTTPS for all network requests
+
+## File Structure
+
+```
+src/
+|-- entry/ # App entry, framework initialization
+|-- core/ # Core framework layer
+|-- shared/ # Shared contracts layer
+|-- packages/ # Business feature packages
+```
+
+## Available Commands
+
+- `/plan` - Create implementation plan
+- `/code-review` - Code quality review
+- `/build-fix` - Fix build errors
+
+## Git Workflow
+
+- Conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`
+- No direct commits to main branch
+- PRs require review
+- All tests must pass before merge
diff --git a/manifests/install-components.json b/manifests/install-components.json
index 0724584bf..d70cc6166 100644
--- a/manifests/install-components.json
+++ b/manifests/install-components.json
@@ -217,6 +217,14 @@
"framework-language"
]
},
+ {
+ "id": "lang:arkts",
+ "family": "language",
+ "description": "HarmonyOS, ArkTS, and ArkUI development guidance including V2 state management, Navigation routing, and HarmonyOS API best practices.",
+ "modules": [
+ "framework-language"
+ ]
+ },
{
"id": "lang:perl",
"family": "language",
@@ -347,6 +355,14 @@
"agents-core"
]
},
+ {
+ "id": "agent:harmonyos-app-resolver",
+ "family": "agent",
+ "description": "HarmonyOS application development expert agent.",
+ "modules": [
+ "agents-core"
+ ]
+ },
{
"id": "agent:refactor-cleaner",
"family": "agent",
diff --git a/rules/README.md b/rules/README.md
index 3a7992c55..efac416d0 100644
--- a/rules/README.md
+++ b/rules/README.md
@@ -20,7 +20,8 @@ rules/
├── golang/ # Go specific
├── web/ # Web and frontend specific
├── swift/ # Swift specific
-└── php/ # PHP specific
+├── php/ # PHP specific
+└── arkts/ # HarmonyOS / ArkTS specific
```
- **common/** contains universal principles — no language-specific code examples.
@@ -39,6 +40,7 @@ rules/
./install.sh web
./install.sh swift
./install.sh php
+./install.sh arkts
# Install multiple languages at once
./install.sh typescript python
@@ -64,6 +66,7 @@ cp -r rules/golang ~/.claude/rules/golang
cp -r rules/web ~/.claude/rules/web
cp -r rules/swift ~/.claude/rules/swift
cp -r rules/php ~/.claude/rules/php
+cp -r rules/arkts ~/.claude/rules/arkts
# Attention ! ! ! Configure according to your actual project requirements; the configuration here is for reference only.
```
diff --git a/rules/arkts/coding-style.md b/rules/arkts/coding-style.md
new file mode 100644
index 000000000..5044ced54
--- /dev/null
+++ b/rules/arkts/coding-style.md
@@ -0,0 +1,153 @@
+---
+paths:
+ - "**/*.ets"
+ - "**/*.ts"
+ - "**/module.json5"
+ - "**/oh-package.json5"
+ - "**/build-profile.json5"
+---
+# HarmonyOS / ArkTS Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with HarmonyOS and ArkTS-specific content.
+
+## ArkTS Language Constraints
+
+ArkTS is a strict, statically-typed subset of TypeScript. Violating these constraints causes **compilation failures**.
+
+### Type System
+
+- No `any` or `unknown` types - always use explicit types
+- No index access types - use type names directly
+- No conditional type aliases or `infer` keyword
+- No intersection types - use inheritance
+- No mapped types - use classes and regular idioms
+- No `typeof` for type annotations - use explicit type declarations
+- No `as const` assertions - use explicit type annotations
+- No structural typing - use inheritance, interfaces, or type aliases
+- No TypeScript utility types except `Partial`, `Required`, `Readonly`, `Record`
+- For `Record<K, V>`, index expression type is `V | undefined`
+- Omit type annotations in `catch` clauses (ArkTS does not support `any`/`unknown`)
+
+### Functions & Classes
+
+- No function expressions - use arrow functions
+- No nested functions - use lambdas
+- No generator functions - use `async`/`await` for multitasking
+- No `Function.apply`, `Function.call`, `Function.bind` - follow traditional OOP for `this`
+- No constructor type expressions - use lambdas
+- No constructor signatures in interfaces or object types - use methods or classes
+- No declaring class fields in constructors - declare in class body
+- No `this` in standalone functions or static methods - only in instance methods
+- No `new.target`
+- No definite assignment assertions (`let v!: T`) - use initialized declarations
+- No class literals - introduce named class types
+- No using classes as objects (assigning to variables) - class declarations introduce types, not values
+- Only one static block per class - merge all static statements
+
+### Object & Property Access
+
+- No dynamic field declaration or `obj["field"]` access - use `obj.field` syntax
+- No `delete` operator - use nullable type with `null` to mark absence
+- No prototype assignment - use classes and interfaces
+- No `in` operator - use `instanceof`
+- No reassigning object methods - use wrapper functions or inheritance
+- No `Symbol()` API (except `Symbol.iterator`)
+- No `globalThis` or global scope - use explicit module exports/imports
+- No namespaces as objects - use classes or modules
+- No statements inside namespaces - use functions
+
+### Destructuring & Spread
+
+- No destructuring assignments or variable declarations - use intermediate objects and field-by-field access
+- No destructuring parameter declarations - pass parameters directly, assign local names manually
+- Spread operator only for expanding arrays (or array-derived classes) into rest parameters or array literals
+
+### Modules & Imports
+
+- No `require()` - use regular `import` syntax
+- No `export = ...` - use normal export/import
+- No import assertions - imports are compile-time in ArkTS
+- No UMD modules
+- No wildcards in module names
+- All `import` statements must appear before all other statements
+- TypeScript codebases must not depend on ArkTS codebases via import (reverse is supported)
+
+### Other Restrictions
+
+- No `var` - use `let`
+- No `for...in` loops - use regular `for` loops for arrays
+- No `with` statements
+- No JSX expressions
+- No `#` private identifiers - use `private` keyword
+- No declaration merging (classes, interfaces, enums) - keep definitions compact
+- No index signatures - use arrays
+- Comma operator only in `for` loops
+- Unary operators `+`, `-`, `~` only for numeric types (no implicit string conversion)
+- Enum members: only same-type compile-time expressions for explicit initializers
+- Function return type inference is limited - specify return types explicitly when calling functions with omitted return types
+
+### Object Literals
+
+- Supported only when compiler can infer the corresponding class or interface
+- NOT supported for: `any`/`Object`/`object` types, classes/interfaces with methods, classes with parameterized constructors, classes with `readonly` fields
+
+## Naming Conventions
+
+- Variables / functions: `camelCase` (e.g., `getUserInfo`, `goodsList`)
+- Classes / interfaces: `PascalCase` (e.g., `UserViewModel`, `IGoodsModel`)
+- Constants: `UPPER_SNAKE_CASE` (e.g., `MAX_PAGE_SIZE`, `COLOR_PRIMARY`)
+- File names: `PascalCase` for components (e.g., `HomePage.ets`), `camelCase` for utilities
+
+## Formatting
+
+- Prefer double quotes for strings
+- Semicolons at end of statements
+- Never use `var` - prefer `const`, then `let`
+- All methods, parameters, return values must have complete type annotations
+
+## File Organization
+
+- Component files (`.ets`): one `@ComponentV2` per file
+- ViewModel files: one ViewModel class per file
+- Model files: related data models may share a file
+- Keep files under 400 lines; extract helpers for files approaching 800 lines
+
+## Comments
+
+- File header: `@file` (file purpose) + `@author` (developer), if the project already uses file headers
+- Public methods: JSDoc with `@param`, `@returns`; add `@example` for complex methods
+- Match the project's existing documentation language; use English unless the repository has already standardized on Chinese comments
+
+## Error Handling
+
+```typescript
+// Use try/catch with proper error handling
+try {
+ const result = await riskyOperation()
+ return result
+} catch (error) {
+ hilog.error(0x0000, 'TAG', 'Operation failed: %{public}s', error)
+ throw new Error('User-friendly error message')
+}
+```
+
+## Immutability
+
+Follow the common immutability principles - create new objects instead of mutating:
+
+```typescript
+// BAD: mutation
+function updateUser(user: UserModel, name: string): UserModel {
+ user.name = name // direct mutation
+ return user
+}
+
+// GOOD: immutable - create new instance
+function updateUser(user: UserModel, name: string): UserModel {
+ const updated = new UserModel()
+ updated.id = user.id
+ updated.name = name
+ updated.email = user.email
+ return updated
+}
+```
diff --git a/rules/arkts/hooks.md b/rules/arkts/hooks.md
new file mode 100644
index 000000000..f870d9180
--- /dev/null
+++ b/rules/arkts/hooks.md
@@ -0,0 +1,135 @@
+---
+paths:
+ - "**/*.ets"
+ - "**/*.ts"
+ - "**/module.json5"
+ - "**/oh-package.json5"
+---
+# HarmonyOS / ArkTS Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with HarmonyOS-specific build and validation hooks.
+
+## Build Commands
+
+### HAP Package Build
+
+```bash
+# Build HAP package (global hvigor environment)
+hvigorw assembleHap -p product=default
+
+# Build with specific module
+hvigorw assembleHap -p module=entry -p product=default
+
+# Clean build
+hvigorw clean
+```
+
+### DevEco Studio CLI
+
+```bash
+# Check project structure
+hvigorw --version
+
+# Install dependencies
+ohpm install
+
+# Update dependencies
+ohpm update
+```
+
+## Recommended PostToolUse Hooks
+
+### After Editing .ets/.ts Files
+
+Run hvigor build to check for ArkTS compilation errors:
+
+```json
+{
+ "type": "PostToolUse",
+ "matcher": {
+ "tool": ["Edit", "Write"],
+ "filePath": ["**/*.ets", "**/*.ts"]
+ },
+ "hooks": [
+ {
+ "command": "hvigorw assembleHap -p product=default 2>&1 | tail -20",
+ "async": true,
+ "timeout": 60000
+ }
+ ]
+}
+```
+
+### After Editing module.json5
+
+Validate permission and ability declarations:
+
+```json
+{
+ "type": "PostToolUse",
+ "matcher": {
+ "tool": "Edit",
+ "filePath": "**/module.json5"
+ },
+ "hooks": [
+ {
+ "command": "echo '[HarmonyOS] module.json5 modified - verify permissions and abilities'",
+ "async": false
+ }
+ ]
+}
+```
+
+### After Editing oh-package.json5
+
+Reinstall dependencies:
+
+```json
+{
+ "type": "PostToolUse",
+ "matcher": {
+ "tool": "Edit",
+ "filePath": "**/oh-package.json5"
+ },
+ "hooks": [
+ {
+ "command": "ohpm install 2>&1 | tail -10",
+ "async": true,
+ "timeout": 30000
+ }
+ ]
+}
+```
+
+## PreToolUse Hooks
+
+### V1 Decorator Guard
+
+Warn when code contains V1 state management decorators:
+
+```json
+{
+ "type": "PreToolUse",
+ "matcher": {
+ "tool": ["Write", "Edit"],
+ "filePath": "**/*.ets"
+ },
+ "hooks": [
+ {
+ "command": "echo '[HarmonyOS] Reminder: Use @ComponentV2 / @Local / @Param - V1 decorators (@State, @Prop, @Link) are prohibited'"
+ }
+ ]
+}
+```
+
+## Validation Checklist
+
+After each implementation cycle, verify:
+
+- [ ] `hvigorw assembleHap` completes without errors
+- [ ] No V1 decorators in new or modified `.ets` files
+- [ ] No `@ohos.router` imports in new or modified files
+- [ ] All API permissions declared in `module.json5`
+- [ ] All dependencies listed in `oh-package.json5`
+- [ ] Resource strings added to all i18n directories
+- [ ] Dark theme colors provided for new color resources
diff --git a/rules/arkts/patterns.md b/rules/arkts/patterns.md
new file mode 100644
index 000000000..549a3d17f
--- /dev/null
+++ b/rules/arkts/patterns.md
@@ -0,0 +1,236 @@
+---
+paths:
+ - "**/*.ets"
+ - "**/*.ts"
+---
+# HarmonyOS / ArkTS Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with HarmonyOS and ArkTS-specific patterns.
+
+## State Management: V2 Only
+
+**MUST use** ArkUI State Management V2. V1 decorators are deprecated and must not be used.
+
+### V2 Decorators
+
+| Decorator | Purpose |
+|-----------|---------|
+| `@ComponentV2` | Marks a struct as a V2 component |
+| `@Local` | Local state within a component |
+| `@Param` | Props received from parent (read-only) |
+| `@Event` | Callback events from child to parent |
+| `@Provider` | Provides state to descendant components |
+| `@Consumer` | Consumes state from ancestor `@Provider` |
+| `@Monitor` | Watches for state changes (replaces V1 `@Watch`) |
+| `@Computed` | Derived/computed values |
+| `@ObservedV2` | Makes a class observable for V2 state management |
+| `@Trace` | Marks observable properties in `@ObservedV2` classes |
+
+### Prohibited V1 Decorators
+
+Never use: `@State`, `@Prop`, `@Link`, `@ObjectLink`, `@Observed`, `@Provide`, `@Consume`, `@Watch`, `@Component` (use `@ComponentV2` instead).
+
+### V2 Component Example
+
+```typescript
+@ObservedV2
+class UserModel {
+ @Trace name: string = ''
+ @Trace age: number = 0
+}
+
+@ComponentV2
+struct UserCard {
+ @Param user: UserModel = new UserModel()
+ @Event onDelete: () => void = () => {}
+
+ build() {
+ Column() {
+ Text(this.user.name)
+ .fontSize($r('app.float.font_size_title'))
+ Text(`${this.user.age}`)
+ .fontSize($r('app.float.font_size_body'))
+ Button($r('app.string.delete'))
+ .onClick(() => this.onDelete())
+ }
+ }
+}
+```
+
+### State Synchronization
+
+```typescript
+@ComponentV2
+struct ParentPage {
+ @Provider('userState') userModel: UserModel = new UserModel()
+
+ build() {
+ Column() {
+ ChildComponent() // automatically receives @Consumer('userState')
+ }
+ }
+}
+
+@ComponentV2
+struct ChildComponent {
+ @Consumer('userState') userModel: UserModel = new UserModel()
+
+ build() {
+ Text(this.userModel.name)
+ }
+}
+```
+
+## Routing: Navigation Only
+
+**MUST use** `Navigation` component with `NavPathStack`. Never use `@ohos.router`.
+
+### Navigation Setup
+
+```typescript
+@ComponentV2
+struct MainPage {
+ @Local navPathStack: NavPathStack = new NavPathStack()
+
+ build() {
+ Navigation(this.navPathStack) {
+ // Home content
+ }
+ .navDestination(this.routerMap)
+ }
+
+ @Builder
+ routerMap(name: string, param: ESObject) {
+ if (name === 'detail') {
+ DetailPage()
+ } else if (name === 'settings') {
+ SettingsPage()
+ }
+ }
+}
+```
+
+### Page Navigation
+
+```typescript
+// Push a new page
+this.navPathStack.pushPath({ name: 'detail', param: { id: '123' } })
+
+// Replace current page
+this.navPathStack.replacePath({ name: 'settings' })
+
+// Pop back
+this.navPathStack.pop()
+
+// Pop to root
+this.navPathStack.clear()
+```
+
+### NavDestination Sub-page
+
+```typescript
+@ComponentV2
+struct DetailPage {
+ build() {
+ NavDestination() {
+ Column() {
+ Text($r('app.string.detail_title'))
+ }
+ }
+ .title($r('app.string.detail_nav_title'))
+ }
+}
+```
+
+## Architecture Pattern: MVVM
+
+Recommended architecture for HarmonyOS applications:
+
+```
+feature/
+ |-- model/ # Data models (@ObservedV2 classes)
+ |-- viewmodel/ # Business logic (ViewModel classes)
+ |-- view/ # UI components (@ComponentV2 structs)
+ |-- service/ # API calls, data access
+```
+
+- **View**: Only rendering logic, no business logic in `build()`
+- **ViewModel**: All business logic encapsulated here
+- **Model**: Pure data classes with `@ObservedV2` and `@Trace`
+- **Service**: Network requests, database operations, file I/O
+
+## ArkUI Animation Patterns
+
+### State-Driven Animation
+
+```typescript
+@ComponentV2
+struct AnimatedCard {
+ @Local isExpanded: boolean = false
+ @Local cardScale: number = 0.8
+
+ build() {
+ Column() {
+ // Content
+ }
+ .scale({ x: this.cardScale, y: this.cardScale })
+ .animation({ duration: 300, curve: Curve.EaseInOut })
+ .onClick(() => {
+ this.isExpanded = !this.isExpanded
+ this.cardScale = this.isExpanded ? 1.0 : 0.8
+ })
+ }
+}
+```
+
+### Animation Rules
+
+- Prefer native HarmonyOS animation APIs and advanced templates
+- Use declarative UI with state-driven animations (change state variables to trigger animations)
+- Set `renderGroup(true)` for complex sub-component animations to reduce render batches
+- **NEVER** frequently change `width`, `height`, `padding`, `margin` during animations - severe performance impact
+- Use `animateTo` for explicit animation control
+- Prefer `transform` (translate, scale, rotate) and `opacity` for performant animations
+
+## Performance Patterns
+
+### LazyForEach for Large Lists
+
+```typescript
+@ComponentV2
+struct LargeList {
+ @Local dataSource: MyDataSource = new MyDataSource()
+
+ build() {
+ List() {
+ LazyForEach(this.dataSource, (item: ItemModel) => {
+ ListItem() {
+ ItemComponent({ item: item })
+ }
+ }, (item: ItemModel) => item.id)
+ }
+ }
+}
+```
+
+### Component Reuse
+
+- Extract reusable components into separate files
+- Use `@Builder` for lightweight UI fragments within a component
+- Use `@Param` for configurable components
+
+## Resource References
+
+Always define UI constants as resources and reference via `$r()`:
+
+```typescript
+// BAD: hardcoded values
+Text('Hello')
+ .fontSize(16)
+ .fontColor('#333333')
+
+// GOOD: resource references
+Text($r('app.string.greeting'))
+ .fontSize($r('app.float.font_size_body'))
+ .fontColor($r('app.color.text_primary'))
+```
diff --git a/rules/arkts/security.md b/rules/arkts/security.md
new file mode 100644
index 000000000..f76717128
--- /dev/null
+++ b/rules/arkts/security.md
@@ -0,0 +1,141 @@
+---
+paths:
+ - "**/*.ets"
+ - "**/*.ts"
+ - "**/module.json5"
+---
+# HarmonyOS / ArkTS Security
+
+> This file extends [common/security.md](../common/security.md) with HarmonyOS-specific security practices.
+
+## Permission Management
+
+### Declare Permissions in module.json5
+
+All system API calls requiring permissions must be declared:
+
+```json5
+{
+ "module": {
+ "requestPermissions": [
+ {
+ "name": "ohos.permission.INTERNET",
+ "reason": "$string:internet_permission_reason",
+ "usedScene": {
+ "abilities": ["EntryAbility"],
+ "when": "always"
+ }
+ }
+ ]
+ }
+}
+```
+
+### Permission Checklist
+
+Before calling system APIs, verify:
+
+- [ ] Permission declared in `module.json5`
+- [ ] Permission reason string defined in resources (for user-facing permissions)
+- [ ] Runtime permission request implemented for sensitive permissions (camera, location, etc.)
+- [ ] Permission check before API call with graceful fallback on denial
+
+### Runtime Permission Request
+
+```typescript
+import { abilityAccessCtrl, bundleManager, Permissions } from '@kit.AbilityKit';
+
+async function checkAndRequestPermission(permission: Permissions): Promise<boolean> {
+ const atManager = abilityAccessCtrl.createAtManager();
+ const bundleInfo = await bundleManager.getBundleInfoForSelf(
+ bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_APPLICATION
+ );
+ const tokenId = bundleInfo.appInfo.accessTokenId;
+ const grantStatus = await atManager.checkAccessToken(tokenId, permission);
+
+ if (grantStatus === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) {
+ return true;
+ }
+
+ const result = await atManager.requestPermissionsFromUser(getContext(), [permission]);
+ return result.authResults[0] === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED;
+}
+```
+
+## Secret Management
+
+- **NEVER** hardcode API keys, tokens, or passwords in `.ets`/`.ts` source files
+- Use HarmonyOS Preferences API for non-sensitive configuration
+- Use HarmonyOS Keystore for sensitive credentials
+- Environment-specific configs should be managed via build profiles
+
+```typescript
+// BAD: hardcoded secret
+const API_KEY: string = 'sk-xxxxxxxxxxxx';
+
+// GOOD: from build profile config (non-sensitive)
+import { BuildProfile } from 'BuildProfile';
+const endpoint = BuildProfile.API_ENDPOINT;
+
+// GOOD: use HUKS to encrypt/decrypt data without exposing key material
+import { huks } from '@kit.UniversalKeystoreKit';
+async function decryptWithKeystore(alias: string, nonce: Uint8Array, aad: Uint8Array, cipherData: Uint8Array): Promise<Uint8Array> {
+ const options: huks.HuksOptions = {
+ properties: [
+ { tag: huks.HuksTag.HUKS_TAG_ALGORITHM, value: huks.HuksKeyAlg.HUKS_ALG_AES },
+ { tag: huks.HuksTag.HUKS_TAG_PURPOSE, value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT },
+ { tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, value: huks.HuksCipherMode.HUKS_MODE_GCM },
+ { tag: huks.HuksTag.HUKS_TAG_PADDING, value: huks.HuksKeyPadding.HUKS_PADDING_NONE },
+ { tag: huks.HuksTag.HUKS_TAG_NONCE, value: nonce },
+ { tag: huks.HuksTag.HUKS_TAG_ASSOCIATED_DATA, value: aad }
+ ],
+ inData: cipherData
+ };
+ const handle = await huks.initSession(alias, options);
+ const result = await huks.finishSession(handle.handle, options);
+ return result.outData;
+}
+```
+
+## Input Validation
+
+- Validate all user input before processing
+- Sanitize data before displaying in UI to prevent injection
+- Validate deep link parameters before navigation
+
+```typescript
+// Validate before navigation
+function handleDeepLink(uri: string): void {
+ const allowedPaths: string[] = ['detail', 'settings', 'profile'];
+ const parsed = new URL(uri);
+ const path = parsed.pathname.replace('/', '');
+
+ if (!allowedPaths.includes(path)) {
+ hilog.warn(0x0000, 'DeepLink', 'Invalid deep link path: %{public}s', path);
+ return;
+ }
+
+ navPathStack.pushPath({ name: path });
+}
+```
+
+## Network Security
+
+- Always use HTTPS for network requests
+- Validate server certificates
+- Implement request timeout and retry policies
+- Never log sensitive data (tokens, user credentials) in network request/response logs
+
+## Data Storage Security
+
+- Use encrypted preferences for sensitive local data
+- Clear sensitive data from memory when no longer needed
+- Implement proper data lifecycle management
+- Consider data classification (public, internal, confidential) when choosing storage mechanisms
+
+## Dependency Security
+
+- Only use dependencies from trusted sources (official ohpm registry)
+- Verify dependency versions in `oh-package.json5`
+- Regularly check for known vulnerabilities in third-party libraries
+- Pin dependency versions to avoid unexpected updates
diff --git a/rules/arkts/testing.md b/rules/arkts/testing.md
new file mode 100644
index 000000000..a32cfa8f2
--- /dev/null
+++ b/rules/arkts/testing.md
@@ -0,0 +1,126 @@
+---
+paths:
+ - "**/*.ets"
+ - "**/*.ts"
+ - "**/ohosTest/**"
+---
+# HarmonyOS / ArkTS Testing
+
+> This file extends [common/testing.md](../common/testing.md) with HarmonyOS-specific testing practices.
+
+## Test Framework
+
+HarmonyOS uses the built-in test framework with `@ohos.test` capabilities:
+
+- **Unit tests**: Located in `src/ohosTest/ets/test/`
+- **UI tests**: Use `@ohos.UiTest` for component testing
+- **Instrument tests**: Run on device/emulator
+
+## Test Directory Structure
+
+```
+module/
+ |-- src/
+ | |-- main/ets/ # Production code
+ | |-- ohosTest/ets/ # Test code
+ | |-- test/
+ | | |-- Ability.test.ets
+ | | |-- List.test.ets
+ | |-- TestAbility.ets
+ | |-- TestRunner.ets
+```
+
+## Running Tests
+
+```bash
+# Run all tests for a module
+hvigorw testHap -p product=default
+
+# Run tests on connected device
+hdc shell aa test -b com.example.app -m entry_test -s unittest /ets/TestRunner/OpenHarmonyTestRunner
+```
+
+## Unit Test Example
+
+```typescript
+import { describe, it, expect } from '@ohos/hypium';
+
+export default function UserViewModelTest() {
+ describe('UserViewModel', () => {
+ it('should_initialize_with_empty_state', 0, () => {
+ const vm = new UserViewModel();
+ expect(vm.userName).assertEqual('');
+ expect(vm.isLoading).assertFalse();
+ });
+
+ it('should_update_user_name', 0, () => {
+ const vm = new UserViewModel();
+ vm.updateUserName('Alice');
+ expect(vm.userName).assertEqual('Alice');
+ });
+
+ it('should_handle_empty_input', 0, () => {
+ const vm = new UserViewModel();
+ vm.updateUserName('');
+ expect(vm.userName).assertEqual('');
+ expect(vm.hasError).assertFalse();
+ });
+ });
+}
+```
+
+## UI Test Example
+
+```typescript
+import { describe, it, expect } from '@ohos/hypium';
+import { Driver, ON } from '@ohos.UiTest';
+
+export default function HomePageUITest() {
+ describe('HomePage_UI', () => {
+ it('should_display_title', 0, async () => {
+ const driver = Driver.create();
+ await driver.delayMs(1000);
+
+ const title = await driver.findComponent(ON.text('Home'));
+ expect(title !== null).assertTrue();
+ });
+
+ it('should_navigate_to_detail_on_click', 0, async () => {
+ const driver = Driver.create();
+ const button = await driver.findComponent(ON.id('detailButton'));
+ await button.click();
+ await driver.delayMs(500);
+
+ const detailTitle = await driver.findComponent(ON.text('Detail'));
+ expect(detailTitle !== null).assertTrue();
+ });
+ });
+}
+```
+
+## TDD Workflow for HarmonyOS
+
+Follow the standard TDD cycle adapted for HarmonyOS:
+
+1. **RED**: Write a failing test in `ohosTest/ets/test/`
+2. **GREEN**: Implement minimal code in `main/ets/` to pass
+3. **REFACTOR**: Clean up while keeping tests green
+4. **BUILD**: Run `hvigorw assembleHap` to verify compilation
+5. **VERIFY**: Run tests on device/emulator
+
+## Test Coverage Requirements
+
+- Minimum 80% coverage for all critical application code (ViewModels, services, utilities)
+- **Unit tests**: All utility functions, ViewModel logic, data models
+- **Integration tests**: API calls, database operations, cross-module interactions
+- **E2E / UI tests**: Critical user flows (login, navigation, data submission)
+- Test edge cases: empty data, network errors, permission denials
+
+## Testing Best Practices
+
+- Keep tests independent - no shared mutable state between tests
+- Mock network calls and system APIs in unit tests
+- Use meaningful test names: `should_[expected_behavior]_when_[condition]`
+- Test V2 state management reactivity: verify `@Trace` properties trigger UI updates
+- Test Navigation flows: verify `NavPathStack` push/pop/replace operations
+- Avoid testing framework internals - focus on business logic and user-visible behavior
diff --git a/rules/common/agents.md b/rules/common/agents.md
index 09d636489..d7dd1be92 100644
--- a/rules/common/agents.md
+++ b/rules/common/agents.md
@@ -16,6 +16,7 @@ Located in `~/.claude/agents/`:
| refactor-cleaner | Dead code cleanup | Code maintenance |
| doc-updater | Documentation | Updating docs |
| rust-reviewer | Rust code review | Rust projects |
+| harmonyos-app-resolver | HarmonyOS app development | HarmonyOS/ArkTS projects |
## Immediate Agent Usage
diff --git a/scripts/lib/install-manifests.js b/scripts/lib/install-manifests.js
index b5623b11c..2b677ce76 100644
--- a/scripts/lib/install-manifests.js
+++ b/scripts/lib/install-manifests.js
@@ -42,6 +42,8 @@ const LEGACY_LANGUAGE_ALIAS_TO_CANONICAL = Object.freeze({
csharp: 'csharp',
go: 'go',
golang: 'go',
+ arkts: 'arkts',
+ harmonyos: 'arkts',
java: 'java',
javascript: 'typescript',
kotlin: 'java',
@@ -57,6 +59,7 @@ const LEGACY_LANGUAGE_EXTRA_MODULE_IDS = Object.freeze({
cpp: ['framework-language'],
csharp: ['framework-language'],
go: ['framework-language'],
+ arkts: ['framework-language'],
java: ['framework-language'],
perl: [],
php: [],