UXDOPS-2843: Add /ux-design workflow for UX design and implementation handoff

AGENTS.md

@@ -21,6 +21,7 @@ This repository contains reusable AI coding workflows and focused skills that ca
 - **implement** — Story-to-code workflow (ingest, plan, revise, code, validate, publish, respond)
 - **kcs** — KCS Solution article workflow (gather, draft, validate, handoff)
 - **prd** — Requirements-to-PRD workflow (ingest, clarify, draft, revise, publish, respond)
+- **ux-design** — UX design workflow (ingest, research, prototype, evaluate, handoff, revise, publish, respond)
 - **rebase-stack** — Rebase a stacked-branch chain with conflict guidance, per-branch validation, and push (start, continue, validate, push)
 - **sizing** — Pre-cycle Feature sizing with T-shirt sizes and team effort breakdowns (ingest, assess, apply)
 - **skill-reviewer** — Meta-workflow that audits AI skill directories
@@ -83,7 +84,7 @@ _shared/
   review-protocol.md              # Shared code review criteria, finding format, severity definitions
   sizing-rubric.md                # Shared sizing definitions (T-shirt sizes, heuristics, team effort guidance)
   scripts/
-    provenance.py                 # Capture/render CLI (used by prd and design provenance recipes)
+    provenance.py                 # Capture/render CLI (used by prd, design, and ux-design provenance recipes)
     pr-comments.py                # Deterministic PR comment operations (fetch, reply, log)
     publish.py                    # Deterministic publish operations (push, PR/MR, metadata)
     resolve-phase.py              # Deterministic phase override resolution (file-existence check)
