moai-adk-go Domain Patterns
Architecture Quick Reference
moai-adk-go is a Go binary (moai) with four subsystems:
- 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.
- 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.
- Config (
internal/config/) — defaults.go (single source for
thresholds), envkeys.go (env-var constants), TemplateContext renderer.
- 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:
- Edit
internal/template/templates/<path> FIRST.
- Run
make build → recompiles the binary (templates embedded via
//go:embed all:templates in embed.go; no generated .go file).
- Sync to local:
moai update (or manual copy).
- Verify the local
.claude/ / .moai/ reflects the template.
- 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
- Create file at
internal/template/templates/<path>.
make build.
moai update (or test via ./moai init /tmp/test-project).
go test ./internal/template/... -run TestTemplateNeutralityAudit.
Add a hook
- Write
.claude/hooks/moai/handle-<event>.sh (bash, reads stdin JSON, calls
moai hook <event>).
- Wire in
.claude/settings.json with "$CLAUDE_PROJECT_DIR/..." quoting +
timeout: 5.
- 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)
- Create
.claude/agents/harness/<role>-specialist.md with name,
trigger-shaped description, skills: array (companion skill), tools:
(CSV string).
- Ensure the companion
harness-* skill exists (else self-activation
smoke gate FAILs).
Add a SPEC
/moai plan "<description>" → manager-spec authors plan-phase artifacts.
plan-auditor independent audit gate.
- Implementation Kickoff Approval human gate (orchestrator runs
AskUserQuestion).
/moai run SPEC-<ID> → manager-develop (cycle_type per quality.yaml).
/moai sync SPEC-<ID> → manager-docs.
sync-auditor 4-dimension gate.
- 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
1---
2name: hns-moaiadk-patterns
3description: >
4 moai-adk-go domain-patterns reference for the 4 harness specialists
5 (cli-template-specialist, quality-specialist, workflow-specialist,
6 hook-ci-specialist). Covers the CLI/template/config/hook/spec subsystem
7 architecture, key source paths, the Pipeline specialist delegation map, the
8 Template-First build cycle, the namespace separation contract, and common
9 add-a-template / add-a-hook / add-an-agent / add-a-SPEC workflows. Loaded by
10 the specialists when working on moai-adk-go's own Go codebase and templates.
11allowed-tools: Read, Grep, Glob, Bash
12user-invocable: false
13metadata:
14 source: https://skillmd.com/skills/modu-ai/hns-moaiadk-patterns
15 version: "1.0.0"
16 category: "harness/domain-patterns"
17 status: "active"
18 updated: "2026-06-17"
19 tags: "moai-adk-go,cli,template,harness,patterns"
20progressive_disclosure:
21 level_1_tokens: 120
22 level_2_tokens: 4500
23 level_3_optional: true
24triggers:
25 agents:
26 - cli-template-specialist
27 - quality-specialist
28 - workflow-specialist
29 - hook-ci-specialist
30 keywords: moai-adk-go, internal/cli, internal/template, embed.go, make build, go:embed, template-first, harness namespace
31paths: "internal/**/*.go,internal/template/templates/**,.claude/**,.moai/**"
32---
33
34# moai-adk-go Domain Patterns
35
36## Architecture Quick Reference
37
38moai-adk-go is a Go binary (`moai`) with four subsystems:
39
401. **CLI** (`internal/cli/*.go`, `cmd/moai/`) — Cobra commands: `init`,
41 `update`, `hook`, `build`, `glm`, `cc`, `cg`, `version`, `doctor`,
42 `spec`. Subcommand handlers read stdin JSON for hooks, emit structured
43 output for the orchestrator.
442. **Template system** (`internal/template/`) — `go:embed`-based scaffolding.
45 Source at `internal/template/templates/`, embedded into the binary via
46 `//go:embed all:templates` in `internal/template/embed.go` (no generated
47 `.go` file). `make build` recompiles the binary.
48 `TemplateContext` (`{{.GoBinPath}}` / `{{.HomeDir}}`) renders at `moai init`.
493. **Config** (`internal/config/`) — `defaults.go` (single source for
50 thresholds), `envkeys.go` (env-var constants), `TemplateContext` renderer.
514. **Hook + CI** (`.claude/hooks/moai/*.sh`, `.github/workflows/`) — bash
52 wrapper hooks calling `moai hook <event>`; CI guard enforces template
53 neutrality.
54
55Plus the **SPEC lifecycle** (`.moai/specs/`) governing the project's own
56development (plan→run→sync→Mx).
57
58## Key Source Paths
59
60| Subsystem | Path | Notes |
61|-----------|------|-------|
62| Cobra commands | `internal/cli/*.go` | wired from `cmd/moai/` |
63| Template source | `internal/template/templates/**` | edit HERE first |
64| Embedded assets | `internal/template/embed.go` | `//go:embed all:templates` (no generated file) |
65| Config defaults | `internal/config/defaults.go` | threshold SSOT |
66| Env constants | `internal/config/envkeys.go` | no hardcoded env names |
67| SPEC docs | `.moai/specs/SPEC-*/` | spec/plan/acceptance/progress |
68| Era classifier | `internal/spec/era.go` | `ClassifyEra()` H-1..H-6 |
69| Hook scripts | `.claude/hooks/moai/*.sh` | bash only, no Python |
70| CI workflows | `.github/workflows/*.yaml` | neutrality guard active |
71| Harness agents | `.claude/agents/harness/*.md` | USER-OWNED (this skill) |
72
73## Pipeline Specialist Delegation Map
74
75This harness is a 4-stage pipeline; each specialist delegates to retained
76agents (never archived, never replaces them):
77
78```
79CLI/Template ──→ quality ──→ workflow ──→ hook/CI
80 │ │ │ │
81 ├─ manager-develop (tdd, backend)
82 ├─ Explore (read-only)
83 ├─ sync-auditor (4-dim scoring)
84 ├─ sync-phase-quality-gate.sh (Stop hook)
85 ├─ manager-spec (plan)
86 ├─ manager-develop (run)
87 ├─ manager-docs (sync)
88 ├─ plan-auditor (audit)
89 ├─ builder-harness (artifact_type=hook|command|plugin)
90 └─ Agent(general-purpose, model: opus, tools: ..., prompt: "...CI specialist...")
91```
92
93## Template-First Build Cycle
94
95When adding/editing anything that ships to user projects:
96
971. Edit `internal/template/templates/<path>` FIRST.
982. Run `make build` → recompiles the binary (templates embedded via
99 `//go:embed all:templates` in `embed.go`; no generated `.go` file).
1003. Sync to local: `moai update` (or manual copy).
1014. Verify the local `.claude/` / `.moai/` reflects the template.
1025. Run `go test ./internal/template/...` (neutrality audit included).
103
104Never edit `.claude/` or `.moai/` directly without a template source. The
105source of truth is `templates/` — edit files there, then `make build`.
106
107## Namespace Separation Contract
108
109Two namespaces, enforced by `moai update`:
110
111| Namespace | Location | Owner | `moai update` behavior |
112|-----------|----------|-------|------------------------|
113| Template-managed | `internal/template/templates/**` → `.claude/agents/{core,expert,meta}/`, `moai-*` skills | MoAI-ADK distribution | Overwrites local on sync |
114| User-owned (this harness) | `.claude/agents/harness/`, `harness-*` skills, `.moai/harness/` | Project developer | NEVER deleted/modified; backup before update |
115
116The canonical user-owned skill prefix is `harness-*` (recognized by Go
117enforcement after the namespace catch-up, SPEC-V3R6-HARNESS-NAMESPACE-V2-001).
118The legacy `my-harness-*` form is retained during a backward-compat
119deprecation window; new skills MUST use the bare `harness-*` prefix.
120
121## Common Workflows
122
123### Add a template
124
1251. Create file at `internal/template/templates/<path>`.
1262. `make build`.
1273. `moai update` (or test via `./moai init /tmp/test-project`).
1284. `go test ./internal/template/... -run TestTemplateNeutralityAudit`.
129
130### Add a hook
131
1321. Write `.claude/hooks/moai/handle-<event>.sh` (bash, reads stdin JSON, calls
133 `moai hook <event>`).
1342. Wire in `.claude/settings.json` with `"$CLAUDE_PROJECT_DIR/..."` quoting +
135 `timeout: 5`.
1363. If the hook is template-distributable, add the wrapper template source AND
137 the settings.json entry to `internal/template/templates/`.
138
139### Add an agent (harness specialist)
140
1411. Create `.claude/agents/harness/<role>-specialist.md` with `name`,
142 trigger-shaped `description`, `skills:` array (companion skill), `tools:`
143 (CSV string).
1442. Ensure the companion `harness-*` skill exists (else self-activation
145 smoke gate FAILs).
146
147### Add a SPEC
148
1491. `/moai plan "<description>"` → `manager-spec` authors plan-phase artifacts.
1502. `plan-auditor` independent audit gate.
1513. **Implementation Kickoff Approval** human gate (orchestrator runs
152 `AskUserQuestion`).
1534. `/moai run SPEC-<ID>` → `manager-develop` (cycle_type per quality.yaml).
1545. `/moai sync SPEC-<ID>` → `manager-docs`.
1556. `sync-auditor` 4-dimension gate.
1567. 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).
157
158## Cross-References
159
160- CLAUDE.local.md §2 (Template-First Rule), §7 (hooks), §21 (dev-only commands)
161- `.claude/rules/moai/development/agent-authoring.md` — agent frontmatter schema
162- `.claude/rules/moai/development/skill-authoring.md` — skill frontmatter schema
163- `.claude/rules/moai/workflow/archived-agent-rejection.md` §C — migration table
164- `.claude/skills/moai-meta-harness/SKILL.md` § Namespace Separation