# 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
```