@@ -97,7 +98,7 @@ _shared/
     validation-gate.md            # Pre-commit build/test/lint discovery gate (used by bugfix)
 ```
 
-Recipes are self-contained, parameterized procedures that packages reference via relative path (e.g., `../../_shared/recipes/self-review-gate.md` from a workflow phase). Workflows and simple skills may also reference shared files from guidelines, phases, references, templates, prompts, scripts, and other behavioral files — all such references count as consumers for the shared-file cascade (see Package Versioning). The **prd** and **design** workflows use the provenance recipes on `/draft`, `/revise`, `/respond` (capture) and `/publish` plus docs-sync paths (render). See `_shared/provenance-schema.md` for the published footer format.
+Recipes are self-contained, parameterized procedures that packages reference via relative path (e.g., `../../_shared/recipes/self-review-gate.md` from a workflow phase). Workflows and simple skills may also reference shared files from guidelines, phases, references, templates, prompts, scripts, and other behavioral files — all such references count as consumers for the shared-file cascade (see Package Versioning). The **prd** and **design** workflows use the provenance recipes on `/draft`, `/revise`, `/respond` (capture) and `/publish` plus docs-sync paths (render). The **ux-design** workflow uses them on `/handoff`, `/revise`, `/respond` (capture) and `/publish` plus `/respond` (render). See `_shared/provenance-schema.md` for the published footer format.
 
 ### File Reference Conventions
 
@@ -236,7 +237,7 @@ ai-workflows/
 │   ├── review-protocol.md     # Shared code review criteria and finding format
 │   ├── sizing-rubric.md       # Shared sizing definitions and heuristics
 │   ├── scripts/
-│   │   ├── provenance.py      # Capture/render CLI for prd/design provenance
+│   │   ├── provenance.py      # Capture/render CLI for prd/design/ux-design provenance
 │   │   ├── pr-comments.py     # Deterministic PR comment operations (fetch, reply, log)
 │   │   ├── publish.py         # Deterministic publish operations (push, PR/MR, metadata)
 │   │   ├── resolve-phase.py   # Deterministic phase override resolution
@@ -273,6 +274,7 @@ ai-workflows/
 │       ├── references/
 │       ├── scripts/
 │       └── templates/
+├── ux-design/
 ├── install.sh                 # Installer with auto-discovery
 ├── uninstall.sh              # Removal script
 ├── AGENTS.md                 # AI assistant guidance (this file)

README.md

@@ -65,6 +65,9 @@ Reusable AI coding workflows and focused skills a team member can install global
 - **Skill Reviewer** -- Meta-workflow that audits AI skill directories against eight quality dimensions.
   See [skill-reviewer/README.md](skill-reviewer/README.md).
 
+- **UX Design** -- UX design workflow: ingest a feature request, conduct user research, generate prototypes, run heuristic evaluation, and produce a validated design handoff for the `ui-design` workflow.
+  See [ux-design/README.md](ux-design/README.md).
+
 ## How It Works
 
 Each workflow is a top-level directory with a `SKILL.md`, while focused skills

_shared/recipes/capture-provenance-event.md

@@ -1,6 +1,6 @@
 ---
 name: capture-provenance-event
-version: 0.1.1
+version: 0.1.2
 ---
 # Recipe: Capture Provenance Event
 
@@ -11,9 +11,9 @@ phase mutates the planning document. See `../provenance-schema.md`.
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
-| WORKFLOW | Yes | `prd` or `design` |
+| WORKFLOW | Yes | `prd`, `design`, or `ux-design` |
 | ISSUE_KEY | Yes | Full Jira issue key including project prefix (e.g., `PROJ-1234`, not `1234`) |
-| PHASE | Yes | `draft`, `revise`, or `respond` |
+| PHASE | Yes | For `prd` and `design`: `draft`, `revise`, or `respond`. For `ux-design`: `handoff`, `revise`, or `respond` |
 | AUTHORING_MODE | Yes | `skill` (default for phase skills) or `manual` |
 
 ## Procedure

_shared/recipes/render-provenance-footer.md

@@ -1,6 +1,6 @@
 ---
 name: render-provenance-footer
-version: 0.2.0
+version: 0.2.1
 ---
 # Recipe: Render Provenance Footer
 
@@ -11,7 +11,7 @@ docs-repo copy before `git add`. See `../provenance-schema.md` for format.
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
-| WORKFLOW | Yes | `prd` or `design` |
+| WORKFLOW | Yes | `prd`, `design`, or `ux-design` |
 | ISSUE_KEY | Yes | Full Jira issue key including project prefix (e.g., `PROJ-1234`, not `1234`) |
 | TARGET_FILE | Yes | Absolute path to the local artifact or docs-repo file to render |
 | ALLOW_MISSING | No | Set to `yes` only after the user explicitly declines provenance |

_shared/scripts/provenance.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Capture and render provenance for prd/design planning document workflows.
+"""Capture and render provenance for prd/design/ux-design planning documents.
 
 Exit codes:
     0: Success (capture or render completed)
@@ -23,9 +23,29 @@
 WORKFLOW_DOCS = {
     "prd": "03-prd.md",
     "design": "03-design.md",
+    "ux-design": "05-handoff.md",
 }
 
-AUTHORING_PHASES = frozenset({"draft", "revise", "respond", "manual-edit"})
+# The phase that legitimately originates each workflow's document. prd/design
+# originate from a template-checked /draft; ux-design assembles its handoff spec
+# in /handoff (there is no template-from-origin step), so `handoff` is its
+# origin. A first event other than this marks the phase history as untracked.
+ORIGIN_PHASE = {
+    "prd": "draft",
+    "design": "draft",
+    "ux-design": "handoff",
+}
+
+AUTHORING_PHASES = frozenset(
+    {"draft", "handoff", "revise", "respond", "manual-edit"}
+)
+
+# Per-workflow valid phases (for validation in capture_event)
+WORKFLOW_PHASES = {
+    "prd": frozenset({"draft", "revise", "respond", "manual-edit", "commit"}),
+    "design": frozenset({"draft", "revise", "respond", "manual-edit", "commit"}),
+    "ux-design": frozenset({"handoff", "revise", "respond", "manual-edit", "commit"}),
+}
 
 DRIFT_FIELDS = (
     "workflow_version",
@@ -56,10 +76,18 @@
 COMMIT_ONLY_NOTE = (
     "> Authoring phases not recorded this session (commit-time snapshot only)."
 )
-ORIGIN_UNTRACKED_NOTE = (
-    "> This document's phase history does not include an initial /draft — "
-    "structure was not verified against the template from origin."
-)
+def origin_untracked_note(workflow: str | None = None) -> str:
+    origin = ORIGIN_PHASE.get(workflow, "draft")
+    # ux-design has no template step; its /handoff assembles from scratch
+    if workflow == "ux-design":
+        return (
+            f"> This document's phase history does not include an initial /{origin} — "
+            "structure was not verified from origin."
+        )
+    return (
+        f"> This document's phase history does not include an initial /{origin} — "
+        "structure was not verified against the template from origin."
+    )
 
 
 def repo_root(start: Path) -> Path | None:
@@ -260,12 +288,15 @@ def provenance_kind(events: list[dict[str, Any]]) -> str:
     return "session"
 
 
-def origin_untracked(events: list[dict[str, Any]]) -> bool:
+def origin_untracked(
+    events: list[dict[str, Any]], workflow: str | None = None
+) -> bool:
     if not events:
         return False
     if provenance_kind(events) == "commit_only":
         return False
-    return events[0].get("phase") != "draft"
+    origin = ORIGIN_PHASE.get(workflow, "draft")
+    return events[0].get("phase") != origin
 
 
 def capture_event(
@@ -274,6 +305,14 @@ def capture_event(
     phase: str,
     authoring_mode: str,
 ) -> None:
+    # Validate phase is valid for this workflow
+    valid_phases = WORKFLOW_PHASES.get(workflow)
+    if valid_phases and phase not in valid_phases:
+        raise ValueError(
+            f"Phase '{phase}' is not valid for workflow '{workflow}'. "
+            f"Valid phases: {', '.join(sorted(valid_phases))}"
+        )
+
     ai_root = ai_workflows_root()
     ws_root = workspace_root()
     path = provenance_path(workflow, issue)
@@ -352,6 +391,7 @@ def build_metrics_payload(data: dict[str, Any]) -> dict[str, Any]:
     last = events[-1] if events else {}
     drift = data.get("drift", {})
     kind = provenance_kind(events)
+    workflow = data.get("workflow", "unknown")
     return {
         "schema_version": 1,
         "provenance_kind": kind,
@@ -368,7 +408,7 @@ def build_metrics_payload(data: dict[str, Any]) -> dict[str, Any]:
             {event.get("authoring_mode", "skill") for event in events}
         ),
         "context_changed": drift.get("context_changed", False),
-        "origin_untracked": origin_untracked(events),
+        "origin_untracked": origin_untracked(events, workflow),
     }
 
 
@@ -403,9 +443,9 @@ def build_footer(data: dict[str, Any]) -> str:
         if len(phases) > 1:
             lines.append(f"Phases: {', '.join(phases)}")
 
-    if origin_untracked(events):
+    if origin_untracked(events, workflow):
         lines.append("")
-        lines.append(ORIGIN_UNTRACKED_NOTE)
+        lines.append(origin_untracked_note(workflow))
 
     lines.append("")
     lines.append(metrics_comment)
@@ -491,7 +531,9 @@ def render_footer(workflow: str, issue: str, target: Path, *, allow_missing: boo
 
 
 def main() -> int:
-    parser = argparse.ArgumentParser(description="PRD/design provenance helper")
+    parser = argparse.ArgumentParser(
+        description="PRD/design/ux-design provenance helper"
+    )
     sub = parser.add_subparsers(dest="command", required=True)
 
     capture = sub.add_parser("capture", help="Append a provenance event")
@@ -500,7 +542,7 @@ def main() -> int:
     capture.add_argument(
         "--phase",
         required=True,
-        choices=["draft", "revise", "respond", "manual-edit", "commit"],
+        choices=["draft", "handoff", "revise", "respond", "manual-edit", "commit"],
     )
     capture.add_argument(
         "--authoring-mode",

_shared/scripts/test_provenance.py

@@ -108,6 +108,46 @@ def test_origin_untracked_false_when_all_events_are_commit(self) -> None:
         self.assertEqual(provenance.provenance_kind(events), "commit_only")
         self.assertFalse(provenance.origin_untracked(events))
 
+    def test_origin_untracked_false_for_ux_design_handoff_first(self) -> None:
+        # ux-design originates its document in /handoff (not /draft), so a
+        # handoff-first log is a tracked origin and must NOT be flagged.
+        events = [{"phase": "handoff"}, {"phase": "revise"}]
+        self.assertFalse(provenance.origin_untracked(events, "ux-design"))
+
+    def test_origin_untracked_true_for_ux_design_revise_first(self) -> None:
+        # ux-design entered at /revise with no prior /handoff is untracked.
+        events = [{"phase": "revise"}]
+        self.assertTrue(provenance.origin_untracked(events, "ux-design"))
+
+    def test_origin_untracked_true_for_prd_handoff_first(self) -> None:
+        # 'handoff' is not prd's origin phase, so a handoff-first prd log is
+        # still untracked -- the per-workflow origin must not leak across.
+        events = [{"phase": "handoff"}]
+        self.assertTrue(provenance.origin_untracked(events, "prd"))
+
+    def test_origin_untracked_note_names_workflow_origin_phase(self) -> None:
+        ux_note = provenance.origin_untracked_note("ux-design")
+        self.assertIn("/handoff", ux_note)
+        # ux-design has no template step, so note should not mention "template"
+        self.assertNotIn("template", ux_note)
+
+        prd_note = provenance.origin_untracked_note("prd")
+        self.assertIn("/draft", prd_note)
+        self.assertIn("template", prd_note)  # prd/design DO have templates
+
+        self.assertIn("/draft", provenance.origin_untracked_note())
+
+    def test_workflow_phase_validation_rejects_invalid_combinations(self) -> None:
+        # prd/design don't have 'handoff' phase
+        with self.assertRaises(ValueError) as cm:
+            provenance.capture_event("prd", "TEST-123", "handoff", "skill")
+        self.assertIn("not valid for workflow 'prd'", str(cm.exception))
+
+        # ux-design doesn't have 'draft' phase
+        with self.assertRaises(ValueError) as cm:
+            provenance.capture_event("ux-design", "TEST-456", "draft", "skill")
+        self.assertIn("not valid for workflow 'ux-design'", str(cm.exception))
+
     def test_build_metrics_payload_flags_origin_untracked(self) -> None:
         data = {
             "workflow": "prd",

design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design
-version: 0.11.3
+version: 0.11.4
 description: >-
   Design-and-decompose workflow that takes a PRD, researches the problem space,
   drafts a technical design document with a requirement-anchored testplan,