diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index 31c0de9..9fe7f87 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -39,6 +39,18 @@ "authentication": "ON_INSTALL" }, "category": "Productivity" + }, + { + "name": "dart-package-kit", + "source": { + "source": "local", + "path": "./plugins/dart-package-kit" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Coding" } ] } diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 5ca3d7d..a15b621 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -18,7 +18,12 @@ { "name": "design-kit", "source": "./plugins/design-kit" + }, + { + "name": "dart-package-kit", + "source": "./plugins/dart-package-kit", + "description": "Package-specific guidance for ACK validation, Noir terminal apps, Mix styling, and Remix Flutter components." } ], - "description": "Private Concepta plugins for product and engineering workflows." + "description": "Product, engineering, design, and Dart package plugins from Concepta." } diff --git a/AGENTS.md b/AGENTS.md index a4aa7d0..0ff8ab3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # Agent Plugins -This repository owns Concepta's Product, Engineering, and Design kits for Codex +This repository owns Concepta's Product, Engineering, Design, and Dart Package kits for Codex and Claude Code. Maintain these kits directly; do not introduce upstream skill tracking, import/merge workflows, or synchronization with another skills repository. @@ -13,7 +13,9 @@ tracking, import/merge workflows, or synchronization with another skills reposit breakdowns distinct from implementation plans; no automatic handoff is required. - Design Kit owns interface design, critique, accessibility, UX copy, and study planning. Product Kit owns research synthesis; Engineering Kit owns functional verification. -- Dart/Flutter is an external official plugin managed by the client. Keep its +- Dart Package Kit owns workflows for ACK, Noir, Mix, and Remix. Use the consuming + project's resolved package as the API reference. Link to package-maintained guides and skills. +- General Dart/Flutter is an external official plugin managed by the client. Keep its skills and MCP configuration out of these kits; see docs/external-plugins.md. ## Author and maintain diff --git a/README.md b/README.md index 2f12959..e583126 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,7 @@ repository; there is no upstream import, tracking, or merge workflow. | --- | --- | --- | --- | | [Product Kit](plugins/product-kit/README.md) | Research, requirements, PRDs, and delivery breakdowns | 6 | 0.3.2 | | [Engineering Kit](plugins/engineering-kit/README.md) | Technical decisions, implementation, reviews, PR/CI workflows, writing, and verification | 16 | 0.2.0 | +| [Dart Package Kit](plugins/dart-package-kit/README.md) | ACK schemas, Noir terminal apps, Mix styling, and Remix UI components | 4 | 0.1.0 | | [Design Kit](plugins/design-kit/README.md) | Interface design, critique, accessibility, UX copy, and research planning | 10 | 0.1.1 | Product Kit owns the shared requirements, questions, and decisions. Engineering @@ -16,7 +17,7 @@ Kit turns settled scope into implementation work without creating a second requirement baseline. Use the skill that matches the task; no automatic sequence or handoff is required. -A [flattened source snapshot](agent-plugins.flattened.md) is available for review. +An [earlier snapshot of the Product, Engineering, and Design kits](agent-plugins.flattened.md) is available for historical review. The plugin directories above contain the current skills. Binary assets are listed by hash; install plugins from their folders, not the snapshot. ## Install @@ -30,6 +31,7 @@ codex plugin marketplace add https://github.com/btwld/agent-plugins.git codex plugin add product-kit@conceptadev codex plugin add engineering-kit@conceptadev codex plugin add design-kit@conceptadev +codex plugin add dart-package-kit@conceptadev ``` ### Claude Code @@ -39,6 +41,7 @@ claude plugin marketplace add https://github.com/btwld/agent-plugins.git claude plugin install product-kit@conceptadev claude plugin install engineering-kit@conceptadev claude plugin install design-kit@conceptadev +claude plugin install dart-package-kit@conceptadev ``` Start a new session afterward. In Codex, request the relevant skill. Claude @@ -46,8 +49,8 @@ commands include `/product-kit:write-prd`, `/product-kit:write-wbs`, and `/engineering-kit:writing-plans`. Use one active provider for each plugin namespace; cloning or maintaining this repository does not replace installed plugins. -Dart/Flutter uses a separate official provider. See [Dart/Flutter setup](docs/external-plugins.md). -Neither kit duplicates its skills or MCP server. +For general Dart and Flutter tasks, install the official provider. Dart Package +Kit adds workflows for four specific packages alongside it. [Dart and Flutter setup](docs/external-plugins.md) ## Maintain @@ -77,6 +80,7 @@ python3 -m unittest discover -s tests claude plugin validate plugins/product-kit --strict claude plugin validate plugins/engineering-kit --strict claude plugin validate plugins/design-kit --strict +claude plugin validate plugins/dart-package-kit --strict claude plugin validate . --strict ``` diff --git a/docs/external-plugins.md b/docs/external-plugins.md index 6c26b30..e0b4c25 100644 --- a/docs/external-plugins.md +++ b/docs/external-plugins.md @@ -3,8 +3,9 @@ Use `dart-flutter@dart-flutter` from the official [Flutter plugin repository](https://github.com/flutter/agent-plugins). Follow its [setup guide](https://docs.flutter.dev/ai/get-started) for SDK and client -requirements. This provider is separate from the company-owned Product and -Engineering kits; its skills and Dart MCP server are not copied into this repo. +requirements. The official provider supplies the general skills and the Dart MCP +server. For ACK, Noir, Mix, or Remix, install the company package kit alongside +it. [Dart Package Kit](../plugins/dart-package-kit/README.md) ## Install diff --git a/plugins/dart-package-kit/.claude-plugin/plugin.json b/plugins/dart-package-kit/.claude-plugin/plugin.json new file mode 100644 index 0000000..0ab52e9 --- /dev/null +++ b/plugins/dart-package-kit/.claude-plugin/plugin.json @@ -0,0 +1,11 @@ +{ + "name": "dart-package-kit", + "version": "0.1.0", + "description": "Package-specific guidance for ACK validation, Noir terminal apps, Mix styling, and Remix Flutter components.", + "author": { + "name": "Concepta" + }, + "skills": "./skills/", + "license": "BSD-3-Clause", + "repository": "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/btwld/agent-plugins" +} diff --git a/plugins/dart-package-kit/.codex-plugin/plugin.json b/plugins/dart-package-kit/.codex-plugin/plugin.json new file mode 100644 index 0000000..d616305 --- /dev/null +++ b/plugins/dart-package-kit/.codex-plugin/plugin.json @@ -0,0 +1,25 @@ +{ + "name": "dart-package-kit", + "version": "0.1.0", + "description": "Package-specific guidance for ACK validation, Noir terminal apps, Mix styling, and Remix Flutter components.", + "author": { + "name": "Concepta" + }, + "skills": "./skills/", + "interface": { + "displayName": "Dart Package Kit", + "shortDescription": "ACK, Noir, Mix, and Remix", + "longDescription": "Package-specific guidance for ACK validation, Noir terminal apps, Mix styling, and Remix Flutter components.", + "developerName": "Concepta", + "category": "Coding", + "capabilities": [ + "Read", + "Write" + ], + "defaultPrompt": [ + "Help me use ACK, Noir, Mix, or Remix with the version in my project." + ] + }, + "license": "BSD-3-Clause", + "repository": "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/btwld/agent-plugins" +} diff --git a/plugins/dart-package-kit/LICENSE b/plugins/dart-package-kit/LICENSE new file mode 100644 index 0000000..9edd81d --- /dev/null +++ b/plugins/dart-package-kit/LICENSE @@ -0,0 +1,28 @@ +BSD 3-Clause License + +Copyright (c) 2026, Leo Farias + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +3. Neither the name of the copyright holder nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/plugins/dart-package-kit/README.md b/plugins/dart-package-kit/README.md new file mode 100644 index 0000000..c54e349 --- /dev/null +++ b/plugins/dart-package-kit/README.md @@ -0,0 +1,16 @@ +# Dart Package Kit + +Four skills for projects that use ACK, Noir, Mix, or Remix. Each starts with the version resolved by the consuming project. You can use this kit alongside the official Dart and Flutter plugin. + +| Skill | When to use it | Example request | +| --- | --- | --- | +| [ack](skills/ack/SKILL.md) | Validate structured input with the Dart ACK schema library. | “Validate this API response with ACK and show how to report a missing field.” | +| [noir](skills/noir/SKILL.md) | Build or debug an interactive terminal UI using Dart Noir. | “Show the selected row in my Noir terminal list and handle keyboard navigation.” | +| [mix](skills/mix/SKILL.md) | Style Flutter widgets using Mix tokens, modifiers, and variants. | “Give this Mix-styled panel different padding at the compact breakpoint.” | +| [remix-flutter](skills/remix-flutter/SKILL.md) | Build a Flutter interface with Remix components and the project's theme or presets. | “Use our Remix buttons for this form and preserve the loading state.” | + +## Install + +After registering the marketplace, run `codex plugin add dart-package-kit@conceptadev` or `claude plugin install dart-package-kit@conceptadev`. Start a fresh session. In Codex, try `$ack`. In Claude Code, try `/dart-package-kit:remix-flutter`. + +If you already load a package's own skill, choose one entry for that task to avoid competing instructions. For a general SDK or framework task, use the official Dart and Flutter plugin. Package references and credits are in [SOURCES.md](SOURCES.md). diff --git a/plugins/dart-package-kit/SOURCES.md b/plugins/dart-package-kit/SOURCES.md new file mode 100644 index 0000000..4f8435a --- /dev/null +++ b/plugins/dart-package-kit/SOURCES.md @@ -0,0 +1,10 @@ +# Dart Package Kit sources + +The workflow instructions in this plugin are original and distributed under the [plugin license](LICENSE). The package teams maintain the detailed APIs, examples, and guides. The following revisions identify the documentation reviewed when this kit was written. + +| Package | Sources reviewed | +| --- | --- | +| ACK | [ACK LLM guide](https://github.com/btwld/ack/blob/b8eb8ebc9887cccaf21b7fe97a08fadc2839d0ba/llms.txt) · [published versions](https://pub.dev/packages/ack/versions) | +| Noir | [Noir terminal skill and references](https://github.com/btwld/noir/tree/1924c3ac3625dcf2f01c1b83a28ac1adb61ee12a/skills/noir) · [published versions](https://pub.dev/packages/noir/versions) | +| Mix | [Mix skill and references](https://github.com/btwld/mix/tree/e5259d8e65a32f7b7f11d14e6d734fe76226f8e6/skills/mix) · [published versions](https://pub.dev/packages/mix/versions) | +| Remix | [Remix usage and design-system skills](https://github.com/btwld/remix/tree/a3642ff2030efd42c1ecda9c3848e61fc7770f48/skills) · [published versions](https://pub.dev/packages/remix/versions) | diff --git a/plugins/dart-package-kit/skills/ack/SKILL.md b/plugins/dart-package-kit/skills/ack/SKILL.md new file mode 100644 index 0000000..f9f08fe --- /dev/null +++ b/plugins/dart-package-kit/skills/ack/SKILL.md @@ -0,0 +1,50 @@ +--- +name: ack +description: >- + Use when a Dart or Flutter project uses package:ack and needs to validate + untrusted input, define a schema or bidirectional codec, generate an Ack + model, import or export JSON Schema, or migrate between Ack versions. + Also use when the user explicitly asks to adopt Ack for one of these tasks. +--- + +# Ack schema validation + +Start at the caller. Identify the input the application receives, the Dart value it needs, and whether another consumer expects that value to encode back to a particular wire format. + +## Match the project's version + +Read the consuming package's `pubspec.yaml` and resolved `pubspec.lock`, including workspace overrides. For Git or path dependencies inspect the resolved checkout. For a hosted package use the API reference and source for that release. Ack's `llms.txt` indexes the guides **on its own revision**. For example, the 2.0 beta index links to code generation and null-handling rules that differ from 1.7. When adding Ack to a new project, check SDK compatibility and respect the project's stable or prerelease policy. [Published releases](https://pub.dev/packages/ack/versions) · [Ack 1.7.1 guide index](https://github.com/btwld/ack/blob/v1.7.1/llms.txt) · [Ack 2.0.0-beta.3 guide index](https://github.com/btwld/ack/blob/v2.0.0-beta.3/llms.txt) + +## Implement the boundary + +- **Validate external input.** Define required fields and constraints with the fluent builders. Use `safeParse` when invalid input is an expected outcome. Branch on `isOk` or `isFail` before reading the value or error. Preserve the field-level error information the caller needs. +- **Model missing values deliberately.** Decide separately whether a field may be omitted, may contain JSON null, or needs a default. PATCH handlers commonly distinguish “leave unchanged” from “clear this field.” Check how the resolved version represents those two cases before mapping to a nullable Dart field. +- **Encode values sent elsewhere.** If parsing changes the type or representation, choose a bidirectional codec with an explicit encoding rule. Test the wire value produced by encoding. A one-way parse transform can be sufficient when the value stays inside the application. +- **Generate models or integrate a provider when the task calls for it.** Follow the matching model-generation or adapter guide in the index. Check compatibility of companion packages and SDK constraints. For generated models, edit the source definition, run the project's generator, and validate untrusted inputs at the parse boundary. For JSON Schema interchange, confirm the consumer's dialect and check a representative schema through the actual consumer. + +For example, this schema accepts an omitted delivery note, an explicit null, or a string. A quantity of zero fails at the boundary. + +```dart +import 'package:ack/ack.dart'; + +final orderSchema = Ack.object({ + 'quantity': Ack.integer().min(1), + 'note': Ack.string().optional().nullable(), +}); + +void main() { + final result = orderSchema.safeParse({'quantity': 0}); + if (result.isFail) { + final error = result.getError(); + if (error is SchemaNestedError) { + for (final field in error.errors) { + print(field.path); + } + } else { + print(error.path); + } + } +} +``` + +Exercise a valid payload and the smallest invalid payload that demonstrates the rule. For a PATCH endpoint, also test omitted and explicit-null fields through the handler. For a codec or generated model, parse and encode a known input and compare the resulting wire payload. Run the project's analyzer and focused tests, and report which boundary they exercised. diff --git a/plugins/dart-package-kit/skills/ack/evals/evals.json b/plugins/dart-package-kit/skills/ack/evals/evals.json new file mode 100644 index 0000000..6464097 --- /dev/null +++ b/plugins/dart-package-kit/skills/ack/evals/evals.json @@ -0,0 +1,27 @@ +{ + "skill_name": "ack", + "evals": [ + { + "id": 1, + "prompt": "Our checkout service already uses ack 1.7.1. Validate an incoming order with a positive integer quantity and a delivery note that may be missing, null, or a string. A bad order should produce a field-specific validation error without a 500.", + "expected_output": "A version-compatible Ack object schema, safe handling of a rejected payload, and checks of the supported field states.", + "files": [], + "expectations": [ + "Uses the resolved 1.7.1 API and keeps the existing dependency.", + "Requires a positive integer quantity and handles each of the three note states.", + "Inspects the failure branch before reading the error and tests a rejected quantity." + ] + }, + { + "id": 2, + "prompt": "We've pinned ack and ack_generator to 2.0.0-beta.3. A PATCH model currently treats both omitted nickname and explicit null as 'leave unchanged'. Fix it and make the outgoing JSON preserve the difference.", + "expected_output": "A version-matched model change and handler and encoding tests covering omitted, null, and present values.", + "files": [], + "expectations": [ + "Checks the prerelease guide and the generated model's source definition.", + "Preserves three separate states through parsing, applying the patch, and encoding.", + "Regenerates affected files when needed and reports the checks actually run." + ] + } + ] +} diff --git a/plugins/dart-package-kit/skills/ack/evals/trigger_queries.json b/plugins/dart-package-kit/skills/ack/evals/trigger_queries.json new file mode 100644 index 0000000..4fdcf2f --- /dev/null +++ b/plugins/dart-package-kit/skills/ack/evals/trigger_queries.json @@ -0,0 +1,10 @@ +[ + {"query": "Validate incoming orders using the Ack dependency already in pubspec, and show which field caused a 400.", "should_trigger": true}, + {"query": "How do I make package:ack preserve missing versus explicit-null keys in a PATCH model?", "should_trigger": true}, + {"query": "Our Ack codec reads timestamps but emits the wrong representation on save. Can you fix the round trip?", "should_trigger": true}, + {"query": "Migrate our Ack schemas from 1.7 to 2.0 and check the generated model changes.", "should_trigger": true}, + {"query": "Add null-safe fromJson and toJson methods to this Dart class using only dart:convert.", "should_trigger": false}, + {"query": "Write a build_runner generator for annotated classes in a Dart package.", "should_trigger": false}, + {"query": "Why isn't our broker receiving the consumer's ACK between reconnects?", "should_trigger": false}, + {"query": "Review this TypeScript Zod schema for my checkout endpoint.", "should_trigger": false} +] diff --git a/plugins/dart-package-kit/skills/mix/SKILL.md b/plugins/dart-package-kit/skills/mix/SKILL.md new file mode 100644 index 0000000..c998c1a --- /dev/null +++ b/plugins/dart-package-kit/skills/mix/SKILL.md @@ -0,0 +1,24 @@ +--- +name: mix +description: Use when a Flutter task asks to change package:mix styles, layout primitives, tokens, or variants, or diagnose how a Mix styler resolves on a widget. Remix component behavior and generic Flutter layout have separate workflows. +--- + +# Style Flutter widgets with Mix + +Find the widget that renders the affected surface and the style it receives. Check the resolved `mix` version in `pubspec.lock`. For path or Git dependencies, follow the package location in `.dart_tool/package_config.json`. Use that source to check the actual constructor, styler methods and token types before editing. + +Work at the point that owns the appearance. To change a single widget, compose the appropriate concrete styler and pass it to that widget. Return or assign the new style from each fluent call. To change a shared design value, trace the token to its enclosing `MixScope` and identify which other widgets inherit it. For a state-specific change, inspect which widget supplies the hover, focus or press state. Keep changes to Remix component behavior, selection or semantics in the component that owns them. + +For example, this Mix 2.4 widget adds a uniform inset to its child. Reuse the application's spacing token when one exists. + +```dart +import 'package:flutter/widgets.dart'; +import 'package:mix/mix.dart'; + +Widget insetPanel(Widget child) => + Box(style: BoxStyler().padding(.all(12)), child: child); +``` + +Exercise the changed property in the consuming app. A spacing test can measure the distance between a keyed child and its parent. For a hover or theme change, exercise both states and inspect the visible result. Run the targeted widget test and Flutter analyzer using the project's SDK. + +For version-specific examples, start from the installed package and the upstream guide for the relevant API. The Mix repository publishes its own full skill, with focused guides to layouts, variants, tokens, generators and testing. [Upstream Mix skill](https://github.com/btwld/mix/tree/main/skills/mix) · [Documentation index for agents](https://raw.githubusercontent.com/btwld/mix/main/llms.txt) · [Published versions](https://pub.dev/packages/mix/versions) diff --git a/plugins/dart-package-kit/skills/mix/evals/evals.json b/plugins/dart-package-kit/skills/mix/evals/evals.json new file mode 100644 index 0000000..1f992ff --- /dev/null +++ b/plugins/dart-package-kit/skills/mix/evals/evals.json @@ -0,0 +1,25 @@ +{ + "skill_name": "mix", + "evals": [ + { + "id": 1, + "prompt": "Our Flutter project resolves mix 2.4.0. A panel applies BoxStyler().padding(.all(12)) in a separate statement but its child still touches the edge. Explain what to check and show a widget test that distinguishes 12 logical pixels from zero.", + "expected_output": "Find whether the result of padding was discarded or never supplied to the actual Box, and test the resulting inset.", + "files": [], + "expectations": [ + "Traces which Box receives the modified style and preserves the returned styler.", + "Measures the laid-out inset of the child against the parent in a focused widget test." + ] + }, + { + "id": 2, + "prompt": "Our Flutter app uses Mix from a local path override. A docs example uses a method our analyzer does not recognize. Change the widget's design token to show a different color in one subtree.", + "expected_output": "Resolve the package path, use its actual API, scope the token override to the requested subtree and check an unaffected sibling.", + "files": [], + "expectations": [ + "Checks the resolved local package before choosing an API.", + "Localizes the change to the subtree and verifies both affected and unaffected widgets." + ] + } + ] +} diff --git a/plugins/dart-package-kit/skills/mix/evals/trigger_queries.json b/plugins/dart-package-kit/skills/mix/evals/trigger_queries.json new file mode 100644 index 0000000..a6d5fe5 --- /dev/null +++ b/plugins/dart-package-kit/skills/mix/evals/trigger_queries.json @@ -0,0 +1,34 @@ +[ + { + "query": "This Flutter BoxStyler returns a new style, but I can't get the inset to show on my Mix Box.", + "should_trigger": true + }, + { + "query": "The hover background on this Mix Pressable is right in isolation but wrong under a nested MixScope. Trace it.", + "should_trigger": true + }, + { + "query": "Convert the repeated raw spacing in these package:mix widgets to our existing spacing token.", + "should_trigger": true + }, + { + "query": "Set the responsive tracks for a grouped Flutter Mix GridBox.", + "should_trigger": true + }, + { + "query": "Fix keyboard activation and selection in a Remix menu without changing its look.", + "should_trigger": false + }, + { + "query": "Plan an accessibility study for a mobile checkout.", + "should_trigger": false + }, + { + "query": "Fix a RenderFlex overflow inside a plain Flutter Row. We use only the Material SDK.", + "should_trigger": false + }, + { + "query": "Wire up a Remix loader for this TypeScript web route.", + "should_trigger": false + } +] diff --git a/plugins/dart-package-kit/skills/noir/SKILL.md b/plugins/dart-package-kit/skills/noir/SKILL.md new file mode 100644 index 0000000..3f44b98 --- /dev/null +++ b/plugins/dart-package-kit/skills/noir/SKILL.md @@ -0,0 +1,22 @@ +--- +name: noir +description: Build, debug, or test Dart terminal user interfaces that use package:noir. Use for Noir widgets, terminal layout, focus and keyboard input, reactive state, and drive-mode inspection. Use the framework contributor guide for renderer internals. Ordinary Dart command-line tools, Flutter screens, and Noir zero-knowledge circuits have separate tooling. +--- + +# Noir terminal applications + +Start from the application entry point and its resolved dependency. Check `pubspec.lock` for the Noir version and `.dart_tool/package_config.json` for the package source. A path or workspace dependency may contain newer APIs than the published release. Match constructors and tooling to the resolved library, especially for `noir_signals` and `noir_driver`. + +Use `package:noir/noir.dart` and `runTuiApp` for application UI. For a first screen, start with a single text widget. + +```dart +import 'package:noir/noir.dart'; + +void main() => runTuiApp(const Text('Ready')); +``` + +For an existing app, build on the closest widget and follow its state ownership. Size layouts in character cells. For a keyboard interaction, trace the event from the app handler to the focused widget. Give driven controls stable `ValueKey` identifiers so the driver can target them. Dispose caller-owned controllers and focus nodes with their owner. + +The following upstream guidance was checked against Noir 0.0.7. Read the relevant section of [Noir’s application skill](https://github.com/btwld/noir/blob/noir-v0.0.7/skills/noir/SKILL.md). Its adjacent references cover [widgets and layout](https://github.com/btwld/noir/blob/noir-v0.0.7/skills/noir/references/widgets.md), [input and focus](https://github.com/btwld/noir/blob/noir-v0.0.7/skills/noir/references/inputs-and-focus.md), and [Signals and hooks](https://github.com/btwld/noir/blob/noir-v0.0.7/packages/noir_signals/doc/hooks.md). When working offline, use the resolved package's public exports and examples. + +Check the result at the layer the user cares about. Run `dart analyze` and focused application tests. A headless mount checks lifecycle; for a layout or input change, exercise the interaction in a terminal or with a compatible `noir_driver`, and inspect the rendered frame at the relevant terminal size. Report the behavior observed and any terminal-dependent checks still open. [Noir testing guide](https://btwld.github.io/noir/docs/testing/) diff --git a/plugins/dart-package-kit/skills/noir/evals/evals.json b/plugins/dart-package-kit/skills/noir/evals/evals.json new file mode 100644 index 0000000..2c2c9a4 --- /dev/null +++ b/plugins/dart-package-kit/skills/noir/evals/evals.json @@ -0,0 +1,27 @@ +{ + "skill_name": "noir", + "evals": [ + { + "id": 1, + "prompt": "Sketch a minimal Dart entry point for a package:noir status screen that displays Ready. I already depend on Noir. How do I check that it renders inside an 80-column terminal?", + "expected_output": "A runnable Noir-only screen and a way to inspect it at a known width.", + "files": [], + "expectations": [ + "Uses package:noir/noir.dart, runTuiApp and a public text widget.", + "Checks visual output using a real terminal or a compatible driver at the requested geometry.", + "Distinguishes a headless lifecycle check from a rendered frame." + ] + }, + { + "id": 2, + "prompt": "A Noir TUI search field no longer receives the letter q after I registered a global quit shortcut. How would you isolate and verify the fix without changing my project's dependencies?", + "expected_output": "An input-routing diagnosis and a narrow interactive regression check.", + "files": [], + "expectations": [ + "Examines app-level key handling and focus before changing the text field.", + "Checks event handling against the resolved Noir package.", + "Exercises typing q into the focused field and quitting through the intended shortcut." + ] + } + ] +} diff --git a/plugins/dart-package-kit/skills/noir/evals/trigger_queries.json b/plugins/dart-package-kit/skills/noir/evals/trigger_queries.json new file mode 100644 index 0000000..f1bcb8d --- /dev/null +++ b/plugins/dart-package-kit/skills/noir/evals/trigger_queries.json @@ -0,0 +1,66 @@ +[ + { + "query": "Sketch a minimal Dart entry point for a package:noir status screen that displays Ready. I already depend on Noir. How do I check that it renders inside an 80-column terminal?", + "should_trigger": true + }, + { + "query": "A Noir TUI search field no longer receives the letter q after I registered a global quit shortcut. How would you isolate and verify the fix without changing my project's dependencies?", + "should_trigger": true + }, + { + "query": "Check how my package:noir dashboard wraps at 40 terminal columns.", + "should_trigger": true + }, + { + "query": "Add keyboard navigation to this Noir terminal form.", + "should_trigger": true + }, + { + "query": "Test mount and disposal of a Dart Noir widget without opening a real terminal.", + "should_trigger": true + }, + { + "query": "Inspect the focus order of my Noir TUI using noir_driver.", + "should_trigger": true + }, + { + "query": "Compare SignalWidget with the stateful approach for this Noir terminal application.", + "should_trigger": true + }, + { + "query": "Use $noir to add a status row to my TUI.", + "should_trigger": true + }, + { + "query": "Write a zero-knowledge range proof in Noir.", + "should_trigger": false + }, + { + "query": "Implement a Flutter screen with two TextFields and a submit button.", + "should_trigger": false + }, + { + "query": "Build a standard Dart CLI command with package:args and JSON output.", + "should_trigger": false + }, + { + "query": "Capture a film-noir look for the cover artwork.", + "should_trigger": false + }, + { + "query": "Add keyboard navigation to a React OpenTUI application.", + "should_trigger": false + }, + { + "query": "Validate a Dart JSON payload with package:ack.", + "should_trigger": false + }, + { + "query": "Investigate a layout overflow in a Flutter widget test.", + "should_trigger": false + }, + { + "query": "Make my zsh prompt print the current Git branch.", + "should_trigger": false + } +] diff --git a/plugins/dart-package-kit/skills/remix-flutter/SKILL.md b/plugins/dart-package-kit/skills/remix-flutter/SKILL.md new file mode 100644 index 0000000..08d4de6 --- /dev/null +++ b/plugins/dart-package-kit/skills/remix-flutter/SKILL.md @@ -0,0 +1,66 @@ +--- +name: remix-flutter +description: >- + Use when adding, styling, debugging, or upgrading Remix widgets in a Flutter + app that uses btwld/remix, package:remix/remix.dart, or a remix.yaml registry. + Covers version-specific component stylers, app-owned Vanilla, Fortal, and + HeroUI presets, theme and overlay setup, and remix_cli registry changes. + The Flutter package is distinct from React Remix, standalone Mix styling, and + standalone naked_ui primitives. +--- + +# Remix for Flutter + +## Identify the API the app uses + +1. Read the owning Flutter app's `pubspec.yaml`, `pubspec.lock`, and + `remix.yaml` if present. Check the resolved `remix`, `mix`, `naked_ui`, and + any `remix_cli` versions, the Flutter SDK, and dependency overrides. Use + `.dart_tool/package_config.json` to locate the resolved package source. For + a Git or path dependency, inspect the actual revision or checkout. +2. Inspect nearby components and local theme setup. In a registry project, + find the configured preset, prefix, UI path, and registry revision. Read the + app-owned recipes, barrels, generated wrappers, and any installed upstream + Remix skill for that revision. The package version and registry revision are + independent. +3. Confirm each unfamiliar constructor, style method, behavior root, or CLI + option against the resolved package and matching upstream material. Use the + [version and preset reference](references/versions-and-presets.md) to locate + the right source before applying examples from the website. + +## Work in the app's existing layer + +- **Direct widgets.** Use the exported `Remix*` widget, its matching styler, and + existing app tokens. Keep behavior in the public component and its group or + controller. Check the component's reported states before styling selected, + disabled, or focus variants. +- **App-owned presets.** Use the configured prefix and local `ui.dart` barrel. + Choose the installed constructor or runtime variant for the requested visual + intent. When the local wrapper supports `style:`, use it for a single-instance + override. Edit the app's recipe or theme for changes that should apply across + the app. Regenerate adapters with the app's code-generation command after + changing annotated inputs. +- **Registry changes.** Check the pinned catalog and installed ownership records + before adding or refreshing items. Review a diff before replacing existing + owned code and retain intentional local changes. For reusable presets or + published registries, follow the [upstream registry-authoring skill](https://github.com/btwld/remix/tree/main/skills/building-remix-design-system). +- **Host and interaction.** Place the installed theme above the Navigator when + routes and overlays consume its tokens. Verify the resolved component's host + requirements. Check overlays for menus and text selection, a Navigator for + dialogs, and the toast scope where the resolved API provides it. For preset + details, read the installed `using-remix` skill or find its source by + replacing `main` in the upstream link with the `@remix` revision. + [Using Remix](https://github.com/btwld/remix/tree/main/skills/using-remix) + +Remix owns component composition. Mix provides stylers, variants, and tokens. +Naked UI supplies interaction behavior. For a standalone Mix or Naked UI task, +use that package's public API and documentation. + +## Verify + +Run the project's formatter, `flutter analyze`, and relevant Flutter widget +tests. Exercise the behavior that changed, including applicable keyboard focus, +activation, selected or disabled states, and overlay opening and dismissal. +For generated wrappers, confirm the build output and final imports agree with +the installed prefix. Report the resolved version or revision and the checks +that ran. When execution is unavailable, report source verification separately. diff --git a/plugins/dart-package-kit/skills/remix-flutter/evals/evals.json b/plugins/dart-package-kit/skills/remix-flutter/evals/evals.json new file mode 100644 index 0000000..c223cd8 --- /dev/null +++ b/plugins/dart-package-kit/skills/remix-flutter/evals/evals.json @@ -0,0 +1,35 @@ +{ + "skill_name": "remix-flutter", + "evals": [ + { + "id": 1, + "prompt": "My Flutter app resolves remix 0.2.0. I copied ButtonStyler().padding(.all(12)) from the Remix site and Flutter can't find ButtonStyler. Give me a styled Save button that works with our current lockfile.", + "expected_output": "Use RemixButton with the styling API verified against the stable 0.2.0 package and keep the current dependency line.", + "files": [], + "expectations": [ + "Uses package:remix/remix.dart, RemixButton and RemixButtonStyle from the 0.2.0 public API.", + "Retains the dependency line and supplies a version-appropriate padding call and Save callback." + ] + }, + { + "id": 2, + "prompt": "pubspec.lock resolves remix 1.0.0-rc.4. An old example uses FortalScope and FortalButtonStyle, but we're building a hand-styled Save button and don't use remix.yaml. What should go in the widget and how would you verify it?", + "expected_output": "Use the release candidate public widget and styler directly and verify the Save action in the existing host.", + "files": [], + "expectations": [ + "Uses RemixButton and ButtonStyler and keeps the existing host and callback.", + "Explains that a preset is optional for direct widgets and provides an analysis or widget-test check for the requested behavior." + ] + }, + { + "id": 3, + "prompt": "I'm on Flutter 3.44 and followed the Remix RC docs. remix init --preset vanilla fails with 'No registry-stable branch is published for btwld/remix'. I mainly need a styled button and can wait on Vanilla. Help me get it working.", + "expected_output": "Identify the unavailable upstream registry ref and provide a direct Remix component path when the user can defer the preset.", + "files": [], + "expectations": [ + "Identifies the missing official registry ref and does not claim init supports a --ref option.", + "Provides a direct package:remix/remix.dart solution using the supported release candidate API and defers preset installation." + ] + } + ] +} diff --git a/plugins/dart-package-kit/skills/remix-flutter/evals/trigger_queries.json b/plugins/dart-package-kit/skills/remix-flutter/evals/trigger_queries.json new file mode 100644 index 0000000..e31f461 --- /dev/null +++ b/plugins/dart-package-kit/skills/remix-flutter/evals/trigger_queries.json @@ -0,0 +1,34 @@ +[ + { + "query": "ButtonStyler is missing even though our Flutter app has remix in pubspec.lock. Check the installed version and show how to style RemixButton.", + "should_trigger": true + }, + { + "query": "Our Remix Fortal button recipe keeps its old color on hover. Change the app-owned recipe so its states use our tokens.", + "should_trigger": true + }, + { + "query": "How can I update the button template at the @remix pin without losing the edits in my Flutter app's lib/ui?", + "should_trigger": true + }, + { + "query": "The Remix toast from the settings route can't find its scope. Fix it in this Flutter app.", + "should_trigger": true + }, + { + "query": "Why does this ColorToken resolve outside the nested MixScope on our plain Mix Box widget?", + "should_trigger": false + }, + { + "query": "Fix focus wraparound on a NakedMenu using only the naked_ui package.", + "should_trigger": false + }, + { + "query": "Move the Remix route's TypeScript loader and action to React Router.", + "should_trigger": false + }, + { + "query": "Make the Flutter Material ElevatedButton use the active ColorScheme on hover.", + "should_trigger": false + } +] diff --git a/plugins/dart-package-kit/skills/remix-flutter/references/versions-and-presets.md b/plugins/dart-package-kit/skills/remix-flutter/references/versions-and-presets.md new file mode 100644 index 0000000..6fafe9f --- /dev/null +++ b/plugins/dart-package-kit/skills/remix-flutter/references/versions-and-presets.md @@ -0,0 +1,98 @@ +# Remix versions and presets + +The Dart package is `remix`, published from `btwld/remix`. Both API lines below +use `package:remix/remix.dart` and re-export Mix. The resolved source remains +authoritative for later releases. + +| Published API | Button styler | Theme and installation | +| --- | --- | --- | +| Stable `0.2.0` | `RemixButtonStyle` | The package exports `FortalScope` and `FortalButtonStyle` as well as its base widgets. [Released source](https://pub.dev/api/archives/remix-0.2.0.tar.gz) | +| Prerelease `1.0.0-rc.4` | `ButtonStyler` | Base widgets ship without a theme. The CLI installs editable preset recipes and theme files when wanted. This release requires Flutter 3.44 and Dart 3.12 or newer within its SDK constraints. [Released source](https://github.com/btwld/remix/tree/remix-v1.0.0-rc.4/packages/remix) | + +Use the [pub.dev versions page](https://pub.dev/packages/remix/versions) to +check published candidates before adding dependencies. In an existing app, +keep the resolved release line unless the task calls for an upgrade. For a Git +or path dependency, use its source even when the manifest version matches a Pub +release. When docs and source differ, check the public export barrel, component +constructor, and generated styler of the resolved source. + +## Direct widget examples + +Use one of these button implementations inside the existing Flutter host. +Start with `RemixButtonStyle` on 0.2.0. Older examples may use helpers such as +`paddingX` or `borderRadiusAll`, which newer Mix 2.x releases deprecate. + +```dart +import 'package:flutter/widgets.dart'; +import 'package:remix/remix.dart'; + +Widget saveButton(VoidCallback save) => RemixButton( + label: 'Save', + onPressed: save, + style: RemixButtonStyle() + .padding(.symmetric(horizontal: 16, vertical: 10)) + .color(const Color(0xFF244B8F)) + .borderRadius(.circular(8)) + .label(TextStyler().color(const Color(0xFFFFFFFF))), +); +``` + +The 1.0.0-rc.4 implementation uses the component's `ButtonStyler` with Mix +shorthand supported by the resolved version. + +```dart +import 'package:flutter/widgets.dart'; +import 'package:remix/remix.dart'; + +Widget saveButton(VoidCallback save) => RemixButton( + label: 'Save', + onPressed: save, + style: ButtonStyler() + .padding(.symmetric(horizontal: 16, vertical: 10)) + .color(const Color(0xFF244B8F)) + .borderRadius(.circular(8)) + .label(TextStyler().color(const Color(0xFFFFFFFF))), +); +``` + +For other components, consult the exact [stable API](https://pub.dev/documentation/remix/0.2.0/) +or [release candidate component docs](https://github.com/btwld/remix/tree/remix-v1.0.0-rc.4/docs/components). + +## Preset workflows on the 1.0 release candidate line + +Direct widget use requires only the `remix` dependency. For a fresh app opting +into the release candidate registry workflow, verify the CLI and package +constraints and check that the official `registry-stable` ref exists. The CLI's +`init` command needs that ref to create a new `remix.yaml`. If it is unavailable, +report the registry blocker. Direct widgets can still be used when they satisfy +the task. [CLI release source](https://github.com/btwld/remix/tree/remix_cli-v1.0.0-rc.1/packages/remix_cli) + +```sh +flutter pub add 'remix:^1.0.0-rc.4' +dart pub global activate remix_cli '^1.0.0-rc.1' +remix init --preset vanilla +remix add button +``` + +An unversioned Pub install selects the stable line, including the earlier +CLI `0.1.0`. Where the app already pins the CLI as a dev dependency, use its +project-local invocation such as `dart run remix_cli:remix list`. + +- **Add items.** `remix list` reads the pinned catalogs. The CLI installs an + item's dependency closure, which can include theme files. Use the current + `remix.yaml` prefix and UI path to locate and import the owned barrel and + theme. Preset and prefix are independent. [Registry installation](https://fluttermix.com/remix/docs/open-code/install/) +- **Refresh owned source.** `remix registry update @remix` resolves the + configured ref and moves its pin. Supply `--ref ` to move off a + SHA or tag or to select a different release ref. + `remix add --diff` previews template differences, including local + edits. `--overwrite` replaces named items and does not merge. Keep authored + changes and review which items need refreshing, including `theme` where + applicable. [Registry updates](https://fluttermix.com/remix/docs/open-code/updating/) +- **Read pin-specific guidance.** Prefer the app's installed `using-remix` + skill or read it at the registry SHA. If the project uses `remix skills + install`, compare `remix.skills.json` with the `@remix` revision before + using those instructions. The installation command writes project skill + files and an `AGENTS.md` block. [CLI skill setup](https://fluttermix.com/remix/docs/open-code/install/#agent-skills) + +For current docs and deeper upstream guidance, consult the [Remix docs](https://fluttermix.com/remix/docs/), [package changelog](https://pub.dev/packages/remix/changelog), and [upstream skills](https://github.com/btwld/remix/tree/main/skills). diff --git a/tests/test_packaging.py b/tests/test_packaging.py index 969f678..31ff59f 100644 --- a/tests/test_packaging.py +++ b/tests/test_packaging.py @@ -5,6 +5,7 @@ ROOT = Path(__file__).resolve().parents[1] SKILLS = { + 'dart-package-kit': {'ack', 'noir', 'mix', 'remix-flutter'}, 'design-kit': {'design-system', 'image-to-code', 'accessibility-review', 'design-verification', 'frontend-design', 'ux-copy', 'visual-exploration', 'design-critique', 'user-research', 'url-to-code'}, 'product-kit': {'product-brainstorming', 'research-synthesis', 'competitive-brief', 'ux-friction-research', 'write-prd', 'write-wbs'},