docs(agent-workflows): propose future Artifacts workspace

[mmabrouk]

Context

Agents can currently communicate through chat and bounded questionnaires, but there is no planned shared interactive surface for work such as a CRM, go-to-market board, or editable project object.

Changes

This design workspace proposes Artifacts as a future direction. An artifact is a sandboxed HTML, CSS, and JavaScript application in an agent mount. It persists user changes to its own files, which the agent can read on a later turn.

The proposal records:

• the artifact directory and state-file model;
• the isolated runtime and scoped-write boundary;
• a future artifacts skill and build toolkit;
• starter templates for CRM, go-to-market, project-board, and decision-canvas use cases;
• an expandable playground work area beside the agent files.

No runtime, agent skill, toolkit, templates, or frontend behavior is implemented in this PR.

Tests / notes

• Verified the final commit contains exactly five files under docs/design/agent-workflows/projects/artifacts/.
• Ran git diff --check on the new workspace.
• The repository-wide pre-commit hook was not used for the docs-only commit because unrelated API work currently fails ruff unused-import checks.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jul 11, 2026 9:40pm

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 36b0c368-81ca-4ca9-9254-4eb2010696d7

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/artifacts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mmabrouk]

🤖 The AI agent says:

This is intentionally a future-only design PR. Please review the model, not an implementation. The main decisions to settle are:

1. Should the first persistence interface mirror localStorage, support scoped relative fetch, or include both?
2. Should the expandable Artifacts work area begin in the playground inspector, or be a persistent sibling of chat?

The proposal also assumes artifacts complement questionnaires: use an artifact for shared interactive work, and retain questionnaires for bounded structured answers.