Dart Development Guidelines

Guidelines specific to Dart package development in the Tom Framework workspace.

---

Documents

Document	Purpose
coding_guidelines.md	Naming conventions, error handling, code patterns
clean_code_principles.md	DRY, abstractions, library extraction, code smells
unit_tests.md	Test structure, matchers, mocking patterns
examples.md	Example file creation and organization
api_summary_creation.md	API documentation format
api_reference_creation.md	Combined PDF reference generation
project_refactoring.md	Refactoring workflow for Dart projects
tool_installation.md	One-time setup for CLI tools (PATH, shell functions, tokens)
pub_cache_troubleshooting.md	Recognising and repairing pub-cache damage (the two shapes, and why dart pub get only fixes one)
test_tracking.md	Testkit CLI usage and test tracking
using_issuekit_and_testkit.md	Quick reference for issue and test tools
tests_buildtools.md	Build tools testing with zom_ prefix
new_project_setup.md	New Dart project creation checklist
project_republishing.md	Pub.dev publishing workflow

---

Quick Reference

Standard Commands

dart pub get              # Get dependencies
dart analyze              # Check for errors
dart test                 # Run tests
dart run build_runner build --delete-conflicting-outputs  # Code generation

Test Execution

testkit :test             # Run tests with baseline tracking
testkit :baseline         # Create new test baseline

Package Structure

{project}/
├── lib/
│   ├── src/              # Implementation (private)
│   └── {package}.dart    # Public API (barrel file)
├── test/
│   └── *_test.dart       # Test files
├── example/
│   └── *.dart            # Usage examples
├── doc/
│   └── *.md              # User documentation
└── _copilot_guidelines/
    └── index.md          # Project guidelines (links here)

---

Applies To

All Dart packages in the workspace. Projects reference these guidelines from their local _copilot_guidelines/index.md.