Develop and Extend

Purpose

Understand AE package boundaries, services, and ports so you can extend or debug the core, CLI, or MCP adapter safely.

Prerequisites

• Dart toolchain and repo checkout (see Local development below).

Summary

AE is split into core, CLI, and MCP adapter packages.

Architecture map

Package structure

• agentic_executables_core/: typed business logic, ports, adapters, and service contracts
• agentic_executables_cli/: ae executable interface
• agentic_executables_mcp/: MCP-facing adapter

Capability model

                    ┌→ Implement directly (human/agent reads knowledge)
ae know build ──────┤
                    └→ ae generate --know ──┬→ hub/use/{project}/
                                            └→ ae package (optional)

Core service map

Service	Purpose
AeHubService	Hub init, status, pull, push
AeKnowService	Build, list, show, remove, update, diff knowledge packs
AeGenerationService	Generate ae_use files (template or inference engine)
AeRegistryService	Fetch/submit to remote registry
AeInstructionService	Load context-appropriate prompt documents
AeValidationService	Verify and evaluate AE compliance

Port/adapter pattern

All external I/O flows through ports (interfaces) with swappable adapters:

• HubResolver → FileHubResolver
• KnowledgeExtractor → PassthroughExtractor, UrlExtractor, RepoExtractor
• KnowledgeStore → FileKnowledgeStore
• RegistryClient → GitHubRawRegistryClient
• GenerationEngine → TemplateGenerationEngine, InferenceGenerationEngine

Local development

cd agentic_executables_core && dart test
cd ../agentic_executables_cli && dart test
cd ../agentic_executables_mcp && dart test

Design and DX references

• Design FAQ
• DX FAQ
• Architecture diagram

Verify

dart test passes in agentic_executables_core, agentic_executables_cli, and agentic_executables_mcp after your change.

If it fails

See failing package tests and Troubleshooting for environment issues.

Contribution rule for docs quality

Any CLI or MCP behavior change must update:

1. Get Started or Install docs if onboarding impact exists.
2. Error/recovery docs when new codes or failure modes are introduced.
3. Agent contract docs when payload shape changes.