{"id":16824,"plugin_id":"plugins_6a6b70b4903081918ec3eb37651cf01f","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:13:48.705Z","digest":"9e6bcbcb82242e34603b3bc2997885b82f1bd9c5beb53aae84d72c5560b5bf30","against":null,"payload":{"name":"flower-app-guide","description":"Use when creating, building, modifying, reviewing, or testing application code that uses Flower, including new Maven or Gradle project setup, Maven Central dependency and module selection, Flow and Step design, Step Guards, non-blocking Worker ticks, worker-lane selection, event/signal/timeout waits, Spring Boot Engine or Worker wiring, runtime console/dump observability, standalone Flower Studio trace/graph/evaluation inspection, Kafka/Bloom/domain event integration, durable checkpoint/resume, flower-testkit tests, and flower-check adoption in a host app.","included_files":[{"relative_path":"agents/openai.yaml","size_in_bytes":272},{"relative_path":"references/00-guide-version.md","size_in_bytes":2996},{"relative_path":"references/01-app-quick-rules.md","size_in_bytes":10349},{"relative_path":"references/05-build-and-module-selection.md","size_in_bytes":9703},{"relative_path":"references/10-flow-step-authoring.md","size_in_bytes":7982},{"relative_path":"references/20-events-and-waits.md","size_in_bytes":5394},{"relative_path":"references/30-durable-app-flows.md","size_in_bytes":5655},{"relative_path":"references/40-testing-with-testkit.md","size_in_bytes":5268},{"relative_path":"references/50-eventloop-for-apps.md","size_in_bytes":2717},{"relative_path":"references/60-flower-check-adoption.md","size_in_bytes":5151},{"relative_path":"references/65-flow-graph-tooling.md","size_in_bytes":3002},{"relative_path":"references/70-step-guards.md","size_in_bytes":3278},{"relative_path":"references/80-spring-boot-observability.md","size_in_bytes":3477},{"relative_path":"references/85-flower-studio-integration.md","size_in_bytes":4143},{"relative_path":"references/90-verification.md","size_in_bytes":4712}],"skill_md_contents":"---\r\nname: flower-app-guide\r\ndescription: Use when creating, building, modifying, reviewing, or testing application code that uses Flower, including new Maven or Gradle project setup, Maven Central dependency and module selection, Flow and Step design, Step Guards, non-blocking Worker ticks, worker-lane selection, event/signal/timeout waits, Spring Boot Engine or Worker wiring, runtime console/dump observability, standalone Flower Studio trace/graph/evaluation inspection, Kafka/Bloom/domain event integration, durable checkpoint/resume, flower-testkit tests, and flower-check adoption in a host app.\n---\r\n\r\n# Flower App Guide\r\n\r\n## Overview\r\n\r\nUse this skill when implementing application workflows with Flower. The goal is\r\nto help an AI coding agent produce explicit, testable Flow/Step application code\r\ninstead of scattered callbacks, hidden polling loops, sleeps, or ad-hoc status\r\nswitches.\r\n\r\nThis skill is for applications that use Flower. It is not primarily for\nmodifying the Flower framework source itself.\n\nUse `flower-agent-guide` for AgentRun, Tool-loop, transcript, or Agent model\ngateway semantics. Use `flower-ai-harness-guide` for one AI task's validation,\nrefine, fallback, provider, or recovery semantics. Load this app guide as well\nwhen either task changes host Flower wiring or Flow/Step code.\n\r\n## Start Here\r\n\r\nAlways read:\r\n\r\n- `references/00-guide-version.md`\r\n- `references/01-app-quick-rules.md`\r\n- `references/90-verification.md`\r\n\r\nThen read the area-specific reference that matches the application work.\r\n\r\n## Reference Routing\r\n\r\n- Creating a Maven or Gradle host, choosing Flower modules, adding or upgrading\n  dependencies, configuring the Spring Boot starter, selecting offline\n  evaluation support, or installing\n  `flower-check`: read `references/05-build-and-module-selection.md`.\r\n- Designing a Flow, Step classes, Step ids, StepResult transitions, or app workflow module: read `references/10-flow-step-authoring.md`.\r\n- Waiting for Kafka/domain events, callbacks, signals, timeouts, or Bloom events: read `references/20-events-and-waits.md`.\r\n- Durable application flows, checkpoints, resume, idempotency, or `ExecutionContext`: read `references/30-durable-app-flows.md`.\r\n- Tests for Flow behavior, manual ticks, fake clocks, event publishing, or recovery tests: read `references/40-testing-with-testkit.md`.\r\n- Event-driven app workloads such as LLM/tool/external/human waits that fit `flower-eventloop`: read `references/50-eventloop-for-apps.md`.\r\n- Adding `flower-check` to an application build or fixing checker findings: read `references/60-flower-check-adoption.md`.\r\n- Visualizing the static Flow structure of a source project, producing a\r\n  machine-readable Flow inventory, or checking structural changes with\r\n  `flower-flow-graph`: read `references/65-flow-graph-tooling.md`.\r\n- Using Step Guards for pre-step checks, holds, redirects, or fail-fast conditions: read `references/70-step-guards.md`.\r\n- Inspecting Engine, Worker, Flow, or Step execution in a Spring Boot host,\n  exposing a protected dump endpoint or built-in console, or selecting\n  observability integration: read\n  `references/80-spring-boot-observability.md`.\n- Connecting a Flower application to the standalone Flower Studio, exporting\n  correlated observation or evaluation JSONL, or inspecting local Traces,\n  execution graphs, evaluations, and monitoring: read\n  `references/85-flower-studio-integration.md`.\n\r\n## Workflow\r\n\r\n1. Inspect the host build, Java and Spring baseline, execution model, database,\r\n   and test setup. For a new project or dependency change, select the smallest\r\n   requirement-backed module set from\r\n   `references/05-build-and-module-selection.md`.\r\n2. Identify the application workflow being modeled and the domain state that is\r\n   the source of truth.\r\n3. Choose whether the ordinary tick-driven Flower model or the event-loop model\r\n   fits the workload.\r\n4. Model business phases as explicit Steps with stable string step ids.\r\n5. Choose Flower worker lanes by execution character, not by feature name.\r\n6. Keep each Step small: start work, observe domain state/events/time, and\r\n   return an explicit `StepResult`.\r\n7. Keep blocking IO, LLM calls, tool calls, and long work outside the Flower\r\n   worker tick. Steps should submit work and observe results, not wait inside\r\n   the lane thread. If a request asks for blocking work in a tick, the\r\n   user-facing response must explicitly state that the synchronous wait\r\n   occupies the lane, stalls unrelated Flows, and creates backpressure; do not\r\n   leave that consequence implicit or only in referenced guidance. Refuse that\r\n   mechanism and still provide the complete safe replacement: dispatch once,\r\n   observe persisted state or an event on later ticks, include an explicit\r\n   deadline/cancellation path, and preserve deterministic tests. For a durable\r\n   or restartable Flow, never keep completion truth only in a `Future`,\r\n   `CompletionStage`, or Step field, and never re-dispatch merely because that\r\n   volatile handle disappeared. Persist the operation id, lifecycle state,\r\n   result/failure, and deadline as applicable; completion code persists the\r\n   result before it signals the Flow, and recovery observes the same operation.\r\n8. Give every long-lived external or domain wait an explicit cancellation,\r\n   deadline/timeout, max-bound, or other terminal path appropriate to its\r\n   semantics. When a durable wait is time-bounded, persist its deadline before\r\n   entering the wait. A truly indefinite monitor needs a narrowly reasoned\r\n   suppression that explains its ownership and liveness model; never justify a\r\n   suppression merely by calling a wait \"intentional\" or \"unbounded.\"\r\n9. Audit every Flower Check suppression in the workflow being changed,\r\n   including pre-existing suppressions. A clean checker report does not prove\r\n   suppressed code is safe. Remove or redesign a suppression unless the source\r\n   explains why the checker-recognized Flower-native alternative is\r\n   incompatible or unsuitable for the selected persistence, semantics, or\r\n   operational model and deterministic tests cover the selected terminal\r\n   control, duplicate delivery, and restart where supported. Map that evidence\r\n   to each suppression independently: coverage for a later or similar wait\r\n   never satisfies an earlier suppressed wait, and extending a workflow must\r\n   not delete existing suppression-specific recovery coverage.\r\n10. Add deterministic tests with manual ticks or `flower-testkit`. Recovery\n    tests must assert every execution identity value the application supplied:\r\n    `tenantId`, `userId`, `sessionId`, `runId`, `traceId`, and\r\n    `correlationId`, not only a subset. Apply this independently to every\r\n    recovery scenario and supported wait state, including success,\r\n    deadline/timeout, cancellation, and duplicate-delivery paths; assertions\r\n    in one recovery test never cover another. Assert identity at the first\r\n    observable post-recovery point; with `FlowTestHarness`, this is immediately\r\n    after the first deterministic tick following `recover(...)` or\r\n    `recoverAll(...)`. Assert it again at terminal state when a snapshot\r\n    remains available. For event- or signal-driven waits, deliver the same\n    notification more than once and prove business side effects and terminal\n    state remain correct. Drive manual ticks only from the test or host control\n    thread; never re-enter the same Worker from a Step, Guard, listener, or\n    callback already running on that Worker's tick thread.\n11. Run the verification command from `references/90-verification.md` that\r\n   matches the host application.\r\n\r\n## Flower Source And Docs\r\n\r\nWhen the public Flower repository is available, inspect its README, examples,\r\nand module docs for exact API names before writing code. Application code should\r\nfollow the public API and examples first.\r\n\r\n```text\r\nhttps://github.com/flowerjvm/flower\r\nflower/README.md\r\nflower/docs/\r\n```\r\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}