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.jsonindex 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.jsonindex 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.mdindex 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 subagentsskills/ — 208 workflow skills and domain knowledgecommands/ — 72 slash commandshooks/ — Trigger-based automationsdiff --git a/README.md b/README.mdindex 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 yourcp -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 toolsswift/ # Swift specific patterns and toolsphp/ # 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.mdindex 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.mdnew file mode 100644index 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.mdindex 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.mdindex 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.mdnew file mode 100644index 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 mergediff --git a/manifests/install-components.json b/manifests/install-components.jsonindex 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.mdindex 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/golangcp -r rules/web ~/.claude/rules/webcp -r rules/swift ~/.claude/rules/swiftcp -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.mdnew file mode 100644index 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.mdnew file mode 100644index 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 resourcesdiff --git a/rules/arkts/patterns.md b/rules/arkts/patterns.mdnew file mode 100644index 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.mdnew file mode 100644index 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 updatesdiff --git a/rules/arkts/testing.md b/rules/arkts/testing.mdnew file mode 100644index 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 behaviordiff --git a/rules/common/agents.md b/rules/common/agents.mdindex 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 Usagediff --git a/scripts/lib/install-manifests.js b/scripts/lib/install-manifests.jsindex 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: [],