Add ui-implement workflow for [UI] story implementation

AGENTS.md

@@ -19,6 +19,7 @@ This repository contains reusable AI coding workflows and focused skills that ca
 - **docs-writer** — Documentation creation workflow (gather, plan, draft, validate, apply, mr)
 - **e2e** — Story-to-tests workflow for [QE] stories (ingest, plan, revise, code, validate, publish, respond)
 - **implement** — Story-to-code workflow (ingest, plan, revise, code, validate, publish, respond)
+- **ui-implement** — Story-to-code workflow for UI/front-end [UI] stories (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)
 - **rebase-stack** — Rebase a stacked-branch chain with conflict guidance, per-branch validation, and push (start, continue, validate, push)
@@ -256,6 +257,7 @@ ai-workflows/
 ├── docs-writer/
 ├── e2e/
 ├── implement/
+├── ui-implement/
 ├── kcs/
 ├── prd/
 ├── rebase-stack/

README.md

@@ -41,6 +41,9 @@ Reusable AI coding workflows and focused skills a team member can install global
 - **Implement** -- Story-to-code workflow: take a Jira Story, plan the implementation, write contract-based tests and production code via TDD, validate against the project's CI expectations, and manage review via GitHub PRs.
   See [implement/README.md](implement/README.md).
 
+- **UI Implement** -- Story-to-code workflow for UI/front-end [UI] stories: take a Jira Story, discover the project's UI toolchain (test framework, design system, i18n), plan the implementation with component/hook interfaces, write contract-based unit tests and production code via TDD, write integration/e2e test stubs, validate against the project's CI expectations, and manage review via GitHub PRs.
+  See [ui-implement/README.md](ui-implement/README.md).
+
 - **E2E** -- Story-to-tests workflow for [QE] stories: discover the project's e2e testing infrastructure, map acceptance criteria to test scenarios, write e2e test code following the project's patterns and reference suite, validate against anti-patterns and scenario coverage, and manage review via GitHub PRs.
   See [e2e/README.md](e2e/README.md).
 
@@ -194,6 +197,7 @@ Each workflow or skill is intended for a specific project or use case:
 - **prd** -- teams drafting Product Requirements Documents from Jira features
 - **design** -- teams creating technical design documents and Jira-ready epic/story breakdowns from PRDs
 - **implement** -- teams implementing Jira stories produced by the design workflow
+- **ui-implement** -- teams implementing [UI] stories for front-end/React projects produced by the design workflow with a ui-design document
 - **e2e** -- teams writing e2e tests for [QE] stories produced by the design workflow
 - **cve-fix** -- teams patching CVEs and updating vulnerable dependencies from Jira vulnerability tickets
 - **ai-ready** -- onboarding any project for AI agents by generating AGENTS.md

ui-implement/README.md

