ae-adk

module

v1.5.2 Latest Latest Go to latest Published: Apr 16, 2026 License: GPL-3.0

README ¶

AE-ADK

AngelEyes Agentic Development Kit for Claude Code

AE-ADK is a personal fork of moai-adk, optimized for single-developer workflows. It extends Claude Code with AI agent orchestration, automated quality gates, and a SPEC-driven development pipeline.

Built as a single Go binary -- zero dependencies, instant startup on Windows, macOS, and Linux.

Features

SPEC-Driven Workflow -- Plan requirements, implement with TDD/DDD, sync documentation in one pipeline
AI Agent Orchestration -- Specialized agents for backend, frontend, security, testing, and more
Automated Quality Gates -- TRUST 5 framework enforces test coverage, security, and code style
Cross-Platform -- ae win / ae mac for seamless platform switching with PATH auto-reconfiguration
Self-Updating -- Built-in binary update with checksum verification and automatic rollback
Hook System -- Pre/post tool hooks for formatting, linting, and security scanning

Installation

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/AngeleyesTrue/ae-adk/main/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/AngeleyesTrue/ae-adk/main/install.ps1 | iex

Build from Source

git clone https://github.com/AngeleyesTrue/ae-adk.git
cd ae-adk && make build

Prebuilt binaries are available on the Releases page.

Quick Start

# 1. Initialize a project
ae init my-project

# 2. Start developing with Claude Code
/ae plan "Add user authentication"     # Create SPEC document
/ae run SPEC-AUTH-001                   # Implement with TDD/DDD
/ae sync SPEC-AUTH-001                  # Generate docs & create PR

Development Pipeline

graph LR
    A["ae plan"] -->|SPEC| B["ae run"]
    B -->|Code + Tests| C["ae sync"]
    C -->|Docs + PR| D["Done"]

    style A fill:#E3F2FD,stroke:#1565C0
    style B fill:#E8F5E9,stroke:#2E7D32
    style C fill:#FFF3E0,stroke:#E65100
    style D fill:#F3E5F5,stroke:#7B1FA2

CLI Reference

Terminal Commands

Command	Description
`ae init`	Interactive project setup with language/framework auto-detection
`ae update`	Update binary with rollback support
`ae doctor`	System health diagnosis
`ae win`	Switch to Windows platform (PATH + diagnostics)
`ae mac`	Switch to macOS platform (PATH + diagnostics)
`ae worktree`	Git worktree management for parallel development
`ae version`	Display version, commit, and build date

Claude Code Commands

Command	Purpose
`/ae plan "description"`	Create SPEC document (EARS format)
`/ae run SPEC-XXX`	TDD/DDD implementation
`/ae sync`	Documentation sync + PR creation
`/ae fix`	Auto-fix LSP errors and lint issues
`/ae loop`	Iterative fix until all errors resolved
`/ae review`	Multi-perspective code review
`/ae coverage`	Test coverage analysis + gap filling
`/ae mx`	Add @MX code annotations for AI context
`/ae clean`	Dead code identification and removal
`/ae agency`	AI Agency creative production pipeline

Development Methodology

AE-ADK automatically selects the optimal methodology based on your project state:

flowchart TD
    A["Project Analysis"] --> B{"Test Coverage?"}
    B -->|">= 10%"| C["TDD: RED -> GREEN -> REFACTOR"]
    B -->|"< 10%"| D["DDD: ANALYZE -> PRESERVE -> IMPROVE"]

    style C fill:#4CAF50,color:#fff
    style D fill:#2196F3,color:#fff

Methodology	Cycle	Best For
TDD (default)	Write test -> Implement -> Refactor	New projects, features
DDD	Analyze code -> Add tests -> Improve	Legacy code with low coverage

Quality Framework (TRUST 5)

Every code change is validated against five criteria:

