---

📖 Welcome

Transform your development workflow with intelligent code generation, analysis, and architectural guidance. The Claude Dart/Flutter Toolkit generates a "Project Intelligence Core"—a highly contextual system prompt that ensures Claude fundamentally understands your project's unique architecture, state management patterns, and team size before it writes a single line of code.

✨ Key Features

• 🎮 Interactive CLI: A beautiful, terminal UI that asks you exactly what your project needs.
• 🧠 Project Intelligence Core: Generates a robust claude.md file that acts as a strict System Prompt for Claude, injecting detailed architectural constraints (Clean Architecture, MVVM, Hexagonal, etc.) directly into its context window.
• 🏗️ 8-Layer Foundation System: Extensible domain knowledge, coding rules, and generation templates organized cleanly.
• 🩺 Automated Visual Health Checks: Run doctor at any time to verify dependencies, Toolkit health, and environment readiness.

---

🚀 Installation & Setup

1. Global Installation

Install the toolkit globally on your machine using Dart pub:

dart pub global activate --source path .
# Or install from pub.dev:
# dart pub global activate claude_toolkit

2. Initialization Workflow

Navigate to the root of your Dart or Flutter project and run:

claude_toolkit init

The Interactive CLI will guide you through:

1. Confirming your project type (Dart, Flutter, Package).
2. Providing a 1-sentence description of your project's business domain.
3. Indicating the project size and team scope.
4. Selecting strict Architectural approaches (e.g., Clean Architecture).
5. Picking your State Management (e.g., BLoC, Riverpod).

3. Verification

Run the automated health checker at any time to ensure your environment and toolkit are configured correctly:

claude_toolkit doctor

---

🧠 The Project Intelligence Core (claude.md)

When you complete the init command, the toolkit generates a claude.md file at the root of your project.

This is not just documentation. It is a System Prompt.

By pointing Claude to this file (or including it in its context window), it learns the strict constraints of your application. For example, if you selected Clean Architecture and BLoC, the claude.md strictly commands Claude:

• Inner layers (Domain) MUST NOT depend on outer layers.
• Controllers MUST NEVER depend on dart:ui.
• Do NOT use setState for business logic.

When you ask Claude: "Generate a User Login feature", it no longer guesses how to build it. It builds it exactly how you configured the toolkit.

---

🏗️ Deep Dive: The 8-Layer Foundation Architecture

The toolkit provides Claude with deep, structural knowledge through a local foundation folder (accessible via the paths listed in your generated claude.md).

Foundation Layers:
├── 🛠️ Skills     - Core functionality (template engine, file ops, validation)
├── 📝 Templates  - Code generation templates (Dart, Flutter, base)
├── 🧠 Contexts   - Domain knowledge (patterns, frameworks, practices)
├── 📏 Rules      - Quality standards, strict linting, and conventions
├── ⚡ Commands   - Executable command handlers
├── 🔄 Workflows  - Multi-step process orchestration
├── 📜 Scripts    - Automation utilities
└── 🪝 Hooks      - Event-driven integrations (pre/post code generation)

By reading these directories, Claude understands not just the rules, but the tools available to automate your workspace.

---

🧑‍💻 Usage Examples

Once your project is initialized, you can start talking to Claude like a senior pair-programmer.

Code Generation

"Hey Claude, read claude.md. Generate a user repository following our Clean Architecture rules and BLoC state management."

Architecture Analysis

"Claude, analyze /lib/features/auth/ against the strict constraints defined in my claude.md. Is there any bleeding of the Presentation layer into the Domain layer?"

Refactoring

"Take this old setState spaghetti code in login_screen.dart and refactor it into proper Cubits as dictated by the Project Intelligence Core."

---

�️ Customizing for Your Team

The toolkit is designed to be highly extensible. You can define company-specific rules or custom generation templates.

1. Custom Templates: Add your company's proprietary code generators to foundation/shared/templates/.
2. Custom Rules: Add strict styling or package constraints to the Rules layer, ensuring AI never hallucinations outdated packages.

---

🐛 Troubleshooting

Error / Issue	Solution
Command Not Found	Ensure your Dart global package path is added to your environment variables (~/.pub-cache/bin). Run dart pub global list to verify.
Missing Foundation Directories	Run claude_toolkit doctor. It will print exact missing paths. Reinstalling the toolkit globally usually resolves this.
Debugging Toolkit Issues	Run any command with the --verbose flag for deep logging (claude_toolkit init --verbose).

---

🤝 Contributing & Community

Contributions are highly welcome! To get started:

1. Fork the repository.
2. Read the ARCHITECTURE.md to understand our clean-CLI principles.
3. Submit a PR focusing on:
   • New standard Templates
   • Improved Context prompts
   • Added interactive CLI features