Appendices
Appendix A: Complete Manifest JSON Schema Reference
Section titled “Appendix A: Complete Manifest JSON Schema Reference”The normative JSON Schema for manifest.json is published separately at spec/schemas/manifest.schema.json in the ccpkg repository. The schema in this appendix is informational.
Installers SHOULD validate manifests against the published JSON Schema.
Appendix B: Reserved Package Names
Section titled “Appendix B: Reserved Package Names”The following package names are reserved and MUST NOT be used by third-party packages:
ccpkg— reserved for the installer itself.core— reserved for future use.test— reserved for test fixtures.
Appendix C: Glossary
Section titled “Appendix C: Glossary”| Term | Definition |
|---|---|
| Archive | A .ccpkg ZIP file containing a manifest and package components. |
| Component | A discrete unit of functionality within a package (skill, agent, command, hook, MCP server, LSP server, or instructions). |
| Config slot | A declared configuration variable in the manifest that accepts user-supplied values. |
| Host | The AI coding assistant application that loads and uses installed packages. |
| Installer | The tool that processes .ccpkg archives and registers components with the host. |
| Lockfile | A JSON file recording the exact installed state of all packages at a scope. |
| Manifest | The manifest.json file at the archive root that declares package identity, contents, and configuration. |
| Registry | An optional JSON index of available packages, hosted at any URL. |
| Scope | The installation level: user (personal, global) or project (per-repository). |
| Template | A JSON configuration file (.mcp.json or .lsp.json) containing ${config.*} variable substitution markers. |
Appendix D: Future Host Integration Targets
Section titled “Appendix D: Future Host Integration Targets”The following features are not currently implementable without changes to host applications. They are documented here as aspirational targets to guide future host development. ccpkg implementations MUST NOT depend on these features and MUST NOT claim to provide them.
D.1 Hot-Reload After Install
Section titled “D.1 Hot-Reload After Install”Description: Components become available immediately after install without requiring a session restart.
Requires: A host API or file-watch mechanism to detect new plugins mid-session and load them into the running context.
Current behavior: Hosts typically discover plugins by scanning plugin directories at session startup only. Changes to plugin registration take effect on the next session start. The installer informs the user that a restart is required.
D.2 Host-Aware Lockfile Loading
Section titled “D.2 Host-Aware Lockfile Loading”Description: The host reads ccpkg-lock.json at startup for optimized package discovery, enabling faster startup by skipping directory scanning for known packages.
Requires: The host application to understand the ccpkg lockfile format and use it as a package index.
Current behavior: Hosts discover packages via their native plugin discovery mechanisms (directory scanning, marketplace registration, etc.). The ccpkg lockfile is used only by the ccpkg installer for lifecycle management (install, update, uninstall), not by the host.
D.3 Runtime Component State Machine
Section titled “D.3 Runtime Component State Machine”Description: Components track lifecycle states (Idle -> Active -> Idle) with host-managed activation tracking per component.
Requires: Host-managed activation state tracking, event emission for component transitions, and an API for querying component state.
Current behavior: Components are either installed (files exist in the plugin directory and the plugin is enabled) or not. There is no intermediate state. The host loads component content on demand but does not expose activation state to external tools.
D.4 Lazy Loading
Section titled “D.4 Lazy Loading”Description: Only package metadata is loaded at session startup. Full component content (SKILL.md bodies, AGENT.md bodies, command files) is deferred until the component is actually invoked. This minimizes startup time and context token consumption.
For full details on lazy loading behavior, triggers, and current host support, see the dedicated Lazy Loading page.