@jterrats/open-orchestra 1.0.4 → 1.0.6

package/skills/oclif-plugin-development/SKILL.md

@@ -0,0 +1,118 @@
+# Oclif Plugin Development
+
+Use this skill when a task designs, implements, tests, packages, or reviews an
+Open Orchestra plugin based on oclif, TypeScript, React, Vite, hooks, manifests,
+or CLI command extensions.
+
+## When To Load
+
+- Trigger: `oclif`
+- Trigger: `plugin`
+- Trigger: `cli plugin`
+- Trigger: `command plugin`
+- Trigger: `hook`
+- Trigger: `manifest`
+- Trigger: `package exports`
+- Trigger: `npm plugin`
+- Trigger: `React/Vite plugin UI`
+- Trigger: `TypeScript plugin package`
+
+## Architecture
+
+- Treat plugin specialization as an on-demand skill, not as a permanent role
+  profile. Developer, Architect, QA, Security, DevOps, UX, or Tech Lead can use
+  this skill when the task requires plugin work.
+- Keep command classes or command modules nearly logicless: parse flags/args,
+  call one service/use-case, format output, and map expected errors to
+  user-safe messages.
+- Put business rules, workflow policy, persistence, batching, retries, plugin
+  discovery, and registry mutations in domain services or use-cases.
+- Define public plugin contracts before implementation: plugin id, supported
+  host version, commands, hooks, capabilities, permissions, configuration,
+  outputs, evidence expectations, and compatibility constraints.
+- Prefer typed registries and manifest-derived metadata over hardcoded command
+  or hook lists. Load `collection-standards` when plugin work repeats commands,
+  hooks, providers, roles, statuses, selectors, fixtures, or validators.
+
+## Oclif CLI Standards
+
+- Use TypeScript and typed flags/args.
+- Keep stdout, stderr, exit code, and JSON output stable and testable.
+- Provide JSON output for machine consumers when a command returns structured
+  data.
+- Keep help, examples, aliases, deprecations, and hidden/internal command status
+  explicit.
+- Treat hooks as integration points with clear ordering, idempotency, timeout,
+  failure, and observability behavior.
+- Do not hide network calls, filesystem writes, shell execution, or destructive
+  actions inside command parsing.
+
+## Package Standards
+
+- Prefer ESM-first package structure unless compatibility requires otherwise.
+- Define `exports`, `types`, files included in the package, and supported Node
+  versions.
+- Keep package metadata, command metadata, plugin manifest data, and docs
+  derived from one source where possible.
+- Validate install/link/package smoke behavior before release.
+- Use semantic versioning and document host compatibility or migration needs.
+
+## Plugin Capability Manifest
+
+A plugin capability contract should declare:
+
+- plugin id and display name;
+- commands and command surfaces;
+- hooks and lifecycle events;
+- capabilities and activation triggers;
+- required permissions;
+- configuration schema and defaults;
+- UI contributions, if any;
+- evidence types expected for QA/release;
+- compatibility with host Open Orchestra version;
+- security constraints and tenant/regulatory limitations;
+- ownership, support, and deprecation policy.
+
+## React/Vite UI Contributions
+
+- Use React + TypeScript conventions for UI plugin surfaces.
+- Use Vite for local dev/build when the host package supports it.
+- Separate presentation, state, API access, and domain logic.
+- Keep UI mobile-first, accessible, and covered with loading, empty, error,
+  success, and recovery states.
+- Add Playwright evidence for user-visible plugin UI flows.
+
+## QA Evidence
+
+Plugin QA should prove:
+
+- command exit code, stdout, stderr, and JSON contract;
+- flags/args validation and help output;
+- generated files or workflow events;
+- hook invocation, ordering, idempotency, and failure behavior;
+- install/link/package smoke;
+- compatibility with the declared host version;
+- Playwright screenshots/traces when UI is involved;
+- API side effects or external integration outcomes when the plugin triggers
+  them.
+
+## Security
+
+- Use `spawn`/`execFile` with args arrays for shell execution. Never interpolate
+  shell strings.
+- Validate file paths and reject traversal.
+- Validate URLs before network calls.
+- Do not hardcode secrets or write credentials to plugin manifests.
+- Define least-privilege plugin permissions and review them before release.
+- Treat third-party plugins and plugin-provided config as untrusted input.
+- Run secret scanning, dependency audit, static analysis, duplicate-code checks,
+  and package provenance checks before release.
+
+## Handoff Checklist
+
+- Plugin contract or manifest updated.
+- Command/hook behavior covered by tests.
+- Security-sensitive surfaces reviewed.
+- Evidence attached for CLI/API/UI behavior.
+- Package/install smoke completed or explicitly deferred.
+- Compatibility and release notes updated when user-facing behavior changes.

package/skills/oclif-plugin-development/manifest.json

@@ -0,0 +1,58 @@
+{
+  "id": "oclif-plugin-development",
+  "name": "Oclif Plugin Development",
+  "summary": "Build Open Orchestra plugins with oclif, TypeScript, command contracts, hooks, manifests, QA evidence, and secure package boundaries.",
+  "triggers": [
+    "oclif",
+    "plugin",
+    "plugins",
+    "cli plugin",
+    "command plugin",
+    "hook",
+    "hooks",
+    "manifest",
+    "plugin manifest",
+    "package exports",
+    "npm plugin",
+    "cli extension",
+    "react plugin ui",
+    "vite plugin ui",
+    "typescript plugin package"
+  ],
+  "roles": [
+    "developer",
+    "tech_lead",
+    "architect",
+    "qa",
+    "sdet",
+    "security",
+    "devops",
+    "platform_engineer",
+    "frontend_specialist"
+  ],
+  "capabilities": [
+    "plugin-development",
+    "cli-command-contracts",
+    "typescript-package-architecture",
+    "plugin-security",
+    "plugin-qa-evidence"
+  ],
+  "riskAreas": [
+    "maintainability",
+    "security",
+    "release",
+    "devops",
+    "integration",
+    "ux"
+  ],
+  "sourceGroups": [
+    "codebase",
+    "architecture",
+    "quality-security",
+    "devops-runtime",
+    "product-backlog"
+  ],
+  "evidence": ["command", "file", "report", "screenshot", "trace"],
+  "loadBudget": "normal",
+  "entry": "skills/oclif-plugin-development/SKILL.md"
+}