conventional-git 1.2.0__tar.gz → 2.1.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {conventional_git-1.2.0 → conventional_git-2.1.1}/.claude-plugin/plugin.json +1 -1
- {conventional_git-1.2.0 → conventional_git-2.1.1}/.gitignore +3 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/.pre-commit-config.yaml +7 -0
- conventional_git-2.1.1/AGENTS.md +115 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/CONTRIBUTING.md +4 -1
- {conventional_git-1.2.0 → conventional_git-2.1.1}/Makefile +31 -2
- {conventional_git-1.2.0 → conventional_git-2.1.1}/PKG-INFO +33 -21
- {conventional_git-1.2.0 → conventional_git-2.1.1}/README.md +32 -20
- {conventional_git-1.2.0 → conventional_git-2.1.1}/dictionary.txt +2 -0
- conventional_git-2.1.1/docs/agents/agent-skills-format.md +68 -0
- conventional_git-2.1.1/docs/agents/claude-code-install-scopes.md +50 -0
- conventional_git-2.1.1/docs/agents/claude-code-marketplace-install.md +67 -0
- conventional_git-2.1.1/docs/agents/claude-code-plugin-updates.md +71 -0
- conventional_git-2.1.1/docs/agents/claude-code-shell-install.md +58 -0
- conventional_git-2.1.1/docs/agents/claude-code-skill-invocation.md +52 -0
- conventional_git-2.1.1/docs/agents/index.md +50 -0
- conventional_git-2.1.1/docs/agents/install-channels.md +65 -0
- conventional_git-2.1.1/docs/agents/npx-skills-install.md +65 -0
- conventional_git-2.1.1/docs/agents/npx-skills-manage.md +58 -0
- conventional_git-2.1.1/docs/agents/opencode-mcp-config.md +83 -0
- conventional_git-2.1.1/docs/agents/opencode-mcp-server.md +68 -0
- conventional_git-2.1.1/docs/agents/opencode-skill-discovery.md +50 -0
- conventional_git-2.1.1/docs/agents/opencode-skill-permissions.md +48 -0
- conventional_git-2.1.1/docs/agents/plugin-identity.md +73 -0
- conventional_git-2.1.1/docs/conventions/claude-md-check.md +21 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/conventions/commits-check.md +12 -3
- conventional_git-2.1.1/docs/conventions/help-check.md +22 -0
- conventional_git-2.1.1/docs/conventions/index.md +17 -0
- conventional_git-2.1.1/docs/conventions/tag-vocabulary.md +28 -0
- conventional_git-2.1.1/docs/conventions/versioning.md +47 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/enforcement/attribution-trailers.md +3 -2
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/enforcement/git-hooks.md +1 -1
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/enforcement/hook-install-path.md +1 -1
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/enforcement/pre-commit-framework.md +1 -1
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/enforcement/pre-commit-local-hooks.md +3 -3
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/gitlint/install.md +1 -1
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/index.md +5 -0
- conventional_git-2.1.1/docs/log.md +126 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/mcp/index.md +7 -0
- conventional_git-2.1.1/docs/mcp/no-auth-tools.md +23 -0
- conventional_git-2.1.1/docs/mcp/out-of-band-auth.md +39 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/mcp/plugin-bundled-server.md +9 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/mcp/suggest-commit-message.md +29 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/python/interpreter-source.md +1 -1
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/toolchain/index.md +4 -0
- conventional_git-2.1.1/docs/toolchain/layering-rule.md +28 -0
- conventional_git-2.1.1/docs/toolchain/retag-notes.md +29 -0
- conventional_git-2.1.1/docs/toolchain/sh-uid-unused.md +23 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/mk/python.mk +10 -3
- conventional_git-2.1.1/okf-base.yaml +42 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/package.json +2 -2
- {conventional_git-1.2.0 → conventional_git-2.1.1}/pnpm-lock.yaml +120 -120
- {conventional_git-1.2.0 → conventional_git-2.1.1}/pyproject.toml +4 -3
- conventional_git-2.1.1/skills/conventional-auth/SKILL.md +67 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/skills/conventional-branch/SKILL.md +1 -3
- {conventional_git-1.2.0 → conventional_git-2.1.1}/skills/conventional-commit/SKILL.md +8 -9
- conventional_git-2.1.1/skills/conventional-suggest/SKILL.md +86 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/adapters/gitlint_rules.py +6 -3
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/cli/check.py +1 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/cli/create.py +13 -14
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/commit/rules.py +3 -1
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/commit/vocabulary.py +2 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/config.py +2 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/helpers.py +3 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/mcp/server.py +1 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_cli_smoke.py +53 -4
- {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_commit_rules.py +18 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_commit_vocabulary.py +15 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_config.py +20 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_gitlint_rules.py +19 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_helpers.py +16 -0
- conventional_git-2.1.1/tests/test_sh_uid_unused.py +39 -0
- conventional_git-2.1.1/tools/docs-retag.py +141 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/uv.lock +12 -12
- conventional_git-1.2.0/AGENTS.md +0 -80
- conventional_git-1.2.0/docs/conventions/index.md +0 -9
- conventional_git-1.2.0/docs/log.md +0 -70
- conventional_git-1.2.0/docs/toolchain/layering-rule.md +0 -35
- {conventional_git-1.2.0 → conventional_git-2.1.1}/.claude-plugin/marketplace.json +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/.editorconfig +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/.github/dependabot.yml +2 -2
- {conventional_git-1.2.0 → conventional_git-2.1.1}/.github/workflows/ci.yml +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/.github/workflows/publish.yml +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/.github/workflows/python.yml +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/.markdownlint-cli2.jsonc +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/.markdownlint.yaml +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/.mcp.json +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/.pre-commit-hooks.yaml +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/LICENSE +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/checkmake.ini +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/cspell.config.yaml +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/architecture/index.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/architecture/optional-extras.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/architecture/three-layers.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/architecture/validation-vs-generation.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/architecture/violation-contract.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/architecture/vocabulary-as-data.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/conventions/commits-and-branches.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/enforcement/branch-name-gap.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/enforcement/ci-recipe.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/enforcement/commitizen-adapter.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/enforcement/house-rules.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/enforcement/index.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/enforcement/skill-vocabulary-copies.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/gitlint/behavior-vs-cli.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/gitlint/extra-path.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/gitlint/index.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/gitlint/recommended-config.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/gitlint/when-to-use.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/gitlint/wiring.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/mcp/describe-convention.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/mcp/self-correction-loop.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/mcp/server-install.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/mcp/validate-tools.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/python/index.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/python/pyproject-defaults.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/release/index.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/release/pypi-trusted-publishing.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/suggestions/apply-does-not-commit.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/suggestions/data-egress.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/suggestions/index.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/suggestions/keyring-scope.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/suggestions/llm-extra-install.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/suggestions/provider-fallback.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/suggestions/providers-and-credentials.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/toolchain/extras-self-reference.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/toolchain/rejected-install-backends.md +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/mise.toml +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/mk/.gitkeep +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/mk/conventional-git.mk +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/pnpm-workspace.yaml +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/skills/conventional-branch/references/branch-types.csv +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/skills/conventional-commit/references/commit-types.csv +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/__init__.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/adapters/__init__.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/adapters/commitizen_config.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/branch/__init__.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/branch/grammar.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/branch/rules.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/branch/vocabulary.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/cli/__init__.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/cli/app.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/cli/auth.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/cli/capabilities.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/cli/hook.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/cli/mcp.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/commit/__init__.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/commit/compose.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/commit/grammar.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/csv_columns.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/data/__init__.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/data/branch-exempt-prefixes.csv +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/data/branch-trunks.csv +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/data/branch-types.csv +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/data/commit-attribution.csv +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/data/commit-types.csv +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/generation/__init__.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/generation/credentials.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/generation/diff.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/generation/heuristic.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/generation/protocol.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/generation/typesafe.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/mcp/__init__.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/py.typed +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/violations.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/__init__.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_branch_rules.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_branch_vocabulary.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_cli_auth.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_cli_capabilities.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_cli_hook.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_commit_compose.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_credentials.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_diff.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_generation_suggest.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_heuristic.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_mcp_server.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_plugin_version.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_skill_vocabularies.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_typesafe_client_factory.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_typesafe_provider.py +0 -0
- {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_violation_code_coverage.py +0 -0
|
@@ -7,6 +7,9 @@ mise.local.toml
|
|
|
7
7
|
# Obsidian vault metadata (docs/ is opened directly as a vault)
|
|
8
8
|
.obsidian/
|
|
9
9
|
|
|
10
|
+
# Answers and batches of `make docs-retag`
|
|
11
|
+
.cache/
|
|
12
|
+
|
|
10
13
|
# Created by https://www.toptal.com/developers/gitignore/api/linux,macos,jetbrains+all,visualstudiocode,node,python
|
|
11
14
|
# Edit at https://www.toptal.com/developers/gitignore?templates=linux,macos,jetbrains+all,visualstudiocode,node,python
|
|
12
15
|
|
|
@@ -27,6 +27,13 @@ repos:
|
|
|
27
27
|
language: system
|
|
28
28
|
pass_filenames: false
|
|
29
29
|
|
|
30
|
+
- id: docs-lint
|
|
31
|
+
name: okflint
|
|
32
|
+
entry: make docs-lint
|
|
33
|
+
language: system
|
|
34
|
+
files: ^(docs/.*\.md|okf-base\.yaml)$
|
|
35
|
+
pass_filenames: false
|
|
36
|
+
|
|
30
37
|
- id: conventional-commit-msg
|
|
31
38
|
name: conventional-git commit message
|
|
32
39
|
entry: uvx conventional-git@latest check commit --file
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
|
|
4
|
+
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
|
|
5
|
+
interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
|
|
6
|
+
|
|
7
|
+
## Agent instructions
|
|
8
|
+
|
|
9
|
+
- `AGENTS.md` is the only agent instructions file; put project rules here. The
|
|
10
|
+
repository MUST NOT contain a `CLAUDE.md` or any other tool-specific copy,
|
|
11
|
+
because a second copy drifts from this one; `make claude-md-check` fails on
|
|
12
|
+
one.
|
|
13
|
+
|
|
14
|
+
## Command surface
|
|
15
|
+
|
|
16
|
+
- Run the `Makefile` targets (`make check`, `make fix`, `make test`, ...)
|
|
17
|
+
instead of the underlying tools, so the agent and CI use the same options.
|
|
18
|
+
`make help` lists them.
|
|
19
|
+
- Give every new target a `##` help line; `make help` prints it and
|
|
20
|
+
`make help-check` fails on a target without one.
|
|
21
|
+
|
|
22
|
+
## Gate
|
|
23
|
+
|
|
24
|
+
- `make check` and `make test` MUST pass before any commit.
|
|
25
|
+
- Run `make fix` first for findings it can repair, then edit by hand.
|
|
26
|
+
|
|
27
|
+
## Commits and branches
|
|
28
|
+
|
|
29
|
+
- Write commit messages as
|
|
30
|
+
[Conventional Commits](https://www.conventionalcommits.org/) and branch
|
|
31
|
+
names as [Conventional Branch](https://conventionalbranch.org/)
|
|
32
|
+
(`<type>/<description>`, e.g. `feat/add-enforcement`,
|
|
33
|
+
`fix/normalize-description-grammar`). A pre-commit hook and
|
|
34
|
+
`make commits-check` enforce both; see
|
|
35
|
+
[`docs/conventions/commits-check.md`](docs/conventions/commits-check.md).
|
|
36
|
+
- Name a documentation or dependency branch `chore/...`: a branch type is not
|
|
37
|
+
a commit type, and `docs/` is not one.
|
|
38
|
+
|
|
39
|
+
## Pull requests
|
|
40
|
+
|
|
41
|
+
Once a pull request is open, the agent MUST:
|
|
42
|
+
|
|
43
|
+
1. Wait for CI; while it fails, fix the cause, push to the same branch and
|
|
44
|
+
wait again until it passes.
|
|
45
|
+
2. Squash-merge a pull request with exactly one commit and use a regular merge
|
|
46
|
+
commit otherwise (`gh pr view --json commits` gives the count).
|
|
47
|
+
3. Delete the branch on the remote and locally.
|
|
48
|
+
4. Switch back to the base branch, pull it and run `git fetch --prune`.
|
|
49
|
+
|
|
50
|
+
## Versioning and releases
|
|
51
|
+
|
|
52
|
+
- Decide every version bump, tag and release as
|
|
53
|
+
[`docs/conventions/versioning.md`](docs/conventions/versioning.md) defines;
|
|
54
|
+
it is the only place those rules live.
|
|
55
|
+
|
|
56
|
+
## Documentation
|
|
57
|
+
|
|
58
|
+
- Follow the organization's shared documentation-writing guide, kept in one
|
|
59
|
+
place rather than copied into this repository so it cannot drift from other
|
|
60
|
+
projects that follow the same guide.
|
|
61
|
+
- Add a new `docs/` note to its directory's `index.md` and, by file name, to
|
|
62
|
+
[`docs/log.md`](docs/log.md); `make docs-lint` fails on a missing field or a
|
|
63
|
+
broken link.
|
|
64
|
+
- Cover exactly one concept per note.
|
|
65
|
+
- Write a note only when it explains something a reader cannot already get
|
|
66
|
+
from `make help`, a linter's own message, or the configuration it comes
|
|
67
|
+
from.
|
|
68
|
+
|
|
69
|
+
## Dependencies
|
|
70
|
+
|
|
71
|
+
- Add a new tool to the ecosystem manager that owns it (`package.json` for
|
|
72
|
+
Node, `pyproject.toml` `[dependency-groups].dev` for Python); use
|
|
73
|
+
`mise.toml` only for a tool that bootstraps an ecosystem or has no manager
|
|
74
|
+
in this repository.
|
|
75
|
+
- Declare a tool in one layer only: two pins can drift and the gate would no
|
|
76
|
+
longer cover both. See
|
|
77
|
+
[`docs/toolchain/layering-rule.md`](docs/toolchain/layering-rule.md).
|
|
78
|
+
|
|
79
|
+
## Layering
|
|
80
|
+
|
|
81
|
+
The codebase is intentionally three layers; the agent MUST NOT cross the
|
|
82
|
+
boundaries below.
|
|
83
|
+
|
|
84
|
+
1. **Spec core** — `conventional_git.commit.*` and `conventional_git.branch.*`.
|
|
85
|
+
Pure functions, no git calls, no `SystemExit`, no I/O. Validation returns
|
|
86
|
+
a `Report` of `Violation`s. This is the only layer that holds rules.
|
|
87
|
+
2. **Adapters** — `conventional_git.adapters.*` (gitlint rules, commitizen
|
|
88
|
+
schema emitter). Translate `Violation` into the consumer tool's error
|
|
89
|
+
type. The adapter is the only place that imports the consumer SDK.
|
|
90
|
+
3. **Front-ends** — `conventional_git.cli.*` and `conventional_git.mcp.*`.
|
|
91
|
+
Map user input into core calls and core output into user output. These
|
|
92
|
+
are the only layers that may call `SystemExit`.
|
|
93
|
+
|
|
94
|
+
A new rule MUST land in the core; an adapter that hardcodes the rule
|
|
95
|
+
duplicates it. A new vocabulary entry MUST land in
|
|
96
|
+
`data/{commit,branch}-types.csv`; a regex inside the core is a bug, not a
|
|
97
|
+
feature.
|
|
98
|
+
|
|
99
|
+
## Python
|
|
100
|
+
|
|
101
|
+
- Write no docstrings on functions, methods or classes; add a comment only
|
|
102
|
+
where the *why* is not obvious from the code. `pylint-gajaguar`'s
|
|
103
|
+
`gajaguar-no-docstrings` fails `make check` on any docstring.
|
|
104
|
+
- Enable the plugin with `enable = ["gajaguar"]` in `pyproject.toml`'s
|
|
105
|
+
`[tool.pylint."messages control"]`, not with a list of rules, so a rule
|
|
106
|
+
added by a `pylint-gajaguar` upgrade runs without a config change.
|
|
107
|
+
- Keep `pyproject.toml` to settings that differ from the tool's default, and
|
|
108
|
+
keep a `lint.per-file-ignores` entry only while it matches a current
|
|
109
|
+
violation; see
|
|
110
|
+
[`docs/python/pyproject-defaults.md`](docs/python/pyproject-defaults.md).
|
|
111
|
+
- Keep the spec core free of `git` imports and `SystemExit`. Returning a
|
|
112
|
+
`Report` is the contract; only front-ends turn violations into exit codes.
|
|
113
|
+
- Tag a minor or major bump with `make release-tag` after its pull request
|
|
114
|
+
merges, as [`docs/conventions/versioning.md`](docs/conventions/versioning.md)
|
|
115
|
+
describes; the target tags the base branch as `v<project.version>`.
|
|
@@ -33,7 +33,10 @@ This repository dogfoods its own rules:
|
|
|
33
33
|
[Conventional Commits](https://www.conventionalcommits.org/).
|
|
34
34
|
- Branch names MUST follow
|
|
35
35
|
[Conventional Branch](https://conventionalbranch.org/)
|
|
36
|
-
(`<type>/<description>`, e.g. `fix/normalize-branch-name`).
|
|
36
|
+
(`<type>/<description>`, e.g. `fix/normalize-branch-name`). The branch
|
|
37
|
+
type is one of `feat` (or `feature`), `fix` (or `bugfix`), `hotfix`,
|
|
38
|
+
`release`, or `chore`; documentation and dependency work uses `chore/`,
|
|
39
|
+
because `docs/` is not a branch type.
|
|
37
40
|
- Commit messages MUST NOT carry an attribution trailer (`Co-Authored-By:`,
|
|
38
41
|
"Generated with …", a 🤖 marker); the project's own commit-msg hook
|
|
39
42
|
rejects them — see
|
|
@@ -13,6 +13,11 @@ FILES ?=
|
|
|
13
13
|
# docs/conventions/commits-check.md.
|
|
14
14
|
BASE ?= origin/main
|
|
15
15
|
CONVENTIONAL_GIT ?= uvx conventional-git@latest
|
|
16
|
+
# Pinned, not @latest: a linter's verdict changes between versions. See
|
|
17
|
+
# docs/toolchain/okflint.md and docs/documentation/retag-notes.md.
|
|
18
|
+
OKFLINT ?= uvx okflint@0.4.1
|
|
19
|
+
TYPESAFE ?= uvx --from typesafe-unofficial-cli@1.1.0 typesafe
|
|
20
|
+
DOCS_RETAG := uv run --script tools/docs-retag.py
|
|
16
21
|
BRANCH ?= $(or $(GITHUB_HEAD_REF),$(shell git branch --show-current))
|
|
17
22
|
|
|
18
23
|
.DEFAULT_GOAL := help
|
|
@@ -73,9 +78,20 @@ commits-check: ## Validate the commit range and branch name against Conventional
|
|
|
73
78
|
done
|
|
74
79
|
@$(CONVENTIONAL_GIT) check branch --name "$(BRANCH)"
|
|
75
80
|
|
|
76
|
-
check:
|
|
81
|
+
help-check: ## Fail if a Makefile target lacks its ## help line — see docs/conventions/help-check.md
|
|
82
|
+
@missing=$$(grep -HnE '^[a-zA-Z][a-zA-Z0-9_-]*[[:space:]]*:([^=]|$$)' Makefile mk/*.mk 2>/dev/null | grep -v '##' || true); \
|
|
83
|
+
test -z "$$missing" || { echo "target without a ## help line:" >&2; echo "$$missing" >&2; exit 1; }
|
|
77
84
|
|
|
78
|
-
|
|
85
|
+
claude-md-check: ## Fail if a CLAUDE.md exists, since AGENTS.md is the only agent file — see docs/conventions/claude-md-check.md
|
|
86
|
+
@found=$$(git ls-files --cached --others --exclude-standard | grep -E '(^|/)CLAUDE\.md$$' || true); \
|
|
87
|
+
test -z "$$found" || { echo "CLAUDE.md found; fold it into AGENTS.md and delete it:" >&2; echo "$$found" >&2; exit 1; }
|
|
88
|
+
|
|
89
|
+
docs-lint: ## Validate docs/ as an OKF bundle with okflint — see docs/toolchain/okflint.md
|
|
90
|
+
@$(OKFLINT) validate
|
|
91
|
+
|
|
92
|
+
check: makefile-lint md-lint spell docs-lint commits-check help-check claude-md-check $(LANG_CHECK_TARGETS) ## Run the full read-only validation gate
|
|
93
|
+
|
|
94
|
+
.PHONY: makefile-lint md-lint spell docs-lint commits-check help-check claude-md-check check
|
|
79
95
|
|
|
80
96
|
##@ Writable fixes (mutate files in place)
|
|
81
97
|
|
|
@@ -106,3 +122,16 @@ fix-unsafe: _md-fix-scoped $(LANG_FIX_UNSAFE_TARGETS) ## Apply all auto-fixes, i
|
|
|
106
122
|
test: $(LANG_TEST_TARGETS) ## Run the test suite
|
|
107
123
|
|
|
108
124
|
.PHONY: test
|
|
125
|
+
|
|
126
|
+
##@ Docs tagging (optional, billed — not part of check)
|
|
127
|
+
|
|
128
|
+
docs-retag: ## Ask TypeSafe which tags each docs/ note carries, then show a dry run — one billed request per note
|
|
129
|
+
@$(DOCS_RETAG) build
|
|
130
|
+
@$(TYPESAFE) -o jsonl ask --states-file .cache/docs-retag/states.jsonl --questions-file .cache/docs-retag/questions.json --concurrency 4 > .cache/docs-retag/answers.jsonl
|
|
131
|
+
@$(DOCS_RETAG) apply
|
|
132
|
+
|
|
133
|
+
docs-retag-apply: ## Write the tags from the last docs-retag run into the notes, then validate docs/
|
|
134
|
+
@$(DOCS_RETAG) apply --write
|
|
135
|
+
@$(MAKE) docs-lint
|
|
136
|
+
|
|
137
|
+
.PHONY: docs-retag docs-retag-apply
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: conventional-git
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 2.1.1
|
|
4
4
|
Summary: Conventional Commits and Conventional Branch enforcement, validation, and generation
|
|
5
5
|
Project-URL: Repository, https://github.com/gajaguar/conventional-git
|
|
6
6
|
Project-URL: Issues, https://github.com/gajaguar/conventional-git/issues
|
|
@@ -146,9 +146,6 @@ conventional-git create branch --type feature --description "add login"
|
|
|
146
146
|
# feature/add-login
|
|
147
147
|
```
|
|
148
148
|
|
|
149
|
-
Use `--dry-run` when you need the generated value without taking further
|
|
150
|
-
action. The current implementation prints the value in either mode.
|
|
151
|
-
|
|
152
149
|
### Enforce
|
|
153
150
|
|
|
154
151
|
Install `commit-msg`, `pre-commit`, and `pre-push` hooks in a repository:
|
|
@@ -170,8 +167,9 @@ credential, `create suggest` always falls back to the built-in heuristic
|
|
|
170
167
|
provider and prints a notice; it never fails the command:
|
|
171
168
|
|
|
172
169
|
```bash
|
|
173
|
-
|
|
170
|
+
conventional-git create suggest
|
|
174
171
|
conventional-git create suggest --diff-file changes.diff --apply
|
|
172
|
+
git diff main... | conventional-git create suggest --diff-file -
|
|
175
173
|
```
|
|
176
174
|
|
|
177
175
|
With the `llm` extra installed and a credential available, `create suggest`
|
|
@@ -218,33 +216,45 @@ uvx --from 'conventional-git[mcp]' conventional-git-mcp
|
|
|
218
216
|
```
|
|
219
217
|
|
|
220
218
|
The server exposes `validate_commit_message`, `validate_branch_name`,
|
|
221
|
-
`describe_convention`, and `suggest_commit_message`.
|
|
219
|
+
`describe_convention`, and `suggest_commit_message`. The server has no auth
|
|
220
|
+
tools: for `suggest_commit_message` to use `jev`, run
|
|
221
|
+
`conventional-git auth login` first and launch it with the `llm` extra (see
|
|
222
|
+
[`docs/mcp/out-of-band-auth.md`](docs/mcp/out-of-band-auth.md)). See
|
|
222
223
|
[`docs/mcp/index.md`](docs/mcp/index.md).
|
|
223
224
|
|
|
224
225
|
## Agents
|
|
225
226
|
|
|
226
227
|
The repository is both a Claude Code plugin and an
|
|
227
228
|
[Agent Skills](https://agentskills.io/specification)-compliant `skills/`
|
|
228
|
-
directory.
|
|
229
|
+
directory. See [`docs/agents/index.md`](docs/agents/index.md) for the full
|
|
230
|
+
install guide; one command per channel.
|
|
229
231
|
|
|
230
|
-
**Claude Code
|
|
231
|
-
`conventional-commit`, `conventional-branch`,
|
|
232
|
+
**Claude Code**: add the marketplace, then install the plugin. It bundles
|
|
233
|
+
`conventional-commit`, `conventional-branch`, `conventional-suggest`,
|
|
234
|
+
`conventional-auth`, and the MCP server:
|
|
232
235
|
|
|
233
236
|
```text
|
|
234
237
|
/plugin marketplace add gajaguar/conventional-git
|
|
235
238
|
/plugin install conventional-git@conventional-git-skills
|
|
239
|
+
/reload-plugins
|
|
236
240
|
```
|
|
237
241
|
|
|
238
242
|
See [`docs/mcp/plugin-bundled-server.md`](docs/mcp/plugin-bundled-server.md)
|
|
239
243
|
for how the bundled `.mcp.json` launches the server.
|
|
240
244
|
|
|
241
245
|
**Any other agent that supports Agent Skills** (Codex, Cursor, Gemini CLI,
|
|
242
|
-
Copilot,
|
|
246
|
+
Copilot, and others):
|
|
243
247
|
|
|
244
248
|
```bash
|
|
245
249
|
npx skills add gajaguar/conventional-git
|
|
246
250
|
```
|
|
247
251
|
|
|
252
|
+
**opencode**:
|
|
253
|
+
|
|
254
|
+
```bash
|
|
255
|
+
npx skills add gajaguar/conventional-git -a opencode -y
|
|
256
|
+
```
|
|
257
|
+
|
|
248
258
|
Skills call `conventional-git capabilities --json` before drafting, so they
|
|
249
259
|
only offer `create suggest` (see [Suggest](#suggest)) when the `llm` extra
|
|
250
260
|
and a credential are both present, and never send a diff to a third party
|
|
@@ -259,8 +269,8 @@ return `1`.
|
|
|
259
269
|
| :------------- | ---------------------------------------------------------------------------------------- | ------------: |
|
|
260
270
|
| check commit | `-m, --message`; `-f, --file`; `--types-csv` | 0 or 1 |
|
|
261
271
|
| check branch | `-n, --name`; `--types-csv` | 0 or 1 |
|
|
262
|
-
| create commit | `--type`; `--description`; `--scope`; `--body`; `--breaking`; `--types-csv
|
|
263
|
-
| create branch | `--type`; `--description`; `--types-csv
|
|
272
|
+
| create commit | `--type`; `--description`; `--scope`; `--body`; `--breaking`; `--types-csv` | 0 or 1 |
|
|
273
|
+
| create branch | `--type`; `--description`; `--types-csv` | 0 or 1 |
|
|
264
274
|
| create suggest | `--diff-file`; `--provider`; `--apply` | 0 or 1 |
|
|
265
275
|
| hook install | `--target`; `--force` | 0 or 1 |
|
|
266
276
|
| hook uninstall | `--target` | 0 |
|
|
@@ -276,13 +286,14 @@ Use `conventional-git <command> --help` for the full option descriptions.
|
|
|
276
286
|
|
|
277
287
|
Create `.conventional-git.toml` in the current repository:
|
|
278
288
|
|
|
279
|
-
| Key
|
|
280
|
-
|
|
|
281
|
-
| `[commit] attribution_patterns`
|
|
282
|
-
| `[commit]
|
|
283
|
-
| `[
|
|
284
|
-
| `[branch]
|
|
285
|
-
| `[branch]
|
|
289
|
+
| Key | Default | Purpose |
|
|
290
|
+
| :---------------------------------------------- | ------------- | ---------------------------------- |
|
|
291
|
+
| `[commit] attribution_patterns` | built-in list | Extra attribution regexes |
|
|
292
|
+
| `[commit] disable_default_attribution_patterns` | `false` | Skip the built-in attribution list |
|
|
293
|
+
| `[commit] type_overrides` | `[]` | Extra commit types |
|
|
294
|
+
| `[branch] type_overrides` | `[]` | Extra branch types |
|
|
295
|
+
| `[branch] trunk_overrides` | `[]` | Extra trunk branch names |
|
|
296
|
+
| `[branch] exempt_prefix_overrides` | `[]` | Extra exempt name prefixes |
|
|
286
297
|
|
|
287
298
|
Relative CSV paths in `type_overrides` / `trunk_overrides` /
|
|
288
299
|
`exempt_prefix_overrides` are resolved
|
|
@@ -290,7 +301,8 @@ against the directory containing `.conventional-git.toml`, not the process's
|
|
|
290
301
|
current directory. Every consumer that loads the file — the CLI, the MCP
|
|
291
302
|
server, and the gitlint adapter — honors it. See
|
|
292
303
|
[`docs/enforcement/attribution-trailers.md`](docs/enforcement/attribution-trailers.md)
|
|
293
|
-
for what `attribution_patterns` extends
|
|
304
|
+
for what `attribution_patterns` extends and how
|
|
305
|
+
`disable_default_attribution_patterns` turns the built-in list off.
|
|
294
306
|
|
|
295
307
|
The `--types-csv` option extends the default vocabulary; it does not replace
|
|
296
308
|
it. Vocabulary files live in `data/{commit,branch}-types.csv`.
|
|
@@ -327,7 +339,7 @@ and render its output. See [`docs/architecture/index.md`](docs/architecture/inde
|
|
|
327
339
|
│ ├── adapters/{gitlint_rules,commitizen_config}.py
|
|
328
340
|
│ ├── cli/{app,auth,check,create,hook,mcp}.py
|
|
329
341
|
│ └── mcp/server.py
|
|
330
|
-
├── skills/conventional-{commit,branch}/SKILL.md
|
|
342
|
+
├── skills/conventional-{commit,branch,suggest,auth}/SKILL.md
|
|
331
343
|
└── tests/
|
|
332
344
|
```
|
|
333
345
|
|
|
@@ -125,9 +125,6 @@ conventional-git create branch --type feature --description "add login"
|
|
|
125
125
|
# feature/add-login
|
|
126
126
|
```
|
|
127
127
|
|
|
128
|
-
Use `--dry-run` when you need the generated value without taking further
|
|
129
|
-
action. The current implementation prints the value in either mode.
|
|
130
|
-
|
|
131
128
|
### Enforce
|
|
132
129
|
|
|
133
130
|
Install `commit-msg`, `pre-commit`, and `pre-push` hooks in a repository:
|
|
@@ -149,8 +146,9 @@ credential, `create suggest` always falls back to the built-in heuristic
|
|
|
149
146
|
provider and prints a notice; it never fails the command:
|
|
150
147
|
|
|
151
148
|
```bash
|
|
152
|
-
|
|
149
|
+
conventional-git create suggest
|
|
153
150
|
conventional-git create suggest --diff-file changes.diff --apply
|
|
151
|
+
git diff main... | conventional-git create suggest --diff-file -
|
|
154
152
|
```
|
|
155
153
|
|
|
156
154
|
With the `llm` extra installed and a credential available, `create suggest`
|
|
@@ -197,33 +195,45 @@ uvx --from 'conventional-git[mcp]' conventional-git-mcp
|
|
|
197
195
|
```
|
|
198
196
|
|
|
199
197
|
The server exposes `validate_commit_message`, `validate_branch_name`,
|
|
200
|
-
`describe_convention`, and `suggest_commit_message`.
|
|
198
|
+
`describe_convention`, and `suggest_commit_message`. The server has no auth
|
|
199
|
+
tools: for `suggest_commit_message` to use `jev`, run
|
|
200
|
+
`conventional-git auth login` first and launch it with the `llm` extra (see
|
|
201
|
+
[`docs/mcp/out-of-band-auth.md`](docs/mcp/out-of-band-auth.md)). See
|
|
201
202
|
[`docs/mcp/index.md`](docs/mcp/index.md).
|
|
202
203
|
|
|
203
204
|
## Agents
|
|
204
205
|
|
|
205
206
|
The repository is both a Claude Code plugin and an
|
|
206
207
|
[Agent Skills](https://agentskills.io/specification)-compliant `skills/`
|
|
207
|
-
directory.
|
|
208
|
+
directory. See [`docs/agents/index.md`](docs/agents/index.md) for the full
|
|
209
|
+
install guide; one command per channel.
|
|
208
210
|
|
|
209
|
-
**Claude Code
|
|
210
|
-
`conventional-commit`, `conventional-branch`,
|
|
211
|
+
**Claude Code**: add the marketplace, then install the plugin. It bundles
|
|
212
|
+
`conventional-commit`, `conventional-branch`, `conventional-suggest`,
|
|
213
|
+
`conventional-auth`, and the MCP server:
|
|
211
214
|
|
|
212
215
|
```text
|
|
213
216
|
/plugin marketplace add gajaguar/conventional-git
|
|
214
217
|
/plugin install conventional-git@conventional-git-skills
|
|
218
|
+
/reload-plugins
|
|
215
219
|
```
|
|
216
220
|
|
|
217
221
|
See [`docs/mcp/plugin-bundled-server.md`](docs/mcp/plugin-bundled-server.md)
|
|
218
222
|
for how the bundled `.mcp.json` launches the server.
|
|
219
223
|
|
|
220
224
|
**Any other agent that supports Agent Skills** (Codex, Cursor, Gemini CLI,
|
|
221
|
-
Copilot,
|
|
225
|
+
Copilot, and others):
|
|
222
226
|
|
|
223
227
|
```bash
|
|
224
228
|
npx skills add gajaguar/conventional-git
|
|
225
229
|
```
|
|
226
230
|
|
|
231
|
+
**opencode**:
|
|
232
|
+
|
|
233
|
+
```bash
|
|
234
|
+
npx skills add gajaguar/conventional-git -a opencode -y
|
|
235
|
+
```
|
|
236
|
+
|
|
227
237
|
Skills call `conventional-git capabilities --json` before drafting, so they
|
|
228
238
|
only offer `create suggest` (see [Suggest](#suggest)) when the `llm` extra
|
|
229
239
|
and a credential are both present, and never send a diff to a third party
|
|
@@ -238,8 +248,8 @@ return `1`.
|
|
|
238
248
|
| :------------- | ---------------------------------------------------------------------------------------- | ------------: |
|
|
239
249
|
| check commit | `-m, --message`; `-f, --file`; `--types-csv` | 0 or 1 |
|
|
240
250
|
| check branch | `-n, --name`; `--types-csv` | 0 or 1 |
|
|
241
|
-
| create commit | `--type`; `--description`; `--scope`; `--body`; `--breaking`; `--types-csv
|
|
242
|
-
| create branch | `--type`; `--description`; `--types-csv
|
|
251
|
+
| create commit | `--type`; `--description`; `--scope`; `--body`; `--breaking`; `--types-csv` | 0 or 1 |
|
|
252
|
+
| create branch | `--type`; `--description`; `--types-csv` | 0 or 1 |
|
|
243
253
|
| create suggest | `--diff-file`; `--provider`; `--apply` | 0 or 1 |
|
|
244
254
|
| hook install | `--target`; `--force` | 0 or 1 |
|
|
245
255
|
| hook uninstall | `--target` | 0 |
|
|
@@ -255,13 +265,14 @@ Use `conventional-git <command> --help` for the full option descriptions.
|
|
|
255
265
|
|
|
256
266
|
Create `.conventional-git.toml` in the current repository:
|
|
257
267
|
|
|
258
|
-
| Key
|
|
259
|
-
|
|
|
260
|
-
| `[commit] attribution_patterns`
|
|
261
|
-
| `[commit]
|
|
262
|
-
| `[
|
|
263
|
-
| `[branch]
|
|
264
|
-
| `[branch]
|
|
268
|
+
| Key | Default | Purpose |
|
|
269
|
+
| :---------------------------------------------- | ------------- | ---------------------------------- |
|
|
270
|
+
| `[commit] attribution_patterns` | built-in list | Extra attribution regexes |
|
|
271
|
+
| `[commit] disable_default_attribution_patterns` | `false` | Skip the built-in attribution list |
|
|
272
|
+
| `[commit] type_overrides` | `[]` | Extra commit types |
|
|
273
|
+
| `[branch] type_overrides` | `[]` | Extra branch types |
|
|
274
|
+
| `[branch] trunk_overrides` | `[]` | Extra trunk branch names |
|
|
275
|
+
| `[branch] exempt_prefix_overrides` | `[]` | Extra exempt name prefixes |
|
|
265
276
|
|
|
266
277
|
Relative CSV paths in `type_overrides` / `trunk_overrides` /
|
|
267
278
|
`exempt_prefix_overrides` are resolved
|
|
@@ -269,7 +280,8 @@ against the directory containing `.conventional-git.toml`, not the process's
|
|
|
269
280
|
current directory. Every consumer that loads the file — the CLI, the MCP
|
|
270
281
|
server, and the gitlint adapter — honors it. See
|
|
271
282
|
[`docs/enforcement/attribution-trailers.md`](docs/enforcement/attribution-trailers.md)
|
|
272
|
-
for what `attribution_patterns` extends
|
|
283
|
+
for what `attribution_patterns` extends and how
|
|
284
|
+
`disable_default_attribution_patterns` turns the built-in list off.
|
|
273
285
|
|
|
274
286
|
The `--types-csv` option extends the default vocabulary; it does not replace
|
|
275
287
|
it. Vocabulary files live in `data/{commit,branch}-types.csv`.
|
|
@@ -306,7 +318,7 @@ and render its output. See [`docs/architecture/index.md`](docs/architecture/inde
|
|
|
306
318
|
│ ├── adapters/{gitlint_rules,commitizen_config}.py
|
|
307
319
|
│ ├── cli/{app,auth,check,create,hook,mcp}.py
|
|
308
320
|
│ └── mcp/server.py
|
|
309
|
-
├── skills/conventional-{commit,branch}/SKILL.md
|
|
321
|
+
├── skills/conventional-{commit,branch,suggest,auth}/SKILL.md
|
|
310
322
|
└── tests/
|
|
311
323
|
```
|
|
312
324
|
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: reference
|
|
3
|
+
title: Agent Skills format
|
|
4
|
+
description: SKILL.md frontmatter fields and their constraints, progressive disclosure, and the optional references/ subdirectory.
|
|
5
|
+
tags: [agents, skills, documentation]
|
|
6
|
+
status: stable
|
|
7
|
+
stale_after: 2027-03-29
|
|
8
|
+
sources:
|
|
9
|
+
- id: agentskills-spec
|
|
10
|
+
resource: https://agentskills.io/specification
|
|
11
|
+
title: Agent Skills specification
|
|
12
|
+
author: team:agentskills
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
# Agent Skills format
|
|
16
|
+
|
|
17
|
+
An Agent Skill is a directory that contains a `SKILL.md` file: YAML
|
|
18
|
+
frontmatter followed by Markdown instructions. Agents load the `name`
|
|
19
|
+
and `description` at startup to decide when a skill applies.[^agentskills-spec]
|
|
20
|
+
|
|
21
|
+
| Field | Required | Purpose |
|
|
22
|
+
| :-------------- | :------- | :------------------------------------------ |
|
|
23
|
+
| `name` | Yes | Skill identifier |
|
|
24
|
+
| `description` | Yes | What the skill does and when to use it |
|
|
25
|
+
| `license` | No | License name or bundled license file |
|
|
26
|
+
| `compatibility` | No | Environment requirements |
|
|
27
|
+
| `metadata` | No | String-to-string map of extra properties |
|
|
28
|
+
| `allowed-tools` | No | Pre-approved tools (experimental) |
|
|
29
|
+
|
|
30
|
+
Constraints from the specification:[^agentskills-spec]
|
|
31
|
+
|
|
32
|
+
* `name`: 1-64 characters; lowercase letters, digits, and hyphens only;
|
|
33
|
+
no leading, trailing, or consecutive hyphens; must match the parent
|
|
34
|
+
directory name.
|
|
35
|
+
* `description`: 1-1024 characters; say what the skill does and when to
|
|
36
|
+
use it.
|
|
37
|
+
* `license`: a license name or a reference to a bundled license file;
|
|
38
|
+
keep it short.
|
|
39
|
+
* `compatibility`: 1-500 characters; for example the intended product,
|
|
40
|
+
system packages, or network access.
|
|
41
|
+
* `metadata`: a map from string keys to string values; use reasonably
|
|
42
|
+
unique key names.
|
|
43
|
+
* `allowed-tools`: a space-separated string of pre-approved tools.
|
|
44
|
+
Experimental, so support varies between agents.
|
|
45
|
+
|
|
46
|
+
## Progressive disclosure
|
|
47
|
+
|
|
48
|
+
Agents load a skill in three steps:[^agentskills-spec]
|
|
49
|
+
|
|
50
|
+
1. **Metadata** (about 100 tokens): `name` and `description`, loaded
|
|
51
|
+
at startup for every skill.
|
|
52
|
+
2. **Instructions** (under 5000 tokens recommended): the full
|
|
53
|
+
`SKILL.md` body, loaded when the skill activates.
|
|
54
|
+
3. **Resources**: files under `scripts/`, `references/`, or `assets/`,
|
|
55
|
+
loaded only when needed.
|
|
56
|
+
|
|
57
|
+
Keep `SKILL.md` under 500 lines and move detailed material into
|
|
58
|
+
separate files.
|
|
59
|
+
|
|
60
|
+
## `references/` subdirectory
|
|
61
|
+
|
|
62
|
+
A skill may put additional documentation under `references/` (for
|
|
63
|
+
example `REFERENCE.md` or a domain-specific file) and link to it with a
|
|
64
|
+
relative path from the skill root. Agents read these files on demand, so
|
|
65
|
+
keep each one focused. Keep references one level deep from
|
|
66
|
+
`SKILL.md`.[^agentskills-spec]
|
|
67
|
+
|
|
68
|
+
[^agentskills-spec]: Agent Skills specification
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: reference
|
|
3
|
+
title: Claude Code install scopes
|
|
4
|
+
description: user, project, and local scopes — which settings file each writes to, the precedence order, and when each is the right choice.
|
|
5
|
+
tags: [agents, claude-code]
|
|
6
|
+
status: stable
|
|
7
|
+
stale_after: 2027-03-29
|
|
8
|
+
sources:
|
|
9
|
+
- id: claude-discover-plugins
|
|
10
|
+
resource: https://code.claude.com/docs/en/discover-plugins
|
|
11
|
+
title: Discover and install Claude Code plugins
|
|
12
|
+
author: team:anthropic
|
|
13
|
+
- id: claude-loading
|
|
14
|
+
resource: https://code.claude.com/docs/en/plugins/loading
|
|
15
|
+
title: How Claude Code loads plugins
|
|
16
|
+
author: team:anthropic
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
# Claude Code install scopes
|
|
20
|
+
|
|
21
|
+
Every install, by `/plugin install` or `claude plugin install`, is
|
|
22
|
+
recorded in a settings file under one of three scopes.[^claude-discover-plugins]
|
|
23
|
+
|
|
24
|
+
| Scope | Settings file | Reaches |
|
|
25
|
+
| :-------- | :----------------------------------- | :-------------------------------------- |
|
|
26
|
+
| `user` | `~/.claude/settings.json` | You, in every project on this machine |
|
|
27
|
+
| `project` | `.claude/settings.json` (committed) | Everyone who works in the repository |
|
|
28
|
+
| `local` | `.claude/settings.local.json` | You, in this repository only |
|
|
29
|
+
|
|
30
|
+
The entry is written under `enabledPlugins` in that file.
|
|
31
|
+
|
|
32
|
+
## Which scope to pick
|
|
33
|
+
|
|
34
|
+
* **`user`**: the default for `claude plugin install`. Use it for
|
|
35
|
+
plugins you want in every project.
|
|
36
|
+
* **`project`**: the entry lives in the committed `.claude/settings.json`.
|
|
37
|
+
Use it when the repository itself depends on the plugin. Committing the
|
|
38
|
+
entry enables the plugin for collaborators but does not download it, so
|
|
39
|
+
each collaborator runs
|
|
40
|
+
`claude plugin install <plugin>@<marketplace> --scope project` once.[^claude-loading]
|
|
41
|
+
* **`local`**: the entry lives in `.claude/settings.local.json`. Use it
|
|
42
|
+
for a personal setup in one repository.
|
|
43
|
+
|
|
44
|
+
## Precedence
|
|
45
|
+
|
|
46
|
+
When the same plugin is set at several scopes, `local` overrides
|
|
47
|
+
`project`, and `project` overrides `user`.[^claude-loading]
|
|
48
|
+
|
|
49
|
+
[^claude-discover-plugins]: Discover and install Claude Code plugins
|
|
50
|
+
[^claude-loading]: How Claude Code loads plugins
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: playbook
|
|
3
|
+
title: Installing through the Claude Code marketplace
|
|
4
|
+
description: Add a marketplace and install a plugin from it inside a Claude Code session, including the one-step form and the reload.
|
|
5
|
+
tags: [agents, claude-code]
|
|
6
|
+
status: stable
|
|
7
|
+
stale_after: 2027-03-29
|
|
8
|
+
sources:
|
|
9
|
+
- id: claude-discover-plugins
|
|
10
|
+
resource: https://code.claude.com/docs/en/discover-plugins
|
|
11
|
+
title: Discover and install Claude Code plugins
|
|
12
|
+
author: team:anthropic
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
# Installing through the Claude Code marketplace
|
|
16
|
+
|
|
17
|
+
Use the `/plugin` slash commands inside a Claude Code session to add a
|
|
18
|
+
marketplace and install a plugin from it.[^claude-discover-plugins]
|
|
19
|
+
|
|
20
|
+
## Two commands
|
|
21
|
+
|
|
22
|
+
```text
|
|
23
|
+
/plugin marketplace add <owner>/<repo>[#ref]
|
|
24
|
+
/plugin install <plugin>@<marketplace>
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Add `#ref` to pin a branch or tag. `<marketplace>` is the name the
|
|
28
|
+
marketplace registered under, and `<plugin>` is the plugin's name. Both
|
|
29
|
+
names are listed in [`plugin-identity.md`](plugin-identity.md).
|
|
30
|
+
|
|
31
|
+
In a session, `/plugin install` does not install right away. It opens
|
|
32
|
+
the `/plugin` panel on the plugin's details so you can review it and
|
|
33
|
+
pick a scope: user, project (all collaborators on the repository), or
|
|
34
|
+
local (you, this repository only).
|
|
35
|
+
|
|
36
|
+
## One-step form
|
|
37
|
+
|
|
38
|
+
To add a marketplace and install from it in one command, pass
|
|
39
|
+
`--marketplace` with the marketplace source. This form requires Claude
|
|
40
|
+
Code v2.1.275 or later.
|
|
41
|
+
|
|
42
|
+
```text
|
|
43
|
+
/plugin install <plugin> --marketplace <owner>/<repo>
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Give the plugin name by itself, without an `@<marketplace>` suffix. If
|
|
47
|
+
the marketplace is not added yet, Claude Code shows the source it
|
|
48
|
+
resolved and asks you to confirm before adding it.
|
|
49
|
+
|
|
50
|
+
## Scope
|
|
51
|
+
|
|
52
|
+
You choose the scope in the panel, not with a flag. The `--scope` flag
|
|
53
|
+
belongs to the shell command; see
|
|
54
|
+
[`claude-code-shell-install.md`](claude-code-shell-install.md). For what
|
|
55
|
+
each scope writes, see
|
|
56
|
+
[`claude-code-install-scopes.md`](claude-code-install-scopes.md).
|
|
57
|
+
|
|
58
|
+
## Reload
|
|
59
|
+
|
|
60
|
+
The install summary ends with one of two outcomes: `Plugin is now
|
|
61
|
+
active.`, or `Run /reload-plugins to activate.` In the second case, the
|
|
62
|
+
panel closes and Claude Code runs the reload for you. If the reload
|
|
63
|
+
would invalidate the prompt cache, Claude Code warns and leaves the
|
|
64
|
+
plugin pending; run `/reload-plugins --force` to activate it
|
|
65
|
+
anyway.[^claude-discover-plugins]
|
|
66
|
+
|
|
67
|
+
[^claude-discover-plugins]: Discover and install Claude Code plugins
|