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.
2. 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.
3. Config (internal/config/) — defaults.go (single source for thresholds), envkeys.go (env-var constants), TemplateContext renderer.
4. 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).
3. Sync to local: moai update (or manual copy).
4. Verify the local .claude/ / .moai/ reflects the template.
5. 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>).
2. Wire in .claude/settings.json with "$CLAUDE_PROJECT_DIR/..." quoting + timeout: 5.
3. 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).
2. 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).
4. /moai run SPEC-<ID> → manager-develop (cycle_type per quality.yaml).
5. /moai sync SPEC-<ID> → manager-docs.
6. sync-auditor 4-dimension gate.
7. 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