How Forge Works

SKILL.md --> Parse --> Discover tools/requirements --> Compile AgentSpec
                                                            |
                                                            v
                                                    Apply security policy
                                                            |
                                                            v
                                                    Run LLM agent loop
                                               (tool calling + memory + cron)

go.work
├── forge-core/       Embeddable library
├── forge-cli/        CLI frontend
├── forge-plugins/    Channel plugin implementations
├── forge-ui/         Local web dashboard
└── forge-skills/     Skill system (registry, parser, compiler)

func Compile(req CompileRequest) (*CompileResult, error)
func ValidateConfig(cfg *types.ForgeConfig) *validate.ValidationResult
func ValidateAgentSpec(jsonData []byte) ([]string, error)
func ValidateCommandCompat(spec *agentspec.AgentSpec) *validate.ValidationResult
func SimulateImport(spec *agentspec.AgentSpec) *validate.ImportSimResult
func NewRuntime(cfg RuntimeConfig) *runtime.LLMExecutor

type AgentExecutor interface {
    Execute(ctx context.Context, task *a2a.Task, msg *a2a.Message) (*a2a.Message, error)
    ExecuteStream(ctx context.Context, task *a2a.Task, msg *a2a.Message) (<-chan *a2a.Message, error)
    Close() error
}

type Client interface {
    Chat(ctx context.Context, req *ChatRequest) (*ChatResponse, error)
    ChatStream(ctx context.Context, req *ChatRequest) (<-chan StreamDelta, error)
    ModelID() string
}

type Tool interface {
    Name() string
    Description() string
    Category() Category
    InputSchema() json.RawMessage
    Execute(ctx context.Context, args json.RawMessage) (string, error)
}

type ToolExecutor interface {
    Execute(ctx context.Context, name string, arguments json.RawMessage) (string, error)
    ToolDefinitions() []llm.ToolDefinition
}

type ChannelPlugin interface {
    Name() string
    Init(cfg ChannelConfig) error
    Start(ctx context.Context, handler EventHandler) error
    Stop() error
    NormalizeEvent(raw []byte) (*ChannelEvent, error)
    SendResponse(event *ChannelEvent, response *a2a.Message) error
}

type Stage interface {
    Name() string
    Execute(ctx context.Context, bc *BuildContext) error
}

type FrameworkPlugin interface {
    Name() string
    DetectProject(dir string) (bool, error)
    ExtractAgentConfig(dir string) (*AgentConfig, error)
    GenerateWrapper(config *AgentConfig) ([]byte, error)
    RuntimeDependencies() []string
}

forge.yaml
  → config.Load()                         [forge-cli/config]
  → types.ForgeConfig                     [forge-core/types]
  → validate.ValidateForgeConfig()        [forge-core/validate]
  → skills.Compile()                      [forge-core/skills]
  → compiler.Compile()                    [forge-core/compiler]
  → agentspec.AgentSpec + SecurityConfig  [forge-core/agentspec, forge-core/security]

forgecore.Compile(CompileRequest) → CompileResult

AgentSpec + Tools
  → forgecore.NewRuntime(RuntimeConfig)   [forge-core/forgecore]
  → runtime.LLMExecutor                   [forge-core/runtime]
  → llm.Client (provider selection)       [forge-core/llm/providers]
  → Agent loop: prompt → LLM → tool calls → results → LLM → response
  → a2a.Message                           [forge-core/a2a]

forge run
  → config.Load()                         [forge-cli/config]
  → tools.Discover() + tools.Registry     [forge-cli/tools, forge-core/tools]
  → runtime.LLMExecutor                   [forge-core/runtime]
  → server.A2AServer                      [forge-cli/server]
  → channels.Router (optional)            [forge-cli/channels]

forge/
  forge-core/          Core library
    a2a/               A2A protocol types
    llm/               LLM client, fallback chains, OAuth
    memory/            Long-term memory (vector + keyword search)
    runtime/           Agent loop, hooks, compactor, audit logger
    scheduler/         Cron scheduler (parser, tick loop, overlap prevention)
    secrets/           Encrypted secret storage (AES-256-GCM + Argon2id)
    security/          Egress resolver, enforcer, proxy, K8s NetworkPolicy
    tools/             Tool registry, builtins, adapters, skill_tool
    types/             Config types
  forge-cli/           CLI application
    cmd/               CLI commands (init, build, run, serve, schedule, etc.)
    runtime/           Runner, skill registration, scheduler store, subprocess executor
    internal/tui/      Interactive init wizard (Bubbletea)
    tools/             CLI-specific tools (cli_execute, skill executor)
  forge-plugins/       Channel plugins
    telegram/          Telegram adapter (polling, document upload)
    slack/             Slack adapter (Socket Mode, file upload)
    markdown/          Markdown converter, message splitting
  forge-ui/            Local web dashboard
    server.go          HTTP server, routing, CORS
    handlers*.go       REST API (agents, config, wizard, skills)
    process.go         Agent process manager
    discovery.go       Workspace scanner
    sse.go             Real-time event broker
    chat.go            A2A streaming chat proxy
    static/dist/       Embedded SPA (Preact + HTM + Monaco)
  forge-skills/        Skill system
    contract/          Skill types, registry interface, filtering
    local/             Embedded + local skill registries
    parser/            SKILL.md parser (frontmatter + body extraction)
    compiler/          Skill compiler (prompt generation)
    requirements/      Requirement aggregation and derivation
    analyzer/          Security audit for skills
    resolver/          Binary and env var resolution
    trust/             Skill signing and verification