main
23 次代码提交
| 作者 | SHA1 | 备注 | 提交日期 | |
|---|---|---|---|---|
 Seth Hobson
|
608c3840ca |
feat: native plugin-install for Codex/Cursor/Gemini + CLAUDE.md→AGENTS.md symlink
Add lean, native plugin-install entry points so each harness's own plugin manager can install this marketplace (mirroring obra/superpowers) — committing only small JSON registries, not duplicated skill/agent content trees. - Codex: committed marketplace registry (.agents/plugins/marketplace.json) + per-plugin manifests (plugins/*/.codex-plugin/plugin.json). Entries point at source ./plugins/<name>; Codex reads SKILL.md directly. Transformed .codex/skills|agents stay gitignored. - Cursor: commit the existing .cursor-plugin/ marketplace + .cursor/rules/ (these already point at source plugins/). - Gemini: gemini-extension.json already committed (contextFileName: AGENTS.md); transformed trees stay gitignored (install via clone + make generate). - OpenCode: unchanged — install via `make install-opencode` (transformed tree stays gitignored). - CLAUDE.md is now a symlink to AGENTS.md; Claude-Code addenda moved to docs/harnesses.md. - CI: new step fails if `make generate-all` drifts from the committed registries. Net new committed: ~720 KB of manifests (no skill/agent duplication). Adds round-trip tests for the new registries + the symlink. Docs updated across README, docs/harnesses.md, ARCHITECTURE.md, CONTRIBUTING.md, GEMINI.md, docs/authoring.md, and the PR template. |
||
|
Seth Hobson
|
f31aba246e |
Skip Claude review on fork PRs (#559)
Fork PRs don't have access to secrets or OIDC tokens, causing claude-code-action to fail on OIDC authentication. Skip the job entirely for cross-repository PRs so CI stays green. |
||
|
Seth Hobson
|
8df77ecd46 |
Fix duplicate agent name collisions (#554)
* fix: namespace duplicate agent names * fix: format duplicate-name regression test * fix: align command phase output references * docs: clarify agent naming formula |
||
|
Seth Hobson
|
9834a5f38d |
Add Pensyve external integration (#552)
* feat: add Pensyve external integration * docs: fix skill plugin count |
||
|
Seth Hobson
|
b2b62b2b61 |
ci: add dependabot for uv-managed Python projects (#545)
* ci: add dependabot for uv-managed Python projects Configure weekly dependency updates for the two uv projects in the repo — tools/yt-design-extractor and plugins/plugin-eval. Minor and patch bumps are grouped per-project so each ecosystem produces at most one rollup PR per week; majors arrive as individual PRs. Native uv support is available in Dependabot since 2024 — it updates pyproject.toml and uv.lock in lock-step. * deps: drop include:scope to avoid double-parenthesized commit subject With prefix "deps(yt-design-extractor)" + include:"scope", dependabot would render commits as "deps(yt-design-extractor)(uv): bump foo from 1 to 2" — double parens. Drop include:scope on both ecosystem entries; project identity stays in the prefix. Caught by the claude-code-review workflow on PR #545. |
||
|
Seth Hobson
|
1385ee046d |
Add Claude Code GitHub Workflow (#544)
* "Claude PR Assistant workflow"
* "Claude Code Review workflow"
* ci: tune Claude Code workflows for marketplace review
- Auto-review (claude-code-review.yml): replace generic
/code-review:code-review slash command with a multi-line prompt that
carries the repo's invariants (source-of-truth under plugins/, no __
in plugin names, Codex 8 KB skill cap, AGENTS.md/CLAUDE.md/GEMINI.md
sync, quality gates). Bump model to claude-opus-4-7. Grant
pull-requests: write so inline comments and PR summaries can post.
Add track_progress: true. Skip drafts and dependabot.
- @claude responder (claude.yml): bump model to claude-opus-4-7. Grant
write scopes for contents/pull-requests/issues so @claude can
actually fix things. Gate on author_association so only OWNER /
MEMBER / COLLABORATOR can trigger writes (closes a real auth gap
flagged by coderabbit, critical now that scopes are write). Curate
--allowedTools for this repo's uv + ruff + ty + pytest + make + gh +
git toolchain.
- Both: pin actions/checkout to SHA with persist-credentials: false to
match .github/workflows/validate.yml convention.
Inspired by major7apps/pensyve and major7apps/maverick-bot review
workflows.
* ci: address coderabbit review on claude workflows
- Pin anthropics/claude-code-action to v1 commit SHA
(4481e6d3c7bbb88db2a928ca3444c536f589c7c1) — satisfies zizmor's
blanket-pin policy.
- Drop the implicit "approve with a one-line summary" instruction from
the review prompt; the workflow's allowedTools only expose inline
comments and gh pr comment, not a review-submission API. Replace
with an explicit "post a one-line ✅ summary via gh pr comment and
stop" so the success path is actually executable.
- Swap issues.types from [opened, assigned] to [opened, edited] on
claude.yml. The if:-condition only checks issue.body/title for
@claude, so reassignment-firing produces false triggers while edits
to existing issues currently fire nothing.
Skipped (with reason): "checkout PR head ref" finding. Anthropic's
canonical claude.yml template (anthropics/claude-code-action examples)
does not set with.ref — the action resolves the PR head internally
via the GitHub API. Forcing a specific ref would diverge from the
upstream contract.
* ci: enumerate git subcommands in @claude allowedTools
Replace the `Bash(git:*)` wildcard with an explicit list of safe
subcommands (status/diff/log/show/rev-parse/branch/tag/ls-files for
inspection; add/commit/checkout/switch/fetch/pull/push/stash for
workflow). Destructive ops like `reset`, `clean`, `rebase`,
`filter-branch`, and `branch -D` are no longer callable — they are
absent from the enumeration.
Addresses coderabbit finding: the wildcard conflicted with the repo's
own security checklist ("no destructive git in scripts") embedded in
claude-code-review.yml.
* ci: further tighten @claude allowedTools to read-only git + scoped gh
Drop `Bash(gh:*)` wildcard and the write-side `git` subcommands.
- `gh` is now enumerated: pr view/diff/list/comment/edit/checks,
issue view/list/comment/edit, api, run view, workflow view, search.
- `git` is now read-only: status, diff, log, show, rev-parse, ls-files.
Removed `branch`, `tag`, `add`, `commit`, `checkout`, `switch`,
`fetch`, `pull`, `push`, `stash` — `git branch -D`, `git tag -d`,
`git checkout -- .`, `git push --force`, etc. are no longer reachable.
Commits and branch creation are handled by anthropics/claude-code-action
internally via the GitHub API (`branch_prefix` / `branch_name_template`
action inputs), so local write-side git is not required for @claude to
fix things — `Edit`/`Write` produce the changes; the action commits.
Addresses coderabbit follow-up: --allowedTools doesn't understand
destructive flags, so safety comes from precise command patterns.
* ci: scope @claude gh api allowlist to specific endpoints
Drop `Bash(gh api:*)` (which exposed the entire GitHub REST API
surface, including DELETE/PATCH endpoints) in favor of three scoped
patterns sufficient for reading discussion context:
- repos/*/pulls/*/comments — PR review-thread reads
- repos/*/issues/*/comments — issue-thread reads
- repos/*/issues/*/timeline — issue history
Mirrors the same scoping style used in claude-code-review.yml. The
enumerated `gh pr` / `gh issue` / `gh run` / `gh workflow` / `gh search`
subcommands cover the rest of the responder's typical needs.
Addresses coderabbit finding.
|
||
|
Seth Hobson
|
2d3f6a8527 |
chore: move toolchain to uv-native (no pip, no requirements.txt) (#543)
* chore: move toolchain to uv-native (no pip, no requirements.txt)
The repo previously mixed uv (for plugin-eval) with pip + requirements.txt
(for yt-design-extractor) and raw `python3` invocations in the Makefile and
CI workflows. This makes the toolchain uniformly uv-managed.
## yt-design-extractor
Moved `tools/yt-design-extractor.py` into `tools/yt-design-extractor/` with its
own `pyproject.toml` + `uv.lock`. EasyOCR (and its ~2 GB torch dependency)
becomes an optional extra (`uv sync --extra easyocr`). Deleted
`tools/requirements.txt`.
## Makefile
All targets now route through uv:
- `make install` / `make install-easyocr` / `make deps` / `make check` / `make run*`:
`cd tools/yt-design-extractor && uv run/uv sync`
- `make generate` / `make validate` / `make garden` / `make clean-generated`:
`uv run --project plugins/plugin-eval python tools/...` (reuses plugin-eval's
venv — it already has pyyaml and `extra-paths = ["../.."]` for tools/adapters)
- `make test` / `make smoke-test`: `uv run --project plugins/plugin-eval pytest`
## CI
- `.github/workflows/validate.yml`:
- `multi-harness-generate` swapped from `actions/setup-python@v5` to
`astral-sh/setup-uv@v5` + `uv sync` of plugin-eval before `make generate-all`
- Workflow-level `permissions: contents: read` + `persist-credentials: false`
on every checkout (carrying the security hardening forward consistently)
- `.github/workflows/code-quality.yml`:
- `json-lint` job swapped from `setup-python` to `setup-uv`
- YAML validator now uses `uv run --with pyyaml python` (no pre-step install)
- JSON/TOML validators use `uv run python` (stdlib `json.tool`, `tomllib`)
- Dropped the standalone `pip install pyyaml --quiet` line
## Inline hints
- `plugins/plugin-eval/src/plugin_eval/layers/judge.py`: error message
recommends `uv sync --extra llm` instead of `pip install plugin-eval[llm]`
- `tools/yt-design-extractor/yt-design-extractor.py`: usage docstring and
install hints now reference `make install` / `make install-easyocr` / `uv run`
The pip refs inside plugin-authored commands (deps-audit.md, doc-generate.md,
error-trace.md) describe scanning **user** Python projects — those legitimately
use pip and are out of scope.
Local gates green: make test (385 pass), make garden (0 errors), make validate
clean, ruff + format + ty all pass, markdownlint clean.
* chore: address PR #543 review feedback
- checkmake (Makefile): consolidate the multi-line `.PHONY:` declaration
onto a single line. The previous backslash-continued form was readable
but checkmake couldn't parse it, falsely flagging `validate` and
`clean-generated` as missing from .PHONY. They were already declared —
just invisible to the linter.
Other CodeRabbit feedback declined:
- pyproject.toml dep version constraints (CodeRabbit self-tagged "Low value"):
uv.lock pins exact versions for reproducibility; upper bounds on yt-dlp,
Pillow, etc. would invite stale-pin churn without changing the locked
installation. Tracking upstream aggressively is the right default for a
utility tool.
- SHA-pinning for GitHub Actions (CodeRabbit "Major" but defensible):
Workflow has no write scope (permissions: contents: read on both files),
no secrets are exposed, and the actions involved are first-party Anthropic
(astral-sh, actions/*, DavidAnson). Same policy decision as PR #542 —
blanket SHA pinning is a bigger commitment than this PR's scope warrants.
* chore: pin all GitHub Actions to commit SHAs
Addresses CodeRabbit's Major finding (zizmor `unpinned-uses`). Reverses the
earlier policy decision now that the workflow scope has grown — pins both
workflows consistently in one pass:
- actions/checkout v4 → 34e114876b0b11c390a56381ad16ebd13914f8d5
- actions/setup-node v4 → 49933ea5288caeca8642d1e84afbd3f7d6820020
- actions/upload-artifact v4 → ea165f8d65b6e75b540449e92b4886f43607fa02
- astral-sh/setup-uv v5 → e58605a9b6da7c637471fab8847a5e5a6b8df081
- DavidAnson/markdownlint-cli2-action v18 → eb5ca3ab411449c66620fe7f1b3c9e10547144b0
- oven-sh/setup-bun v2 → 0c5077e51419868618aeaa5fe8019c62421857d6
Each pin keeps the version tag in a trailing comment for human readability
and dependabot/renovate compatibility.
Both workflows YAML-validated locally; functionality unchanged.
|
||
|
Seth Hobson
|
03e6dae50a |
docs: remove redundant per-harness setup files
CODEX.md, CURSOR.md, and OPENCODE.md were human-readable setup guides that no harness actually loads as a context file — Codex, Cursor, and OpenCode all read AGENTS.md natively. The substantive content (install one-liner, capability deltas, authoring caveats) lives in: - README.md "Pick your harness" section — install flow - docs/harnesses.md — full capability matrix + graceful-degradation table - docs/authoring.md — portable-content style guide GEMINI.md stays because .gemini/settings.json includes it in context.fileName — it IS loaded into context every Gemini prompt. Updated references: - README.md — badge links + setup-guide line point at docs/harnesses.md - AGENTS.md, ARCHITECTURE.md — table-of-contents + tree diagram - docs/authoring.md — context-file cap rule - .github/PULL_REQUEST_TEMPLATE.md — scope checklist - tools/doc_gardener.py — CONTEXT_FILES map + dead-link traversal roots - tools/tests/test_round_trip.py — TestContextFileBudgets parametrize list Local lints: ruff (CI scope) clean, ruff format clean, ty clean, markdownlint clean, doc_gardener 0 errors, 31 round-trip + gardener tests pass. |
||
|
Seth Hobson
|
98862b56d8 |
feat: AGENTS.md canonical context + OpenAI harness-engineering layout (#542)
* feat: AGENTS.md canonical context + OpenAI harness-engineering layout Promote AGENTS.md to the committed cross-harness context file (per the agents.md convention and OpenAI's harness-engineering blog). Harness- specific files become thin redirects: - AGENTS.md — canonical, committed (~74 lines, table-of-contents) - CLAUDE.md — `@AGENTS.md` import + Claude-specific addenda - GEMINI.md — Gemini-specific setup only - .gemini/settings.json — redirects Gemini CLI's context to read AGENTS.md - ARCHITECTURE.md — new at root, top-level architectural map - gemini-extension.json — bumps version to 1.7.0, sets contextFileName: AGENTS.md - .gitignore — drops the AGENTS.md entry (file is now committed) Harness support verified: - Codex CLI reads AGENTS.md natively (root → cwd walk, 32 KiB cap) - Cursor 2.5+ reads AGENTS.md natively - OpenCode reads AGENTS.md natively (wins over CLAUDE.md if both exist) - Claude Code: `CLAUDE.md` first line is `@AGENTS.md` (Anthropic's documented interop pattern) - Gemini CLI: `.gemini/settings.json` context.fileName redirect (Gemini doesn't support @-imports) Codex adapter no longer generates AGENTS.md — `emit_global` instead validates the committed file fits Codex's 32 KiB cap and the 150-line table-of-contents convention. Tests updated. Clean-output target no longer touches AGENTS.md. ## Auxiliary files updated for multi-harness reality - `.github/ISSUE_TEMPLATE/bug_report.yml` — dropdown for harness + component path; renames "subagent" → "plugin/agent/skill/command" - `.github/ISSUE_TEMPLATE/feature_request.yml` — scope dropdown covers framework / harness / tooling / docs / CI in addition to components - `.github/ISSUE_TEMPLATE/new_subagent.yml` — relabeled "New Component Proposal" with component-type dropdown (plugin/agent/skill/command/ harness adapter) and cross-harness portability field - `.github/ISSUE_TEMPLATE/config.yml` — links to AGENTS.md, authoring guide, per-harness docs; updated Contributing link to root - `.github/CONTRIBUTING.md` — thin pointer to canonical root CONTRIBUTING.md - `.github/PULL_REQUEST_TEMPLATE.md` — new; scope + affected-harness checklists, test-plan checklist, portability-notes section - CONTRIBUTING.md (root) — updated to reference AGENTS.md / ARCHITECTURE.md - gemini-extension.json — version 1.6.0 → 1.7.0, count fixes, redirects to AGENTS.md as contextFileName ## Code-quality CI New `.github/workflows/code-quality.yml` with three jobs: - `python-lint` — `ruff check`, `ruff format --check`, `ty check` on the adapter framework + plugin-eval. yt-design-extractor.py legacy code excluded. - `markdown-lint` — markdownlint-cli2 against README, AGENTS, ARCHITECTURE, CLAUDE, top-level guides, and docs/. Config in `.markdownlint.json`. - `json-lint` — validates every JSON / TOML / YAML in the repo (excluding generated trees). Required ty environment config added to plugin-eval/pyproject.toml so `tools.adapters.*` resolves from outside the package. Fixed one ty error in `tools/adapters/base.py:HarnessAdapter.capabilities` (return-type annotation didn't match the `Capability` dataclass returned). Fixed two ruff SIM108 ternary suggestions in codex.py and doc_gardener.py. ruff format applied across all in-scope files (formatting-only diffs). ## Tests + verification - 387 pytest tests pass (1 new test for the AGENTS.md validate-don't-overwrite behavior) - `make validate STRICT=1` clean - `make garden` 0 errors (10 warnings — remaining oversize source skills) - `make smoke-test` clean against locally installed OpenCode/Gemini/Codex/Claude Code - Real-CLI round-trip: `opencode agent list` discovers 193 subagents, `gemini extensions validate .` succeeds, all 191 Codex agent TOMLs parse ## Tag recommendations (separate task — for repo About panel) Top 20 by reach + relevance (from `gh api search/repositories?q=topic:<tag>`): automation mcp ai-agents developer-tools claude-code anthropic agentic-ai agents prompt-engineering cursor multi-agent agent-skills orchestration opencode workflows gemini-cli codex-cli claude-code-skills cursor-rules claude-code-plugins * fix(ci): YAML multi-doc + markdownlint scope/rules Two CI failures on PR #542, both fixed: ## JSON/TOML/YAML syntax job (3 false-positive YAML errors) The job's YAML validation used `yaml.safe_load` which only reads the first document in a multi-document YAML stream. Three Kubernetes manifest templates use the standard `---` document separator (valid YAML) and were mis-flagged: plugins/kubernetes-operations/skills/k8s-manifest-generator/assets/configmap-template.yaml plugins/kubernetes-operations/skills/k8s-manifest-generator/assets/service-template.yaml plugins/kubernetes-operations/skills/k8s-security-policies/assets/network-policy-template.yaml Switched to `list(yaml.safe_load_all(...))` so multi-doc YAML is accepted. ## Markdown lint job (lots of pre-existing plugin-README violations) Two changes: 1. **Narrow the lint glob** — markdownlint now runs against top-level guides (README, AGENTS, ARCHITECTURE, CLAUDE, per-harness setup, CONTRIBUTING) and our authored `docs/` only. Per-plugin READMEs (`plugins/*/README.md`) are owned by their plugin authors and not lint-gated as part of this framework PR. Lint enforcement for those belongs at the plugin-author layer, not the framework PR layer. 2. **Tighten `.markdownlint.json`** — disable two rules that produce noise without catching real defects: - MD040 (fenced-code-language) — terminal output / shell command blocks frequently omit a language by convention - MD060 (table-column-style) — cosmetic table-pipe spacing; doesn't affect rendering Genuine formatting rules kept: MD029 (ol-prefix), MD031 (blanks- around-fences), MD032 (blanks-around-lists), MD056 (table-column- count), MD058 (blanks-around-tables). ## Real defects caught and fixed The narrower scope still caught 5 real issues: - `docs/agent-skills.md:397` — code fence inside an ordered list item needed a blank line before the fence - `docs/authoring.md:90` — bulleted list needed a blank line above - `docs/plugin-eval.md:87` — table needed a blank line above - `OPENCODE.md:39` — table-column-count error caused by literal `|` inside backticks: ``mode: primary|subagent|all`` (3 cells reads as 5) Rewrote as ``mode:` one of `primary` / `subagent` / `all`` ## Verification - `npx markdownlint-cli2 "*.md" "docs/*.md"` → 0 errors - `yaml.safe_load_all` accepts all multi-doc YAMLs (0 errors) - All other CI jobs already passing (Python ruff/ty, multi-harness generate, CLI smoke test, plugin-eval pytest, tools pytest) * fix: address PR #542 bot feedback - Codex P2 (chatgpt-codex-connector): emit_global now reads AGENTS.md from the repo root (WORKTREE), not output_root. Previously `--output-root <scratch>` produced a false "missing" warning even when AGENTS.md was committed at the real root, breaking --strict generation outside the repo. Added a constructor arg `repo_root` so tests can stage a fake AGENTS.md without touching the committed file, plus a regression test that proves the two paths are decoupled. - CodeRabbit nitpick (code-quality.yml): added workflow-level `permissions: contents: read` and `persist-credentials: false` on every checkout. Skipped the SHA-pinning recommendation — it's a heavier blanket-policy decision and the workflow has no write scope to abuse. - CodeRabbit nitpick (pyproject.toml): consolidated the duplicate `dev` groups by moving `ty` into `[project.optional-dependencies].dev` and removing the now-empty `[dependency-groups]` block. Dropped `--group dev` from `code-quality.yml`'s `uv sync` since `--all-extras` now covers it. - Verified gemini-extension.json counts (82/191/155/102) against the actual source-of-truth: 81 local plugins + 1 external = 82 in marketplace.json, 191 agent .md files, 155 SKILL.md files, 102 command .md files. Counts are correct as-is — CodeRabbit's quick-win was a regex miscount. |
||
|
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
|
08ded5e7b0 |
fix: agent teams coordination guardrails (#535)
* fix agent teams coordination guardrails * address agent teams review feedback |
||
|
Seth Hobson
|
0041fc7194 |
ci: add plugin eval reporting workflow with per-plugin scores
Adds a GitHub Action that runs the full plugin-eval engine across every local plugin and emits a structured report for review — not a PR gate. - scripts/eval_all.py batch-runs EvalEngine.evaluate_plugin across plugins/*/, writing per-plugin JSON plus summary.md and summary.json - Report surfaces composite score, 95% CI, badge, confidence label, anti-pattern flags, and three weakest dimensions per plugin - Separate "Issues requiring attention" section for plugins scoring under 60 or with anti-pattern flags raised - Workflow triggers: workflow_dispatch (choose depth + optional comma-separated plugin filter) and weekly cron (Mondays 06:00 UTC) - Depth quick = static only (no credentials); standard/deep require ANTHROPIC_API_KEY repo secret for LLM judge / Monte Carlo layers - Posts summary.md to the job summary, uploads full eval-reports/ directory as an artifact for 30 days Smoke-tested locally: 77 plugins evaluated at quick depth in < 5s, mean 83.1/100, 2 plugins flagged (incident-response with DEAD_CROSS_REF, plugin-eval with ORPHAN_REFERENCE + DEAD_CROSS_REF). |
||
|
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
|
47a5dbc3f9 |
fix(skills): remove phantom resource references and fix CoC links (#447)
Remove references to non-existent resource files (references/, assets/, scripts/, examples/) from 115 skill SKILL.md files. These sections pointed to directories and files that were never created, causing confusion when users install skills. Also fix broken Code of Conduct links in issue templates to use absolute GitHub URLs instead of relative paths that 404. |
||
|
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
|
f95810b340 |
chore: remove Claude Code GitHub workflows
The workflows were failing for fork PRs due to GitHub security restrictions on secrets access. Removing until a better solution is implemented. |
||
|
Seth Hobson
|
cf82055296 |
docs(conduct): add automated abuse and LLM spam policies
Add explicit language prohibiting bulk automated issue/PR creation and LLM-generated spam, with zero-tolerance enforcement policy. |
||
|
Seth Hobson
|
27a246a8c6 |
Add Claude Code GitHub Workflow (#140)
* "Claude PR Assistant workflow" * "Claude Code Review workflow" |
||
|
Seth Hobson
|
cc31a8f777 | remove github workflows | ||
|
Seth Hobson
|
e88a6ee87d |
Add GitHub Sponsors button
Add FUNDING.yml to enable sponsor button on repository |
||
|
Seth Hobson
|
4dad1937e9 |
Format all YAML files to pass yamllint validation
- Added document start markers (---) to all YAML files
- Fixed line length issues by breaking long lines appropriately
- Removed trailing whitespace throughout all files
- Added proper newlines at end of files
- Fixed truthy value format ('on' -> 'on')
- Standardized YAML formatting across workflows and issue templates
- Used multi-line strings (>) for long descriptions
- Maintained readability while adhering to 80-character line limit
All YAML files now pass yamllint validation with only minor warnings remaining.
|
||
|
Seth Hobson
|
fe236a76b5 |
Fix GitHub Actions welcome workflow using best practices
Problem Analysis: - Original workflow used complex GitHub search API causing rate limiting issues - Custom first-time contributor detection was unreliable and fragile - Used pull_request instead of pull_request_target for PRs (security issue) - Complex github-script logic prone to failures Solution Implemented: - Replaced custom logic with GitHub's official actions/first-interaction@v1 - Changed to pull_request_target for PR security and reliability - Eliminated API rate limiting issues by removing search calls - Simplified permissions and workflow structure - Added comprehensive welcome messages with community guidelines Benefits: - More reliable first-time contributor detection - No rate limiting issues - Better security with pull_request_target - Easier to maintain using official GitHub action - Consistent messaging across issues and PRs Also included alternative implementation example using garg3133/welcome-new-contributors@v1.2 |
||
|
Seth Hobson
|
ea5644ab9b |
Implement comprehensive content moderation and community protection
- Added Code of Conduct with clear behavioral standards - Created Contributing guidelines with submission requirements - Implemented structured issue templates (bug reports, features, new agents, moderation) - Disabled blank issues to enforce template usage - Added automated content moderation via GitHub Actions: * Real-time scanning for hate speech, threats, and profanity * Automatic closure/locking of critical violations * Moderation alerts for maintainer review - Set up welcome system for new contributors with community guidelines - Enabled GitHub Discussions as alternative to issues for general questions - Closed and locked existing hate speech issue #30 - Blocked offending user account This creates a multi-layered defense against inappropriate content while maintaining an open, welcoming environment for legitimate contributors. |