@event4u/agent-config 1.13.0 → 1.15.0

package/README.md

@@ -1,11 +1,13 @@
 # Agent Config — Governed Agent System
 
+> **agent-config is not a runtime, but it ships a deterministic orchestration contract / state machine for host agents.**
+
 Teach your AI agents Laravel, PHP, testing, Git workflows, and **120+ more skills** — with quality guardrails built in.
 
 > Your agent learns to write Laravel code, run tests, create PRs, fix CI — and follows your team's coding standards while doing it.
 
 <p align="center">
-  <strong>124 Skills</strong> · <strong>46 Rules</strong> · <strong>73 Commands</strong> · <strong>46 Guidelines</strong> · <strong>8 AI Tools</strong>
+  <strong>128 Skills</strong> · <strong>55 Rules</strong> · <strong>77 Commands</strong> · <strong>46 Guidelines</strong> · <strong>8 AI Tools</strong>
 </p>
 
 ---
@@ -69,7 +71,8 @@ Install directly in your agent for global, cross-project use:
 2. `"Add caching to this"` → watch: agent asks instead of guessing
 3. `"Implement this feature"` → watch: agent respects your codebase
 
-→ [Full getting started guide](docs/getting-started.md)
+→ [Full getting started guide](docs/getting-started.md) ·
+[More examples & expected behavior](docs/showcase.md)
 
 ### Optional: persistent agent memory
 
