Reposition Caplets around Whole Stack agent capabilities

[ian-pascoe]

Problem Statement

Caplets currently leads with token efficiency, prompt-surface compression, and the contrast between Capabilities and giant tool walls. Those claims are technically credible, but they describe how Caplets optimizes an already-connected agent rather than the larger outcome an agent power user wants: a coding agent that can work across the systems surrounding the repository.

The current framing creates four user-facing problems:

• It makes Caplets appear primarily to be an MCP context optimization rather than the capability layer that can connect coding agents to a Whole Stack.
• It can make the Prebuilt Caplets Catalog look like the boundary of supported systems, even though users can create Caplets for MCP servers, OpenAPI APIs, Google Discovery APIs, GraphQL endpoints, simple HTTP APIs, and curated CLI commands.
• It underplays the portability of a Caplet across supported agent environments and the ability to share reusable capabilities without sharing credentials or authenticated authority.
• It focuses attention on token savings before establishing the more emotionally resonant problem: the agent stops where the repository ends, leaving the user to carry context and actions between the agent and the rest of the stack.

Caplets needs one canonical public position that makes breadth and agency the promise, preserves deliberate access control, and drives users toward Caplet Activation rather than catalog browsing or installation alone.

Solution

Reposition Caplets as the capability layer for coding agents and make “Give your coding agent the whole stack.” the canonical public promise.

The canonical above-the-fold message is:

• Category: The capability layer for coding agents
• Headline: Give your coding agent the whole stack.
• Subheadline: Turn MCP servers, APIs, and commands into reusable Caplets your agent can use from issue to production. You choose what each agent can access.
• Primary action: Connect your first capability
• Secondary action: Browse shared Caplets

The public argument should establish the promise in this order:

1. State the Whole Stack promise.
2. Prove breadth immediately with “MCP. APIs. Commands. All of it.” and the complete supported connection model, rather than implying that current service logos or catalog inventory define coverage.
3. Name the primary pain: the user is acting as the agent’s human integration layer because the agent stops at the repository.
4. Define a Caplet as a reusable capability for coding agents and explain Capability Composition: the agent selects and combines capabilities for the task instead of requiring a human-authored automation workflow.
5. Show Agent Portability across supported coding-agent environments.
6. Explain Capability Sharing as portable, user-owned capability definitions and operating guidance without transferred credentials or inherited authority.
7. Illustrate the flagship outcome with an issue-to-production journey while avoiding guarantees of unrestricted autonomy.
8. Retain Code Mode, tool-surface compression, round-trip reduction, and token-efficiency evidence as technical differentiation rather than the primary brand promise.
9. End with an activation path that produces a first successful Caplet execution, then helps the user connect a capability from their own stack.

Apply this position consistently across the repository-owned landing, documentation, catalog, repository introduction, metadata, launch content, and canonical strategy/product language. Preserve technical precision in reference documentation and preserve all existing catalog safety warnings.

User Stories

