Skip to content

admin: Add AI coding assistant configuration #5206

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lgritz wants to merge 2 commits into
base: main
Choose a base branch
from
Open

admin: Add AI coding assistant configuration #5206

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
835b3c3
admin: Add AI coding assistant configuration
lgritz May 18, 2026
574fd4c
Take 2: minimal checked-in components, script to do per-tool setup
lgritz May 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
294 changes: 294 additions & 0 deletions .agents/setup-agent
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,294 @@
#!/usr/bin/env bash
# .agents/setup-agent — Set up AI coding tool integration for this repository.
#
# Creates the tool-specific symlinks and config files needed to use the shared
# resources in AGENTS.md and .agents/ with your preferred AI coding assistant.
# Run "setup-agent <tool>" once after cloning; re-running is always safe.
#
# The canonical project instructions live in AGENTS.md (root) and skills live
# in .agents/skills/<name>/SKILL.md. Everything tool-specific is either a
# symlink into those locations, or a thin wrapper that references them.
# Tool-specific directories (.claude/, .cursor/, etc.) are git-ignored so that
# each developer runs this script for the tool they actually use.
#
# ─────────────────────────────────────────────────────────────────────────────
# TOOL STRATEGIES (update this section when tool conventions change)
# ─────────────────────────────────────────────────────────────────────────────
#
# CLAUDE CODE
# Reads: .claude/CLAUDE.md (project) or CLAUDE.md (root) — NOT AGENTS.md natively.
# If Anthropic eventually adds native AGENTS.md support, the
# .claude/CLAUDE.md wrapper can be retired.
# Skills: .claude/skills/ (each subdirectory is a skill)
# Setup: Write .claude/CLAUDE.md containing "@AGENTS.md" (Claude's include
# syntax), symlink .claude/skills -> ../.agents/skills.
# Docs: https://docs.anthropic.com/en/docs/claude-code/memory
# https://docs.anthropic.com/en/docs/claude-code/skills
#
# OPENAI CODEX
# Reads: AGENTS.md natively — no wrapper needed.
# Skills: .agents/skills/ natively, and also .codex/skills/ as a fallback.
# Setup: Symlink .codex/skills -> ../.agents/skills so either path works.
# Docs: https://developers.openai.com/codex/guides/agents-md
# https://developers.openai.com/codex/skills
#
# CURSOR
# Reads: .cursor/rules/*.mdc files — does NOT read AGENTS.md natively.
# If Cursor adds native AGENTS.md support, the rules symlink can be
# retired.
# Skills: Cursor uses a different slash-command mechanism; .agents/skills/
# are not directly usable today, but the convention may change.
# Setup: Symlink .cursor/rules/project.mdc -> ../../AGENTS.md so Cursor
# picks up our instructions as a project rule.
# Docs: https://docs.cursor.com/context/rules-for-ai
# https://docs.cursor.com/cmdk/overview
#
# OPENCODE
# Reads: AGENTS.md natively — no wrapper needed.
# Skills: Documented to read .agents/skills/ natively, but in practice also
# requires .opencode/commands/<name>.md symlinks (as of 2025-05).
# Remove the per-command symlinks once opencode reliably finds
# .agents/skills/ on its own.
# Setup: Symlink .opencode/skills -> ../.agents/skills (future-proof),
# plus individual .opencode/commands/<name>.md -> skill SKILL.md
# files (current workaround).
# Docs: https://opencode.ai/docs/configuration
# https://opencode.ai/docs/skills
#
# GITHUB COPILOT
# Reads: AGENTS.md natively (VS Code Copilot ≥ 1.99 / GitHub Copilot Chat).
# Also reads .github/copilot-instructions.md as a fallback for older
# clients or non-VS Code surfaces.
# Skills: .agents/skills/ natively supported.
# Setup: Symlink .github/copilot-instructions.md -> ../AGENTS.md so older
# clients also receive our instructions. Remove once all Copilot
# surfaces reliably pick up AGENTS.md directly.
# Docs: https://code.visualstudio.com/docs/copilot/customization/custom-instructions
# https://docs.github.com/en/copilot/concepts/about-prompting-copilot
# https://docs.github.com/en/copilot/concepts/agents/about-agent-skills
# ─────────────────────────────────────────────────────────────────────────────