@@ -90,7 +93,7 @@ Install in the same project (dev-only):
 npm install --save-dev @event4u/agent-memory
 ```
 
-→ [Memory contract & retrieval API](agents/contexts/agent-memory-contract.md)
+→ [Memory contract & retrieval API](docs/contracts/agent-memory-contract.md) (beta)
 
 ---
 
@@ -128,7 +131,69 @@ so you decide — never a silent guess. Persona comes from
 (plan-only, skips implementation).
 
 → [Command reference](.agent-src/commands/implement-ticket.md) ·
-  [Flow contract](agents/contexts/implement-ticket-flow.md)
+  [Flow contract](docs/contracts/implement-ticket-flow.md) (beta)
+
+### Sibling entrypoint: `/work` (free-form prompt)
+
+Same engine, different envelope. Use `/work` when you have a goal
+but no ticket yet:
+
+```
+/work add a CSV export endpoint to the audit-log controller
+```
+
+The first pass scores the prompt on five dimensions
+(`goal_clarity`, `scope_boundary`, `ac_evidence`, `stack_data`,
+`reversibility`) and routes on the resulting band:
+
+| Band | Score | Engine action |
+|---|---|---|
+| **high** | `≥ 0.8` | Silent proceed — reconstructed AC + assumptions land in the delivery report |
+| **medium** | `0.5–0.79` | Halts with assumptions report; you confirm or edit before plan |
+| **low** | `< 0.5` | Halts with **one** clarifying question on the weakest dimension |
+
+After the band gate releases, the rest of the flow is identical
+to `/implement-ticket`. UI-shaped prompts are routed through the
+**product UI track** — see below.
+
+→ [Command reference](.agent-src/commands/work.md) ·
+  [`refine-prompt` skill](.agent-src/skills/refine-prompt/SKILL.md) ·
+  [ADR](docs/contracts/adr-prompt-driven-execution.md)
+
+**Pick which one:** ticket id or pasted ticket payload → `/implement-ticket`.
+Free-form goal, no ticket → `/work`. The two share `.work-state.json`
+and refuse to switch envelopes mid-flight.
+
+### Product UI track
+
+UI-shaped work (build a screen, improve a component, fix microcopy)
+switches the engine to one of three directive sets:
+
+| `directive_set` | When | Flow |
+|---|---|---|
+| `ui` | Non-trivial UI surface | `audit → design → apply → review → polish → report` |
+| `ui-trivial` | Bounded edit (≤ 1 file, ≤ 5 changed lines) | `apply → test → report` |
+| `mixed` | Backend + UI | `contract → ui → stitch` |
+
+Four load-bearing properties: (1) **existing-UI audit is a hard gate** —
+no `apply` without audit, enforced at dispatcher AND
+[`ui-audit-before-build`](.agent-src/rules/ui-audit-before-build.md) rule;
+(2) **design brief is locked microcopy** — placeholders (`<placeholder>`,
+`Lorem`, `TODO:`) rejected at both ends; (3) **polish has a 2-round
+ceiling**, then halts ship-as-is / abort / hand-off; (4) **a11y precedence**
+— unresolved axe-core / pa11y violations must be fixed or explicitly
+accepted before ship, regardless of round counter (one-shot extension
+allowed). The engine never renders UI itself: rendering happens
+out-of-process, the engine consumes a `preview_envelope` (status /
+screenshots / findings) via a defined contract. Stack detection routes
+(`composer.json` + `package.json`) to `blade-livewire-flux` /
+`react-shadcn` / `vue` / `plain`; trivial path reclassifies loudly when
+preconditions fail. Halt budget on the happy path is 2.
+
+→ [Mental model](docs/ui-track-mental-model.md) (1 page — when each set, where it stops, what the agent must never do) ·
+  [Flow contract](docs/contracts/ui-track-flow.md) (beta) ·
+  [ADR](docs/contracts/adr-product-ui-track.md) ·
+  [Stack-extension recipe](docs/contracts/ui-stack-extension.md) (beta)
 
 ---
 
@@ -190,16 +255,16 @@ Start with **Rules + Skills**. Everything else is optional.
 | Mode | What's active | Token overhead |
 |---|---|---|
 | **Minimal** (default) | Rules, Skills, Commands | Zero |
-| **Balanced** | + Runtime dispatcher for skills that declare a shell command | Low |
-| **Full** | + Tool adapters (GitHub / Jira read-only, opt-in) | Moderate |
+| **Balanced** | + Runtime Dispatcher for skills that declare a shell command | Low |
+| **Full** | + Tool Adapters (GitHub / Jira read-only, opt-in) | Moderate |
 
 Nothing runs automatically without your control. [Configure modes →](docs/customization.md)
 
-> **Experimental modules:** the runtime (dispatcher + shell handler) runs
-> two pilot skills in CI (`lint-skills`, `check-refs`). The tool registry
-> ships two read-only adapters (GitHub, Jira) behind the `full` profile.
-> Other handlers (`php`, `node`) are still scaffold. The `minimal`
-> profile — which most users should pick — is unaffected.
+> **Stability tiers** — [`STABILITY.md`](docs/contracts/STABILITY.md) for
+> the full matrix. Runtime Dispatcher: **stable** (`php` / `node` handlers
+> scaffold). Work Engine: **beta (beta)** — orchestrator behind `/work`
+> + `/implement-ticket`. Tool Adapters: **experimental**, read-only,
+> behind `full`. `minimal` profile unaffected.
 
 ---
 
@@ -259,7 +324,7 @@ can prioritize the right skills for extraction.
 | [`/jira-ticket`](.agent-src/commands/jira-ticket.md) | Read ticket from branch, implement feature |
 | [`/compress`](.agent-src/commands/compress.md) | Compress skills for token efficiency |
 
-→ [Browse all 73 commands](.agent-src/commands/)
+→ [Browse all 77 commands](.agent-src/commands/)
 
 ---
 
@@ -284,7 +349,7 @@ Every developer gets the same behavior. No per-user setup needed.
 native slash-commands)
 
 > **What this means in practice:** Augment Code and Claude Code get the full
-> package (rules + 124 skills + 73 native commands). Cursor, Cline, Windsurf,
+> package (rules + 128 skills + 77 native commands). Cursor, Cline, Windsurf,
 > Gemini CLI, and GitHub Copilot only get the **rules** natively; skills and
 > commands are available to them as documentation the agent can read, not as
 > first-class features.
@@ -303,6 +368,23 @@ Skills use a `SKILL.md` format with YAML frontmatter that is compatible with
 the [Agent Skills](https://agentskills.io) community spec and with Claude
 Code's Agent Skills specification.
 
+### Cloud / Hosted-agent surfaces (paste-in or upload)
+
+For platforms where the package's scripts cannot run, the package
+builds artefacts you upload or paste into the platform's own surface.
+
+| Surface | Output | How to install |
+|---|---|---|
+| **Linear AI** (Codegen, Charlie, …) | `dist/linear/{workspace,team,personal}.md` | [Install →](docs/installation.md#linear-ai-codegen-charlie-) |
+| **Claude.ai Web Skills** | `dist/cloud/<skill>.zip` | [Install →](docs/installation.md#claudeai-web-skills-ui) |
+
+The Linear digest is split into three layers — workspace (universal
+coding posture), team (framework-specific), personal (empty stub). See
+[`docs/contracts/linear-ai-three-layers.md`](docs/contracts/linear-ai-three-layers.md) (beta)
+for the rationale and
+[`docs/contracts/linear-ai-rules-inclusion.md`](docs/contracts/linear-ai-rules-inclusion.md) (beta)
+for the per-rule routing.
+
 ---
 
 ## Core Principles
@@ -325,12 +407,53 @@ Code's Agent Skills specification.
 | [**Development**](docs/development.md) | Prerequisites, editing workflow, all `task` commands, project structure |
 | [**Customization**](docs/customization.md) | Overrides, AGENTS.md, agent settings, cost profiles |
 | [**Quality & CI**](docs/quality.md) | Linting, CI pipeline, compression system |
+| [**Migration**](docs/MIGRATION.md) | Per-version upgrade steps (e.g. `implement_ticket → work_engine` in 1.15.0) |
 
 Uninstalling: see
 [docs/installation.md#uninstalling](docs/installation.md#uninstalling) —
 there is no dedicated uninstall command; removal is a documented manual
 step (package manager + `rm -rf` of generated dirs).
 
+### Maintainer telemetry (opt-in, default-off)
+
+A local-only artefact-engagement log can be enabled by maintainers to see
+which skills, rules, commands, and guidelines the agent actually consults
+and applies during a `/implement-ticket` or `/work` run. The log is a
+JSONL file under the project root; nothing is uploaded, nothing is shared
+across projects. Default is off; consumers see no prompts.
+
+```yaml
+# .agent-settings.yml — opt in only when you want measurement
+telemetry:
+  artifact_engagement:
+    enabled: true
+```
+
+Reports: `./agent-config telemetry:report`. Full contract,
+privacy/redaction floor, and quartile semantics:
+[`docs/contracts/artifact-engagement-flow.md`](docs/contracts/artifact-engagement-flow.md) (beta).
+
+### Context-aware command suggestion
+
+When a user prompt matches a command's purpose ("setze ticket ABC-123 um"
+→ `/implement-ticket`), the agent surfaces matches as a numbered-options
+block with an always-present "run the prompt as-is" escape. **Nothing
+auto-executes** — the user picks every time. Three opt-out paths:
+
+```yaml
+# .agent-settings.yml
+commands:
+  suggestion:
+    enabled: true            # global on/off
+    blocklist: []            # specific commands never suggested
+    confidence_floor: 0.6    # tunable per command in frontmatter
+```
+
+Per-conversation: `/command-suggestion-off` disables the layer until
+re-enabled or the chat ends. Full scoring contract and hardening:
+[`adr-command-suggestion`](docs/contracts/adr-command-suggestion.md),
+[`command-suggestion-flow`](docs/contracts/command-suggestion-flow.md) (beta).
+
 ---
 
 ## Development
@@ -371,7 +494,6 @@ task lint-skills   # Lint skills, rules, commands
 **For contributors only** (rebuilding `.augment/` locally):
 
 - [Task](https://taskfile.dev/) — runs the CI pipeline (`task ci`).
-- No runtime dependencies — the package ships static markdown files.
 
 ## License
 

package/config/agent-settings.template.yml

@@ -46,6 +46,15 @@ personal:
   # Personal preference — each developer decides for themselves.
   pr_comment_bot_icon: false
 
+  # Autonomous execution — suppress trivial workflow questions (on, off, auto)
+  # on   = act on the obvious next step; never ask "Step 2 or 3?", "should I commit?", etc.
+  # off  = ask trivial workflow questions (legacy behavior)
+  # auto = behaves like 'off' until the user says "arbeite selbstständig" / "work autonomously"
+  #        in the conversation, then switches to 'on' for the rest of the chat.
+  # Blocking decisions (security, scope expansion, push/merge/branch/PR) are NEVER suppressed.
+  # See rules/autonomous-execution.md for the full definition.
+  autonomy: auto
+
 # --- Project / team preferences ---
 project:
   # Path to the PR template file (relative to project root)
@@ -96,6 +105,13 @@ chat_history:
   #   compress = mark for summarization on the next agent turn
   on_overflow: __CHAT_HISTORY_ON_OVERFLOW__
 
+  # Heartbeat marker visibility (token-cost knob)
+  #   on     = print the 📒 marker every reply (~20 tokens/reply, legacy)
+  #   off    = never print (zero tokens, drift only visible by reading the file)
+  #   hybrid = print only on drift states (missing/foreign/returning); silent otherwise
+  # YAML 1.1 booleanizes bare on/off — both are accepted, no quoting needed.
+  heartbeat: hybrid
+
 # --- Optional pipelines ---
 pipelines:
   # Skill improvement pipeline (true, false)
@@ -133,3 +149,32 @@ onboarding:
   # Set to true automatically by /onboard at the end. Flip to false if
   # you want to re-run the flow.
   onboarded: false
+
+# --- Command suggestion (numbered-options shortcut finder) ---
+#
+# When the user's free-form prompt matches an eligible slash command,
+# the agent surfaces a numbered-options block with the recommendation
+# plus an always-present "run as-is" option. The suggestion layer
+# never auto-executes — the user picks. See rules/command-suggestion.md.
+commands:
+  suggestion:
+    # Master switch (true, false). false = the layer is silent; explicit
+    # /commands still work as today.
+    enabled: true
+
+    # Minimum match score (0.0–1.0) before a suggestion surfaces.
+    # 0.6 = default; raise to 0.7 for stricter behaviour, lower to 0.5
+    # if too many useful suggestions are being suppressed.
+    confidence_floor: 0.6
+
+    # Cooldown in seconds between re-suggestions of the same
+    # (command, evidence) pair. Default 600s = 10m.
+    cooldown_seconds: 600
+
+    # Max number of command suggestions before the as-is option.
+    # The as-is option is always extra (so total = max_options + 1).
+    max_options: 4
+
+    # Commands to never suggest. Still work when typed explicitly.
+    # Example: ["/refine-ticket", "/work"]
+    blocklist: []

package/config/gitignore-block.txt

@@ -22,3 +22,7 @@
 .agent-chat-history
 .agent-chat-history.bak
 .agent-chat-history.*.bak
+
+# Agent config — artefact engagement telemetry (default-off, maintainer-only, never commit)
+.agent-engagement.jsonl
+.agent-engagement.jsonl.bak

package/docs/MIGRATION.md

@@ -0,0 +1,122 @@
+# Migration Guide
+
+How to move existing checkouts forward when `event4u/agent-config`
+ships breaking layout changes. Each section is self-contained: read
+only the version you are upgrading to.
+
+> Symbol legend — 🔄 automatic, ✋ manual, 💡 advisory.
+
+## 1.14.x → 1.15.0 — `implement_ticket` → `work_engine`
+
+1.15.0 finishes the rename started with PR #29: the orchestration
+package is now `work_engine` and the default state file is
+`.work-state.json`. A back-compat shim keeps `implement_ticket`
+imports working for one minor release; the legacy state filename is
+detected on load and surfaces a one-shot migration hint instead of
+failing silently.
+
+### What changed
+
+| Surface | 1.14.x | 1.15.0 |
+|---|---|---|
+| Orchestration package | `implement_ticket/` | `work_engine/` |
+| Default state file | `.implement-ticket-state.json` | `.work-state.json` |
+| Legacy package import | native | thin shim, removed in 1.16.0 |
+| State schema | v0 (flat `ticket`) | v1 (`input.kind` envelope) |
+
+The schema migration itself shipped in 1.14.0 (`migrate_payload`
+already wraps v0 → v1). 1.15.0 only flips the *default* output
+filename and the shipped package name; v0 files on disk are still
+recognised on a clear error path.
+
+### Required action
+
+✋ **Run the one-shot migration** if your project still has a
+`.implement-ticket-state.json` file:
+
+```bash
+python3 -m work_engine.migration.v0_to_v1 .implement-ticket-state.json
+```
+
+This:
+
+1. Writes `.work-state.json` with the v1 envelope alongside the
+   legacy file.
+2. Rotates the v0 file to `.implement-ticket-state.json.bak` (or
+   `.bak.1`, `.bak.2`, … if a previous backup is already present —
+   no silent overwrites).
+3. Refuses to overwrite an existing `.work-state.json`.
+4. Exits `0` on success, `2` on schema errors.
+
+Pass `--no-backup` if you do not want the v0 file kept around, or
+`--destination <path>` for a custom location.
+
+🔄 **Detection on load.** If the engine is invoked with
+`--state-file .work-state.json` (or no `--state-file` at all) and
+finds only the legacy file, it stops with:
+
+```
+error: Found legacy state file .implement-ticket-state.json but no
+.work-state.json. The default state file was renamed in 1.15.0. Run
+`python3 -m work_engine.migration.v0_to_v1 .implement-ticket-state.json`
+to migrate, or pass `--state-file .implement-ticket-state.json` to
+keep using the old name. See docs/MIGRATION.md.
+```
+
+The detection only fires when the requested state file uses the
+canonical name; explicit `--state-file <other>.json` bypasses it,
+so power users with their own naming scheme stay in control.
+
+### Optional — keep using the legacy name
+
+💡 You do **not** have to migrate immediately. Both of these keep
+working through the 1.15.x cycle:
+
+- Pass `--state-file .implement-ticket-state.json` on every CLI
+  invocation. The loader reads v0 and v1 transparently; format is
+  preserved on save.
+- Keep importing from `implement_ticket` — the shim under
+  `templates/scripts/implement_ticket/` re-exports the
+  `work_engine` API verbatim. Removed in 1.16.0.
+
+The legacy hint is a UX nudge, not a hard cutover.
+
+### Rolling back
+
+If something goes wrong:
+
+```bash
+mv .work-state.json /tmp/work-state-bad.json
+mv .implement-ticket-state.json.bak .implement-ticket-state.json
+```
+
+Then either re-run the migration or pin to 1.14.x until the issue
+is reported. The v0 backup is byte-equal with the input —
+`migrate_file` only renames the source after successfully writing
+the v1 destination.
+
+### CI / repository hygiene
+
+If your project commits state files (uncommon but supported):
+
+- Update `.gitignore` to exclude both `.implement-ticket-state.json`
+  and `.work-state.json` if you want them transient.
+- Otherwise, commit the new `.work-state.json` and either delete
+  the `.bak` rotation or move it under an archive path — the
+  loader never reads `.bak` files.
+
+### Reference
+
+- Schema and field-by-field semantics:
+  [`docs/contracts/implement-ticket-flow.md`](contracts/implement-ticket-flow.md#workstate-v1-schema).
+- Stability level: `work_engine` is **beta** — see
+  [`docs/contracts/STABILITY.md`](contracts/STABILITY.md).
+- Source of truth for the migrator:
+  [`templates/scripts/work_engine/migration/v0_to_v1.py`](../.agent-src.uncompressed/templates/scripts/work_engine/migration/v0_to_v1.py).
+
+## Older versions
+
+No formal migration was required before 1.15.0. The pre-1.14.0 v0
+state schema (flat `ticket`, `.implement-ticket-state.json`) is
+documented in `docs/contracts/implement-ticket-flow.md` and is
+covered by the same `v0_to_v1` migrator above.

package/docs/architecture.md

@@ -1,17 +1,22 @@
 # Architecture
 
+> **agent-config is not a runtime, but it ships a deterministic orchestration contract / state machine for host agents.**
+
 ## System overview
 
 ```
