refactor: update command architecture and documentation for improved clarity and dependency injection

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>

Author: coisa

README.md

@@ -83,6 +83,15 @@ composer dev-tools gitattributes
 # Generates a LICENSE file from composer.json license information
 composer dev-tools license
 
+# Copies packaged or local resources into the consumer repository
+composer dev-tools copy-resource --source resources/docblock --target .docheader
+
+# Installs Fast Forward Git hooks
+composer dev-tools git-hooks
+
+# Updates the composer.json file to match the packaged schema
+composer dev-tools update-composer-json --force
+
 # Installs and synchronizes dev-tools scripts, GitHub Actions workflows,
 # .editorconfig, .gitignore rules, packaged skills, and the repository wiki
 # submodule in .github/wiki
@@ -119,6 +128,17 @@ keeps the same command vocabulary when you prefer running tools directly from
 `vendor/bin/dev-tools`. The consumer sync flow also refreshes `.agents/skills`
 so agents can discover the packaged skills shipped with this repository.
 
+## 🏗️ Architecture
+
+Commands no longer extend a shared abstract base. Each command is self-contained
+and receives its dependencies through constructor injection, following
+the :abbr:`DI` pattern. The ``ProcessBuilder`` and ``ProcessQueue`` classes
+provide a fluent API for constructing and executing system processes in sequence.
+
+- ``ProcessBuilderInterface`` - Builds process commands with arguments
+- ``ProcessQueueInterface`` - Manages and executes process queues
+- ``FilesystemInterface`` - Abstracts filesystem operations
+
 ## 🤝 Contributing
 
 Run `composer dev-tools` before opening a pull request. If you change public

docs/api/commands.rst

@@ -1,20 +1,16 @@
 Command Classes
 ===============
 
-All public CLI commands extend
-``FastForward\DevTools\Console\Command\AbstractCommand``, which provides path
-resolution, configuration fallback, PSR-4 lookup, and child-command dispatch.
+All public CLI commands extend ``Composer\Command\BaseCommand`` and receive
+dependencies through constructor injection. The architecture uses
+``ProcessBuilder`` and ``ProcessQueue`` for fluent process management.
 
 .. list-table::
    :header-rows: 1
 
    * - Class
      - CLI command
      - Responsibility
-   * - ``FastForward\DevTools\Console\Command\AbstractCommand``
-     - n/a
-     - Shared helpers for path resolution, packaged fallback files, PSR-4
-       discovery, and subcommand execution.
    * - ``FastForward\DevTools\Console\Command\StandardsCommand``
      - ``standards``
      - Runs the full quality pipeline.
@@ -52,6 +48,18 @@ resolution, configuration fallback, PSR-4 lookup, and child-command dispatch.
    * - ``FastForward\DevTools\Console\Command\GitIgnoreCommand``
      - ``gitignore``
      - Merges and synchronizes .gitignore files.
+   * - ``FastForward\DevTools\Console\Command\GitAttributesCommand``
+     - ``gitattributes``
+     - Manages export-ignore rules in .gitattributes.
    * - ``FastForward\DevTools\Console\Command\LicenseCommand``
      - ``license``
      - Generates a LICENSE file from composer.json license information.
+   * - ``FastForward\DevTools\Console\Command\CopyResourceCommand``
+     - ``copy-resource``
+     - Copies packaged or local resources into the consumer repository.
+   * - ``FastForward\DevTools\Console\Command\GitHooksCommand``
+     - ``git-hooks``
+     - Installs Fast Forward Git hooks.
+   * - ``FastForward\DevTools\Console\Command\UpdateComposerJsonCommand``
+     - ``update-composer-json``
+     - Updates the composer.json file to match the packaged schema.

docs/configuration/overriding-defaults.rst

@@ -7,13 +7,16 @@ without forking the whole package.
 Resolution Order
 ----------------
 
-``FastForward\DevTools\Console\Command\AbstractCommand::getConfigFile()`` resolves
-configuration in this order:
+Commands use ``Symfony\Component\Config\FileLocatorInterface`` to locate
+configuration files. The locator resolves configuration in this order:
 
 1. Check whether the file exists in the current working directory.
 2. Use the local file when it exists.
 3. Otherwise fall back to the packaged file inside ``fast-forward/dev-tools``.
 
