From 9731ce763d8dc2bedec43f1606c56ccaaf9f54d8 Mon Sep 17 00:00:00 2001 From: logosghservice Date: Thu, 21 May 2026 10:18:38 +0000 Subject: [PATCH] Apply convention apm --- .agents/skills/repo-conventions/SKILL.md | 23 ++ .../references/cli-reference.md | 104 +++++++++ .../references/convention-authoring.md | 198 ++++++++++++++++++ .../references/convention-configuration.md | 79 +++++++ .../references/repository-configuration.md | 61 ++++++ apm.lock.yaml | 12 +- 6 files changed, 471 insertions(+), 6 deletions(-) create mode 100644 .agents/skills/repo-conventions/SKILL.md create mode 100644 .agents/skills/repo-conventions/references/cli-reference.md create mode 100644 .agents/skills/repo-conventions/references/convention-authoring.md create mode 100644 .agents/skills/repo-conventions/references/convention-configuration.md create mode 100644 .agents/skills/repo-conventions/references/repository-configuration.md diff --git a/.agents/skills/repo-conventions/SKILL.md b/.agents/skills/repo-conventions/SKILL.md new file mode 100644 index 0000000..73b02b2 --- /dev/null +++ b/.agents/skills/repo-conventions/SKILL.md @@ -0,0 +1,23 @@ +--- +name: repo-conventions +description: Create, update, document, or use RepoConventions repository configurations, convention directories, convention.yml files, convention.ps1 scripts, settings, tests, and supporting files. +--- + +# RepoConventions + +Use this skill when working with RepoConventions configuration, CLI usage, published convention directories, or convention authoring documentation. + +## Agent Instructions + +- Start with the feature page that matches the task, then inspect the current repository files before editing. +- Preserve published convention paths and setting names unless the user explicitly requests a breaking change. +- Keep convention changes coherent: update `convention.yml`, `convention.ps1`, convention-local `README.md`, tests, and supporting files together when the behavior changes. +- Prefer deterministic, idempotent scripts and stable YAML over broad rewrites or formatting-only churn. +- Validate with the narrowest meaningful tests first; for larger convention behavior changes, run the repository's required final test command when practical. + +## Features + +- [**Repository Configuration**](./references/repository-configuration.md) — Configure `.github/conventions.yml`, declare local and remote conventions, pass settings, and configure pull request metadata. +- [**CLI Reference**](./references/cli-reference.md) — Run the `add`, `validate`, and `apply` commands, with path options, pull request options, and clean-repository requirements. +- [**Convention Configuration**](./references/convention-configuration.md) — Learn the shared YAML model for convention references, settings, commit settings, and pull request settings. +- [**Convention Authoring**](./references/convention-authoring.md) — Create idempotent convention directories with `convention.yml`, scripts, local documentation, tests, and child settings expressions. diff --git a/.agents/skills/repo-conventions/references/cli-reference.md b/.agents/skills/repo-conventions/references/cli-reference.md new file mode 100644 index 0000000..b8f8b66 --- /dev/null +++ b/.agents/skills/repo-conventions/references/cli-reference.md @@ -0,0 +1,104 @@ +# CLI Reference + +RepoConventions has three commands: + +```pwsh +dnx repo-conventions add [...] [options] +dnx repo-conventions apply [options] +dnx repo-conventions validate [options] +``` + +## Common Path Options + +| Option | Description | +| --- | --- | +| `--repo ` | Target repository root. Defaults to the current directory. Relative paths are resolved from the current process directory. | +| `--config ` | Conventions configuration file. Defaults to `.github/conventions.yml` under the target repository root. Relative paths are resolved from the current process directory. | +| `--temp ` | Temporary root for RepoConventions-managed transient files. Defaults to the system temp directory. Relative paths are resolved from the current process directory. | + +## Common Pull Request Options + +| Option | Description | +| --- | --- | +| `--open-pr` | Apply conventions, create commits, push a `repo-conventions` branch, and open or update a pull request. | +| `--draft` / `--no-draft` | Override configured draft behavior. These options cannot be used together. | +| `--auto-merge` / `--no-auto-merge` | Override configured auto-merge behavior. These options cannot be used together. | +| `--merge-method ` | Preferred auto-merge method. Must be `merge`, `squash`, or `rebase`. | +| `--git-no-verify` | Pass `--no-verify` to git commit and git push commands run by RepoConventions. | + +## `add` + +`repo-conventions add` appends one or more convention paths to the configuration file. If the file is missing, it creates it. If a path is already present, it leaves the file unchanged for that path. New paths are validated before the configuration file is changed. If settings are required, add them by hand to the configuration file. + +Examples: + +```pwsh +dnx repo-conventions add Faithlife/CodingGuidelines/conventions/dotnet-sdk +dnx repo-conventions add ./conventions/local-policy +dnx repo-conventions add ./conventions/dotnet-sdk ./conventions/github-actions +``` + +`add` requires the target repository path to be a Git repository root. When `--commit`, `--apply`, and `--open-pr` are not used, it can run when the target repository has tracked or untracked file changes. + +Additional `add` options: + +| Option | Description | +| --- | --- | +| `--commit` | Commit newly added convention references. Requires a clean repository. | +| `--apply` | Commit newly added convention references, then apply all conventions. Requires a clean repository. | +| `--open-pr` | Commit newly added convention references, apply all conventions, and open or update a pull request. Requires a clean repository. | + +With `--open-pr`, `add` commits any newly added convention references, applies the resulting configuration, commits convention changes, and opens or updates a pull request: + +```pwsh +dnx repo-conventions add ./conventions/local-policy --open-pr +``` + +## `apply` + +`repo-conventions apply` loads the configuration file, resolves the full convention plan, applies each convention in order, and creates commits for conventions that leave changes behind. + +Examples: + +```pwsh +dnx repo-conventions apply +dnx repo-conventions apply --git-no-verify +``` + +`apply` requires no tracked or untracked file changes in the target repository before it starts. + +When running in GitHub Actions, RepoConventions groups output per convention and appends the final summary line to `GITHUB_STEP_SUMMARY` when that environment variable is available. + +With `--open-pr`, `apply` pushes any convention commits and opens or updates a GitHub pull request: + +```pwsh +dnx repo-conventions apply --open-pr +dnx repo-conventions apply --open-pr --draft +dnx repo-conventions apply --open-pr --auto-merge --merge-method rebase +dnx repo-conventions apply --open-pr --no-auto-merge +``` + +`--open-pr` requires: + +- a non-detached starting branch +- no unpushed commits on the starting branch +- the GitHub CLI `gh` installed and authenticated + +When opening a pull request, RepoConventions creates a branch named `repo-conventions`, `repo-conventions-2`, or the next available suffix. If an open RepoConventions pull request already targets the starting branch, the command updates that pull request instead of opening another one. If the base branch has advanced, the existing PR branch is rebuilt from the current base and force-pushed. + +If applying the conventions produces no commits, RepoConventions returns to the starting branch and does not keep the generated local branch, push a branch, or open a pull request. + +## `validate` + +`repo-conventions validate` loads the configuration file and resolves the complete convention plan without running convention scripts, creating commits, or changing the working tree. + +Examples: + +```pwsh +dnx repo-conventions validate +dnx repo-conventions validate --config .config/repo-conventions.yml +``` + +`validate` requires the target repository path to be a Git repository root. It can run when the target repository has tracked or untracked file changes. + +When validation succeeds, it prints a summary with the number of conventions that were validated. diff --git a/.agents/skills/repo-conventions/references/convention-authoring.md b/.agents/skills/repo-conventions/references/convention-authoring.md new file mode 100644 index 0000000..6eb2fd3 --- /dev/null +++ b/.agents/skills/repo-conventions/references/convention-authoring.md @@ -0,0 +1,198 @@ +# Convention Authoring + +Use this guide when creating or updating convention directories consumed by RepoConventions. + +## Goal + +Produce conventions with stable paths, documented settings, predictable output, and idempotent behavior that matches the RepoConventions execution contract. + +## Authoring Checklist + +- Define the policy boundary first. Prefer one coherent convention over a grab bag of unrelated changes. +- Inspect existing published conventions in the repository before introducing new structure or terminology. +- Choose whether the convention is composite, executable, or both. +- Keep the public surface small: stable path, clearly named settings, predictable outputs. +- Write or update the convention-local `README.md` in the same change. +- Test the non-compliant case, the already-compliant case, and a second successful run for idempotency. + +## Directory Model + +- A published convention directory may contain `convention.yml`, `convention.ps1`, or both. +- If both files exist, RepoConventions applies `convention.yml` first and then executes `convention.ps1`. +- `convention.yml` composes child conventions and can provide commit or pull request settings. +- `convention.ps1` inspects or rewrites the target repository. +- `README.md` documents the convention for consumers. +- Supporting files may be read by the script or by settings expressions. + +Recommended layout: + +```text +conventions/my-convention/ + README.md + convention.yml + convention.ps1 + convention.Tests.ps1 + files/ + supporting-file.txt +``` + +See [Convention Configuration](./convention-configuration.md) for child reference paths, settings values, commit settings, and pull request settings. + +## `convention.yml` + +Use `convention.yml` when a convention composes other conventions, provides default commit settings, provides default pull request settings, or any combination of those. + +Composition-only conventions must include a `conventions` sequence. Executable conventions that also contain `convention.ps1` may omit `conventions` and include only `commit` or `pull-request` settings. + +Example: + +```yaml +commit: + message: Update .NET repository conventions + +pull-request: + labels: + - dependencies + auto-merge: true + merge-method: squash + +conventions: + - path: ../dotnet-sdk + settings: + version: 10 + - path: ../dotnet-slnx +``` + +Guidelines: + +- Keep child conventions in the order they should be applied. +- Use explicit local relative paths, such as `../dotnet-sdk`, for conventions published from the same repository. +- Keep settings JSON-compatible: objects, arrays, strings, numbers, booleans, or null. +- Keep settings shallow unless nesting communicates a real domain boundary. +- Avoid formatting-only churn in generated files unless formatting is the purpose of the convention. + +Supported root properties: + +| Property | Type | Description | +| --- | --- | --- | +| `conventions` | sequence | Child convention references to apply in declaration order. Required when the directory has no `convention.ps1`; optional when the convention is executable. | +| `commit` | object | Default automatic commit settings for this convention and its child conventions. | +| `pull-request` | object | Pull request metadata contributed when this convention creates commits. | + +## Child Settings Expressions + +Composite conventions can map parent settings into child settings with expressions. + +`settings` lookup: + +```yaml +conventions: + - path: ../dotnet-sdk + settings: + version: ${{ settings.sdk.version }} +``` + +- Reads a dotted property path from the parent convention's settings object. +- When the whole value is one expression, preserves JSON-compatible types such as strings, numbers, booleans, arrays, objects, and null. +- When embedded in a larger string, converts strings directly, null to `null`, and arrays or objects to compact JSON. +- Missing values are omitted from object properties and array items. If the missing expression is embedded in a larger string, it contributes an empty string. +- If an array expression is used as an array item, its items are spliced into the destination array. + +`readText("path")`: + +```yaml +conventions: + - path: ../write-file + settings: + body: ${{ readText("./body.txt") }} +``` + +- Reads UTF-8 text from a file. A UTF-8 BOM is ignored. +- Relative paths resolve from the YAML file that contains the expression. +- Paths beginning with `/` resolve from the root of the repository that contains the YAML file. +- Native absolute paths and paths that escape the containing repository are rejected. +- Use it when file-backed text is clearer than embedding long YAML strings. + +## `convention.ps1` + +Use `convention.ps1` when the convention must inspect repository state, run tools, or rewrite files. + +Execution contract: + +- The script runs with `pwsh -NoProfile`. +- The current working directory is the target Git repository root, not the convention directory. +- The first argument is the path to a JSON input file. +- Use `$args[0]` to access the input path so future arguments do not break the script. +- The JSON input file contains a single `settings` property. +- RepoConventions captures stdout and stderr as UTF-8. Set `[Console]::OutputEncoding` before invoking native tools so their output is emitted as UTF-8 too. + +Standard header for `convention.ps1`: + +```pwsh +#requires -PSEdition Core +#requires -Version 7.0 +Set-StrictMode -Version Latest +$ErrorActionPreference = 'Stop' +$utf8 = [System.Text.UTF8Encoding]::new($false) +[Console]::InputEncoding = $utf8 +[Console]::OutputEncoding = $utf8 +$OutputEncoding = $utf8 +``` + +Then, if settings are used: + +```pwsh +$conventionInput = Get-Content -Raw $args[0] | ConvertFrom-Json +$settings = $conventionInput.settings +``` + +Authoring expectations: + +- Read the JSON input only when settings are needed. +- Make the script idempotent. A second successful run should produce no further changes. +- Exit with code zero when the repository is already compliant or after successfully making it compliant. +- Use a non-zero exit code only when the convention genuinely cannot complete. +- Avoid interactive prompts, editor launches, global machine-local state, and hidden credentials. +- Prefer deterministic file writes, stable ordering, and stable line endings. +- Emit focused output that explains what changed or why the convention cannot continue. +- If the convention naturally consists of multiple meaningful steps, the script may create its own commits with informative messages. + +## Commit and Failure Behavior + +- On success, if `convention.ps1` leaves tracked or untracked changes and does not create commits itself, RepoConventions creates an automatic commit using the effective `commit.message`, or `Apply convention ` when no message is configured. +- If the script creates commits itself, RepoConventions preserves those commits. +- If the convention leaves no changes or new commits, RepoConventions does not add a commit for that convention. +- If the script exits with a non-zero code, RepoConventions hard-resets the target repository to the commit before that convention started and stops the run. +- RepoConventions builds the convention plan before applying any convention, so path and settings-expression errors prevent partial application. + +## Documentation + +Always include a `README.md` in the convention directory. Document: + +- what the convention does +- every supported setting, including defaults and examples +- required tools, frameworks, or repository assumptions +- notable files the convention creates, rewrites, or commits +- any important limitations or follow-up steps for consumers + +Keep repository-level consumer docs focused on using RepoConventions. + +## Testing + +- Test the convention with Pester if possible. +- Put Pester tests in the same directory as the convention they cover, e.g. `conventions/my-convention/convention.Tests.ps1`. +- Prefer new temporary repositories with no preexisting tracked or untracked file changes so tests exercise real files, git state, and command behavior. +- Test both an already-compliant repository and a non-compliant repository. +- Re-run after the first successful application to confirm idempotency. +- If the convention has settings, exercise at least one non-default settings case. +- Test failure paths when settings are required or external tools may be unavailable. + +## Agent Workflow + +When an AI agent updates a convention: + +- Read the existing convention directory and nearby conventions first. +- Preserve the published path and setting names unless the user explicitly requests a breaking change. +- Update `convention.yml`, `convention.ps1`, local docs, and tests as one coherent change. +- Prefer small, deterministic scripts over broad repository rewrites. +- Validate by running the narrowest meaningful tests, then the repository's required final test command when appropriate. diff --git a/.agents/skills/repo-conventions/references/convention-configuration.md b/.agents/skills/repo-conventions/references/convention-configuration.md new file mode 100644 index 0000000..8e904e7 --- /dev/null +++ b/.agents/skills/repo-conventions/references/convention-configuration.md @@ -0,0 +1,79 @@ +# Convention Configuration + +RepoConventions uses the same convention reference model in repository configuration and in convention-local `convention.yml` files. This page covers the YAML elements used by repository consumers and convention authors: references, settings, commit settings, and pull request settings. + +## Convention References + +Each convention reference must contain a non-empty `path`. It may also contain `settings`, `commit`, and `pull-request`. + +`path` identifies a convention directory. Each convention should document its own settings, behavior, and required tools. + +Supported path forms: + +| Form | Meaning | +| --- | --- | +| `owner/repo/path@ref` | Clone a GitHub repository and use `path` inside it. `path` may be omitted to use the repository root. `@ref` may be omitted to use the default branch. | +| `./relative/path` | Resolve relative to the YAML file that contains the reference. | +| `../relative/path` | Resolve relative to the YAML file that contains the reference. The result must stay inside that YAML file's repository. | +| `/root/relative/path` | Resolve from the root of the repository that contains the YAML file. | + +Local paths must stay inside the repository that contains the YAML file. This rule applies to conventions checked into the target repository and to convention repositories cloned from GitHub. + +`settings` is passed to the convention as JSON-compatible data. Use YAML objects, arrays, strings, numbers, booleans, or null values. Each convention documents the settings it accepts. + +## Commit Settings + +Commit settings control the automatic commit created when `convention.ps1` leaves uncommitted changes and does not create commits itself. + +Supported properties: + +| Property | Type | Description | +| --- | --- | --- | +| `message` | string | Commit message for the automatic commit. Empty or whitespace-only values are treated as unspecified. | + +Behavior: + +- If no message is configured, RepoConventions uses `Apply convention `. +- A convention reference's `commit` settings override the convention's own defaults. +- Composite conventions pass the effective commit message down to child conventions. A child convention's own `commit` settings, or settings on that child reference, can override the inherited message. +- Commit settings do not affect commits created directly by `convention.ps1`. +- When adjacent automatic commits in the same run use the same message, RepoConventions amends the previous automatic commit instead of creating a second adjacent commit with the same message. + +Use a custom `message` when the convention has a stable, recognizable purpose. Prefer a concise imperative subject, such as `Update .NET SDK version` or `Refresh generated CI files`. + +## Pull Request Settings + +Pull request settings describe metadata for the pull request generated from applying conventions. This metadata is used when the command runs with `--open-pr`. + +Supported properties: + +| Property | Type | Description | +| --- | --- | --- | +| `labels` | string sequence | Labels to add to the generated pull request. Missing labels are created automatically. The `repo-conventions` label is always added. | +| `reviewers` | string sequence | GitHub users or teams to request as reviewers. | +| `assignees` | string sequence | GitHub users to assign. | +| `draft` | boolean | When true, create the pull request as a draft. | +| `auto-merge` | boolean | When true, enable GitHub auto-merge after opening the pull request. | +| `merge-method` | string | Preferred auto-merge method: `merge`, `squash`, or `rebase`. Defaults to `squash` when auto-merge is enabled and no single method is configured. | + +Pull request settings can appear at three levels: + +- Top-level repository `pull-request` settings apply to the whole generated pull request. +- A convention reference's `pull-request` settings apply only if that convention contributes commits to the generated pull request. +- A convention's own `convention.yml` can provide default `pull-request` settings for that convention, whether the convention is stored in the target repository or cloned from a remote repository. + +Merge behavior: + +- `labels`, `reviewers`, and `assignees` are appended, then de-duplicated case-insensitively. +- `draft`, `auto-merge`, and `merge-method` are scalar settings; reference-level settings override convention defaults. +- Convention-level pull request metadata is ignored when the convention does not create commits. +- When auto-merge is enabled, reviewers and assignees are not requested. +- If multiple contributing conventions request conflicting merge methods and no repository-level or reference-level setting resolves the conflict, RepoConventions falls back to `squash`. + +CLI flags override configured pull request settings for a single run: + +- `--draft` and `--no-draft` override `draft`. +- `--auto-merge` and `--no-auto-merge` override `auto-merge`. +- `--merge-method merge|squash|rebase` overrides `merge-method`. + +If a requested merge method is disabled or rejected by GitHub, RepoConventions tries other allowed methods, preferring `squash` as the first fallback. If auto-merge was enabled by configuration and cannot be enabled, the command reports the failure but still succeeds. If `--auto-merge` was provided explicitly and auto-merge cannot be enabled, the command fails. diff --git a/.agents/skills/repo-conventions/references/repository-configuration.md b/.agents/skills/repo-conventions/references/repository-configuration.md new file mode 100644 index 0000000..2cae273 --- /dev/null +++ b/.agents/skills/repo-conventions/references/repository-configuration.md @@ -0,0 +1,61 @@ +# Repository Configuration + +RepoConventions reads `.github/conventions.yml` from the target repository root by default. The file declares the conventions to apply to the repository and optional pull request metadata for `--open-pr` runs. + +## Top-Level Properties + +| Property | Required | Description | +| --- | --- | --- | +| `conventions` | Yes | Sequence of convention references, applied in declaration order. | +| `pull-request` | No | Pull request settings for the generated pull request. | + +Complete example: + +```yaml +conventions: + - path: Faithlife/CodingGuidelines/conventions/dotnet-sdk + settings: + version: 10 + - path: ./conventions/local-policy + commit: + message: Update local policy files + pull-request: + labels: + - dependencies + auto-merge: false + +pull-request: + labels: + - automation + reviewers: + - octocat + merge-method: squash +``` + +## Convention References + +Each item in `conventions` must contain a non-empty `path`. It may also contain `settings`, `commit`, and `pull-request`. + +Use `settings` to pass JSON-compatible data to a convention: objects, arrays, strings, numbers, booleans, or null values. Top-level repository configuration uses literal settings values. + +See [Convention Configuration](./convention-configuration.md) for reference path forms, settings behavior, commit settings, and reference-level pull request settings. + +See [Convention Authoring](./convention-authoring.md) for composite conventions and child settings expressions. + +## Pull Request Settings + +Top-level `pull-request` settings apply to the generated pull request when the command runs with `--open-pr`. Convention references and convention directories can also contribute pull request settings when they create commits. + +List values such as `labels`, `reviewers`, and `assignees` are appended and de-duplicated case-insensitively. Scalar values such as `draft`, `auto-merge`, and `merge-method` can be overridden by reference-level settings or CLI flags. + +See [Convention Configuration](./convention-configuration.md#pull-request-settings) for the full pull request settings table and merge behavior. + +## Validation + +Run validation after editing repository configuration: + +```pwsh +dnx repo-conventions validate +``` + +Validation loads the configuration file and resolves the complete convention plan without running convention scripts, creating commits, or changing the working tree. diff --git a/apm.lock.yaml b/apm.lock.yaml index edb6ed4..83606ad 100644 --- a/apm.lock.yaml +++ b/apm.lock.yaml @@ -1,13 +1,13 @@ lockfile_version: '1' -generated_at: '2026-05-14T21:36:31.700582+00:00' -apm_version: 0.13.0 +generated_at: '2026-05-21T10:18:36.432445+00:00' +apm_version: 0.14.0 dependencies: - repo_url: Faithlife/RepoConventions host: github.com - resolved_commit: 30c7ec805d4c6fe24478bf808e771b79b3899e79 - virtual_path: skills/create-repo-conventions + resolved_commit: b5f984f28aaf59004f73b06a28cc4f2d4d45ebb6 + virtual_path: skills/repo-conventions is_virtual: true package_type: claude_skill deployed_files: - - .agents/skills/create-repo-conventions - content_hash: sha256:a9c5c1e5380bd467a3dc070ebdc4828808a6a9eedb2a292dc2068ff8f05dbeac + - .agents/skills/repo-conventions + content_hash: sha256:f5667d3131f68fe794c6c1897ed066c1ec28d180b16c9f82b5018fa3286a590b