Repository navigation
Conversation
This was referenced Sep 20, 2026
martient
added this pull request to stack #48
September 20, 2026 17:40
Audit the repository's agent-facing surfaces (AGENTS.md/CLAUDE.md, the shared Codex/Claude plugin and skills, the schema capability contract, generated hooks/CI, and the src/ai LLM integration) against the current state of the agent-integration ecosystem. Records 15 prioritised findings covering defects, compatibility gaps and removals, plus two explicit non-recommendations.
Agents consistently failed against the CLI for three mechanical reasons, each now reproduced and covered by tests/agent_ergonomics_tests.rs. - --non-interactive and -q/--quiet are global, so they parse on either side of the subcommand. --verbose stays root-only: -v belongs to `branch --validate` and --verbose to `config validate|show`, and promoting it would steal both shorts. A test pins that trade-off. - Argument-parse rejections now emit the machine envelope on stdout with code "invalid_usage" when --output json was requested, instead of an empty stdout and prose on stderr. Text mode is unchanged, and --help and --version keep their plain-text form and exit 0. - schema capabilities cover the whole agent command surface (tag, bump, changelog, group-commit, config, packages, schema) and each entry now declares `mutating` and `requires_confirmation`, so an agent can reason about consent without pattern-matching command names. - COMMITTY_NONINTERACTIVE is documented in AGENTS.md, CLAUDE.md and the agent-workflows reference; it makes flag placement irrelevant. Also withdraws the audit's blanket "do not build an MCP server": that was argued against eager-loading MCP, which the 2026-07-28 stateless spec has moved off.
Second half of the agent-ergonomics change: main.rs flag globals and the clap rejection handler, the expanded schema capability list, the ergonomics test suite, and the docs describing flag placement.
Adds tests/agent_ergonomics_tests.rs (12 tests) covering flag placement on both sides of the subcommand, the invalid_usage envelope on argv rejection, the expanded capability surface with consent metadata, and the presence of COMMITTY_NONINTERACTIVE in agent-facing docs. Documents flag placement in the agent-workflows reference and records the diagnosis in the audit, withdrawing its blanket recommendation against an MCP server.
Tooling re-adds Co-Authored-By and Claude-Session by default, so the prohibition has to live where agents read it rather than being restated each session.
martient
force-pushed
the
claude/ai-agents-capabilities-report-fgpp3p-v2
branch
from
September 20, 2026 18:02
48d39e3 to
a331dcc
Compare
Owner
Author
|
Superseded by #49. The stack could not be merged: every PR here is authored by the repo owner, and #49 carries the identical 14 signed commits on a single branch against Generated by Claude Code |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
First of a stacked series resolving the findings in the September 2026 agent compatibility audit.
What this adds
docs/audits/agent-compatibility-2026-09.md— a full audit of every surface an AI coding agent touches: the agent instruction files, the shared Codex/Claude plugin and skills, the machine-readable CLI contract, the generated hooks/CI, and thesrc/aiintegration.What this fixes
Agents were failing against the CLI for three mechanical reasons, each reproduced and now covered by
tests/agent_ergonomics_tests.rs(12 tests):--non-interactiveand-q/--quietwere root-only, socommitty schema --non-interactive …— the form agents write by default — was rejected by clap. Both are nowglobal.--output json. It now emits the standard envelope with"code": "invalid_usage". Text mode is unchanged;--help/--versionstill print plain text and exit 0.COMMITTY_NONINTERACTIVE=1makes flag placement irrelevant but appeared in no agent-facing doc. Now documented inAGENTS.md,CLAUDE.mdand the agent-workflows reference.Capability discovery went from 10 entries to 21, covering the whole surface the shipped skills already tell agents to use (
tag,bump,changelog,group-commit,config,packages). Each now declaresmutatingandrequires_confirmation, so an agent can reason about consent without pattern-matching command names —tag.publishis the only one gated on explicit confirmation.--verbosewas deliberately not made global:-valready means--validateonbranch, and--verbosebelongs toconfig validate|show. Promoting it panics the binary at startup on a short-flag collision. A test pins that trade-off.Verification
cargo test374 passed,cargo fmt --all -- --checkclean,cargo clippy --all-targets --all-features -- -D warningsclean.Two pre-existing test problems were found and are not addressed here:
tag_tests::test_tag_respects_repo_git_overrides_and_cli_can_override_themfails deterministically on a cleandevelop— a tag creation that should be rejected succeeds.config::hierarchy::tests::test_repository_config_overrides_userpasses alone and under--test-threads=1, fails under parallelism — shared global state.