docs: update command-structure design doc to reflect current command inventory

Adds the full top-level command list, one-level and two-level group examples
(dbx spec patch), fixes the stale dbx project -l example, and documents
when two-level nesting is appropriate.

Author: aclark4life

docs/design/command-structure.rst

@@ -1,12 +1,12 @@
 Command Structure
 =================
 
-This document explains the design decision to use top-level commands instead of nested command groups.
+This document explains the design decisions behind how commands are organised in the CLI.
 
 Decision
 --------
 
-We prefer **top-level commands** (``dbx clone``, ``dbx sync``) over **nested command groups** (``dbx repo clone``, ``dbx repo sync``).
+We prefer **top-level commands** (``dbx clone``, ``dbx sync``) over **nested command groups** (``dbx repo clone``, ``dbx repo sync``), but command groups and even two-level nesting are used when the domain is rich enough to warrant it.
 
 Rationale
 ---------
@@ -25,10 +25,11 @@ Common Usage Patterns
 
 The most frequently used commands should be at the top level:
 
-- ``dbx clone`` - Clone repositories from a group
-- ``dbx sync`` - Sync repositories with upstream
-- ``dbx install`` - Install packages
-- ``dbx test`` - Run tests
+- ``dbx clone`` — Clone repositories from a group
+- ``dbx sync`` — Sync repositories with upstream
+- ``dbx install`` — Install packages
+- ``dbx test`` — Run tests
+- ``dbx list`` — List cloned repositories
 
 These are the primary workflows, so they should be as accessible as possible.
 
@@ -37,51 +38,103 @@ Consistency with Git
 
 Git uses top-level commands (``git clone``, ``git pull``, ``git push``) rather than nested groups (``git repo clone``). This pattern is familiar to developers.
 
-When to Use Command Groups
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Current Command Inventory
+-------------------------
 
-Command groups are still useful for:
+Top-Level Commands
+~~~~~~~~~~~~~~~~~~
 
-- **Related subcommands**: ``dbx env create``, ``dbx env activate``, ``dbx env list``
-- **Namespacing**: When multiple commands share a common domain (e.g., environment management)
-- **Organization**: When there are many related commands that would clutter the top level
+Single-action commands that are frequently used or domain-agnostic:
 
-Examples
---------
+.. code-block:: text
 
-Top-Level Commands (Preferred)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+   dbx branch      Git branch operations across repositories
+   dbx clone       Clone a repository group
+   dbx edit        Open a repository in an editor
+   dbx install     Install package dependencies
+   dbx just        Run just commands in a repository
+   dbx list        List cloned repositories
+   dbx log         Git log across repositories
+   dbx open        Open a repository in the browser
+   dbx patch       Create Evergreen CI patches
+   dbx remove      Remove a cloned repository
+   dbx status      Git status across repositories
+   dbx swap        Swap between repository versions
+   dbx switch      Switch git branches across repositories
+   dbx sync        Sync repositories with upstream
+   dbx test        Run tests in a repository
+
+Command Groups (One Level)
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Related subcommands that share a common domain:
 
 .. code-block:: bash
 
-   # Clone repositories
-   dbx clone -g pymongo
+   # Configuration management
+   dbx config init
+   dbx config show
+   dbx config edit
 
-   # Sync a repository
-   dbx sync mongo-python-driver
+   # Documentation operations
+   dbx docs build
+   dbx docs list
+   dbx docs open
 
-   # List repositories
-   dbx list
+   # Virtual environment management
+   dbx env init
+   dbx env list
+   dbx env remove
+
+   # Django project management
+   dbx project add myproject
+   dbx project install
+   dbx project migrate
+   dbx project run
+   dbx project su
+   dbx project list
+   dbx project remove
+
+Command Groups (Two Levels)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Command Groups (When Appropriate)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+When a domain has enough distinct sub-domains, two levels of nesting are acceptable. The only current example is ``dbx spec``, where spec-level operations (``sync``, ``list``, ``status``) are clearly separate from patch lifecycle operations:
 
 .. code-block:: bash
 
