/testing

name: testing
description: "Use when testing a bundle-plugin locally before release — generating dev-marketplace environments, verifying component discovery, running hook smoke tests, and validating cross-platform readiness"

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`

---