docs(spec): move lazy loading from design principles to aspirational appendix

zircote · zircote · commit 39ab20c645c1 · 2026-02-15T17:40:08.000-05:00
Fixes #7 - Remove lazy loading as normative design principle #4, renumber remaining principles 4-6 - Remove standalone Lazy Loading section from spec body - Add D.4 Lazy Loading to Appendix D (Future Host Integration Targets) with current behavior notes - Update Host role description to remove lazy loading ref - Update Host Integration section to remove lazy loading ref - Rewrite lazy-loading.mdx as aspirational feature page - Move Lazy Loading sidebar entry to Reference group with "Aspirational" badge - Update design rationale to remove lazy loading references from Approach C description and implementation scope
diff --git a/astro.config.mjs b/astro.config.mjs
@@ -52,7 +52,6 @@ export default defineConfig({
                   slug: "specification/install-lifecycle",
                 },
                 { label: "Lockfile", slug: "specification/lockfile" },
-                { label: "Lazy Loading", slug: "specification/lazy-loading" },
                 { label: "Registry", slug: "specification/registry" },
               ],
             },
@@ -63,6 +62,11 @@ export default defineConfig({
                 { label: "Portability", slug: "specification/portability" },
                 { label: "Versioning", slug: "specification/versioning" },
                 { label: "Appendices", slug: "specification/appendices" },
+                {
+                  label: "Lazy Loading",
+                  slug: "specification/lazy-loading",
+                  badge: { text: "Aspirational", variant: "caution" },
+                },
               ],
             },
           ],
diff --git a/spec/specification.md b/spec/specification.md
@@ -51,13 +51,11 @@ The following principles guide the design of the ccpkg format. Implementors SHOU
 
 3. **Deterministic installation.** Installation MUST be deterministic. Given the same package archive and the same user configuration, the installed result MUST be identical.
 
-4. **Lazy loading.** Installers SHOULD support lazy loading. Only package metadata is loaded at session startup; full component content is loaded on demand when invoked. This minimizes startup time and context token consumption.
+4. **No central authority.** No central registry is REQUIRED. Packages MAY be distributed via any URL, file path, or registry. Registries are optional and additive.
 
-5. **No central authority.** No central registry is REQUIRED. Packages MAY be distributed via any URL, file path, or registry. Registries are optional and additive.
+5. **Separated configuration.** User configuration MUST be separated from package contents. Secrets, preferences, and environment-specific values live outside the archive and are injected at install or load time.
 
-6. **Separated configuration.** User configuration MUST be separated from package contents. Secrets, preferences, and environment-specific values live outside the archive and are injected at install or load time.
-
-7. **No install-time code execution.** Packages MUST NOT execute arbitrary code during installation. There are no postinstall scripts, no build steps, and no setup hooks. The installation process is purely declarative: extract, configure, register.
+6. **No install-time code execution.** Packages MUST NOT execute arbitrary code during installation. There are no postinstall scripts, no build steps, and no setup hooks. The installation process is purely declarative: extract, configure, register.
 
 8. **No inter-package dependencies.** Inter-package dependencies are explicitly out of scope for this specification version. Each package MUST be self-contained and MUST NOT declare dependencies on other ccpkg packages. If a skill requires an MCP server, both MUST be packaged together in a single `.ccpkg` archive.
 
@@ -90,7 +88,7 @@ flowchart LR
 | **Package Author** | Creates the `.ccpkg` archive containing components and a manifest. Authors are responsible for correctness, licensing, and security of package contents. |
 | **Registry** | An OPTIONAL service or static file that indexes available packages. Registries provide discovery and version resolution but are not required for installation. |
 | **Installer** | The tool or skill that processes `.ccpkg` archives. The installer downloads, verifies, extracts, configures, and registers packages. The ccpkg skill itself serves as the reference installer implementation. |
-| **Host** | The AI coding assistant (e.g., Claude Code, Codex CLI) that loads and uses installed components. The host is responsible for component activation, lazy loading, and runtime integration. |
+| **Host** | The AI coding assistant (e.g., Claude Code, Codex CLI) that loads and uses installed components. The host is responsible for component activation and runtime integration. |
 | **User** | The person who installs and uses packages. Users provide configuration values, approve hook scripts, and control what packages are active. |
 
 ### Component Lifecycle
