evizi-kit 1.0.0

package/kits/agent/.agent/skills/skill-creator/scripts/run_loop.py

@@ -0,0 +1,328 @@
+#!/usr/bin/env python3
+"""Run the eval + improve loop until all pass or max iterations reached.
+
+Combines run_eval.py and improve_description.py in a loop, tracking history
+and returning the best description found. Supports train/test split to prevent
+overfitting.
+"""
+
+import argparse
+import json
+import random
+import sys
+import tempfile
+import time
+import webbrowser
+from pathlib import Path
+
+from scripts.generate_report import generate_html
+from scripts.improve_description import improve_description
+from scripts.run_eval import find_project_root, run_eval
+from scripts.utils import parse_skill_md
+
+
+def split_eval_set(eval_set: list[dict], holdout: float, seed: int = 42) -> tuple[list[dict], list[dict]]:
+    """Split eval set into train and test sets, stratified by should_trigger."""
+    random.seed(seed)
+
+    # Separate by should_trigger
+    trigger = [e for e in eval_set if e["should_trigger"]]
+    no_trigger = [e for e in eval_set if not e["should_trigger"]]
+
+    # Shuffle each group
+    random.shuffle(trigger)
+    random.shuffle(no_trigger)
+
+    # Calculate split points
+    n_trigger_test = max(1, int(len(trigger) * holdout))
+    n_no_trigger_test = max(1, int(len(no_trigger) * holdout))
+
+    # Split
+    test_set = trigger[:n_trigger_test] + no_trigger[:n_no_trigger_test]
+    train_set = trigger[n_trigger_test:] + no_trigger[n_no_trigger_test:]
+
+    return train_set, test_set
+
+
+def run_loop(
+    eval_set: list[dict],
+    skill_path: Path,
+    description_override: str | None,
+    num_workers: int,
+    timeout: int,
+    max_iterations: int,
+    runs_per_query: int,
+    trigger_threshold: float,
+    holdout: float,
+    model: str,
+    verbose: bool,
+    live_report_path: Path | None = None,
+    log_dir: Path | None = None,
+) -> dict:
+    """Run the eval + improvement loop."""
+    project_root = find_project_root()
+    name, original_description, content = parse_skill_md(skill_path)
+    current_description = description_override or original_description
+
+    # Split into train/test if holdout > 0
+    if holdout > 0:
+        train_set, test_set = split_eval_set(eval_set, holdout)
+        if verbose:
+            print(f"Split: {len(train_set)} train, {len(test_set)} test (holdout={holdout})", file=sys.stderr)
+    else:
+        train_set = eval_set
+        test_set = []
+
+    history = []
+    exit_reason = "unknown"
+
+    for iteration in range(1, max_iterations + 1):
+        if verbose:
+            print(f"\n{'='*60}", file=sys.stderr)
+            print(f"Iteration {iteration}/{max_iterations}", file=sys.stderr)
+            print(f"Description: {current_description}", file=sys.stderr)
+            print(f"{'='*60}", file=sys.stderr)
+
+        # Evaluate train + test together in one batch for parallelism
+        all_queries = train_set + test_set
+        t0 = time.time()
+        all_results = run_eval(
+            eval_set=all_queries,
+            skill_name=name,
+            description=current_description,
+            num_workers=num_workers,
+            timeout=timeout,
+            project_root=project_root,
+            runs_per_query=runs_per_query,
+            trigger_threshold=trigger_threshold,
+            model=model,
+        )
+        eval_elapsed = time.time() - t0
+
+        # Split results back into train/test by matching queries
+        train_queries_set = {q["query"] for q in train_set}
+        train_result_list = [r for r in all_results["results"] if r["query"] in train_queries_set]
+        test_result_list = [r for r in all_results["results"] if r["query"] not in train_queries_set]
+
+        train_passed = sum(1 for r in train_result_list if r["pass"])
+        train_total = len(train_result_list)
+        train_summary = {"passed": train_passed, "failed": train_total - train_passed, "total": train_total}
+        train_results = {"results": train_result_list, "summary": train_summary}
+
+        if test_set:
+            test_passed = sum(1 for r in test_result_list if r["pass"])
+            test_total = len(test_result_list)
+            test_summary = {"passed": test_passed, "failed": test_total - test_passed, "total": test_total}
+            test_results = {"results": test_result_list, "summary": test_summary}
+        else:
+            test_results = None
+            test_summary = None
+
+        history.append({
+            "iteration": iteration,
+            "description": current_description,
+            "train_passed": train_summary["passed"],
+            "train_failed": train_summary["failed"],
+            "train_total": train_summary["total"],
+            "train_results": train_results["results"],
+            "test_passed": test_summary["passed"] if test_summary else None,
+            "test_failed": test_summary["failed"] if test_summary else None,
+            "test_total": test_summary["total"] if test_summary else None,
+            "test_results": test_results["results"] if test_results else None,
+            # For backward compat with report generator
+            "passed": train_summary["passed"],
+            "failed": train_summary["failed"],
+            "total": train_summary["total"],
+            "results": train_results["results"],
+        })
+
+        # Write live report if path provided
+        if live_report_path:
+            partial_output = {
+                "original_description": original_description,
+                "best_description": current_description,
+                "best_score": "in progress",
+                "iterations_run": len(history),
+                "holdout": holdout,
+                "train_size": len(train_set),
+                "test_size": len(test_set),
+                "history": history,
+            }
+            live_report_path.write_text(generate_html(partial_output, auto_refresh=True, skill_name=name))
+
+        if verbose:
+            def print_eval_stats(label, results, elapsed):
+                pos = [r for r in results if r["should_trigger"]]
+                neg = [r for r in results if not r["should_trigger"]]
+                tp = sum(r["triggers"] for r in pos)
+                pos_runs = sum(r["runs"] for r in pos)
+                fn = pos_runs - tp
+                fp = sum(r["triggers"] for r in neg)
+                neg_runs = sum(r["runs"] for r in neg)
+                tn = neg_runs - fp
+                total = tp + tn + fp + fn
+                precision = tp / (tp + fp) if (tp + fp) > 0 else 1.0
+                recall = tp / (tp + fn) if (tp + fn) > 0 else 1.0
+                accuracy = (tp + tn) / total if total > 0 else 0.0
+                print(f"{label}: {tp+tn}/{total} correct, precision={precision:.0%} recall={recall:.0%} accuracy={accuracy:.0%} ({elapsed:.1f}s)", file=sys.stderr)
+                for r in results:
+                    status = "PASS" if r["pass"] else "FAIL"
+                    rate_str = f"{r['triggers']}/{r['runs']}"
+                    print(f"  [{status}] rate={rate_str} expected={r['should_trigger']}: {r['query'][:60]}", file=sys.stderr)
+
+            print_eval_stats("Train", train_results["results"], eval_elapsed)
+            if test_summary:
+                print_eval_stats("Test ", test_results["results"], 0)
+
+        if train_summary["failed"] == 0:
+            exit_reason = f"all_passed (iteration {iteration})"
+            if verbose:
+                print(f"\nAll train queries passed on iteration {iteration}!", file=sys.stderr)
+            break
+
+        if iteration == max_iterations:
+            exit_reason = f"max_iterations ({max_iterations})"
+            if verbose:
+                print(f"\nMax iterations reached ({max_iterations}).", file=sys.stderr)
+            break
+
+        # Improve the description based on train results
+        if verbose:
+            print(f"\nImproving description...", file=sys.stderr)
+
+        t0 = time.time()
+        # Strip test scores from history so improvement model can't see them
+        blinded_history = [
+            {k: v for k, v in h.items() if not k.startswith("test_")}
+            for h in history
+        ]
+        new_description = improve_description(
+            skill_name=name,
+            skill_content=content,
+            current_description=current_description,
+            eval_results=train_results,
+            history=blinded_history,
+            model=model,
+            log_dir=log_dir,
+            iteration=iteration,
+        )
+        improve_elapsed = time.time() - t0
+
+        if verbose:
+            print(f"Proposed ({improve_elapsed:.1f}s): {new_description}", file=sys.stderr)
+
+        current_description = new_description
+
+    # Find the best iteration by TEST score (or train if no test set)
+    if test_set:
+        best = max(history, key=lambda h: h["test_passed"] or 0)
+        best_score = f"{best['test_passed']}/{best['test_total']}"
+    else:
+        best = max(history, key=lambda h: h["train_passed"])
+        best_score = f"{best['train_passed']}/{best['train_total']}"
+
+    if verbose:
+        print(f"\nExit reason: {exit_reason}", file=sys.stderr)
+        print(f"Best score: {best_score} (iteration {best['iteration']})", file=sys.stderr)
+
+    return {
+        "exit_reason": exit_reason,
+        "original_description": original_description,
+        "best_description": best["description"],
+        "best_score": best_score,
+        "best_train_score": f"{best['train_passed']}/{best['train_total']}",
+        "best_test_score": f"{best['test_passed']}/{best['test_total']}" if test_set else None,
+        "final_description": current_description,
+        "iterations_run": len(history),
+        "holdout": holdout,
+        "train_size": len(train_set),
+        "test_size": len(test_set),
+        "history": history,
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Run eval + improve loop")
+    parser.add_argument("--eval-set", required=True, help="Path to eval set JSON file")
+    parser.add_argument("--skill-path", required=True, help="Path to skill directory")
+    parser.add_argument("--description", default=None, help="Override starting description")
+    parser.add_argument("--num-workers", type=int, default=10, help="Number of parallel workers")
+    parser.add_argument("--timeout", type=int, default=30, help="Timeout per query in seconds")
+    parser.add_argument("--max-iterations", type=int, default=5, help="Max improvement iterations")
+    parser.add_argument("--runs-per-query", type=int, default=3, help="Number of runs per query")
+    parser.add_argument("--trigger-threshold", type=float, default=0.5, help="Trigger rate threshold")
+    parser.add_argument("--holdout", type=float, default=0.4, help="Fraction of eval set to hold out for testing (0 to disable)")
+    parser.add_argument("--model", required=True, help="Model for improvement")
+    parser.add_argument("--verbose", action="store_true", help="Print progress to stderr")
+    parser.add_argument("--report", default="auto", help="Generate HTML report at this path (default: 'auto' for temp file, 'none' to disable)")
+    parser.add_argument("--results-dir", default=None, help="Save all outputs (results.json, report.html, log.txt) to a timestamped subdirectory here")
+    args = parser.parse_args()
+
+    eval_set = json.loads(Path(args.eval_set).read_text())
+    skill_path = Path(args.skill_path)
+
+    if not (skill_path / "SKILL.md").exists():
+        print(f"Error: No SKILL.md found at {skill_path}", file=sys.stderr)
+        sys.exit(1)
+
+    name, _, _ = parse_skill_md(skill_path)
+
+    # Set up live report path
+    if args.report != "none":
+        if args.report == "auto":
+            timestamp = time.strftime("%Y%m%d_%H%M%S")
+            live_report_path = Path(tempfile.gettempdir()) / f"skill_description_report_{skill_path.name}_{timestamp}.html"
+        else:
+            live_report_path = Path(args.report)
+        # Open the report immediately so the user can watch
+        live_report_path.write_text("<html><body><h1>Starting optimization loop...</h1><meta http-equiv='refresh' content='5'></body></html>")
+        webbrowser.open(str(live_report_path))
+    else:
+        live_report_path = None
+
+    # Determine output directory (create before run_loop so logs can be written)
+    if args.results_dir:
+        timestamp = time.strftime("%Y-%m-%d_%H%M%S")
+        results_dir = Path(args.results_dir) / timestamp
+        results_dir.mkdir(parents=True, exist_ok=True)
+    else:
+        results_dir = None
+
+    log_dir = results_dir / "logs" if results_dir else None
+
+    output = run_loop(
+        eval_set=eval_set,
+        skill_path=skill_path,
+        description_override=args.description,
+        num_workers=args.num_workers,
+        timeout=args.timeout,
+        max_iterations=args.max_iterations,
+        runs_per_query=args.runs_per_query,
+        trigger_threshold=args.trigger_threshold,
+        holdout=args.holdout,
+        model=args.model,
+        verbose=args.verbose,
+        live_report_path=live_report_path,
+        log_dir=log_dir,
+    )
+
+    # Save JSON output
+    json_output = json.dumps(output, indent=2)
+    print(json_output)
+    if results_dir:
+        (results_dir / "results.json").write_text(json_output)
+
+    # Write final HTML report (without auto-refresh)
+    if live_report_path:
+        live_report_path.write_text(generate_html(output, auto_refresh=False, skill_name=name))
+        print(f"\nReport: {live_report_path}", file=sys.stderr)
+
+    if results_dir and live_report_path:
+        (results_dir / "report.html").write_text(generate_html(output, auto_refresh=False, skill_name=name))
+
+    if results_dir:
+        print(f"Results saved to: {results_dir}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

package/kits/agent/.agent/skills/skill-creator/scripts/utils.py

@@ -0,0 +1,47 @@
+"""Shared utilities for skill-creator scripts."""
+
+from pathlib import Path
+
+
+
+def parse_skill_md(skill_path: Path) -> tuple[str, str, str]:
+    """Parse a SKILL.md file, returning (name, description, full_content)."""
+    content = (skill_path / "SKILL.md").read_text()
+    lines = content.split("\n")
+
+    if lines[0].strip() != "---":
+        raise ValueError("SKILL.md missing frontmatter (no opening ---)")
+
+    end_idx = None
+    for i, line in enumerate(lines[1:], start=1):
+        if line.strip() == "---":
+            end_idx = i
+            break
+
+    if end_idx is None:
+        raise ValueError("SKILL.md missing frontmatter (no closing ---)")
+
+    name = ""
+    description = ""
+    frontmatter_lines = lines[1:end_idx]
+    i = 0
+    while i < len(frontmatter_lines):
+        line = frontmatter_lines[i]
+        if line.startswith("name:"):
+            name = line[len("name:"):].strip().strip('"').strip("'")
+        elif line.startswith("description:"):
+            value = line[len("description:"):].strip()
+            # Handle YAML multiline indicators (>, |, >-, |-)
+            if value in (">", "|", ">-", "|-"):
+                continuation_lines: list[str] = []
+                i += 1
+                while i < len(frontmatter_lines) and (frontmatter_lines[i].startswith("  ") or frontmatter_lines[i].startswith("\t")):
+                    continuation_lines.append(frontmatter_lines[i].strip())
+                    i += 1
+                description = " ".join(continuation_lines)
+                continue
+            else:
+                description = value.strip('"').strip("'")
+        i += 1
+
+    return name, description, content

package/kits/agent/manifest.json

@@ -0,0 +1,10 @@
+{
+  "name": "agent",
+  "displayName": "VS Code Agent",
+  "version": "1.0.0",
+  "description": "VS Code Agent mode configuration with skills",
+  "files": [
+    { "src": ".agent/", "dest": ".agent/" }
+  ],
+  "dependencies": ["shared"]
+}

package/kits/claude/.claude/agents/code-pusher.md

@@ -0,0 +1,46 @@
+---
+name: code-pusher
+description: Push current code changes to the Git remote with auto-generated conventional commit messages. Use whenever the user wants to push code, commit and push, save changes to remote, git push, send code upstream, ship code, deploy changes to a branch, or sync local work with the remote — even if they don't explicitly mention git.
+tools: Bash, Read, Grep
+model: claude
+skills:
+  - push-code
+---
+
+You are a Git operations specialist responsible for safely pushing code changes to the remote repository.
+
+Follow the workflow defined in the push-code skill.
+
+When invoked:
+1. Verify git is available and identity (user.name, user.email) is configured
+2. Check the current branch and working tree status
+3. Guard against pushing directly to protected branches (main, master, develop)
+4. Stage changes — respect pre-staged files, only add all if nothing is staged
+5. Generate a conventional commit message from the diff and commit
+6. Push to the remote, setting upstream if needed
+7. Report final status with branch, commit hash, and file count
+
+Key practices:
+- Always stop at the first failure and report clearly — never push broken state
+- If the user provides a commit message, use it exactly as given
+- For large diffs (500+ lines), rely on `--stat` for the commit message rather than reading every line
+- Use conventional commit prefixes: feat, fix, refactor, docs, chore, test, style, ci, build
+
+Report results in this format:
+
+On success:
+```
+✅ Push Completed
+- Branch: [branch_name]
+- Commit: [short_hash] — [commit message]
+- Files changed: [count]
+- Pushed to: origin/[branch_name]
+```
+
+On failure:
+```
+❌ Push Failed
+- Step: [which step failed]
+- Error: [error message]
+- Suggested fix: [actionable guidance]
+```

package/kits/claude/.claude/agents/feature-document-updater.md

@@ -0,0 +1,37 @@
+---
+name: feature-document-updater
+description: Update feature documentation (feature.md and delta.yaml) after completing a ticket. Use when a ticket is done and the feature docs need to reflect the work — even if the user doesn't say "feature document" explicitly. Triggers on requests like "update feature document for ticket X", "log ticket to feature", "update feature after implementing ticket Y", "record ticket completion for feature", "sync docs after finishing ticket Z", or any mention of recording a finished ticket into feature documentation.
+tools: Read, Write, Edit, Grep, Glob
+model: claude
+skills:
+  - update-feature-document
+---
+
+You are a feature documentation specialist responsible for keeping feature.md and delta.yaml in sync with completed ticket work.
+
+Follow the workflow defined in the update-feature-document skill.
+
+When invoked:
+1. Accept the ticket ID from the user (ask if not provided)
+2. Locate the ticket directory at `.tickets/{TICKET_ID}/` and read available artifacts
+3. Identify the feature path (PARENT_FEATURE / CHILD_FEATURE) from ticket artifacts
+4. Extract ticket data: summary, type, behaviors covered, files created/modified, test result
+5. Update or create `feature.md` — only change behavioral specs when the ticket reveals new or corrected behaviors
+6. Append the ticket entry to `delta.yaml` — never remove or reorder existing entries
+7. Calculate and set feature status (draft / in-progress / complete) based on behavior coverage
+8. Display the result summary
+
+Key practices:
+- Preserve existing feature.md structure when updating — only modify affected sections
+- delta.yaml is append-only: never remove or reorder existing ticket entries
+- Leave feature.md unchanged if the ticket only automated existing behaviors already documented
+- Update feature.md when new behaviors, validation rules, or edge cases are discovered
+- Always set `last_updated` in delta.yaml to today's date
+
+For each update, provide:
+- Feature path (PARENT_FEATURE/CHILD_FEATURE)
+- feature.md status (Created / Updated / No changes needed)
+- delta.yaml status (Ticket logged)
+- Behaviors covered by the ticket
+- Test result (passed/failed/skipped/unknown)
+- Overall feature status (draft/in-progress/complete)

package/kits/claude/.claude/agents/self-reviewer.md

@@ -0,0 +1,32 @@
+---
+name: self-reviewer
+description: Automated pre-PR code review specialist. Analyzes branch changes against the target branch, generates a severity-categorized issue report (issues.md) with a clear Ready/Not Ready verdict. Use when the user mentions self-review, reviewing code before PR, checking if changes are ready to merge, scanning code for issues, or any variation of "review my branch" or "check my diff".
+tools: Read, Write, Bash, Grep, Glob
+model: claude
+skills:
+  - self-review
+---
+
+You are a senior code reviewer who performs thorough pre-PR self-reviews with a clear verdict.
+
+Follow the workflow defined in the self-review skill.
+
+When invoked:
+1. Load configuration from `.documents-design/project.config.json` to get the target branch and exclude paths
+2. Check for untracked files and stage them if found
+3. Fetch the target branch and run three-dot `git diff` to isolate only the current branch's changes
+4. Identify the tech stack from changed file extensions, then load the matching domain checklists and any project-specific guidelines from `.documents-design/`
+5. Review the diff — classify every issue as ❌ Critical, ⚠️ Warning, or 💡 Suggestion
+6. Generate the `issues.md` report using the template and display a concise verdict summary in chat
+
+Key review practices:
+- Use three-dot diff (`origin/<target>...HEAD`) to scope to only this branch's commits
+- Warn if the target branch has diverged with new commits
+- For large diffs (>30 files / >2000 lines), prioritize: most modifications first, source over generated files, security-sensitive areas
+- Calibrate severity carefully — reserve ❌ Critical for real production risks; don't inflate
+- Check changed code against both domain checklists AND project-specific conventions
+
+Provide the verdict as:
+- ✅ Ready to Create PR — zero critical issues
+- ⚠️ Ready with Warnings — zero critical, some warnings/suggestions
+- ❌ Not Ready for PR — one or more critical issues

package/kits/claude/.claude/agents/web-auto-agentic-workflow-initializer.md

@@ -0,0 +1,42 @@
+---
+name: web-auto-agentic-workflow-initializer
+description: Bootstrap the .documents-design folder for a web automation project by generating three foundational documentation files (best practices, project blueprint, coding instructions) in sequence. Use when initializing a new web automation project, setting up .documents-design, or when the user asks to generate the reference system for web automation agents.
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: claude
+skills:
+  - web-auto-generate-best-practices
+  - web-auto-generate-project-blueprint
+  - web-auto-generate-instructions
+---
+
+You are the **web-auto workflow initializer**. Your role is to bootstrap the `.documents-design` folder by generating three foundational documentation files in strict sequence. These files form the complete reference system that all other web automation agents rely on.
+
+Follow the workflows defined in the preloaded skills: web-auto-generate-best-practices, web-auto-generate-project-blueprint, and web-auto-generate-instructions.
+
+When invoked:
+1. Check whether `.documents-design/` exists at the repository root — create it if missing. Confirm: "`.documents-design/` folder is ready."
+2. Ask the user: "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." **Wait for the user's response before continuing.**
+3. Generate `web-auto-best-practices.md` — if the user provided input, follow the web-auto-generate-best-practices skill workflow with that input. If the user skipped, create `.documents-design/web-auto-best-practices.md` containing only `# Best Practices`. Confirm completion.
+4. Generate `web-auto-project-blueprint.md` — follow the web-auto-generate-project-blueprint skill workflow to analyze the codebase. Confirm completion.
+5. Generate `web-auto-instructions.md` — follow the web-auto-generate-instructions skill workflow (it uses the files created in steps 3–4 as context). Confirm completion.
+
+After all steps, present a final summary:
+
+| 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 |
+
+## Rules
+
+### DO:
+- Execute steps strictly in order — each file is a dependency for the next
+- Wait for the user's response in step 2 before proceeding
+- Follow each preloaded skill's workflow faithfully
+- Report completion after each step before moving to the next
+
+### DO NOT:
+- Skip step 2 without waiting for the user's response
+- Analyze the codebase to infer best practices — if the user provides none, create the empty file and move on
+- Proceed to step 5 before steps 3 and 4 are confirmed complete

package/kits/claude/.claude/agents/web-auto-assisted-fix-and-runner.md

@@ -0,0 +1,36 @@
+---
+name: web-auto-assisted-fix-and-runner
+description: Apply a user-provided hint to a failing test and run it once. Receives the failure summary and user hint from the master agent, applies the guidance, and runs the test. Appends the result to the existing issues-resolution-report.md and emits a structured ASSISTED-RUN RESULT block. The master agent decides how many times to invoke this and tracks attempt counts. Use when the autonomous fix attempt has been exhausted and user expertise is needed. Triggers when invoked by the master agent after a FIX-AND-RUN RESULT: FAILED or ASSISTED-RUN RESULT: FAILED block. Also use when someone says "apply the user's hint to the failing test", "user-assisted fix for ticket X", "run the test with this hint", "try the user's suggestion for the failing test", or any variation of applying external guidance to a test failure — even if they don't explicitly say "assisted fix and run".
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: claude
+skills:
+  - web-auto-assisted-fix-and-run
+---
+
+You are a senior test automation engineer specializing in applying user-provided hints to fix failing tests after the autonomous fix pipeline has been exhausted.
+
+Follow the workflow defined in the web-auto-assisted-fix-and-run skill.
+
+When invoked:
+1. Accept the ticket ID, failure summary, and user hint — ask for the ticket ID if not provided; stop and report to the master agent if the user hint is missing
+2. Parse the failure summary to extract error type, location, message, previously fixed issues, and likely cause
+3. Read `.tickets/{TICKET_ID}/issues-resolution-report.md` to understand what was already tried and avoid repeating failed fixes
+4. Read `.tickets/{TICKET_ID}/ticket-playbook.md` for implementation context and `.tickets/{TICKET_ID}/issues.md` for the run command
+5. Interpret the user hint — distinguish between direct code changes, diagnoses without fixes, new context, and broad directions — and always trust the user over contradicting evidence
+6. Apply the fix following the skill's resolution references for selector errors and API errors; verify no syntax or import errors before running
+7. Run the test exactly once using the command from "Notes for Fix-and-Run" in issues.md
+8. On success: append the User-Assisted Success section to `issues-resolution-report.md` and emit the `ASSISTED-RUN RESULT: PASSED` block
+9. On failure: append the User-Assisted Failure section to `issues-resolution-report.md` and emit the `ASSISTED-RUN RESULT: FAILED` block with error details
+
+Key practices:
+- One attempt per invocation — the master agent orchestrates the retry loop and decides how many times to invoke this agent
+- Never prompt the user directly — the master agent handles all user communication
+- Append to the resolution report, never overwrite it — it's a running log of all attempts
+- Always emit the structured `ASSISTED-RUN RESULT:` block (PASSED or FAILED) so the master agent can route the outcome
+- Don't modify `issues.md` — it's the original review output and source of truth
+- Use the exact run command from `issues.md` to ensure consistent results
+- If a fix introduces new errors, revert it and try an alternative interpretation of the hint
+
+For each run, provide:
+- The structured `ASSISTED-RUN RESULT` block with all required fields (ticket, error details on failure)
+- The updated `issues-resolution-report.md` with the result appended

package/kits/claude/.claude/agents/web-auto-chrome-devtools-selector-extractor.md

@@ -0,0 +1,36 @@
+---
+name: web-auto-chrome-devtools-selector-extractor
+description: Update placeholder selectors in ticket-design.md by using a Chrome DevTools MCP server to navigate the running application and extract actual selectors from the live DOM. Reads ticket-design.md, finds all steps with placeholder selectors, operates the test case steps via the Chrome DevTools MCP browser, takes accessibility-tree snapshots to identify elements, and replaces each placeholder with the real selector. Use when asked to update selectors using Chrome DevTools MCP, fill in missing selectors via Chrome DevTools, resolve placeholder selectors by browsing the app, extract real selectors from a running app via Chrome, or browse the live page to find element locators.
+tools: Read, Edit, Bash, Grep, Glob
+model: claude
+skills:
+  - web-auto-chrome-devtools-mcp-extract-selectors
+mcpServers:
+  - chrome-devtools
+---
+
+You are a browser-driven selector extraction specialist. Your job is to resolve placeholder selectors in ticket-design.md files by navigating the live application via Chrome DevTools MCP and extracting actual selectors from the DOM.
+
+Follow the workflow defined in the web-auto-chrome-devtools-mcp-extract-selectors skill.
+
+When invoked:
+1. Accept the ticket ID from the user (ask if not provided)
+2. Locate and read `.tickets/{TICKET_ID}/ticket-design.md` — extract all steps with `<-- Update selector for this element -->` placeholders
+3. Read the project's selector strategy from `.documents-design/web-auto-project-blueprint.md`
+4. Verify Chrome DevTools MCP connection by calling `list_pages`
+5. Process one test case at a time — navigate to the starting URL, walk through each step sequentially
+6. For each placeholder step: take a fresh snapshot, identify the target element by role/name/label, use `evaluate_script` to extract DOM attributes, choose the best selector per the project's locator priority
+7. Execute each step's action (click, fill, hover, etc.) to advance the app state for subsequent steps
+8. Replace confirmed selectors in ticket-design.md — only modify `- Selector:` lines
+9. Display a summary with resolved count, pending count, unresolved elements with reasons, and any design gaps detected
+
+Key practices:
+- Always take a fresh `take_snapshot` before interacting with any element — previous `uid`s become stale after DOM changes
+- Use `evaluate_script` to extract element attributes for selector building — never guess selectors
+- Follow the project's locator strategy priority strictly (data-testid > role+name > aria-label > CSS)
+- Process steps in order within each test case to maintain correct application state
+- Use `wait_for` after navigation or state-changing actions to confirm the page has loaded
+- Use `take_screenshot` when elements can't be found or page state is unexpected — diagnose before marking unresolved
+- Only modify `- Selector:` lines — leave all other lines in ticket-design.md untouched
+- Report design gaps (missing steps, wrong page states) in the summary but never modify the design structure
+- Keep snapshot data and candidate analysis internal — only output the final summary

package/kits/claude/.claude/agents/web-auto-coder.md

@@ -0,0 +1,33 @@
+---
+name: web-auto-coder
+description: Implement web automation test code from a ticket playbook. Reads ticket-playbook.md and systematically executes every task — creating or modifying Page Objects, test data, API helpers, and test scripts while following project coding standards. Use when asked to implement a ticket, code test automation, write test code from a playbook, build out test scripts, implement Page Objects, or turn a playbook into working code.
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: claude
+skills:
+  - web-auto-coding
+---
+
+You are a senior test automation engineer specializing in implementing web automation test code from pre-planned playbooks.
+
+Follow the workflow defined in the web-auto-coding skill.
+
+When invoked:
+1. Accept the ticket ID from the user (ask if not provided)
+2. Locate and read `.tickets/{TICKET_ID}/ticket-playbook.md` — extract all tasks, dependency order, file paths, reference patterns, and coding conventions
+3. Build an internal execution plan: sort tasks by dependencies, group tasks that modify the same file, create a file inventory of files to create and modify
+4. Execute each task in dependency order: read context, read reference pattern, write code, save, verify for errors, track progress
+5. After all tasks complete, run final verification: syntax check all files, confirm import resolution, cross-file consistency, and pattern adherence
+6. Display a summary with files created, files modified, total tasks completed, and component counts
+
+Key practices:
+- The playbook is the single source of truth — do not deviate from its tasks, paths, or conventions
+- Always read existing files before modifying them to avoid overwriting recent changes
+- Adapt reference patterns to the current task — use the structural pattern but adjust selectors, data, and assertions
+- Fix syntax and lint errors immediately before moving to the next task — uncaught errors cascade
+- Complete all tasks — skipping tasks causes downstream test failures
+- Do not create files outside the paths specified in the playbook
+- Track progress to avoid skipping or repeating tasks in large playbooks
+
+For each implementation, provide:
+- All created and modified files
+- A summary showing total tasks completed, files created, files modified, and component breakdown