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: harness-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---56# moai-adk-go Domain Patterns78## Architecture Quick Reference910moai-adk-go is a Go binary (`moai`) with four subsystems:11121. **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 structured15 output for the orchestrator.162. **Template system** (`internal/template/`) — `go:embed`-based scaffolding.17 Source at `internal/template/templates/`, embedded into the binary via18 `//go:embed all:templates` in `internal/template/embed.go` (no generated19 `.go` file). `make build` recompiles the binary.20 `TemplateContext` (`{{.GoBinPath}}` / `{{.HomeDir}}`) renders at `moai init`.213. **Config** (`internal/config/`) — `defaults.go` (single source for22 thresholds), `envkeys.go` (env-var constants), `TemplateContext` renderer.234. **Hook + CI** (`.claude/hooks/moai/*.sh`, `.github/workflows/`) — bash24 wrapper hooks calling `moai hook <event>`; CI guard enforces template25 neutrality.2627Plus the **SPEC lifecycle** (`.moai/specs/`) governing the project's own28development (plan→run→sync→Mx).2930## Key Source Paths3132| 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) |4445## Pipeline Specialist Delegation Map4647This harness is a 4-stage pipeline; each specialist delegates to retained48agents (never archived, never replaces them):4950```51CLI/Template ──→ quality ──→ workflow ──→ hook/CI52 │ │ │ │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```6465## Template-First Build Cycle6667When adding/editing anything that ships to user projects:68691. Edit `internal/template/templates/<path>` FIRST.702. Run `make build` → recompiles the binary (templates embedded via71 `//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).7576Never edit `.claude/` or `.moai/` directly without a template source. The77source of truth is `templates/` — edit files there, then `make build`.7879## Namespace Separation Contract8081Two namespaces, enforced by `moai update`:8283| 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 |8788The canonical user-owned skill prefix is `harness-*` (recognized by Go89enforcement after the namespace catch-up, SPEC-V3R6-HARNESS-NAMESPACE-V2-001).90The legacy `my-harness-*` form is retained during a backward-compat91deprecation window; new skills MUST use the bare `harness-*` prefix.9293## Common Workflows9495### Add a template96971. 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`.101102### Add a hook1031041. Write `.claude/hooks/moai/handle-<event>.sh` (bash, reads stdin JSON, calls105 `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 AND109 the settings.json entry to `internal/template/templates/`.110111### Add an agent (harness specialist)1121131. 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-activation117 smoke gate FAILs).118119### Add a SPEC1201211. `/moai plan "<description>"` → `manager-spec` authors plan-phase artifacts.1222. `plan-auditor` independent audit gate.1233. **Implementation Kickoff Approval** human gate (orchestrator runs124 `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).129130## Cross-References131132- CLAUDE.local.md §2 (Template-First Rule), §7 (hooks), §21 (dev-only commands)133- `.claude/rules/moai/development/agent-authoring.md` — agent frontmatter schema134- `.claude/rules/moai/development/skill-authoring.md` — skill frontmatter schema135- `.claude/rules/moai/workflow/archived-agent-rejection.md` §C — migration table136- `.claude/skills/moai-meta-harness/SKILL.md` § Namespace Separation
tuyv