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.
🏗️ Architecture-Agnostic: No longer hardcoded to Clean Architecture. Define your own architecture via 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.
🌐 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

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 generates a structured architecture plan.

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.

utakata validate

`utakata scan / diff / check`

utakata scan    # Snapshot the current lib/ structure
utakata diff    # Compare plan vs actual structure
utakata check   # Run diff and report violations

`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/
├── 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:

Open Source (GNU GPL v3) Free to use, fork, and modify for personal/open-source projects under the GNU GPL v3.
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.