feat: lifecycle event hooks for external plugin authors

[cdub615]

Addresses #1442 (which I opened to propose this lifecycle-events surface). The issue lays out the motivating use case in more detail; this PR is the v1 implementation.

What problem are you trying to solve?

I built a Beads integration as a fork of Superpowers (visible on my fork at cdub615/superpowers:beads-integration). To make it shippable as a standalone plugin — which is what this project's contributor guidelines say domain-specific tools should be — the integration needs to react to plan/task lifecycle moments without modifying core skills. Today there's no supported mechanism for that, so the integration forks three core skills (writing-plans, executing-plans, subagent-driven-development) to add inline bd calls. That's the maintenance burden every workflow plugin author hits.

The specific failure mode: when I tried to extract the integration into a standalone plugin, I had nowhere to attach. The plan-mirror logic needs to fire after writing-plans' self-review passes; the bd update --claim logic needs to fire when a task transitions to in_progress; the close logic needs to fire on completion; the bd update --status blocked needs to fire on BLOCKED. With no hook mechanism, the only way to wire any of those is to edit the skill files. The fork branch is the proof.

I filed #1442 to propose this lifecycle-events surface; this PR is the implementation of the v1 subset of that proposal.

What does this PR change?

Adds a minimum-surface lifecycle event API:

• New scripts/emit-hook.sh (~90 LOC bash) — dispatches events to plugin shell scripts found in $SUPERPOWERS_HOOK_DIRS (colon-separated, like $PATH).
• 4 events emitted from existing core skills via additive markdown blocks: PlanWritten, TaskClaimed, TaskCompleted, BlockedOnHuman. Each block is wrapped in <!-- BEGIN lifecycle:Event --> / <!-- END lifecycle:Event --> markers and is a no-op when SUPERPOWERS_HOOK_DIRS is unset.
• Payloads pass as SP_<KEY> env vars (e.g., SP_PLAN_PATH, SP_TASK_NUMBER, SP_REASON).
• 10s default hook timeout (SUPERPOWERS_HOOK_TIMEOUT override). Plugin failures (timeout, nonzero exit, missing exec bit) log a warning but never propagate — emit-hook.sh always exits 0.
• New docs/superpowers/lifecycle-events.md plugin author reference.
• New tests/lifecycle-events/emit-hook.test.sh — 11 tests covering every documented behavior and failure mode.

Total diff: ~600 LOC, all additive, zero rewrites of existing skill prose.

This is a deliberate v1 subset of the 10 events proposed in #1442 — only the 4 events with a concrete consumer (the Beads integration) are included. The other 6 (BrainstormCompleted, DesignSaved, WorktreeCreated, ReviewFindingCreated, EpicCompleted, BranchFinished) are documented in the spec as roadmap items, each waiting for a real plugin that needs them. This avoids speculative additions per the project's "no theoretical fixes" rule.

Is this change appropriate for the core library?

Yes — this is general-purpose plugin infrastructure, not a domain-specific skill. It benefits all users by giving them a sanctioned way to extend Superpowers' lifecycle without modifying core, which directly aligns with the contributor guidelines ("domain-specific tools belong in standalone plugins").

No third-party dependencies. No domain-specific content. No new domain skills. The Beads use case is mentioned only as evidence that the problem is real; the events themselves are agnostic to any specific consumer. Other consumers #1442 enumerates: Linear/Jira/GitHub Issues sync, Slack/email notifications, per-epic cost controls, CI pre-validation, team-level workflow telemetry — none of which can be built today without forking.

What alternatives did you consider?

1. Direct integration of each plugin into core — what my fork currently does. Doesn't scale; every plugin author hits the same wall and either forks or gives up.
2. JSON-on-stdin payloads instead of env vars — overkill for v1. Current events have flat key/value payloads (paths, ids, free-text reasons). Plugins re-read the canonical artifact (the plan file) from $SP_PLAN_PATH if they need richer structure. Roadmap item if/when an event genuinely needs nested data.
3. Manifest-based plugin discovery (YAML/TOML) — adds a parser and a discovery convention to core. Deferred until ecosystem maturity (3+ plugins). For v1, env-var path list (familiar from $PATH) is the smallest possible discovery surface.
4. Filter events with a return channel — would let plugins inject text back into agent prompts. Rejected because it makes core aware of plugin output shape and complicates the contract. Pure observers are sufficient: plugins that need to enrich prompts mutate the plan file in PlanWritten, and the implementer prompt naturally picks up the mutation since it sends full task body text.
5. All ten events from Expose lifecycle events beyond SessionStart for external integration #1442 in v1 — explicitly deferred to keep the PR scoped to events with proven consumers.

Does this PR contain multiple unrelated changes?

No. Single feature: shell-based lifecycle event hooks for external plugin observers. The 13 commits are scoped TDD increments of one design (skeleton → dispatch → failure handling → timeout → edge tests → 3 skill emit points → reference doc → spec/doc fixes from review).

Existing PRs

• I have reviewed all open AND closed PRs for duplicates or prior art

Most relevant prior art:

• feat: add lifecycle extension system for user-defined workflow hooks #1224 (open, no maintainer response yet) — feat: add lifecycle extension system for user-defined workflow hooks by @jhochenbaum. Same problem space (lifecycle hooks at workflow events), genuinely different mechanism. I want to surface the comparison up front so the maintainer can choose how the project wants to handle this:

  	feat: add lifecycle extension system for user-defined workflow hooks #1224	this PR
  Plugin author writes	A Claude skill (markdown + YAML frontmatter)	A shell script
  Invocation site	Skill tool inside the agent's call graph	External process via Bash
  Discovery	YAML manifest at ~/.superpowers/extensions.yaml and .superpowers/extensions.yaml	$SUPERPOWERS_HOOK_DIRS (colon-separated dirs)
  Plugin runs in agent's loop	Yes — extension output is visible to the agent's reasoning	No — fire-and-forget side effect, no return path
  Events	7 (post-brainstorm, post-plan, pre-task, post-task, post-execution, post-review, pre-finish)	4 (PlanWritten, TaskClaimed, TaskCompleted, BlockedOnHuman)
  Best fit for	In-agent extensions: compound-learning, security audit, compliance check — work that participates in the agent's reasoning	External observers: state mirrors, audit logs, dashboards, issue trackers — work that records what the agent did

  The two approaches solve adjacent problems. feat: add lifecycle extension system for user-defined workflow hooks #1224's design is an excellent fit for the use cases listed in its PR body (extensions that read agent context and contribute to its reasoning). This PR's design is the right fit for use cases like Beads (mirror plan/task state to an external database) where the plugin work happens after the agent has moved on and shouldn't pollute the agent's call graph.

  Honest position: if the maintainer wants only one mechanism, feat: add lifecycle extension system for user-defined workflow hooks #1224 is the more general design. I'd rather see it land than nothing. But if external-observer hooks are seen as complementary infrastructure, this PR's design is genuinely simpler for that use case (no manifest parser, no Skill tool integration, no agent-graph participation). I'm happy to coordinate with @jhochenbaum if there's a unified approach worth pursuing.

• feat(iterating-on-plans): add post-execution iteration skill #943 (open) — post-execution iteration skill. Referenced in feat: add lifecycle extension system for user-defined workflow hooks #1224 as motivation. Not a direct conflict; it's a candidate consumer that either feat: add lifecycle extension system for user-defined workflow hooks #1224 or this PR could enable.

• feat: establish plugin architecture and add tinystruct developer skill #1107 — plugin architecture (skill directory organization). Different scope.

• RFC: Context provider convention for domain-specific sub-agent protocols #1128 / feat: context provider convention for sub-agent protocols #1129 — context provider via MCP. Different scope.

Related issue: #1442 (this PR's motivating issue, opened by me).

Environment tested

Harness	Harness version	Model	Model version/ID
Claude Code	2.1.126	Claude Opus 4.7 (1M)	claude-opus-4-7

Cross-harness validation (Cursor, Codex, Gemini, OpenCode) was not run — the script's harness fallback chain (CLAUDE_PLUGIN_ROOT → CURSOR_PLUGIN_ROOT → SUPERPOWERS_ROOT) follows the existing precedent from hooks/session-start and other scripts but should be validated on at least one non-Claude-Code harness before merge. Happy to run that if requested.

New harness support (required if this PR adds a new harness)

N/A — does not add a new harness.

Evaluation

• Initial prompt: "review the beads-integration branch and look at what events we'd need to expose in order to create a standalone plugin that would replicate the functionality in that branch."
• Sessions run: Single end-to-end session via SDD: brainstorming → spec design (with 4 explicit decision gates) → plan writing → 10-task execution loop with per-task spec compliance + code-quality reviews → final whole-implementation review → spec/doc fixes from review feedback.
• Outcome: 11/11 unit tests pass; 4 events fire correctly with correct payloads in end-to-end stub-plugin verification; no-plugins case is silent (SUPERPOWERS_HOOK_DIRS unset → rc=0, empty output).
• Before/after: Before this change, my Beads integration on beads-integration requires direct edits to writing-plans/SKILL.md, executing-plans/SKILL.md, subagent-driven-development/SKILL.md, plus injecting prompt-template content into subagent-driven-development/implementer-prompt.md — that's 79+ lines of skill modifications a fork has to maintain. After this change, that same plugin can ship as a standalone directory of shell scripts the user adds to $SUPERPOWERS_HOOK_DIRS, with zero edits to core. Default user behavior is identical in both cases — when no plugins are installed, the lifecycle blocks are conditional no-ops.

Rigor

• Skills change discipline: Each emit block is purely additive (paired <!-- BEGIN lifecycle:Event --> / <!-- END lifecycle:Event --> markers; git diff against base shows zero - content lines in skills/). No rewording of existing prose. No modifications to Red Flags / rationalization tables / "human partner" language / behavior-shaping content. The added blocks all open with the no-op-when-unset note so an agent reading them on a default install knows to skip.
• Tested adversarially, not just happy path: the test suite covers every documented failure mode — unset HOOK_DIRS, missing hook script, non-executable hook, hook exits nonzero, hook exceeds timeout, missing event name, multi-dir ordering, stdin/stdout isolation, key=value with literal = in value, malformed args. Pre-impl test runs confirmed each TDD test failed for the expected reason before the implementation landed.
• Did not modify carefully-tuned content: verified by git diff — the skill changes touch only inserted blocks; the existing Red Flags tables, rationalization checklists, "human partner" framings, and any agent-behavior-shaping prose are byte-for-byte unchanged.

Human review

• A human has reviewed the COMPLETE proposed diff before submission. The work was developed via Subagent-Driven Development with per-task spec + code-quality reviews, a final whole-implementation review, and explicit human approval at every decision gate (design choices, scope, alternatives, mechanism, payload format, event naming, marker style, timeout policy, and pre-submission positioning against feat: add lifecycle extension system for user-defined workflow hooks #1224).