v3.0.0 — Multi-runtime skills distributions

[3.0.0] - 2026-07-25

Major release: keep Claude Code as the full canonical plugin while adding
generated, runtime-native skills distributions for Amp, Codex, Pi, and
OpenCode. Each target is explicit about supported workflows and deferred
capabilities rather than claiming cross-runtime feature parity.

Added

• LiveView client-boundary guidance — documents that phx-value-*, form,
  and hook payloads are user-controlled; clarifies that exposed IDs are not an
  authorization flaw by themselves and must be checked against server-side
  state in every event.

• Generated multi-runtime skills distributions — all 51 canonical skills,
  complete resource subtrees, non-Markdown bytes, and executable modes now ship
  as deterministic targets for Amp, Codex, Pi, and OpenCode. Target generators
  normalize names and invocation syntax, validate references and manifests,
  reject collisions and escaping resources, build through staging directories,
  preserve prior output on failure, and provide read-only drift checks. Claude
  Code remains the canonical source and retains its full native hooks, agents,
  MCP, permissions, and instructions.

• Canonical multi-runtime support matrix — documents native invocation,
  distribution, supported and deferred capabilities, generated-target
  acceptance requirements, and isolated Amp, Codex, Pi, and OpenCode smoke-test
  contracts.

• All-runtime generated skills sync command — contributors can run
  make generated-skills-sync to regenerate and validate Amp, Codex, Pi, and
  OpenCode in sequence, then validate the reviewed golden snapshots.
  Target-specific sync and validation commands remain the authoritative
  implementation and keep failures attributable.

• Codex native destructive-command safeguard — the generated Codex plugin
  now includes one trust-gated, synchronous PreToolUse hook that reuses the
  canonical audited blocker for destructive Ecto operations, unguarded force
  pushes, and accidental production Mix commands. The broad Claude hook set,
  async hooks, custom agents, and Tidewave MCP remain deferred.

• Optional runtime smoke harness — make amp-runtime-smoke,
  make codex-runtime-smoke, make pi-runtime-smoke, and
  make opencode-runtime-smoke validate locally
  generated targets, native installation or discovery, all 51 installed skills,
  retained resources and modes, and fresh-process removal in isolated temporary
  homes without requiring credentials or making model calls.

• Generated-target golden snapshots — CI now pins aggregate path, byte, and
  executable-mode digests for Amp, Codex, Pi, and OpenCode before shared
  generator refactoring. Target changes require an explicit reviewed snapshot
  update instead of silently redefining the baseline.

• Package-specific /phx:learn-from-fix routing — verified fixes and
  explicit user-taught rules can now be saved as native background skills with
  --library <package> --scope personal|project. The workflow reads locked
  versions, checks both scopes for shadowing, merges safely, and never writes to
  cached plugin files. General cross-project rules route to personal
  ~/.claude/CLAUDE.md. Description-based activation remains model-selected.

• Amp target drift pre-commit guard — canonical changes under
  plugins/elixir-phoenix/skills/ now trigger make amp-skills-validate and
  require regenerated targets/amp/skills/ changes to be staged. CI retains
  the same drift check as the authoritative fallback. Contributors can run
  make amp-skills-sync to regenerate and verify the complete target in one
  command.

Changed

• Optional release-service configuration — deployment guidance now gates
  optional S3, Redis, and similar credentials behind their feature switch so
  unrelated release commands such as bin/migrate can start without them.

• Portable Amp investigation and review workflows — generated Amp
  phx-investigate and phx-review now preserve evidence-first investigation,
  read-only review, optional native workers, and complete same-session sequential
  fallbacks without Claude task APIs, named agents, hooks, or MCP identifiers.

• Portable PR-review/full workflow overlays — generated Amp, Codex, Pi, and
  OpenCode phx-pr-review now use available GitHub connectors or authenticated
  gh, preserve read-only triage and explicit mutation approval, and never infer
  replies or resolution. Generated phx-full now preserves user phase gates,
  bounded retries/cycles, explicit verification, read-only review, and compound
  completion through portable skill invocation or sequential same-session
  execution. Canonical Claude output remains unchanged; other workflows are not
  claimed portable.

• Portable plan/work workflow overlays — generated Amp, Codex, Pi, and
  OpenCode phx-plan and phx-work skills now use scratchpad research checklists, plan
  checkboxes, and progress.md instead of Claude-only named agents, task APIs,
  question tools, hooks, or MCP identifiers. Optional native subagents and
  Tidewave retain complete same-session sequential fallbacks. Canonical Claude
  skills are unchanged; this does not claim parity for other generated workflows.

• Codex skill descriptions now preserve routing signal within a compact
  budget — generated descriptions are capped at 120 characters while retaining
  key capability and trigger cues. Route-sensitive skills keep explicit negative
  routing rules to avoid collisions. This reduces pressure on Codex's shared
  skills context without changing canonical Claude descriptions, explicit skill
  bodies, or other generated runtimes.

• Amp installation no longer requires cloning this repository — the primary
  project-local and global instructions now install all 51 generated skills
  directly from the GitHub targets/amp/skills tree. Update instructions also
  clarify that Amp copies skills and requires an explicit --overwrite install.

Fixed

• Examples skill routing — clarify that requests for sample code, proper
  implementations, walkthroughs, and expected workflow output should load the
  examples skill alongside the relevant domain skill.

