feat(amp): add deterministic native workflows

.github/workflows/lint.yml

@@ -113,13 +113,16 @@ jobs:
         with:
           python-version: "3.12"
 
+      - name: Setup Bun for Amp plugin runtime harness
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6  # v2.2.0
+
       - name: Install dependencies
         run: pip install -r requirements.txt
 
       - name: Run pytest
         run: python3 -m pytest lab/eval/tests/ scripts/tests/ -v --tb=short
 
-      - name: Check Amp generated skills
+      - name: Check Amp generated target
         run: python3 -m scripts.build_amp_skills --check
 
       - name: Check Codex generated skills

.husky/pre-commit

@@ -71,16 +71,16 @@ fi
 # source and projection land in the same commit. CI repeats the drift check from
 # the committed tree for contributors without Husky.
 if [ -n "$STAGED_CANONICAL_SKILLS" ]; then
-  echo "→ Checking generated Amp skills..."
-  if ! make amp-skills-validate > /tmp/precommit-amp-skills.log 2>&1; then
-    echo "Amp skills are out of date. Run: make amp-skills-sync"
-    tail -30 /tmp/precommit-amp-skills.log
+  echo "→ Checking generated Amp target..."
+  if ! make amp-target-validate > /tmp/precommit-amp-target.log 2>&1; then
+    echo "Amp target is out of date. Run: make amp-target-sync"
+    tail -30 /tmp/precommit-amp-target.log
     exit 1
   fi
 
-  UNTRACKED_AMP_SKILLS=$(git ls-files --others --exclude-standard -- targets/amp/skills)
-  if ! git diff --quiet -- targets/amp/skills || [ -n "$UNTRACKED_AMP_SKILLS" ]; then
-    echo "Generated Amp skill changes are not staged. Run: git add targets/amp/skills"
+  UNTRACKED_AMP_TARGET=$(git ls-files --others --exclude-standard -- targets/amp)
+  if ! git diff --quiet -- targets/amp || [ -n "$UNTRACKED_AMP_TARGET" ]; then
+    echo "Generated Amp target changes are not staged. Run: git add targets/amp"
     exit 1
   fi
 fi

CHANGELOG.md

@@ -35,6 +35,12 @@ Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   search read the whole README and never learned the docs site exists. The
   repo's About → Website field was already set.
 
+- **Deterministic Amp workflow plugin** — the generated Amp target now includes
+  40 workflow palette commands, five read-only domain specialists, bounded
+  parallel review and investigation, a persistent classified edit lock, and a
+  bounded `phx-full` verification gate. The standalone distribution promotes a
+  validated `stable` branch for direct GitHub installation.
+
 ### Changed
 
 - **Release bodies now carry a docs-site footer** — the `release` contributor
@@ -45,6 +51,13 @@ Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   unique cloners from 51 to 120 in a single day (2.4x), decaying to baseline
   over about four days.
 
