Testing Bundle-Plugins

Overview

Dynamic verification of a bundle-plugin project: install it locally, confirm components are discoverable, validate hooks fire correctly, and run cross-platform smoke tests. Complements bundles-forge:auditing (static analysis) with runtime validation.

Core principle: Audit tells you if the structure is correct; testing tells you if it actually works.

Skill type: Flexible — adapt the test scope based on target platforms and project maturity.

Announce at start: "I'm using the testing skill to verify this plugin works correctly."

Step 1: Resolve Input & Detect Scope

Input Normalization

The target must be a local bundle-plugin project (has package.json + skills/). Remote URLs and archives are not supported — testing requires a local working directory.

Scope Detection

Target	Mode
Project root with multiple platforms	Full testing — all 5 test phases
Project root with single platform	Platform testing — phases 1-4 for the target platform
Single skill directory	Skill-only testing — phase 3 (component discovery) only

---

Phase 1: Local Test Environment

Generate a temporary dev-marketplace for local installation testing.

For Claude Code

1. Create ../dev-marketplace/ adjacent to the project directory
2. Generate .claude-plugin/marketplace.json pointing to the project:

{
  "name": "<project-name>-dev",
  "owner": { "name": "dev" },
  "plugins": [
    {
      "name": "<project-name>",
      "source": "../<project-directory-name>"
    }
  ]
}

3. Instruct the user:

Dev marketplace created at ../dev-marketplace/

To install locally:
  /plugin marketplace add ./dev-marketplace
  /plugin install <project-name>@<project-name>-dev

To reload after changes:
  /plugin marketplace update <project-name>-dev

To clean up when done:
  /plugin marketplace remove <project-name>-dev

For Cursor

Cursor plugins are installed from local paths directly:

To test locally in Cursor:
  1. Open Cursor Settings → Extensions → Install from Path
  2. Select the project root directory
  3. Reload Cursor to pick up changes

For Other Platforms

• Codex: Symlink skills/ into ~/.agents/skills/ per INSTALL.md
• OpenCode: Register the plugin path in .opencode/plugins/
• Gemini CLI: Point the extension config to the local directory

See references/platform-test-guides.md for platform-specific setup instructions.

---

Phase 2: Hook Smoke Tests

Verify hooks execute without errors by running them directly.

SessionStart Hook

bash hooks/session-start

Expected: Exits 0, prints a one-line prompt containing the project name and available skills. No stderr output.

Verify output format:

• If CLAUDE_PLUGIN_ROOT is set: valid JSON with hookSpecificOutput.additionalContext
• If CURSOR_PLUGIN_ROOT is set: valid JSON with additional_context
• Neither: plain text

Custom Hooks (if configured)

If the project defines PreToolUse or PostToolUse hooks in hooks.json, run each referenced script directly and verify:

• PreToolUse scripts: exit 0 on a valid project, exit 2 to block writes on critical issues
• PostToolUse scripts: always exit 0, warnings go to stderr

OpenClaw Hook-Pack (if present)

Verify hooks/openclaw-bootstrap/HOOK.md has valid YAML frontmatter with events declaration, and handler.js uses ESM export default.

---

Phase 3: Component Discovery

Verify that all declared components can be found by the host platform.

Skills

For each directory under skills/:

• Contains SKILL.md
• Frontmatter has name and description
• name matches directory name
• description starts with "Use when..."

Agents

For each .md file under agents/:

• Has YAML frontmatter
• Body has 5+ non-empty lines (self-contained protocol)

Platform Manifests

For each target platform:

• Manifest file exists and is valid JSON
• Paths in manifest resolve to existing files/directories
• Version matches package.json version

---

Phase 4: Cross-Platform Readiness

Generate a platform-specific test checklist based on references/platform-test-guides.md and known limitations from bundles-forge:scaffolding — references/platform-adapters.md.

Known Limitations to Verify

Platform	Limitation	Test
Claude Code	Plugin caching breaks ../ paths	Verify no ../ in hook commands or manifest paths
Cursor	Bootstrap lost after /clear	Verify session-start runs independently of prior context
Codex	No hook bootstrap	Verify AGENTS.md or INSTALL.md has manual setup instructions
OpenCode	Plugin JS must use ESM	Verify export default in .opencode/plugins/*.js
Gemini CLI	Extension needs contextFileName	Verify gemini-extension.json has contextFileName field
OpenClaw	Hook-pack wiring uncertain	Document as known risk in test report

---

Phase 5: Test Report

Generate a test report summarizing all findings.

Report Structure

# Test Report: <project-name>

**Date:** YYYY-MM-DD
**Scope:** [Full / Platform / Skill-only]
**Platforms tested:** [list]

## Results

| Phase | Status | Details |
|-------|--------|---------|
| 1. Local Environment | PASS/FAIL/SKIP | ... |
| 2. Hook Smoke Tests | PASS/FAIL/SKIP | ... |
| 3. Component Discovery | PASS/FAIL/SKIP | N skills, K agents |
| 4. Cross-Platform | PASS/FAIL/SKIP | ... |

## Issues Found

### Critical
- (blocks release)

### Warnings
- (should fix before release)

## Recommendations

- ...

Report location: .bundles-forge/audits/<timestamp>-test-report.md

---

Integration with Releasing

In the releasing pipeline, testing runs after auditing and before version bump:

audit → test → version bump → publish

If testing reveals critical issues, the release pipeline is blocked until they are resolved.

---

Common Mistakes

Mistake	Fix
Skipping local install test	Always test with a real dev-marketplace — file discovery differs from file existence
Testing only on one platform	Run cross-platform checklist for every target platform
Ignoring hook exit codes	Hooks must exit 0 to avoid blocking the host; test all code paths
Not cleaning up dev-marketplace	Always remove dev-marketplace after testing
Testing after version bump	Test before bumping — avoid releasing a broken version

Inputs

• project-directory (required) — bundle-plugin project root

Outputs

• test-report — comprehensive test results written to .bundles-forge/audits/
• dev-marketplace (temporary) — local marketplace directory for installation testing

Integration

Called by:

• bundles-forge:releasing — pre-release dynamic verification (after audit, before version bump)
• User directly — standalone local testing during development

Calls:

• (none — testing is a pure executor, does not dispatch other skills)