readme

Author: Tiendil

README.md

@@ -38,9 +38,8 @@ Donna executes such loops for the agents, thereby saving time, context, and toke
 - **Saves context, tokens and time** — agents do not need to think when thinking is not required.
 - **Readable artifacts** — all workflows and specifications are pure Markdown files with some [Jinja2](https://github.com/pallets/jinja) templating.
 - **Artifact management** — non-fuzzy navigation and smart agent-focused rendering of artifacts.
-- **Artifact distribution** — install your docs/workflows/skills as a Python lib.
 - **Agent-centric behavior** — Donna guides agents through workflows, helps them be on the path, and fixes mistakes.
-- **Extensible architecture** — implement your own operations, validators, renderers; add support for new artifact formats and storages (worlds).
+- **Extensible architecture** — implement your own operations, validators, renderers, and artifact sources.
 - **Batteries included** — Donna goes with a set of pre-defined workflows, so you can start using it right away.
 
 ## Example
@@ -117,14 +116,14 @@ What you may notice:
 
 Directives, like `{{ goto("operation_id") }}`, render itself depending on the context:
 
-- For the agent, they render an exact CLI command to run, such as `donna -p llm sessions action-request-completed <action-request-id> 'artifact_id:operation_id'`.
+- For the agent, they render an exact CLI command to run, such as `donna -p llm sessions action-request-completed <action-request-id> '@/specs/work/polish.donna.md:finish'`.
 - For Donna, they render a specific marker that can be extracted and used to analyze an artifact. For example, Donna uses `goto` directives to build an FSM of the workflow and validate it before running: does each operation exist, can the workflow be completed, are there unreachable operations, etc.
 
 Generally speaking, **all you need is `donna.lib.request_action` operation** — it is enough to achieve a great deal of automation by delegating some decisions to the agent. However, there are some more specific operations that simplify things and make workflows more agile or performant.
 
 </details>
 
-You can find a more complex implementation of the same workflow in the [polish.md](./specs/work/polish.md) file. It demonstrates other Donna operations, such as running scripts directly and branching.
+You can find a more complex implementation of the same workflow in the [polish.donna.md](./specs/work/polish.donna.md) file. It demonstrates other Donna operations, such as running scripts directly and branching.
 
 ## Installation
 
@@ -146,8 +145,11 @@ donna workspaces init
 Donna will:
 
 - Create a `.donna/` folder in your project root with a default configuration in `.donna/config.toml`.
+- Sync bundled Donna specs into `.agents/donna/`.
 - Install skills into `.agents/skills/` folder.
 
+If you upgrade Donna later, run `donna workspaces update` to refresh `.agents/donna/` and `.agents/skills/`.
+
 3. Ask your agent to do something like `$donna-do Add a button that …`. The agent will discover the appropriate workflow and execute it.
 
 ## Skills
@@ -177,9 +179,9 @@ Use `donna --help` for a quick reference.
 
 You find detailed documentation in the agent instructions — they are readable and always accurate:
 
-- [CLI specification](./donna/artifacts/usage/cli.md) — full list of commands and how to use them.
-- [Artifacts](./donna/artifacts/usage/artifacts.md) — what are Donna artifact and how to use them.
-- [Worlds](./donna/artifacts/usage/worlds.md) — how Donna discovers and manages its artifacts.
+- [CLI specification](./.agents/donna/usage/cli.donna.md) — full list of commands and how to use them.
+- [Artifacts](./.agents/donna/usage/artifacts.donna.md) — what Donna artifacts are and how to use them.
+- [Filesystem layout](./.agents/donna/usage/worlds.donna.md) — how Donna discovers and manages artifacts on the filesystem.
 
 The documentation below covers aspects important to humans and partially duplicates the agent's instructions.
 
@@ -205,32 +207,21 @@ Note that the default Donna workflows are designed to be reliable and useful for
 
 Points of interest:
 
-- [donna:rfc:specs:request_for_change](./donna/artifacts/rfc/specs/request_for_change.md) — specification of the RFC document.
-- [donna:rfc:work:request](./donna/artifacts/rfc/work/request.md) — workflow to create a RFC document.
-- [donna:rfc:work:plan](./donna/artifacts/rfc/work/plan.md) — workflow to plan work on an RFC — creates a new workflow.
-- [donna:rfc:work:do](./donna/artifacts/rfc/work/do.md) — meta workflow to automate the whole work from a developer request to a changelog update.
-
-## Artifacts and Worlds
-
-- Artifacts are something that Donna owns. Currently, they are Markdown files with workflows and specifications.
-- Worlds are storages for artifacts. Currently, Donna supports two types of worlds:
-    - `donna.lib.worlds.filesystem` — a folder on the filesystem.
-    - `donna.lib.worlds.python` — a Python package.
-
-**Please, tell if you need other world types.** It looks interesting to have `http`, `s3`, `git`, `sql` worlds. How about an `email` world that allows you to send a workflow to someone agent and get the results back in your mailbox?
-
-A world ID is the first part of an artifact ID. For example, `donna:usage:cli` artifact resides in the `donna` world.
+- [@/.agents/donna/rfc/specs/request_for_change.donna.md](./.agents/donna/rfc/specs/request_for_change.donna.md) — specification of the RFC document.
+- [@/.agents/donna/rfc/work/request.donna.md](./.agents/donna/rfc/work/request.donna.md) — workflow to create a RFC document.
+- [@/.agents/donna/rfc/work/plan.donna.md](./.agents/donna/rfc/work/plan.donna.md) — workflow to plan work on an RFC and create a new workflow.
+- [@/.agents/donna/rfc/work/do.donna.md](./.agents/donna/rfc/work/do.donna.md) — meta workflow to automate the whole work from a developer request to a changelog update.
 
-By default, Donna uses the next worlds:
+## Artifacts on Filesystem
 
-- `donna` — artifacts provided by Donna itself;
-- `home` — user-level artifacts in `<HOME>/.donna/` folder;
-- `project` — project-level artifacts in `<project-root>/specs/` folder;
-- `session` — session-level artifacts in `<project-root>/.donna/session/` folder.
+- Artifacts are text files Donna reads and validates. In practice they are usually Markdown workflows and specifications stored as `.donna.md` files.
+- Donna discovers artifacts directly in the project filesystem and limits what is visible via `.donna/config.toml:file_filters`.
 
-A world can be read-only. By default, writable worlds are `session` (current work scope) and `project` (project scope).
+By default, Donna uses these artifact areas:
 
-Agents are not allowed to edit artifacts through Donna CLI directly because artifact consistency is important. Instead, they update the underlying files in writable worlds and rely on Donna validation when needed.
+- `specs/` — project-owned artifacts.
+- `.agents/donna/` — bundled Donna specs and workflows synced by `donna workspaces init` or `donna workspaces update`.
+- `.donna/session/` — session artifacts and Donna runtime state.
 
 ### Rendering
 
@@ -240,44 +231,53 @@ More about Jinja2 rendering is described a bit further.
 
 ### Artifacts Discovery
 
-Artifact is identified by its id: `<world>:<colon-separated-path>`, for example, `donna:usage:cli`.
+Artifact ids are project-relative filepaths prefixed with `@/`. Section ids append `:section_id` to the artifact id.
 
-You and agents can `list` artifacts and `view` them.
+Examples:
+
+- `@/specs/work/polish.donna.md`
+- `@/.agents/donna/usage/cli.donna.md`
+- `@/.donna/session/execute_rfc.donna.md:review_changes`
 
-- `donna -p llm artifacts list <pattern>` — shows a short description from its h1 section.
+You and agents can `list`, `view`, and `validate` artifacts.
+
+- `donna -p llm artifacts list [<pattern>]` — shows a short description from its h1 section.
 - `donna -p llm artifacts view <pattern>` — shows the full content of the artifact with proper rendering.
+- `donna -p llm artifacts validate [<pattern>]` — validates matching artifacts.
+
+Commands accept both precise artifact ids and glob patterns. Patterns may use absolute ids like `@/...` or rooted wildcard forms like `**/intro.donna.md`.
 
-Both commands accept both precise artifact ids and glob patterns. Patterns allow using:
+Patterns allow using:
 
-- `*` to replace a single path segment;
-- `**` to replace multiple path segments.
+- `*` — matches zero or more characters inside one path level.
+- `?` — matches exactly one character inside one path level.
+- `[]` — matches a single character class inside one path level.
+- `**` — matches zero or more path levels.
 
 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.
-- `**: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.
+- `@/*.donna.md` — matches all artifacts directly under the project root.
+- `@/**/intro.donna.md` — matches all artifacts named `intro.donna.md`.
+- `@/.donna/session/**` — matches all session artifacts.
+- `**/test_*.donna.md` — matches artifact filenames that start with `test_`.
 
-Both commands also accept `--predicate/-p '<python-expression>'` option to filter artifacts by
-their primary section properties (available as `section` inside expression).
+Commands that accept an artifact pattern also support `--predicate '<python-expression>'` to filter by primary section properties available as `section`.
 
 Currently, Donna supports two artifact tags:
 
 - `workflow` — marks a workflow artifact — is set automatically by Donna.
 - `specification` — marks a specification artifact — is set automatically by Donna.
 
 You can find all workflows with the command
-`donna -p llm artifacts list '**' --predicate '"workflow" in section.tags'`.
+`donna -p llm artifacts list --predicate '"workflow" in section.tags'`.
 
 ## Sessions
 
-`session` world contains the current state of work performed by Donna: all documents and workflows that are created during work and should not be stored permanently in the project.
+`<project-root>/.donna/session/` contains the current state of work performed by Donna: runtime state plus temporary documents and workflows created during the session.
 
 The developer is responsible for starting/resetting sessions with commands from `donna -p human sessions` group.
 
-- On session start, Donna removes everything from the previous session and creates a fresh `session` world.
+- On session start, Donna removes everything from the previous session and creates a fresh session directory.
 - On session reset donna resets the state of the current session (tasks, action requests, etc.), but keeps artifacts.
 
 The agent is encouraged not to manage sessions directly, because it doesn't have enough context to decide when session artifacts may be safely removed.
@@ -303,7 +303,7 @@ To execute a workflow, Donna uses a simplified virtual machine (VM) that maintai
 
 ### Operations
 
-You can find detailed docs on built-in operations in the [artifacts documentation](./donna/artifacts/usage/artifacts.md).
+You can find detailed docs on built-in operations in the [artifacts documentation](./.agents/donna/usage/artifacts.donna.md).
 
 Here is a short list of them:
 
@@ -320,15 +320,15 @@ Donna can detect errors (in artifacts, in execution, etc). If an error can be fi
 <summary><strong>An example of error message from Donna</strong></summary>
 
 ```bash
-$ donna -p llm sessions run project:work:polish
+$ donna -p llm sessions run @/specs/work/polish.donna.md
 
 kind=artifact_validation_error
 media_type=text/markdown
-artifact_id=project:work:polish
+artifact_id=@/specs/work/polish.donna.md
 error_code=donna.artifacts.section_not_found
 section_id=run_autoflake_scriptx
 
-Error in artifact 'project:work:polish', section 'run_autoflake_scriptx': Section `run_autoflake_scriptx` is not available in artifact `project:work:polish`.
+Error in artifact '@/specs/work/polish.donna.md', section 'run_autoflake_scriptx': Section `run_autoflake_scriptx` is not available in artifact `@/specs/work/polish.donna.md`.
 
 Ways to fix:
 
@@ -352,11 +352,11 @@ The simplest example of such generation is currently used as a primary way for D
 
 ### Discovering workflows
 
-If you want to run a child workflow from an operation, you can just instruct an agent like `Run the workflow project:work:my-cool-workflow` and the agent will find it and run.
+If you want to run a child workflow from an operation, you can just instruct an agent like `Run the workflow @/specs/work/my-cool-workflow.donna.md` and the agent will find it and run.
 
 However, it is not very agile. Instead, I suggest you describe the desired outcome and let the agent find the most suitable workflow. In that case, you'll be able to define customized workflows for specific types of changes and let the agent choose the best one for the current situation.
 
-For example, you can have two workflows `project:work:write-backend-test` and `project:work:write-frontend-test`, and your operation can say `Run the workflow that will write a test for the current change`, and the agent will choose the most suitable workflow based on the context and the workflow descriptions.
+For example, you can have two workflows `@/specs/work/write-backend-test.donna.md` and `@/specs/work/write-frontend-test.donna.md`, and your operation can say `Run the workflow that will write a test for the current change`, and the agent will choose the most suitable workflow based on the context and the workflow descriptions.
 
 ## Jinja2 rendering
 
@@ -378,7 +378,7 @@ Donna defines a set of built-in Jinja2 functions that provide artifacts with the
 
 Directives are used in the next way: `{{ python.import.path(<args>) }}`.
 
-You can find a detailed documentation of all built-in directives in the [artifacts documentation](./donna/artifacts/usage/artifacts.md).
+You can find a detailed documentation of all built-in directives in the [artifacts documentation](./.agents/donna/usage/artifacts.donna.md).
 
 Here they are:
 
@@ -399,35 +399,17 @@ All Donna logic is referenced by Python import paths. That means:
 
 - You can implement your own functionality and use it with Donna.
 - You can enrich your Python packages with additional code to work with Donna.
-- You can distribute your Donna artifacts as Python packages.
 
 What you can implement:
 
 - Custom sections (including operations) for Donna artifacts. Check [./donna/primitives/artifacts](./donna/primitives/artifacts) and [./donna/primitives/operations](./donna/primitives/operations) subpackages for examples.
 - Custom rendering directives. Check [./donna/primitives/directives](./donna/primitives/directives) subpackage for examples.
-- Custom worlds. Check [./donna/workspaces/worlds](./donna/workspaces/worlds) subpackage for examples.
-- Custom parsers for artifacts. Check [./donna/workspaces/sources](./donna/workspaces/sources) subpackage for examples.
+- Custom artifact parsers. Check [./donna/workspaces/sources](./donna/workspaces/sources) subpackage for examples.
 
-Worlds and sources are configured in the `.donna/config.toml` file of your project.
+Sources and file filters are configured in the `.donna/config.toml` file of your project.
 
 Sections and directives are used directly in artifacts by their Python import paths.
 
-## Distribute Your Artifacts
-
-Since Donna world can be a Python lib, you can distribute your artifacts as a Python package.
-
-To define a Donna world in you package you must place a variable `donna_artifacts_root` in your package `__init__.py` file with a import path to the root subpackage with your artifacts.
-
-On the example of Donna:
-
-```python
-donna_artifacts_root = "donna.artifacts"
-```
-
-After that, you can install your package and add the world into the `.donna/config.toml` file of your project.
-
-Since you distribute text files, **you package is not dependent on Donna itself — no additional dependencies are required.**
-
 ## Feedback wanted
 
 Donna is still young and has multiple experimental features — I really appreciate any feedback, ideas, and contributions to make it better.