Android-to-HarmonyOS Converter

A Claude Code plugin that converts Android applications to HarmonyOS (OpenHarmony) applications using a multi-agent pipeline. It analyzes Android source code, designs HarmonyOS architecture, converts UI layouts and business logic to ArkTS, builds the project, and validates the result through code review, on-device self-testing, and integration testing.

How to Run

Load the plugin with Claude Code using the --plugin-dir flag:

claude --plugin-dir ./android-harmonyos-converter/ --dangerously-skip-permissions

Once loaded, all /android-harmonyos-converter:* slash commands become available in the Claude Code session.

Overview

The plugin orchestrates specialized AI agents through a sequential pipeline to perform a complete Android-to-HarmonyOS conversion:

 Android Project
       |
       v
 +---------------------+
 | 1. Requirements     |  Analyze Android manifest, source, resources, dependencies
 |    Analysis         |  -> requirements-analysis.md
 +--------+------------+
          v
 +---------------------+
 | 2. Architecture     |  Design HarmonyOS module structure, navigation, state mgmt
 |    Design           |  -> feature.md
 +--------+------------+
          v
 +---------------------+
 | 3. UI Development   |  Convert XML layouts -> ArkUI declarative components (.ets)
 +--------+------------+
          v
 +---------------------+
 | 4. Logic Development|  Wire business logic to UI scaffold (.ets/.ts)
 +--------+------------+
          v
 +---------------------+
 | 5. Build            |  Compile with hvigor, fix errors (up to 5 iterations),
 |                     |  produce .hap package -> build-report.md
 +--------+------------+
          v
 +---------------------+
 | 6. Code Review      |  Validate code against requirements & user scenarios
 |                     |  -> code-review-report.md
 +--------+------------+
          v
 +---------------------+
 | 6a. Review Fix      |  Fix issues found by code review
 |                     |  -> review-fix-report.md
 +--------+------------+
          v
 +---------------------+
 | 6b. Rebuild         |  Rebuild after review fixes
 |                     |  -> review-fix-build-report.md
 +--------+------------+
          v
 +---------------------+
 | 7. Self-Testing     |  On-device verification loop (up to max-rounds)
 |                     |  -> round-N/self-test-report.md
 +--------+------------+
          v
 +---------------------+
 | 7a. Self-Test Fix   |  Fix failures found in the current self-test round
 |                     |  -> round-N/self-test-fix-report.md
 +--------+------------+
          v
 +---------------------+
 | 7b. Rebuild         |  Rebuild after current round fixes
 |                     |  -> round-N/build-fix-report.md
 +--------+------------+
          |  repeat 7→7a→7b until all passed or max-rounds reached
          v
 +---------------------+
 | 8. Integration      |  End-to-end testing of the built app
 |    Testing          |  -> integration-test-report.md
 +---------------------+
          |
          v
   HarmonyOS App (.hap)

Pipeline Stages — Input / Output Reference

#	Stage	Agent	Input	Output
1	Requirements Analysis	requirements-analyst	Android project path	requirements-analysis.md
2	Architecture Design	architecture-designer	requirements-analysis.md, HarmonyOS project path	plan.md
3	UI Development	ui-developer	plan.md, Android project path	ArkTS UI files in HarmonyOS project, ui-dev-summary.md
4	Logic Context Builder	logic-context-builder	HarmonyOS project path, plan.md, output path, plugin path	logic/plan.md decision contract
4a	Logic Coding	logic-coding	HarmonyOS project path, logic/plan.md, output path, plugin path	.ets/.ts logic changes, logic/commit-info.md, optional logic/issues.md
5	Compilation and Build	build-fixer	HarmonyOS project path, output path, --signed	build-fix-report.md, entry-default-signed.hap
6	Code Review	code-reviewer	HarmonyOS project path, commit ID from commit-info.md, test_case.md, output path	code-review-report.md
6a	Review Fix	review-fixer	code-review-report.md, HarmonyOS project path, Android project path, output path	review-fix-report.md
6b	Rebuild after Review Fix	build-fixer	HarmonyOS project path, output path, --signed	build-fix-report.md (overwritten), entry-default-signed.hap (replaced)
7	Self-Testing	self-tester	.hap file path, test_case.md, output path, harmonyos-project-path, use-auto-test=true	round-N/self-test-report.md, final self-test-report.md
7a	Self-Test Fix	self-test-fixer	round-N/self-test-report.md, HarmonyOS project path, Android project path, round output path	round-N/self-test-fix-report.md, final self-test-fix-report.md
7b	Rebuild after Self-Test Fix	build-fixer	HarmonyOS project path, round output path, --signed	round-N/build-fix-report.md, round-N/entry-default-signed.hap, final root-level mirrored outputs
8	Integration Testing	integration-tester	HarmonyOS project path, .hap file path	integration-test-report.md

