release: 5.2.2 — front-door UX flow fixes (UX-P0-1/2/3) + version sync

UX-P0-1: README led with /atlas which a fresh plugin install doesn't provide
(commands are namespaced /prd:*). Add brand 'atlas' entrypoint skill (/prd:atlas
-> go) and fix README first-run.
UX-P0-2: rewrite setup/discover/generate/handoff entry gates — they documented a
STOP then told the agent to ignore it ('proceed past... see morning brief'). Now
explain check_gate is an EXIT gate; first-entry false is expected. Removed leaked
internal refs (morning brief, Mum dogfood feedback).
UX-P0-3: load_fleet_config now honors token_economy from .atlas-ai/config/atlas.json
(what /customise-workflow writes); fleet.json still wins. Schema doc updated.
Version hygiene: bump __init__.py (5.2.1 missed the source-of-truth).
334 tests green. See docs/audit/UX-FLOW-AUDIT.md.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: claude

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "prd",
-  "version": "5.2.1",
+  "version": "5.2.2",
   "description": "Zero-config goal-to-tasks engine for Claude Code (the Atlas engine). Graded PRD validation, dependency-ordered task graph, and CDD-verified execution.",
   "author": {
     "name": "Atlas AI",

CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to this project are documented here. Format based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.2.2] — 2026-06-14
+
+Front-door UX flow fixes (a UX-flow audit found the *journey* still broke before a
+new user reached the 5.2.1 backend fixes). See `docs/audit/UX-FLOW-AUDIT.md`. Also
+syncs the version source-of-truth (`prd_taskmaster/__init__.py`), which 5.2.1 missed.
+
+### Fixed
+- **UX-P0-1 — the README's first command now resolves.** `README` led with `/atlas`,
+  which a fresh `/plugin install prd` does not provide (plugin commands are namespaced
+  `/prd:*`). Added a brand-name `atlas` entrypoint skill (→ `/prd:atlas`, a thin alias
+  that dispatches to the `go` orchestrator) and updated the README first-run to
+  `/prd:atlas` (or `/prd:go`, or natural language).
+- **UX-P0-2 — phase gates no longer document a self-contradicting STOP.** `setup`/
+  `discover`/`generate`/`handoff` opened with "if the gate fails, stop" immediately
+  followed by "it WILL fail on first entry, proceed past it (see morning brief)" — a
+  compliant autonomous agent would halt. Rewritten to explain `check_gate` is an EXIT
+  gate (evidence to advance, not to enter), so a first-entry `false` is expected; the
+  gate is enforced on advance. Removed leaked internal references ("morning brief",
+  "Mum dogfood feedback").
+- **UX-P0-3 — `token_economy` set via `/customise-workflow` is now honored.** It writes
+  `.atlas-ai/config/atlas.json`, but the engine read economy only from
+  `.atlas-ai/fleet.json`. `load_fleet_config` now reads `token_economy` from `atlas.json`
+  when `fleet.json` doesn't set one (fleet.json wins if it does); the config schema doc
+  adds the key.
+
+### Fixed (version hygiene)
+- `prd_taskmaster/__init__.py` version bumped (5.2.1 set `package.json`/`plugin.json` but
+  missed the `__init__.py` source-of-truth the manifest tests check).
+
 ## [5.2.1] — 2026-06-14
 
 Pre-relaunch hardening — fixes the first-run failures a multi-agent audit found

README.md

@@ -83,7 +83,7 @@ npm install -g task-master-ai
 Open any project in Claude Code and type:
 
 ```
-/atlas      (or /prd:go, or just say: "I want to build …")
+/prd:atlas      (or /prd:go, or just say: "I want to build …")
 ```
 
 Requires Python 3.11+ and Linux / macOS / WSL. The free engine needs **no paid API key** — it

docs/audit/UX-FLOW-AUDIT.md

