Define-side execution + artifacts #266

Merged

toasterson merged 1 commit from claude/wi-019f0576-define-side-execution-artifacts into main

2026-06-29 13:59:37 +00:00

toasterson commented

2026-06-28 23:20:03 +00:00

Owner

Anima work item 019f0576-2594-7c73-825b-76115cf02141.

What to build

Run Define phases: ideation/research as companion sessions emitting Seshat Documents; prototype/pretotype dispatch a build agent into a scratch space (never merged) producing a findings Document; design artefacts (HTML/CSS/SVG) rendered to the user in an iframe. CANDIDATE TO SPLIT (define-think / define-build / artifact) if too big.

Pushed context

ADR 0007. Companion vs build-agent dispatch; scratch space; artifact rendering.

Acceptance criteria

research phase → Seshat Doc\n- [ ] prototype → scratch agent → findings Doc (not merged)\n- [ ] design artefact rendered in iframe

Blocked by

019f0576-23cd-7c20-8a3a-db42d1d7215b (Documents N:N), 019f0576-2425-7023-9905-9f1856d712da (Workflows own phases)

2026-06-26 20:20 UTC

Summary

Implement define-side execution for research, prototype, and design phases: research uses a companion AI session to generate a Seshat document, prototype dispatches a build agent into a scratch environment producing a findings document, and design artifacts are served and displayed in an iframe inside the desktop client.

Approach

Extend the work‑item service with phase‑specific handlers for define workflows. For research/ideation phases, invoke the anima-ai crate to run a Gemini‑backed session that emits a Seshat document, stored via the existing SetAgentDiff RPC. For prototype/pretotype phases, create a temporary scratch‑space record in the database, dispatch a build agent using anima-agent (host‑side daemon), collect the generated findings and artifacts, and write a findings document back to the work item (without merging into the main project branch). For design phases, store the HTML/CSS/SVG artifacts as blobs, provide a lightweight HTTP endpoint to serve them, and in the desktop client render the content inside an <iframe> pointed at that endpoint. The implementation must respect the existing flow orchestration from ADR 0007 and the in‑progress document N:N relationships; artifact preview will be rendered inside the work‑item detail view.

Files likely to change

proto/anima/v1/workitem.proto – add messages for scratch space, findings document, and RPC options.
crates/anima-core/src/domain/scratch_space.rs (new) – domain model for ephemeral agent workspaces.
crates/anima-core/src/domain/findings_document.rs (new) – structured findings document.
crates/anima-db/migrations/NNN_create_scratch_spaces.sql – new migration.
crates/anima-db/src/repo/scratch_space.rs – repository for scratch‑space records.
crates/anima-server/src/services/workitem.rs – add Define phase dispatch logic.
crates/anima-server/src/handlers/artifact.rs (new) – serve design artifacts.
crates/anima-ai/src/lib.rs – companion session for Seshat document generation.
crates/anima-agent/src/dispatch.rs – build‑agent dispatch into scratch environment.
crates/anima-desktop/ui/pages/workitem-detail.slint – insert iframe component for design artifacts.
crates/anima-desktop/src/views/workitem_detail.rs – populate artifact URL and visibility.
crates/anima-desktop/src/bridge.rs – if new Slint properties need bridging.
crates/anima-exec/ – executor image may need capability to collect findings and exit without committing.
AGENTS.md – update commands if new crates or test fixtures are introduced.

Open questions

How is the scratch‑space environment provisioned and cleaned up when the agent finishes?
Should the findings document be stored as a linked document (N:N) or inline in the work item’s agent diff?
What authentication model applies to the artifact serving endpoint (e.g., bearer token, short‑lived URL)?
Is the anima-agent already capable of running in a non‑committing mode, or does it require a new operation mode?
How do we handle cancellation/timeout of companion AI sessions and scratch builds?
Since this work item is flagged as a candidate to split, should we plan sub‑issues: (1) research → Seshat doc, (2) prototype → findings doc, (3) design artifact rendering?

Complexity

L: touches at least 10 files across the entire stack (proto, core, DB, server, AI, agent, desktop UI), requires new database schema and repository patterns, new HTTP endpoint, UI component adjustments, and careful coordination with two blocked dependencies (document relationships and workflow phases). Even if split, each sub‑task is non‑trivial; end‑to‑end integration testing will add further effort.

