fix: move skill directories to repo root and update AGENTS.md structure diagram

AGENTS.md

@@ -1,65 +1,69 @@
 # AGENTS.md - OpenCode Skills Repository
 
-This repository contains AI coding agent skills for HarmonyOS/ArkTS development. Skills teach AI assistants how to build, deploy, and develop HarmonyOS applications.
+AI coding agent skills for HarmonyOS/ArkTS development. This is a **documentation-only** repo -- no build system for the repo itself. The skills teach agents how to build, deploy, and develop HarmonyOS apps.
 
 ## Repository Structure
 
 ```
-skills/
+arkts-development/              # ArkTS/ArkUI development skill
-├── arkts-development/          # ArkTS/ArkUI development skill
+├── SKILL.md                   # Main skill definition (loaded by agent)
-│   ├── SKILL.md               # Main skill definition
+├── assets/*.ets               # Code templates
-│   ├── assets/                # Code templates (.ets files)
+└── references/*.md            # API docs, migration guide, patterns
-│   └── references/            # API docs, migration guide, patterns
+harmonyos-build-deploy/         # Build & deploy skill
-└── harmonyos-build-deploy/    # Build & deploy skill
+├── SKILL.md                   # Main skill definition (loaded by agent)
-    ├── SKILL.md               # Main skill definition
+└── references/*.md            # Device installation guide
-    └── references/            # Device installation guide
 ```
 
-## Build/Lint/Test Commands
+## Build / Lint / Test Commands
 
-This is a documentation repository - no build system for the repo itself. However, the skills document these HarmonyOS CLI tools:
+These commands apply to **HarmonyOS projects** that the skills describe, not this repo.
 
-### Build Commands (hvigorw)
+### Build (hvigorw)
 
 ```bash
-# Incremental build (default for development)
+hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon  # Full app
-hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon
+hvigorw assembleHap -p module=entry@default --mode module -p buildMode=release --no-daemon  # Single module (faster)
-
+hvigorw clean --no-daemon                                                                # Clean artifacts
-# Clean build
+hvigorw --sync -p product=default -p buildMode=release --no-daemon                       # Sync after config change
-hvigorw clean --no-daemon
-hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon
-
-# Build single module (faster iteration)
-hvigorw assembleHap -p module=entry@default --mode module -p buildMode=release --no-daemon
-
-# Run tests
-hvigorw onDeviceTest -p module=entry -p coverage=true    # On-device test
-hvigorw test -p module=entry                              # Local test
 ```
 
-### Package Manager (ohpm)
+### Test
 
 ```bash
-ohpm install --all              # Install all dependencies
+# Run all tests for a module (on-device)
+hvigorw onDeviceTest -p module=entry -p coverage=true --no-daemon
+
+# Run all tests for a module (local / host-side)
+hvigorw test -p module=entry --no-daemon
+
+# Run a single test suite or single test (on-device) -- use -p testParam
+hvigorw onDeviceTest -p module=entry -p testParam="{\"unittest\":\"TestClassName\"}" --no-daemon
+hvigorw onDeviceTest -p module=entry -p testParam="{\"unittest\":\"TestClassName#testMethodName\"}" --no-daemon
+```
+
+### Dependencies (ohpm)
+
+```bash
+ohpm install --all                           # Install all deps
 ohpm clean && ohpm cache clean               # Deep clean
 ```
 
-### Code Linter (codelinter)
+### Lint (codelinter)
 
 ```bash
-codelinter                      # Check current project
+codelinter                                   # Check project
-codelinter --fix                # Check and auto-fix
+codelinter --fix                             # Auto-fix
-codelinter -f json -o report.json  # JSON output
+codelinter -i                                # Incremental (git changes only)
-codelinter -i                   # Incremental (Git changes only)
+codelinter --exit-on error,warn              # CI mode (non-zero exit on issues)
-codelinter --exit-on error,warn # CI/CD with exit codes
+codelinter -f json -o report.json            # JSON report
 ```
 
-### Device Commands (hdc)
+### Device (hdc)
 
 ```bash
 hdc list targets                                        # List devices (returns UDID)
-hdc -t <UDID> file send <local> <remote>  # Push files
+hdc -t <UDID> file send <local_path> <device_path>     # Push files
-hdc -t <UDID> shell "bm install -p <path>" # Install app
+hdc -t <UDID> shell "bm install -p <dir>"              # Install app
 hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"  # Launch app
 ```
 
@@ -67,49 +71,56 @@ hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>" # Launch app
 
 ### ArkTS Language Constraints
 
-ArkTS is stricter than TypeScript. These are prohibited:
+ArkTS is stricter than TypeScript. These features are **prohibited**:
 
 | Prohibited              | Use Instead                        |
-|------------|-------------|
+|-------------------------|------------------------------------|
 | `any`, `unknown`        | Explicit types, interfaces         |
 | `var`                   | `let`, `const`                     |
-| Dynamic property `obj['key']` | Fixed object structure |
+| `obj['key']` (dynamic)  | Fixed object structure             |
-| `for...in`, `delete`, `with` | `for...of`, array methods |
+| `for...in`              | `for...of`, array methods          |
+| `delete`, `with`        | Optional properties, explicit refs |
 | `#privateField`         | `private` keyword                  |
-| Structural typing | Explicit `implements`/`extends` |
+| Structural typing       | Explicit `implements` / `extends`  |
+| `eval()`, `Function()`  | Arrow functions, static code       |
 
 ### Naming Conventions
 
 | Element               | Convention      | Example                     |
-|---------|------------|---------|
+|-----------------------|-----------------|-----------------------------|
 | Components (struct)   | PascalCase      | `HomePage`, `UserCard`      |
