@event4u/agent-config 1.14.0 → 1.16.0

package/README.md

@@ -1,11 +1,13 @@
 # Agent Config — Governed Agent System
 
-Teach your AI agents Laravel, PHP, testing, Git workflows, and **120+ more skills** — with quality guardrails built in.
+> **agent-config is not a runtime, but it ships a deterministic orchestration contract / state machine for host agents.**
 
-> Your agent learns to write Laravel code, run tests, create PRs, fix CI — and follows your team's coding standards while doing it.
+Give your AI agents an audit-disciplined orchestration contract — testing, Git, CI, code review, and **120+ stack-aware skills** — with quality guardrails built in.
+
+> Your agent picks up the project's stack, runs tests, prepares PRs, fixes CI — and follows your team's coding standards while doing it. Stack-aware skill sets ship for PHP (Laravel · Symfony · Zend/Laminas), JavaScript (Next.js · React · Node), and cross-stack concerns (API · testing · security · observability).
 
 <p align="center">
-  <strong>128 Skills</strong> · <strong>53 Rules</strong> · <strong>77 Commands</strong> · <strong>46 Guidelines</strong> · <strong>8 AI Tools</strong>
+  <strong>129 Skills</strong> · <strong>57 Rules</strong> · <strong>69 Commands</strong> · <strong>47 Guidelines</strong> · <strong>8 AI Tools</strong>
 </p>
 
 ---
@@ -91,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)
 
 ---
 
@@ -129,7 +131,7 @@ 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)
 
@@ -156,7 +158,7 @@ to `/implement-ticket`. UI-shaped prompts are routed through the
 
 → [Command reference](.agent-src/commands/work.md) ·
   [`refine-prompt` skill](.agent-src/skills/refine-prompt/SKILL.md) ·
