agents-md-kit 0.0.0-stage → 0.1.0

package/presets/node-backend/manifest.txt

@@ -0,0 +1,30 @@
+# description: Node.js + TypeScript backend tooling: ESLint (typescript-eslint, Node globals), Prettier, commitlint + husky + lint-staged. With --pack github: CI, release-please, Dependabot.
+
+# Commands the installer prints for the user (it never edits package.json / pyproject.toml):
+# run: npm install -D eslint @eslint/js typescript typescript-eslint globals eslint-config-prettier prettier husky lint-staged @commitlint/cli @commitlint/config-conventional
+# run: npm pkg set scripts.prepare="husky" scripts.lint="eslint ." scripts.format="prettier --write ." scripts.format:check="prettier --check ." scripts.typecheck="tsc --noEmit"
+# run: npm run prepare
+
+
+block      node-backend  AGENTS.md  agents-node-backend.md
+copy       eslint.config.mjs
+copy       .prettierrc.json
+block      node-backend  .prettierignore  prettierignore.txt  style=hash
+copy       .editorconfig
+block      node-backend  .gitignore  gitignore.txt  style=hash
+copy       .lintstagedrc.json
+copy       .husky/pre-commit
+copy       .husky/commit-msg
+copy       commitlint.config.mjs
+copy       docs/agent-kit/node-backend.md  from=docs/node-backend.md
+
+# GitHub-only: CI, Dependabot and release-please (release-please runs as a GitHub Action,
+# so its config and the generated CHANGELOG.md come with it; without GitHub, the
+# changelog-and-versioning skill uses manual mode).
+block      node-backend-github  AGENTS.md  agents-node-backend-github.md  requires=github
+copy       .github/workflows/ci.yml              requires=github  from=github/workflows/ci.yml
+copy       .github/workflows/release-please.yml  requires=github  from=github/workflows/release-please.yml
+copy       .github/dependabot.yml                requires=github  from=github/dependabot.yml
+copy       release-please-config.json            requires=github
+copy       .release-please-manifest.json         requires=github
+copy-once  CHANGELOG.md                          requires=github

package/presets/python/docs/python.md

