diff --git a/.agents/skills/deploy/SKILL.md b/.agents/skills/deploy/SKILL.md new file mode 100644 index 0000000..90229b3 --- /dev/null +++ b/.agents/skills/deploy/SKILL.md @@ -0,0 +1,7 @@ +--- +name: deploy +description: Deploy to homelab. Build Docker image, transfer, and restart container. Use for lthn.sh deployments. +--- + +Use the core-agent MCP tools to execute this skill. +Call the appropriate tool: See deployment skill instructions diff --git a/.agents/skills/dispatch/SKILL.md b/.agents/skills/dispatch/SKILL.md new file mode 100644 index 0000000..ade1b5f --- /dev/null +++ b/.agents/skills/dispatch/SKILL.md @@ -0,0 +1,7 @@ +--- +name: dispatch +description: Dispatch a subagent to work on a task in a sandboxed workspace. Use when you need to send work to Gemini, Codex, or Claude agents. +--- + +Use the core-agent MCP tools to execute this skill. +Call the appropriate tool: agentic_dispatch diff --git a/.agents/skills/pipeline/SKILL.md b/.agents/skills/pipeline/SKILL.md new file mode 100644 index 0000000..cf86637 --- /dev/null +++ b/.agents/skills/pipeline/SKILL.md @@ -0,0 +1,7 @@ +--- +name: pipeline +description: Run the review-fix-verify pipeline on code changes. Dispatches reviewer, then fixer, then verifier. +--- + +Use the core-agent MCP tools to execute this skill. +Call the appropriate tool: agentic_dispatch reviewer → wait → agentic_dispatch fixer → wait → verify diff --git a/.agents/skills/recall/SKILL.md b/.agents/skills/recall/SKILL.md new file mode 100644 index 0000000..7d9cfee --- /dev/null +++ b/.agents/skills/recall/SKILL.md @@ -0,0 +1,7 @@ +--- +name: recall +description: Search OpenBrain for memories and context. Use when you need prior session knowledge or architecture context. +--- + +Use the core-agent MCP tools to execute this skill. +Call the appropriate tool: brain_recall diff --git a/.agents/skills/remember/SKILL.md b/.agents/skills/remember/SKILL.md new file mode 100644 index 0000000..ce18996 --- /dev/null +++ b/.agents/skills/remember/SKILL.md @@ -0,0 +1,7 @@ +--- +name: remember +description: Save a fact or decision to OpenBrain. Use to persist knowledge across sessions. +--- + +Use the core-agent MCP tools to execute this skill. +Call the appropriate tool: brain_remember diff --git a/.agents/skills/review/SKILL.md b/.agents/skills/review/SKILL.md new file mode 100644 index 0000000..e26dbb0 --- /dev/null +++ b/.agents/skills/review/SKILL.md @@ -0,0 +1,7 @@ +--- +name: review +description: Review completed agent workspace. Show output, git diff, and merge options. Use after an agent completes a task. +--- + +Use the core-agent MCP tools to execute this skill. +Call the appropriate tool: agentic_status + read agent log + git diff diff --git a/.agents/skills/scan/SKILL.md b/.agents/skills/scan/SKILL.md new file mode 100644 index 0000000..1a4c775 --- /dev/null +++ b/.agents/skills/scan/SKILL.md @@ -0,0 +1,7 @@ +--- +name: scan +description: Scan Forge repos for open issues with actionable labels. Use to find work to dispatch. +--- + +Use the core-agent MCP tools to execute this skill. +Call the appropriate tool: agentic_scan diff --git a/.agents/skills/status/SKILL.md b/.agents/skills/status/SKILL.md new file mode 100644 index 0000000..7aadb78 --- /dev/null +++ b/.agents/skills/status/SKILL.md @@ -0,0 +1,7 @@ +--- +name: status +description: Show status of all agent workspaces (running, completed, blocked, failed). Use to check pipeline progress. +--- + +Use the core-agent MCP tools to execute this skill. +Call the appropriate tool: agentic_status diff --git a/.agents/skills/sweep/SKILL.md b/.agents/skills/sweep/SKILL.md new file mode 100644 index 0000000..d816dc4 --- /dev/null +++ b/.agents/skills/sweep/SKILL.md @@ -0,0 +1,7 @@ +--- +name: sweep +description: Batch audit across all repos using agent dispatch. Use for ecosystem-wide convention checks. +--- + +Use the core-agent MCP tools to execute this skill. +Call the appropriate tool: agentic_dispatch in a loop across repos diff --git a/.codex/agents/fixer.toml b/.codex/agents/fixer.toml new file mode 100644 index 0000000..b93c664 --- /dev/null +++ b/.codex/agents/fixer.toml @@ -0,0 +1,25 @@ +# Review Findings Fixer +# Implements fixes from reviewer findings + +name = "fixer" +description = "Fix code review findings. Takes a list of findings with file:line references and implements the fixes. Creates EXCEPTIONS.md for items that cannot be fixed." +developer_instructions = """ +You are the Review Findings Fixer for the Core ecosystem. + +You receive a list of findings from the reviewer agent. +For each finding: +1. Read the file at the specified line +2. Implement the fix following Core conventions +3. If a fix is impossible (e.g. circular import), add to EXCEPTIONS.md with reason + +After fixing: +- Run go build ./... to verify +- Run go vet ./... to verify +- Run go test ./... if tests exist + +Commit message format: fix(pkg): description of fixes + +Do not add features. Do not refactor beyond the finding. Minimal changes only. +""" +model = "gpt-5.4" +sandbox_mode = "workspace-write" diff --git a/.codex/agents/migrator.toml b/.codex/agents/migrator.toml new file mode 100644 index 0000000..521d4ff --- /dev/null +++ b/.codex/agents/migrator.toml @@ -0,0 +1,32 @@ +# Core Primitives Migrator +# Migrates packages from separate deps to Core built-ins + +name = "migrator" +description = "Migrate Go packages to use Core primitives instead of separate go-io/go-log/strings/fmt packages. Use when upgrading a package to the new Core API." +developer_instructions = """ +You are the Core Primitives Migrator for the Core ecosystem. + +Read .core/reference/RFC-025-AGENT-EXPERIENCE.md for the AX spec. +Read .core/reference/*.go for the Core framework API. + +Migration pattern: +- coreio.Local.Read(path) → fs.Read(path) returning core.Result +- coreio.Local.Write(path, s) → fs.Write(path, s) returning core.Result +- coreio.Local.List(path) → fs.List(path) returning core.Result +- coreio.Local.EnsureDir(path) → fs.EnsureDir(path) returning core.Result +- coreio.Local.IsFile(path) → fs.IsFile(path) returning bool +- coreio.Local.Delete(path) → fs.Delete(path) returning core.Result +- coreerr.E("op", "msg", err) → core.E("op", "msg", err) +- log.Error/Info/Warn → core.Error/Info/Warn +- strings.Contains → core.Contains +- strings.Split → core.Split +- strings.TrimSpace → core.Trim +- strings.HasPrefix → core.HasPrefix +- fmt.Sprintf → core.Sprintf +- embed.FS → core.Mount() + core.Embed + +Add AX usage-example comments to all public types and functions. +Build must pass after migration. +""" +model = "gpt-5.4" +sandbox_mode = "workspace-write" diff --git a/.codex/agents/reviewer.toml b/.codex/agents/reviewer.toml new file mode 100644 index 0000000..4a08ea5 --- /dev/null +++ b/.codex/agents/reviewer.toml @@ -0,0 +1,28 @@ +# AX Convention Reviewer +# Audits code against RFC-025 Agent Experience spec + +name = "reviewer" +description = "Audit Go code against AX conventions (RFC-025). Use for code review, convention checking, and quality assessment. Read-only — never modifies code." +developer_instructions = """ +You are the AX Convention Reviewer for the Core ecosystem. + +Read .core/reference/RFC-025-AGENT-EXPERIENCE.md for the full spec. +Read .core/reference/*.go for the Core framework API. + +Audit all Go files against these conventions: +1. Predictable names — no abbreviations (Cfg→Config, Srv→Service) +2. Comments as usage examples — show HOW with real values +3. Result pattern — core.Result not (value, error) +4. Error handling — core.E("op", "msg", err) not fmt.Errorf +5. Core string ops — core.Contains/Split/Trim not strings.* +6. Core logging — core.Error/Info/Warn not log.* +7. Core filesystem — core.Fs{} not os.ReadFile +8. UK English — initialise not initialize +9. Import aliasing — stdlib io as goio +10. Compile-time assertions — var _ Interface = (*Impl)(nil) + +Report findings with severity (critical/high/medium/low) and file:line. +Group by package. Do NOT fix — report only. +""" +model = "gpt-5.4" +sandbox_mode = "read-only" diff --git a/.codex/config.toml b/.codex/config.toml new file mode 100644 index 0000000..38e3771 --- /dev/null +++ b/.codex/config.toml @@ -0,0 +1,69 @@ +# Core Agent — Codex Configuration +# Shared between CLI and IDE extension + +model = "gpt-5.4" +model_reasoning_effort = "high" +approval_policy = "on-request" +sandbox_mode = "workspace-write" +personality = "pragmatic" + +# Default to LEM when available +# oss_provider = "ollama" + +[profiles.review] +model = "gpt-5.4" +model_reasoning_effort = "extra-high" +approval_policy = "never" +sandbox_mode = "read-only" + +[profiles.quick] +model = "gpt-5.4" +model_reasoning_effort = "low" +approval_policy = "never" + +[profiles.implement] +model = "gpt-5.4" +model_reasoning_effort = "high" +approval_policy = "never" +sandbox_mode = "workspace-write" + +[profiles.lem] +model = "lem-4b" +model_provider = "ollama" +model_reasoning_effort = "high" +approval_policy = "never" +sandbox_mode = "workspace-write" + +# Core Agent MCP Server +[mcp_servers.core-agent] +command = "core-agent" +args = ["mcp"] +required = true +startup_timeout_sec = 15 +tool_timeout_sec = 120 + +[mcp_servers.core-agent.env] +FORGE_TOKEN = "${FORGE_TOKEN}" +CORE_BRAIN_KEY = "${CORE_BRAIN_KEY}" +MONITOR_INTERVAL = "15s" + +# Local model providers +[model_providers.ollama] +name = "Ollama" +base_url = "http://127.0.0.1:11434/v1" + +[model_providers.lmstudio] +name = "LM Studio" +base_url = "http://127.0.0.1:1234/v1" + +# Agent configuration +[agents] +max_threads = 4 +max_depth = 1 +job_max_runtime_seconds = 600 + +# Features +[features] +multi_agent = true +shell_snapshot = true +undo = true diff --git a/.codex/rules/core-agent.rules b/.codex/rules/core-agent.rules new file mode 100644 index 0000000..ea16b44 --- /dev/null +++ b/.codex/rules/core-agent.rules @@ -0,0 +1,67 @@ +# Core Agent — Codex Rules +# Controls which commands can run outside the sandbox + +# Go toolchain — always safe +prefix_rule( + pattern = ["go", ["build", "test", "vet", "fmt", "mod", "get", "work"]], + decision = "allow", + justification = "Go development tools are safe read/build operations", + match = [["go", "build", "./..."], ["go", "test", "./pkg/agentic"]], + not_match = [["go", "run", "main.go"]], +) + +# Core agent binary +prefix_rule( + pattern = ["core-agent", ["mcp", "--version"]], + decision = "allow", + justification = "Core agent MCP server and version check", +) + +# Git read operations +prefix_rule( + pattern = ["git", ["status", "log", "diff", "branch", "tag", "remote", "fetch", "rev-parse", "ls-remote"]], + decision = "allow", + justification = "Read-only git operations are safe", +) + +# Git write — prompt for approval +prefix_rule( + pattern = ["git", ["add", "commit", "merge", "rebase", "stash"]], + decision = "prompt", + justification = "Git write operations need human approval", +) + +# Git push — forbidden (use PR workflow) +prefix_rule( + pattern = ["git", "push"], + decision = "forbidden", + justification = "Never push directly — use PR workflow via agentic_create_pr", +) + +# Git destructive — forbidden +prefix_rule( + pattern = ["git", ["reset", "clean"], "--force"], + decision = "forbidden", + justification = "Destructive git operations are never allowed", +) + +# Curl — prompt (network access) +prefix_rule( + pattern = ["curl"], + decision = "prompt", + justification = "Network requests need approval", +) + +# SSH — forbidden +prefix_rule( + pattern = ["ssh"], + decision = "forbidden", + justification = "Direct SSH is forbidden — use Ansible via deployment skills", +) + +# rm -rf — forbidden +prefix_rule( + pattern = ["rm", "-rf"], + decision = "forbidden", + justification = "Recursive force delete is never allowed", +) diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..a95169b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,76 @@ +# AGENTS.md — Core Agent + +This file provides guidance to Codex when working with code in this repository. + +## Project Overview + +Core Agent (`dappco.re/go/agent`) is the agent orchestration platform for the Core ecosystem. It provides an MCP server binary (`core-agent`) with tools for dispatching subagents, workspace management, cross-agent messaging, OpenBrain integration, and monitoring. + +## Architecture + +``` +cmd/main.go — Binary entry point, Core CLI (no cobra) +pkg/agentic/ — Dispatch, workspace prep, status, queue, plans, PRs, epics +pkg/brain/ — OpenBrain knowledge store (direct HTTP + IDE bridge) +pkg/monitor/ — Background monitoring, harvest, sync +pkg/lib/ — Embedded prompts, tasks, flows, personas, workspace templates +pkg/setup/ — Project detection, config generation, scaffolding +``` + +## Conventions + +This project follows the **AX (Agent Experience)** design principles from RFC-025. + +### Code Style +- **UK English**: colour, organisation, initialise (never American spellings) +- **Errors**: `core.E("operation", "message", err)` — never `fmt.Errorf` +- **Logging**: `core.Error/Info/Warn/Debug` — never `log.*` or `fmt.Print*` +- **Filesystem**: `core.Fs{}` with `Result` returns — never `os.ReadFile/WriteFile` +- **Strings**: `core.Contains/Split/Trim/HasPrefix/Sprintf` — never `strings.*` or `fmt.Sprintf` +- **Returns**: `core.Result{Value, OK}` — never `(value, error)` pairs +- **Comments**: Usage examples showing HOW with real values, not descriptions +- **Names**: Predictable, unabbreviated (Config not Cfg, Service not Srv) +- **Imports**: stdlib `io` aliased as `goio` +- **Interface checks**: `var _ Interface = (*Impl)(nil)` compile-time assertions + +### Build & Test +```bash +go build ./... +go test ./... +go vet ./... +``` + +### Branch Strategy +- Work on `dev` branch, never push to `main` directly +- PRs required for `main` — Codex review gate +- Commit format: `type(scope): description` +- Co-author: `Co-Authored-By: Virgil ` + +### Dependencies +- Only `dappco.re/go/core` for primitives (fs, errors, logging, strings) +- Domain packages: `process`, `ws`, `mcp` for actual services +- No `go-io`, `go-log`, `cli` — Core provides these natively +- Use `go get -u ./...` for dependency updates, never manual go.mod edits + +## MCP Tools + +The binary exposes these MCP tools when run as `core-agent mcp`: + +| Tool | Purpose | +|------|---------| +| `agentic_dispatch` | Dispatch subagent to sandboxed workspace | +| `agentic_status` | List workspace statuses | +| `agentic_resume` | Resume blocked/failed workspace | +| `agentic_prep_workspace` | Prepare workspace without dispatching | +| `agentic_create_pr` | Create PR from workspace | +| `agentic_list_prs` | List PRs across repos | +| `agentic_create_epic` | Create epic with child issues | +| `agentic_scan` | Scan Forge for actionable issues | +| `agentic_plan_*` | Plan CRUD (create, read, update, delete, list) | +| `brain_recall` | Semantic search OpenBrain | +| `brain_remember` | Store to OpenBrain | +| `brain_forget` | Remove from OpenBrain | +| `agent_send` | Send message to another agent | +| `agent_inbox` | Read inbox messages | +| `metrics_record` | Record metrics event | +| `metrics_query` | Query metrics |