@@ -1095,7 +1093,7 @@ For quick one-off testing without any persistent side effects, developers can us
 
 ## Host Integration
 
-ccpkg integrates with Claude Code's plugin system to provide namespaced installation and component discovery. Rather than placing files directly in user-level directories (where namespacing is unavailable), ccpkg installs packages as Claude Code plugins and leverages the host's existing plugin runtime for component registration, namespace isolation, and lazy loading.
+ccpkg integrates with Claude Code's plugin system to provide namespaced installation and component discovery. Rather than placing files directly in user-level directories (where namespacing is unavailable), ccpkg installs packages as Claude Code plugins and leverages the host's existing plugin runtime for component registration and namespace isolation.
 
 ### Bootstrap
 
@@ -1275,31 +1273,6 @@ The lockfile records the state of all installed packages at a given scope. It en
 
 ---
 
-## Lazy Loading
-
-Lazy loading minimizes startup overhead by deferring component activation until the component is actually needed.
-
-### Startup Behavior
-
-Claude Code already implements lazy loading for skills: frontmatter metadata (name and description) is loaded at startup for discovery, while the full SKILL.md body is loaded on invocation via the Skill tool. This same pattern applies to other component types.
-
-ccpkg leverages this existing behavior by placing well-formed component files (SKILL.md, AGENT.md, commands, hooks) in standard plugin directories. No custom host-level lockfile reader is required — the host discovers ccpkg plugins via `extraKnownMarketplaces` → directory source → standard plugin component discovery.
-
-At session start, the host scans the `~/.ccpkg/plugins/` directory (registered via `extraKnownMarketplaces`), reads each plugin's `.claude-plugin/plugin.json`, and indexes component metadata for discovery. Full component content is deferred until invocation.
-
-### On-Demand Loading
-
-| Component | Trigger | What Is Loaded |
-|---|---|---|
-| Skill | LLM decides to activate the skill based on name/description | Full `SKILL.md` body, then `scripts/` and `references/` as needed |
-| Agent | User or LLM activates the agent | Full `AGENT.md` body |
-| Command | User invokes the slash command | Full command file content |
-| Hook | Host event fires matching the hook's event type | Hook script executed |
-| MCP server | First tool invocation targeting the server | Server process started |
-| LSP server | First file opened matching the server's language scope | Server process started |
-
-> **Note:** These behaviors are provided by the host application's existing plugin runtime. ccpkg does not implement a custom lazy loading mechanism.
-
 ---
 
 ## Remote Component References
@@ -1719,6 +1692,25 @@ The following features are **not currently implementable** without changes to th
 
 **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
+
+**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.
+
+**Requires:** A host-level mechanism to index component metadata (name, description, type) separately from component content, and to load full content on demand at invocation time.
+
+**Ideal behavior:** At session start, the host reads only frontmatter or manifest-level metadata for each installed component. When a skill is activated, the full SKILL.md body is loaded. When a command is invoked, the full command file is read. MCP and LSP servers start their processes only on first relevant invocation.
+
+| Component | Trigger | What Is Loaded |
+|---|---|---|
+| Skill | LLM activates based on name/description | Full SKILL.md body |
+| Agent | User or LLM activates the agent | Full AGENT.md body |
+| Command | User invokes the slash command | Full command file content |
+| Hook | Host event fires matching the event type | Hook script executed |
+| MCP server | First tool invocation targeting the server | Server process started |
+| LSP server | First file matching the language scope | Server process started |
+
+**Current behavior:** Claude Code loads skill frontmatter at startup and defers SKILL.md body loading until Skill tool invocation. This partial lazy loading is host-native behavior, not something ccpkg controls. Other component types do not have equivalent deferred loading. ccpkg packages should be structured to take advantage of whatever lazy loading the host provides, but MUST NOT depend on it.
+
 ---
 
 *This specification is published under the terms of the project's license. For the latest version, see the [ccpkg repository](https://github.com/zircote/ccpkg).*
diff --git a/src/content/docs/design/rationale.mdx b/src/content/docs/design/rationale.mdx
@@ -100,17 +100,17 @@ Bundles (like Approach A) plus a manifest index file and a lockfile for version
 
 **Pros**: Adds reproducibility via lockfile. Enables basic discovery through the index.
 
