Addon based agentic AI instructions - POC

[jakubjezek001]

This is a proposal on how to approach the agentic instructions. This currently a single file living in root of repository, but each folder can have its own AGENTS.md file with instrucitons for particular structure. The instructions should not be very long so we keep token spending at minimal, but should help agent to understand the repository quickly.

Changelog Description

wip

Additional review information

wip

Testing notes:

1. start with this step
2. follow this step

[jakubjezek001]

here is some reading for those interested in multirepository agentic instructions distributions and git worktree proved concept. I will be testing it so will see how limited this might be. https://www.ricky-dev.com/coding/2026/01/agentic-tooling-across-multiple-repositories/

[jakubjezek001]

Another inspiring approach for dealing with .agents/skills can be found in https://github.com/openclaw/openclaw repository. Each agentic harness can have own folder in root, such .kilo/skills , .claude/skills, .pi/rules and each are just a simling of .agents/skills.

Next steps:

• are there any git create worktree hook/callbacks and how can those be leveraged for agentic instruction distribution?
• can AGENTS.md at addon root level reference another AGENTS.md instruction above the addon root folder? This way the worktree hook/callback could pull general AYON repositoriy agentic instructions every time worktree is created and put it above the repository root within the BRANCH folder.

[jakubjezek001]

1. Add this to your .git/hooks folder as post-checkout file and make sure it is executable. Make sure you are at root repository git and not in a worktree
2. make sure you are replacing <org><repo> at line 47
3. create new worktree

#!/bin/bash

# 0. Ensure this hook script is executable. Git will silently skip hooks
# that don't have the executable bit set, so we self-correct here and
# also make sure future copies of this file remain executable.
if [ ! -x "$0" ]; then
    chmod +x "$0" 2>/dev/null
fi

# 1. Capture the Git hook arguments
PREV_HEAD="$1"
NEW_HEAD="$2"
IS_BRANCH_CHECKOUT="$3"

# 2. Check if this is a brand new worktree creation
# New worktrees always have an empty all-zero hash for the previous HEAD,
# and the branch checkout flag must be 1, and we must be inside a worktree
# (not the main working tree) to avoid triggering on the initial clone/checkout.
IS_WORKTREE=$(git rev-parse --is-inside-work-tree 2>/dev/null)
GIT_COMMON_DIR=$(git rev-parse --git-common-dir 2>/dev/null)
GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)

if [ "$PREV_HEAD" = "0000000000000000000000000000000000000000" ] \
   && [ "$IS_BRANCH_CHECKOUT" = "1" ] \
   && [ "$IS_WORKTREE" = "true" ] \
   && [ "$GIT_DIR" != "$GIT_COMMON_DIR" ]; then

    # Target directory where the hook is currently running
    CURRENT_WORKTREE_DIR=$(pwd)

    # Extract the current branch name
    CURRENT_BRANCH=$(git symbolic-ref --short HEAD)

    echo "⚙️ New worktree detected for branch [$CURRENT_BRANCH] at: $CURRENT_WORKTREE_DIR"

    # Current location: /project_root/worktrees/[BRANCH]/[repo_root]
    # We want to go up one level to: /project_root/worktrees/[BRANCH]/
    BRANCH_FOLDER=$(dirname "$CURRENT_WORKTREE_DIR")

    echo "🚚 Fetching shared rules/data into branch root: $BRANCH_FOLDER"

    # 4. Pull data from your external central standards repository
    # Using a shallow clone to pull data into a folder named 'central-rules'
    # Only clone if it doesn't already exist to avoid duplicate work on repeated triggers
    if [ ! -d "$BRANCH_FOLDER/central-rules" ]; then
        mkdir -p "$BRANCH_FOLDER"
        git clone --depth 1 https://github.com/<org>/<repo>.git "$BRANCH_FOLDER/agentic-instructions"
    else
        echo "ℹ️ agentic-instructions already exists at $BRANCH_FOLDER, skipping clone."
    fi

    echo "✅ Workspace initialization complete for $CURRENT_BRANCH."
fi

[jakubjezek001]

are we really version tracking uv.lock for documentation @BigRoy ?

[jakubjezek001]

main reason for this soft link is that I could not find a way to direct an agent to read from outside directory. So here are two ways of using this linked folder. Once in a branch at the main worktree, it is using this soft link leading to the sidecar folder (I am usually having all ayon related repositories in single project folder). Then once the git hook is activated and new worktree is created, this softlink is overridden by git clonned repo from this line https://github.com/ynput/ayon-nuke/pull/349/changes#diff-1de7a1e2dcc8a89878c79c478d375256391a47f0b418e22852cf2292e8998fd9R40

[jakubjezek001]

I am not sure if this is good approach but it is best I could find. The hook is important to be added, but it requires a single manual step.