+This behavior is consistent across all commands through the DI container
+and ``FileLocatorInterface``.
+
 Commands and Their Configuration Files
 --------------------------------------
 

docs/internals/architecture.rst

@@ -1,5 +1,5 @@
 Architecture and Command Lifecycle
-==================================
+=================================
 
 The package has two connected execution models: local command execution and
 consumer repository synchronization.
@@ -14,9 +14,8 @@ Local Command Lifecycle
    ``FastForward\DevTools\Composer\Capability\DevToolsCommandProvider``.
 4. ``standards`` is used as the default command when no explicit command name
    is given.
-5. Individual commands resolve local configuration first and packaged
-   fallbacks second through
-   ``FastForward\DevTools\Console\Command\AbstractCommand::getConfigFile()``.
+5. Commands receive dependencies through constructor injection from
+   ``DevToolsServiceProvider``.
 
 Consumer Synchronization Lifecycle
 ----------------------------------
@@ -39,24 +38,33 @@ Documentation Pipeline
 ----------------------
 
 1. ``FastForward\DevTools\Console\Command\DocsCommand`` reads PSR-4 paths from
-   ``composer.json``.
-2. It generates a temporary ``phpdocumentor.xml`` file in
-   ``tmp/cache/phpdoc``.
+   ``composer.json`` via ``ComposerJsonInterface``.
+2. It generates a temporary ``phpdocumentor.xml`` file in the configured cache
+   directory.
 3. phpDocumentor builds API pages from those PSR-4 paths.
 4. phpDocumentor also builds the guide from the selected ``docs/`` source
    directory.
 5. ``FastForward\DevTools\Console\Command\ReportsCommand`` combines that
    documentation build with PHPUnit coverage generation.
 
-Key Abstraction
----------------
+Dependency Injection
+--------------------
+
+Commands receive their dependencies through constructor injection provided by
+``DevToolsServiceProvider``.
 
-``FastForward\DevTools\Console\Command\AbstractCommand`` is the main shared layer. It
-centralizes:
+.. list-table::
+   :header-rows: 1
 
-- current working directory detection;
-- absolute path resolution;
-- local-versus-packaged config lookup;
-- command-to-command dispatch inside the same application;
-- access to Composer package metadata such as PSR-4 namespaces and project
-  description.
+   * - Interface
+     - Purpose
+   * - ``FastForward\DevTools\Process\ProcessBuilderInterface``
+     - Builds process commands with a fluent API for arguments.
+   * - ``FastForward\DevTools\Process\ProcessQueueInterface``
+     - Queues and executes multiple processes in sequence.
+   * - ``FastForward\DevTools\Filesystem\FilesystemInterface``
+     - Abstracts filesystem operations.
+   * - ``FastForward\DevTools\Composer\Json\ComposerJsonInterface``
+     - Reads and validates ``composer.json`` metadata.
+   * - ``Symfony\Component\Config\FileLocatorInterface``
+     - Locates configuration files.

src/Console/Command/SyncCommand.php

@@ -77,7 +77,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
     {
         $output->writeln('<info>Starting dev-tools synchronization...</info>');
 
-        $this->queueDevToolsCommand(['composer-json:update']);
+        $this->queueDevToolsCommand(['update-composer-json']);
         $this->queueDevToolsCommand(
             [
                 'copy-resource',

src/Console/Command/UpdateComposerJsonCommand.php

@@ -36,7 +36,7 @@
  * Updates composer.json with the Fast Forward dev-tools integration metadata.
  */
 #[AsCommand(
-    name: 'composer-json:update',
+    name: 'update-composer-json',
     description: 'Updates composer.json with Fast Forward dev-tools scripts and metadata.',
     help: 'This command adds or updates composer.json scripts and GrumPHP extra configuration required by dev-tools.'
 )]

tests/Console/Command/UpdateComposerJsonCommandTest.php

@@ -66,7 +66,7 @@ protected function setUp(): void
     #[Test]
     public function commandWillSetExpectedNameDescriptionAndHelp(): void
     {
-        self::assertSame('composer-json:update', $this->command->getName());
+        self::assertSame('update-composer-json', $this->command->getName());
         self::assertSame(
             'Updates composer.json with Fast Forward dev-tools scripts and metadata.',
             $this->command->getDescription()