Gate	Meaning	Threshold
Tested	Test coverage	85%+
Readable	Code clarity	0 lint errors
Unified	Style consistency	Consistent formatting
Secured	Security	OWASP compliance
Trackable	Traceability	Conventional commits

Build & Test

make build          # Build binary
make test           # Run tests
make lint           # Run linter
make coverage       # Generate coverage report

Test Results

$ go test ./...
ok   github.com/AngeleyesTrue/ae-adk/internal/cli         4.2s
ok   github.com/AngeleyesTrue/ae-adk/internal/hook         5.5s
ok   github.com/AngeleyesTrue/ae-adk/internal/platform     2.1s   coverage: 97.8%
ok   github.com/AngeleyesTrue/ae-adk/internal/update       4.1s
ok   github.com/AngeleyesTrue/ae-adk/internal/template     2.0s
ok   github.com/AngeleyesTrue/ae-adk/pkg/version           1.2s
...
ok   34/35 packages passed

Cross-Platform Builds

$ goreleaser release --clean
  -> windows/amd64    ae-adk_1.0.1_windows_amd64.zip
  -> windows/arm64    ae-adk_1.0.1_windows_arm64.zip
  -> darwin/amd64     ae-adk_1.0.1_darwin_amd64.tar.gz
  -> darwin/arm64     ae-adk_1.0.1_darwin_arm64.tar.gz
  -> linux/amd64      ae-adk_1.0.1_linux_amd64.tar.gz
  -> linux/arm64      ae-adk_1.0.1_linux_arm64.tar.gz

Project Structure

ae-adk/
├── cmd/ae/              # CLI entry point
├── internal/
│   ├── cli/             # Command handlers (Cobra)
│   ├── hook/            # Claude Code hook system
│   ├── platform/        # Platform diagnostics (ae win/mac)
│   ├── update/          # Self-update mechanism
│   ├── template/        # Embedded template FS
│   └── lsp/             # LSP quality gates
├── pkg/version/         # Build-time version injection
├── install.ps1          # Windows installer
└── install.sh           # macOS/Linux installer

Contributing

Issues and pull requests are welcome. This is a personal development tool, but contributions that improve quality or add useful features are appreciated.

git checkout -b feature/my-feature
make test && make lint              # Ensure quality gates pass
git commit -m "feat: description"   # Conventional commits

License

Copyleft 3.0