set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
SKILLS_DIR=".agents/skills"
SUPPORTED_TOOLS="claude codex cursor opencode copilot"

usage() {
cat <<EOF
Usage: .agents/setup-agent <tool|all|clear|list> [tool...]

Commands:
<tool> [...] Set up one or more tools
all Set up all supported tools
clear Remove all tool-specific setup created by this script
clear <tool> Remove setup for one specific tool
list List supported tools

Supported tools: $SUPPORTED_TOOLS

Examples:
.agents/setup-agent claude
.agents/setup-agent claude cursor
.agents/setup-agent all
.agents/setup-agent clear
.agents/setup-agent clear opencode
EOF
}

rel() { echo "${1#"$REPO_ROOT"/}"; }

# Create a symlink only if the path doesn't already exist.
# Silent if the link already points to the correct target.
safe_symlink() {
local link="$1" target="$2"
if [ -L "$link" ] && [ "$(readlink "$link")" = "$target" ]; then
return 0
elif [ -e "$link" ] || [ -L "$link" ]; then
echo " SKIP (already exists): $(rel "$link")"
return 0
fi
mkdir -p "$(dirname "$link")"
ln -s "$target" "$link"
echo " LINK: $(rel "$link") -> $target"
}

# Write a file only if the path doesn't already exist.
safe_write() {
local file="$1"
shift
local content="$*"
if [ -e "$file" ]; then
echo " SKIP (already exists): $(rel "$file")"
return 0
fi
mkdir -p "$(dirname "$file")"
printf '%s\n' "$content" > "$file"
echo " FILE: $(rel "$file")"
}

# Remove a symlink only if it still points to the expected target.
safe_remove_symlink() {
local link="$1" expected_target="$2"
[ ! -L "$link" ] && return 0
if [ "$(readlink "$link")" = "$expected_target" ]; then
rm "$link"
echo " REMOVED: $(rel "$link")"
else
echo " SKIP (modified, not removing): $(rel "$link")"
fi
}

# Remove a file only if its content still matches what we wrote.
safe_remove_file() {
local file="$1"
shift
local expected="$*"
[ ! -f "$file" ] || [ -L "$file" ] && return 0
if [ "$(cat "$file")" = "$expected" ]; then
rm "$file"
echo " REMOVED: $(rel "$file")"
else
echo " SKIP (modified, not removing): $(rel "$file")"
fi
}

try_rmdir() { rmdir "$1" 2>/dev/null && echo " RMDIR: $(rel "$1")" || true; }

#------------------------------------------------------------------------------
# Claude Code (.claude/)
#------------------------------------------------------------------------------
setup_claude() {
echo "Setting up Claude Code..."
safe_write "$REPO_ROOT/.claude/CLAUDE.md" "@AGENTS.md"
safe_symlink "$REPO_ROOT/.claude/skills" "../.agents/skills"
safe_write "$REPO_ROOT/.claude/.gitignore" "settings.local.json"
}
clear_claude() {
echo "Removing Claude Code setup..."
safe_remove_file "$REPO_ROOT/.claude/CLAUDE.md" "@AGENTS.md"
safe_remove_symlink "$REPO_ROOT/.claude/skills" "../.agents/skills"
safe_remove_file "$REPO_ROOT/.claude/.gitignore" "settings.local.json"
try_rmdir "$REPO_ROOT/.claude"
}

#------------------------------------------------------------------------------
# OpenAI Codex (.codex/)
#------------------------------------------------------------------------------
setup_codex() {
echo "Setting up OpenAI Codex..."
safe_symlink "$REPO_ROOT/.codex/skills" "../.agents/skills"
safe_write "$REPO_ROOT/.codex/.gitignore" "*.log"
}
clear_codex() {
echo "Removing OpenAI Codex setup..."
safe_remove_symlink "$REPO_ROOT/.codex/skills" "../.agents/skills"
safe_remove_file "$REPO_ROOT/.codex/.gitignore" "*.log"
try_rmdir "$REPO_ROOT/.codex"
}

