diff --git a/docs/architecture.md b/docs/architecture.md index c0d63d7..62e25c9 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -124,7 +124,7 @@ Repository indexing metadata is declared in `x-personal-mcp`: 3. tags 4. capabilities 5. depends_on -6. references map (ref id to relative path and optional metadata) +6. optional references map (for nested entries, overrides, and aliases) No `metadata.yaml` sidecar is part of the end-state contract. @@ -143,7 +143,9 @@ For the full URI semantics, parameter validation rules, and compatibility policy Validation rules: 1. `skill_id` is lowercase kebab-case and must satisfy the stable skill id contract. -2. `ref_id` is lowercase kebab-case and must be declared in the skill references manifest. +2. `ref_id` is lowercase kebab-case and must resolve from either: + - top-level auto-discovery of `references/*.md` filename stems, or + - an explicit `x-personal-mcp.references` entry. 3. `path*` resolves only to normalized markdown paths under `docs/`. ### Resource Registration Contract diff --git a/docs/content.md b/docs/content.md index 3b8063f..c65640a 100644 --- a/docs/content.md +++ b/docs/content.md @@ -43,7 +43,7 @@ Rules: 1. Skill metadata is embedded in YAML frontmatter in `SKILL.md`. 2. No `metadata.yaml` sidecar exists in the end state. -3. Reference lookup metadata, including reference id to relative path mappings, is declared from `SKILL.md` frontmatter rather than inferred as a hidden global convention. +3. Reference lookup metadata is documented and explicit: top-level `references/*.md` are auto-discovered from filenames, while `SKILL.md` frontmatter declares overrides and nested mappings when needed. ## Skill Id Contract diff --git a/docs/frontmatter.md b/docs/frontmatter.md index 6124750..d95ff00 100644 --- a/docs/frontmatter.md +++ b/docs/frontmatter.md @@ -107,6 +107,28 @@ Reference entry rules: 6. `title` is an optional display label. 7. Renaming `ref-id` values is allowed when needed; optional aliases may be used during transitions. +## Auto-Generated Reference IDs + +Top-level markdown files directly under `references/` are auto-registered as MCP references even when `x-personal-mcp.references` is empty. + +How `ref-id` is derived: + +1. Start from the filename stem (without `.md`). +2. Normalize to lowercase kebab-case. +3. Publish at `resource://skills//references/`. + +Examples: + +1. `references/ruff-docs.md` -> `ref-id: ruff-docs` +2. `references/Ruff Integrations.md` -> `ref-id: ruff-integrations` +3. `references/python_logging_docs.md` -> `ref-id: python-logging-docs` + +When to use explicit `x-personal-mcp.references` entries: + +1. The file is nested, for example `references/guides/ci.md`. +2. You need to override defaults (`title`, `mime_type`, or custom `ref-id`). +3. You need compatibility aliases during a rename. + ## Validation Models The normative model uses Pydantic v2 with change-friendly validation: diff --git a/docs/skills/new-skill/SKILL.md b/docs/skills/new-skill/SKILL.md index 172a2a3..caa3e24 100644 --- a/docs/skills/new-skill/SKILL.md +++ b/docs/skills/new-skill/SKILL.md @@ -19,14 +19,15 @@ x-personal-mcp: # New Skill Bootstrap -Use this skill to bootstrap a new skill in the docs-first architecture. +Use this skill to bootstrap a new skill in the docs-first architecture. Try to use the `/create-skill` where possible to structure the output, but place it alongside the other skills in this repo. ## Scope 1. Create docs under docs/skills//. 2. Define SKILL frontmatter with Anthropic and x-personal-mcp fields. -3. Declare references via x-personal-mcp.references when needed. -4. Validate the docs build and MCP resource reads. +3. Treat top-level `references/*.md` as auto-discovered references with `ref-id` generated from filename. +4. Declare `x-personal-mcp.references` only when you need overrides or nested `references/**` entries. +5. Validate the docs build and MCP resource reads. ## Authoring Checklist @@ -35,6 +36,8 @@ Use this skill to bootstrap a new skill in the docs-first architecture. 3. Keep skill id and directory name aligned. 4. Keep frontmatter name equal to x-personal-mcp.id. 5. Include resource://skills//document in capabilities. +6. For each top-level `references/.md`, expect `resource://skills//references/` (normalized to lowercase kebab-case). +7. Add explicit `x-personal-mcp.references` entries only for nested paths or metadata overrides. ## Validation diff --git a/docs/skills/ruff-linting-formating/SKILL.md b/docs/skills/ruff-linting-formating/SKILL.md new file mode 100644 index 0000000..049ae03 --- /dev/null +++ b/docs/skills/ruff-linting-formating/SKILL.md @@ -0,0 +1,121 @@ +--- +name: ruff-linting-formating +description: "Reference-first Ruff skill for repository preferences, baseline defaults, and source links. Use to pick consistent Ruff conventions and integration references, not to run migration playbooks." +argument-hint: "Which Ruff preferences or integrations are you deciding (rules, formatting, pre-commit, GitHub Actions)?" +x-personal-mcp: + id: ruff-linting-formating + version: 1.0.0 + tags: + - ruff + - linting + - formatting + - python + - ci + capabilities: + - resource://skills/ruff-linting-formating/document + depends_on: [] +--- + +# Ruff Preferences and References + +Use this skill as a reference index for Ruff preferences, conventions, and source documentation. + +This document is intentionally not a migration or transition playbook. + +Load references only when needed: +- Ruff core documentation: [Ruff docs](./references/ruff-docs.md) +- Tooling integrations (pre-commit and GitHub Actions): [Ruff integrations](./references/ruff-integrations.md) + +## When To Use + +- You want canonical Ruff preferences for this repository context. +- You need source links for rule selection, formatter behavior, and integrations. +- You are deciding configuration defaults, not planning a migration sequence. + +## Preference Baseline + +Use these as default preferences unless the target repository states otherwise: + +1. Keep linting and formatting both enabled. +2. Keep imports sorted via Ruff (`I` rules) rather than a separate import tool. +3. Prefer explicit, small rule-family selection first (`E`, `F`, `I`, `UP`) and expand deliberately. +4. Keep line length, target Python, and formatter settings aligned to repository policy. +5. Keep local and CI execution behavior equivalent. + +### Rule Link Requirement + +When adding a specific rule or ruleset to `ruff.toml`, search for the authoritative Ruff documentation page for that rule or ruleset and include a link to it. You may add the URL as a nearby comment in `ruff.toml` or record it in the repository docs (for example in a CONTRIBUTING or linting section). Prefer links to the official [Ruff rules reference](https://docs.astral.sh/ruff/rules/). + +### Version Discovery Requirement + +When integrating Ruff or any third-party Action for the first time, always search for the latest stable release of: + +- the `ruff` package ([releases](https://github.com/astral-sh/ruff/releases)) +- the `astral-sh/ruff-pre-commit` hook ([releases](https://github.com/astral-sh/ruff-pre-commit/releases)) +- the `astral-sh/ruff-action` ([releases](https://github.com/astral-sh/ruff-action/releases)) +- the `astral-sh/setup-uv` action ([releases](https://github.com/astral-sh/setup-uv/releases)) + +Document the version you chose in the example snippet or in a nearby docs file and prefer pinning to a released tag in CI examples. If you intentionally use `latest`, note the reason and the associated risk in repo docs. + +## Decision Inputs + +Collect only the minimum context needed for preference decisions: + +1. Supported Python versions. +2. Existing `pyproject.toml` constraints. +3. CI provider and required checks. +4. Whether pre-commit is in use. + +## Template + +[Full template ruff.toml](https://gitea.john-stream.com/john/python-template/src/branch/main/project/ruff.toml) + +```toml title="Preferred Baseline" +line-length = 120 +indent-width = 4 +target-version = "py313" + +exclude = [ + ".git", + ".venv", + ".devenv", +] + +[lint] +extend-fixable = ["ALL"] +extend-select = [ + "C4", # https://docs.astral.sh/ruff/rules/#flake8-comprehensions-c4 + "E", "W", # https://docs.astral.sh/ruff/rules/#pycodestyle-e-w + "F", # https://docs.astral.sh/ruff/rules/#pyflakes-f + "FURB", # https://docs.astral.sh/ruff/rules/#refurb-furb + "I", # https://docs.astral.sh/ruff/rules/#isort-i + "N", # https://docs.astral.sh/ruff/rules/#pep8-naming-n + "PD", # https://docs.astral.sh/ruff/rules/#pandas-vet-pd + "PTH", # https://docs.astral.sh/ruff/rules/#flake8-use-pathlib-pth + "UP", # https://docs.astral.sh/ruff/rules/#pyupgrade-up + "SIM", # https://docs.astral.sh/ruff/rules/#flake8-simplify-sim +] + +[lint.isort] +force-single-line = true + +[format] +quote-style = "double" +indent-style = "space" +skip-magic-trailing-comma = false +line-ending = "auto" +``` + +## Reference Map + +1. Rules and settings source of truth: [Ruff docs](./references/ruff-docs.md) +2. pre-commit and GitHub Actions examples: [Ruff integrations](./references/ruff-integrations.md) +3. Template to copy from or compare against: [python-template ruff.toml](https://gitea.john-stream.com/john/python-template/src/branch/main/project/ruff.toml) + +## Non-Goals + +This skill does not define: + +1. Step-by-step migration phases. +2. Rollout modes or cutover timelines. +3. Mechanical rewrite plans for legacy tooling. \ No newline at end of file diff --git a/docs/skills/ruff-linting-formating/references/ruff-docs.md b/docs/skills/ruff-linting-formating/references/ruff-docs.md new file mode 100644 index 0000000..f21c187 --- /dev/null +++ b/docs/skills/ruff-linting-formating/references/ruff-docs.md @@ -0,0 +1,31 @@ +# Ruff Source Documentation + +Use this reference when implementing or tuning Ruff in repositories. + +## Core Docs + +- [Ruff overview](https://docs.astral.sh/ruff/) +- [Rules reference](https://docs.astral.sh/ruff/rules/) +- [Settings reference](https://docs.astral.sh/ruff/settings/) +- [Formatter docs](https://docs.astral.sh/ruff/formatter/) +- [The Ruff linter](https://docs.astral.sh/ruff/linter/) + +## Migration And Integration + +- [Migrating from Black](https://docs.astral.sh/ruff/formatter/#migrating-from-black) +- [Migrating from Flake8](https://docs.astral.sh/ruff/linter/#migrating-from-flake8) +- [Migrating from isort](https://docs.astral.sh/ruff/formatter/#sorting-imports) +- [Pre-commit integration](https://docs.astral.sh/ruff/integrations/#pre-commit) +- [GitHub Actions integration](https://docs.astral.sh/ruff/integrations/#github-actions) + +## Python Packaging Context + +- [PEP 621 project metadata in pyproject.toml](https://peps.python.org/pep-0621/) +- [uv project and workflow docs](https://docs.astral.sh/uv/) + +## Suggested Reading Order + +1. Overview and settings. +2. Rules and linter behavior. +3. Formatter and migration references. +4. CI and pre-commit integration notes. \ No newline at end of file diff --git a/docs/skills/ruff-linting-formating/references/ruff-integrations.md b/docs/skills/ruff-linting-formating/references/ruff-integrations.md new file mode 100644 index 0000000..cb9b9f0 --- /dev/null +++ b/docs/skills/ruff-linting-formating/references/ruff-integrations.md @@ -0,0 +1,128 @@ +# Ruff Integrations: Tooling Patterns + +Use this page when wiring Ruff into local developer workflows and CI. + +## Scope + +This reference covers: + +1. [pre-commit](https://pre-commit.com/) hooks for local and pre-push enforcement. +2. [GitHub Actions](https://docs.github.com/en/actions) checks for pull request and branch protection gates. + +For Ruff-specific flags and settings, see [Ruff docs](./ruff-docs.md). + +## pre-commit Integration + +### Why use it + +Use pre-commit when you want fast feedback before code reaches CI and consistent checks across contributors. + +### Add hooks + +Create or update [.pre-commit-config.yaml](https://pre-commit.com/#2-add-a-pre-commit-configuration) with Ruff hooks from [astral-sh/ruff-pre-commit](https://github.com/astral-sh/ruff-pre-commit): + +```yaml title=".pre-commit-config.yaml" +repos: + - repo: https://github.com/astral-sh/ruff-pre-commit + rev: v0.15.18 + hooks: + - id: ruff-check + args: [--fix] + - id: ruff-format +``` + +Pin the hook revision and update intentionally during dependency maintenance. + +### Install and run + +```bash +uv run pre-commit install +uv run pre-commit run --all-files +``` + +If the project does not manage pre-commit via uv, use your standard Python environment installation path. + +### Recommended policy + +1. Keep auto-fix enabled locally with ruff-check --fix. +2. Keep CI in check-only mode so violations fail loudly. +3. Run hooks on all files in migration PRs to avoid drift. + +## GitHub Actions Integration + +### Why use it + +Use GitHub Actions when you need required status checks on pull requests and a single source of truth for lint and format gates. + +### Minimal workflow + +Create [.github/workflows/ruff.yml](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions): + +```yaml title=".github/workflows/ruff.yml" +name: Ruff + +on: + pull_request: + push: + branches: [main] + +jobs: + ruff: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Install uv + uses: astral-sh/setup-uv@v8.2.0 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Install project dependencies + run: uv sync --dev + + - name: Ruff lint + run: uv run ruff check . + + - name: Ruff format check + run: uv run ruff format --check . +``` + +### Alternative: official Ruff action + +If you want an action-focused setup, see [Ruff GitHub Actions integration](https://docs.astral.sh/ruff/integrations/#github-actions). The official Ruff action is commonly used pinned at `astral-sh/ruff-action@v4.0.0`. Keep behavior equivalent to local commands so results do not diverge. + +## Alignment Checklist + +Keep local hooks and CI checks aligned: + +1. Same rule set from pyproject.toml. +2. Same target Python version and dependency graph. +3. Clear developer remediation command in docs: + - uv run ruff check . --fix + - uv run ruff format . + +## Troubleshooting + +### Hook passes locally but CI fails + +1. Ensure CI uses the same pyproject.toml and not a stale cache. +2. Confirm matching Ruff versions in local and CI environments. +3. Verify CI is not running on a different Python target than local config. + +### CI is slow + +1. Keep Ruff in a dedicated job so failures return early. +2. Use dependency caching from your package workflow. +3. Avoid running both legacy linters and Ruff after migration completion. + +## Source Links + +- [Ruff integrations](https://docs.astral.sh/ruff/integrations/) +- [Ruff pre-commit docs](https://docs.astral.sh/ruff/integrations/#pre-commit) +- [Ruff GitHub Actions docs](https://docs.astral.sh/ruff/integrations/#github-actions) +- [pre-commit official docs](https://pre-commit.com/) +- [GitHub Actions documentation](https://docs.github.com/en/actions) \ No newline at end of file diff --git a/zensical.toml b/zensical.toml index e4adb1a..e53569e 100644 --- a/zensical.toml +++ b/zensical.toml @@ -108,6 +108,11 @@ nav = [ { "Overview" = "skills/python-logging-dictconfig/SKILL.md" }, { "Docs" = "skills/python-logging-dictconfig/references/python-logging-docs.md" }, ] }, + { "Ruff" = [ + { "Overview" = "skills/ruff-linting-formating/SKILL.md" }, + { "Docs" = "skills/ruff-linting-formating/references/ruff-docs.md" }, + { "Integrations" = "skills/ruff-linting-formating/references/ruff-integrations.md" }, + ] }, { "Zensical" = [ { "Overview" = "skills/zensical-docs/SKILL.md" }, { "Map" = "skills/zensical-docs/references/index.md" },