Initial commit

skills/adw-bootstrap/reference/scaled/adw_modules/beads_integration.py

@@ -0,0 +1,292 @@
+"""Beads Integration Module - AI Developer Workflow (ADW)
+
+This module provides beads issue management as an alternative to GitHub issues.
+Allows ADW workflows to work with local beads tasks for offline development.
+"""
+
+import os
+import subprocess
+import json
+from typing import Tuple, Optional
+from adw_modules.data_types import GitHubIssue
+from datetime import datetime
+
+
+def get_workspace_root() -> str:
+    """Get workspace root for beads operations."""
+    # Assume workspace root is the parent of adws directory
+    return os.path.dirname(
+        os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    )
+
+
+def fetch_beads_issue(issue_id: str) -> Tuple[Optional[GitHubIssue], Optional[str]]:
+    """Fetch beads issue and convert to GitHubIssue format.
+
+    Args:
+        issue_id: The beads issue ID
+
+    Returns:
+        Tuple of (GitHubIssue, error_message)
+    """
+    workspace_root = get_workspace_root()
+
+    # Use bd show to get issue details
+    cmd = ["bd", "show", issue_id]
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            cwd=workspace_root,
+        )
+
+        if result.returncode != 0:
+            return None, f"Failed to fetch beads issue: {result.stderr}"
+
+        # Parse the output (bd show returns human-readable format)
+        # Format is:
+        # poc-fjw: Token Infrastructure & Redis Setup
+        # Status: in_progress
+        # Priority: P0
+        # Type: feature
+        # ...
+        # Description:
+        # <description text>
+        output = result.stdout
+
+        # Extract title, description, status from output
+        title = None
+        description = None
+        status = "open"
+        issue_type = "task"
+        in_description = False
+        description_lines = []
+
+        for line in output.split("\n"):
+            stripped = line.strip()
+            
+            # Skip empty lines
+            if not stripped:
+                continue
+            
+            # First line has format: "poc-fjw: Token Infrastructure & Redis Setup"
+            if not title and ":" in line and not line.startswith(" "):
+                parts = line.split(":", 1)
+                if len(parts) == 2 and parts[0].strip() == issue_id:
+                    title = parts[1].strip()
+                    continue
+            
+            # Status line
+            if stripped.startswith("Status:"):
+                status = stripped.split(":", 1)[1].strip()
+                in_description = False
+            # Type line
+            elif stripped.startswith("Type:"):
+                issue_type = stripped.split(":", 1)[1].strip()
+                in_description = False
+            # Description section
+            elif stripped.startswith("Description:"):
+                in_description = True
+                # Check if description is on same line
+                desc_text = stripped.split(":", 1)[1].strip()
+                if desc_text:
+                    description_lines.append(desc_text)
+            elif in_description and stripped and not stripped.startswith("Dependents"):
+                description_lines.append(stripped)
+            elif stripped.startswith("Dependents") or stripped.startswith("Dependencies"):
+                in_description = False
+
+        # Combine description lines
+        if description_lines:
+            description = "\n".join(description_lines)
+
+        if not title:
+            return None, "Could not parse issue title from beads output"
+
+        # Convert to GitHubIssue format for compatibility
+        # Use the issue_id as the number (extract numeric part if present)
+        try:
+            # Try to extract number from ID like "poc-123"
+            number_str = issue_id.split("-")[-1]
+            if number_str.isdigit():
+                number = int(number_str)
+            else:
+                # Use hash of ID as fallback
+                number = hash(issue_id) % 10000
+        except:
+            number = hash(issue_id) % 10000
+
+        # Create GitHubIssue-compatible object
+        issue = GitHubIssue(
+            number=number,
+            title=title or "Untitled Task",
+            body=description or "",
+            state=status,
+            author={"login": "beads"},
+            assignees=[],
+            labels=[{"name": issue_type}],
+            milestone=None,
+            comments=[],
+            createdAt=datetime.now().isoformat(),
+            updatedAt=datetime.now().isoformat(),
+            closedAt=None,
+            url=f"beads://{issue_id}",
+        )
+
+        return issue, None
+
+    except FileNotFoundError:
+        return None, "bd command not found. Is beads installed?"
+    except Exception as e:
+        return None, f"Error fetching beads issue: {str(e)}"
+
+
+def update_beads_status(issue_id: str, status: str) -> Tuple[bool, Optional[str]]:
+    """Update beads issue status.
+
+    Args:
+        issue_id: The beads issue ID
+        status: New status (open, in_progress, blocked, closed)
+
+    Returns:
+        Tuple of (success, error_message)
+    """
+    workspace_root = get_workspace_root()
+
+    cmd = ["bd", "update", issue_id, "--status", status]
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            cwd=workspace_root,
+        )
+
+        if result.returncode != 0:
+            return False, f"Failed to update beads status: {result.stderr}"
+
+        return True, None
+
+    except FileNotFoundError:
+        return False, "bd command not found. Is beads installed?"
+    except Exception as e:
+        return False, f"Error updating beads status: {str(e)}"
+
+
+def close_beads_issue(issue_id: str, reason: str = "Completed via ADW workflow") -> Tuple[bool, Optional[str]]:
+    """Close a beads issue.
+
+    Args:
+        issue_id: The beads issue ID
+        reason: Reason for closing
+
+    Returns:
+        Tuple of (success, error_message)
+    """
+    workspace_root = get_workspace_root()
+
+    cmd = ["bd", "close", issue_id, "--reason", reason]
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            cwd=workspace_root,
+        )
+
+        if result.returncode != 0:
+            return False, f"Failed to close beads issue: {result.stderr}"
+
+        return True, None
+
+    except FileNotFoundError:
+        return False, "bd command not found. Is beads installed?"
+    except Exception as e:
+        return False, f"Error closing beads issue: {str(e)}"
+
+
+def get_ready_beads_tasks(limit: int = 10) -> Tuple[Optional[list], Optional[str]]:
+    """Get ready beads tasks (no blockers).
+
+    Args:
+        limit: Maximum number of tasks to return
+
+    Returns:
+        Tuple of (task_list, error_message)
+    """
+    workspace_root = get_workspace_root()
+
+    cmd = ["bd", "ready", "--limit", str(limit)]
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            cwd=workspace_root,
+        )
+
+        if result.returncode != 0:
+            return None, f"Failed to get ready tasks: {result.stderr}"
+
+        # Parse output to extract task IDs
+        # bd ready returns format like:
+        # 📋 Ready work (1 issues with no blockers):
+        #
+        # 1. [P0] poc-pw3: Credit Consumption & Atomicity
+        #    Assignee: La Boeuf
+        tasks = []
+        
+        # Check if there are no ready tasks
+        if "No ready work found" in result.stdout or "(0 issues" in result.stdout:
+            return [], None
+        
+        for line in result.stdout.split("\n"):
+            line = line.strip()
+            # Skip empty lines, headers, and assignee lines
+            if not line or line.startswith("📋") or line.startswith("Assignee:"):
+                continue
+            
+            # Look for lines with format: "1. [P0] poc-pw3: Title"
+            # Extract the task ID (poc-pw3 in this case)
+            if ". [P" in line or ". [" in line:
+                # Split on ": " to get the ID part
+                parts = line.split(":")
+                if len(parts) >= 2:
+                    # Get the part before the colon, then extract the ID
+                    # Format: "1. [P0] poc-pw3"
+                    id_part = parts[0].strip()
+                    # Split by spaces and get the last token (the ID)
+                    tokens = id_part.split()
+                    if tokens:
+                        task_id = tokens[-1]
+                        # Verify it looks like a beads ID (has hyphen)
+                        if "-" in task_id:
+                            tasks.append(task_id)
+
+        return tasks, None
+
+    except FileNotFoundError:
+        return None, "bd command not found. Is beads installed?"
+    except Exception as e:
+        return None, f"Error getting ready tasks: {str(e)}"
+
+
+def is_beads_issue(issue_identifier: str) -> bool:
+    """Check if an issue identifier is a beads issue.
+
+    Beads issues have format like: poc-abc, feat-123, etc.
+    GitHub issues are just numbers.
+
+    Args:
+        issue_identifier: The issue identifier
+
+    Returns:
+        True if it's a beads issue, False otherwise
+    """
+    # Beads issues contain a hyphen
+    return "-" in issue_identifier and not issue_identifier.isdigit()

skills/adw-bootstrap/reference/scaled/adw_modules/git_ops.py