#------------------------------------------------------------------------------
# Cursor (.cursor/)
#------------------------------------------------------------------------------
setup_cursor() {
echo "Setting up Cursor..."
safe_symlink "$REPO_ROOT/.cursor/rules/project.mdc" "../../AGENTS.md"
safe_write "$REPO_ROOT/.cursor/.gitignore" "$(printf 'composer/\nchat/')"
}
clear_cursor() {
echo "Removing Cursor setup..."
safe_remove_symlink "$REPO_ROOT/.cursor/rules/project.mdc" "../../AGENTS.md"
safe_remove_file "$REPO_ROOT/.cursor/.gitignore" "$(printf 'composer/\nchat/')"
try_rmdir "$REPO_ROOT/.cursor/rules"
try_rmdir "$REPO_ROOT/.cursor"
}

#------------------------------------------------------------------------------
# Opencode (.opencode/)
#------------------------------------------------------------------------------
OPENCODE_GITIGNORE="$(printf 'node_modules\npackage.json\npackage-lock.json\nbun.lock')"

setup_opencode() {
echo "Setting up Opencode..."
safe_symlink "$REPO_ROOT/.opencode/skills" "../.agents/skills"
safe_write "$REPO_ROOT/.opencode/.gitignore" "$OPENCODE_GITIGNORE"
# Individual command links (needed in practice despite docs implying otherwise)
for skill_dir in "$REPO_ROOT/$SKILLS_DIR"/*/; do
[ -d "$skill_dir" ] || continue
local skill_name
skill_name="$(basename "$skill_dir")"
safe_symlink "$REPO_ROOT/.opencode/commands/${skill_name}.md" \
"../../$SKILLS_DIR/${skill_name}/SKILL.md"
done
}
clear_opencode() {
echo "Removing Opencode setup..."
safe_remove_symlink "$REPO_ROOT/.opencode/skills" "../.agents/skills"
safe_remove_file "$REPO_ROOT/.opencode/.gitignore" "$OPENCODE_GITIGNORE"
for skill_dir in "$REPO_ROOT/$SKILLS_DIR"/*/; do
[ -d "$skill_dir" ] || continue
local skill_name
skill_name="$(basename "$skill_dir")"
safe_remove_symlink "$REPO_ROOT/.opencode/commands/${skill_name}.md" \
"../../$SKILLS_DIR/${skill_name}/SKILL.md"
done
try_rmdir "$REPO_ROOT/.opencode/commands"
try_rmdir "$REPO_ROOT/.opencode"
}

#------------------------------------------------------------------------------
# GitHub Copilot (.github/copilot-instructions.md)
# Copilot natively reads AGENTS.md, but also checks copilot-instructions.md.
#------------------------------------------------------------------------------
setup_copilot() {
echo "Setting up GitHub Copilot..."
safe_symlink "$REPO_ROOT/.github/copilot-instructions.md" "../AGENTS.md"
}
clear_copilot() {
echo "Removing GitHub Copilot setup..."
safe_remove_symlink "$REPO_ROOT/.github/copilot-instructions.md" "../AGENTS.md"
}

#------------------------------------------------------------------------------
# Dispatch
#------------------------------------------------------------------------------
run_tool() {
local action="$1" tool="$2"
case "$tool" in
claude) "${action}_claude" ;;
codex) "${action}_codex" ;;
cursor) "${action}_cursor" ;;
opencode) "${action}_opencode" ;;
copilot) "${action}_copilot" ;;
*)
echo "Unknown tool: $tool (supported: $SUPPORTED_TOOLS)" >&2
exit 1
;;
esac
}

[ $# -eq 0 ] && { usage; exit 0; }

case "$1" in
all)
for t in $SUPPORTED_TOOLS; do run_tool setup "$t"; done
;;
clear)
shift
if [ $# -eq 0 ]; then
for t in $SUPPORTED_TOOLS; do run_tool clear "$t"; done
else
for t in "$@"; do run_tool clear "$t"; done
fi
;;
list)
echo "Supported tools: $SUPPORTED_TOOLS"
;;
-h|--help|help)
usage
;;
*)
for t in "$@"; do run_tool setup "$t"; done
;;
esac
104 changes: 104 additions & 0 deletions .agents/skills/prepare-patch-release/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
---
name: prepare-patch-release
description: Do all the tasks needed for a patch release of the project.
argument-hint: [new-version]
---

