Mobile Engineering Harness

AI coding harness cho các sản phẩm Android / Compose Multiplatform tuân theo concept Clean Architecture + SOLID + MVI + Compose + Coroutines.

Harness biến AI agent (Claude Code, Codex, CLI agent khác) từ "generic coder" thành "senior-aware coder" nhận biết chuẩn kiến trúc + convention + verification gate của bạn — không phải nhắc lại rule mỗi task.

Current version: v0.6.0 — 68 files upstream, 11 skills, 5 workflows, 5 blueprints, 4 agent roles, 11 knowledge files, 3-tool verification stack (Konsist + Detekt + Lint), 5 eval scenarios + rubrics + regression tracking.

Install

One-liner

curl -fsSL https://raw.githubusercontent.com/huypqapero/mobile-engineering-harness/main/bootstrap.sh | bash

Script tự:

Clone upstream vào ~/.mobile-engineering-harness/
Symlink CLI thành mehcli ở ~/.local/bin/
Check prerequisites (git, python3, PyYAML)
Warn nếu PATH chưa chứa ~/.local/bin

Quick start cho product mới (3 lệnh)

# 1. Scaffold overlay trong project Android
mehcli init --project /path/to/your/android-project

# 2. Edit .harness-overlay/overlay.yaml — điền vars product (xem overlay.schema.yaml)

# 3. Render templates + create manifest
mehcli install --overlay /path/to/your/android-project/.harness-overlay

Setup time ~15 phút.

Alternative: skill-based onboarding qua Claude Code

Nếu dùng Claude Code, consumer có thể gọi skill harness-init thay vì mehcli init:

/harness-init

Skill tự:

Scout settings.gradle.kts + libs.versions.toml → auto-detect stack.
Hỏi 3 branding key (PRODUCT_NAME, THEME_PREFIX, THEME_CLASS).
Render .harness-overlay/overlay.yaml + validate schema.
Install 21 skills + 11 agents vào project-local ./.claude/.
Install SessionStart hook check overlay existence.

Uninstall / offboarding

Khi deprecate harness khỏi product repo:

# Remove skills + agents + hook, giữ overlay
.harness-overlay/upstream/scripts/uninstall-all.sh --target .

# Full teardown: thêm xóa .harness-overlay/
.harness-overlay/upstream/scripts/uninstall-all.sh --target . --purge

mehcli uninstall --overlay <path> chỉ remove rendered templates, không touch Claude Code symlink hoặc hook — dùng uninstall-all.sh cho full teardown.

Install + run luôn (1 lệnh)

curl -fsSL https://raw.githubusercontent.com/huypqapero/mobile-engineering-harness/main/bootstrap.sh | bash -s init --project .

Env vars cho bootstrap

Var	Default	Khi dùng
`MEH_INSTALL_DIR`	`$HOME/.mobile-engineering-harness`	Custom install location
`MEH_BIN_DIR`	`$HOME/.local/bin`	Prefer `/usr/local/bin` (cần sudo)
`MEH_REF`	`main`	Pin version: `MEH_REF=v0.6.0 curl ... \| bash`

Update to latest

Workflow cập nhật harness lên version mới nhất trong product repo đang consume harness.

Prerequisites

Product repo đã có .harness-overlay/overlay.yaml (từ mehcli init).
Upstream location đã install qua bootstrap.sh (symlink) hoặc git submodule.

Workflow (symlink mode — default bootstrap.sh)

# 1. Check version đang pin
mehcli version
# → commit <hash>, tag <v0.X.Y>

# 2. Fetch latest upstream (git pull --ff-only)
mehcli self-update
# → "Updated: <old-hash> → <new-hash>" hoặc "Already up to date"

# 3. Re-render templates với latest upstream + overlay.yaml hiện tại
mehcli update --overlay .harness-overlay

# 4. Review diff trong product repo
cd /path/to/product
git diff .harness-overlay/