-Rules         → Behavior enforcement (always active)         ← stable
-Skills        → Execution logic (on-demand expertise)        ← stable
-Runtime       → Dispatcher + shell handler (pilot skills)    ← partial
-Tools         → External integrations (GitHub, Jira)         ← experimental
+Rules               → Behavior enforcement (always active)              ← stable
+Skills              → Execution logic (on-demand expertise)             ← stable
+Runtime Dispatcher  → Single-skill shell execution (pilot skills)       ← stable (mechanism)
+Work Engine         → Multi-step orchestration for /work + /implement   ← beta
+Tool Adapters       → External integrations (GitHub, Jira)              ← experimental
 ```
 
-**Stable** = shipped, documented, exercised by the default (`minimal`) profile.
-**Experimental** = scaffold with tests and data model, but no real execution
-wired up yet.
+Stability tiers follow [`docs/contracts/STABILITY.md`](contracts/STABILITY.md):
+
+- **stable** = shipped, documented, exercised by the default (`minimal`) profile or by CI on every PR; SemVer-major for breaks.
+- **beta** = shipped and load-bearing for one or more flows, but the surface is expected to evolve; minor-version breaks allowed under a `### Breaking` CHANGELOG note.
+- **experimental** = scaffold or pilot status; breaks allowed in any release.
 
 > The previous "observability, feedback, lifecycle" layers were removed in
 > 1.5 — they were scaffolds without production consumers. See the
