Espanso Dynamic Forms

Agent Tooling

This repository contains portable agent tooling: dual-host plugin packages, host-agnostic skill payloads, Rust-backed launchers, and repo harness scripts.

Repository layout

Top-level plugins/ contains plugin packages that may bundle skills, hooks, MCP servers, apps, and host manifests. Top-level skills/ is kept with .gitkeep for future standalone, host-agnostic skill packages that are not distributed as plugins.

WHEN adding a plugin package to this repository THEN you SHALL place it under plugins/<plugin-name>/. WHEN adding reusable skill content that is not a plugin package THEN you SHALL place it under skills/<skill-name>/. WHEN a plugin bundles skill instructions THEN you SHALL keep those bundled skills inside the plugin package's own skills/ directory.

Marketplace manifests:

• Codex: .agents/plugins/marketplace.json
• Claude: .claude-plugin/marketplace.json

Current local plugins:

• plugins/code-review/
• plugins/docker-architect/
• plugins/espanso-dynamic-forms/
• plugins/excel-foundry/
• plugins/friction-diagnostics/
• plugins/gitops-workflow/
• plugins/goal-foundry/ exposes goal-foundry for both Codex and Claude and bundles the agnostic $authoring-goals skill payload.
• plugins/playwright-testing/
• plugins/project-harness/
• plugins/rust-development/
• plugins/skill-auditor/

Plugin Packages

code-review

Unified code review skill with two workflows:

• Reviewer: perform adversarial code reviews using UACRP and produce a structured review report
• Applicator: apply review feedback from completed reports and track dispositions/progress

Both workflows coordinate artifacts under .local/reports/code_reviews/{YYYY-MM-DD}/ and use a bundled mpcr tool for deterministic reviewer/session operations (ID generation, locking, session JSON updates, report writing).

Path: plugins/code-review/skills/code-review/

Migration note: perform-code-review and apply-code-review were consolidated into code-review. Update any tooling or docs that reference skills/perform-code-review/ or skills/apply-code-review/ to use plugins/code-review/skills/code-review/.

docker-architect

Deterministic Docker architecture skill spanning both Compose/Swarm deployment design and image supply-chain planning with strict output ordering and traceability IDs (AC-*, IMG-*, RSK-*, O-*).

• Compose/Swarm workflow via plugins/docker-architect/skills/docker-architect/scripts/docker-architect-compose (packaged-binary launcher)
• Image/build workflow via plugins/docker-architect/skills/docker-architect/scripts/docker-architect-image (packaged-binary launcher)
• API-first image metadata refresh with optional scraping fallback
• Cached deterministic render/check workflow for reproducible outputs

Path: plugins/docker-architect/skills/docker-architect/

Plugin portability converter

scripts/plugin_port.py converts Codex and Claude Code plugin packages and marketplaces while preserving source trees and writing a conversion report to .plugin-portability/report.json.

Common commands:

• python3 scripts/plugin_port.py inspect <path> --format json|md [--from codex|claude]
• python3 scripts/plugin_port.py convert <plugin-dir> --to codex|claude --out <output-dir> --mode strict|best-effort [--summary full|json|md]
• python3 scripts/plugin_port.py convert-marketplace <marketplace-root-or-json> --to codex|claude --out <output-dir> [--summary full|json|md]
• python3 scripts/plugin_port.py validate <plugin-dir> --host codex|claude [--require-external-validator] [--summary full|json|md]
• python3 scripts/plugin_port.py roundtrip <plugin-dir> --to codex|claude --tmp <work-dir> [--summary full|json|md]

Compatibility contract:

• Supported active surfaces: plugin detection, plugin/marketplace inspection, Codex skills, Claude skills, Claude commands converted to Codex skills, basic manifests, local marketplaces, MCP path normalization, and hook placeholder normalization.
• Preserved-only surfaces: Codex apps and plugin-root CLAUDE.md files when targeting Claude; Claude LSP/output styles/themes/monitors/bin/settings when targeting Codex. Root CLAUDE.md files are moved to .plugin-portability/preserved/CLAUDE.md in Claude output because Claude plugin validation rejects plugin-root context files.
• Strict rejection surfaces: unsupported hook events, async command hooks, handler-level hook filters, non-command hook handlers, invalid JSON/YAML, non-local marketplace entries, and marketplace paths that escape the marketplace root.
• Best-effort behavior: the source tree is still copied, but semantic loss is recorded in unsupported, preserved_only, and executable_surfaces. Invalid skill, command, or agent frontmatter is repaired with generated target metadata only in best-effort conversion; validation still rejects malformed source frontmatter.