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