Capability Lifecycle, Extraction & Fleet Upsell Protocol Specification

Document Status: Living True Specification (Single Source of Truth)
Authority: Product, Architecture, Governance & Commercial Strategy
Related Epics & Issues: #23 (Umbrella Spec: Capability Lifecycle & Upsell Protocol), #319 (Extraction Guidelines & Package Anatomy), #320 (Catalog Metadata & CLI Tooling), #321 (Agent Backport Runbook), #322 (Commercial Pricing & Retainer Upgrade Tiers), #323 (Author True Spec)
Related Documents: CAPABILITY_PACKAGE_ANATOMY.md, CAPABILITY_MANAGEMENT.md, CLIENT_APPLICATION_ANATOMY.md, EVALUATION_AND_LINTER_SUITE.md, HIGH_LEVEL_DESIGN.md, PRD.md

1. Executive Summary & The Compounding Moat

In SiteSwarm, capabilities represent the core compounding engine of the business.

Traditional agency models suffer from linear economics: when an agency builds a custom feature (such as an automated catering quote estimator, emergency SMS broadcast banner, or photo gallery pipeline) for a single client, that investment is trapped within that client’s bespoke codebase. Building it for the next client requires billable hours from scratch, or brittle copy-pasting that decays across disconnected repositories.

SiteSwarm fundamentally shifts this dynamic through a unified monorepo and structured Capability Lifecycle:

