docs: add workflow automation platform spec

.agents/tasks/2025/08/21-0939-codetype-interface

@@ -40,3 +40,61 @@ Implement the CodeObjectWrapper as designed. Update the Tracer trait as well as
 There is an issue in the current implementation. We don't use caching effectively, since we create a new CodeObjectWrapper at each callback_xxx call. We need a global cache, probably keyed by the code object id. Propose design changes and update the design documents. Don't implement the changes themselves before I approve them.
 --- FOLLOW UP TASK ---
 Implement the global code object registry.
+
+--- FOLLOW UP TASK ---
+Take a look at agents.just and scripts/. Also at the design docs for jj-workspaces. This is a proof-of-concept solution for defining and running agent workflows defined by the user. I want to create a real product based on this s proof of concept.\n\nUsers should be able to define their own workflows. They should also be able to publish workflows and fetch them from a central repository. It should be possible to parallelize work - be able to work on several workflows at once.\n\nCreate a technical specification for the components that need to be developed for this product. We will use Rust as our main programming language
+--- FOLLOW UP TASK ---
+In previous turns, the user had the following interaction with the agent:
+
+<TURN_1>
+<USER_INPUT>
+Take a look at agents.just and scripts/. Also at the design docs for jj-workspaces. This is a proof-of-concept solution for defining and running agent workflows defined by the user. I want to create a real product based on this s proof of concept.
+
+Users should be able to define their own workflows. They should also be able to publish workflows and fetch them from a central repository. It should be possible to parallelize work - be able to work on several workflows at once.
+
+Create a technical specification for the components that need to be developed for this product. We will use Rust as our main programming language 
+</USER_INPUT>
+<ASSISTANT_OUTPUT>
+
+**Summary**
+* Authored a comprehensive workflow automation platform specification covering product goals, requirements, and a full Rust-based architecture spanning workflow definitions, execution engine, workspace manager, CLI, registry services, observability, and packaging considerations.
+
+
+* Documented migration steps from the existing proof of concept along with open questions to guide the transition to the production platform.
+
+
+
+**Testing**
+* ⚠️ Not run (not requested for documentation-only change).
+
+</ASSISTANT_OUTPUT>
+</TURN_1>
+
+
+The user was unsatisfied with the code that the agent previously produced, which can be found as the latest commit in the git history.
+
+<PREVIOUS_PR_TITLE>
+docs: add workflow automation platform spec
+</PREVIOUS_PR_TITLE>
+
+<PREVIOUS_PR_DESCRIPTION>
+## Summary
+- add a technical specification for the workflow automation product
+- describe requirements, system architecture, and crate breakdown for a Rust implementation
+- cover registry service, CLI, executor, workspace management, observability, and migration steps
+
+## Testing
+- not run (documentation-only change)
+
+</PREVIOUS_PR_DESCRIPTION>
+
+<PREVIOUS_PR_DIFF_AND_COMMENTS>
+diff --git a/.agents/tasks/2025/08/21-0939-codetype-interface b/.agents/tasks/2025/08/21-0939-codetype-interface
+(File changed with 3 additions, 0 deletions)
+diff --git a/None b/design-docs/workflow-platform-spec.md
+(File changed with 283 additions, 0 deletions)
+</PREVIOUS_PR_DIFF_AND_COMMENTS>
+
+Please address any inline comments on the diff, as well as any additional instructions below.
+
+Now write a PR/FAQ document for this product. If there are important questions whose answers are unclear add them to the FAQ but don't write an answer 

.gitignore

@@ -5,4 +5,5 @@
 **/target/
 build
 *~
-.idea/
+.idea/
+.agent-tools/

AGENTS.md

@@ -17,6 +17,30 @@ Then to run the tests do
 just test
 ```
 
+## Agent Workspaces
+
+Automation now runs inside dedicated Jujutsu workspaces that live outside of the
+repository tree. Use the helper recipes to inspect and control them:
+
+- `just agents::consolidate <workspace-id> <start-change> <end-change>` – run the
+  consolidate workflow inside a workspace. The workspace is trusted with `direnv`
+  so the nix environment loads automatically.
+- `just agents::workspace-status [<workspace-id>]` – list all workspaces for this
+  repository or show metadata for a single workspace.
+- `just agents::workspace-shell <workspace-id>` – attach an interactive shell to a
+  workspace (the environment is prepared with `direnv allow`).
+- `just agents::workspace-clean <workspace-id>` – forget the workspace and delete
+  its cached directory once the work is integrated.
+- `just agents::workspace-sync-tools <workspace-id>` – refresh the copied automation
+  bundle inside a workspace without re-running the workflow.
+
+Workspaces are stored under `${AI_WORKSPACES_ROOT:-$XDG_CACHE_HOME/ai-workspaces}`
+using a repository-specific namespace. Each workspace contains a `.agent-tools/`
+directory with the current automation (`agents.just`, `scripts/`, `rules/`). The helper
+copies these files before every run so workflows see the latest tooling even when the
+target change is older. See `design-docs/jj-workspaces.md` for full rationale and
+lifecycle details.
+
 # Code quality guidelines
 
 - Strive to achieve high code quality.