donna 0.2.0__py3-none-any.whl

donna/__init__.py

@@ -0,0 +1 @@
+donna_artifacts_root = "donna.artifacts"

donna/artifacts/usage/artifacts.md

@@ -0,0 +1,224 @@
+# Default Text Artifacts Behavior
+
+```toml donna
+kind = "donna.lib.specification"
+```
+
+This document describes the default format and behavior of Donna's text artifacts.
+This format and behavior is what should be expected by default from an artifact if not specified otherwise.
+
+## Overview
+
+An artifact is any text or binary document that Donna manages in its worlds. For example, via CLI commands `donna -p <protocol> artifacts …`.
+
+The text artifact has a source and one or more rendered representations, produced in specific rendering modes.
+
+— The source is the raw text content of the artifact as it is stored on disk or in remote storage.
+- The representation is the rendered version of the artifact for a specific rendering mode. In practice, the same source is rendered in `view` mode for CLI display, `execute` mode for workflow execution, and `analysis` mode for internal parsing and validation (see "Rendering artifacts").
+
+To change the artifact, developers and agents edit its source.
+
+To get information from the artifact, developers, agents and Donna view one of its representations (typically via the view rendering mode).
+
+**If you need an information from the artifact, you MUST view its representation**. Artifact sources are only for editing.
+
+Read the specification `{{ donna.lib.view("donna:usage:cli") }}` to learn how to work with artifacts via Donna CLI.
+
+## Source Format and Rendering
+
+The source of the text artifact is a Jinja2-template of Markdown document.
+
+When rendering the artifact, Donna processes the Jinja2 template with a predefined context (at minimum `render_mode` and `artifact_id`, and optionally `current_task`/`current_work_unit` during workflow execution), then renders the resulting Markdown content into the desired representation based on the selected rendering mode.
+
+**Artifact source should not use Jinja2 inheretance features** like `{{ "{% extends %}" }}` and `{{ "{% block %}" }}`.
+
+Donna provides a set of special directives that can and MUST be used in the artifact source to enhance its behavior. Some of these directives are valid for all artifacts, some are valid only for specific section kinds.
+
+Here are some examples:
+
+- `{{ "{{ donna.lib.view(<artifact-id>) }}" }}` — references another artifact. In `view`/`execute` modes it renders an exact CLI command to view the artifact; in `analysis` mode it renders a `$$donna ... $$` marker used for internal parsing.
+- `{{ "{{ donna.lib.goto(<workflow-operation-id>) }}" }}` — references the next workflow operation to execute. In `view`/`execute` modes it renders an exact CLI command to advance the workflow; in `analysis` mode it renders a `$$donna goto ... $$` marker used to extract workflow transitions.
+
+## Rendering artifacts
+
+Donna renders the same artifact source into different representations depending on the rendering mode. The mode is internal to Donna (users do not select it directly) and controls how directives are expanded and which metadata is included.
+
+- `view` — default representation used when the CLI loads artifacts for display (`artifacts view`, `artifacts list`, `artifacts validate`). This is the human/agent-facing output.
+- `execute` — representation used when Donna executes workflow operations (`sessions run`). It renders directives with task/work-unit context so the resulting text is actionable for the agent.
+- `analysis` — internal representation used during parsing and validation. It emits `$$donna ... $$` markers so Donna can extract workflow transitions and other structured signals.
+
+## Structure of a Text Artifact
+
+Technically, any valid Markdown document is a valid text artifact.
+
+However, Donna assignes special meaning to some elements of the Markdown document to provide enhanced behavior and capabilities.
+
+### Sections
+
+Artifact is devided into multiple sections:
+
+- H1 header and all text till the first H2 header is considered the `head section` of the artifact.
+- Each H2 header and all text till the next H2 header (or end of document) is considered a `tail section` of the artifact.
+
+Head section provides a description of the artifact and its purpose and MUST contain a configuration block of the artifact. The head section is also the artifact's `primary section` and is used when Donna needs to show a brief summary of the artifact, for example, when listing artifacts or when an operation targets the artifact without specifying a section.
+
+Tail sections describes one of the components of the artifact and CAN contain configuration blocks as well. Configuration blocks placed in subsections (h3 and below) count as part of the parent tail section.
+
+The content of the header (text after `#` or `##`) is considered the section title.
+
+Donna always interprets the head section as a general description of the artifact and treats it as the primary section.
+
+Donna interprets a tail section according to the primary section kind and configuration blocks in that section.
+
+### Configuration Blocks
+
+Configuration blocks are fenced code blocks with specified primary format, followed by the `donna` keyword and, optionally, list of properties.
+
+The supported primary formats are: TOML, JSON, YAML. **You MUST prefer TOML for configuration blocks**.
+
+The configuration block properties format is `property1 property2=value2 property3=value3"`, which will be parsed into a dictionary like:
+
+```python
+{
+    "property1": True,
+    "property2": "value2",
+    "property3": "value3",
+}
+```
+
+The content of the block is parsed according to the primary format and interpreted according its properties.
+
+Configuration blocks are parsed by Donna and removed from rendered Markdown representations; they remain in the source for editing and inspection (e.g., via `artifacts fetch` or the repository file).
+
+Fences without `donna` keyword are considered regular code blocks and have no special meaning for Donna.
+
+### Configuration Merging
+
+When a section contains multiple configuration blocks, Donna merges them in document order.
+
+- The merge is applied per section: the head section is merged independently, and each tail section has its own merged configuration.
+- Config blocks are merged in the order they appear; later blocks override earlier keys.
+- The merge is shallow: if a key maps to a nested object, a later block replaces the whole value (there is no deep merge).
+- Config blocks in subsections (H3 and below) belong to their parent H2 tail section and are merged into that section's configuration.
+
+## Section Kinds, Their Formats and Behaviors
+
+### Header section
+
+Header section MUST contain a config block with a `kind` property. The `kind` MUST be a full Python import path pointing to the primary section kind instance.
+
+Example (`donna` keyword skipped for examples):
+
+```toml
+kind = "donna.lib.specification"
+```
+
+Header section MUST also contain short human-readable description of the artifact outside of the config block.
+
+### Kind: Specification
+
+Specification artifacts describe various aspects of the project in a structured way.
+
+Currently there is no additional structure or semantics for this kind of artifact.
+
+### Kind: Workflow
+
+Workflow artifacts describe a sequence of operations that Donna and agents can perform to achieve a specific goal.
+
+Workflow is a Finite State Machine (FSM) where each tail section describes one operation in the workflow.
+
+Donna validates workflows by ensuring the start operation exists, reachable sections are valid operations, final operations have no outgoing transitions, and non-final operations have at least one outgoing transition. It does not currently report unreachable sections.
+
+Workflow start operation MUST be declared in the workflow head-section config via `start_operation_id`
+and MUST reference an existing operation section.
+
+Example (`donna` keyword skipped for examples):
+
+```toml
+kind = "donna.lib.workflow"
+start_operation_id = "start_operation"
+```
+
+Each tail section MUST contain config block with `id` and `kind` properties that specifies the identifier and kind of the operation.
+
+Example (`donna` keyword skipped for examples):
+
+```toml
+id = "operation_id"
+kind = "donna.lib.request_action"
+```
+
+#### Kinds of Workflow Operations
+
+1. `donna.lib.request_action` operation kind indicates that Donna will request the agent to perform some action.
+
+The content of the tail section is the text instructions for the agent on what to do.
+
+Example of the instructions:
+
+```
+1. Run `some cli command` to do something.
+2. If no errors encountered `{{ '{{ donna.lib.goto("next_operation") }}' }}`
+3. If errors encountered `{{ '{{ donna.lib.goto("error_handling_operation") }}' }}`
+
+Here may be any additional instructions, requirements, notes, references, etc.
+```
+
+`donna.lib.goto` directive will be rendered in the direct instruction for agent of what to call after it completed the action.
+
+**The body of the operation MUST contain a neat strictly defined algorithm for the agent to follow.**
+
+2. `donna.lib.run_script` operation kind executes a script from the operation body without agent/user interaction.
+
+The body of the operation MUST include exactly one fenced code block whose info string includes `<language> donna script`.
+Any other text in the operation body is ignored.
+
+Script example:
+
+```bash donna script
+#!/usr/bin/bash
+
+echo "Hello, World!"
+```
+
+Configuration options:
+
+```toml
+id = "<operation_id>"
+kind = "donna.lib.run_script"
+
+save_stdout_to = "<variable_name>"  # optional
+save_stderr_to = "<variable_name>"  # optional
+
+goto_on_success = "<next_operation_id>"  # required
+goto_on_failure = "<next_operation_id>"  # required
+goto_on_code = {                         # optional
+    "1" = "<next_operation_id_for_code_1>"
+    "2" = "<next_operation_id_for_code_2>"
+}
+
+timeout = 60  # optional, in seconds
+```
+
+Routing rules:
+
+- Exit code `0` routes to `goto_on_success`.
+- Non-zero exit codes first check `goto_on_code`, then fall back to `goto_on_failure`.
+- Timeouts are treated as exit code `124`.
+
+When `save_stdout_to` and/or `save_stderr_to` are set, the operation stores captured output in the task context
+under the specified variable names.
+
+3. `donna.lib.finish` operation kind indicates that the workflow is finished.
+
+Each possible path through the workflow MUST end with this operation kind.
+
+## Directives
+
+Donna provides multiple directives that MUST be used in the artifact source to enhance its behavior.
+
+Here they are:
+
+1. `{{ "{{ donna.lib.view(<full-artifact-id>) }}" }}` — references another artifact. In `view`/`execute` modes it renders an exact CLI command to view the artifact; in `analysis` mode it renders a `$$donna ... $$` marker.
+2. `{{ "{{ donna.lib.goto(<workflow-operation-id>) }}" }}` — references the next workflow operation to execute. In `view`/`execute` modes it renders an exact CLI command to advance the workflow; in `analysis` mode it renders a `$$donna goto ... $$` marker used for transition extraction.
+3. `{{ "{{ donna.lib.task_variable(<variable_name>) }}" }}` — in `view` mode renders a placeholder note about task-variable substitution, in `execute` mode renders the actual task-context value (or an explicit error marker if missing), and in `analysis` mode renders a `$$donna task_variable ... $$` marker.