Anima work item `019f0576-2594-7c73-825b-76115cf02141`. ## What to build Run Define phases: ideation/research as companion sessions emitting Seshat Documents; prototype/pretotype dispatch a build agent into a scratch space (never merged) producing a findings Document; design artefacts (HTML/CSS/SVG) rendered to the user in an iframe. CANDIDATE TO SPLIT (define-think / define-build / artifact) if too big. ## Pushed context ADR 0007. Companion vs build-agent dispatch; scratch space; artifact rendering. ## Acceptance criteria - [ ] research phase → Seshat Doc\n- [ ] prototype → scratch agent → findings Doc (not merged)\n- [ ] design artefact rendered in iframe ## Blocked by 019f0576-23cd-7c20-8a3a-db42d1d7215b (Documents N:N), 019f0576-2425-7023-9905-9f1856d712da (Workflows own phases)  2026-06-26 20:20 UTC ## Summary Implement define-side execution for research, prototype, and design phases: research uses a companion AI session to generate a Seshat document, prototype dispatches a build agent into a scratch environment producing a findings document, and design artifacts are served and displayed in an iframe inside the desktop client. ## Approach Extend the work‑item service with phase‑specific handlers for `define` workflows. For research/ideation phases, invoke the `anima-ai` crate to run a Gemini‑backed session that emits a Seshat document, stored via the existing `SetAgentDiff` RPC. For prototype/pretotype phases, create a temporary scratch‑space record in the database, dispatch a build agent using `anima-agent` (host‑side daemon), collect the generated findings and artifacts, and write a findings document back to the work item (without merging into the main project branch). For design phases, store the HTML/CSS/SVG artifacts as blobs, provide a lightweight HTTP endpoint to serve them, and in the desktop client render the content inside an `<iframe>` pointed at that endpoint. The implementation must respect the existing flow orchestration from ADR 0007 and the in‑progress document N:N relationships; artifact preview will be rendered inside the work‑item detail view. ## Files likely to change - `proto/anima/v1/workitem.proto` – add messages for scratch space, findings document, and RPC options. - `crates/anima-core/src/domain/scratch_space.rs` (new) – domain model for ephemeral agent workspaces. - `crates/anima-core/src/domain/findings_document.rs` (new) – structured findings document. - `crates/anima-db/migrations/NNN_create_scratch_spaces.sql` – new migration. - `crates/anima-db/src/repo/scratch_space.rs` – repository for scratch‑space records. - `crates/anima-server/src/services/workitem.rs` – add Define phase dispatch logic. - `crates/anima-server/src/handlers/artifact.rs` (new) – serve design artifacts. - `crates/anima-ai/src/lib.rs` – companion session for Seshat document generation. - `crates/anima-agent/src/dispatch.rs` – build‑agent dispatch into scratch environment. - `crates/anima-desktop/ui/pages/workitem-detail.slint` – insert iframe component for design artifacts. - `crates/anima-desktop/src/views/workitem_detail.rs` – populate artifact URL and visibility. - `crates/anima-desktop/src/bridge.rs` – if new Slint properties need bridging. - `crates/anima-exec/` – executor image may need capability to collect findings and exit without committing. - `AGENTS.md` – update commands if new crates or test fixtures are introduced. ## Open questions - How is the scratch‑space environment provisioned and cleaned up when the agent finishes? - Should the findings document be stored as a linked document (N:N) or inline in the work item’s agent diff? - What authentication model applies to the artifact serving endpoint (e.g., bearer token, short‑lived URL)? - Is the `anima-agent` already capable of running in a non‑committing mode, or does it require a new operation mode? - How do we handle cancellation/timeout of companion AI sessions and scratch builds? - Since this work item is flagged as a candidate to split, should we plan sub‑issues: (1) research → Seshat doc, (2) prototype → findings doc, (3) design artifact rendering? ## Complexity L: touches at least 10 files across the entire stack (proto, core, DB, server, AI, agent, desktop UI), requires new database schema and repository patterns, new HTTP endpoint, UI component adjustments, and careful coordination with two blocked dependencies (document relationships and workflow phases). Even if split, each sub‑task is non‑trivial; end‑to‑end integration testing will add further effort.

toasterson changed title from ~~WIP: Define-side execution + artifacts~~ to Define-side execution + artifacts

2026-06-28 23:30:15 +00:00

toasterson force-pushed claude/wi-019f0576-define-side-execution-artifacts from ae3d7341b3

CI / conflict-check (pull_request) Failing after 0s

Details

CI / snapshot (pull_request) Failing after 0s

Details

CI / docker (pull_request) Failing after 11m8s

Details

to a7c038920f

CI / conflict-check (pull_request) Failing after 0s

Details