1. As an agent power user, I want to understand immediately that Caplets can connect my coding agent to the systems around my code, so that I can imagine broader work than repository editing.
2. As an agent power user, I want Caplets described as a capability layer for coding agents, so that I can place it in my toolchain without mistaking it for an agent, workflow engine, or marketplace.
3. As a landing-page visitor, I want the Whole Stack promise stated before technical efficiency claims, so that I understand the outcome before evaluating the mechanism.
4. As a developer using many backend systems, I want the public message to emphasize connection breadth, so that I do not assume Caplets only supports the services shown in its catalog.
5. As a developer with an MCP server, I want to see MCP named as a supported connection method, so that I know my existing server can become a Caplet.
6. As a developer with an OpenAPI service, I want to see machine-described APIs represented in the breadth proof, so that I know I can expose my service without waiting for a premade catalog entry.
7. As a developer using Google APIs, I want Google Discovery APIs represented accurately, so that I know those APIs are supported without being mislabeled as OpenAPI.
8. As a developer with a GraphQL service, I want GraphQL represented as a supported backend family, so that I can connect my schema-driven endpoint.
9. As a developer with a simple HTTP service, I want simple HTTP actions represented as a supported backend family, so that a full formal schema is not presented as mandatory.
10. As a developer using repository commands, I want curated CLI commands represented as a supported backend family, so that useful local operations can become controlled agent capabilities.
11. As a user evaluating breadth, I want familiar service names or logos presented only as examples, so that I do not confuse example coverage with the product boundary.
12. As a user unfamiliar with Caplets, I want a Caplet defined as a reusable capability for coding agents, so that I understand what I create, install, reuse, and share.
13. As a user with a custom backend, I want to understand that I can create my own Caplet, so that I am not dependent on the Prebuilt Caplets Catalog.
14. As a user who wants a quick start, I want to install a shared no-auth Caplet and execute it successfully, so that I can prove the capability path before configuring credentials.
15. As an activated user, I want a clear next path to connect a system from my own stack, so that the initial demonstration turns into personally relevant usage.
16. As a user choosing a primary action, I want “Connect your first capability” to lead to the activation path, so that the most prominent action advances me toward real product value.
17. As a user who prefers existing work, I want “Browse shared Caplets” available as a secondary action, so that I can reuse community work without mistaking the catalog for the only connection path.
18. As a coding-agent user, I want the page to name the problem of carrying work between my agent and other systems, so that the product reflects the frustration I already experience.
19. As a coding-agent user, I want an issue-to-production scenario, so that I can see how Caplets helps the agent work beyond the repository.
20. As a cautious user, I want the issue-to-production scenario framed as access to composable capabilities rather than guaranteed autonomous deployment, so that the claim remains credible.
21. As a user comparing Caplets with workflow automation, I want to understand that the agent composes Caplets for the current task, so that I do not expect to build fixed Zapier- or n8n-style workflows.
22. As a user with changing tasks, I want capabilities to remain independently reusable, so that the agent can choose a different path without requiring a new automation recipe.
23. As a user of Codex, I want to know Caplets can serve my agent through its supported integration surface, so that I can keep my preferred client.
24. As a user of Claude, I want to know Caplets works through supported MCP integration, so that I can reuse the same Caplet definitions.
25. As a user of OpenCode or Pi, I want native and MCP compatibility represented accurately, so that Agent Portability does not imply identical client experiences.
26. As a user who switches coding agents, I want to reuse Caplet definitions across supported environments, so that changing the agent does not require redefining every backend capability.
27. As a user running a local Caplets host, I want the portability promise to distinguish reusable Caplet definitions from credentials, so that I do not expect secrets to move automatically.
28. As a remote Caplets user, I want the shared capability layer explained without implying that every client receives unrestricted authority, so that the trust model remains clear.
29. As an individual power user, I want to keep a Caplet private and local, so that sharing remains optional.
30. As a team member, I want to distribute a reusable Caplet definition and its operating guidance, so that teammates do not have to rediscover the same integration setup.
31. As a community author, I want to publish a useful Caplet, so that other users can reuse the capability.
32. As a Caplet recipient, I want to supply and authorize my own credentials, so that installing another person’s Caplet never grants inherited access.
33. As a security-conscious user, I want “Whole Stack” defined as intentionally exposed capabilities, so that I do not interpret the message as blanket access to every system or credential.
34. As a security-conscious user, I want “Share capabilities, not secrets” reflected consistently, so that portability does not imply credential sharing.
35. As a technical evaluator, I want Code Mode described as the default exposure surface, so that the new marketing position remains consistent with the accepted runtime architecture.
36. As a technical evaluator, I want direct and progressive exposure presented as supported alternatives rather than the primary product frame, so that the public documentation matches runtime behavior.
37. As a technical evaluator, I want benchmark methodology and task-parity claims preserved, so that token and round-trip evidence remains reproducible.
38. As a prospective user, I want token-efficiency claims placed after the broader product value, so that I can treat them as proof rather than decipher them as the reason to adopt Caplets.
39. As a documentation reader, I want the documentation introduction to use the same canonical category and promise as the landing page, so that moving between public surfaces does not change the product story.
40. As a repository visitor, I want the README opening to use the canonical position before explaining Code Mode, so that the open-source project and website describe the same product.
41. As a catalog visitor, I want the catalog framed as a search and distribution surface for shared Caplets, so that I understand its role without treating it as Caplets’ compatibility boundary.
42. As a catalog visitor, I want the existing inspection-first and not-security-reviewed warnings preserved, so that stronger ecosystem messaging does not weaken safety expectations.
43. As a user arriving from search or social media, I want page titles, descriptions, and social metadata to reflect the Whole Stack position, so that the promise is consistent before and after I click.
44. As a user navigating the landing page, I want section labels and navigation to match the new promise, breadth, trust, proof, and activation structure, so that the old tool-wall narrative does not reappear through navigation.
45. As a keyboard or screen-reader user, I want the revised sections and actions to retain semantic headings, landmarks, accessible names, focus behavior, and reduced-motion support, so that the repositioning does not reduce accessibility.
46. As a mobile visitor, I want the kitchen-sink breadth presentation to remain readable without horizontal overflow or illegible density, so that breadth does not become visual clutter.
47. As a maintainer, I want public-site intent events to classify the new primary and secondary actions categorically, so that wording changes do not make the funnel unmeasurable.
48. As a privacy-conscious user, I want marketing attribution to remain categorical and content-free, so that measuring the new position does not collect Caplet IDs, credentials, prompts, tool arguments, or outputs.
49. As a product owner, I want first successful Caplet execution to define Caplet Activation, so that install and catalog traffic are treated as funnel diagnostics rather than product value.
50. As a product owner, I want repeat successful use across backend families available as a retention indicator, so that the Whole Stack promise can be evaluated after initial activation.
51. As a maintainer, I want the canonical position recorded in durable product and strategy language, so that future public copy does not drift back to token efficiency as the primary promise.
52. As a maintainer, I want reference documentation to remain technically precise, so that canonical marketing language does not replace exact backend, auth, exposure, or safety contracts.
53. As a maintainer, I want launch and profile copy derived from the same canonical message, so that external acquisition surfaces do not introduce a competing tagline.
54. As a user who already understands the old positioning, I want the technical tool-wall explanation retained in an appropriate lower-level section, so that the repositioning does not discard a real product advantage.
55. As an existing Caplets user, I want this work to change public positioning without changing runtime behavior, so that upgrades do not alter my configuration, Caplets, credentials, or exposure modes.

