/hns-moaiadk-best-practices

name: hns-moaiadk-best-practices
description: >
  moai-adk-go best-practices reference for the 4 harness specialists
  (cli-template-specialist, quality-specialist, workflow-specialist,
  hook-ci-specialist). Covers TRUST 5 gates, Go test isolation
  (t.TempDir, no OTEL env in parallel tests), hardcoding-prevention rules
  (env constants in envkeys.go, thresholds in defaults.go), the
  AskUserQuestion orchestrator-only boundary, the deferred-tool preload rule,
  the archived-agent rejection contract, and verification-claim integrity.
  Loaded by the specialists when authoring or reviewing moai-adk-go code.
allowed-tools: Read, Grep, Glob, Bash
user-invocable: false
metadata:
  version: "1.0.0"
  category: "harness/best-practices"
  status: "active"
  updated: "2026-06-17"
  tags: "moai-adk-go,best-practices,trust5,testing,hardcoding"
progressive_disclosure:
  level_1_tokens: 120
  level_2_tokens: 4000
  level_3_optional: true
triggers:
  agents:
    - cli-template-specialist
    - quality-specialist
    - workflow-specialist
    - hook-ci-specialist
  keywords: TRUST 5, t.TempDir, envkeys.go, defaults.go, AskUserQuestion, archived-agent, verification-claim, deferred tool
paths: "internal/**/*.go,**/*_test.go,.claude/rules/**"

moai-adk-go Best Practices

TRUST 5 Quality Gates

Every change must pass all five dimensions before completion:

| Pillar | Gate | Failure action | |--------|------|----------------| | **Tested** | `go test ./...` with coverage | Block merge; generate missing tests | | **Readable** | `golangci-lint run` | Warn; suggest refactoring | | **Unified** | `go fmt` + `goimports` | Auto-format or warn | | **Secured** | OWASP-aligned review (per-spawn opus agent) | Block; require review | | **Trackable** | Conventional Commits regex | Suggest format |

Coverage targets: 85% package minimum; 90%+ for critical packages (`internal/cli`, `internal/template`, `internal/hook`).

Test Isolation

• **Always** `t.TempDir()` for temp dirs — auto-cleanup, under `os.TempDir()`.
• **macOS path pitfall**: `t.TempDir()` returns `/var/folders/...`. Go's

`filepath.Join(cwd, absPath)` does NOT strip the leading `/`: `filepath.Join("/a/b", "/var/folders/x")` → `"/a/b/var/folders/x"` (WRONG). Use `filepath.Abs()` when resolving user-supplied paths in CLI commands.

• **No OTEL env in parallel tests** (CLAUDE.local.md §WARN): never

`t.Setenv("OTEL_EXPORTER_*", ...)` in parallel tests — the OTEL SDK initializes global state from env vars on first use, causing data races. Use a fake/no-op exporter instead; or make the parent test non-parallel.

• **No `t.Setenv("HOME", tmpDir)`** in GLM integration tests — parallel-test

pollution. Use `t.TempDir()` + explicit path construction.

• **After fixing any test**, run the FULL suite (`go test ./...`) to catch

cascading failures. Use `-count=1` to disable caching when debugging flaky tests; use `-race` for concurrency-safety checks.

Hardcoding Prevention

• **URLs / model names / org names / API headers** → extract to `const`.
• **Environment variable names** → define in `internal/config/envkeys.go` as

constants; reference the constant everywhere. Never inline a raw env string.

• **Thresholds** → single source in `internal/config/defaults.go`. Never

duplicate a threshold across packages.

• **Cross-platform paths** → prefer `$HOME`, `HOMEBREW_PREFIX`, etc. In

`.sh.tmpl` fallback paths use `$HOME` (not `.HomeDir`), because `.HomeDir` freezes at `moai init` time and breaks for users with non-standard layouts.

• **Hardcoding allowed** only in `CLAUDE.local.md`, `settings.local.json`,

and `_test.go` files inside `t.TempDir()`.

AskUserQuestion Boundary (orchestrator-only)

• `AskUserQuestion` is the ONLY user-facing question channel, and it is

reserved for the MoAI orchestrator (main session).

• **Subagents (including these harness specialists) MUST NOT invoke

AskUserQuestion.** If user input is required, return a structured blocker report to the orchestrator (see `.claude/rules/moai/core/askuser-protocol.md` § Blocker Report Format).

• **Deferred-tool preload**: `AskUserQuestion`, `TaskCreate`, `TaskUpdate`,

`TaskList`, `TaskGet` are deferred tools — schema not loaded at session start. The orchestrator MUST call `ToolSearch(query: "select:AskUserQuestion,TaskCreate,...")` before first use. Subagents inherit this constraint.

• Free-form prose questions in response text are prohibited — always route

through AskUserQuestion (orchestrator) or a blocker report (subagent).

Archived-Agent Rejection Contract

12 agents are ARCHIVED and MUST NOT be referenced anywhere in generated harness files — no `delegates-to`, no prose, no examples. The full list of archived names lives in the canonical SSOT at `.claude/rules/moai/workflow/archived-agent-rejection.md` §B; this skill does not repeat the literal names (repeating them in every generated file would re-seed the exact tokens the rejection contract is meant to suppress).

The 8 RETAINED agents are the only valid delegation targets:

manager-spec, manager-develop, manager-docs, manager-git,
plan-auditor, sync-auditor, builder-harness, Explore (Anthropic built-in)

For domain expertise formerly provided by the archived domain-expert agents, use the per-spawn pattern: `Agent(subagent_type: "general-purpose", model: "opus", tools: "<whitelist>", prompt: "...<domain> specialist: <conventions>...")` at delegation time. See `.claude/rules/moai/workflow/archived-agent-rejection.md` §C for the full migration table (rows #1-#12), which maps each archived agent to its canonical retained-agent or per-spawn replacement.

Verification-Claim Integrity

Per `.claude/rules/moai/core/verification-claim-integrity.md`:

• **No unobserved claims.** A "tests pass" / "coverage 87%" / "lint clean"

assertion is valid ONLY when the actor ran the command and observed the output. An unran command is a gap, never a pass.

• **No unobserved defect claims.** Inferrin