diff --git a/plugins/kyberforge/skills/pc-author/README.md b/plugins/kyberforge/skills/pc-author/README.md new file mode 100644 index 0000000..272bfbb --- /dev/null +++ b/plugins/kyberforge/skills/pc-author/README.md @@ -0,0 +1,23 @@ +# pc-author + +Create, add, remove, update, and configure `.pre-commit-config.yaml`. + +## What it does + +Manages the pre-commit configuration file in any git repo. When invoked, it scans the repo for languages, proposes appropriate hooks with rationale, and writes or modifies `.pre-commit-config.yaml`. It validates every write with `pre-commit validate-config` and flags stale revision pins. It does not run hooks or install them into `.git/hooks/` — use `pc-run` for that. + +## Usage + +``` +/pc-author +``` + +Invoke with no arguments. The skill determines from context whether to create a new config or modify an existing one. + +## Files + +| File | Purpose | +|------|---------| +| `SKILL.md` | Skill instructions for agents | +| `references/hooks-by-language.md` | Hook recommendations by detected language/extension | +| `references/sources.md` | Provenance — research sources that informed this skill | diff --git a/plugins/kyberforge/skills/pc-author/SKILL.md b/plugins/kyberforge/skills/pc-author/SKILL.md new file mode 100644 index 0000000..e014e6c --- /dev/null +++ b/plugins/kyberforge/skills/pc-author/SKILL.md @@ -0,0 +1,88 @@ +--- +name: pc-author +description: > + Use when the user wants to create, add hooks to, remove hooks from, update, + or configure .pre-commit-config.yaml. Triggers on: "set up pre-commit", + "add a hook", "remove this hook", "configure pre-commit", "create a pre-commit + config", "disable trailing whitespace hook", "add shellcheck", "update my + pre-commit config", even if the user does not name pre-commit explicitly. + Do not use for running hooks, installing git hooks, or bumping revision pins + — use pc-run for those. +allowed-tools: Bash Read Write Edit +metadata: + category: devtools + source_keys: + - context7-pre-commit-com + - pre-commit-com + - context7-pre-commit-hooks + - pre-commit-hooks-github +--- + +## Gotchas + +- `rev` must be an immutable tag or commit SHA — never a branch name. `pre-commit autoupdate` breaks silently on branches. +- Fixers (`trailing-whitespace`, `end-of-file-fixer`, `pretty-format-json`) modify files but do NOT auto-stage them. The commit is blocked; the user must re-stage and recommit. Warn when adding fixers. +- `pre-commit validate-config` catches YAML structure errors and unknown hook IDs but does NOT download or run hooks. It is fast; run it after every write. +- When removing a hook leaves its repo block with zero hooks, delete the entire repo block — an empty `hooks: []` causes `validate-config` to fail. +- `language: system` and `language: script` are deprecated names. Use `language: unsupported` and `language: unsupported_script` for new local hooks. + +## Route + +Check before acting: + +- `.pre-commit-config.yaml` does not exist → **Create from scratch** +- File exists → **Modify existing** + +## Create from scratch + +1. Run a shallow extension scan: + ```bash + git ls-files | grep -oE '\.[a-z]+$' | sort | uniq -c | sort -rn + ``` +2. Read `references/hooks-by-language.md` to map detected extensions to recommended hooks. +3. State the proposed config in full before writing. Wait for user confirmation. +4. Write `.pre-commit-config.yaml`. +5. Run `pre-commit validate-config`. If non-zero: show the error, fix it, re-validate. Never leave a broken config. + +## Modify existing + +Read `.pre-commit-config.yaml` first. Note any stale `rev` values (see **Rev staleness** below) but do not change them. + +### Adding a hook + +1. Run a shallow extension scan to detect languages in the repo: + ```bash + git ls-files | grep -oE '\.[a-z]+$' | sort | uniq -c | sort -rn + ``` +2. Read `references/hooks-by-language.md` for the correct repo URL, rev, and recommended args for any hook before writing. +3. Check for duplicates — if the same hook ID or equivalent tool already exists in the config, say so and stop. +4. If the hook's source repo already exists in the config, add the hook under that repo block. Otherwise append a new repo block. +5. State the proposed addition. Wait for confirmation. +6. Write. Run `pre-commit validate-config`. If non-zero: show error, fix, re-validate. + +### Removing a hook + +1. Identify the hook entry and its repo block. +2. State what will be removed: hook ID, and whether the parent repo block will also be deleted (if it would have zero hooks remaining). Wait for confirmation. +3. Remove the hook entry. If the repo block now has zero hooks remaining, remove the entire repo block. +4. Write. Run `pre-commit validate-config`. If non-zero: revert the edit, show the error, and stop — do not leave a broken config. + +### Configuring top-level keys + +Only when the user explicitly asks. Valid keys: `fail_fast`, `default_stages`, `default_language_version`, `minimum_pre_commit_version`, `exclude`, `files`, `default_install_hook_types`. + +State the proposed change and wait for confirmation before writing. + +## Rev staleness + +When reading the config, for each repo listed in `references/hooks-by-language.md`, compare its `rev` in the user's config against the rev in that file. Flag any mismatch as potentially outdated and tell the user to run `pc-run` to autoupdate. Repos not in the reference cannot be checked — skip them silently. Do not modify `rev` values yourself. + +## Scope boundary + +This skill manages `.pre-commit-config.yaml` only. It does not: +- Author `.pre-commit-hooks.yaml` (publishing hooks for external consumers) +- Run `pre-commit install` +- Execute hooks or run the test suite +- Bump `rev` values + +For those operations, use `pc-run`. diff --git a/plugins/kyberforge/skills/pc-author/references/hooks-by-language.md b/plugins/kyberforge/skills/pc-author/references/hooks-by-language.md new file mode 100644 index 0000000..7ca7f8d --- /dev/null +++ b/plugins/kyberforge/skills/pc-author/references/hooks-by-language.md @@ -0,0 +1,104 @@ +--- +source_keys: + - context7-pre-commit-com + - pre-commit-com + - context7-pre-commit-hooks + - pre-commit-hooks-github +--- + +# Hook Recommendations by Language / Context + +Use this table when creating a config from scratch or recommending hooks to add. +Always check the existing config for duplicates before proposing. + +## Universal (recommend for every repo) + +| Hook ID | Repo | Rev | Rationale | +|---------|------|-----|-----------| +| `end-of-file-fixer` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Ensures files end with a newline — prevents spurious diffs | +| `trailing-whitespace` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Strips trailing whitespace — prevents invisible diff noise | +| `check-merge-conflict` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Catches unresolved merge markers before commit | +| `detect-private-key` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Blocks PEM private key material | + +## Shell (`.sh`) + +| Hook ID | Repo | Rev | Rationale | +|---------|------|-----|-----------| +| `shellcheck` | `https://github.com/jumanjihouse/pre-commit-hooks` | `3.0.0` | Static analysis for shell scripts; catches common errors | + +Recommended args: `args: [--severity=warning]` + +## Python (`.py`) + +| Hook ID | Repo | Rev | Rationale | +|---------|------|-----|-----------| +| `check-ast` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Validates Python files parse as valid AST | +| `check-builtin-literals` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Enforces literal syntax for `dict()`, `list()` | + +For formatting: check if `black`, `ruff`, or `isort` is already configured in `pyproject.toml` before recommending them. + +## JSON (`.json`) + +| Hook ID | Repo | Rev | Rationale | +|---------|------|-----|-----------| +| `check-json` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Validates JSON parses correctly | +| `pretty-format-json` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Auto-formats JSON (fixer — warns user to re-stage after commit) | + +## YAML (`.yaml`, `.yml`) + +| Hook ID | Repo | Rev | Rationale | +|---------|------|-----|-----------| +| `check-yaml` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Validates YAML parses correctly | + +For Kubernetes/Helm YAML with custom tags, add `args: ['--unsafe']` and `exclude: ^helm/templates/`. + +## TOML (`.toml`) + +| Hook ID | Repo | Rev | Rationale | +|---------|------|-----|-----------| +| `check-toml` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Validates TOML parses correctly | + +## Secrets / security + +| Hook ID | Repo | Rev | Rationale | +|---------|------|-----|-----------| +| `gitleaks` | `https://github.com/gitleaks/gitleaks` | `v8.21.2` | Scans for secrets and high-entropy strings | + +## Commit message + +| Hook ID | Repo | Rev | Stage | Rationale | +|---------|------|-----|-------|-----------| +| `conventional-pre-commit` | `https://github.com/compilerla/conventional-pre-commit` | `v2.4.0` | `commit-msg` | Enforces Conventional Commits format | + +When adding commit-msg hooks, also add `default_install_hook_types: [pre-commit, commit-msg]` to the top-level config if not already present. + +## Meta-validation (add last, after all other repos) + +```yaml +- repo: meta + hooks: + - id: check-hooks-apply # catches hooks that match no files + - id: check-useless-excludes # catches exclude patterns that match no files +``` + +## Local hooks (repo: local) + +Use for repo-specific scripts that don't belong in an external hook repo. + +```yaml +- repo: local + hooks: + - id: run-tests + name: Run test suite + entry: bash tests/run-tests.sh + language: unsupported_script + pass_filenames: false + always_run: true + stages: [pre-push] +``` + +Language choices for local hooks: +- `unsupported` — system PATH tool (pre-commit does not manage env) +- `unsupported_script` — script at a repo-relative path +- `fail` — always-fail guard; `entry` text becomes the error message +- `python` — isolated venv; use `additional_dependencies` for pip packages diff --git a/plugins/kyberforge/skills/pc-author/references/sources.md b/plugins/kyberforge/skills/pc-author/references/sources.md new file mode 100644 index 0000000..f18aeb5 --- /dev/null +++ b/plugins/kyberforge/skills/pc-author/references/sources.md @@ -0,0 +1,33 @@ +# Sources + +## context7-pre-commit-com + +- **URL:** context7:/pre-commit/pre-commit.com +- **Description:** Official pre-commit.com documentation — installation, configuration schema, CLI reference, hook authoring, advanced features, troubleshooting +- **Contributing files:** SKILL.md, references/hooks-by-language.md +- **Research doc:** plugins/kyberforge/docs/research/docs/pre-commit/sources.md +- **Status:** `extracted` + +## pre-commit-com + +- **URL:** https://pre-commit.com/ +- **Description:** Pre-commit framework homepage — full docs covering install, config, CLI, hook authoring, stages, local hooks, meta hooks, hazmat helpers, CI integration +- **Contributing files:** SKILL.md, references/hooks-by-language.md +- **Research doc:** plugins/kyberforge/docs/research/docs/pre-commit/sources.md +- **Status:** `extracted` + +## context7-pre-commit-hooks + +- **URL:** context7:/pre-commit/pre-commit-hooks +- **Description:** Official pre-commit-hooks collection — all available hook IDs with options and examples +- **Contributing files:** references/hooks-by-language.md +- **Research doc:** plugins/kyberforge/docs/research/docs/pre-commit/sources.md +- **Status:** `extracted` + +## pre-commit-hooks-github + +- **URL:** https://raw.githubusercontent.com/pre-commit/pre-commit-hooks/main/README.md +- **Description:** Official pre-commit-hooks README — complete hook listing with all args, categories, deprecated hooks, and latest version (v6.0.0) +- **Contributing files:** references/hooks-by-language.md +- **Research doc:** plugins/kyberforge/docs/research/docs/pre-commit/sources.md +- **Status:** `extracted` diff --git a/plugins/kyberforge/skills/pc-run/README.md b/plugins/kyberforge/skills/pc-run/README.md new file mode 100644 index 0000000..7113b56 --- /dev/null +++ b/plugins/kyberforge/skills/pc-run/README.md @@ -0,0 +1,29 @@ +# pc-run + +Runs, installs, updates, and maintains pre-commit hooks in a local git clone. + +## What it does + +`pc-run` handles everything that happens *after* `.pre-commit-config.yaml` exists: wiring hooks into git, running them, bumping their versions, and maintaining the cache. When hooks fail, it identifies the cause and suggests a concrete fix — it does not auto-fix files or edit the config. For creating or editing `.pre-commit-config.yaml`, use `pc-author` instead. + +## Before you start + +- `pre-commit` must be installed and available on `PATH` +- A `.pre-commit-config.yaml` must exist at the repo root (use `pc-author` to create one) + +## Usage + +Common invocations: +- `/pc-run` — run all hooks against all files (default) +- `/pc-run install` — wire hooks into `.git/hooks/` +- `/pc-run autoupdate` — bump all `rev` values to latest +- `/pc-run clean` — wipe the pre-commit cache (requires confirmation) + +## Files + +| File | Purpose | +|------|---------| +| `SKILL.md` | Skill instructions for agents | +| `references/failure-patterns.md` | Hook failure causes and concrete fix suggestions | +| `references/sources.md` | Provenance: research sources that informed this skill | +| `references/README.md` | Directory index for references/ | diff --git a/plugins/kyberforge/skills/pc-run/SKILL.md b/plugins/kyberforge/skills/pc-run/SKILL.md new file mode 100644 index 0000000..fc5d9e5 --- /dev/null +++ b/plugins/kyberforge/skills/pc-run/SKILL.md @@ -0,0 +1,121 @@ +--- +name: pc-run +description: > + Use when the user wants to run pre-commit hooks, install git hooks, update + hook versions, or maintain the pre-commit cache. Triggers on: "run + pre-commit", "run all hooks", "check everything passes", "install hooks", + "wire hooks into git", "update hook versions", "autoupdate", "bump revs", + "clean the cache", "rebuild environments", "gc", "why is my hook failing", + "hooks aren't running". Do not use for creating or editing + `.pre-commit-config.yaml` — use `pc-author` for that. + +compatibility: Requires pre-commit installed and available on PATH. + +metadata: + category: devtools + source_keys: + - context7-pre-commit-com + - pre-commit-com + +allowed-tools: Bash Read +--- + +## Gotchas + +- Hooks not running on `git commit` almost always means `pre-commit install` was never run in this clone. Git hooks are per-clone — they are not committed to the repo. +- When a hook modifies files (e.g. `trailing-whitespace`, `end-of-file-fixer`), the commit is blocked intentionally — the staged version is stale. The fix is `git add -u && git commit`. Do NOT call `pre-commit install -f` here; that is for overwriting existing hooks, not re-staging. +- `pre-commit autoupdate` modifies `.pre-commit-config.yaml` in-place. Re-read the file after calling it to show the user the updated `rev` values. +- The `SKIP` env var requires exact hook `id` values, comma-separated, no spaces: `SKIP=check-yaml,gitleaks git commit -m "msg"`. A space after the comma silently skips nothing. +- A stages mismatch — hook stage not installed — means the hook was added to the config but `pre-commit install` was not re-run with the correct `-t` flags. Hooks in stages not listed under `default_install_hook_types` will never fire. + +## Route + +Determine intent from the user's request, then execute the matching operation: + +| User intent | Operation | +|---|---| +| "run", "check", "verify", "test hooks" | `pre-commit run --all-files` (default) | +| "staged", "simulate commit" | `pre-commit run` (staged files only) | +| "install", "set up hooks", "wire into git" | `pre-commit install` — see Install | +| "pre-create environments", "install-hooks", "warm cache" | `pre-commit install-hooks` — see Install | +| "remove hooks", "uninstall", "tear down pre-commit" | `pre-commit uninstall` | +| "autoupdate", "update versions", "bump revs" | `pre-commit autoupdate` | +| "gc", "garbage collect" | `pre-commit gc` | +| "clean", "wipe cache", "rebuild from scratch" | `pre-commit clean` — see Clean | + +If the intent is ambiguous, default to `pre-commit run --all-files`. + +## Run + +Default: `pre-commit run --all-files`. Never silently run staged-only. + +```bash +pre-commit run --all-files +``` + +**When hooks fail**, read the output and: +1. Identify which hook failed and the specific cause. Be concrete: "gitleaks blocked `config.json` (high-entropy string on line 12)", not just "gitleaks failed". +2. Suggest a concrete next step. Common patterns are in `references/failure-patterns.md`. +3. Do NOT auto-fix code files. Do NOT modify `.pre-commit-config.yaml`. Those are the user's or `pc-author`'s responsibility. + +If the user asks to run only staged files: `pre-commit run` (no `--all-files`). +If the user names a specific hook: `pre-commit run `. + +## Install + +Only run when the user explicitly asks to install or set up hooks. + +Before running, check for existing hook files: + +```bash +ls .git/hooks/ +``` + +If any hook files exist (e.g. a hand-written `pre-commit`), `pre-commit install` will refuse and exit with an error — it will not overwrite them without `-f`. If files are present, warn the user: "Existing hook files found at `.git/hooks/`. Running `pre-commit install -f` will replace them permanently. Proceed?" Wait for confirmation before using `-f`. + +```bash +pre-commit install +``` + +Re-run with `-t` flags when `default_install_hook_types` was changed or when hooks in non-default stages aren't firing: + +```bash +pre-commit install -t pre-commit -t pre-push -t commit-msg +``` + +To pre-create all hook environments without running hooks (useful for CI warm-up or first-time setup): + +```bash +pre-commit install-hooks +``` + +To remove pre-commit from `.git/hooks/` entirely: + +```bash +pre-commit uninstall +``` + +## Autoupdate + +```bash +pre-commit autoupdate +``` + +After it completes, read `.pre-commit-config.yaml` and report which `rev` values changed. If the user wants to pin to exact SHAs (for reproducibility): `pre-commit autoupdate --freeze`. + +## Clean and GC + +**`gc`** — removes only unused cached environments. Safe to run at any time: +```bash +pre-commit gc +``` + +**`clean`** — wipes the entire cache at `~/.cache/pre-commit`. All hook environments will be re-downloaded on next run. Require explicit confirmation before running: + +> "This will wipe the entire pre-commit cache. All hook environments will be re-downloaded on next run. Proceed?" + +Wait for the user to say yes before executing: + +```bash +pre-commit clean +``` diff --git a/plugins/kyberforge/skills/pc-run/references/README.md b/plugins/kyberforge/skills/pc-run/references/README.md new file mode 100644 index 0000000..557d71f --- /dev/null +++ b/plugins/kyberforge/skills/pc-run/references/README.md @@ -0,0 +1,6 @@ +# references/ + +| File | Purpose | +|---|---| +| `failure-patterns.md` | Hook failure causes and concrete fix suggestions — loaded when hooks fail | +| `sources.md` | Provenance: research sources that informed this skill | diff --git a/plugins/kyberforge/skills/pc-run/references/failure-patterns.md b/plugins/kyberforge/skills/pc-run/references/failure-patterns.md new file mode 100644 index 0000000..b6b55b6 --- /dev/null +++ b/plugins/kyberforge/skills/pc-run/references/failure-patterns.md @@ -0,0 +1,88 @@ +--- +source_keys: + - context7-pre-commit-com + - pre-commit-com +--- + +# Hook Failure Patterns + +Common hook failure causes and concrete next-step suggestions. + +## Hook modified files — commit blocked + +Cause: A fixer hook (e.g. `trailing-whitespace`, `end-of-file-fixer`, `pretty-format-json`) modified staged files. The commit is blocked because the staged version is now stale. + +Fix: Re-stage and recommit. +```bash +git add -u +git commit -m "same message" +``` + +## Secret detected (gitleaks) + +Cause: gitleaks found a high-entropy string or known secret pattern in a staged file. + +Suggestions: +- If it's a false positive: add a `# gitleaks:allow` inline comment, or add the path to `.gitleaksignore`. +- If it's a real secret: remove it from the file, rotate the credential, then commit. + +## Shellcheck warning + +Cause: shellcheck found a shell script issue. The output includes the file path, line number, and SC-code. + +Fix: Look up the SC-code on shellcheck.net or pass `--explain SCxxxx` to shellcheck for a detailed explanation. The most common fixes: +- SC2086 (unquoted variable): wrap in double quotes. +- SC2046 (unquoted command substitution): wrap in double quotes. +- SC2181 (check exit code of `$?`): use `if command; then` directly. + +## pretty-format-json fails but doesn't fix + +Cause: `pretty-format-json` requires `args: [--autofix]` to modify files. Without it, the hook only fails. + +Fix: The user (or `pc-author`) must add `args: [--autofix]` to the hook override in `.pre-commit-config.yaml`. + +## Environment stale or broken + +Cause: A hook's cached environment is corrupted or out of date. + +Fix: +```bash +pre-commit clean # wipe all environments +pre-commit install-hooks # rebuild everything +``` + +Or less destructively: +```bash +pre-commit gc # remove only unused environments +``` + +## Hooks don't run on `git commit` + +Cause: `pre-commit install` was never run in this clone. + +Fix: `pre-commit install`. Git hooks are per-clone — they are not committed to the repo. + +## Hook runs but matches wrong files (or no files) + +Cause: The `files:` pattern uses `re.search()` not full-string match. A pattern that looks correct may match unexpectedly. + +Diagnosis: `identify-cli ` shows the type tags for a file. Verify `types:` filters against these. + +## stages mismatch — hook never fires + +Cause: Hook is defined for a stage (e.g. `pre-push`) but `pre-commit install` was not run with `-t pre-push`. + +Fix: +```bash +pre-commit install -t pre-commit -t pre-push -t commit-msg +``` + +Or add `default_install_hook_types` to `.pre-commit-config.yaml` and re-run `pre-commit install`. + +## `validate-config` schema error + +Common causes: +- Missing `id` under a hook block +- Missing `rev` under a non-local repo block +- `repo: local` hook missing `language` or `entry` +- Indentation error (valid YAML but invalid pre-commit schema) diff --git a/plugins/kyberforge/skills/pc-run/references/sources.md b/plugins/kyberforge/skills/pc-run/references/sources.md new file mode 100644 index 0000000..5adfb5e --- /dev/null +++ b/plugins/kyberforge/skills/pc-run/references/sources.md @@ -0,0 +1,33 @@ +# Sources + +## context7-pre-commit-com + +- **URL:** context7:/pre-commit/pre-commit.com +- **Description:** Official pre-commit.com documentation — installation, configuration schema, CLI reference, hook authoring, advanced features, troubleshooting +- **Contributing files:** SKILL.md, references/failure-patterns.md +- **Research doc:** plugins/kyberforge/docs/research/docs/pre-commit/sources.md +- **Status:** `extracted` + +## pre-commit-com + +- **URL:** https://pre-commit.com/ +- **Description:** Pre-commit framework homepage — full docs covering install, config, CLI, hook authoring, stages, local hooks, meta hooks, hazmat helpers, CI integration +- **Contributing files:** SKILL.md, references/failure-patterns.md +- **Research doc:** plugins/kyberforge/docs/research/docs/pre-commit/sources.md +- **Status:** `extracted` + +## context7-pre-commit-hooks + +- **URL:** context7:/pre-commit/pre-commit-hooks +- **Description:** Official pre-commit-hooks collection — all available hook IDs with options and examples +- **Contributing files:** (none) +- **Research doc:** plugins/kyberforge/docs/research/docs/pre-commit/sources.md +- **Status:** `extracted` + +## pre-commit-hooks-github + +- **URL:** https://raw.githubusercontent.com/pre-commit/pre-commit-hooks/main/README.md +- **Description:** Official pre-commit-hooks README — complete hook listing with all args, categories, deprecated hooks, and latest version +- **Contributing files:** (none) +- **Research doc:** plugins/kyberforge/docs/research/docs/pre-commit/sources.md +- **Status:** `extracted`