| name | tutti-agent-workspace-app |
| description | Build or evolve a complex agent-enabled Tutti workspace app repository. Use for Tutti apps with web/server/shared monorepos, @tutti-os/agent-acp-kit local agent runtimes, kit-owned TUTTI_CLI agent/composer discovery, dynamic agent catalogs, run-scoped MCP tool gateways, app-owned package builders, web-first debugging, i18n harnesses, and production package validation. For simple package creation or repair, use tutti-workspace-app-factory instead. |
Tutti Agent Workspace App
Use this skill when the task is to create or evolve a full Tutti app repository, not just a final package directory. The target app is usually a local-first web app with a server, shared contracts, optional local agent runtime, and an app-owned scripts/package-tutti-app.mjs.
For the final package contract, defer to $tutti-workspace-app-factory and its references. This skill owns app architecture patterns; the factory skill owns tutti.app.json, tutti.cli.json, bootstrap.sh, runtime env, storage, i18n harness, and static package validation rules.
When To Use
Use this skill for:
- New agent-enabled Tutti app repositories.
- Existing web/server apps being converted into maintainable Tutti app repos.
- Apps that need
@tutti-os/agent-acp-kit for app-owned local Agent execution and @tutti-os/agent-acp-kit/tutti for auto CLI-backed/standalone platform context.
- App-specific MCP or command gateways that expose domain tools to local agents.
- Multi-package
pnpm workspaces with apps/web, apps/server, and packages/shared.
- App-owned packaging, smoke tests, i18n enforcement, and CLI/reference endpoints.
- GitHub Actions release workflows for publishing Tutti app releases and staging/production catalogs.
Use $tutti-workspace-app-factory instead for a small standalone package, package repair, or manifest-only validation.
Required References
Read only the references needed for the task:
references/app-architecture.md for repository layout, web/server/shared boundaries, and dependency choices.references/agent-acp-kit.md when implementing local agent providers, ACP event mapping, or run-scoped MCP tools.references/dynamic-agent-providers.md when implementing agent catalog/composer endpoints, standalone behavior, agent pickers, default selection, or canonical agent-id persistence. Read this before hard-coding any agent or provider list.references/package-builder.md when adding scripts/package-tutti-app.mjs, bootstrap.sh, Tutti CLI output docs, or package validation.references/github-actions-release.md when creating or changing .github/workflows/publish-tutti-app.yml, .github/workflows/publish-tutti-app-staging.yml, release variables, or catalog publishing.references/i18n-and-web-debugging.md when changing UI copy, language handling, web-first debug flow, or smoke/e2e checks.
Also read $tutti-workspace-app-factory before changing final package files or package runtime behavior.
Workflow
- Inspect the existing app shape, scripts, runtime dependencies, build output, storage, i18n, and agent surfaces.
- Choose the smallest architecture that can stay maintainable: do not add local agents, WebSocket, MCP, CLI, or background workers unless the product needs them.
- Define shared contracts before wiring web/server calls. Keep domain DTOs, WebSocket messages, CLI-visible shapes, and runtime profile types in
packages/shared.
- Build the web UI as the primary development surface. Keep the server as local API/static host and app orchestration layer.
- If agents are needed, add an exact released
@tutti-os/agent-acp-kit, use its default app-owned runtime, call the /tutti auto facade for catalog/composer/skill context, normalize events, and add a run-scoped tool gateway.
Follow references/dynamic-agent-providers.md: do not pass mode, check TUTTI_CLI, call Agent catalog HTTP routes, read app ID/token/API environment, parse CLI JSON, or maintain provider aliases. Render every facade agent, persist exact agent target ids, keep unavailable entries disabled with their reason, and never maintain a fixed provider catalog.
For apps that must run both locally and in cloud/managed Tutti, follow references/agent-acp-kit.md exactly: managed credentials come from request headers on the server, never from browser JSB fallback or request body fields.
- Add package generation only after the local dev app runs. Package the built web assets, bundled server,
tutti.app.json, optional tutti.cli.json, executable bootstrap.sh, assets, locales, and package-local AGENTS.md.
- If the user asks to connect to the Tutti app ecosystem, treat ecosystem integration as required: expose app capabilities through
tutti.cli.json, make the app callable by other Tutti apps and agents, and use TUTTI_CLI for any calls to other installed Tutti apps.
- For GitHub-hosted app repositories that should publish releases, add staging and production release workflows after the package builder is stable.
- Verify with the repo's targeted checks first, then package checks.
Managed and standalone agent checklist
Keep Tutti-hosted and standalone behavior behind the kit's fixed auto facade while sharing the same runtime execution layer:
- Pin an exact kit version that exports the auto catalog/composer/skill facade and managed header context helper.
- Call
loadTuttiAgentCatalog({ runtime }); do not use the deprecated provider-catalog projection, pass mode, or inspect TUTTI_CLI.
- Load composer options lazily for one exact agent target id and expose only app/domain DTO projections.
- Persist only canonical agent target ids returned by the facade. Migrate legacy provider-only state only when it maps unambiguously to one current agent; never retain provider as selection identity.
- Await
createManagedAgentRunContextFromHeaders(...) directly. Do not pre-read credentials or pre-check provider support in app code.
- Without a managed header, use an app-owned local cwd. Pass the provider derived from the selected agent entry, selected cwd, and optional
managedAgentInvocation into runtime execution.
- Delete raw Agent HTTP/CLI clients, browser credential fallbacks, request-body credential fields, alias maps, and dependency patch scripts.
- Never persist managed credentials or expose managed cwd and credentials through frontend events, logs, status APIs, or stored app state.
- Do not hard-code
/workspace, .agent-runs, or CODEX_HOME; the kit derives managed context.
- If instructions arrive over WebSocket, confirm the host injects the managed credential into that route; do not create a second credential channel.
- Package the built server, web assets, MCP/tool entrypoints, and runtime metadata needed by Tutti.
- Test CLI-backed auto, standalone auto, configured CLI failure, canonical IDs, managed/local run context, and secret non-leakage.
Validation
Prefer app-local scripts when they exist:
pnpm check
pnpm test
pnpm typecheck
pnpm check:i18n
pnpm package:tutti
For final package validation, run the validator from $tutti-workspace-app-factory when available:
python3 <factory-skill>/scripts/validate_tutti_app_package.py <generated-package-root>
If the app includes real local agent execution, add or run a smoke check that starts with provider detection before launching a real turn.