@@ -0,0 +1,316 @@
+"""Git operations for ADW composable architecture.
+
+Provides centralized git operations that build on top of github.py module.
+"""
+
+import subprocess
+import json
+import logging
+from typing import Optional, Tuple
+
+# Import GitHub functions from existing module
+from adw_modules.github import get_repo_url, extract_repo_path, make_issue_comment
+
+
+def get_current_branch(cwd: Optional[str] = None) -> str:
+    """Get current git branch name."""
+    result = subprocess.run(
+        ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+        capture_output=True,
+        text=True,
+        cwd=cwd,
+    )
+    return result.stdout.strip()
+
+
+def push_branch(
+    branch_name: str, cwd: Optional[str] = None
+) -> Tuple[bool, Optional[str]]:
+    """Push current branch to remote. Returns (success, error_message)."""
+    result = subprocess.run(
+        ["git", "push", "-u", "origin", branch_name],
+        capture_output=True,
+        text=True,
+        cwd=cwd,
+    )
+    if result.returncode != 0:
+        return False, result.stderr
+    return True, None
+
+
+def check_pr_exists(branch_name: str) -> Optional[str]:
+    """Check if PR exists for branch. Returns PR URL if exists."""
+    # Use github.py functions to get repo info
+    try:
+        repo_url = get_repo_url()
+        repo_path = extract_repo_path(repo_url)
+    except Exception as e:
+        return None
+
+    result = subprocess.run(
+        [
+            "gh",
+            "pr",
+            "list",
+            "--repo",
+            repo_path,
+            "--head",
+            branch_name,
+            "--json",
+            "url",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode == 0:
+        prs = json.loads(result.stdout)
+        if prs:
+            return prs[0]["url"]
+    return None
+
+
+def create_branch(
+    branch_name: str, cwd: Optional[str] = None
+) -> Tuple[bool, Optional[str]]:
+    """Create and checkout a new branch. Returns (success, error_message)."""
+    # Create branch
+    result = subprocess.run(
+        ["git", "checkout", "-b", branch_name], capture_output=True, text=True, cwd=cwd
+    )
+    if result.returncode != 0:
+        # Check if error is because branch already exists
+        if "already exists" in result.stderr:
+            # Try to checkout existing branch
+            result = subprocess.run(
+                ["git", "checkout", branch_name],
+                capture_output=True,
+                text=True,
+                cwd=cwd,
+            )
+            if result.returncode != 0:
+                return False, result.stderr
+            return True, None
+        return False, result.stderr
+    return True, None
+
+
+def commit_changes(
+    message: str, cwd: Optional[str] = None
+) -> Tuple[bool, Optional[str]]:
+    """Stage all changes and commit. Returns (success, error_message)."""
+    # Check if there are changes to commit
+    result = subprocess.run(
+        ["git", "status", "--porcelain"], capture_output=True, text=True, cwd=cwd
+    )
+    if not result.stdout.strip():
+        return True, None  # No changes to commit
+
+    # Stage all changes
+    result = subprocess.run(
+        ["git", "add", "-A"], capture_output=True, text=True, cwd=cwd
+    )
+    if result.returncode != 0:
+        return False, result.stderr
+
+    # Commit
+    result = subprocess.run(
+        ["git", "commit", "-m", message], capture_output=True, text=True, cwd=cwd
+    )
+    if result.returncode != 0:
+        return False, result.stderr
+    return True, None
+
+
+def get_pr_number(branch_name: str) -> Optional[str]:
+    """Get PR number for a branch. Returns PR number if exists."""
+    # Use github.py functions to get repo info
+    try:
+        repo_url = get_repo_url()
+        repo_path = extract_repo_path(repo_url)
+    except Exception as e:
+        return None
+
+    result = subprocess.run(
+        [
+            "gh",
+            "pr",
+            "list",
+            "--repo",
+            repo_path,
+            "--head",
+            branch_name,
+            "--json",
+            "number",
+            "--limit",
+            "1",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode == 0:
+        prs = json.loads(result.stdout)
+        if prs:
+            return str(prs[0]["number"])
+    return None
+
+
+def approve_pr(pr_number: str, logger: logging.Logger) -> Tuple[bool, Optional[str]]:
+    """Approve a PR. Returns (success, error_message)."""
+    try:
+        repo_url = get_repo_url()
+        repo_path = extract_repo_path(repo_url)
+    except Exception as e:
+        return False, f"Failed to get repo info: {e}"
+
+    result = subprocess.run(
+        [
+            "gh",
+            "pr",
+            "review",
+            pr_number,
+            "--repo",
+            repo_path,
+            "--approve",
+            "--body",
+            "ADW Ship workflow approved this PR after validating all state fields.",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        return False, result.stderr
+
+    logger.info(f"Approved PR #{pr_number}")
+    return True, None
+
+
+def merge_pr(
+    pr_number: str, logger: logging.Logger, merge_method: str = "squash"
+) -> Tuple[bool, Optional[str]]:
+    """Merge a PR. Returns (success, error_message).
+
+    Args:
+        pr_number: The PR number to merge
+        logger: Logger instance
+        merge_method: One of 'merge', 'squash', 'rebase' (default: 'squash')
+    """
+    try:
+        repo_url = get_repo_url()
+        repo_path = extract_repo_path(repo_url)
+    except Exception as e:
+        return False, f"Failed to get repo info: {e}"
+
+    # First check if PR is mergeable
+    result = subprocess.run(
+        [
+            "gh",
+            "pr",
+            "view",
+            pr_number,
+            "--repo",
+            repo_path,
+            "--json",
+            "mergeable,mergeStateStatus",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        return False, f"Failed to check PR status: {result.stderr}"
+
+    pr_status = json.loads(result.stdout)
+    if pr_status.get("mergeable") != "MERGEABLE":
+        return (
+            False,
+            f"PR is not mergeable. Status: {pr_status.get('mergeStateStatus', 'unknown')}",
+        )
+
+    # Merge the PR
+    merge_cmd = [
+        "gh",
+        "pr",
+        "merge",
+        pr_number,
+        "--repo",
+        repo_path,
+        f"--{merge_method}",
+    ]
+
+    # Add auto-merge body
+    merge_cmd.extend(
+        ["--body", "Merged by ADW Ship workflow after successful validation."]
+    )
+
+    result = subprocess.run(merge_cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        return False, result.stderr
+
+    logger.info(f"Merged PR #{pr_number} using {merge_method} method")
+    return True, None
+
+
+def finalize_git_operations(
+    state: "ADWState", logger: logging.Logger, cwd: Optional[str] = None
+) -> None:
+    """Standard git finalization: push branch and create/update PR."""
+    branch_name = state.get("branch_name")
+    if not branch_name:
+        # Fallback: use current git branch if not main
+        current_branch = get_current_branch(cwd=cwd)
+        if current_branch and current_branch != "main":
+            logger.warning(
+                f"No branch name in state, using current branch: {current_branch}"
+            )
+            branch_name = current_branch
+        else:
+            logger.error(
+                "No branch name in state and current branch is main, skipping git operations"
+            )
+            return
+
+    # Always push
+    success, error = push_branch(branch_name, cwd=cwd)
+    if not success:
+        logger.error(f"Failed to push branch: {error}")
+        return
+
+    logger.info(f"Pushed branch: {branch_name}")
+
+    # Handle PR
+    pr_url = check_pr_exists(branch_name)
+    issue_number = state.get("issue_number")
+    adw_id = state.get("adw_id")
+
+    if pr_url:
+        logger.info(f"Found existing PR: {pr_url}")
+        # Post PR link for easy reference
+        if issue_number and adw_id:
+            make_issue_comment(issue_number, f"{adw_id}_ops: ✅ Pull request: {pr_url}")
+    else:
+        # Create new PR - fetch issue data first
+        if issue_number:
+            try:
+                repo_url = get_repo_url()
+                repo_path = extract_repo_path(repo_url)
+                from adw_modules.github import fetch_issue
+
+                issue = fetch_issue(issue_number, repo_path)
+
+                from adw_modules.workflow_ops import create_pull_request
+
+                pr_url, error = create_pull_request(branch_name, issue, state, logger, cwd)
+            except Exception as e:
+                logger.error(f"Failed to fetch issue for PR creation: {e}")
+                pr_url, error = None, str(e)
+        else:
+            pr_url, error = None, "No issue number in state"
+
+        if pr_url:
+            logger.info(f"Created PR: {pr_url}")
+            # Post new PR link
+            if issue_number and adw_id:
+                make_issue_comment(
+                    issue_number, f"{adw_id}_ops: ✅ Pull request created: {pr_url}"
+                )
+        else:
+            logger.error(f"Failed to create PR: {error}")

skills/adw-bootstrap/reference/scaled/adw_modules/github.py

@@ -0,0 +1,312 @@
+#!/usr/bin/env -S uv run
+# /// script
+# dependencies = ["python-dotenv", "pydantic"]
+# ///
+
+"""
+GitHub Operations Module - AI Developer Workflow (ADW)
+
+This module contains all GitHub-related operations including:
+- Issue fetching and manipulation
+- Comment posting
+- Repository path extraction
+- Issue status management
+"""
+
+import subprocess
+import sys
+import os
+import json
+from typing import Dict, List, Optional
+from .data_types import GitHubIssue, GitHubIssueListItem, GitHubComment
+
+# Bot identifier to prevent webhook loops and filter bot comments
+ADW_BOT_IDENTIFIER = "[ADW-AGENTS]"
+
+
+def get_github_env() -> Optional[dict]:
+    """Get environment with GitHub token set up. Returns None if no GITHUB_PAT.
+    
+    Subprocess env behavior:
+    - env=None → Inherits parent's environment (default)
+    - env={} → Empty environment (no variables)
+    - env=custom_dict → Only uses specified variables
+    
+    So this will work with gh authentication:
+    # These are equivalent:
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    result = subprocess.run(cmd, capture_output=True, text=True, env=None)
+    
+    But this will NOT work (no PATH, no auth):
+    result = subprocess.run(cmd, capture_output=True, text=True, env={})
+    """
+    github_pat = os.getenv("GITHUB_PAT")
+    if not github_pat:
+        return None
+    
+    # Only create minimal env with GitHub token
+    env = {
+        "GH_TOKEN": github_pat,
+        "PATH": os.environ.get("PATH", ""),
+    }
+    return env
+
+
+def get_repo_url() -> str:
+    """Get GitHub repository URL from git remote."""
+    try:
+        result = subprocess.run(
+            ["git", "remote", "get-url", "origin"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        return result.stdout.strip()
+    except subprocess.CalledProcessError:
+        raise ValueError(
+            "No git remote 'origin' found. Please ensure you're in a git repository with a remote."
+        )
+    except FileNotFoundError:
+        raise ValueError("git command not found. Please ensure git is installed.")
+
+
+def extract_repo_path(github_url: str) -> str:
+    """Extract owner/repo from GitHub URL."""
+    # Handle both https://github.com/owner/repo and https://github.com/owner/repo.git
+    return github_url.replace("https://github.com/", "").replace(".git", "")
+
+
+def fetch_issue(issue_number: str, repo_path: str) -> GitHubIssue:
+    """Fetch GitHub issue using gh CLI and return typed model."""
+    # Use JSON output for structured data
+    cmd = [
+        "gh",
+        "issue",
+        "view",
+        issue_number,
+        "-R",
+        repo_path,
+        "--json",
+        "number,title,body,state,author,assignees,labels,milestone,comments,createdAt,updatedAt,closedAt,url",
+    ]
+
+    # Set up environment with GitHub token if available
+    env = get_github_env()
+
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, env=env)
+
+        if result.returncode == 0:
+            # Parse JSON response into Pydantic model
+            issue_data = json.loads(result.stdout)
+            issue = GitHubIssue(**issue_data)
+
+            return issue
+        else:
+            print(result.stderr, file=sys.stderr)
+            sys.exit(result.returncode)
+    except FileNotFoundError:
+        print("Error: GitHub CLI (gh) is not installed.", file=sys.stderr)
+        print("\nTo install gh:", file=sys.stderr)
+        print("  - macOS: brew install gh", file=sys.stderr)
+        print(
+            "  - Linux: See https://github.com/cli/cli#installation",
+            file=sys.stderr,
+        )
+        print(
+            "  - Windows: See https://github.com/cli/cli#installation", file=sys.stderr
+        )
+        print("\nAfter installation, authenticate with: gh auth login", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error parsing issue data: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def make_issue_comment(issue_id: str, comment: str) -> None:
+    """Post a comment to a GitHub issue using gh CLI."""
+    # Get repo information from git remote
+    github_repo_url = get_repo_url()
+    repo_path = extract_repo_path(github_repo_url)
+
+    # Ensure comment has ADW_BOT_IDENTIFIER to prevent webhook loops
+    if not comment.startswith(ADW_BOT_IDENTIFIER):
+        comment = f"{ADW_BOT_IDENTIFIER} {comment}"
+
+    # Build command
+    cmd = [
+        "gh",
+        "issue",
+        "comment",
+        issue_id,
+        "-R",
+        repo_path,
+        "--body",
+        comment,
+    ]
+
+    # Set up environment with GitHub token if available
+    env = get_github_env()
+
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, env=env)
+
+        if result.returncode == 0:
+            print(f"Successfully posted comment to issue #{issue_id}")
+        else:
+            print(f"Error posting comment: {result.stderr}", file=sys.stderr)
+            raise RuntimeError(f"Failed to post comment: {result.stderr}")
+    except Exception as e:
+        print(f"Error posting comment: {e}", file=sys.stderr)
+        raise
+
+
+def mark_issue_in_progress(issue_id: str) -> None:
+    """Mark issue as in progress by adding label and comment."""
+    # Get repo information from git remote
+    github_repo_url = get_repo_url()
+    repo_path = extract_repo_path(github_repo_url)
+
+    # Add "in_progress" label
+    cmd = [
+        "gh",
+        "issue",
+        "edit",
+        issue_id,
+        "-R",
+        repo_path,
+        "--add-label",
+        "in_progress",
+    ]
+
+    # Set up environment with GitHub token if available
+    env = get_github_env()
+
+    # Try to add label (may fail if label doesn't exist)
+    result = subprocess.run(cmd, capture_output=True, text=True, env=env)
+    if result.returncode != 0:
+        print(f"Note: Could not add 'in_progress' label: {result.stderr}")
+
+    # Post comment indicating work has started
+    # make_issue_comment(issue_id, "🚧 ADW is working on this issue...")
+
+    # Assign to self (optional)
+    cmd = [
+        "gh",
+        "issue",
+        "edit",
+        issue_id,
+        "-R",
+        repo_path,
+        "--add-assignee",
+        "@me",
+    ]
+    result = subprocess.run(cmd, capture_output=True, text=True, env=env)
+    if result.returncode == 0:
+        print(f"Assigned issue #{issue_id} to self")
+
+
+def fetch_open_issues(repo_path: str) -> List[GitHubIssueListItem]:
+    """Fetch all open issues from the GitHub repository."""
+    try:
+        cmd = [
+            "gh",
+            "issue",
+            "list",
+            "--repo",
+            repo_path,
+            "--state",
+            "open",
+            "--json",
+            "number,title,body,labels,createdAt,updatedAt",
+            "--limit",
+            "1000",
+        ]
+
+        # Set up environment with GitHub token if available
+        env = get_github_env()
+
+        # DEBUG level - not printing command
+        result = subprocess.run(
+            cmd, capture_output=True, text=True, check=True, env=env
+        )
+
+        issues_data = json.loads(result.stdout)
+        issues = [GitHubIssueListItem(**issue_data) for issue_data in issues_data]
+        print(f"Fetched {len(issues)} open issues")
+        return issues
+
+    except subprocess.CalledProcessError as e:
+        print(f"ERROR: Failed to fetch issues: {e.stderr}", file=sys.stderr)
+        return []
+    except json.JSONDecodeError as e:
+        print(f"ERROR: Failed to parse issues JSON: {e}", file=sys.stderr)
+        return []
+
+
+def fetch_issue_comments(repo_path: str, issue_number: int) -> List[Dict]:
+    """Fetch all comments for a specific issue."""
+    try:
+        cmd = [
+            "gh",
+            "issue",
+            "view",
+            str(issue_number),
+            "--repo",
+            repo_path,
+            "--json",
+            "comments",
+        ]
+
+        # Set up environment with GitHub token if available
+        env = get_github_env()
+
+        result = subprocess.run(
+            cmd, capture_output=True, text=True, check=True, env=env
+        )
+        data = json.loads(result.stdout)
+        comments = data.get("comments", [])
+
+        # Sort comments by creation time
+        comments.sort(key=lambda c: c.get("createdAt", ""))
+
+        # DEBUG level - not printing
+        return comments
+
+    except subprocess.CalledProcessError as e:
+        print(
+            f"ERROR: Failed to fetch comments for issue #{issue_number}: {e.stderr}",
+            file=sys.stderr,
+        )
+        return []
+    except json.JSONDecodeError as e:
+        print(
+            f"ERROR: Failed to parse comments JSON for issue #{issue_number}: {e}",
+            file=sys.stderr,
+        )
+        return []
+
+
+def find_keyword_from_comment(keyword: str, issue: GitHubIssue) -> Optional[GitHubComment]:
+    """Find the latest comment containing a specific keyword.
+    
+    Args:
+        keyword: The keyword to search for in comments
+        issue: The GitHub issue containing comments
+        
+    Returns:
+        The latest GitHubComment containing the keyword, or None if not found
+    """
+    # Sort comments by created_at date (newest first)
+    sorted_comments = sorted(issue.comments, key=lambda c: c.created_at, reverse=True)
+    
+    # Search through sorted comments (newest first)
+    for comment in sorted_comments:
+        # Skip ADW bot comments to prevent loops
+        if ADW_BOT_IDENTIFIER in comment.body:
+            continue
+            
+        if keyword in comment.body:
+            return comment
+    
+    return None

skills/adw-bootstrap/reference/scaled/adw_modules/state.py

@@ -0,0 +1,172 @@
+"""State management for ADW composable architecture.
+
+Provides persistent state management via file storage and
+transient state passing between scripts via stdin/stdout.
+"""
+
+import json
+import os
+import sys
+import logging
+from typing import Dict, Any, Optional
+from adw_modules.data_types import ADWStateData
+
+
+class ADWState:
+    """Container for ADW workflow state with file persistence."""
+
+    STATE_FILENAME = "adw_state.json"
+
+    def __init__(self, adw_id: str):
+        """Initialize ADWState with a required ADW ID.
+        
+        Args:
+            adw_id: The ADW ID for this state (required)
+        """
+        if not adw_id:
+            raise ValueError("adw_id is required for ADWState")
+        
+        self.adw_id = adw_id
+        # Start with minimal state
+        self.data: Dict[str, Any] = {"adw_id": self.adw_id}
+        self.logger = logging.getLogger(__name__)
+
+    def update(self, **kwargs):
+        """Update state with new key-value pairs."""
+        # Filter to only our core fields
+        core_fields = {"adw_id", "issue_number", "branch_name", "plan_file", "issue_class", "worktree_path", "backend_port", "frontend_port", "model_set", "all_adws"}
+        for key, value in kwargs.items():
+            if key in core_fields:
+                self.data[key] = value
+
+    def get(self, key: str, default=None):
+        """Get value from state by key."""
+        return self.data.get(key, default)
+
+    def append_adw_id(self, adw_id: str):
+        """Append an ADW ID to the all_adws list if not already present."""
+        all_adws = self.data.get("all_adws", [])
+        if adw_id not in all_adws:
+            all_adws.append(adw_id)
+            self.data["all_adws"] = all_adws
+
+    def get_working_directory(self) -> str:
+        """Get the working directory for this ADW instance.
+        
+        Returns worktree_path if set (for isolated workflows),
+        otherwise returns the main repo path.
+        """
+        worktree_path = self.data.get("worktree_path")
+        if worktree_path:
+            return worktree_path
+        
+        # Return main repo path (parent of adws directory)
+        return os.path.dirname(
+            os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        )
+
+    def get_state_path(self) -> str:
+        """Get path to state file."""
+        project_root = os.path.dirname(
+            os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        )
+        return os.path.join(project_root, "agents", self.adw_id, self.STATE_FILENAME)
+
+    def save(self, workflow_step: Optional[str] = None) -> None:
+        """Save state to file in agents/{adw_id}/adw_state.json."""
+        state_path = self.get_state_path()
+        os.makedirs(os.path.dirname(state_path), exist_ok=True)
+
+        # Create ADWStateData for validation
+        state_data = ADWStateData(
+            adw_id=self.data.get("adw_id"),
+            issue_number=self.data.get("issue_number"),
+            branch_name=self.data.get("branch_name"),
+            plan_file=self.data.get("plan_file"),
+            issue_class=self.data.get("issue_class"),
+            worktree_path=self.data.get("worktree_path"),
+            backend_port=self.data.get("backend_port"),
+            frontend_port=self.data.get("frontend_port"),
+            model_set=self.data.get("model_set", "base"),
+            all_adws=self.data.get("all_adws", []),
+        )
+
+        # Save as JSON
+        with open(state_path, "w") as f:
+            json.dump(state_data.model_dump(), f, indent=2)
+
+        self.logger.info(f"Saved state to {state_path}")
+        if workflow_step:
+            self.logger.info(f"State updated by: {workflow_step}")
+
+    @classmethod
+    def load(
+        cls, adw_id: str, logger: Optional[logging.Logger] = None
+    ) -> Optional["ADWState"]:
+        """Load state from file if it exists."""
+        project_root = os.path.dirname(
+            os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        )
+        state_path = os.path.join(project_root, "agents", adw_id, cls.STATE_FILENAME)
+
+        if not os.path.exists(state_path):
+            return None
+
+        try:
+            with open(state_path, "r") as f:
+                data = json.load(f)
+
+            # Validate with ADWStateData
+            state_data = ADWStateData(**data)
+
+            # Create ADWState instance
+            state = cls(state_data.adw_id)
+            state.data = state_data.model_dump()
+
+            if logger:
+                logger.info(f"🔍 Found existing state from {state_path}")
+                logger.info(f"State: {json.dumps(state_data.model_dump(), indent=2)}")
+
+            return state
+        except Exception as e:
+            if logger:
+                logger.error(f"Failed to load state from {state_path}: {e}")
+            return None
+
+    @classmethod
+    def from_stdin(cls) -> Optional["ADWState"]:
+        """Read state from stdin if available (for piped input).
+
+        Returns None if no piped input is available (stdin is a tty).
+        """
+        if sys.stdin.isatty():
+            return None
+        try:
+            input_data = sys.stdin.read()
+            if not input_data.strip():
+                return None
+            data = json.loads(input_data)
+            adw_id = data.get("adw_id")
+            if not adw_id:
+                return None  # No valid state without adw_id
+            state = cls(adw_id)
+            state.data = data
+            return state
+        except (json.JSONDecodeError, EOFError):
+            return None
+
+    def to_stdout(self):
+        """Write state to stdout as JSON (for piping to next script)."""
+        # Only output core fields
+        output_data = {
+            "adw_id": self.data.get("adw_id"),
+            "issue_number": self.data.get("issue_number"),
+            "branch_name": self.data.get("branch_name"),
+            "plan_file": self.data.get("plan_file"),
+            "issue_class": self.data.get("issue_class"),
+            "worktree_path": self.data.get("worktree_path"),
+            "backend_port": self.data.get("backend_port"),
+            "frontend_port": self.data.get("frontend_port"),
+            "all_adws": self.data.get("all_adws", []),
+        }
+        print(json.dumps(output_data, indent=2))

skills/adw-bootstrap/reference/scaled/adw_modules/workflow_ops.py

@@ -0,0 +1,714 @@
+"""Shared AI Developer Workflow (ADW) operations."""
+
+import glob
+import json
+import logging
+import os
+import subprocess
+import re
+from typing import Tuple, Optional
+from adw_modules.data_types import (
+    AgentTemplateRequest,
+    GitHubIssue,
+    AgentPromptResponse,
+    IssueClassSlashCommand,
+    ADWExtractionResult,
+)
+from adw_modules.agent import execute_template
+from adw_modules.github import get_repo_url, extract_repo_path, ADW_BOT_IDENTIFIER
+from adw_modules.state import ADWState
+from adw_modules.utils import parse_json
+
+
+# Agent name constants
+AGENT_PLANNER = "sdlc_planner"
+AGENT_IMPLEMENTOR = "sdlc_implementor"
+AGENT_CLASSIFIER = "issue_classifier"
+AGENT_BRANCH_GENERATOR = "branch_generator"
+AGENT_PR_CREATOR = "pr_creator"
+
+# Available ADW workflows for runtime validation
+AVAILABLE_ADW_WORKFLOWS = [
+    # Isolated workflows (all workflows are now iso-based)
+    "adw_plan_iso",
+    "adw_patch_iso",
+    "adw_build_iso",
+    "adw_test_iso",
+    "adw_review_iso",
+    "adw_document_iso",
+    "adw_ship_iso",
+    "adw_sdlc_ZTE_iso",  # Zero Touch Execution workflow
+    "adw_plan_build_iso",
+    "adw_plan_build_test_iso",
+    "adw_plan_build_test_review_iso",
+    "adw_plan_build_document_iso",
+    "adw_plan_build_review_iso",
+    "adw_sdlc_iso",
+]
+
+
+def format_issue_message(
+    adw_id: str, agent_name: str, message: str, session_id: Optional[str] = None
+) -> str:
+    """Format a message for issue comments with ADW tracking and bot identifier."""
+    # Always include ADW_BOT_IDENTIFIER to prevent webhook loops
+    if session_id:
+        return f"{ADW_BOT_IDENTIFIER} {adw_id}_{agent_name}_{session_id}: {message}"
+    return f"{ADW_BOT_IDENTIFIER} {adw_id}_{agent_name}: {message}"
+
+
+def extract_adw_info(text: str, temp_adw_id: str) -> ADWExtractionResult:
+    """Extract ADW workflow, ID, and model_set from text using classify_adw agent.
+    Returns ADWExtractionResult with workflow_command, adw_id, and model_set."""
+
+    # Use classify_adw to extract structured info
+    request = AgentTemplateRequest(
+        agent_name="adw_classifier",
+        slash_command="/classify_adw",
+        args=[text],
+        adw_id=temp_adw_id,
+    )
+
+    try:
+        response = execute_template(request)  # No logger available in this function
+
+        if not response.success:
+            print(f"Failed to classify ADW: {response.output}")
+            return ADWExtractionResult()  # Empty result
+
+        # Parse JSON response using utility that handles markdown
+        try:
+            data = parse_json(response.output, dict)
+            adw_command = data.get("adw_slash_command", "").replace(
+                "/", ""
+            )  # Remove slash
+            adw_id = data.get("adw_id")
+            model_set = data.get("model_set", "base")  # Default to "base"
+
+            # Validate command
+            if adw_command and adw_command in AVAILABLE_ADW_WORKFLOWS:
+                return ADWExtractionResult(
+                    workflow_command=adw_command,
+                    adw_id=adw_id,
+                    model_set=model_set
+                )
+
+            return ADWExtractionResult()  # Empty result
+
+        except ValueError as e:
+            print(f"Failed to parse classify_adw response: {e}")
+            return ADWExtractionResult()  # Empty result
+
+    except Exception as e:
+        print(f"Error calling classify_adw: {e}")
+        return ADWExtractionResult()  # Empty result
+
+
+def classify_issue(
+    issue: GitHubIssue, adw_id: str, logger: logging.Logger
+) -> Tuple[Optional[IssueClassSlashCommand], Optional[str]]:
+    """Classify GitHub issue and return appropriate slash command.
+    Returns (command, error_message) tuple."""
+
+    # Use the classify_issue slash command template with minimal payload
+    # Only include the essential fields: number, title, body
+    minimal_issue_json = issue.model_dump_json(
+        by_alias=True, include={"number", "title", "body"}
+    )
+
+    request = AgentTemplateRequest(
+        agent_name=AGENT_CLASSIFIER,
+        slash_command="/classify_issue",
+        args=[minimal_issue_json],
+        adw_id=adw_id,
+    )
+
+    logger.debug(f"Classifying issue: {issue.title}")
+
+    response = execute_template(request)
+
+    logger.debug(
+        f"Classification response: {response.model_dump_json(indent=2, by_alias=True)}"
+    )
+
+    if not response.success:
+        return None, response.output
+
+    # Extract the classification from the response
+    output = response.output.strip()
+
+    # Look for the classification pattern in the output
+    # Claude might add explanation, so we need to extract just the command
+    classification_match = re.search(r"(/chore|/bug|/feature|0)", output)
+
+    if classification_match:
+        issue_command = classification_match.group(1)
+    else:
+        issue_command = output
+
+    if issue_command == "0":
+        return None, f"No command selected: {response.output}"
+
+    if issue_command not in ["/chore", "/bug", "/feature"]:
+        return None, f"Invalid command selected: {response.output}"
+
+    return issue_command, None  # type: ignore
+
+
+def build_plan(
+    issue: GitHubIssue,
+    command: str,
+    adw_id: str,
+    logger: logging.Logger,
+    working_dir: Optional[str] = None,
+) -> AgentPromptResponse:
+    """Build implementation plan for the issue using the specified command."""
+    # Use minimal payload like classify_issue does
+    minimal_issue_json = issue.model_dump_json(
+        by_alias=True, include={"number", "title", "body"}
+    )
+
+    issue_plan_template_request = AgentTemplateRequest(
+        agent_name=AGENT_PLANNER,
+        slash_command=command,
+        args=[str(issue.number), adw_id, minimal_issue_json],
+        adw_id=adw_id,
+        working_dir=working_dir,
+    )
+
+    logger.debug(
+        f"issue_plan_template_request: {issue_plan_template_request.model_dump_json(indent=2, by_alias=True)}"
+    )
+
+    issue_plan_response = execute_template(issue_plan_template_request)
+
+    logger.debug(
+        f"issue_plan_response: {issue_plan_response.model_dump_json(indent=2, by_alias=True)}"
+    )
+
+    return issue_plan_response
+
+
+def implement_plan(
+    plan_file: str,
+    adw_id: str,
+    logger: logging.Logger,
+    agent_name: Optional[str] = None,
+    working_dir: Optional[str] = None,
+) -> AgentPromptResponse:
+    """Implement the plan using the /implement command."""
+    # Use provided agent_name or default to AGENT_IMPLEMENTOR
+    implementor_name = agent_name or AGENT_IMPLEMENTOR
+
+    implement_template_request = AgentTemplateRequest(
+        agent_name=implementor_name,
+        slash_command="/implement",
+        args=[plan_file],
+        adw_id=adw_id,
+        working_dir=working_dir,
+    )
+
+    logger.debug(
+        f"implement_template_request: {implement_template_request.model_dump_json(indent=2, by_alias=True)}"
+    )
+
+    implement_response = execute_template(implement_template_request)
+
+    logger.debug(
+        f"implement_response: {implement_response.model_dump_json(indent=2, by_alias=True)}"
+    )
+
+    return implement_response
+
+
+def generate_branch_name(
+    issue: GitHubIssue,
+    issue_class: IssueClassSlashCommand,
+    adw_id: str,
+    logger: logging.Logger,
+) -> Tuple[Optional[str], Optional[str]]:
+    """Generate a git branch name for the issue.
+    Returns (branch_name, error_message) tuple."""
+    # Remove the leading slash from issue_class for the branch name
+    issue_type = issue_class.replace("/", "")
+
+    # Use minimal payload like classify_issue does
+    minimal_issue_json = issue.model_dump_json(
+        by_alias=True, include={"number", "title", "body"}
+    )
+
+    request = AgentTemplateRequest(
+        agent_name=AGENT_BRANCH_GENERATOR,
+        slash_command="/generate_branch_name",
+        args=[issue_type, adw_id, minimal_issue_json],
+        adw_id=adw_id,
+    )
+
+    response = execute_template(request)
+
+    if not response.success:
+        return None, response.output
+
+    branch_name = response.output.strip()
+    logger.info(f"Generated branch name: {branch_name}")
+    return branch_name, None
+
+
+def create_commit(
+    agent_name: str,
+    issue: GitHubIssue,
+    issue_class: IssueClassSlashCommand,
+    adw_id: str,
+    logger: logging.Logger,
+    working_dir: str,
+) -> Tuple[Optional[str], Optional[str]]:
+    """Create a git commit with a properly formatted message.
+    Returns (commit_message, error_message) tuple."""
+    # Remove the leading slash from issue_class
+    issue_type = issue_class.replace("/", "")
+
+    # Create unique committer agent name by suffixing '_committer'
+    unique_agent_name = f"{agent_name}_committer"
+
+    # Use minimal payload like classify_issue does
+    minimal_issue_json = issue.model_dump_json(
+        by_alias=True, include={"number", "title", "body"}
+    )
+
+    request = AgentTemplateRequest(
+        agent_name=unique_agent_name,
+        slash_command="/commit",
+        args=[agent_name, issue_type, minimal_issue_json],
+        adw_id=adw_id,
+        working_dir=working_dir,
+    )
+
+    response = execute_template(request)
+
+    if not response.success:
+        return None, response.output
+
+    commit_message = response.output.strip()
+    logger.info(f"Created commit message: {commit_message}")
+    return commit_message, None
+
+
+def create_pull_request(
+    branch_name: str,
+    issue: Optional[GitHubIssue],
+    state: ADWState,
+    logger: logging.Logger,
+    working_dir: str,
+) -> Tuple[Optional[str], Optional[str]]:
+    """Create a pull request for the implemented changes.
+    Returns (pr_url, error_message) tuple."""
+
+    # Get plan file from state (may be None for test runs)
+    plan_file = state.get("plan_file") or "No plan file (test run)"
+    adw_id = state.get("adw_id")
+
+    # If we don't have issue data, try to construct minimal data
+    if not issue:
+        issue_data = state.get("issue", {})
+        issue_json = json.dumps(issue_data) if issue_data else "{}"
+    elif isinstance(issue, dict):
+        # Try to reconstruct as GitHubIssue model which handles datetime serialization
+        from adw_modules.data_types import GitHubIssue
+
+        try:
+            issue_model = GitHubIssue(**issue)
+            # Use minimal payload like classify_issue does
+            issue_json = issue_model.model_dump_json(
+                by_alias=True, include={"number", "title", "body"}
+            )
+        except Exception:
+            # Fallback: use json.dumps with default str converter for datetime
+            issue_json = json.dumps(issue, default=str)
+    else:
+        # Use minimal payload like classify_issue does
+        issue_json = issue.model_dump_json(
+            by_alias=True, include={"number", "title", "body"}
+        )
+
+    request = AgentTemplateRequest(
+        agent_name=AGENT_PR_CREATOR,
+        slash_command="/pull_request",
+        args=[branch_name, issue_json, plan_file, adw_id],
+        adw_id=adw_id,
+        working_dir=working_dir,
+    )
+
+    response = execute_template(request)
+
+    if not response.success:
+        return None, response.output
+
+    pr_url = response.output.strip()
+    logger.info(f"Created pull request: {pr_url}")
+    return pr_url, None
+
+
+def ensure_plan_exists(state: ADWState, issue_number: str) -> str:
+    """Find or error if no plan exists for issue.
+    Used by isolated build workflows in standalone mode."""
+    # Check if plan file is in state
+    if state.get("plan_file"):
+        return state.get("plan_file")
+
+    # Check current branch
+    from adw_modules.git_ops import get_current_branch
+
+    branch = get_current_branch()
+
+    # Look for plan in branch name
+    if f"-{issue_number}-" in branch:
+        # Look for plan file
+        plans = glob.glob(f"specs/*{issue_number}*.md")
+        if plans:
+            return plans[0]
+
+    # No plan found
+    raise ValueError(
+        f"No plan found for issue {issue_number}. Run adw_plan_iso.py first."
+    )
+
+
+def ensure_adw_id(
+    issue_number: str,
+    adw_id: Optional[str] = None,
+    logger: Optional[logging.Logger] = None,
+) -> str:
+    """Get ADW ID or create a new one and initialize state.
+
+    Args:
+        issue_number: The issue number to find/create ADW ID for
+        adw_id: Optional existing ADW ID to use
+        logger: Optional logger instance
+
+    Returns:
+        The ADW ID (existing or newly created)
+    """
+    # If ADW ID provided, check if state exists
+    if adw_id:
+        state = ADWState.load(adw_id, logger)
+        if state:
+            if logger:
+                logger.info(f"Found existing ADW state for ID: {adw_id}")
+            else:
+                print(f"Found existing ADW state for ID: {adw_id}")
+            return adw_id
+        # ADW ID provided but no state exists, create state
+        state = ADWState(adw_id)
+        state.update(adw_id=adw_id, issue_number=issue_number)
+        state.save("ensure_adw_id")
+        if logger:
+            logger.info(f"Created new ADW state for provided ID: {adw_id}")
+        else:
+            print(f"Created new ADW state for provided ID: {adw_id}")
+        return adw_id
+
+    # No ADW ID provided, create new one with state
+    from adw_modules.utils import make_adw_id
+
+    new_adw_id = make_adw_id()
+    state = ADWState(new_adw_id)
+    state.update(adw_id=new_adw_id, issue_number=issue_number)
+    state.save("ensure_adw_id")
+    if logger:
+        logger.info(f"Created new ADW ID and state: {new_adw_id}")
+    else:
+        print(f"Created new ADW ID and state: {new_adw_id}")
+    return new_adw_id
+
+
+def find_existing_branch_for_issue(
+    issue_number: str, adw_id: Optional[str] = None, cwd: Optional[str] = None
+) -> Optional[str]:
+    """Find an existing branch for the given issue number.
+    Returns branch name if found, None otherwise."""
+    # List all branches
+    result = subprocess.run(
+        ["git", "branch", "-a"], capture_output=True, text=True, cwd=cwd
+    )
+
+    if result.returncode != 0:
+        return None
+
+    branches = result.stdout.strip().split("\n")
+
+    # Look for branch with standardized pattern: *-issue-{issue_number}-adw-{adw_id}-*
+    for branch in branches:
+        branch = branch.strip().replace("* ", "").replace("remotes/origin/", "")
+        # Check for the standardized pattern
+        if f"-issue-{issue_number}-" in branch:
+            if adw_id and f"-adw-{adw_id}-" in branch:
+                return branch
+            elif not adw_id:
+                # Return first match if no adw_id specified
+                return branch
+
+    return None
+
+
+def find_plan_for_issue(
+    issue_number: str, adw_id: Optional[str] = None
+) -> Optional[str]:
+    """Find plan file for the given issue number and optional adw_id.
+    Returns path to plan file if found, None otherwise."""
+    import os
+
+    # Get project root
+    project_root = os.path.dirname(
+        os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    )
+    agents_dir = os.path.join(project_root, "agents")
+
+    if not os.path.exists(agents_dir):
+        return None
+
+    # If adw_id is provided, check specific directory first
+    if adw_id:
+        plan_path = os.path.join(agents_dir, adw_id, AGENT_PLANNER, "plan.md")
+        if os.path.exists(plan_path):
+            return plan_path
+
+    # Otherwise, search all agent directories
+    for agent_id in os.listdir(agents_dir):
+        agent_path = os.path.join(agents_dir, agent_id)
+        if os.path.isdir(agent_path):
+            plan_path = os.path.join(agent_path, AGENT_PLANNER, "plan.md")
+            if os.path.exists(plan_path):
+                # Check if this plan is for our issue by reading branch info or checking commits
+                # For now, return the first plan found (can be improved)
+                return plan_path
+
+    return None
+
+
+def create_or_find_branch(
+    issue_number: str,
+    issue: GitHubIssue,
+    state: ADWState,
+    logger: logging.Logger,
+    cwd: Optional[str] = None,
+) -> Tuple[str, Optional[str]]:
+    """Create or find a branch for the given issue.
+
+    1. First checks state for existing branch name
+    2. Then looks for existing branches matching the issue
+    3. If none found, classifies the issue and creates a new branch
+
+    Returns (branch_name, error_message) tuple.
+    """
+    # 1. Check state for branch name
+    branch_name = state.get("branch_name") or state.get("branch", {}).get("name")
+    if branch_name:
+        logger.info(f"Found branch in state: {branch_name}")
+        # Check if we need to checkout
+        from adw_modules.git_ops import get_current_branch
+
+        current = get_current_branch(cwd=cwd)
+        if current != branch_name:
+            result = subprocess.run(
+                ["git", "checkout", branch_name],
+                capture_output=True,
+                text=True,
+                cwd=cwd,
+            )
+            if result.returncode != 0:
+                # Branch might not exist locally, try to create from remote
+                result = subprocess.run(
+                    ["git", "checkout", "-b", branch_name, f"origin/{branch_name}"],
+                    capture_output=True,
+                    text=True,
+                    cwd=cwd,
+                )
+                if result.returncode != 0:
+                    return "", f"Failed to checkout branch: {result.stderr}"
+        return branch_name, None
+
+    # 2. Look for existing branch
+    adw_id = state.get("adw_id")
+    existing_branch = find_existing_branch_for_issue(issue_number, adw_id, cwd=cwd)
+    if existing_branch:
+        logger.info(f"Found existing branch: {existing_branch}")
+        # Checkout the branch
+        result = subprocess.run(
+            ["git", "checkout", existing_branch],
+            capture_output=True,
+            text=True,
+            cwd=cwd,
+        )
+        if result.returncode != 0:
+            return "", f"Failed to checkout branch: {result.stderr}"
+        state.update(branch_name=existing_branch)
+        return existing_branch, None
+
+    # 3. Create new branch - classify issue first
+    logger.info("No existing branch found, creating new one")
+
+    # Classify the issue
+    issue_command, error = classify_issue(issue, adw_id, logger)
+    if error:
+        return "", f"Failed to classify issue: {error}"
+
+    state.update(issue_class=issue_command)
+
+    # Generate branch name
+    branch_name, error = generate_branch_name(issue, issue_command, adw_id, logger)
+    if error:
+        return "", f"Failed to generate branch name: {error}"
+
+    # Create the branch
+    from adw_modules.git_ops import create_branch
+
+    success, error = create_branch(branch_name, cwd=cwd)
+    if not success:
+        return "", f"Failed to create branch: {error}"
+
+    state.update(branch_name=branch_name)
+    logger.info(f"Created and checked out new branch: {branch_name}")
+
+    return branch_name, None
+
+
+def find_spec_file(state: ADWState, logger: logging.Logger) -> Optional[str]:
+    """Find the spec file from state or by examining git diff.
+
+    For isolated workflows, automatically uses worktree_path from state.
+    """
+    # Get worktree path if in isolated workflow
+    worktree_path = state.get("worktree_path")
+
+    # Check if spec file is already in state (from plan phase)
+    spec_file = state.get("plan_file")
+    if spec_file:
+        # If worktree_path exists and spec_file is relative, make it absolute
+        if worktree_path and not os.path.isabs(spec_file):
+            spec_file = os.path.join(worktree_path, spec_file)
+
+        if os.path.exists(spec_file):
+            logger.info(f"Using spec file from state: {spec_file}")
+            return spec_file
+
+    # Otherwise, try to find it from git diff
+    logger.info("Looking for spec file in git diff")
+    result = subprocess.run(
+        ["git", "diff", "origin/main", "--name-only"],
+        capture_output=True,
+        text=True,
+        cwd=worktree_path,
+    )
+
+    if result.returncode == 0:
+        files = result.stdout.strip().split("\n")
+        spec_files = [f for f in files if f.startswith("specs/") and f.endswith(".md")]
+
+        if spec_files:
+            # Use the first spec file found
+            spec_file = spec_files[0]
+            if worktree_path:
+                spec_file = os.path.join(worktree_path, spec_file)
+            logger.info(f"Found spec file: {spec_file}")
+            return spec_file
+
+    # If still not found, try to derive from branch name
+    branch_name = state.get("branch_name")
+    if branch_name:
+        # Extract issue number from branch name
+        import re
+
+        match = re.search(r"issue-(\d+)", branch_name)
+        if match:
+            issue_num = match.group(1)
+            adw_id = state.get("adw_id")
+
+            # Look for spec files matching the pattern
+            import glob
+
+            # Use worktree_path if provided, otherwise current directory
+            search_dir = worktree_path if worktree_path else os.getcwd()
+            pattern = os.path.join(
+                search_dir, f"specs/issue-{issue_num}-adw-{adw_id}*.md"
+            )
+            spec_files = glob.glob(pattern)
+
+            if spec_files:
+                spec_file = spec_files[0]
+                logger.info(f"Found spec file by pattern: {spec_file}")
+                return spec_file
+
+    logger.warning("No spec file found")
+    return None
+
+
+def create_and_implement_patch(
+    adw_id: str,
+    review_change_request: str,
+    logger: logging.Logger,
+    agent_name_planner: str,
+    agent_name_implementor: str,
+    spec_path: Optional[str] = None,
+    issue_screenshots: Optional[str] = None,
+    working_dir: Optional[str] = None,
+) -> Tuple[Optional[str], AgentPromptResponse]:
+    """Create a patch plan and implement it.
+    Returns (patch_file_path, implement_response) tuple."""
+
+    # Create patch plan using /patch command
+    args = [adw_id, review_change_request]
+
+    # Add optional arguments in the correct order
+    if spec_path:
+        args.append(spec_path)
+    else:
+        args.append("")  # Empty string for optional spec_path
+
+    args.append(agent_name_planner)
+
+    if issue_screenshots:
+        args.append(issue_screenshots)
+
+    request = AgentTemplateRequest(
+        agent_name=agent_name_planner,
+        slash_command="/patch",
+        args=args,
+        adw_id=adw_id,
+        working_dir=working_dir,
+    )
+
+    logger.debug(
+        f"Patch plan request: {request.model_dump_json(indent=2, by_alias=True)}"
+    )
+
+    response = execute_template(request)
+
+    logger.debug(
+        f"Patch plan response: {response.model_dump_json(indent=2, by_alias=True)}"
+    )
+
+    if not response.success:
+        logger.error(f"Error creating patch plan: {response.output}")
+        # Return None and a failed response
+        return None, AgentPromptResponse(
+            output=f"Failed to create patch plan: {response.output}", success=False
+        )
+
+    # Extract the patch plan file path from the response
+    patch_file_path = response.output.strip()
+
+    # Validate that it looks like a file path
+    if "specs/patch/" not in patch_file_path or not patch_file_path.endswith(".md"):
+        logger.error(f"Invalid patch plan path returned: {patch_file_path}")
+        return None, AgentPromptResponse(
+            output=f"Invalid patch plan path: {patch_file_path}", success=False
+        )
+
+    logger.info(f"Created patch plan: {patch_file_path}")
+
+    # Now implement the patch plan using the provided implementor agent name
+    implement_response = implement_plan(
+        patch_file_path, adw_id, logger, agent_name_implementor, working_dir=working_dir
+    )
+
+    return patch_file_path, implement_response

skills/adw-bootstrap/reference/scaled/adw_modules/worktree_ops.py

@@ -0,0 +1,243 @@
+"""Worktree and port management operations for isolated ADW workflows.
+
+Provides utilities for creating and managing git worktrees under trees/<adw_id>/
+and allocating unique ports for each isolated instance.
+"""
+
+import os
+import subprocess
+import logging
+import socket
+from typing import Tuple, Optional
+from adw_modules.state import ADWState
+
+
+def create_worktree(adw_id: str, branch_name: str, logger: logging.Logger) -> Tuple[str, Optional[str]]:
+    """Create a git worktree for isolated ADW execution.
+    
+    Args:
+        adw_id: The ADW ID for this worktree
+        branch_name: The branch name to create the worktree from
+        logger: Logger instance
+        
+    Returns:
+        Tuple of (worktree_path, error_message)
+        worktree_path is the absolute path if successful, None if error
+    """
+    # Get project root (parent of adws directory)
+    project_root = os.path.dirname(
+        os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    )
+    
+    # Create trees directory if it doesn't exist
+    trees_dir = os.path.join(project_root, "trees")
+    os.makedirs(trees_dir, exist_ok=True)
+    
+    # Construct worktree path
+    worktree_path = os.path.join(trees_dir, adw_id)
+    
+    # Check if worktree already exists
+    if os.path.exists(worktree_path):
+        logger.warning(f"Worktree already exists at {worktree_path}")
+        return worktree_path, None
+    
+    # First, fetch latest changes from origin
+    logger.info("Fetching latest changes from origin")
+    fetch_result = subprocess.run(
+        ["git", "fetch", "origin"], 
+        capture_output=True, 
+        text=True, 
+        cwd=project_root
+    )
+    if fetch_result.returncode != 0:
+        logger.warning(f"Failed to fetch from origin: {fetch_result.stderr}")
+    
+    # Create the worktree using git, branching from origin/main
+    # Use -b to create the branch as part of worktree creation
+    cmd = ["git", "worktree", "add", "-b", branch_name, worktree_path, "origin/main"]
+    result = subprocess.run(cmd, capture_output=True, text=True, cwd=project_root)
+    
+    if result.returncode != 0:
+        # If branch already exists, try without -b
+        if "already exists" in result.stderr:
+            cmd = ["git", "worktree", "add", worktree_path, branch_name]
+            result = subprocess.run(cmd, capture_output=True, text=True, cwd=project_root)
+            
+        if result.returncode != 0:
+            error_msg = f"Failed to create worktree: {result.stderr}"
+            logger.error(error_msg)
+            return None, error_msg
+    
+    logger.info(f"Created worktree at {worktree_path} for branch {branch_name}")
+    return worktree_path, None
+
+
+def validate_worktree(adw_id: str, state: ADWState) -> Tuple[bool, Optional[str]]:
+    """Validate worktree exists in state, filesystem, and git.
+    
+    Performs three-way validation to ensure consistency:
+    1. State has worktree_path
+    2. Directory exists on filesystem
+    3. Git knows about the worktree
+    
+    Args:
+        adw_id: The ADW ID to validate
+        state: The ADW state object
+        
+    Returns:
+        Tuple of (is_valid, error_message)
+    """
+    # Check state has worktree_path
+    worktree_path = state.get("worktree_path")
+    if not worktree_path:
+        return False, "No worktree_path in state"
+    
+    # Check directory exists
+    if not os.path.exists(worktree_path):
+        return False, f"Worktree directory not found: {worktree_path}"
+    
+    # Check git knows about it
+    result = subprocess.run(["git", "worktree", "list"], capture_output=True, text=True)
+    if worktree_path not in result.stdout:
+        return False, "Worktree not registered with git"
+    
+    return True, None
+
+
+def get_worktree_path(adw_id: str) -> str:
+    """Get absolute path to worktree.
+    
+    Args:
+        adw_id: The ADW ID
+        
+    Returns:
+        Absolute path to worktree directory
+    """
+    project_root = os.path.dirname(
+        os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    )
+    return os.path.join(project_root, "trees", adw_id)
+
+
+def remove_worktree(adw_id: str, logger: logging.Logger) -> Tuple[bool, Optional[str]]:
+    """Remove a worktree and clean up.
+    
+    Args:
+        adw_id: The ADW ID for the worktree to remove
+        logger: Logger instance
+        
+    Returns:
+        Tuple of (success, error_message)
+    """
+    worktree_path = get_worktree_path(adw_id)
+    
+    # First remove via git
+    cmd = ["git", "worktree", "remove", worktree_path, "--force"]
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    
+    if result.returncode != 0:
+        # Try to clean up manually if git command failed
+        if os.path.exists(worktree_path):
+            try:
+                shutil.rmtree(worktree_path)
+                logger.warning(f"Manually removed worktree directory: {worktree_path}")
+            except Exception as e:
+                return False, f"Failed to remove worktree: {result.stderr}, manual cleanup failed: {e}"
+    
+    logger.info(f"Removed worktree at {worktree_path}")
+    return True, None
+
+
+def setup_worktree_environment(worktree_path: str, backend_port: int, frontend_port: int, logger: logging.Logger) -> None:
+    """Set up worktree environment by creating .ports.env file.
+    
+    The actual environment setup (copying .env files, installing dependencies) is handled
+    by the install_worktree.md command which runs inside the worktree.
+    
+    Args:
+        worktree_path: Path to the worktree
+        backend_port: Backend port number
+        frontend_port: Frontend port number
+        logger: Logger instance
+    """
+    # Create .ports.env file with port configuration
+    ports_env_path = os.path.join(worktree_path, ".ports.env")
+    
+    with open(ports_env_path, "w") as f:
+        f.write(f"BACKEND_PORT={backend_port}\n")
+        f.write(f"FRONTEND_PORT={frontend_port}\n")
+        f.write(f"VITE_BACKEND_URL=http://localhost:{backend_port}\n")
+    
+    logger.info(f"Created .ports.env with Backend: {backend_port}, Frontend: {frontend_port}")
+
+
+# Port management functions
+
+def get_ports_for_adw(adw_id: str) -> Tuple[int, int]:
+    """Deterministically assign ports based on ADW ID.
+    
+    Args:
+        adw_id: The ADW ID
+        
+    Returns:
+        Tuple of (backend_port, frontend_port)
+    """
+    # Convert first 8 chars of ADW ID to index (0-14)
+    # Using base 36 conversion and modulo to get consistent mapping
+    try:
+        # Take first 8 alphanumeric chars and convert from base 36
+        id_chars = ''.join(c for c in adw_id[:8] if c.isalnum())
+        index = int(id_chars, 36) % 15
+    except ValueError:
+        # Fallback to simple hash if conversion fails
+        index = hash(adw_id) % 15
+    
+    backend_port = 9100 + index
+    frontend_port = 9200 + index
+    
+    return backend_port, frontend_port
+
+
+def is_port_available(port: int) -> bool:
+    """Check if a port is available for binding.
+    
+    Args:
+        port: Port number to check
+        
+    Returns:
+        True if port is available, False otherwise
+    """
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.settimeout(1)
+            s.bind(('localhost', port))
+            return True
+    except (socket.error, OSError):
+        return False
+
+
+def find_next_available_ports(adw_id: str, max_attempts: int = 15) -> Tuple[int, int]:
+    """Find available ports starting from deterministic assignment.
+    
+    Args:
+        adw_id: The ADW ID
+        max_attempts: Maximum number of attempts (default 15)
+        
+    Returns:
+        Tuple of (backend_port, frontend_port)
+        
+    Raises:
+        RuntimeError: If no available ports found
+    """
+    base_backend, base_frontend = get_ports_for_adw(adw_id)
+    base_index = base_backend - 9100
+    
+    for offset in range(max_attempts):
+        index = (base_index + offset) % 15
+        backend_port = 9100 + index
+        frontend_port = 9200 + index
+        
+        if is_port_available(backend_port) and is_port_available(frontend_port):
+            return backend_port, frontend_port
+    
+    raise RuntimeError("No available ports in the allocated range")

skills/adw-bootstrap/reference/scaled/commands/bug.md

@@ -0,0 +1,106 @@
+# Bug Planning
+
+Create a new plan to resolve the `Bug` using the exact specified markdown `Plan Format`. Follow the `Instructions` to create the plan use the `Relevant Files` to focus on the right files.
+
+## Variables
+issue_number: $1
+adw_id: $2
+issue_json: $3
+
+## Instructions
+
+- IMPORTANT: You're writing a plan to resolve a bug based on the `Bug` that will add value to the application.
+- IMPORTANT: The `Bug` describes the bug that will be resolved but remember we're not resolving the bug, we're creating the plan that will be used to resolve the bug based on the `Plan Format` below.
+- You're writing a plan to resolve a bug, it should be thorough and precise so we fix the root cause and prevent regressions.
+- Create the plan in the `specs/` directory with filename: `issue-{issue_number}-adw-{adw_id}-sdlc_planner-{descriptive-name}.md`
+  - Replace `{descriptive-name}` with a short, descriptive name based on the bug (e.g., "fix-login-error", "resolve-timeout", "patch-memory-leak")
+- Use the plan format below to create the plan. 
+- Research the codebase to understand the bug, reproduce it, and put together a plan to fix it.
+- IMPORTANT: Replace every <placeholder> in the `Plan Format` with the requested value. Add as much detail as needed to fix the bug.
+- Use your reasoning model: THINK HARD about the bug, its root cause, and the steps to fix it properly.
+- IMPORTANT: Be surgical with your bug fix, solve the bug at hand and don't fall off track.
+- IMPORTANT: We want the minimal number of changes that will fix and address the bug.
+- Don't use decorators. Keep it simple.
+- If you need a new library, use `uv add` and be sure to report it in the `Notes` section of the `Plan Format`.
+- IMPORTANT: If the bug affects the UI or user interactions:
+  - Add a task in the `Step by Step Tasks` section to create a separate E2E test file in `.claude/commands/e2e/test_<descriptive_name>.md` based on examples in that directory
+  - Add E2E test validation to your Validation Commands section
+  - IMPORTANT: When you fill out the `Plan Format: Relevant Files` section, add an instruction to read `.claude/commands/test_e2e.md`, and `.claude/commands/e2e/test_basic_query.md` to understand how to create an E2E test file. List your new E2E test file to the `Plan Format: New Files` section.
+  - To be clear, we're not creating a new E2E test file, we're creating a task to create a new E2E test file in the `Plan Format` below
+- Respect requested files in the `Relevant Files` section.
+- Start your research by reading the `README.md` file.
+
+## Relevant Files
+
+Focus on the following files:
+- `README.md` - Contains the project overview and instructions.
+- `app/server/**` - Contains the codebase server.
+- `app/client/**` - Contains the codebase client.
+- `scripts/**` - Contains the scripts to start and stop the server + client.
+- `adws/**` - Contains the AI Developer Workflow (ADW) scripts.
+
+- Read `.claude/commands/conditional_docs.md` to check if your task requires additional documentation
+- If your task matches any of the conditions listed, include those documentation files in the `Plan Format: Relevant Files` section of your plan
+
+Ignore all other files in the codebase.
+
+## Plan Format
+
+```md
+# Bug: <bug name>
+
+## Metadata
+issue_number: `{issue_number}`
+adw_id: `{adw_id}`
+issue_json: `{issue_json}`
+
+## Bug Description
+<describe the bug in detail, including symptoms and expected vs actual behavior>
+
+## Problem Statement
+<clearly define the specific problem that needs to be solved>
+
+## Solution Statement
+<describe the proposed solution approach to fix the bug>
+
+## Steps to Reproduce
+<list exact steps to reproduce the bug>
+
+## Root Cause Analysis
+<analyze and explain the root cause of the bug>
+
+## Relevant Files
+Use these files to fix the bug:
+
+<find and list the files that are relevant to the bug describe why they are relevant in bullet points. If there are new files that need to be created to fix the bug, list them in an h3 'New Files' section.>
+
+## Step by Step Tasks
+IMPORTANT: Execute every step in order, top to bottom.
+
+<list step by step tasks as h3 headers plus bullet points. use as many h3 headers as needed to fix the bug. Order matters, start with the foundational shared changes required to fix the bug then move on to the specific changes required to fix the bug. Include tests that will validate the bug is fixed with zero regressions.>
+
+<If the bug affects UI, include a task to create a E2E test file. Your task should look like: "Read `.claude/commands/e2e/test_basic_query.md` and `.claude/commands/e2e/test_complex_query.md` and create a new E2E test file in `.claude/commands/e2e/test_<descriptive_name>.md` that validates the bug is fixed, be specific with the steps to prove the bug is fixed. We want the minimal set of steps to validate the bug is fixed and screen shots to prove it if possible.">
+
+<Your last step should be running the `Validation Commands` to validate the bug is fixed with zero regressions.>
+
+## Validation Commands
+Execute every command to validate the bug is fixed with zero regressions.
+
+<list commands you'll use to validate with 100% confidence the bug is fixed with zero regressions. every command must execute without errors so be specific about what you want to run to validate the bug is fixed with zero regressions. Include commands to reproduce the bug before and after the fix.>
+
+<If you created an E2E test, include the following validation step: "Read .claude/commands/test_e2e.md`, then read and execute your new E2E `.claude/commands/e2e/test_<descriptive_name>.md` test file to validate this functionality works.">
+
+- `cd app/server && uv run pytest` - Run server tests to validate the bug is fixed with zero regressions
+- `cd app/client && bun tsc --noEmit` - Run frontend tests to validate the bug is fixed with zero regressions
+- `cd app/client && bun run build` - Run frontend build to validate the bug is fixed with zero regressions
+
+## Notes
+<optionally list any additional notes or context that are relevant to the bug that will be helpful to the developer>
+```
+
+## Bug
+Extract the bug details from the `issue_json` variable (parse the JSON and use the title and body fields).
+
+## Report
+
+- IMPORTANT: Return exclusively the path to the plan file created and nothing else.

skills/adw-bootstrap/reference/scaled/commands/classify_adw.md

@@ -0,0 +1,57 @@
+# ADW Workflow Extraction
+
+Extract ADW workflow information from the text below and return a JSON response.
+
+## Instructions
+
+- Look for ADW workflow commands in the text (e.g., `/adw_plan_iso`, `/adw_build_iso`, `/adw_test_iso`, `/adw_review_iso`, `/adw_document_iso`, `/adw_patch_iso`, `/adw_plan_build_iso`, `/adw_plan_build_test_iso`, `/adw_plan_build_test_review_iso`, `/adw_sdlc_iso`, `/adw_sdlc_ZTE_iso`)
+- Also recognize commands without the `_iso` suffix and automatically add it (e.g., `/adw_plan` → `/adw_plan_iso`)
+- Also recognize variations like `adw_plan_build`, `adw plan build`, `/adw plan then build`, etc. and map to the correct command
+- Look for ADW IDs (8-character alphanumeric strings, often after "adw_id:" or "ADW ID:" or similar)
+- Look for model set specification: "model_set base" or "model_set heavy" (case insensitive)
+  - Default to "base" if no model_set is specified
+  - Also recognize variations like "model set: heavy", "modelset heavy", etc.
+- Return a JSON object with the extracted information
+- If no ADW workflow is found, return empty JSON: `{}`
+- IMPORTANT: DO NOT RUN the `adw_sdlc_ZTE_iso` workflows unless `ZTE` is EXPLICITLY uppercased. This is a dangerous workflow and it needs to be absolutely clear when we're running it. If zte is not capitalized, then run the non zte version `/adw_sdlc_iso`.
+
+## Valid ADW Commands
+
+- `/adw_plan_iso` - Planning only
+- `/adw_build_iso` - Building only (requires adw_id)
+- `/adw_test_iso` - Testing only (requires adw_id)
+- `/adw_review_iso` - Review only (requires adw_id)
+- `/adw_document_iso` - Documentation only (requires adw_id)
+- `/adw_ship_iso` - Ship/approve and merge PR (requires adw_id)
+- `/adw_patch_iso` - Direct patch from issue
+- `/adw_plan_build_iso` - Plan + Build
+- `/adw_plan_build_test_iso` - Plan + Build + Test
+- `/adw_plan_build_review_iso` - Plan + Build + Review (skips test)
+- `/adw_plan_build_document_iso` - Plan + Build + Document (skips test and review)
+- `/adw_plan_build_test_review_iso` - Plan + Build + Test + Review
+- `/adw_sdlc_iso` - Complete SDLC: Plan + Build + Test + Review + Document
+- `/adw_sdlc_zte_iso` - Zero Touch Execution: Complete SDLC + auto-merge to production. Note: as per instructions, 'ZTE' must be capitalized. Do not run this if 'zte' is not capitalized.
+
+## Response Format
+
+Respond ONLY with a JSON object in this format:
+```json
+{
+  "adw_slash_command": "/adw_plan",
+  "adw_id": "abc12345",
+  "model_set": "base"
+}
+```
+
+Fields:
+- `adw_slash_command`: The ADW command found (include the slash)
+- `adw_id`: The 8-character ADW ID if found
+- `model_set`: The model set to use ("base" or "heavy"), defaults to "base" if not specified
+
+If only some fields are found, include only those fields.
+If nothing is found, return: `{}`
+IMPORTANT: Always include `model_set` with value "base" if no model_set is explicitly mentioned in the text.
+
+## Text to Analyze
+
+$ARGUMENTS

skills/adw-bootstrap/reference/scaled/commands/classify_issue.md

@@ -0,0 +1,22 @@
+# Github Issue Command Selection
+
+Based on the `Github Issue` below, follow the `Instructions` to select the appropriate command to execute based on the `Command Mapping`.
+
+## Instructions
+
+- Based on the details in the `Github Issue`, select the appropriate command to execute.
+- IMPORTANT: Respond exclusively with '/' followed by the command to execute based on the `Command Mapping` below.
+- Use the command mapping to help you decide which command to respond with.
+- Don't examine the codebase just focus on the `Github Issue` and the `Command Mapping` below to determine the appropriate command to execute.
+
+## Command Mapping
+
+- Respond with `/chore` if the issue is a chore.
+- Respond with `/bug` if the issue is a bug.
+- Respond with `/feature` if the issue is a feature.
+- Respond with `/patch` if the issue is a patch.
+- Respond with `0` if the issue isn't any of the above.
+
+## Github Issue
+
+$ARGUMENTS

skills/adw-bootstrap/reference/scaled/commands/cleanup_worktrees.md

@@ -0,0 +1,44 @@
+# Cleanup ADW Worktrees
+
+Clean up isolated ADW worktrees and their associated resources.
+
+## Variables
+
+action: $1 (all|specific|list)
+adw_id: $2 (optional, required if action is "specific")
+
+## Instructions
+
+Manage git worktrees created by isolated ADW workflows:
+- If action is "list": Show all worktrees under trees/ directory
+- If action is "specific": Remove the specific worktree for the given adw_id
+- If action is "all": Remove all worktrees under trees/ directory
+
+## Run
+
+Based on the action:
+
+### List worktrees
+If action is "list":
+- Run `git worktree list | grep "trees/"` to show isolated worktrees
+- List the contents of the trees/ directory with sizes
+
+### Remove specific worktree
+If action is "specific" and adw_id is provided:
+- Check if trees/{adw_id} exists
+- Run `git worktree remove trees/{adw_id}` to remove it
+- Report success or any errors
+
+### Remove all worktrees
+If action is "all":
+- First list all worktrees that will be removed
+- For each worktree under trees/, run `git worktree remove`
+- Clean up any remaining directories under trees/
+- Run `git worktree prune` to clean up any stale entries
+
+## Report
+
+Report the results of the cleanup operation:
+- Number of worktrees removed
+- Any errors encountered
+- Current status after cleanup

skills/adw-bootstrap/reference/scaled/commands/document.md

@@ -0,0 +1,129 @@
+# Document Feature
+
+Generate concise markdown documentation for implemented features by analyzing code changes and specifications. This command creates documentation in the `app_docs/` directory based on git diff analysis against the main branch and the original feature specification.
+
+## Variables
+
+adw_id: $1
+spec_path: $2 if provided, otherwise leave it blank
+documentation_screenshots_dir: $3 if provided, otherwise leave it blank
+
+## Instructions
+
+### 1. Analyze Changes
+- Run `git diff origin/main --stat` to see files changed and lines modified
+- Run `git diff origin/main --name-only` to get the list of changed files
+- For significant changes (>50 lines), run `git diff origin/main <file>` on specific files to understand the implementation details
+
+### 2. Read Specification (if provided)
+- If `spec_path` is provided, read the specification file to understand:
+  - Original requirements and goals
+  - Expected functionality
+  - Success criteria
+- Use this to frame the documentation around what was requested vs what was built
+
+### 3. Analyze and Copy Screenshots (if provided)
+- If `documentation_screenshots_dir` is provided, list and examine screenshots
+- Create `app_docs/assets/` directory if it doesn't exist
+- Copy all screenshot files (*.png) from `documentation_screenshots_dir` to `app_docs/assets/`
+  - Preserve original filenames
+  - Use `cp` command to copy files
+- Use visual context to better describe UI changes or visual features
+- Reference screenshots in documentation using relative paths (e.g., `assets/screenshot-name.png`)
+
+### 4. Generate Documentation
+- Create a new documentation file in `app_docs/` directory
+- Filename format: `feature-{adw_id}-{descriptive-name}.md`
+  - Replace `{descriptive-name}` with a short feature name (e.g., "user-auth", "data-export", "search-ui")
+- Follow the Documentation Format below
+- Focus on:
+  - What was built (based on git diff)
+  - How it works (technical implementation)
+  - How to use it (user perspective)
+  - Any configuration or setup required
+
+### 5. Update Conditional Documentation
+- After creating the documentation file, read `.claude/commands/conditional_docs.md`
+- Add an entry for the new documentation file with appropriate conditions
+- The entry should help future developers know when to read this documentation
+- Format the entry following the existing pattern in the file
+
+### 6. Final Output
+- When you finish writing the documentation and updating conditional_docs.md, return exclusively the path to the documentation file created and nothing else
+
+## Documentation Format
+
+```md
+# <Feature Title>
+
+**ADW ID:** <adw_id>
+**Date:** <current date>
+**Specification:** <spec_path or "N/A">
+
+## Overview
+
+<2-3 sentence summary of what was built and why>
+
+## Screenshots
+
+<If documentation_screenshots_dir was provided and screenshots were copied>
+
+![<Description>](assets/<screenshot-filename.png>)
+
+## What Was Built
+
+<List the main components/features implemented based on the git diff analysis>
+
+- <Component/feature 1>
+- <Component/feature 2>
+- <etc>
+
+## Technical Implementation
+
+### Files Modified
+
+<List key files changed with brief description of changes>
+
+- `<file_path>`: <what was changed/added>
+- `<file_path>`: <what was changed/added>
+
+### Key Changes
+
+<Describe the most important technical changes in 3-5 bullet points>
+
+## How to Use
+
+<Step-by-step instructions for using the new feature>
+
+1. <Step 1>
+2. <Step 2>
+3. <etc>
+
+## Configuration
+
+<Any configuration options, environment variables, or settings>
+
+## Testing
+
+<Brief description of how to test the feature>
+
+## Notes
+
+<Any additional context, limitations, or future considerations>
+```
+
+## Conditional Docs Entry Format
+
+After creating the documentation, add this entry to `.claude/commands/conditional_docs.md`:
+
+```md
+- app_docs/<your_documentation_file>.md
+  - Conditions:
+    - When working with <feature area>
+    - When implementing <related functionality>
+    - When troubleshooting <specific issues>
+```
+
+## Report
+
+- IMPORTANT: Return exclusively the path to the documentation file created and nothing else.

skills/adw-bootstrap/reference/scaled/commands/generate_branch_name.md

@@ -0,0 +1,34 @@
+# Generate Git Branch Name
+
+Based on the `Instructions` below, take the `Variables` follow the `Run` section to generate a concise Git branch name following the specified format. Then follow the `Report` section to report the results of your work.
+
+## Variables
+
+issue_class: $1
+adw_id: $2
+issue: $3
+
+## Instructions
+
+- Generate a branch name in the format: `<issue_class>-issue-<issue_number>-adw-<adw_id>-<concise_name>`
+- The `<concise_name>` should be:
+  - 3-6 words maximum
+  - All lowercase
+  - Words separated by hyphens
+  - Descriptive of the main task/feature
+  - No special characters except hyphens
+- Examples:
+  - `feat-issue-123-adw-a1b2c3d4-add-user-auth`
+  - `bug-issue-456-adw-e5f6g7h8-fix-login-error`
+  - `chore-issue-789-adw-i9j0k1l2-update-dependencies`
+  - `test-issue-323-adw-m3n4o5p6-fix-failing-tests`
+- Extract the issue number, title, and body from the issue JSON
+
+## Run
+
+Generate the branch name based on the instructions above.
+Do NOT create or checkout any branches - just generate the name.
+
+## Report
+
+Return ONLY the generated branch name (no other text)

skills/adw-bootstrap/reference/scaled/commands/install_worktree.md

@@ -0,0 +1,82 @@
+# Install Worktree
+
+This command sets up an isolated worktree environment with custom port configuration.
+
+## Parameters
+- Worktree path: {0}
+- Backend port: {1}
+- Frontend port: {2}
+
+## Read
+- .env.sample (from parent repo)
+- ./app/server/.env.sample (from parent repo)
+- .mcp.json (from parent repo)
+- playwright-mcp-config.json (from parent repo)
+
+## Steps
+
+1. **Navigate to worktree directory**
+   ```bash
+   cd {0}
+   ```
+
+2. **Create port configuration file**
+   Create `.ports.env` with:
+   ```
+   BACKEND_PORT={1}
+   FRONTEND_PORT={2}
+   VITE_BACKEND_URL=http://localhost:{1}
+   ```
+
+3. **Copy and update .env files**
+   - Copy `.env` from parent repo if it exists
+   - Append `.ports.env` contents to `.env`
+   - Copy `app/server/.env` from parent repo if it exists
+   - Append `.ports.env` contents to `app/server/.env`
+
+4. **Copy and configure MCP files**
+   - Copy `.mcp.json` from parent repo if it exists
+   - Copy `playwright-mcp-config.json` from parent repo if it exists
+   - These files are needed for Model Context Protocol and Playwright automation
+   
+   After copying, update paths to use absolute paths:
+   - Get the absolute worktree path: `WORKTREE_PATH=$(pwd)`
+   - Update `.mcp.json`:
+     - Find the line containing `"./playwright-mcp-config.json"`
+     - Replace it with `"${WORKTREE_PATH}/playwright-mcp-config.json"`
+     - Use a JSON-aware tool or careful string replacement to maintain valid JSON
+   - Update `playwright-mcp-config.json`:
+     - Find the line containing `"dir": "./videos"`
+     - Replace it with `"dir": "${WORKTREE_PATH}/videos"`
+     - Create the videos directory: `mkdir -p ${WORKTREE_PATH}/videos`
+   - This ensures MCP configuration works correctly regardless of execution context
+
+5. **Install backend dependencies**
+   ```bash
+   cd app/server && uv sync --all-extras
+   ```
+
+6. **Install frontend dependencies**
+   ```bash
+   cd ../client && bun install
+   ```
+
+7. **Setup database**
+   ```bash
+   cd ../.. && ./scripts/reset_db.sh
+   ```
+
+## Error Handling
+- If parent .env files don't exist, create minimal versions from .env.sample files
+- Ensure all paths are absolute to avoid confusion
+
+## Report
+- List all files created/modified (including MCP configuration files)
+- Show port assignments
+- Confirm dependencies installed
+- Note any missing parent .env files that need user attention
+- Note any missing MCP configuration files
+- Show the updated absolute paths in:
+  - `.mcp.json` (should show full path to playwright-mcp-config.json)
+  - `playwright-mcp-config.json` (should show full path to videos directory)
+- Confirm videos directory was created

skills/adw-bootstrap/reference/scaled/commands/patch.md

@@ -0,0 +1,92 @@
+# Patch Plan
+
+Create a **focused patch plan** to resolve a specific issue based on the `review_change_request`. Follow the `Instructions` to create a concise plan that addresses the issue with minimal, targeted changes.
+
+## Variables
+
+adw_id: $1
+review_change_request: $2
+spec_path: $3 if provided, otherwise leave it blank
+agent_name: $4 if provided, otherwise use 'patch_agent'
+issue_screenshots: $ARGUMENT (optional) - comma-separated list of screenshot paths if provided
+
+## Instructions
+
+- IMPORTANT: You're creating a patch plan to fix a specific review issue. Keep changes small, focused, and targeted
+- Read the original specification (spec) file at `spec_path` if provided to understand the context and requirements
+- IMPORTANT Use the `review_change_request` to understand exactly what needs and use it as the basis for your patch plan
+- If `issue_screenshots` are provided, examine them to better understand the visual context of the issue
+- Create the patch plan in `specs/patch/` directory with filename: `patch-adw-{adw_id}-{descriptive-name}.md`
+  - Replace `{descriptive-name}` with a short name based on the issue (e.g., "fix-button-color", "update-validation", "correct-layout")
+- IMPORTANT: This is a PATCH - keep the scope minimal. Only fix what's described in the `review_change_request` and nothing more. Address only the `review_change_request`.
+- Run `git diff --stat`. If changes are available, use them to understand what's been done in the codebase and so you can understand the exact changes you should detail in the patch plan.
+- Ultra think about the most efficient way to implement the solution with minimal code changes
+- Base your `Plan Format: Validation` on the validation steps from `spec_path` if provided
+  - If any tests fail in the validation steps, you must fix them.
+  - If not provided, READ `.claude/commands/test.md: ## Test Execution Sequence` and execute the tests to understand the tests that need to be run to validate the patch.
+- Replace every <placeholder> in the `Plan Format` with specific implementation details
+- IMPORTANT: When you finish writing the patch plan, return exclusively the path to the patch plan file created and nothing else.
+
+## Relevant Files
+
+Focus on the following files:
+- `README.md` - Contains the project overview and instructions.
+- `app/server/**` - Contains the codebase server.
+- `app/client/**` - Contains the codebase client.
+- `scripts/**` - Contains the scripts to start and stop the server + client.
+- `adws/**` - Contains the AI Developer Workflow (ADW) scripts.
+
+- Read `.claude/commands/conditional_docs.md` to check if your task requires additional documentation
+- If your task matches any of the conditions listed, reference those documentation files to understand the context better when creating your patch plan
+
+Ignore all other files in the codebase.
+
+
+## Plan Format
+
+```md
+# Patch: <concise patch title>
+
+## Metadata
+adw_id: `{adw_id}`
+review_change_request: `{review_change_request}`
+
+## Issue Summary
+**Original Spec:** <spec_path>
+**Issue:** <brief description of the review issue based on the `review_change_request`>
+**Solution:** <brief description of the solution approach based on the `review_change_request`>
+
+## Files to Modify
+Use these files to implement the patch:
+
+<list only the files that need changes - be specific and minimal>
+
+## Implementation Steps
+IMPORTANT: Execute every step in order, top to bottom.
+
+<list 2-5 focused steps to implement the patch. Each step should be a concrete action.>
+
+### Step 1: <specific action>
+- <implementation detail>
+- <implementation detail>
+
+### Step 2: <specific action>
+- <implementation detail>
+- <implementation detail>
+
+<continue as needed, but keep it minimal>
+
+## Validation
+Execute every command to validate the patch is complete with zero regressions.
+
+<list 1-5 specific commands or checks to verify the patch works correctly>
+
+## Patch Scope
+**Lines of code to change:** <estimate>
+**Risk level:** <low|medium|high>
+**Testing required:** <brief description>
+```
+
+## Report
+
+- IMPORTANT: Return exclusively the path to the patch plan file created and nothing else.

skills/adw-bootstrap/reference/scaled/commands/pull_request.md

@@ -0,0 +1,41 @@
+# Create Pull Request
+
+Based on the `Instructions` below, take the `Variables` follow the `Run` section to create a pull request. Then follow the `Report` section to report the results of your work.
+
+## Variables
+
+branch_name: $1
+issue: $2
+plan_file: $3
+adw_id: $4
+
+## Instructions
+
+- Generate a pull request title in the format: `<issue_type>: #<issue_number> - <issue_title>`
+- The PR body should include:
+  - A summary section with the issue context
+  - Link to the implementation `plan_file` if it exists
+  - Reference to the issue (Closes #<issue_number>)
+  - ADW tracking ID
+  - A checklist of what was done
+  - A summary of key changes made
+- Extract issue number, type, and title from the issue JSON
+- Examples of PR titles:
+  - `feat: #123 - Add user authentication`
+  - `bug: #456 - Fix login validation error`
+  - `chore: #789 - Update dependencies`
+  - `test: #1011 - Test xyz`
+- Don't mention Claude Code in the PR body - let the author get credit for this.
+
+## Run
+
+1. Run `git diff origin/main...HEAD --stat` to see a summary of changed files
+2. Run `git log origin/main..HEAD --oneline` to see the commits that will be included
+3. Run `git diff origin/main...HEAD --name-only` to get a list of changed files
+4. Run `git push -u origin <branch_name>` to push the branch
+5. Set GH_TOKEN environment variable from GITHUB_PAT if available, then run `gh pr create --title "<pr_title>" --body "<pr_body>" --base main` to create the PR
+6. Capture the PR URL from the output
+
+## Report
+
+Return ONLY the PR URL that was created (no other text)

skills/adw-bootstrap/reference/scaled/commands/review.md

@@ -0,0 +1,85 @@
+# Review
+
+Follow the `Instructions` below to **review work done against a specification file** (specs/*.md) to ensure implemented features match requirements. Use the spec file to understand the requirements and then use the git diff if available to understand the changes made. Capture screenshots of critical functionality paths as documented in the `Instructions` section. If there are issues, report them if not then report success.
+
+## Variables
+
+adw_id: $1
+spec_file: $2
+agent_name: $3 if provided, otherwise use 'review_agent'
+review_image_dir: `<absolute path to codebase>/agents/<adw_id>/<agent_name>/review_img/`
+
+## Instructions
+
+- Check current git branch using `git branch` to understand context
+- Run `git diff origin/main` to see all changes made in current branch. Continue even if there are no changes related to the spec file.
+- Find the spec file by looking for specs/*.md files in the diff that match the current branch name
+- Read the identified spec file to understand requirements
+- IMPORTANT: If the work can be validated by UI validation then (if not skip the section):
+  - Use the playwright mcp server commands to validate the work.
+  - Look for corresponding e2e test files in ./claude/commands/e2e/test_*.md that mirror the feature name
+  - Use e2e test files only as navigation guides for screenshot locations, not for other purposes
+  - IMPORTANT: To be clear, we're not testing. We know the functionality works. We're reviewing the implementation against the spec to make sure it matches what was requested.
+  - IMPORTANT: Take screen shots along the way to showcase the new functionality and any issues you find
+    - Capture visual proof of working features through targeted screenshots
+    - Navigate to the application and capture screenshots of only the critical paths based on the spec
+    - Compare implemented changes with spec requirements to verify correctness
+    - Do not take screenshots of the entire process, only the critical points.
+    - IMPORTANT: Aim for `1-5` screenshots to showcase that the new functionality works as specified.
+    - If there is a review issue, take a screenshot of the issue and add it to the `review_issues` array. Describe the issue, resolution, and severity.
+    - Number your screenshots in the order they are taken like `01_<descriptive name>.png`, `02_<descriptive name>.png`, etc.
+    - IMPORTANT: Be absolutely sure to take a screen shot of the critical point of the new functionality
+    - IMPORTANT: Copy all screenshots to the provided `review_image_dir`
+    - IMPORTANT: Store the screenshots in the `review_image_dir` and be sure to use full absolute paths.
+    - Focus only on critical functionality paths - avoid unnecessary screenshots
+    - Ensure screenshots clearly demonstrate that features work as specified
+    - Use descriptive filenames that indicate what part of the change is being verified
+- IMPORTANT: Issue Severity Guidelines
+  - Think hard about the impact of the issue on the feature and the user
+  - Guidelines:
+    - `skippable` - the issue is non-blocker for the work to be released but is still a problem
+    - `tech_debt` - the issue is non-blocker for the work to be released but will create technical debt that should be addressed in the future
+    - `blocker` - the issue is a blocker for the work to be released and should be addressed immediately. It will harm the user experience or will not function as expected.
+- IMPORTANT: Return ONLY the JSON array with test results
+  - IMPORTANT: Output your result in JSON format based on the `Report` section below.
+  - IMPORTANT: Do not include any additional text, explanations, or markdown formatting
+  - We'll immediately run JSON.parse() on the output, so make sure it's valid JSON
+- Ultra think as you work through the review process. Focus on the critical functionality paths and the user experience. Don't report issues if they are not critical to the feature.
+
+## Setup
+
+IMPORTANT: Read and **Execute** `.claude/commands/prepare_app.md` now to prepare the application for the review.
+- Note: prepare_app.md will automatically detect and use ports from `.ports.env` if running in a worktree environment
+- The application URL will be http://localhost:PORT where PORT is from `.ports.env` (FRONTEND_PORT) or default 5173
+
+## Report
+
+- IMPORTANT: Return results exclusively as a JSON array based on the `Output Structure` section below.
+- `success` should be `true` if there are NO BLOCKING issues (implementation matches spec for critical functionality)
+- `success` should be `false` ONLY if there are BLOCKING issues that prevent the work from being released
+- `review_issues` can contain issues of any severity (skippable, tech_debt, or blocker)
+- `screenshots` should ALWAYS contain paths to screenshots showcasing the new functionality, regardless of success status. Use full absolute paths.
+- This allows subsequent agents to quickly identify and resolve blocking errors while documenting all issues
+
+### Output Structure
+
+```json
+{
+    success: "boolean - true if there are NO BLOCKING issues (can have skippable/tech_debt issues), false if there are BLOCKING issues",
+    review_summary: "string - 2-4 sentences describing what was built and whether it matches the spec. Written as if reporting during a standup meeting. Example: 'The natural language query feature has been implemented with drag-and-drop file upload and interactive table display. The implementation matches the spec requirements for SQL injection protection and supports both CSV and JSON formats. Minor UI improvements could be made but all core functionality is working as specified.'",
+    review_issues: [
+        {
+            "review_issue_number": "number - the issue number based on the index of this issue",
+            "screenshot_path": "string - /absolute/path/to/screenshot_that_shows_review_issue.png",
+            "issue_description": "string - description of the issue",
+            "issue_resolution": "string - description of the resolution",
+            "issue_severity": "string - severity of the issue between 'skippable', 'tech_debt', 'blocker'"
+        },
+        ...
+    ],
+    screenshots: [
+        "string - /absolute/path/to/screenshot_showcasing_functionality.png",
+        "string - /absolute/path/to/screenshot_showcasing_functionality.png",
+        "...",
+    ]
+}

skills/adw-bootstrap/reference/scaled/commands/test.md

@@ -0,0 +1,115 @@
+# Application Validation Test Suite
+
+Execute comprehensive validation tests for both frontend and backend components, returning results in a standardized JSON format for automated processing.
+
+## Purpose
+
+Proactively identify and fix issues in the application before they impact users or developers. By running this comprehensive test suite, you can:
+- Detect syntax errors, type mismatches, and import failures
+- Identify broken tests or security vulnerabilities  
+- Verify build processes and dependencies
+- Ensure the application is in a healthy state
+
+## Variables
+
+TEST_COMMAND_TIMEOUT: 5 minutes
+
+## Instructions
+
+- Execute each test in the sequence provided below
+- Capture the result (passed/failed) and any error messages
+- IMPORTANT: Return ONLY the JSON array with test results
+  - IMPORTANT: Do not include any additional text, explanations, or markdown formatting
+  - We'll immediately run JSON.parse() on the output, so make sure it's valid JSON
+- If a test passes, omit the error field
+- If a test fails, include the error message in the error field
+- Execute all tests even if some fail
+- Error Handling:
+  - If a command returns non-zero exit code, mark as failed and immediately stop processing tests
+  - Capture stderr output for error field
+  - Timeout commands after `TEST_COMMAND_TIMEOUT`
+  - IMPORTANT: If a test fails, stop processing tests and return the results thus far
+- Some tests may have dependencies (e.g., server must be stopped for port availability)
+- API health check is required
+- Test execution order is important - dependencies should be validated first
+- All file paths are relative to the project root
+- Always run `pwd` and `cd` before each test to ensure you're operating in the correct directory for the given test
+
+## Test Execution Sequence
+
+### Backend Tests
+
+1. **Python Syntax Check**
+   - Preparation Command: None
+   - Command: `cd app/server && uv run python -m py_compile server.py main.py core/*.py`
+   - test_name: "python_syntax_check"
+   - test_purpose: "Validates Python syntax by compiling source files to bytecode, catching syntax errors like missing colons, invalid indentation, or malformed statements"
+
+2. **Backend Code Quality Check**
+   - Preparation Command: None
+   - Command: `cd app/server && uv run ruff check .`
+   - test_name: "backend_linting"
+   - test_purpose: "Validates Python code quality, identifies unused imports, style violations, and potential bugs"
+
+3. **All Backend Tests**
+   - Preparation Command: None
+   - Command: `cd app/server && uv run pytest tests/ -v --tb=short`
+   - test_name: "all_backend_tests"
+   - test_purpose: "Validates all backend functionality including file processing, SQL security, LLM integration, and API endpoints"
+
+### Frontend Tests
+
+4. **TypeScript Type Check**
+   - Preparation Command: None
+   - Command: `cd app/client && bun tsc --noEmit`
+   - test_name: "typescript_check"
+   - test_purpose: "Validates TypeScript type correctness without generating output files, catching type errors, missing imports, and incorrect function signatures"
+
+5. **Frontend Build**
+   - Preparation Command: None
+   - Command: `cd app/client && bun run build`
+   - test_name: "frontend_build"
+   - test_purpose: "Validates the complete frontend build process including bundling, asset optimization, and production compilation"
+
+## Report
+
+- IMPORTANT: Return results exclusively as a JSON array based on the `Output Structure` section below.
+- Sort the JSON array with failed tests (passed: false) at the top
+- Include all tests in the output, both passed and failed
+- The execution_command field should contain the exact command that can be run to reproduce the test
+- This allows subsequent agents to quickly identify and resolve errors
+
+### Output Structure
+
+```json
+[
+  {
+    "test_name": "string",
+    "passed": boolean,
+    "execution_command": "string",
+    "test_purpose": "string",
+    "error": "optional string"
+  },
+  ...
+]
+```
+
+### Example Output
+
+```json
+[
+  {
+    "test_name": "frontend_build",
+    "passed": false,
+    "execution_command": "cd app/client && bun run build",
+    "test_purpose": "Validates TypeScript compilation, module resolution, and production build process for the frontend application",
+    "error": "TS2345: Argument of type 'string' is not assignable to parameter of type 'number'"
+  },
+  {
+    "test_name": "all_backend_tests",
+    "passed": true,
+    "execution_command": "cd app/server && uv run pytest tests/ -v --tb=short",
+    "test_purpose": "Validates all backend functionality including file processing, SQL security, LLM integration, and API endpoints"
+  }
+]
+```

skills/adw-bootstrap/reference/scaled/workflows/adw_plan_build_test_review_iso.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env -S uv run
+# /// script
+# dependencies = ["python-dotenv", "pydantic"]
+# ///
+
+"""
+ADW Plan Build Test Review Iso - Compositional workflow for isolated planning, building, testing, and reviewing
+
+Usage: uv run adw_plan_build_test_review_iso.py <issue-number> [adw-id] [--skip-e2e] [--skip-resolution]
+
+This script runs:
+1. adw_plan_iso.py - Planning phase (isolated)
+2. adw_build_iso.py - Implementation phase (isolated)
+3. adw_test_iso.py - Testing phase (isolated)
+4. adw_review_iso.py - Review phase (isolated)
+
+The scripts are chained together via persistent state (adw_state.json).
+"""
+
+import subprocess
+import sys
+import os
+
+# Add the parent directory to Python path to import modules
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from adw_modules.workflow_ops import ensure_adw_id
+
+
+def main():
+    """Main entry point."""
+    # Check for flags
+    skip_e2e = "--skip-e2e" in sys.argv
+    skip_resolution = "--skip-resolution" in sys.argv
+    
+    # Remove flags from argv
+    if skip_e2e:
+        sys.argv.remove("--skip-e2e")
+    if skip_resolution:
+        sys.argv.remove("--skip-resolution")
+    
+    if len(sys.argv) < 2:
+        print("Usage: uv run adw_plan_build_test_review_iso.py <issue-number> [adw-id] [--skip-e2e] [--skip-resolution]")
+        print("\nThis runs the isolated plan, build, test, and review workflow:")
+        print("  1. Plan (isolated)")
+        print("  2. Build (isolated)")
+        print("  3. Test (isolated)")
+        print("  4. Review (isolated)")
+        sys.exit(1)
+
+    issue_number = sys.argv[1]
+    adw_id = sys.argv[2] if len(sys.argv) > 2 else None
+
+    # Ensure ADW ID exists with initialized state
+    adw_id = ensure_adw_id(issue_number, adw_id)
+    print(f"Using ADW ID: {adw_id}")
+
+    # Get the directory where this script is located
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+
+    # Run isolated plan with the ADW ID
+    plan_cmd = [
+        "uv",
+        "run",
+        os.path.join(script_dir, "adw_plan_iso.py"),
+        issue_number,
+        adw_id,
+    ]
+    print(f"\n=== ISOLATED PLAN PHASE ===")
+    print(f"Running: {' '.join(plan_cmd)}")
+    plan = subprocess.run(plan_cmd)
+    if plan.returncode != 0:
+        print("Isolated plan phase failed")
+        sys.exit(1)
+
+    # Run isolated build with the ADW ID
+    build_cmd = [
+        "uv",
+        "run",
+        os.path.join(script_dir, "adw_build_iso.py"),
+        issue_number,
+        adw_id,
+    ]
+    print(f"\n=== ISOLATED BUILD PHASE ===")
+    print(f"Running: {' '.join(build_cmd)}")
+    build = subprocess.run(build_cmd)
+    if build.returncode != 0:
+        print("Isolated build phase failed")
+        sys.exit(1)
+
+    # Run isolated test with the ADW ID
+    test_cmd = [
+        "uv",
+        "run",
+        os.path.join(script_dir, "adw_test_iso.py"),
+        issue_number,
+        adw_id,
+    ]
+    if skip_e2e:
+        test_cmd.append("--skip-e2e")
+    
+    print(f"\n=== ISOLATED TEST PHASE ===")
+    print(f"Running: {' '.join(test_cmd)}")
+    test = subprocess.run(test_cmd)
+    if test.returncode != 0:
+        print("Isolated test phase failed")
+        sys.exit(1)
+
+    # Run isolated review with the ADW ID
+    review_cmd = [
+        "uv",
+        "run",
+        os.path.join(script_dir, "adw_review_iso.py"),
+        issue_number,
+        adw_id,
+    ]
+    if skip_resolution:
+        review_cmd.append("--skip-resolution")
+    
+    print(f"\n=== ISOLATED REVIEW PHASE ===")
+    print(f"Running: {' '.join(review_cmd)}")
+    review = subprocess.run(review_cmd)
+    if review.returncode != 0:
+        print("Isolated review phase failed")
+        sys.exit(1)
+
+    print(f"\n=== ISOLATED WORKFLOW COMPLETED ===")
+    print(f"ADW ID: {adw_id}")
+    print(f"All phases completed successfully!")
+
+
+if __name__ == "__main__":
+    main()

skills/adw-bootstrap/reference/scaled/workflows/adw_sdlc_iso.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env -S uv run
+# /// script
+# dependencies = ["python-dotenv", "pydantic"]
+# ///
+
+"""
+ADW SDLC Iso - Complete Software Development Life Cycle workflow with isolation
+
+Usage: uv run adw_sdlc_iso.py <issue-number> [adw-id] [--skip-e2e] [--skip-resolution]
+
+This script runs the complete ADW SDLC pipeline in isolation:
+1. adw_plan_iso.py - Planning phase (isolated)
+2. adw_build_iso.py - Implementation phase (isolated)
+3. adw_test_iso.py - Testing phase (isolated)
+4. adw_review_iso.py - Review phase (isolated)
+5. adw_document_iso.py - Documentation phase (isolated)
+
+The scripts are chained together via persistent state (adw_state.json).
+Each phase runs in its own git worktree with dedicated ports.
+"""
+
+import subprocess
+import sys
+import os
+
+# Add the parent directory to Python path to import modules
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from adw_modules.workflow_ops import ensure_adw_id
+
+
+def main():
+    """Main entry point."""
+    # Check for flags
+    skip_e2e = "--skip-e2e" in sys.argv
+    skip_resolution = "--skip-resolution" in sys.argv
+    
+    # Remove flags from argv
+    if skip_e2e:
+        sys.argv.remove("--skip-e2e")
+    if skip_resolution:
+        sys.argv.remove("--skip-resolution")
+    
+    if len(sys.argv) < 2:
+        print("Usage: uv run adw_sdlc_iso.py <issue-number> [adw-id] [--skip-e2e] [--skip-resolution]")
+        print("\nThis runs the complete isolated Software Development Life Cycle:")
+        print("  1. Plan (isolated)")
+        print("  2. Build (isolated)")
+        print("  3. Test (isolated)")
+        print("  4. Review (isolated)")
+        print("  5. Document (isolated)")
+        sys.exit(1)
+
+    issue_number = sys.argv[1]
+    adw_id = sys.argv[2] if len(sys.argv) > 2 else None
+
+    # Ensure ADW ID exists with initialized state
+    adw_id = ensure_adw_id(issue_number, adw_id)
+    print(f"Using ADW ID: {adw_id}")
+
+    # Get the directory where this script is located
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+
+    # Run isolated plan with the ADW ID
+    plan_cmd = [
+        "uv",
+        "run",
+        os.path.join(script_dir, "adw_plan_iso.py"),
+        issue_number,
+        adw_id,
+    ]
+    print(f"\n=== ISOLATED PLAN PHASE ===")
+    print(f"Running: {' '.join(plan_cmd)}")
+    plan = subprocess.run(plan_cmd)
+    if plan.returncode != 0:
+        print("Isolated plan phase failed")
+        sys.exit(1)
+
+    # Run isolated build with the ADW ID
+    build_cmd = [
+        "uv",
+        "run",
+        os.path.join(script_dir, "adw_build_iso.py"),
+        issue_number,
+        adw_id,
+    ]
+    print(f"\n=== ISOLATED BUILD PHASE ===")
+    print(f"Running: {' '.join(build_cmd)}")
+    build = subprocess.run(build_cmd)
+    if build.returncode != 0:
+        print("Isolated build phase failed")
+        sys.exit(1)
+
+    # Run isolated test with the ADW ID
+    test_cmd = [
+        "uv",
+        "run",
+        os.path.join(script_dir, "adw_test_iso.py"),
+        issue_number,
+        adw_id,
+        "--skip-e2e",  # Always skip E2E tests in SDLC workflows
+    ]
+    
+    print(f"\n=== ISOLATED TEST PHASE ===")
+    print(f"Running: {' '.join(test_cmd)}")
+    test = subprocess.run(test_cmd)
+    if test.returncode != 0:
+        print("Isolated test phase failed")
+        # Note: Continue anyway as some tests might be flaky
+        print("WARNING: Test phase failed but continuing with review")
+
+    # Run isolated review with the ADW ID
+    review_cmd = [
+        "uv",
+        "run",
+        os.path.join(script_dir, "adw_review_iso.py"),
+        issue_number,
+        adw_id,
+    ]
+    if skip_resolution:
+        review_cmd.append("--skip-resolution")
+    
+    print(f"\n=== ISOLATED REVIEW PHASE ===")
+    print(f"Running: {' '.join(review_cmd)}")
+    review = subprocess.run(review_cmd)
+    if review.returncode != 0:
+        print("Isolated review phase failed")
+        sys.exit(1)
+
+    # Run isolated documentation with the ADW ID
+    document_cmd = [
+        "uv",
+        "run",
+        os.path.join(script_dir, "adw_document_iso.py"),
+        issue_number,
+        adw_id,
+    ]
+    print(f"\n=== ISOLATED DOCUMENTATION PHASE ===")
+    print(f"Running: {' '.join(document_cmd)}")
+    document = subprocess.run(document_cmd)
+    if document.returncode != 0:
+        print("Isolated documentation phase failed")
+        sys.exit(1)
+
+    print(f"\n=== ISOLATED SDLC COMPLETED ===")
+    print(f"ADW ID: {adw_id}")
+    print(f"All phases completed successfully!")
+    print(f"\nWorktree location: trees/{adw_id}/")
+    print(f"To clean up: ./scripts/purge_tree.sh {adw_id}")
+
+
+if __name__ == "__main__":
+    main()

skills/adw-bootstrap/reference/scaled/workflows/adw_ship_iso.py

@@ -0,0 +1,340 @@
+#!/usr/bin/env -S uv run
+# /// script
+# dependencies = ["python-dotenv", "pydantic"]
+# ///
+
+"""
+ADW Ship Iso - AI Developer Workflow for shipping (merging) to main
+
+Usage:
+  uv run adw_ship_iso.py <issue-number> <adw-id>
+
+Workflow:
+1. Load state and validate worktree exists
+2. Validate ALL state fields are populated (not None)
+3. Perform manual git merge in main repository:
+   - Fetch latest from origin
+   - Checkout main
+   - Merge feature branch
+   - Push to origin/main
+4. Post success message to issue
+
+This workflow REQUIRES that all previous workflows have been run and that
+every field in ADWState has a value. This is our final approval step.
+
+Note: Merge operations happen in the main repository root, not in the worktree,
+to preserve the worktree's state.
+"""
+
+import sys
+import os
+import logging
+import json
+import subprocess
+from typing import Optional, Dict, Any, Tuple
+from dotenv import load_dotenv
+
+from adw_modules.state import ADWState
+from adw_modules.github import (
+    make_issue_comment,
+    get_repo_url,
+    extract_repo_path,
+)
+from adw_modules.beads_integration import is_beads_issue, close_beads_issue
+from adw_modules.workflow_ops import format_issue_message
+from adw_modules.worktree_ops import validate_worktree
+from adw_modules.data_types import ADWStateData
+
+# Setup logging
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+logger = logging.getLogger(__name__)
+
+# Agent name constant
+AGENT_SHIPPER = "shipper"
+
+
+def get_main_repo_root() -> str:
+    """Get the main repository root directory (parent of adws)."""
+    # This script is in adws/, so go up one level to get repo root
+    return os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+
+def manual_merge_to_main(branch_name: str, logger: logging.Logger) -> Tuple[bool, Optional[str]]:
+    """Manually merge a branch to main using git commands.
+    
+    This runs in the main repository root, not in a worktree.
+    
+    Args:
+        branch_name: The feature branch to merge
+        logger: Logger instance
+        
+    Returns:
+        Tuple of (success, error_message)
+    """
+    repo_root = get_main_repo_root()
+    logger.info(f"Performing manual merge in main repository: {repo_root}")
+    
+    try:
+        # Save current branch to restore later
+        result = subprocess.run(
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            capture_output=True, text=True, cwd=repo_root
+        )
+        original_branch = result.stdout.strip()
+        logger.debug(f"Original branch: {original_branch}")
+        
+        # Step 1: Fetch latest from origin
+        logger.info("Fetching latest from origin...")
+        result = subprocess.run(
+            ["git", "fetch", "origin"],
+            capture_output=True, text=True, cwd=repo_root
+        )
+        if result.returncode != 0:
+            return False, f"Failed to fetch from origin: {result.stderr}"
+        
+        # Step 2: Checkout main
+        logger.info("Checking out main branch...")
+        result = subprocess.run(
+            ["git", "checkout", "main"],
+            capture_output=True, text=True, cwd=repo_root
+        )
+        if result.returncode != 0:
+            return False, f"Failed to checkout main: {result.stderr}"
+        
+        # Step 3: Pull latest main
+        logger.info("Pulling latest main...")
+        result = subprocess.run(
+            ["git", "pull", "origin", "main"],
+            capture_output=True, text=True, cwd=repo_root
+        )
+        if result.returncode != 0:
+            # Try to restore original branch
+            subprocess.run(["git", "checkout", original_branch], cwd=repo_root)
+            return False, f"Failed to pull latest main: {result.stderr}"
+        
+        # Step 4: Merge the feature branch (no-ff to preserve all commits)
+        logger.info(f"Merging branch {branch_name} (no-ff to preserve all commits)...")
+        result = subprocess.run(
+            ["git", "merge", branch_name, "--no-ff", "-m", f"Merge branch '{branch_name}' via ADW Ship workflow"],
+            capture_output=True, text=True, cwd=repo_root
+        )
+        if result.returncode != 0:
+            # Try to restore original branch
+            subprocess.run(["git", "checkout", original_branch], cwd=repo_root)
+            return False, f"Failed to merge {branch_name}: {result.stderr}"
+        
+        # Step 5: Push to origin/main
+        logger.info("Pushing to origin/main...")
+        result = subprocess.run(
+            ["git", "push", "origin", "main"],
+            capture_output=True, text=True, cwd=repo_root
+        )
+        if result.returncode != 0:
+            # Try to restore original branch
+            subprocess.run(["git", "checkout", original_branch], cwd=repo_root)
+            return False, f"Failed to push to origin/main: {result.stderr}"
+        
+        # Step 6: Restore original branch
+        logger.info(f"Restoring original branch: {original_branch}")
+        subprocess.run(["git", "checkout", original_branch], cwd=repo_root)
+        
+        logger.info("✅ Successfully merged and pushed to main!")
+        return True, None
+        
+    except Exception as e:
+        logger.error(f"Unexpected error during merge: {e}")
+        # Try to restore original branch
+        try:
+            subprocess.run(["git", "checkout", original_branch], cwd=repo_root)
+        except:
+            pass
+        return False, str(e)
+
+
+def validate_state_completeness(state: ADWState, logger: logging.Logger) -> tuple[bool, list[str]]:
+    """Validate that all fields in ADWState have values (not None).
+    
+    Returns:
+        tuple of (is_valid, missing_fields)
+    """
+    # Get the expected fields from ADWStateData model
+    expected_fields = {
+        "adw_id",
+        "issue_number",
+        "branch_name",
+        "plan_file",
+        "issue_class",
+        "worktree_path",
+        "backend_port",
+        "frontend_port",
+    }
+    
+    missing_fields = []
+    
+    for field in expected_fields:
+        value = state.get(field)
+        if value is None:
+            missing_fields.append(field)
+            logger.warning(f"Missing required field: {field}")
+        else:
+            logger.debug(f"✓ {field}: {value}")
+    
+    return len(missing_fields) == 0, missing_fields
+
+
+def main():
+    """Main entry point."""
+    # Load environment variables
+    load_dotenv()
+    
+    # Parse command line args
+    # INTENTIONAL: adw-id is REQUIRED - we need it to find the worktree and state
+    if len(sys.argv) < 3:
+        print("Usage: uv run adw_ship_iso.py <issue-number> <adw-id>")
+        print("\nError: Both issue-number and adw-id are required")
+        print("Run the complete SDLC workflow before shipping")
+        sys.exit(1)
+    
+    issue_number = sys.argv[1]
+    adw_id = sys.argv[2]
+    
+    # Try to load existing state
+    state = ADWState.load(adw_id, logger)
+    if not state:
+        # No existing state found
+        logger.error(f"No state found for ADW ID: {adw_id}")
+        logger.error("Run the complete SDLC workflow before shipping")
+        print(f"\nError: No state found for ADW ID: {adw_id}")
+        print("Run the complete SDLC workflow before shipping")
+        sys.exit(1)
+    
+    # Update issue number from state if available
+    issue_number = state.get("issue_number", issue_number)
+    
+    # Track that this ADW workflow has run
+    state.append_adw_id("adw_ship_iso")
+    
+    logger.info(f"ADW Ship Iso starting - ID: {adw_id}, Issue: {issue_number}")
+    
+    # Check if this is a beads issue
+    is_beads = is_beads_issue(issue_number)
+    logger.info(f"Issue type: {'beads' if is_beads else 'GitHub'}")
+    
+    # Post initial status (only for GitHub issues)
+    if not is_beads:
+        make_issue_comment(
+            issue_number,
+            format_issue_message(adw_id, "ops", f"🚢 Starting ship workflow\n"
+                               f"📋 Validating state completeness...")
+        )
+    
+    # Step 1: Validate state completeness
+    logger.info("Validating state completeness...")
+    is_valid, missing_fields = validate_state_completeness(state, logger)
+    
+    if not is_valid:
+        error_msg = f"State validation failed. Missing fields: {', '.join(missing_fields)}"
+        logger.error(error_msg)
+        if not is_beads:
+            make_issue_comment(
+                issue_number,
+                format_issue_message(adw_id, AGENT_SHIPPER, f"❌ {error_msg}\n\n"
+                                   "Please ensure all workflows have been run:\n"
+                                   "- adw_plan_iso.py (creates plan_file, branch_name, issue_class)\n"
+                                   "- adw_build_iso.py (implements the plan)\n" 
+                                   "- adw_test_iso.py (runs tests)\n"
+                                   "- adw_review_iso.py (reviews implementation)\n"
+                                   "- adw_document_iso.py (generates docs)")
+            )
+        sys.exit(1)
+    
+    logger.info("✅ State validation passed - all fields have values")
+    
+    # Step 2: Validate worktree exists
+    valid, error = validate_worktree(adw_id, state)
+    if not valid:
+        logger.error(f"Worktree validation failed: {error}")
+        if not is_beads:
+            make_issue_comment(
+                issue_number,
+                format_issue_message(adw_id, AGENT_SHIPPER, f"❌ Worktree validation failed: {error}")
+            )
+        sys.exit(1)
+    
+    worktree_path = state.get("worktree_path")
+    logger.info(f"✅ Worktree validated at: {worktree_path}")
+    
+    # Step 3: Get branch name
+    branch_name = state.get("branch_name")
+    logger.info(f"Preparing to merge branch: {branch_name}")
+    
+    if not is_beads:
+        make_issue_comment(
+            issue_number,
+            format_issue_message(adw_id, AGENT_SHIPPER, f"📋 State validation complete\n"
+                               f"🔍 Preparing to merge branch: {branch_name}")
+        )
+    
+    # Step 4: Perform manual merge
+    logger.info(f"Starting manual merge of {branch_name} to main...")
+    if not is_beads:
+        make_issue_comment(
+            issue_number,
+            format_issue_message(adw_id, AGENT_SHIPPER, f"🔀 Merging {branch_name} to main...\n"
+                               "Using manual git operations in main repository")
+        )
+    
+    success, error = manual_merge_to_main(branch_name, logger)
+    
+    if not success:
+        logger.error(f"Failed to merge: {error}")
+        if not is_beads:
+            make_issue_comment(
+                issue_number,
+                format_issue_message(adw_id, AGENT_SHIPPER, f"❌ Failed to merge: {error}")
+            )
+        sys.exit(1)
+    
+    logger.info(f"✅ Successfully merged {branch_name} to main")
+
+    # Step 5: Close beads issue if applicable
+    if is_beads:
+        logger.info(f"Closing beads issue: {issue_number}")
+        success, error = close_beads_issue(
+            issue_number,
+            f"Completed via ADW {adw_id} - merged to main"
+        )
+        if not success:
+            logger.warning(f"Failed to close beads issue: {error}")
+        else:
+            logger.info(f"✅ Closed beads issue: {issue_number}")
+
+    # Step 6: Post success message (only for GitHub issues)
+    if not is_beads:
+        make_issue_comment(
+            issue_number,
+            format_issue_message(adw_id, AGENT_SHIPPER,
+                               f"🎉 **Successfully shipped!**\n\n"
+                               f"✅ Validated all state fields\n"
+                               f"✅ Merged branch `{branch_name}` to main\n"
+                               f"✅ Pushed to origin/main\n\n"
+                               f"🚢 Code has been deployed to production!")
+        )
+
+    # Save final state
+    state.save("adw_ship_iso")
+
+    # Post final state summary (only for GitHub issues)
+    if not is_beads:
+        make_issue_comment(
+            issue_number,
+            f"{adw_id}_ops: 📋 Final ship state:\n```json\n{json.dumps(state.data, indent=2)}\n```"
+        )
+
+    logger.info("Ship workflow completed successfully")
+
+
+if __name__ == "__main__":
+    main()