donna/artifacts/usage/cli.md

@@ -0,0 +1,117 @@
+# Donna Usage Instructions
+
+```toml donna
+kind = "donna.lib.specification"
+```
+
+This document describes how agents MUST use Donna to manage and perform their workflows.
+
+**Agents MUST follow the instructions and guidelines outlined in this document precisely.**
+
+## Overview
+
+`donna` is a CLI tool that helps manage the work of AI agents like OpenAI Codex.
+
+It is designed to invert control flow: instead of agents deciding what to do next, the `donna` tells agents what to do next by following predefined workflows.
+
+The core idea is that most high-level workflows are more algorithmic than it may seem at first glance. For example, it may be difficult to fix a particular type issue in the codebase, but the overall process of polishing the codebase is quite linear:
+
+1. Ensure all tests pass.
+2. Ensure the code is formatted correctly.
+3. Ensure there are no linting errors.
+4. Go to the step 1 if you changed something in the process.
+5. Finish.
+
+We may need coding agents on the each step of the process, but there no reason for agents to manage the whole loop by themselves — it takes longer time, spends tokens and confuses agents.
+
+## Primary Rules
+
+- All work is always done in the context of a session. There is only one active session at a time.
+- You MUST always work on one task assigned to you.
+- If developer asked you to do something and you have no session, you create one with the `donna` tool.
+- If you have a session, you MUST keep all the information about it in your memory. Ask `donna` tool for the session details when you forget something.
+
+## Protocol
+
+Protocol selects the output formatting and behavior of Donna's CLI for different consumers (humans, LLMs, automation).
+When an agent invokes Donna, it SHOULD use the `llm` protocol (`-p llm`) unless the workflow explicitly requires another protocol.
+
+### Session workflow
+
+- You start session by calling `donna -p <protocol> sessions start`.
+- After you started a session:
+  1. List all possible workflows with command `donna -p <protocol> artifacts list`.
+  2. Choose the most appropriate workflow for the task you are going to work on or ask the developer if you are not sure which workflow to choose.
+  3. Start working by calling `donna -p <protocol> sessions run <workflow-id>`.
+  4. The `donna` tool will output descriptions of all operations it performs to complete the story.
+  5. The `donna` tool will output **action requests** that you MUST perform. You MUST follow these instructions precisely.
+- When you done doing your part, you call `donna -p <protocol> sessions action-request-completed <action-request-id> <next-full-operation-id>` to report that you completed the action request. `<next-full-operation-id>` MUST contain full identifier of the next operation, like `<world>:<artifact>:<operation-id>`.
+- After you report the result:
+  1. The `donna` tool will output what you need to do next.
+  2. You repeat the process until the story is completed.
+
+### Starting work
+
+- If the developer asked you to do something:
+  - run `donna -p <protocol> sessions status` to get the status of the current session.
+  - or run `donna -p <protocol> sessions details` to get detailed information about the current session, including list of active action requests.
+  - If there is no active session, start a new session by calling `donna -p <protocol> sessions start`.
+  - If the session is already active and there are no unfinished work in it, start a new session by calling `donna -p <protocol> sessions start`.
+  - If the session is already active and there are unfinished work in it, you MUST ask the developer whether to continue the work in the current session or start a new one.
+- If the developer asked you to continue your work, you MUST call `donna -p <protocol> sessions continue` to get your instructions on what to do next.
+
+### Working with artifacts
+
+An artifact is a markdown document with extra metadata stored in one of the Donna's worlds.
+
+Use the next commands to work with artifacts
+
+- `donna -p <protocol> artifacts list [--pattern <artifact-pattern>]` — list all artifacts corresponding to the given pattern. If `<artifact-pattern>` is omitted, list all artifacts in all worlds. Use this command when you need to find an artifact or see what artifacts are available.
+- `donna -p <protocol> artifacts view <world>:<artifact>` — get the meaningful (rendered) content of the artifact. This command shows the rendered information about the artifact. Use this command when you need to read the artifact content.
+- `donna -p <protocol> artifacts fetch <world>:<artifact>` — download the original source of the artifact content, outputs the file path to the artifact's copy you can change. Use this command when you need to change the content of the artifact.
+- `donna -p <protocol> artifacts update <world>:<artifact> <file-path>` — upload the given file as the artifact. Use this command when you finished changing the content of the artifact.
+- `donna -p <protocol> artifacts validate <world>:<artifact>` — validate the given artifact to ensure it is correct and has no issues.
+- `donna -p <protocol> artifacts validate-all [--pattern <artifact-pattern>]` — validate all artifacts corresponding to the given pattern.
+
+The format of `<artifact-pattern>` is as follows:
+
+- full artifact identifier: `<world>:<artifact>`
+- `*` — single wildcard matches a single level in the artifact path. Examples:
+  - `*:artifact:name` — matches all artifacts named `artifact:name` in all worlds.
+  - `world:*:name` — matches all artifacts with id `something:name` in the `world` world.
+- `**` — double wildcard matches multiple levels in the artifact path. Examples:
+  - `**:name` — matches all artifacts with id ending with `:name` in all worlds.
+  - `world:**` — matches all artifacts in the `world` world.
+  - `world:**:name` — matches all artifacts with id ending with `:name` in the `world` world.
+
+## IMPORTANT ON DONNA TOOL USAGE
+
+**Strictly follow described command syntax**
+
+**You MUST follow `donna` call conventions specified in**, by priority:
+
+  1. Direct instructions from the developer.
+  2. `AGENTS.md` document.
+  3. Specifications in `project:` world.
+  4. This document.
+
+**All Donna CLI commands MUST include an explicit protocol selection using `-p <mode>`.** Like `donna -p llm <command>`.
+
+**Pass text arguments to the tool in quotes with respect to escaping.** The tool MUST receive the exact text you want to pass as an argument.
+
+Use one of the next approaches to correctly escape text arguments:
+
+```
+# option 1
+donna -p <protocol> <command> <...>  $'# Long text\n\nwith escape sequences...'
+
+# option 2
+donna -p <protocol> <command> <...> \
+  "$(cat <<'EOF'
+# Long text
+
+with escape sequences...
+EOF
+)"
+
+```