-   # Environment management
-   dbx env create -g pymongo
-   dbx env activate -g pymongo
-   dbx env list
+   # Spec-level operations
+   dbx spec sync crud sessions
+   dbx spec list
+   dbx spec status
 
-   # Project management
-   dbx project add myproject
-   dbx project run myproject
-   dbx project -l
+   # Patch lifecycle (sub-group)
+   dbx spec patch apply
+   dbx spec patch create PYTHON-1234
+   dbx spec patch list
+   dbx spec patch remove PYTHON-1234
+   dbx spec patch verify
+
+Two-level nesting should remain rare. The bar for adding a third level is very high — if you find yourself wanting ``dbx foo bar baz``, consider whether ``foo`` and ``bar`` should be merged or whether ``baz`` belongs at a higher level.
+
+When to Use Command Groups
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Command groups are appropriate when:
+
+- **Multiple related subcommands** share a common domain (e.g., environment management, spec sync)
+- **Namespacing prevents collisions** — ``dbx spec list`` and ``dbx list`` do different things
+- **The group has 3+ subcommands** — a group with only one subcommand adds friction without benefit
+
+Top-level placement is preferred when:
+
+- The command is used frequently in isolation
+- It has no natural siblings that share state or configuration
+- Adding it to a group would make it harder to discover
 
 Migration Notes
 ---------------
 
-This decision was implemented in a refactoring that moved ``clone`` and ``sync`` from the ``repo`` command group to the top level.
+This design was established when ``clone`` and ``sync`` were promoted from the ``repo`` command group to the top level.
 
 **Before:**
 
@@ -99,12 +152,12 @@ This decision was implemented in a refactoring that moved ``clone`` and ``sync``
    dbx sync mongo-python-driver
    dbx list
 
-The ``repo.py`` module was converted from a command module to a helper functions module, containing only utility functions like ``get_config()``, ``get_base_dir()``, and ``get_repo_groups()``.
+The ``repo.py`` module was converted from a command module to a utility functions module containing helpers like ``get_config()``, ``get_base_dir()``, and ``get_repo_groups()``.
 
 Smart Defaults for Convenience
 -------------------------------
 
-To further improve usability, commands should provide smart defaults when possible. This reduces typing and makes common workflows faster.
+To further improve usability, commands should provide smart defaults when possible.
 
 Project Commands Default to Newest
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -113,35 +166,31 @@ Most ``dbx project`` commands default to the newest project when no project name
 
 .. code-block:: bash
 
-   # These commands work without specifying a project name
    dbx project run              # Run newest project
    dbx project manage shell     # Open shell on newest project
    dbx project su               # Create superuser on newest project
    dbx project migrate          # Run migrations on newest project
    dbx project remove           # Remove newest project
 
-The "newest" project is determined by filesystem modification time. This is particularly useful during active development when you're frequently working with the same project.
-
-When a command defaults to the newest project, it displays an informative message:
+The "newest" project is determined by filesystem modification time. When a command defaults to the newest project, it displays an informative message:
 
 .. code-block:: text
 
    ℹ️  No project specified, using newest: 'myproject'
 
-This design decision follows the principle of **optimizing for the common case**: developers typically work on one project at a time, so requiring the project name for every command adds unnecessary friction.
+This follows the principle of **optimizing for the common case**: developers typically work on one project at a time, so requiring the project name for every command adds unnecessary friction.
 
 Future Considerations
 ---------------------
 
-As the CLI grows, we should continue to evaluate whether commands belong at the top level or in a group:
+As the CLI grows, continue to evaluate whether commands belong at the top level or in a group:
 
 - **Top level**: Frequently used, standalone operations
 - **Command groups**: Related operations that share context or configuration
+- **Two-level groups**: Only when a domain is large enough to have distinct sub-domains
 
-We should also look for opportunities to add smart defaults that reduce typing while maintaining clarity:
+When adding smart defaults:
 
 - **Sensible defaults**: Commands should work with minimal arguments for common use cases
 - **Clear feedback**: When defaults are applied, inform the user what was chosen
 - **Easy override**: Defaults should be easy to override when needed
-
-The goal is to keep the CLI intuitive and easy to use while maintaining good organization.