@@ -1,6 +1,6 @@
 {
   "name": "prd-taskmaster",
-  "version": "5.2.1",
+  "version": "5.2.2",
   "description": "Zero-config goal-to-tasks engine for Claude Code (the Atlas engine)",
   "author": {
     "name": "Atlas AI",

package.json

@@ -1,3 +1,3 @@
 """prd-taskmaster: zero-config goal-to-tasks engine (deterministic CLI core)."""
 
-__version__ = "5.2.0"
+__version__ = "5.2.2"

prd_taskmaster/__init__.py

@@ -51,17 +51,40 @@
 BACKEND_CHOICES = {"auto", "taskmaster", "native"}
 
 
+ATLAS_CONFIG_PATH = Path(".atlas-ai") / "config" / "atlas.json"
+
+
+def _atlas_config_economy() -> str | None:
+    """token_economy set via /customise-workflow (.atlas-ai/config/atlas.json).
+
+    /customise-workflow is the discoverable customization tool; the economy a user
+    sets there must take effect even though the lower-level routing file is fleet.json.
+    """
+    if not ATLAS_CONFIG_PATH.is_file():
+        return None
+    try:
+        raw = json.loads(ATLAS_CONFIG_PATH.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+    if not isinstance(raw, dict):
+        return None
+    val = raw.get("token_economy")
+    return val if isinstance(val, str) else None
+
+
 def load_fleet_config(path=None):
     """Load .atlas-ai/fleet.json merged over defaults.
 
     Malformed files and invalid values fall back to defaults silently —
     a broken optional config must never block a fleet run.
+
+    Economy precedence: fleet.json (explicit) > atlas.json (/customise-workflow) > default.
     """
     cfg = {
         "max_concurrency": DEFAULT_FLEET_CONFIG["max_concurrency"],
         "routing": dict(DEFAULT_ROUTING),
         "experimental_backends": DEFAULT_FLEET_CONFIG["experimental_backends"],
-        "token_economy": DEFAULT_FLEET_CONFIG["token_economy"],
+        "token_economy": _atlas_config_economy() or DEFAULT_FLEET_CONFIG["token_economy"],
         "backend": DEFAULT_FLEET_CONFIG["backend"],
     }
     p = Path(path) if path else FLEET_CONFIG_PATH

prd_taskmaster/fleet.py

@@ -0,0 +1,18 @@
+---
+name: atlas
+description: >-
+  The Atlas engine — turn any goal into a validated PRD and an executable, verified
+  task graph. Brand-name entrypoint; a thin alias for the `go` orchestrator. Use when
+  the user types /prd:atlas, says "I want to build", or asks for a PRD / task-driven build.
+user-invocable: true
+allowed-tools:
+  - Skill
+---
+
+# atlas (entrypoint alias)
+
+This is the brand-name entrypoint for the Atlas engine. It holds no procedure of its
+own — **immediately invoke the `go` orchestrator** via the Skill tool (`/prd:go`).
+
+`go` reads pipeline state and dispatches to the correct phase
+(SETUP → DISCOVER → GENERATE → HANDOFF → EXECUTE). Do not duplicate that routing here.

skills/atlas/SKILL.md

@@ -142,10 +142,11 @@ just that key, re-validate, and re-write.
 
 ## Config Schema
 
-`.atlas-ai/config/atlas.json` has 6 top-level keys:
+`.atlas-ai/config/atlas.json` has 7 top-level keys:
 
 ```json
 {
+  "token_economy": "conservative|balanced|performance",
   "provider": {
     "main": "gemini-cli|claude-code|anthropic|openai|openrouter|ollama|...",
     "model_main": "gemini-3-pro-preview|sonnet|gpt-4o|...",
@@ -184,6 +185,10 @@ Phase files (`skills/setup`, `skills/discover`, `skills/generate`,
 `skills/handoff`, `skills/execute-task`) read this config at runtime and apply
 user preferences before falling back to documented defaults.
 
+`token_economy` here is honored by the engine itself: `load_fleet_config` reads it
+from this file when `.atlas-ai/fleet.json` does not set one (fleet.json wins if it
+does), so the economy you pick via this skill actually drives model-tier routing.
+
 ## Customizations directory
 
 For tweaks that go beyond the curated questions — custom template overrides,

skills/customise-workflow/SKILL.md

@@ -31,18 +31,17 @@ skill.**
 
 ## Entry gate
 
-1. Call `mcp__plugin_prd_go__check_gate(phase="DISCOVER", evidence={})`.
-   If the call returns `{gate_passed: false, violations: [...]}`, report the
-   violations and stop. The gate protects against re-entering a completed
-   phase or skipping ahead from SETUP.
-
-   **Known issue (Mum dogfood feedback [4]):** check_gate is structurally
-   an EXIT gate. On first DISCOVER entry, evidence=`{}` will fail the
-   `user_approved=true OR auto_classification=CLEAR with assumptions_documented`
-   requirement (which the User Approval Gate / Self-Approval Gate below
-   produces). State machine LEGAL_TRANSITIONS already prevents illegal
-   entry — proceed past this gate on first entry. Semantic fix in flight
-   (see morning brief).
+1. Call `mcp__plugin_prd_go__check_gate(phase="DISCOVER", evidence={})` for diagnostics.
+
+   `check_gate` is an EXIT gate: it verifies the evidence to *advance*, not to *enter*.
+   On first DISCOVER entry you have no evidence yet (the User Approval / Self-Approval
+   Gate below produces `user_approved=true` OR `auto_classification=CLEAR with
+   assumptions_documented`), so a `gate_passed: false` here is EXPECTED — the state
+   machine's legal transitions already guarantee only legal entry.
+
+   - **First entry** (no evidence yet): note the result and continue with the Procedure.
+   - **Re-entry**: if the gate reports violations, report them and stop — it protects
+     against re-running a completed phase or skipping ahead from SETUP.
 2. Detect execution context. If any of the following signals are present,
    switch to Autonomous Mode:
    - `.claude/ralph-loop.local.md` exists in the project root