• Accurate Tidewave MCP setup boundary — update the maintained Phoenix
  dependency requirement and repository link, distinguish exposing Tidewave's
  HTTP server from registering it with a client, and document external
  registration for Claude Code, Codex, and OpenCode.

• Claude Code 2.1.217–2.1.220 nested-agent compatibility — flagship
  workflows account for the depth-1 default in 2.1.217–2.1.218 and the restored
  depth-3 default in 2.1.219+. Explicit lower-depth configurations keep
  orchestration in the main conversation while spawning leaf specialists
  directly, preserving the plan/work/verify/review contracts. Nested
  investigation tracks apply tracing directly to avoid a depth-4 chain.

• Claude Code 2.1.212 Agent invocation compatibility — removed the ignored,
  deprecated Task/Agent mode parameter from workflow instructions. Subagents
  inherit the parent session's permission mode.

• Fork-session continuity on Claude Code 2.1.214+ — resume, scratchpad, and
  branch-freshness SessionStart checks now also run for source fork.

• Claude Code 2.1.218 agent validation compatibility — declared agent names
  remain unqualified while concrete runtime invocations use the phx: plugin
  namespace. Regression coverage rejects colons in declared agent names and
  unrecognized agent tool names.

• Claude Code slash-command compatibility remains stable in v3 — the
  marketplace package keeps its elixir-phoenix install identity while the
  plugin namespace now explicitly registers /phx:*; auto-installed ecto
  and lv compatibility plugins preserve /ecto:* and /lv:*. The call
  tracing skill directory now matches /phx:trace, and regression coverage
  checks effective namespace-plus-frontmatter command names. Canonical
  frontmatter names contain only the final command segment because Claude Code
  2.1.216+ retains the plugin prefix when a skill declares name.

• v2 → v3 upgrade path preserves newly added compatibility dependencies —
  install the new ecto and lv compatibility plugins from the updated
  marketplace before updating elixir-phoenix. This avoids a temporary
  missing-dependency state on existing installations. Restart Claude Code
  before relying on the updated hooks and agents.

• Generated freeze is now honest about its safety boundary — Amp, Codex,
  Pi, and OpenCode receive an advisory current-session edit scope instead of a
  sentinel that falsely claimed enforcement by an uninstalled Claude hook.

• Generated nested resource links now resolve from their containing file —
  Amp, Codex, Pi, and OpenCode projections compute skill-relative paths from
  each Markdown resource directory instead of the skill root, fixing broken
  cross-skill and sibling links under nested references/ directories.

• Pre-release test and docs-site consistency — npm test now includes the
  scripts/tests/ port suite, matching make test and CI, and the docs-site
  rebuild workflow triggers on all five runtime guides instead of only
  docs/amp.md.

• Pi Git-package metadata now matches the generated distribution — the
  repository-root manifest used by the documented Pi installation reports the
  same pi-elixir-phoenix name, 3.0.0 version, and Pi-focused description as
  targets/pi/package.json.

• Amp generation now rejects source symlinks and preserves Markdown modes —
  generated resources can no longer dereference links outside the canonical
  skill tree, and transformed Markdown permissions no longer depend on the
  invoking process's umask.

• Runtime support and security claims now match operational boundaries —
  the flagship portability contract is scoped to adapted Codex, Pi, and
  OpenCode workflows; Codex documents and surfaces its Bash/jq hook
  prerequisites; and security documentation distinguishes absent telemetry or
  covert egress from visible, user-authorized external service calls.

• Codex dependency-vetting routing metadata stays complete — the generated
  phx-deps-vet description now preserves both its post-audit trigger and its
  distinction from dependency scanning instead of ending mid-clause.

• Reliable behavioral trigger gates and routing boundaries — deterministic
  structural evals no longer depend on ignored local result caches, while
  make eval-full runs a fresh Claude Haiku 4.5 gate requiring every skill to
  reach 75% accuracy. The judge now receives complete descriptions, validates
  the exact skill/fixture set, retries infrastructure failures, rejects malformed
  output, and writes results atomically. Generalized routing fixes brought all
  51 skills above the threshold in the final full run (95.74% aggregate).

• Generated-runtime install lifecycle guidance — Amp now documents native,
  target-scoped removal and exact-sync boundaries; Pi distinguishes configured
  Git refs from unpinned dependencies and includes both project and user clean
  reinstall flows; OpenCode uses its documented plural skills path and treats
  slash invocation as a tested 1.17.2 convenience rather than the portable API.

• Codex plugin skill references now use their required runtime namespace —
  explicit invocations and generated sibling references use
  $elixir-phoenix:phx-investigate rather than the non-resolving unqualified
  $phx-investigate form. README and Codex installation guidance now document
  the exact plugin-qualified syntax inserted by /skills.

• Portable command rewriting now requires complete invocation tokens — Amp,
  Codex, Pi, and OpenCode projections leave filesystem paths, URLs, uppercase
  names, underscored suffixes, and malformed namespace wildcards unchanged. Pi
  now emits native /skill:* syntax directly instead of passing through a
  path-like intermediate form.

• Learning destination and skill-loading documentation — project-keyed
  auto-memory is no longer described as applying to every Elixir project, and
  the intro now documents native paths: frontmatter as a file-path gate.