-| Methods | camelCase | `loadData()`, `handleClick()` |
-| Properties/Variables | camelCase | `isLoading`, `userName` |
 | Interfaces            | PascalCase      | `UserInfo`, `ApiResponse`   |
+| Methods / Functions   | camelCase       | `loadData()`, `handleClick` |
+| Properties / Variables| camelCase       | `isLoading`, `userName`     |
 | Constants             | camelCase or UPPER_SNAKE | `maxRetries`, `API_URL` |
-| Files (skill docs) | kebab-case | `api-reference.md` |
 | Skill directories     | kebab-case      | `arkts-development`         |
+| Filenames (docs)      | kebab-case      | `api-reference.md`          |
 
 ### Type Annotations
 
-Always use explicit type annotations:
+Always use **explicit** type annotations on declarations, parameters, and return types:
 
 ```typescript
-// Required: Explicit types on declarations
 @State isLoading: boolean = false;
 @State items: ItemType[] = [];
-
-// Required: Return types on methods
 async loadData(): Promise<void> { }
 navigateToDetail(item: ItemType): void { }
-
-// Required: Parameter types
 ForEach(this.items, (item: ItemType) => { ... }, (item: ItemType) => item.id)
 ```
 
+### Imports
+
+Use HarmonyOS Kit-style imports:
+
+```typescript
+import { router } from '@kit.ArkUI';
+import { http } from '@kit.NetworkKit';
+import { preferences } from '@kit.ArkData';
+```
+
 ### Component Structure
 
-Follow this standard component layout:
+Follow this ordering inside every `@Component` struct:
 
 ```typescript
 @Entry
@@ -118,23 +129,21 @@ struct ComponentName {
   // 1. State decorators
   @State isLoading: boolean = false;
   @State errorMessage: string = '';
-
+  // 2. Lifecycle
-  // 2. Lifecycle methods
   aboutToAppear(): void { this.loadData(); }
   aboutToDisappear(): void { /* cleanup */ }
-
   // 3. Business methods
   async loadData(): Promise<void> { }
-
+  // 4. @Builder methods (reusable UI blocks)
-  // 4. Builder methods (reusable UI blocks)
   @Builder ItemCard(item: ItemType) { }
-
+  // 5. build() -- always last
-  // 5. Build method (always last)
   build() { }
 }
 ```
 
-### Error Handling Pattern
+### Error Handling
+
+Wrap async work in try/catch/finally with loading state:
 
 ```typescript
 async loadData(): Promise<void> {
@@ -149,81 +158,40 @@ async loadData(): Promise<void> {
 }
 ```
 
-### Import Style
+### ForEach -- always provide types and a key generator
-
-Use HarmonyOS Kit imports:
-
-```typescript
-import { router } from '@kit.ArkUI';
-import { http } from '@kit.NetworkKit';
-import { preferences } from '@kit.ArkData';
-```
-
-## Skill File Format
-
-Each skill follows this structure:
-
-```markdown
----
-name: skill-name
-description: Detailed description for AI agent matching
----
-
-# Skill Title
-
-## Quick Start / Quick Reference
-## Main Content Sections
-## Troubleshooting
-## Reference Files
-```
-
-### YAML Frontmatter
-
-Required fields:
-- `name`: kebab-case identifier matching directory name
-- `description`: Detailed description for AI agent matching (trigger keywords)
-
-## Documentation Conventions
-
-- Use tables for command references and parameters
-- Include code blocks with language specifiers (`typescript`, `bash`)
-- Cross-reference related skills and reference files
-- Use bilingual content (Chinese/English) for HarmonyOS context
-- Structure: Quick Reference first, then detailed sections
-
-## File Organization
-
-- Main skill definition: `SKILL.md` (uppercase)
-- Code templates: `assets/*.ets`
-- Reference documentation: `references/*.md`
-- All filenames: kebab-case
-
-## Common Patterns
-
-### State Management Decorators
-
-| Decorator | Direction | Usage |
-|-----------|-----------|-------|
-| `@State` | Internal | Component's own mutable state |
-| `@Prop` | Parent → Child | One-way binding (child copy) |
-| `@Link` | Parent ↔ Child | Two-way binding (pass with `$var`) |
-| `@Provide/@Consume` | Ancestor → Descendant | Cross-level state sharing |
-
-### Layout Components
-
-```typescript
-Column({ space: 10 }) { }  // Vertical layout
-Row({ space: 10 }) { }     // Horizontal layout
-Stack() { }                 // Overlay layout
-List({ space: 10 }) { }    // Scrollable list
-```
-
-### ForEach Pattern
-
-Always provide explicit types and key generator:
 
 ```typescript
 ForEach(this.items, (item: ItemType) => {
   ListItem() { Text(item.title) }
-}, (item: ItemType) => item.id)  // Key generator for efficient updates
+}, (item: ItemType) => item.id)
 ```
+
+## Skill File Format
+
+Every skill directory contains a `SKILL.md` with YAML frontmatter:
+
+```markdown
+---
+name: skill-name          # kebab-case, matches directory name
+description: ...          # Detailed description for agent matching
+---
+# Skill Title
+## Quick Start / Quick Reference
+## Detailed Sections
+## Troubleshooting
+## Reference Files
+```
+
+### File Organization Rules
+
+- Main definition: `SKILL.md` (uppercase)
+- Code templates: `assets/*.ets`
+- Reference docs: `references/*.md`
+- All filenames: **kebab-case**
+
+## Documentation Conventions
+
+- Use **tables** for command references and parameter lists.
+- Use **fenced code blocks** with language specifiers (`typescript`, `bash`).
+- Structure content as: Quick Reference first, then detailed sections.
+- Cross-reference related skills and reference files by relative path.