@@ -0,0 +1,228 @@
+# UI Implement Workflow
+
+A story-to-code workflow for UI/front-end stories. Takes a Jira [UI] Story, plans the implementation using discovered design-system and testing conventions, writes contract-based unit tests and production code via TDD, validates against the project's CI expectations, and manages review via GitHub PRs.
+
+## Phase Flow
+
+```mermaid
+graph TD
+    ingest([ingest]) --> plan
+    plan --> revise
+    revise --> revise
+    plan --> code
+    revise --> code
+    code --> validate
+    validate -->|pass| publish
+    validate -->|fail| code
+    publish --> respond
+    respond --> respond
+```
+
+## Prerequisites
+
+| Tool | Required | Purpose |
+|------|----------|---------|
+| Jira access (MCP or CLI) | For `/ingest` | Fetch Story issue details |
+| GitHub CLI (`gh`) | For `/publish`, `/respond` | Create PRs, post review comments |
+| Git | Yes | Branch management, commits |
+| Project build/test tooling | Yes | Discovered during `/ingest` from project's AGENTS.md, package.json, CI workflows |
+| Docs repo (local clone) | For `/ingest` | Read ui-design, PRD, handoff, and API findings documents |
+
+## Phases
+
+| Phase | Command | Purpose | Artifact(s) |
+|-------|---------|---------|-------------|
+| Ingest | `/ingest` | Fetch story, load ui-design/PRD/handoff context, discover UI toolchain | `01-context.md`, `testplan.md` (when test cases match) |
+| Plan | `/plan` | Design implementation approach, component/hook interfaces, test strategy | `02-plan.md` |
+| Revise | `/revise` | Incorporate feedback into the plan | Updated `02-plan.md` |
+| Code | `/code` | Write unit tests and code via TDD, then integration/e2e stubs | `03-test-report.md`, `04-impl-report.md` |
+| Validate | `/validate` | Run tests, lint, type checking, coverage analysis | `05-validation-report.md` |
+| Publish | `/publish` | Push branch, create draft PR | `06-pr-description.md` |
+| Respond | `/respond` | Address reviewer comments | `07-review-responses.md` |
+
+Each phase command invokes `skills/dispatch.md` with the requested phase. The
+dispatcher resolves any project override, loads only that phase, and passes
+along the command context. After the phase reports its result,
+`skills/completion.md` supplies the shared next-step guidance without loading
+the full controller. The controller remains the entry point for workflow
+discovery and ambiguous requests.
+
+## Typical Flow
+
+```text
+/ingest EDM-1234
+  → fetches story from Jira
+  → loads ui-design document, design document, PRD, handoff, API findings
+  → explores affected components and UI codebase areas
+  → discovers UI toolchain (test framework, design system, i18n, state management)
+  → discovers validation profile (build, test, lint, type-check commands)
+  → writes .artifacts/ui-implement/EDM-1234/01-context.md
+  → writes testplan.md when story test cases match
+
+/plan
+  → designs implementation approach
+  → defines component props and hook signatures (the contracts)
+  → plans unit test strategy per component/hook
+  → plans integration/e2e test stubs (if e2e framework exists)
+  → plans UI cross-cutting concerns (design system, i18n, a11y, permissions, states)
+  → breaks work into ordered tasks
+  → optionally includes Task 0 for test framework introduction
+  → writes 02-plan.md
+
+/revise (optional, repeatable)
+  → user reviews plan, requests changes
+  → plan updated, consistency maintained
+
+/code
+  → creates feature branch
+  → for each task: write unit tests → write code → review → commit
+  → after all tasks: write integration/e2e test stubs (if planned)
+  → updates 02-plan.md with task completion status
+  → writes 03-test-report.md, 04-impl-report.md
+
+/validate
+  → runs full validation suite (discovered during /ingest)
+  → analyzes coverage for untested behavioral paths
+  → verifies UI cross-cutting concerns (design system, i18n, a11y, states)
+  → adds tests for gaps, fixes lint/type issues
+  → writes 05-validation-report.md
+
+/publish
+  → pushes feature branch
+  → creates draft GitHub PR with Jira link
+  → writes 06-pr-description.md
+
+/respond (repeatable)
+  → fetches PR review comments
+  → proposes responses (user approves before posting)
+  → applies code changes if needed
+  → writes 07-review-responses.md
+```
+
+## Artifacts
+
+All artifacts are stored in `.artifacts/ui-implement/{issue-key}/`.
+
+```text
+.artifacts/ui-implement/EDM-1234/
+  01-context.md              (story context, UI toolchain, validation profile)
+  testplan.md                (story-scoped test cases, when ingest finds matches)
+  02-plan.md                 (task breakdown, test strategy — updated as tasks complete)
+  03-test-report.md          (tests written, contracts covered)
+  04-impl-report.md          (changes, commits, UI concerns applied, deviations)
+  05-validation-report.md    (check results, coverage, UI cross-cutting verification)
+  06-pr-description.md       (PR body)
+  07-review-responses.md     (review comment log)
+  publish-metadata.json      (PR number, branch, URL)
+
+.artifacts/ui-implement/
+  _validation-profile.md     (discovered build/test/lint commands, cached across stories)
+  .meta.json                 (file hashes/mtimes for validation cache invalidation)
+```
+
+## Key Design Decisions
+
+### Contract-Based Testing (TDD for Unit Tests)
+
+Unit tests validate behavioral contracts through public interfaces:
+- **Components:** Test rendered output, user interactions, accessibility attributes
+- **Hooks:** Test return values, state transitions, side effects
+- Tests should remain valid if the implementation were rewritten
+- Unit tests use TDD: write tests first, then implementation, task by task
+
+### Integration/E2E Test Stubs (Post-Implementation)
+
+Integration and e2e test stubs are written **after** all implementation tasks complete:
+- Stubs follow the project's existing e2e patterns (if any)
+- They provide scaffolding (describe blocks, pending tests) — not full implementations
+- Full e2e test suites are the responsibility of `[QE]` stories
+
+### Discovery-Based Everything
+
+The workflow does not hardcode any tool assumptions. During `/ingest`, it discovers:
+- Test framework (Vitest, Jest, Mocha, etc.)
+- Design system (PatternFly, MUI, Chakra, custom, etc.)
+- i18n library (react-i18next, react-intl, FormatJS, etc.)
+- State management approach
+- Routing library
+- E2e framework (Cypress, Playwright, etc.)
+- Permission/RBAC patterns
+- Build, test, lint, and type-check commands
+
+If the project adds new tools or changes conventions, the next `/ingest` picks them up.
+
+### Test Framework Introduction
+
+When `/ingest` discovers no unit testing framework exists:
+- It identifies suitable frameworks based on the project's build tooling
+- Records a recommendation in `01-context.md`
+- `/plan` includes this as "Task 0: Introduce unit testing framework"
+- The user approves the framework choice before any story code is written
+
+### Upstream Design Documents
+
+This workflow reads published docs from the docs repo, never from another
+workflow's `.artifacts/` directory:
+- `ui-design.md` — **required** — component architecture, hook designs, state management, accessibility plan
+- `handoff.md` — **optional** — interaction specs, state matrix, acceptance criteria enrichment
+- `api-findings.md` — **optional** — resolved endpoints, API gaps
+- `prd.md` — requirements coverage
+- `design.md` — API contracts, data models
+
+### UI Cross-Cutting Concerns
+
+Every `/code` task and `/validate` review checks:
+- **Design system compliance** — use design system components, not raw HTML
+- **i18n** — wrap all user-visible strings
+- **Accessibility** — ARIA attributes, keyboard navigation, screen reader text
+- **Permission-aware rendering** — use discovered RBAC patterns
+- **State completeness** — loading, error, and empty states
+
+### What This Workflow Does NOT Do
+
+- Full e2e test suites (those are for `[QE]` stories via the `e2e` workflow)
+- Visual regression tests
+- Backend implementation (that's the `implement` workflow for `[DEV]` stories)
+
+## Directory Structure
+
+```text
+ui-implement/
+├── SKILL.md                    # Workflow entry point
+├── guidelines.md               # Behavioral rules and guardrails
+├── README.md                   # This file
+├── templates/
+│   ├── 01-context.md           # Ingest context skeleton
+│   └── story-testplan.md       # Story-scoped testplan skeleton
+├── skills/
+│   ├── controller.md           # Discovery and ambiguous-input router
+│   ├── dispatch.md             # Explicit-phase dispatcher
+│   ├── completion.md           # Shared next-step guidance
+│   ├── ingest.md               # Fetch story, discover UI toolchain, explore codebase
+│   ├── plan.md                 # Design implementation approach
+│   ├── revise.md               # Incorporate plan feedback
+│   ├── code.md                 # Write tests and code via TDD, then stubs
+│   ├── validate.md             # Run validation suite
+│   ├── publish.md              # Create GitHub PR
+│   └── respond.md              # Address review comments
+└── commands/
+    ├── ingest.md               # /ingest command
+    ├── plan.md                 # /plan command
+    ├── revise.md               # /revise command
+    ├── code.md                 # /code command
+    ├── validate.md             # /validate command
+    ├── publish.md              # /publish command
+    └── respond.md              # /respond command
+```
+
+## Getting Started
+
+```bash
+# Install the workflow
+./install.sh claude --packages ui-implement
+
+# Or install all workflows
+./install.sh all
+```
+
+Then in your project, run the `ui-implement` workflow's `ingest` command for your Jira story (e.g., EDM-1234).

ui-implement/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: ui-implement
+version: 0.1.0
+description: >-
+  Story-to-code workflow for UI/front-end stories. Takes a Jira [UI] Story,
+  plans the implementation using discovered design-system and testing
+  conventions, writes contract-based unit tests and production code via TDD,
+  validates against the project's CI expectations, and manages review via
+  GitHub PRs. Use when implementing [UI] stories produced by the design
+  workflow with a ui-design document.
+  Activated by commands: /ingest, /plan, /revise, /code, /validate, /publish, /respond.
+---
+# UI Implement Workflow Orchestrator
+
+## Quick Start
+
+1. If the user invoked a specific command (e.g., `/plan`, `/code`), read
+   the matching file in commands/ and follow it.
+2. Otherwise, read `skills/controller.md` to load the workflow controller:
+   - If the user provided a Jira issue key or URL, execute the `/ingest` phase
+   - Otherwise, execute the first phase the user requests
+
+If a step fails or produces unexpected output (e.g., Jira MCP errors, test
+failures, build errors), stop and report the error to the user. Do not
+advance to the next phase. Offer to retry the failed step or escalate.
+
+For principles, hard limits, safety, quality, and escalation rules, see `guidelines.md`.

ui-implement/commands/code.md

@@ -0,0 +1,11 @@
+---
+name: ui-implement:code
+description: "Write unit tests and production code via TDD, then integration/e2e test stubs, committing incrementally"
+---
+# /code
+
+Read `../skills/dispatch.md` and follow it with `PHASE=code`.
+
+Context:
+
+$ARGUMENTS

ui-implement/commands/ingest.md

@@ -0,0 +1,11 @@
+---
+name: ui-implement:ingest
+description: "Fetch Jira story, load ui-design/PRD context, explore codebase, discover UI toolchain, build validation profile"
+---
+# /ingest
+
+Read `../skills/dispatch.md` and follow it with `PHASE=ingest`.
+
+Context:
+
+$ARGUMENTS

ui-implement/commands/plan.md

@@ -0,0 +1,11 @@
+---
+name: ui-implement:plan
+description: "Design the UI implementation approach with task breakdown, component/hook interfaces, and test strategy"
+---
+# /plan
+
+Read `../skills/dispatch.md` and follow it with `PHASE=plan`.
+
+Context:
+
+$ARGUMENTS

ui-implement/commands/publish.md

@@ -0,0 +1,11 @@
+---
+name: ui-implement:publish
+description: "Push the feature branch and create a draft PR for the UI implementation"
+---
+# /publish
+
+Read `../skills/dispatch.md` and follow it with `PHASE=publish`.
+
+Context:
+
+$ARGUMENTS

ui-implement/commands/respond.md

@@ -0,0 +1,11 @@
+---
+name: ui-implement:respond
+description: "Fetch and address PR reviewer comments on UI implementation code"
+---
+# /respond
+
+Read `../skills/dispatch.md` and follow it with `PHASE=respond`.
+
+Context:
+
+$ARGUMENTS

ui-implement/commands/revise.md

@@ -0,0 +1,11 @@
+---
+name: ui-implement:revise
+description: "Incorporate user feedback into the UI implementation plan"
+---
+# /revise
+
+Read `../skills/dispatch.md` and follow it with `PHASE=revise`.
+
+Context:
+
+$ARGUMENTS

ui-implement/commands/validate.md

@@ -0,0 +1,11 @@
+---
+name: ui-implement:validate
+description: "Run the full validation suite, analyze coverage, verify UI cross-cutting concerns, iterate on gaps"
+---
+# /validate
+
+Read `../skills/dispatch.md` and follow it with `PHASE=validate`.
+
+Context:
+
+$ARGUMENTS