Conversation
…bundles, v2 install UI Decision spans four coordinated changes: 1. `commonly_attach_file` extension tool wrapping the upload endpoint and `[[upload:...]]` directive — protocol glue, not a skill, lives alongside `commonly_post_message` in the OpenClaw `commonly` extension. 2. Toolchain in `clawdbot-gateway` Dockerfile centered on OfficeCLI (Apache-2.0, pinned 30 MB static binary) for DOCX/XLSX/PPTX, plus pandoc for md→PDF, markitdown + pypdf for parse direction. ~170 MB image growth, replacing the ~600 MB python-office + LibreOffice stack the first draft proposed before OfficeCLI discovery. 3. Default skill bundles for the four production dev presets (Theo / Nova / Pixel / Ops) — currently shipping with empty `defaultSkills: []`. Adds `github`, `officecli`, `pandic-office`, `markdown-converter`, `pdf` (plus `tmux` for the engineers). 4. V2 inspector Skills tab (<400 lines, vs v1's 2,061-line catalog page) — search + installed list + recommended row + escape hatch to v1 Browse. Includes "Relationship to Installable taxonomy (ADR-001)" mapping each piece to the future Installable model and the migration story when ADR-001 Phase 3 (currently paused per ADR-011) unpauses. None of the work in this ADR becomes throwaway when Phase 3 lands; the data source flips, the wire shape doesn't. Rejected alternatives captured: server-side `/render` service, copying Anthropic's proprietary skills bundle, authoring duplicate Commonly-specific office skills, sub-agents per format, skill-only approach (no kernel tool), and the python-office + LibreOffice stack the first draft proposed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
v3 had Part 4 scoped to "inspector Skills tab only" with agent
install/fork pushed entirely out of scope. That left the user-asked
v2 marketplace page and Agents tab undesigned.
v4 expands Part 4 into four sections:
4a. Top-level V2 Marketplace page (/v2/marketplace) — unified
Agents + Skills browse, replaces v1 AgentsHub.tsx (4954 lines)
and SkillsCatalogPage.tsx (2061 lines) over time. Wires on top
of existing /api/marketplace/* (PR #215+#230) and /api/skills/*.
4b. Inspector Skills tab — per-pod contextual install. Shows which
agents have which skills.
4c. Inspector Agents tab — per-pod agent membership + install/fork
affordances. Per-installed-agent: Talk to / Configure / Fork.
Per-browse-agent: Install / Fork.
4d. Shared <V2MarketplaceList> component (~400 lines) consumed by
both inspector tabs and the Marketplace page. Future apps and
widgets ports cleanly onto the same component.
Phasing expanded from 4 phases to 8 active + 2 deferred to cover the
new surfaces and a v1 deprecation cycle. Open questions #8–10 added
covering nav-rail placement, fork ownership backend, and
PersonalityBuilder UX migration.
This ADR now also lands the active "Marketplace frontend" track from
ADR-011 alongside the file-production work — they're the same surface.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
samxu01
changed the title
…end state v3 and v4 made two assumptions that turned out to be wrong: 1. Designed a new /v2/marketplace page from scratch — but the route already exists and renders v1 AppsMarketplacePage (771 lines) with Discover|Installed sub-tabs. /v2/agents/browse and /v2/skills also exist as separate v2 routes rendering v1 components. The right move is to extend AppsMarketplacePage in place with kind tabs (Apps · Agents · Skills · Integrations), not author a new file. 2. Framed /api/marketplace/* (Randy, PR #215+#230) as legacy AR — but per #215's description, it's "ADR-001 Phase 2 for marketplace operations — first dual-write path between Installable (canonical) and AgentRegistry (compat shim)." The marketplace backend is Installable-canonical TODAY; what was missing is frontend wiring. v5 corrections: - Part 4a rewritten: extend existing AppsMarketplacePage with kind tabs, wire each tab to the right backend (Agents → Installable, Skills → AR for now, Apps/Integrations unchanged). Soft-redirect /v2/agents/browse and /v2/skills with deep-link query params. - Part 4d shrunk: the shared piece is a small <MarketplaceCardList> subcomponent (~250 lines) extracted FROM the page in Phase 3 and reused BY the inspector tabs in Phase 4. v4's heavyweight <V2MarketplaceList> was over-engineering. - Phasing collapsed from 8 active to 5 active. No new top-level page to design; v1 deprecation simplifies to one cleanup phase. - §"Relationship to Installable taxonomy" rewritten to reflect the per-kind split — agents are already on Installable, skills are still on AR. ADR-013 is the marketplace-frontend track from ADR-011 by definition for the agent surface. - Open question #7 (accelerate Phase 3?) closed/re-framed: the agent read-path switch is implicitly done by Randy's dual-write; the skills read-path switch defers until separately motivated. - Open question #8 (nav-rail placement) closed: page already mounted. - Open question #9 (fork ownership) narrowed: Randy's /api/marketplace/mine likely covers it; just verify response shape. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…apshot Catalog index (docs/skills/awesome-agent-skills-index.json) has updatedAt: 2026-02-05 — nearly 3 months stale at draft time. All numbers derived from it (~1,659 skills, `github` skill 603 stars, license fields) are point-in-time evidence, not live counts. Added §Caveat in the Context section spelling this out, plus inline annotations on each citation. Numbers fetched live via GitHub API today (OfficeCLI 2,768 stars + v1.0.70 release date) are explicitly timestamped 2026-05-03 and treated separately. Reviewers should re-sync the catalog before any sales-pitchy or external claims using the figures. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…olders The ASCII mockups for the marketplace page and inspector Agents tab had invented numbers that looked authoritative: - "Apps (12)", "Agents (78)" — kind-tab counts I made up - "★ 4.8 · 240 installs" (Liz), "★ 4.6 · 88 installs" (Theo) - "★ 4.5 · 175 installs" (Tarik) Reviewers could mistake these for projections or commitments. Replaced all with em-dash placeholders (—) and added a mockup note clarifying that live values come from the marketplace API at runtime. Same hygiene as v5.1's catalog-snapshot caveats — distinguish what's real (cited with timestamp) from what's illustrative. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…rawer v5.2 over-redacted: removed real GitHub star counts along with the fake Commonly ratings. v5.3 re-distinguishes: - GitHub stars (real upstream signal): render. Catalog snapshot for catalog skills; live GitHub API for locally-bundled (officecli). - Commonly review-style ratings (★ 4.8): don't render. The system doesn't exist; introducing it needs its own ADR. - Install counts (real Commonly metric): render where cheap; omit otherwise. Plus added §4d **Per-agent skill management drawer** — the friendly UX the user flagged was missing. The pod-centric Skills tab (4b) shows multi-agent rollups; the per-agent drawer is single-column, single-agent, with inline [×] removal and preset-aware "Recommended for ___" surfacing capability gaps. Configure drawer opens from any agent click (Members tab, Agents tab, Marketplace agent card). Tabs inside: Persona · Heartbeat · Skills · Memory. <300 lines target. Existing 4d (shared subcomponent) renumbered to 4e. Open question #11 added for per-agent install scoping in POST /api/skills/import. Phase 4 expanded to cover the drawer. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
samxu01
left a comment
samxu01
left a comment
There was a problem hiding this comment.
ADR-013 review
Strong design — the v5 correction (recognizing /v2/marketplace and /api/marketplace/* already exist and Randy's work is Installable-canonical) is exactly the kind of "verify the actual state before designing" that saves a phase of rework. The four-coordinated-changes shape is right; the rejected-alternatives section honestly captures why each path was abandoned; phasing is reasonable for an ADR-only PR.
Things to address before this turns into implementation PRs
- OfficeCLI supply-chain (line ~155): the "fall back to python-office stack" escape doesn't exist if Part 2 removes that stack from the image. Either keep the python-office stack staged in a Dockerfile target, or rewrite the mitigation. Also, mirroring the pinned binary into our own AR/GCS bucket would insulate us from upstream artifact swap on a 7-week-old project.
OFFICECLI_SHA256placeholder (line ~130): confirm upstream actually publishesSHA256SUMSbefore merging. If they don't, the Phase-0 verification is a no-op.- Open question 11 is load-bearing for Phase 4, not Phase-4-time work: the per-agent skill scoping in
POST /api/skills/importmay require a deeper change than a parameter add givensyncOpenClawSkillsis keyed onaccountId. Pull the verification into Phase 0/0.5. - Phase 0 verification path doesn't match what Phase 0 ships (line ~461): toolchain ships in Phase 0, skills in Phase 1 — so the smoke test as written needs a manual hand-installed skill on Nova or a skill-free pandoc invocation.
Worth resolving
- Inline
[×]UX vs reprovision-all (line ~348): "removing on next sync" can mean ~60s or never. Either trigger per-agent reprovision on click, or word the inline state honestly. - Configure-drawer permissions (line ~373): "all members read, admins write" leaks IDENTITY.md and memory contents to non-admins. Worth an explicit "what's reader-safe vs. operator-private" pass before Phase 4.
- Live GitHub stars on locally-bundled skills (line ~227): client-side direct-to-GitHub fetch will hit rate limits + has no specified failure mode. Server-side proxy with TTL cache is one endpoint to add in Phase 0/3.
- Phase 5 deletion gate (line ~469): "no fallback complaints" needs a concrete listening signal — add a redirect-hit counter so the deletion has a numeric trigger.
Smaller notes
- The "~5 PRs" estimate likely undersells if open question 11 turns out to need a real backend change (Phase 4 then needs a backend PR pair).
- Invariant 4 ("
commonly_attach_filereuses the workspace-boundary helper fromacpx_run") assumes that helper is cleanly extractable. Worth a Phase-0 spike to confirm.
This is COMMENT, not REQUEST_CHANGES — none of these are merge-blockers for an ADR. The design is fundamentally right; the comments are about pinning down the assumptions before they become silent obstacles in the implementation PRs.
Generated by Claude Code
| - Add `officecli --version`, `pandoc --version`, `python3 -c "import markitdown, pypdf"` to the gateway healthcheck so a regression (lost binary, broken pip) surfaces before an agent hits `command not found`. | ||
|
|
||
| **Why a 7-week-old project.** OfficeCLI is young (created 2026-03-15, 2,768 stars, v1.0.70 released 2026-05-02) — but the alternative is shipping a 600 MB stack that produces inferior output for the same use cases. Risk is real but bounded: the binary is pinned + checksummed; if upstream goes inactive or breaks something, we have an easy escape (downgrade pin, or fall back to the python-office stack as a Phase-N retreat). For now, the quality + size + license combination dominates. | ||
|
|
There was a problem hiding this comment.
Supply-chain risk on OfficeCLI is under-mitigated. The mitigation paragraph reads "if upstream goes inactive or breaks something, we have an easy escape (downgrade pin, or fall back to the python-office stack as a Phase-N retreat)" — but Part 2 explicitly removes the python-office stack from the image. The fallback isn't there to fall back to. A real escape requires keeping the python-office stack staged in a labeled Dockerfile target, or accepting that "downgrade pin" is the only real escape and stating that.
Also, "young + small project hosting a binary we exec inside the gateway" deserves more than a SHA256 pin — a 7-week-old repo can have its release artifact replaced after a maintainer compromise without changing the source tree. Consider:
- Mirror the pinned binary into our own AR/GCS bucket and download from there in the Dockerfile (full insulation from any upstream artifact swap).
- Document who watches upstream's release cadence and who notices a checksum mismatch (the Phase-0 verification just says CI fails the build; that's correct but who deals with it at 2am).
Generated by Claude Code
| pandoc texlive-xetex texlive-fonts-recommended \ | ||
| poppler-utils python3-pip && \ | ||
| rm -rf /var/lib/apt/lists/* | ||
|
|
There was a problem hiding this comment.
OFFICECLI_SHA256=<lookup-from-SHA256SUMS-at-pin-time> — has anyone confirmed iOfficeAI/OfficeCLI actually publishes a SHA256SUMS artifact alongside its releases? Many small projects don't. If they don't, this verification step in Phase 0 is a no-op and we ship "trust the GitHub release tarball" which is exactly the supply-chain footgun the previous comment flags.
Two-line fix to the ADR: add a Phase-0 prerequisite "verify upstream publishes SHA256SUMS for the pinned tag; if not, compute the checksum once locally, commit it as a constant, and update the build-arg lookup to read from the committed value." Either way the answer should not stay as a placeholder.
Generated by Claude Code
| 8. ~~Top-level Marketplace nav-rail placement~~ **Closed in v5.** `/v2/marketplace` already has its place in the v2 chrome. No new nav-rail entry needed; deep links from `/v2/agents/browse` and `/v2/skills` redirect with the right tab pre-selected. | ||
|
|
||
| 9. **Fork ownership and storage.** Mostly resolved by Randy's work: `/api/marketplace/fork` is Installable-canonical and `/api/marketplace/mine` returns the calling user's published + forked items. **Verify before Phase 3 ships:** does `/api/marketplace/mine` return enough metadata to render the "My Agents" view (name, version, fork-source link, install count)? If yes, no backend addition needed. If no, small backend extension to widen the response shape — not a new route. | ||
|
|
There was a problem hiding this comment.
Open question 11 is load-bearing for Phase 4 — the entire 4d Configure drawer UX is built on the assumption that per-agent install scoping works against POST /api/skills/import. The ADR notes "If the route is pod-scoped only, small backend extension to add a targetAgentId parameter — not a new route" — but syncOpenClawSkills is described as keyed on accountId. If multiple agents share an accountId (which the current install pipeline strongly suggests, since "scopes skills to (agentName, instanceId, podId)" is a projection of accountId), per-agent scoping might require a deeper change than a parameter add — separate skill directories per (agentName, instanceId) inside the workspace, plus updates to how the gateway resolves which skills the agent sees.
Recommend pulling this verification into a Phase-0.5 prerequisite (alongside open question #1) instead of Phase 4. If it turns out to be a meaningful backend change, Phase 4's lift target (<300 lines) is wrong and the phasing collapses.
Generated by Claude Code
|
|
||
| **Rejected because:** it adds an entire layer of orchestration (cross-agent calls, identity per format, separate budgets) for a problem that is just "call a binary." The complexity is unjustified. | ||
|
|
||
| ### E. Skill-only approach (no `commonly_attach_file` tool — make the upload protocol a skill) |
There was a problem hiding this comment.
Phase 0's verification ("agent runs pandoc, calls commonly_attach_file, file appears in chat") assumes Nova has pandic-office (or at least raw pandoc) installed — but defaultSkills for Nova doesn't ship until Phase 1. Phase 0 only adds the binaries to the image. So the smoke-test as written needs either:
- a hand-imported
pandic-officeskill on Nova before Phase 0 verifies, or - a manual
pandocinvocation viaacpx_run(skips the skill layer entirely),
neither of which is what Phase 0 is actually verifying. Either reorder Phase 0 / Phase 1 to ship together (so the smoke test exercises the real path), or rewrite Phase 0's verification to be skill-free ("agent uses acpx_run to invoke pandoc directly, then calls commonly_attach_file"). The latter is fine but it under-tests the real loop.
Generated by Claude Code
| │ Skills (5) [+ Add] │ | ||
| │ ───────── │ | ||
| │ ✓ github steipete · ★ <gh-stars> │ | ||
| │ Interact with GitHub via gh CLI [×] │ |
There was a problem hiding this comment.
"single click + confirm toast (no modal). The skill markdown gets pulled from the agent's PVC via syncOpenClawSkills on the next reprovision; in the meantime the row goes greyed-out with 'removing on next sync.'"
The CLAUDE.md "Agent Runtime — Quick Rules" entry on reprovision-all says it takes ~60s and is fire-and-forget. So "next sync" in this UX could mean anywhere from "next time someone clicks the global Reprovision button" to "never in this dev session." That's a fundamentally different UX from what the ✓-with-[×] affordance promises (which reads as "instant").
Two ways to make the contract honest:
- Trigger an immediate per-agent reprovision on
[×]click (if that's even a thing the provisioner supports today — probably not without backend work). - Reword the inline state from "removing on next sync" to "queued — takes effect on next reprovision" with a tooltip explaining what a reprovision is. Less satisfying but truthful.
Without one of these, the friendly UX of 4d will set up exactly the "I clicked X, why is it still here 5 min later?" complaint loop.
Generated by Claude Code
| - **One agent at a time** — no multi-row "@nova, @theo, @pixel" cognitive overhead. The drawer shows exactly the skills installed for *this* agent in *this* pod. | ||
| - **Inline `[×]` removal** — single click + confirm toast (no modal). The skill markdown gets pulled from the agent's PVC via `syncOpenClawSkills` on the next reprovision; in the meantime the row goes greyed-out with "removing on next sync." | ||
| - **`[+ Add]` opens a search-first picker** — typeahead over the catalog filtered by what's *not* yet installed for this agent. Picking a skill installs it for THIS agent only, not pod-wide. (Backend: scoped `POST /api/skills/import` with the `agentInstallationId` instead of `podId` — small extension, see open question #11 below.) | ||
| - **"Recommended for Dev PM"** — preset-aware. Each preset declares its `defaultSkills` already (Part 3); when an agent is missing one of its preset's defaults, surface it under Recommended with a one-click install. This makes "fix the agent's missing capabilities" a glanceable affordance rather than a hunt. |
There was a problem hiding this comment.
"all members can see the drawer. Only owner + admin can install/uninstall skills or modify persona. Non-admin viewers see grey-out states with explanatory tooltip, not hidden controls — discoverability matters more than chrome."
This is a permissions decision worth surfacing in invariants, not just inline. A non-admin member opening the Configure drawer sees the agent's full IDENTITY.md / persona / heartbeat schedule + memory tab read-only. Some persona content can include private operator notes (e.g. who's allowed to invoke certain tools, internal "be skeptical of X" rules) that the operator may not want every pod member to see.
Two mitigations to consider before merging this section:
- Make the entire drawer admin-only by default; flip individual fields to "visible to members" via an explicit
members.canRead = trueopt-in per-field. - Carve memory tab out specifically — recent
AgentMemoryentries can include cross-pod context the agent learned in DMs, which leaking to a pod member is an ADR-003 §Visibility violation.
At minimum, add an open question: "What in the Configure drawer is reader-safe vs. operator-private?" Currently the ADR assumes everything except install actions is fine to expose, which doesn't match how IDENTITY.md is used in practice (e.g. nova/theo's persona files in this repo).
Generated by Claude Code
| - **N installs** — count of `AgentInstallation` rows referencing this skill across the user's accessible pods (or instance-wide for admins). Cheap query. Skip rendering if the count would require a cross-instance aggregate or hits a privacy boundary; default to omitting rather than computing. | ||
| - **Author + license** — small muted line above the metrics. Author from manifest, license from the catalog row. | ||
|
|
||
| **What does NOT render:** |
There was a problem hiding this comment.
"For locally-bundled skills like officecli, fetch live from the source repo's GitHub API once per page load and cache for the session."
Two issues with the live-fetch path:
- Rate limit. Unauth GitHub API is 60 req/hr per IP. Even with one repo, "once per page load" with 10 admins navigating the marketplace burns the budget fast. Authed = 5000/hr but requires a service-side token + proxy (don't ship a token to the browser).
- Failure mode unspecified. What renders when the fetch fails —
★ ?, hide the badge, fall back to a stale value? The mockup just shows★ <gh-stars>which doesn't answer.
Recommend: server-side proxy that periodically refreshes a small cache (cron or on-demand TTL) for the small list of locally-bundled skills (today: just officecli). Add it to Phase 0 or Phase 3 plumbing rather than client-side direct-to-GitHub fetches. Also makes the catalog vs live distinction less awkward — both eventually flow through one server endpoint.
Generated by Claude Code
|
|
||
| ### F. Build the file-generation toolchain on `pandoc` + `python-docx` + `python-pptx` + `openpyxl` + `reportlab` + `docx-js` + `libreoffice` (the stack Anthropic's official skills use) | ||
|
|
||
| Initial draft of this ADR (v1, before discovering OfficeCLI on 2026-05-03) proposed exactly this — a ~600 MB toolchain layered into the gateway image, with skills like `pandic-office`, `pdf`, plus Commonly-authored DOCX/PPTX/XLSX wrappers calling the python libs. |
There was a problem hiding this comment.
"after Phase 3's redirects have been live ≥2 weeks with no fallback complaints"
There's no concrete listening mechanism for "fallback complaints" — /v2/agents/browse and /v2/skills are quietly redirected with a banner; users either notice or don't. In practice this becomes "delete when someone remembers."
Make it actionable by adding a server-side counter on the redirect path that logs hits, and gate Phase 5 on "≥2 weeks AND <N hits/week on the redirect path." That gives a concrete signal instead of a vibe-check. ~5 lines of telemetry in Phase 3.
Generated by Claude Code
Eight inline comments + PR-level summary on PR #287. All addressed: 1. Line 155 — "fall back to python-office stack" was a lie (Part 2 removes it). Rewrote escape paths honestly: downgrade pin (cheap) → staged Dockerfile target (mid) → full re-author (expensive). Added binary-mirror requirement (AR/GCS) to insulate from upstream artifact swap. Documented operational ownership for 2am checksum-mismatch incidents. 2. Line 130 — SHA256SUMS placeholder. Confirmed unverified whether iOfficeAI publishes SHA256SUMS. Two paths: upstream artifact OR committed-constant-checksum. Resolved in Phase 0a (i). Open question #13 added. 3. Line 516 — Open question #11 escalated to Phase 0a (ii). If syncOpenClawSkills is keyed only on accountId and multiple agents share that, per-agent install scoping is a real backend change, not a parameter add. Phase 4 may split into 4a/4b. 4. Line 461 — Phase 0b verification rewritten to be skill-free (uses acpx_run to invoke pandoc directly) since pandic-office doesn't ship until Phase 1. Full skill-loop verification moves to end of Phase 1. 5. Line 348 — Inline [×] UX. Committed to per-agent reprovision endpoint as the target with "Queued — applies on next reprovision" wording as acceptable v1. Eliminated misleading "removing on next sync" copy. 6. Line 373 — Configure drawer permissions. Flipped default to admin-only after review feedback. Per-field "visible to members" is explicit opt-in; Memory tab is never member- readable in v1 (ADR-003 §Visibility). Added Invariant 7. 7. Line 227 — Live GitHub stars. Moved from client-side direct fetch (60/hr unauth limit, no token in browser) to server-side proxy endpoint with TTL cache. Failure mode: ★ — with tooltip. 8. Line 469 — Phase 5 deletion gate. Replaced "no fallback complaints" with concrete <N hits/week telemetry threshold on redirect path. ~5 lines added to Phase 3 scope. Plus Invariant 8 making Phase 0a prereqs non-optional, Open question #12 on workspace-helper extractability, and PR estimate widened from ~5 to 5–7 to reflect Phase 0a (ii) uncertainty. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
v5.4 — addressing review feedbackPushed
Plus structural changes:
The two smaller PR-level notes:
None of these changed the overall design shape — all of v5's structural decisions hold (extend Ready for re-review. |
…position Per CLAUDE.md and ADR-005 Stage 3, acpx_run is being phased out in favor of A2A-via-DM (agent-to-agent delegation through 1:1 agent-rooms) using wrapper agents like sam-local-codex. ADR-013 doesn't block on the deprecation — it makes it easier: - commonly_attach_file is correctly placed at the kernel layer (CAP verb), not in any specific runtime. Wrapper agents speaking CAP get file-attach for free. - Phase 0b's acpx_run smoke test is a pragmatic bootstrap using the path that exists today. The shape of the test re-runs unchanged when ADR-005 Stage 3 completes. - Default skill bundles in Part 3 are runtime-agnostic by construction — SKILL.md instructs the model to invoke binaries; the agent decides how to actually run them (acpx_run today, wrapper-agent local subprocess tomorrow). Added §"Relationship to ADR-005" parallel to the existing ADR-001 relationship section. Listed ADR-005 in the companion header. Added a bullet in §"What this unlocks" calling out that ADR-013 reinforces ADR-005 Stage 3 rather than competing with it. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds OPENCLAW_INSTALL_DOC_TOOLCHAIN gated install of the document-generation toolchain that backs commonly_attach_file's deliverable flow per ADR-013 (Team-Commonly/commonly#287). Same opt-in pattern as the existing OPENCLAW_INSTALL_GH_CLI / OPENCLAW_INSTALL_DOCKER_CLI / OPENCLAW_INSTALL_BROWSER flags so upstream openclaw's default image stays unchanged. What gets installed (~170 MB total when enabled): * OfficeCLI (iOfficeAI, Apache-2.0): pinned static binary for DOCX/XLSX/PPTX create+edit+validate. Pinned via OPENCLAW_OFFICECLI_VERSION (default 1.0.70). Downloads platform-appropriate asset, verifies SHA256 against the release's published SHA256SUMS artifact, installs to /usr/local/bin/officecli. * pandoc + texlive-xetex + texlive-fonts-recommended: markdown → PDF (LaTeX engine), markdown → simple DOCX fallback. * poppler-utils: pdftoppm/pdftotext for PDF-skill workflows. * python3 + pip + markitdown + pypdf: parse direction — agent reads user-attached PDFs/DOCX/XLSX and converts to markdown for input. Build-time self-test runs `officecli --version`, `pandoc --version`, and a `python3 -c "import markitdown, pypdf"` check so a regression surfaces at build time rather than as "command not found" at agent runtime. Architecture-aware: x86_64 → officecli-linux-x64; aarch64 → officecli-linux-arm64; other arches fail the build (rather than silently skipping). Commonly's deploy invocation enables this with --build-arg OPENCLAW_INSTALL_DOC_TOOLCHAIN=1. Upstream builds unaffected. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…294) Closes Phase 0b of ADR-013 by wiring up the kernel verb, toolchain, dev preset bundles, auto-import, and a locally-bundled OfficeCLI skill so the four production dev agents (Theo/Nova/Pixel/Ops) can produce real deliverables and attach them to chat after a single reprovision-all. What ships in one merge: 1. **Submodule bump** _external/clawdbot → 4bf74dfc5 on rebase-2026.3.29 (openclaw#2 merge commit). Adds the `commonly_attach_file` extension tool, the `uploadFile()` client method, the `toRelativeWorkspacePath` plugin-sdk export for path-traversal protection, and the `OPENCLAW_INSTALL_DOC_TOOLCHAIN` Dockerfile build-arg gating the ~170MB document toolchain (pinned OfficeCLI 1.0.70 + pandoc + texlive-xetex + markitdown + pypdf, with build-time self-test). 2. **deploy-dev.yml** passes `--build-arg OPENCLAW_INSTALL_DOC_TOOLCHAIN=1` to the clawdbot-gateway docker build so dev gateways get the toolchain. 3. **defaultSkills** for the four production dev presets (dev-pm/Theo, backend-engineer/Nova, frontend-engineer/Pixel, devops-engineer/Ops): github + officecli + pandic-office + markdown-converter + pdf, plus tmux for the three engineers. These four presets previously shipped with `defaultSkills: []` despite the install pipeline being fully wired — a quiet correctness bug ADR-013 (#287) flagged. 4. **backend/services/presetSkillsAutoImport.ts** (~210 lines, new) — resolves each defaultSkills entry to SKILL.md content (local bundle first, then catalog index → fetched via the existing fetchSkillContentFromSource), then upserts each as a PodAsset via the existing PodAssetService.upsertImportedSkillAsset. Idempotent across reprovisions. Pure reuse of the same pipeline the manual POST /api/skills/import route uses — no new install plumbing. 5. **provision.ts + reprovision.ts** invoke applyPresetDefaultSkills after provisionAgentRuntime returns and BEFORE syncOpenClawSkills runs. The new PodAssets land just in time for the existing gateway sync to pick them up and write their SKILL.md files to /workspace/<accountId>/skills/<id>/ on the gateway PVC. 6. **commonly-bundled-skills/officecli/** — local bundle of the upstream Apache-2.0 SKILL.md + LICENSE. Bundled because the upstream awesome-agent-skills catalog was last synced 2026-02-05 and OfficeCLI was created 2026-03-15. README.md documents the bundling convention so future skills follow the same pattern; when upstream gains the skill, the local bundle can be deleted. After Deploy Dev + reprovision-all on dev: - Theo/Nova/Pixel/Ops each have their bundle synced to PVC - Agent runs `pandoc input.md -o report.pdf` (or officecli for slides) - Agent calls commonly_attach_file({podId, filePath, message: '...'}) - Pill renders with preview in chat Companion: ADR-013 (#287) merged. Phase 0a findings (#291) still open. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 participant
Summary
Adds ADR-013 at
docs/adr/ADR-013-agent-file-production-and-skill-bundles.md(534 lines, design only — no implementation).Documents the design for letting OpenClaw agents produce real artifacts (DOCX / XLSX / PPTX / PDF) and surface them in pod chat, plus the v2 install surfaces — extending the existing
/v2/marketplacepage with kind tabs (Apps · Agents · Skills · Integrations) and adding per-pod inspector Skills/Agents tabs. The two are coupled: file production is meaningless without a way to install the skills that enable it, and the install UI is the surface where users discover both new skills and new agents.Four coordinated changes (design only — no implementation in this PR)
commonly_attach_fileextension tool — wraps the upload endpoint and[[upload:fn|on|sz|kind|fileId]]directive. Protocol glue, not a skill; lives alongsidecommonly_post_messagein the OpenClawcommonlyextension.Toolchain in
clawdbot-gatewayDockerfile — centered on OfficeCLI (iOfficeAI/OfficeCLI, Apache-2.0, pinned 30 MB static binary, purpose-built for AI agents) for DOCX/XLSX/PPTX. Plus pandoc for md→PDF and markitdown + pypdf for the parse direction. ~170 MB image growth.Default skill bundles for the four production dev presets — Theo / Nova / Pixel / Ops currently ship with
defaultSkills: []. This ADR fills them in withgithub,officecli,pandic-office,markdown-converter,pdf(plustmuxfor the engineers).V2 install surfaces — extend, don't reinvent:
/v2/marketplace(AppsMarketplacePage, 771 lines) with kind tabs Apps · Agents · Skills · Integrations. Wire Agents tab to Randy's Installable-canonical/api/marketplace/*(PR AR: Agent Registry & Marketplace - Publish and Fork #215 + fix(marketplace-api): close dual-write drift gaps from PR #215 review #230). Soft-redirect/v2/agents/browseand/v2/skillswith deep-link query params.<MarketplaceCardList>subcomponent (~250 lines) extracted FROM the marketplace page in Phase 3 and reused BY the inspector tabs in Phase 4.Plus a two-line addition to
SOUL.md("if you produce a file, attach it viacommonly_attach_file").Key correction landed in v5
After verifying the actual backend + frontend state, two assumptions in earlier drafts were wrong:
/v2/marketplacealready exists — rendersAppsMarketplacePage(v1 component) withDiscover | Installedsub-tabs./v2/agents/browseand/v2/skillsalso exist as separate v2 routes. v4's "design a new top-level Marketplace page" was over-design; v5 extends the existing page in place.Randy's
/api/marketplace/*(PR AR: Agent Registry & Marketplace - Publish and Fork #215 + fix(marketplace-api): close dual-write drift gaps from PR #215 review #230) is already Installable-canonical — per AR: Agent Registry & Marketplace - Publish and Fork #215's description, it's "ADR-001 Phase 2 for marketplace operations — first dual-write path betweenInstallable(canonical) andAgentRegistry(compat shim)." The marketplace backend is already on Installable today; what was missing is frontend wiring. ADR-013's Phase 3 wires against the canonical side from day one and is the marketplace-frontend track from ADR-011 by definition for the agent surface.This re-framed the work substantially: phasing collapsed from 8 active phases to 5, the §"Relationship to Installable taxonomy" rewrote to reflect a per-kind split (agents already on Installable, skills still on AR), and several open questions closed.
Phasing (5 active + 2 deferred)
commonly_attach_file+ Dockerfile toolchaindefaultSkillsbundles for four dev presetsofficecliSKILL.md packaged locally/v2/marketplace(AppsMarketplacePage) with kind tabs; wire Agents tab to Installable; redirect/v2/agents/browse+/v2/skillsAgentsHub.tsx(4,954 lines) +SkillsCatalogPage.tsx(2,061 lines) after redirect cooling-offcommonly-pptx,commonly-xlsx/api/marketplace/publishEstimated ~5 PRs across backend (1–2) + clawdbot (1) + frontend (2) + cleanup (1).
Open questions flagged
POST /api/skills/importactually push SKILL.md to the gateway PVC, or only register metadata?githubskill resolutionghalready in image.Accelerate ADR-001 Phase 3?Re-framed (v5) — agent read-path switch implicitly done by Randy's dual-write; skills migration deferred until separately motivated. ADR-013's wiring is the verification gate for ADR-011's Phase 3 reactivation trigger.Marketplace nav-rail placementClosed (v5) — page already mounted./api/marketplace/fork+/api/marketplace/minelikely cover it; verify response shape covers "My Agents" UX needs.Rejected alternatives captured
A) Server-side
/renderservice · B) Copy Anthropic's proprietary skills bundle · C) Author duplicate Commonly-specific office skills · D) Per-format specialized sub-agents · E) Skill-only approach (no kernel tool) · F) Build on the pandoc + python-office + LibreOffice + docx-js stack (the v1 draft of this ADR before OfficeCLI discovery)Test plan
tmux? do all four needofficecli?)AppsMarketplacePageshape/api/marketplace/*being Installable-canonicalCompanion ADRs
ADR-001,ADR-002,ADR-008,ADR-011(this ADR satisfies the "Marketplace frontend" track for the agent surface).🤖 Generated with Claude Code