moai-adk-go Domain Patterns

Architecture Quick Reference

moai-adk-go is a Go binary (moai) with four subsystems:

1. CLI (internal/cli/*.go, cmd/moai/) — Cobra commands: init,

update, hook, build, glm, cc, cg, version, doctor, spec. Subcommand handlers read stdin JSON for hooks, emit structured output for the orchestrator.

1. Template system (internal/template/) — go:embed-based scaffolding.

Source at internal/template/templates/, embedded into the binary via //go:embed all:templates in internal/template/embed.go (no generated .go file). make build recompiles the binary. TemplateContext ({{.GoBinPath}} / {{.HomeDir}}) renders at moai init.

1. Config (internal/config/) — defaults.go (single source for

thresholds), envkeys.go (env-var constants), TemplateContext renderer.

1. Hook + CI (.claude/hooks/moai/*.sh, .github/workflows/) — bash

wrapper hooks calling moai hook <event>; CI guard enforces template neutrality.

Plus the SPEC lifecycle (.moai/specs/) governing the project's own development (plan→run→sync→Mx).

Key Source Paths

| Subsystem | Path | Notes | |-----------|------|-------| | Cobra commands | internal/cli/*.go | wired from cmd/moai/ | | Template source | internal/template/templates/** | edit HERE first | | Embedded assets | internal/template/embed.go | //go:embed all:templates (no generated file) | | Config defaults | internal/config/defaults.go | threshold SSOT | | Env constants | internal/config/envkeys.go | no hardcoded env names | | SPEC docs | .moai/specs/SPEC-*/ | spec/plan/acceptance/progress | | Era classifier | internal/spec/era.go | ClassifyEra() H-1..H-6 | | Hook scripts | .claude/hooks/moai/*.sh | bash only, no Python | | CI workflows | .github/workflows/*.yaml | neutrality guard active | | Harness agents | .claude/agents/harness/*.md | USER-OWNED (this skill) |

Pipeline Specialist Delegation Map

This harness is a 4-stage pipeline; each specialist delegates to retained agents (never archived, never replaces them):

CLI/Template ──→ quality ──→ workflow ──→ hook/CI
  │                │            │            │
  ├─ manager-develop (tdd, backend)
  ├─ Explore (read-only)
  ├─ sync-auditor (4-dim scoring)
  ├─ sync-phase-quality-gate.sh (Stop hook)
  ├─ manager-spec (plan)
  ├─ manager-develop (run)
  ├─ manager-docs (sync)
  ├─ plan-auditor (audit)
  ├─ builder-harness (artifact_type=hook|command|plugin)
  └─ Agent(general-purpose, model: opus, tools: ..., prompt: "...CI specialist...")

Template-First Build Cycle

When adding/editing anything that ships to user projects:

1. Edit internal/template/templates/<path> FIRST.
2. Run make build → recompiles the binary (templates embedded via

//go:embed all:templates in embed.go; no generated .go file).

1. Sync to local: moai update (or manual copy).
2. Verify the local .claude/ / .moai/ reflects the template.
3. Run go test ./internal/template/... (neutrality audit included).

Never edit .claude/ or .moai/ directly without a template source. The source of truth is templates/ — edit files there, then make build.

Namespace Separation Contract

Two namespaces, enforced by moai update:

| Namespace | Location | Owner | moai update behavior | |-----------|----------|-------|------------------------| | Template-managed | internal/template/templates/** → .claude/agents/{core,expert,meta}/, moai-* skills | MoAI-ADK distribution | Overwrites local on sync | | User-owned (this harness) | .claude/agents/harness/, harness-* skills, .moai/harness/ | Project developer | NEVER deleted/modified; backup before update |

The canonical user-owned skill prefix is harness-* (recognized by Go enforcement after the namespace catch-up, SPEC-V3R6-HARNESS-NAMESPACE-V2-001). The legacy my-harness-* form is retained during a backward-compat deprecation window; new skills MUST use the bare harness-* prefix.

Common Workflows

Add a template

1. Create file at internal/template/templates/<path>.
2. make build.
3. moai update (or test via ./moai init /tmp/test-project).
4. go test ./internal/template/... -run TestTemplateNeutralityAudit.

Add a hook

1. Write .claude/hooks/moai/handle-<event>.sh (bash, reads stdin JSON, calls

moai hook <event>).

1. Wire in .claude/settings.json with "$CLAUDE_PROJECT_DIR/..." quoting +

timeout: 5.

1. If the hook is template-distributable, add the wrapper template source AND

the settings.json entry to internal/template/templates/.

Add an agent (harness specialist)

1. Create .claude/agents/harness/<role>-specialist.md with name,

trigger-shaped description, skills: array (companion skill), tools: (CSV string).

1. Ensure the companion harness-* skill exists (else self-activation

smoke gate FAILs).

Add a SPEC

1. /moai plan "<description>" → manager-spec authors plan-phase artifacts.
2. plan-auditor independent audit gate.
3. Implementation Kickoff Approval human gate (orchestrator runs

AskUserQuestion).

1. /moai run SPEC-<ID> → manager-develop (cycle_type per quality.yaml).
2. /moai sync SPEC-<ID> → manager-docs.
3. sync-auditor 4-dimension gate.
4. 3-phase close on the single sync commit (populate sync_commit_sha in §E.4; the sync commit carries the implemented → completed transition — per SPEC-V3R6-LIFECYCLE-REDESIGN-001, the former separate mx_commit_sha / §E.5 Mx-phase step is retired; MX Tag validation is a sync sub-step).

Cross-References

• CLAUDE.local.md §2 (Template-First Rule), §7 (hooks), §21 (dev-only commands)
• .claude/rules/moai/development/agent-authoring.md — agent frontmatter schema
• .claude/rules/moai/development/skill-authoring.md — skill frontmatter schema
• .claude/rules/moai/workflow/archived-agent-rejection.md §C — migration table
• .claude/skills/moai-meta-harness/SKILL.md § Namespace Separation