-**Cons**: More complex than A without fully solving the problems. The registry is local-only, so discovery is still limited. No lazy loading.
+**Cons**: More complex than A without fully solving the problems. The registry is local-only, so discovery is still limited. No deferred component loading.
 
 ### Approach C: Lazy Bundle (Selected)
 
-Archive bundles + lockfile + lazy loading + optional decentralized registries + checksum verification.
+Archive bundles + lockfile + optional decentralized registries + checksum verification.
 
 **Pros**: Directly targets all three pain points. Builds on the proven mcpb archive pattern. Borrows lazy.nvim's best ideas (deferred loading + lockfiles). Keeps registries optional and decentralized (Homebrew tap model meets Terraform registry protocol). Checksum verification adds the trust layer.
 
 **Cons**: Largest design surface. More to implement. But the complexity maps 1:1 to real problems -- there is no accidental complexity here.
 
-**Selected Approach C.** The additional complexity over A and B is justified because each added component (lazy loading, lockfile, registry protocol) directly eliminates a specific user pain point.
+**Selected Approach C.** The additional complexity over A and B is justified because each added component (lockfile, registry protocol, checksum verification) directly eliminates a specific user pain point.
 
 ---
 
@@ -132,7 +132,7 @@ ccpkg itself is a Claude Code plugin. It uses all four extension types available
 
 - **Skills** for interactive, agentic operations (init wizard, search, describe). These are conversational -- Claude adapts its responses based on context.
 - **Commands** for deterministic operations (`/ccpkg:install`, `/ccpkg:pack`, `/ccpkg:verify`). Same input, same behavior, every time.
-- **Hooks** for enforcement (PostSessionStart lazy loading, integrity verification on install). These run without LLM interpretation.
+- **Hooks** for enforcement (integrity verification on install). These run without LLM interpretation.
 - **Scripts** (Node.js) for heavy lifting (ZIP handling, SHA256 checksums, lockfile resolution, cache management). Hooks and commands delegate to scripts for anything computationally intensive.
 
 **Why this split?** Each extension type has a natural role. Using the wrong type creates friction: a skill that should be deterministic frustrates users with inconsistent behavior. A command that should be conversational cannot adapt to context. A hook that invokes the LLM adds latency to every session start. The four-type split matches each operation to its natural execution model.
@@ -269,7 +269,7 @@ The ccpkg manager is itself a Claude Code plugin. This is not a gimmick -- it va
 
 - **Commands**: `/ccpkg:init`, `/ccpkg:pack`, `/ccpkg:install`, `/ccpkg:verify`, `/ccpkg:list`, `/ccpkg:update`, `/ccpkg:config`, `/ccpkg:search`
 - **Skills**: Interactive init wizard (guides authors through manifest creation), package discovery and search
-- **Hooks**: `PostSessionStart` for lazy loading installed packages, integrity verification on install
+- **Hooks**: integrity verification on install
 - **Scripts**: Node.js/TypeScript for ZIP handling, SHA256 checksum computation, lockfile resolution, cache management, registry queries
 
 ### Technology choices
diff --git a/src/content/docs/specification/lazy-loading.mdx b/src/content/docs/specification/lazy-loading.mdx
@@ -1,31 +1,33 @@
 ---
 title: "Lazy Loading"
-description: "Startup behavior and on-demand component loading for minimal session overhead."
+description: "Aspirational lazy loading behavior for on-demand component activation."
 ---
 
-# Lazy Loading
+# Lazy Loading (Aspirational)
 
-Lazy loading minimizes startup overhead by deferring component activation until the component is actually needed.
+Lazy loading is a **future host integration target**, not a current normative requirement. It is documented here to guide host development and package authoring best practices. See [Appendix D](/specification/appendices/) for other aspirational features.
 
-## Startup Behavior
+ccpkg implementations MUST NOT depend on lazy loading and MUST NOT claim to provide it. Packages should be structured to benefit from whatever lazy loading the host provides natively.
 
-At session start, the host performs the following:
+## Ideal Behavior
 
