Guided onboarding#

The onboarding skills guide an adopter through project-local installation and initial testing. They use discovery, parallel planning, a resource-led coverage discussion, and approval of concrete changes. The runner and SDK remain separate from installed skill folders.

Install and invoke#

From a SnagBadger checkout containing these skills, offer this project-local command after selecting the adopting project and agent. Replace . with the actual accessible runner checkout when running from the adopting project:

pnpm dlx skills@1.7.2 add . --skill snagbadger-setup snagbadger-initialize-tests snagbadger-create-test snagbadger-test run-test-plan execute-test create-test-report create-test-bug

The official skills CLI supports local sources and explicit skill selection. This command pins the verified CLI version and uses the checkout's pnpm runtime. From an adopting project with a compatible Node runtime, npx skills@1.7.2 add is the equivalent launcher; provide the actual source path and same skill selection. Keep agent/scope selection explicit when the CLI auto-detects agents or runs non-interactively. After this change is available in the remote source, the source can be CosticaPuntaru/SnagBadger with existing repository access. Do not claim a remote branch contains unmerged skills or install every repository skill indiscriminately. pnpm skills:install remains the repository merge-skill installer, not this product installation flow.

Portable installed names are snagbadger-setup, snagbadger-initialize-tests, snagbadger-create-test, and snagbadger-test. In Codex these can be invoked as $snagbadger-setup, and similarly for the other names. The product discussion names snagbadger:setup and its testing counterparts describe these workflows; colon namespaces depend on the host's plugin packaging and are not registered by this standalone installation. Existing initialize-testing/run-test-plan and worker/reporting skills remain supported.

Locate the accessible runner checkout explicitly when installed skills are outside it. Read contracts from that runner root; references inside each installed skill remain local to its folder. Install/build the runner with its declared pinned toolchain before catalog execution. Installation of skill Markdown alone does not publish SDK packages, provide a browser runtime, or connect an external provider.

Read-only discovery#

node tooling/onboarding/discover.mts --root /path/to/adopting-workspace

The command returns JSON evidence: manifest/application candidates, JavaScript dependencies/frameworks/script names, package-manager lockfile clues, documentation/configuration/test-support paths, supported built-in factories, custom-harvester candidates, and warnings. Script bodies, secret files, documentation bodies, and credentials are not exported, and project commands are not executed. A root must be a real directory; nested symlinks and hidden/generated directories are skipped. Inventory is bounded by depth six and 10,000 entries; path lists and diagnostics are bounded. The persistent partial flag and omitted counts expose capped results even when detailed warnings are capped. Documentation includes application-local docs/openspec directories. Discovery is a snapshot, not a security audit or confirmation of provider connectivity.

Node package dependencies are extracted. Python/Rust/Go/PHP/Ruby/Dart/.NET manifests are inventory clues; use stack-specific inspection for dependencies and integration support. Multiple manifests in one directory represent one target candidate. Missing/malformed manifests and partial inventory require explicit follow-up rather than assumptions about support. Lockfiles identify possible package managers, not permission to replace one.

Interview and change plan#

Start discovery alongside the reporting/testing/both interview. Review detected targets and choose shared choices or tailored setup one application at a time. Read existing setup before offering update or replacement. Updates preserve authored tests/adapters; replacement lists affected files before approval and preserves unrelated application files.

Plan provider/harvesters, test resources/coverage, and execution prerequisites independently in read-only workers where available. Without delegation, perform the same work sequentially and disclose that limitation. Consolidate suggestions and missing decisions into a project-local scratchpad; ask only questions whose prerequisites are known. It should contain target paths, settled choices, resource pointers, scenario proposals/acceptance, the concrete change plan, and per-scenario readiness with missing prerequisites. Keep secret values out of it. During setup, child skills return proposed changes for the consolidated approval; standalone skills obtain their own approval.

Configure file output or actual Jira/Linear project identifiers. End users connect their accounts in the browser. For a button plus external provider, ask about shared devices and disabled/optional/mandatory account selection with account-specific PIN policy. Use real supported adapters/policy; unresolved integration capabilities remain pending.

Recommend available built-ins preselected for review. The current package exposes browser/application/HTTP/WebSocket factories. State/query/network libraries can suggest custom application-owned harvesters; their detection does not make an adapter built-in. Explain bounded data collection and lifecycle/sanitization settings before approval. Session-only collection remains the default; pre-recording is an explicit opt-in. Consult configuration and the current harvester experiment for contracts and available capabilities.

Initial tests and prerequisites#

Ask for or confirm documentation, application URLs, and ticket boards for implementations and bugs. Explore accessible sources, expose gaps/conflicts, chart proposed scenarios, and refine them with the user before creating agreed tests. Use the catalog and execution contract; current behavior alone does not establish the correct expectation.

Discover startup commands, browser/runtime capabilities, fixtures, authentication helpers, and server-action APIs. Ask how required actions work and guide approved missing host API work. Support lifecycle hooks and explicit scenario actions; registered lifecycle functions are not automatically exposed to workers. The current bridge has no invokeFunction request: scenario actions need an actual authorized API/CLI/tool mechanism. Preserve fresh agent/context requirements.

Apply approved files, initialize the agreed catalog/runtime, and inspect it through the existing runner. Validate ready capabilities; document unavailable support in test prerequisites and the scratchpad rather than inventing unsupported frontmatter. A structurally valid catalog is not proof of a passing test. Setup can finish with clearly blocked scenarios and usable integrations. Offer execution of ready tests with explicit selection through snagbadger-test, preserving excluded/blocked scenarios and genuine application failures.

Completion and availability#

Report changed files, observed checks, ready features and blocked prerequisites for each application. Recovery that changes approved scope returns to review; interrupted work retains its scratchpad and files for resumption. Independent verification can overlap only with isolated resources and supported host commands.

The skills implement orchestration and guided host changes using current repository contracts. Real Jira/Linear transport/account policy, additional built-in library adapters, and a hosted test-support service are not delivered by these instructions. Custom adapters and missing APIs are proposed and implemented in the adopter's application only when approved and supported by its environment.