All output files are written to the <assets-output-path> directory. Stage 7 uses per-round subdirectories (round-N/) to preserve history, then mirrors the final round's key outputs back to the root output directory using the canonical filenames. The pipeline also maintains pipeline-manifest.md as a cumulative progress log updated after every stage and every Stage 7 loop round.

Requirements

• Claude Code CLI installed
• DevEco Studio (provides Node.js, hvigor build tool, and HarmonyOS SDK)
• HarmonyOS SDK (API 12+ / HarmonyOS 5.0+)
• An existing Android project to convert
• A target HarmonyOS project directory (for build stages)
• A HarmonyOS device connected via hdc (for self-testing stages)

Quick Start

1. Launch the Plugin

claude --plugin-dir ./android-harmonyos-converter/ --dangerously-skip-permissions

2. Setup

Configure tool paths (Node.js, HarmonyOS SDK, Python, Java):

/android-harmonyos-converter:setup

This writes a converter-config.json in the plugin's .claude-plugin/ directory. You can skip any path to use auto-detection.

3. Run the Full Pipeline

Convert an entire Android app in one command:

/android-harmonyos-converter:dev_pipeline <android-project-path> <harmonyos-project-path> <assets-output-path> [skip] [max-rounds]

Parameters:

Parameter	Required	Description
android-project-path	Yes	Path to the Android source project
harmonyos-project-path	Yes	Path to the target HarmonyOS project directory
assets-output-path	Yes	Directory to store all output/report files
skip	No	true to skip non-essential stages (see Skip Mode below)
max-rounds	No	Maximum number of Stage 7→7a→7b rounds to run. Default 2. Must be passed as the 5th positional argument, e.g. false 3.

Example:

/android-harmonyos-converter:dev_pipeline D:\projects\my-android-app D:\projects\my-harmonyos-app D:\projects\output

4. Run Individual Stages

Each pipeline stage is also available as a standalone command for single-step debugging and development. <> denotes required arguments, [] denotes optional arguments.

Command	Arguments
requirements-analysis	<android-project-path> [output-path]
architecture-design	<requirements-analysis.md-path> [output-path]
ui-dev	<feature.md-path> <android-project-path> [output-path]
logic-dev	<harmonyos-project-path> <output-path> <feature-md> [requirement-md]
build	<harmonyos-project-path> [output-path]
code-review	<harmonyos-project-path> <commit-id> <output-path> [requirements-doc-path] [feature-doc-path]
fix	<bug-report-or-project-path> [harmonyos-project-path] [output-path] [--android-src <path>] [--signed]
self-test	<hap-path> <output-path> [test-case-path]
integration-test	<harmonyos-project-path> [output-path]
dev_pipeline	<android-project-path> <harmonyos-project-path> <assets-output-path> [skip] [max-rounds]
setup	(no arguments — interactive)

All commands are prefixed with /android-harmonyos-converter:. For example:

/android-harmonyos-converter:requirements-analysis D:\projects\my-android-app D:\projects\output

When [output-path] is omitted, a timestamped folder is created automatically under the plugin root.

Agents

The plugin includes specialized agents, each responsible for one or more pipeline stages:

Agent	Role	Key Output
requirements-analyst
architecture-designer
ui-developer
logic-context-builder	Reads the feature contract and project evidence, then writes a short executable logic decision contract.	logic/plan.md
logic-coding	Executes the narrowed logic contract, verifies local/project/platform facts, patches scoped code, validates, and commits.	.ets/.ts logic files, logic/commit-info.md, optional logic/issues.md
logic-context-builder-minimal	Baseline planner variant for A/B evaluation.	logic/plan.md
logic-coding-minimal	Baseline coder variant for A/B evaluation.	.ets/.ts logic files, logic/commit-info.md
build-engineer	DEPRECATED — use build-fixer instead.	—
build-fixer	Resolves build environment, compiles the project, auto-fixes compilation errors (up to 20 iterations), produces .hap, copies to output directory. Supports --signed for signed builds.	build-fix-report.md, .hap
code-reviewer	Validates code against requirement descriptions and user scenarios. Assigns per-scenario verdicts (PASS/PARTIAL/FAIL).	code-review-report.md
review-fixer	Verifies each issue from the code review report before fixing, references Android source for correct behavior.	review-fix-report.md
self-tester	Verifies device connectivity, installs HAP, runs test cases from test_case.md using AutoTest mode, and writes one report per Stage 7 round.	round-N/self-test-report.md, final self-test-report.md
self-test-fixer	Reads the current round self-test report, white-box verifies failures in HarmonyOS code, plans and executes fixes in order.	round-N/self-test-fix-report.md, final self-test-fix-report.md
integration-tester

Skip Mode

For projects that already have UI scaffold code and only need logic wiring, build, review, and testing:

/android-harmonyos-converter:dev_pipeline <android-path> <harmonyos-path> <output-path> true [max-rounds]

When skip=true, only these stages are executed:

• Stage 4 — Logic Development
• Stage 5 — Compilation and Build
• Stage 6 — Code Review
• Stage 6a — Review Fix
• Stage 6b — Rebuild after Review Fix

Skipped stages (1 Requirements Analysis, 2 Architecture Design, 3 UI Development, 7 Self-Testing, 7a Self-Test Fix, 7b Rebuild after Self-Test Fix, 8 Integration Testing) are marked as "Skipped (skip=true)" without launching their agents. In skip mode, max-rounds is parsed but unused because the Stage 7 loop is not entered.

Output Structure

All reports and artifacts are saved to the output directory:

<assets-output-path>/
+-- pipeline-manifest.md          # Cumulative progress log
+-- logic/
|   +-- plan.md                   # Stage 4 logic decision contract
|   +-- commit-info.md            # Stage 4a logic commit ID
|   +-- issues.md                 # Stage 4a blockers, if any
+-- commit-info.md                # Root mirror of Stage 4a commit ID
+-- build-fix-report.md           # Latest root-level build report (Stage 5 / 6b / final 7b)
+-- entry-default-signed.hap      # Final promoted package (if successful)
+-- code-review-report.md         # Stage 6 output
+-- review-fix-report.md          # Stage 6a output
+-- test_case.md                  # Test case descriptions
+-- self-test-report.md           # Final round Stage 7 output (mirrored from round-N/)
+-- self-test-fix-report.md       # Final round Stage 7a output (mirrored from round-N/)
+-- round-1/
|   +-- self-test-report.md
|   +-- self-test-fix-report.md
|   +-- build-fix-report.md
|   +-- entry-default-signed.hap
|   +-- screenshots/
+-- round-2/
|   +-- self-test-report.md
|   +-- self-test-fix-report.md
|   +-- build-fix-report.md
|   +-- entry-default-signed.hap
|   +-- screenshots/
+-- ...

The round-N/ directories preserve each Stage 7 loop round. The final completed round is also mirrored back to the root output directory using the canonical filenames for backward compatibility with Stage 8 and external consumers.

Build Environment

The build agent resolves tools in this order:

1. Plugin config — reads converter-config.json for explicit paths (deveco_studio_path, node_path)
2. DevEco Studio bundled tools — derives Node.js and hvigor from the DevEco Studio installation
3. Auto-detection — searches common install locations and environment variables (OHOS_SDK_HOME, HVIGOR_HOME, PATH)

If auto-detection fails, run /android-harmonyos-converter:setup to configure paths manually.

The build requires DEVECO_SDK_HOME to be set to the DevEco Studio installation root.

Plugin Structure

android-harmonyos-converter/
+-- .claude-plugin/
|   +-- plugin.json               # Plugin metadata (name, version, author)
|   +-- converter-config.json     # Tool path configuration
+-- agents/
|   +-- requirements-analyst.md   # Requirements analysis agent
|   +-- architecture-designer.md  # Architecture design agent
|   +-- ui-developer.md           # UI conversion agent
|   +-- logic-context-builder.md  # Logic planning agent
|   +-- logic-coding.md           # Logic implementation agent
|   +-- logic-context-builder-minimal.md # Baseline logic planning agent
|   +-- logic-coding-minimal.md   # Baseline logic implementation agent
|   +-- build-engineer.md         # DEPRECATED — use build-fixer
|   +-- build-fixer.md            # Build-fix loop agent
|   +-- code-reviewer.md          # Code review agent
|   +-- review-fixer.md           # Review fix agent
|   +-- self-tester.md            # On-device testing agent
|   +-- self-test-fixer.md        # Self-test fix agent
|   +-- integration-tester.md     # Integration testing agent
+-- commands/
|   +-- dev_pipeline.md           # Full pipeline command
|   +-- setup.md                  # Tool path configuration command
|   +-- requirements-analysis.md  # Individual stage commands
|   +-- architecture-design.md
|   +-- ui-dev.md
|   +-- logic-dev.md
|   +-- build.md
|   +-- code-review.md
|   +-- self-test.md
|   +-- fix.md
|   +-- integration-test.md
+-- tools/                        # Supporting tools (code review scripts, auto-test, etc.)
+-- README.md

How to Add a New Agent

Follow these three steps to extend the plugin with a new agent.

Step 1: Implement the Agent

Create a new Markdown file in the agents/ directory (e.g., agents/my-new-agent.md).

The agent file defines the agent's role, capabilities, and instructions. It uses frontmatter for metadata:

---
description: Short description of what the agent does
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - Agent
---

# My New Agent

You are the my-new-agent. Your role is to ...

## Instructions

1. Read input files ...
2. Process ...
3. Write output to `<output-path>/my-output.md`

Step 2: Implement a Command for Single-Step Debugging

Create a corresponding command file in the commands/ directory (e.g., commands/my-new-command.md).

Important: Keep the command arguments consistent with the agent's expected inputs, so the command can directly pass arguments through to the agent.

---
description: Short description of the command
argument-hint: <required-arg> [optional-arg]
---

# My New Command

**Raw arguments**: $ARGUMENTS

## Argument Parsing

Parse `$ARGUMENTS` as space-separated values:
- **Arg 1** (`required-arg`): Description (required)
- **Arg 2** (`optional-arg`): Description (optional)

If `optional-arg` is not provided, use a default value or create a timestamped folder.

## Instructions

1. Ensure the output directory exists.
2. Launch the **my-new-agent** agent with the parsed arguments.
3. Tell the user where the output was saved.

This command allows you to run and debug the agent independently via:

/android-harmonyos-converter:my-new-command <required-arg> [optional-arg]

Step 3: Add the Agent to the Pipeline (If Necessary)

If the new agent should be part of the automated pipeline, edit commands/dev_pipeline.md:

1. Add a new stage in the Pipeline Execution section at the appropriate position.
2. Add a task entry in the Progress Tracking table so it shows up in the task list.
3. Wire dependencies — ensure the new stage receives outputs from previous stages and passes its outputs to subsequent stages.
4. Handle skip mode — if the stage should be skippable, add skip-aware logic.
5. Update the README — add the new command to the command reference and the new agent to the agents table.

Author

Huawei

Version

1.0.0