Implementation Decisions

• Adopt Capability Layer as the canonical market category. “Capability gateway” may describe a controlled runtime role where technically useful, but it must not remain a competing top-level category.
• Adopt Whole Stack as the breadth promise. It means the set of backend capabilities a user intentionally makes available through Caplets; it does not mean blanket authority, automatic access to credentials, or the current contents of the Prebuilt Caplets Catalog.
• Adopt the locked category, headline, subheadline, and CTA hierarchy from the Solution section across repository-owned acquisition surfaces.
• Treat individual agent power users as the primary audience, teams as the expansion audience, and community authors/users as the ecosystem audience.
• Replace the user-facing primary antagonist of direct MCP with the user acting as the agent’s human integration layer. Keep direct MCP and giant tool-wall comparisons as technical differentiation.
• Make backend-family breadth the first proof after the hero. The breadth presentation must name MCP, OpenAPI, Google Discovery, GraphQL, simple HTTP, curated CLI commands, and shared Caplet Files accurately.
• Use service names and logos only as illustrative examples. Do not communicate or calculate compatibility from current catalog inventory.
• Use the kitchen-sink breadth line “MCP. APIs. Commands. All of it.” The supporting explanation must qualify the claim through supported interfaces rather than claim magical access to systems with no callable surface.
• Define a Caplet near the top of public acquisition content as “a reusable capability for coding agents.” More technical surfaces may use the fuller glossary definition.
• Explain Capability Composition as task-specific agent selection and combination of Caplets. Do not describe Caplets as a workflow builder or imply that Caplets itself plans and completes work autonomously.
• Use issue-to-production as the flagship illustrative outcome. The scenario should show capabilities spanning issue tracking, source control, CI, deployment, and status, while stating or visually preserving that only authorized capabilities are available.
• Promote Agent Portability as a primary supporting promise after breadth, not as a competing hero message. Name supported agents accurately and avoid identical-client or automatic-credential-portability claims.
• Frame Caplet portability and sharing around user ownership. A user can keep a Caplet local, reuse it, distribute it to a team, or publish it publicly.
• Define Capability Sharing as transfer of the reusable Caplet definition and operating guidance without credentials or authenticated authority. Each receiving user or host supplies and authorizes its own access.
• Use “Share capabilities, not secrets.” as the trust shorthand where space permits.
• Keep the catalog as a secondary discovery and distribution channel. Preserve its source inspection, warning, suppression, and “not security-reviewed” boundaries.
• Reorder and revise the landing-page argument to follow the nine-part structure in the Solution section. Existing interactive and visual components may be adapted, reordered, or removed when they support the new argument; do not preserve old sections merely because they already exist.
• Keep the existing design system, accessibility baseline, and quiet technical credibility. The copy may be bolder, but it must not introduce generic AI-autonomy promises, integration-platform jargon, or a new visual identity.
• Update public titles, descriptions, open-graph metadata, navigation labels, section anchors, and calls to action so the old tool-wall position does not survive in high-salience surfaces.
• Align the documentation introduction and repository introduction with the canonical promise, then transition quickly into exact Code Mode, setup, backend, and safety guidance.
• Align catalog metadata and introductory framing with portable shared Caplets without weakening the catalog’s safety warning or implying marketplace certification.
• Update durable product and strategy language so future content has one source of positioning truth. Include reusable one-liners suitable for launch content and externally managed social profiles.
• Preserve ADR 0001: Code Mode remains the default backend exposure. The repositioning changes message hierarchy, not the accepted runtime architecture or security boundary.
• Preserve Caplet File and Effective Caplet semantics, including project/global/SQL precedence. Marketing portability must not imply automatic synchronization or mutation of installed Caplets.
• Preserve the current no-auth first-success route as the lowest-friction activation step, followed immediately by a clear path to connect one capability from the user’s own stack. Do not turn incremental setup into the public positioning; the marketing remains deliberately kitchen-sink in its breadth claim.
• Define Caplet Activation as the first successful backend operation through a configured Caplet. Landing clicks, catalog views, installation, and setup completion remain funnel diagnostics.
• Reuse existing privacy-safe runtime activation and outcome events where sufficient. Any marketing-to-runtime attribution must remain short, categorical, one-way, and free of user identity, Caplet IDs, credentials, prompts, Code Mode source, arguments, outputs, URLs, hostnames, and file paths.
• Classify the new primary and secondary CTAs through explicit categorical behavior rather than relying on exact visible copy. Preserve the existing analytics allowlist and disabled-by-default behavior when provider configuration is absent.
• Do not add a new backend family, runtime API, configuration schema, catalog ingestion contract, credential model, or exposure mode for this work.
• Do not add an ADR. This is a reversible product-positioning decision recorded in the domain glossary and product strategy, not a hard-to-reverse architectural trade-off.

