Removed the donna.workspaces.worlds.python world#69
Conversation
There was a problem hiding this comment.
Pull request overview
This PR removes the Python-package-backed donna world implementation and switches the default donna world to a filesystem world rooted at .agents/donna, with workspace init/update syncing bundled Donna specs from donna/fixtures/specs.
Changes:
- Removed the
donna.workspaces.worlds.pythonworld and its constructor wiring. - Added workspace syncing of bundled specs into
.agents/donna(new--specs/--no-specsCLI option). - Introduced bundled specs/workflows under
donna/fixtures/specsand updated internal architecture/migration notes accordingly.
Reviewed changes
Copilot reviewed 22 out of 35 changed files in this pull request and generated 10 comments.
Show a summary per file
| File | Description |
|---|---|
| donna/workspaces/worlds/python.py | Deletes the Python-backed world implementation. |
| donna/workspaces/initialization.py | Adds specs sync logic and new install_specs toggles for init/update. |
| donna/workspaces/config.py | Changes default donna world to filesystem world pointing at .agents/donna. |
| donna/lib/worlds.py | Removes exported python world constructor; keeps filesystem constructor. |
| donna/fixtures/specs/usage/worlds.md | Adds/updates bundled “worlds” usage documentation for .agents/donna. |
| donna/fixtures/specs/usage/cli.md | Adds bundled CLI usage specification (fixtures). |
| donna/fixtures/specs/usage/artifacts.md | Adds bundled artifacts format/behavior specification (fixtures). |
| donna/fixtures/specs/rfc/work/request.md | Adds RFC “request” workflow fixture. |
| donna/fixtures/specs/rfc/work/plan.md | Adds RFC “plan” workflow fixture. |
| donna/fixtures/specs/rfc/work/do.md | Adds RFC end-to-end “do” workflow fixture. |
| donna/fixtures/specs/rfc/work/design.md | Adds RFC “design” workflow fixture. |
| donna/fixtures/specs/rfc/specs/request_for_change.md | Adds RFC document format specification fixture. |
| donna/fixtures/specs/rfc/specs/design.md | Adds design document format specification fixture. |
| donna/fixtures/specs/research/work/research.md | Adds research workflow fixture. |
| donna/fixtures/specs/research/specs/report.md | Adds research report format specification fixture. |
| donna/fixtures/specs/intro.md | Adds bundled “intro” specification fixture. |
| donna/cli/types.py | Introduces --specs/--no-specs option type for workspace commands. |
| donna/cli/commands/workspaces.py | Wires the new --specs/--no-specs option into `workspaces init |
| donna/init.py | Removes donna_artifacts_root marker used by the removed Python world. |
| changes/unreleased.md | Updates migration/breaking-change notes for removal of Python world + specs sync. |
| .donna/project/core/top_level_architecture.md | Updates architecture doc to reflect fixtures-based skills/specs distribution. |
| .agents/donna/usage/worlds.md | Updates the checked-in workspace copy of the “worlds” spec for .agents/donna. |
| .agents/donna/usage/cli.md | Adds checked-in workspace copy of CLI usage spec. |
| .agents/donna/usage/artifacts.md | Adds checked-in workspace copy of artifacts spec. |
| .agents/donna/rfc/work/request.md | Adds checked-in workspace copy of RFC “request” workflow. |
| .agents/donna/rfc/work/plan.md | Adds checked-in workspace copy of RFC “plan” workflow. |
| .agents/donna/rfc/work/do.md | Adds checked-in workspace copy of RFC “do” workflow. |
| .agents/donna/rfc/work/design.md | Adds checked-in workspace copy of RFC “design” workflow. |
| .agents/donna/rfc/specs/request_for_change.md | Adds checked-in workspace copy of RFC format spec. |
| .agents/donna/rfc/specs/design.md | Adds checked-in workspace copy of design format spec. |
| .agents/donna/research/work/research.md | Adds checked-in workspace copy of research workflow. |
| .agents/donna/research/specs/report.md | Adds checked-in workspace copy of research report spec. |
| .agents/donna/intro.md | Adds checked-in workspace copy of intro spec. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| if install_skills: | ||
| _sync_donna_skill(project_dir) | ||
|
|
||
| if install_specs: | ||
| _sync_donna_specs(project_dir) | ||
|
|
There was a problem hiding this comment.
update_workspace only syncs skills/specs but does not migrate existing .donna/config.toml entries that still reference the removed donna.lib.worlds.python world kind. After upgrading, workspaces created with older versions will fail at runtime during primitive resolution unless the config is rewritten (e.g., change the donna world to donna.lib.worlds.filesystem with path = ".agents/donna"). Consider performing this config migration here (or keeping a backward-compatible alias/constructor) so donna workspaces update is sufficient for existing projects.
| @@ -1,10 +1,14 @@ | |||
| ### Migration | |||
|
|
|||
| - Run `donna workspaces update` in existing projects so bundled Donna specs are installed into `.agents/donna` for the new filesystem-backed `donna` world. | |||
There was a problem hiding this comment.
Migration instructions say to run donna workspaces update to install bundled specs into .agents/donna, but existing workspaces will also still have .donna/config.toml pointing at the removed donna.lib.worlds.python kind. Add an explicit migration step (or note) to update the donna world config to donna.lib.worlds.filesystem with path = ".agents/donna", otherwise Donna will fail to start after upgrade.
| - Run `donna workspaces update` in existing projects so bundled Donna specs are installed into `.agents/donna` for the new filesystem-backed `donna` world. | |
| - Run `donna workspaces update` in existing projects so bundled Donna specs are installed into `.agents/donna` for the new filesystem-backed `donna` world. | |
| - In existing workspaces, update the `donna` world entry in `.donna/config.toml` to use `kind = "donna.lib.worlds.filesystem"` with `path = ".agents/donna"` so Donna loads bundled specs from the new location. |
|
|
||
| ### Protocol cells | ||
|
|
||
| Donna communicates its progress and requests by outputting inrofmation organized in "cells". There are two kinds of cells output: |
There was a problem hiding this comment.
Typo in user-facing docs: "inrofmation" should be "information".
| Donna communicates its progress and requests by outputting inrofmation organized in "cells". There are two kinds of cells output: | |
| Donna communicates its progress and requests by outputting information organized in "cells". There are two kinds of cells output: |
| - `donna -p <protocol> sessions status` — get the status of the current session. | ||
| - `donna -p <protocol> sessions details` — get detailed information about the current session, including list of active action requests. | ||
| - `donna -p <protocol> sessions start` — start a new session. This command resets session state AND removes all session-level artifacts. | ||
| - Run `donna -p <protocol> sessions reset` to reset the current session. This command resets session state BUT keeps all session-level artifacts. Use this command when you need to restart the worklow but keep all the artifacts you created during the session. |
There was a problem hiding this comment.
Typo in user-facing docs: "worklow" should be "workflow".
| - Run `donna -p <protocol> sessions reset` to reset the current session. This command resets session state BUT keeps all session-level artifacts. Use this command when you need to restart the worklow but keep all the artifacts you created during the session. | |
| - Run `donna -p <protocol> sessions reset` to reset the current session. This command resets session state BUT keeps all session-level artifacts. Use this command when you need to restart the workflow but keep all the artifacts you created during the session. |
| 2. If the step requires both research and implementation, split it into two steps: research step and implementation step. | ||
| 3. If the step required editing multiple artifacts (multiple files, multiple functions, etc.), split it into multiple steps, one per change required. | ||
| 4. If the step is too big or complex, split it into multiple smaller steps. | ||
| 5. Fux & improve naming and IDs in the step's title and body. |
There was a problem hiding this comment.
Typo in workflow instructions: "Fux & improve naming" should be "Fix & improve naming".
| 5. Fux & improve naming and IDs in the step's title and body. | |
| 5. Fix & improve naming and IDs in the step's title and body. |
|
|
||
| ## Overview | ||
|
|
||
| Donna is designed to to invert control flow: instead of agents deciding what to do next, the `donna` tells agents what to do next by following predefined workflows. |
There was a problem hiding this comment.
Grammar in user-facing docs: "designed to to invert" has a duplicated "to".
| Donna is designed to to invert control flow: instead of agents deciding what to do next, the `donna` tells agents what to do next by following predefined workflows. | |
| Donna 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. |
| 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 grooming loop by themselves — it take longer time, spends tokens and may lead to confusion of agents. |
There was a problem hiding this comment.
Grammar in user-facing docs: "it take longer time" should be "it takes longer time" (or rephrase).
| We may need coding agents on the each step of the process, but there no reason for agents to manage the whole grooming loop by themselves — it take longer time, spends tokens and may lead to confusion of agents. | |
| We may need coding agents on the each step of the process, but there no reason for agents to manage the whole grooming loop by themselves — it takes longer time, spends tokens and may lead to confusion of agents. |
| 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. |
There was a problem hiding this comment.
Wording/grammar: "text files, primary in Markdown format" should be "primarily in Markdown format".
| s3 buckets, git repositories, databases, etc. | ||
|
|
||
| Default worlds and there locations are: | ||
|
|
There was a problem hiding this comment.
Typo: "Default worlds and there locations are" should be "Default worlds and their locations are".
| 3. `{{ donna.lib.goto("fomalize_form_of_final_solution") }}` | ||
|
|
||
| ## Formalize form of final solution | ||
|
|
||
| ```toml donna | ||
| id = "fomalize_form_of_final_solution" |
There was a problem hiding this comment.
Operation id has a typo: id = "fomalize_form_of_final_solution" should be spelled formalize_form_of_final_solution for consistency/readability. If you rename it, make sure to update the corresponding goto target in the previous step as well.
| 3. `{{ donna.lib.goto("fomalize_form_of_final_solution") }}` | |
| ## Formalize form of final solution | |
| ```toml donna | |
| id = "fomalize_form_of_final_solution" | |
| 3. `{{ donna.lib.goto("formalize_form_of_final_solution") }}` | |
| ## Formalize form of final solution | |
| ```toml donna | |
| id = "formalize_form_of_final_solution" |
No description provided.