Features originate as vertical custom solutions solving an immediate need for one paying client.
High-value features graduate into reusable, headless capability packages (packages/capabilities/*) conforming to strict architectural invariants.
Every newly extracted capability expands our sales pitch for prospective clients and creates an immediate recurring revenue upsell opportunity across our existing roster of clients.
AI coding agents execute fleet-wide backports in minutes by pairing the headless capability engine with bespoke visual UI matching each client’s brand aesthetic.

flowchart LR
    A["Stage 1: Vertical Inception\n(apps/<client>/src)"] --> B["Stage 2: Swarm Extraction\n(packages/capabilities/<name>)"]
    B --> C["Stage 3: Catalog & Packaging\n(Retainer Pricing & Sales Pitch)"]
    C --> D["Stage 4: Fleet Backport\n(Agent Synthesis & Bespoke UI)"]
    D --> E["Compounding Retainer Revenue\n(+$29 to +$99/mo per client)"]
    E --> A

2. The Four Stages of the Capability Lifecycle

2.1 Stage 1: Client Inception & Vertical Implementation

All software development begins grounded in real customer utility. Rather than building speculative horizontal abstractions, features are authored directly within the target client application:

Directory Boundary: Implementation resides inside apps/<client>/src/ (e.g. apps/bakery/src/components/SeasonalSpecials.astro).

Manifest Registration: Tagged inside the client’s swarm.config.ts as type: "vertical-custom":

export default defineAppConfig({
  name: "bakery",
  capabilities: {
    "seasonal-specials": {
      type: "vertical-custom",
      description: "Rotating weekly pastry drop countdown and reservation ledger",
      targets: ["src/components/SeasonalSpecials.astro"]
    }
  }
});

Linter Governance: Monitored by @siteswarm/governance to ensure client isolation (no cross-tenant leakage) and edge runtime compatibility.

2.2 Stage 2: Generalization & Swarm Extraction

When a vertical feature demonstrates commercial appeal or is requested by a second client, it is promoted to a horizontal capability.

Graduation Threshold Criteria:

Multi-Tenant Demand: The feature is requested by $\ge 2$ clients, or represents a core small business necessity (e.g., Lead Capture, SEO, Media Ingestion, Design Critique).
Commercial Upsell Viability: The feature can be bundled into a monthly retainer add-on (e.g., $+$29$ to $+$99/\text{mo}$).
Headless Extractability: Business logic, schemas, and state transitions can be cleanly severed from markup and visual styling.

Extraction Protocol:

Package Provisioning: Provision a dedicated workspace under packages/capabilities/<capability-name>/ with package name @siteswarm/<capability-name>.
Strict Headless Invariant:
- Zero .astro, .vue, or raw .html templates.
- Zero CSS files, utility classes, or design tokens.
- 100% pure TypeScript business logic, calculation engines, and state machines.
Subpath Isolation:
- ./client: DOM-agnostic event controllers, client state machines, and form handlers.
- ./server: Edge route handlers, validation pipelines, and service binding proxies.
- ./schemas (or root): Zod schemas, TypeScript types, and mathematical formulas.
Database Table Namespacing: Any D1 migrations must prefix tables with cap_<capability-name>_* to prevent collision with client or platform tables.

2.3 Stage 3: Catalog Registration & Commercial Packaging

Once extracted, the capability is registered in the platform registry and packaged for commercial client acquisition:

Registry Integration: Registered in SwarmCapabilityRegistry within @siteswarm/governance:

export const SwarmCapabilityRegistry = {
  // ...
  "seasonal-specials": {
    name: "seasonal-specials",
    displayName: "Seasonal Drop & Special Reservations",
    category: "commerce",
    recommendedTier: "growth",
    monthlyRetainerAddOn: 49,
    optionsSchema: SeasonalSpecialsOptionsSchema,
    dependencies: ["media"]
  }
};

Commercial Pitch Collateral:
- One-paragraph client value proposition written in non-technical business language.
- Before-and-after conversion metrics.
- Suggested monthly retainer upgrade tier.
CLI Introspection: Available to human leads and agents via pnpm swarm capabilities:list.

2.4 Stage 4: Fleet Backport & Retainer Upsell

When an existing client approves a capability upsell, an AI coding agent executes the backport with zero human markup rewriting:

The 5-Step Agent Backport Protocol:

Step 1: Manifest Enrollment:
- Add the capability to apps/<client>/swarm.config.ts under type: "horizontal" with client-specific options.
Step 2: Headless Package Import:
- Add @siteswarm/<capability-name>: "workspace:*" to apps/<client>/package.json.
Step 3: Bespoke UI Generation:
- AI agent authors a 100% bespoke Astro component (e.g. src/components/SeasonalSpecials.astro) consuming the headless ./client runner or ./server API.
- Styling adheres strictly to the client’s existing design tokens and color scheme.
Step 4: Quality Gate Verification:
- Run pnpm run audit and pnpm run lint:arch to verify target registration and modularity.
- Execute @axe-core/playwright accessibility check (WCAG 2.1 AA) and Lighthouse mobile budgeting.
Step 5: Commercial Invoicing Activation:
- Update client billing subscription in Stripe (feat(billing)) to reflect the new monthly retainer tier.

3. Commercial Retainer Upgrade & Pricing Models

Capabilities are packaged into three commercial delivery tiers that drive agency recurring revenue:

Capability Tier	Typical Capabilities	Suggested Client Retainer Add-on	Amortized Cloudflare Cost	Gross Margin
Tier 1: Essential	OpenGraph Social Cards, Basic SEO, Critique Feedback	Included in Base Retainer ($$99/\text{mo}$)	$<$0.01/\text{mo}$	$>99%$
Tier 2: Growth	Media Optimization (R2/Images), Instant Quote Calculator, Lead Capture	$+$29$ to $+$49/\text{mo}$	$\approx $0.10/\text{mo}$	$>98%$
Tier 3: Scale	SMS Emergency Broadcast, Shopify Inventory Sync, Multi-Tenant CMS	$+$99$ to $+$199/\text{mo}$	$\approx $0.50/\text{mo}$	$>95%$

Fleet Compounding Dynamics:

With 10 clients adopting 1 Tier 2 capability ($+$49/\text{mo}$), agency ARR increases by $$5,880$ against zero incremental server maintenance cost.
With 50 clients adopting 2 capabilities ($+$98/\text{mo}$), agency ARR increases by $$58,800$ purely from backporting software that already exists in the monorepo.

4. Governance, SemVer & Backward Compatibility Invariants

Because shared capabilities power multiple live client properties, breaking changes carry a fleet-wide blast radius:

SemVer Invariants:
- Patch (0.x.X): Bug fixes and internal refactors. Zero schema changes.
- Minor (0.X.0): Backward-compatible schema additions (new optional fields with sensible defaults).
- Major (X.0.0): Breaking contract changes. Must be accompanied by an automated AST codemod or migration script updating all enrolled client swarm.config.ts files in a single pull request.
Database Migration Invariants:
- D1 migrations must be strictly additive (new tables, new nullable columns).
- Column deletions or renames require a two-phase rollout (expand $\to$ contract) to prevent downtime during edge deployments.
Deprecation Protocol:
- Capabilities slated for retirement (e.g. legacy cms-bau) must emit build-time deprecation warnings for at least 30 days before removal.

5. Implementation Roadmap & Sub-Ticket Matrix

Sub-Ticket	Focus Area	Scope & Deliverables	Priority
#319	Extraction Guidelines	Canonical documentation and step-by-step extraction recipe for graduating vertical features to horizontal headless packages.	`priority:high`
#320	Catalog CLI Tooling	`SwarmCapabilityRegistry` commercial metadata schema and `pnpm swarm capabilities:list` introspection CLI.	`priority:medium`
#321	Agent Backport Runbook	Step-by-step prompt protocol and automated verification sequence for AI coding agents to backport capabilities to client apps.	`priority:high`
#322	Commercial Pricing Matrix	Authoritative pricing tiers, retainer add-on contracts, and small business owner pitch scripts.	`priority:medium`

6. Living Specification Invariants

The Compounding Moat Invariant: Every custom feature built for a client must be evaluated for extraction into a reusable, revenue-generating horizontal capability.
The Headless Purity Invariant: Capability packages must never render DOM markup or inject CSS styling; visual presentation remains 100% bespoke to each client.
The Zero-Lockout Invariant: Enrolling or unenrolling a client from a capability must never destroy client content or corrupt their independent data isolation.