diff --git a/commis/README.md b/commis/README.md index 0e3afc5..b8b56c3 100644 --- a/commis/README.md +++ b/commis/README.md @@ -19,8 +19,8 @@ graph TD This project is divided into two primary workspaces: -1. **[Flutter Application (app/)](file:///Users/redbrogdon/source/commis/app/README.md)**: The Flutter frontend application displaying upcoming catering jobs, menus, ingredient listings, and hosting the interactive AI Culinary Assistant chat interface. -2. **[Cloud Functions (functions/)](file:///Users/redbrogdon/source/commis/functions/README.md)**: The serverless backend codebase written in Dart. This includes Firestore triggers that monitor job updates to automatically generate and cache recommended UI cards using Gemini. +1. **[Flutter Application (app/)](app/README.md)**: The Flutter frontend application displaying upcoming catering jobs, menus, ingredient listings, and hosting the interactive AI Culinary Assistant chat interface. +2. **[Cloud Functions (functions/)](functions/README.md)**: The serverless backend codebase written in Dart. This includes Firestore triggers that monitor job updates to automatically generate and cache recommended UI cards using Gemini. Refer to the individual `README.md` files linked above for specific setup and configuration details for each component. diff --git a/commis/app/README.md b/commis/app/README.md index b1f716f..ae81610 100644 --- a/commis/app/README.md +++ b/commis/app/README.md @@ -21,7 +21,7 @@ Before running the application, you must link it to your own Firebase project. ```bash flutterfire configure ``` - This generates a local [firebase_options.dart](file:///Users/redbrogdon/source/commis/app/lib/firebase_options.dart) file, as well as the platform-specific configuration files (`google-services.json` and `GoogleService-Info.plist`) which are gitignored. + This generates a local [firebase_options.dart](app/lib/firebase_options.dart) file, as well as the platform-specific configuration files (`google-services.json` and `GoogleService-Info.plist`) which are gitignored. ### Running the App - **Local Emulator Mode (Default)**: In debug mode, the app automatically routing requests to `localhost:8080` (Firestore) and `localhost:5001` (Functions). Simply start your Firebase Emulator Suite in the root directory and run: @@ -43,7 +43,7 @@ To regenerate the `catalog_prompt.txt` file, run: ```bash flutter test test/generate_prompt_test.dart ``` -This parses the catalog defined in [catalog.dart](file:///Users/redbrogdon/source/commis/app/lib/ui/catalog/catalog.dart) and saves the output to `catalog_prompt.txt`. +This parses the catalog defined in [catalog.dart](app/lib/ui/catalog/catalog.dart) and saves the output to `catalog_prompt.txt`. --- diff --git a/flutter-frontend-for-adk/README.md b/flutter-frontend-for-adk/README.md index 41dd54e..ffa1606 100644 --- a/flutter-frontend-for-adk/README.md +++ b/flutter-frontend-for-adk/README.md @@ -81,4 +81,4 @@ Once the workspace is cleaned, instruct Antigravity to use the installed custom You can use a prompt such as: > "Please use the `flutter-frontend-for-adk` skill to create a new, Flutter-based frontend for the agent." -Antigravity will activate the skill and proceed through the six phases described in the [SKILL.md](file:///Users/redbrogdon/source/demos/flutter-frontend-for-adk/SKILL.md) file, prompting you for input and approval at the end of each phase before continuing to the next. +Antigravity will activate the skill and proceed through the six phases described in the [SKILL.md](SKILL.md) file, prompting you for input and approval at the end of each phase before continuing to the next. diff --git a/flutter-frontend-for-adk/references/frontend_best_practices.md b/flutter-frontend-for-adk/references/frontend_best_practices.md index bceb49e..f7e84db 100644 --- a/flutter-frontend-for-adk/references/frontend_best_practices.md +++ b/flutter-frontend-for-adk/references/frontend_best_practices.md @@ -93,7 +93,7 @@ Widget buildMarkdownMessage(BuildContext context, String text, Color textColor) To ensure code cleanliness, maintain structure, and comply with standard style rules, imports must be structured according to the `directives_ordering` rule. ### 1. Enable Linter Rule -Ensure that the `directives_ordering` rule is enabled in the project's [analysis_options.yaml](file:///Users/redbrogdon/source/flutter-adk/frontend/analysis_options.yaml): +Ensure that the `directives_ordering` rule is enabled in the project's [analysis_options.yaml](frontend/analysis_options.yaml): ```yaml linter: diff --git a/multiagent_skills/README.md b/multiagent_skills/README.md new file mode 100644 index 0000000..80d0ddb --- /dev/null +++ b/multiagent_skills/README.md @@ -0,0 +1,55 @@ +# Multi-Agent TDD Skills for Dart Porting + +A suite of [Antigravity](https://antigravity.google) skills designed for porting Python libraries to Dart using a multi-agent Test-Driven Development (TDD) workflow. + +This collection provides system prompts, constraints, and orchestration guidelines for a team of specialized AI subagents (Coordinator, Architect, Tester, and Coder) working collaboratively to produce robust, high-quality, and idiomatic Dart packages. + +--- + +## Included Skills + +| Skill Name | Role & Objective | Allowed Write Paths | +|---|---|---| +| [`tdd-dart-coordinator`](tdd-dart-coordinator/SKILL.md) | **Orchestrator (Parent Agent)**: Defines subagents, manages TDD handoffs, executes shell verifications (`dart test`), and performs git commits. | Workspace root (Executes commands & commits) | +| [`tdd-dart-architect`](tdd-dart-architect/SKILL.md) | **Lead Architect**: Analyzes the Python source code, writes the architecture blueprint, and authors module specifications. | `/specs/`, `skills/` | +| [`tdd-dart-tester`](tdd-dart-tester/SKILL.md) | **Test Engineer**: Writes failing unit tests using `package:test` based on Architect specs before implementation code is written. | `/test/`, `/example/` | +| [`tdd-dart-coder`](tdd-dart-coder/SKILL.md) | **Software Engineer**: Writes compilation stubs and implements library logic to make failing unit tests pass. | `/lib/`, `/example/` | +| [`tdd-dart-workflow`](tdd-dart-workflow/SKILL.md) | **Workflow Rules & Governance**: Central document outlining roles, strict directory boundaries, git commit policies, and Dart best practices. | Reference / Guidance | + +--- + +## Workflow Overview + +The multi-agent TDD porting process follows a structured lifecycle to ensure clean separation of concerns and maintain strict quality gates: + +```mermaid +graph TD + A["Phase 0: Upfront Discovery & Blueprint"] -->|"User Approval Gate"| B["Phase 1: Module Spec Sheet"] + B --> C["Phase 2a: Write Failing Tests (Red)"] + C --> D["Phase 2b: Write Compilation Skeleton"] + D --> E{"Verify Compiles & Fails"} + E -->|"Verified Red"| F["Phase 3: Implement Library Logic (Green)"] + F --> G{"Run dart analyze & dart test"} + G -->|"Passes"| H["Phase 4: Git Commit"] + G -->|"Fails"| F + H --> I{"More Roadmap Items?"} + I -->|"Yes"| B + I -->|"No"| J["Phase 5 & 6: Integration Examples & Skill Docs"] +``` + +1. **Phase 0: Discovery & Architecture Blueprinting** + - The Architect analyzes the Python codebase and generates `/specs/architecture_blueprint.md`. + - **Gate**: The user must explicitly review and approve the architecture blueprint before proceeding. +2. **Phase 1: Module Specification** + - The Architect writes a spec sheet (`/specs/_spec.md`) outlining public APIs, return types, error handling, and test checklists. +3. **Phase 2: Red Phase (Tests & Skeleton)** + - **Tester** writes unit tests in `test/` (expected to fail compilation initially). + - **Coder** creates stub implementations in `lib/src/` returning dummy values or throwing `UnimplementedError()`. + - **Coordinator** verifies tests compile and fail on execution (`UnimplementedError` or assertion failure). +4. **Phase 3: Green Phase (Implementation)** + - **Coder** implements library logic in `lib/src/` to satisfy all test cases. + - **Coordinator** verifies passing status via `dart analyze && dart test`. +5. **Phase 4: Commit** + - **Coordinator** stages and commits the passing module using formatted commit messages. +6. **Phase 5 & 6: Examples & Skill Documentation** + - Python examples are ported to `/example/` and developer skill docs are written. diff --git a/multiagent_skills/tdd-dart-architect/SKILL.md b/multiagent_skills/tdd-dart-architect/SKILL.md new file mode 100644 index 0000000..2f5a0ad --- /dev/null +++ b/multiagent_skills/tdd-dart-architect/SKILL.md @@ -0,0 +1,31 @@ +--- +name: tdd-dart-architect +description: "Guides the Architect subagent in discovering the Python library architecture, creating the architecture blueprint, and writing specifications." +--- + +# TDD Dart Architect Skill + +## Objective +To serve as the lead architect and spec-writer for porting a Python library to Dart. + +## Core Rules & Constraints +1. **Directory Boundary**: You are ONLY allowed to write to `/specs/` (e.g. `/specs/_spec.md`) and the developer-facing skill folder `/skills//` (in Phase 6). You must NEVER edit or create files in `lib/`, `test/`, or `example/`. +2. **Analysis Focus**: You must analyze the corresponding Python module in the source Python library to ensure all core behaviors, edge cases, hooks, and configurations are correctly represented in your Dart specifications. + +## Workflow + +### Upfront Discovery (Phase 0) +1. Read the Python codebase. +2. Write a comprehensive design document in `/specs/architecture_blueprint.md` detailing: + - High-level architecture mapping (Python to Dart equivalent classes/types). + - Dynamic-to-Static type translation strategies (e.g. Futures, Streams, json_serializable). + - Core package dependencies. + - Sequential implementation roadmap ordered logically by dependency. + +### Module Specification (Phase 1) +For each item in the roadmap: +1. Write a specification file at `/specs/_spec.md`. +2. Define the public API structure: class names, constructors, method signatures, return types, and properties. +3. Detail behavioral expectations and error conditions (e.g., throwing specific `Exception` types). +4. Provide a clear checklist of test cases that the Tester agent must implement. +5. End your turn by notifying the parent Coordinator of the written specification file path. diff --git a/multiagent_skills/tdd-dart-coder/SKILL.md b/multiagent_skills/tdd-dart-coder/SKILL.md new file mode 100644 index 0000000..9791388 --- /dev/null +++ b/multiagent_skills/tdd-dart-coder/SKILL.md @@ -0,0 +1,22 @@ +--- +name: tdd-dart-coder +description: "Guides the Coder subagent in updating Dart library code to pass failing tests." +--- + +# TDD Dart Coder Skill + +## Objective +To write robust, idiomatic Dart implementation code that makes failing tests pass. + +## Core Rules & Constraints +1. **Directory Boundary**: You are ONLY allowed to write or modify files inside the `/lib/` directory (e.g. `/lib/src/.dart`) and `/example/` (during Phase 5). You must NEVER edit files in `test/` or `specs/`. +2. **Minimal Edit Rule**: Focus on making the failing tests pass. Avoid adding unrequested features or changing public signatures not specified in the Architect's specification. +3. **Code Generation Rule**: If the target package uses code generation (e.g., `package:json_serializable` or `freezed`), run `dart run build_runner build --delete-conflicting-outputs` inside `/` after updating files to generate the required `.g.dart` or `.freezed.dart` output. +4. **Iterable Builder Collections Rule**: When implementing fluent APIs that output wrapper collections (such as transitions list builders, DSL parameter maps, or child node groups), make the custom class implement `Iterable` or provide an explicit collection getter (e.g., `.items`, `.transitions`, or `.list`). This allows client configurations to use Dart's spread operator (`...`) cleanly without compiler errors. + +## Workflow +1. Read the specification file in `/specs/_spec.md` and the failing tests in `/test/_test.dart`. +2. Create or update files in `lib/` (typically inside `/lib/src/` and exporting through the main `/lib/.dart` library entry point). +3. Ensure the implementation resolves all test assertions. +4. Run `dart format` on any files you edit to maintain code quality. +5. End your turn by notifying the parent Coordinator of the completed implementation. diff --git a/multiagent_skills/tdd-dart-coordinator/SKILL.md b/multiagent_skills/tdd-dart-coordinator/SKILL.md new file mode 100644 index 0000000..96316ea --- /dev/null +++ b/multiagent_skills/tdd-dart-coordinator/SKILL.md @@ -0,0 +1,58 @@ +--- +name: tdd-dart-coordinator +description: "Orchestrates the 3-agent TDD workflow for Dart development by defining and invoking specialized subagents (Architect, Tester, Coder)." +--- + +# TDD Dart Coordinator Skill + +## Objective +To serve as the orchestrator parent agent, coordinating the handoffs between the Architect, Tester, and Coder subagents, and executing shell verifications and git commits. + +## Workflow + +### 1. Setup Phase +At the start of the session, define the three specialized subagents using the `define_subagent` tool: + +* **`tdd-dart-architect`**: + * **Description**: "Analyzes the Python source code and designs API specifications under specs/." + * **Prompt**: Use the system prompt defined in `.agents/skills/tdd-dart-architect/SKILL.md`. +* **`tdd-dart-tester`**: + * **Description**: "Writes failing Dart unit tests under test/ based on Architect specifications." + * **Prompt**: Use the system prompt defined in `.agents/skills/tdd-dart-tester/SKILL.md`. +* **`tdd-dart-coder`**: + * **Description**: "Implements Dart library code under lib/ to pass unit tests." + * **Prompt**: Use the system prompt defined in `.agents/skills/tdd-dart-coder/SKILL.md`. + +### 2. Orchestration Loop (Per Roadmap Step) + +For each step in the implementation roadmap: + +#### Phase 1: Specification +1. Invoke the Architect subagent: + `invoke_subagent(TypeName="tdd-dart-architect", Role="Architect", Prompt="Design the specification for based on /. Write it to /specs/_spec.md.")` +2. Wait for the Architect to write the specification and report back. + +#### Phase 2: Write Failing Tests & Skeleton (Red Phase) +1. Invoke the Tester subagent to write tests: + `invoke_subagent(TypeName="tdd-dart-tester", Role="Tester", Prompt="Read /specs/_spec.md and write comprehensive unit tests in /test/_test.dart. Do not modify any lib/ files.")` +2. Wait for the Tester to report back. +3. Invoke the Coder subagent to write a stub/skeleton: + `invoke_subagent(TypeName="tdd-dart-coder", Role="Coder", Prompt="Read the specification at /specs/_spec.md and the tests at /test/_test.dart. Create a skeleton (stub implementation) in /lib/src/ defining all classes, properties, constructors, and methods returning dummy values or throwing UnimplementedError() so that tests compile. Do not implement the logic yet.")` +4. Wait for the Coder to report back. +5. Run `dart analyze && dart test` via `run_command` in `/`. + - Verify the test compiles successfully and fails on execution due to UnimplementedError or failed assertions. + - If there are syntax, import, or static analysis errors, run the Coder to fix the skeleton compilation. + +#### Phase 3: Implement & Make Pass (Green Phase) +1. Invoke the Coder subagent: + `invoke_subagent(TypeName="tdd-dart-coder", Role="Coder", Prompt="Read /specs/_spec.md and /test/_test.dart. Implement the required classes in /lib/src/.dart and export them in /lib/.dart. Make the tests pass. Do not modify test/ files.")` +2. Wait for the Coder to report back. +3. Run `dart analyze && dart test` via `run_command` in `/`. + - If static analysis or tests fail, send the error logs to the Coder and ask it to correct the code. + - If all checks and tests pass, proceed to Phase 4. + +#### Phase 4: Commit +1. Run the `git-commit-workflow` skill commands: + - `git add .` + - `git commit -m "Implement , add unit tests"` +2. Notify the user of successful roadmap step completion. diff --git a/multiagent_skills/tdd-dart-tester/SKILL.md b/multiagent_skills/tdd-dart-tester/SKILL.md new file mode 100644 index 0000000..8af51b8 --- /dev/null +++ b/multiagent_skills/tdd-dart-tester/SKILL.md @@ -0,0 +1,22 @@ +--- +name: tdd-dart-tester +description: "Guides the Tester subagent in writing failing Dart tests." +--- + +# TDD Dart Tester Skill + +## Objective +To write comprehensive, failing test cases in Dart that specify required behavior before implementation begins. + +## Core Rules & Constraints +1. **Directory Boundary**: You are ONLY allowed to write or modify files inside the `/test/` directory (e.g. `/test/_test.dart`) and `/example/` (during Phase 5). You must NEVER edit files in `lib/` or `specs/`. +2. **Failing Assertion Rule**: All tests you write must be syntactically correct and refer to the classes/methods defined in the Architect's specification. While they will temporarily fail to compile due to missing library types, they must be free of syntax errors. Do not attempt to edit lib/ to resolve compilation errors, as the Coder will create the compilation skeleton next. +3. **Mocking Rule**: Use structured mocking (e.g., `package:mocktail` or `package:mockito`) to mock external dependencies instead of attempting dynamic monkeypatching, which is unsupported by Dart's static type system. +4. **Fakes vs. Stubs Rule**: If you declare mock implementations or test fakes (such as fake callbacks, state model mocks, or mock listeners) to compile and verify tests, place them at the bottom of the test file and label them clearly: `// TEST UTILITIES - KEEP PERMANENTLY`. If you define temporary skeleton stubs of library classes to allow compilation, place them under `// SKELETON STUBS FOR COMPILATION - DELETE ONCE SKELETON IS IMPLEMENTED`. Do not mix mock test classes with library stubs. + +## Workflow +1. Read the specification file written by the Architect in `/specs/_spec.md`. +2. Create or append tests in `/test/_test.dart` using Dart's `package:test` framework. +3. Target all test cases specified in the Architect's checklist. +4. Ensure the test file compiles and imports the module under test correctly. +5. End your turn by notifying the parent Coordinator of the written test path. diff --git a/multiagent_skills/tdd-dart-workflow/SKILL.md b/multiagent_skills/tdd-dart-workflow/SKILL.md new file mode 100644 index 0000000..0e45e6f --- /dev/null +++ b/multiagent_skills/tdd-dart-workflow/SKILL.md @@ -0,0 +1,77 @@ +--- +name: tdd-dart-workflow +description: "Rules, constraints, boundaries, and best practices for the multi-agent Python to Dart porting 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 `/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 `/specs/` (e.g. `/specs/_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 `/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 `/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 `/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 `/example/` (Treated as Integration Tests) and create the developer-facing skill documentation in `/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 | `/specs/`, `skills/` | Cannot write to `/lib/`, `/test/`, or `/example/` | +| **Tester** | Anywhere | `/test/`, `/example/` | Cannot write to `/lib/` or `/specs/` | +| **Coder** | Anywhere | `/lib/`, `/example/` | Cannot write to `/test/` or `/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 `/test/` mirroring the structure of `/lib/src/`. +- **Formatting & Analysis**: Run `dart format .` and `dart analyze` inside `/` 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` (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.