feat(amp): add deterministic native workflows (#132)

* feat(amp): add deterministic native workflows

Generate a complete Amp target with explicit palette commands, read-only
specialists, bounded parallel analysis, and lifecycle guards. Keep the source
target byte-identical to the validated standalone distribution and cover the
runtime policies with model-free tests and smoke checks.

Co-authored-by: Oliver Kriska <oliver@ideax.sk>

* fix(amp): align hosted profiles and local resolution

Amp-Thread-ID: https://ampcode.com/threads/T-019ff034-17cd-735a-900c-f8ac5252b8f4

* fix(amp): fit hosted plugin transport

Amp-Thread-ID: https://ampcode.com/threads/T-019ff034-17cd-735a-900c-f8ac5252b8f4

* fix(amp): generate both Amp plugins from one target build

main added a second, hand-written Amp plugin (phx-watch-pr.ts, copied
verbatim and byte-checked against its canonical source) while this branch
added a first one (elixir-phoenix.ts, rendered from Python so it can embed
projected agent bodies and skill metadata). Both landed on the same
build_target(), the same validate_plugin(), the same OUTPUT_DIR, and the
same snapshot digest.

Neither generation style can replace the other: the workflow plugin has to
be rendered because it inlines canonical content, and the watch plugin has
to be copied because it is real TypeScript with no projected data. So the
target now emits both.

- validate_plugin() keeps main's signature and meaning (watch plugin,
  byte-identity against source). The rendered one becomes
  validate_workflow_plugin(), and PLUGIN_RELATIVE_PATH becomes
  WORKFLOW_PLUGIN_RELATIVE_PATH, so main's committed API is untouched and
  the rename stays confined to the incoming branch.
- build_target() discovers specialists, copies the watch plugin, renders
  the workflow plugin, and returns skills + commands + plugins.
- The runtime smoke test now execs both plugins: session.start for
  phx-watch-pr, agent.start for elixir-phoenix.
- Docs and the runtime-support matrix describe two plugins rather than
  one, keeping both sides' capability rows.

The transport budget needed the whole branch to land: after commit 1 the
rendered plugin hit 98,745 bytes against its own 96,000 assert, because
phx-watch-pr joined PORTABLE_WORKFLOWS and the shared specialist contract
was still inlined five times. Commit 3's compaction brings it to 95,191
with 809 bytes of headroom.

---------

Co-authored-by: Amp <amp@ampcode.com>

Author: oliver-kriska

.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: