Changed the default location of project specs to specs/

README.md

@@ -45,7 +45,7 @@ Donna executes such loops for the agents, thereby saving time, context, and toke
 
 ## Example
 
-Donna is developed via Donna itself. You can find real-life examples of workflows and specifications in the [.donna/project](./.donna/project) folder of this repository.
+Donna is developed via Donna itself. You can find real-life examples of workflows and specifications in the [specs](./specs) folder of this repository.
 
 The example below is a simplified version of the polishing workflow that formats code, runs linters, and fixes found problems until all checks pass. It uses the single operation type `donna.lib.request_action` to ask the agent to perform specific instructions.
 
@@ -124,7 +124,7 @@ Generally speaking, **all you need is `donna.lib.request_action` operation** —
 
 </details>
 
-You can find a more complex implementation of the same workflow in the [polish.md](./.donna/project/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.md](./specs/work/polish.md) file. It demonstrates other Donna operations, such as running scripts directly and branching.
 
 ## Installation
 
@@ -225,7 +225,7 @@ By default, Donna uses the next worlds:
 
 - `donna` — artifacts provided by Donna itself;
 - `home` — user-level artifacts in `<HOME>/.donna/` folder;
-- `project` — project-level artifacts in `<project-root>/.donna/project/` folder;
+- `project` — project-level artifacts in `<project-root>/specs/` folder;
 - `session` — session-level artifacts in `<project-root>/.donna/session/` folder.
 
 A world can be read-only. By default, writable worlds are `session` (current work scope) and `project` (project scope).

changes/unreleased.md

@@ -1,10 +1,14 @@
 ### Migration
 
+- Move project-specific specs from `.donna/project` to `specs`, or set an explicit `project` world path in your Donna workspace config before upgrading.
 - Run `donna workspaces update` in existing projects so bundled Donna specs are installed into `.agents/donna` for the new filesystem-backed `donna` world.
 - Update your scripts and specs to use external tools or direct file edits to create, update, move, copy, or delete world artifacts instead using removed Donna commands.
 
 ### Changes
 
+- Changed the default location of project specs to `specs/`.
+  - Updated the default `project` world path to load from `specs/` instead of `.donna/project/`.
+  - Rewrote the moved project specs and repository docs to reference the new `specs/` location.
 - `--tag` option is replaced with `--predicate` in all CLI commands that accept artifact patterns.
 - Removed the Python donna world.
   - Added workspace spec dumping into `.agents/donna` on `donna workspaces init` and `donna workspaces update`.

donna/fixtures/specs/usage/worlds.md

@@ -23,7 +23,7 @@ Default worlds and there locations are:
 
 - `donna` — `<project-root>/.agents/donna` — the project-local bundled Donna specs installed from `donna/fixtures/specs` by workspace init/update.
 - `home` — `~/.donna/home` — the user-level donna artifacts, i.e. those that should be visible for all workspaces on this machine.
-- `project` — `<project-root>/.donna/project` — the project-level donna artifacts, i.e. those that are specific to this project.
+- `project` — `<project-root>/specs` — 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.

donna/workspaces/config.py

@@ -24,6 +24,7 @@
 DONNA_WORLD_SESSION_DIR_NAME = "session"
 DONNA_WORLD_PROJECT_DIR_NAME = "project"
 DONNA_WORLD_HOME_DIR_NAME = "home"
+DONNA_WORLD_PROJECT_PATH = pathlib.Path("specs")
 
 
 class WorldConfig(BaseEntity):
@@ -73,7 +74,7 @@ def _create_default_worlds() -> list[WorldConfig]:
                 "id": WorldId("project"),
                 "kind": "donna.lib.worlds.filesystem",
                 "session": False,
-                "path": pathlib.Path(DONNA_DIR_NAME) / DONNA_WORLD_PROJECT_DIR_NAME,
+                "path": DONNA_WORLD_PROJECT_PATH,
             }
         ),
         WorldConfig.model_validate(

.donna/project/intro.md → specs/intro.md

@@ -46,7 +46,8 @@ We may need coding agents on each step of the process, but there is no reason fo
 ## Points of interest
 
 - `./donna/` — a directory containing source code of project — `donna` CLI tool.
-- `./.donna/` — a directory containing project-specific donna artifacts that is used to manage the work of AI agents on this project.
+- `./specs/` — a directory containing project-specific donna artifacts that is used to manage the work of AI agents on this project.
+- `./.donna/` — a directory containing donn-specific artifacts that is used to manage the work of AI agents on this project.
 
 ## Specifications of interest