Capability Lifecycle, Extraction & Fleet Backport Specification

Capability Lifecycle, Extraction & Fleet Backport Specification

Document Status: Living True Specification (Single Source of Truth)
Authority: Product, Architecture & Platform Engineering
Related Epics & Issues: #23 (Umbrella Spec: Capability Lifecycle & Extraction), #319 (Extraction Guidelines & Package Anatomy), #320 (Catalog Metadata & CLI Tooling), #321 (Agent Backport Runbook), #352 (Governance & Intent Lineage Reform)
Related Documents: INTENT_LINEAGE_AND_GOVERNANCE.md, CAPABILITY_PACKAGE_ANATOMY.md, CAPABILITY_MANAGEMENT.md, CLIENT_APPLICATION_ANATOMY.md, EVALUATION_AND_LINTER_SUITE.md, PRD.md

---

1. Executive Summary & The Compounding Technical Moat

In SiteSwarm, capabilities represent the core compounding engineering engine of the platform.

Traditional agency models suffer from linear economics: when an agency builds a custom feature (such as an interactive seasonal menu, photo gallery pipeline, or booking request form) 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:

1. Features originate as vertical custom solutions solving an immediate need for one client.
2. High-value features graduate into reusable, headless capability packages (packages/capabilities/*) conforming to strict architectural invariants.
3. Every newly extracted capability expands the catalog of available building blocks across the entire client fleet.
4. 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 Registration\n(Platform Registry & Schemas)"]
    C --> D["Stage 4: Fleet Backport\n(Agent Synthesis & Bespoke UI)"]
    D --> E["Compounding Platform Velocity\n(Zero-Cost Shared Infrastructure)"]
    E --> A

[!NOTE] Per INTENT_LINEAGE_AND_GOVERNANCE.md, pricing, retainer add-ons, and commercial packaging models are strictly out of scope for architectural designs and technical specifications. Software contracts define technical interfaces and entitlements, never dollar amounts or billing figures.

---

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 utility across multiple contexts or is requested by a second client, it is promoted to a horizontal capability.

Graduation Threshold Criteria:

1. Multi-Tenant Demand: The feature is requested by $\ge 2$ clients, or provides common utility across multiple vertical templates.
2. Reusability & Generalization: The feature’s domain logic can operate independently of any single business’s domain model.
3. Headless Extractability: Business logic, schemas, and state transitions can be cleanly severed from markup and visual styling.

Extraction Protocol:

1. Package Provisioning: Provision a dedicated workspace under packages/capabilities/<capability-name>/ with package name @siteswarm/<capability-name>.
2. 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.
3. 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.
4. 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 & Technical Entitlements

Once extracted, the capability is registered in the platform registry for fleet-wide discovery and configuration:

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

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

2. Technical Metadata:
   • Technical category (commerce, content, utility, feedback).
   • Configuration schema validation via Zod.
   • Inter-capability dependency declarations.
3. CLI Introspection: Available to human developers and agents via pnpm swarm capabilities:list.

---

2.4 Stage 4: Fleet Backport Protocol

When a client application enables a capability, an AI coding agent executes the backport with zero human markup rewriting:

The 5-Step Agent Backport Protocol:

1. Step 1: Manifest Enrollment:
   • Add the capability to apps/<client>/swarm.config.ts under type: "horizontal" with client-specific configuration.
2. Step 2: Headless Package Import:
   • Add @siteswarm/<capability-name>: "workspace:*" to apps/<client>/package.json.
3. 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.
4. Step 4: Two-Tier Quality Gate Verification:
   • Tier 1 (Machine): Run pnpm run audit and pnpm run check to verify target registration, modularity, and types.
   • Tier 2 (Behavioral): Execute @axe-core/playwright accessibility check (WCAG 2.1 AA) and inspect runtime rendering.
5. Step 5: Client Verification & Review:
   • Validate the feature in the client’s ephemeral PR preview before human merge.

---

3. Capability Packaging & Technical Entitlements

Capabilities are categorized by technical complexity and runtime footprint, keeping architecture cleanly decoupled from commercial sales pricing:

Capability Tier	Technical Characteristics	Example Capabilities	Runtime Footprint
Foundational	Pure client/edge utilities, zero persistence, stateless computation.	OpenGraph Social Cards, SEO metadata, Design Critique feedback.	Zero database storage; client-side or edge render only.
Interactive	Client-side state machines with edge validation and asset handling.	Media Optimization (R2/Images), Inquiry and reservation forms.	Edge Worker routes; ephemeral or external storage bindings.
Stateful / Integrated	Multi-step business workflows requiring persistent storage or third-party webhooks.	Seasonal reservation drops, Headless CMS integration.	D1 namespaced tables (cap_*); transactional edge routes.

[!IMPORTANT] Commercial Pricing Decoupling: Client retainer upgrades, setup fees, and margin analyses are governed by founder business proposals. Technical packages must remain completely agnostic to client billing models.

---

4. Decisions Intentionally Deferred

Per INTENT_LINEAGE_AND_GOVERNANCE.md §5, good architecture maximizes the number of decisions that can be safely deferred. The following areas are explicitly deferred:

1. Commercial Retainer & Billing Automation:
   • Automated Stripe subscription modification and invoicing hooks are deferred. Billing arrangements remain an offline/founder affair.
2. Enterprise Observability & Incident Pagers:
   • PagerDuty/BetterStack escalation countdowns and live on-call rotation schedules are deferred until fleet operational volume justifies them.
3. Speculative Capability Implementations:
   • Unratified features mentioned as future ideas (e.g. automated quote estimators, SMS emergency broadcast banners, SEO audit engines) are Horizon 3 ideas. They are intentionally deferred and will not be scaffolded or added as dependencies until explicitly prioritized.

---

5. Governance, SemVer & Backward Compatibility Invariants

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

1. 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.
2. 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.
3. Deprecation Protocol:
   • Capabilities slated for retirement must emit build-time deprecation warnings for at least 30 days before removal.

---

6. 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 technical 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
#352	Intent Governance Reform	Codify domain separation, anti-anchor research spikes, and two-tier verification gates.	priority:high

---

7. Living Specification Invariants

1. The Compounding Moat Invariant: Every custom feature built for a client must be evaluated for extraction into a reusable horizontal capability.
2. The Headless Purity Invariant: Capability packages must never render DOM markup or inject CSS styling; visual presentation remains 100% bespoke to each client.
3. The Zero-Lockout Invariant: Enrolling or unenrolling a client from a capability must never destroy client content or corrupt their independent data isolation.
4. The Domain Separation Invariant: Capability specifications and code must never contain commercial pricing, margin models, or founder business determinations.