tdd-dart-workflow

# Python to Dart Porting Implementation Rules These rules govern the development, design, and TDD workflow of porting a Python library to Dart. All agents running in this workspace must adhere strictly to these guidelines. --- ## 1. Multi-Agent TDD Workflow Development proceeds in structured TDD cycles coordinated by the parent agent: ### Phase 0: Discovery & Architecture Blueprinting * **Objective**: The Architect maps Python paradigms to Dart and produces `<dart_package_dir>/specs/architecture_blueprint.md`. * **Gate**: The User must explicitly approve the blueprint before TDD cycles begin. ### Phase 1: Design Specification * **Objective**: The Architect writes a targeted spec sheet under `<dart_package_dir>/specs/` (e.g. `<dart_package_dir>/specs/<module_name>_spec.md`) describing the interfaces, types, behaviors, and expected test cases for a single module. ### Phase 2: Write Failing Tests & Skeleton (Red Phase) * **Step 2a (Tester)**: Writes unit tests in `<dart_package_dir>/test/` based on the spec (compilation errors targeting missing classes are expected here). * **Rule (Test Fakes vs Stubs)**: Label fakes/mocks kept permanently inside the test file as `// TEST UTILITIES - KEEP PERMANENTLY`. Label temporary stub classes that will be moved to `lib/` as `// SKELETON STUBS FOR COMPILATION - DELETE ONCE SKELETON IS IMPLEMENTED`. * **Step 2b (Coder)**: Creates a skeleton (stub implementation) in `<dart_package_dir>/lib/src/` defining all required classes, constructors, methods, and properties, but returning dummy values or throwing `UnimplementedError()`. * **Verification**: The Coordinator runs `dart test` and verifies the test compiles successfully and fails on execution due to `UnimplementedError` or assertion failure, NOT syntax or import errors. * **Clean Up**: Once the Coder implements the skeleton, the Coordinator removes the compilation stubs from the test file while preserving the permanent test utilities. ### Phase 3: Implement & Make Pass (Green Phase) * **Objective**: The Coder reads the spec and test, and updates the library implementation in `<dart_package_dir>/lib/` to make all tests pass. * **Verification**: The Coordinator runs `dart test` and verifies the tests pass successfully. ### Phase 4: Commit & Record * **Objective**: The Coordinator stages and commits both the new test and the code. ### Phase 5 & 6: Integration & Documentation * Port Python examples to `<dart_package_dir>/example/` (Treated as Integration Tests) and create the developer-facing skill documentation in `<dart_package_dir>/skills/`. --- ## 2. Agent Constraints & Boundaries To preserve strict roles, agents are restricted to write to specific directories: | Agent Role | Allowed Read Path | Allowed Write Path | Forbidden Actions | |---|---|---|---| | **Coordinator (Parent)** | Anywhere | Anywhere | Direct code modifications (delegates to Coder/Tester instead) | | **Architect** | Anywhere | `<dart_package_dir>/specs/`, `skills/` | Cannot write to `<dart_package_dir>/lib/`, `<dart_package_dir>/test/`, or `<dart_package_dir>/example/` | | **Tester** | Anywhere | `<dart_package_dir>/test/`, `<dart_package_dir>/example/` | Cannot write to `<dart_package_dir>/lib/` or `<dart_package_dir>/specs/` | | **Coder** | Anywhere | `<dart_package_dir>/lib/`, `<dart_package_dir>/example/` | Cannot write to `<dart_package_dir>/test/` or `<dart_package_dir>/specs/` | *Note: The Coordinator is the only agent allowed to execute Git operations or run arbitrary tests in the shell.* --- ## 3. Git Commit Rules - **Execution**: Only the Coordinator agent (or the user) runs Git commands. Subagents have no Git permissions. - **Timing**: Commits are made only when a TDD cycle is successfully completed (tests are Green) or a refactoring pass is verified. No commits of broken code. - **Formatting**: Must adhere to the `git-commit-workflow` rules: - Capitalize the first word. - Keep under 60 characters. - Pithy, paratactic descriptions (e.g., `Add AgentConfig properties, write unit tests`). --- ## 4. Dart Best Practices - **Strict Types**: Always use explicit type annotations for public APIs (no raw `dynamic` unless required by external JSON parsing). Avoid `dynamic` collections (use generics or shared interface classes). - **Asynchrony**: Use Dart `Future` for async values and `Stream` for streaming data (e.g. async event stream). - **Unit Testing**: Use `package:test` for writing tests. Place tests in `<dart_package_dir>/test/` mirroring the structure of `<dart_package_dir>/lib/src/`. - **Formatting & Analysis**: Run `dart format .` and `dart analyze` inside `<dart_package_dir>/` before verifying implementations. - **Code Generation**: Use `package:json_serializable` or `freezed` via `build_runner` for serialization. Avoid writing custom JSON parser logic unless necessary. - **Mocking**: Use structured mocking libraries like `package:mocktail` or `package:mockito` instead of patching dynamic properties. - **Abstract Interface Pattern**: Instead of dynamic property/method checks (`hasattr`), use Dart `abstract interface class` definitions, or explicit callback delegates to achieve same results type-safely. - **Iterable Custom Builders**: If a custom builder class represents a list or collection of items that Python would unpack/spread, make the class implement `Iterable<T>` (forwarding its iterator to the underlying list) or expose an explicit collection getter (e.g. `.transitions`, `.items`) so that Dart's spread operator (`...`) can be used cleanly in configurations.