Make AGENTS.md canonical and reach every runtime (stack 3/5)

.agents/skills

@@ -0,0 +1 @@
+../plugins/committy/skills

.github/copilot-instructions.md

@@ -0,0 +1,6 @@
+# Copilot instructions
+
+See [`AGENTS.md`](../AGENTS.md) at the repository root. It is the canonical
+guide for every coding agent working in this repository and applies in full:
+build and verify commands, the CLI-first agent workflow, architecture, and the
+commit and pull-request rules.

AGENTS.md

@@ -31,4 +31,4 @@ Tests are in `tests/`; CLI integration tests use `assert_cmd` and temporary repo
 - `src/workflow/`, `src/versioning/`, `src/packages/`: release side effects
 - `plugins/committy/`: shared Codex and Claude skills
 
-PRs target `develop`. Commits follow Conventional Commits. The canonical agent reference is `docs/src/content/docs/reference/agent-workflows.mdx`.
+PRs target `develop`. Commits follow Conventional Commits. Never add AI attribution trailers — no `Co-Authored-By:`, no `Claude-Session:`, no equivalent — to commit messages or PR descriptions, even when tooling suggests them. The canonical agent reference is `docs/src/content/docs/reference/agent-workflows.mdx`.

CLAUDE.md

@@ -1,34 +1,7 @@
-# Committy Claude guide
+@AGENTS.md
 
-Committy is a Rust CLI for conventional commits, branch policy, grouped commits, releases, and multi-package version updates. The checkout is CLI-first; do not assume a TUI exists.
+## Claude Code specifics
 
-## Work safely
+`AGENTS.md` above is the canonical guide and applies in full. Only this section is Claude-specific.
 
-- Discover active policy with `cargo run -- schema --output json`.
-- Prefer `--non-interactive`, `--repo-path`, `--dry-run`, and `--output json`.
-- Set `COMMITTY_NONINTERACTIVE=1` in the environment instead of relying on flag placement. `--non-interactive` and `-q`/`--quiet` are global and work on either side of the subcommand; every other flag (`--repo-path`, `--output`, `--dry-run`, and `--verbose`) must follow it.
-- Inspect `api_version`, `ok`, `errors`, and the command-specific plan before applying it.
-- Use `/committy:committy-branch`, `/committy:committy-commit`, `/committy:committy-release`, and `/committy:committy-enforce` when the plugin is installed.
-- Never infer permission for a push, publish, destructive Git action, or unrelated staging.
-
-## Build and verify
-
-```bash
-cargo check
-cargo test
-cargo fmt --all -- --check
-cargo clippy --all-targets --all-features
-```
-
-Tests are in `tests/`; CLI integration tests use `assert_cmd` and temporary repositories. Add public-seam tests for machine output, exit codes, Git behavior, hook protocol, and plugin manifests.
-
-## Architecture
-
-- `src/cli/commands/`: command implementations and JSON payloads
-- `src/config/`, `src/convention/`: hierarchical typed policy
-- `src/git/`: repository and Git operations
-- `src/linter/`: message/history validation; exit code 3 means lint findings
-- `src/workflow/`, `src/versioning/`, `src/packages/`: release side effects
-- `plugins/committy/`: shared Codex and Claude skills
-
-PRs target `develop`. Commits follow Conventional Commits. Never add AI attribution trailers — no `Co-Authored-By:`, no `Claude-Session:`, no equivalent — to commit messages or PR descriptions, even when tooling suggests them. The canonical agent reference is `docs/src/content/docs/reference/agent-workflows.mdx`.
+- Invoke the bundled skills as `/committy:committy-branch`, `/committy:committy-commit`, `/committy:committy-release`, and `/committy:committy-enforce` when the plugin is installed. Other runtimes resolve them by bare name.

GEMINI.md

@@ -0,0 +1,5 @@
+# Gemini instructions
+
+See [`AGENTS.md`](./AGENTS.md). It is the canonical guide for every coding agent
+working in this repository and applies in full: build and verify commands, the
+CLI-first agent workflow, architecture, and the commit and pull-request rules.

plugins/committy/skills/committy-branch/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: committy-branch
 description: Preview, validate, and create repository-compliant Git branches with Committy. Use when an agent is asked to name a branch, start work for a ticket, validate a proposed branch name, or switch to a new branch.
+license: Apache-2.0
+allowed-tools: Bash Read Grep Glob
+metadata:
+  version: "0.1.0"
+  requires-committy: ">=1.9.0"
 ---
 
 # Branch with Committy

