Skip to content

PRODUCT_CONTRACT.md

Latest commit

 

History

History
162 lines (130 loc) · 7.55 KB

PRODUCT_CONTRACT.md

File metadata and controls

162 lines (130 loc) · 7.55 KB
Raw

Product Contract

This document defines what sxmc claims to support today, what should fail gracefully, and what is intentionally outside the contract.

Use this document together with:

Rewrite Baseline

The full product contract stays broader than the current rewrite milestone. When maintainers need the stable migration baseline for the onboarding and reconciliation loop, use GOLDEN_PATH_CONTRACT.md.

Supported And Expected To Work

These are the core product paths we should treat as stable:

1. Skills -> MCP

  • sxmc serve loads skill directories and exposes them over MCP
  • sxmc serve --discovery-snapshot <file-or-dir> exposes saved discovery snapshots as MCP-readable resources
  • per-skill prompts are available when SKILL.md is present
  • scripts/ entries become MCP tools
  • references/ entries become MCP resources
  • hybrid retrieval tools are always available:
    • get_available_skills
    • get_skill_details
    • get_skill_related_file

2. MCP -> CLI

  • sxmc stdio can discover and invoke tools, prompts, and resources from a stdio MCP server
  • sxmc http can discover and invoke tools, prompts, and resources from a streamable HTTP MCP server
  • sxmc mcp can discover and invoke tools, prompts, and resources from baked stdio/http MCP connections
  • sxmc mcp session <server> supports stateful multi-step workflows against a single baked MCP connection
  • --list, --list-tools, --list-prompts, --list-resources, --describe, and --describe-tool are supported CLI surfaces
  • one-shot tool execution is supported
  • one-shot prompt fetches with --prompt are supported
  • one-shot resource reads with --resource are supported
  • baked server/tool workflows are supported through mcp servers|grep|tools|info|call|prompt|read|session

3. API -> CLI

  • sxmc api auto-detects OpenAPI vs GraphQL
  • sxmc spec supports direct OpenAPI execution
  • sxmc graphql supports GraphQL schema-driven invocation

4. Hosting And Auth

  • local stdio MCP hosting is supported
  • remote streamable HTTP MCP hosting at /mcp is supported
  • /healthz is supported for hosted deployments
  • bearer-token and required-header auth are supported for remote MCP hosting

5. CLI -> AI Startup Surfaces

  • sxmc inspect cli <command> is supported for deterministic help-based inspection
  • sxmc add <command> is supported as the one-step inspect/save/onboard workflow
  • sxmc setup is supported as the multi-tool onboarding workflow
  • sxmc init ai --from-cli <command> --client <profile> is supported for generating startup-facing artifacts
  • sxmc init ai --from-cli <command> --coverage full is supported for generating multi-host startup coverage
  • sxmc init discovery <snapshot-or-dir> is supported for delivering saved discovery snapshots into startup-facing host docs
  • sxmc doctor is supported for startup-file health and repair guidance
  • sxmc status is supported as the unified machine-readable host/setup state surface
  • sxmc sync is supported as the local reconciliation workflow for saved profiles and AI-host artifacts
  • sxmc scaffold agent-doc --from-profile ... is supported
  • sxmc scaffold client-config --from-profile ... is supported
  • sxmc scaffold skill --from-profile ... is supported
  • sxmc skills install ... supports project-local and user-global managed skill installs
  • sxmc skills update ... refreshes metadata-managed installed skills from their recorded source
  • sxmc scaffold mcp-wrapper --from-profile ... is supported
  • sxmc scaffold llms-txt --from-profile ... is supported as an optional export
  • host profiles are supported for:
    • claude-code
    • cursor
    • gemini-cli
    • github-copilot
    • continue-dev
    • open-code
    • jetbrains-ai-assistant
    • junie
    • windsurf
    • openai-codex
    • generic-stdio-mcp
    • generic-http-mcp
  • preview, sidecar, patch, and apply modes are supported
  • project-local installs are the default, and --global / --local are supported across the startup lifecycle to choose between repo-local and user-level host artifact targets
  • apply mode updates managed markdown blocks or mergeable config files only
  • full-coverage apply updates only the explicitly selected --host targets and sidecars the rest
  • sxmc add, sxmc setup, sxmc doctor, sxmc status, and sxmc sync all support explicit structured output via --pretty / --format ...
  • sxmc add --client ... / sxmc setup --client ... and sxmc doctor --host ... / sxmc status --host ... are stable naming aliases for the primary host-selection flags
  • sxmc skills list --installed --json returns additive management metadata for managed skills, including managed, install_scope, install_source, and update_status

6. Stable Machine-Readable Contracts

These machine-readable surfaces are part of the promised product contract:

  • sxmc add --format ...
  • sxmc setup --format ...
  • sxmc doctor --format ...
  • sxmc status --format ...
  • sxmc sync --format ...

Contract rules for these outputs:

  • top-level shapes should remain stable within the 1.x line
  • new fields should be added additively rather than replacing old ones
  • stable exit-code behavior should not drift silently
  • recovery guidance should become more specific over time, not disappear
  • install_scope may be added or returned additively on startup-lifecycle structured outputs, but existing top-level fields should remain stable

Should Fail Gracefully

These scenarios should not crash the product or produce misleading results:

  • promptless/resource-less MCP servers should still allow tool discovery and one-shot tool calls
  • zero-argument MCP tools should receive {} rather than an omitted argument object
  • startup-only invocations like sxmc --version and sxmc --help should succeed on all supported platforms
  • unsupported optional MCP surfaces should be skipped with a clear note rather than failing all discovery
  • scan should continue to use non-zero exit status for findings by design, but not be treated as a crash
  • existing AGENTS.md / CLAUDE.md files should not be overwritten wholesale by CLI->AI generation
  • scaffolded skill and MCP-wrapper files should be created as new files rather than overwriting arbitrary existing files

Explicitly Outside The Contract

These are not promised as current product behavior:

  • persistent multi-turn MCP sessions through repeated fresh sxmc stdio ... invocations
  • stateful "dialog" continuity across separate CLI invocations without an explicit sxmc mcp session
  • automated CI launch of proprietary clients like Cursor, Codex, or Claude Code
  • universal compatibility with every third-party MCP server without caveats
  • benchmark numbers as proof of broad client compatibility
  • fully automatic client startup discovery without either a real config file or a real startup-read doc file

Release Bar

Before a release, we should be able to point to:

  1. a passing local certification run
  2. a current compatibility matrix
  3. a current benchmark snapshot
  4. a documented support boundary for anything still out of scope
  5. a current STABILITY.md statement that still matches the shipped UX

If a behavior is not covered by one of those, it should not be described as a guaranteed product path.