go-agent/CLAUDE.md

CLAUDE.md — go-agent

Overview

Agent orchestration and plugin marketplace. Combines AgentCI dispatch (Clotho dual-run verification, agent config, SSH security), the jobrunner pipeline (poll-dispatch-report loop with 7 handlers), and the plugin marketplace (27 Claude/Codex/Gemini plugins with shared MCP server).

Module: forge.lthn.ai/core/go-agent Extracted from: forge.lthn.ai/core/go-scm (agentci/ + jobrunner/) and forge.lthn.ai/agentic/plugins

Build & Test

go test ./... -v              # Run all tests (~150 tests)
go test -run TestName         # Run single test
go build ./cmd/mcp/           # Build marketplace MCP server

Architecture

go-agent/
├── clotho.go              # Clotho orchestrator: dual-run verification, run modes
├── config.go              # Agent config: YAML-driven agent target management
├── security.go            # SSH security: sanitisation, secure commands, token masking
│
├── jobrunner/             # Pipeline orchestration
│   ├── types.go           # PipelineSignal, ActionResult, JobSource/JobHandler interfaces
│   ├── poller.go          # Poll-dispatch-report loop
│   ├── journal.go         # JSONL audit log, date-partitioned
│   ├── forgejo/           # Forgejo JobSource: epic polling, signal building
│   │   ├── source.go
│   │   └── signals.go
│   └── handlers/          # 7 JobHandler implementations
│       ├── dispatch.go        # SSH ticket dispatch to agent machines
│       ├── completion.go      # Post-completion label management
│       ├── enable_auto_merge.go
│       ├── publish_draft.go
│       ├── resolve_threads.go
│       ├── send_fix_command.go
│       └── tick_parent.go     # Epic checklist progress
│
├── cmd/mcp/               # Marketplace MCP server (standalone binary)
│   ├── main.go
│   ├── server.go          # 4 MCP tools: marketplace_list, plugin_info, core_cli, ethics_check
│   ├── marketplace.go
│   ├── plugin_info.go
│   ├── core_cli.go
│   ├── ethics.go
│   ├── types.go
│   └── util.go
│
├── claude/                # 11 Claude Code plugins (shell scripts + JSON config)
├── codex/                 # 14 Codex plugins + ethics kernel
└── google/                # Gemini CLI extension + MCP wrapper

Key Types

// Root package (agent orchestration)
type Spinner struct { Config ClothoConfig; Agents map[string]AgentConfig }
type RunMode string // "standard" or "dual"
type AgentConfig struct { Host, QueueDir, ForgejoUser, Model, Runner, VerifyModel string; ... }
type ClothoConfig struct { Strategy string; ValidationThreshold float64; SigningKeyPath string }

// jobrunner package
type PipelineSignal struct { EpicNumber, ChildNumber, PRNumber int; RepoOwner, RepoName string; ... }
type JobSource interface { Name() string; Poll(ctx) ([]PipelineSignal, error); Report(ctx, signal, result) error }
type JobHandler interface { Name() string; Match(signal) bool; Execute(ctx, signal) (*ActionResult, error) }
type Poller struct { ... } // poll-dispatch-report loop
type Journal struct { ... } // JSONL audit log

Test Naming

_Good, _Bad, _Ugly suffix pattern. Tests use mock HTTP servers for Forgejo API.

Coding Standards

• UK English in comments
• Co-Authored-By: Virgil <virgil@lethean.io> in commits
• Errors wrapped with context
• Path traversal protection on all user-supplied paths

Dependencies

• forge.lthn.ai/core/go/pkg/config — YAML config management
• forge.lthn.ai/core/go/pkg/log — Structured logging
• forge.lthn.ai/core/go-scm/forge — Forgejo API client (will migrate to go-forge)
• codeberg.org/mvdkleijn/forgejo-sdk/forgejo/v2 — Forgejo SDK types
• github.com/mark3labs/mcp-go — MCP server (cmd/mcp only)

Forge Remote

git remote add forge ssh://git@forge.lthn.ai:2223/core/go-agent.git

Plugin Installation

claude plugin add core/go-agent                    # All 27 plugins
claude plugin add core/go-agent/claude/code        # Specific plugin