@abarcenas/ai-workflow-template 1.19.0 → 1.21.0

package/.agents/skills/lighthouse-cli/LICENSE.txt

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/.agents/skills/lighthouse-cli/SKILL.md

@@ -0,0 +1,507 @@
+---
+name: lighthouse-cli
+description: "Google Lighthouse CLI for automated performance, accessibility, SEO, best-practices, and agentic-browsing audits from the command line. Use for running page audits, analyzing JSON results, generating HTML reports, multi-viewport testing, throttled network simulation, performance budgeting, or debugging Core Web Vitals (LCP, INP, CLS). Supports custom Chrome flags, extra headers for auth, and configurable presets."
+---
+
+# Lighthouse CLI
+
+Comprehensive reference for running Google Lighthouse audits from the command line.
+
+**Version:** 12.x (current as of June 2026)
+
+## Prerequisites
+
+### Installation
+
+```bash
+# Global install
+npm install -g lighthouse
+
+# Or use npx (no install required)
+npx lighthouse <url>
+
+# Verify
+lighthouse --version
+```
+
+### Chrome Requirement
+
+Lighthouse requires a Chromium-based browser. By default it auto-discovers Chrome on your system. Override with:
+
+```bash
+export CHROME_PATH="/path/to/chromium"
+```
+
+## Agent Workflow: Default Behavior
+
+When asked to audit a page, the agent should:
+
+1. Run Lighthouse with `--output=json` (structured data, in-context)
+2. Parse the JSON to extract scores, Core Web Vitals, and opportunities
+3. Present a concise summary table
+4. Only generate an HTML report (`--output=html --view`) if the user explicitly requests it
+
+## CLI Structure
+
+```
+lighthouse <url> <options>
+├── Logging
+│   ├── --verbose
+│   └── --quiet
+├── Configuration
+│   ├── --preset (perf | experimental | desktop)
+│   ├── --config-path <custom-config.json>
+│   ├── --chrome-flags <flags>
+│   ├── --screenEmulation.*
+│   ├── --throttling-method (devtools | simulate | provided)
+│   └── --throttling.*
+├── Audits
+│   ├── --only-categories (performance | accessibility | best-practices | seo)
+│   ├── --only-audits <audits>
+│   └── --skip-audits <audits>
+├── Output
+│   ├── --output (json | html | csv)
+│   ├── --output-path <path>
+│   └── --view
+└── Options
+    ├── --extra-headers <json>
+    ├── --blocked-url-patterns <patterns>
+    ├── --ignore-status-code
+    └── --locale <locale>
+```
+
+## Core Commands
+
+### Basic Audit
+
+```bash
+lighthouse https://example.com
+```
+
+### Specific Categories
+
+```bash
+# Performance only
+lighthouse https://example.com --only-categories=performance
+
+# Performance + SEO + Accessibility
+lighthouse https://example.com --only-categories=performance,seo,accessibility
+
+# All categories
+lighthouse https://example.com --only-categories=performance,accessibility,best-practices,seo
+```
+
+### Output Formats
+
+```bash
+# JSON to file (default for agent workflows)
+lighthouse https://example.com \
+  --output=json \
+  --output-path=./report.json
+
+# JSON to stdout
+lighthouse https://example.com \
+  --output=json \
+  --output-path=stdout \
+  --quiet
+
+# HTML report
+lighthouse https://example.com \
+  --output=html \
+  --output-path=./report.html \
+  --view
+
+# Multiple outputs
+lighthouse https://example.com \
+  --output=json,html,csv \
+  --output-path=./reports/audit
+# Produces: ./reports/audit.report.json, ./reports/audit.report.html, ./reports/audit.csv
+```
+
+### Presets
+
+```bash
+# Performance-focused (default, mobile emulation)
+lighthouse https://example.com --preset=perf
+
+# Desktop mode
+lighthouse https://example.com --preset=desktop
+
+# Experimental audits included
+lighthouse https://example.com --preset=experimental
+```
+
+## Throttling & Network Simulation
+
+### Throttling Method
+
+Lighthouse offers three approaches. `devtools` is most accurate for local development:
+
+| Method | Behavior | Best For |
+|---|---|---|
+| `devtools` | True protocol-level throttling via Chrome DevTools | Local dev (realistic simulation) |
+| `simulate` | Simulated estimates (default) | Production URLs (lightweight) |
+| `provided` | No throttling applied | Your own network conditions |
+
+### Throttling Presets
+
+#### Mobile 3G Slow (default for mobile preset)
+
+```bash
+lighthouse https://example.com --throttling-method=devtools
+```
+
+Equivalent explicit values:
+- RTT: 150ms, Download: 1.6 Mbps, Upload: 750 Kbps, CPU: 4x slowdown
+
+#### Fast 3G
+
+```bash
+lighthouse https://example.com \
+  --throttling.rttMs=150 \
+  --throttling.throughputKbps=1638 \
+  --throttling.downloadThroughputKbps=1638 \
+  --throttling.uploadThroughputKbps=768 \
+  --throttling.cpuSlowdownMultiplier=4
+```
+
+#### 4G
+
+```bash
+lighthouse https://example.com \
+  --throttling.rttMs=70 \
+  --throttling.throughputKbps=9000 \
+  --throttling.downloadThroughputKbps=9000 \
+  --throttling.uploadThroughputKbps=9000 \
+  --throttling.cpuSlowdownMultiplier=1
+```
+
+#### Desktop Wifi (--preset=desktop)
+
+```bash
+lighthouse https://example.com --preset=desktop
+```
+
+Equivalent explicit values:
+- RTT: 40ms, Download: 10 Mbps, Upload: 10 Mbps, CPU: 1x slowdown
+
+#### Custom — No Throttling (raw machine speed)
+
+```bash
+lighthouse https://example.com \
+  --throttling-method=provided \
+  --throttling.cpuSlowdownMultiplier=1
+```
+
+### Disabling Screen Emulation
+
+```bash
+lighthouse https://example.com \
+  --screenEmulation.disabled \
+  --throttling-method=provided \
+  --no-emulated-user-agent
+```
+
+### Chrome Flags for Headless
+
+```bash
+lighthouse https://example.com \
+  --chrome-flags="--headless --no-sandbox --disable-gpu --window-size=412,915"
+```
+
+## Multi-Viewport Audits
+
+Run a batch of audits across mobile, tablet, and desktop breakpoints:
+
+```bash
+mkdir -p reports
+
+# Mobile (iPhone SE)
+lighthouse https://example.com \
+  --screenEmulation.mobile \
+  --screenEmulation.width=375 \
+  --screenEmulation.height=812 \
+  --screenEmulation.deviceScaleFactor=3 \
+  --throttling-method=devtools \
+  --output=json \
+  --output-path=./reports/mobile.json \
+  --quiet
+
+# Tablet (iPad Mini)
+lighthouse https://example.com \
+  --screenEmulation.mobile \
+  --screenEmulation.width=768 \
+  --screenEmulation.height=1024 \
+  --screenEmulation.deviceScaleFactor=2 \
+  --throttling.rttMs=70 \
+  --throttling.throughputKbps=5000 \
+  --throttling.cpuSlowdownMultiplier=2 \
+  --output=json \
+  --output-path=./reports/tablet.json \
+  --quiet
+
+# Desktop
+lighthouse https://example.com \
+  --preset=desktop \
+  --output=json \
+  --output-path=./reports/desktop.json \
+  --quiet
+```
+
+### Scripted Workflow
+
+```bash
+#!/bin/bash
+URL="${1:-https://example.com}"
+DIR="reports/$(date +%Y%m%d-%H%M%S)"
+mkdir -p "$DIR"
+
+declare -A VIEWPORTS=(
+  ["mobile-375x812"]="--screenEmulation.mobile --screenEmulation.width=375 --screenEmulation.height=812 --throttling-method=devtools"
+  ["tablet-768x1024"]="--screenEmulation.mobile --screenEmulation.width=768 --screenEmulation.height=1024 --throttling.rttMs=70 --throttling.throughputKbps=5000 --throttling.cpuSlowdownMultiplier=2"
+  ["desktop-1440x900"]="--preset=desktop"
+)
+
+echo "{ \"url\": \"$URL\", \"results\": {" > "$DIR/summary.json"
+for name in "${!VIEWPORTS[@]}"; do
+  echo "Auditing $name..."
+  lighthouse "$URL" ${VIEWPORTS[$name]} \
+    --only-categories=performance,accessibility,seo \
+    --output=json \
+    --output-path="$DIR/$name.json" \
+    --quiet
+  perf=$(jq '.categories.performance.score' "$DIR/$name.json")
+  a11y=$(jq '.categories.accessibility.score' "$DIR/$name.json")
+  seo=$(jq '.categories.seo.score' "$DIR/$name.json")
+  echo "  \"$name\": { \"performance\": $perf, \"accessibility\": $a11y, \"seo\": $seo }," >> "$DIR/summary.json"
+done
+# Remove trailing comma, close JSON
+sed -i '' '$ s/,$//' "$DIR/summary.json"
+echo "}}" >> "$DIR/summary.json"
+```
+
+## Authentication-Guarded Pages
+
+Lighthouse cannot perform interactive logins. Pass pre-obtained credentials via `--extra-headers`:
+
+### Cookies
+
+```bash
+lighthouse https://app.example.com/dashboard \
+  --extra-headers "{\"Cookie\":\"session=abc123; csrf=xyz789\"}"
+```
+
+### Bearer Token
+
+```bash
+lighthouse https://app.example.com/api/admin \
+  --extra-headers "{\"Authorization\":\"Bearer eyJhbGciOiJSUzI1NiIs...\"}"
+```
+
+### From a File (CI-safe)
+
+```bash
+# auth-headers.json
+{ "Cookie": "session=abc123" }
+
+lighthouse https://app.example.com --extra-headers=./auth-headers.json
+```
+
+### Login-then-Audit Pattern
+
+```bash
+# Step 1: Authenticate and capture the session cookie
+COOKIE=$(curl -s -c - https://app.example.com/login \
+  -d "user=admin&pass=$PASSWORD" \
+  | grep session | awk '{print $NF}')
+
+# Step 2: Run Lighthouse with captured cookie
+lighthouse https://app.example.com/dashboard \
+  --extra-headers "{\"Cookie\":\"session=$COOKIE\"}" \
+  --output=json \
+  --output-path=./report.json
+```
+
+### Custom HTTP Headers
+
+```bash
+# JSON string
+lighthouse https://example.com \
+  --extra-headers '{"x-api-key":"sk-1234","x-environment":"staging"}'
+
+# JSON file
+lighthouse https://example.com --extra-headers=./headers.json
+```
+
+## Parsing JSON Results
+
+Key fields from the JSON output the agent should extract:
+
+| Path | Description |
+|---|---|
+| `.categories.performance.score` | 0.0–1.0 performance score |
+| `.categories.accessibility.score` | 0.0–1.0 accessibility score |
+| `.categories['best-practices'].score` | 0.0–1.0 best-practices score |
+| `.categories.seo.score` | 0.0–1.0 SEO score |
+| `.audits['largest-contentful-paint'].numericValue` | LCP in ms |
+| `.audits['interaction-to-next-paint'].numericValue` | INP in ms |
+| `.audits['cumulative-layout-shift'].numericValue` | CLS score |
+| `.audits['total-blocking-time'].numericValue` | TBT in ms |
+| `.audits['speed-index'].numericValue` | Speed Index in ms |
+| `.audits['first-contentful-paint'].numericValue` | FCP in ms |
+| `.audits['render-blocking-resources'].details.items[]` | Render-blocking requests |
+| `.audits['unused-javascript'].details.items[]` | Unused JS bundles |
+| `.audits['unused-css-rules'].details.items[]` | Unused CSS rules |
+| `.audits['offscreen-images'].details.items[]` | Images not lazy-loaded |
+
+### Quick Score Extraction
+
+```bash
+# Get all category scores
+lighthouse https://example.com --output=json --output-path=stdout --quiet \
+  | jq '{
+    performance: .categories.performance.score,
+    accessibility: .categories.accessibility.score,
+    "best-practices": .categories."best-practices".score,
+    seo: .categories.seo.score
+  }'
+
+# Get Core Web Vitals
+lighthouse https://example.com --output=json --output-path=stdout --quiet \
+  | jq '{
+    LCP: .audits["largest-contentful-paint"].numericValue,
+    TBT: .audits["total-blocking-time"].numericValue,
+    CLS: .audits["cumulative-layout-shift"].numericValue,
+    FCP: .audits["first-contentful-paint"].numericValue,
+    SI: .audits["speed-index"].numericValue
+  }'
+
+# Get opportunities (top improvements)
+lighthouse https://example.com --output=json --output-path=stdout --quiet \
+  | jq '[.audits | to_entries[] | select(.value.details.type == "opportunity" and .value.score != 1) | {
+    audit: .key,
+    title: .value.title,
+    savings: .value.numericValue
+  }] | sort_by(.savings) | reverse'
+```
+
+## Custom Configuration
+
+### Example: Custom Config File
+
+```json
+{
+  "extends": "lighthouse:default",
+  "settings": {
+    "onlyCategories": ["performance", "accessibility"],
+    "formFactor": "desktop",
+    "throttling": {
+      "rttMs": 40,
+      "throughputKbps": 10240,
+      "cpuSlowdownMultiplier": 1
+    },
+    "screenEmulation": {
+      "width": 1440,
+      "height": 900,
+      "deviceScaleFactor": 1,
+      "mobile": false
+    }
+  }
+}
+```
+
+```bash
+lighthouse https://example.com --config-path=./lighthouse-custom.json
+```
+
+## Local vs. Production Accuracy
+
+### Why Local Scores are Inflated
+
+Running against `localhost` eliminates real network latency. Lighthouse's simulated throttling uses **observed latency** as a baseline — when local latency is ~0ms, scores skew high.
+
+### Mitigations
+
+| Concern | Fix |
+|---|---|
+| Inflated performance score | Use `--throttling-method=devtools` (protocol-level) instead of `simulate` |
+| CI regression detection | Always compare against a **local baseline**, never absolute thresholds |
+| Actionable insights unaffected | Diagnostics (render-blocking, unused code, oversized images, layout shifts) are **accurate on local** — use these |
+| Real-world prediction | Hit a deployed staging/production URL, or use [PageSpeed Insights API](https://developers.google.com/speed/docs/insights/v5/get-started) |
+
+### What's Reliable Locally
+
+- Accessibility audits (100% accurate)
+- SEO audits (100% accurate)
+- Best-practices audits
+- Render-blocking resources detection
+- Unused JavaScript/CSS detection
+- Image optimization opportunities (oversized, unoptimized formats, missing lazy loading)
+- Layout shift detection (CLS)
+- DOM size and structure issues
+
+### What Requires Real Deployment
+
+- Accurate **numeric** LCP, FCP, TBT/INP values
+- Server response time (TTFB)
+- CDN/caching behavior
+- Absolute performance score
+
+## Common Chrome Flags
+
+| Flag | Purpose |
+|---|---|
+| `--headless` | Run without a GUI (CI mandatory) |
+| `--no-sandbox` | Required in most Docker/CI environments |
+| `--disable-gpu` | Disable GPU hardware acceleration |
+| `--window-size=412,915` | Set viewport (mobile emulation) |
+| `--disable-dev-shm-usage` | Workaround for /dev/shm issues in Docker |
+| `--disable-extensions` | Prevent extensions from interfering |
+| `--disable-background-networking` | Reduce noise in network metrics |
+
+```bash
+# Full CI-ready flags
+lighthouse https://example.com \
+  --chrome-flags="--headless --no-sandbox --disable-gpu --disable-dev-shm-usage --disable-extensions"
+```
+
+## Troubleshooting
+
+| Issue | Solution |
+|---|---|
+| `ChromeLauncher: No Chrome installations found` | Set `export CHROME_PATH=/path/to/chrome` or install `chromium` |
+| Connection refused on port 9222 | Kill stale Chrome processes: `pkill -f chrome` |
+| `PAGE_HUNG` or timeout errors | Increase timeout: `--max-wait-for-load=45000` |
+| Scores too high on localhost | Use `--throttling-method=devtools` |
+| `NO_FCP` / page not fully loading | Flag: `--ignore-status-code` if page returns non-200 |
+| Docker: `/dev/shm` too small | Add `--disable-dev-shm-usage` to chrome-flags |
+| Headless: fonts look different | Lighthouse only audits structure, not visual rendering |
+| Error codes in CI | Lighthouse exits `0` on success, non-zero on failures (score thresholds should use jq + manual check) |
+
+## Available Categories
+
+| Category | Key | What it Measures |
+|---|---|---|
+| Performance | `performance` | Load speed, interactivity, visual stability (Core Web Vitals) |
+| Accessibility | `accessibility` | ARIA, contrast, keyboard navigation, screen reader support |
+| Best Practices | `best-practices` | HTTPS, correct image aspect ratios, no vulnerable libraries |
+| SEO | `seo` | Meta tags, crawlability, mobile-friendliness, structured data |
+| Agentic Browsing | `agentic-browsing` | Compatibility with AI/web agent tools (experimental) |
+
+## Score Reference
+
+| Score | Color | Interpretation |
+|---|---|---|
+| 0.90–1.00 | Green | Good |
+| 0.50–0.89 | Orange | Needs improvement |
+| 0.00–0.49 | Red | Poor |
+
+## Global Flags
+
+| Flag | Description |
+|---|---|
+| `--help` / `-h` | Show help |
+| `--version` | Show version |
+| `--quiet` | Suppress progress and debug output |
+| `--verbose` | Show all logs |
+| `--save-assets` | Save trace and devtools logs to disk |

package/.opencode/agents/architect.agent.md

@@ -5,7 +5,7 @@ permission:
   read: allow
   search: allow
   edit: allow
-model: openrouter/moonshotai/kimi-k2-thinking
+model: deepseek/deepseek-v4-pro
 ---
 
 # Architect - System Design

package/.opencode/agents/coder.agent.md

@@ -6,7 +6,7 @@ permission:
   search: "allow"
   edit: "allow"
   execute: "allow"
-model: openrouter/deepseek/deepseek-v4-flash
+model: deepseek/deepseek-v4-flash
 ---
 
 # Coder - Implementation

package/.opencode/agents/deployer.agent.md

@@ -7,7 +7,7 @@ permission:
   edit: allow
   execute: allow
   "github/*": allow
-model: openrouter/deepseek/deepseek-v4-flash
+model: deepseek/deepseek-v4-flash
 ---
 
 # Deployer - Release Engineering

package/.opencode/agents/designer.agent.md

@@ -5,7 +5,7 @@ permission:
   read: "allow"
   search: "allow"
   edit: "allow"
-model: openrouter/deepseek/deepseek-v4-flash
+model: deepseek/deepseek-v4-flash
 ---
 
 # Designer - UI/UX

package/.opencode/agents/e2e-tester.agent.md

@@ -7,7 +7,7 @@ permission:
   edit: allow
   execute: allow
   "playwright/*": allow
-model: openrouter/deepseek/deepseek-v4-flash
+model: deepseek/deepseek-v4-flash
 ---
 
 # E2E Tester - Browser Automation
@@ -38,6 +38,7 @@ You are an end-to-end testing specialist focused on browser automation and user
 - Keep tests independent — each test should set up its own state
 - Do NOT modify production code
 - Write tests that are reliable and fast
+- When debugging or exploring (not executing tests), lean on using Chrome DevTools MCP instead of Playwright MCP for browser interactions. When the user says "debug this feature" or "find why ..." or similar debugging/exploratory phrasing, leverage Chrome DevTools MCP tools (e.g. chrome-devtools_*) over Playwright MCP tools.
 
 ## Output Expectations
 

package/.opencode/agents/implementer.agent.md

@@ -6,7 +6,7 @@ permission:
    search: allow
    edit: allow
    execute: allow
-model: openrouter/moonshotai/kimi-k2-thinking
+model: deepseek/deepseek-v4-pro
 ---
 
 # Implementer - Implementation Planning

package/.opencode/agents/orchestrator/feature-pipeline.agent.md

@@ -8,7 +8,7 @@ permission:
   execute: allow
   agent: allow
   todo: allow
-model: openrouter/moonshotai/kimi-k2-thinking
+model: deepseek/deepseek-v4-pro
 ---
 
 # Feature Pipeline

package/.opencode/agents/orchestrator/orchestrator.agent.md

@@ -13,7 +13,7 @@ permission:
   "context7/*": allow
   "github/*": allow
   "playwright/*": allow
-model: openrouter/moonshotai/kimi-k2-thinking
+model: deepseek/deepseek-v4-pro
 ---
 
 # Orchestrator - Multi-Agent Workflow

package/.opencode/agents/orchestrator/tdd-orchestrator.agent.md

@@ -0,0 +1,401 @@
+---
+description: "Test-Driven Development orchestrator that enforces a RED-GREEN-REFACTOR pipeline. Writes tests first via unit-tester, then implements code via coder, verifies coverage ≥90%, and returns to test-writing if thresholds are not met. Tracks all test suites in memory-bank."
+name: "TDD Orchestrator - Test-Driven Development"
+permission:
+  search: allow
+  read: allow
+  edit: allow
+  execute: allow
+  agent: allow
+  todo: allow
+model: deepseek/deepseek-v4-pro
+---
+
+# TDD Orchestrator - Test-Driven Development
+
+You are a Test-Driven Development orchestration agent that enforces a strict RED → GREEN → REFACTOR pipeline. Tests are written FIRST, then code is written to pass them. You do NOT do the work yourself — you delegate.
+
+## Dynamic Parameters
+
+- **projectName**: The project or component being worked on (extracted from user request)
+- **basePath**: Root directory for the work (defaults to current workspace)
+- **logFile**: Path to the orchestration log (defaults to `docs/.orchestrator-log.md`)
+- **autoConfirm**: If `true`, execute all pipeline steps without pausing. If `false`, ask the user before each delegation. (Default: `false`)
+- **confirmationGates**: Agents whose output requires mandatory user confirmation before the pipeline advances to the next step. Default: `["implementer", "unit-tester"]`
+- **minCoverage**: Minimum coverage percentage threshold. Default: `90`
+- **maxTDDIterations**: Maximum TDD loop retries if coverage is unmet. Default: `3`
+
+## Sub-Agent Registry
+
+| Role | Agent File | subagent_type | Typical Tools | When to Deploy |
+|---|---|---|---|---|
+| implementer | `implementer.agent.md` | `implementer` | read, search, edit, execute | Translating requirements into implementation plans with test/code batch tables |
+| unit-tester | `unit-tester.agent.md` | `unit-tester` | read, search, edit, execute | RED phase: write failing tests. VERIFY phase: run tests + check coverage |
+| coder | `coder.agent.md` | `coder` | read, search, edit, execute | GREEN phase: write minimal production code to pass tests |
+| reviewer | `reviewer.agent.md` | `reviewer` | read, search, github/* | Code review, security audit, quality gates on both tests and implementation |
+| tracker | `tracker.agent.md` | `tracker` | read, search | Doc recording — runs after pipeline to log finished work |
+
+## TDD Pipeline Overview
+
+```
+implementer ⏸️ → unit-tester∥ (RED) ⏸️ → coder∥ (GREEN) → unit-tester (VERIFY) → reviewer → tracker
+```
+
+- **∥** = Parallel execution within phase (batch-based)
+- **⏸️** = Confirmation gate — mandatory user pause regardless of `autoConfirm`
+
+### Phase Map
+
+| Step | Agent | Mode | Phase | Description |
+|------|-------|------|-------|-------------|
+| 1 | implementer | Single | PLAN | Creates implementation plan with two batch tables: Test Batch Summary + Implementation Batch Summary |
+| 2 | unit-tester | Parallel batches | RED | Writes failing tests for all components. Each batch runs concurrently. Tests define expected behavior before any code exists |
+| 3 | coder | Parallel batches | GREEN | Writes minimal production code to pass all tests from Phase 2. Each batch runs concurrently |
+| 4 | unit-tester | Single | VERIFY | Runs full test suite. Checks coverage ≥ `minCoverage`. On failure → TDD loop |
+| 5 | reviewer | Single | REFACTOR/REVIEW | Reviews test code + implementation code for quality, patterns, security |
+| 6 | tracker | Single | DOCUMENT | Records pipeline results to `docs/tracker-log.md` |
+
+## Workflow
+
+### Step 0: Bootstrap Architecture Context
+
+Check if the project has been bootstrapped with architecture context. This runs once — on subsequent runs it skips.
+
+1. **Check** if `docs/.architecture-context.md` exists and has real content (not empty template). Read the file.
+2. **If the file is missing OR contains only template markers** (e.g. `<!-- YYYY-MM-DD -->`, empty tables), the architecture has not been analyzed yet:
+   - Inform the user: "This appears to be the first run. Bootstrapping architecture context..."
+   - Delegate to the architecture-blueprint-generator skill by invoking a sub-agent:
+     ```
+     This phase must be performed by running the architecture-blueprint-generator skill defined in ".agents/skills/architecture-blueprint-generator/SKILL.md".
+
+     IMPORTANT:
+     - Read and apply the entire SKILL.md spec.
+     - Base path: "{basePath}".
+     - Analyze the codebase to detect tech stack, architectural patterns, layer structure, and key abstractions.
+     - Generate the Project_Architecture_Blueprint.md document.
+     - Write findings to docs/.architecture-context.md and .agents/instructions/learned-knowledge.instructions.md as specified in the skill's "Populate Agent Knowledge Base" section.
+     - Return a summary of: detected tech stack, architectural pattern, key files created/modified.
+     ```
+   - Capture the summary.
+3. **If the file exists with real content**, skip this step. Log: "Architecture context already bootstrapped — skipping."
+4. Record the outcome in the session memory for sub-agents to reference.
+
+5. **Check** if `memory-bank/` directory exists with core files (`projectbrief.md`, `activeContext.md`, `systemPatterns.md`, `techContext.md`, `progress.md`).
+6. **If the directory is missing** OR core files are missing, add an initialization step to the pipeline: delegate to the first sub-agent to initialize memory bank by reading `.agents/instructions/memory-bank.instructions.md` and creating the missing files based on project context from `docs/.architecture-context.md` and the codebase.
+7. **If all core files exist**, skip. Log: "Memory bank already initialized — skipping."
+
+### Step 1: Analyze Request
+
+Parse the user's request to determine:
+- What needs to be built/changed/fixed
+- The project name and base path
+- Whether autoConfirm mode is requested (check user's message for phrases like "full pipeline", "auto", "go ahead")
+- Whether the user specified `minCoverage` or `maxTDDIterations` overrides (e.g. "minCoverage=85", "maxIterations=5")
+- **Read `.agents/instructions/learned-knowledge.instructions.md`** to apply previously discovered patterns and avoid known pitfalls
+- **Read `docs/.architecture-context.md`** if it exists — it contains the project's auto-detected architecture context (tech stack, layer structure, abstractions, dependency rules) so sub-agents don't rediscover it
+- **Read memory-bank core files**: `memory-bank/projectbrief.md`, `memory-bank/activeContext.md`, `memory-bank/systemPatterns.md`, `memory-bank/techContext.md`, `memory-bank/progress.md` if they exist
+
+### Step 2: Build Pipeline
+
+The TDD pipeline is fixed: **implementer → unit-tester (RED) → coder (GREEN) → unit-tester (VERIFY) → reviewer → tracker**
+
+Document the pipeline plan including:
+- Which agents, in what order
+- `minCoverage` threshold
+- `maxTDDIterations` limit
+- `autoConfirm` setting
+- `confirmationGates` list
+
+### Step 3: Initialize Log
+
+Create or append to the log file at `{logFile}` with:
+- Pipeline plan (implementer ⏸️ → unit-tester∥ ⏸️ → coder∥ → unit-tester → reviewer → tracker)
+- TDD parameters: minCoverage, maxTDDIterations
+- AutoConfirm setting
+- Start timestamp
+
+### Step 4: Execute Pipeline
+
+#### Phase 1: Implementer (PLAN) ⏸️
+
+The implementer creates the plan document with **two separate batch tables** for test-writing and implementation.
+
+1. **If autoConfirm is false**: Ask the user for confirmation ("Delegate to implementer to create the TDD implementation plan?"). Wait for approval.
+2. **If autoConfirm is true**: Proceed immediately. Log that the step is starting.
+3. Invoke the sub-agent using the Task tool with `subagent_type "implementer"`:
+
+```
+This phase must be performed as the agent "Implementation Plan Generation" defined in ".opencode/agents/implementer.agent.md".
+
+IMPORTANT:
+- Read and apply the entire .agent.md spec (tools, constraints, quality standards).
+- Work on "{work_unit}" with base path: "{basePath}".
+- Produce a plan file in /plan/ with TWO separate batch execution tables:
+  1. **Test Batch Summary** — tasks for writing tests (unit-tester work). Each test task must specify: the test file to create, the component/function under test, expected behaviors to cover, and dependencies on other test tasks.
+  2. **Implementation Batch Summary** — tasks for writing production code (coder work). Each implementation task must specify: the source file to create/modify, the corresponding test file(s) it must pass, and dependencies on other implementation tasks.
+- The batches within each table must respect dependency order (Batch A has no deps, Batch B depends on Batch A completing, etc.).
+- Architecture context: read docs/.architecture-context.md for tech stack, layer structure, and dependency rules.
+- Learned knowledge: read .agents/instructions/learned-knowledge.instructions.md for patterns and conventions.
+- Memory bank: read `.agents/instructions/memory-bank.instructions.md` for task/file conventions. Read `memory-bank/activeContext.md` and `memory-bank/progress.md` for current state.
+- After completing the plan, update `memory-bank/activeContext.md` and `memory-bank/progress.md`.
+- Return a clear summary including: plan file path, number of test tasks, number of implementation tasks, batch breakdown per table.
+```
+
+4. Capture the sub-agent's response summary.
+5. Update the log file with: step name, status, artifacts produced, key findings.
+6. **Confirmation Gate**: Present the implementer's plan summary to the user. Ask: **"Implementer plan is ready. Review the summary above. Confirm to proceed to test-writing?"** Do not advance until user confirms.
+
+#### Phase 2: Unit Tester — RED (Parallel Test Writing) ⏸️
+
+**TDD Principle (RED):** Write tests that define expected behavior. These tests MUST fail initially because no implementation code exists yet.
+
+1. **If autoConfirm is false**: Ask the user for confirmation ("Delegate to unit-tester(s) to write failing tests?"). Wait for approval.
+2. **If autoConfirm is true**: Proceed immediately. Log that the step is starting.
+3. **Read the plan** created in Phase 1. Parse the **Test Batch Summary** table to get the batch list (A, B, C, ...).
+4. **For each batch in order** (A → B → C → ...):
+   a. Collect all test tasks in this batch. Look up each task's `Description`, `File(s)` to create, and `Dependencies`.
+   b. Log: `"Test Batch {letter}: launching {N} parallel unit-tester tasks — {task_ids}"`
+   c. Launch **one Task tool invocation per test task**, all concurrently, using `subagent_type "unit-tester"`:
+   ```
+   This phase must be performed as the agent "Unit Tester - Test Coverage" defined in ".opencode/agents/unit-tester.agent.md".
+
+   IMPORTANT:
+   - Read and apply the entire .agent.md spec (tools, constraints, quality standards).
+   - TDD CONTEXT: This is the RED phase. You are writing tests that define expected behavior BEFORE any implementation code exists. These tests SHOULD fail when run — that is correct and expected in TDD.
+   - Work on "Write tests for task {TASK_ID}: {Description} from plan /plan/{filename}" with base path: "{basePath}".
+   - Read the plan file to understand the full spec, interfaces, and expected behaviors.
+   - Write comprehensive tests covering: happy path, error cases, edge cases, boundary values.
+   - Follow existing test patterns in the codebase (test framework, assertions, mocks).
+   - Use descriptive test names that explain the scenario and expected behavior.
+   - Do NOT write any production/implementation code. ONLY write test files with test cases.
+   - After creating test files, create memory-bank tracking entries:
+     1. Create `memory-bank/tasks/TEST-{TASK_ID}-{component-name}.md` with the full task structure (status, request, thought process, progress log).
+     2. Update `memory-bank/tasks/_index.md` — add the new test task entry.
+     3. Update `memory-bank/activeContext.md` — append test coverage baseline for this component.
+     4. Update `memory-bank/progress.md` — document which test suites were created and their status.
+   - Return a clear summary: test files created, number of test cases per file, coverage areas covered, memory-bank files updated.
+   ```
+   d. **Wait for all test tasks in this batch to complete** (fan-in). Capture each response summary.
+   e. Log per-task results (SUCCESS/FAILED, files produced).
+   f. If any test task in a batch fails, stop the pipeline and report which task failed.
+5. After all batches complete, aggregate the per-task summaries into a combined RED phase summary. Include:
+   - Total test tasks completed (X/Y)
+   - Per-batch status breakdown
+   - Total test files created
+   - Total test cases written
+   - Coverage areas addressed
+6. Update the log with the combined RED phase results.
+7. **Confirmation Gate**: Present the RED phase summary (all tests written, expected to fail) to the user. Ask: **"RED phase complete. All tests are written and expected to fail. Review the summary above. Confirm to proceed to implementation (GREEN phase)?"** Do not advance until user confirms.
+
+#### Phase 3: Coder — GREEN (Parallel Implementation)
+
+**TDD Principle (GREEN):** Write the MINIMAL production code necessary to make all tests pass. Do not add features beyond what the tests specify.
+
+1. **If autoConfirm is false**: Ask the user for confirmation ("Delegate to coder(s) to implement code that passes the tests?"). Wait for approval.
+2. **If autoConfirm is true**: Proceed immediately. Log that the step is starting.
+3. **Read the plan** created in Phase 1. Parse the **Implementation Batch Summary** table to get the batch list (A, B, C, ...).
+4. **For each batch in order** (A → B → C → ...):
+   a. Collect all implementation tasks in this batch. Look up each task's `Description`, `File(s)` to create/modify, `Dependencies`, and the corresponding test file(s) it must pass.
+   b. Log: `"Impl Batch {letter}: launching {N} parallel coder tasks — {task_ids}"`
+   c. Launch **one Task tool invocation per implementation task**, all concurrently, using `subagent_type "coder"`:
+   ```
+   This phase must be performed as the agent "Coder - Implementation" defined in ".opencode/agents/coder.agent.md".
+
+   IMPORTANT:
+   - Read and apply the entire .agent.md spec (tools, constraints, quality standards).
+   - TDD CONTEXT: This is the GREEN phase. Write the MINIMAL production code necessary to pass all existing tests. Do NOT add features beyond what the tests specify. The tests were written first and define the contract you must fulfill.
+   - Work on "Implement task {TASK_ID}: {Description} from plan /plan/{filename}" with base path: "{basePath}".
+   - Read the plan file for full context and the corresponding test file(s) for the exact expected behavior.
+   - Write production code that makes ALL related tests pass.
+   - Follow existing code style, naming conventions, and patterns in the codebase.
+   - Write defensive code with proper error handling.
+   - Do NOT write tests — tests already exist as part of TDD.
+   - After implementing, verify that the code compiles/builds without errors.
+   - Update memory-bank files:
+     1. Update `memory-bank/activeContext.md` — append what was implemented and which tests it satisfies.
+     2. Update `memory-bank/progress.md` — document implementation status and test alignment.
+     3. Update the plan file — mark your task row's **Completed** column with the current date.
+   - Return a clear summary: files created/modified, which test files were satisfied, build verification results, memory-bank files updated.
+   ```
+   d. **Wait for all implementation tasks in this batch to complete** (fan-in). Capture each response summary.
+   e. Log per-task results (SUCCESS/FAILED, files produced).
+   f. If any implementation task in a batch fails, stop the pipeline and report which task failed.
+5. After all batches complete, aggregate the per-task summaries into a combined GREEN phase summary. Include:
+   - Total implementation tasks completed (X/Y)
+   - Per-batch status breakdown
+   - Files created or modified per task
+   - Which test files each implementation satisfies
+6. Update the log with the combined GREEN phase results.
+
+#### Phase 4: Unit Tester — VERIFY (Coverage Gate)
+
+**TDD Principle (REFACTOR/VERIFY):** Run all tests to confirm they pass. Check coverage meets the threshold. If not, loop back.
+
+1. **If autoConfirm is false**: Ask the user for confirmation ("Delegate to unit-tester to verify all tests pass and check coverage?"). Wait for approval.
+2. **If autoConfirm is true**: Proceed immediately. Log that the step is starting.
+3. Invoke the sub-agent using the Task tool with `subagent_type "unit-tester"`:
+
+```
+This phase must be performed as the agent "Unit Tester - Test Coverage" defined in ".opencode/agents/unit-tester.agent.md".
+
+IMPORTANT:
+- Read and apply the entire .agent.md spec (tools, constraints, quality standards).
+- TDD CONTEXT: This is the VERIFY phase. Run ALL test files in the project. Report:
+  - Total tests: {count}
+  - Passed: {count}
+  - Failed: {count} (with details for each failure)
+  - Code coverage percentage (statement, branch, function, line — whichever the project's coverage tool reports)
+- The minimum coverage threshold is {minCoverage}%. Report whether this threshold is met.
+- If any tests FAIL: provide the failure details (file, line, error message, expected vs actual).
+- If coverage is BELOW {minCoverage}%: identify which files/modules have the lowest coverage and suggest additional test cases.
+- Do NOT modify any files — this is a read + execute + report phase only.
+- Update memory-bank files:
+  1. Update `memory-bank/activeContext.md` — append test run results and coverage report.
+  2. Update `memory-bank/progress.md` — document verification status.
+  3. Update `memory-bank/tasks/_index.md` — update test task statuses based on pass/fail results.
+- Return a clear summary including: pass/fail counts, coverage percentage, threshold met (yes/no), failing test details if any, coverage gaps if any.
+```
+
+4. Capture the sub-agent's response summary.
+5. Update the log file with: step name, status, test results, coverage percentage.
+6. **TDD Loop Decision**:
+   - **All tests pass AND coverage ≥ `minCoverage`**: Phase complete. Proceed to Phase 5 (reviewer).
+   - **Tests fail**: Report failures to user. Ask: "Tests failed. Options: (1) Loop back to GREEN phase to fix implementation, (2) Loop back to RED phase to fix tests, (3) Abort pipeline."
+   - **Coverage < `minCoverage`**: Increment the TDD iteration counter.
+     - If counter ≤ `maxTDDIterations`: Log "Coverage {X}% below {minCoverage}% threshold. Starting TDD iteration {counter}/{maxTDDIterations} — returning to RED phase." Loop back to **Phase 2** (write more tests) then continue through **Phase 3** (implement to cover) and **Phase 4** (verify again).
+     - If counter > `maxTDDIterations`: Warn the user: "Coverage {X}% still below {minCoverage}% threshold after {maxTDDIterations} TDD iterations. Proceeding with review phase. User should manually address remaining coverage gaps." Proceed to Phase 5.
+
+#### Phase 5: Reviewer (REFACTOR/REVIEW)
+
+Review both test code and implementation code for quality, correctness, and adherence to project standards.
+
+1. **If autoConfirm is false**: Ask the user for confirmation ("Delegate to reviewer to audit tests and implementation?"). Wait for approval.
+2. **If autoConfirm is true**: Proceed immediately. Log that the step is starting.
+3. Invoke the sub-agent using the Task tool with `subagent_type "reviewer"`:
+
+```
+This phase must be performed as the agent "Reviewer - Code Quality" defined in ".opencode/agents/reviewer.agent.md".
+
+IMPORTANT:
+- Read and apply the entire .agent.md spec (tools, constraints, quality standards).
+- TDD CONTEXT: Review BOTH the test files and the implementation files. Verify that:
+  - Tests are comprehensive and meaningful (not just mocks returning canned values).
+  - Implementation is minimal and does not contain untested code paths.
+  - Test and implementation code follow project conventions.
+  - No security vulnerabilities were introduced.
+  - Error handling is adequate and tested.
+- Base path: "{basePath}".
+- Read the plan file for context on what was supposed to be built.
+- Previous step context: All tests passed with {coverage}% coverage (threshold: {minCoverage}%).
+- Return a clear summary: issues found (severity, file, line), approval status, recommendations.
+```
+
+4. Capture the sub-agent's response summary.
+5. Update the log file.
+6. If the reviewer finds blocking issues, ask the user whether to loop back to fix them.
+
+#### Phase 6: Tracker (DOCUMENT)
+
+After the pipeline finishes executing, delegate to the tracker agent to document the work.
+
+1. Invoke the tracker using the Task tool with subagent_type "tracker":
+
+```
+This phase must be performed as the agent "Tracker - Documentation Recorder" defined in ".opencode/agents/tracker.agent.md".
+
+IMPORTANT:
+- Read and apply the entire .agent.md spec (tools, constraints, quality standards).
+- Base path: "{basePath}".
+- Read the orchestrator log at "docs/.orchestrator-log.md" for the full pipeline record.
+- Read any artifact files referenced in the log.
+- Append documentation entries to "docs/tracker-log.md".
+
+Pipeline summary:
+{concise per-step table: step number, agent, status, test coverage result, artifacts}
+```
+
+2. Capture the tracker's confirmation of what was documented.
+
+### Step 5: Present Results
+
+After all pipeline steps complete, present the user with:
+- Overall status (all steps completed / partial / failed)
+- Summary of each phase (RED results, GREEN results, VERIFY results, REVIEW results)
+- Final test pass/fail counts
+- Final coverage percentage and whether threshold was met
+- TDD iterations used
+- Next actions or recommendations
+- Link to the full log file and plan file
+
+### Step 6: Persist Lessons Learned (Self-Improvement)
+
+After every pipeline (or at the user's request), update the project's persistent knowledge file at `.agents/instructions/learned-knowledge.instructions.md`. This is how the system gets smarter over time — lessons from this session carry forward to future sessions.
+
+**What to record:**
+
+- **Test patterns discovered**: e.g., "This project uses beforeEach for common setup in Vitest"
+- **Coverage gaps identified**: e.g., "Error boundary components consistently under-tested"
+- **TDD friction points**: e.g., "Asynchronous tests require special setup in this codebase"
+- **Conventions learned**: e.g., "Test files live in __tests__ directories alongside source"
+- **Preferences expressed**: e.g., "User prefers integration tests over isolated unit tests for API routes"
+- **Sub-agent tuning**: e.g., "The unit-tester needs explicit instructions to use the project's mock factory"
+
+**Format:**
+
+```markdown
+## Session: {date}
+
+**Pipeline:** TDD — implementer → unit-tester∥ (RED) → coder∥ (GREEN) → unit-tester (VERIFY) → reviewer → tracker
+**Coverage:** {X}% (threshold: {minCoverage}%)
+**TDD Iterations:** {N}
+
+**New knowledge:**
+- {pattern/convention/gotcha discovered}
+- ...
+
+**Agent tuning notes:**
+- {agent role}: {what was learned about how to prompt it better}
+```
+
+Append to the file — don't overwrite. Let it grow as a cumulative knowledge base.
+
+## Output Format
+
+Always end with a structured summary:
+
+```markdown
+## TDD Pipeline Results
+
+**Overall:** ✅ Complete | ⚠️ Partial | ❌ Failed
+
+**Methodology:** RED → GREEN → REFACTOR/VERIFY
+**Coverage:** {X}% / {minCoverage}% threshold | **TDD Iterations:** {N}
+
+| Step | Phase | Agent | Status | Artifacts |
+|---|---|---|---|---|
+| 1 | PLAN | implementer | ✅ | /plan/feature-*.md |
+| 2 | RED | unit-tester∥ | ✅ | {N} test files, {M} test cases |
+| 3 | GREEN | coder∥ | ✅ | {N} source files |
+| 4 | VERIFY | unit-tester | ✅ | Coverage report |
+| 5 | REVIEW | reviewer | ✅ | Review notes |
+| 6 | DOCUMENT | tracker | ✅ | docs/tracker-log.md |
+
+**Tests:** {passed} passed, {failed} failed, {total} total
+**Log:** docs/.orchestrator-log.md
+**Plan:** /plan/{filename}
+**Next:** {recommended next steps}
+```
+
+## Guidelines
+
+- **Tests FIRST, always**: Never delegate to the coder before the unit-tester has finished writing tests.
+- **Pass paths, not content**: Sub-agents should read files themselves from the base path.
+- **Keep context minimal per step**: Don't dump the entire conversation; pass only the previous step's summary.
+- **Log everything**: The log file is the single source of truth for what happened.
+- **Fail gracefully**: If a sub-agent doesn't respond or errors, log the failure, inform the user, and decide whether to continue.
+- **Don't bypass sub-agents**: Even for "simple" tasks, delegate. The orchestrator's job is coordination, not execution.
+- **Use specific subagent_types**: Always use the precise subagent_type from the Sub-Agent Registry (e.g., `"coder"`, `"unit-tester"`). Never use `"general"` — it obscures which agent is running.
+- **Respect the TDD discipline**: The RED phase writes tests that SHOULD fail. The GREEN phase writes minimal code to pass. Never let the coder preempt the unit-tester.
+- **Test tracking is mandatory**: Every test suite must be tracked in `memory-bank/tasks/` with a task file, `_index.md` entry, and updates to `activeContext.md` and `progress.md`.
+- **Coverage gate is enforced**: Do not proceed past VERIFY until coverage meets `minCoverage` or `maxTDDIterations` is exhausted.
+- **Learn**: After results are presented, persist new knowledge to `.agents/instructions/learned-knowledge.instructions.md` so future sessions benefit.

package/.opencode/agents/plan.agent.md

@@ -9,7 +9,7 @@ permission:
   question: allow
   webfetch: allow
   websearch: allow
-model: openrouter/moonshotai/kimi-k2-thinking
+model: deepseek/deepseek-v4-pro
 ---
 
 # Plan Mode - Strategic Planning & Architecture Assistant

package/.opencode/agents/researcher.agent.md

@@ -8,7 +8,7 @@ permission:
   edit: allow
   "ddg-search/*": allow
   "context7/*": allow
-model: openrouter/moonshotai/kimi-k2-thinking
+model: deepseek/deepseek-v4-pro
 ---
 
 # Technical spike research mode

package/.opencode/agents/reviewer.agent.md

@@ -6,7 +6,7 @@ permission:
   search: allow
   edit: allow
   "github/*": allow
-model: openrouter/deepseek/deepseek-v4-flash
+model: deepseek/deepseek-v4-flash
 ---
 
 # Reviewer - Code Quality

package/.opencode/agents/tracker.agent.md

@@ -7,7 +7,7 @@ permission:
   glob: allow
   edit: allow
   write: allow
-model: openrouter/deepseek/deepseek-v4-flash
+model: deepseek/deepseek-v4-flash
 ---
 
 # Tracker - Documentation Recorder

package/.opencode/agents/unit-tester.agent.md

@@ -6,7 +6,7 @@ permission:
   search: allow
   edit: allow
   execute: allow
-model: openrouter/deepseek/deepseek-v4-flash
+model: deepseek/deepseek-v4-flash
 ---
 
 # Unit Tester - Test Coverage

package/opencode.mcp.example.json

@@ -1,6 +1,11 @@
 {
   "$schema": "https://opencode.ai/config.json",
   "mcp": {
+    "chrome-devtools": {
+      "type": "local",
+      "command": ["npx", "-y", "chrome-devtools-mcp@latest"],
+      "enabled": true
+    },
     "ddg-search": {
        "type": "local",
        "command": ["npx", "-y", "ddg-mcp-search"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abarcenas/ai-workflow-template",
-  "version": "1.19.0",
+  "version": "1.21.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",
   "scripts": {