CLAUDE.md · diff
git:20260504.4d670ef to git:20260504.c704c26
2 added, 2 removed. Audit A to A.
# AI-Driven Development — Development Guide
This repo is a single-plugin marketplace and a cross-agent skill collection in one. The same `skills/` directory at the repo root is read by both `npx skills add` (the cross-agent CLI) and Claude Code's plugin install (`/plugin marketplace add` + `/plugin install …@ai-driven-development`). The plugin sees the repo root as itself via `source: "./"` in `marketplace.json` — no nesting, no symlinks, no duplication.
## When to create tags and releases
**Only create git tags and GitHub releases when skill, hook, or plugin files change.**
### Requires a new tag/release
- `skills/*/` — any skill file changes (SKILL.md, scripts, references, assets)
- `hooks/*/` — any hook source changes (Go code, install scripts, hook configs)
- `.claude-plugin/plugin.json` — plugin manifest changes
- `.claude-plugin/marketplace.json` — marketplace catalogue changes
- `LICENSE` — licence changes
Examples:
- Adding a new skill or hook
- Updating skill instructions in SKILL.md
- Modifying skill scripts
- Changing plugin metadata or version
### Does NOT require a new tag/release
Documentation-only changes don't need tagging:
- `README.md` — documentation and use-case updates
- `CLAUDE.md` — this file
- Commit messages
- GitHub-specific files (`.github/*`)
**Rationale:** users install specific commits via SHA. Documentation updates don't affect functionality, so they don't need version bumps. This keeps the release history clean.
## README maintenance
The repo ships **English-only**. When you add or remove a skill, or change a skill description:
- Update the relevant section table in `README.md`
- Update the skill's own `SKILL.md` (agent-facing) and `README.md` (human-facing, optional)
- Update `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json` versions
## Versioning
Follow semver:
- **MAJOR** (x.0.0) — breaking changes to skill interfaces, removals, layout overhauls
- **MINOR** (X.x.0) — new skills, new hooks, backward-compatible features
- **PATCH** (X.X.x) — bug fixes, prompt tweaks, doc fixes that ship in skills
## Release process
When skill/hook/plugin files change:
1. Bump version in `.claude-plugin/plugin.json` AND `.claude-plugin/marketplace.json` (keep them in sync).
2. Commit changes.
3. Create and push tag: `git tag -a vX.Y.Z -m "Version X.Y.Z" && git push origin vX.Y.Z`
4. Create GitHub release: `gh release create vX.Y.Z --title "vX.Y.Z — Title" --notes "Release notes"`
- The bash-guard hook ships its own pre-built binary release with a separate tag (`bash-guard-vX.Y.Z`) — see [hooks/optimal-safety-hooks/](hooks/optimal-safety-hooks/) for that release flow.
+ The bash-guard hook ships its own pre-built binary release with a separate tag (`bash-guard-vX.Y.Z`) — see [hooks/balanced-safety-hooks/](hooks/balanced-safety-hooks/) for that release flow.
## Repository structure
```
ai-driven-development/
├── .claude-plugin/
│ ├── marketplace.json ← single-plugin marketplace, source: "./"
│ └── plugin.json
├── skills/ ← canonical Agent Skills layout (npx skills add)
│ └── <skill-name>/SKILL.md (+ optional README.md, references/, scripts/, assets/)
├── hooks/
│ └── <hook-name>/ ← Claude Code hooks (Go binary + install scripts)
├── README.md
├── CLAUDE.md
└── LICENSE
```
## Adding a new skill
1. Create `skills/<skill-name>/SKILL.md` with YAML frontmatter (`name`, `description`).
2. Add optional `README.md`, `references/`, `scripts/`, `assets/` as needed.
3. Update the relevant section table in the root `README.md`.
4. Bump `version` in both `.claude-plugin/*.json` files (minor bump for new skill).
5. Commit, tag, release.
## Adding a new hook
1. Create `hooks/<hook-name>/` with the hook implementation, `install.sh`, and `README.md`.
- 2. If the hook ships pre-built binaries, add a release flow (see `hooks/optimal-safety-hooks/` as the canonical example: cross-platform Go build via `make build-all`, GitHub release with `SHA256SUMS`, `install-prebuilt.sh` that pins by tag).
+ 2. If the hook ships pre-built binaries, add a release flow (see `hooks/balanced-safety-hooks/` as the canonical example: cross-platform Go build via `make build-all`, GitHub release with `SHA256SUMS`, `install-prebuilt.sh` that pins by tag).
3. Update the Hooks section in the root `README.md`.
4. Bump `version` in both `.claude-plugin/*.json` files.
5. Commit, tag, release.