ai-instructions

Central, version-controlled home for AI agent instructions and shared context used across Ocean Protocol repositories.

The goal is one source of truth: instead of every repo maintaining its own drifting copy of agent definitions, they all pull from here as a git submodule and stay in sync by bumping a commit pointer.

What's in here

ai-instructions/
├── agents/          # Claude Code subagent definitions (one .md per agent, with frontmatter)
│   └── README.md    # Full roster, routing cheat-sheet, and design rationale
├── hooks/           # Claude Code hooks: format+lint, destructive-command guard, PostCompact refresh
│   ├── README.md    # What each hook does, rollout status, how to add a new one
│   └── settings.snippet.json  # Copy-paste .claude/settings.json block that wires them up
└── README.md        # This file

• agents/ — Markdown agent definitions (name, description, tools, model, effort frontmatter + system prompt) for roles like architect, backend-developer, security-check, etc. See agents/README.md for the full roster and when to use each one.
• hooks/ — Shell scripts for Claude Code lifecycle hooks (auto format/lint, block destructive commands, refresh context after compaction). See hooks/README.md for what each one does and its rollout status.

More categories of shared AI context (e.g. skills, prompt fragments, style guides) may be added here over time as they're identified — this repo is meant to be the general-purpose container for "things AI agents should know or use" across the Ocean Protocol org.

Using this repo as a submodule

Consumer repos add this repo as a git submodule, then point Claude Code at it (or the tool of your choice) so its contents get picked up automatically.

Add the submodule

From the root of the consuming repo:

git submodule add https://github.com/oceanprotocol/ai-instructions.git ai-instructions
git commit -m "Add ai-instructions submodule"

This clones the repo into ./ai-instructions and records the exact commit it's pinned to in .gitmodules and the parent repo's tree — it will not auto-update on its own.

Wire up Claude Code agents

Claude Code loads subagents from .claude/agents/. Symlink that path to the submodule's agents/ folder so definitions load without duplication:

mkdir -p .claude
ln -s ../ai-instructions/agents .claude/agents
git add .claude/agents ai-instructions .gitmodules
git commit -m "Wire up shared agents from ai-instructions"

(If .claude/ is already used for repo-specific settings, symlink just the agents subdirectory as above rather than the whole .claude/ folder.)

Wire up Claude Code hooks

Unlike agents, Claude Code doesn't auto-discover a hooks folder — hooks must be declared explicitly in .claude/settings.json. So wiring up hooks is two steps: symlink the scripts in (same idea as agents), then merge the hook configuration into that repo's settings.

1. Symlink the hooks folder:

   mkdir -p .claude
   ln -s ../ai-instructions/hooks .claude/hooks
   git add .claude/hooks ai-instructions .gitmodules

2. Merge hooks/settings.snippet.json into .claude/settings.json. If the repo already has a .claude/settings.json with its own keys (permissions, env, other hooks), merge the hooks block in — don't overwrite the file. If there's no existing file, you can copy the snippet in as-is:

   cp hooks/settings.snippet.json .claude/settings.json   # only if the file doesn't already exist
   git add .claude/settings.json
   git commit -m "Wire up shared hooks from ai-instructions"

3. Verify before merging the PR. Each hook reads a JSON payload on stdin, so you can pipe-test it directly against this repo's own files instead of trusting it blind:

   export CLAUDE_PROJECT_DIR="$(pwd)"
   
   # format-and-lint.sh (PostToolUse, Write|Edit) — point at a real file in this repo
   echo '{"tool_name":"Edit","tool_input":{"file_path":"'"$CLAUDE_PROJECT_DIR"'/path/to/file.ts"}}' \
     | .claude/hooks/format-and-lint.sh
   
   # block-destructive.sh (PreToolUse, Bash) — should print a "deny" decision
   echo '{"tool_name":"Bash","tool_input":{"command":"git push --force"}}' \
     | .claude/hooks/block-destructive.sh
   
   # refresh-context.sh (PostCompact) — should print additionalContext JSON
   echo '{"session_id":"test","trigger":"auto"}' | .claude/hooks/refresh-context.sh

   If a hook errors out or does nothing when it should act, check that the project's toolchain matches what the hook expects (see the "Known limitation" note in hooks/README.md) before merging.

4. Reload the config. New or edited hooks under .claude/ only take effect once Claude Code picks up the settings change — open /hooks once in an interactive session (or restart) after merging.

Cloning a repo that already has this submodule

Submodules are not checked out by a plain git clone. Use one of:

git clone --recurse-submodules <consumer-repo-url>

# or, if already cloned:
git submodule update --init --recursive

Pulling in updates

Submodules pin to a specific commit, so updates in ai-instructions don't automatically appear in consumer repos. To bump the pointer to the latest commit:

git submodule update --remote ai-instructions
git add ai-instructions
git commit -m "Bump ai-instructions submodule"

To pin to a specific tag/branch instead of always tracking the default branch, set it once:

git config -f .gitmodules submodule.ai-instructions.branch <branch-or-tag>
git submodule update --remote ai-instructions

Making changes

Treat ai-instructions as its own repo even when accessed through a submodule path — cd into it, branch, commit, and push there directly (or open a PR against oceanprotocol/ai-instructions). Then bump the pointer in the consumer repo(s) as above so they pick up the change. Avoid editing files under a submodule path and committing from the parent repo; it works, but changes are easy to lose track of since they live in a detached-HEAD checkout by default.

Contributing

• Keep additions generic enough to be useful across repos — repo-specific instructions belong in that repo's own CLAUDE.md or config, not here.
• When adding or changing an agent, update agents/README.md's roster table and routing cheat-sheet in the same change.
• When adding or changing a hook, update hooks/README.md's table and hooks/settings.snippet.json in the same change, and pipe-test it against at least one consumer repo before merging.