-1. Read the lockfile(s) (user and project scope).
-2. For each installed package, load **only** the manifest metadata: `name`, `description`, and the `components` declaration.
-3. Register skill and agent names and descriptions for discovery (so the LLM can decide when to activate them).
-4. Register command names and descriptions for slash-command completion.
-5. Register hook event bindings (but do not execute hook scripts).
-
-The host MUST NOT read full `SKILL.md`, `AGENT.md`, or command file contents at startup.
+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.
 
 ## On-Demand Loading
 
 | Component | Trigger | What Is Loaded |
 |---|---|---|
-| Skill | LLM decides to activate the skill based on name/description | Full `SKILL.md` body, then `scripts/` and `references/` as needed |
-| Agent | User or LLM activates the agent | Full `AGENT.md` body |
+| Skill | LLM activates based on name/description | Full SKILL.md body |
+| Agent | User or LLM activates the agent | Full AGENT.md body |
 | Command | User invokes the slash command | Full command file content |
-| Hook | Host event fires matching the hook's event type | Hook script executed |
+| Hook | Host event fires matching the event type | Hook script executed |
 | MCP server | First tool invocation targeting the server | Server process started |
-| LSP server | First file opened matching the server's language scope | Server process started |
+| LSP server | First file matching the language scope | Server process started |
+
+## Current Behavior
+
+Claude Code loads skill frontmatter at startup and defers SKILL.md body loading until Skill tool invocation. This partial lazy loading is host-native behavior, not something ccpkg controls. Other component types do not have equivalent deferred loading.
+
+## What This Requires
+
+A host-level mechanism to index component metadata (name, description, type) separately from component content, and to load full content on demand at invocation time. No host currently provides this as a general-purpose API.
diff --git a/src/content/docs/specification/overview.mdx b/src/content/docs/specification/overview.mdx
@@ -50,13 +50,11 @@ The following principles guide the design of the ccpkg format. Implementors SHOU
 
 3. **Deterministic installation.** Installation MUST be deterministic. Given the same package archive and the same user configuration, the installed result MUST be identical.
 
-4. **Lazy loading.** Installers SHOULD support lazy loading. Only package metadata is loaded at session startup; full component content is loaded on demand when invoked. This minimizes startup time and context token consumption.
+4. **No central authority.** No central registry is REQUIRED. Packages MAY be distributed via any URL, file path, or registry. Registries are optional and additive.
 
-5. **No central authority.** No central registry is REQUIRED. Packages MAY be distributed via any URL, file path, or registry. Registries are optional and additive.
+5. **Separated configuration.** User configuration MUST be separated from package contents. Secrets, preferences, and environment-specific values live outside the archive and are injected at install or load time.
 
-6. **Separated configuration.** User configuration MUST be separated from package contents. Secrets, preferences, and environment-specific values live outside the archive and are injected at install or load time.
-
-7. **No install-time code execution.** Packages MUST NOT execute arbitrary code during installation. There are no postinstall scripts, no build steps, and no setup hooks. The installation process is purely declarative: extract, configure, register.
+6. **No install-time code execution.** Packages MUST NOT execute arbitrary code during installation. There are no postinstall scripts, no build steps, and no setup hooks. The installation process is purely declarative: extract, configure, register.
 
 8. **No inter-package dependencies.** Inter-package dependencies are explicitly out of scope for this specification version. Each package MUST be self-contained and MUST NOT declare dependencies on other ccpkg packages. If a skill requires an MCP server, both MUST be packaged together in a single `.ccpkg` archive.
 
@@ -89,7 +87,7 @@ flowchart LR
 | **Package Author** | Creates the `.ccpkg` archive containing components and a manifest. Authors are responsible for correctness, licensing, and security of package contents. |
 | **Registry** | An OPTIONAL service or static file that indexes available packages. Registries provide discovery and version resolution but are not required for installation. |
 | **Installer** | The tool or skill that processes `.ccpkg` archives. The installer downloads, verifies, extracts, configures, and registers packages. The ccpkg skill itself serves as the reference installer implementation. |
-| **Host** | The AI coding assistant (e.g., Claude Code, Codex CLI) that loads and uses installed components. The host is responsible for component activation, lazy loading, and runtime integration. |
+| **Host** | The AI coding assistant (e.g., Claude Code, Codex CLI) that loads and uses installed components. The host is responsible for component activation and runtime integration. |
 | **User** | The person who installs and uses packages. Users provide configuration values, approve hook scripts, and control what packages are active. |
 
 ### Component Lifecycle
