git 4.3.2 → 5.0.0.beta.1

data/.github/skills/facade-yard-documentation/SKILL.md

@@ -0,0 +1,429 @@
+---
+name: facade-yard-documentation
+description: "Facade-specific YARD documentation rules for Git::Repository::* topic modules and their facade methods, overriding and extending the general yard-documentation skill. Use when writing or reviewing YARD docs for facade modules under lib/git/repository/."
+---
+
+# Facade YARD Documentation
+
+Write and verify YARD documentation for facade modules and methods on
+`Git::Repository::*`. This skill overrides and extends the general
+[YARD Documentation](../yard-documentation/SKILL.md) skill with facade-specific
+rules.
+
+The facade is the **public API surface** of the gem. Facade docs describe what
+the caller passes and what they get back — never the internal command class,
+parser, or execution context that implements the behavior.
+
+## Contents
+
+- [Related skills](#related-skills)
+- [Input](#input)
+- [Reference](#reference)
+  - [Module-level docs](#module-level-docs)
+  - [Method-level docs](#method-level-docs)
+  - [Documenting forwarded options with `@overload`](#documenting-forwarded-options-with-overload)
+  - [Return type rules](#return-type-rules)
+  - [`@raise` rules](#raise-rules)
+  - [Cross-referencing the implementation](#cross-referencing-the-implementation)
+  - [Common issues](#common-issues)
+- [Workflow](#workflow)
+- [Output](#output)
+
+## Related skills
+
+- [YARD Documentation](../yard-documentation/SKILL.md) — authoritative source for
+  general YARD formatting rules; **must be loaded** as a prerequisite
+- [Facade Implementation](../facade-implementation/SKILL.md) — facade module
+  structure and orchestration patterns
+- [Facade Test Conventions](../facade-test-conventions/SKILL.md) — unit and
+  integration test conventions for facade methods
+- [Command YARD Documentation](../command-yard-documentation/SKILL.md) — sibling
+  skill for the underlying command classes (different rules — facade docs do
+  **not** mirror command DSL)
+
+## Input
+
+Before starting, you **MUST** load the following skill(s) in their entirety:
+
+- [YARD Documentation](../yard-documentation/SKILL.md) — authoritative source for
+  YARD formatting rules and writing standards
+
+Then gather:
+
+1. **Facade module source** — `lib/git/repository/<topic>.rb`
+2. **Underlying command class(es)** — `lib/git/commands/<command>.rb` for each
+   command the facade method calls. Use these to confirm option semantics, but
+   do **not** copy the command's `@option` docs verbatim — the facade only
+   exposes the options it documents in its public contract.
+3. **Underlying parser/result class** — when the facade returns a structured
+   value, read the parser or result class to confirm the documented return type.
+
+## Reference
+
+### Module-level docs
+
+Every facade module under `lib/git/repository/` requires a module-level YARD
+block:
+
+```ruby
+module Git
+  class Repository
+    # Short summary of the topic and the facade methods it provides
+    #
+    # Included by {Git::Repository}.
+    #
+    # @api public
+    #
+    module Topic
+      # ...
+    end
+  end
+end
+```
+
+Module-level tags appear in the order required by
+[YARD Documentation — Modules](../yard-documentation/SKILL.md#element-specific-rules):
+`@note`, `@deprecated`, `@see`, `@api`. (Facade modules do not use module-level
+`@example` — see the override note below.)
+
+Required tags:
+
+- [ ] short summary describing the topic (e.g. "Facade methods for staging-area
+  operations: adding and resetting files") — follows the short-description
+  rules in [YARD Documentation](../yard-documentation/SKILL.md)
+- [ ] sentence noting "Included by {Git::Repository}." with the YARD link
+- [ ] `@api public` — every facade module is part of the public API
+
+Do **not** add:
+
+- `@see Git::Commands::*` at the module level — implementation detail
+- `@see https://git-scm.com/docs/...` at the module level — git man-page
+  links belong on the individual facade methods, where the link maps directly
+  to the command being invoked. A module typically groups several facade
+  methods (sometimes spanning multiple git commands), so a single module-level
+  link is misleading; for single-command modules it is redundant with the
+  method-level link.
+- `@example` blocks at the module level — **facade-specific override of
+  [YARD Documentation — Modules](../yard-documentation/SKILL.md#element-specific-rules)**,
+  which permits module-level `@example` when a module provides standalone
+  methods. Facade modules do provide standalone methods, but every facade
+  method already carries its own `@example`, so a module-level example would
+  be redundant. Examples belong on the methods.
+
+### Method-level docs
+
+Every facade method requires full YARD docs. Two acceptable forms:
+
+**Form A — `@overload` with anonymous splat in the `def`** (the **default**
+for any method that forwards positional args and/or keyword options unchanged
+to the underlying command). The `def` uses an anonymous splat — `**`, `*`, or
+`...` — to satisfy RuboCop's `Style/ArgumentsForwarding` cop, and the
+`@overload` block introduces named parameters that `@param` and `@option` bind
+to:
+
+```ruby
+# Update the index with the current content found in the working tree
+#
+# @overload add(paths = '.', **options)
+#
+#   @example Stage all changed files
+#     repo.add
+#
+#   @example Stage a specific file
+#     repo.add('README.md')
+#
+#   @param paths [String, Array<String>] a file or files to add (relative to
+#     the worktree root); defaults to `'.'` (all files)
+#
+#   @param options [Hash] options for the add command
+#
+#   @option options [Boolean, nil] :all (nil) add, modify, and remove index
+#     entries to match the worktree
+#
+#   @option options [Boolean, nil] :force (nil) allow adding otherwise ignored
+#     files
+#
+#   @return [String] git's stdout from the add
+#
+# @raise [ArgumentError] if unsupported options are provided
+#
+# @raise [Git::FailedError] if `git add` exits with a non-zero status
+#
+def add(paths = '.', **)
+  Git::Repository::Internal.assert_valid_opts!(ADD_ALLOWED_OPTS, **)
+  Git::Commands::Add.new(@execution_context).call(*Array(paths), **).stdout
+end
+```
+
+See [Documenting forwarded options with
+`@overload`](#documenting-forwarded-options-with-overload) for the rationale
+and variations (`*`, `...`, multiple call shapes).
+
+**Form B — direct doc comment on a fully named signature** (the **narrow
+exception**: use only when the method body must inspect or mutate the options
+hash before forwarding it, or when the signature has no splat at all). When
+the `def` has a named parameter for every documented argument, `@param` and
+`@option` bind directly:
+
+```ruby
+# Commit staged changes
+#
+# @example Commit with a message
+#   repo.commit('Initial commit')
+#
+# @example Amend the previous commit
+#   repo.commit('Updated message', amend: true)
+#
+# @param message [String] the commit message
+#
+# @param opts [Hash] commit options
+#
+# @option opts [Boolean, nil] :amend (nil) amend the previous commit
+#
+# @return [String] git's stdout from the commit
+#
+# @raise [ArgumentError] if unsupported options are provided
+#
+# @raise [Git::FailedError] if `git commit` exits with a non-zero status
+#
+def commit(message, opts = {})
+  Git::Repository::Internal.assert_valid_opts!(COMMIT_ALLOWED_OPTS, **opts)
+  opts = opts.merge(message: message) if message
+  Git::Commands::Commit.new(@execution_context).call(no_edit: true, **opts).stdout
+end
+```
+
+Form B is required here because the method body needs a named variable (`opts`)
+to build and transform before forwarding — e.g. `opts.merge(message: message)`
+returns a new hash that is assigned back, and `opts = deprecate_commit_no_gpg_sign_option(opts)`
+reassigns it; an anonymous `**` in the `def` provides no named variable to
+operate on.
+
+When a method has multiple genuinely distinct call shapes (e.g.
+`commit(message)` vs. `commit(message, opts)` with materially different
+return types), use one `@overload` block per shape — see
+[YARD Documentation — Overload
+template](../yard-documentation/SKILL.md#overload-template).
+
+Required elements (apply to both forms):
+
+- [ ] one-line summary describing what the method does from the caller's
+  perspective (not "calls `Git::Commands::Foo`")
+- [ ] at least one `@example` block with a descriptive title (required on every
+  public facade method; use representative input and show the return value)
+- [ ] `@param` for every positional parameter, with type and short description
+- [ ] `@param <name> [Hash]` preceding any `@option` tags — the name comes
+  from the `@overload` signature (e.g. `options` or `opts`) when the actual
+  `def` uses anonymous `**` for `Style/ArgumentsForwarding`; otherwise it
+  matches the named parameter on the `def` itself
+- [ ] `@option` for every option the facade exposes (the caller-facing contract,
+  not every option the underlying command accepts)
+- [ ] `@return` with the **documented public return type** (see [Return type
+  rules](#return-type-rules))
+- [ ] `@raise` for every error the caller can hit (see [`@raise`
+  rules](#raise-rules))
+
+### Documenting forwarded options with `@overload`
+
+When a facade method forwards positional args and/or keyword options unchanged
+to the underlying command, keep the anonymous splat (`**`, `*`, or `...`) in
+the `def` (so `Style/ArgumentsForwarding` stays satisfied) and document the
+call shape with an `@overload` block that names the parameters — Form A in
+[Method-level docs](#method-level-docs) above shows the canonical `add`
+example.
+
+Key constraints:
+
+- **Do not** name the splat — or expand `...` into `*args, **kwargs, &block` —
+  solely to make `@param`/`@option` bind. **Do not** suppress
+  `Style/ArgumentsForwarding` with `# rubocop:disable`. The `@overload` form is
+  the project-standard resolution.
+- The `@overload` signature owns the parameter names; `@param`, `@option`,
+  `@yield`, and `@yieldparam` tags inside the overload bind to those names.
+- When a facade method has multiple distinct call shapes (e.g.
+  `commit(message)` vs. `commit(message, **opts)`), write one `@overload`
+  block per shape.
+- Form B (named splat, direct doc comment) is the narrow exception — use only
+  when the body inspects or mutates the options hash before forwarding it.
+- The **anonymous block parameter (`&`)** is not covered by this rule.
+  `@yield`/`@yieldparam`/`@yieldreturn` describe what is yielded rather than
+  the block parameter itself, so anonymous `&` is fine. Name the block
+  (`&block`) only when documenting it as a first-class `Proc` value.
+
+See the general
+[YARD Documentation — Documenting anonymous splats with `@overload`](../yard-documentation/SKILL.md#documenting-anonymous-splats-with-overload)
+for the underlying rule.
+
+Decision rules for facade methods:
+
+- Use `@overload` when the method uses anonymous `*`, `**`, or `...`
+- Use `@overload` when call shapes differ meaningfully (different params and/or
+  return contracts)
+- Skip `@overload` only when a single named signature fully describes the API
+
+When using `@overload`, place tags as follows:
+
+- Put `@param`, `@option`, and `@return` in overload blocks
+- Put overload-specific `@raise` only in the relevant overload block
+- Put shared `@raise` once at top level
+- Do not duplicate the same `@raise` at both levels
+
+### Return type rules
+
+The `@return` annotation must reflect the **public contract** of the facade
+method, not the type of the underlying call expression.
+
+| Facade does | `@return` type |
+| --- | --- |
+| Returns the raw `CommandLineResult` | `[Git::CommandLineResult]` |
+| Returns `result.stdout` (chomped or raw) | `[String]` |
+| Returns parsed structured data via a parser | The parser's return type (e.g. `[Array<Git::BranchInfo>]`, `[Hash]`) |
+| Returns a result-class instance via a factory | The result class (e.g. `[Git::BranchDeleteResult]`) |
+| Returns a single Boolean derived from the result | `[Boolean]` |
+
+Never write `@return [Git::Commands::Foo::Result]` — command-class result types
+are internal. Surface `Git::CommandLineResult` only when the topic module's
+documented contract is to expose raw results.
+
+### `@raise` rules
+
+- Always include `@raise [Git::FailedError]` for any facade method that can
+  cause git to exit non-zero. Use the canonical generic wording matching the
+  command's exit-status range:
+
+  | Command's `allow_exit_status` | Facade `@raise` wording |
+  | --- | --- |
+  | none / `0..0` | `if git exits with a non-zero exit status` |
+  | `0..1` | `if git exits outside the allowed range (exit code > 1)` |
+
+- When the facade calls `assert_valid_opts!`, include
+  `@raise [ArgumentError] if unsupported options are provided`.
+- When the facade itself validates arguments and raises (e.g. "you must specify
+  a remote if a branch is specified"), document with a specific `@raise
+  [ArgumentError]` line that names the constraint.
+- Do **not** enumerate specific git failure causes (no "if the branch doesn't
+  exist", no "if the working tree is dirty"). Use the generic form.
+
+Scope `@raise` tags by call-shape:
+
+- Shared across all overloads: keep as one top-level `@raise`
+- Specific to one or more overloads: keep only in those overload blocks
+- Never duplicate identical `@raise` tags at both top level and overload level
+
+### Cross-referencing the implementation
+
+When useful, cross-link to the underlying components with `@see` tags **at the
+end** of the method's doc block:
+
+```ruby
+# @see Git::Commands::Branch::List
+# @see Git::Parsers::Branch
+# @see https://git-scm.com/docs/git-branch git-branch
+```
+
+Use sparingly — only when the cross-link helps a reader navigate to non-obvious
+internals. Do not add `@see` for every command and parser by default; trivial
+delegators do not need them.
+
+### Common issues
+
+- **`@return [Git::CommandLineResult]` on a method that actually returns a
+  parsed value.** Match the actual return value, not the inner call expression.
+- **Copying `@option` blocks from the command class.** The facade exposes only
+  the options listed in its public contract (and the `<METHOD>_ALLOWED_OPTS`
+  whitelist when present). Do not copy every option the command DSL declares.
+- **Documenting policy defaults as caller options.** When the facade hardcodes
+  `no_edit: true`, do not list `:no_edit` as a caller option. The facade's contract
+  is "non-interactive commit"; mention the policy in prose if relevant, not as
+  an `@option`.
+- **Documenting the underlying command in the summary.** Wrong: "Calls
+  `Git::Commands::Add.#call`". Right: "Update the index with the current
+  content found in the working tree."
+- **Leaking `Git::ExecutionContext::Repository` into docs.** The execution
+  context is injected once at construction; facade method docs do not mention
+  it.
+- **Missing `@example` on a public method.** Every public facade method requires
+  at least one `@example` block with a descriptive title. Examples belong on the
+  method, not at the module level.
+- **Missing `@param <name> [Hash]` before `@option` tags.** Every `@option` tag
+  requires a preceding `@param` for the options hash. Use the parameter name from
+  the `@overload` signature when the `def` uses anonymous `**`.
+- **Missing `@api public` on the module.** Every facade module is part of the
+  public API and must declare it.
+- **Uppercase first letter or trailing period on tag short descriptions.** Same
+  rule as command YARD: lowercase start, no trailing punctuation on the short
+  description.
+- **Raw blank line inside a doc comment block.** A line with no leading `#`
+  silently terminates the YARD block. Use blank comment lines (`#`) inside
+  multi-paragraph descriptions.
+
+## Workflow
+
+For each facade module file, run through these checks in order:
+
+### 1. Module-level docs
+
+- [ ] short topic summary (per
+  [YARD Documentation](../yard-documentation/SKILL.md) short-description rules)
+- [ ] "Included by {Git::Repository}." sentence with the YARD link
+- [ ] `@api public`
+- [ ] no `@example` at the module level
+- [ ] no `@see Git::Commands::*` at the module level
+- [ ] no `@see https://git-scm.com/docs/...` at the module level (those belong
+  on the individual facade methods)
+
+### 2. Method-level docs (per method)
+
+- [ ] one-line summary describing caller-facing behavior
+- [ ] at least one `@example` block with a descriptive title
+- [ ] every positional parameter has `@param` with type and short description
+- [ ] every facade-exposed option has `@option` (matching the
+  `<METHOD>_ALLOWED_OPTS` whitelist when present)
+- [ ] when `@option` is used, `@param <name> [Hash]` precedes the `@option`
+  tags; for methods using `@overload`, the parameter name comes from the
+  overload signature (e.g. `@overload add(paths, **options)`) — the `def`
+  may still use anonymous `**`
+- [ ] options that exist on the underlying command but are not exposed by the
+  facade are **not** listed
+- [ ] policy defaults the facade hardcodes are not listed as `@option`
+- [ ] `@return` matches the actual return value type per [Return type
+  rules](#return-type-rules)
+- [ ] `@raise` tags follow [`@raise` rules](#raise-rules)
+- [ ] shared `@raise` tags are top-level; overload-specific `@raise` tags are in
+  the relevant overload only
+- [ ] no duplicate identical `@raise` appears at both top level and overload level
+- [ ] `@see` tags appear at the end and are limited to non-obvious cross-links
+
+### 3. Formatting consistency
+
+- [ ] every YARD tag is preceded by a blank comment line (`#`)
+- [ ] no raw blank lines inside any doc block
+- [ ] tag short descriptions start lowercase and have no trailing punctuation
+- [ ] multi-paragraph tag descriptions have a blank `#` line between paragraphs
+- [ ] all general formatting rules from
+  [YARD Documentation](../yard-documentation/SKILL.md) are satisfied
+
+## Output
+
+### When writing new facade YARD docs
+
+Produce the complete YARD doc block(s) for the module and each method, then
+self-verify by running every checklist item from [Workflow](#workflow) against
+your output. Fix and re-verify until all checks pass.
+
+### When reviewing existing facade YARD docs
+
+For each file, provide:
+
+1. issue table
+
+   | Check | Status | Issue |
+   | --- | --- | --- |
+
+2. corrected doc block snippets (only where needed)
+
+3. **Self-verify before concluding** — re-run every checklist item against
+   your proposed snippets until all checks pass.
+
+> **Branch workflow:** Implement any fixes on a feature branch. Never commit or
+> push directly to `main` — open a pull request when changes are ready to merge.

data/.github/skills/make-skill-template/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: make-skill-template
+description: 'Create new Agent Skills for GitHub Copilot from user requests or by duplicating this template. Use when asked to "create a skill", "make a new skill", "scaffold a skill", or when building specialized AI capabilities with bundled resources. Generates SKILL.md files with proper frontmatter, directory structure, and optional scripts/references/assets folders.'
+---
+
+# Make Skill Template
+
+A meta-skill for creating new Agent Skills. Use this skill when you need to scaffold a new skill folder, generate a SKILL.md file, or help users understand the Agent Skills specification.
+
+## Contents
+
+- [How to use this skill](#how-to-use-this-skill)
+- [Related skills](#related-skills)
+- [When to Use This Skill](#when-to-use-this-skill)
+- [Prerequisites](#prerequisites)
+- [Creating a New Skill](#creating-a-new-skill)
+- [Example: Complete Skill Structure](#example-complete-skill-structure)
+- [Quick Start: Duplicate This Template](#quick-start-duplicate-this-template)
+- [Validation Checklist](#validation-checklist)
+- [Troubleshooting](#troubleshooting)
+- [References](#references)
+
+## How to use this skill
+
+Attach this file to your Copilot Chat context, then invoke it when creating or
+refining a skill under `.github/skills/`. Use it to scaffold new skills and to
+check discoverability quality before committing.
+
+## Related skills
+
+- [Reviewing Skills](../reviewing-skills/SKILL.md) — audit a skill for quality,
+    discoverability, and best-practice compliance after authoring
+- [Development Workflow](../development-workflow/SKILL.md) — integrate skill
+    creation changes into the repository workflow
+- [PR Readiness Review](../pr-readiness-review/SKILL.md) — final validation
+    before opening a pull request with new or updated skills
+
+## When to Use This Skill
+
+- User asks to "create a skill", "make a new skill", or "scaffold a skill"
+- User wants to add a specialized capability to their GitHub Copilot setup
+- User needs help structuring a skill with bundled resources
+- User wants to duplicate this template as a starting point
+
+## Prerequisites
+
+- Understanding of what the skill should accomplish
+- A clear, keyword-rich description of capabilities and triggers
+- Knowledge of any bundled resources needed (scripts, references, assets, templates)
+
+## Creating a New Skill
+
+### Step 1: Create the Skill Directory
+
+Create a new folder with a lowercase, hyphenated name:
+
+```
+.github/skills/<skill-name>/
+└── SKILL.md          # Required
+```
+
+### Step 2: Generate SKILL.md with Frontmatter
+
+Every skill requires YAML frontmatter with `name` and `description`:
+
+```yaml
+---
+name: <skill-name>
+description: '<What it does>. Use when <specific triggers, scenarios, keywords users might say>.'
+---
+```
+
+#### Frontmatter Field Requirements
+
+| Field | Required | Constraints |
+| ----- | -------- | ----------- |
+| `name` | **Yes** | 1-64 chars, lowercase letters/numbers/hyphens only, must match folder name |
+| `description` | **Yes** | 10-1024 chars, must describe WHAT it does AND WHEN to use it |
+| `license` | No | License name or reference to bundled LICENSE.txt |
+| `compatibility` | No | 1-500 chars, environment requirements if needed |
+| `metadata` | No | Key-value pairs for additional properties |
+| `allowed-tools` | No | Space-delimited list of pre-approved tools (experimental) |
+
+#### Description Best Practices
+
+**CRITICAL**: The `description` is the PRIMARY mechanism for automatic skill discovery. Include:
+
+1. **WHAT** the skill does (capabilities)
+2. **WHEN** to use it (triggers, scenarios, file types)
+3. **Keywords** users might mention in requests
+
+**Good example:**
+
+```yaml
+description: 'Toolkit for testing local web applications using Playwright. Use when asked to verify frontend functionality, debug UI behavior, capture browser screenshots, or view browser console logs. Supports Chrome, Firefox, and WebKit.'
+```
+
+**Poor example:**
+
+```yaml
+description: 'Web testing helpers'
+```
+
+### Step 3: Write the Skill Body
+
+After the frontmatter, add markdown instructions. Recommended sections:
+
+| Section | Purpose |
+| ------- | ------- |
+| `# Title` | Brief overview |
+| `## When to Use This Skill` | Reinforces description triggers |
+| `## Prerequisites` | Required tools, dependencies |
+| `## Step-by-Step Workflows` | Numbered steps for tasks |
+| `## Troubleshooting` | Common issues and solutions |
+| `## References` | Links to bundled docs |
+
+### Step 4: Add Optional Directories (If Needed)
+
+| Folder | Purpose | When to Use |
+| ------ | ------- | ----------- |
+| `scripts/` | Executable code (Python, Bash, JS) | Automation that performs operations |
+| `references/` | Documentation agent reads | API references, schemas, guides |
+| `assets/` | Static files used AS-IS | Images, fonts, templates |
+| `templates/` | Starter code agent modifies | Scaffolds to extend |
+
+## Example: Complete Skill Structure
+
+```
+my-awesome-skill/
+├── SKILL.md                    # Required instructions
+├── LICENSE.txt                 # Optional license file
+├── scripts/
+│   └── helper.py               # Executable automation
+├── references/
+│   ├── api-reference.md        # Detailed docs
+│   └── examples.md             # Usage examples
+├── assets/
+│   └── diagram.png             # Static resources
+└── templates/
+    └── starter.ts              # Code scaffold
+```
+
+## Quick Start: Duplicate This Template
+
+1. Copy the `make-skill-template/` folder
+2. Rename to your skill name (lowercase, hyphens)
+3. Update `SKILL.md`:
+   - Change `name:` to match folder name
+   - Write a keyword-rich `description:`
+   - Replace body content with your instructions
+4. Add bundled resources as needed
+5. Review with the [Reviewing Skills](../reviewing-skills/SKILL.md) skill
+
+## Validation Checklist
+
+- [ ] Folder name is lowercase with hyphens
+- [ ] `name` field matches folder name exactly
+- [ ] `description` is 10-1024 characters
+- [ ] `description` explains WHAT and WHEN
+- [ ] `description` is wrapped in single quotes
+- [ ] Body content is under 500 lines
+- [ ] Bundled assets are under 5MB each
+
+## Troubleshooting
+
+| Issue | Solution |
+| ----- | -------- |
+| Skill not discovered | Improve description with more keywords and triggers |
+| Validation fails on name | Ensure lowercase, no consecutive hyphens, matches folder |
+| Description too short | Add capabilities, triggers, and keywords |
+| Assets not found | Use relative paths from skill root |
+
+## References
+
+- Agent Skills official spec: <https://agentskills.io/specification>
+- Skill authoring best practices: <https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices>