** Plugin and Extension Architecture for Custom Pipeline Stages and Hooks

[github-actions]

Strategic Improvement

** Create a plugin system allowing custom pipeline stages, hooks, and integrations without modifying core Shipwright code. This enables community contributions, specialized workflows, and organization-specific customizations.

Acceptance Criteria

• Plugin manifest schema (name, version, stage definitions, hook points, dependencies)
• Plugin discovery and loading from .claude/plugins/ directory
• API for plugin lifecycle (init, execute, cleanup) with context injection
• Custom stage registration that integrates with pipeline composer
• Example plugins: Slack notifier, Terraform plan validator, custom security scanner
• Documentation for plugin development with starter template

Context

• Priority: ** P5
• Complexity: ** full
• Generated by: Strategic Intelligence Agent
• Strategy alignment: ** P5: Community & Growth

[github-actions]

⚓ Shipwright Triage — Issue Declined

This issue was reviewed by the automated triage system and does not appear to align with Shipwright's project goals.

Reason: Plugin architecture is premature abstraction for hypothetical integrations; propose concrete features (Slack notifier, Terraform validator) as native commands instead.

If you believe this is incorrect, a maintainer can override by:

1. Running the workflow manually with "Skip triage" enabled
2. Adding context to the issue and re-applying the shipwright label

For questions or support, please use Discussions instead.

[github-actions]

⚓ Shipwright Pipeline Starting

Field	Value
Template	standard
Complexity	full
Max Iterations	30
Triage	Aligns with Shipwright's extensibility mission and community goals, but requires significant architectural work (manifest schema, discovery mechanism, API design, integration with pipeline composer, examples, and documentation). Should be approached incrementally, starting with formalizing existing and hook patterns.
Runner	ubuntu-latest
Risk Level	unknown
Workflow	25252023783

The autonomous pipeline is processing this issue. Updates will be posted as stages complete.

[github-actions]

[github-actions]

[github-actions]

📋 Implementation Plan

Click to expand full plan (226 lines)