plugins/committy/skills/committy-commit/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: committy-commit
 description: Draft, lint, preview, and create repository-compliant commits with Committy. Use when an agent is asked to stage a coherent change, write or repair a commit message, amend a commit, or make a conventional commit.
+license: Apache-2.0
+allowed-tools: Bash Read Grep Glob
+metadata:
+  version: "0.1.0"
+  requires-committy: ">=1.9.0"
 ---
 
 # Commit with Committy

plugins/committy/skills/committy-enforce/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: committy-enforce
 description: Configure and enforce repository commit and branch conventions with Committy Git hooks and CI. Use when an agent is asked to adopt Committy, define typed convention descriptions or branch ticket rules, install hooks, or add convention checks to GitHub Actions.
+license: Apache-2.0
+allowed-tools: Bash Read Grep Glob Edit Write
+metadata:
+  version: "0.1.0"
+  requires-committy: ">=1.9.0"
 ---
 
 # Enforce with Committy

plugins/committy/skills/committy-release/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: committy-release
 description: Plan and apply version bumps, changelogs, tags, and prereleases with Committy. Use when an agent is asked to prepare, preview, tag, or publish a release, or inspect the release impact of commit history.
+license: Apache-2.0
+allowed-tools: Bash Read Grep Glob
+metadata:
+  version: "0.1.0"
+  requires-committy: ">=1.9.0"
 ---
 
 # Release with Committy
@@ -12,4 +17,4 @@ description: Plan and apply version bumps, changelogs, tags, and prereleases wit
 5. Apply only after mutation is authorized. Publishing additionally requires the CLI confirmation flag; never infer remote-mutation consent.
 6. Report resulting versions, tags, and publish state.
 
-Use `$committy-commit` for ordinary commits and `$committy-enforce` for hooks or CI setup.
+Use the `committy-commit` skill for ordinary commits and `committy-enforce` for hooks or CI setup.

tests/agent_ergonomics_tests.rs

@@ -413,19 +413,24 @@ fn test_capabilities_declare_consent_metadata() {
 fn test_agent_docs_mention_the_non_interactive_env_var() {
     let repo_root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
 
+    // `AGENTS.md` is canonical. Per-runtime files may either restate the rule
+    // or defer to it; what must never happen is a runtime being told nothing.
     let agent_facing = [
         "AGENTS.md",
         "CLAUDE.md",
+        "GEMINI.md",
+        ".github/copilot-instructions.md",
         "docs/src/content/docs/reference/agent-workflows.mdx",
     ];
 
     for relative in agent_facing {
         let body = fs::read_to_string(repo_root.join(relative))
             .unwrap_or_else(|e| panic!("cannot read {relative}: {e}"));
+        let defers_to_canonical = body.contains("AGENTS.md");
         assert!(
-            body.contains("COMMITTY_NONINTERACTIVE"),
-            "{relative} must document COMMITTY_NONINTERACTIVE; it is the escape hatch \
-             that makes flag placement irrelevant for agents"
+            body.contains("COMMITTY_NONINTERACTIVE") || defers_to_canonical,
+            "{relative} must document COMMITTY_NONINTERACTIVE or point at AGENTS.md; \
+             it is the escape hatch that makes flag placement irrelevant for agents"
         );
 
         // Documenting `-v` as global would be worse than not documenting
@@ -436,3 +441,32 @@ fn test_agent_docs_mention_the_non_interactive_env_var() {
         );
     }
 }
+
+/// The cross-tool skill discovery path must resolve to the real skills.
+///
+/// `.agents/skills` is a symlink. If a checkout materialises it as a plain
+/// file (Windows without developer mode, or `core.symlinks=false`), discovery
+/// silently breaks for every runtime that reads that path.
+#[test]
+fn test_skills_are_discoverable_at_the_cross_tool_path() {
+    let repo_root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
+    let cross_tool = repo_root.join(".agents/skills");
+
+    assert!(
+        cross_tool.is_dir(),
+        ".agents/skills must resolve to a directory; if this is a plain file, \
+         the symlink did not survive checkout"
+    );
+
+    for skill in [
+        "committy-branch",
+        "committy-commit",
+        "committy-enforce",
+        "committy-release",
+    ] {
+        assert!(
+            cross_tool.join(skill).join("SKILL.md").is_file(),
+            "{skill}/SKILL.md must be reachable via .agents/skills"
+        );
+    }
+}