The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
Incorporate Worktrunk patterns into workspace plan
Dotta25d3bf2c64ea
diff --git a/doc/plans/workspace-product-model-and-work-product.md b/doc/plans/workspace-product-model-and-work-product.mdindex ae5b8e793d..25c8c46454 100644--- a/doc/plans/workspace-product-model-and-work-product.md+++ b/doc/plans/workspace-product-model-and-work-product.md@@ -1011,6 +1011,143 @@ Instead:- work product- runtime service or preview+## Patterns Learned from Worktrunk++Worktrunk is a useful reference point because it is unapologetically focused on git-worktree-based developer workflows.++Paperclip should not copy its product framing wholesale, but there are several good patterns worth applying.++References:++- `https://worktrunk.dev/tips-patterns/`+- `https://github.com/max-sixty/worktrunk`++## 1. Deterministic per-workspace resources++Worktrunk treats a derived workspace as something that can deterministically own:++- ports+- local URLs+- databases+- runtime process identity++This is a strong pattern for Paperclip.++### Recommendation++Execution workspaces should be able to deterministically derive and expose:++- preview URLs+- port allocations+- database/schema names+- runtime service reuse keys++This makes previews and local runtime services more predictable and easier to manage across many parallel workspaces.++## 2. Lifecycle hooks should stay simple and explicit++Worktrunk uses practical lifecycle hooks such as create/start/remove/merge-oriented commands.++The main lesson is not to build a huge workflow engine. The lesson is to give users a few well-defined lifecycle moments to attach automation to.++### Recommendation++Paperclip should keep workspace automation centered on a small set of hooks:++- `setup`+- `cleanup`+- optionally `before_review`+- optionally `after_merge` or `after_close`++These should remain project/workspace policy concerns, not agent-prompt conventions.++## 3. Workspace status visibility is a real product feature++Worktrunk's listing/status experience is doing important product work:++- which workspaces exist+- what branch they are on+- what services or URLs they own+- whether they are active or stale++### Recommendation++Paperclip should provide the equivalent visibility in the project `Code` surface:++- active execution workspaces+- linked issues+- linked PRs+- linked previews/runtime services+- cleanup eligibility++This reinforces why `execution workspace` needs to be a first-class recorded object.++## 4. Execution workspaces are runtime islands, not just checkouts++One of Worktrunk's strongest implicit ideas is that a worktree is not only code. It often owns an entire local runtime environment.++### Recommendation++Paperclip should treat execution workspaces as the natural home for:++- dev servers+- preview processes+- sandbox credentials or provider references+- branch/ref identity+- local or remote environment bootstrap++This supports the `work product` model and the preview/runtime service model proposed above.++## 5. Machine-readable workspace state matters++Worktrunk exposes structured state that can be consumed by tools and automation.++### Recommendation++Paperclip should ensure that execution workspaces and work product have clean structured API surfaces, not just UI-only representation.++That is important for:++- agents+- CLIs+- dashboards+- future automation and cleanup tooling++## 6. Cleanup should be first-class, not an afterthought++Worktrunk makes create/remove/merge cleanup part of the workflow.++### Recommendation++Paperclip should continue treating cleanup policy as part of the core workspace model:++- when is cleanup allowed+- what blocks cleanup+- what gets archived versus destroyed+- what happens when cleanup fails++This validates the explicit cleanup policy proposed earlier in this plan.++## 7. What not to copy++There are also important limits to the analogy.++Paperclip should not adopt these Worktrunk assumptions as universal product rules:++- every execution workspace is a local git worktree+- the Paperclip host has direct shell and filesystem access+- every workflow is merge-centric+- every user wants developer-tool-level workspace detail in the main navigation++### Product implication++Paperclip should borrow Worktrunk's good execution patterns while keeping the broader Paperclip model:++- project plans the work+- workspace defines where work happens+- work product defines what came out+- git worktree remains one implementation strategy, not the product itself+## Behavior Rules## 1. Cleanup must not depend on agents remembering `in_review`