utakata 0.5.2

A Dart CLI tool for building Flutter apps with pluggable architecture templates (Clean Architecture, MVVM, and more), designed for human and AI agent collaboration.

utakata

utakata is a Dart CLI tool by utakata code, designed for humans and AI agents to collaboratively build Flutter applications through specification-driven development.

日本語のドキュメントは README_ja.md を参照してください。

---

Features

• 🤖 AI-Native Development: Commands designed for both humans and AI agents. Combined with .agent/ rules and AI/guides/, AI can develop without architectural drift.
• 🏗️ Multi-Architecture Support: Ships with Clean Architecture (4-layer) and MVVM (3-layer) out of the box. Create your own via utakata arch create or arch_definition.yaml.
• 🔍 Validate Everything: utakata validate detects naming rule violations and directory structure violations — based on your arch_definition.yaml.
• 📋 Specification-Driven: Define features in feature_request.yaml, generate a plan, scaffold all layers at once.
• 📊 File-Level Diff: utakata diff compares planned vs actual file names, not just directories — enabling precise progress tracking.
• 🌐 Internationalized: CLI messages support English and Japanese.

---

Installation

dart pub global activate utakata

Make sure $HOME/.pub-cache/bin is added to your PATH.

---

Quick Start

# Create a new Flutter project (includes .agent/ and AI/ templates)
utakata create my_app --org com.example

# Define features in AI/specs/feature_request.yaml, then:
utakata plan          # Generate architecture plan
utakata feature init  # Scaffold all features at once

# Validate structure and naming rules
utakata validate

---

Built-in Architectures

utakata arch list    # List all available architectures
utakata arch show mvvm  # Show layer structure and naming rules

Architecture	Layers	Description
clean_architecture	4	Domain → Infrastructure → Application → Presentation
mvvm	3	Model → ViewModel → View

Specify in feature_request.yaml:

project:
  name: "my_app"
  architecture: "mvvm"     # Project-wide default

features:
  todo:
    entity: todo
    # architecture: "clean_architecture"  # Per-feature override

---

Command Reference

utakata create

Creates a new Flutter project with the selected architecture base structure and AI workflow templates.

utakata create my_app --org com.example

utakata plan

Reads AI/specs/feature_request.yaml and dynamically generates a structured architecture plan based on your arch_definition.yaml.

utakata plan

utakata feature

# Add a single feature
utakata feature add <feature_name> [--permission user|admin|shared|direct]

# Bulk-generate all features defined in plan_architecture.yaml
utakata feature init

utakata validate

Validates naming rules and directory structure against arch_definition.yaml. Auto-detects architecture from feature_request.yaml.

utakata validate
utakata validate --arch mvvm  # Explicit override

utakata scan / diff / check

utakata scan    # Snapshot the current lib/ structure
utakata diff    # Compare plan vs actual (directories + files)
utakata check   # Run diff and report violations

utakata arch

utakata arch list              # List available architectures
utakata arch show <id>         # Show layer structure and naming rules
utakata arch create <id>       # Create a custom architecture locally
utakata arch export <id>       # Export raw YAML definition

utakata status

Analyzes Flutter version, lint status, and architecture diff in one command.

utakata status

---

For AI Agents

The generated project includes .agent/rules/flutter.md and AI/guides/ with detailed workflow guides.

Always use the utakata CLI to extend the project structure rather than creating files manually. Run utakata validate before committing to ensure zero violations.

---

Architecture

utakata itself is implemented using Clean Architecture:

packages/utakata_code/lib/src/
├── 0_templates/     # Architecture templates (clean_architecture, mvvm)
├── 1_domain/        # Entities, Repository interfaces, Use cases
├── 2_infrastructure/ # Filesystem, YAML, Process data sources
└── 3_application/   # Command handlers, Runner

---

License

This project uses a dual license:

1. Open Source (GNU GPL v3) Free to use, fork, and modify for personal/open-source projects under the GNU GPL v3.

2. Commercial Use Commercial use of this tool or any code generated by it requires a separate commercial license. Contact the author (@code_utakata) for details.

---

Links

• Repository
• pub.dev
• X (Twitter) @code_utakata
• utakata code