Testing Decisions

• The highest verification seam is one browser-level journey across production-built public surfaces: load the landing page, observe the canonical hero and immediate breadth proof, follow the primary activation path, follow the secondary catalog path, and confirm that documentation and catalog entry surfaces preserve the same category, trust boundary, and navigation intent.
• Exercise that browser journey at representative desktop and mobile widths. Verify visual hierarchy, readable breadth density, no horizontal overflow, keyboard navigation, visible focus, semantic heading order, accessible action names, and reduced-motion behavior.
• Use the existing public-app build and typecheck commands to prove that landing, documentation, and catalog content compiles through their real Astro pipelines.
• Use the repository public-docs check to protect required technical pages, generated-reference boundaries, and forbidden internal guidance. Extend it only for durable structural requirements, never subjective marketing copy.
• Use existing landing activation-link tests as prior art for durable CTA destinations and setup-mode behavior. Update or replace source-string assertions with rendered or explicit behavior assertions where practical.
• Use existing landing observability tests as prior art for categorical navigation, CTA, and attribution behavior. Add behavior coverage for the new primary activation action and secondary catalog action if classification changes.
• Use existing shared web-observability privacy tests as prior art for allowlisted categorical values and payload sanitization. Any new category must be tested at the sanitizer boundary and must not widen accepted arbitrary data.
• Use existing runtime telemetry tests as prior art for successful tool activation and Code Mode outcomes. Do not add a duplicate marketing-specific runtime event when the current event can establish Caplet Activation.
• Keep the catalog API, ingestion, Markdown sanitization, search, and warning tests unchanged unless catalog framing requires behavior changes. Public copy must not weaken tested safety behavior.
• Preserve the benchmark report and benchmark check as the source for token, surface, round-trip, and task-parity claims. Do not edit benchmark numbers by hand or add tests that pin marketing prose to those numbers.
• Do not add tests for exact headlines, subheadlines, slogans, body copy, metadata prose, section labels, or subjective positioning. Those are human-reviewed marketing decisions under the repository test-quality policy.
• Do not add source-text tests merely to prove that a phrase exists. Tests must defend observable routing, attribution, accessibility, rendering, privacy, or content-system contracts.
• Complete a human copy review against the glossary and accepted decisions, specifically checking that “Whole Stack” never implies unrestricted authority, catalog-complete coverage, inherited credentials, or guaranteed autonomous deployment.
• Complete a browser smoke test after the production build. Screenshots or direct visual observation are the acceptance evidence for layout and hierarchy; unit tests are not a substitute for visual confirmation.

