61e01bfdf1
Consolidates three codebases into a single agent orchestration repo: - agentci (from go-scm): Clotho dual-run verification, agent config, SSH security (sanitisation, secure commands, token masking) - jobrunner (from go-scm): Poll-dispatch-report pipeline with 7 handlers (dispatch, completion, auto-merge, publish draft, dismiss reviews, send fix command, tick parent epic) - plugins marketplace (from agentic/plugins): 27 Claude/Codex/Gemini plugins with shared MCP server All 150+ tests passing across 6 packages. Co-Authored-By: Virgil <virgil@lethean.io>
104 lines
4.1 KiB
Markdown
104 lines
4.1 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```go
|
|
// 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
|
|
|
|
```bash
|
|
git remote add forge ssh://git@forge.lthn.ai:2223/core/go-agent.git
|
|
```
|
|
|
|
## Plugin Installation
|
|
|
|
```bash
|
|
claude plugin add core/go-agent # All 27 plugins
|
|
claude plugin add core/go-agent/claude/code # Specific plugin
|
|
```
|