@abarcenas/ai-workflow-template 1.45.0 → 1.47.0

package/AGENTS.md

@@ -9,10 +9,14 @@ This project includes AI-assisted development configuration distributed through
 - `.opencode/agents/` — Specialized agent definitions for planning, research, and implementation
 - `.agents/prompts/` — Reusable prompt templates
 
+## Project-Specific Rules
+
+Put project-specific agent rules in `AGENTS.project.md` at the repository root. That file is project-owned: sync never overwrites or prunes it, and `--force` cannot replace it. New projects load it automatically through the `instructions` entry in `opencode.json`.
+
 ## Core Workflow
 
 1. **Understand before acting** — Read relevant instructions from `.agents/instructions/` before working with specific technologies
-2. **Plan before implementing** — Use `.opencode/agents/plan.agent.md` or `.opencode/agents/implementer.agent.md` patterns for structured work
+2. **Plan before implementing** — Narrow underspecified work with the `scope` agent first, then use the `.opencode/agents/plan.agent.md` (optional deep planning) or `.opencode/agents/implementer.agent.md` patterns for structured work
 3. **Track progress** — Update `memory-bank/activeContext.md` and `memory-bank/progress.md` after each task (see `.agents/instructions/task-implementation.instructions.md`)
 4. **Maintain context** — Keep memory bank files updated (see `.agents/instructions/memory-bank.instructions.md`)
 
@@ -41,7 +45,7 @@ This project includes AI-assisted development configuration distributed through
 
 ## Available Skills
 