@@ -0,0 +1,66 @@
+# python preset: setup
+
+Installed by agent-kit. This preset adds Python tooling that does **not** need Node in your project: Ruff (lint + format), pytest, optional mypy, and git hooks through the [pre-commit](https://pre-commit.com) framework (Conventional Commit messages, Ruff, YAML/TOML/JSON syntax checks). With `--pack github` it also adds CI, release-please (`release-type: python`) and Dependabot.
+
+All configuration lives in standalone files (`ruff.toml`, `pytest.ini`, `mypy.ini`, `.pre-commit-config.yaml`). The installer never edits `pyproject.toml`. Keep tool settings out of it too, or the two sources will disagree. Note that `pytest.ini` takes precedence over `[tool.pytest.ini_options]`.
+
+## 1. Install the tools and the hooks
+
+Use whatever you use for dev dependencies (pip, uv, Poetry, pipx). With pip in a virtualenv:
+
+```bash
+python -m pip install ruff==0.17.4 pytest pre-commit   # add mypy if you keep mypy.ini
+pre-commit install          # installs the pre-commit and commit-msg hooks
+```
+
+`default_install_hook_types` in `.pre-commit-config.yaml` makes `pre-commit install` set up both hook types. The pinned hook revisions (verified 2026-11-11):
+
+| Hook repo | rev | Hooks |
+|---|---|---|
+| `astral-sh/ruff-pre-commit` | `v0.17.4` | `ruff-check --fix`, `ruff-format` |
+| `pre-commit/pre-commit-hooks` | `v6.0.0` | `check-yaml`, `check-toml`, `check-json`, `check-merge-conflict`, `check-added-large-files` |
+| `compilerla/conventional-pre-commit` | `v4.5.0` | `conventional-pre-commit` (commit-msg stage) |
+
+Update them with `pre-commit autoupdate`, and keep the `ruff==` pin in `.github/workflows/ci.yml` in sync with the ruff-pre-commit rev.
+
+## 2. Check it works
+
+```bash
+ruff check .
+ruff format --check .
+pytest
+mypy src            # optional
+git commit -m "Added stuff."        # rejected by the commit-msg hook
+git commit -m "feat: add totals"    # accepted
+```
+
+The commit-msg hook checks the Conventional Commits format and the allowed types. It does not enforce the 72-character header limit that commitlint enforces in the Node presets. Keep headers short anyway (see the `git-commit-and-workflow` skill).
+
+## 3. GitHub repository settings (only with `--pack github`)
+
+1. **Pull requests: allow squash merging only**, with *Default to pull request title* as the commit message. This makes the PR title the release note.
+2. **Branch protection on `main`**: require a pull request, require the `checks` and `pr-title` status checks, block force pushes.
+3. **Actions > General > Workflow permissions**: *Read and write*, and tick **Allow GitHub Actions to create and approve pull requests** (needed by release-please).
+4. Optional: add a `RELEASE_PLEASE_TOKEN` secret (PAT or GitHub App token) and pass it in `.github/workflows/release-please.yml`, so CI also runs on the release PR.
+
+CI (`.github/workflows/ci.yml`) installs Ruff and pytest, then `requirements.txt` / `requirements-dev.txt` if present and the project itself (`pip install -e .`) if `pyproject.toml` exists, and runs `ruff check`, `ruff format --check` and `pytest`. Adjust the install step if you use uv or Poetry. pytest exits with code 5 when it collects no tests, so add at least one test before enabling CI.
+
+## 4. What release-please expects (only with `--pack github`)
+
+With `release-type: python`, merging the release PR updates `CHANGELOG.md`, tags `vX.Y.Z`, and bumps the version in these files when they exist:
+
+- `pyproject.toml`: a **static** `version = "..."` under `[project]` (or `[tool.poetry]`). A `dynamic = ["version"]` setup is not bumped.
+- `setup.py` and `setup.cfg`.
+- `<package>/__init__.py` or `src/<package>/__init__.py` (`__version__ = "..."`), where the package name comes from `[project] name` (dashes also tried as underscores).
+- Any `version.py`.
+
+The first release starts from `0.0.0` in `.release-please-manifest.json`. Set `version = "0.0.0"` in `pyproject.toml` to match, or put your current version in the manifest. `feat` is Added, `fix` is Fixed, `perf` and `revert` are Changed; other types are hidden.
+
+Without the github pack, release-please files are not installed and the `changelog-and-versioning` skill uses manual mode.
+
+## 5. Customize
+
+- **Rules:** edit `select` in `ruff.toml`. Set `target-version` there if you have no `requires-python`.
+- **Types:** delete `mypy.ini` if you don't type-check; otherwise add mypy to CI and, if you like, as a pre-commit hook (`pre-commit/mirrors-mypy`).
+- **Ignore lists:** add your own lines to `.gitignore` outside the `agent-kit` markers.
+- **Not using release-please?** Delete `release-please-config.json`, `.release-please-manifest.json` and `.github/workflows/release-please.yml`; the `changelog-and-versioning` skill switches to manual mode.

package/presets/python/files/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 4
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{yml,yaml,json,toml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

package/presets/python/files/.pre-commit-config.yaml

@@ -0,0 +1,32 @@
+# Git hooks via the pre-commit framework (https://pre-commit.com). No Node needed.
+# Run once per clone:  pre-commit install
+# (default_install_hook_types makes that install both the pre-commit and commit-msg hooks.)
+# Update the pinned revs with:  pre-commit autoupdate
+default_install_hook_types: [pre-commit, commit-msg]
+# Hooks without an explicit `stages` run only before commits, not again on the message.
+default_stages: [pre-commit]
+
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.17.4
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-yaml
+      - id: check-toml
+      - id: check-json
+      - id: check-merge-conflict
+      - id: check-added-large-files
+
+  # Conventional Commits on every commit message (types match the git-commit-and-workflow skill).
+  - repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v4.5.0
+    hooks:
+      - id: conventional-pre-commit
+        stages: [commit-msg]
+        args: [feat, fix, perf, refactor, docs, test, build, ci, style, chore, revert]

package/presets/python/files/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.0.0"
+}

package/presets/python/files/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+This file is generated by [release-please](https://github.com/googleapis/release-please) from Conventional Commits. Do not edit it by hand. See the `changelog-and-versioning` skill.

package/presets/python/files/mypy.ini

@@ -0,0 +1,5 @@
+# Optional: mypy type checking. Delete this file if you don't use mypy.
+[mypy]
+strict = True
+warn_unreachable = True
+exclude = (?x)(^build/|^dist/|^\.venv/)

package/presets/python/files/pytest.ini

@@ -0,0 +1,6 @@
+# pytest configuration. Kept in its own file so agent-kit never edits pyproject.toml.
+# Note: pytest.ini takes precedence over [tool.pytest.ini_options] in pyproject.toml.
+[pytest]
+testpaths = tests
+addopts = -ra --strict-markers --strict-config
+xfail_strict = true

package/presets/python/files/release-please-config.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "release-type": "python",
+  "include-component-in-tag": false,
+  "bump-minor-pre-major": true,
+  "bump-patch-for-minor-pre-major": false,
+  "packages": {
+    ".": {
+      "changelog-path": "CHANGELOG.md"
+    }
+  },
+  "changelog-sections": [
+    { "type": "feat", "section": "Added" },
+    { "type": "fix", "section": "Fixed" },
+    { "type": "perf", "section": "Changed" },
+    { "type": "revert", "section": "Changed" },
+    { "type": "docs", "section": "Documentation", "hidden": true },
+    { "type": "style", "section": "Styles", "hidden": true },
+    { "type": "refactor", "section": "Refactoring", "hidden": true },
+    { "type": "test", "section": "Tests", "hidden": true },
+    { "type": "build", "section": "Build", "hidden": true },
+    { "type": "ci", "section": "CI", "hidden": true },
+    { "type": "chore", "section": "Chores", "hidden": true }
+  ]
+}

package/presets/python/files/ruff.toml

@@ -0,0 +1,17 @@
+# Ruff linter and formatter (https://docs.astral.sh/ruff/).
+# Kept in its own file so agent-kit never edits pyproject.toml.
+# target-version: when unset, Ruff infers it from `requires-python` in pyproject.toml.
+
+line-length = 100
+extend-exclude = ["build", "dist"]
+
+[lint]
+# E4/E7/E9/F: pyflakes + error-prone pycodestyle; W: warnings; I: import order;
+# B: bugbear; UP: pyupgrade; S: bandit security; SIM: simplify; RUF: ruff-specific.
+select = ["E4", "E7", "E9", "F", "W", "I", "B", "UP", "S", "SIM", "RUF"]
+
+[lint.per-file-ignores]
+"tests/**" = ["S101"] # assert is how pytest works
+
+[format]
+docstring-code-format = true

package/presets/python/fragments/agents-python-github.md

@@ -0,0 +1,7 @@
+### GitHub automation (python preset + github pack)
+
+| Tool | Config | Enforces |
+|---|---|---|
+| CI | `.github/workflows/ci.yml` | Ruff lint, Ruff format check, pytest |
+| release-please | `release-please-config.json`, `.release-please-manifest.json`, `.github/workflows/release-please.yml` | Version bumps (`pyproject.toml` and related files), `CHANGELOG.md`, tags. Don't hand-edit `CHANGELOG.md` or version fields |
+| Dependabot | `.github/dependabot.yml` | Weekly pip and GitHub Actions updates with Conventional Commit messages |

package/presets/python/fragments/agents-python.md

@@ -0,0 +1,14 @@
+## Python
+
+### Tooling (installed by the python preset; don't work around it)
+
+| Tool | Config | Enforces |
+|---|---|---|
+| pre-commit `commit-msg` | `.pre-commit-config.yaml` (conventional-pre-commit) | Conventional Commit format on every commit |
+| pre-commit `pre-commit` | `.pre-commit-config.yaml` | Ruff lint (with fixes) and format; YAML/TOML/JSON syntax; merge markers; large files |
+| Ruff | `ruff.toml` | Lint rules (pyflakes, bugbear, bandit, pyupgrade, imports) and formatting |
+| pytest | `pytest.ini` | Test discovery in `tests/`, strict markers and config |
+| mypy (optional) | `mypy.ini` | Strict type checking |
+| EditorConfig | `.editorconfig` | Charset, line endings, indentation |
+
+Never bypass these (`--no-verify`, disabling rules to make a check pass). Fix the underlying issue. Keep this configuration out of `pyproject.toml`. Setup and versions: `docs/agent-kit/python.md`.

package/presets/python/fragments/gitignore.txt

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Environment and secrets (keep .env.example)
+.env
+.env.*
+!.env.example
+
+# Logs and OS/editor files
+*.log
+.DS_Store
+.idea/
+.vscode/*
+!.vscode/extensions.json

package/presets/python/github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: build
+      include: scope # produces "build(deps): bump ..."
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: ci
+      include: scope

package/presets/python/github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    name: checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13' # adjust to your project's supported Python version
+
+      - name: Install tools and the project
+        run: |
+          python -m pip install --upgrade pip
+          # Keep the ruff version in sync with .pre-commit-config.yaml.
+          python -m pip install ruff==0.17.4 pytest
+          if [ -f requirements.txt ]; then python -m pip install -r requirements.txt; fi
+          if [ -f requirements-dev.txt ]; then python -m pip install -r requirements-dev.txt; fi
+          if [ -f pyproject.toml ]; then python -m pip install -e .; fi
+
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: pytest

package/presets/python/github/workflows/release-please.yml

@@ -0,0 +1,21 @@
+name: release-please
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+          # PRs opened with the default GITHUB_TOKEN do not trigger other workflows (e.g. CI).
+          # If you want CI to run on the release PR, create a PAT or GitHub App token
+          # and pass it here: token: ${{ secrets.RELEASE_PLEASE_TOKEN }}

package/presets/python/manifest.txt

@@ -0,0 +1,25 @@
+# description: Python tooling without Node: Ruff (lint + format), pytest, optional mypy, pre-commit hooks (Conventional Commits, Ruff). With --pack github: CI, release-please (python), Dependabot.
+
+# Commands the installer prints for the user (it never edits package.json / pyproject.toml):
+# run: python -m pip install ruff==0.17.4 pytest pre-commit
+# run: pre-commit install
+
+block      python  AGENTS.md  agents-python.md
+copy       ruff.toml
+copy       pytest.ini
+copy       mypy.ini
+copy       .pre-commit-config.yaml
+copy       .editorconfig
+block      python  .gitignore  gitignore.txt  style=hash
+copy       docs/agent-kit/python.md  from=docs/python.md
+
+# GitHub-only: CI, Dependabot and release-please. release-please runs as a GitHub Action,
+# so its config and the generated CHANGELOG.md come with it; without GitHub, the
+# changelog-and-versioning skill uses manual mode.
+block      python-github  AGENTS.md  agents-python-github.md  requires=github
+copy       .github/workflows/ci.yml              requires=github  from=github/workflows/ci.yml
+copy       .github/workflows/release-please.yml  requires=github  from=github/workflows/release-please.yml
+copy       .github/dependabot.yml                requires=github  from=github/dependabot.yml
+copy       release-please-config.json            requires=github
+copy       .release-please-manifest.json         requires=github
+copy-once  CHANGELOG.md                          requires=github

package/presets/react-typescript/docs/react-typescript.md

@@ -0,0 +1,71 @@
+# react-typescript preset: setup
+
+Installed by agent-kit. This preset adds React + TypeScript tooling and the `react-principles` skill. It always brings the `web` pack (HTML/accessibility and SEO skills). With `--pack github` it also adds CI, release-please and Dependabot.
+
+The installer never edits `package.json`. Run the commands below yourself.
+
+## 1. Install the tooling
+
+```bash
+npm install -D \
+  eslint@9 @eslint/js@9 typescript typescript-eslint globals \
+  eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-jsx-a11y eslint-config-prettier \
+  prettier husky lint-staged @commitlint/cli @commitlint/config-conventional
+
+npm pkg set scripts.prepare="husky"
+npm pkg set scripts.lint="eslint ."
+npm pkg set scripts.format="prettier --write ."
+npm pkg set scripts.format:check="prettier --check ."
+npm pkg set scripts.typecheck="tsc --noEmit"
+
+npm run prepare          # activates the git hooks in .husky/ (sets core.hooksPath)
+```
+
+`test` and `build` scripts come from your framework scaffold (Vite, Next.js, etc.). Add `tsconfig.json`, the framework config and a test runner (Vitest or Jest + React Testing Library) from your scaffolder. They are intentionally not included.
+
+Using pnpm or yarn? Swap the install commands, replace `npm ci` / `npm audit` in `.github/workflows/ci.yml`, and change `npx` in `.husky/*` to `pnpm exec` / `yarn`.
+
+### Why `eslint@9`?
+
+Verified on 2026-11-11: plain `npm install eslint` resolves ESLint 10, but `eslint-plugin-jsx-a11y@6.10.2` only declares support up to ESLint 9, so npm fails with `ERESOLVE`. Forcing it with `--legacy-peer-deps` also pulls in TypeScript 7, which `typescript-eslint` rejects (it needs TypeScript 6.x). npm prints a "no longer supported" warning for ESLint 9; that is expected.
+
+Once `eslint-plugin-jsx-a11y` supports ESLint 10 (`npm view eslint-plugin-jsx-a11y peerDependencies`), drop the `@9` pins and check that `npm run lint` still passes. Consider recording this in your `MEMORY.md` under Gotchas:
+
+```
+- [2026-11-11] Keep `eslint` and `@eslint/js` pinned to `@9` until eslint-plugin-jsx-a11y supports ESLint 10 (npm ERESOLVE otherwise). See docs/agent-kit/react-typescript.md. (verified)
+```
+
+## 2. Check it works
+
+```bash
+echo "feat(auth): add passkey login" | npx commitlint     # passes
+echo "Added stuff." | npx commitlint                       # fails
+npm run lint
+npx prettier --check .
+```
+
+Husky v9 hook files have no shebang and need the exec bit on macOS/Linux (the installer sets it there). On Windows, run `git update-index --chmod=+x .husky/pre-commit .husky/commit-msg` before committing them, so they work for colleagues on other systems.
+
+## 3. GitHub repository settings (only with `--pack github`)
+
+1. **Pull requests: allow squash merging only**, with *Default to pull request title* as the commit message. This makes the PR title the release note.
+2. **Branch protection on `main`**: require a pull request, require the `checks` and `pr-title` status checks, block force pushes.
+3. **Actions > General > Workflow permissions**: *Read and write*, and tick **Allow GitHub Actions to create and approve pull requests** (needed by release-please).
+4. Optional: add a `RELEASE_PLEASE_TOKEN` secret (PAT or GitHub App token) and pass it in `.github/workflows/release-please.yml`. PRs opened with the default `GITHUB_TOKEN` do not trigger other workflows, so without it CI does not run on the release PR.
+
+## 4. How releases work (only with `--pack github`)
+
+1. Merge PRs to `main` with Conventional Commit titles.
+2. release-please opens (and keeps updating) a **release PR** with the next version and the generated `CHANGELOG.md` section.
+3. Review and merge the release PR. release-please tags `vX.Y.Z` and creates the GitHub Release.
+
+Version bumps: `fix` is patch, `feat` is minor, `!` or a `BREAKING CHANGE:` footer is major (below 1.0.0, breaking changes bump minor). The first release starts from `0.0.0` in `.release-please-manifest.json`. Changelog sections use Keep a Changelog names: `feat` is Added, `fix` is Fixed, `perf` and `revert` are Changed; other types are hidden.
+
+Without the github pack, release-please files are not installed and the `changelog-and-versioning` skill uses manual mode.
+
+## 5. Customize
+
+- **Scopes:** uncomment `scope-enum` in `commitlint.config.mjs`.
+- **Changelog sections:** edit `changelog-sections` in `release-please-config.json`.
+- **Ignore lists:** add your own lines to `.gitignore` / `.prettierignore` outside the `agent-kit` markers. The installer only manages the text between the markers.
+- **Not using release-please?** Delete `release-please-config.json`, `.release-please-manifest.json` and `.github/workflows/release-please.yml`. The `changelog-and-versioning` skill switches to manual mode when `release-please-config.json` is absent.