evizi-kit 1.0.0

package/README.md

@@ -0,0 +1,506 @@
+# Web Automation Agentic Workflow
+
+## Overview
+
+The **Web Automation Agentic Workflow** is a fully orchestrated, end-to-end pipeline for automated web testing — from ticket intake to code deployment. It is designed around a **coordinator-subagent architecture**: a single orchestrator agent (`web-auto`) delegates each stage of work to a specialized subagent, verifies its output, and proceeds to the next stage.
+
+The workflow is available across three AI platforms. All agent files are maintained in this design repository under platform-specific folders:
+
+| Platform | Source Folder (this repo) | Target Directory (your project) | Agent File Extension |
+|----------|--------------------------|--------------------------------|----------------------|
+| **Cursor** | `cursor-agents/` | `.cursor/agents/` | `.agent.md` |
+| **GitHub Copilot** | `github-copilot-agents/` | `.github/agents/` | `.agent.md` |
+| **Claude Code** | `claude-code-agents/` | `.claude/agents/` | `.md` |
+
+### Setup: Copy Agents and Skills to Your Project
+
+To enable the workflow in your project, copy the corresponding agent folder and the shared `skills/` folder into the correct directory for your platform:
+
+1. **Choose your platform folder** from the table above (e.g., `cursor-agents/` for Cursor)
+2. **Copy all agent files** from that folder into your project's target directory (e.g., `.cursor/agents/`)
+3. **Copy the `skills/` folder** from this design repo into the matching skills directory in your project (e.g., `.cursor/skills/`, `.github/skills/`, or `.claude/skills/`)
+
+All platforms share the same agent logic — only the file format and invocation method differ. The workflow consists of **16 specialized agents** that work together in a defined sequence.
+
+### What It Does
+
+Given a **ticket ID** and its **ticket instruction** (test requirements), the workflow will:
+1. Generate BDD Gherkin test cases
+2. Transform them into an implementation-ready test design
+3. Resolve UI selectors from source code or a live browser
+4. Create a step-by-step implementation playbook
+5. Implement the test code
+6. Self-review the code for issues
+7. Fix issues and run the test (with up to 2 user-assisted retries)
+8. Extract lessons learned
+9. Feed learnings back into project standards
+10. Update feature documentation
+11. Push all changes to Git
+
+### Agents at a Glance
+
+| Agent | Role |
+|-------|------|
+| `web-auto-agentic-workflow-initializer` | Bootstraps the `.documents-design/` folder with foundational reference files |
+| `web-auto` | Pipeline orchestrator — delegates to all other agents in sequence |
+| `web-auto-test-cases-generator` | Generates BDD Gherkin test cases from ticket instruction |
+| `web-auto-ticket-designer` | Transforms Gherkin into implementation-ready test design |
+| `web-auto-fe-selector-extractor` | Resolves placeholder selectors from front-end source code |
+| `web-auto-chrome-devtools-selector-extractor` | Resolves selectors via Chrome DevTools MCP (live DOM) |
+| `web-auto-playwright-mcp-selector-extractor` | Resolves selectors via Playwright MCP (live DOM) |
+| `web-auto-ticket-playbook-planner` | Creates a task-by-task implementation playbook |
+| `web-auto-coder` | Implements test code from the playbook |
+| `self-reviewer` | Pre-PR code review with severity-categorized issues |
+| `web-auto-fix-and-runner` | Autonomous fix of review issues + single test run |
+| `web-auto-assisted-fix-and-runner` | User-assisted fix when autonomous fix fails |
+| `web-auto-lessons-learned-extractor` | Post-implementation analysis and recommendations |
+| `web-auto-source-instructions-updater` | Feeds lessons back into project standards |
+| `feature-document-updater` | Updates feature-level documentation |
+| `code-pusher` | Pushes all changes to the Git remote |
+
+---
+
+## Initialization
+
+Before running the main pipeline for the first time, you must initialize the project's reference system. This is a **one-time setup** that creates the foundational documentation files all other agents depend on.
+
+### Using the Initializer Agent
+
+Invoke the `web-auto-agentic-workflow-initializer` agent:
+
+| Platform | How to invoke |
+|----------|---------------|
+| **Cursor** | Type `/web-auto-agentic-workflow-initializer` in chat, then enter: `Initialize the new AI web automation workflow` |
+| **GitHub Copilot** | Select `web-auto-agentic-workflow-initializer` from the agent picker, then enter: `Initialize the new AI web automation workflow` |
+| **Claude Code** | Type `/web-auto-agentic-workflow-initializer` in chat, then enter: `Initialize the new AI web automation workflow` |
+
+It will:
+
+1. **Create `.documents-design/`** — checks if the folder exists at the repository root and creates it if missing
+2. **Collect best practices** — asks you: _"Do you have any web automation best practices to add? You can paste rules, standards, or anti-patterns in any format — or say **skip** to create an empty file."_ It waits for your response before continuing
+3. **Generate `web-auto-best-practices.md`** — if you provided input, it follows the `web-auto-generate-best-practices` skill to structure and format them; if you skipped, it creates a minimal file with only the heading
+4. **Generate `web-auto-project-blueprint.md`** — follows the `web-auto-generate-project-blueprint` skill to analyze your codebase and document framework, folder structure, selector strategy, and conventions
+5. **Generate `web-auto-instructions.md`** — follows the `web-auto-generate-instructions` skill, using the files from steps 3–4 as context to produce comprehensive coding instructions
+
+After completion, you'll see a summary table:
+
+| File | Status |
+|------|--------|
+| `.documents-design/web-auto-best-practices.md` | Created |
+| `.documents-design/web-auto-project-blueprint.md` | Created |
+| `.documents-design/web-auto-instructions.md` | Created |
+
+**⚠️ Important:** Steps must execute in order — each file is a dependency for the next. Do not skip the user prompt in step 2.
+
+### Create `project.config.json` (Manual)
+
+After the initializer completes, manually create `.documents-design/project.config.json`. This file defines the base branch, platform settings, repository mapping, and feature flags used by the `self-review` and `pr-review` skills.
+
+Example structure:
+
+```json
+{
+  "baseBranch": "develop",
+  "platform": "gitea",
+  "platformConfig": {
+    "gitea": {
+      "apiUrl": "https://gitea.example.com/api/v1"
+    }
+  },
+  "repos": {
+    "webAuto": {
+      "gitea": { "owner": "org-name", "repo": "webdriver-io" }
+    },
+    "webApp": {
+      "gitea": { "owner": "org-name", "repo": "dashboard" }
+    }
+  },
+  "enableCommentPosting": true,
+  "enableNotification": true
+}
+```
+
+### Platform-Specific Setup
+
+After running the initializer, you should create the workspace-level AI navigation file appropriate for your platform:
+
+#### Cursor / GitHub Copilot → Create `AGENTS.md`
+
+Use the `workspace-ai-nav-creator` skill to scan the workspace and generate an `AGENTS.md` file at the workspace root. This file guides the AI to:
+- Navigate to the correct repository for any given task
+- Invoke the correct agents for each workflow step
+- Follow workspace-specific commands, conventions, and documentation rules
+
+**Invocation**: Ask the agent to _"Create AGENTS.md for this workspace"_ or _"Generate AGENTS.md for Cursor/Copilot"_.
+
+#### Claude Code → Create `CLAUDE.md`
+
+Use the `workspace-ai-nav-creator` skill to scan the workspace and generate a `CLAUDE.md` file at the workspace root. This serves the same purpose as `AGENTS.md` but uses Claude Code's instruction format.
+
+**Invocation**: Ask the agent to _"Create CLAUDE.md for this workspace"_ or _"Generate CLAUDE.md for Claude Code"_.
+
+**📝 Note:** The `workspace-ai-nav-creator` skill automatically detects the target AI system based on existing configuration (`.github/agents/`, `.cursor/agents/`, `.claude/agents/`). If both are detected, it will ask which file to generate.
+
+---
+
+## Pipeline Execution — Step by Step
+
+Once initialization is complete, the main workflow is triggered by calling the `web-auto` agent with a ticket ID. The orchestrator manages the entire pipeline.
+
+### How to Start the Pipeline
+
+| Platform | How to invoke |
+|----------|---------------|
+| **Cursor** | Type `/web-auto` in chat, then enter: `Implement ticket TKT-001` |
+| **GitHub Copilot** | Select `web-auto` from the agent picker, then enter: `Implement ticket TKT-001` |
+| **Claude Code** | Type `/web-auto` in chat, then enter: `Implement ticket TKT-001` |
+
+Replace `TKT-001` with your actual ticket ID.
+
+### Pre-Pipeline: Collect Ticket Instruction
+
+After invocation, the orchestrator asks:
+
+> _Please provide the ticket instructions for ticket {TICKET_ID}. The ticket may contain one or more test cases — include all of them. Paste the ticket instructions below:_
+
+The user pastes the ticket instruction and the pipeline begins.
+
+---
+
+### Step 1: Generate Test Cases
+
+| | |
+|---|---|
+| **Subagent** | `web-auto-test-cases-generator` |
+| **Input** | Ticket ID + ticket instruction |
+| **Output** | `.tickets/{TICKET_ID}/test-cases.md` |
+
+The test-cases-generator:
+1. Extracts `PARENT_FEATURE` and `CHILD_FEATURE` from the ticket's Feature field
+2. Creates the `.tickets/{TICKET_ID}/` directory
+3. Performs full ticket analysis — extracts all Test Case IDs and maps scenarios 1:1
+4. Generates comprehensive BDD Gherkin content with exact test case IDs, `@cleanup` tags where post-conditions require it, and double-quoted variable data
+5. Saves to `test-cases.md` and reports scenario count
+
+**Verification**: The orchestrator confirms that `test-cases.md` was created.
+
+---
+
+### Step 2: Create Test Design
+
+| | |
+|---|---|
+| **Subagent** | `web-auto-ticket-designer` |
+| **Input** | Ticket ID (reads `test-cases.md` from ticket directory) |
+| **Output** | `.tickets/{TICKET_ID}/ticket-design.md` |
+
+The ticket-designer:
+1. Reads and parses `test-cases.md` — extracts features, test case IDs, key actions, elements, and quoted test data
+2. Deeply searches the codebase for existing Page Objects, element locators, action methods, and API helpers
+3. Builds an internal catalog of all discovered reusable resources
+4. Transforms each Gherkin step using a format selection guide (Format 1–4) based on what exists in the codebase
+5. Saves the design to `ticket-design.md` with a summary of reuse counts and new implementation needs
+
+**Verification & Decision**: The orchestrator checks whether the design contains **placeholder selectors** (`<-- Update selector for this element -->`):
+- **Placeholders found** → proceed to Step 3
+- **No placeholders** → skip Step 3, proceed directly to Step 4
+
+---
+
+### Step 3: Resolve Selectors (Conditional)
+
+| | |
+|---|---|
+| **Subagent** | Automatically selected (see decision tree below) |
+| **Input** | Ticket ID (reads `ticket-design.md`) |
+| **Output** | Updated `ticket-design.md` with real selectors |
+
+This step only executes if Step 2 found placeholder selectors. The orchestrator automatically selects the appropriate subagent:
+
+**Selector Agent Decision Tree:**
+
+1. **Check** — Does the workspace contain `.tsx`, `.jsx`, or `.vue` files?
+   - ✅ **Yes** → Use **`web-auto-fe-selector-extractor`** (search front-end source)
+     - After extraction, do placeholders still remain?
+       - ✅ **Yes** → Run Chrome DevTools or Playwright MCP extractor as fallback
+       - ❌ **No** → Done, proceed to Step 4
+   - ❌ **No** → Continue to next check
+2. **Check** — Are `chrome-devtools/*` MCP tools available?
+   - ✅ **Yes** → Use **`web-auto-chrome-devtools-selector-extractor`** (live DOM via Chrome)
+   - ❌ **No** → Use **`web-auto-playwright-mcp-selector-extractor`** (live DOM via Playwright, default)
+
+#### Option A: Front-End Source Extractor (`web-auto-fe-selector-extractor`)
+Searches front-end source code (`.tsx`, `.jsx`, `.vue`) using a funnel strategy: narrow feature-scoped search → dynamic/template patterns → broad fallback → component hierarchy. Confirms each match by reading surrounding code context.
+
+#### Option B: Chrome DevTools MCP Extractor (`web-auto-chrome-devtools-selector-extractor`)
+Navigates the live application via Chrome DevTools MCP. Takes accessibility-tree snapshots, uses `evaluate_script` to extract DOM attributes, and picks the best selector per the project's locator priority (data-testid > role+name > aria-label > CSS).
+
+#### Option C: Playwright MCP Extractor (`web-auto-playwright-mcp-selector-extractor`)
+Navigates the live app via Playwright MCP. Uses `browser_snapshot` and `browser_run_javascript` to identify elements and extract DOM attributes. Same locator priority strategy as Chrome DevTools.
+
+**📝 Note:** All selector extractors only modify `- Selector:` lines in `ticket-design.md` — they never alter the design structure. Unresolvable placeholders are left unchanged and reported.
+
+---
+
+### Step 4: Create Implementation Playbook
+
+| | |
+|---|---|
+| **Subagent** | `web-auto-ticket-playbook-planner` |
+| **Input** | Ticket ID (reads `ticket-design.md` + project reference files) |
+| **Output** | `.tickets/{TICKET_ID}/ticket-playbook.md` |
+
+The playbook planner:
+1. Reads `ticket-design.md` and all project instruction files (`web-auto-project-blueprint.md`, `web-auto-instructions.md`, `web-auto-best-practices.md`)
+2. Deeply searches the codebase for reusable Page Objects, utilities, fixtures, and reference patterns
+3. Plans implementation tasks in dependency order: **Test Data → API Helpers → Page Object Updates → New Page Objects → Test Scripts**
+4. Validates the dependency graph (no circular deps, correct ordering, all imports covered)
+5. Saves the playbook with enough detail for the coding agent to implement without re-searching the codebase
+
+---
+
+### Step 5: Implement Test Code
+
+| | |
+|---|---|
+| **Subagent** | `web-auto-coder` |
+| **Input** | Ticket ID (reads `ticket-playbook.md`) |
+| **Output** | Created/modified source files (Page Objects, test data, API helpers, test scripts) |
+
+The coder:
+1. Reads the playbook — extracts all tasks, dependency order, file paths, reference patterns, and conventions
+2. Sorts tasks by dependencies and groups same-file modifications
+3. Executes each task in order: reads context, reads reference pattern, writes code, verifies for errors
+4. Runs final verification: syntax check, import resolution, cross-file consistency, pattern adherence
+5. Reports files created, files modified, and component counts
+
+**⚠️ Important:** The playbook is the single source of truth. The coder does not deviate from its tasks, paths, or conventions.
+
+---
+
+### Step 6: Review Code Changes
+
+| | |
+|---|---|
+| **Subagent** | `self-reviewer` |
+| **Input** | Ticket ID (analyzes git diff of current branch) |
+| **Output** | `.tickets/{TICKET_ID}/issues.md` |
+
+The self-reviewer:
+1. Loads project configuration to determine the target branch and exclude paths
+2. Fetches the target branch and runs a three-dot `git diff` to isolate only the current branch's changes
+3. Identifies the tech stack and loads matching domain checklists + project-specific guidelines
+4. Reviews every change and classifies issues:
+   - ❌ **Critical** — real production risks
+   - ⚠️ **Warning** — potential problems
+   - 💡 **Suggestion** — improvements
+5. Generates `issues.md` with a verdict:
+   - ✅ **Ready to Create PR** — zero critical issues
+   - ⚠️ **Ready with Warnings** — zero critical, some warnings
+   - ❌ **Not Ready for PR** — one or more critical issues
+
+---
+
+### Step 7: Fix Issues and Run Test (Autonomous)
+
+| | |
+|---|---|
+| **Subagent** | `web-auto-fix-and-runner` |
+| **Input** | Ticket ID (reads `issues.md` + `ticket-playbook.md`) |
+| **Output** | `.tickets/{TICKET_ID}/issues-resolution-report.md` + structured result |
+
+The fix-and-runner:
+1. Reads `issues.md` — extracts all issues by severity and the test run command
+2. Fixes all issues in priority order: **Critical → Warnings → Suggestions**
+3. Groups same-file fixes to avoid stale-read conflicts
+4. Runs the test command **exactly once** and captures full output
+5. Emits a structured result block:
+   - `FIX-AND-RUN RESULT: PASSED` → proceeds to Step 8
+   - `FIX-AND-RUN RESULT: FAILED` → proceeds to Step 7B
+
+---
+
+### Step 7B: User-Assisted Fix — Attempt 1 (Conditional)
+
+| | |
+|---|---|
+| **Subagent** | `web-auto-assisted-fix-and-runner` |
+| **Condition** | Only runs if Step 7 returned `FAILED` |
+
+The orchestrator displays the error to the user and asks:
+
+> _Autonomous fix failed for ticket {TICKET_ID}._
+> _Error: {error details}_
+> _Do you have any hints or fixes to try? (Attempt 1/2)_
+
+After receiving the user's hint, it invokes the assisted-fix-and-runner, which:
+1. Parses the failure summary and reads what was already tried
+2. Interprets the user hint (direct code change, diagnosis, new context, or broad direction)
+3. Applies the fix and runs the test once
+4. Emits `ASSISTED-RUN RESULT: PASSED` or `FAILED`
+
+---
+
+### Step 7C: User-Assisted Fix — Attempt 2, Final (Conditional)
+
+| | |
+|---|---|
+| **Subagent** | `web-auto-assisted-fix-and-runner` |
+| **Condition** | Only runs if Step 7B returned `FAILED` |
+
+Same flow as 7B but this is the **final attempt** (max 2 user-assisted retries). If it still fails, the orchestrator reports the final failure and proceeds to Step 8 anyway.
+
+**Fix & Run Retry Flow:**
+
+| Stage | Result | Next Action |
+|-------|--------|-------------|
+| Step 7: Autonomous Fix & Run | ✅ PASSED | → Step 8: Lessons Learned |
+| Step 7: Autonomous Fix & Run | ❌ FAILED | → Step 7B: User-Assisted Fix (Attempt 1) |
+| Step 7B: User-Assisted Fix (1/2) | ✅ PASSED | → Step 8: Lessons Learned |
+| Step 7B: User-Assisted Fix (1/2) | ❌ FAILED | → Step 7C: User-Assisted Fix (Attempt 2, Final) |
+| Step 7C: User-Assisted Fix (2/2) | ✅ PASSED | → Step 8: Lessons Learned |
+| Step 7C: User-Assisted Fix (2/2) | ❌ FAILED | → Step 8: Lessons Learned (proceeds anyway, failure noted) |
+
+---
+
+### Step 8: Extract Lessons Learned
+
+| | |
+|---|---|
+| **Subagent** | `web-auto-lessons-learned-extractor` |
+| **Input** | Ticket ID (reads `issues.md`, `issues-resolution-report.md`, ticket artifacts, and project standards) |
+| **Output** | `.tickets/{TICKET_ID}/lessons-learned.md` |
+
+The lessons-learned extractor:
+1. Reads the review report and resolution report
+2. Analyzes four dimensions: what worked well, challenges encountered, how issues were resolved, recommendations
+3. Deduplicates recommendations against existing project standards — only recommends what's genuinely missing
+4. Focuses on specificity over completeness — precise root causes over generic reports
+5. Failures and user-assisted fixes receive deeper analytical attention
+
+---
+
+### Step 9: Update Source Instructions
+
+| | |
+|---|---|
+| **Subagent** | `web-auto-source-instructions-updater` |
+| **Input** | Ticket ID (reads `lessons-learned.md` + project instruction files) |
+| **Output** | Updated `.documents-design/` files |
+
+The source instructions updater:
+1. Extracts recommendations from `lessons-learned.md` grouped by target document
+2. Deduplicates rigorously against existing content — drops already-covered items, reframes partial matches
+3. Flags contradictions for user input (never silently overrides existing content)
+4. Applies surviving recommendations to the appropriate files:
+   - **Project Blueprint** ← structural details
+   - **Coding Instructions** ← code patterns
+   - **Best Practices** ← Do/Don't rows and code examples
+
+**💡 Tip:** This step closes the **feedback loop** — lessons from each ticket continuously improve the project's reference system, making future tickets more accurate.
+
+---
+
+### Step 10: Update Feature Documentation
+
+| | |
+|---|---|
+| **Subagent** | `feature-document-updater` |
+| **Input** | Ticket ID (reads all ticket artifacts) |
+| **Output** | Updated `feature.md` and appended `delta.yaml` |
+
+The feature document updater:
+1. Identifies the feature path (`PARENT_FEATURE / CHILD_FEATURE`) from ticket artifacts
+2. Extracts ticket data: summary, type, behaviors, files created/modified, test result
+3. Updates or creates `feature.md` — only changes behavioral specs when the ticket reveals new or corrected behaviors
+4. Appends the ticket entry to `delta.yaml` (append-only — never removes or reorders)
+5. Calculates and sets feature status: `draft` / `in-progress` / `complete`
+
+---
+
+### Step 11: Push Code
+
+| | |
+|---|---|
+| **Subagent** | `code-pusher` |
+| **Input** | Ticket ID |
+| **Output** | Git commit and push |
+
+The code pusher:
+1. Verifies git identity is configured
+2. Checks for protected branch guards (main, master, develop)
+3. Stages changes and generates a conventional commit message from the diff
+4. Pushes to the remote, setting upstream if needed
+5. Reports: branch, commit hash, file count
+
+---
+
+## Pipeline Summary
+
+Upon completing all steps, the orchestrator displays a final summary:
+
+```
+Pipeline Complete for ticket {TICKET_ID}
+
+✓ Step 1: Generate Test Cases
+✓ Step 2: Create Test Design
+✓ Step 3: Resolve Selectors (executed - placeholder selectors found)
+✓ Step 4: Create Implementation Playbook
+✓ Step 5: Implement Test Code
+✓ Step 6: Review Code Changes
+✓ Step 7: Fix Issues and Run Test (Autonomous)
+— Step 7B: User-Assisted Fix Attempt 1 (skipped - Step 7 passed)
+— Step 7C: User-Assisted Fix Attempt 2 (skipped - Step 7 passed)
+✓ Step 8: Extract Lessons Learned
+✓ Step 9: Update Source Instructions
+✓ Step 10: Update Feature Documentation
+✓ Step 11: Push Code
+
+All changes have been pushed to the repository.
+```
+
+---
+
+## Artifacts Produced Per Ticket
+
+All artifacts are stored under `.tickets/{TICKET_ID}/`:
+
+| Artifact | Created By | Description |
+|----------|-----------|-------------|
+| `test-cases.md` | Step 1 — test-cases-generator | BDD Gherkin scenarios |
+| `ticket-design.md` | Step 2 — ticket-designer | Implementation-ready test design with selectors |
+| `ticket-playbook.md` | Step 4 — playbook-planner | Task-by-task implementation plan |
+| `issues.md` | Step 6 — self-reviewer | Code review report with severity-categorized issues |
+| `issues-resolution-report.md` | Step 7/7B/7C — fix-and-runner | Fix attempts and test results |
+| `lessons-learned.md` | Step 8 — lessons-learned-extractor | Post-implementation analysis and recommendations |
+
+## End-to-End Flow
+
+### Initialization (One-time)
+
+```
+web-auto-agentic-workflow-initializer
+  ├── web-auto-best-practices.md
+  ├── web-auto-project-blueprint.md
+  ├── web-auto-instructions.md
+  └── AGENTS.md / CLAUDE.md (via workspace-ai-nav-creator)
+```
+
+### Pipeline (Per Ticket)
+
+```
+Ticket ID + Content
+  │
+  ├── 1. Test Cases Generator
+  ├── 2. Ticket Designer
+  ├── 3. Resolve Selectors? ─── (if placeholders found) ──→ Selector Extractor
+  │                          └─ (no placeholders) ──────────────────┐
+  ├── 4. Playbook Planner  ←────────────────────────────────────────┘
+  ├── 5. Coder
+  ├── 6. Self-Reviewer
+  ├── 7. Fix & Run ─── (PASSED) ──→ 8. Lessons Learned
+  │              └──── (FAILED) ──→ 7B/7C. Assisted Fix & Run ──→ 8. Lessons Learned
+  ├── 9. Update Source Instructions
+  ├── 10. Update Feature Docs
+  └── 11. Push Code
+```