diff --git a/docs/tools/agent/claude.md b/docs/tools/agent/claude.md new file mode 100644 index 0000000..2bc4494 --- /dev/null +++ b/docs/tools/agent/claude.md @@ -0,0 +1,177 @@ +--- +title: Claude Code Plugins +description: Claude Code plugin marketplace, installation, and command reference for the Core platform. +--- + +# Claude Code Plugins + +Core Agent provides a **plugin marketplace** for Claude Code with development workflows, code review, verification, and language-specific tooling. + + +## Marketplace + +The marketplace is hosted in `core/agent` and distributed via npm as `@lthn/core-agent`. + +### Install the Marketplace + +```bash +# From npm (recommended for most users) +claude plugin marketplace add @lthn/core-agent + +# From git (Forge access) +claude plugin marketplace add https://forge.lthn.ai/core/agent.git +``` + +### Install All Plugins + +Once the marketplace is added, install plugins individually: + +```bash +claude plugin install code@core-agent +claude plugin install review@core-agent +claude plugin install verify@core-agent +claude plugin install core-php@core-agent +claude plugin install go-build@core-agent +claude plugin install devops@core-agent +``` + + +## Plugins + +### code + +Development hooks, auto-approve workflow, and research data collection. + +| Type | Name | Description | +|------|------|-------------| +| Command | `/remember` | Save context to memory | +| Command | `/yes` | Auto-approve workflow | +| Skill | `bitcointalk` | BitcoinTalk forum research | +| Skill | `block-explorer` | Block explorer data collection | +| Skill | `coinmarketcap` | CoinMarketCap data collection | +| Skill | `community-chat` | Community chat research | +| Skill | `cryptonote-discovery` | CryptoNote project discovery | +| Skill | `github-history` | GitHub history research | +| Skill | `job-collector` | Job posting collection | +| Skill | `ledger-papers` | Academic paper archive (crypto/blockchain) | +| Skill | `mining-pools` | Mining pool research | +| Skill | `project-archaeology` | Dead project salvage reports | +| Skill | `wallet-releases` | Wallet release tracking | +| Skill | `whitepaper-archive` | Whitepaper collection | + +**Source:** `core/agent` · **npm:** `@lthn/core-agent` + +--- + +### review + +Code review automation with multi-agent pipeline. + +| Type | Name | Description | +|------|------|-------------| +| Command | `/review` | Perform code review on staged changes or PRs | +| Command | `/security` | Security-focused code review | +| Command | `/pr` | Review a pull request | +| Command | `/pipeline` | Run the 5-agent review pipeline | +| Skill | `architecture-review` | Architecture-level review | +| Skill | `reality-check` | Sanity check implementation against intent | +| Skill | `security-review` | Security vulnerability analysis | +| Skill | `senior-dev-fix` | Senior developer fix suggestions | +| Skill | `test-analysis` | Test coverage and quality analysis | + +**Source:** `core/agent` · **npm:** `@lthn/core-agent` + +--- + +### verify + +Work verification before committing. + +| Type | Name | Description | +|------|------|-------------| +| Command | `/verify` | Verify work is complete before stopping | +| Command | `/ready` | Quick check if work is ready to commit | +| Command | `/tests` | Verify tests pass for changed files | + +**Source:** `core/agent` · **npm:** `@lthn/core-agent` + +--- + +### core-php + +PHP/Laravel development skills and API generation. + +| Type | Name | Description | +|------|------|-------------| +| Command | `/api-generate` | Generate TypeScript/JavaScript API client from Laravel routes | +| Skill | `php` | PHP development conventions and patterns | +| Skill | `laravel` | Laravel framework patterns | +| Skill | `php-agent` | PHP agent development guidance | + +**Source:** `core/php` · **npm:** `@lthn/core-claude-php` + +--- + +### go-build + +Go QA pipeline and build tooling. + +| Type | Name | Description | +|------|------|-------------| +| Command | `/qa` | Run full QA pipeline and fix all issues iteratively | +| Command | `/check` | Run QA checks without fixing (report only) | +| Command | `/fix` | Fix a specific QA issue | +| Command | `/lint` | Run linter and fix issues | + +**Source:** `core/go-build` · **npm:** `@lthn/core-claude-build` + +--- + +### devops + +CI/CD, deployment, and issue tracking. + +| Type | Name | Description | +|------|------|-------------| +| Command | `/ci` | Check CI status and manage workflows | +| Command | `/ci-status` | Show CI status for current branch | +| Command | `/ci-run` | Trigger a CI workflow run | +| Command | `/ci-fix` | Analyse and fix failing CI | +| Command | `/ci-workflow` | Create or update CI workflow | +| Command | `/coolify-deploy` | Deploy a service to Coolify | +| Command | `/coolify-status` | Check Coolify deployment status | +| Command | `/issue-list` | List open issues | +| Command | `/issue-view` | View issue details | +| Command | `/issue-start` | Start working on an issue | +| Command | `/issue-close` | Close an issue with a commit | + +**Source:** `core/go-devops` · **npm:** `@lthn/core-claude-devops` + + +## npm Packages + +All plugins are published to npm under the `@lthn` scope for public distribution: + +| Package | Plugin | Version | +|---------|--------|---------| +| `@lthn/core-agent` | Marketplace (code, review, verify) | 0.2.0 | +| `@lthn/core-claude-php` | core-php | 0.1.0 | +| `@lthn/core-claude-build` | go-build | 0.1.0 | +| `@lthn/core-claude-devops` | devops | 0.1.0 | + + +## Plugin Development + +Plugins live in `.claude-plugin/` directories within their source repositories. Each plugin has: + +- `plugin.json` -- manifest with name, description, version +- `commands/` -- slash command markdown files (auto-discovered) +- `skills/` -- skill directories with `SKILL.md` files (auto-discovered) +- `hooks.json` -- optional event hooks + +See the [Claude Code plugin documentation](https://code.claude.com/docs/en/plugins) for the full specification. + + +## Licence + +EUPL-1.2 diff --git a/docs/tools/agent/codex.md b/docs/tools/agent/codex.md new file mode 100644 index 0000000..720eefc --- /dev/null +++ b/docs/tools/agent/codex.md @@ -0,0 +1,77 @@ +--- +title: OpenAI Codex Plugins +description: OpenAI Codex plugin structure and command reference for the Core platform. +--- + +# OpenAI Codex Plugins + +Core Agent includes a `codex/` directory that mirrors the Claude plugin structure for OpenAI Codex compatibility, with additional plugins for ethics, guardrails, and performance. + + +## Structure + +Codex plugins use `AGENTS.md` files for agent instructions (equivalent to Claude's `CLAUDE.md`). Each plugin directory contains commands and scripts. + +``` +codex/ ++-- AGENTS.md ++-- code/ # Core development ++-- review/ # Code review ++-- verify/ # Work verification ++-- qa/ # QA pipeline ++-- ci/ # CI/CD management ++-- issue/ # Issue tracking ++-- coolify/ # Coolify deployment ++-- api/ # API generation ++-- ethics/ # Ethics guardrails ++-- guardrails/ # Safety checks ++-- perf/ # Performance analysis ++-- awareness/ # Context awareness ++-- collect/ # Data collection ++-- core/ # Core framework +``` + + +## Plugins + +### Development + +| Plugin | Purpose | Key Commands | +|--------|---------|--------------| +| **code** | Development workflow | Research, data collection | +| **review** | Code review | Review, security, PR review | +| **verify** | Work verification | Verify, ready check, tests | + +### Quality + +| Plugin | Purpose | Key Commands | +|--------|---------|--------------| +| **qa** | QA pipeline | `qa`, `fix`, `check`, `lint` | +| **ci** | CI/CD management | `ci`, `status`, `run`, `fix`, `workflow` | + +### Operations + +| Plugin | Purpose | Key Commands | +|--------|---------|--------------| +| **issue** | Issue tracking | `list`, `view`, `start`, `close` | +| **coolify** | Coolify deployment | `deploy`, `status` | +| **api** | API generation | `generate` | + +### Safety + +| Plugin | Purpose | +|--------|---------| +| **ethics** | Ethical guardrails for agent actions | +| **guardrails** | Safety checks and boundaries | +| **perf** | Performance analysis and monitoring | +| **awareness** | Context awareness and self-reflection | + + +## Configuration + +Codex reads `AGENTS.md` at the repository root and within each plugin directory. No marketplace or install step is needed -- Codex discovers `AGENTS.md` files automatically. + + +## Licence + +EUPL-1.2 diff --git a/docs/tools/agent/gemini.md b/docs/tools/agent/gemini.md new file mode 100644 index 0000000..3dbfe2b --- /dev/null +++ b/docs/tools/agent/gemini.md @@ -0,0 +1,56 @@ +--- +title: Gemini CLI Extension +description: Google Gemini CLI extension for the Core platform. +--- + +# Gemini CLI Extension + +Core Agent includes a Gemini CLI extension (`google/gemini-cli/`) that provides tool integration for Google's Gemini CLI. + + +## Structure + +``` +google/gemini-cli/ ++-- gemini-extension.json # Extension manifest ++-- GEMINI.md # Agent instructions ++-- package.json # npm dependencies ++-- src/ # TypeScript source ++-- commands/ # Slash commands ++-- hooks/ # Event hooks +``` + + +## Installation + +The Gemini extension is a TypeScript package. Install dependencies and register it with Gemini CLI: + +```bash +cd core/agent/google/gemini-cli +npm install +``` + +Gemini CLI reads `GEMINI.md` at the repository root for agent instructions, similar to how Claude Code reads `CLAUDE.md`. + + +## MCP Server + +A separate HTTP MCP server (`google/mcp/`) provides Gemini-compatible tools: + +| Tool | Description | +|------|-------------| +| `core_go_test` | Run Go tests | +| `core_dev_health` | Check development environment health | +| `core_dev_commit` | Commit changes across repos | + +The MCP server listens on `:8080` and uses HTTP transport. + +```bash +# Start the MCP server +go run google/mcp/main.go +``` + + +## Licence + +EUPL-1.2 diff --git a/docs/tools/agent/index.md b/docs/tools/agent/index.md index 9ccf57e..9c3c149 100644 --- a/docs/tools/agent/index.md +++ b/docs/tools/agent/index.md @@ -87,21 +87,16 @@ The package auto-registers via Laravel's service provider discovery (`Core\Mod\A | `cmd/mcp/` | stdio (mcp-go) | `marketplace_list`, `marketplace_plugin_info`, `core_cli`, `ethics_check` | | `google/mcp/` | HTTP (:8080) | `core_go_test`, `core_dev_health`, `core_dev_commit` | -### Claude Code Plugins +### AI Platform Plugins -| Plugin | Path | Commands | -|--------|------|----------| -| **code** | `claude/code/` | `/code:remember`, `/code:yes`, `/code:qa` | -| **review** | `claude/review/` | `/review:review`, `/review:security`, `/review:pr` | -| **verify** | `claude/verify/` | `/verify:verify`, `/verify:ready`, `/verify:tests` | -| **qa** | `claude/qa/` | `/qa:qa`, `/qa:fix` | -| **ci** | `claude/ci/` | `/ci:ci`, `/ci:workflow`, `/ci:fix`, `/ci:run`, `/ci:status` | +Core Agent provides plugins for multiple AI coding assistants. Each platform has its own plugin format and distribution method. -Install all plugins: `claude plugin add host-uk/core-agent` - -### Codex Plugins - -The `codex/` directory mirrors the Claude plugin structure for OpenAI Codex, plus additional plugins for ethics, guardrails, performance, and issue management. +| Platform | Directory | Distribution | Details | +|----------|-----------|-------------|---------| +| **Claude Code** | `claude/` | npm marketplace (`@lthn/core-agent`) | [Claude Code Plugins](claude.md) | +| **OpenAI Codex** | `codex/` | `AGENTS.md` auto-discovery | [Codex Plugins](codex.md) | +| **Google Gemini** | `google/gemini-cli/` | TypeScript extension | [Gemini Extension](gemini.md) | +| **LEM** | *(integrated)* | Local inference | [LEM Integration](lem.md) | ### PHP Package diff --git a/docs/tools/agent/lem.md b/docs/tools/agent/lem.md new file mode 100644 index 0000000..a421670 --- /dev/null +++ b/docs/tools/agent/lem.md @@ -0,0 +1,68 @@ +--- +title: LEM Agent Integration +description: Lethean Evaluation Model agent integration for the Core platform. +--- + +# LEM Agent Integration + +LEM (Lethean Evaluation Model) is a locally-hosted AI model trained on the Core ecosystem. It integrates with the agent orchestration layer for on-device inference without external API dependencies. + + +## Overview + +LEM runs as a native macOS application (LEM Lab) or as a backend service, providing: + +- **Local inference** -- MLX-based, runs on Apple Silicon with no cloud dependency +- **Ecosystem knowledge** -- trained on Core framework documentation, patterns, and conventions +- **Cascade scoring** -- EaaS (Evaluation as a Service) for grading agent outputs +- **Poindexter spatial indexing** -- KDTree/cosine similarity for knowledge gap detection + + +## Integration Points + +### Agent Dispatch + +The agent orchestration layer (`pkg/lifecycle/`) can dispatch work to LEM instances alongside Claude, Gemini, and Codex. LEM is registered as an agent in the fleet registry. + +### MCP Tools + +LEM exposes tools via the Model Context Protocol, making them available to other agents in the fleet: + +| Tool | Description | +|------|-------------| +| `lem_evaluate` | Score a response using the EaaS cascade | +| `lem_embed` | Generate embeddings for knowledge indexing | +| `lem_chat` | Local chat completion | + +### Scorer Binary + +The LEM scorer binary (`core-lem`) can be invoked as a subprocess from the PHP platform: + +```bash +# Score a response against criteria +core-lem score --input response.txt --criteria accuracy,completeness +``` + +The PHP module (`app/Mod/Lem/`) wraps this via `proc_open` for integration with the Laravel application. + + +## Community Compute + +LEM is designed for distributed evaluation across community-donated compute: + +1. **Local-first** -- each contributor runs LEM on their own hardware +2. **No API keys required** -- MLX inference runs entirely on-device +3. **Federated scoring** -- results are aggregated without sharing raw data +4. **Google Developer credits** -- contributors can donate their API credits for cloud-based model access + + +## Requirements + +- macOS with Apple Silicon (M1+) for MLX inference +- 16 GB RAM minimum (32 GB recommended for larger models) +- Core CLI (`core` binary) for build and orchestration + + +## Licence + +EUPL-1.2 diff --git a/zensical.toml b/zensical.toml index d4ffa61..4a8fcd0 100644 --- a/zensical.toml +++ b/zensical.toml @@ -204,6 +204,10 @@ nav = [ "tools/index.md", {"Agent" = [ "tools/agent/index.md", + "tools/agent/claude.md", + "tools/agent/codex.md", + "tools/agent/gemini.md", + "tools/agent/lem.md", ]}, {"MCP" = [ "tools/mcp/index.md",