facade-implementation

name	facade-implementation
description	Scaffolds new and reviews existing Git::Repository facade methods (organized into Git::Repository::* topic modules) with unit tests, integration tests, and YARD docs. Use when adding a new facade method to Git::Repository, updating an existing facade method, choosing or creating a topic module under lib/git/repository/, or reviewing a facade method for correctness.

Facade Implementation

Scaffold new and review existing facade methods on Git::Repository. Facade methods live in topic modules under lib/git/repository/<topic>.rb (e.g. {Git::Repository::Staging}) and are included into the Git::Repository class.

A facade method is the public-API entry point that orchestrates one or more Git::Commands::* calls, optional argument pre-processing, and optional output parsing into rich Ruby return values. See redesign/2_architecture_redesign.md §2.1 for the five facade responsibilities this layer is designed around.

Contents

• How to use this skill
• Related skills
• Input
  • Existing facade source
  • Existing facade tests
  • Underlying command class(es)
  • Underlying parsers (if any)
• Reference
• Workflow
• Output

How to use this skill

Attach this file to your Copilot Chat context, then invoke with the facade method to scaffold, update, or review. Examples:

Using the Facade Implementation skill, scaffold Git::Repository::Staging#add.

Facade Implementation review: Git::Repository::Committing#commit.

Related skills

• Facade Test Conventions — unit and integration test conventions for facade methods (load when scaffolding or reviewing tests)
• Facade YARD Documentation — facade-specific YARD rules for module-level and method-level docs
• Command Implementation — the underlying Git::Commands::* classes a facade method calls. Scaffold any missing command class first.
• YARD Documentation — baseline YARD formatting rules
• RSpec Unit Testing Standards — baseline RSpec rules
• Project Context — three-layer architecture overview

Input

The user provides:

1. Method name — the public Ruby method name (e.g. add, branches_all, commit).
2. Git operation(s) — which Git::Commands::* class(es) the method orchestrates. If the relevant command class does not exist yet, scaffold it first via Command Implementation.

Note: Git::Repository is intentionally empty during early phases of the redesign. Its initialize(execution_context:) constructor is introduced alongside the first facade method extraction; subsequent extractions only add new topic modules and include lines.

The agent then gathers:

Existing facade source

Read lib/git/repository.rb to see the include Git::Repository::<Topic> lines and which topic modules exist. List lib/git/repository/ to see all current topic modules and the facade methods they already define.

Skip when scaffolding into a brand-new topic module.

Existing facade tests

Read spec/unit/git/repository/<topic>_spec.rb and spec/integration/git/repository/<topic>_spec.rb (if present). Use as supplemental evidence of the existing test style before extending or reviewing.

Underlying command class(es)

Read lib/git/commands/<command>.rb for each command the facade method calls. The command's arguments do block defines the option keys the facade may forward, and the YARD @!method call block documents what each option does. The facade must not pass option keys the command does not declare.

Underlying parsers (if any)

Read lib/git/parsers/<parser>.rb for any parser the facade uses to transform command stdout into structured data.

Reference

See REFERENCE.md for the full reference covering:

• Files to generate
• Topic module selection (existing modules + decision rules for creating a new module)
• Designing a facade method (return type, signature, body shape)
• Topic module skeleton (file layout)
• The five facade responsibilities as a checklist
• Argument pre-processing patterns (path normalization, option whitelisting via SharedPrivate.assert_valid_opts! + private_constant, deprecation handling, defaults)
• Internal helpers and encapsulation (sibling module_function modules under lib/git/repository/ instead of private methods on Git::Repository; bare-noun naming; growth path from SharedPrivate to responsibility-named modules)
• When to call multiple commands (orchestration sequences)
• When to use a parser vs. raw stdout
• When to use a result-class factory method
• Common failures (one-line delegation when orchestration is needed; leaking command-class types into the public API; bypassing the execution context; hardcoding policy options the caller cannot override)

Subagents load REFERENCE.md directly during the workflow steps that need it.

Workflow

This skill supports three modes. Determine which mode applies before starting:

• Scaffold — adding a new facade method (and possibly a new topic module). Follow all steps.
• Update — modifying an existing facade method (e.g. adding a new option to forward). Skip step 2 (module selection); steps 3a–3c are extending existing files rather than creating them.
• Review — auditing an existing facade method (no changes). Follow all steps but produce findings instead of code.

1. Gather input — collect the method name, target git operation(s), and any migration source per Input. Read the underlying command class(es) and parser(s) the method will call.

2. Choose the topic module — load REFERENCE.md and apply Topic module selection:

   • Prefer extending an existing module under lib/git/repository/.
   • Create a new module only when the topic is recognizable — preferably matching a git-scm category (https://git-scm.com/docs) — and the methods would be awkward to place in any existing module. The deciding factor is topic fit, not method count; a single method that is genuinely distinct can start its own module.
   • New module names follow the two-tier convention: gerund (Staging, Logging, Diffing) for single-action modules; Noun + Operations (RemoteOperations, ObjectOperations) for mixed-bag modules. See REFERENCE.md §Naming a new topic module.

3. For the facade method, repeat steps 3a–3e:

   a. Scaffold the facade method (subagent) (scaffold/update modes only) — delegate to a subagent: load REFERENCE.md and the Facade YARD Documentation skill, then create or extend lib/git/repository/<topic>.rb using the Designing a facade method section and Topic module skeleton. For new topic modules, also add the require and include lines to lib/git/repository.rb.

   Steps 3b and 3c may run in parallel (they produce independent files).

   b. Scaffold unit tests (subagent) (scaffold/update modes only) — delegate to a subagent: load Facade Test Conventions (which loads RSpec Unit Testing Standards), then create or extend spec/unit/git/repository/<topic>_spec.rb following the unit conventions (stub Git::Commands::* and Git::Parsers::* via instance_double; assert delegation contracts; cover each pre-processing branch).

Output

For scaffold and update modes, produce:

1. Topic module — lib/git/repository/<topic>.rb (created or extended)
2. Facade wiring — lib/git/repository.rb updated with require and include when a new topic module was created
3. Unit tests — spec/unit/git/repository/<topic>_spec.rb
4. Integration tests — spec/integration/git/repository/<topic>_spec.rb (omit only for true one-line delegators)
5. All quality gates pass — rspec, minitest, rubocop, and yard all green

For review mode, produce:

Check	Status	Issue
Topic module placement	Pass/Fail	...
Orchestration via @execution_context	Pass/Fail	...
Argument pre-processing complete	Pass/Fail	...
Option whitelisting (where required)	Pass/Fail	...
*_ALLOWED_OPTS placed immediately before its method	Pass/Fail	...
Signature classification documented	Pass/Fail	...
Signature shape matches classification	Pass/Fail	...
Return value matches documented contract	Pass/Fail	...
Parser/result-class wiring correct	Pass/Fail	...
YARD docs complete	Pass/Fail	...
Unit + integration coverage	Pass/Fail	...

Then list required fixes.

Branch workflow: Implement scaffolding or updates on a feature branch. Never commit or push directly to main — open a pull request when changes are ready to merge.