/hns-moaiadk-dev-reference

name: hns-moaiadk-dev-reference
description: moai-adk-go local dev reference — version management/release process (sec 5), shell-script hook development (sec 7), build & dev commands (sec 10). Load only when performing these specific tasks.

hns-moaiadk-dev-reference

> moai-adk-go 로컬 dev 레퍼런스 — `CLAUDE.local.md` §5/§7/§10 의 작업 특화 상세를 이곳으로 이관 (lazy-load). 세션마다 필요 없는 참고 자료. 항상-로드 컨텍스트 절감용. > 소유: `hns-*` 네임스페이스 (user-owned, `moai update` 보존 — CLAUDE.local.md §24). 템플릿 미러 금지.

---

Version Management (from CLAUDE.local.md §5)

Single Source of Truth

• [HARD] `go.mod` module version + git tags are the authoritative sources
• [HARD] `pkg/version/version.go` reads from git tags at build time

**Version Reference:**

• Authoritative Source: Git tags (e.g., `v1.0.0`)
• Runtime Access: `pkg/version/version.go` via `git describe`
• Config Display: `.moai/config/sections/system.yaml` (updated by release process)

Build Version Injection

Version is injected at build time using ldflags:

# Build with version injection
go build -ldflags="-X github.com/modu-ai/moai-adk/pkg/version.Version=v1.0.0"

# Makefile handles this automatically
make build VERSION=1.0.0

Files Requiring Version Sync

When releasing new version, update:

**Documentation Files:**

• README.md (Version line)
• README.ko.md (Version line)
• CHANGELOG.md (New version entry)

**Configuration Files:**

• .moai/config/sections/system.yaml (moai.version)
• internal/template/templates/.moai/config/sections/system.yaml.tmpl (moai.version)

Release Process

1. Update CHANGELOG.md with new version entry 2. Create git tag: `git tag v1.0.0` 3. Push tag: `git push origin v1.0.0` 4. Build release binaries: `make release VERSION=1.0.0`

---

Hook Development (from CLAUDE.local.md §7)

[HARD] Shell Script Hooks Only

moai-adk-go uses shell scripts for hooks, NOT Python:

**Hook Wrapper Pattern:**

#!/bin/bash
# .claude/hooks/moai/handle-session-start.sh

# Read stdin JSON from Claude Code
INPUT=$(cat)

# Call moai binary with hook subcommand
moai hook session-start <<< "$INPUT"

**Why Shell Scripts:**

• Faster execution (no Python startup overhead)
• Always available (no dependency on uv/python)
• Cross-platform (bash, /bin/sh)

Hook Command Format

**settings.json hook configuration:**

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/moai/handle-session-start.sh\"",
        "timeout": 5
      }]
    }]
  }
}

**Key Rules:**

• [HARD] Always quote `$CLAUDE_PROJECT_DIR`: `"$CLAUDE_PROJECT_DIR"`
• [HARD] Use full path to hook wrapper script
• [HARD] Set appropriate timeout. MoAI policy default is 5 seconds (the Claude Code platform default is 10 minutes; MoAI tightens this to 5 seconds to avoid stalling the session).

Platform Differences

**macOS/Linux:**

"command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/moai/hook.sh\""

**Windows:**

"command": "\"%CLAUDE_PROJECT_DIR%\\.claude\\hooks\\moai\\hook.sh\""

---

Build & Dev Commands (from CLAUDE.local.md §10)

Common Commands

# Build the project
make build

# Run tests
make test

# Run with race detection
make test-race

# Run linter
make lint

# Format code
make fmt

# Install locally
make install

# Clean build artifacts
make clean

# Run go fix modernizers
make fix

Development Workflow

# 1. Edit templates
vim internal/template/templates/.claude/skills/moai/SKILL.md

# 2. Regenerate embedded files
make build

# 3. Run tests
go test ./internal/template/...

# 4. Test locally
./moai init test-project

# 5. Commit
git add internal/template/templates/
git commit -m "feat(template): update SKILL.md"