wshobson-agents/CLAUDE.md at 05231aa6398384ca94bb39d8be9d848a1b3b21db

mirror of https://github.com/wshobson/agents synced 2026-06-21 14:13:58 +00:00

Files

T

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.

2026-05-22 11:16:39 -04:00

1.1 KiB

Raw Blame History

@AGENTS.md

Claude Code

This file imports the canonical AGENTS.md (Anthropic's recommended pattern for repos that adopt the cross-harness convention). Any Claude-Code-specific addenda live below.

Native features unique to Claude Code

Per-agent tool allowlist — tools: frontmatter honored verbatim (Cursor / Codex are coarser; the OpenCode adapter translates this into a permission: block).
Task / Agent spawn tool — fan-out parallel subagent execution. (Codex requires naming an agent in prose to delegate.)
TodoWrite — native progress tracking. (Not available in Codex / Cursor / Gemini.)
Slash-command marketplace — full /plugin install, /plugin marketplace workflow.

Claude-Code-only paths

.claude-plugin/marketplace.json — plugin registry (source of truth)
plugins/<name>/.claude-plugin/plugin.json — per-plugin manifest

All other working conventions, quality gates, and component models are described in AGENTS.md above.

1.1 KiB Raw Blame History

Claude Code

Native features unique to Claude Code

Claude-Code-only paths

1.1 KiB

Raw Blame History