@@ -29,16 +34,40 @@ wired up yet.
     ↓ install.sh (Cursor, Cline, Windsurf, Augment VSCode) / plugin system
 .claude/ .cursor/ .clinerules/  ← Tool-specific symlinks/copies (auto-generated)
 .windsurfrules  GEMINI.md
+    ↓ scripts/build_cloud_bundle.py    (Phase 1 — cloud distribution)
+dist/cloud/<skill>.zip          ← Anthropic Skills bundles (Claude.ai Web / Skills API)
 ```
 
+### Cloud-bundle pipeline
+
+`task build-cloud-bundles-all` produces one ZIP per skill at
+`dist/cloud/<skill>.zip`, ready for upload to Claude.ai Web (Settings →
+Customize → Skills) or the Anthropic Skills API. Per-skill behavior
+follows the cloud-tier classification from `scripts/audit_cloud_compatibility.py`:
+
+| Tier  | Bundle action                                                     |
+|-------|-------------------------------------------------------------------|
+| T1    | Bundle as-is — pure guidance, sandbox-safe                        |
+| T2    | Bundle with prepended sandbox note + package-internal path-swap   |
+| T3-S  | Same as T2; optional script calls degrade gracefully on cloud     |
+| T3-H  | **Skipped** — Phase 2 cloud-aware variant required before bundling |
+
+Cloud-side caps enforced by the builder: `description` ≤ 200 chars
+(Claude.ai Web) with a 1024-char hard cap (Anthropic spec). The sandbox
+note explains to the agent that `.agent-src/`, `agents/`, and `task …`
+references are descriptive — the host has no filesystem access.
+
+CI gate: `task ci-cloud-bundle` runs the builder in `--check` mode and
+fails on any source-side violation, without producing artifacts.
+
 ## What's inside
 
 | Layer | Count | Purpose |
 |---|---|---|
-| **Skills** | 93 | On-demand expertise — Laravel, testing, Docker, API design, security, ... |
-| **Rules** | 31 | Always-active constraints — coding standards, scope control, verification |
-| **Commands** | 51 | Slash-command workflows — `/commit`, `/create-pr`, `/fix-ci`, `/compress`, ... |
-| **Guidelines** | 34 | Coding guidelines by language — PHP patterns, Eloquent, Playwright, ... |
+| **Skills** | 128 | On-demand expertise — Laravel, testing, Docker, API design, security, ... |
+| **Rules** | 55 | Always-active constraints — coding standards, scope control, verification |
+| **Commands** | 77 | Slash-command workflows — `/commit`, `/create-pr`, `/fix-ci`, `/compress`, ... |
+| **Guidelines** | 46 | Coding guidelines by language — PHP patterns, Eloquent, Playwright, ... |
 | **Templates** | 7 | Scaffolds for features, roadmaps, contexts, skills, overrides |
 | **Contexts** | 5 | Shared knowledge about the system itself |
 
@@ -55,18 +84,25 @@ wired up yet.
 
 Ensures: no guessing, analysis before action, real verification, consistent outputs.
 
-### 2. Execution Layer (Runtime) — partially real, partially scaffold
+### 2. Runtime Dispatcher — stable mechanism, pilot coverage
+
+> **Scope:** single-skill execution. Resolves a `SKILL.md` with
+> `execution.command` argv, enforces safety constraints, hands off to
+> the matching handler. **Not** a multi-step orchestrator — that is
+> the Work Engine (next section).
 
 > **Status:**
-> - **Real:** shell-handler path — skills that declare an `execution.command`
->   argv are dispatched and executed by `scripts/runtime_handler.py`. A typed
->   `ExecutionResult` (exit code, stdout, stderr, duration, artifacts) is
->   returned and can be persisted as JSON via `--output FILE`. Pilots:
->   `lint-skills`, `check-refs`. Both run on every PR and appear in the
->   GitHub Step Summary via `scripts/ci_summary.py`.
-> - **Scaffold:** `php` and `node` handlers — the frontmatter accepts them
->   and the registry validates them, but no handler implementation exists
->   yet.
+> - **Stable mechanism:** the dispatcher itself
+>   (`scripts/runtime_dispatcher.py`), the shell handler
+>   (`scripts/runtime_handler.py`), and the `ExecutionResult` shape.
+>   `subprocess.run` is invoked with `shell=False` (argv only); the
+>   environment is scrubbed to an explicit allowlist.
+> - **Pilot coverage:** two skills ship as live pilots —
+>   `lint-skills` and `check-refs` — both run on every PR and appear
+>   in the GitHub Step Summary via `scripts/ci_summary.py`.
+> - **Scaffold:** `php` and `node` handlers — the frontmatter accepts
+>   them and the registry validates them, but no handler
+>   implementation exists yet.
 
 Skills opt into runtime by declaring execution metadata:
 
@@ -89,14 +125,49 @@ Invoke a runtime-capable skill end-to-end:
 python3 scripts/runtime_dispatcher.py run --skill lint-skills
 ```
 
