q792602257andClaude Opus 4.6
e5a12f9b74
Change is complete (24/24 tasks) per its declared scope (read-only local catalog + MCP tools + sync client contract). Management UI and the upstream Subscription Platform were explicitly out of scope. Deltas synced into three new main specs: skill-catalog, skill-mcp-tools, skill-subscription-sync. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
65 lines
4.8 KiB
Markdown
65 lines
4.8 KiB
Markdown
# skill-subscription-sync Specification
|
|
|
|
## Purpose
|
|
Keeps the local Skill Catalog aligned with the external Subscription Platform via periodic pull sync (and optional push-triggered sync), enforcing subscription-based visibility and degrading gracefully on sync failures.
|
|
## Requirements
|
|
### Requirement: Pull-based sync from the Subscription Platform
|
|
The system SHALL periodically fetch, from the external Subscription Platform, the set of skills the current deployment (tenant/device/agent) is entitled to, and SHALL apply creates/updates/removals to the local Skill Catalog to match that entitled set.
|
|
|
|
#### Scenario: New skill appears after sync
|
|
- **WHEN** the Subscription Platform reports a new entitled skill that does not yet exist locally
|
|
- **THEN** the next sync cycle creates it in the local Skill Catalog
|
|
|
|
#### Scenario: Updated skill content is refreshed
|
|
- **WHEN** the Subscription Platform reports a newer version of a skill already present locally
|
|
- **THEN** the next sync cycle updates the local copy to the newer version
|
|
|
|
#### Scenario: Revoked entitlement removes local visibility
|
|
- **WHEN** the Subscription Platform no longer includes a previously-entitled skill in the current entitled set
|
|
- **THEN** the next sync cycle removes or marks that skill as no longer visible in the local Skill Catalog
|
|
|
|
#### Scenario: Sync interval is configurable
|
|
- **WHEN** the deployment is configured with a sync poll interval
|
|
- **THEN** the system performs pull sync on approximately that interval without requiring a restart to take effect on the next cycle
|
|
|
|
### Requirement: Optional push-triggered sync
|
|
The system MAY support receiving a change notification (e.g. webhook) from the Subscription Platform, and WHEN it does, SHALL trigger an immediate out-of-cycle pull sync rather than waiting for the next poll interval; correctness of the catalog SHALL NOT depend on push notifications being delivered.
|
|
|
|
#### Scenario: Push notification triggers immediate sync
|
|
- **WHEN** a change notification is received from the Subscription Platform
|
|
- **THEN** the system performs a pull sync immediately, independent of the regular poll schedule
|
|
|
|
#### Scenario: No push configured still stays eventually consistent
|
|
- **WHEN** push notifications are not configured or not received
|
|
- **THEN** the local Skill Catalog still reflects the Subscription Platform's entitled set within one poll interval via the baseline pull sync
|
|
|
|
### Requirement: Subscription-based visibility enforcement
|
|
The system SHALL enforce, at both sync time and query time, that only skills belonging to the caller's currently active subscription(s) are stored as visible or returned by catalog queries.
|
|
|
|
#### Scenario: Query-time re-check catches stale entitlement
|
|
- **WHEN** a skill's entitlement has been revoked but the local cache has not yet completed its next sync cycle
|
|
- **AND** a catalog query for that skill is made using already-known revocation information
|
|
- **THEN** the system does not return that skill as visible, even though its record may still exist locally pending cleanup
|
|
|
|
#### Scenario: Multiple subscriptions compose visibility
|
|
- **WHEN** a deployment holds more than one active subscription, each entitling a different set of skills
|
|
- **THEN** catalog queries return the union of skills entitled across all of that deployment's active subscriptions
|
|
|
|
### Requirement: Sync client contract is transport-replaceable
|
|
The system SHALL define the Subscription Platform integration (fetch entitled skills, optional change notification receipt) behind a single internal interface, so the concrete HTTP client/auth mechanism can be adjusted to match the real Subscription Platform API without changes to the Skill Catalog or MCP tool layers.
|
|
|
|
#### Scenario: Sync client swap does not affect catalog/tools
|
|
- **WHEN** the concrete Subscription Platform client implementation is replaced (e.g. different auth scheme or request/response shape)
|
|
- **THEN** `skill-catalog` and `skill-mcp-tools` behavior and their own specs remain unaffected, as long as the new client still satisfies the sync interface
|
|
|
|
### Requirement: Sync failure handling
|
|
The system SHALL treat a failed sync attempt (network error, auth failure, malformed response) as non-fatal to already-cached skills: the local catalog SHALL continue serving its last-known-good state, and the failure SHALL be recorded/observable rather than silently discarded.
|
|
|
|
#### Scenario: Sync failure preserves last-known catalog
|
|
- **WHEN** a sync attempt fails due to a network or platform error
|
|
- **THEN** the local Skill Catalog is left unchanged (not cleared or partially corrupted) and remains queryable using its last successfully synced state
|
|
|
|
#### Scenario: Sync failure is observable
|
|
- **WHEN** a sync attempt fails
|
|
- **THEN** the system records the failure (e.g. last-error timestamp/reason) so it can be surfaced to operators rather than failing silently forever
|