-Skills in `.agents/skills/` provide structured workflows for common tasks. Load them when the task matches the skill's purpose:
+All 34 skills installed in `.agents/skills/` are listed below. Load one when the task matches its purpose. The five scoping skills (`domain-modeling`, `grill-me`, `grill-with-docs`, `grilling`, `prototype`) are described in detail in [`## Agent skills`](#agent-skills).
 
 - `architecture-blueprint-generator` — Generate project architecture blueprints
 - `conventional-commit` — Create conventional commit messages
@@ -69,6 +73,14 @@ Skills in `.agents/skills/` provide structured workflows for common tasks. Load
 - `caveman-stats` — Tracking and statistics for caveman usage
 - `cavecrew` — Multi-agent coordination for caveman skills
 - `compress` — General compression utilities
+- `domain-modeling` — Build and sharpen the project's domain model (`GLOSSARY.md`, ADRs)
+- `graphify-framework-aware` — Exclude framework boilerplate from graphify knowledge graphs
+- `grill-me` — Human-invoked router for a relentless interview (calls `grilling`)
+- `grill-with-docs` — Human-invoked router for the interview plus glossary/ADR writing
+- `grilling` — Stress-test a plan or idea with rounds of numbered questions
+- `lighthouse-cli` — Run Lighthouse performance, accessibility, and SEO audits
+- `memory-search` — Semantic vector search over the memory bank
+- `prototype` — Build a throwaway prototype to answer a design question
 
 ## Available Prompts
 
@@ -79,13 +91,44 @@ Prompts in `.agents/prompts/` can be invoked directly:
 - `playwright-generate-test` — Generate Playwright tests
 - `documentation-writer` — Write documentation (Diataxis framework)
 
+## Agent skills
+
+Five skills installed from `mattpocock/skills` (pinned at `v1.3.1`) drive scoping and design work. They sit beside the other skills in `.agents/skills/`; this section explains when to reach for them and what they pair with.
+
+### Skills
+
+| Skill | Path | Use it when |
+|-------|------|-------------|
+| `grilling` | `.agents/skills/grilling/SKILL.md` | A plan, decision, or idea needs stress-testing, or a request is too vague to plan. Works a design tree in rounds: the current frontier is asked as numbered questions, each with a recommended answer. |
+| `grill-me` | `.agents/skills/grill-me/SKILL.md` | You want the same interview with no repository context and no document output — a stateless, one-shot entry point. |
+| `grill-with-docs` | `.agents/skills/grill-with-docs/SKILL.md` | You want the interview plus the written record — the glossary and ADRs are created as decisions settle. |
+| `domain-modeling` | `.agents/skills/domain-modeling/SKILL.md` | Project terminology or an architectural decision is being introduced or changed and `GLOSSARY.md` or an ADR needs to capture it. |
+| `prototype` | `.agents/skills/prototype/SKILL.md` | A design question can only be settled by running throwaway code — the logic branch for state models and data flow, the UI branch for look and feel. |
+
+`grill-me` and `grill-with-docs` are **human-invoked routers**: both set `disable-model-invocation: true`, so an agent cannot load them. Agents invoke `grilling` directly, plus `domain-modeling` when a term or decision actually settles.
+
+### Scope agent
+
+`.opencode/agents/scope.agent.md` is the front door for underspecified work. It runs `grilling` in rounds against a single draft file, emits each round's frontier as numbered questions with a recommended answer per question, and stops when the frontier is empty or the remaining unknowns are explicitly deferred.
+
+It terminates by writing `docs/spike-<feature>.md` — the spike document `.opencode/agents/researcher.agent.md` already expects as its input. From there the work continues to `researcher` (open questions need evidence), `implementer` (scope settled, planning remains), or `architect` (the shape of the system is the open problem).
+
+The agent has no command-execution permission: it never builds, runs, or tests code. When a question can only be settled empirically it emits `prototype needed: <question>` with a branch, and that work is handed off to `coder` (logic) or `designer` (UI).
+
+### Domain docs
+
+`.agents/config/domain.md` declares where domain documentation lives: `GLOSSARY.md` at the repository root and ADRs in `docs/adr/`, numbered `0001-slug.md` onwards — the single-context layout.
+The `domain-modeling` skill reads it before exploring the codebase; when the file or the docs it names are absent, the skill proceeds silently and creates them lazily, only once a term or decision has actually been settled.
+
 ## Available Agent Workflows
 
 These agent workflows (from `.opencode/agents/`) define specialized modes of operation. Invoke the relevant workflow at the start of a task by stating which mode you want to activate.
 
 ### Plan Mode — Strategic Planning & Architecture
 
-Use this when starting a new feature, refactoring, or any non-trivial change. Follow this sequence:
+Underspecified work does not start here. The default front door is the **`scope` agent** (see [`## Agent skills`](#agent-skills)): it narrows the request through grilling rounds and writes `docs/spike-<feature>.md`, which is handed to `researcher` when open questions need evidence, or to `implementer` when only planning remains.
+
+`.opencode/agents/plan.agent.md` remains available as an **optional deep-planning mode** for work that is already scoped but needs a step-by-step plan. It is not deleted and not deprecated — it is demoted in the default flow only. When you use it, follow this sequence:
 
 1. **Understand the Goal** — Ask clarifying questions about requirements and goals
 2. **Explore Context** — Examine relevant files, components, and systems that will be affected

package/README.md

@@ -52,7 +52,7 @@ npx ai-workflow-setup --help           # Show all options
 
 ## What This Package Does
 
-- **29 specialized AI skills**, framework instructions, and prompt templates (`.agents/`)
+- **34 specialized AI skills**, framework instructions, and prompt templates (`.agents/`)
 - **Smart agent frameworks** — Plan Mode, Implementation Plans, Research Spikes
 - **Multi-agent orchestrator** — dynamic pipelines with 10+ specialized sub-agents
 - **TDD orchestrator** — strict RED→GREEN→REFACTOR/VERIFY pipeline (90% coverage gate)
@@ -75,8 +75,29 @@ npm run sync                # Normal sync
 - New files are copied automatically
 - Unmodified files are refreshed from the package
 - Locally edited files are preserved (skipped by default)
+- Project-owned files are never overwritten or pruned after creation, and `--force` cannot replace them
 - GitHub Actions workflows are excluded from consumer sync (`.github/workflows/`)
 
+> `--dry-run` previews copies and prunes, but missing scaffold files (memory-bank stubs, `opencode.json`, `AGENTS.project.md`, `.prettierignore`) are still created. This matches the pre-existing scaffold behaviour.
+
+### Project-owned files
+
+`AGENTS.project.md` is the supported home for project-specific agent rules. It is created if absent, then treated as project-owned: sync never overwrites or prunes it, `--force` cannot replace it, and deleting it recreates it on the next sync. New projects load it through `"instructions": ["AGENTS.project.md"]` in `opencode.json`; a project created before that entry existed must add it once, because sync never rewrites an existing `opencode.json`.
+
+The same ownership rule protects `opencode.json`, `.prettierignore`, and `.agents/instructions/learned-knowledge.instructions.md`. `.agents-sync-ignore` is also protected from overwrite and deletion, but sync does **not** read or honour its contents yet — do not rely on it.
+
+`__project__/<file>` entries in `.agents-sync-manifest.json` are reporting metadata written only when sync creates the file. Files that already existed before the upgrade are intentionally absent, because sync has no managed baseline for them.
+
+The package ships a `.prettierignore` and scaffolds it when absent. New projects get coverage automatically for `.agents/`, `.opencode/agents/`, `.opencode/commands/`, `AGENTS.md`, `skills-lock.json`, and every synced script; the shipped file also ignores `AGENTS.project.md`, though that file is not hash-managed. Existing projects keep their own `.prettierignore` untouched (it is project-owned), so if it does not cover every managed path sync prints one warning:
+
+```text
+[ai-workflow-template] Existing .prettierignore does not protect managed files; merge the patterns from node_modules/@abarcenas/ai-workflow-template/.prettierignore
+```
+
+Merge those patterns manually — sync never edits the file. Template-side additions to `rootFiles` or `scriptsToSync` also require a matching manual line in an existing project; the shipped file only updates the defaults for new projects. A formatter run over managed files rewrites their hashes, so every later sync skips them and the consumer stops receiving template updates.
+
+If sync warns `Skipped locally modified root file: AGENTS.md`, move those local rules into `AGENTS.project.md`, restore the managed file from `node_modules/@abarcenas/ai-workflow-template/AGENTS.md`, then re-run sync.
+
 ## Core Structure
 
 Post-install, your project receives this structure:
@@ -84,12 +105,13 @@ Post-install, your project receives this structure:
 ```text
 .agents/
 ├── instructions/   # Framework, workflow, and security guidance
-├── skills/         # 29 specialized AI skills
+├── skills/         # 34 specialized AI skills
 └── prompts/        # Reusable prompt templates
 .opencode/agents/   # Orchestrator + specialized sub-agents
 .github/workflows/  # CI/CD automation (excluded from sync)
 docs/               # Guides (e.g. playwright-mcp-configuration.md)
 AGENTS.md           # Master instruction file with agent guidance
+AGENTS.project.md   # Project-owned rules (recreated if deleted, never overwritten)
 ```
 
 ## Multi-Agent Orchestrator
@@ -99,6 +121,7 @@ AGENTS.md           # Master instruction file with agent guidance
 | Agent | File | Role |
 | --- | --- | --- |
 | Orchestrator | `.opencode/agents/orchestrator/orchestrator.agent.md` | Master — analyzes requests, builds pipelines, delegates |
+| Scope | `.opencode/agents/scope.agent.md` | Conditional front door for underspecified requests — grilling rounds, then a spike doc |
 | Researcher | `.opencode/agents/researcher.agent.md` | Technical investigation, library evaluation |
 | Architect | `.opencode/agents/architect.agent.md` | System design, component architecture |
 | Implementer | `.opencode/agents/implementer.agent.md` | Translates designs into implementation plans |
@@ -121,6 +144,7 @@ Invoke the orchestrator with `@orchestrator` followed by your task:
 ```
 
 - **Run flow:** auto-bootstraps architecture on first run → builds a pipeline → executes agents sequentially (confirm/skip each step, or enable auto-confirm) → tracker documents to `docs/tracker-log.md` → persists new knowledge.
+- **Scope step (conditional, runs first):** inserted at the front of the pipeline only when the request is underspecified — `scope` runs grilling rounds against a draft file, writes `docs/spike-<feature>.md`, then hands off to `researcher` or `implementer`. Always interactive (auto-confirm cannot skip it) and has **no command-execution permission** — prototypes are delegated to `coder` (logic) or `designer` (UI).
 - **First run only:** runs the architecture-blueprint-generator skill to detect tech stack/patterns, writing context to `docs/.architecture-context.md` and `.agents/instructions/learned-knowledge.instructions.md`; later runs skip this.
 
 ### MCP Tooling
@@ -222,6 +246,7 @@ All memory-bank files use YAML frontmatter (`id`, `title`, `updated`, `tags`, `e
 
 ## Featured Skills
 
+- **Feature scoping:** `grilling`, `grill-me`, `grill-with-docs`, `domain-modeling`, `prototype` — narrow underspecified requests into a spike; `GLOSSARY.md` and `docs/adr/` locations come from `.agents/config/domain.md`
 - **Workflow automation:** `architecture-blueprint-generator`, `create-implementation-plan`, `create-readme`, `context-map`, `graphify` (global skill), `graphify-framework-aware`
 - **Development tools:** `playwright-explore-website`, `playwright-generate-test`, `github-issues`, `gh-cli`, `polygot-test-agent`, `microsoft-docs`
 - **Token & efficiency:** `caveman`, `caveman-compress`, `compress`, `caveman-commit`, `cavecrew`, `caveman-stats`
@@ -283,6 +308,8 @@ npm run memory:normalize   # Normalize frontmatter (runs automatically on instal
 
 - Uses `INIT_CWD` to install against the consuming project (not the package dir)
 - Local changes are always preserved unless `--force` is used
+- Project-owned files (`AGENTS.project.md`, `opencode.json`, `.prettierignore`, learned knowledge) are created if absent and never overwritten or pruned after that, even with `--force`
+- Do not add `AGENTS.project.md` or `opencode.json` to `package.json` `files`: both are scaffolded create-if-absent and must never ship from the package
 - `AGENTS.md` is the main instruction file agents should read
 - Package assumes the public npm registry
 - Playwright MCP integration is documented in `docs/`

package/opencode.mcp.example.json

@@ -1,5 +1,6 @@
 {
   "$schema": "https://opencode.ai/config.json",
+  "instructions": ["AGENTS.project.md"],
   "mcp": {
     "chrome-devtools": {
       "type": "local",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abarcenas/ai-workflow-template",
-  "version": "1.45.0",
+  "version": "1.47.0",
   "description": "A comprehensive template repository for AI-assisted development workflows using GitHub Copilot. This template provides a structured approach to leveraging AI assistance through pre-configured skills, prompts, agents, and coding standards.",
   "main": "index.js",
   "bin": {
@@ -38,6 +38,7 @@
     "url": "https://github.com/abarcenas29/ai-workflow-template/issues"
   },
   "homepage": "https://github.com/abarcenas29/ai-workflow-template#readme",
+  "//": "Never add AGENTS.project.md or opencode.json to files: both are scaffolded create-if-absent at the consumer root and must not ship from the package.",
   "files": [
     "bin/",
     ".agents/",
@@ -49,6 +50,7 @@
     ".husky/",
     "memory-bank/.vocabulary.json",
     "AGENTS.md",
+    ".prettierignore",
     "opencode.mcp.example.json",
     "skills-lock.json",
     ".husky/post-merge",

package/scripts/bump-version.test.js

@@ -0,0 +1,238 @@
+// ═════════════════════════════════════════════════════════════════════════════
+// bump-version.test.js — Unit tests for the pre-commit version bumper
+// ═════════════════════════════════════════════════════════════════════════════
+//
+// bump-version.js is a top-level script: it reads package.json on import,
+// derives the previous major version from `git show HEAD:package.json`, writes
+// the new version, and stages the file.  Tests therefore mock `fs` and
+// `child_process` so the repository's real package.json is never touched, then
+// re-import the module for each scenario with `vi.resetModules()`.
+//
+// Covered scenarios:
+//   1.  SKIP_BUMP=1                      → logs skip, exits 0, no fs/git calls
+//   2.  SKIP_BUMP=yes                     → same (any non-empty value is truthy)
+//   3.  SKIP_BUMP=0                       → same (string "0" is truthy in Node)
+//   4.  SKIP_BUMP=""                      → falsy, bump proceeds
+//   5.  Minor bump (same major)           → 1.4.7 → 1.5.0
+//   6.  Minor bump with multi-digit minor → 1.10.3 → 1.11.0
+//   7.  No HEAD (git show fails)          → falls back to current major, bumps minor
+//   8.  Major changed                     → 3.2.1 → 3.0.0
+//   9.  Exact serialisation              → 2-space JSON + trailing newline, fields preserved
+//  10.  Git commands                     → `git show HEAD:package.json` then `git add package.json`
+// ═════════════════════════════════════════════════════════════════════════════
+
+import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest'
+
+vi.mock('fs', () => ({
+  readFileSync: vi.fn(),
+  writeFileSync: vi.fn(),
+}))
+
+vi.mock('child_process', () => ({
+  execSync: vi.fn(),
+}))
+
+import { readFileSync, writeFileSync } from 'fs'
+import { execSync } from 'child_process'
+
+const EXIT_SENTINEL = new Error('__process_exit__')
+
+/**
+ * Re-imports bump-version.js with the current mock state.
+ *
+ * @returns {Promise<void>}
+ */
+async function loadModule() {
+  vi.resetModules()
+  await import('./bump-version.js')
+}
+
+/**
+ * Wires the fs/git mocks for a normal (non-skip) run.
+ *
+ * @param {object}   opts
+ * @param {object}   opts.pkg          - Contents returned for package.json.
+ * @param {object}   [opts.prevPkg]    - Contents returned for HEAD:package.json.
+ * @param {boolean}  [opts.noHead]     - When true, `git show` throws.
+ */
+function mockNormalRun({ pkg, prevPkg, noHead = false }) {
+  readFileSync.mockReturnValue(JSON.stringify(pkg))
+  execSync.mockImplementation((cmd) => {
+    if (cmd === 'git show HEAD:package.json') {
+      if (noHead) throw new Error('fatal: invalid object name HEAD')
+      return JSON.stringify(prevPkg)
+    }
+    return ''
+  })
+}
+
+describe('bump-version.js', () => {
+  let logSpy
+  let exitSpy
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    delete process.env.SKIP_BUMP
+    logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    delete process.env.SKIP_BUMP
+    logSpy.mockRestore()
+    exitSpy.mockRestore()
+  })
+
+  // ── SKIP_BUMP guard ──────────────────────────────────────────────────────
+
+  it('SKIP_BUMP=1: logs skip message, exits 0, touches nothing', async () => {
+    process.env.SKIP_BUMP = '1'
+    exitSpy.mockImplementation(() => {
+      throw EXIT_SENTINEL
+    })
+
+    await expect(loadModule()).rejects.toBe(EXIT_SENTINEL)
+
+    expect(logSpy).toHaveBeenCalledWith('SKIP_BUMP set — version bump skipped')
+    expect(exitSpy).toHaveBeenCalledWith(0)
+    expect(readFileSync).not.toHaveBeenCalled()
+    expect(writeFileSync).not.toHaveBeenCalled()
+    expect(execSync).not.toHaveBeenCalled()
+  })
+
+  it('SKIP_BUMP=yes: any non-empty value skips the bump', async () => {
+    process.env.SKIP_BUMP = 'yes'
+    exitSpy.mockImplementation(() => {
+      throw EXIT_SENTINEL
+    })
+
+    await expect(loadModule()).rejects.toBe(EXIT_SENTINEL)
+
+    expect(exitSpy).toHaveBeenCalledWith(0)
+    expect(writeFileSync).not.toHaveBeenCalled()
+  })
+
+  it('SKIP_BUMP=0: the string "0" is truthy, so the bump is skipped', async () => {
+    process.env.SKIP_BUMP = '0'
+    exitSpy.mockImplementation(() => {
+      throw EXIT_SENTINEL
+    })
+
+    await expect(loadModule()).rejects.toBe(EXIT_SENTINEL)
+
+    expect(exitSpy).toHaveBeenCalledWith(0)
+    expect(execSync).not.toHaveBeenCalled()
+  })
+
+  it('SKIP_BUMP="": empty string is falsy, so the bump proceeds', async () => {
+    process.env.SKIP_BUMP = ''
+    mockNormalRun({
+      pkg: { name: 'fixture', version: '1.4.7' },
+      prevPkg: { version: '1.4.0' },
+    })
+
+    await loadModule()
+
+    expect(exitSpy).not.toHaveBeenCalled()
+    expect(logSpy).toHaveBeenCalledWith('Version bumped: 1.4.7 → 1.5.0')
+  })
+
+  // ── Version arithmetic ───────────────────────────────────────────────────
+
+  it('same major: bumps the minor and resets the patch', async () => {
+    mockNormalRun({
+      pkg: { name: 'fixture', version: '1.4.7' },
+      prevPkg: { version: '1.4.0' },
+    })
+
+    await loadModule()
+
+    const written = JSON.parse(writeFileSync.mock.calls[0][1])
+    expect(written.version).toBe('1.5.0')
+  })
+
+  it('multi-digit minor: increments numerically (1.10.3 → 1.11.0)', async () => {
+    mockNormalRun({
+      pkg: { name: 'fixture', version: '1.10.3' },
+      prevPkg: { version: '1.9.9' },
+    })
+
+    await loadModule()
+
+    expect(logSpy).toHaveBeenCalledWith('Version bumped: 1.10.3 → 1.11.0')
+  })
+
+  it('no HEAD yet: catch path keeps the current major and bumps the minor', async () => {
+    mockNormalRun({
+      pkg: { name: 'fixture', version: '2.3.1' },
+      noHead: true,
+    })
+
+    await loadModule()
+
+    expect(logSpy).toHaveBeenCalledWith('Version bumped: 2.3.1 → 2.4.0')
+  })
+
+  it('major changed: normalises to N.0.0', async () => {
+    mockNormalRun({
+      pkg: { name: 'fixture', version: '3.2.1' },
+      prevPkg: { version: '2.9.9' },
+    })
+
+    await loadModule()
+
+    expect(logSpy).toHaveBeenCalledWith('Version bumped: 3.2.1 → 3.0.0')
+  })
+
+  // ── Serialisation and git side-effects ───────────────────────────────────
+
+  it('writes 2-space JSON with a trailing newline and preserves other fields', async () => {
+    const pkg = {
+      name: 'fixture',
+      version: '1.4.7',
+      scripts: { test: 'vitest' },
+      keywords: ['a', 'b'],
+    }
+    mockNormalRun({ pkg, prevPkg: { version: '1.0.0' } })
+
+    await loadModule()
+
+    const [path, contents] = writeFileSync.mock.calls[0]
+    expect(path).toMatch(/package\.json$/)
+    expect(contents.endsWith('\n')).toBe(true)
+    expect(contents).toBe(
+      JSON.stringify({ ...pkg, version: '1.5.0' }, null, 2) + '\n',
+    )
+  })
+
+  it('reads HEAD:package.json then stages package.json', async () => {
+    mockNormalRun({
+      pkg: { name: 'fixture', version: '0.9.2' },
+      prevPkg: { version: '0.9.0' },
+    })
+
+    await loadModule()
+
+    expect(execSync).toHaveBeenNthCalledWith(
+      1,
+      'git show HEAD:package.json',
+      { encoding: 'utf8' },
+    )
+    expect(execSync).toHaveBeenNthCalledWith(2, 'git add package.json')
+    expect(execSync).toHaveBeenCalledTimes(2)
+  })
+
+  it('reads package.json from the package root', async () => {
+    mockNormalRun({
+      pkg: { name: 'fixture', version: '1.0.0' },
+      prevPkg: { version: '1.0.0' },
+    })
+
+    await loadModule()
+
+    expect(readFileSync).toHaveBeenCalledWith(
+      expect.stringMatching(/package\.json$/),
+      'utf8',
+    )
+  })
+})

package/scripts/mcp/playwright-mcp-launcher.js

@@ -6,41 +6,67 @@
  * based on environment variables and project settings.
  */
 
-const { spawn } = require('child_process');
-const path = require('path');
+import { spawn } from 'node:child_process'
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
 
-// Get environment variables
-const headless = process.env.HEADLESS === 'true';
-const slowMo = process.env.SLOW_MO ? parseInt(process.env.SLOW_MO) : 0;
+/**
+ * Builds the `npx @playwright/mcp@latest` argument list from the environment.
+ *
+ * @param {NodeJS.ProcessEnv} [env=process.env] - Environment to read.
+ * @returns {string[]} Arguments passed to `npx`.
+ */
+export function buildArgs(env = process.env) {
+  const args = ['@playwright/mcp@latest']
 
-// Build command arguments
-const args = ['@playwright/mcp@latest'];
+  if (env.HEADLESS === 'true') {
+    args.push('--headless')
+  }
 
-// Add headless flag if needed
-if (headless) {
-  args.push('--headless');
-}
+  if (env.VIEWPORT) {
+    args.push('--viewport', env.VIEWPORT)
+  }
 
-// Add viewport size if specified
-if (process.env.VIEWPORT) {
-  args.push('--viewport', process.env.VIEWPORT);
+  return args
 }
 
-// Launch the MCP server
-const child = spawn('npx', args, {
-  stdio: 'inherit',
-  shell: true
-});
+/**
+ * Spawns the Playwright MCP server and forwards signals / exit codes.
+ *
+ * @param {object}   [options]
+ * @param {object}   [options.env=process.env] - Environment to read.
+ * @param {object}   [options.proc=process]    - Process-like emitter for signals.
+ * @param {Function} [options.exit=process.exit] - Exit function.
+ * @returns {import('node:child_process').ChildProcess} The spawned child.
+ */
+export function launch({
+  env = process.env,
+  proc = process,
+  exit = process.exit,
+} = {}) {
+  const child = spawn('npx', buildArgs(env), {
+    stdio: 'inherit',
+    shell: true,
+  })
+
+  proc.on('SIGINT', () => {
+    child.kill('SIGINT')
+  })
+
+  proc.on('SIGTERM', () => {
+    child.kill('SIGTERM')
+  })
 
-// Handle process signals
-process.on('SIGINT', () => {
-  child.kill('SIGINT');
-});
+  child.on('exit', (code) => {
+    exit(code || 0)
+  })
 
-process.on('SIGTERM', () => {
-  child.kill('SIGTERM');
-});
+  return child
+}
 
-child.on('exit', (code) => {
-  process.exit(code || 0);
-});
+const isDirectRun =
+  process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+
+if (isDirectRun) {
+  launch()
+}