# 5. Smoke verify
./gradlew konsistTest detekt

# 6. Commit overlay delta
git add .harness-overlay/
git commit -m "chore: update harness to v0.X.Y"

Workflow (submodule mode — CI pin)

Thay step 2 bằng:

# Pull submodule tới latest main (hoặc checkout specific tag)
git -C .harness-overlay/upstream fetch --tags
git -C .harness-overlay/upstream checkout v0.14.0   # pin cụ thể
# hoặc
git submodule update --remote .harness-overlay/upstream   # follow tracked branch

# Rồi step 3 trở đi giữ nguyên
mehcli update --overlay .harness-overlay

Rollback

Nếu update broken, revert về version trước:

# Symlink mode: checkout tag cũ trong upstream clone
cd $(dirname $(readlink .harness-overlay/upstream))
git checkout v0.12.0   # version cũ ổn định
cd -
mehcli update --overlay .harness-overlay

# Submodule mode: checkout tag cũ + commit submodule pointer
git -C .harness-overlay/upstream checkout v0.12.0
git add .harness-overlay/upstream
git commit -m "chore: rollback harness to v0.12.0"
mehcli update --overlay .harness-overlay

Breaking change check

Trước khi update qua major/minor bump:

Đọc CHANGELOG.md entry của version mới (section "Migration" nếu có).
Kiểm overlay.yaml còn match schema mới không (mehcli install sẽ fail nếu required field missing).
Nếu CHANGELOG ghi "zero breaking change" (v0.13 → v0.14): update an toàn.
Nếu có breaking: review migration guide trước, apply overlay.yaml adjustments, rồi mới mehcli update.

Pin strategy cho CI

Development product repo: MEH_REF=main + mehcli self-update khi cần.
Production CI: pin tag cụ thể (MEH_REF=v0.14.0) để build reproducible; update tag theo release schedule.
Multi-product org: 1 team maintain upstream clone shared (MEH_INSTALL_DIR=/opt/harness), từng product self-update independently.

AI Harness là gì

Vấn đề

AI coding agent (Claude Code, Codex) có kiến thức generic về Android/Kotlin. Nhưng khi làm việc trong 1 codebase thực tế:

Mỗi task phải nhắc lại architecture (Clean Arch? MVVM? MVI? Which flavor?)
Mỗi task phải nhắc lại convention (naming, module structure, DI framework)
Mỗi task phải nhắc lại verification (Konsist? Detekt? CI gates nào?)
AI quên rule giữa chừng → vi phạm architecture dù "đồng ý" ở prompt
Không có cách enforce automatic: rule chỉ là text, không block code

Giải pháp — Harness 5 layer

┌──────────────────────────────────────────────────────────────┐
│                       AI AGENT                                │
│         (Claude Code / Codex / CLI agent)                     │
└──────────────────────────────────────────────────────────────┘
                            ▼
┌──────────────────────────────────────────────────────────────┐
│  LAYER 1 — CONSTITUTION (luật bắt buộc)                       │
│  MUST / SHOULD / FORBIDDEN rules với verification method      │
│  constitution/{architecture, concurrency, kotlin, dod}.md     │
└──────────────────────────────────────────────────────────────┘
                            ▼
