Shepherd

Português (BR) | English | Español

A tool and package to manage DDD (Domain Driven Design) projects in Dart/Flutter, with domain health analysis, cleaning automation, YAML export, and CLI integration.

Installation

Or install globally to use the CLI (Recommended):

dart pub global activate shepherd

Add to your pubspec.yaml to use as a package:

dependencies:
  shepherd: ^0.7.4

1. Setup & Onboarding

Getting started with Shepherd is easy, whether you're starting a new project or joining an existing one.

Quick Start

# Simply run Shepherd - it will guide you through setup
shepherd

When you run Shepherd for the first time in a project, it automatically detects that configuration is missing and presents you with options:

  1. Initialize a new project - Set up Shepherd from scratch
  2. Pull from existing project - Import configuration from a team repository

Setup Modes

If you choose to initialize, you'll select a setup mode:

  1. Automation Only: Lightweight setup for CI/CD automation.

    • Configures: Project info, environments, user details
    • Enables: clean, changelog, deploy commands
    • Skips: Domain modeling and team management

  2. Full Setup: Complete DDD project management.

    • Everything in Automation mode, plus:
    • Domain registration and health tracking
    • Team ownership and responsibility mapping
    • Interactive menu for ongoing management

Result: Generates configuration files (.shepherd/project.yaml, .shepherd/environments.yaml, etc.)

Alternative: Direct Init

# You can also run init directly
shepherd init

Recommended for new team members. This command synchronizes your local database with the project's devops/domains.yaml file, importing all domains and owners so you are ready to work immediately.

2. Automation & CI/CD

Shepherd automates the tedious parts of development, from deep cleaning to deployment.

Deep Cleaning

# Clean all projects and microfrontends at once
shepherd clean

# Clean only the current project
shepherd clean project

Useful for mono-repos where you need to run flutter clean across multiple packages.

Note: This command relies on the project configuration (generated by shepherd init) to locate all registered microfrontends in microfrontends.yaml.

Automatic Changelog

shepherd changelog

Automatically handles your CHANGELOG.md using two distinct modes based on your current branch:

  1. Generation Mode (Feature Branches):

    • Context: You are working on a feature (e.g., feature/new-login).
    • Action: Scans your commits that are ahead of develop.
    • Result: Adds new entries to CHANGELOG.md under an "Unreleased" section.

  2. Update Mode (Release & Main Branches):

    • Context: You are finalizing a version (e.g., release/1.0.0) or on main.
    • Action: Recognizes that features come from develop.
    • Result: Pulls the latest changelog entries from develop and merges them into your current manifest, ensuring consistency without duplicating commit scans.

Note: This command never changes the project version number. Version bumping is handled exclusively by shepherd deploy.

Deployment Pipeline

shepherd deploy

Runs the full deploy workflow depending on the branch:

  1. Version Bump: Prompts to bump the version (patch, minor, major).
  2. Changelog: Generates the final changelog for the version.
  3. Pull Request: Automatically opens a PR integrated with GitHub CLI and Azure CLI.

Branch Strategy:

  • develop: Default working branch.
  • release: For preparing a new version.
  • main: Production code.

3. DDD & Project Management 🚧 Alpha Development

Shepherd helps you maintain a clean architecture by managing domains, owners, and health checks.

Domain Health Analysis

shepherd analyze

Checks your project for architectural violations, missing owners, or structure issues.

Configuration & Owners

# Interactive configuration menu
shepherd config

# Add an owner to a specific domain
shepherd add-owner <domain>

Persistence

shepherd export-yaml

Exports all registered domains and owners to devops/domains.yaml, allowing you to version control your project structure settings.

Documentation

Shepherd Domain Architecture

Shepherd is organized into core domains, each responsible for a part of the management and automation flow:

+-------------------+
|     Shepherd      |
+-------------------+
         |
         +-----------------------------+
         |                             |
+--------+--------+         +----------+----------+
|     Domains     |         |      Functions      |
+-----------------+         +---------------------+
|                 |         |                     |
|  config         |<------->|  Configuration,     |
|  deploy         |<------->|  Deploy,            |
|  init           |<------->|  Initialization,    |
|  domains        |<------->|  Business Domains   |
|  menu           |<------->|  Menus & CLI UX     |
|  tools          |<------->|  Utilities,         |
|  sync           |<------->|  Synchronization    |
+-----------------+         +---------------------+

Domain Details:

  • config - Manages project configuration, environments, users.
  • deploy - Manages deployment flow, PRs, versioning.
  • init - Onboarding, project creation and initialization.
  • domains - Business logic, entities, domain use cases.
  • menu - Menus, navigation and CLI user experience.
  • tools - Utilities, helpers, auxiliary services.
  • sync - Data synchronization, import/export, database integration.

Domains communicate primarily via the domain and service layers, keeping code modular and maintainable.

License

MIT © 2026 Vinicius Cruvinel

Libraries

shepherd