-The dispatcher resolves the skill, enforces safety constraints, then hands
-off to the matching handler. Environment is scrubbed to an explicit
-allowlist; `subprocess.run` is invoked with `shell=False` (argv only).
-
-Planned scope (still to come): `php` / `node` handlers, tool-registry
-wiring for `allowed_tools`, streaming output.
-
-### 3. Tool Integration — experimental
+A typed `ExecutionResult` (exit code, stdout, stderr, duration,
+artifacts) is returned and can be persisted as JSON via
+`--output FILE`.
+
+Planned scope: `php` / `node` handlers, tool-registry wiring for
+`allowed_tools`, streaming output.
+
+### 3. Work Engine — beta, multi-step orchestration
+
+> **Scope:** multi-step phase dispatch for `/work` and
+> `/implement-ticket`. Drives the
+> `refine → score → plan → implement → test → verify → report` loop,
+> persists state in `.work-state.json`, and routes UI-shaped work
+> through the product UI track. Lives at
+> [`templates/scripts/work_engine/`](../.agent-src.uncompressed/templates/scripts/work_engine/);
+> shipped to consumer projects via `scripts/install.py`.
+
+> **Status: beta.** The contract (directive sets, halt budgets,
+> envelope shape) has shipped one full SemVer-minor cycle, but the
+> surface is still expected to evolve. Breaks are allowed in
+> minor-version releases under a `### Breaking` CHANGELOG note. See
+> [`docs/contracts/STABILITY.md`](contracts/STABILITY.md).
+
+Key responsibilities:
+
+- **Directive routing** — `ui` / `ui-trivial` / `mixed` directive
+  sets, locked into the contract at
+  [`adr-product-ui-track.md`](contracts/adr-product-ui-track.md) (beta).
+- **Halt protocol** — every phase emits a structured halt; the
+  agent re-enters with the user's answer, never improvises.
+- **State machine** — `.work-state.json` is the single source of
+  truth across resumes; the engine refuses to switch envelope
+  mid-flight. Legacy `.implement-ticket-state.json` files are
+  detected on load and routed through
+  [`docs/MIGRATION.md`](MIGRATION.md).
+- **Hooks** — chat-history, telemetry, and platform hooks fire
+  through the engine's hook layer.
+
+The Work Engine **uses** the Runtime Dispatcher when a phase needs
+to execute a single skill (e.g. lint, refs check), but the two are
+independent components with separate stability tiers.
+
+### 4. Tool Adapters — experimental
 
 > **Status: scaffold + read-only GitHub calls.** With a `GITHUB_TOKEN` the
 > GitHub adapter performs real read calls; without one it returns scaffold
