Add CLAUDE.md documenting repo architecture and conventions
This commit is contained in:
Henner M. Kruse
@@ -0,0 +1,129 @@
|
|||||||
|
# CLAUDE.md
|
||||||
|
|
||||||
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||||
|
|
||||||
|
## What this repo is
|
||||||
|
|
||||||
|
`skill-repo`: a private collection of tool-neutral [Agent Skills](https://agentskills.io)
|
||||||
|
(`SKILL.md` + `scripts/`), currently two plugins for Claude Code:
|
||||||
|
|
||||||
|
- **`git-manager`** — routes all git operations through one wrapper script
|
||||||
|
(`skills/git-manager/scripts/git_cmd.sh`) so multi-repo work never needs
|
||||||
|
`cd` or shell chaining (`&&`, `;`, `|`), which is what breaks Bash
|
||||||
|
permission whitelisting.
|
||||||
|
- **`obsidian-vault-kb`** — turns an Obsidian vault into a searchable
|
||||||
|
knowledge base via three wrapper scripts (`vault_index.sh`,
|
||||||
|
`vault_search.sh`, `vault_backlinks.sh`).
|
||||||
|
|
||||||
|
There is no build, lint, or test tooling in this repo — it's shell scripts
|
||||||
|
plus Markdown/JSON, exercised by running the wrapper scripts directly (e.g.
|
||||||
|
`skills/git-manager/scripts/git_cmd.sh status --repo <name>`) or by
|
||||||
|
installing the plugin in Claude Code and running its `/‹plugin›:setup`
|
||||||
|
command.
|
||||||
|
|
||||||
|
## If you're operating from the `skills` local checkout wrapper
|
||||||
|
|
||||||
|
If this repo is checked out at `<workspace>/repo/` with a sibling
|
||||||
|
`<workspace>/.claude/` holding local, un-versioned Claude Code settings
|
||||||
|
(that's the standard local layout for this repo), the working directory
|
||||||
|
Claude Code starts in is `<workspace>`, one level above this repo root —
|
||||||
|
**use the `git-manager` skill for all git operations** (`status`, `commit`,
|
||||||
|
`push`, etc.), not raw `git`/`cd`, registered there with `--repo skills`
|
||||||
|
pointing at this directory. Raw `git -C <workspace>/repo ...` or
|
||||||
|
`cd <workspace>/repo && git ...` works mechanically but bypasses the
|
||||||
|
whitelisted wrapper that setup is built around.
|
||||||
|
|
||||||
|
## Architecture: `skills/` vs `vendor/`
|
||||||
|
|
||||||
|
The repo (see `ARCHITECTURE.md`) deliberately splits tool-neutral skill
|
||||||
|
content from host-tool-specific plumbing:
|
||||||
|
|
||||||
|
```
|
||||||
|
.
|
||||||
|
├── skills/<name>/ # canonical, tool-neutral — SKILL.md, scripts/, references/
|
||||||
|
└── vendor/claude-code/plugins/<name>/ # Claude Code-specific adapter
|
||||||
|
├── .claude-plugin/plugin.json
|
||||||
|
├── skills/<name> -> ../../../../../skills/<name> (symlink, not a copy)
|
||||||
|
├── commands/setup.md # -> /<name>:setup
|
||||||
|
├── permissions-whitelist.template.json
|
||||||
|
└── hooks/ # git-manager only, currently
|
||||||
|
```
|
||||||
|
|
||||||
|
- `skills/<name>/` is the *only* place skill content lives. It assumes
|
||||||
|
nothing about the host tool: config is read from
|
||||||
|
`~/.agent-skills/<name>/config.json`, never a Claude-specific path, so the
|
||||||
|
same `SKILL.md` works unmodified in other Agent-Skills-compatible tools.
|
||||||
|
- `vendor/claude-code/plugins/<name>/` holds everything Claude Code-specific:
|
||||||
|
plugin manifest, `Bash(...)` permission whitelist, the `/setup` slash
|
||||||
|
command, and (for git-manager) `PreToolUse` hooks. Its `skills/<name>` is
|
||||||
|
a symlink back into the top-level `skills/` dir — never a duplicated copy
|
||||||
|
that can drift.
|
||||||
|
- `.claude-plugin/marketplace.json` lists both plugins and must live at the
|
||||||
|
repo root (Claude Code convention, not `vendor/claude-code/`).
|
||||||
|
|
||||||
|
Adding a third host tool (e.g. Codex) means adding a new `vendor/<tool>/`
|
||||||
|
tree symlinked back to the same `skills/<name>/`, without touching skill
|
||||||
|
content.
|
||||||
|
|
||||||
|
## The permission-whitelisting philosophy (applies to every plugin here)
|
||||||
|
|
||||||
|
This is the design constraint that shapes almost every file in this repo —
|
||||||
|
worth understanding before editing any wrapper script, `setup.sh`, or
|
||||||
|
`permissions-whitelist.template.json`:
|
||||||
|
|
||||||
|
- **Never whitelist a generic command.** No `Bash(git:*)`, `Bash(find:*)`,
|
||||||
|
`Bash(cd:*)`. Each plugin whitelists exactly one (or a few) wrapper
|
||||||
|
script(s), pinned by exact absolute path. The wrapper enforces its own
|
||||||
|
scope (allowed subcommands, vault boundaries) — the whitelist entry just
|
||||||
|
says "this specific, self-limiting script may run without asking."
|
||||||
|
- **Wrapper scripts never accept a raw filesystem path from the caller.**
|
||||||
|
They resolve everything (repo path, vault path) from a config file at
|
||||||
|
`~/.agent-skills/<name>/config.json` by *name*. This is what makes
|
||||||
|
whitelisting the script by path safe — it can't be pointed at an arbitrary
|
||||||
|
directory.
|
||||||
|
- **Setup copies scripts to a stable, self-owned location before writing any
|
||||||
|
permission rule** — `~/.agent-skills/<name>/bin/`, never Claude Code's
|
||||||
|
internal plugin cache path (`~/.claude/plugins/cache/.../<version>/`),
|
||||||
|
which changes on every plugin version bump. This is why each `setup.sh`
|
||||||
|
does "copy scripts → write permissions → write config" in that order, and
|
||||||
|
why permission rules are written in **tilde form** (`~/...`), matching the
|
||||||
|
literal unexpanded command text Claude Code matches against — not the
|
||||||
|
resolved `$HOME` path.
|
||||||
|
- **Nothing destructive is silently whitelisted.** Config-file writes
|
||||||
|
(registering a new repo/vault) and anything outside the fixed
|
||||||
|
subcommand/action allowlist always fall through to a normal confirmation
|
||||||
|
prompt.
|
||||||
|
- **Optional `PreToolUse` hooks are advisory, never blocking.** They only
|
||||||
|
ever emit `permissionDecision: "ask"` (never `"deny"`, never `"allow"`) —
|
||||||
|
see `force-ask-on-chaining.sh` and `force-ask-on-raw-git.sh` in
|
||||||
|
`vendor/claude-code/plugins/git-manager/hooks/`. If `jq` is missing they
|
||||||
|
fail open (no output) rather than block every Bash call.
|
||||||
|
|
||||||
|
## Adding a new skill
|
||||||
|
|
||||||
|
Documented in full in `ARCHITECTURE.md`; short version:
|
||||||
|
|
||||||
|
1. `skills/<new-name>/` with `SKILL.md` (+ `scripts/`/`references/` as
|
||||||
|
needed). Config path: `~/.agent-skills/<new-name>/config.json`.
|
||||||
|
2. `vendor/claude-code/plugins/<new-name>/` with `.claude-plugin/plugin.json`,
|
||||||
|
a `skills/<new-name>` symlink back to the top-level skill dir, and — if
|
||||||
|
the skill needs restricted shell access — `commands/setup.md` plus
|
||||||
|
`permissions-whitelist.template.json` following the existing plugins'
|
||||||
|
pattern (wrapper scripts that resolve scope from config, whitelisted only
|
||||||
|
by exact absolute path).
|
||||||
|
3. Add an entry to `.claude-plugin/marketplace.json`.
|
||||||
|
4. Bump `version` in both the plugin's `plugin.json` and its
|
||||||
|
`marketplace.json` entry on any update.
|
||||||
|
|
||||||
|
## Gotchas specific to this repo
|
||||||
|
|
||||||
|
- Symlinks (`vendor/.../skills/<name> -> ../../../../../skills/<name>`)
|
||||||
|
assume POSIX; this repo doesn't try to be Windows-checkout-friendly.
|
||||||
|
- `permissions-whitelist.template.json` files are **reference/documentation
|
||||||
|
only** — the actual rules are generated and written by each plugin's
|
||||||
|
`scripts/setup.sh`, not read from the template at runtime.
|
||||||
|
- git-manager's wrapper deliberately rejects `stash`, `merge`, `rebase`,
|
||||||
|
`reset`, and arbitrary `git config` — these can rewrite/discard
|
||||||
|
history or working-tree state irreversibly. Raw `git` remains a valid,
|
||||||
|
visible fallback for those (nudged, not blocked, by
|
||||||
|
`force-ask-on-raw-git.sh` if that hook is installed).
|
||||||
Reference in New Issue
Block a user