+- **Amp installation profiles and scope names now match current Amp** — docs
+  distinguish hosted-native from paired-full behavior, use native `skill:
+  invoke` for deterministic hosted skill loading, and separate machine-local
+  `--global` installs from personal/workspace hosted repositories. The public
+  standalone repository, generated target, gated `stable` branch, paired local
+  install, and GitHub/curl fallback remain supported.
+
 - **`deep-bug-investigator` synthesizes on opus, its four tracks run on sonnet**
   (thanks @BugsBunny338, #133) — the agent coordinates four parallel
   investigation tracks and then reconciles their often-conflicting evidence.
@@ -115,6 +128,14 @@ Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   all four Claude-facing manifests while the gate looked at one of them. All
   five manifests are validated now.
 
+- **Amp wrapper skill resolution follows supported local precedence** — the
+  generated plugin now checks machine-local skill roots before workspace roots
+  and searches `.agents/skills` and `.claude/skills` through the parent
+  directories exposed from `workspaceRoot`. Docs explicitly call out sources
+  the Plugin API cannot resolve, including hosted repositories, built-ins,
+  plugin caches, custom `amp.skills.path`, and nested invocation roots that are
+  not exposed to plugins.
+
 - **`displayName` removed from all Claude Code manifests** (reported by
   @ndrean, #130) — the field was introduced alongside the v3 plugin split and
   reported as an install blocker one day later. It is undocumented: it appears

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help lint lint-fix eval eval-all eval-fix eval-full eval-ci eval-triggers eval-tournament eval-skills eval-agents eval-multimodel eval-compare-models test validate amp-skills amp-skills-sync amp-skills-validate amp-runtime-smoke codex-skills codex-skills-sync codex-skills-validate codex-runtime-smoke pi-skills pi-skills-sync pi-skills-validate pi-runtime-smoke opencode-skills opencode-skills-sync opencode-skills-validate opencode-runtime-smoke generated-skills-sync generated-skills-snapshots generated-skills-snapshots-validate security ci clean
+.PHONY: help lint lint-fix eval eval-all eval-fix eval-full eval-ci eval-triggers eval-tournament eval-skills eval-agents eval-multimodel eval-compare-models test validate amp-target amp-target-sync amp-target-validate amp-skills amp-skills-sync amp-skills-validate amp-runtime-smoke codex-skills codex-skills-sync codex-skills-validate codex-runtime-smoke pi-skills pi-skills-sync pi-skills-validate pi-runtime-smoke opencode-skills opencode-skills-sync opencode-skills-validate opencode-runtime-smoke generated-skills-sync generated-skills-snapshots generated-skills-snapshots-validate security ci clean
 
 # Default target
 help: ## Show available commands
@@ -66,14 +66,20 @@ validate: ## Run claude plugin validate on every plugin + marketplace manifest
 	@claude plugin validate plugins/catchup
 	@claude plugin validate .
 
-amp-skills: ## Generate Amp skills from the canonical Claude plugin
+amp-target: amp-skills ## Generate the complete Amp skills and workflow plugin target
+
+amp-target-sync: amp-skills-sync ## Regenerate and verify the complete Amp target
+
+amp-target-validate: amp-skills-validate ## Check the complete Amp target for generated drift
+
+amp-skills: ## Generate the Amp skills and workflow plugin (backward-compatible name)
 	@python3 -m scripts.build_amp_skills
 
 amp-skills-sync: ## Regenerate and verify the committed Amp target
 	@$(MAKE) amp-skills
 	@$(MAKE) amp-skills-validate
 
-amp-skills-validate: ## Check committed Amp skills for generated drift
+amp-skills-validate: ## Check the committed Amp target for generated drift
 	@python3 -m scripts.build_amp_skills --check
 
 amp-runtime-smoke: ## Optional: smoke-test local target with an isolated Amp runtime

README.md

@@ -16,11 +16,12 @@ expertise, fresh context, and enforced [Iron Laws](#iron-laws-non-negotiable-rul
 that catch the bugs your tests won't.
 
 **Using Amp?** Install the generated edition for the same 51 Elixir, Phoenix,
-LiveView, Ecto, Oban, testing, and security skills plus the optional native PR
-watch lifecycle plugin. See
-[Use with Amp](#use-with-amp) for the important differences from the full Claude
-Code plugin, or the [Amp install guide](https://phxagents.dev/install/amp/) on
-phxagents.dev.
+LiveView, Ecto, Oban, testing, and security skills, plus 40 deterministic
+workflow wrappers, five read-only specialist agents, parallel review/investigation, and
+native edit/verification guards, and the native PR watch lifecycle
+plugin. See [Use with Amp](#use-with-amp) for the
+important differences from the full Claude Code plugin, or the
+[Amp install guide](https://phxagents.dev/install/amp/) on phxagents.dev.
 
 **Using Codex?** Install the native generated skills plugin for all 51 skills,
 including `$elixir-phoenix:phx-investigate` and
@@ -262,69 +263,64 @@ directories provide the legacy `/ecto:*` and `/lv:*` aliases.
 
 ### Use with Amp
 
-Amp can install the plugin's 51 skills from the generated Agent Skills target.
-Project-local installation is recommended because it keeps the Elixir/Phoenix
-guidance scoped to the repository where it applies:
+Amp supports two profiles from the same generated snapshot:
+
+- **Hosted-native:** publish the skills and plugin independently to Amp personal
+  or workspace repositories. Use Amp's native `skill: invoke` command. The
+  plugin still provides specialists, parallel analysis, and edit lock, but its
+  filesystem wrappers cannot load hosted-only skills and native `phx-full` does
+  not arm the plugin verification gate.
+- **Paired-full:** install matching skills and plugin locally. This preserves all
+  40 `phx:*`/`ecto:*`/`lv:*` wrappers and the wrapper-activated `phx-full` gate.
+
+Project-local paired installation is recommended for reproducible full behavior:
 
 ```bash
-# Install into one Elixir/Phoenix project
 cd /path/to/your-phoenix-project
+
+# Install the 51 skills into this project
 amp skill add \
-  https://github.com/oliver-kriska/claude-elixir-phoenix/tree/main/targets/amp/skills \
+  https://github.com/oliver-kriska/amp-elixir-phoenix/tree/stable/skills \
   --target "$PWD/.agents/skills"
 
-# Or install for every Amp workspace
-amp skill add \
-  https://github.com/oliver-kriska/claude-elixir-phoenix/tree/main/targets/amp/skills \
-  --global
+# Add deterministic workflows, read-only agents, and native guards
+mkdir -p .amp/plugins
+plugin=".amp/plugins/elixir-phoenix.ts"
+temporary="$(mktemp "${plugin}.XXXXXX")"
+curl --fail --silent --show-error --location \
+  https://raw.githubusercontent.com/oliver-kriska/amp-elixir-phoenix/stable/plugins/elixir-phoenix.ts \
+  --output "$temporary" && mv "$temporary" "$plugin"
 ```
 
-`phx-watch-pr` additionally needs the generated Amp plugin. Install it into the
-project where the worker Orb opens and watches PRs:
+Open Amp's command palette with `Ctrl+O`, run `skill: invoke`, choose
+`phx-investigate`, and send the bug details. This native path resolves the
+effective skill whether it is local, built-in, personal hosted, or workspace
+hosted. With paired-full, the familiar `phx: investigate`, `phx: review`,
+`ecto: n1-check`, and `lv: assigns` wrappers are also available; they inject the
+matching local skill for one turn. `phx: full` activates the plugin verification
+gate only through that wrapper, not through native `skill: invoke`.
+
+`amp skill add --global` means **machine-local**, under
+`~/.config/agents/skills/`; it is not personal hosted/account-wide. Personal
+hosted artifacts are managed through Amp's Personal Settings or personal Git
+repositories and work across machines and orbs. See the complete [Amp guide](docs/amp.md)
+for hosted publication, source precedence, wrapper limits, updates, fallback
+installation, specialists, safety boundaries, and verification.
+`phx-watch-pr` additionally needs the separate `phx-watch-pr.ts` plugin.
+Install it into the project where the worker Orb opens and watches PRs:
 
 ```bash
 amp plugins add \
   https://raw.githubusercontent.com/oliver-kriska/claude-elixir-phoenix/main/targets/amp/plugins/phx-watch-pr.ts \
   --target workspace
 ```
 
-The plugin holds a bounded Orb keep-alive lease, filters deployment-like checks
-out of readiness, persists reload-safe state, and wakes the same worker thread
-only for failed/cancelled required CI, unresolved feedback, and terminal
-outcomes. Its defaults are a 60-second poll, 15-minute activity-based quiet
-period, and 2-hour active-watch cap. Head pushes, required-check transitions,
-reviews, and comments restart the quiet period without routine model turns;
-deployment-like transitions do neither. With `--fix`, actionable feedback and
-branch-owned CI failures are repaired in one serialized same-thread workflow.
-It never blindly reruns shared CI, merges, or deploys.
-
-Amp copies skills at installation time; it does not update them automatically.
-Rerun the same command with `--overwrite` to install the latest version from
-`main`. Cloning this repository is only necessary for local development.
-
-Namespaced Claude commands use hyphenated Amp names: `/phx:plan` becomes
-`phx-plan`, `/ecto:n1-check` becomes `ecto-n1-check`, and so on. Start a fresh
-Amp session after installation. To invoke the equivalent of `/phx:investigate`
-reliably, open Amp's command palette with `Ctrl+O` (or type `/` in the CLI), run
-`skill: invoke`, and select `phx-investigate`. Amp forces the selected skill to
-load with your next message.
-
-You can also name skills explicitly in a prompt, which is convenient for copied
-prompts and non-interactive use:
-
-```text
-Load phx-investigate and investigate this LiveView filter reset.
-```
-
-Exact Claude-style entries such as `/phx:review` are not registered as Amp slash
-commands; Amp uses its command palette and native skill invocation instead. Amp
-may also select skills automatically from their descriptions, but automatic
-selection is model-driven and is not guaranteed on every prompt. The Amp
-edition ships skills, their bundled resources, and the focused `phx-watch-pr`
-lifecycle plugin—not the Claude-specific hooks, custom agents, permission
-settings, or MCP setup. Read the complete
-[Amp installation and usage guide](docs/amp.md) for verification, updates,
-skill precedence, examples, troubleshooting, and the portability matrix.
+It holds a bounded Orb keep-alive lease, filters deployment-like checks out of
+readiness, persists reload-safe state, and wakes the same worker thread only for
+failed/cancelled required CI, unresolved feedback, and terminal outcomes. With
+`--fix`, actionable feedback and branch-owned CI failures are repaired in one
+serialized same-thread workflow. It never blindly reruns shared CI, merges, or
+deploys.
 
 ### Use with Codex
 
@@ -393,10 +389,12 @@ updates, uninstall, feature-branch review, discovery debugging, and limitations.
 
 The remainder of this README describes the full Claude Code plugin and uses
 Claude Code `/phx:*`, `/ecto:*`, and `/lv:*` syntax. For generated runtimes,
-translate invocations using the runtime guide: Amp uses `skill: invoke`, Codex
-uses `$elixir-phoenix:<skill>`, Pi uses `/skill:<name>`, and OpenCode uses its
-skill tool. Generated editions do not install Claude Code's complete custom
-agent, lifecycle-hook, permission, or MCP configuration.
+translate invocations using the runtime guide: Amp natively uses
+`skill: invoke` and paired-full also provides generated entries such as
+`phx: investigate`; Codex uses
+`$elixir-phoenix:<skill>`, Pi uses `/skill:<name>`, and OpenCode uses its skill
+tool. Generated editions do not install Claude Code's complete custom agent,
+lifecycle-hook, permission, or MCP configuration.
 
 New to the plugin? Run the interactive tutorial: