git:20260215.b9ef420 to git:20260504.4d670ef

61 added, 47 removed. Audit A to A.

- # Agents Reflection Skills - Development Guide

+ # AI-Driven Development — Development Guide

- ## When to Create Tags and Releases

+ 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.

- **Only create git tags and GitHub releases when skill or plugin files change.**

+ ## When to create tags and releases

- ### Requires New Tag/Release

+ **Only create git tags and GitHub releases when skill, hook, or plugin files change.**

- Changes to these files/directories require a new version tag and release:

+ ### Requires a new tag/release

- - `skills/*/` - Any skill file changes (SKILL.md, scripts, references, assets)

- - `.claude-plugin/plugin.json` - Plugin manifest changes

- - `.claude-plugin/marketplace.json` - Marketplace catalog changes

- - `LICENSE` - License changes

+ - `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

+ - Adding a new skill or hook

- Updating skill instructions in SKILL.md

- Modifying skill scripts

- Changing plugin metadata or version

- ### Does NOT Require New Tag/Release

+ ### Does NOT require a new tag/release

- Documentation-only changes do not require tagging:

+ Documentation-only changes don't need tagging:

- - `README.md` - Documentation and use case updates

- - `CLAUDE.md` - This file

+ - `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 and meaningful.

+ - GitHub-specific files (`.github/*`)

- ## README Maintenance

+ **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.

- Keep all README files in sync when updating documentation:

+ ## README maintenance

- - `README.md` - Main English documentation

- - `README.ru.md` - Russian translation

- - `README.zh.md` - Chinese translation

- - `README.pt-BR.md` - Brazilian Portuguese translation

- - `plugins/agents-reflection-skills/README.md` - Plugin README (required by plugin spec)

+ The repo ships **English-only**. When you add or remove a skill, or change a skill description:

- When adding/removing skills or changing descriptions, update all five files.

+ - 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 semantic versioning (semver):

+ Follow semver:

- - **MAJOR** (x.0.0) - Breaking changes to skill interfaces

- - **MINOR** (1.x.0) - New skills or backward-compatible features

- - **PATCH** (1.0.x) - Bug fixes and minor improvements

+ - **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

+ ## Release process

- When skill/plugin files change:

+ When skill/hook/plugin files change:

- 1. Update version in `.claude-plugin/plugin.json`

- 2. Commit changes

+ 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"`

+ 4. Create GitHub release: `gh release create vX.Y.Z --title "vX.Y.Z — Title" --notes "Release notes"`

- ## Current Structure

+ 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.

+ ## Repository structure

```

- agents-reflection-skills/

+ ai-driven-development/

├── .claude-plugin/

- │ └── plugin.json # Version metadata - changes require release

- ├── skills/ # All changes require release

- │ ├── mcp-management/

- │ ├── hooks-management/

- │ ├── settings-management/

- │ ├── subagents-management/

- │ ├── skills-management/

- │ └── plugins-management/

- ├── README.md # Documentation - no release needed

- ├── CLAUDE.md # This file - no release needed

- └── LICENSE # Changes require release

+ │ ├── 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).

+ 3. Update the Hooks section in the root `README.md`.

+ 4. Bump `version` in both `.claude-plugin/*.json` files.

+ 5. Commit, tag, release.