Implementation Plan: Plugin & Extension Architecture (Issue #458)

Goal

Create a plugin system that allows custom pipeline stages, hooks, and integrations to be added without modifying core Shipwright code. Plugins are discovered from .claude/plugins/, declare their capabilities in a manifest, and integrate with the existing pipeline composer and emit_event hook surface.

Brainstorming / Socratic Refinement

Requirements Clarity

• Minimum viable change: a discovery+loader (scripts/lib/plugin-loader.sh), a manifest schema (config/plugin-manifest.schema.json), a CLI surface (shipwright plugin <list|info|validate|run>), a stage registration hook into pipeline-composer, an event-bus subscription mechanism for hooks, three example plugins, and developer docs + starter template.
• Implicit requirements: sandboxed execution (plugins must not silently break the pipeline), version compatibility checks (shipwright_min_version), idempotent enable/disable, deterministic load order (sort by name), failure isolation (one plugin failing must not crash the pipeline).
• Acceptance criteria (re-derived; issue's section is empty): (1) Manifest schema published & validated by jq. (2) .claude/plugins/<name>/plugin.json discovered automatically. (3) shipwright plugin list enumerates loaded plugins with version/status. (4) Custom stage declared by a plugin runs when included in a composed pipeline. (5) Hook pipeline.stage_completed fires for subscribed plugins. (6) Three example plugins ship under plugins/ and execute end-to-end in tests. (7) docs/plugins.md covers manifest, lifecycle, hooks, and a starter template under templates/plugin-starter/.

Design Alternatives

1. Bash-sourced plugins (CHOSEN) — Each plugin is a directory with plugin.json + plugin.sh. The loader validates the manifest, then sources plugin.sh only inside subshells for lifecycle calls. Pros: zero new runtime dependency, matches existing architecture (every other extension point in Shipwright is a sourced bash module), easy debugging, reuses helpers. Cons: plugins share the parent shell namespace — must enforce isolation.
2. Subprocess plugins (rejected) — Each plugin is an executable invoked via JSON-over-stdin. Pros: language-agnostic, hard isolation. Cons: doubles invocation overhead, no access to shared helpers (emit_event, info, _smart_model), drifts from architecture conventions, larger blast radius.
3. Hybrid (deferred) — Bash for stages/hooks; subprocess for "integrations only". Defer until a real plugin can't be expressed in bash. All three example plugins fit option 1.

Choice rationale: option 1 minimizes blast radius (one new lib + one new CLI script + composer touch-up), reuses emit_event, and matches the "Pipeline stages source from scripts/lib/" architecture rule.

Risk Assessment

• A misbehaving plugin sourced into the parent shell could exit, trip set -e, or clobber globals → mitigated by sourcing only inside subshells for each lifecycle call.
• Manifest injection (eval-style) → mitigated by jq --arg parsing only; never eval manifest fields.
• Plugin name collision with built-in stages → loader rejects manifest if stages[].id matches a reserved built-in stage list.
• Path traversal via plugin.json paths → loader rejects any path containing .. or absolute paths.

Dependency Analysis

• Depends on: scripts/lib/helpers.sh (emit_event, output helpers), scripts/sw-pipeline-composer.sh for stage merging, jq.
• Reverse dependencies: sw-pipeline.sh indirectly via composer; sw-daemon.sh for plugin auto-discovery.
• No circular dependency risk: plugin-loader sits above helpers, below composer.

Simplicity Check

• One library, one CLI script, one composer touch-up. Reuses emit_event for hook dispatch — no new event bus.
• Examples live in plugins/ (top-level shipped examples). Discovery directory is .claude/plugins/. A copy script (or symlink) makes shipped examples installable.

API Design

Manifest Schema (config/plugin-manifest.schema.json)

{
  "name": "string (kebab-case, required)",
  "version": "semver string (required)",
  "api": "integer (plugin API version, required, currently 1)",
  "shipwright_min_version": "semver string",
  "description": "string",
  "author": "string",
  "entrypoint": "relative path to .sh (required)",
  "stages": [
    { "id": "kebab-case", "after": "stage-id", "timeout_seconds": 600, "effort": "low|medium|high" }
  ],
  "hooks": [

</details>

## ✅ Task Checklist
- [ ] No `eval` of manifest values
- [ ] All `jq` calls use `--arg` for user-supplied strings
- [ ] Subshell isolation for every lifecycle call
- [ ] `timeout` on every lifecycle invocation
- [ ] Path traversal rejection in loader
- [ ] Plugin events flow to `events.jsonl` for auditability
- [ ] **Task 1**: Author `config/plugin-manifest.schema.json` and manifest validator helpers in `plugin-loader.sh` *(no deps)*
- [ ] **Task 2**: Implement `plugin-loader.sh` discovery, registry, invoke, dispatch *(blocks 4, 5, 6, 9, 10)*
- [ ] **Task 3**: Wire `emit_event` → `plugin_dispatch_hook` in `helpers.sh` with depth guard *(depends on 2)*
- [ ] **Task 4**: Composer integration for plugin-declared stages *(depends on 2)*
- [ ] **Task 5**: `run_plugin_stage` in `pipeline-stages.sh` *(depends on 2, 4)*
- [ ] **Task 6**: `sw-plugin.sh` CLI + `scripts/sw` router wiring *(depends on 2)*
- [ ] **Task 7**: Starter template under `templates/plugin-starter/` *(depends on 1)*
- [ ] **Task 8**: Three example plugins under `plugins/` *(depends on 2, 3, 4)*
- [ ] **Task 9**: `sw-plugin-test.sh` covering loader, CLI, hooks, stage execution, STRIDE mitigations *(depends on 2-6)*
- [ ] **Task 10**: Register test in `package.json`; full `npm test` pass *(depends on 9)*
- [ ] **Task 11**: `docs/plugins.md` and `.claude/CLAUDE.md` Plugin System section *(depends on 1-8)*
- [ ] **Task 12**: Bash 3.2 + lint pass + version header sync *(depends on 2, 6, 9)*
- [ ] `config/plugin-manifest.schema.json` exists; validator rejects every listed bad input with typed errors.
- [ ] `.claude/plugins/<name>/plugin.json` discovered automatically with default-deny (`.enabled` marker).

---
_Generated by `shipwright pipeline` at 2026-05-02T12:45:35Z_

[github-actions]

[github-actions]

[github-actions]

📐 Architecture Decision Record

Click to expand ADR (210 lines)

Design: Plugin and Extension Architecture for Custom Pipeline Stages and Hooks

Context

Shipwright currently has 14 fixed pipeline stages and a closed set of hook points. Users who need custom stages (e.g., terraform-plan, security-scan) or custom event handlers (e.g., Slack notification on PR creation) must fork the repo or modify core scripts. This violates the "extend through composition, not modification" principle and creates maintenance burden.

Constraints from the codebase:

• Bash 3.2 compatible — no declare -A, readarray, or ${var,,}
• All scripts use set -euo pipefail with VERSION= headers synced to package.json
• Existing extension surfaces: emit_event (events.jsonl), scripts/lib/ modules, sw-pipeline-composer.sh
• Architecture rule: pipeline stages source from scripts/lib/; CLI scripts dispatch via scripts/sw
• Test harness: PASS/FAIL counters, mock binaries in temp dirs, ERR traps
• Default-deny posture for anything that executes user-supplied code

Decision

Bash-sourced plugins discovered from .claude/plugins/<name>/, each declaring a plugin.json manifest and plugin.sh entrypoint. Lifecycle calls execute in subshells with timeout, isolating crashes from the parent pipeline. Plugins integrate via two seams: the composer (for custom stages) and emit_event (for hook dispatch).

Data flow:

.claude/plugins/<name>/         scripts/lib/                 scripts/sw-pipeline-composer.sh
├── plugin.json    ──┐          plugin-loader.sh             │
├── plugin.sh        │          ├── discover()  ──→ registry │
└── .enabled         └────────→ ├── validate()      .json   ─┴──→ composed-pipeline.json
                                ├── load()  (parse-only subshell)
                                └── invoke() (subshell + timeout)
                                        ▲
                                        │
                  emit_event() ─────────┘  (depth-guarded fan-out)

Error handling: Every lifecycle call returns a typed error code (PLUGIN_MANIFEST_INVALID, PLUGIN_LIFECYCLE_FAILED, etc.) emitted as plugin.failed events. Composer falls back to built-in stages if registry load fails — pipeline never blocks on plugin subsystem failure.

Trust model: Default-deny via .enabled marker (created by shipwright plugin enable). Manifest declares permissions.env and permissions.binaries; loader exports only allowlisted env vars to subshells and verifies binaries via command -v at registration.

Alternatives Considered

1. Subprocess plugins (JSON-over-stdin executables) — Pros: language-agnostic, hard process isolation. Cons: doubles invocation overhead, no access to shared bash helpers (emit_event, _smart_model), drifts from architecture conventions, larger surface area for the loader. Rejected: all three example plugins fit the bash model cleanly.
2. Hybrid (bash for stages/hooks, subprocess for integrations) — Pros: future-proofs language-agnostic plugins. Cons: two loaders, two manifest dialects, two security models. Deferred until a real plugin can't be expressed in bash.
3. In-tree extension functions (no manifest) — Pros: simpler. Cons: no discovery, no versioning, no isolation, no default-deny. Rejected: doesn't meet the "no core modification" DoD criterion.

Component Diagram

┌─────────────────────────────────────────────────────────────────┐
│                      scripts/sw (router)                         │
│                              │                                   │
│                              ▼                                   │
│                    scripts/sw-plugin.sh                          │
│                  (CLI: list/info/validate/                       │
│                   enable/disable/run)                            │
└────────────────────────────┬─────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│              scripts/lib/plugin-loader.sh                        │
│  ┌──────────┐  ┌──────────┐  ┌────────────┐  ┌──────────────┐  │
│  │ discover │→ │ validate │→ │  registry  │→ │ invoke (sub- │  │
│  │ (sorted) │  │ (jq+regex)│  │ (atomic)   │  │ shell+timeout)│  │
│  └──────────┘  └──────────┘  └────────────┘  └──────────────┘  │

</details>

---
_Generated by `shipwright pipeline` design stage at 2026-05-02T12:48:07Z_

[github-actions]