Do all the tasks needed for a patch release of the project. These patch
releases generally happen on the first day of every month.

Arguments: `$ARGUMENTS`
- First argument (optional): the version of the upcoming release we are
preparing. If omitted, find the most recent tag on this branch, and the
new version will update the third portion of the version. It might be
either a version number (like `3.1.4.0`) or a tag (like `v3.1.4.0`).

Hint: The numeric "version" is a four-part numeric deignation with the pattern
`MAJOR.MINOR.PATCH.TWEAK`. The "version tag" is usually the numeric version
with a "v" prepended, for example, `v3.1.4.0`.

## Steps and Checklist

- [ ] Determine the version of the new release.
- [ ] Update the main @CMakeLists.txt.
- [ ] Use the "release-notes-update" skill to update @CHANGES.md.
- [ ] Review the release notes to ensure that the changes do not deprecate any
API calls or break API or ABI backward-compatibility, or remove support
for any dependency or toolchain versions. If you think these rules are
being violated, ask for confirmation.
- [ ] Review @README.md for changes.
- [ ] Review @INSTALL.md for changes.
- [ ] Review @CREDITS.md for changes.
- [ ] Review @SECURITY.md for changes.

## Steps to determine the versions of the last and new releases.

1. **Determine the previous tag** if not provided by looking at the
most recent git tag in the current branch, and deducing the 4-part
version number from that.
2. The assumed new version for a patch release has the same major and minor
numbers, the patch number is incremented by one since the last tag, and the
tweak number is "0".
3. If no optional version was present in the arguments, use the assumed new
version.
4. If a version was supplied in the arguments, double check that it differs
from the last tag as explained above. If it does not, ask for verification
that the version requested is correct before proceeding.

## Steps to update CMakeLists.txt

1. In the main @CMakeLists.txt, alter the version to that of the new release,
if it isn't already the same.
2. For a patch release, ensure that `${PROJECT_NAME}_SUPPORTED_RELEASE` should
be set to ON. In main (not yet a supported release) it shold be OFF. If you
find these to not be as expected, ask for confirmation of whether to fix.
3. For a patch release, `PROJECT_VERSEION_RELEASE_TYPE` should be set to empty
(""). In main, it will typically be "dev", "beta", or other designations.
If you find these to not be as expected, ask for confirmation of whether to
fix.

## Reviewing README.md

If this release added support for any new image file formats, be sure that
README.md mentions them in its list of image formats supported.

## Reviewing INSTALL.md

If any of the new commits (as described in the release notes for this version)
appear to add dependencies, or add support for new versions of dependencies,
be sure that INSTALL.md is updated to include that dependency (if not already
listed among the required and optional dependencies), and reflects the latest
version that we claim to support.

Double check @externalpackages.cmake and ensure that any minimum required
versions of dependencies that cmake will enforce match the oldest versions
of those dependencies as documentd in INSTALL.md.

## Reviewing CREDITS.md

The @CREDITS.md file lists all known contributors to the project, sorted alpha
by first name. In cases where an author's actual name is unknown, we use the
GitHub userid.

Ensure that any authors referenced in the new release notes for the version we
are releasing are inserted in the credit list, if they are not already
present. You don't need to check older versions, we presume those have already
been included.

## Reviewing SECURITY.md

The @SECURITY.md file lists which versions are currently supported at what
levels, and lists all previously-fixed SVE's or security advisories. Be sure
to check this file in older branches (the last two releases, say), and if you
are preparing a patch release, also check in main and more recent (higher
numbered) releases for more recently modified SECURITY.md, and be sure that
this branch gets amended with any information that seems to have been updated
more recently in those other branches. Check whichever is newer of the local
and remote copy of that branch, since the local one may have had release notes
or its version in CMakeLists.txt updated, but not yet pushed to GitHub.


## Reference

- Full release procedures: `docs/dev/RELEASING.md`
- Steps for updating release notes: `release-notes-update/SKILL.md`
Loading
Loading