Deliver the user's intended outcome with the least unnecessary complexity. Exercise independent judgment: surface material errors, risks, and tradeoffs early, then respect the user's informed decision.
The user owns goals, scope, and consequential product choices. The agent owns routine engineering decisions. Ask only when missing information would materially change the outcome, risk, cost, or authorized scope.
When implementing or modifying code, do not keep a change artificially local by recreating, overriding, or correcting behavior outside its existing owner or source of truth. Change the owning implementation directly when that remains within scope. If doing so would materially widen the task or conflict with an established contract, surface the tradeoff before adding a workaround.
Preserve unrelated work and staging state. Clean up temporary resources created for the task, including stopping verification servers before delivery.
Prefer the least complex solution that satisfies the explicit request and established contracts. Start with native platform behavior and existing project primitives. Before adding state, effects, observers, DOM measurement, portals, abstractions, compatibility layers, or infrastructure, require a concrete user-visible need that simpler options cannot meet. Do not expand small issues to cover hypothetical cases. If implementation or maintenance cost exceeds the likely benefit, stop and choose the simpler solution. Reassess immediately when the user proposes a simpler approach.
Prefer clear, direct code and existing conventions. Shared behavior belongs in shared production code; features compose it instead of duplicating it. Tests and Stories exercise production behavior without becoming parallel implementations. Remove obsolete unpublished behavior rather than preserving it speculatively.
Keep durable principles in instructions, product boundaries in architecture, exact contracts in technical references, and implementation details in code. Historical plans are context, not policy.
Each behavior has one authoritative owner. Correct defects there; clients must not compensate for incomplete contracts or maintain competing sources of truth. Preserve established contracts unless the task changes them, and update their affected implementations, consumers, and specifications.
packages/open-flow owns the public product, packages/command owns the CLI, and apps/ owns
deployments. Cross-workspace dependencies use public entries. Common code is platform-neutral, and
browser code is independent of Node. Dependencies should make these boundaries visible.
Provider, Action, and Connection data keep independent fetching and caching authority, including scope, freshness, refresh, and invalidation. Consumers derive combined views at the consumption layer. Do not embed one source's state in another or couple cache lifecycles merely because a feature uses them together.
Caches store complete responses by request identity and own storage, freshness, conditional requests, and coordination. They do not merge business entities across responses or infer authority from arrival order. Add a derived multi-source layer only when its benefit and ownership justify it. Keep caching simpler than the repeated work it removes.
Before implementing or reviewing frontend appearance, layout, components, or interactions, read and use the frontend-ui skill.
- Host shell and chrome: Keep host selectors inside host-owned UI. Customize Open Flow through
public
--open-flow-*tokens. Do not target packaged product roots or force them to inherit host tokens. - Workbench and canvas chrome: The
.open-flow-workbenchroot establishes.open-flow-theme. It owns the node outline, node picker, and canvas control islands. Product theme tokens belong inpackages/open-flow/src/ui/browser/theme.css. - Canvas content: The canvas surface owns nodes, edges, handles, and node-local popovers. Its compact palette and geometry must not leak into Workbench chrome.
- Property panel:
.open-flow-property-panelmay narrow control-specific tokens such as--ui-control-radius, but must not replace product-wide tokens such as--ui-radius. - Lab: Lab owns its shell, story framing, and guidance. It must not restyle production components, which use the same theme and surface contracts as real hosts.
Fix cross-boundary leaks at their owner. Do not add compensating component overrides.
ContextPanel is the property panel's only cross-section stacking context. Sections and field tables
must not trap feedback or popups in local stacking contexts. Individual editors may isolate internal
content, but cross-section elevation uses the semantic layers in context-panel.css. Do not introduce
independent z-index scales, portals, DOM measurement, observers, or runtime positioning solely to
repair stacking that the shared CSS contract can express. Verify stacking changes across adjacent
sections in a composed panel.
Lab stories are the design-alignment and visual-inspection surface. Use real production components
with deterministic data and present meaningful related states together. Every second-level Lab
navigation directory has an UnoCSS Iconify icon in directory metadata. Put concise story guidance in
description; keep sample labels with their examples. Register sample-only controls through
useStoryActions from packages/open-flow/dev/designer/storyActions.tsx; production controls remain
in production components.
Maintain affected Lab stories with component changes. Confirm broad story reorganizations, removal of useful coverage, or changes to verification scope unless the task already authorizes them.
Evidence must support the claimed outcome. Choose verification by behavior, ownership, propagation, and risk. Start with the smallest check that can falsify the intended change; broaden only when shared contracts, indirect consumers, failures, or unresolved uncertainty justify it. Reuse valid evidence.
Tests protect consequential behavior and stable contracts. Favor public outputs, state transitions, persistence, side effects, error handling, accessibility semantics, and ownership boundaries. Do not test incidental markup, class strings, source layout, or exhaustive inventories unless they are an explicit contract. Revise obsolete assertions instead of weakening an intentional design.
Use evidence that can observe the claim: pure tests for rules and data contracts, behavioral tests for user-visible interaction and semantics, and rendered inspection for appearance and layout. Static source checks are reserved for durable architecture or safety boundaries. A shared primitive, public entry, schema, persistence or execution contract, cache, localization system, build pipeline, or package artifact requires evidence from affected boundaries; a local or visual change usually does not justify unrelated suites.
Use Lab as the preferred visual surface for component appearance and interaction, supplemented by the product when integration matters. Browser acceptance is warranted when rendering or real interaction is material and cheaper evidence is insufficient. Report material verification gaps honestly.
Run the Open Flow test suite with bun run test from packages/open-flow. Do not invoke bun test
directly because it bypasses the project's Vitest configuration.
When changes affect the published Open Flow package, including bundled code or assets, public exports,
type declarations, dependencies, or packaging logic, run
bun run --filter @oomol-lab/open-flow test:package from the repository root before delivery.
This builds and checks the actual tarball in an isolated consumer; source tests and type checks do not
replace it. For changes affecting other distributable artifacts, also run their package tests.
Before every Git commit, run bun run check from the repository root and require it to pass. Run it
again after any rebase or merge that changes the result before committing or pushing.
Consult only references relevant to the task:
- Architecture: product contracts, persistence, execution, and ownership.
- Iconify skill: UI icon selection and integration.
- Contributing: environment, checks, and contribution requirements.