mirror of
https://github.com/wshobson/agents
synced 2026-06-21 14:13:58 +00:00
main
11 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Seth Hobson
|
767d969a73 |
docs: sync plugin/agent/skill counts to 84/192/156 after social-publishing merge
PR #558 updated the headline totals but left trailing references at 83/191/155 across README, AGENTS.md, GEMINI.md, ARCHITECTURE.md, and docs/*. Sync them all to the true counts (82 local + 2 external = 84 plugins, 192 agents, 156 skills). Also runs make generate-all to bring the committed harness registries in sync — adds the social-publishing entries to .agents/ and .cursor-plugin/ (which the original PR could not regenerate) and fixes the stale count in the generated cursor manifests. Left round-trip-results.md (point-in-time CLI verification results) and plugin-eval.md (grade threshold) unchanged. |
||
|
Seth Hobson
|
9834a5f38d |
Add Pensyve external integration (#552)
* feat: add Pensyve external integration * docs: fix skill plugin count |
||
|
Seth Hobson
|
be57c0b2e3 |
feat: multi-harness plugin marketplace (Codex, Cursor, OpenCode, Gemini) (#541)
* feat(adapters): multi-harness framework + harness_portability eval dimension
Turn this Claude Code plugin marketplace into a generic agentic-harness
marketplace. Adapters under tools/adapters/ emit harness-native artifacts
for OpenAI Codex CLI, Cursor, OpenCode, and Gemini CLI from a single
Markdown source. Source-of-truth stays under plugins/ — Claude Code is
unchanged.
Framework (tools/adapters/):
- base.py — PluginSource parser, HarnessAdapter ABC, write/mirror helpers
(path-traversal guard, UTF-8-safe), inline-list + block-list + block-scalar
YAML-ish parser, _utf8_safe_cut, _split_inline_list, _normalize_author
- capabilities.py — per-harness capability matrix, TOOL_NAME_MAPS,
MODEL_ALIASES, resolve_model() with explicit warnings
- codex.py — emits .codex/{skills,agents}/ + AGENTS.md (≤150-line
table-of-contents). Fence-aware body splitter, _utf8_safe_cut for
multibyte safety, _yaml_scalar with reserved-word + special-char quoting.
Skill/command name collision detection (and second-order __cmd fallback).
- cursor.py — emits .cursor-plugin/{plugin,marketplace}.json + curated
.cursor/rules/*.mdc. _validate_mdc_frontmatter handles YAML block scalars
(no false positives on colons in description body). _normalize_author
handles dict, npm-style strings, and author lists.
- opencode.py — transpiles agents to .opencode/agents/<id>.md with
mode:subagent + permission: deny-everything-else block (skill/task always
allowed as base capabilities — Claude's implicit defaults).
- gemini.py — emits native skills/, agents/, and commands/ at extension
root (April 2026 spec). Tool-allowlist remapped via TOOL_NAME_MAPS.
CLI + tooling:
- tools/generate.py — unified `make generate HARNESS=<x> [PLUGIN=<y>]`,
with --clean (containment-guarded; case-insensitive on Darwin/Win32),
--prune (orphan removal across all per-harness output trees), --strict
(warnings fail), per-plugin error aggregation, refuses --clean --plugin
(would silently wipe other plugins' artifacts).
- tools/validate_generated.py — structural validation across all four
harness outputs. Codex 8KB cap → error. _extract_permission_block
correctly handles nested permission keys (column-0 only).
- tools/doc_gardener.py — recurring drift detection per OpenAI harness-
engineering principle. STALE_ARTIFACT (info), DEAD_LINK (error),
MARKETPLACE_ORPHAN (error), SKILL_OVER_CODEX_CAP (warning), grouped
output sorted by severity.
plugin-eval (extends existing framework):
- New harness_portability dimension (6% weight, rebalanced from existing
static sub-scores). Surfaces non-portable patterns with concrete
remediation hints: SKILL_OVER_CODEX_CAP, CLAUDE_TOOL_REFS,
CLAUDE_TOOL_PROSE, AGENT_NAME_COLLISION, BARE_MODEL_ALIAS.
- _CAMEL_TOOL_PATTERN requires Claude-tool context (no false positives
on Rust's `Task` etc.). _TOOL_PROSE_PATTERN case-sensitive on tool
names, case-insensitive on the leading article.
- Findings do NOT also feed anti_pattern_penalty (no double-counting).
Documentation:
- Top-level guides: CODEX.md, CURSOR.md, OPENCODE.md (≤150 lines each,
table-of-contents pattern per OpenAI harness-engineering post)
- docs/harnesses.md — capability matrix, graceful-degradation table,
generated output paths
- docs/authoring.md — portable-content style guide (tools, models,
collision rules, fence-respect)
- docs/round-trip-results.md — real-CLI verification recipes (OpenCode
discovers 193 subagents, Gemini extensions validate passes, Codex
TOMLs all parse)
- CONTRIBUTING.md — new file pointing at docs/authoring.md
- README.md — rewritten for multi-harness (145 lines, was 460)
- CLAUDE.md — trimmed to 60-line table-of-contents
- GEMINI.md — trimmed from 1500 to 500 tokens (3× over budget previously)
Tests: 181 passing (103 plugin-eval + 78 tools/tests). Real-CLI round-trip
verified for OpenCode, Gemini, and Codex (TOML parses).
Replaces tools/generate_gemini_commands.py with the unified CLI.
* refactor(skills): extract detail to references/details.md (~75 skills)
Apply Anthropic's canonical SKILL.md progressive-disclosure pattern across
the marketplace: SKILL.md body becomes a navigation tier (trigger phrasing
+ quick start), detailed templates and worked examples move to
references/details.md (loaded on demand by the agent).
Motivation: OpenAI Codex CLI hard-truncates skills at 8 KB. Before this
change, ~90 skills exceeded that cap and would silently break on Codex.
The progressive-disclosure pattern is also Anthropic's documented
recommendation for token efficiency — Claude Code reads references/ files
on demand when the body navigation says to.
What's extracted, by pattern:
- Pass 1 (## Templates section): 19 skills — full template libraries
moved to references/details.md
- Pass 2 (## Implementation Patterns / ## Advanced Patterns): 13 skills
- Pass 3 (everything between nav-tier and wrap-tier headings): 53 skills
- Conservative re-extraction for 8 skills that got over-reduced — kept
~6-7 KB inline (most of the quick-start tier) plus references/ overflow
What stays inline (SKILL.md navigation tier):
- description: frontmatter (triggering — unchanged for all skills)
- ## When to Use This Skill / ## Core Concepts / ## Quick Start
- ## Best Practices / ## Troubleshooting / ## See Also wrap-ups
- A pointer note ("see references/details.md") so the agent knows where
to look for detail
What goes to references/details.md (detail tier, on-demand load):
- ## Templates (full code template libraries)
- ## Implementation Patterns / ## Advanced Patterns (deep examples)
- Mid-skill walkthroughs that exceed the inline budget
Also in this commit:
- plugins/brand-landingpage description trimmed from 958→543 chars
(preserves trigger phrasing, drops verbose example-quote list)
Net effect:
- SKILL_OVER_CODEX_CAP findings: 90 → 10 (88% reduction)
- All triggers unchanged — discovery behavior identical across harnesses
- 75 new references/details.md files with the extracted content
- Same depth of guidance, loaded progressively
Remaining 10 oversized skills are complex multi-section docs (e.g.
postgresql, code-review-excellence, evaluation-methodology) that need
per-skill manual judgment — flagged by `make garden` for future work.
* chore: bump all plugin versions (multi-harness release)
Patch-bump every local plugin (81) in both .claude-plugin/marketplace.json
entries and each plugins/<name>/.claude-plugin/plugin.json. Minor-bump the
top-level marketplace metadata.version (1.6.0 → 1.7.0) to signal the
multi-harness adapter framework addition.
The external git-subdir entry (qa-orchestra) is unaffected — its version
is governed by its upstream repo.
* fix(opencode): preserve explicit tools:[] + word-boundary subtask match
Addresses two Codex review findings on PR #541.
## P1 — `tools: []` silently upgraded to permissive (privilege escalation)
Before: `_build_permission_block` returned `{}` for any empty list, which
omits the `permission:` block entirely from the emitted agent. An author
who explicitly wrote `tools: []` to lock down an advisory-only agent got
an UNRESTRICTED agent in OpenCode. Affected agent in this tree:
`plugins/arm-cortex-microcontrollers/agents/arm-cortex-expert.md`.
Fix: `_build_permission_block` now takes a `has_tools_field` flag so the
caller can distinguish "tools: key missing" (Claude default permissive)
from "tools: []" (explicit lock-down). The lock-down case emits a
deny-everything block that allows ONLY the base capabilities (skill, task)
that Claude Code always grants implicitly. Verified against the real
arm-cortex-expert agent — now emits read/edit/write/bash/grep/glob/list:
deny, task/skill: allow.
## P2 — `"agent" in cmd.body.lower()` false-positives on substrings
Before: a command body containing `PerformanceReviewAgent` (class name
in a code snippet) or `useragent` triggered `subtask: true`, changing
runtime behavior based on incidental text.
Fix: switch to a compiled word-boundary regex `\b(agent|subagent)s?\b`
(case-insensitive). Tests confirm the substring `PerformanceReviewAgent`
no longer fires, while a real "spawn a subagent" sentence still does.
## Tests
3 new regression tests in tools/tests/test_adapters.py:
- `test_explicit_empty_tools_yields_locked_permission_block` (P1)
- `test_missing_tools_field_yields_no_permission_block` (P1 boundary)
- `test_subtask_inference_word_boundary` (P2)
184 total tests pass (was 181). OpenCode round-trip still discovers all
193 subagents; arm-cortex-expert agent is now properly locked down.
* test: behavioral verification + CI gates for multi-harness pipeline
Adds three layers of automated verification that pure-Python parser tests
miss, plus the CI jobs that turn them into hard gates. Catches the kinds
of issues that previously only surfaced when a real user installed the
marketplace and tried to use it.
## test_real_world.py — real-source structural tests
Runs against the actual `plugins/` tree (not synthetic fixtures). Catches
issues that only appear on real content:
- every marketplace entry resolves to a plugins/<name>/ dir
- every local plugin dir appears in marketplace.json
- marketplace.json version == per-plugin plugin.json version (catches drift)
- every plugin loads via load_plugin() without error
- no plugin name contains `__` (adapter namespace separator)
- every agent has name + description; every skill has a trigger phrase
(same regex plugin_eval's MISSING_TRIGGER check uses)
- no agent name collides with Codex built-ins
- every refactored skill (with `references/details.md`) has:
- meaningful detail content (>=500 B in details.md)
- a pointer to references/ in the SKILL.md body
- a navigation-tier heading preserved (When to Use, Overview, etc.)
- body >= 600 B (not a stub)
- every plugin.json has name + version matching the dir
This test pass found and fixed three real defects before commit:
- ship-mate/skills/scan: description had no trigger phrase ("Use when…")
- reverse-engineering/skills/memory-forensics: nav-tier section lost
during extraction
- reverse-engineering/skills/binary-analysis-patterns: same
All three are now fixed (preserved trigger phrasing, added When-to-Use
sections back to the skills my extraction over-trimmed).
## test_round_trip.py — generate→parse→verify
CI runs this AFTER `make generate-all`. Catches generation-time regressions:
- OpenCode/Codex/Gemini agent counts match source agent count (no skips)
- every Codex SKILL.md under 8 KB (the cap that would silently truncate)
- every Codex agent TOML has required fields + valid sandbox_mode
- every OpenCode agent has mode in {primary,subagent,all} and
provider-prefixed model
- locked agents (source `tools: []`) emit proper deny-everything permission
block with skill/task allow (regression guard for PR-541 P1)
- every Gemini @{path} injection resolves to a real source file
- every Gemini command TOML has prompt + {{args}} placeholder
- every context file (CLAUDE.md, AGENTS.md, GEMINI.md, etc.) within
150-line cap
- Cursor marketplace + per-plugin manifests cover all local plugins
- .cursor/rules/*.mdc only use the 3 documented frontmatter keys
## test_cli_smoke.py — real-CLI subprocess tests
Invokes the actual harness binaries (OpenCode, Gemini, Codex, Claude Code)
against the generated artifacts. Catches CLI-level issues pure-Python
parsing can't see: schema-loader drift, plugin-discovery bugs, version
incompatibilities.
- `opencode agent list` — must succeed AND discover every source agent
(currently 191 + 2 OpenCode built-ins)
- `gemini extensions validate <repo>` — must return success
- `codex doctor` — must report healthy install
- every Codex agent TOML must parse with stdlib `tomllib`
- `claude --version` — sanity check the Claude Code CLI loads
- marketplace.json must have owner + metadata.version for Claude Code's loader
Per-CLI tests skip gracefully when the binary isn't on PATH, so local
devs only exercise what they have installed. CI installs OpenCode +
Gemini and turns those skips into hard gates.
## Makefile + CI
- `make test` — full pytest suite (plugin-eval + tools/tests/)
- `make smoke-test` — generates if needed, then runs real-CLI smoke tests
- `.github/workflows/validate.yml` extended with:
- `tools-tests` job — runs pytest tools/tests/
- `multi-harness-generate` job — `make generate-all && make validate
STRICT=1 && make garden`, uploads generated artifacts on every run
- `cli-smoke-test` job — installs OpenCode + Gemini, runs test_cli_smoke.py
## Test counts
- Before: 184 tests
- After: 386 tests (parameterized real-source tests over all 82 plugins)
- All passing locally on OpenCode 1.15.7 + Gemini 0.42.0 + Codex 0.133.0
+ Claude Code 2.1.148
|
||
|
Seth Hobson
|
9f9ba32370 |
docs: synchronize plugin/agent/skill counts (closes #517) (#522)
* docs: synchronize plugin/agent/skill counts (closes #517)
Live counts are 80 local plugins (81 incl. external git-subdir),
185 agents, 153 skills, 100 commands. Six docs were stale:
- marketplace.json metadata.description: 79/184/150 -> 80/185/153
- docs/plugins.md: 78 plugins (77 local) -> 81 plugins (80 local)
- docs/agents.md: 184 agents -> 185
- docs/agent-skills.md: 150 skills / 37 plugins -> 153 skills / 40 plugins
- docs/architecture.md: 79 plugins, 99 agents, 150 skills -> 81/185/153
- docs/usage.md: 150 skills, 79 plugins -> 153 skills, 80 plugins
Companion to
|
||
|
Seth Hobson
|
6625d1ead4 |
docs: refresh counts for protect-mcp + qa-orchestra; add CI validation
- Counts now reflect 79 plugins (77 local + 2 external via git-subdir), 184 agents, 150 skills, 98 commands across 25 categories - README/docs: add Governance category (protect-mcp), bump Testing to 2 (adds qa-orchestra), expand Security table to include reverse-engineering and block-no-verify, add Protect MCP skills section, surface pensyve in AI & ML - marketplace.json: bump metadata to 1.6.0, bump pensyve to 1.2.0 - Add .github/workflows/validate.yml to gate PRs on: - marketplace.json + every plugin.json + hooks.json parse as JSON - every ./plugins/<name> source resolves on disk with a plugin.json - plugin-eval pytest suite (would have caught the #482 sdk.stream bug class) |
||
|
Seth Hobson
|
03d0b4b9eb |
docs: refresh counts and add missing sections after recent plugin merges
- README and docs now reflect 77 plugins / 182 agents / 149 skills / 96 commands - agent-skills.md: add 9 missing plugin sections (agent-teams, reverse-engineering, startup-business-analyst, shell-scripting, database-design, documentation-standards, dotnet-contribution, plugin-eval, block-no-verify) covering 23 previously undocumented skills; fix python-development from 5 to 16 skills - plugins.md: correct 8 stale category counts and add missing Creative section - agents.md: fix header from 100 to 182 agents - architecture.md, usage.md: update plugin and skill counts - README: surface HADS and block-no-verify in their categories, add 5 categories that had been omitted (Creative, Accessibility, API, Utilities, Modernization) Also a one-line follow-up to #462: team-composition-patterns/SKILL.md line 136 in the Troubleshooting section still referenced the old Task tool — updated to the current Agent tool name. |
||
|
Seth Hobson
|
682abfcdeb |
fix: remove stale code-review-ai plugin (#134, #135)
Plugin had inconsistent content (OpenAI references, CI/CD workflow baked into review command). Replaced by official pr-review-toolkit and comprehensive-review plugins. Also answered discussions #138, #421, #422. |
||
|
Seth Hobson
|
f662524f9a |
feat: add Conductor plugin for Context-Driven Development
Add comprehensive Conductor plugin implementing Context-Driven Development methodology with tracks, specs, and phased implementation plans. Components: - 5 commands: setup, new-track, implement, status, revert - 1 agent: conductor-validator - 3 skills: context-driven-development, track-management, workflow-patterns - 18 templates for project artifacts Documentation updates: - README.md: Updated counts (68 plugins, 100 agents, 110 skills, 76 tools) - docs/plugins.md: Added Conductor to Workflows section - docs/agents.md: Added conductor-validator agent - docs/agent-skills.md: Added Conductor skills section Also includes Prettier formatting across all project files. |
||
|
Seth Hobson
|
01d93fc227 |
feat: add 5 new specialized agents with 20 skills
Add domain expert agents with comprehensive skill sets: - service-mesh-expert (cloud-infrastructure): Istio/Linkerd patterns, mTLS, observability - event-sourcing-architect (backend-development): CQRS, event stores, projections, sagas - vector-database-engineer (llm-application-dev): embeddings, similarity search, hybrid search - monorepo-architect (developer-essentials): Nx, Turborepo, Bazel, pnpm workspaces - threat-modeling-expert (security-scanning): STRIDE, attack trees, security requirements Update all documentation to reflect correct counts: - 67 plugins, 99 agents, 107 skills, 71 commands |
||
|
Mike Kazmier
|
16cddabb75 |
add c4 documentation workflow and agents (#129)
* add c4 documentation workflow and agents * update the c4-code agent to use proper mermaid diagram types |
||
|
Seth Hobson
|
65e5cb093a |
feat: add Agent Skills and restructure documentation
- Add 47 Agent Skills across 14 plugins following Anthropic's specification - Python (5): async patterns, testing, packaging, performance, UV package manager - JavaScript/TypeScript (4): advanced types, Node.js patterns, testing, modern JS - Kubernetes (4): manifests, Helm charts, GitOps, security policies - Cloud Infrastructure (4): Terraform, multi-cloud, hybrid networking, cost optimization - CI/CD (4): pipeline design, GitHub Actions, GitLab CI, secrets management - Backend (3): API design, architecture patterns, microservices - LLM Applications (4): LangChain, prompt engineering, RAG, evaluation - Blockchain/Web3 (4): DeFi protocols, NFT standards, Solidity security, Web3 testing - Framework Migration (4): React, Angular, database, dependency upgrades - Observability (4): Prometheus, Grafana, distributed tracing, SLO - Payment Processing (4): Stripe, PayPal, PCI compliance, billing - API Scaffolding (1): FastAPI templates - ML Operations (1): ML pipeline workflow - Security (1): SAST configuration - Restructure documentation into /docs directory - agent-skills.md: Complete guide to all 47 skills - agents.md: All 85 agents with model configuration - plugins.md: Complete catalog of 63 plugins - usage.md: Commands, workflows, and best practices - architecture.md: Design principles and patterns - Update README.md - Add Agent Skills banner announcement - Reduce length by ~75% with links to detailed docs - Add What's New section showcasing Agent Skills - Add Popular Use Cases with real examples - Improve navigation with Core Guides and Quick Links - Update marketplace.json with skills arrays for 14 plugins All 47 skills follow Agent Skills Specification: - Required YAML frontmatter (name, description) - Use when activation clauses - Progressive disclosure architecture - Under 1024 character descriptions |