Links

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
ae command @MX:ANCHOR: [AUTO] main is the entry point of ae CLI.	@MX:ANCHOR: [AUTO] main is the entry point of ae CLI.
internal
astgrep Package astgrep provides AST-based code analysis using the ast-grep (sg) CLI tool.	Package astgrep provides AST-based code analysis using the ast-grep (sg) CLI tool.
cli Package cli provides the Cobra command tree and dependency injection wiring for the AE-ADK CLI.	Package cli provides the Cobra command tree and dependency injection wiring for the AE-ADK CLI.
cli/wizard Package wizard provides an interactive Bubble Tea-based wizard for AE project initialization.	Package wizard provides an interactive Bubble Tea-based wizard for AE project initialization.
cli/worktree Package worktree provides Git worktree management subcommands.	Package worktree provides Git worktree management subcommands.
cmd/datestamp command Package main prints the current UTC time in ISO 8601 format.	Package main prints the current UTC time in ISO 8601 format.
config Package config provides configuration management for AE-ADK Go Edition.	Package config provides configuration management for AE-ADK Go Edition.
core
core/git Package git provides Git repository operations for AE-ADK.	Package git provides Git repository operations for AE-ADK.
core/project Package project provides project initialization, detection, and validation for the AE-ADK Go Edition.	Package project provides project initialization, detection, and validation for the AE-ADK Go Edition.
core/quality @MX:ANCHOR: [AUTO] Core package of the TRUST 5 quality gate framework.	@MX:ANCHOR: [AUTO] Core package of the TRUST 5 quality gate framework.
defs Package defs provides project-wide constants for directory names, file names, file permissions and timeouts used across AE-ADK.	Package defs provides project-wide constants for directory names, file names, file permissions and timeouts used across AE-ADK.
foundation Package foundation provides core methodology types and definitions for AE-ADK.	Package foundation provides core methodology types and definitions for AE-ADK.
git Package git provides higher-level Git utilities built on top of core/git.	Package git provides higher-level Git utilities built on top of core/git.
git/convention Package convention provides commit message convention validation, parsing, and detection for common commit formats.	Package convention provides commit message convention validation, parsing, and detection for common commit formats.
git/ops Package ops provides optimized Git operations with parallel execution, result caching, and connection pooling.	Package ops provides optimized Git operations with parallel execution, result caching, and connection pooling.
github Package github provides GitHub CLI integration for PR and issue operations.	Package github provides GitHub CLI integration for PR and issue operations.
hook Package hook implements the Compiled Hook System for AE-ADK Go Edition.	Package hook implements the Compiled Hook System for AE-ADK Go Edition.
hook/agents
hook/lifecycle Package lifecycle provides session lifecycle utilities for AE-ADK.	Package lifecycle provides session lifecycle utilities for AE-ADK.
hook/memo
hook/mx Package mx provides MX tag auto-validation for Go source files.	Package mx provides MX tag auto-validation for Go source files.
hook/quality
hook/security Package security provides AST-Grep based security scanning for Claude Code hooks.	Package security provides AST-Grep based security scanning for Claude Code hooks.
i18n Package i18n provides multilingual comment generation for GitHub issue automation.	Package i18n provides multilingual comment generation for GitHub issue automation.
loop Package loop implements the Ralph Feedback Loop Engine state machine, persistence, and lifecycle management for AE-ADK.	Package loop implements the Ralph Feedback Loop Engine state machine, persistence, and lifecycle management for AE-ADK.
lsp Package lsp provides a Language Server Protocol (LSP) client system for communicating with language servers using JSON-RPC 2.0 over stdio or TCP.	Package lsp provides a Language Server Protocol (LSP) client system for communicating with language servers using JSON-RPC 2.0 over stdio or TCP.
lsp/hook Package hook provides LSP diagnostics integration for AE-ADK hooks.	Package hook provides LSP diagnostics integration for AE-ADK hooks.
manifest Package manifest provides file provenance tracking and change detection for the AE-ADK template deployment system.	Package manifest provides file provenance tracking and change detection for the AE-ADK template deployment system.
merge Package merge provides a 3-way merge engine for template files.	Package merge provides a 3-way merge engine for template files.
platform
profile
resilience Package resilience provides resilience patterns for external service integration.	Package resilience provides resilience patterns for external service integration.
shell Package shell provides shell detection, environment configuration, and PATH diagnostics for AE-ADK.	Package shell provides shell detection, environment configuration, and PATH diagnostics for AE-ADK.
statusline Package statusline implements the AE-ADK statusline rendering system for Claude Code integration.	Package statusline implements the AE-ADK statusline rendering system for Claude Code integration.
template Package template provides template deployment and rendering for AE projects.	Package template provides template deployment and rendering for AE projects.
tmux Package tmux provides tmux session management for parallel SPEC development.	Package tmux provides tmux session management for parallel SPEC development.
ui Package ui provides terminal UI components for AE-ADK Go Edition.	Package ui provides terminal UI components for AE-ADK Go Edition.
update Package update provides self-update functionality for the AE-ADK binary.	Package update provides self-update functionality for the AE-ADK binary.
workflow Package workflow orchestrates AE development workflows across Git worktrees.	Package workflow orchestrates AE development workflows across Git worktrees.
pkg
models @MX:NOTE: [AUTO] Defines development methodology modes.	@MX:NOTE: [AUTO] Defines development methodology modes.
version Package version provides build-time version information for AE-ADK.	Package version provides build-time version information for AE-ADK.