@@ -110,14 +181,16 @@ Controlled integration via adapters:
 - Tool registry with safety rules for execution
 - Structured responses with error classification
 
-### 4. Cost Control
+### 5. Cost Control
 
 > **Key principle:** Opt-in by default.
 
-The dispatcher and tool adapters activate only under the `balanced` or
-`full` profile. The default `minimal` profile ships rules, skills, and
-commands and nothing else. All settings and their profile defaults are
-documented in
+The Runtime Dispatcher and Tool Adapters activate only under the
+`balanced` or `full` profile. The Work Engine activates whenever
+`/work` or `/implement-ticket` is invoked and is independent of the
+cost profile. The default `minimal` profile ships rules, skills, and
+commands and nothing else. All settings and their profile defaults
+are documented in
 [`.agent-src.uncompressed/templates/agent-settings.md`](../.agent-src.uncompressed/templates/agent-settings.md).
 
 ---
@@ -134,10 +207,13 @@ documented in
 | **Cline** | ✅ | — | — | — | install.sh (symlinks) |
 | **Windsurf** | ✅ | — | — | — | install.sh (concatenated) |
 | **Gemini CLI** | ✅ | — | — | — | install.sh (symlink → AGENTS.md) |
+| **Claude.ai Web / Skills API** | — | ✅ | — | — | `task build-cloud-bundles-all` → `dist/cloud/<skill>.zip` |
 
 Skills use a `SKILL.md` format with YAML frontmatter, compatible with the
 [Agent Skills](https://agentskills.io) community spec and with Claude Code's
-Agent Skills specification.
+Agent Skills specification. Cloud bundles produced by
+`scripts/build_cloud_bundle.py` follow the same format with cloud-side
+adjustments (description budget, sandbox note, package-internal path-swap).
 
 ---