donna/artifacts/usage/worlds.md

@@ -0,0 +1,36 @@
+# Donna World Layout
+
+```toml donna
+kind = "donna.lib.specification"
+```
+
+This document describes how Donna discovers and manages its dynamic and/or external artifacts.
+Including usage docs, work workflows, operations, current work state and additional code.
+
+## Overview
+
+In order to function properly and to perform in a full potential, Donna relies on a set of artifacts
+that guide its behavior and provide necessary capabilities.
+
+These artifacts are represented as text files, primary in Markdown format, however other text-based
+formats can be used as well, if explicitly requested by the developer or by the workflows.
+
+Donna discovers these artifacts by scanning the "worlds" specified in `<project-root>/.donna/config.toml`
+as `worlds` list. Most of worlds are filesystem folders, however other world types can be implemented such as:
+s3 buckets, git repositories, databases, etc.
+
+Default worlds and there locations are:
+
+- `donna` — `donna.artifacts` — the subpackage with artifacts provided by Donna itself.
+- `home` — `~/.donna/home` — the user-level donna artifacts, i.e. those that should be visible to all projects on this machine.
+- `project` — `<project-root>/.donna/project` — the project-level donna artifacts, i.e. those that are specific to this project.
+- `session` — `<project-root>/.donna/session` — the session world that contains the current state of work performed by Donna.
+
+All worlds have a free layout, defined by developers who own the particular world.
+
+## Write Access
+
+By default, worlds are read-only. Besides the next exceptions:
+
+- `session` in the project world is read-write, Donna stores its current state of work here.
+- `<project-root>/.donna` is read-write when the developer explicitly asks Donna to change it. For example, to add the result of performed work into project usage docs.

donna/artifacts/work/do_it.md

@@ -0,0 +1,142 @@
+# Meta Work Loop
+
+```toml donna
+kind = "donna.lib.workflow"
+start_operation_id = "start"
+```
+
+General purpose work planning and execution workflow. Use it when you need to do complex work and there is no more specific workflow available.
+
+## Start Work
+
+```toml donna
+id = "start"
+kind = "donna.lib.request_action"
+fsm_mode = "start"
+```
+
+1. Read the specification `{{ donna.lib.view("donna:work:planning") }}` if you haven't done it yet.
+2. Read the specification `{{ donna.lib.view("donna:usage:artifacts") }}` if you haven't done it yet.
+3. If the developer hasn't provided you a description of the work for this session, ask them to provide it.
+4. Create new session-level specification `session:work_scope` with developer-provided description of the work to be done.
+5. `{{ donna.lib.goto("create_work_description") }}`
+
+## Create Work Description
+
+```toml donna
+id = "create_work_description"
+kind = "donna.lib.request_action"
+```
+
+1. Read the specification `{{ donna.lib.view("donna:work:planning") }}` if you haven't done it yet.
+2. Read the specification `{{ donna.lib.view("donna:usage:artifacts") }}` if you haven't done it yet.
+3. Formulate a concise high-level description of the work to be done, based on the developer-provided description.
+4. Add this description to the `session:work_scope`.
+5. `{{ donna.lib.goto("list_primary_goals") }}`
+
+## List Primary Goals
+
+```toml donna
+id = "list_primary_goals"
+kind = "donna.lib.request_action"
+```
+
+1. Read the specification `{{ donna.lib.view("donna:work:planning") }}` if you haven't done it yet.
+2. Read the specification `{{ donna.lib.view("donna:usage:artifacts") }}` if you haven't done it yet.
+3. If you can add more goals based on existing `{{ donna.lib.view("session:work_scope") }}` add them to the specification.
+4. If you can polish the existing goals according to the quality criteria in the `{{ donna.lib.view("donna:work:planning") }}` do it.
+5. `{{ donna.lib.goto("list_objectives") }}`
+
+## List Objectives
+
+```toml donna
+id = "list_objectives"
+kind = "donna.lib.request_action"
+```
+
+You MUST list objectives that need to be achieved to complete each goal.
+
+1. Read the specification `{{ donna.lib.view("donna:work:planning") }}` if you haven't done it yet.
+2. Read the specification `{{ donna.lib.view("donna:usage:artifacts") }}` if you haven't done it yet.
+3. If you can add more objectives based on existing `{{ donna.lib.view("session:work_scope") }}` add them to the specification.
+4. If you can polish the existing objectives according to the quality criteria in the `{{ donna.lib.view("donna:work:planning") }}` do it.
+5. `{{ donna.lib.goto("list_constraints") }}`
+
+## List Constraints
+
+```toml donna
+id = "list_constraints"
+kind = "donna.lib.request_action"
+```
+
+1. Read the specification `{{ donna.lib.view("donna:work:planning") }}` if you haven't done it yet.
+2. Read the specification `{{ donna.lib.view("donna:usage:artifacts") }}` if you haven't done it yet.
+3. If you can add more constraints based on existing `{{ donna.lib.view("session:work_scope") }}` add them to the specification.
+4. If you can polish the existing constraints according to the quality criteria in the `{{ donna.lib.view("donna:work:planning") }}` do it.
+5. `{{ donna.lib.goto("list_acceptance_criteria") }}`
+
+## List Acceptance Criteria
+
+```toml donna
+id = "list_acceptance_criteria"
+kind = "donna.lib.request_action"
+```
+
+1. Read the specification `{{ donna.lib.view("donna:work:planning") }}` if you haven't done it yet.
+2. Read the specification `{{ donna.lib.view("donna:usage:artifacts") }}` if you haven't done it yet.
+3. If you can add more acceptance criteria based on existing `{{ donna.lib.view("session:work_scope") }}` add them to the specification.
+4. If you can polish the existing acceptance criteria according to the quality criteria in the `{{ donna.lib.view("donna:work:planning") }}` do it.
+5. `{{ donna.lib.goto("list_deliverables") }}`
+
+## List Deliverables
+
+```toml donna
+id = "list_deliverables"
+kind = "donna.lib.request_action"
+```
+
+1. Read the specification `{{ donna.lib.view("donna:work:planning") }}` if you haven't done it yet.
+2. Read the specification `{{ donna.lib.view("donna:usage:artifacts") }}` if you haven't done it yet.
+3. If you can list more deliverables based on existing `{{ donna.lib.view("session:work_scope") }}` add them to the specification.
+4. If you can polish the existing deliverables according to the quality criteria in the `{{ donna.lib.view("donna:work:planning") }}` do it.
+5. `{{ donna.lib.goto("prepare_plan") }}`
+
+## Prepare Work Plan
+
+```toml donna
+id = "prepare_plan"
+kind = "donna.lib.request_action"
+```
+
+1. Read the specification `{{ donna.lib.view("donna:work:planning") }}` if you haven't done it yet.
+2. Read the specification `{{ donna.lib.view("donna:usage:artifacts") }}` if you haven't done it yet.
+3. Read the specification `{{ donna.lib.view("session:work_scope") }}` if you haven't done it yet.
+4. Create new session-level workflow `session:work_execution` according to the scope of work you have defined.
+5. `{{ donna.lib.goto("execute_plan") }}`
+
+## Execute Plan
+
+```toml donna
+id = "execute_plan"
+kind = "donna.lib.request_action"
+```
+
+1. Run workflow `session:work_execution` to execute the work according to the plan.
+2. `{{ donna.lib.goto("groom_work") }}`
+
+## Groom Work
+
+```toml donna
+id = "groom_work"
+kind = "donna.lib.request_action"
+```
+
+1. Run the grooming workflow to ensure that the result is polished, clean, and ready for review.
+2. `{{ donna.lib.goto("finish") }}`
+
+## Finish
+
+```toml donna
+id = "finish"
+kind = "donna.lib.finish"
+```

donna/artifacts/work/do_it_fast.md

@@ -0,0 +1,98 @@
+# Show Workflow Spec + Schema
+
+```toml donna
+kind = "donna.lib.workflow"
+start_operation_id = "read_workflow_source"
+```
+
+<!-- This is a temporary worflow, later Donna should have a specialized command to display the spec -->
+
+This workflow guides an agent through loading a workflow artifact source, choosing the correct FSM graph DSL, and producing a concise schema summary with a graph and per-operation descriptions.
+
+## Read workflow source
+
+```toml donna
+id = "read_workflow_source"
+kind = "donna.lib.request_action"
+fsm_mode = "start"
+```
+
+1. Identify the full workflow artifact id to summarize from the developer request (for example: `project:work:grooming`).
+2. If the workflow id is missing or ambiguous, ask the developer to provide the exact id, then repeat this operation.
+3. Fetch the workflow artifact source with:
+   - `./bin/donna.sh artifacts fetch '<workflow-id>'`
+4. Read the fetched source from the path printed by the command to capture:
+   - Workflow name (H1 title) and short description.
+   - The start operation (from `start_operation_id` in the workflow head config, which must be marked with `fsm_mode = "start"`).
+   - Each operation `id`, `kind`, and any {% raw %}`{{ donna.lib.goto(...) }}`{% endraw %} transitions in its body.
+5. Continue to {{ donna.lib.goto("select_fsm_dsl") }}.
+
+## Select FSM graph DSL
+
+```toml donna
+id = "select_fsm_dsl"
+kind = "donna.lib.request_action"
+```
+
+1. Determine whether the developer requested a specific FSM graph DSL (from the original request or provided inputs).
+2. If a DSL is specified, record it verbatim for rendering.
+3. If no DSL is specified, select Mermaid DSL.
+4. Continue to {{ donna.lib.goto("render_schema") }}.
+
+## Render short schema
+
+```toml donna
+id = "render_schema"
+kind = "donna.lib.request_action"
+```
+
+1. Produce the schema output in the exact meta format below, using the selected DSL for the FSM graph:
+
+```
+# <workflow name>
+
+<very short one sentence description of what it does>
+
+<FSM graph description in some DSL>
+
+<list of operations: `<id>` — <short one sentence description of what it does>
+```
+
+2. Ensure the FSM graph includes all operations and transitions, and clearly marks the start and finish operations.
+3. For Mermaid, use a `stateDiagram-v2` or `flowchart` representation and keep node ids aligned with operation ids.
+4. For each operation list entry, write a single concise sentence that is clean, complete, and faithful to the operation body.
+5. Continue to {{ donna.lib.goto("refine_schema") }}.
+
+## Refine schema output
+
+```toml donna
+id = "refine_schema"
+kind = "donna.lib.request_action"
+```
+
+1. Re-read the produced schema and improve clarity and correctness without changing the required format.
+2. Tighten wording to keep each description to a single clean sentence while still being thorough and accurate.
+3. Ensure the DSL selection rule is reflected in the graph and described output.
+4. Continue to {{ donna.lib.goto("validate_schema") }}.
+
+## Validate schema output
+
+```toml donna
+id = "validate_schema"
+kind = "donna.lib.request_action"
+```
+
+1. Verify the output contains the title, one-sentence description, FSM graph, and operation list in the required order.
+2. Confirm the chosen DSL is correct (developer-specified or Mermaid by default).
+3. Confirm each operation description is a single sentence and matches the operation purpose.
+4. If any check fails, return to {{ donna.lib.goto("refine_schema") }}.
+5. If all checks pass, proceed to {{ donna.lib.goto("finish") }}.
+
+## Finish
+
+```toml donna
+id = "finish"
+kind = "donna.lib.finish"
+```
+
+Workflow complete.