feat(dev): add agentic dev setup

Author: HardeepAsrani

.github/ISSUE_TEMPLATE/agent_task.yml

@@ -0,0 +1,46 @@
+name: "Agent Task"
+description: "Structured task for coding agents"
+labels: ["agent"]
+body:
+  - type: textarea
+    id: goal
+    attributes:
+      label: Goal / Acceptance Criteria
+      description: "What does 'done' look like? Be specific."
+      placeholder: "Example: Update E2E docs to use npm run env:up/env:down and ensure credentials match bin/cli-setup.sh."
+    validations:
+      required: true
+
+  - type: textarea
+    id: constraints
+    attributes:
+      label: Constraints / Do Not Touch
+      description: "List files/areas to avoid or any guardrails."
+      placeholder: "Example: Do not edit build outputs directly; do not change vendor/ or node_modules/."
+    validations:
+      required: false
+
+  - type: textarea
+    id: relevant_files
+    attributes:
+      label: Relevant Files (if known)
+      description: "Optional: point the agent to likely files."
+      placeholder: "Example: tests/e2e/README.md, AGENTS.md"
+    validations:
+      required: false
+
+  - type: textarea
+    id: tests
+    attributes:
+      label: Tests to Run
+      description: "Default is PHPUnit + E2E unless explicitly scoped out."
+      value: |
+        Default:
+        - composer lint
+        - composer phpstan
+        - ./vendor/bin/phpunit
+        - npm run env:up
+        - npm run test:e2e:playwright
+        - npm run env:down
+    validations:
+      required: true

.github/workflows/copilot-setup-steps.yml

@@ -0,0 +1,51 @@
+name: "Copilot Setup Steps"
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
+jobs:
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+    services:
+      mysql:
+        image: mysql:5.7
+        env:
+          MYSQL_ROOT_PASSWORD: root
+        ports:
+          - 3306:3306
+        options: --health-cmd="mysqladmin ping" --health-interval=10s --health-timeout=5s --health-retries=3
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "18"
+          cache: "npm"
+
+      - name: Install JavaScript dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: "7.4"
+          extensions: simplexml, mysql
+
+      - name: Install PHP dependencies
+        run: composer install
+
+      - name: Pre-pull E2E Docker images
+        run: docker compose -f docker-compose.ci.yml pull

AGENTS.md

@@ -39,6 +39,41 @@ npm run dev                         # Watch mode for development
 
 ---
 
+## Agent Quickstart
+
+### Copilot Coding Agent Environment
+This repo includes `.github/workflows/copilot-setup-steps.yml` to preinstall dependencies for Copilot Coding Agent. This workflow is not part of normal CI and only prepares the agent environment. Note: Copilot only uses it once it exists on the default branch.
+
+### Standard Test Sequence
+1. `composer lint`
+2. `composer phpstan`
+3. `./vendor/bin/phpunit`
+4. `npm ci` (if deps missing)
+5. `npm run gutenberg:build`
+6. `npm run chartbuilder:build`
+7. `npm run d3renderer:build`
+8. `npm run env:up`
+9. `npm run test:e2e:playwright`
+10. `npm run env:down`
+
+### E2E Environment
+- Default: Docker via `npm run env:up` / `npm run env:down` (uses `docker-compose.ci.yml`).
+- Optional: `wp-env` is supported, but Docker is the default for agents.
+
+### Build Outputs
+If you change anything under `classes/Visualizer/**/src`, you must run the corresponding build and commit the output:
+- Gutenberg: `npm run gutenberg:build`
+- ChartBuilder: `npm run chartbuilder:build`
+- D3Renderer: `npm run d3renderer:build`
+
+### Do / Don't
+- Do: keep changes scoped to the task and run the standard test sequence.
+- Do: update both classic and Gutenberg editor paths when changing settings UI.
+- Don't: edit build artifacts directly (edit `src`, then build).
+- Don't: modify `vendor/` or `node_modules/`.
+
+---
+
 ## Architecture Overview
 
 ### Bootstrapping (`index.php`)

bin/run-e2e-tests-default.sh

@@ -1,5 +1,8 @@
 #!/usr/bin/env bash
+set -euo pipefail
 
+export DOCKER_FILE=${DOCKER_FILE:-docker-compose.ci.yml}
 