-  [ADR](agents/contexts/adr-prompt-driven-execution.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`
@@ -175,7 +177,7 @@ switches the engine to one of three directive sets:
 
 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;
+[`ui-audit-gate`](.agent-src/rules/ui-audit-gate.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**
@@ -188,9 +190,10 @@ screenshots / findings) via a defined contract. Stack detection routes
 `react-shadcn` / `vue` / `plain`; trivial path reclassifies loudly when
 preconditions fail. Halt budget on the happy path is 2.
 
-→ [Flow contract](agents/contexts/ui-track-flow.md) ·
-  [ADR](agents/contexts/adr-product-ui-track.md) ·
-  [Stack-extension recipe](agents/contexts/ui-stack-extension.md)
+→ [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)
 
 ---
 
@@ -203,11 +206,11 @@ description of intent — not a guarantee of output.
 | Default behavior | With agent-config (the agent is instructed to) |
 |---|---|
 | Guess and edit blindly | Analyze code before changing it — no blind edits |
-| Drift from project conventions | Follow the project's PHP/Laravel coding standards |
-| Skip or invent tests | Write Pest tests following the project's conventions |
-| Write generic commit messages | Use Conventional Commits with scope and Jira links |
-| Skip quality checks | Run PHPStan, Rector, ECS and fix reported errors |
-| Open PRs without context | Produce structured PR descriptions from Jira tickets |
+| Drift from project conventions | Follow the project's coding standards (detected from the stack) |
+| Skip or invent tests | Write tests in the project's framework (Pest, PHPUnit, Vitest, Jest, …) |
+| Write generic commit messages | Use Conventional Commits with scope and ticket links |
+| Skip quality checks | Run the project's quality pipeline (PHPStan/Rector/ECS, ESLint/Prettier/tsc, …) and fix reported errors |
+| Open PRs without context | Produce structured PR descriptions from Jira / Linear / GitHub tickets |
 | Claim "done" without proof | Verify with real execution before claiming "done" |
 
 ---
@@ -249,39 +252,35 @@ session is explicitly not.
 
 Start with **Rules + Skills**. Everything else is optional.
 
-| Mode | What's active | Token overhead |
+| Mode | What's active | Runtime process 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 |
+| **Minimal** (default) | Rules, Skills, Commands | None |
+| **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.
 
 ---
 
 ## Who this is for
 
-The content is **built for PHP / Laravel teams** and is where the package
-is most useful out of the box. Skills, rules, and quality-tool integration
-assume a Laravel-style repository (Pest, PHPStan, Rector, ECS, Artisan,
-Composer workflows). You can install it on any project, but:
+`agent-config` ships a **stack-agnostic governance core** (orchestration contract, role modes, command clusters, quality gates, audit-discipline) plus **parallel stack-specific skill sets** at varying depth:
 
-| Stack | Fit |
+| Stack | Coverage |
 |---|---|
-| **Laravel / modern PHP** | ✅ Primary audience — most skills apply directly |
-| **Other PHP frameworks** (Symfony, Zend/Laminas) | ☑️ Deep-analysis skills apply; framework-specific ones do not |
-| **JavaScript / TypeScript / Next.js / Node** | ☑️ General skills + governance apply; PHP-specific skills are noise |
-| **Other stacks** | ⚠️ Cherry-pick rules/commands; expect to disable a lot |
+| Laravel · modern PHP | Skills, rules, project-analysis, quality-tool wiring (Pest · PHPStan · Rector · ECS) |
+| Symfony · Zend / Laminas | Project-analysis skills + shared PHP coder/quality skills |
+| Next.js · React · Node / Express | Project-analysis skills + UI directive set (`react-shadcn`) |
+| Vue · plain HTML | UI directive set (`vue` / `plain`) — analysis skills as they ship |
+| Cross-stack | API design · testing · security · database · Docker · Git · CI · review · threat modeling · observability |
 
-A language-agnostic core is on the roadmap but not yet extracted. If you
-adopt the package outside the primary audience, please open an issue so we
-can prioritize the right skills for extraction.
+**Deepest reference stack today: Laravel.** Skill density covers Pest, PHPStan, Rector, Eloquent, Livewire/Flux, Horizon, Pulse, Reverb, Pennant — the stack the package was first proven on. Other stacks ship in the order they are battle-tested, not second-class. Adopting on a thin stack? Open an issue so we can prioritize the right skills for extraction.
 
 ---
 
@@ -294,8 +293,8 @@ can prioritize the right skills for extraction.
 | [`eloquent`](.agent-src/skills/eloquent/SKILL.md) | Eloquent models, relationships, scopes, eager loading, type safety |
 | [`create-pr`](.agent-src/commands/create-pr.md) | Create GitHub PRs with structured descriptions from Jira tickets |
 | [`commit`](.agent-src/commands/commit.md) | Stage and commit changes following Conventional Commits |
-| [`fix-ci`](.agent-src/commands/fix-ci.md) | Fetch CI errors from GitHub Actions and fix them |
-| [`fix-pr-comments`](.agent-src/commands/fix-pr-comments.md) | Fix and reply to all open review comments on a PR |
+| [`/fix ci`](.agent-src/commands/fix.md) | Fetch CI errors from GitHub Actions and fix them |
+| [`/fix pr-comments`](.agent-src/commands/fix.md) | Fix and reply to all open review comments on a PR |
 | [`quality-fix`](.agent-src/commands/quality-fix.md) | Run PHPStan/Rector/ECS and fix all errors |
 | [`bug-analyzer`](.agent-src/skills/bug-analyzer/SKILL.md) | Root cause analysis from Sentry errors or Jira tickets |
 | [`improve-before-implement`](.agent-src/rules/improve-before-implement.md) | Challenge weak requirements before coding |
@@ -304,7 +303,7 @@ can prioritize the right skills for extraction.
 | [`api-design`](.agent-src/skills/api-design/SKILL.md) | REST conventions, versioning, deprecation |
 | [`database`](.agent-src/skills/database/SKILL.md) | MariaDB optimization, indexing, query performance |
 
-→ [Browse all skills](docs/skills-catalog.md) · [llms.txt](llms.txt)
+→ [Public catalog](docs/catalog.md) (all rules, skills, commands, guidelines) · [Skills only](docs/skills-catalog.md) · [llms.txt](llms.txt)
 
 ---
 
@@ -314,14 +313,16 @@ can prioritize the right skills for extraction.
 |---|---|
 | [`/commit`](.agent-src/commands/commit.md) | Stage and commit with Conventional Commits |
 | [`/create-pr`](.agent-src/commands/create-pr.md) | Create PR with Jira-linked description |
-| [`/fix-ci`](.agent-src/commands/fix-ci.md) | Fetch and fix GitHub Actions failures |
-| [`/fix-pr-comments`](.agent-src/commands/fix-pr-comments.md) | Fix and reply to review comments |
+| [`/fix ci`](.agent-src/commands/fix.md) | Fetch and fix GitHub Actions failures |
+| [`/fix pr-comments`](.agent-src/commands/fix.md) | Fix and reply to review comments |
+| [`/optimize skills`](.agent-src/commands/optimize.md) | Audit skills, find duplicates, run linter |
+| [`/feature plan`](.agent-src/commands/feature.md) | Interactively plan a feature |
 | [`/quality-fix`](.agent-src/commands/quality-fix.md) | Run and fix all quality checks |
 | [`/review-changes`](.agent-src/commands/review-changes.md) | Self-review before creating a PR |
 | [`/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 77 commands](.agent-src/commands/)
+→ [Browse all 69 active commands](.agent-src/commands/) &nbsp;<sub>(84 files total — 15 are deprecation shims that redirect to clustered commands)</sub>
 
 ---
 
@@ -346,7 +347,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 + 128 skills + 77 native commands). Cursor, Cline, Windsurf,
+> package (rules + 129 skills + 69 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.
@@ -377,9 +378,9 @@ builds artefacts you upload or paste into the platform's own surface.
 
 The Linear digest is split into three layers — workspace (universal
 coding posture), team (framework-specific), personal (empty stub). See
-[`agents/contexts/linear-ai-three-layers.md`](agents/contexts/linear-ai-three-layers.md)
+[`docs/contracts/linear-ai-three-layers.md`](docs/contracts/linear-ai-three-layers.md) (beta)
 for the rationale and
-[`agents/contexts/linear-ai-rules-inclusion.md`](agents/contexts/linear-ai-rules-inclusion.md)
+[`docs/contracts/linear-ai-rules-inclusion.md`](docs/contracts/linear-ai-rules-inclusion.md) (beta)
 for the per-rule routing.
 
 ---
@@ -404,6 +405,7 @@ for the per-rule routing.
 | [**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) —
@@ -427,7 +429,7 @@ telemetry:
 
 Reports: `./agent-config telemetry:report`. Full contract,
 privacy/redaction floor, and quartile semantics:
-[`agents/contexts/artifact-engagement-flow.md`](agents/contexts/artifact-engagement-flow.md).
+[`docs/contracts/artifact-engagement-flow.md`](docs/contracts/artifact-engagement-flow.md) (beta).
 
 ### Context-aware command suggestion
 
@@ -446,11 +448,9 @@ commands:
 ```
 
 Per-conversation: `/command-suggestion-off` disables the layer until
-the user re-enables or the chat ends. Full scoring contract and
-hardening list:
-[`agents/contexts/adr-command-suggestion.md`](agents/contexts/adr-command-suggestion.md)
-and
-[`agents/contexts/command-suggestion-flow.md`](agents/contexts/command-suggestion-flow.md).
+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).
 
 ---
 
@@ -492,7 +492,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

@@ -138,6 +138,63 @@ subagents:
   # Integer, default 3. Set to 1 to serialize. Hard cap enforced by runtime.
   max_parallel: 3
 
+# --- AI Council (external second-opinion network) ---
+#
+# When enabled, the /council command lets the agent poll independent
+# external models (OpenAI, Anthropic) for a neutral critique of a
+# roadmap, diff, prompt, or file set. Council members never see the
+# host agent's reasoning — only the artefact + a neutral system prompt.
+#
+# Tokens are NEVER stored here. They live in ~/.config/agent-config/
+# <provider>.key (mode 0600), installed via:
+#   bash scripts/install_anthropic_key.sh
+#   bash scripts/install_openai_key.sh
+#
+# Cost note: every consultation makes real, paid API calls. The
+# autonomy directive does NOT silently spend tokens — the /council
+# command always asks before invoking, even under autonomy: on.
+ai_council:
+  # Master switch (true, false). Default false — installing a key is
+  # not the same as wanting the agent to spend money on it.
+  enabled: false
+
+  # Default transport mode for every member (overridable per-member
+  # below, and per-invocation via `/council mode:<x>`).
+  #
+  #   api        = direct SDK call against the provider's API (billable).
+  #   manual     = copy-paste loop, user is the transport (free).
+  #   playwright = browser automation (Phase 2c, not yet wired).
+  #
+  # Precedence: invocation flag > per-member mode > global mode > "api".
+  mode: "api"
+
+  # Per-member configuration. Set enabled=true on the providers you want
+  # to consult. The model field selects which model receives the query.
+  # Optional `mode:` overrides the global setting for that member only.
+  members:
+    anthropic:
+      enabled: false
+      model: "claude-sonnet-4-5"
+      # mode: "api"      # uncomment to override ai_council.mode
+    openai:
+      enabled: false
+      model: "gpt-4o"
+      # mode: "manual"   # uncomment to override ai_council.mode
+
+  # Hard cost ceiling per /council invocation. The orchestrator pauses
+  # before any member whose projected spend would breach a cap and asks
+  # the user to continue. `max_total_usd: 0` disables the USD ceiling
+  # (token caps still apply).
+  #
+  # Prices come from `.agent-prices.md` (gitignored, refreshed weekly
+  # by `python3 scripts/update_prices.py`; bootstrapped from
+  # scripts/ai_council/_default_prices.py on first run).
+  cost_budget:
+    max_input_tokens: 50000
+    max_output_tokens: 20000
+    max_calls: 10
+    max_total_usd: 0.50
+
 # --- Onboarding ---
 #
 # Tracks whether the initial setup flow (/onboard) has been completed
@@ -155,7 +212,7 @@ onboarding:
 # 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.
+# never auto-executes — the user picks. See rules/command-suggestion-policy.md.
 commands:
   suggestion:
     # Master switch (true, false). false = the layer is silent; explicit

package/config/gitignore-block.txt

@@ -26,3 +26,6 @@
 # Agent config — artefact engagement telemetry (default-off, maintainer-only, never commit)
 .agent-engagement.jsonl
 .agent-engagement.jsonl.bak
+
+# Agent config — AI Council price table (refreshed weekly, never commit)
+.agent-prices.md

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
@@ -59,10 +64,10 @@ fails on any source-side violation, without producing artifacts.
 
 | 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** | 129 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
+| **Rules** | 57 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
+| **Commands** | 84 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
+| **Guidelines** | 47 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
 | **Templates** | 7 | Scaffolds for features, roadmaps, contexts, skills, overrides |
 | **Contexts** | 5 | Shared knowledge about the system itself |
 
@@ -79,18 +84,25 @@ fails on any source-side violation, without producing artifacts.
 
 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:
 
@@ -113,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
@@ -134,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).
 
 ---