Shepherd

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

Advanced CLI automation and productivity engine for Flutter/Dart. Simplifies developer workflows (clean, deploy, changelog) and bridges Design Systems to testing with Atomic Design and Maestro.

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.8.3

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:

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

Setup Modes

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

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
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:

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.
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.

Automated Test Generation

shepherd test gen

Scans your project for @ShepherdTag and ShepherdPageKey annotations and automatically generates Maestro test flows.

Enrichment: Uses data from .shepherd/shepherd_activity.yaml to add context to flows.
Output: Flows are saved in .shepherd/maestro/flows/.

Tag Generation

# Generate tag wrapper classes from annotations
shepherd tag gen

Scans your code for @ShepherdPageKey and @ShepherdTag to generate typesafe Tag Wrapper classes. It ensures your UI keys match the interaction contract defined in your user stories.

Story & Atomic Design Management

# Manage User Stories
shepherd story add <id> <title> <domain> <description>
shepherd story list

# Manage Design Elements (Atoms, Molecules, etc.)
shepherd element add <storyId> <elementId> <title> <type>
shepherd element list

# Manage Agile Tasks
shepherd task add <storyId> <title>

Organize your development cycle with Atomic Design principles. Categorize elements as atom, molecule, organism, or token to drive intelligent test generation.

Deployment Pipeline

shepherd deploy

Runs the full deploy workflow depending on the branch:

Version Bump: Prompts to bump the version (patch, minor, major).
Changelog: Generates the final changelog for the version.
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

Contributing Guide: Workflow, code standards, and setup.
Architecture Guide: DDD, Clean Architecture, and project structure.

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.