┌──────────────────────────────────────────────────────────────┐
│  LAYER 2 — KNOWLEDGE (kiến thức nền)                          │
│  Essentials per domain, link-first, không duplicate Google    │
│  knowledge/{architecture, compose, mvi, coroutines, data,     │
│             patterns, security, performance}/*.md             │
└──────────────────────────────────────────────────────────────┘
                            ▼
┌──────────────────────────────────────────────────────────────┐
│  LAYER 3 — SKILLS (procedures per task type)                  │
│  Trigger + Prerequisites + Steps + Validation + Anti-patterns │
│  skills/android-{feature,compose,mvi,coroutines,network,...}  │
└──────────────────────────────────────────────────────────────┘
                            ▼
┌──────────────────────────────────────────────────────────────┐
│  LAYER 4 — WORKFLOWS + AGENT ROLES (orchestration)            │
│  State machine: inspect → plan → implement → verify → report  │
│  workflows/*.md + agents/{architect,implementer,reviewer,...} │
└──────────────────────────────────────────────────────────────┘
                            ▼
┌──────────────────────────────────────────────────────────────┐
│  LAYER 5 — VERIFICATION (automatic enforcement)               │
│  Konsist (architecture) + Detekt (code) + Lint (platform)     │
│  verification/{architecture-tests,detekt,lint,scripts}/        │
└──────────────────────────────────────────────────────────────┘
                            ▼
┌──────────────────────────────────────────────────────────────┐
│  LAYER 6 — EVALUATION (feedback)                              │
│  Scenario templates + rubrics + regression tracking           │
│  evaluations/{templates,rubrics,regression}/                  │
└──────────────────────────────────────────────────────────────┘

Nguyên tắc thiết kế

Opinionated but configurable — chuẩn kỹ thuật rõ ràng, cho phép product customize qua overlay
Progressive disclosure — không load toàn bộ context mỗi task; agent khám phá skill + knowledge theo nhu cầu
Convention over configuration — default sẵn, agent không reinvent mỗi task
Verification over instruction — rule có cách enforce (Konsist/Detekt), không chỉ là text
Minimal sufficient architecture — không tạo abstraction nếu chưa có lý do (YAGNI)
Reproducibility — cùng request + cùng config → implementation kiến trúc nhất quán
Evidence-based completion — không claim DONE khi chưa compile/test/verify

Kiến trúc 2-layer

Harness tổ chức theo 2 tầng:

Upstream (generic, shared)

Repo này — chứa content generic parameterized bằng {{VARS}}. 1 source of truth cho rule + skill + workflow.

Install location: ~/.mobile-engineering-harness/

Overlay (product-specific)

Mỗi product có .harness-overlay/ chứa:

overlay.yaml — vars (package, module names, theme, SDK dùng)
upstream → symlink hoặc submodule tới upstream repo
constitution/product-extensions.md [KB → develop/constitution, kb_search "product extensions"] — rules đặc thù product
blueprints/live-reference-feature.md — pointer tới live feature làm reference
Rendered files: Konsist test, verify.sh, harness.yaml (từ templates)
.manifest.yaml — track rendered files (clean install/uninstall)

DRY ratio

Upstream carries ~78% content (reusable across products). Overlay chỉ ~22% product-specific.

Product A overlay (22%)  ──┐
Product B overlay (22%)  ──┼──→  Upstream (78%)
Product C overlay (22%)  ──┘

Current state

Breakdown v0.6.0

Component	Count	Files
Constitution	5 files	architecture-rules, concurrency-rules, kotlin-conventions, engineering-principles, definition-of-done
Knowledge	11 files / 7 domains	architecture, compose, mvi, coroutines, data (4 files), patterns, security, performance
Skills	11 skills	feature, compose, mvi, coroutines, network, database, refactor, debug, performance, code-review, testing
Blueprints	5 patterns	reference-feature, network-service, compose-screen, repository, usecase
Workflows	5 workflows	feature-development, fix-bug, review-pull-request, refactor-module, release-validation
Agent roles	14 agents (3 layer)	product (product-analyst, project-manager, designer, design-analyst), engineering (tech-lead, architect, coder, reviewer, qa + e2e-author/ui-judge subagent), meta (orchestrator, lesson-miner, harness-guardian)
Agent workflows	5 routing docs	feature-full-flow, bugfix-fast-path, bug-triage, release-gate, parallel-features
Verification	3 tools	Konsist (template), Detekt (config + custom rule scaffold), Android Lint (scaffold)
Evaluations	5 scenarios + rubrics + regression	E01-E05 + shared rubric + trend tracking

Structure

mobile-engineering-harness/
├── README.md                        ← bạn đang đọc
├── AGENTS.md                        ← entry point generic cho AI
├── CLAUDE.md                        ← short entry cho Claude Code
├── CHANGELOG.md
├── harness.yaml.template            ← config template
├── install.sh                       ← CLI (symlink thành `mehcli`)
├── bootstrap.sh                     ← one-liner installer
├── overlay.schema.yaml              ← schema cho overlay.yaml
│
├── constitution/                    ← Layer 1: luật
├── knowledge/                       ← Layer 2: kiến thức
├── skills/                          ← Layer 3: procedures
├── workflows/                       ← Layer 4: orchestration
├── agents/                          ← Layer 4: role prompts
├── verification/                    ← Layer 5: enforcement
├── blueprints/                      ← Golden implementations
└── evaluations/                     ← Layer 6: feedback

Best practices

Khi dùng harness

DO

Install qua bootstrap.sh — managed update + consistent location
Pin version cho CI (MEH_REF=v0.6.0) để reproducible builds
Edit overlay.yaml thực tế — không skip, mỗi field vai trò enforcement
Chạy mehcli install sau mỗi self-update — rerender templates với latest upstream
Add Konsist + Detekt + Lint vào CI — enforcement không skip
Review product-extensions.md mỗi sprint — product-specific rule có drift không
Promote rule overlay → upstream khi 2+ product cùng rule
Test harness bằng evaluations/templates/ — baseline measurement + regression tracking
Document deviation từ blueprint trong PR

DON'T

Fork upstream rule trong overlay — luôn add qua constitution/product-extensions.md [KB → develop/constitution, kb_search "product extensions"] extend, không override
Commit .manifest.yaml nếu nó varies per machine (xem gitignore)
Hardcode absolute path trong constitution/skills — dùng {{PACKAGE_ROOT}} placeholder
Add rule không có verification method — rule không enforce được = decorative
Add file < 50 dòng vào knowledge — short content → link-first thay vì tạo file riêng
Disable Konsist/Detekt test khi fail — fix cause hoặc downgrade rule severity
Skip baseline measurement → không biết harness thực sự improve hay không

Khi viết rule mới

Có user story thực tế — AI đã vi phạm pattern này ≥ 3 lần
Rule verifiable — Konsist test hoặc Detekt rule hoặc explicit review checklist
Severity rõ — MUST (chặn task) / SHOULD (default) / MAY (option) / FORBIDDEN (never)
Rationale 1 câu — tại sao rule tồn tại
Violation example + fix — concrete, không vague "best practice"
Add vào Konsist/Detekt cùng commit — không delay enforcement

Khi expand skill

Trigger rõ — khi nào invoke skill
Prerequisites — file cần đọc trước
Procedure có steps rõ — không "AI figure it out"
Required policies — rule nào từ constitution áp dụng
Common mistakes — anti-patterns với fix
Output contract — deliverable cụ thể

Khi update harness

Semver bump rõ (breaking? feature? patch?)
CHANGELOG entry với rationale
Backward compat check — overlay cũ còn work?
Test với 1 overlay thực — regression check trước khi tag
Tag + GitHub Release — reproducible pin point

Agent interaction patterns

Pattern 1 — Full feature end-to-end

User: "Implement Login feature với Google OAuth + save token"

AI resolution:
1. Load CLAUDE.md + AGENTS.md
2. Route task → skills/coding-feature
3. Load constitution/architecture-rules + concurrency-rules
4. Load blueprint reference-feature
5. Follow workflow feature-development
6. Agent role: architect (plan) → implementer → qa → reviewer
7. Verify: konsistTest + detekt + unit tests
8. Report theo DoD template

Pattern 2 — Code review PR

User: "Review PR #42"

AI resolution:
1. Route task → skills/coding-review + workflow/review-pull-request
2. Agent role: reviewer
3. Scan diff 10 dimensions
4. Each finding: Rule ID, severity, file:line, evidence, fix
5. Report theo review template

Pattern 3 — Debug bug

User: "Fix crash in BookDetail khi offline"

AI resolution:
1. Route task → skills/coding-diagnose (`--mode bug`) + workflow/fix-bug
2. Agent role: debugger
3. Stages: reproduce → isolate → cause → fix → verify
4. Fix tại cause, không mask symptom
5. Add regression test

Context cost optimization

Harness design cho progressive disclosure — tối ưu context budget:

Agent không load toàn bộ harness mỗi task
Load theo order:
1. AGENTS.md (entry, ~200 lines) — always
2. Skill tương ứng (SKILL.md, ~250 lines) — per task
3. Constitution rule relevant — khi verify
4. Knowledge essentials — khi deep concept
5. Blueprint — khi tạo pattern mới

Mỗi task thường chỉ cần ~1500-3000 tokens harness context, không phải full 68 files.

CLI reference

Subcommands

mehcli init         --project <path>              # scaffold overlay + schema
mehcli install      --overlay <path>              # render templates + manifest
mehcli update       --overlay <path>              # idempotent re-render
mehcli uninstall    --overlay <path> [--purge]    # remove rendered; --purge nukes overlay
mehcli self-update                                # git pull upstream in-place
mehcli version                                    # print installed version
mehcli help

Flags chung

Flag	Hiệu lực
`--dry-run`	Print actions, không execute
`--yes`, `-y`	Skip confirmation (cho CI)

Chi tiết subcommand

init — scaffold overlay structure:

Tạo .harness-overlay/ trong project
Copy overlay.schema.yaml → .harness-overlay/overlay.yaml
Symlink .harness-overlay/upstream → upstream repo
KHÔNG render; đợi user điền overlay.yaml

install — render templates:

Đọc overlay.yaml, validate required fields
Render 4 files: ArchitectureRulesTest.kt, verify.sh, harness.yaml, overlay README.md
Ghi .manifest.yaml track rendered files + upstream commit
Idempotent

update — alias install. Dùng sau self-update hoặc khi overlay.yaml đổi.

uninstall — remove rendered artifacts:

Default: xóa 4 rendered files + manifest; preserve overlay.yaml, constitution/, blueprints/, upstream symlink
--purge: xóa toàn bộ .harness-overlay/ (2x confirm)
Konsist test đã copy sang source → user xóa thủ công

self-update — git pull upstream trong installed location. Reports before/after commit.

Submodule thay vì symlink (CI)

Sau khi init:

cd /path/to/your/android-project/.harness-overlay
rm upstream
cd ..
git submodule add https://github.com/huypqapero/mobile-engineering-harness.git .harness-overlay/upstream

Setup Konsist dep (one-time per product)

Trong gradle/libs.versions.toml:

[versions]
konsist = "0.17.3"

[libraries]
konsist = { module = "com.lemonappdev:konsist", version.ref = "konsist" }

Copy rendered Konsist test:

cp .harness-overlay/verification/architecture-tests/ArchitectureRulesTest.kt \
   presenter/src/jvmTest/kotlin/<package>/harness/

Add test dep + run:

./gradlew konsistTest

Setup Detekt (one-time per product)

cp .harness-overlay/upstream/verification/detekt/detekt-config-template.yml ./detekt.yml
./gradlew detekt
./gradlew detektBaseline       # generate baseline cho existing codebase

Chi tiết .harness-overlay/upstream/verification/detekt/README.md.

Verify tổng

./.harness-overlay/verification/scripts/verify.sh

Chạy đủ gates: compile + unit tests + Konsist + Detekt + build.

Agent resolution order

Khi AI agent nhận task trong project có overlay:

1. Project root CLAUDE.md (nếu có) — product-specific context cao nhất
   ↓
2. .harness-overlay/overlay.yaml — resolve vars
   ↓
3. .harness-overlay/upstream/AGENTS.md — generic entry (substitute vars)
   ↓
4. Skill tương ứng: upstream/skills/<name>/SKILL.md
   ↓
5. Constitution (upstream/constitution/) khi verify rule
   ↓
6. Knowledge (upstream/knowledge/) khi cần deep concept
   ↓
7. Blueprint: ưu tiên overlay/blueprints/live-reference-feature.md,
   fallback upstream/blueprints/reference-feature/README.md

Rule precedence (cao → thấp)

Project CLAUDE.md — product/repo chủ ý override
Overlay constitution (.harness-overlay/constitution/product-extensions.md [KB → develop/constitution, kb_search "product extensions"]) — product-specific delta
Upstream constitution — generic baseline

Nếu cùng rule ID xuất hiện ở overlay + upstream → overlay thắng.

Workflow + agent role interplay

WORKFLOW (orchestration)         AGENT ROLE (mindset)
────────────────────────         ────────────────────
feature-development              architect → implementer → qa → reviewer
fix-bug                          debugger (role tích hợp trong agents/)
review-pull-request              reviewer
refactor-module                  architect → implementer → reviewer
release-validation               implementer + qa + reviewer

1 agent có thể chuyển mindset qua các role trong 1 workflow. Multi-agent setup: dedicated subagent per role.

Governance

Upstream maintenance

Owner sở hữu rule + skill upstream, bump version theo semver
Breaking rule change → major bump; overlay specify harness_version: ">=X.Y.0" để pin
Review quarterly: rule có outdated không, Compose/Coroutines có thay đổi, Konsist/Detekt API drift
CHANGELOG + GitHub Release mỗi version — reproducible pin

Overlay maintenance

Product chỉ add delta qua constitution/product-extensions.md [KB → develop/constitution, kb_search "product extensions"], không fork upstream rule
Promote overlay → upstream khi 2+ product độc lập có cùng rule
Baseline measurement định kỳ — chạy eval E01-E05 để verify không regression
Konsist/Detekt baseline shrink mỗi sprint — fix 1-2 old issue

Rule lifecycle

Discover → Propose → Review → Approve → Publish → Evaluate → Version

Mỗi rule có:

id: COROUTINE-004
title: Preserve coroutine cancellation
level: MUST
rationale: Cancellation là part của structured concurrency
validation: Detekt SwallowedException + manual review
exceptions: []
sources: [concurrency-rules.md]

Rule evolution

Rule nào Konsist/Detekt không bao giờ catch (test luôn pass) → downgrade MUST → SHOULD hoặc delete (dead rule)
Rule nào bị vi phạm thường nhưng Konsist không catch → thêm Detekt custom rule
Rule nào conflict với rule khác → ADR giải quyết + merge

Phạm vi áp dụng

Loại sản phẩm	Fit	Note
Compose Multiplatform (Android + iOS)	✓ chính	Full stack covered
Android-only Jetpack Compose	✓	Bỏ platform SDK iOS section trong `overlay.yaml`
Android XML/MVVM legacy	⚠	MVI rule phần lớn apply; Compose rule skip; cần adaptation
Kotlin Multiplatform (shared logic + native UI)	✓	Customize profile trong `overlay.yaml`
iOS-only Swift/SwiftUI	✗	Ngoài scope — harness Kotlin-centric
React Native / Flutter	✗	Khác ecosystem

Profile types (`overlay.yaml`)

profile: app                     # Default: consumer app
# profile: sdk-library           # Phase 2: feature extract thành library
# profile: multiplatform-library # KMP shared library

sdk-library promote MOD-001..003 severity SHOULD → MUST + thêm binary compat gate.

Stack options

Harness support đa stack qua stack.* fields trong overlay.yaml:

Field	Options	Note
`stack.ui`	`compose-multiplatform` / `compose-android` / `xml-android`	UI framework
`stack.di`	`koin` / `hilt` / `manual`	DI framework
`stack.network`	`ktor` (KMP) / `ktorfit` (KMP annotation) / `retrofit` (Android-only)	API client
`stack.database`	`sqldelight` (KMP + Android) / `room` (Android + KMP 2.7+) / `datastore` / `none`	Local DB
`stack.image`	`coil` / `glide` / `kamel` / `none`	Image loader
`stack.serialization`	`kotlinx-serialization` / `moshi` / `gson`	JSON serialization

Decision guides chi tiết:

Network: .harness-overlay/upstream/knowledge/coding/data/network.md [KB → develop/networking, kb_search "data network"] §Library selection
Database: .harness-overlay/upstream/knowledge/coding/data/persistence.md [KB → develop/networking, kb_search "data persistence"] §Relational DB

Agent sử dụng stack value để chọn snippet trong knowledge/skills (ví dụ stack.network: retrofit → Retrofit code, không Ktor).

Architecture profile (v0.8.0+)

Pick 1 trong 3 profiles qua architecture.profile:

Profile	Target	ARCH-010 (platform SDK)
`cmp`	Compose Multiplatform (shared UI + logic)	MUST enforce
`kmp`	Kotlin Multiplatform (shared logic, native UI)	MUST enforce
`android-only`	Jetpack Compose Android	SKIP (relaxed)

Chi tiết + migration guide: .harness-overlay/upstream/knowledge/coding/clean-arch/architecture-profiles.md [KB → develop/clean-arch, kb_search "clean arch architecture profiles"].

Rule overrides (v0.8.0+)

Overlay có thể override rule MUST qua rule_overrides nhưng rationale ≥ 50 chars bắt buộc. Install validate — thiếu rationale → fail.

rule_overrides:
  - rule: ARCH-008
    severity: SHOULD              # Downgrade từ MUST
    rationale: "Settings app simple không có remote data, 5-state coverage over-strict."

Enforcement mode (v0.8.0+)

enforcement:
  mode: strict     # Default: fail CI khi violation
  # mode: advisory # Warn only — dùng khi mới migrate hoặc evaluation phase

Agent orchestration (v0.9.0+)

4 orchestration modes qua orchestration.mode:

Mode	Khi dùng	Cost	Latency wall-clock
`single`	Task < 300 LOC, 1 feature	1x	1x
`team`	Cross-module hoặc high-risk	2-3x	3x (sequential handoff)
`parallel-features`	Build 3-5 features từ spec cùng lúc	3-5x	1.2-1.5x (parallel speedup)
`auto`	Default — harness quyết dựa trên task	Varies	Varies

orchestration:
  mode: parallel-features     # Build N feature song song từ spec
  parallel:
    max_concurrent: 3
    isolation: feature-package           # Mỗi subagent 1 feature package, không conflict
    shared_file_strategy: coordinator    # DI/Nav/resources handled serial

Flow parallel-features (xem workflows/parallel-feature-development.md):

spec → architect decompose → isolation check → spawn N parallel Task subagents
     → aggregate shared files (coordinator) → reviewer audit → verify

Claude Code Task tool native support. Subagent per role, tool subset limit (ví dụ reviewer chỉ Read+Grep, không Edit → prevent bias).

Chi tiết: knowledge/meta/agent-orchestration/essentials.md [KB → develop/meta-orchestration, kb_search "agent orchestration essentials"].

Release history

Mỗi version một dòng. Chi tiết đầy đủ xem CHANGELOG.md.

v0.1.0: harness 2 lớp đầu tiên, gồm 14 rule ARCH, 10 rule CORO, 5 skill, blueprint ItemCatalog, Konsist và verify.sh
v0.2.0: CLI quản lý vòng đời (init/install/update/uninstall), manifest, --dry-run/--yes
v0.3.0: cài đặt một lệnh qua bootstrap.sh, thêm mehcli self-update và mehcli version
v0.4.0: kotlin-conventions (12 rule KOT), skill coroutines, workflow fix-bug và review-PR, các role trong agents/
v0.5.0: skill network và database, workflow refactor và release, knowledge/data, Detekt
v0.6.0: skill refactor, debug và performance, 3 blueprint, knowledge patterns/security/performance, rubrics/regression, Lint
v0.7.0: data layer nhiều lựa chọn: Ktor/Ktorfit/Retrofit và SQLDelight/Room
v0.8.0: architecture.profile, rule_overrides (lý do từ 50 ký tự trở lên), enforcement.mode
v0.9.0: agent orchestration gồm 4 mode: single, team, parallel-features, auto
v0.10.0: Factory pack gồm task YAML contract, build 4 level, auto-fix có fingerprint, phân loại lỗi, chọn model theo tier
v0.10.1 và v0.10.2: MIT LICENSE và CONTRIBUTING.md
v0.11.0: ARCH-004 mới, Repository không kế thừa BaseRepository, API trả ApiResult qua CallAdapter (Retrofit) / Converter (Ktorfit) / safeRequest (Ktor)

Sắp tới — v1.0.0: Production proof, có từ 3 product trở lên dùng trong production và đo được ROI.

References

Repo: https://github.com/huypqapero/mobile-engineering-harness
Releases: https://github.com/huypqapero/mobile-engineering-harness/releases
Changelog: CHANGELOG.md
Entry point AI agent: AGENTS.md
Overlay schema: overlay.schema.yaml

External resources

License

Free for commercial + private use. Attribution appreciated nhưng không required.

Contributing

Issue + PR welcome. Khi contribute:

Open issue mô tả scope + rationale trước
Follow rule trong constitution/
Add Konsist/Detekt rule đi kèm nếu add rule mới
Update CHANGELOG + bump version
Test regression với ít nhất 1 real overlay nếu có

Name		Name	Last commit message	Last commit date
agents		agents
blueprints		blueprints
docs		docs
evaluations		evaluations
plans		plans
scripts		scripts
skills		skills
verification		verification
workflows		workflows
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
bootstrap.sh		bootstrap.sh
harness.yaml.template		harness.yaml.template
install.sh		install.sh
overlay.schema.yaml		overlay.schema.yaml

Latest commit

History

Folders and files

Repository files navigation

Mobile Engineering Harness

Table of contents

Install

One-liner

Quick start cho product mới (3 lệnh)

Alternative: skill-based onboarding qua Claude Code

Uninstall / offboarding

Install + run luôn (1 lệnh)

Env vars cho bootstrap

Update to latest

Prerequisites

Workflow (symlink mode — default bootstrap.sh)

Workflow (submodule mode — CI pin)

Rollback

Breaking change check

Pin strategy cho CI

AI Harness là gì

Vấn đề

Giải pháp — Harness 5 layer

Nguyên tắc thiết kế

Kiến trúc 2-layer

Upstream (generic, shared)

Overlay (product-specific)

DRY ratio

Current state

Breakdown v0.6.0

Structure

Best practices

Khi dùng harness

DO

DON'T

Khi viết rule mới

Khi expand skill

Khi update harness

Agent interaction patterns

Pattern 1 — Full feature end-to-end

Pattern 2 — Code review PR

Pattern 3 — Debug bug

Context cost optimization

CLI reference

Subcommands

Flags chung

Chi tiết subcommand

Submodule thay vì symlink (CI)

Setup Konsist dep (one-time per product)

Setup Detekt (one-time per product)

Verify tổng

Agent resolution order

Rule precedence (cao → thấp)

Workflow + agent role interplay

Governance

Upstream maintenance

Overlay maintenance

Rule lifecycle

Rule evolution

Phạm vi áp dụng

Profile types (overlay.yaml)

Stack options

Architecture profile (v0.8.0+)

Rule overrides (v0.8.0+)

Enforcement mode (v0.8.0+)

Agent orchestration (v0.9.0+)

Release history

References

External resources

Related

License

Contributing

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Profile types (`overlay.yaml`)