Flower

View saved version →

---
name: flower-action-runtime-guide
description: Use when creating, building, modifying, reviewing, migrating, or testing Java code that uses flower-action-runtime, including new Maven or Gradle project setup, Maven Central dependency and backend-module selection, ActionProposal and ActionDefinition design, registry/validation/policy/approval/pre-execution controls, visibility-safe owner-aware in-memory or JDBC duplicate handling, explicit failure retry policy, synchronous/async/deferred executor selection, ActionRun and RunStore persistence, JDBC CAS concurrency, completion/cancellation/recovery, Flower workflow or event-loop backends, and 0.1/0.2-to-0.3 migration.
---

# Flower Action Runtime Guide

## Overview

Use this skill to keep business actions behind one explicit control boundary
while supporting approval, audit, asynchronous work, durable completion, and
safe concurrent state changes.

This skill owns action-runtime guidance. When the host also authors Flower
Flows, Steps, Guards, Workers, event waits, or checkpoints, also load the
sibling `flower-app-guide` skill and follow both sets of rules.

## Start Here

Always read:

- `references/00-guide-version.md`
- `references/01-runtime-quick-rules.md`
- `references/90-verification.md`

Then read the reference that matches the task.

## Reference Routing

- Creating a Maven or Gradle host, choosing Action Runtime modules, adding or
  upgrading dependencies, or resolving Flower compatibility: read
  `references/05-build-and-module-selection.md`.
- Designing actions, proposal identity, definitions, policy, approval,
  pre-execution checks, results, audit, or idempotency: read
  `references/10-action-model-and-controls.md`.
- Choosing synchronous, in-process async, or durable deferred execution and
  implementing completion/cancellation: read
  `references/20-execution-modes.md`.
- Working with `ActionRun`, custom `RunStore`, JDBC schema/migrations, CAS,
  recovery, or multiple server instances: read
  `references/30-persistence-and-concurrency.md`.
- Selecting `DefaultActionRuntime`, the workflow backend, or the event-loop
  backend: read `references/40-flower-backends.md`.
- Writing unit, parity, concurrency, persistence, or recovery tests: read
  `references/50-testing.md`.
- Integrating the runtime into REST, MCP, schedulers, AI planners, Spring, a
  domain application, or Flower's common observation pipeline: read
  `references/60-host-integration.md`.

## Workflow

1. Identify the business side effect and every entry point that can request it.
2. Before changing a host build, read
   `references/05-build-and-module-selection.md`, preserve compatible host
   dependency management, and select only requirement-backed modules. Pin the
   published Maven Central `0.3.3` artifacts and verify APIs against the
   `v0.3.3` source tag. Inspect a mutable checkout only when modifying the
   runtime itself; its main branch may be a later SNAPSHOT.
3. Define a stable action id and register exactly one controlled executor.
4. Map request channel, proposer type, execution principal, tenant, run id, and
   idempotency key without collapsing them into one actor field. In 0.3,
   `ActionOrigin` no longer exists.
5. Configure validation, policy, approval, duplicate handling, audit/trace, and
   the pre-execution guard before exposing the action.
6. Choose the executor mode by lifetime and durability, not by convenience.
7. Use a queryable `RunStore` for approval, async, deferred, callback, or
   cancellation work. `InMemoryRunStore` may be sufficient for same-JVM
   local/test use; use a shared durable store for restart-sensitive,
   multi-instance, or production deferred work.
8. If Flower drives the backend, keep Worker/EventWorker ticks non-blocking and
   keep governance semantics in the shared action pipeline.
9. Add focused failure, resume, race, and recovery tests. Before reporting the
   work complete, map every applicable control to

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 11 — file references are metadata, not package contents.

View saved version →

---
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.
---

# Flower App Guide

## Overview

Use this skill when implementing application workflows with Flower. The goal is
to help an AI coding agent produce explicit, testable Flow/Step application code
instead of scattered callbacks, hidden polling loops, sleeps, or ad-hoc status
switches.

This skill is for applications that use Flower. It is not primarily for
modifying the Flower framework source itself.

Use `flower-agent-guide` for AgentRun, Tool-loop, transcript, or Agent model
gateway semantics. Use `flower-ai-harness-guide` for one AI task's validation,
refine, fallback, provider, or recovery semantics. Load this app guide as well
when either task changes host Flower wiring or Flow/Step code.

## Start Here

Always read:

- `references/00-guide-version.md`
- `references/01-app-quick-rules.md`
- `references/90-verification.md`

Then read the area-specific reference that matches the application work.

## Reference Routing

- Creating a Maven or Gradle host, choosing Flower modules, adding or upgrading
  dependencies, configuring the Spring Boot starter, selecting offline
  evaluation support, or installing
  `flower-check`: read `references/05-build-and-module-selection.md`.
- Designing a Flow, Step classes, Step ids, StepResult transitions, or app workflow module: read `references/10-flow-step-authoring.md`.
- Waiting for Kafka/domain events, callbacks, signals, timeouts, or Bloom events: read `references/20-events-and-waits.md`.
- Durable application flows, checkpoints, resume, idempotency, or `ExecutionContext`: read `references/30-durable-app-flows.md`.
- Tests for Flow behavior, manual ticks, fake clocks, event publishing, or recovery tests: read `references/40-testing-with-testkit.md`.
- Event-driven app workloads such as LLM/tool/external/human waits that fit `flower-eventloop`: read `references/50-eventloop-for-apps.md`.
- Adding `flower-check` to an application build or fixing checker findings: read `references/60-flower-check-adoption.md`.
- Visualizing the static Flow structure of a source project, producing a
  machine-readable Flow inventory, or checking structural changes with
  `flower-flow-graph`: read `references/65-flow-graph-tooling.md`.
- Using Step Guards for pre-step checks, holds, redirects, or fail-fast conditions: read `references/70-step-guards.md`.
- Inspecting Engine, Worker, Flow, or Step execution in a Spring Boot host,
  exposing a protected dump endpoint or built-in console, or selecting
  observability integration: read
  `references/80-spring-boot-observability.md`.
- Connecting a Flower application to the standalone Flower Studio, exporting
  correlated observation or evaluation JSONL, or inspecting local Traces,
  execution graphs, evaluations, and monitoring: read
  `references/85-flower-studio-integration.md`.

## Workflow

1. Inspect the host build, Java and Spring baseline, execution model, database,
   and test setup. For a new project or dependency change, select the smallest
   requirement-backed module set from
   `references/05-build-and-module-selection.md`.
2. Identify the application workflow being modeled and the domain state that is
   the source of truth.
3. Choose whether the ordinary tick-driven Flower model or the event-loop model
   fits the workload.
4. Model business phases as explicit Steps with stable string step ids.
5. Choose

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 15 — file references are metadata, not package contents.