-
-
+npm run env:up
+npm run test:e2e:playwright
+npm run env:down

bin/run-e2e-tests-gutenberg-datatable.sh

@@ -1,6 +1,11 @@
 #!/usr/bin/env bash
-docker compose -f $DOCKER_FILE run  --rm -u root cli bash -c "wp --allow-root plugin deactivate classic-editor"
+# NOTE: This script only toggles plugin state for Gutenberg DataTable variants.
+# It does not run tests. Use bin/run-e2e-tests-default.sh for a full run.
+# Requires the environment to be up.
+set -euo pipefail
 
+export DOCKER_FILE=${DOCKER_FILE:-docker-compose.ci.yml}
+docker compose -f $DOCKER_FILE run --rm -u root cli bash -c "wp --allow-root plugin deactivate classic-editor"
 
 
 

bin/run-e2e-tests-gutenberg.sh

@@ -1,2 +1,8 @@
 #!/usr/bin/env bash
-docker compose -f $DOCKER_FILE run  --rm -u root cli bash -c "wp --allow-root plugin deactivate classic-editor"
+# NOTE: This script only toggles plugin state for Gutenberg E2E variants.
+# It does not run tests. Use bin/run-e2e-tests-default.sh for a full run.
+# Requires the environment to be up.
+set -euo pipefail
+
+export DOCKER_FILE=${DOCKER_FILE:-docker-compose.ci.yml}
+docker compose -f $DOCKER_FILE run --rm -u root cli bash -c "wp --allow-root plugin deactivate classic-editor"

skills/unit.md

@@ -5,9 +5,19 @@ Run the PHPUnit test suite for the Visualizer free plugin.
 ## Commands
 
 ```bash
+# Ensure MySQL is running and accessible (default: 127.0.0.1:3306).
+# Example (macOS/Homebrew):
+# brew services start mysql
+# Example (Linux):
+# sudo service mysql start
+
 # Install PHP dependencies if not already done
 composer install
 
+# Install WordPress test suite (required for phpunit)
+# Format: bash bin/install-wp-tests.sh <db_name> <db_user> <db_pass> <db_host> [wp_version]
+bash bin/install-wp-tests.sh wordpress_test root root 127.0.0.1
+
 # Run the full PHPUnit suite
 ./vendor/bin/phpunit
 
@@ -18,8 +28,9 @@ composer install
 ## Instructions
 
 1. Check that `vendor/` exists. If not, run `composer install` first.
-2. Run the tests. Show output as it streams.
-3. Report a summary: how many tests passed, failed, and any error messages.
-4. If the user specified a particular test file or test name, run only that:
+2. Ensure the WordPress test suite is installed using `bin/install-wp-tests.sh`.
+3. Run the tests. Show output as it streams.
+4. Report a summary: how many tests passed, failed, and any error messages.
+5. If the user specified a particular test file or test name, run only that:
    - Single file: `./vendor/bin/phpunit tests/test-<name>.php`
    - Single test method: `./vendor/bin/phpunit --filter testMethodName`

tests/e2e/README.md

@@ -14,17 +14,24 @@ npx playwright install
 Create the testing instance using the following command:
 
 ```bash
-npm run ci:up
+npm run env:up
 ```
 
 This will create a WordPress instance. The port is `8889` and the user is `admin` and the password is `password` (the same values used by `wp-env` testing instance).
+If you see port `8080`, ignore it for E2E; the test environment is expected at `http://localhost:8889`.
 
 For the _headless_ mode, use the following command:
 
 ```bash
 npm run test:e2e:playwright
 ```
 
+Tear down the environment when finished:
+
+```bash
+npm run env:down
+```
+
 For _debug_ mode (which will open the browser along with Playwright Editor), use the following command:
 
 ```bash
@@ -42,6 +49,18 @@ For database connection, the credentials are:
 - Password: `password`
 - Port: `3306`
 
+### Build requirements
+
+If you change any sources under `classes/Visualizer/**/src`, run the matching build before E2E:
+
+- `npm run gutenberg:build`
+- `npm run chartbuilder:build`
+- `npm run d3renderer:build`
+
+### Docker file
+
+The E2E environment uses `docker-compose.ci.yml` (via `npm run env:up`).
+
 > [!NOTE]
 > You can modify the credentials in the `docker-compose.yml` file.