command-implementation

Command Implementation

Scaffold new and review existing Git::Commands::Base command classes, unit tests, integration tests, and YARD docs.

Contents

• Contents
• Related skills
• Input
  • Command source code
  • Command test code
  • Git documentation for the git command
• Reference
• Workflow
• Output

Related skills

Additional related skills:

• Review Arguments DSL — verify every DSL entry is correct and complete
• Command YARD Documentation — verify documentation completeness and formatting
• RSpec Unit Testing Standards — baseline RSpec rules all generated unit specs must comply with
• Command Test Conventions — conventions for writing and reviewing unit and integration tests for command classes
• Review Cross-Command Consistency — sibling consistency within a command family
• Facade Implementation — the v5.0.0 facade layer (Git::Repository::*) that calls these command classes; new facade wiring goes into a Git::Repository::* facade module rather than directly into the command class

Input

The user provides the target Git::Commands::* class name and the git subcommand (or subcommand + sub-action) it wraps. The agent gathers the following.

Command source code

Read the command class from lib/git/commands/{command}.rb or, for subcommands, lib/git/commands/{command}/{subcommand}.rb. For subcommands, also read the namespace module at lib/git/commands/{command}.rb which lists all sibling subcommands and provides the module-level documentation.

Skip this step when scaffolding a new command (the file does not exist yet).

Command test code

Read unit tests matching spec/unit/git/commands/{command}/**/*_spec.rb. Use these as supplemental evidence when tracing the verification chain (Ruby call → bound argument → expected git CLI). Coverage completeness is assessed by the Command Test Conventions skill.

Skip this step when scaffolding a new command (the file does not exist yet).

Git documentation for the git command

• Latest-version online command documentation

  Read the entire official git documentation online man page for the command for the latest version of git. This version will be used as the primary authority for DSL completeness, including the options to include in the DSL, argument names, aliases, ordering, etc. Fetch this version from the URL https://git-scm.com/docs/git-{command} (this URL always serves the latest release).

• Minimum-version online command documentation

  Read the entire official git documentation online man page for the command for the Git::MINIMUM_GIT_VERSION version of git. This will be used only for command-introduction and requires_git_version decisions. Fetch this version from URL https://git-scm.com/docs/git-{command}/{version}.

Do not scaffold from local git <command> -h output — the installed Git version is unknown and may differ from the latest supported version. Local help should NOT be used even as a supplemental check.

Reference

See REFERENCE.md for the full reference covering:

• Files to generate
• Single class vs. sub-command namespace (when to split, naming, templates)
• Architecture contract and structural requirements
• Command template (Base pattern)
• #call override guidance (when to override, stdin feeding, action-option patterns)
• Base#with_stdin mechanics
• Options completeness (version conventions, execution-model conflicts)
• end_of_options placement rules
• Exit status guidance
• Facade delegation and policy options
• Internal compatibility contract
• Phased rollout requirements
• Common failures

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 — creating a new command class from scratch. Follow all steps.
• Update — adding options to an existing command class: skip steps 2, 3a, 3b, and 3c (the class and test files already exist). Start from step 1, then proceed directly to 3d → 3e → 3f → 4 → 5.
• Review — auditing an existing command class for correctness (no changes). Follow all steps but produce findings instead of code.

1. Gather input — collect the target class name and git subcommand from the Input, then fetch the latest-version and minimum-version git documentation per Git documentation for the git command.

2. Determine class structure (scaffold mode only) — decide between a single class and a sub-command namespace per Single class vs. sub-command namespace.

3. For each command / sub-command class, repeat steps 3a–3f:

   a. Scaffold the command class (subagent) (scaffold mode only) — delegate to a subagent: load REFERENCE.md and the YARD Documentation skill, then generate lib/git/commands/{command}.rb using the Command template. Populate the arguments do block with all options from the latest-version docs per Options completeness, applying the Execution-model conflicts, end_of_options placement, and Exit status guidance rules. Pass the fetched git documentation to the subagent.

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

   b. Scaffold unit tests (subagent) (scaffold mode only) — delegate to a subagent: load Command Test Conventions (which loads RSpec Unit Testing Standards), then generate spec/unit/git/commands/{command}_spec.rb following the unit test conventions. Fix all findings, then repeat the review until clean.

   c. Scaffold integration tests (subagent) (scaffold mode only) — delegate to a subagent: load Command Test Conventions, then generate spec/integration/git/commands/{command}_spec.rb following the integration test conventions. Fix all findings, then repeat the review until clean.

   d. Review Arguments DSL (subagent) — delegate to a subagent: load and apply Review Arguments DSL (and its CHECKLIST.md) against the arguments do block. Fix all findings, then repeat the review until clean. Complete this step before starting steps 3e–3f — DSL corrections change the CLI arguments that tests and YARD docs must reflect.

   Steps 3e and 3f may run in parallel (they review independent file sets).

   e. Review Command Tests (subagent) — delegate to a subagent: load and apply Command Test Conventions against the unit and integration spec files. Fix all findings, then repeat the review until clean.

   f. Review YARD Documentation (subagent) — delegate to a subagent: load and apply Command YARD Documentation against the command class. Fix all findings, then repeat the review until clean.

4. Review class shape and declarations — load REFERENCE.md and verify against the Architecture contract, #call override guidance, Exit status guidance, requires_git_version convention, Internal compatibility contract, and Common failures. Additionally:

   • For scaffold and update modes: write or update the Git::Repository::* facade method per Facade delegation and policy options.
   • For migration PRs: verify Phased rollout requirements.

5. Run quality gates — discover the prerequisite tasks for default:parallel and run them sequentially, fixing failures before advancing:

   bundle exec ruby -e "require 'rake'; load 'Rakefile'; puts Rake::Task['default:parallel'].prerequisites"
   

   Run each listed task individually in order via bundle exec rake <task> (one task per invocation — never combine multiple tasks in a single command). On failure, fix the issue and re-run that same task. Once it passes, continue to the next task. After all tasks pass, if any task required a fix during this cycle, start a new cycle from the first task using the same one-at-a-time approach. Keep cycling until every task passes on its first attempt with no fixes needed.

Output

For scaffold and update modes, produce:

1. Command class — lib/git/commands/{command}.rb (and optionally the namespace module file for the first command in a namespace)
2. Unit tests — spec/unit/git/commands/{command}_spec.rb
3. Integration tests — spec/integration/git/commands/{command}_spec.rb
4. Facade delegation — updated Git::Repository::* facade method in lib/git/repository/<topic>.rb
5. All quality gates pass — RSpec, RuboCop, YARD, and build all green

For review mode, produce:

Then list required fixes and indicate whether the migration slice is safe to merge under phased-rollout rules.