Out of Scope

• Adding new runtime backend families or expanding the semantics of existing MCP, OpenAPI, Google Discovery, GraphQL, HTTP, CLI, or Caplet Set backends.
• Adding premade Caplets solely to make the breadth claim look larger.
• Changing Code Mode, progressive exposure, direct exposure, generated declarations, session state, or recovery behavior.
• Building a workflow engine, automation canvas, orchestration DSL, autonomous deployment system, or fixed issue-to-production recipe.
• Granting agents blanket access to a user’s systems or changing capability, credential, Vault, Remote Client Role, or host authorization boundaries.
• Transferring credentials, OAuth state, authenticated sessions, or inherited authority when a Caplet is shared.
• Turning the Catalog Search Site into a security scanner, certification program, endorsement list, or commercial marketplace.
• Changing public catalog indexing, install-count ranking, source suppression, or community submission mechanics.
• Changing benchmark methodology, generating new performance numbers, or replacing deterministic claims with live-run claims.
• Redesigning the Caplets brand, replacing the existing design system, or introducing a new visual identity unrelated to the positioning hierarchy.
• Introducing pricing, packaging, paid acquisition, lifecycle email, or sales collateral.
• Collecting known-user analytics, person profiles, raw tool activity, Caplet identities, credentials, prompts, arguments, outputs, or other prohibited telemetry.
• Changing runtime behavior, public API contracts, configuration schemas, generated SDK artifacts, storage semantics, or deployment architecture.

Further Notes

• The confirmed vocabulary is recorded in the root domain glossary: Caplet, Capability Layer, Whole Stack, Capability Sharing, Capability Composition, Agent Portability, and Caplet Activation.
• “Whole Stack” is intentionally bold, kitchen-sink wording. Do not dilute it into a progressive-adoption headline. The operational onboarding path may still begin with a low-friction no-auth success.
• The primary proof is supported connection breadth, not a logo count, catalog count, workflow demo, or token benchmark.
• The issue-to-production journey is an illustrative outcome and secondary proof. It must demonstrate composable access without implying that Caplets independently plans, authorizes, or executes an unrestricted workflow.
• Token efficiency remains a valuable differentiator and benchmarked proof point. It is being demoted in message hierarchy, not disputed or removed.
• The public positioning should remain precise, calm, and technically credible despite the bolder headline.
• Externally managed social profiles may require owner credentials. The implementation should provide the canonical short description and profile-ready one-liner in the durable strategy language and report any external account update as an operator action rather than blocking repository completion.