From 483a1236d8d7c5154a828a11b13c4cfcbfeeef0f Mon Sep 17 00:00:00 2001 From: Chai Bot Date: Thu, 1 Oct 2026 18:51:51 +0000 Subject: [PATCH 01/12] Add ui-implement workflow for UI/front-end story implementation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New 7-phase workflow (ingest, plan, revise, code, validate, publish, respond) that mirrors implement's structure but adapts it for UI/front-end development: - Discovery-based UI toolchain: test framework, design system, i18n, state management, routing, permissions, e2e framework — all discovered from the codebase during /ingest, never hardcoded - TDD for unit tests: contract-based testing through component/hook public interfaces (rendered output, user interactions, hook return values), task by task with review gates - Integration/e2e test stubs written after all tasks complete, following the project's existing patterns (if any) - Test framework introduction: when /ingest discovers no unit testing, identifies suitable frameworks and /plan includes Task 0 for setup - Upstream docs from docs repo: ui-design.md (required), handoff.md and api-findings.md (optional), plus prd.md and design.md - UI cross-cutting concerns: design system compliance, i18n wrapping, ARIA/keyboard accessibility, permission-aware rendering, loading/error/empty states - Registers in AGENTS.md, README.md; auto-discovered by install.sh Assisted-by: Claude Opus 4.6 --- AGENTS.md | 2 + README.md | 4 + ui-implement/README.md | 224 +++++++++ ui-implement/SKILL.md | 27 ++ ui-implement/commands/code.md | 11 + ui-implement/commands/ingest.md | 11 + ui-implement/commands/plan.md | 11 + ui-implement/commands/publish.md | 11 + ui-implement/commands/respond.md | 11 + ui-implement/commands/revise.md | 11 + ui-implement/commands/validate.md | 11 + ui-implement/guidelines.md | 92 ++++ ui-implement/skills/code.md | 571 +++++++++++++++++++++++ ui-implement/skills/completion.md | 34 ++ ui-implement/skills/controller.md | 114 +++++ ui-implement/skills/dispatch.md | 48 ++ ui-implement/skills/ingest.md | 383 +++++++++++++++ ui-implement/skills/plan.md | 349 ++++++++++++++ ui-implement/skills/publish.md | 279 +++++++++++ ui-implement/skills/respond.md | 234 ++++++++++ ui-implement/skills/revise.md | 134 ++++++ ui-implement/skills/validate.md | 362 ++++++++++++++ ui-implement/templates/01-context.md | 187 ++++++++ ui-implement/templates/story-testplan.md | 26 ++ 24 files changed, 3147 insertions(+) create mode 100644 ui-implement/README.md create mode 100644 ui-implement/SKILL.md create mode 100644 ui-implement/commands/code.md create mode 100644 ui-implement/commands/ingest.md create mode 100644 ui-implement/commands/plan.md create mode 100644 ui-implement/commands/publish.md create mode 100644 ui-implement/commands/respond.md create mode 100644 ui-implement/commands/revise.md create mode 100644 ui-implement/commands/validate.md create mode 100644 ui-implement/guidelines.md create mode 100644 ui-implement/skills/code.md create mode 100644 ui-implement/skills/completion.md create mode 100644 ui-implement/skills/controller.md create mode 100644 ui-implement/skills/dispatch.md create mode 100644 ui-implement/skills/ingest.md create mode 100644 ui-implement/skills/plan.md create mode 100644 ui-implement/skills/publish.md create mode 100644 ui-implement/skills/respond.md create mode 100644 ui-implement/skills/revise.md create mode 100644 ui-implement/skills/validate.md create mode 100644 ui-implement/templates/01-context.md create mode 100644 ui-implement/templates/story-testplan.md diff --git a/AGENTS.md b/AGENTS.md index 875149ce..3301e847 100644 --- a/AGENTS.md +++ b/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/ diff --git a/README.md b/README.md index acec82d5..fe3bb3f4 100644 --- a/README.md +++ b/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 diff --git a/ui-implement/README.md b/ui-implement/README.md new file mode 100644 index 00000000..523e7830 --- /dev/null +++ b/ui-implement/README.md @@ -0,0 +1,224 @@ +# 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) +``` + +## 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). diff --git a/ui-implement/SKILL.md b/ui-implement/SKILL.md new file mode 100644 index 00000000..ab7260ff --- /dev/null +++ b/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`. diff --git a/ui-implement/commands/code.md b/ui-implement/commands/code.md new file mode 100644 index 00000000..b4769b29 --- /dev/null +++ b/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 diff --git a/ui-implement/commands/ingest.md b/ui-implement/commands/ingest.md new file mode 100644 index 00000000..daee6e7b --- /dev/null +++ b/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 diff --git a/ui-implement/commands/plan.md b/ui-implement/commands/plan.md new file mode 100644 index 00000000..48232dfb --- /dev/null +++ b/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 diff --git a/ui-implement/commands/publish.md b/ui-implement/commands/publish.md new file mode 100644 index 00000000..c73f9376 --- /dev/null +++ b/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 diff --git a/ui-implement/commands/respond.md b/ui-implement/commands/respond.md new file mode 100644 index 00000000..c1283156 --- /dev/null +++ b/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 diff --git a/ui-implement/commands/revise.md b/ui-implement/commands/revise.md new file mode 100644 index 00000000..411e29e2 --- /dev/null +++ b/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 diff --git a/ui-implement/commands/validate.md b/ui-implement/commands/validate.md new file mode 100644 index 00000000..a6e0a1af --- /dev/null +++ b/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 diff --git a/ui-implement/guidelines.md b/ui-implement/guidelines.md new file mode 100644 index 00000000..bcdb3489 --- /dev/null +++ b/ui-implement/guidelines.md @@ -0,0 +1,92 @@ +# UI Implement Workflow Guidelines + +## Principles + +- The implementation must satisfy the **story's acceptance criteria** as written. Do not reinterpret, expand, or reduce scope. +- **Tests validate contracts, not implementations.** Test through public component/hook interfaces. Every behavioral path reachable through a public interface is a distinct contract that needs its own test case. Tests should remain valid if the implementation were rewritten. +- **Unit tests are always required.** Test components via their rendered output and user interactions, and hooks via their return values and effects. Integration/e2e test stubs are written after all tasks complete, following the project's existing patterns (if any). +- Follow the **project's existing patterns.** Read neighboring components and tests before writing new code. Match naming conventions, file organization, test style, and error handling patterns. +- **Follow the project's commit format** as discovered during `/ingest` and recorded in the validation profile. Commit one logical unit of work per commit — typically one commit per plan task. Don't batch everything into a single commit, but don't create a commit per file either. +- Each completed story must leave the system in a **stable state**. All tests pass, linter is clean, no regressions. +- The implementation plan is a **living document**. Update `02-plan.md` as tasks are completed so it reflects current progress. +- **Discover, don't assume.** The project's build commands, test framework, design system, i18n library, and commit format are discovered during `/ingest` and recorded in the validation profile. Never hardcode assumptions about specific tools (Vitest, Cypress, PatternFly, react-i18next, or any other library). +- **Comments must earn their place — and describe the final state, not the journey.** Default to no comments unless the project's conventions require doc comments on exported symbols. Add a comment only when the *why* is non-obvious. Do not: + - Restate what the function signature or component props already say + - Reference abandoned approaches or prior states + - Cite design-document sections or ticket IDs + - Embed verification notes ("confirmed by inspection", "matches the design's table") + - Document callers or consumers ("used by X", "consumed by Y") + - Cross-reference private functions from public doc comments + - Repeat the same explanation at every usage site of a shared mechanism + + Code comments, commit messages, PR descriptions, and test names describe what the code does now. A reader who has never seen the design document or the prior codebase must find every comment useful. Internal artifacts (implementation report, review responses, plan) may document the journey. + +## UI-Specific Principles + +- **Design system compliance.** Use the project's discovered design system components and tokens. Do not introduce raw HTML elements or inline styles when a design system equivalent exists. If a pattern is not covered by the design system, note it in the implementation report. +- **Internationalization.** Wrap all user-visible strings with the project's discovered i18n mechanism. If the project has no i18n, note the gap but do not introduce one without user approval. +- **Accessibility.** Every interactive element must be keyboard-navigable and have appropriate ARIA attributes. Follow the project's existing accessibility patterns. Test accessibility contracts (role, aria-label, keyboard interaction) alongside functional contracts. +- **Permission-aware rendering.** When the design specifies permission-gated UI, use the project's discovered permission/RBAC patterns. Do not hardcode permission checks. +- **State completeness.** Every data-dependent component must handle loading, error, and empty states unless the design explicitly excludes them. +- **Component composition.** Prefer composition over prop drilling. Follow the project's existing patterns for state management, context usage, and data fetching. + +## Shared Content Rules + +Read and follow `../_shared/content-rules.md` for generated-content rules. Those standards apply to all +artifacts and published output from this workflow. + +## Hard Limits + +- No fabricated implementations. Every code change must trace to a story requirement, acceptance criterion, or explicit user direction. +- No auto-advancing between phases. Always wait for the user. +- No publishing (creating PRs, pushing branches) without explicit user approval. +- No Jira modifications. This workflow is read-only with respect to Jira. +- **No scope creep.** Do not refactor adjacent components, add features beyond the story, or "improve" code you didn't need to change. If you discover something that should be fixed, note it in the implementation report — don't fix it silently. +- **No test shortcuts.** Do not write tests that test implementation details, mock internal component logic, or exist solely to increase coverage numbers. Every test must validate a behavioral contract through a public interface (rendered output, user events, hook return values). +- No committing to `main` directly. Use a feature branch. +- No force-push or destructive git operations. +- **No hardcoded tool assumptions.** Never assume a specific test runner (Vitest, Jest, Mocha), design system (PatternFly, MUI, Chakra), i18n library (react-i18next, FormatJS), or e2e framework (Cypress, Playwright). All tooling is discovered during `/ingest`. + +## Safety + +- Show your work before finalizing. After `/plan`, present the task breakdown for review — do not assume it's ready. +- Before `/code`, confirm the feature branch name and starting point with the user. +- Before `/publish`, confirm the PR target branch and description with the user. +- **Read before writing.** Before modifying any file, read it first. Before writing tests for a component, read existing tests in that package to match patterns. +- **Deviation transparency.** If during `/code` you encounter something unexpected (a bug in adjacent code, a missing dependency, a design assumption that doesn't hold), report it. Apply deviation rules (see `skills/code.md`) but never silently change approach. +- Flag assumptions explicitly. If the story or design doesn't specify something and you made a judgment call, note it in the implementation report. + +## Quality + +- Follow the project's `AGENTS.md` and `CLAUDE.md` for coding conventions, testing standards, and contribution guidelines. +- **Contract-based test coverage.** Identify all behavioral contracts of each public component/hook — every meaningful input (props, user interaction, state change) that produces distinct observable behavior. Write test cases that exercise each one. Don't test internal state or implementation details, but do ensure every behavior the public interface promises is verified through its observable effects (rendered output, fired events, returned values). +- Use code coverage tooling as a **signal, not a target.** If coverage shows an uncovered branch inside a component, ask: "Is there a behavioral contract I missed?" Write a test for the *behavior*, not the uncovered line. +- **Low coverage through public APIs is a design signal.** If new code cannot reach the project's minimum coverage threshold (discovered during `/ingest`, defaults to 90%) through tests that invoke public interfaces, the component is likely too coarse-grained — too much behavior is hidden behind a narrow API. The response is to decompose into smaller components with more testable interfaces, not to write tests that reach into internals. +- Run the project's full validation suite (lint, unit tests, type checking) before considering implementation complete. +- Self-review code before presenting. Check for: unused imports, dead code, missing error handling, inconsistent naming, violations of project conventions, missing i18n wrapping, accessibility gaps. + +## Escalation + +Stop and request human guidance when: + +- Story acceptance criteria are ambiguous or contradictory +- The implementation approach requires architectural decisions not covered by the design document +- A story dependency is unmerged and blocks meaningful progress +- The design document's guidance contradicts the current state of the codebase +- Test infrastructure is unavailable or broken (not a code problem — an environment problem) +- A code change would affect components outside the story's scope +- Confidence in the implementation approach is low +- The ui-design document specifies components or patterns that conflict with the project's discovered design system +- The handoff document's interaction specs are incomplete or contradictory +- No unit test framework exists and the user has not approved introducing one + +## Working With the Project + +This workflow gets deployed into different projects. Respect the target project: + +- Read and follow the project's own `AGENTS.md` or `CLAUDE.md` files +- Adopt the project's coding conventions, component patterns, and commit message format +- Use the project's build, test, and lint commands as discovered during `/ingest` +- Respect the project's CI/CD pipeline expectations +- Use the project's design system components and tokens — do not introduce alternatives +- Follow the project's i18n, routing, and state management patterns diff --git a/ui-implement/skills/code.md b/ui-implement/skills/code.md new file mode 100644 index 00000000..9621c23d --- /dev/null +++ b/ui-implement/skills/code.md @@ -0,0 +1,571 @@ +--- +name: code +description: Write unit tests and production code via TDD, then integration/e2e test stubs, committing incrementally. +--- + +# Code Skill + +You are a principal front-end engineer. Your job is to execute the implementation +plan by writing tests and production code, following the project's conventions +and committing incrementally. + +## Your Role + +Work through the plan's task breakdown, writing contract-based unit tests and +production code for each task. Use TDD as the internal discipline: write +tests that define the behavioral contract, then write code that satisfies +the contract. Commit each logical unit of work independently. After all +tasks complete, write integration/e2e test stubs following the project's +existing patterns (if any). + +## Critical Rules + +- **Follow the plan.** Execute tasks in the order specified in `02-plan.md`. If you need to deviate, update the plan and note why. +- **Read before writing.** Before modifying any file, read it. Before writing tests for a component, read existing tests in that package. +- **Tests validate contracts, not implementations.** Test through public interfaces only — rendered output, user interactions, hook return values. Every behavioral path reachable through the public interface needs a test case. Tests should remain valid if the implementation were rewritten. +- **Unit tests are always required.** Test components via rendered output and user events. Test hooks via their return values and effects. +- **One commit per plan task.** Each commit must follow the project's commit format (from the validation profile) and be independently meaningful. Don't batch everything into a single commit, but don't create a commit per file either — one logical unit of work per commit. +- **Update the plan.** Mark tasks as completed in `02-plan.md` as you go. On re-invocation, check the plan to see what's already done. +- **No scope creep.** Do not refactor adjacent components, fix unrelated bugs, or add features beyond the story. Note discoveries in the implementation report. +- **Integration/e2e test stubs come last.** Write them only after all plan tasks are complete, as a separate commit. They follow the project's existing e2e patterns (if any). + +## Process + +### Step 1: Read the Plan and Context + +Read these files: +1. `.artifacts/ui-implement/{issue-key}/02-plan.md` (implementation plan) +2. `.artifacts/ui-implement/{issue-key}/01-context.md` (story context and validation profile) +3. `.artifacts/ui-implement/{issue-key}/testplan.md` (story-scoped testplan, if exists) +4. The project's `AGENTS.md` and/or `CLAUDE.md` (coding conventions) + +If the plan doesn't exist, tell the user that `/plan` should be run first. + +### Step 2: Determine Starting Point + +Check the plan for task completion status: +- Tasks with **Status:** `Done` are complete — skip them +- The first task with **Status:** `Pending` is where to start +- On first invocation, all tasks will be Pending — start with Task 0 (if present) or Task 1 + +Read the `## Branch` section of `02-plan.md` to get the planned branch +name and Local Base. Then check the current branch: + +```bash +git branch --show-current +``` + +If the user is already on a feature branch (not `main`, `master`, or the +plan's Local Base branch), ask whether to use the current branch or create the +planned branch. If the user wants to use the current branch, update the +`## Branch` section in `02-plan.md` to reflect the actual branch name. + +Otherwise, sync with the upstream base before creating or checking out +the branch. + +Check the **Repository Topology** section of `01-context.md`. Read +`{owner}/{repo}` from the **Origin** field. If the repo is a fork, sync +the fork's base branch with upstream first: + +```bash +gh repo sync {owner}/{repo} --branch {pr-target} +``` + +If `gh repo sync` fails, warn the user that the fork may be behind +upstream. + +Then fetch, regardless of topology: + +```bash +git fetch origin +``` + +If the fetch fails (network issues, authentication expired), warn the user +that remote branch status cannot be verified. Proceed with local-only +information and note the caveat. + +Check if the planned branch already exists: + +```bash +git branch --list {branch-name} +``` + +```bash +git branch -r --list origin/{branch-name} +``` + +Depending on results: + +```bash +# If branch exists locally: +git checkout {branch-name} + +# If branch does not exist locally but exists on remote: +git checkout -b {branch-name} origin/{branch-name} + +# If branch doesn't exist at all — create from the fetched base: +git checkout -b {branch-name} origin/{local-base} +``` + +If the branch already existed (locally or on remote), sync it with +the base branch. Before syncing, verify the working tree is clean: + +```bash +git status --porcelain +``` + +If output is non-empty, report the uncommitted files to the user and +ask how to proceed (stash, commit, or abort) before any rebase/merge +operation. + +Check whether a PR has already been created by looking for +`.artifacts/ui-implement/{issue-key}/publish-metadata.json`. + +If no PR exists yet, rebase: + +```bash +git rebase origin/{local-base} +``` + +If a PR already exists, merge instead — rebasing a branch with an +open PR requires a force-push, which orphans review comments and +disrupts reviewers: + +```bash +git merge origin/{local-base} +``` + +If conflicts occur during either operation, follow the same conflict +handling as Step 3h (stop, show conflicts, offer to resolve, proceed +only with user approval). + +Verify the starting point: + +```bash +git log --oneline -5 +``` + +### Step 3: Execute Tasks + +For each task in the plan, follow this cycle. **The ordering is +intentional and must be followed: tests before implementation.** Write +the unit tests first, verify they fail for the right reason (the +production code doesn't exist yet), then write the implementation that +makes them pass. Do not write the implementation first and add tests +after — that inverts the discipline and allows implementation details +to shape the tests rather than the behavioral contract. If a task's +Files section lists both test files and implementation files, always +create or modify the test files before the implementation files. + +**Exception — Task 0 (test framework introduction):** If the plan +includes Task 0 for introducing a unit test framework, execute it as +specified in the plan (install, configure, smoke test). This task does +not follow TDD since it is infrastructure setup, not behavioral code. + +#### 3a: Read Affected Files + +Before making any changes, read: +- Every file listed in the task's "Files" section +- Existing test files in the same directory/module (to match patterns) +- Any components, hooks, or types referenced by the task + +#### 3b: Write Unit Tests FIRST + +Write tests that define the behavioral contracts for this task: + +1. **Identify contracts:** What observable behaviors does this change introduce + or modify? For components: what renders, what responds to user events, what + ARIA attributes are present. For hooks: what values are returned, what + side effects occur. +2. **Write test cases:** Use the project's discovered test framework and + conventions (from the validation profile and neighboring tests). +3. **Cover behavioral paths:** For each public component/hook, test every + meaningful input that produces distinct observable behavior. This + includes: + - **Components:** rendering with different props, user interactions + (click, type, keyboard), loading/error/empty states, accessibility + attributes (roles, aria-labels, keyboard navigation) + - **Hooks:** return values for different inputs, state transitions, + error handling, cleanup/unmount behavior +4. **Mock only external dependencies.** Mock API calls, router, i18n + provider, permission context — whatever the project's patterns use. Do + not mock internal component logic or child components (unless the + project's test patterns explicitly do so). +5. **Wrap with required providers.** If the project's components need + context providers (router, i18n, theme, query client), use the project's + existing test utilities or create a render wrapper matching existing + patterns. +6. **Name tests after the contract they validate,** not after bugs + discovered during development. + +#### 3c: Write Implementation (after tests exist) + +Write the production code that makes the tests from 3b pass: + +1. Follow existing component/hook patterns in the project +2. Match naming conventions, file organization, and code style +3. Use the project's discovered design system components — do not + introduce raw HTML elements or inline styles when a design system + equivalent exists +4. Wrap all user-visible strings with the project's discovered i18n + mechanism (if one exists) +5. Include appropriate ARIA attributes and keyboard event handlers + for interactive elements +6. Handle loading, error, and empty states as specified in the plan +7. Apply permission gates as specified in the plan +8. Keep changes focused on what the task describes +9. **Comments must earn their place.** Default to writing no comments + unless the project's lint or style conventions require doc comments + on exported symbols. Add a comment only when the *why* is non-obvious. + + **Journey narration anti-patterns** — never include these: + - Referencing a prior architecture or design documents + - Citing section numbers or ticket IDs + - Embedding verification notes + - Counting methods/fields as proof of completeness + + **Coupling anti-patterns** — never include these: + - Cross-referencing private functions from public doc comments + - Documenting callers or consumers + - Repeating the same explanation at every usage site + +#### 3d: Run Tests + +Look up the test commands from the **Pre-PR Checks** section of +`01-context.md`. Each entry has a purpose label (e.g., "unit test", +"type check"). Match the label to the type of tests you wrote: + +1. Run the unit test command for the specific module/file first (fast feedback) +2. If type checking is a separate command, run it to verify TypeScript types + +Run each test command as a separate invocation — do not chain commands. +Fix any failures before proceeding. + +If a test failure is ambiguous, use diagnostic failure routing (see below). + +#### 3e: Lint and Format + +Before committing, run the fast quality checks on the files changed by +this task. Look up the lint and format commands from the **Pre-PR Checks** +section of `01-context.md` (entries labeled "lint", "format", or similar). + +Run them scoped to the affected files or packages where possible. Fix +any issues before committing — formatting and lint errors should be +part of the task's commit, not a separate cleanup commit later. + +If the lint tool reports errors and all error locations are in files +you did not modify in this task, the errors are from pre-existing code +or downstream consumers not yet updated after an interface change — skip +the lint for this commit and note the skip in the implementation report +(Deviations section). If errors appear in files you changed, fix them +before committing. The full validation suite in `/validate` will catch +any remaining issues once all tasks are complete and the code compiles. + +Do not run the full validation suite here — save expensive checks +(full test suite, coverage analysis) for `/validate`. + +#### 3f: Code Review + +Stage the task's changes first — the review and commit steps both +operate on the staged diff: + +```bash +git add {specific files} +``` + +Run the self-review gate on the staged changes. + +Read and follow `../../_shared/recipes/self-review-gate.md` with these +parameters: + +| Parameter | Value | +|-----------|-------| +| DIFF_COMMAND | `git diff --cached` | +| MAX_ROUNDS | `1` | +| CONTEXT_FILES | `.artifacts/ui-implement/{issue-key}/01-context.md`, `.artifacts/ui-implement/{issue-key}/02-plan.md` (if they exist) | +| SUPPLEMENTARY_CRITERIA | UI-specific: (1) Design system compliance — are design system components used instead of raw HTML where equivalents exist? (2) i18n — are all user-visible strings wrapped with the i18n mechanism? (3) Accessibility — do interactive elements have ARIA attributes and keyboard handlers? (4) State completeness — are loading, error, and empty states handled where applicable? | + +If the gate reports FLAG (unfixed CRITICAL or HIGH findings), stop and +present the findings to the user before committing. + +If the gate made code fixes, re-stage the affected files, then re-run +the task-scoped tests (Step 3d) and fast quality checks (Step 3e) to +verify the fixes. Only proceed to commit once checks pass. Note any +dismissed findings in the implementation report (Discoveries section) +so there is a paper trail. + +**Test plan reconciliation (if story-scoped testplan exists):** + +After the self-review gate passes, check whether this task has TC IDs +mapped to it in the Test Plan Coverage matrix of `02-plan.md`. If it +does, verify each mapped TC ID before proceeding to commit: + +1. For each mapped TC ID, locate its entry in `testplan.md`. If a + mapped TC ID does not exist in the testplan, stop and report the + inconsistency. Read the full test case entry (the Preconditions, + Steps, and Expected Results sections). If any of these sections is + missing, stop and report the testplan as malformed. +2. Verify that a test exists (written in Step 3b or a prior task) + whose assertions validate the Expected Results described in the + test case. The match is behavioral, not textual — the test must + exercise the described scenario and assert the described outcomes. +3. If a TC ID mapped to this task has no corresponding test with + sufficient assertion depth, write the missing test (Step 3b), run + it (Step 3d), run the fast quality checks (Step 3e), stage the new + files (`git add`), re-run the review gate, then re-check. + +This is a hard gate — the task cannot proceed to commit until every +mapped TC ID has coverage. A TC ID may be treated as N/A only if the +plan's Test Plan Coverage matrix already marks it N/A with a non-empty +rationale — the code phase must not invent N/A exemptions that the +plan did not authorize. + +If no story-scoped testplan exists and `02-plan.md` has no Test Plan +Coverage section, skip this check. However, if `02-plan.md` has TC +mappings but `testplan.md` is missing or malformed, stop and report +the inconsistency. + +#### 3g: Commit + +The changes are already staged from Step 3f. Create the commit: + +```bash +git commit -m "{issue-key}: {task description}" +``` + +Follow the commit format from the **Commit Format** section of +`01-context.md`. The commit message must: +- Use the discovered format +- Describe what the code does, not the development journey +- Be independently meaningful + +If the commit fails (e.g., rejected by pre-commit hooks), diagnose and +fix the issue before proceeding to the sync step. + +#### 3h: Sync with Base + +After committing, rebase onto the latest base branch to keep subsequent +tasks building against head-of-line. + +Check the **Repository Topology** section of `01-context.md`. Read +`{owner}/{repo}` from the **Origin** field. If the repo is a fork, sync +the fork with upstream first: + +```bash +gh repo sync {owner}/{repo} --branch {pr-target} +``` + +Then, regardless of topology: + +```bash +git fetch origin +``` + +If the fetch fails (network issues), warn the user and continue — the +sync is best-effort during development. + +Check whether new commits exist on the base branch: + +```bash +git rev-list --count HEAD..origin/{local-base} +``` + +If the count is 0, no new upstream commits exist — skip the rebase and +test re-run, and proceed directly to Step 3i. + +If new commits exist, check whether a PR has already been created by +looking for `.artifacts/ui-implement/{issue-key}/publish-metadata.json`. + +**If no PR exists yet** (pre-publish), rebase: + +```bash +git rebase origin/{local-base} +``` + +**If a PR already exists** (post-publish), merge instead: + +```bash +git merge origin/{local-base} +``` + +If the operation applies cleanly, re-run the task's tests to confirm +the committed work still passes against the updated base. If tests +fail, diagnose using the failure routing in Step 4. + +**If there are conflicts:** + +1. Stop and report the conflicting files to the user +2. Show the conflict markers so the user can see what's colliding +3. Offer to resolve the conflicts — describe what you would do +4. Proceed only after the user approves the resolution (or resolves it + themselves) +5. After resolution, run `git rebase --continue` or commit the merge + resolution as appropriate, then re-run the task's tests + +#### 3i: Update Plan + +Mark the task as completed in `02-plan.md`: +- Change `Pending` to `Done` + +Update the status immediately after each task, not in bulk at the end. +This is the checkpoint that allows the session to resume correctly if +interrupted. + +### Step 3-post: Write Integration/E2E Test Stubs + +After all plan tasks are complete (all marked `Done`), check whether the +plan includes an integration/e2e test stubs task. If it does: + +1. Read the project's existing e2e test files (discovered during `/ingest`) + to match patterns — file naming, describe block structure, test + utilities, selectors +2. Write stub test files with: + - Describe blocks for each planned scenario + - Pending/skipped test cases with descriptive names + - Comments noting what each test should verify + - Proper imports matching the project's e2e patterns +3. Do **not** write full e2e test implementations — those are for `[QE]` + stories. Stubs provide scaffolding only. +4. Run lint on the stub files +5. Commit separately: + +```bash +git add {stub files} +git commit -m "{issue-key}: add integration/e2e test stubs" +``` + +If the project has no e2e framework, skip this step entirely. + +### Step 4: Diagnostic Failure Routing + +When tests fail, diagnose **where** the problem is before fixing: + +| Diagnosis | Symptom | Action | +|-----------|---------|--------| +| **Test is wrong** | Test asserts implementation details, or the assertion doesn't match the contract | Fix the test | +| **Implementation is wrong** | Component doesn't render correctly, hook returns wrong value | Fix the implementation | +| **Plan was wrong** | Component design is flawed, approach doesn't work | Update the plan, note the deviation, flag to user if significant | +| **Existing code has a bug** | Pre-existing issue revealed by new tests | Note in implementation report — do not fix unless it blocks the story | +| **Provider/wrapper missing** | Test fails because a required context provider is not in the test render wrapper | Add the provider to the test setup | +| **Environment issue** | Test infrastructure unavailable, missing dependency | Report to user — this is not a code problem | + +### Step 5: Deviation Rules + +During implementation, you may encounter unexpected situations: + +| Situation | Action | Approval | +|-----------|--------|----------| +| Minor bug in adjacent component that blocks the story | Fix it, add a test, commit separately, note in report | Auto | +| Missing i18n key for a string the design requires | Add it, note in report | Auto | +| Missing design system component (no equivalent exists) | **Stop and ask the user** — use raw HTML or request design system addition? | Required | +| Architectural question (new shared hook, context provider, breaking change) | **Stop and ask the user** | Required | +| Story guidance contradicts current codebase state | **Stop and ask the user** | Required | +| Implementation is significantly simpler than planned | Note in report, continue | Auto | +| Implementation is significantly more complex than planned | **Stop and ask the user** — the story may need re-scoping | Required | +| Accessibility requirement unclear or conflicting | **Stop and ask the user** — a11y must not be guessed | Required | + +### Step 6: Write Reports + +After all tasks are complete (or if interrupted), write: + +**Test report** (`.artifacts/ui-implement/{issue-key}/03-test-report.md`): + +```markdown +# Test Report — {issue-key} + +## Unit Tests Written + +| Test File | Tests | Contracts Covered | +|-----------|-------|-------------------| +| {path} | {count} | {brief description — rendered output, user interactions, hook behavior} | + +## Integration/E2E Test Stubs + +| Test File | Stubs | Scenarios Covered | +|-----------|-------|-------------------| +| {path} | {count} | {brief description} | + +{If no stubs written: "No integration/e2e test stubs — project has no e2e + framework." or "No integration/e2e test stubs — not included in plan."} + +## Test Plan Reconciliation + +{Include only if story-scoped testplan exists. Omit entirely otherwise.} + +| TC ID | Title | Outcome | Notes | +|-------|-------|---------|-------| +| TC-FR1-01 | {title} | verified | Test existed, assertions matched | +| TC-FR1-02 | {title} | written | Test added during task execution | +| TC-NFR1-01 | {title} | N/A | See Deviations from Plan | + +## Coverage Notes + +{Qualitative assessment of what behavioral paths are covered and any + known gaps.} +``` + +**Implementation report** (`.artifacts/ui-implement/{issue-key}/04-impl-report.md`): + +```markdown +# Implementation Report — {issue-key} + +## Changes Summary + +| File | Action | Description | +|------|--------|-------------| +| {path} | {created/modified} | {brief description} | + +## Commits + +| Hash | Message | +|------|---------| +| {short hash} | {commit message} | + +## UI Cross-Cutting Concerns Applied + +| Concern | Applied | Notes | +|---------|---------|-------| +| Design system | {components used} | | +| i18n | {keys added} | | +| Accessibility | {ARIA/keyboard added} | | +| Permissions | {gates applied or N/A} | | +| Loading/error/empty | {states handled} | | + +## Deviations from Plan + +{Any deviations from the original plan, with rationale. + If none: "No deviations from the implementation plan."} + +## Discoveries + +{Anything notable found during implementation that doesn't affect this + story but may be relevant to the team. E.g., adjacent bugs, missing + i18n in existing components, accessibility gaps in existing code. + If none: "No notable discoveries."} + +## Status + +{Complete / Incomplete — if incomplete, note which tasks remain and why.} +``` + +## Output + +- Test files in the source repo (on the feature branch) +- Production code in the source repo (on the feature branch) +- Integration/e2e test stubs (if applicable) +- Incremental commits (following the project's commit format) +- `.artifacts/ui-implement/{issue-key}/02-plan.md` (updated with task status) +- `.artifacts/ui-implement/{issue-key}/03-test-report.md` +- `.artifacts/ui-implement/{issue-key}/04-impl-report.md` + +## When This Phase Is Done + +Report your results: +- Tasks completed and their commits +- Tests written (unit tests with contract coverage summary) +- Integration/e2e test stubs written (if applicable) +- Any deviations from the plan +- Any discoveries +- Overall implementation status + +Then return to the invoking workflow router for completion guidance. diff --git a/ui-implement/skills/completion.md b/ui-implement/skills/completion.md new file mode 100644 index 00000000..ad7276f9 --- /dev/null +++ b/ui-implement/skills/completion.md @@ -0,0 +1,34 @@ +--- +name: completion +description: Recommend next steps after one attended ui-implement phase. +--- + +# UI Implement Phase Completion + +After the completed `PHASE` reports its results, recommend the best next step +for the actual outcome, mention relevant alternatives briefly, and stop for the +user. + +- **ingest:** Recommend `/plan` unless the story context has blocking gaps. If + the story is contradictory or incomplete, recommend clarification from the + story author before planning. If no unit test framework was found and the + context recommends introducing one, note that `/plan` will include a Task 0 + for framework setup. +- **plan:** Recommend `/revise` for user-requested changes, or `/code` when the + user has already reviewed and accepted the plan. +- **revise:** Recommend `/code` when the user is satisfied, or another + `/revise` round when further changes remain. +- **code:** Recommend `/validate`. If implementation exposed a plan gap, note + the inline plan update or offer `/plan` when redesign requires user review. +- **validate:** Recommend `/publish` only when validation passed. When failures + remain, recommend fixing them and rerunning `/validate`; offer `/plan` for a + design concern or ambiguous acceptance criterion that requires re-scoping. +- **publish:** Recommend `/respond` when review comments arrive; otherwise the + workflow is complete for now. +- **respond:** Recommend `/validate` after code changes, another `/respond` + round while comments remain, or note completion when the PR is approved and + no work remains. + +The user may start at `/code` with an existing plan or partial implementation, +and may skip `/publish` and `/respond` when working locally. Never auto-advance +between attended phases. diff --git a/ui-implement/skills/controller.md b/ui-implement/skills/controller.md new file mode 100644 index 00000000..af3f6ae9 --- /dev/null +++ b/ui-implement/skills/controller.md @@ -0,0 +1,114 @@ +--- +name: controller +description: Discover and route ambiguous UI story implementation requests. +--- + +# UI Implement Workflow Controller + +Use this controller for workflow discovery and ambiguous-input routing. Once a +phase is selected, delegate its execution and completion guidance to the +lightweight dispatcher. + +## Phases + +1. **Ingest** (`/ingest`) — `ingest.md` + Fetch the Jira story, load ui-design/PRD/handoff context, explore the + relevant codebase, discover the UI toolchain, and build a validation profile. + +2. **Plan** (`/plan`) — `plan.md` + Design the implementation approach: task breakdown, component/hook + interfaces, test strategy, and risk assessment. + +3. **Revise** (`/revise`) — `revise.md` + Incorporate user feedback into the implementation plan. Repeatable. + +4. **Code** (`/code`) — `code.md` + Write unit tests and production code via TDD (task by task), then write + integration/e2e test stubs after all tasks complete. Commit incrementally. + +5. **Validate** (`/validate`) — `validate.md` + Run the full validation suite (tests, lint, type checking, coverage), + iterate on gaps. + +6. **Publish** (`/publish`) — `publish.md` + Push the feature branch and create a draft PR in the source repo. + +7. **Respond** (`/respond`) — `respond.md` + Fetch and address PR reviewer comments. Repeatable. + +## Workspace + +All work happens in the **source repo** — this workflow modifies code directly. +Planning artifacts live in `.artifacts/ui-implement/{issue-key}/` (gitignored). +Code changes live on a feature branch in the source repo. + +### Artifact directory + +All working artifacts are stored in `.artifacts/ui-implement/{issue-key}/` within +the source repo: + +| Artifact | File | Written by | +|----------|------|------------| +| Story context | `01-context.md` | `/ingest` | +| Story testplan | `testplan.md` | `/ingest` (when test cases match) | +| Implementation plan | `02-plan.md` | `/plan`, `/revise`, `/code` | +| Test report | `03-test-report.md` | `/code` | +| Implementation report | `04-impl-report.md` | `/code` | +| Validation report | `05-validation-report.md` | `/validate` | +| PR description | `06-pr-description.md` | `/publish` | +| Publish metadata | `publish-metadata.json` | `/publish` | +| Review responses | `07-review-responses.md` | `/respond` | + +## How to Execute a Phase + +Set `PHASE` to the selected phase, then read `dispatch.md` and follow it. The +dispatcher owns phase announcement, override resolution, execution, and +completion routing for both built-in phases and project overrides. + +## Starting the Workflow + +When the user provides a Jira issue key or URL: +1. Set `PHASE=ingest`. +2. Read `dispatch.md` and follow it. + +If the user invokes a specific command (e.g., `/code`), set `PHASE` to that +command's phase, then read `dispatch.md` and follow it. Do not force the user +through earlier phases. + +For any other input, summarize the available phases, ask the user for a Jira +issue key or URL or a specific phase command, and stop without reading +`dispatch.md`. + +## Error Handling + +If a phase cannot complete because of an operational error (for example, a +Jira MCP, build, or git error): + +1. **Stop immediately.** Do not advance to the next phase. +2. **Report the error** to the user with the specific error message. +3. **Offer options:** retry the failed step, skip the phase (if optional), or escalate. + +Do not fabricate results when a tool call fails. Do not silently continue +past errors. A completed validation report with a failing verdict is a valid +phase outcome; route it through `completion.md` for fix-and-rerun guidance. + +## Context Management + +When the AI detects that its own output quality is degrading (e.g., it +misses details, repeats itself, or loses track of earlier decisions), +consider spawning the next phase as a subagent with a fresh context window. +This is self-monitoring by the AI, not something a human operator watches. Load the subagent with +the skill file for the phase being executed, the relevant artifact files from +`.artifacts/ui-implement/{issue-key}/`, and the project's `AGENTS.md`/`CLAUDE.md`. + +This is a recommendation, not a requirement — not all AI runtimes support +subagent spawning. + +## Rules + +- **Never auto-advance.** Always wait for the user between phases. +- **Recommendations come from `completion.md`.** Phase skills report findings; + the completion guide provides the authoritative next-step model. +- **Jira is read-only.** The `/ingest` phase reads from Jira but never modifies it. No phase in this workflow writes to Jira. +- **Plan evolves during implementation.** `/code` updates `02-plan.md` as tasks are completed. This is expected, not a sign of plan failure. +- **Validation is mandatory before publishing.** Never recommend `/publish` unless `/validate` has passed. diff --git a/ui-implement/skills/dispatch.md b/ui-implement/skills/dispatch.md new file mode 100644 index 00000000..fedf1803 --- /dev/null +++ b/ui-implement/skills/dispatch.md @@ -0,0 +1,48 @@ +--- +name: dispatch +description: Resolve and execute one explicitly requested ui-implement phase. +--- + +# UI Implement Phase Dispatch + +Require `PHASE` to be one of `ingest`, `plan`, `revise`, `code`, `validate`, +`publish`, or `respond`. If it is missing or unsupported, report the valid +phases and stop before resolving a filename. + +Before dispatching, initialize `COMPLETION_CONSUMED=false` and read the project's +`AGENTS.md` or `CLAUDE.md` only if neither is already in the session. For +`PHASE=ingest`, do not glob this workflow, load `guidelines.md` or `gh-stack`, or +call `GetDynamicTools`; these guards apply before loading either a built-in +phase or a project override. + +Announce `Starting /{PHASE}.` and read and follow +`../../_shared/recipes/phase-override-resolution.md` with `WORKFLOW=ui-implement` +and `PHASE_FILE={PHASE}.md`. Read and execute the resolved phase file, passing +through the command context unchanged. + +The built-in fallback is the phase file beside this dispatcher. Follow the +phase through its reporting step. Normalize the recipe's supported exits to a +return to this dispatcher: an invoking-router return, a request for this +workflow's completion guide, or a return to this workflow's controller. Map +`COMPLETION_HANDOFF=router-defined` to the invoking-router return. This mapping +applies during override validation as well as execution. Normalize the handoff +without executing its destination and leave `COMPLETION_CONSUMED=false`. Then +read `completion.md` once and follow its guidance for `PHASE`; the dispatcher +is the only component that reads the completion guide. + +Legacy completion instructions may say to follow `controller.md` only if it +is already in the session. After such a phase finishes its steps and report, +treat it as a supported return even when that condition skips reading the +controller. Preserve the loading condition; do not load the controller just to +complete the phase. + +Controller-return normalization preserves the completion contract of existing +project overrides and remains supported. Prefer an invoking-router return for +new ui-implement phases and overrides; legacy exits do not require migration. + +If the recipe rejects an override, continue with its built-in fallback. Stop +without reading `completion.md` only if that fallback cannot be resolved, an +operational error prevents the phase from completing, or the executing phase +lacks supported completion behavior. Report the specific failure. A completed phase +report with a failing verdict, including `validate.md` reporting `FAIL`, is a +valid outcome: read `completion.md` so it can provide fix-and-rerun guidance. diff --git a/ui-implement/skills/ingest.md b/ui-implement/skills/ingest.md new file mode 100644 index 00000000..ea373329 --- /dev/null +++ b/ui-implement/skills/ingest.md @@ -0,0 +1,383 @@ +--- +name: ingest +description: Fetch the Jira story, load ui-design/PRD/handoff context, explore the codebase, discover the UI toolchain, and build a validation profile. +--- + +# Ingest Story Context Skill + +Fetch the Jira story, load upstream ui-design/PRD/handoff/api-findings slices, +index the affected code, discover the UI toolchain, and write `01-context.md` +for `/plan`. + +## Critical Rules + +- Jira is read-only. Capture, don't implement. Note unknowns explicitly. +- Explore relevant areas only. Don't map the entire codebase. Focus on components the story will affect. +- Re-invocation diffs before overwriting. If `01-context.md` already exists, preserve it before exploring. After compiling new context, diff against the previous version and present changes to the user before overwriting (see Steps 2a and 8a). +- Ingest is an index. `/plan` opens cited files. Paths, section refs, signatures — not dumps. +- Never Read the same path twice. Never Grep the same (path, pattern) pair twice. +- Do not glob this workflow. Do not load `guidelines.md` or `gh-stack`. +- Do not re-read `AGENTS.md` / `CLAUDE.md` if already in session. +- Grep locates; Read loads. Never grep `.`. Never grep `-A`/`-B`/`-C`. Never grep `.git/`. +- Do not glob the docs repo root. After Step 5b, search only the feature directory. +- **Write each output path once.** No Delete+rewrite, no second Write to the same file. +- Do not call `GetDynamicTools` / list Jira tools. Use the shared fetch-issue script. +- **Discover, don't assume.** Never hardcode assumptions about test runners, design systems, i18n libraries, or any UI tooling. All tool choices come from the codebase. + +## Shared Script + +This skill delegates deterministic Jira issue fetching to a shared +script. Reference it using a relative path from this file: + +``` +../../_shared/scripts/fetch-issue.py +``` + +The script provides subcommands: `get` and `search`. See the script +header for full usage. It requires `JIRA_URL` and `JIRA_TOKEN` +environment variables. + +## Jira call (use as-is) + +Resolve the shared script to an absolute path so it remains valid +regardless of working directory: + +```bash +FETCH_ISSUE_SCRIPT="${HOME}/.ai-workflows/_shared/scripts/fetch-issue.py" +``` + +Use `$FETCH_ISSUE_SCRIPT` instead of the relative path in all subsequent +commands. + +- **Story:** `python3 "$FETCH_ISSUE_SCRIPT" get {KEY} --fields summary,description,issuetype,status,labels,fixVersions --parent --parent-fields summary,status,issuetype,parent --links --link-fields summary,status` +- **Parent epic/feature:** skip if `parent.key` (and its parent) are already in the story payload. Use those keys for docs lookup. Fetch only if a key is missing: `python3 "$FETCH_ISSUE_SCRIPT" get {KEY} --fields summary,status,issuetype --parent --parent-fields summary,status,issuetype,parent` +- **Blocking deps only:** `python3 "$FETCH_ISSUE_SCRIPT" get {KEY} --fields summary,status` + +## Process + +### Step 1: Identify the Story + +The user will provide one of: +- A Jira issue key or URL +- A path to an existing story file from the design workflow + +Extract the full Jira issue key, including the project prefix (e.g., +`PROJ-1234`, not just `1234`). Use this as `{issue-key}` throughout +the workflow — it is the context identifier for the artifact directory +and all downstream phases. + +### Step 2: Create Artifact Directory + +```bash +mkdir -p .artifacts/ui-implement/{issue-key} +``` + +Verify that `.artifacts/` is covered by the project's `.gitignore`. If it +is not, warn the user that implementation artifacts could be accidentally +committed with the code. + +### Step 2a: Check for Prior Ingest + +If `.artifacts/ui-implement/{issue-key}/01-context.md` already exists, this is a +re-invocation. Copy the existing file to `01-context.md.prev` so it is +preserved for the diff in Step 8a. + +### Step 3: Fetch the Jira Story + +One `fetch-issue.py get` call for the story (using the Story command from +the Jira call section). + +Capture: +- Summary and description +- User story (As a... I want... So that...) +- Acceptance criteria +- Implementation guidance (if present) +- Testing approach (if present) +- `Validated by` TC IDs and `PRD Requirements` from the Design Reference (used to filter the testplan in Step 5d) +- Design refs +- Story type prefix (`[UI]`, `[DEV]`, etc.) +- Parent key (epic) and its parent key (feature), from the `--parent --parent-fields` response +- Story dependencies (linked issues — "depends on", "is blocked by") +- Fix version / sprint (if set) + +### Step 4: Check Story Dependencies + +For each dependency identified in Step 3: +1. Check if the dependent story's Jira status indicates completion + (Done, Closed, Resolved). Fetch with `fetch-issue.py get` (Blocking deps + command from the Jira call section). +2. Check if the dependent story's code has been merged to the main branch: + `git log main --oneline --grep="{key}" -5`. + +If dependencies are unresolved, **warn the user** but do not block. Report: +- Which dependencies are unresolved +- What risk this presents (merge conflicts, missing APIs, etc.) +- A recommendation to proceed with caution or wait + +### Step 5: Load Upstream Context + +The ui-design document, PRD, and related documents are published to a docs +repo by the prd, design, and ui-design workflows. Fetch them from there. + +#### 5a: Resolve the Docs Repo + +Check for an existing docs repo configuration at `.artifacts/config.json`. +This config is workspace-level and shared across all workflows — a prior +workflow run may have already created it. + +If it exists, Read it and validate: +1. Path exists on disk +2. Directory is a git repo +3. `git remote get-url origin` matches `docs_repo_remote` + +If any check fails, tell the user and re-ask. Resolve `~` to an absolute path before saving. + +If it does not exist, ask for docs repo local path and remote. Resolve `~` to absolute. Write `.artifacts/config.json` with `docs_repo_path` and `docs_repo_remote`. + +#### 5b: Find the Feature Directory + +The docs repo organizes documents by Feature-level Jira issue. To find the +right directory, walk the Jira hierarchy from the story: + +1. The story (e.g., `PROJ-1234`) has a parent **Epic** — its key is in the + `parent.key` field of the story payload from Step 3 +2. The Epic has a parent **Feature** — its key is in `parent.parent.key` + (or `parent.fields.parent.key`) of the story payload, since the Story + command fetches `--parent-fields summary,status,issuetype,parent` + +If the Feature key is not in the story payload (the `--parent-fields parent` +did not return a grandparent), fetch the Epic with `fetch-issue.py get` +(Parent epic/feature command from the Jira call section) to get its parent. + +The docs repo structure is `{release}/{feature-slug}/`, where `{feature-slug}` +includes the Feature issue key (e.g., `port-mappings-PROJ-1100`). + +Search the docs repo for the Feature key: + +```bash +find "{docs_repo_path}" -type d -name "*{feature-key}*" +``` + +If multiple directories match (e.g., the same Feature across releases), +prefer the one whose release matches the story's fix version. If ambiguous, +ask the user to choose. + +If the hierarchy traversal fails or no directory is found, ask the user +for the path to the relevant documents within the docs repo. + +#### 5c: Read Upstream Documents (section-scoped) + +Do **not** Read an entire `ui-design.md`, `design.md`, `prd.md`, or +`testplan.md`. Those files are often thousands of lines. Search, then slice. + +1. Collect search terms from the Jira story: issue key, design section + refs, FR/NFR IDs, AC keywords, component names. +2. Grep each document for those terms and for heading lines (`^#`). +3. Read **only** the matching heading ranges (`offset`/`limit`). Prefer + one contiguous range per relevant section. +4. If grep finds nothing useful, Read the first ~80 lines of the document + (title, TOC, or overview) and grep again using TOC entries — still + do not Read the rest of the file. + +Need (in priority order): + +1. **UI design document** (`ui-design.md`) — **required.** Sections that bind + this story: component architecture tree, hook designs, state management, + route structure, data flow mapping, persona decomposition, accessibility + plan, testing strategy. +2. **Design document** (`design.md`) — sections that bind this story (API + contracts, data models, flows) +3. **PRD** (`prd.md`) — FR/NFR this story covers +4. **Handoff document** (`handoff.md`) — **optional.** Interaction specs, + state matrix, component mapping, accessibility requirements, acceptance + criteria enrichment +5. **API findings** (`api-findings.md`) — **optional.** Resolved endpoints, + API gaps, mock strategies +6. **Testplan** (`testplan.md`) — candidate test cases for Step 5d + +If `ui-design.md` is not found, **warn the user** — this is the primary +design input for UI stories. Ask whether to proceed with only the Jira story +and general design document, or to wait for the ui-design document. + +If `design.md` or `prd.md` are not found, proceed with available context — +the story's acceptance criteria are the primary contract. + +#### 5d: Filter Testplan to Story Scope + +Match the story's `Validated by` TC IDs (captured in Step 3) against the +testplan's test-case headings. If `Validated by` is missing, empty, or +`None` (no TC IDs), fall back to requirement match: collect every test case +whose requirement heading matches a `PRD Requirements` ID from the story's +Design Reference. + +| Outcome | Condition | Action | +|---------|-----------|--------| +| Normal | Matches found | Write `testplan.md` **once** from `../templates/story-testplan.md` | +| Expected zero | No matches and type is `[QE]`/`[DOCS]`/`[UX]`/`[CI]` | Note expected; delete stale story testplan if present | +| Anomalous zero | No matches and type is `[DEV]`/`[UI]` (or unknown) | Warn; delete stale story testplan if present | + +No feature testplan: note and continue. + +### Step 6: Explore the Codebase + +Based on the story's scope, explore the areas of the codebase that will be +affected. + +**Budgets (hard):** +- ≤ **20** Greps, each `head_limit` ≤ 25. **One** Makefile grep for `lint|test|generate|tidy|cover`. +- ≤ **4** Globs. Never `**/*` on `.artifacts`. Never repo-wide `**/*{story-keyword}*`. +- Repo-wide Grep: `output_mode: files_with_matches`. Then signature Reads. +- ≤ **8** source Reads, `offset`/`limit` ≤ 80 around signatures. +- Stop after 3 consecutive Reads with no new pattern. +- Stack: `git branch --show-current`, `git log --oneline -8`, `gh stack view --json`. No `.git/` listing. +- Topology: parse `{owner}/{repo}` from `git remote get-url origin` (never substitute a well-known upstream name). Then `gh repo view {owner}/{repo} --json isFork,parent`. If `gh` fails, ask the user whether this is a fork and, if so, for upstream `{owner}/{repo}`. + +**Validation cache:** If `.artifacts/ui-implement/_validation-profile.md` exists and `.meta.json` hashes/mtimes still match, merge the profile into the in-memory context draft, skip config Reads, and do not Write `01-context.md` until Step 8 or Step 8a. Else one discovery pass: bounded Greps of present `AGENTS.md` and `CONTRIBUTING.md` (unless already in session) for lint/test/coverage commands, one Makefile grep, plus CI filenames via `git ls-files '.github/workflows/*.yml' '.github/workflows/*.yaml'`. For each listed workflow, Grep command-bearing keys (`run:`, `make`, lint/test targets) — not full workflow bodies. Then Write cache files **once**. + +Skip `AGENTS.md` and `CONTRIBUTING.md` Reads if already in session. Path-only for PR template unless the body is required. + +`.artifacts/ui-implement/.meta.json` schema (write **once** on cache miss; compare these keys on hit): + +```json +{ + "AGENTS.md": {"mtime": "{unix}", "sha256": "{hex or empty}"}, + "CONTRIBUTING.md": {"mtime": "{unix}", "sha256": "{hex or empty}"}, + "Makefile": {"mtime": "{unix}", "sha256": "{hex or empty}"}, + "package.json": {"mtime": "{unix}", "sha256": "{hex or empty}"}, + "ci_workflows": { + "{filename}": {"mtime": "{unix}", "sha256": "{hex or empty}"} + } +} +``` + +Focus on: + +1. **Project configuration** (skip this block when the validation cache + hits): + - `AGENTS.md`, `CLAUDE.md` — only if not already in session; grep for + coverage thresholds and commit/PR conventions + - `package.json` — grep for scripts (build, test, lint, format, type-check) + - Makefile or equivalent — grep build, test, lint commands + - CI/CD workflows — grep what checks run on PRs; Read a workflow + file only if grep cannot name the make target + - `CONTRIBUTING.md` — grep PR and commit message conventions + - `.github/PULL_REQUEST_TEMPLATE.md` or `.github/PULL_REQUEST_TEMPLATE/` — + path is enough; Read only if the template body is needed for the + profile + +2. **Affected components:** + - Which components, hooks, pages, or modules will this story touch? + - Grep for component/hook names; Read signatures (`offset`/`limit`), not full files + - Note existing test file paths from glob/grep; Read a test file only + to capture the test pattern, not the whole suite + +3. **UI toolchain discovery** (record all findings in `01-context.md`): + - **Test framework:** grep `package.json` for test runner (vitest, jest, + mocha, etc.), testing library (@testing-library/react, enzyme, etc.), + and test scripts. Record the framework, assertion library, and run command. + - **Design system:** grep imports across components for design system + packages (e.g., `@patternfly`, `@mui`, `@chakra-ui`, custom design + system). Record the package name and import patterns. + - **i18n:** grep for i18n library usage (react-i18next, react-intl, + FormatJS, custom). Record the library and wrapping convention (e.g., + `t('key')`, ``, `useTranslation`). + - **State management:** grep for state management patterns (Redux, + Zustand, Jotai, React Query, SWR, context-based). Record the approach. + - **Routing:** grep for routing library (react-router, Next.js routing, + etc.). Record the library and pattern. + - **Permission/RBAC:** grep for permission check patterns. Record the + mechanism if found. + - **E2e framework:** grep for e2e test tooling (Cypress, Playwright, + etc.) if present. Record for integration/e2e stub writing. + - **If no unit test framework is found:** note the absence. Identify + candidate frameworks based on the project's build tooling (e.g., + Vite → Vitest, Create React App → Jest). Record the recommendation + and rationale in `01-context.md` under Test Infrastructure. This + becomes "Task 0" material for `/plan`. + +4. **Relevant data models and APIs:** + - What TypeScript types/interfaces will be extended or consumed? + - What API hooks or fetch patterns exist? + - What API specifications exist (OpenAPI, GraphQL schema)? + +Record components as path + signature + test path. `/plan` opens cited files. + +**Must-record (index, not dump):** + +- **UI design:** For each cited section, 2–5 binding bullets for *this* story (component tree, hook interface, state shape, route, data flow, accessibility requirement). One `[UI Design: §x.y]` each. Not a restatement of the chapter. +- **Design:** For each cited section, 2–5 binding bullets for *this* story (API contract, data model). One `[Design: §x.y]` each. +- **PRD:** One clause per FR/NFR ID from the story or from slices already Read. Do not Read whole `prd.md`. +- **Handoff:** If found — interaction specs, state matrix entries, component mapping items relevant to this story. One `[Handoff: §x.y]` each. +- **API findings:** If found — resolved endpoints, mock strategies for this story. One `[API: §x.y]` each. +- **Cite what `/plan` would not guess** (path + one line; extra grep hits stay unread): sibling implementation in another component ("pattern only, do not import"); shared hooks or utilities; neighboring unit test paths if grep found them. List leftover `files_with_matches` hits under **Cited, not opened**. +- **Open questions:** Fill or mark `N/A (reason)` for: component props contract; story boundary vs dependency/successor; spec vs AC conflict (record both, do not pick); missing design system component; placement (existing module vs new); permission gate not in current code; loading/error/empty state not specified. Concrete question or N/A. No vague "how should errors work?" + +### Step 7: Discover UI Cross-Cutting Concerns + +Based on the codebase exploration, document the cross-cutting patterns that +`/code` must follow. These are discovered, not assumed: + +1. **Design system usage patterns:** How are design system components imported + and composed? Are there project-specific wrappers? +2. **i18n patterns:** How are translation keys structured? Where do translation + files live? Is there a key naming convention? +3. **Accessibility patterns:** Does the project use specific a11y testing + utilities? Are there ARIA patterns enforced by lint rules? +4. **Permission patterns:** How are feature gates and RBAC checks applied to + UI elements? +5. **State management patterns:** How do components fetch and cache server + data? How is client state managed? +6. **Error handling patterns:** How are API errors displayed? Is there a + shared error boundary or toast system? +7. **Loading state patterns:** How are loading indicators rendered? Skeletons, + spinners, or placeholders? + +### Step 8: Compile Context + +Compile all findings into `01-context.md`. If this is a re-invocation +(Step 2a found an existing file), **do not write the file yet** — hold the +compiled content and proceed to Step 8a first. + +If this is a first invocation: Read `../templates/01-context.md` **once**, +fill it tightly (must-record bullets; 5–8 lines per component; signatures +only; every open-question slot filled or N/A), Write `01-context.md` +**once**. + +### Step 8a: Diff Against Prior Ingest (Re-invocation Only) + +Diff compiled content vs `.prev`. Focus on: +- Acceptance criteria +- Implementation guidance or testing approach +- Dependency status +- New components or patterns +- Validation profile +- UI toolchain discoveries + +If `02-plan.md` or later artifacts exist, list them. Wait for confirmation. If confirmed, Write `01-context.md` **once** and delete `.prev`. If declined, delete `.prev` and stop without overwriting. + +### Step 9: Report + +8–12 lines. Do not paste `01-context.md`. Point at the file. Include: +- Story scope and key ACs +- UI design / design / PRD loaded (or missing) +- Handoff and API findings status +- Dependency warnings +- Affected components +- UI toolchain summary (test framework, design system, i18n, state management) +- Test infrastructure status (found / not found — recommendation if absent) +- Validation cache hit/miss and profile summary +- Testplan status (matches / expected zero / anomalous zero / none) +- Open questions as `/plan` work, not blockers +- Readiness for `/plan` + +If the user declined overwrite in 8a, report the diff and that existing context was kept. + +## Output + +- `.artifacts/ui-implement/{issue-key}/01-context.md` +- `.artifacts/ui-implement/{issue-key}/testplan.md` (normal testplan outcome only) +- `.artifacts/ui-implement/_validation-profile.md` (+ `.meta.json`) on cache miss + +## Done + +Return to the invoking workflow router for completion guidance. diff --git a/ui-implement/skills/plan.md b/ui-implement/skills/plan.md new file mode 100644 index 00000000..f3cbe417 --- /dev/null +++ b/ui-implement/skills/plan.md @@ -0,0 +1,349 @@ +--- +name: plan +description: Design the UI implementation approach with task breakdown, component/hook interfaces, test strategy, and risk assessment. +--- + +# Plan UI Implementation Skill + +You are a principal front-end engineer planning an implementation. Your job is +to read the story context and produce a structured implementation plan: a task +breakdown, component/hook interface definitions, test strategy, and risk +assessment. + +## Your Role + +Translate the story's acceptance criteria into a concrete, ordered sequence +of implementation tasks. Each task should be specific enough that an AI agent +(or developer) can execute it without ambiguity. The plan is the user's +review checkpoint before any code is written. + +## Critical Rules + +- **Every task must trace to an acceptance criterion.** If a task doesn't serve an AC, it's scope creep. +- **Follow existing patterns.** The codebase context from `/ingest` shows how things are done in this project. Match those patterns. +- **Be specific.** Name the files, components, hooks, types, and modules. A plan that says "add a component" without specifying where is too vague. +- **Tests are part of the plan, not an afterthought.** The unit test strategy is designed alongside the implementation. Integration/e2e test stubs are planned as a final post-task step. +- **No scope reduction.** Don't simplify acceptance criteria or defer parts to "later." +- **Design system first.** Plan to use discovered design system components. Flag gaps where no design system component exists. +- **Accessibility is not optional.** Every interactive component must have keyboard navigation and ARIA attributes planned. + +## Process + +### Step 1: Read Source Material + +Read these files in order: +1. `.artifacts/ui-implement/{issue-key}/01-context.md` (story context) +2. `.artifacts/ui-implement/{issue-key}/testplan.md` (story-scoped testplan, if exists) +3. The project's `AGENTS.md` and/or `CLAUDE.md` (coding conventions) + +If `01-context.md` doesn't exist, tell the user that `/ingest` should be +run first. + +Then open **citations only** from `01-context.md` (ingest is an index; this is where the files are read): + +1. Each `[UI Design: §…]`, `[Design: §…]`, `[Handoff: §…]`, `[API: §…]` (or equivalent) → that path + heading range. Do not Read the rest of the document. +2. Cited source/test paths (Affected Components + Cited, not opened) as needed to name types. Signature `offset`/`limit` slices, not whole files. +3. Cap **≤12** cited source Reads total (bootstrap reads of `01-context.md`, `testplan.md`, and `AGENTS.md`/`CLAUDE.md` do not count). Skip a citation if it is not needed to lock a task or interface. +4. Do not glob, repo-wide grep, Jira, or unrelated sibling artifacts. Read the required `testplan.md` when it exists. Do not re-run ingest exploration. +5. Classify each ingest open question (ingest is an index, not a spec). Do **not** treat ingest text as a complete contract: + - **Already specified:** citations (or an unambiguous AC) define the component, hook, or behavior → **Locked decision**. + - **Implementer default:** unspecified but `/code` needs a choice (component name, prop name, default state value, error message text). Lock a default that matches cited neighboring code; note it is a default `/revise` may change. Do not leave it open. + - **Product fork:** spec vs AC, or two product-legal behaviors. Keep under **Open Questions**. Follow AC in the tasks until the user picks. Do not silently lock the design side. +6. Do not paste opened file bodies into `02-plan.md` (signatures and decisions only). + +### Step 1a: Evaluate Test Infrastructure + +Check the **Test Infrastructure** section of `01-context.md`: + +- **If a unit test framework exists:** proceed normally. Plan tests using + the discovered framework and patterns. +- **If no unit test framework exists:** the context will include a + recommendation. Plan a **Task 0: Introduce unit testing framework** that: + 1. Installs the recommended test framework and testing library + 2. Adds test scripts to `package.json` + 3. Creates a minimal test configuration file + 4. Writes one smoke test for an existing simple component to verify the setup + 5. Runs the test to confirm the framework works + + Present the framework recommendation to the user for approval. Task 0 must + be completed and approved before any story tasks are planned — the test + strategy for all subsequent tasks depends on the chosen framework. + +### Step 2: Determine Local Base and PR Target + +Before writing the plan, determine two distinct branches: + +**Local Base** — the branch this story's commits are stacked on locally. +Used by `/code` and `/validate` for all `git rebase` and sync operations. + +Run: + +```bash +git branch --show-current +``` + +Evaluate the result: + +- **If the current branch is a trunk branch** (`main`, `master`, `develop`, or similar) — use it as the Local Base. +- **If the current branch is a feature branch** (e.g., a prior story branch) — the user is likely stacking stories. Present both options and ask which to use: + - Use the current branch (e.g., `EDM-1233-prior-story`) as the Local Base — correct for stacked stories + - Use `main` (or the project default) as the Local Base — correct if the user has already switched to the wrong branch by mistake + +**PR Target** — the branch the pull request will target (`--base` in `gh pr create`). +This is almost always the repository's default trunk branch (`main`, `master`, etc.), +regardless of how the story is stacked locally. + +Read the **Repository Topology** section of `01-context.md`: + +- **If the repo is a fork**: PR Target = the upstream default branch. Confirm by running: + ```bash + gh repo view {upstream-owner}/{upstream-repo} --json defaultBranchRef --jq '.defaultBranchRef.name' + ``` +- **If the repo is a direct clone**: PR Target = `main` (or the project default) unless the user explicitly wants PR-based stacking against a prior story's branch. + +Do not conflate Local Base with PR Target. A stacked story rebases locally onto a prior story's branch, but its PR still targets the selected PR Target. + +### Step 3: Map Acceptance Criteria to Changes + +Before writing the plan, create a mental map: +- Which acceptance criteria require new components vs. modifications to existing components? +- What new components, hooks, types, or utilities are needed? +- What existing components or hooks need to be extended? +- Which changes have dependencies on each other (ordering constraints)? +- Where will tests live? What test patterns from neighboring code should be followed? +- What design system components will be used? +- Which components need i18n string wrapping? +- What accessibility requirements apply (ARIA roles, keyboard navigation, screen reader text)? +- Are there loading, error, and empty states to implement? +- Are there permission gates to implement? + +### Step 4: Write the Implementation Plan + +Write `.artifacts/ui-implement/{issue-key}/02-plan.md` with this structure: + +```markdown +# Implementation Plan — {issue-key} + +## Summary + +{1-2 sentence summary of the implementation approach.} + +## Branch + +- **Name:** {issue-key}-{short-slug} (e.g., EDM-1234-fleet-dashboard) +- **Local Base:** {branch confirmed in Step 2 — used for rebasing during /code and /validate} +- **PR Target:** {branch confirmed in Step 2 — used as --base in gh pr create; typically `main`} + +## Locked Decisions + +{Ingest gaps resolved as "already specified" or "implementer default." Each bullet: decision + one-line why (citation or "default, match {existing pattern}"). Product forks do not belong here.} + +## Interface Definitions + +{New or modified public component props, hook signatures, and TypeScript + types. These define the contracts that tests will validate. Show + signatures with doc comments, not implementations.} + +### New Components + +{If none: "No new components required."} + +{For each new component:} + +#### `{ComponentName}` +- **File:** {path} +- **Props:** `{TypeScript interface}` +- **Design system components used:** {list} +- **i18n keys:** {translation keys needed, if i18n exists} +- **Accessibility:** {ARIA roles, keyboard interactions} +- **States:** {loading, error, empty — if applicable} + +### New Hooks + +{If none: "No new hooks required."} + +{For each new hook:} + +#### `{useHookName}` +- **File:** {path} +- **Signature:** `{TypeScript signature}` +- **Returns:** {return type description} +- **Side effects:** {API calls, state mutations, etc.} + +### Modified Components/Hooks + +{If none: "No modifications required."} + +### New Types + +{If none: "No new types required."} + +## Test Strategy + +### Unit Tests + +{For each component/hook being created or changed:} + +#### {Component/Hook} +- **Test file:** {path} +- **Contracts to test:** {list of behavioral contracts — rendered output, user interactions, hook return values} +- **Test pattern:** {match project conventions discovered during /ingest} +- **Mocks needed:** {API calls, router, i18n provider, etc.} + +### Integration/E2E Test Stubs + +{Written after all tasks complete. Describe what stubs will cover:} + +- **Framework:** {discovered e2e framework, or "None — project has no e2e framework"} +- **Stubs planned:** {list of test scenarios, or "No stubs — no e2e framework in project"} + +### Coverage Goals + +{Qualitative description of what behavioral coverage looks like for this + story. Focus on behavioral paths through public interfaces, not numeric + targets.} + +## Task Breakdown + +{Ordered list of tasks. Each task includes what to change, why, and which + AC it serves. Tasks are grouped into logical commits. + + Tasks must produce code or test changes. Do not include tasks for + running linters, validation suites, or other checks — lint and format + issues are caught by `/code`'s per-task lint step and by `/validate`. + They do not need their own plan tasks. + + If Task 0 (test framework introduction) is needed, it appears first.} + +### Task 0: Introduce unit testing framework (conditional) + +{Include only if /ingest found no unit test framework. Otherwise omit.} + +- **Files:** {package.json, test config, smoke test file} +- **What:** {install framework, configure, write smoke test} +- **Why:** No unit test framework exists — required before any story tasks +- **Commit message:** `{use commit format from 01-context.md}` +- **Status:** Pending + +### Task 1: {description} +- **Files:** {paths to create or modify} +- **What:** {specific changes} +- **Why:** {which acceptance criterion this serves, e.g., AC-1, AC-3} +- **UI concerns:** {design system components, i18n keys, a11y attributes, states} +- **Commit message:** `{use commit format from 01-context.md}` +- **Status:** Pending + +### Task 2: {description} +... + +### Task N+1: Write integration/e2e test stubs (conditional) + +{Include only if the project has an e2e framework discovered during /ingest. + Otherwise omit.} + +- **Files:** {paths for test stubs} +- **What:** {stub test files with describe blocks and pending/skip test cases} +- **Why:** Provide scaffolding for QE to implement full e2e tests +- **Commit message:** `{use commit format from 01-context.md}` +- **Status:** Pending + +## Acceptance Criteria Coverage + +{Matrix showing which tasks cover which acceptance criteria.} + +| AC | Description | Covered by | +|----|-------------|------------| +| AC-1 | {brief} | Task 1, Task 3 | +| AC-2 | {brief} | Task 2, Task 4 | + +{Every AC must appear in at least one task. Flag any gaps.} + +## Test Plan Coverage + +{Include this section only if `.artifacts/ui-implement/{issue-key}/testplan.md` + exists. If no story-scoped testplan: omit this section entirely.} + +| TC ID | Title | Covered by Task | Notes | +|-------|-------|-----------------|-------| +| TC-FR1-01 | {title} | Task 2 | | +| TC-FR1-02 | {title} | Task 3 | | +| TC-NFR1-01 | {title} | N/A | {rationale} | + +{Every TC ID from testplan.md must appear. Each must be assigned to a + task or marked N/A with a rationale. This is a set-diff gate: + compute the difference between the set of TC IDs in testplan.md and + the set assigned to tasks or marked N/A. If the difference is + non-empty, the plan is incomplete — resolve before proceeding.} + +## UI Cross-Cutting Concerns + +{Summarize how each cross-cutting concern applies to this story's tasks.} + +| Concern | Approach | Tasks Affected | +|---------|----------|----------------| +| Design system | {components to use} | {task list} | +| i18n | {keys/patterns} | {task list} | +| Accessibility | {ARIA/keyboard plan} | {task list} | +| Permissions | {gate pattern or N/A} | {task list} | +| Loading/error/empty | {state handling} | {task list} | + +## Risk Assessment + +{Things the plan author is uncertain about. Ordered by impact.} + +- **{Risk}:** {description and mitigation} + +## Open Questions + +{Product forks only — spec vs AC or two product-legal behaviors. Not + implementer defaults. If none: "None — `/code` can proceed."} +``` + +### Step 5: Self-Review + +Before presenting the plan, verify: + +- [ ] Every acceptance criterion is addressed by at least one task +- [ ] Task ordering respects dependencies (e.g., types defined before components that use them, hooks before components that call them) +- [ ] New components and hooks follow the project's naming conventions +- [ ] Test strategy covers all public interface behavioral paths +- [ ] Each proposed component exposes enough public surface area that its significant behavioral paths can be tested without reaching into internals +- [ ] File paths are specific (not "somewhere in components/") +- [ ] Commit messages follow the project's format (from validation profile) +- [ ] No tasks modify code outside the story's scope +- [ ] Task count is reasonable — if you have more than 10 tasks, consider whether the story needs re-scoping +- [ ] The plan is achievable — no tasks depend on unavailable infrastructure or unmerged code +- [ ] If story-scoped testplan exists: every TC ID is assigned to a task or marked N/A with rationale (Test Plan Coverage set-diff is clean) +- [ ] Every ingest open question is a locked decision (specified or implementer default) or a product fork still listed +- [ ] Open Questions contains only product forks, not defaults `/code` could pick +- [ ] Cited Reads stayed within the cap; `02-plan.md` has no pasted file bodies +- [ ] Design system components are specified for each new UI element +- [ ] i18n wrapping is planned for all user-visible strings (if i18n exists) +- [ ] Accessibility attributes are specified for all interactive elements +- [ ] Loading, error, and empty states are planned where applicable +- [ ] Integration/e2e test stubs are planned as the final task (if e2e framework exists) + +### Step 6: Present to User + +Show the user the complete plan and highlight: +- Implementation approach and key decisions +- Component/hook interface definitions (the contracts that tests will validate) +- Test strategy and what behavioral paths will be covered +- UI cross-cutting concerns and how they're addressed +- Any risks or open questions +- Anything where you made a judgment call vs. following explicit guidance +- If Task 0 is included: the test framework recommendation and why + +## Output + +- `.artifacts/ui-implement/{issue-key}/02-plan.md` + +## When This Phase Is Done + +Report your results: +- The plan has been written and saved +- Highlight key implementation decisions +- Note any risks or open questions +- Assessment of plan completeness + +Then return to the invoking workflow router for completion guidance. diff --git a/ui-implement/skills/publish.md b/ui-implement/skills/publish.md new file mode 100644 index 00000000..12e79ed7 --- /dev/null +++ b/ui-implement/skills/publish.md @@ -0,0 +1,279 @@ +--- +name: publish +description: Push the feature branch and create a draft PR in the source repo. +--- + +# Publish Implementation Skill + +You are a principal submission specialist. Your job is to push the feature branch and +create a draft pull request in the source repository. + +## Your Role + +Verify the branch is ready, push it, and create a draft PR with a clear +description linking back to the Jira story. Confirm all details with the +user before taking action. + +## Critical Rules + +- **Confirm before pushing.** Verify the target branch, PR title, and PR details with the user. +- **One story per PR.** Each pull request corresponds to exactly one Jira story. Do not combine multiple stories into a single PR. +- **Draft PR.** Always create as a draft — the user decides when to mark it ready for review. +- **No force-push.** No destructive git operations. +- **No direct commits to main.** The feature branch must already exist from `/code`. +- **Validation must have passed.** Check for a passing validation report before proceeding. + +## Shared Script + +This skill delegates deterministic git and CLI operations to a shared +script. Reference it using a relative path from this file: + +``` +../../_shared/scripts/publish.py +``` + +The script provides subcommands: `preflight`, `push`, `check-existing`, +`create-pr`, and `save-metadata`. See the script header for full usage. + +## Process + +### Prerequisites: Resolve Script Path + +Before running any subcommands, resolve the shared script to an +absolute path so it remains valid regardless of working directory: + +```bash +PUBLISH_SCRIPT="${HOME}/.ai-workflows/_shared/scripts/publish.py" +``` + +Use `$PUBLISH_SCRIPT` instead of the relative path in all subsequent +commands. + +### Step 1: Pre-Flight Checks + +Verify readiness: + +1. Read `.artifacts/ui-implement/{issue-key}/05-validation-report.md`. Check + that the `## Result` section contains `PASS`. If the file doesn't exist, + the `## Result` section is missing, or it contains `FAIL`, tell the user + that `/validate` should be run (or re-run) first. + +2. Verify the feature branch exists and has commits: + + ```bash + git branch --show-current + ``` + + Read the `## Branch` section of `02-plan.md` to get the Local Base and PR Target. + + ```bash + git log --oneline {local-base}..HEAD + ``` + + If there are no commits ahead of the Local Base, there's nothing to publish. + +3. Run the shared pre-flight checks: + + ```bash + python3 "$PUBLISH_SCRIPT" preflight --platform github + ``` + + Parse the output to confirm `auth_ok=true`. If `auth_ok=false`, stop + and tell the user to authenticate first. Check for + `has_uncommitted=true`, `has_staged=true`, or `has_untracked=true`. + If there are uncommitted or untracked changes, ask the user how to + proceed. + +### Step 2: Cross-Cutting Review + +Each sub-task was already reviewed individually during `/code`. This +review focuses on issues that only emerge when looking at the branch +as a whole — problems that span tasks or arise from their interaction. + +Read the `## Branch` section of `02-plan.md` to get the Local Base, then +read and follow `../../_shared/recipes/self-review-gate.md` with these +parameters: + +| Parameter | Value | +|-----------|-------| +| DIFF_COMMAND | `git diff {local-base}...HEAD` | +| MAX_ROUNDS | `3` | +| CONTEXT_FILES | `.artifacts/ui-implement/{issue-key}/01-context.md`, `.artifacts/ui-implement/{issue-key}/02-plan.md` (if they exist) | +| SUPPLEMENTARY_CRITERIA | This is a cross-cutting review. Each sub-task was already reviewed individually. Focus on inter-task issues: (1) Inconsistencies across components (naming conventions, prop patterns, event handling style). (2) Duplicated logic that emerged across separate tasks — shared hooks or utilities that should be extracted. (3) Integration gaps between components implemented in different tasks. (4) Design system usage coherence (consistent component choices, token usage). (5) i18n key consistency (naming convention, namespace usage). Skip issues already caught per-task: individual component correctness, per-file error handling, single-task test coverage. | + +If the gate reports FLAG (unfixed CRITICAL or HIGH findings), stop and +present the findings to the user. Do not proceed until the user decides +how to handle them. + +If the gate made code fixes, commit them before proceeding: + +```bash +git add {fixed files} +git commit -m "{issue-key}: address cross-cutting review findings" +``` + +### Step 3: Confirm Details + +Present the PR details to the user for confirmation: + +- **Branch:** `{branch-name}` (from the plan) +- **Local Base:** `{local-base}` (from `## Branch` in `02-plan.md`) +- **PR Target:** `{pr-target}` (from `## Branch` in `02-plan.md`) +- **Commits:** List the commits that will be included + +```bash +git log --oneline {local-base}..HEAD +``` + +- **PR title:** Use the title format from the **PR Conventions** section of + `01-context.md` (typically `{issue-key}: {story title}`) + +Confirm with the user before proceeding. + +### Step 4: Push Branch + +```bash +python3 "$PUBLISH_SCRIPT" push --remote origin --branch {branch-name} +``` + +### Step 5: Create PR Description + +Check the **PR Conventions** section of `01-context.md`: + +- If a **PR template** path is listed, read the template and populate it + with content from the story context and implementation/test reports. +- If no project template exists, use the default template below. + +In either case, save the result to +`.artifacts/ui-implement/{issue-key}/06-pr-description.md`. + +**Default template** (used when the project has no PR template): + +```markdown +## {issue-key}: {story title} + +**Jira:** {jira-link} +**Story type:** {[UI]} + +### Summary +{2-3 sentence summary of what was implemented and why.} + +### Changes +{Bulleted list of key changes, organized by component.} + +### New Components +{List of new components/hooks added, with brief description.} + +### Testing +- **Unit tests:** {summary of unit tests added} +- **Integration/e2e stubs:** {summary of stubs added, or "N/A"} +- **Coverage:** {qualitative assessment} + +### UI Concerns +- **Design system:** {components used} +- **i18n:** {keys added or "N/A — project has no i18n"} +- **Accessibility:** {a11y features implemented} + +### Acceptance Criteria +{Checklist of acceptance criteria from the story.} + +- [ ] AC-1: {description} +- [ ] AC-2: {description} +``` + +### Step 6: Create Draft PR + +Check the **Repository Topology** section of `01-context.md` to determine +whether this is a fork-based workflow. + +First, check whether a PR already exists for this branch: + +```bash +python3 "$PUBLISH_SCRIPT" check-existing --repo {upstream-owner}/{repo} --head {branch-name} +``` + +If exit code is 5, a PR already exists — parse the PR number and URL, +then skip to Step 7. If non-zero exit other than 5, stop and report the +error. If exit code is 0, create a new PR. + +**If the repo is a fork:** + +```bash +python3 "$PUBLISH_SCRIPT" create-pr \ + --repo {upstream-owner}/{repo} \ + --base {pr-target} \ + --head {fork-owner}:{branch-name} \ + --title "{issue-key}: {story title}" \ + --body-file .artifacts/ui-implement/{issue-key}/06-pr-description.md \ + --draft +``` + +**If the repo is a direct clone:** + +```bash +python3 "$PUBLISH_SCRIPT" create-pr \ + --base {pr-target} \ + --head {branch-name} \ + --title "{issue-key}: {story title}" \ + --body-file .artifacts/ui-implement/{issue-key}/06-pr-description.md \ + --draft +``` + +Parse the PR number from the URL. If the script exits with code 4, fall +back to providing a GitHub compare URL. + +### Step 7: Save Publish Metadata + +Read `{owner}/{repo}` from the **Origin** field of the Repository +Topology section of `01-context.md`. If the repo is a fork, also read +the **Upstream** field. + +**If the repo is a fork:** + +```bash +python3 "$PUBLISH_SCRIPT" save-metadata \ + --file .artifacts/ui-implement/{issue-key}/publish-metadata.json \ + repo={upstream-owner}/{repo} \ + origin={fork-owner}/{repo} \ + branch={branch-name} \ + base={pr-target} \ + pr_number={pr-number} \ + pr_url={url-from-create-pr-output} \ + jira_key={issue-key} +``` + +**If the repo is a direct clone:** + +```bash +python3 "$PUBLISH_SCRIPT" save-metadata \ + --file .artifacts/ui-implement/{issue-key}/publish-metadata.json \ + repo={owner}/{repo} \ + origin={owner}/{repo} \ + branch={branch-name} \ + base={pr-target} \ + pr_number={pr-number} \ + pr_url={url-from-create-pr-output} \ + jira_key={issue-key} +``` + +### Step 8: Report to User + +Present: +- PR URL (the full `https://github.com/...` link) +- Branch name and base +- Number of commits included + +## Output + +- Feature branch pushed to remote +- Draft PR created +- `.artifacts/ui-implement/{issue-key}/06-pr-description.md` +- `.artifacts/ui-implement/{issue-key}/publish-metadata.json` + +## When This Phase Is Done + +Report your results: +- PR URL and branch name +- Commits included + +Then return to the invoking workflow router for completion guidance. diff --git a/ui-implement/skills/respond.md b/ui-implement/skills/respond.md new file mode 100644 index 00000000..a257a8e4 --- /dev/null +++ b/ui-implement/skills/respond.md @@ -0,0 +1,234 @@ +--- +name: respond +description: Fetch and address PR reviewer comments, applying code changes with user approval. +--- + +# Respond to Review Skill + +You are a principal review coordinator. Your job is to fetch reviewer comments from +the PR, help the user understand and respond to them, and apply any resulting +code changes. + +## Your Role + +Read PR comments, categorize them, propose responses and code changes, and — +with user approval — post replies and update the code. This phase is +repeatable as new comments arrive. + +## Critical Rules + +- **Never post comments without user approval.** Propose responses, then wait for the user to approve, modify, or reject each one. +- **Separate code changes from clarifications.** Some comments need code edits; others just need a reply. +- **Preserve the review trail.** Don't delete or modify existing comments. +- **Re-validate after code changes.** If code was changed, recommend re-running `/validate` before continuing. +- **Commit changes using the project's commit format.** Review feedback commits follow the same format discovered during `/ingest`. +- **Allowed `gh` operations:** + - **Read:** `gh pr view` (for PR discovery only — comment fetching is + delegated to the shared script) + - **Write:** delegated to `pr-comments.py reply` (do not call `gh api` + or `gh pr comment` directly for review replies) + - **Forbidden:** `gh pr close`, `gh pr merge`, `gh pr edit`, `gh pr ready` + +## Shared Script + +This skill delegates deterministic PR comment operations to a shared +script. Reference it using a relative path from this file: + +``` +../../_shared/scripts/pr-comments.py +``` + +The script provides subcommands: `fetch`, `reply`, and `log`. See the +script header for full usage. + +## Process + +### Step 1: Read Context and Fetch PR Comments + +Read `.artifacts/ui-implement/{issue-key}/publish-metadata.json` to get the +PR number and `{owner}/{repo}` (the `repo` field). If metadata doesn't +exist, tell the user that `/publish` should be run first. If the user +provides a PR number directly, use that instead. + +If `{owner}/{repo}` is not available from metadata, check the **Repository +Topology** section of `01-context.md`: + +- If the repo is a fork, use the **Upstream** field as `{owner}/{repo}` +- If the repo is a direct clone, use the **Origin** field + +If `01-context.md` is also unavailable, derive `{owner}/{repo}` from +the source repo remote: + +```bash +git remote get-url origin +``` + +Resolve the shared script to an absolute path: + +```bash +PR_COMMENTS_SCRIPT="${HOME}/.ai-workflows/_shared/scripts/pr-comments.py" +``` + +Fetch all comments using the shared script: + +```bash +python3 "$PR_COMMENTS_SCRIPT" fetch --owner {owner} --repo {repo} --pr {pr-number} --responses-log .artifacts/ui-implement/{issue-key}/responses.jsonl --include-review-threads +``` + +If fetch returns non-zero, report the error to the user and stop. + +If no comments are found, tell the user and suggest checking back later. + +### Step 2: Categorize Comments + +Group comments into categories: + +| Category | Action | +|----------|--------| +| **Code change request** | Propose specific code edits | +| **Clarification request** | Draft a reply explaining the rationale | +| **Bug/defect identified** | Propose a fix with tests | +| **Style/convention issue** | Apply the fix, acknowledge in reply | +| **Design alternative** | Evaluate, propose a response | +| **Technically incorrect** | Draft a respectful rebuttal citing specific code behavior | +| **Would degrade quality** | Draft a response explaining what would be lost | +| **Accessibility concern** | Evaluate and propose a fix or rationale | +| **Design system concern** | Evaluate against discovered patterns | +| **Approval / positive** | Acknowledge | +| **Out of scope** | Draft a reply explaining why | + +### Step 3: Propose Responses + +Evaluate each comment on its technical merit. Do not reflexively agree +with every suggestion — assess whether the proposed change would +actually improve the code. When a comment is technically incorrect, +based on a misunderstanding of the code, or would degrade correctness, +performance, or maintainability, recommend pushback with a clear +technical rationale. + +Present each comment with a proposed response: + +```markdown +## Review Comment Summary + +### Comment 1 — {reviewer} on {file}:{line} +> {quoted comment text} + +**Category:** Code change request +**Assessment:** {Agree / Disagree / Partially agree — with rationale} +**Proposed response:** {your suggested reply} +**Code change needed:** Yes — {describe the change} +``` + +Wait for the user to approve, modify, or reject each response. + +### Step 4: Apply Approved Changes + +#### Code changes + +For comments requiring code changes: + +1. Read the affected file(s) +2. Apply the change +3. If the change affects behavior, update or add tests. Tests must + validate behavioral contracts through public interfaces — the same + standard as `/code`. Match existing test patterns. +4. Run the affected tests to verify +5. Run lint and format checks on the changed files. Fix any issues. +6. Commit using the project's commit format: + +```bash +git add {specific files} +git commit -m "{issue-key}: Address review feedback — {brief description}" +git push +``` + +#### Posting replies + +Write the reply to a temp file to avoid shell metacharacter issues. +Use the file-writing tool (Write) to create the file. + +Write `{approved reply text}` to `.artifacts/ui-implement/{issue-key}/tmp-reply.md`. + +Route each comment based on its `type` field from the fetch output: + +**When `type` is `"line_comment"`**, reply in-thread: + +```bash +python3 "$PR_COMMENTS_SCRIPT" reply --owner {owner} --repo {repo} --pr {pr-number} --body-file .artifacts/ui-implement/{issue-key}/tmp-reply.md --comment-id {id} +``` + +**When `type` is `"review"` or `"top_level"`**, post a top-level comment: + +```bash +python3 "$PR_COMMENTS_SCRIPT" reply --owner {owner} --repo {repo} --pr {pr-number} --body-file .artifacts/ui-implement/{issue-key}/tmp-reply.md +``` + +If the reply command fails, report the error and continue to the next +comment **without calling `log`**. + +After each **successful** reply, record the `id` in the responses log: + +```bash +python3 "$PR_COMMENTS_SCRIPT" log --responses-log .artifacts/ui-implement/{issue-key}/responses.jsonl --comment-id {id} +``` + +**If the log command fails, stop immediately** — continuing without +logging would allow duplicate replies on the next respond round. + +Clean up the temporary reply file: + +```bash +rm .artifacts/ui-implement/{issue-key}/tmp-reply.md +``` + +### Step 5: Update Response Log + +Write or update `.artifacts/ui-implement/{issue-key}/07-review-responses.md`: + +```markdown +# Review Responses — {issue-key} + +## Round {N} — {date} + +### Comment by {reviewer} on {file}:{line} +- **Comment:** {summary} +- **Category:** {category} +- **Response:** {what was replied} +- **Code change:** {Yes/No — description if yes} +- **Commit:** {hash, if code was changed} +``` + +### Step 6: Assess Re-Validation Need + +If code changes were made: +- Recommend re-running `/validate` to ensure all checks still pass +- Note which changes might affect test results + +If only clarification replies were posted: +- No re-validation needed + +### Step 7: Report to User + +Summarize: +- How many comments were addressed +- How many code changes were made +- How many replies were posted +- Whether re-validation is recommended +- Whether any comments remain unresolved + +## Output + +- PR comments posted (with user approval) +- Code changes committed and pushed (if applicable) +- `.artifacts/ui-implement/{issue-key}/07-review-responses.md` + +## When This Phase Is Done + +Report your results: +- Comments addressed and responses posted +- Code changes made and committed +- Re-validation recommendation +- Outstanding items + +Then return to the invoking workflow router for completion guidance. diff --git a/ui-implement/skills/revise.md b/ui-implement/skills/revise.md new file mode 100644 index 00000000..48e89956 --- /dev/null +++ b/ui-implement/skills/revise.md @@ -0,0 +1,134 @@ +--- +name: revise +description: Incorporate user feedback into the UI implementation plan. +--- + +# Revise Plan Skill + +You are a principal editor. Your job is to incorporate the user's feedback into the +implementation plan while maintaining internal consistency. + +## Your Role + +Read the user's feedback, apply changes to the plan, and ensure the plan +remains coherent after edits. This phase is repeatable — the user may request +multiple rounds of revision. This phase only modifies the plan, not code. + +## Critical Rules + +- **Change only what's requested.** Do not "improve" parts of the plan the user didn't mention. +- **Evaluate before applying.** Assess whether the requested change would introduce bugs, break behavioral contracts, violate design constraints, or reduce test coverage of critical paths. If it would, say so before making the change — explain the concern, recommend an alternative if you have one, and let the user decide. +- **Maintain consistency.** If a task change affects the test strategy, AC coverage, or UI cross-cutting concerns, update those sections too. +- **Preserve traceability.** Every task must still trace to an acceptance criterion after revision. +- **Show your changes.** After revising, summarize what changed so the user can verify. +- **No scope reduction.** Do not silently simplify, even when revising. +- **Preserve UI concerns.** If a task change affects design system usage, i18n keys, accessibility attributes, or state handling, update the UI Cross-Cutting Concerns table. + +## Process + +### Step 1: Read Current Plan + +Read `.artifacts/ui-implement/{issue-key}/02-plan.md`. + +If the plan doesn't exist, tell the user that `/plan` should be run first. + +Also read `.artifacts/ui-implement/{issue-key}/01-context.md` for reference +(acceptance criteria, validation profile, UI toolchain). + +### Step 2: Understand the Feedback + +The user's feedback may target: + +**Implementation approach changes:** +- Different approach ("Use an existing hook instead of a new one") +- Task reordering ("Move the types task before the component task") +- Task splitting ("Task 3 is too large, split it") +- Task combining ("Tasks 2 and 3 can be a single commit") + +**Test strategy changes:** +- Additional test coverage ("Add tests for the error state rendering") +- Different test approach ("Mock the API hook instead of the fetch call") +- Test removal ("We don't need to test the generated types") + +**Interface changes:** +- Different naming ("Use FleetDashboard, not FleetOverview") +- Different props ("The component should accept an onRefresh callback") +- Added or removed components/hooks + +**UI concern changes:** +- Different design system components ("Use a DataList instead of a Table") +- Different state handling ("Use a skeleton loader instead of a spinner") +- Accessibility adjustments ("Add a live region for status updates") +- i18n key changes + +Clarify with the user if the feedback is ambiguous before making changes. + +If the feedback is clear but would weaken the plan, raise the concern +before applying it. For example: + +- Removing error handling or empty state handling that guards against real failure modes +- Dropping tests for behavioral paths that are reachable through the public interface +- Changing an approach in a way that contradicts the ui-design document or acceptance criteria +- Introducing a dependency ordering problem between tasks +- Removing accessibility attributes from interactive elements + +Present the concern with specific reasoning, recommend an alternative +if you have one, and apply the change only after the user has considered +the tradeoff. The user may have context you lack — but they should make +an informed decision, not an unexamined one. + +### Step 3: Apply Changes + +Edit the plan: +- For specific edits: apply them directly +- For directional feedback: propose concrete changes and confirm before applying +- For new requirements: add tasks to the appropriate section + +### Step 4: Consistency Check + +After applying changes, verify: +- Does every acceptance criterion still have at least one task covering it? +- Does the task ordering still respect dependencies? +- Does the test strategy still align with the tasks? +- Do component/hook interface definitions match what the tasks describe? +- Are commit messages still properly formatted? +- If a Test Plan Coverage section exists: do the TC ID → Task mappings still reflect the current task breakdown? +- Does the UI Cross-Cutting Concerns table still accurately reflect the tasks? + +### Step 5: Update Artifact + +Overwrite `.artifacts/ui-implement/{issue-key}/02-plan.md` with the revised plan. + +### Step 6: Present Changes + +Summarize what changed: + +```markdown +## Revision Summary + +### Changes Applied +- Task 3: Changed component from DataTable to DataList per design system +- Test strategy: Added test for empty state rendering +- Interface: Renamed FleetOverview → FleetDashboard + +### Consistency Updates +- Task ordering adjusted — Task 4 now depends on Task 3 (was independent) +- AC coverage matrix updated to reflect new task mapping +- UI Cross-Cutting Concerns updated for new design system component + +### Items to Note +- The approach change in Task 3 reduces the number of new files from 4 to 2 +``` + +## Output + +- `.artifacts/ui-implement/{issue-key}/02-plan.md` (updated) + +## When This Phase Is Done + +Report your results: +- What was changed and why +- Any consistency updates made as a side effect +- Assessment of plan readiness for `/code` + +Then return to the invoking workflow router for completion guidance. diff --git a/ui-implement/skills/validate.md b/ui-implement/skills/validate.md new file mode 100644 index 00000000..d2b53d51 --- /dev/null +++ b/ui-implement/skills/validate.md @@ -0,0 +1,362 @@ +--- +name: validate +description: Run the full validation suite, analyze coverage, and iterate on gaps. +--- + +# Validate Implementation Skill + +You are a principal quality engineer. Your job is to run the project's full validation +suite, analyze test coverage, identify gaps, and iterate until the +implementation meets quality standards. + +## Your Role + +Execute every check from the validation profile (discovered during `/ingest`), +analyze the results, fix any issues, and assess whether the implementation is +ready for PR creation. This phase may loop — you fix issues, re-run checks, +and repeat until everything passes. + +## Critical Rules + +- **Run the project's actual commands.** Use the validation profile from `01-context.md`, not hardcoded commands. +- **Fix issues, don't skip them.** If linting fails, fix the code. If tests fail, diagnose and fix. Do not suppress warnings or skip checks. If the user asks to skip a failing check, evaluate the risk: explain what the failing check is testing, what behavior would go unverified if skipped, and whether skipping could mask a real bug, broken contract, or regression. Present this assessment to the user so they can make an informed decision. +- **Coverage is a signal, not a target.** If coverage shows an uncovered branch in a public component/hook, ask "Is there a behavioral contract I missed?" Write a test for the behavior, not the line. +- **New tests follow the same standards.** Any tests added during validation must validate behavioral contracts through public interfaces — no coverage-gaming tests. +- **Commit fixes separately.** Validation fixes get their own commits following the project's commit format. +- **Do not modify code outside the story's scope** to fix pre-existing lint or test issues. Note them in the validation report. + +## Process + +### Step 1: Read Context + +Read: +1. `.artifacts/ui-implement/{issue-key}/01-context.md` (validation profile) +2. `.artifacts/ui-implement/{issue-key}/02-plan.md` (what was implemented) +3. `.artifacts/ui-implement/{issue-key}/04-impl-report.md` (implementation status) +4. `.artifacts/ui-implement/{issue-key}/testplan.md` (story-scoped testplan, if exists) + +Extract the validation profile's pre-PR checks list. + +### Step 2: Check Base Branch Currency + +Before running checks, verify the branch is current with its base. + +Check the **Repository Topology** section of `01-context.md`. Read +`{owner}/{repo}` from the **Origin** field (the fork or direct clone). + +If the repo is a fork, sync the fork with upstream first: + +```bash +gh repo sync {owner}/{repo} --branch {pr-target} +``` + +If `gh repo sync` fails, warn the user and record the failure in the +validation report. Do not silently skip. + +Then, regardless of topology: + +```bash +git fetch origin +``` + +If `git fetch` fails, warn the user. Record the failure in the validation +report under Branch Currency as "Unable to verify — fetch failed." + +```bash +git rev-list --count HEAD..origin/{local-base} +``` + +If the branch is behind base, check whether a PR has already been +created by looking for `.artifacts/ui-implement/{issue-key}/publish-metadata.json`. + +**If no PR exists yet** (pre-publish), offer to rebase: + +```bash +git rebase origin/{local-base} +``` + +**If a PR already exists** (post-publish), offer to merge instead: + +```bash +git merge origin/{local-base} +``` + +If conflicts occur, stop and report to the user. If the user declines +either operation, continue but note the staleness in the validation report. + +### Step 3: Run Pre-PR Checks + +Execute each check from the validation profile in order. For each check: + +1. **Run the command** +2. **Capture the output** +3. **Assess the result:** pass, fail, or warning + +Typical checks (discovered, not hardcoded): +- Type checking (e.g., TypeScript compilation) +- Linting +- Unit tests +- Code formatting +- Build verification + +**If a check fails:** + +1. Diagnose the failure — is it caused by the story's changes or pre-existing? +2. If caused by the story's changes: fix it, commit the fix, re-run the check +3. If pre-existing: note it in the validation report, do not fix it +4. If unclear: report to the user + +### Step 4: Analyze Coverage + +Run coverage analysis on the packages affected by the story: + +1. Use the coverage command from the validation profile +2. Focus on the **new and modified code** specifically — compare the + coverage report's per-function or per-line breakdown against the + story's diff to isolate new-code coverage from pre-existing code +3. For each public component/hook added or modified: + - Are all rendering paths exercised by tests? + - Are user interaction paths tested? + - Are error, loading, and empty states tested? + - Are accessibility contracts tested (roles, aria attributes)? + +If coverage analysis reveals untested behavioral paths in new code: + +1. Write additional tests for the missing behaviors +2. Follow the same contract-based testing standards +3. Run the tests to verify they pass +4. Commit following the project's commit format +5. Re-run coverage to confirm improvement + +Read the **Minimum new-code coverage** percentage from the Coverage +Tooling section of `01-context.md` (discovered during `/ingest`, +defaults to 90% if the project does not specify one). + +If new code coverage through public API tests remains below that +threshold after filling behavioral gaps, **do not write tests that +reach into internals to close the gap.** Low coverage signals that +the component is too coarse-grained. Escalate to the user: + +- Report the current coverage and which code is unreachable through + public interfaces +- Recommend decomposing the component into smaller units with more + testable public APIs +- Note this in the validation report as a design concern + +### Step 5: Regression Check + +Verify that the story's changes haven't broken existing functionality: + +1. Run the full unit test suite (not just affected packages) +2. Run the full build (if applicable) +3. Check for any test failures unrelated to the story + +If regressions are found: +- Diagnose whether the story's changes caused them +- Fix regressions caused by the story, commit separately +- Note pre-existing failures in the validation report + +### Step 6: Code Quality Review + +After automated checks pass, review the story's full diff for issues +that automated tooling does not catch. Read the Local Base from the +`## Branch` section of `02-plan.md`, then run the self-review gate. + +Read and follow `../../_shared/recipes/self-review-gate.md` with these +parameters: + +| Parameter | Value | +|-----------|-------| +| DIFF_COMMAND | `git diff {local-base}...HEAD` | +| MAX_ROUNDS | `3` | +| CONTEXT_FILES | `.artifacts/ui-implement/{issue-key}/01-context.md`, `.artifacts/ui-implement/{issue-key}/02-plan.md` (if they exist) | +| SUPPLEMENTARY_CRITERIA | This is the full-branch validation review — the last quality gate before PR creation. In addition to the standard protocol criteria, evaluate: (1) **Design system compliance** — are design system components used consistently? Any raw HTML where a design system equivalent exists? (2) **i18n completeness** — are all user-visible strings wrapped with the i18n mechanism? (3) **Accessibility completeness** — do all interactive elements have ARIA attributes and keyboard handlers? (4) **State completeness** — are loading, error, and empty states handled for all data-dependent components? (5) **Backward compatibility** — does the change modify public component props or hook signatures? If so, is it backward-compatible? (6) **Completeness across usage sites** — if the story introduces a pattern (permission gate, error boundary, i18n wrapping), search for similar components needing the same treatment. A pattern applied to 7 of 8 similar components is itself a bug. | + +If the gate reports FLAG (unfixed CRITICAL or HIGH findings), stop and +present the findings to the user before proceeding. + +If the gate made code fixes, re-run the affected pre-PR checks from +Step 3 to verify the post-fix state. Once checks pass, commit: + +```bash +git add {fixed files} +git commit -m "{issue-key}: address validation review findings" +``` + +### Step 7: Acceptance Criteria Verification + +After automated checks and code quality review, verify that every +acceptance criterion from the story has been satisfied. + +1. Read the **Acceptance Criteria** from `01-context.md` +2. Read the **Acceptance Criteria Coverage** matrix from `02-plan.md` +3. For each acceptance criterion: + - **Trace to implementation:** Is there code that implements this + criterion? Follow the task mapping — check that the task is marked + Done and that the corresponding code exists. + - **Trace to tests:** Is there at least one test that verifies this + criterion's behavior through a public interface? + - **Assess satisfaction:** Based on the implementation and tests, + is the criterion fully satisfied, partially satisfied, or not + addressed? + +Record the result for each criterion. If any criterion is not fully +satisfied: + +1. If it's a gap in implementation or tests — fix it, commit the fix, + and re-run the relevant checks +2. If it's ambiguous whether the criterion is met — flag it to the + user with your assessment +3. If the criterion cannot be verified through automated means (e.g., + it requires visual verification or describes a UX quality) — note + it as "requires manual verification" + +### Step 7b: Test Plan Verification + +If `.artifacts/ui-implement/{issue-key}/testplan.md` exists, independently +verify that every test case has been implemented. This check re-derives +the required TC ID list from `testplan.md` directly — it does NOT rely +on the plan's task-to-TC-ID mappings or `/code`'s per-task reconciliation. +This is an intentional independent verification. + +If `testplan.md` does not exist and `02-plan.md` has no Test Plan +Coverage section, skip this step entirely. + +1. Read `testplan.md` and extract all TC IDs. Verify that Preconditions, + Steps, and Expected Results sections are present for each entry. +2. For each TC ID (except those legitimately N/A based on the plan's + rationale): + - Search the test files on the feature branch for a test whose + scenario matches the TC's Steps and whose assertions match the + Expected Results. + - Record the test file and test name for each TC ID. +3. If any TC ID lacks a corresponding test: + - Write the missing test following contract-based testing standards. + - Commit the test following the project's commit format. + - Re-run the relevant checks from Step 3. +4. Record results for the validation report. + +### Step 8: Write Validation Report + +Write `.artifacts/ui-implement/{issue-key}/05-validation-report.md`: + +```markdown +# Validation Report — {issue-key} + +## Branch Currency + +{Current with base / N commits behind {local-base} — rebased before validation + / N commits behind {local-base} — user chose to continue without rebasing} + +## Check Results + +| Check | Command | Result | Notes | +|-------|---------|--------|-------| +| {name} | `{command}` | {pass/fail/warning} | {brief note} | + +## Coverage Analysis + +### Packages Affected +| Package | Coverage | Notes | +|---------|----------|-------| +| {path} | {qualitative assessment} | {behavioral paths covered} | + +### Behavioral Coverage Assessment +{Qualitative description of what's covered and what's not. Focus on + whether all behavioral contracts of public interfaces are tested.} + +### Design Concern — Decomposition Needed +{If new code coverage through public API tests is below the minimum + threshold: flag it. Otherwise: "No decomposition concern."} + +### Tests Added During Validation +| Test File | Tests Added | Reason | +|-----------|-------------|--------| +| {path} | {count} | {which behavioral gap it fills} | + +{If no tests added: "No additional tests needed."} + +## Regressions + +{Any test failures in existing tests. Distinguish between caused by + this story's changes vs. pre-existing. + If none: "No regressions detected."} + +## Acceptance Criteria Verification + +| AC | Description | Implementation | Tests | Status | +|----|-------------|----------------|-------|--------| +| AC-1 | {brief} | {file or commit} | {test file:test name} | {satisfied/partial/manual verification} | + +## Test Plan Verification + +{Include only if testplan.md exists. Omit entirely otherwise.} + +| TC ID | Title | Test File | Test Name | Status | +|-------|-------|-----------|-----------|--------| +| TC-FR1-01 | {title} | {file} | {test name} | covered | + +## UI Cross-Cutting Verification + +| Concern | Status | Notes | +|---------|--------|-------| +| Design system compliance | {pass/issues found} | {details} | +| i18n completeness | {pass/issues found} | {details} | +| Accessibility | {pass/issues found} | {details} | +| State completeness | {pass/issues found} | {details} | + +## Quality Review Findings + +{Findings from the code quality review gate. If none: "No quality review findings."} + +## Pre-existing Issues + +{Lint warnings, test failures, or other issues that existed before this + story. If none: "No pre-existing issues observed."} + +## Validation Commits + +| Hash | Message | +|------|---------| +| {short hash} | {commit message} | + +{If no validation commits: "No additional commits needed during + validation."} + +## Result + +{PASS — all checks pass, coverage is comprehensive, all acceptance + criteria satisfied, no regressions. + OR + FAIL — with explanation of what still needs fixing.} +``` + +### Step 9: Present Results + +Summarize for the user: +- Which checks passed and which failed +- Coverage assessment (behavioral, not numeric) +- Acceptance criteria status +- Test plan verification status (if testplan exists) +- UI cross-cutting verification status +- Any tests added during validation +- Any regressions found +- Overall verdict: ready for `/publish` or not + +## Output + +- `.artifacts/ui-implement/{issue-key}/05-validation-report.md` +- Additional test files (if coverage gaps were found) +- Fix commits (if issues were found and fixed) + +## When This Phase Is Done + +Report your results: +- Validation check results (all pass / some fail) +- Coverage assessment +- Acceptance criteria status +- UI cross-cutting status +- Regression status +- Overall verdict + +Then return to the invoking workflow router for completion guidance. diff --git a/ui-implement/templates/01-context.md b/ui-implement/templates/01-context.md new file mode 100644 index 00000000..27178fde --- /dev/null +++ b/ui-implement/templates/01-context.md @@ -0,0 +1,187 @@ +# Story Context — {issue-key} + +## Story Summary + +- **Title:** {title} +- **Type:** {story type prefix, e.g., [UI]} +- **Jira:** {issue-key} +- **Epic:** {parent epic key and title} +- **Feature:** {parent feature key, if known} + +### User Story + +{As a... I want... So that...} + +### Acceptance Criteria + +{Numbered list, preserving original wording} + +### Implementation Guidance + +{From the story or design document. If none: "No implementation guidance provided."} + +### Testing Approach + +{From the story or design document. If none: "No specific testing approach prescribed — follow project conventions."} + +### Dependencies + +| Story | Status | Merged | Risk | +|-------|--------|--------|------| +| {key} | {jira status} | {yes/no} | {brief risk note} | + +{If no dependencies: "No story dependencies."} + +## Design Context + +### UI Design Sections + +{2–5 locked bullets per cited section for this story (component tree, hook interface, state shape, route, data flow, accessibility requirement). Refs like [UI Design: §4.1]. Not a paraphrase of the chapter.} + +### Relevant Design Sections + +{2–5 locked bullets per cited section for this story (API contract, data model, flow). Refs like [Design: §4.1]. If no general design sections apply: "No general design sections cited."} + +### Handoff Context + +{If handoff.md found: interaction specs, state matrix entries, component mapping items relevant to this story. Refs like [Handoff: §x.y]. + If not found: "No handoff document available."} + +### API Findings + +{If api-findings.md found: resolved endpoints, mock strategies for this story. Refs like [API: §x.y]. + If not found: "No API findings document available."} + +### PRD Requirements Covered + +{One clause per FR/NFR ID, not an ID-only list. From the story or slices already read.} + +### Story Test Plan + +{If written: "Story-scoped test plan written to `.artifacts/ui-implement/{issue-key}/testplan.md` with {N} test cases. TC IDs: {list}." + + If feature testplan exists but no matches (expected): "Feature-level testplan found but no cases match this {story-type} story (expected). No story-scoped testplan written." + + If feature testplan exists but no matches (anomalous): "Feature-level testplan found but no cases reference this {story-type} story (anomalous). No story-scoped testplan written." + + If no feature testplan: "No feature-level testplan available. No story-scoped testplan written."} + +## Codebase Context + +### Affected Components + +#### {Component Name} +- **Location:** {path} +- **Purpose:** {what it does} +- **Current patterns:** {relevant patterns to follow} +- **What changes:** {brief note on what the story requires} +- **Existing tests:** {test file locations, framework, patterns} + +### Cited, not opened + +| Path | Why | +|------|-----| +| {path} | {one line: pattern-only / shared hook / leftover grep hit} | + +{If none: "None."} + +### Relevant Types and Interfaces + +{TypeScript signatures only, not implementations.} + +### Relevant APIs + +{Endpoints, hooks, or specs this story extends or calls.} + +## Repository Topology + +- **Origin:** {owner}/{repo from `git remote get-url origin`} +- **Type:** Fork | Direct {from `isFork` on that origin repo, not a substituted upstream} +- **Upstream:** {upstream-owner}/{upstream-repo} (fork only, omit if direct) + +## UI Toolchain + +### Test Infrastructure + +- **Unit test framework:** {discovered framework (e.g., "vitest", "jest") or "None — see recommendation below"} +- **Testing library:** {discovered testing library (e.g., "@testing-library/react") or "None"} +- **Test run command:** {discovered command or "N/A"} +- **Test file pattern:** {discovered pattern (e.g., "*.test.tsx", "*.spec.tsx") or "N/A"} +- **Test utilities:** {project-specific test helpers, render wrappers, mocks} + +{If no unit test framework found:} +#### Recommendation: Introduce Unit Testing +- **Recommended framework:** {framework based on build tooling} +- **Rationale:** {why this framework fits the project} +- **Required packages:** {list of npm packages} +- **Configuration:** {brief config description} + +### Design System + +- **Package:** {discovered package (e.g., "@patternfly/react-core") or "None — raw HTML/CSS"} +- **Import pattern:** {how components are imported} +- **Token usage:** {CSS variables, theme tokens, or "N/A"} + +### Internationalization + +- **Library:** {discovered library or "None — no i18n in project"} +- **Wrapping convention:** {e.g., "t('key')", "", or "N/A"} +- **Key structure:** {key naming convention or "N/A"} +- **Translation files:** {path to translation files or "N/A"} + +### State Management + +- **Approach:** {discovered approach (e.g., "React Query for server state, React context for client state")} +- **Data fetching:** {pattern description} + +### Routing + +- **Library:** {discovered library or "N/A"} +- **Pattern:** {route organization pattern} + +### Permission/RBAC + +- **Mechanism:** {discovered pattern or "None — no permission checks in UI"} +- **Usage pattern:** {how permission checks are applied} + +### E2E Framework + +- **Framework:** {discovered framework or "None — no e2e tests in project"} +- **Test location:** {path or "N/A"} +- **Run command:** {command or "N/A"} + +## Validation Profile + +### Commit Format +- **Pattern:** {e.g., "JIRA-KEY: Description"} +- **Discovered from:** {source file} + +### Pre-PR Checks (ordered) +1. `{command}` — {purpose} + +### PR Conventions +- **Title format:** {discovered format} +- **PR template:** {path or "None — use default template"} +- **Description guidance:** {from CONTRIBUTING.md or AGENTS.md} + +### Coverage Tooling +- **Command:** {how to generate coverage} +- **Report location:** {where reports are written} +- **View command:** {if available} +- **Minimum new-code coverage:** {from AGENTS.md/CLAUDE.md, default 90%} + +### Discovered from +{Files read to build this profile} + +## Open Questions + +Fill each slot with a concrete question or `N/A (reason)`: + +- **Component props contract:** {expected props shape / render behavior, or N/A} +- **Story boundary:** {vs dependency or successor, or N/A} +- **Spec vs AC:** {conflict: record both; or N/A} +- **Missing design system component:** {needed but not available, or N/A} +- **Placement:** {existing module vs new, or N/A} +- **Permission gate:** {RBAC check not in current code, or N/A} +- **Loading/error/empty states:** {not specified in design, or N/A} +- **i18n keys:** {naming convention unclear, or N/A} diff --git a/ui-implement/templates/story-testplan.md b/ui-implement/templates/story-testplan.md new file mode 100644 index 00000000..2cf55f0e --- /dev/null +++ b/ui-implement/templates/story-testplan.md @@ -0,0 +1,26 @@ +# Story Test Plan — {issue-key} + +- **Source:** {docs-repo-path}/testplan.md +- **Story:** {issue-key} — {story-title} +- **Test cases:** {count} + +One `## {tc-id}` section per filtered story test case: + +## {tc-id}: {scenario title} + +| Requirement | Interface Change | Priority | Automation | +|-------------|------------------|----------|------------| +| {requirement-id} | {interface-change-id} | {priority} | {automation} | + +### Preconditions + +- {precondition} + +### Steps + +1. {step} +2. {step} + +### Expected Results + +- {expected outcome} From 7fc81b844bee388397df475f0295322df937a2cd Mon Sep 17 00:00:00 2001 From: Chai Bot Date: Thu, 1 Oct 2026 19:57:36 +0000 Subject: [PATCH 02/12] ui-implement: flatten step numbering and remove hardcoded paths MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - code.md: Promote lettered substeps (3a–3i) to sequential Steps 4–12, rename Step 3-post to Step 13, renumber Steps 4–6 to Steps 14–16, update all internal cross-references - code.md: Remove hardcoded commit format placeholder from e2e stubs section; reference discovered format from 01-context.md instead - ingest.md: Promote lettered substeps (5a–5d) to sequential Steps 5–8, renumber Steps 6–9 to Steps 9–12, update all internal cross-references - ingest.md: Replace HOME-based absolute path with relative path reference for fetch-issue.py script resolution Assisted-by: Claude Opus 4.6 --- ui-implement/skills/code.md | 58 ++++++++++++++++------------------- ui-implement/skills/ingest.md | 41 ++++++++++++------------- 2 files changed, 47 insertions(+), 52 deletions(-) diff --git a/ui-implement/skills/code.md b/ui-implement/skills/code.md index 9621c23d..85b5c550 100644 --- a/ui-implement/skills/code.md +++ b/ui-implement/skills/code.md @@ -136,7 +136,7 @@ git merge origin/{local-base} ``` If conflicts occur during either operation, follow the same conflict -handling as Step 3h (stop, show conflicts, offer to resolve, proceed +handling as Step 11 (stop, show conflicts, offer to resolve, proceed only with user approval). Verify the starting point: @@ -147,8 +147,8 @@ git log --oneline -5 ### Step 3: Execute Tasks -For each task in the plan, follow this cycle. **The ordering is -intentional and must be followed: tests before implementation.** Write +For each task in the plan, follow the cycle in Steps 4–12. **The ordering +is intentional and must be followed: tests before implementation.** Write the unit tests first, verify they fail for the right reason (the production code doesn't exist yet), then write the implementation that makes them pass. Do not write the implementation first and add tests @@ -162,14 +162,14 @@ includes Task 0 for introducing a unit test framework, execute it as specified in the plan (install, configure, smoke test). This task does not follow TDD since it is infrastructure setup, not behavioral code. -#### 3a: Read Affected Files +### Step 4: Read Affected Files Before making any changes, read: - Every file listed in the task's "Files" section - Existing test files in the same directory/module (to match patterns) - Any components, hooks, or types referenced by the task -#### 3b: Write Unit Tests FIRST +### Step 5: Write Unit Tests FIRST Write tests that define the behavioral contracts for this task: @@ -198,9 +198,9 @@ Write tests that define the behavioral contracts for this task: 6. **Name tests after the contract they validate,** not after bugs discovered during development. -#### 3c: Write Implementation (after tests exist) +### Step 6: Write Implementation (after tests exist) -Write the production code that makes the tests from 3b pass: +Write the production code that makes the tests from Step 5 pass: 1. Follow existing component/hook patterns in the project 2. Match naming conventions, file organization, and code style @@ -229,7 +229,7 @@ Write the production code that makes the tests from 3b pass: - Documenting callers or consumers - Repeating the same explanation at every usage site -#### 3d: Run Tests +### Step 7: Run Tests Look up the test commands from the **Pre-PR Checks** section of `01-context.md`. Each entry has a purpose label (e.g., "unit test", @@ -243,7 +243,7 @@ Fix any failures before proceeding. If a test failure is ambiguous, use diagnostic failure routing (see below). -#### 3e: Lint and Format +### Step 8: Lint and Format Before committing, run the fast quality checks on the files changed by this task. Look up the lint and format commands from the **Pre-PR Checks** @@ -264,7 +264,7 @@ any remaining issues once all tasks are complete and the code compiles. Do not run the full validation suite here — save expensive checks (full test suite, coverage analysis) for `/validate`. -#### 3f: Code Review +### Step 9: Code Review Stage the task's changes first — the review and commit steps both operate on the staged diff: @@ -289,7 +289,7 @@ If the gate reports FLAG (unfixed CRITICAL or HIGH findings), stop and present the findings to the user before committing. If the gate made code fixes, re-stage the affected files, then re-run -the task-scoped tests (Step 3d) and fast quality checks (Step 3e) to +the task-scoped tests (Step 7) and fast quality checks (Step 8) to verify the fixes. Only proceed to commit once checks pass. Note any dismissed findings in the implementation report (Discoveries section) so there is a paper trail. @@ -305,13 +305,13 @@ does, verify each mapped TC ID before proceeding to commit: inconsistency. Read the full test case entry (the Preconditions, Steps, and Expected Results sections). If any of these sections is missing, stop and report the testplan as malformed. -2. Verify that a test exists (written in Step 3b or a prior task) +2. Verify that a test exists (written in Step 5 or a prior task) whose assertions validate the Expected Results described in the test case. The match is behavioral, not textual — the test must exercise the described scenario and assert the described outcomes. 3. If a TC ID mapped to this task has no corresponding test with - sufficient assertion depth, write the missing test (Step 3b), run - it (Step 3d), run the fast quality checks (Step 3e), stage the new + sufficient assertion depth, write the missing test (Step 5), run + it (Step 7), run the fast quality checks (Step 8), stage the new files (`git add`), re-run the review gate, then re-check. This is a hard gate — the task cannot proceed to commit until every @@ -325,16 +325,12 @@ Coverage section, skip this check. However, if `02-plan.md` has TC mappings but `testplan.md` is missing or malformed, stop and report the inconsistency. -#### 3g: Commit +### Step 10: Commit -The changes are already staged from Step 3f. Create the commit: +The changes are already staged from Step 9. Create the commit using the +format from the **Commit Format** section of `01-context.md`. -```bash -git commit -m "{issue-key}: {task description}" -``` - -Follow the commit format from the **Commit Format** section of -`01-context.md`. The commit message must: +The commit message must: - Use the discovered format - Describe what the code does, not the development journey - Be independently meaningful @@ -342,7 +338,7 @@ Follow the commit format from the **Commit Format** section of If the commit fails (e.g., rejected by pre-commit hooks), diagnose and fix the issue before proceeding to the sync step. -#### 3h: Sync with Base +### Step 11: Sync with Base After committing, rebase onto the latest base branch to keep subsequent tasks building against head-of-line. @@ -371,7 +367,7 @@ git rev-list --count HEAD..origin/{local-base} ``` If the count is 0, no new upstream commits exist — skip the rebase and -test re-run, and proceed directly to Step 3i. +test re-run, and proceed directly to Step 12. If new commits exist, check whether a PR has already been created by looking for `.artifacts/ui-implement/{issue-key}/publish-metadata.json`. @@ -390,7 +386,7 @@ git merge origin/{local-base} If the operation applies cleanly, re-run the task's tests to confirm the committed work still passes against the updated base. If tests -fail, diagnose using the failure routing in Step 4. +fail, diagnose using the failure routing in Step 14. **If there are conflicts:** @@ -402,7 +398,7 @@ fail, diagnose using the failure routing in Step 4. 5. After resolution, run `git rebase --continue` or commit the merge resolution as appropriate, then re-run the task's tests -#### 3i: Update Plan +### Step 12: Update Plan Mark the task as completed in `02-plan.md`: - Change `Pending` to `Done` @@ -411,7 +407,7 @@ Update the status immediately after each task, not in bulk at the end. This is the checkpoint that allows the session to resume correctly if interrupted. -### Step 3-post: Write Integration/E2E Test Stubs +### Step 13: Write Integration/E2E Test Stubs After all plan tasks are complete (all marked `Done`), check whether the plan includes an integration/e2e test stubs task. If it does: @@ -431,12 +427,12 @@ plan includes an integration/e2e test stubs task. If it does: ```bash git add {stub files} -git commit -m "{issue-key}: add integration/e2e test stubs" +git commit -m "{use commit format from 01-context.md}" ``` If the project has no e2e framework, skip this step entirely. -### Step 4: Diagnostic Failure Routing +### Step 14: Diagnostic Failure Routing When tests fail, diagnose **where** the problem is before fixing: @@ -449,7 +445,7 @@ When tests fail, diagnose **where** the problem is before fixing: | **Provider/wrapper missing** | Test fails because a required context provider is not in the test render wrapper | Add the provider to the test setup | | **Environment issue** | Test infrastructure unavailable, missing dependency | Report to user — this is not a code problem | -### Step 5: Deviation Rules +### Step 15: Deviation Rules During implementation, you may encounter unexpected situations: @@ -464,7 +460,7 @@ During implementation, you may encounter unexpected situations: | Implementation is significantly more complex than planned | **Stop and ask the user** — the story may need re-scoping | Required | | Accessibility requirement unclear or conflicting | **Stop and ask the user** — a11y must not be guessed | Required | -### Step 6: Write Reports +### Step 16: Write Reports After all tasks are complete (or if interrupted), write: diff --git a/ui-implement/skills/ingest.md b/ui-implement/skills/ingest.md index ea373329..fe43dcff 100644 --- a/ui-implement/skills/ingest.md +++ b/ui-implement/skills/ingest.md @@ -13,13 +13,13 @@ for `/plan`. - Jira is read-only. Capture, don't implement. Note unknowns explicitly. - Explore relevant areas only. Don't map the entire codebase. Focus on components the story will affect. -- Re-invocation diffs before overwriting. If `01-context.md` already exists, preserve it before exploring. After compiling new context, diff against the previous version and present changes to the user before overwriting (see Steps 2a and 8a). +- Re-invocation diffs before overwriting. If `01-context.md` already exists, preserve it before exploring. After compiling new context, diff against the previous version and present changes to the user before overwriting (see Steps 2a and 11a). - Ingest is an index. `/plan` opens cited files. Paths, section refs, signatures — not dumps. - Never Read the same path twice. Never Grep the same (path, pattern) pair twice. - Do not glob this workflow. Do not load `guidelines.md` or `gh-stack`. - Do not re-read `AGENTS.md` / `CLAUDE.md` if already in session. - Grep locates; Read loads. Never grep `.`. Never grep `-A`/`-B`/`-C`. Never grep `.git/`. -- Do not glob the docs repo root. After Step 5b, search only the feature directory. +- Do not glob the docs repo root. After Step 6, search only the feature directory. - **Write each output path once.** No Delete+rewrite, no second Write to the same file. - Do not call `GetDynamicTools` / list Jira tools. Use the shared fetch-issue script. - **Discover, don't assume.** Never hardcode assumptions about test runners, design systems, i18n libraries, or any UI tooling. All tool choices come from the codebase. @@ -39,14 +39,15 @@ environment variables. ## Jira call (use as-is) -Resolve the shared script to an absolute path so it remains valid -regardless of working directory: +Resolve the shared script to an absolute path at runtime. The path is +relative to this file: -```bash -FETCH_ISSUE_SCRIPT="${HOME}/.ai-workflows/_shared/scripts/fetch-issue.py" +``` +../../_shared/scripts/fetch-issue.py ``` -Use `$FETCH_ISSUE_SCRIPT` instead of the relative path in all subsequent +Before the first Jira call, resolve this to an absolute path and assign +it to `FETCH_ISSUE_SCRIPT`. Use `$FETCH_ISSUE_SCRIPT` in all subsequent commands. - **Story:** `python3 "$FETCH_ISSUE_SCRIPT" get {KEY} --fields summary,description,issuetype,status,labels,fixVersions --parent --parent-fields summary,status,issuetype,parent --links --link-fields summary,status` @@ -114,13 +115,11 @@ If dependencies are unresolved, **warn the user** but do not block. Report: - What risk this presents (merge conflicts, missing APIs, etc.) - A recommendation to proceed with caution or wait -### Step 5: Load Upstream Context +### Step 5: Resolve the Docs Repo The ui-design document, PRD, and related documents are published to a docs repo by the prd, design, and ui-design workflows. Fetch them from there. -#### 5a: Resolve the Docs Repo - Check for an existing docs repo configuration at `.artifacts/config.json`. This config is workspace-level and shared across all workflows — a prior workflow run may have already created it. @@ -134,7 +133,7 @@ If any check fails, tell the user and re-ask. Resolve `~` to an absolute path be If it does not exist, ask for docs repo local path and remote. Resolve `~` to absolute. Write `.artifacts/config.json` with `docs_repo_path` and `docs_repo_remote`. -#### 5b: Find the Feature Directory +### Step 6: Find the Feature Directory The docs repo organizes documents by Feature-level Jira issue. To find the right directory, walk the Jira hierarchy from the story: @@ -165,7 +164,7 @@ ask the user to choose. If the hierarchy traversal fails or no directory is found, ask the user for the path to the relevant documents within the docs repo. -#### 5c: Read Upstream Documents (section-scoped) +### Step 7: Read Upstream Documents (section-scoped) Do **not** Read an entire `ui-design.md`, `design.md`, `prd.md`, or `testplan.md`. Those files are often thousands of lines. Search, then slice. @@ -193,7 +192,7 @@ Need (in priority order): criteria enrichment 5. **API findings** (`api-findings.md`) — **optional.** Resolved endpoints, API gaps, mock strategies -6. **Testplan** (`testplan.md`) — candidate test cases for Step 5d +6. **Testplan** (`testplan.md`) — candidate test cases for Step 8 If `ui-design.md` is not found, **warn the user** — this is the primary design input for UI stories. Ask whether to proceed with only the Jira story @@ -202,7 +201,7 @@ and general design document, or to wait for the ui-design document. If `design.md` or `prd.md` are not found, proceed with available context — the story's acceptance criteria are the primary contract. -#### 5d: Filter Testplan to Story Scope +### Step 8: Filter Testplan to Story Scope Match the story's `Validated by` TC IDs (captured in Step 3) against the testplan's test-case headings. If `Validated by` is missing, empty, or @@ -218,7 +217,7 @@ Design Reference. No feature testplan: note and continue. -### Step 6: Explore the Codebase +### Step 9: Explore the Codebase Based on the story's scope, explore the areas of the codebase that will be affected. @@ -232,7 +231,7 @@ affected. - Stack: `git branch --show-current`, `git log --oneline -8`, `gh stack view --json`. No `.git/` listing. - Topology: parse `{owner}/{repo}` from `git remote get-url origin` (never substitute a well-known upstream name). Then `gh repo view {owner}/{repo} --json isFork,parent`. If `gh` fails, ask the user whether this is a fork and, if so, for upstream `{owner}/{repo}`. -**Validation cache:** If `.artifacts/ui-implement/_validation-profile.md` exists and `.meta.json` hashes/mtimes still match, merge the profile into the in-memory context draft, skip config Reads, and do not Write `01-context.md` until Step 8 or Step 8a. Else one discovery pass: bounded Greps of present `AGENTS.md` and `CONTRIBUTING.md` (unless already in session) for lint/test/coverage commands, one Makefile grep, plus CI filenames via `git ls-files '.github/workflows/*.yml' '.github/workflows/*.yaml'`. For each listed workflow, Grep command-bearing keys (`run:`, `make`, lint/test targets) — not full workflow bodies. Then Write cache files **once**. +**Validation cache:** If `.artifacts/ui-implement/_validation-profile.md` exists and `.meta.json` hashes/mtimes still match, merge the profile into the in-memory context draft, skip config Reads, and do not Write `01-context.md` until Step 11 or Step 11a. Else one discovery pass: bounded Greps of present `AGENTS.md` and `CONTRIBUTING.md` (unless already in session) for lint/test/coverage commands, one Makefile grep, plus CI filenames via `git ls-files '.github/workflows/*.yml' '.github/workflows/*.yaml'`. For each listed workflow, Grep command-bearing keys (`run:`, `make`, lint/test targets) — not full workflow bodies. Then Write cache files **once**. Skip `AGENTS.md` and `CONTRIBUTING.md` Reads if already in session. Path-only for PR template unless the body is required. @@ -312,7 +311,7 @@ Record components as path + signature + test path. `/plan` opens cited files. - **Cite what `/plan` would not guess** (path + one line; extra grep hits stay unread): sibling implementation in another component ("pattern only, do not import"); shared hooks or utilities; neighboring unit test paths if grep found them. List leftover `files_with_matches` hits under **Cited, not opened**. - **Open questions:** Fill or mark `N/A (reason)` for: component props contract; story boundary vs dependency/successor; spec vs AC conflict (record both, do not pick); missing design system component; placement (existing module vs new); permission gate not in current code; loading/error/empty state not specified. Concrete question or N/A. No vague "how should errors work?" -### Step 7: Discover UI Cross-Cutting Concerns +### Step 10: Discover UI Cross-Cutting Concerns Based on the codebase exploration, document the cross-cutting patterns that `/code` must follow. These are discovered, not assumed: @@ -332,7 +331,7 @@ Based on the codebase exploration, document the cross-cutting patterns that 7. **Loading state patterns:** How are loading indicators rendered? Skeletons, spinners, or placeholders? -### Step 8: Compile Context +### Step 11: Compile Context Compile all findings into `01-context.md`. If this is a re-invocation (Step 2a found an existing file), **do not write the file yet** — hold the @@ -343,7 +342,7 @@ fill it tightly (must-record bullets; 5–8 lines per component; signatures only; every open-question slot filled or N/A), Write `01-context.md` **once**. -### Step 8a: Diff Against Prior Ingest (Re-invocation Only) +### Step 11a: Diff Against Prior Ingest (Re-invocation Only) Diff compiled content vs `.prev`. Focus on: - Acceptance criteria @@ -355,7 +354,7 @@ Diff compiled content vs `.prev`. Focus on: If `02-plan.md` or later artifacts exist, list them. Wait for confirmation. If confirmed, Write `01-context.md` **once** and delete `.prev`. If declined, delete `.prev` and stop without overwriting. -### Step 9: Report +### Step 12: Report 8–12 lines. Do not paste `01-context.md`. Point at the file. Include: - Story scope and key ACs @@ -370,7 +369,7 @@ If `02-plan.md` or later artifacts exist, list them. Wait for confirmation. If c - Open questions as `/plan` work, not blockers - Readiness for `/plan` -If the user declined overwrite in 8a, report the diff and that existing context was kept. +If the user declined overwrite in 11a, report the diff and that existing context was kept. ## Output From 9a09fc10ab808531ef3df953d5e9868f1c553220 Mon Sep 17 00:00:00 2001 From: Chai Bot Date: Thu, 1 Oct 2026 20:00:05 +0000 Subject: [PATCH 03/12] ui-implement: fix Task 0 gating, check-existing fork qualification, push approval MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - plan.md: Task 0 no longer blocks story task planning — all tasks are planned alongside it; the user approves the framework recommendation as part of the normal plan review; /code runs Task 0 first - publish.md: Fork-qualify the --head argument in check-existing invocation to match create-pr convention ({fork-owner}:{branch-name}) - respond.md: Separate git push from git commit with an explicit user approval gate — confirm with the user before pushing review changes Assisted-by: Claude Opus 4.6 --- ui-implement/skills/plan.md | 13 ++++++++----- ui-implement/skills/publish.md | 11 ++++++++++- ui-implement/skills/respond.md | 7 +++++++ 3 files changed, 25 insertions(+), 6 deletions(-) diff --git a/ui-implement/skills/plan.md b/ui-implement/skills/plan.md index f3cbe417..bfb7d9c6 100644 --- a/ui-implement/skills/plan.md +++ b/ui-implement/skills/plan.md @@ -58,16 +58,19 @@ Check the **Test Infrastructure** section of `01-context.md`: - **If a unit test framework exists:** proceed normally. Plan tests using the discovered framework and patterns. - **If no unit test framework exists:** the context will include a - recommendation. Plan a **Task 0: Introduce unit testing framework** that: + recommendation. Include a **Task 0: Introduce unit testing framework** + in the plan that: 1. Installs the recommended test framework and testing library 2. Adds test scripts to `package.json` 3. Creates a minimal test configuration file 4. Writes one smoke test for an existing simple component to verify the setup 5. Runs the test to confirm the framework works - Present the framework recommendation to the user for approval. Task 0 must - be completed and approved before any story tasks are planned — the test - strategy for all subsequent tasks depends on the chosen framework. + Plan all story tasks normally alongside Task 0 — use the recommended + framework for the test strategy. Present the framework recommendation + as part of the plan review; the user approves it when they approve + the plan. `/code` runs Task 0 first so the framework is in place + when subsequent tasks execute. ### Step 2: Determine Local Base and PR Target @@ -221,7 +224,7 @@ Write `.artifacts/ui-implement/{issue-key}/02-plan.md` with this structure: - **Files:** {package.json, test config, smoke test file} - **What:** {install framework, configure, write smoke test} -- **Why:** No unit test framework exists — required before any story tasks +- **Why:** No unit test framework exists — must run first during /code - **Commit message:** `{use commit format from 01-context.md}` - **Status:** Pending diff --git a/ui-implement/skills/publish.md b/ui-implement/skills/publish.md index 12e79ed7..b44bbca5 100644 --- a/ui-implement/skills/publish.md +++ b/ui-implement/skills/publish.md @@ -186,7 +186,16 @@ In either case, save the result to Check the **Repository Topology** section of `01-context.md` to determine whether this is a fork-based workflow. -First, check whether a PR already exists for this branch: +First, check whether a PR already exists for this branch. Use the same +`--head` format that `create-pr` uses — fork-qualified for forks: + +**If the repo is a fork:** + +```bash +python3 "$PUBLISH_SCRIPT" check-existing --repo {upstream-owner}/{repo} --head {fork-owner}:{branch-name} +``` + +**If the repo is a direct clone:** ```bash python3 "$PUBLISH_SCRIPT" check-existing --repo {upstream-owner}/{repo} --head {branch-name} diff --git a/ui-implement/skills/respond.md b/ui-implement/skills/respond.md index a257a8e4..07d40b47 100644 --- a/ui-implement/skills/respond.md +++ b/ui-implement/skills/respond.md @@ -140,6 +140,13 @@ For comments requiring code changes: ```bash git add {specific files} git commit -m "{issue-key}: Address review feedback — {brief description}" +``` + +7. After all approved code changes are committed and replies posted, + confirm with the user before pushing. Present the list of commits + to push: + +```bash git push ``` From cc6058feddd454fe78911405b0a28b227389d9f3 Mon Sep 17 00:00:00 2001 From: Chai Bot Date: Thu, 1 Oct 2026 20:02:46 +0000 Subject: [PATCH 04/12] ui-implement: fix validate step numbering, result template, and artifact docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - validate.md: Promote Step 7b to standalone Step 8, renumber former Steps 8–9 to Steps 9–10 for sequential numbering - validate.md: Restructure Result section so the verdict token (PASS or FAIL) appears as a single first-line token, not embedded in prose - README.md: Document _validation-profile.md and .meta.json in the Artifacts section as repo-level cached artifacts Assisted-by: Claude Opus 4.6 --- ui-implement/README.md | 4 ++++ ui-implement/skills/validate.md | 18 +++++++++++------- 2 files changed, 15 insertions(+), 7 deletions(-) diff --git a/ui-implement/README.md b/ui-implement/README.md index 523e7830..6fb307ee 100644 --- a/ui-implement/README.md +++ b/ui-implement/README.md @@ -114,6 +114,10 @@ All artifacts are stored in `.artifacts/ui-implement/{issue-key}/`. 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 diff --git a/ui-implement/skills/validate.md b/ui-implement/skills/validate.md index d2b53d51..889403b3 100644 --- a/ui-implement/skills/validate.md +++ b/ui-implement/skills/validate.md @@ -211,7 +211,7 @@ satisfied: it requires visual verification or describes a UX quality) — note it as "requires manual verification" -### Step 7b: Test Plan Verification +### Step 8: Test Plan Verification If `.artifacts/ui-implement/{issue-key}/testplan.md` exists, independently verify that every test case has been implemented. This check re-derives @@ -236,7 +236,7 @@ Coverage section, skip this step entirely. - Re-run the relevant checks from Step 3. 4. Record results for the validation report. -### Step 8: Write Validation Report +### Step 9: Write Validation Report Write `.artifacts/ui-implement/{issue-key}/05-validation-report.md`: @@ -325,13 +325,17 @@ Write `.artifacts/ui-implement/{issue-key}/05-validation-report.md`: ## Result -{PASS — all checks pass, coverage is comprehensive, all acceptance - criteria satisfied, no regressions. - OR - FAIL — with explanation of what still needs fixing.} + + +PASS + +{When all checks pass, coverage is comprehensive, all acceptance + criteria satisfied, and no regressions. Otherwise:} + +FAIL — {explanation of what still needs fixing.} ``` -### Step 9: Present Results +### Step 10: Present Results Summarize for the user: - Which checks passed and which failed From 79216f21d335bb825da1114b465a611557c0df46 Mon Sep 17 00:00:00 2001 From: Chai Bot Date: Thu, 1 Oct 2026 20:14:18 +0000 Subject: [PATCH 05/12] ui-implement: revert to lettered substeps in code.md and ingest.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Restore the original lettered-substep convention (3a–3i, Step 3-post, 5a–5d) that matches the implement/ workflow's established pattern. The flat sequential numbering diverged from the upstream convention without justification. Assisted-by: Claude Opus 4.6 --- ui-implement/skills/code.md | 58 +++++++++++++++++++---------------- ui-implement/skills/ingest.md | 41 +++++++++++++------------ 2 files changed, 52 insertions(+), 47 deletions(-) diff --git a/ui-implement/skills/code.md b/ui-implement/skills/code.md index 85b5c550..9621c23d 100644 --- a/ui-implement/skills/code.md +++ b/ui-implement/skills/code.md @@ -136,7 +136,7 @@ git merge origin/{local-base} ``` If conflicts occur during either operation, follow the same conflict -handling as Step 11 (stop, show conflicts, offer to resolve, proceed +handling as Step 3h (stop, show conflicts, offer to resolve, proceed only with user approval). Verify the starting point: @@ -147,8 +147,8 @@ git log --oneline -5 ### Step 3: Execute Tasks -For each task in the plan, follow the cycle in Steps 4–12. **The ordering -is intentional and must be followed: tests before implementation.** Write +For each task in the plan, follow this cycle. **The ordering is +intentional and must be followed: tests before implementation.** Write the unit tests first, verify they fail for the right reason (the production code doesn't exist yet), then write the implementation that makes them pass. Do not write the implementation first and add tests @@ -162,14 +162,14 @@ includes Task 0 for introducing a unit test framework, execute it as specified in the plan (install, configure, smoke test). This task does not follow TDD since it is infrastructure setup, not behavioral code. -### Step 4: Read Affected Files +#### 3a: Read Affected Files Before making any changes, read: - Every file listed in the task's "Files" section - Existing test files in the same directory/module (to match patterns) - Any components, hooks, or types referenced by the task -### Step 5: Write Unit Tests FIRST +#### 3b: Write Unit Tests FIRST Write tests that define the behavioral contracts for this task: @@ -198,9 +198,9 @@ Write tests that define the behavioral contracts for this task: 6. **Name tests after the contract they validate,** not after bugs discovered during development. -### Step 6: Write Implementation (after tests exist) +#### 3c: Write Implementation (after tests exist) -Write the production code that makes the tests from Step 5 pass: +Write the production code that makes the tests from 3b pass: 1. Follow existing component/hook patterns in the project 2. Match naming conventions, file organization, and code style @@ -229,7 +229,7 @@ Write the production code that makes the tests from Step 5 pass: - Documenting callers or consumers - Repeating the same explanation at every usage site -### Step 7: Run Tests +#### 3d: Run Tests Look up the test commands from the **Pre-PR Checks** section of `01-context.md`. Each entry has a purpose label (e.g., "unit test", @@ -243,7 +243,7 @@ Fix any failures before proceeding. If a test failure is ambiguous, use diagnostic failure routing (see below). -### Step 8: Lint and Format +#### 3e: Lint and Format Before committing, run the fast quality checks on the files changed by this task. Look up the lint and format commands from the **Pre-PR Checks** @@ -264,7 +264,7 @@ any remaining issues once all tasks are complete and the code compiles. Do not run the full validation suite here — save expensive checks (full test suite, coverage analysis) for `/validate`. -### Step 9: Code Review +#### 3f: Code Review Stage the task's changes first — the review and commit steps both operate on the staged diff: @@ -289,7 +289,7 @@ If the gate reports FLAG (unfixed CRITICAL or HIGH findings), stop and present the findings to the user before committing. If the gate made code fixes, re-stage the affected files, then re-run -the task-scoped tests (Step 7) and fast quality checks (Step 8) to +the task-scoped tests (Step 3d) and fast quality checks (Step 3e) to verify the fixes. Only proceed to commit once checks pass. Note any dismissed findings in the implementation report (Discoveries section) so there is a paper trail. @@ -305,13 +305,13 @@ does, verify each mapped TC ID before proceeding to commit: inconsistency. Read the full test case entry (the Preconditions, Steps, and Expected Results sections). If any of these sections is missing, stop and report the testplan as malformed. -2. Verify that a test exists (written in Step 5 or a prior task) +2. Verify that a test exists (written in Step 3b or a prior task) whose assertions validate the Expected Results described in the test case. The match is behavioral, not textual — the test must exercise the described scenario and assert the described outcomes. 3. If a TC ID mapped to this task has no corresponding test with - sufficient assertion depth, write the missing test (Step 5), run - it (Step 7), run the fast quality checks (Step 8), stage the new + sufficient assertion depth, write the missing test (Step 3b), run + it (Step 3d), run the fast quality checks (Step 3e), stage the new files (`git add`), re-run the review gate, then re-check. This is a hard gate — the task cannot proceed to commit until every @@ -325,12 +325,16 @@ Coverage section, skip this check. However, if `02-plan.md` has TC mappings but `testplan.md` is missing or malformed, stop and report the inconsistency. -### Step 10: Commit +#### 3g: Commit -The changes are already staged from Step 9. Create the commit using the -format from the **Commit Format** section of `01-context.md`. +The changes are already staged from Step 3f. Create the commit: -The commit message must: +```bash +git commit -m "{issue-key}: {task description}" +``` + +Follow the commit format from the **Commit Format** section of +`01-context.md`. The commit message must: - Use the discovered format - Describe what the code does, not the development journey - Be independently meaningful @@ -338,7 +342,7 @@ The commit message must: If the commit fails (e.g., rejected by pre-commit hooks), diagnose and fix the issue before proceeding to the sync step. -### Step 11: Sync with Base +#### 3h: Sync with Base After committing, rebase onto the latest base branch to keep subsequent tasks building against head-of-line. @@ -367,7 +371,7 @@ git rev-list --count HEAD..origin/{local-base} ``` If the count is 0, no new upstream commits exist — skip the rebase and -test re-run, and proceed directly to Step 12. +test re-run, and proceed directly to Step 3i. If new commits exist, check whether a PR has already been created by looking for `.artifacts/ui-implement/{issue-key}/publish-metadata.json`. @@ -386,7 +390,7 @@ git merge origin/{local-base} If the operation applies cleanly, re-run the task's tests to confirm the committed work still passes against the updated base. If tests -fail, diagnose using the failure routing in Step 14. +fail, diagnose using the failure routing in Step 4. **If there are conflicts:** @@ -398,7 +402,7 @@ fail, diagnose using the failure routing in Step 14. 5. After resolution, run `git rebase --continue` or commit the merge resolution as appropriate, then re-run the task's tests -### Step 12: Update Plan +#### 3i: Update Plan Mark the task as completed in `02-plan.md`: - Change `Pending` to `Done` @@ -407,7 +411,7 @@ Update the status immediately after each task, not in bulk at the end. This is the checkpoint that allows the session to resume correctly if interrupted. -### Step 13: Write Integration/E2E Test Stubs +### Step 3-post: Write Integration/E2E Test Stubs After all plan tasks are complete (all marked `Done`), check whether the plan includes an integration/e2e test stubs task. If it does: @@ -427,12 +431,12 @@ plan includes an integration/e2e test stubs task. If it does: ```bash git add {stub files} -git commit -m "{use commit format from 01-context.md}" +git commit -m "{issue-key}: add integration/e2e test stubs" ``` If the project has no e2e framework, skip this step entirely. -### Step 14: Diagnostic Failure Routing +### Step 4: Diagnostic Failure Routing When tests fail, diagnose **where** the problem is before fixing: @@ -445,7 +449,7 @@ When tests fail, diagnose **where** the problem is before fixing: | **Provider/wrapper missing** | Test fails because a required context provider is not in the test render wrapper | Add the provider to the test setup | | **Environment issue** | Test infrastructure unavailable, missing dependency | Report to user — this is not a code problem | -### Step 15: Deviation Rules +### Step 5: Deviation Rules During implementation, you may encounter unexpected situations: @@ -460,7 +464,7 @@ During implementation, you may encounter unexpected situations: | Implementation is significantly more complex than planned | **Stop and ask the user** — the story may need re-scoping | Required | | Accessibility requirement unclear or conflicting | **Stop and ask the user** — a11y must not be guessed | Required | -### Step 16: Write Reports +### Step 6: Write Reports After all tasks are complete (or if interrupted), write: diff --git a/ui-implement/skills/ingest.md b/ui-implement/skills/ingest.md index fe43dcff..ea373329 100644 --- a/ui-implement/skills/ingest.md +++ b/ui-implement/skills/ingest.md @@ -13,13 +13,13 @@ for `/plan`. - Jira is read-only. Capture, don't implement. Note unknowns explicitly. - Explore relevant areas only. Don't map the entire codebase. Focus on components the story will affect. -- Re-invocation diffs before overwriting. If `01-context.md` already exists, preserve it before exploring. After compiling new context, diff against the previous version and present changes to the user before overwriting (see Steps 2a and 11a). +- Re-invocation diffs before overwriting. If `01-context.md` already exists, preserve it before exploring. After compiling new context, diff against the previous version and present changes to the user before overwriting (see Steps 2a and 8a). - Ingest is an index. `/plan` opens cited files. Paths, section refs, signatures — not dumps. - Never Read the same path twice. Never Grep the same (path, pattern) pair twice. - Do not glob this workflow. Do not load `guidelines.md` or `gh-stack`. - Do not re-read `AGENTS.md` / `CLAUDE.md` if already in session. - Grep locates; Read loads. Never grep `.`. Never grep `-A`/`-B`/`-C`. Never grep `.git/`. -- Do not glob the docs repo root. After Step 6, search only the feature directory. +- Do not glob the docs repo root. After Step 5b, search only the feature directory. - **Write each output path once.** No Delete+rewrite, no second Write to the same file. - Do not call `GetDynamicTools` / list Jira tools. Use the shared fetch-issue script. - **Discover, don't assume.** Never hardcode assumptions about test runners, design systems, i18n libraries, or any UI tooling. All tool choices come from the codebase. @@ -39,15 +39,14 @@ environment variables. ## Jira call (use as-is) -Resolve the shared script to an absolute path at runtime. The path is -relative to this file: +Resolve the shared script to an absolute path so it remains valid +regardless of working directory: -``` -../../_shared/scripts/fetch-issue.py +```bash +FETCH_ISSUE_SCRIPT="${HOME}/.ai-workflows/_shared/scripts/fetch-issue.py" ``` -Before the first Jira call, resolve this to an absolute path and assign -it to `FETCH_ISSUE_SCRIPT`. Use `$FETCH_ISSUE_SCRIPT` in all subsequent +Use `$FETCH_ISSUE_SCRIPT` instead of the relative path in all subsequent commands. - **Story:** `python3 "$FETCH_ISSUE_SCRIPT" get {KEY} --fields summary,description,issuetype,status,labels,fixVersions --parent --parent-fields summary,status,issuetype,parent --links --link-fields summary,status` @@ -115,11 +114,13 @@ If dependencies are unresolved, **warn the user** but do not block. Report: - What risk this presents (merge conflicts, missing APIs, etc.) - A recommendation to proceed with caution or wait -### Step 5: Resolve the Docs Repo +### Step 5: Load Upstream Context The ui-design document, PRD, and related documents are published to a docs repo by the prd, design, and ui-design workflows. Fetch them from there. +#### 5a: Resolve the Docs Repo + Check for an existing docs repo configuration at `.artifacts/config.json`. This config is workspace-level and shared across all workflows — a prior workflow run may have already created it. @@ -133,7 +134,7 @@ If any check fails, tell the user and re-ask. Resolve `~` to an absolute path be If it does not exist, ask for docs repo local path and remote. Resolve `~` to absolute. Write `.artifacts/config.json` with `docs_repo_path` and `docs_repo_remote`. -### Step 6: Find the Feature Directory +#### 5b: Find the Feature Directory The docs repo organizes documents by Feature-level Jira issue. To find the right directory, walk the Jira hierarchy from the story: @@ -164,7 +165,7 @@ ask the user to choose. If the hierarchy traversal fails or no directory is found, ask the user for the path to the relevant documents within the docs repo. -### Step 7: Read Upstream Documents (section-scoped) +#### 5c: Read Upstream Documents (section-scoped) Do **not** Read an entire `ui-design.md`, `design.md`, `prd.md`, or `testplan.md`. Those files are often thousands of lines. Search, then slice. @@ -192,7 +193,7 @@ Need (in priority order): criteria enrichment 5. **API findings** (`api-findings.md`) — **optional.** Resolved endpoints, API gaps, mock strategies -6. **Testplan** (`testplan.md`) — candidate test cases for Step 8 +6. **Testplan** (`testplan.md`) — candidate test cases for Step 5d If `ui-design.md` is not found, **warn the user** — this is the primary design input for UI stories. Ask whether to proceed with only the Jira story @@ -201,7 +202,7 @@ and general design document, or to wait for the ui-design document. If `design.md` or `prd.md` are not found, proceed with available context — the story's acceptance criteria are the primary contract. -### Step 8: Filter Testplan to Story Scope +#### 5d: Filter Testplan to Story Scope Match the story's `Validated by` TC IDs (captured in Step 3) against the testplan's test-case headings. If `Validated by` is missing, empty, or @@ -217,7 +218,7 @@ Design Reference. No feature testplan: note and continue. -### Step 9: Explore the Codebase +### Step 6: Explore the Codebase Based on the story's scope, explore the areas of the codebase that will be affected. @@ -231,7 +232,7 @@ affected. - Stack: `git branch --show-current`, `git log --oneline -8`, `gh stack view --json`. No `.git/` listing. - Topology: parse `{owner}/{repo}` from `git remote get-url origin` (never substitute a well-known upstream name). Then `gh repo view {owner}/{repo} --json isFork,parent`. If `gh` fails, ask the user whether this is a fork and, if so, for upstream `{owner}/{repo}`. -**Validation cache:** If `.artifacts/ui-implement/_validation-profile.md` exists and `.meta.json` hashes/mtimes still match, merge the profile into the in-memory context draft, skip config Reads, and do not Write `01-context.md` until Step 11 or Step 11a. Else one discovery pass: bounded Greps of present `AGENTS.md` and `CONTRIBUTING.md` (unless already in session) for lint/test/coverage commands, one Makefile grep, plus CI filenames via `git ls-files '.github/workflows/*.yml' '.github/workflows/*.yaml'`. For each listed workflow, Grep command-bearing keys (`run:`, `make`, lint/test targets) — not full workflow bodies. Then Write cache files **once**. +**Validation cache:** If `.artifacts/ui-implement/_validation-profile.md` exists and `.meta.json` hashes/mtimes still match, merge the profile into the in-memory context draft, skip config Reads, and do not Write `01-context.md` until Step 8 or Step 8a. Else one discovery pass: bounded Greps of present `AGENTS.md` and `CONTRIBUTING.md` (unless already in session) for lint/test/coverage commands, one Makefile grep, plus CI filenames via `git ls-files '.github/workflows/*.yml' '.github/workflows/*.yaml'`. For each listed workflow, Grep command-bearing keys (`run:`, `make`, lint/test targets) — not full workflow bodies. Then Write cache files **once**. Skip `AGENTS.md` and `CONTRIBUTING.md` Reads if already in session. Path-only for PR template unless the body is required. @@ -311,7 +312,7 @@ Record components as path + signature + test path. `/plan` opens cited files. - **Cite what `/plan` would not guess** (path + one line; extra grep hits stay unread): sibling implementation in another component ("pattern only, do not import"); shared hooks or utilities; neighboring unit test paths if grep found them. List leftover `files_with_matches` hits under **Cited, not opened**. - **Open questions:** Fill or mark `N/A (reason)` for: component props contract; story boundary vs dependency/successor; spec vs AC conflict (record both, do not pick); missing design system component; placement (existing module vs new); permission gate not in current code; loading/error/empty state not specified. Concrete question or N/A. No vague "how should errors work?" -### Step 10: Discover UI Cross-Cutting Concerns +### Step 7: Discover UI Cross-Cutting Concerns Based on the codebase exploration, document the cross-cutting patterns that `/code` must follow. These are discovered, not assumed: @@ -331,7 +332,7 @@ Based on the codebase exploration, document the cross-cutting patterns that 7. **Loading state patterns:** How are loading indicators rendered? Skeletons, spinners, or placeholders? -### Step 11: Compile Context +### Step 8: Compile Context Compile all findings into `01-context.md`. If this is a re-invocation (Step 2a found an existing file), **do not write the file yet** — hold the @@ -342,7 +343,7 @@ fill it tightly (must-record bullets; 5–8 lines per component; signatures only; every open-question slot filled or N/A), Write `01-context.md` **once**. -### Step 11a: Diff Against Prior Ingest (Re-invocation Only) +### Step 8a: Diff Against Prior Ingest (Re-invocation Only) Diff compiled content vs `.prev`. Focus on: - Acceptance criteria @@ -354,7 +355,7 @@ Diff compiled content vs `.prev`. Focus on: If `02-plan.md` or later artifacts exist, list them. Wait for confirmation. If confirmed, Write `01-context.md` **once** and delete `.prev`. If declined, delete `.prev` and stop without overwriting. -### Step 12: Report +### Step 9: Report 8–12 lines. Do not paste `01-context.md`. Point at the file. Include: - Story scope and key ACs @@ -369,7 +370,7 @@ If `02-plan.md` or later artifacts exist, list them. Wait for confirmation. If c - Open questions as `/plan` work, not blockers - Readiness for `/plan` -If the user declined overwrite in 11a, report the diff and that existing context was kept. +If the user declined overwrite in 8a, report the diff and that existing context was kept. ## Output From fa2ba0b0d253f4fdd91db89daf89c85face9d620 Mon Sep 17 00:00:00 2001 From: Chai Bot Date: Thu, 1 Oct 2026 20:17:44 +0000 Subject: [PATCH 06/12] ui-implement: restore skill-relative paths and discovered commit format The revert in 79216f2 restored lettered substeps but accidentally also reverted two other fixes from 7fc81b8: 1. ingest.md: Replace HOME-based path for fetch-issue.py with a skill-relative path using $(dirname "$0") so the script resolves correctly regardless of install location. 2. code.md: Remove hardcoded commit format example and direct the agent to use the discovered format from 01-context.md instead of prescribing a specific pattern. Assisted-by: Claude (claude.ai) --- ui-implement/skills/code.md | 8 ++------ ui-implement/skills/ingest.md | 2 +- 2 files changed, 3 insertions(+), 7 deletions(-) diff --git a/ui-implement/skills/code.md b/ui-implement/skills/code.md index 9621c23d..90fa2c81 100644 --- a/ui-implement/skills/code.md +++ b/ui-implement/skills/code.md @@ -329,13 +329,9 @@ the inconsistency. The changes are already staged from Step 3f. Create the commit: -```bash -git commit -m "{issue-key}: {task description}" -``` - -Follow the commit format from the **Commit Format** section of +Use the commit format from the **Commit Format** section of `01-context.md`. The commit message must: -- Use the discovered format +- Use the discovered format exactly - Describe what the code does, not the development journey - Be independently meaningful diff --git a/ui-implement/skills/ingest.md b/ui-implement/skills/ingest.md index ea373329..2c40df94 100644 --- a/ui-implement/skills/ingest.md +++ b/ui-implement/skills/ingest.md @@ -43,7 +43,7 @@ Resolve the shared script to an absolute path so it remains valid regardless of working directory: ```bash -FETCH_ISSUE_SCRIPT="${HOME}/.ai-workflows/_shared/scripts/fetch-issue.py" +FETCH_ISSUE_SCRIPT="$(cd "$(dirname "$0")/../../_shared/scripts" && pwd)/fetch-issue.py" ``` Use `$FETCH_ISSUE_SCRIPT` instead of the relative path in all subsequent From 064da8e12855a38112dc3fa2ca8f4653bfb48cc4 Mon Sep 17 00:00:00 2001 From: Chai Bot Date: Thu, 1 Oct 2026 20:33:33 +0000 Subject: [PATCH 07/12] ui-implement: fix respond.md list lint and validate.md FAIL template - Indent code blocks under list items 6 and 7 in respond.md so the ordered list is not broken by unindented fenced blocks (fixes MD029) - Put FAIL on its own line in the result template so the first line is a single verdict token, matching the PASS template above it Assisted-by: Claude (Anthropic) --- ui-implement/skills/respond.md | 14 +++++++------- ui-implement/skills/validate.md | 3 ++- 2 files changed, 9 insertions(+), 8 deletions(-) diff --git a/ui-implement/skills/respond.md b/ui-implement/skills/respond.md index 07d40b47..49acc051 100644 --- a/ui-implement/skills/respond.md +++ b/ui-implement/skills/respond.md @@ -137,18 +137,18 @@ For comments requiring code changes: 5. Run lint and format checks on the changed files. Fix any issues. 6. Commit using the project's commit format: -```bash -git add {specific files} -git commit -m "{issue-key}: Address review feedback — {brief description}" -``` + ```bash + git add {specific files} + git commit -m "{issue-key}: Address review feedback — {brief description}" + ``` 7. After all approved code changes are committed and replies posted, confirm with the user before pushing. Present the list of commits to push: -```bash -git push -``` + ```bash + git push + ``` #### Posting replies diff --git a/ui-implement/skills/validate.md b/ui-implement/skills/validate.md index 889403b3..6c1e0fcc 100644 --- a/ui-implement/skills/validate.md +++ b/ui-implement/skills/validate.md @@ -332,7 +332,8 @@ PASS {When all checks pass, coverage is comprehensive, all acceptance criteria satisfied, and no regressions. Otherwise:} -FAIL — {explanation of what still needs fixing.} +FAIL +{explanation of what still needs fixing.} ``` ### Step 10: Present Results From 87714810c5518b52d5248f318d66f216dfe1a9a0 Mon Sep 17 00:00:00 2001 From: Chai Bot Date: Fri, 2 Oct 2026 13:59:00 +0000 Subject: [PATCH 08/12] fix: correct guidelines.md references in dispatch and ingest skills Change `guidelines.md` to `../guidelines.md` in dispatch.md and ingest.md so the paths resolve to ui-implement/guidelines.md instead of the non-existent ui-implement/skills/guidelines.md. Assisted-by: SHIP CHAI --- ui-implement/skills/dispatch.md | 2 +- ui-implement/skills/ingest.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/ui-implement/skills/dispatch.md b/ui-implement/skills/dispatch.md index fedf1803..0f2fce6a 100644 --- a/ui-implement/skills/dispatch.md +++ b/ui-implement/skills/dispatch.md @@ -11,7 +11,7 @@ phases and stop before resolving a filename. Before dispatching, initialize `COMPLETION_CONSUMED=false` and read the project's `AGENTS.md` or `CLAUDE.md` only if neither is already in the session. For -`PHASE=ingest`, do not glob this workflow, load `guidelines.md` or `gh-stack`, or +`PHASE=ingest`, do not glob this workflow, load `../guidelines.md` or `gh-stack`, or call `GetDynamicTools`; these guards apply before loading either a built-in phase or a project override. diff --git a/ui-implement/skills/ingest.md b/ui-implement/skills/ingest.md index 2c40df94..6e4e97ed 100644 --- a/ui-implement/skills/ingest.md +++ b/ui-implement/skills/ingest.md @@ -16,7 +16,7 @@ for `/plan`. - Re-invocation diffs before overwriting. If `01-context.md` already exists, preserve it before exploring. After compiling new context, diff against the previous version and present changes to the user before overwriting (see Steps 2a and 8a). - Ingest is an index. `/plan` opens cited files. Paths, section refs, signatures — not dumps. - Never Read the same path twice. Never Grep the same (path, pattern) pair twice. -- Do not glob this workflow. Do not load `guidelines.md` or `gh-stack`. +- Do not glob this workflow. Do not load `../guidelines.md` or `gh-stack`. - Do not re-read `AGENTS.md` / `CLAUDE.md` if already in session. - Grep locates; Read loads. Never grep `.`. Never grep `-A`/`-B`/`-C`. Never grep `.git/`. - Do not glob the docs repo root. After Step 5b, search only the feature directory. From 77caab5b3ecfcb96e2bdc1f214e0d00e1be0c686 Mon Sep 17 00:00:00 2001 From: Chai Bot Date: Fri, 2 Oct 2026 14:10:44 +0000 Subject: [PATCH 09/12] fix: use 1/1/1 ordered-list markers for MD029 compliance All ordered list items in ui-implement skill files now use `1.` as the marker instead of incrementing numbers, matching the repo's markdownlint MD029 `style: one` configuration. Assisted-by: Claude (claude.ai) --- ui-implement/skills/code.md | 54 +++++++++++++++---------------- ui-implement/skills/controller.md | 18 +++++------ ui-implement/skills/ingest.md | 42 ++++++++++++------------ ui-implement/skills/plan.md | 14 ++++---- ui-implement/skills/publish.md | 4 +-- ui-implement/skills/respond.md | 12 +++---- ui-implement/skills/validate.md | 46 +++++++++++++------------- 7 files changed, 95 insertions(+), 95 deletions(-) diff --git a/ui-implement/skills/code.md b/ui-implement/skills/code.md index 90fa2c81..147e7750 100644 --- a/ui-implement/skills/code.md +++ b/ui-implement/skills/code.md @@ -35,9 +35,9 @@ existing patterns (if any). Read these files: 1. `.artifacts/ui-implement/{issue-key}/02-plan.md` (implementation plan) -2. `.artifacts/ui-implement/{issue-key}/01-context.md` (story context and validation profile) -3. `.artifacts/ui-implement/{issue-key}/testplan.md` (story-scoped testplan, if exists) -4. The project's `AGENTS.md` and/or `CLAUDE.md` (coding conventions) +1. `.artifacts/ui-implement/{issue-key}/01-context.md` (story context and validation profile) +1. `.artifacts/ui-implement/{issue-key}/testplan.md` (story-scoped testplan, if exists) +1. The project's `AGENTS.md` and/or `CLAUDE.md` (coding conventions) If the plan doesn't exist, tell the user that `/plan` should be run first. @@ -177,9 +177,9 @@ Write tests that define the behavioral contracts for this task: or modify? For components: what renders, what responds to user events, what ARIA attributes are present. For hooks: what values are returned, what side effects occur. -2. **Write test cases:** Use the project's discovered test framework and +1. **Write test cases:** Use the project's discovered test framework and conventions (from the validation profile and neighboring tests). -3. **Cover behavioral paths:** For each public component/hook, test every +1. **Cover behavioral paths:** For each public component/hook, test every meaningful input that produces distinct observable behavior. This includes: - **Components:** rendering with different props, user interactions @@ -187,15 +187,15 @@ Write tests that define the behavioral contracts for this task: attributes (roles, aria-labels, keyboard navigation) - **Hooks:** return values for different inputs, state transitions, error handling, cleanup/unmount behavior -4. **Mock only external dependencies.** Mock API calls, router, i18n +1. **Mock only external dependencies.** Mock API calls, router, i18n provider, permission context — whatever the project's patterns use. Do not mock internal component logic or child components (unless the project's test patterns explicitly do so). -5. **Wrap with required providers.** If the project's components need +1. **Wrap with required providers.** If the project's components need context providers (router, i18n, theme, query client), use the project's existing test utilities or create a render wrapper matching existing patterns. -6. **Name tests after the contract they validate,** not after bugs +1. **Name tests after the contract they validate,** not after bugs discovered during development. #### 3c: Write Implementation (after tests exist) @@ -203,18 +203,18 @@ Write tests that define the behavioral contracts for this task: Write the production code that makes the tests from 3b pass: 1. Follow existing component/hook patterns in the project -2. Match naming conventions, file organization, and code style -3. Use the project's discovered design system components — do not +1. Match naming conventions, file organization, and code style +1. Use the project's discovered design system components — do not introduce raw HTML elements or inline styles when a design system equivalent exists -4. Wrap all user-visible strings with the project's discovered i18n +1. Wrap all user-visible strings with the project's discovered i18n mechanism (if one exists) -5. Include appropriate ARIA attributes and keyboard event handlers +1. Include appropriate ARIA attributes and keyboard event handlers for interactive elements -6. Handle loading, error, and empty states as specified in the plan -7. Apply permission gates as specified in the plan -8. Keep changes focused on what the task describes -9. **Comments must earn their place.** Default to writing no comments +1. Handle loading, error, and empty states as specified in the plan +1. Apply permission gates as specified in the plan +1. Keep changes focused on what the task describes +1. **Comments must earn their place.** Default to writing no comments unless the project's lint or style conventions require doc comments on exported symbols. Add a comment only when the *why* is non-obvious. @@ -236,7 +236,7 @@ Look up the test commands from the **Pre-PR Checks** section of "type check"). Match the label to the type of tests you wrote: 1. Run the unit test command for the specific module/file first (fast feedback) -2. If type checking is a separate command, run it to verify TypeScript types +1. If type checking is a separate command, run it to verify TypeScript types Run each test command as a separate invocation — do not chain commands. Fix any failures before proceeding. @@ -305,11 +305,11 @@ does, verify each mapped TC ID before proceeding to commit: inconsistency. Read the full test case entry (the Preconditions, Steps, and Expected Results sections). If any of these sections is missing, stop and report the testplan as malformed. -2. Verify that a test exists (written in Step 3b or a prior task) +1. Verify that a test exists (written in Step 3b or a prior task) whose assertions validate the Expected Results described in the test case. The match is behavioral, not textual — the test must exercise the described scenario and assert the described outcomes. -3. If a TC ID mapped to this task has no corresponding test with +1. If a TC ID mapped to this task has no corresponding test with sufficient assertion depth, write the missing test (Step 3b), run it (Step 3d), run the fast quality checks (Step 3e), stage the new files (`git add`), re-run the review gate, then re-check. @@ -391,11 +391,11 @@ fail, diagnose using the failure routing in Step 4. **If there are conflicts:** 1. Stop and report the conflicting files to the user -2. Show the conflict markers so the user can see what's colliding -3. Offer to resolve the conflicts — describe what you would do -4. Proceed only after the user approves the resolution (or resolves it +1. Show the conflict markers so the user can see what's colliding +1. Offer to resolve the conflicts — describe what you would do +1. Proceed only after the user approves the resolution (or resolves it themselves) -5. After resolution, run `git rebase --continue` or commit the merge +1. After resolution, run `git rebase --continue` or commit the merge resolution as appropriate, then re-run the task's tests #### 3i: Update Plan @@ -415,15 +415,15 @@ plan includes an integration/e2e test stubs task. If it does: 1. Read the project's existing e2e test files (discovered during `/ingest`) to match patterns — file naming, describe block structure, test utilities, selectors -2. Write stub test files with: +1. Write stub test files with: - Describe blocks for each planned scenario - Pending/skipped test cases with descriptive names - Comments noting what each test should verify - Proper imports matching the project's e2e patterns -3. Do **not** write full e2e test implementations — those are for `[QE]` +1. Do **not** write full e2e test implementations — those are for `[QE]` stories. Stubs provide scaffolding only. -4. Run lint on the stub files -5. Commit separately: +1. Run lint on the stub files +1. Commit separately: ```bash git add {stub files} diff --git a/ui-implement/skills/controller.md b/ui-implement/skills/controller.md index af3f6ae9..2923beae 100644 --- a/ui-implement/skills/controller.md +++ b/ui-implement/skills/controller.md @@ -15,25 +15,25 @@ lightweight dispatcher. Fetch the Jira story, load ui-design/PRD/handoff context, explore the relevant codebase, discover the UI toolchain, and build a validation profile. -2. **Plan** (`/plan`) — `plan.md` +1. **Plan** (`/plan`) — `plan.md` Design the implementation approach: task breakdown, component/hook interfaces, test strategy, and risk assessment. -3. **Revise** (`/revise`) — `revise.md` +1. **Revise** (`/revise`) — `revise.md` Incorporate user feedback into the implementation plan. Repeatable. -4. **Code** (`/code`) — `code.md` +1. **Code** (`/code`) — `code.md` Write unit tests and production code via TDD (task by task), then write integration/e2e test stubs after all tasks complete. Commit incrementally. -5. **Validate** (`/validate`) — `validate.md` +1. **Validate** (`/validate`) — `validate.md` Run the full validation suite (tests, lint, type checking, coverage), iterate on gaps. -6. **Publish** (`/publish`) — `publish.md` +1. **Publish** (`/publish`) — `publish.md` Push the feature branch and create a draft PR in the source repo. -7. **Respond** (`/respond`) — `respond.md` +1. **Respond** (`/respond`) — `respond.md` Fetch and address PR reviewer comments. Repeatable. ## Workspace @@ -69,7 +69,7 @@ completion routing for both built-in phases and project overrides. When the user provides a Jira issue key or URL: 1. Set `PHASE=ingest`. -2. Read `dispatch.md` and follow it. +1. Read `dispatch.md` and follow it. If the user invokes a specific command (e.g., `/code`), set `PHASE` to that command's phase, then read `dispatch.md` and follow it. Do not force the user @@ -85,8 +85,8 @@ If a phase cannot complete because of an operational error (for example, a Jira MCP, build, or git error): 1. **Stop immediately.** Do not advance to the next phase. -2. **Report the error** to the user with the specific error message. -3. **Offer options:** retry the failed step, skip the phase (if optional), or escalate. +1. **Report the error** to the user with the specific error message. +1. **Offer options:** retry the failed step, skip the phase (if optional), or escalate. Do not fabricate results when a tool call fails. Do not silently continue past errors. A completed validation report with a failing verdict is a valid diff --git a/ui-implement/skills/ingest.md b/ui-implement/skills/ingest.md index 6e4e97ed..c2d5484c 100644 --- a/ui-implement/skills/ingest.md +++ b/ui-implement/skills/ingest.md @@ -106,7 +106,7 @@ For each dependency identified in Step 3: 1. Check if the dependent story's Jira status indicates completion (Done, Closed, Resolved). Fetch with `fetch-issue.py get` (Blocking deps command from the Jira call section). -2. Check if the dependent story's code has been merged to the main branch: +1. Check if the dependent story's code has been merged to the main branch: `git log main --oneline --grep="{key}" -5`. If dependencies are unresolved, **warn the user** but do not block. Report: @@ -127,8 +127,8 @@ workflow run may have already created it. If it exists, Read it and validate: 1. Path exists on disk -2. Directory is a git repo -3. `git remote get-url origin` matches `docs_repo_remote` +1. Directory is a git repo +1. `git remote get-url origin` matches `docs_repo_remote` If any check fails, tell the user and re-ask. Resolve `~` to an absolute path before saving. @@ -141,7 +141,7 @@ right directory, walk the Jira hierarchy from the story: 1. The story (e.g., `PROJ-1234`) has a parent **Epic** — its key is in the `parent.key` field of the story payload from Step 3 -2. The Epic has a parent **Feature** — its key is in `parent.parent.key` +1. The Epic has a parent **Feature** — its key is in `parent.parent.key` (or `parent.fields.parent.key`) of the story payload, since the Story command fetches `--parent-fields summary,status,issuetype,parent` @@ -172,10 +172,10 @@ Do **not** Read an entire `ui-design.md`, `design.md`, `prd.md`, or 1. Collect search terms from the Jira story: issue key, design section refs, FR/NFR IDs, AC keywords, component names. -2. Grep each document for those terms and for heading lines (`^#`). -3. Read **only** the matching heading ranges (`offset`/`limit`). Prefer +1. Grep each document for those terms and for heading lines (`^#`). +1. Read **only** the matching heading ranges (`offset`/`limit`). Prefer one contiguous range per relevant section. -4. If grep finds nothing useful, Read the first ~80 lines of the document +1. If grep finds nothing useful, Read the first ~80 lines of the document (title, TOC, or overview) and grep again using TOC entries — still do not Read the rest of the file. @@ -185,15 +185,15 @@ Need (in priority order): this story: component architecture tree, hook designs, state management, route structure, data flow mapping, persona decomposition, accessibility plan, testing strategy. -2. **Design document** (`design.md`) — sections that bind this story (API +1. **Design document** (`design.md`) — sections that bind this story (API contracts, data models, flows) -3. **PRD** (`prd.md`) — FR/NFR this story covers -4. **Handoff document** (`handoff.md`) — **optional.** Interaction specs, +1. **PRD** (`prd.md`) — FR/NFR this story covers +1. **Handoff document** (`handoff.md`) — **optional.** Interaction specs, state matrix, component mapping, accessibility requirements, acceptance criteria enrichment -5. **API findings** (`api-findings.md`) — **optional.** Resolved endpoints, +1. **API findings** (`api-findings.md`) — **optional.** Resolved endpoints, API gaps, mock strategies -6. **Testplan** (`testplan.md`) — candidate test cases for Step 5d +1. **Testplan** (`testplan.md`) — candidate test cases for Step 5d If `ui-design.md` is not found, **warn the user** — this is the primary design input for UI stories. Ask whether to proceed with only the Jira story @@ -265,13 +265,13 @@ Focus on: path is enough; Read only if the template body is needed for the profile -2. **Affected components:** +1. **Affected components:** - Which components, hooks, pages, or modules will this story touch? - Grep for component/hook names; Read signatures (`offset`/`limit`), not full files - Note existing test file paths from glob/grep; Read a test file only to capture the test pattern, not the whole suite -3. **UI toolchain discovery** (record all findings in `01-context.md`): +1. **UI toolchain discovery** (record all findings in `01-context.md`): - **Test framework:** grep `package.json` for test runner (vitest, jest, mocha, etc.), testing library (@testing-library/react, enzyme, etc.), and test scripts. Record the framework, assertion library, and run command. @@ -295,7 +295,7 @@ Focus on: and rationale in `01-context.md` under Test Infrastructure. This becomes "Task 0" material for `/plan`. -4. **Relevant data models and APIs:** +1. **Relevant data models and APIs:** - What TypeScript types/interfaces will be extended or consumed? - What API hooks or fetch patterns exist? - What API specifications exist (OpenAPI, GraphQL schema)? @@ -319,17 +319,17 @@ Based on the codebase exploration, document the cross-cutting patterns that 1. **Design system usage patterns:** How are design system components imported and composed? Are there project-specific wrappers? -2. **i18n patterns:** How are translation keys structured? Where do translation +1. **i18n patterns:** How are translation keys structured? Where do translation files live? Is there a key naming convention? -3. **Accessibility patterns:** Does the project use specific a11y testing +1. **Accessibility patterns:** Does the project use specific a11y testing utilities? Are there ARIA patterns enforced by lint rules? -4. **Permission patterns:** How are feature gates and RBAC checks applied to +1. **Permission patterns:** How are feature gates and RBAC checks applied to UI elements? -5. **State management patterns:** How do components fetch and cache server +1. **State management patterns:** How do components fetch and cache server data? How is client state managed? -6. **Error handling patterns:** How are API errors displayed? Is there a +1. **Error handling patterns:** How are API errors displayed? Is there a shared error boundary or toast system? -7. **Loading state patterns:** How are loading indicators rendered? Skeletons, +1. **Loading state patterns:** How are loading indicators rendered? Skeletons, spinners, or placeholders? ### Step 8: Compile Context diff --git a/ui-implement/skills/plan.md b/ui-implement/skills/plan.md index bfb7d9c6..a94a56e8 100644 --- a/ui-implement/skills/plan.md +++ b/ui-implement/skills/plan.md @@ -33,8 +33,8 @@ review checkpoint before any code is written. Read these files in order: 1. `.artifacts/ui-implement/{issue-key}/01-context.md` (story context) -2. `.artifacts/ui-implement/{issue-key}/testplan.md` (story-scoped testplan, if exists) -3. The project's `AGENTS.md` and/or `CLAUDE.md` (coding conventions) +1. `.artifacts/ui-implement/{issue-key}/testplan.md` (story-scoped testplan, if exists) +1. The project's `AGENTS.md` and/or `CLAUDE.md` (coding conventions) If `01-context.md` doesn't exist, tell the user that `/ingest` should be run first. @@ -42,14 +42,14 @@ run first. Then open **citations only** from `01-context.md` (ingest is an index; this is where the files are read): 1. Each `[UI Design: §…]`, `[Design: §…]`, `[Handoff: §…]`, `[API: §…]` (or equivalent) → that path + heading range. Do not Read the rest of the document. -2. Cited source/test paths (Affected Components + Cited, not opened) as needed to name types. Signature `offset`/`limit` slices, not whole files. -3. Cap **≤12** cited source Reads total (bootstrap reads of `01-context.md`, `testplan.md`, and `AGENTS.md`/`CLAUDE.md` do not count). Skip a citation if it is not needed to lock a task or interface. -4. Do not glob, repo-wide grep, Jira, or unrelated sibling artifacts. Read the required `testplan.md` when it exists. Do not re-run ingest exploration. -5. Classify each ingest open question (ingest is an index, not a spec). Do **not** treat ingest text as a complete contract: +1. Cited source/test paths (Affected Components + Cited, not opened) as needed to name types. Signature `offset`/`limit` slices, not whole files. +1. Cap **≤12** cited source Reads total (bootstrap reads of `01-context.md`, `testplan.md`, and `AGENTS.md`/`CLAUDE.md` do not count). Skip a citation if it is not needed to lock a task or interface. +1. Do not glob, repo-wide grep, Jira, or unrelated sibling artifacts. Read the required `testplan.md` when it exists. Do not re-run ingest exploration. +1. Classify each ingest open question (ingest is an index, not a spec). Do **not** treat ingest text as a complete contract: - **Already specified:** citations (or an unambiguous AC) define the component, hook, or behavior → **Locked decision**. - **Implementer default:** unspecified but `/code` needs a choice (component name, prop name, default state value, error message text). Lock a default that matches cited neighboring code; note it is a default `/revise` may change. Do not leave it open. - **Product fork:** spec vs AC, or two product-legal behaviors. Keep under **Open Questions**. Follow AC in the tasks until the user picks. Do not silently lock the design side. -6. Do not paste opened file bodies into `02-plan.md` (signatures and decisions only). +1. Do not paste opened file bodies into `02-plan.md` (signatures and decisions only). ### Step 1a: Evaluate Test Infrastructure diff --git a/ui-implement/skills/publish.md b/ui-implement/skills/publish.md index b44bbca5..08528729 100644 --- a/ui-implement/skills/publish.md +++ b/ui-implement/skills/publish.md @@ -58,7 +58,7 @@ Verify readiness: the `## Result` section is missing, or it contains `FAIL`, tell the user that `/validate` should be run (or re-run) first. -2. Verify the feature branch exists and has commits: +1. Verify the feature branch exists and has commits: ```bash git branch --show-current @@ -72,7 +72,7 @@ Verify readiness: If there are no commits ahead of the Local Base, there's nothing to publish. -3. Run the shared pre-flight checks: +1. Run the shared pre-flight checks: ```bash python3 "$PUBLISH_SCRIPT" preflight --platform github diff --git a/ui-implement/skills/respond.md b/ui-implement/skills/respond.md index 49acc051..cec8df1f 100644 --- a/ui-implement/skills/respond.md +++ b/ui-implement/skills/respond.md @@ -129,20 +129,20 @@ Wait for the user to approve, modify, or reject each response. For comments requiring code changes: 1. Read the affected file(s) -2. Apply the change -3. If the change affects behavior, update or add tests. Tests must +1. Apply the change +1. If the change affects behavior, update or add tests. Tests must validate behavioral contracts through public interfaces — the same standard as `/code`. Match existing test patterns. -4. Run the affected tests to verify -5. Run lint and format checks on the changed files. Fix any issues. -6. Commit using the project's commit format: +1. Run the affected tests to verify +1. Run lint and format checks on the changed files. Fix any issues. +1. Commit using the project's commit format: ```bash git add {specific files} git commit -m "{issue-key}: Address review feedback — {brief description}" ``` -7. After all approved code changes are committed and replies posted, +1. After all approved code changes are committed and replies posted, confirm with the user before pushing. Present the list of commits to push: diff --git a/ui-implement/skills/validate.md b/ui-implement/skills/validate.md index 6c1e0fcc..683fe3ba 100644 --- a/ui-implement/skills/validate.md +++ b/ui-implement/skills/validate.md @@ -31,9 +31,9 @@ and repeat until everything passes. Read: 1. `.artifacts/ui-implement/{issue-key}/01-context.md` (validation profile) -2. `.artifacts/ui-implement/{issue-key}/02-plan.md` (what was implemented) -3. `.artifacts/ui-implement/{issue-key}/04-impl-report.md` (implementation status) -4. `.artifacts/ui-implement/{issue-key}/testplan.md` (story-scoped testplan, if exists) +1. `.artifacts/ui-implement/{issue-key}/02-plan.md` (what was implemented) +1. `.artifacts/ui-implement/{issue-key}/04-impl-report.md` (implementation status) +1. `.artifacts/ui-implement/{issue-key}/testplan.md` (story-scoped testplan, if exists) Extract the validation profile's pre-PR checks list. @@ -89,8 +89,8 @@ either operation, continue but note the staleness in the validation report. Execute each check from the validation profile in order. For each check: 1. **Run the command** -2. **Capture the output** -3. **Assess the result:** pass, fail, or warning +1. **Capture the output** +1. **Assess the result:** pass, fail, or warning Typical checks (discovered, not hardcoded): - Type checking (e.g., TypeScript compilation) @@ -102,19 +102,19 @@ Typical checks (discovered, not hardcoded): **If a check fails:** 1. Diagnose the failure — is it caused by the story's changes or pre-existing? -2. If caused by the story's changes: fix it, commit the fix, re-run the check -3. If pre-existing: note it in the validation report, do not fix it -4. If unclear: report to the user +1. If caused by the story's changes: fix it, commit the fix, re-run the check +1. If pre-existing: note it in the validation report, do not fix it +1. If unclear: report to the user ### Step 4: Analyze Coverage Run coverage analysis on the packages affected by the story: 1. Use the coverage command from the validation profile -2. Focus on the **new and modified code** specifically — compare the +1. Focus on the **new and modified code** specifically — compare the coverage report's per-function or per-line breakdown against the story's diff to isolate new-code coverage from pre-existing code -3. For each public component/hook added or modified: +1. For each public component/hook added or modified: - Are all rendering paths exercised by tests? - Are user interaction paths tested? - Are error, loading, and empty states tested? @@ -123,10 +123,10 @@ Run coverage analysis on the packages affected by the story: If coverage analysis reveals untested behavioral paths in new code: 1. Write additional tests for the missing behaviors -2. Follow the same contract-based testing standards -3. Run the tests to verify they pass -4. Commit following the project's commit format -5. Re-run coverage to confirm improvement +1. Follow the same contract-based testing standards +1. Run the tests to verify they pass +1. Commit following the project's commit format +1. Re-run coverage to confirm improvement Read the **Minimum new-code coverage** percentage from the Coverage Tooling section of `01-context.md` (discovered during `/ingest`, @@ -148,8 +148,8 @@ the component is too coarse-grained. Escalate to the user: Verify that the story's changes haven't broken existing functionality: 1. Run the full unit test suite (not just affected packages) -2. Run the full build (if applicable) -3. Check for any test failures unrelated to the story +1. Run the full build (if applicable) +1. Check for any test failures unrelated to the story If regressions are found: - Diagnose whether the story's changes caused them @@ -189,8 +189,8 @@ After automated checks and code quality review, verify that every acceptance criterion from the story has been satisfied. 1. Read the **Acceptance Criteria** from `01-context.md` -2. Read the **Acceptance Criteria Coverage** matrix from `02-plan.md` -3. For each acceptance criterion: +1. Read the **Acceptance Criteria Coverage** matrix from `02-plan.md` +1. For each acceptance criterion: - **Trace to implementation:** Is there code that implements this criterion? Follow the task mapping — check that the task is marked Done and that the corresponding code exists. @@ -205,9 +205,9 @@ satisfied: 1. If it's a gap in implementation or tests — fix it, commit the fix, and re-run the relevant checks -2. If it's ambiguous whether the criterion is met — flag it to the +1. If it's ambiguous whether the criterion is met — flag it to the user with your assessment -3. If the criterion cannot be verified through automated means (e.g., +1. If the criterion cannot be verified through automated means (e.g., it requires visual verification or describes a UX quality) — note it as "requires manual verification" @@ -224,17 +224,17 @@ Coverage section, skip this step entirely. 1. Read `testplan.md` and extract all TC IDs. Verify that Preconditions, Steps, and Expected Results sections are present for each entry. -2. For each TC ID (except those legitimately N/A based on the plan's +1. For each TC ID (except those legitimately N/A based on the plan's rationale): - Search the test files on the feature branch for a test whose scenario matches the TC's Steps and whose assertions match the Expected Results. - Record the test file and test name for each TC ID. -3. If any TC ID lacks a corresponding test: +1. If any TC ID lacks a corresponding test: - Write the missing test following contract-based testing standards. - Commit the test following the project's commit format. - Re-run the relevant checks from Step 3. -4. Record results for the validation report. +1. Record results for the validation report. ### Step 9: Write Validation Report From cfa025ded1dbfd324f83f9c8eaa5a3300e8d2640 Mon Sep 17 00:00:00 2001 From: Chai Bot Date: Fri, 2 Oct 2026 14:14:17 +0000 Subject: [PATCH 10/12] fix: normalize remaining ordered-list markers to 1. (MD029) The prior MD029 fix (77caab5) addressed skill files but missed SKILL.md, a nested list in plan.md, and the story-testplan template. Assisted-by: Claude Opus 4.6 (claude.ai) --- ui-implement/SKILL.md | 2 +- ui-implement/skills/plan.md | 8 ++++---- ui-implement/templates/story-testplan.md | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/ui-implement/SKILL.md b/ui-implement/SKILL.md index ab7260ff..da2abbe3 100644 --- a/ui-implement/SKILL.md +++ b/ui-implement/SKILL.md @@ -16,7 +16,7 @@ description: >- 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: +1. 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 diff --git a/ui-implement/skills/plan.md b/ui-implement/skills/plan.md index a94a56e8..7bf947a0 100644 --- a/ui-implement/skills/plan.md +++ b/ui-implement/skills/plan.md @@ -61,10 +61,10 @@ Check the **Test Infrastructure** section of `01-context.md`: recommendation. Include a **Task 0: Introduce unit testing framework** in the plan that: 1. Installs the recommended test framework and testing library - 2. Adds test scripts to `package.json` - 3. Creates a minimal test configuration file - 4. Writes one smoke test for an existing simple component to verify the setup - 5. Runs the test to confirm the framework works + 1. Adds test scripts to `package.json` + 1. Creates a minimal test configuration file + 1. Writes one smoke test for an existing simple component to verify the setup + 1. Runs the test to confirm the framework works Plan all story tasks normally alongside Task 0 — use the recommended framework for the test strategy. Present the framework recommendation diff --git a/ui-implement/templates/story-testplan.md b/ui-implement/templates/story-testplan.md index 2cf55f0e..3d7e1ce4 100644 --- a/ui-implement/templates/story-testplan.md +++ b/ui-implement/templates/story-testplan.md @@ -19,7 +19,7 @@ One `## {tc-id}` section per filtered story test case: ### Steps 1. {step} -2. {step} +1. {step} ### Expected Results From a7cdb73cd9c5abc282d020a5400e3087bac8f2aa Mon Sep 17 00:00:00 2001 From: Chai Bot Date: Fri, 2 Oct 2026 14:15:37 +0000 Subject: [PATCH 11/12] Revert "fix: normalize remaining ordered-list markers to 1. (MD029)" This reverts commit cfa025ded1dbfd324f83f9c8eaa5a3300e8d2640. --- ui-implement/SKILL.md | 2 +- ui-implement/skills/plan.md | 8 ++++---- ui-implement/templates/story-testplan.md | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/ui-implement/SKILL.md b/ui-implement/SKILL.md index da2abbe3..ab7260ff 100644 --- a/ui-implement/SKILL.md +++ b/ui-implement/SKILL.md @@ -16,7 +16,7 @@ description: >- 1. If the user invoked a specific command (e.g., `/plan`, `/code`), read the matching file in commands/ and follow it. -1. Otherwise, read `skills/controller.md` to load the workflow controller: +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 diff --git a/ui-implement/skills/plan.md b/ui-implement/skills/plan.md index 7bf947a0..a94a56e8 100644 --- a/ui-implement/skills/plan.md +++ b/ui-implement/skills/plan.md @@ -61,10 +61,10 @@ Check the **Test Infrastructure** section of `01-context.md`: recommendation. Include a **Task 0: Introduce unit testing framework** in the plan that: 1. Installs the recommended test framework and testing library - 1. Adds test scripts to `package.json` - 1. Creates a minimal test configuration file - 1. Writes one smoke test for an existing simple component to verify the setup - 1. Runs the test to confirm the framework works + 2. Adds test scripts to `package.json` + 3. Creates a minimal test configuration file + 4. Writes one smoke test for an existing simple component to verify the setup + 5. Runs the test to confirm the framework works Plan all story tasks normally alongside Task 0 — use the recommended framework for the test strategy. Present the framework recommendation diff --git a/ui-implement/templates/story-testplan.md b/ui-implement/templates/story-testplan.md index 3d7e1ce4..2cf55f0e 100644 --- a/ui-implement/templates/story-testplan.md +++ b/ui-implement/templates/story-testplan.md @@ -19,7 +19,7 @@ One `## {tc-id}` section per filtered story test case: ### Steps 1. {step} -1. {step} +2. {step} ### Expected Results From eb938d1a79e473112504ca46f06be2ed59d1ad38 Mon Sep 17 00:00:00 2001 From: Chai Bot Date: Fri, 2 Oct 2026 14:16:54 +0000 Subject: [PATCH 12/12] Revert "fix: use 1/1/1 ordered-list markers for MD029 compliance" This reverts commit 77caab5b3ecfcb96e2bdc1f214e0d00e1be0c686. --- ui-implement/skills/code.md | 54 +++++++++++++++---------------- ui-implement/skills/controller.md | 18 +++++------ ui-implement/skills/ingest.md | 42 ++++++++++++------------ ui-implement/skills/plan.md | 14 ++++---- ui-implement/skills/publish.md | 4 +-- ui-implement/skills/respond.md | 12 +++---- ui-implement/skills/validate.md | 46 +++++++++++++------------- 7 files changed, 95 insertions(+), 95 deletions(-) diff --git a/ui-implement/skills/code.md b/ui-implement/skills/code.md index 147e7750..90fa2c81 100644 --- a/ui-implement/skills/code.md +++ b/ui-implement/skills/code.md @@ -35,9 +35,9 @@ existing patterns (if any). Read these files: 1. `.artifacts/ui-implement/{issue-key}/02-plan.md` (implementation plan) -1. `.artifacts/ui-implement/{issue-key}/01-context.md` (story context and validation profile) -1. `.artifacts/ui-implement/{issue-key}/testplan.md` (story-scoped testplan, if exists) -1. The project's `AGENTS.md` and/or `CLAUDE.md` (coding conventions) +2. `.artifacts/ui-implement/{issue-key}/01-context.md` (story context and validation profile) +3. `.artifacts/ui-implement/{issue-key}/testplan.md` (story-scoped testplan, if exists) +4. The project's `AGENTS.md` and/or `CLAUDE.md` (coding conventions) If the plan doesn't exist, tell the user that `/plan` should be run first. @@ -177,9 +177,9 @@ Write tests that define the behavioral contracts for this task: or modify? For components: what renders, what responds to user events, what ARIA attributes are present. For hooks: what values are returned, what side effects occur. -1. **Write test cases:** Use the project's discovered test framework and +2. **Write test cases:** Use the project's discovered test framework and conventions (from the validation profile and neighboring tests). -1. **Cover behavioral paths:** For each public component/hook, test every +3. **Cover behavioral paths:** For each public component/hook, test every meaningful input that produces distinct observable behavior. This includes: - **Components:** rendering with different props, user interactions @@ -187,15 +187,15 @@ Write tests that define the behavioral contracts for this task: attributes (roles, aria-labels, keyboard navigation) - **Hooks:** return values for different inputs, state transitions, error handling, cleanup/unmount behavior -1. **Mock only external dependencies.** Mock API calls, router, i18n +4. **Mock only external dependencies.** Mock API calls, router, i18n provider, permission context — whatever the project's patterns use. Do not mock internal component logic or child components (unless the project's test patterns explicitly do so). -1. **Wrap with required providers.** If the project's components need +5. **Wrap with required providers.** If the project's components need context providers (router, i18n, theme, query client), use the project's existing test utilities or create a render wrapper matching existing patterns. -1. **Name tests after the contract they validate,** not after bugs +6. **Name tests after the contract they validate,** not after bugs discovered during development. #### 3c: Write Implementation (after tests exist) @@ -203,18 +203,18 @@ Write tests that define the behavioral contracts for this task: Write the production code that makes the tests from 3b pass: 1. Follow existing component/hook patterns in the project -1. Match naming conventions, file organization, and code style -1. Use the project's discovered design system components — do not +2. Match naming conventions, file organization, and code style +3. Use the project's discovered design system components — do not introduce raw HTML elements or inline styles when a design system equivalent exists -1. Wrap all user-visible strings with the project's discovered i18n +4. Wrap all user-visible strings with the project's discovered i18n mechanism (if one exists) -1. Include appropriate ARIA attributes and keyboard event handlers +5. Include appropriate ARIA attributes and keyboard event handlers for interactive elements -1. Handle loading, error, and empty states as specified in the plan -1. Apply permission gates as specified in the plan -1. Keep changes focused on what the task describes -1. **Comments must earn their place.** Default to writing no comments +6. Handle loading, error, and empty states as specified in the plan +7. Apply permission gates as specified in the plan +8. Keep changes focused on what the task describes +9. **Comments must earn their place.** Default to writing no comments unless the project's lint or style conventions require doc comments on exported symbols. Add a comment only when the *why* is non-obvious. @@ -236,7 +236,7 @@ Look up the test commands from the **Pre-PR Checks** section of "type check"). Match the label to the type of tests you wrote: 1. Run the unit test command for the specific module/file first (fast feedback) -1. If type checking is a separate command, run it to verify TypeScript types +2. If type checking is a separate command, run it to verify TypeScript types Run each test command as a separate invocation — do not chain commands. Fix any failures before proceeding. @@ -305,11 +305,11 @@ does, verify each mapped TC ID before proceeding to commit: inconsistency. Read the full test case entry (the Preconditions, Steps, and Expected Results sections). If any of these sections is missing, stop and report the testplan as malformed. -1. Verify that a test exists (written in Step 3b or a prior task) +2. Verify that a test exists (written in Step 3b or a prior task) whose assertions validate the Expected Results described in the test case. The match is behavioral, not textual — the test must exercise the described scenario and assert the described outcomes. -1. If a TC ID mapped to this task has no corresponding test with +3. If a TC ID mapped to this task has no corresponding test with sufficient assertion depth, write the missing test (Step 3b), run it (Step 3d), run the fast quality checks (Step 3e), stage the new files (`git add`), re-run the review gate, then re-check. @@ -391,11 +391,11 @@ fail, diagnose using the failure routing in Step 4. **If there are conflicts:** 1. Stop and report the conflicting files to the user -1. Show the conflict markers so the user can see what's colliding -1. Offer to resolve the conflicts — describe what you would do -1. Proceed only after the user approves the resolution (or resolves it +2. Show the conflict markers so the user can see what's colliding +3. Offer to resolve the conflicts — describe what you would do +4. Proceed only after the user approves the resolution (or resolves it themselves) -1. After resolution, run `git rebase --continue` or commit the merge +5. After resolution, run `git rebase --continue` or commit the merge resolution as appropriate, then re-run the task's tests #### 3i: Update Plan @@ -415,15 +415,15 @@ plan includes an integration/e2e test stubs task. If it does: 1. Read the project's existing e2e test files (discovered during `/ingest`) to match patterns — file naming, describe block structure, test utilities, selectors -1. Write stub test files with: +2. Write stub test files with: - Describe blocks for each planned scenario - Pending/skipped test cases with descriptive names - Comments noting what each test should verify - Proper imports matching the project's e2e patterns -1. Do **not** write full e2e test implementations — those are for `[QE]` +3. Do **not** write full e2e test implementations — those are for `[QE]` stories. Stubs provide scaffolding only. -1. Run lint on the stub files -1. Commit separately: +4. Run lint on the stub files +5. Commit separately: ```bash git add {stub files} diff --git a/ui-implement/skills/controller.md b/ui-implement/skills/controller.md index 2923beae..af3f6ae9 100644 --- a/ui-implement/skills/controller.md +++ b/ui-implement/skills/controller.md @@ -15,25 +15,25 @@ lightweight dispatcher. Fetch the Jira story, load ui-design/PRD/handoff context, explore the relevant codebase, discover the UI toolchain, and build a validation profile. -1. **Plan** (`/plan`) — `plan.md` +2. **Plan** (`/plan`) — `plan.md` Design the implementation approach: task breakdown, component/hook interfaces, test strategy, and risk assessment. -1. **Revise** (`/revise`) — `revise.md` +3. **Revise** (`/revise`) — `revise.md` Incorporate user feedback into the implementation plan. Repeatable. -1. **Code** (`/code`) — `code.md` +4. **Code** (`/code`) — `code.md` Write unit tests and production code via TDD (task by task), then write integration/e2e test stubs after all tasks complete. Commit incrementally. -1. **Validate** (`/validate`) — `validate.md` +5. **Validate** (`/validate`) — `validate.md` Run the full validation suite (tests, lint, type checking, coverage), iterate on gaps. -1. **Publish** (`/publish`) — `publish.md` +6. **Publish** (`/publish`) — `publish.md` Push the feature branch and create a draft PR in the source repo. -1. **Respond** (`/respond`) — `respond.md` +7. **Respond** (`/respond`) — `respond.md` Fetch and address PR reviewer comments. Repeatable. ## Workspace @@ -69,7 +69,7 @@ completion routing for both built-in phases and project overrides. When the user provides a Jira issue key or URL: 1. Set `PHASE=ingest`. -1. Read `dispatch.md` and follow it. +2. Read `dispatch.md` and follow it. If the user invokes a specific command (e.g., `/code`), set `PHASE` to that command's phase, then read `dispatch.md` and follow it. Do not force the user @@ -85,8 +85,8 @@ If a phase cannot complete because of an operational error (for example, a Jira MCP, build, or git error): 1. **Stop immediately.** Do not advance to the next phase. -1. **Report the error** to the user with the specific error message. -1. **Offer options:** retry the failed step, skip the phase (if optional), or escalate. +2. **Report the error** to the user with the specific error message. +3. **Offer options:** retry the failed step, skip the phase (if optional), or escalate. Do not fabricate results when a tool call fails. Do not silently continue past errors. A completed validation report with a failing verdict is a valid diff --git a/ui-implement/skills/ingest.md b/ui-implement/skills/ingest.md index c2d5484c..6e4e97ed 100644 --- a/ui-implement/skills/ingest.md +++ b/ui-implement/skills/ingest.md @@ -106,7 +106,7 @@ For each dependency identified in Step 3: 1. Check if the dependent story's Jira status indicates completion (Done, Closed, Resolved). Fetch with `fetch-issue.py get` (Blocking deps command from the Jira call section). -1. Check if the dependent story's code has been merged to the main branch: +2. Check if the dependent story's code has been merged to the main branch: `git log main --oneline --grep="{key}" -5`. If dependencies are unresolved, **warn the user** but do not block. Report: @@ -127,8 +127,8 @@ workflow run may have already created it. If it exists, Read it and validate: 1. Path exists on disk -1. Directory is a git repo -1. `git remote get-url origin` matches `docs_repo_remote` +2. Directory is a git repo +3. `git remote get-url origin` matches `docs_repo_remote` If any check fails, tell the user and re-ask. Resolve `~` to an absolute path before saving. @@ -141,7 +141,7 @@ right directory, walk the Jira hierarchy from the story: 1. The story (e.g., `PROJ-1234`) has a parent **Epic** — its key is in the `parent.key` field of the story payload from Step 3 -1. The Epic has a parent **Feature** — its key is in `parent.parent.key` +2. The Epic has a parent **Feature** — its key is in `parent.parent.key` (or `parent.fields.parent.key`) of the story payload, since the Story command fetches `--parent-fields summary,status,issuetype,parent` @@ -172,10 +172,10 @@ Do **not** Read an entire `ui-design.md`, `design.md`, `prd.md`, or 1. Collect search terms from the Jira story: issue key, design section refs, FR/NFR IDs, AC keywords, component names. -1. Grep each document for those terms and for heading lines (`^#`). -1. Read **only** the matching heading ranges (`offset`/`limit`). Prefer +2. Grep each document for those terms and for heading lines (`^#`). +3. Read **only** the matching heading ranges (`offset`/`limit`). Prefer one contiguous range per relevant section. -1. If grep finds nothing useful, Read the first ~80 lines of the document +4. If grep finds nothing useful, Read the first ~80 lines of the document (title, TOC, or overview) and grep again using TOC entries — still do not Read the rest of the file. @@ -185,15 +185,15 @@ Need (in priority order): this story: component architecture tree, hook designs, state management, route structure, data flow mapping, persona decomposition, accessibility plan, testing strategy. -1. **Design document** (`design.md`) — sections that bind this story (API +2. **Design document** (`design.md`) — sections that bind this story (API contracts, data models, flows) -1. **PRD** (`prd.md`) — FR/NFR this story covers -1. **Handoff document** (`handoff.md`) — **optional.** Interaction specs, +3. **PRD** (`prd.md`) — FR/NFR this story covers +4. **Handoff document** (`handoff.md`) — **optional.** Interaction specs, state matrix, component mapping, accessibility requirements, acceptance criteria enrichment -1. **API findings** (`api-findings.md`) — **optional.** Resolved endpoints, +5. **API findings** (`api-findings.md`) — **optional.** Resolved endpoints, API gaps, mock strategies -1. **Testplan** (`testplan.md`) — candidate test cases for Step 5d +6. **Testplan** (`testplan.md`) — candidate test cases for Step 5d If `ui-design.md` is not found, **warn the user** — this is the primary design input for UI stories. Ask whether to proceed with only the Jira story @@ -265,13 +265,13 @@ Focus on: path is enough; Read only if the template body is needed for the profile -1. **Affected components:** +2. **Affected components:** - Which components, hooks, pages, or modules will this story touch? - Grep for component/hook names; Read signatures (`offset`/`limit`), not full files - Note existing test file paths from glob/grep; Read a test file only to capture the test pattern, not the whole suite -1. **UI toolchain discovery** (record all findings in `01-context.md`): +3. **UI toolchain discovery** (record all findings in `01-context.md`): - **Test framework:** grep `package.json` for test runner (vitest, jest, mocha, etc.), testing library (@testing-library/react, enzyme, etc.), and test scripts. Record the framework, assertion library, and run command. @@ -295,7 +295,7 @@ Focus on: and rationale in `01-context.md` under Test Infrastructure. This becomes "Task 0" material for `/plan`. -1. **Relevant data models and APIs:** +4. **Relevant data models and APIs:** - What TypeScript types/interfaces will be extended or consumed? - What API hooks or fetch patterns exist? - What API specifications exist (OpenAPI, GraphQL schema)? @@ -319,17 +319,17 @@ Based on the codebase exploration, document the cross-cutting patterns that 1. **Design system usage patterns:** How are design system components imported and composed? Are there project-specific wrappers? -1. **i18n patterns:** How are translation keys structured? Where do translation +2. **i18n patterns:** How are translation keys structured? Where do translation files live? Is there a key naming convention? -1. **Accessibility patterns:** Does the project use specific a11y testing +3. **Accessibility patterns:** Does the project use specific a11y testing utilities? Are there ARIA patterns enforced by lint rules? -1. **Permission patterns:** How are feature gates and RBAC checks applied to +4. **Permission patterns:** How are feature gates and RBAC checks applied to UI elements? -1. **State management patterns:** How do components fetch and cache server +5. **State management patterns:** How do components fetch and cache server data? How is client state managed? -1. **Error handling patterns:** How are API errors displayed? Is there a +6. **Error handling patterns:** How are API errors displayed? Is there a shared error boundary or toast system? -1. **Loading state patterns:** How are loading indicators rendered? Skeletons, +7. **Loading state patterns:** How are loading indicators rendered? Skeletons, spinners, or placeholders? ### Step 8: Compile Context diff --git a/ui-implement/skills/plan.md b/ui-implement/skills/plan.md index a94a56e8..bfb7d9c6 100644 --- a/ui-implement/skills/plan.md +++ b/ui-implement/skills/plan.md @@ -33,8 +33,8 @@ review checkpoint before any code is written. Read these files in order: 1. `.artifacts/ui-implement/{issue-key}/01-context.md` (story context) -1. `.artifacts/ui-implement/{issue-key}/testplan.md` (story-scoped testplan, if exists) -1. The project's `AGENTS.md` and/or `CLAUDE.md` (coding conventions) +2. `.artifacts/ui-implement/{issue-key}/testplan.md` (story-scoped testplan, if exists) +3. The project's `AGENTS.md` and/or `CLAUDE.md` (coding conventions) If `01-context.md` doesn't exist, tell the user that `/ingest` should be run first. @@ -42,14 +42,14 @@ run first. Then open **citations only** from `01-context.md` (ingest is an index; this is where the files are read): 1. Each `[UI Design: §…]`, `[Design: §…]`, `[Handoff: §…]`, `[API: §…]` (or equivalent) → that path + heading range. Do not Read the rest of the document. -1. Cited source/test paths (Affected Components + Cited, not opened) as needed to name types. Signature `offset`/`limit` slices, not whole files. -1. Cap **≤12** cited source Reads total (bootstrap reads of `01-context.md`, `testplan.md`, and `AGENTS.md`/`CLAUDE.md` do not count). Skip a citation if it is not needed to lock a task or interface. -1. Do not glob, repo-wide grep, Jira, or unrelated sibling artifacts. Read the required `testplan.md` when it exists. Do not re-run ingest exploration. -1. Classify each ingest open question (ingest is an index, not a spec). Do **not** treat ingest text as a complete contract: +2. Cited source/test paths (Affected Components + Cited, not opened) as needed to name types. Signature `offset`/`limit` slices, not whole files. +3. Cap **≤12** cited source Reads total (bootstrap reads of `01-context.md`, `testplan.md`, and `AGENTS.md`/`CLAUDE.md` do not count). Skip a citation if it is not needed to lock a task or interface. +4. Do not glob, repo-wide grep, Jira, or unrelated sibling artifacts. Read the required `testplan.md` when it exists. Do not re-run ingest exploration. +5. Classify each ingest open question (ingest is an index, not a spec). Do **not** treat ingest text as a complete contract: - **Already specified:** citations (or an unambiguous AC) define the component, hook, or behavior → **Locked decision**. - **Implementer default:** unspecified but `/code` needs a choice (component name, prop name, default state value, error message text). Lock a default that matches cited neighboring code; note it is a default `/revise` may change. Do not leave it open. - **Product fork:** spec vs AC, or two product-legal behaviors. Keep under **Open Questions**. Follow AC in the tasks until the user picks. Do not silently lock the design side. -1. Do not paste opened file bodies into `02-plan.md` (signatures and decisions only). +6. Do not paste opened file bodies into `02-plan.md` (signatures and decisions only). ### Step 1a: Evaluate Test Infrastructure diff --git a/ui-implement/skills/publish.md b/ui-implement/skills/publish.md index 08528729..b44bbca5 100644 --- a/ui-implement/skills/publish.md +++ b/ui-implement/skills/publish.md @@ -58,7 +58,7 @@ Verify readiness: the `## Result` section is missing, or it contains `FAIL`, tell the user that `/validate` should be run (or re-run) first. -1. Verify the feature branch exists and has commits: +2. Verify the feature branch exists and has commits: ```bash git branch --show-current @@ -72,7 +72,7 @@ Verify readiness: If there are no commits ahead of the Local Base, there's nothing to publish. -1. Run the shared pre-flight checks: +3. Run the shared pre-flight checks: ```bash python3 "$PUBLISH_SCRIPT" preflight --platform github diff --git a/ui-implement/skills/respond.md b/ui-implement/skills/respond.md index cec8df1f..49acc051 100644 --- a/ui-implement/skills/respond.md +++ b/ui-implement/skills/respond.md @@ -129,20 +129,20 @@ Wait for the user to approve, modify, or reject each response. For comments requiring code changes: 1. Read the affected file(s) -1. Apply the change -1. If the change affects behavior, update or add tests. Tests must +2. Apply the change +3. If the change affects behavior, update or add tests. Tests must validate behavioral contracts through public interfaces — the same standard as `/code`. Match existing test patterns. -1. Run the affected tests to verify -1. Run lint and format checks on the changed files. Fix any issues. -1. Commit using the project's commit format: +4. Run the affected tests to verify +5. Run lint and format checks on the changed files. Fix any issues. +6. Commit using the project's commit format: ```bash git add {specific files} git commit -m "{issue-key}: Address review feedback — {brief description}" ``` -1. After all approved code changes are committed and replies posted, +7. After all approved code changes are committed and replies posted, confirm with the user before pushing. Present the list of commits to push: diff --git a/ui-implement/skills/validate.md b/ui-implement/skills/validate.md index 683fe3ba..6c1e0fcc 100644 --- a/ui-implement/skills/validate.md +++ b/ui-implement/skills/validate.md @@ -31,9 +31,9 @@ and repeat until everything passes. Read: 1. `.artifacts/ui-implement/{issue-key}/01-context.md` (validation profile) -1. `.artifacts/ui-implement/{issue-key}/02-plan.md` (what was implemented) -1. `.artifacts/ui-implement/{issue-key}/04-impl-report.md` (implementation status) -1. `.artifacts/ui-implement/{issue-key}/testplan.md` (story-scoped testplan, if exists) +2. `.artifacts/ui-implement/{issue-key}/02-plan.md` (what was implemented) +3. `.artifacts/ui-implement/{issue-key}/04-impl-report.md` (implementation status) +4. `.artifacts/ui-implement/{issue-key}/testplan.md` (story-scoped testplan, if exists) Extract the validation profile's pre-PR checks list. @@ -89,8 +89,8 @@ either operation, continue but note the staleness in the validation report. Execute each check from the validation profile in order. For each check: 1. **Run the command** -1. **Capture the output** -1. **Assess the result:** pass, fail, or warning +2. **Capture the output** +3. **Assess the result:** pass, fail, or warning Typical checks (discovered, not hardcoded): - Type checking (e.g., TypeScript compilation) @@ -102,19 +102,19 @@ Typical checks (discovered, not hardcoded): **If a check fails:** 1. Diagnose the failure — is it caused by the story's changes or pre-existing? -1. If caused by the story's changes: fix it, commit the fix, re-run the check -1. If pre-existing: note it in the validation report, do not fix it -1. If unclear: report to the user +2. If caused by the story's changes: fix it, commit the fix, re-run the check +3. If pre-existing: note it in the validation report, do not fix it +4. If unclear: report to the user ### Step 4: Analyze Coverage Run coverage analysis on the packages affected by the story: 1. Use the coverage command from the validation profile -1. Focus on the **new and modified code** specifically — compare the +2. Focus on the **new and modified code** specifically — compare the coverage report's per-function or per-line breakdown against the story's diff to isolate new-code coverage from pre-existing code -1. For each public component/hook added or modified: +3. For each public component/hook added or modified: - Are all rendering paths exercised by tests? - Are user interaction paths tested? - Are error, loading, and empty states tested? @@ -123,10 +123,10 @@ Run coverage analysis on the packages affected by the story: If coverage analysis reveals untested behavioral paths in new code: 1. Write additional tests for the missing behaviors -1. Follow the same contract-based testing standards -1. Run the tests to verify they pass -1. Commit following the project's commit format -1. Re-run coverage to confirm improvement +2. Follow the same contract-based testing standards +3. Run the tests to verify they pass +4. Commit following the project's commit format +5. Re-run coverage to confirm improvement Read the **Minimum new-code coverage** percentage from the Coverage Tooling section of `01-context.md` (discovered during `/ingest`, @@ -148,8 +148,8 @@ the component is too coarse-grained. Escalate to the user: Verify that the story's changes haven't broken existing functionality: 1. Run the full unit test suite (not just affected packages) -1. Run the full build (if applicable) -1. Check for any test failures unrelated to the story +2. Run the full build (if applicable) +3. Check for any test failures unrelated to the story If regressions are found: - Diagnose whether the story's changes caused them @@ -189,8 +189,8 @@ After automated checks and code quality review, verify that every acceptance criterion from the story has been satisfied. 1. Read the **Acceptance Criteria** from `01-context.md` -1. Read the **Acceptance Criteria Coverage** matrix from `02-plan.md` -1. For each acceptance criterion: +2. Read the **Acceptance Criteria Coverage** matrix from `02-plan.md` +3. For each acceptance criterion: - **Trace to implementation:** Is there code that implements this criterion? Follow the task mapping — check that the task is marked Done and that the corresponding code exists. @@ -205,9 +205,9 @@ satisfied: 1. If it's a gap in implementation or tests — fix it, commit the fix, and re-run the relevant checks -1. If it's ambiguous whether the criterion is met — flag it to the +2. If it's ambiguous whether the criterion is met — flag it to the user with your assessment -1. If the criterion cannot be verified through automated means (e.g., +3. If the criterion cannot be verified through automated means (e.g., it requires visual verification or describes a UX quality) — note it as "requires manual verification" @@ -224,17 +224,17 @@ Coverage section, skip this step entirely. 1. Read `testplan.md` and extract all TC IDs. Verify that Preconditions, Steps, and Expected Results sections are present for each entry. -1. For each TC ID (except those legitimately N/A based on the plan's +2. For each TC ID (except those legitimately N/A based on the plan's rationale): - Search the test files on the feature branch for a test whose scenario matches the TC's Steps and whose assertions match the Expected Results. - Record the test file and test name for each TC ID. -1. If any TC ID lacks a corresponding test: +3. If any TC ID lacks a corresponding test: - Write the missing test following contract-based testing standards. - Commit the test following the project's commit format. - Re-run the relevant checks from Step 3. -1. Record results for the validation report. +4. Record results for the validation report. ### Step 9: Write Validation Report