bug-setup

/bugflow:bug-setup — Configuration Wizard

Sets up the Bugflow plugin for the current project by generating environment.json and playwright.json configuration files.

When to Run

• First time using Bugflow in a project
• When environment details change (URLs, credentials, Slack channel)
• When $ARGUMENTS contains --reconfigure

Prerequisites

• The Bugflow plugin must be installed and enabled

Process

Step 0: Check Existing Configuration

Check if .claude/bugflow/config/environment.json already exists in the project root.

• If it exists AND $ARGUMENTS does NOT contain --reconfigure: Inform the user that configuration already exists and ask if they want to reconfigure. If no, exit.
• If it exists AND $ARGUMENTS contains --reconfigure: Proceed with reconfiguration, showing current values as defaults.
• If it does not exist: Proceed with first-time setup.

Step 1: Collect Bugzilla Configuration

Ask the user using AskUserQuestion:

Question 1: "What is your Bugzilla server URL?"

• Options: Common patterns like https://bugzilla.example.com, http://bugzilla.internal
• The user will likely provide a custom URL via "Other"

Store as bugzillaUrl.

Step 2: Collect Application Configuration

Ask the user using AskUserQuestion:

Question 1: "What is your application's production URL?"

• Example: https://app.example.com/myapp/

Question 2: "What is your application's development URL?"

• Example: http://localhost:3000/ or http://localhost:8080/myapp/

Store as appProductionUrl and appDevUrl.

Step 3: Collect Credentials

Ask the user using AskUserQuestion:

Question 1: "What username and password should be used to log into your application for testing?"

• Explain: These are stored locally in .claude/bugflow/config/ and auto-added to .gitignore

Question 2: "What are your Bugzilla login credentials (email and password)?"

• Explain: Used for scraping bug data and posting comments

Store as appUsername, appPassword, bugzillaEmail, bugzillaPassword.

Step 4: Collect Login Form Selectors

Ask the user using AskUserQuestion:

Question: "What CSS selectors identify your application's login form fields?"

• Provide sensible defaults: #username, #password, button[type='submit']
• Explain: These are used by the verification agent to log into your app during browser tests

Store as loginUsernameSelector, loginPasswordSelector, loginSubmitSelector.

Step 5: Collect Slack Configuration (Optional)

Ask the user using AskUserQuestion:

Question: "Would you like to enable Slack notifications?"

• Options:
  • "Yes, I have a Slack channel ID ready"
  • "No, skip Slack notifications"

If yes, ask for the Slack channel ID.

Store as slackChannelId and slackChannelName (or null if skipped).

Step 6: Collect Path Preferences

Ask the user using AskUserQuestion:

Question: "Where should workflow state and dossier files be stored?"

• Options:
  • "Use defaults (.bugflow/ and docs/bugflow/)" (Recommended)
  • "Let me specify custom paths"

Store as stateDir and dossierDir.

Step 7: Generate Configuration Files

1. Create directory: mkdir -p .claude/bugflow/config

2. Generate .claude/bugflow/config/environment.json:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Environment Configuration",
    "description": "Generated by /bugflow:bug-setup. Do NOT commit this file.",
    "version": "1.0.0",

    "_usage": {
        "note": "Commands and agents read from this file for environment-specific values",
        "path": ".claude/bugflow/config/environment.json"
    },

    "slack": {
        "channelId": "<slackChannelId or 'DISABLED'>",
        "channelName": "<slackChannelName or 'N/A'>",
        "description": "Channel for workflow notifications"
    },

    "bugzilla": {
        "baseUrl": "<bugzillaUrl>",
        "showBugUrl": "<bugzillaUrl>/show_bug.cgi",
        "description": "Bugzilla server URLs"
    },

    "app": {
        "productionUrl": "<appProductionUrl>",
        "developmentUrl": "<appDevUrl>",
        "description": "Application URLs for verification tests"
    },

    "git": {
        "branchPrefix": "bug/",
        "branchPattern": "bug/<bugId>-<slug>",
        "description": "Git branch naming conventions"
    },

    "workflow": {
        "lockExpiryHours": 4,
        "maxPlanRevisions": 3,
        "maxVerifyRetries": 2,
        "description": "Workflow behavior configuration"
    },

    "paths": {
        "stateDir": "<stateDir>",
        "dossierDir": "<dossierDir>",
        "logsDir": "<stateDir>/_logs",
        "patternsDir": "<stateDir>/_shared/patterns",
        "description": "Standard paths for workflow artifacts"
    }
}

3. Generate .claude/bugflow/config/playwright.json:

{
    "baseUrl": "<appProductionUrl base (protocol + host)>",
    "appPath": "<appProductionUrl path component>",
    "credentials": {
        "username": "<appUsername>",
        "password": "<appPassword>"
    },
    "options": {
        "ignoreHTTPSErrors": <true if appProductionUrl uses https with self-signed cert, false otherwise>
    },
    "sessionManagement": {
        "reuseContext": true,
        "maxRetries": 3,
        "loginTimeout": 5000,
        "actionTimeout": 2000,
        "maxSessionsPerUser": 5
    },
    "instrumentation": {
        "prefix": "[BUGFIX-",
        "suffix": "]",
        "blockStart": "// INSTRUMENTATION BLOCK - Bug",
        "blockEnd": "// END INSTRUMENTATION BLOCK"
    },
    "selectors": {
        "loginForm": {
            "username": "<loginUsernameSelector>",
            "password": "<loginPasswordSelector>",
            "submitButton": "<loginSubmitSelector>"
        },
        "app": {}
    },
    "verification": {
        "maxIterations": 3,
        "retryDelay": 1000,
        "cleanupRequired": true
    },
    "bugzilla": {
        "baseUrl": "<bugzillaUrl>",
        "credentials": {
            "email": "<bugzillaEmail>",
            "password": "<bugzillaPassword>"
        },
        "selectors": {
            "loginEmail": "input[name='Bugzilla_login']",
            "loginPassword": "input[name='Bugzilla_password']",
            "loginButton": "input[type='submit'][value='Log in']",
            "commentTextarea": "#comment",
            "saveButton": "#commit",
            "statusDropdown": "select[name='bug_status']"
        }
    }
}

Step 8: Update .gitignore

Check if .gitignore exists in the project root.

• If it exists, check if .claude/bugflow/config/ is already listed. If not, append:

  # Bugflow plugin config (contains credentials)
  .claude/bugflow/config/environment.json
  .claude/bugflow/config/playwright.json
  

• If .gitignore does not exist, create it with the above content.

Step 9: Create State Directory Structure

mkdir -p <stateDir>
mkdir -p <stateDir>/_logs
mkdir -p <stateDir>/_shared/patterns
mkdir -p <dossierDir>

Step 10: Verify and Confirm

Display a summary to the user:

Bugflow Configuration Complete!

  Bugzilla:     <bugzillaUrl>
  App (prod):   <appProductionUrl>
  App (dev):    <appDevUrl>
  Slack:        <slackChannelId or "Disabled">
  State dir:    <stateDir>
  Dossier dir:  <dossierDir>

Config files:
  .claude/bugflow/config/environment.json
  .claude/bugflow/config/playwright.json

Added to .gitignore (credential protection).

You can now run:
  /bugflow:bug-start <bug-id>    Start a bug workflow
  /bugflow:bug-setup --reconfigure    Change these settings

Error Handling

• If the user cancels at any step, exit gracefully without creating partial configs
• If directory creation fails, report the error clearly
• If .gitignore update fails, warn the user to add the entries manually