cellenium 0.2.0__tar.gz → 0.2.1__tar.gz

cellenium-0.2.1/.claude/commands/cellenium/artifact.md

@@ -0,0 +1,9 @@
+---
+name: artifact
+description: Turn a PRD or specification into traceable pytest tests, execute them, and evaluate their quality through the complete TestFlow pipeline.
+argument-hint: <PRD/spec path and test target>
+command: /cellenium:artifact
+---
+
+Before doing anything else, read `.claude/skills/cellenium/artifact/SKILL.md` (or `~/.claude/skills/cellenium/artifact/SKILL.md` if it is not in the project) and follow it as your instructions. Each stage it names lives in a sibling folder, e.g. `prd-reader` is `.claude/skills/cellenium/prd-reader/SKILL.md`; read a stage's SKILL.md before applying it. 
+Pass `$ARGUMENTS` as the pipeline input and complete every reachable TestFlow stage.

{cellenium-0.2.0/.claude/commands/testflow → cellenium-0.2.1/.claude/commands/cellenium}/checklist/before-startup.md

@@ -1,7 +1,7 @@
 ---
 name: before-startup
 description: System readiness check before building tests. Use before starting TestFlow or writing any test to verify that the repository, toolchain, browsers, configuration, external services, test infrastructure, baseline, and inputs are healthy and ready for test creation.
-command: /before-startup
+command: /cellenium:checklist:before-startup
 ---
 
-Invoke the Skill tool with `skill: "testflow:before-startup"` before doing anything else.
+Before doing anything else, read `.claude/skills/cellenium/before-startup/SKILL.md` (or `~/.claude/skills/cellenium/before-startup/SKILL.md` if it is not in the project) and follow it as your instructions.

{cellenium-0.2.0/.claude/commands/testflow → cellenium-0.2.1/.claude/commands/cellenium}/checklist/cruising.md

@@ -1,7 +1,7 @@
 ---
 name: cruising
 description: In-flight check while tests are being built. Use after any TestFlow stage, after writing or changing tests, or before a commit or PR to verify that everything is in place and to hunt for critical errors and potential bugs in the tests, locators, fixtures, and observed product behavior.
-command: /cruising
+command: /cellenium:checklist:cruising
 ---
 
-Invoke the Skill tool with `skill: "testflow:cruising"` before doing anything else.
+Before doing anything else, read `.claude/skills/cellenium/cruising/SKILL.md` (or `~/.claude/skills/cellenium/cruising/SKILL.md` if it is not in the project) and follow it as your instructions.

{cellenium-0.2.0/.claude/commands/testflow → cellenium-0.2.1/.claude/commands/cellenium}/checklist/fordec.md

@@ -6,7 +6,7 @@ description: |
   Use when a production outage, failed deploy, broken main branch, 
   data corruption, security incident, or other consequential engineering 
   problem needs a clear, time-aware choice, assigned actions, and active reassessment.
-command: /fordec
+command: /cellenium:checklist:fordec
 ---
 
-Invoke the Skill tool with `skill: "testflow:fordec"` before doing anything else.
+Before doing anything else, read `.claude/skills/cellenium/emergency/fordec/SKILL.md` (or `~/.claude/skills/cellenium/emergency/fordec/SKILL.md` if it is not in the project) and follow it as your instructions.

{cellenium-0.2.0/.claude/commands/testflow → cellenium-0.2.1/.claude/commands/cellenium}/checklist/landing.md

@@ -1,7 +1,7 @@
 ---
 name: landing
 description: Final production-readiness checklist. Use before final PR approval, merge, release, or production deployment to verify the final state, compare land and go-around options, make an explicit decision, define or perform the authorized execution, and check production signals with rollback triggers.
-command: /landing
+command: /cellenium:checklist:landing
 ---
 
-Invoke the Skill tool with `skill: "testflow:landing"` before doing anything else.
+Before doing anything else, read `.claude/skills/cellenium/landing/SKILL.md` (or `~/.claude/skills/cellenium/landing/SKILL.md` if it is not in the project) and follow it as your instructions.

{cellenium-0.2.0/.claude/commands/testflow → cellenium-0.2.1/.claude/commands/cellenium}/evaluator.md

@@ -2,9 +2,8 @@
 name: evaluator
 description: Evaluate pytest tests against requirements, specifications, implementation contracts, and execution evidence.
 argument-hint: <requirements, tests, and execution results>
-command: /testflow:evaluator
+command: /cellenium:evaluator
 ---
 
-Invoke the Skill tool with `skill: "testflow:evaluator"` 
-before doing anything else. Pass `$ARGUMENTS` as the evaluation 
+Before doing anything else, read `.claude/skills/cellenium/evaluator/SKILL.md` (or `~/.claude/skills/cellenium/evaluator/SKILL.md` if it is not in the project) and follow it as your instructions. Pass `$ARGUMENTS` as the evaluation 
 scope and return the coverage matrix, evidence-backed findings, residual risks, and verdict.

{cellenium-0.2.0/.claude/commands/testflow → cellenium-0.2.1/.claude/commands/cellenium}/executor.md

@@ -2,9 +2,9 @@
 name: executor
 description: Run repository-native pytest commands, preserve exact evidence, and classify collection, environment, test, and product failures.
 argument-hint: <test paths, node IDs, or markers>
-command: /testflow:executor
+command: /cellenium:executor
 ---
 
-Invoke the Skill tool with `skill: "testflow:executor"` before doing anything else. 
+Before doing anything else, read `.claude/skills/cellenium/executor/SKILL.md` (or `~/.claude/skills/cellenium/executor/SKILL.md` if it is not in the project) and follow it as your instructions. 
 Pass `$ARGUMENTS` as the requested test selection and report exact commands, 
 results, failure classifications, and verdict.

cellenium-0.2.1/.claude/commands/cellenium/locator-writer.md

@@ -0,0 +1,9 @@
+---
+name: locator-writer
+description: Discover stable Playwright locators, validate the target elements, and upsert them into the configured Google Sheets Page Object Model.
+argument-hint: <page, screen, and required elements>
+command: /cellenium:locator-writer
+---
+
+Before doing anything else, read `.claude/skills/cellenium/locator-writer/SKILL.md` (or `~/.claude/skills/cellenium/locator-writer/SKILL.md` if it is not in the project) and follow it as your instructions. Pass `$ARGUMENTS` as the UI target and element requirements. 
+Preview updates before replacing existing non-empty sheet rows.

{cellenium-0.2.0/.claude/commands/testflow → cellenium-0.2.1/.claude/commands/cellenium}/prd-reader.md

@@ -2,9 +2,8 @@
 name: prd-reader
 description: Extract testable, traceable pytest requirements from a PRD, feature brief, ticket, or acceptance criteria.
 argument-hint: <PRD path, issue, or requirements>
-command: /testflow:prd-reader
+command: /cellenium:prd-reader
 ---
 
-Invoke the Skill tool with `skill: "testflow:prd-reader"` 
-before doing anything else. Pass `$ARGUMENTS` as the product 
+Before doing anything else, read `.claude/skills/cellenium/prd-reader/SKILL.md` (or `~/.claude/skills/cellenium/prd-reader/SKILL.md` if it is not in the project) and follow it as your instructions. Pass `$ARGUMENTS` as the product 
 source and return the requirement matrix without running downstream stages.

cellenium-0.2.1/.claude/commands/cellenium/test-spec.md

@@ -0,0 +1,8 @@
+---
+name: test-spec
+description: Convert requirements and technical specifications into a complete, traceable pytest test specification.
+argument-hint: <requirements/spec path and target>
+command: /cellenium:test-spec
+---
+
+Before doing anything else, read `.claude/skills/cellenium/test-spec/SKILL.md` (or `~/.claude/skills/cellenium/test-spec/SKILL.md` if it is not in the project) and follow it as your instructions. Pass `$ARGUMENTS` as specification context and return the test strategy, cases, file plan, environment contract, and traceability map.

{cellenium-0.2.0/.claude/commands/testflow → cellenium-0.2.1/.claude/commands/cellenium}/web.md

@@ -2,10 +2,9 @@
 name: web
 description: Explore a live web application in a real browser to discover and document reproducible potential bugs with evidence.
 argument-hint: <URL, scope, role, and optional PRD/spec>
-command: /testflow:web
+command: /cellenium:web
 ---
 
-Invoke the Skill tool with `skill: "testflow:web"` 
-before doing anything else. Pass `$ARGUMENTS` as the exploration charter. 
+Before doing anything else, read `.claude/skills/cellenium/web/SKILL.md` (or `~/.claude/skills/cellenium/web/SKILL.md` if it is not in the project) and follow it as your instructions. Pass `$ARGUMENTS` as the exploration charter. 
 Use a real browser, preserve safety boundaries, 
 and return verified findings plus regression-test candidates without modifying application code.

{cellenium-0.2.0/.claude/commands/testflow → cellenium-0.2.1/.claude/commands/cellenium}/writer.md

@@ -2,9 +2,8 @@
 name: writer
 description: Implement approved test cases as deterministic, behavior-focused pytest tests that follow repository conventions.
 argument-hint: <test specification and target>
-command: /testflow:writer
+command: /cellenium:writer
 ---
 
-Invoke the Skill tool with `skill: "testflow:writer"` 
-before doing anything else. Pass `$ARGUMENTS` as the 
+Before doing anything else, read `.claude/skills/cellenium/writer/SKILL.md` (or `~/.claude/skills/cellenium/writer/SKILL.md` if it is not in the project) and follow it as your instructions. Pass `$ARGUMENTS` as the 
 approved test specification, write the pytest tests, and return collection plus targeted execution evidence.

{cellenium-0.2.0 → cellenium-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cellenium
-Version: 0.2.0
+Version: 0.2.1
 Summary: Playwright browser automation with a Google Sheets Page Object Model and CrewAI vision analysis
 Project-URL: Homepage, https://github.com/MedviJenka/cellenium-playwright
 License-File: LICENSE
@@ -70,12 +70,15 @@ uv run playwright install --with-deps chromium
 In the project where you use cellenium, run:
 
 ```sh
-cellenium init     # writes a .env template, adds .env and credentials.json to .gitignore, installs Chromium
+cellenium init     # writes a .env template, adds .env and credentials.json to .gitignore, installs Chromium and the Claude Code commands
+cellenium claude   # (re)installs the /cellenium:* Claude Code commands and skills into .claude/
 cellenium doctor   # checks settings, credentials.json, Google Sheet access, and that Chromium launches
 ```
 
 `cellenium init --with-deps` also installs Chromium's system libraries (Linux/CI). `cellenium doctor --offline` skips opening the sheet; it exits non-zero when a check fails, so it can gate CI.
 
+`cellenium claude --global` installs the commands into `~/.claude` so they are available in every project; locally modified files are kept unless you pass `--force`. Restart Claude Code after installing. `cellenium init --skip-claude` skips this step.
+
 Settings are read from `.env` in the working directory or from environment variables:
 
 ```dotenv
@@ -182,14 +185,14 @@ claude plugin validate .
 Run Claude Code from the repository and invoke either the complete pipeline or an individual stage:
 
 ```text
-/testflow:web
-/testflow:artifact
-/testflow:prd-reader
-/testflow:test-spec
-/testflow:locator-writer
-/testflow:writer
-/testflow:executor
-/testflow:evaluator
+/cellenium:web
+/cellenium:artifact
+/cellenium:prd-reader
+/cellenium:test-spec
+/cellenium:locator-writer
+/cellenium:writer
+/cellenium:executor
+/cellenium:evaluator
 ```
 
 The skills are manual-only. The locator writer previews changes before replacing existing Google Sheet selectors and verifies selectors against the live UI.
@@ -200,9 +203,9 @@ The separate checklist skills live under `.claude/skills/checklist/`: `before-st
 
 ```text
 .github/workflows/               GitHub Actions CI
-.claude/skills/testflow/         Pytest TestFlow skill definitions
+.claude/skills/cellenium/        Pytest TestFlow skill definitions
 .claude/skills/checklist/        Checklist skills (before-startup, cruising, landing, fordec)
-.claude/commands/testflow/       TestFlow slash-command entries
+.claude/commands/cellenium/      TestFlow slash-command entries
 .claude-plugin/plugin.json       Claude Code plugin metadata
 src/core/engine/                 Playwright browser and page engines
 src/core/functions/              Locator resolution and direct Google Sheets access

{cellenium-0.2.0 → cellenium-0.2.1}/README.md

@@ -1,206 +1,209 @@
-# Cellenium Playwright
-
-Cellenium Playwright is an experimental Python browser-automation toolkit built on [Playwright](https://playwright.dev/python/). It provides browser lifecycle management, a Google-Sheets-backed Page Object Model (POM), screenshot capture, and components for structured visual analysis with CrewAI.
-
-The repository also contains **TestFlow**, a set of Claude Code skills that turns product requirements and technical specifications into traceable pytest tests, validated UI locators, execution evidence, and a test-quality verdict.
-
-> **Status:** active development. The browser and locator layers are usable, but the checked-in vision test is still a scaffold and does not currently pass. Install it from PyPI with `pip install cellenium` (or `uv add cellenium`), then run `playwright install chromium`. Configuration (`.env`, `credentials.json`) is read from your project's working directory.
-
-## Features
-
-- Synchronous Chromium, Firefox, or WebKit sessions through Playwright.
-- Reusable `PageEngine` helpers for navigation, locators, screenshots, scrolling, dropdowns, and tabs.
-- Page Object Model data read directly from Google Sheets at runtime.
-- Locator strategies for name, XPath, ID, CSS, class name, link text, and tag name.
-- Structured image-analysis components built with CrewAI and Pydantic.
-- Parallel pytest execution in CI on Python 3.13 and 3.14.
-- Optional TestFlow skills for end-to-end pytest test generation and evaluation.
-
-## Requirements
-
-- Python 3.13 or 3.14
-- [`uv`](https://docs.astral.sh/uv/)
-- A Playwright-supported browser
-- A Google service account for resolving locators
-- An OpenAI-compatible model and API key when using the vision components
-
-## Quick start
-
-Clone the repository and install the locked dependencies:
-
-```sh
-git clone https://github.com/MedviJenka/cellenium-playwright.git
-cd cellenium-playwright
-uv sync --frozen
-```
-
-Install Chromium:
-
-```sh
-uv run playwright install chromium
-```
-
-On Ubuntu or another Debian-based CI runner, install Chromium and its system dependencies together:
-
-```sh
-uv run playwright install --with-deps chromium
-```
-
-## Configuration
-
-In the project where you use cellenium, run:
-
-```sh
-cellenium init     # writes a .env template, adds .env and credentials.json to .gitignore, installs Chromium
-cellenium doctor   # checks settings, credentials.json, Google Sheet access, and that Chromium launches
-```
-
-`cellenium init --with-deps` also installs Chromium's system libraries (Linux/CI). `cellenium doctor --offline` skips opening the sheet; it exits non-zero when a check fails, so it can gate CI.
-
-Settings are read from `.env` in the working directory or from environment variables:
-
-```dotenv
-GOOGLE_SHEETS=<spreadsheet-edit-url>
-CREDENTIALS_JSON=credentials.json
-OPENAI_MODEL=<model-name>
-OPENAI_API_KEY=<optional-api-key>
-LOGFIRE_TOKEN=<optional-logfire-token>
-TEST_HEADLESS=true
-```
-
-`GOOGLE_SHEETS` selects the locator spreadsheet. When `LOGFIRE_TOKEN` is omitted, logging remains local and no data is sent to Logfire.
-
-Save the Google service-account key as `credentials.json` and share the locator spreadsheet with its `client_email` as a viewer (`cellenium doctor` prints the address). Never commit `.env` or `credentials.json`.
-
-## Google Sheets Page Object Model
-
-Each worksheet tab represents one screen. The first row must contain these columns:
-
-| Column | Purpose |
-|---|---|
-| `name` | Logical element name used by tests |
-| `locator` | Locator strategy such as `NAME`, `XPATH`, `ID`, or `CSS` |
-| `type` | Locator value; this name is retained for compatibility with the source sheet |
-| `actions` | Optional metadata |
-| `comments` | Optional notes |
-
-Example worksheet:
-
-| name | locator | type | actions | comments |
-|---|---|---|---|---|
-| search | NAME | q | fill | Google search field |
-| button | NAME | btnK | click | Search button |
-
-`PageEngine(screen="Google")` reads locator rows directly from the worksheet tab
-named `Google`. No generated JSON mapping or synchronization step is required.
-
-## Browser automation
-
-```python
-from src.core.engine.page_engine import PageEngine
-
-engine = PageEngine(screen="Google", headless=True)
-
-try:
-    engine.get_web("https://www.google.com")
-    engine.get_element("search").fill("cats")
-    engine.get_element("button").click()
-    screenshot = engine.get_screenshot("google-results")
-    print(screenshot)
-finally:
-    engine.teardown()
-```
-
-`screen="Google"` selects the worksheet tab named `Google`. With multiple tabs, pass the page's tab name when constructing `PageEngine` (for example, `Google`, `Heroku`, or `ST`). Missing worksheets, missing element names, and unsupported locator strategies raise explicit exceptions.
-
-## Tests and linting
-
-Run the test suite:
-
-```sh
-uv run --frozen pytest src/tests tests -v -n auto --dist loadscope
-```
-
-`src/tests/test_google_search.py` exercises the live browser flow. The unit regressions in `tests/` cover screenshot persistence and direct worksheet selection without contacting external services.
-
-Run the blocking CI lint checks:
-
-```sh
-uvx --from flake8==7.4.1 flake8 main.py settings.py src \
-  --count --select=E9,F63,F7,F82 --show-source --statistics
-```
-
-The GitHub Actions workflow in `.github/workflows/python-package.yml` performs locked dependency installation, installs Chromium, runs lint checks, and executes the tests under Xvfb for Python 3.13 and 3.14.
-
-## TestFlow Claude Code skills
-
-TestFlow separates pytest creation into focused stages:
-
-```text
-PRD → test specification → UI locators → pytest writer → executor → evaluator
-```
-
-| Order | Skill | Purpose |
-|---:|---|---|
-| Optional | `web` | Explore a live application in a real browser and produce reproducible bug evidence |
-| 1 | `prd-reader` | Extract explicit, derived, and unknown test requirements from the PRD |
-| 2 | `test-spec` | Design traceable pytest cases, boundaries, fixtures, and execution prerequisites |
-| 3 | `locator-writer` | For UI cases, validate stable Playwright selectors and upsert elements into Google Sheets |
-| 4 | `writer` | Implement deterministic, behavior-focused pytest tests |
-| 5 | `executor` | Run collection, targeted tests, related tests, and classify failures |
-| 6 | `evaluator` | Evaluate traceability, regression sensitivity, coverage quality, and execution evidence |
-
-`artifact` orchestrates the complete pipeline and repeats only the affected downstream stages when evaluation finds a defect.
-
-`web` is a report-only exploratory entry point. Verified findings become regression candidates for `test-spec`; it does not modify application code.
-
-Validate the Claude Code plugin metadata:
-
-```sh
-claude plugin validate .
-```
-
-Run Claude Code from the repository and invoke either the complete pipeline or an individual stage:
-
-```text
-/testflow:web
-/testflow:artifact
-/testflow:prd-reader
-/testflow:test-spec
-/testflow:locator-writer
-/testflow:writer
-/testflow:executor
-/testflow:evaluator
-```
-
-The skills are manual-only. The locator writer previews changes before replacing existing Google Sheet selectors and verifies selectors against the live UI.
-
-The separate checklist skills live under `.claude/skills/checklist/`: `before-startup` (system ready to build tests), `cruising` (everything in place, critical errors and potential bugs), `landing` (final production readiness), and the standalone `fordec` emergency decision skill.
-
-## Project layout
-
-```text
-.github/workflows/               GitHub Actions CI
-.claude/skills/testflow/         Pytest TestFlow skill definitions
-.claude/skills/checklist/        Checklist skills (before-startup, cruising, landing, fordec)
-.claude/commands/testflow/       TestFlow slash-command entries
-.claude-plugin/plugin.json       Claude Code plugin metadata
-src/core/engine/                 Playwright browser and page engines
-src/core/functions/              Locator resolution and direct Google Sheets access
-src/core/ai/                     CrewAI configuration and vision components
-src/tests/                       Browser test scenarios
-settings.py                      Environment-backed runtime configuration
-pyproject.toml                   Python requirements and dependencies
-uv.lock                          Reproducible dependency lockfile
-```
-
-## Known limitations
-
-- The checked-in vision test uses a placeholder `VisionAssertion` without a `run()` implementation.
-- The sample end-to-end test depends on Google and is not hermetic.
-- Configuration currently requires fields that are reserved but not consumed by every component.
-- The project does not yet define a wheel/sdist build or publishing workflow.
-
-## License
-
-Licensed under the [ISC License](LICENSE). Copyright © 2026 Jenia Petrusenko.
+# Cellenium Playwright
+
+Cellenium Playwright is an experimental Python browser-automation toolkit built on [Playwright](https://playwright.dev/python/). It provides browser lifecycle management, a Google-Sheets-backed Page Object Model (POM), screenshot capture, and components for structured visual analysis with CrewAI.
+
+The repository also contains **TestFlow**, a set of Claude Code skills that turns product requirements and technical specifications into traceable pytest tests, validated UI locators, execution evidence, and a test-quality verdict.
+
+> **Status:** active development. The browser and locator layers are usable, but the checked-in vision test is still a scaffold and does not currently pass. Install it from PyPI with `pip install cellenium` (or `uv add cellenium`), then run `playwright install chromium`. Configuration (`.env`, `credentials.json`) is read from your project's working directory.
+
+## Features
+
+- Synchronous Chromium, Firefox, or WebKit sessions through Playwright.
+- Reusable `PageEngine` helpers for navigation, locators, screenshots, scrolling, dropdowns, and tabs.
+- Page Object Model data read directly from Google Sheets at runtime.
+- Locator strategies for name, XPath, ID, CSS, class name, link text, and tag name.
+- Structured image-analysis components built with CrewAI and Pydantic.
+- Parallel pytest execution in CI on Python 3.13 and 3.14.
+- Optional TestFlow skills for end-to-end pytest test generation and evaluation.
+
+## Requirements
+
+- Python 3.13 or 3.14
+- [`uv`](https://docs.astral.sh/uv/)
+- A Playwright-supported browser
+- A Google service account for resolving locators
+- An OpenAI-compatible model and API key when using the vision components
+
+## Quick start
+
+Clone the repository and install the locked dependencies:
+
+```sh
+git clone https://github.com/MedviJenka/cellenium-playwright.git
+cd cellenium-playwright
+uv sync --frozen
+```
+
+Install Chromium:
+
+```sh
+uv run playwright install chromium
+```
+
+On Ubuntu or another Debian-based CI runner, install Chromium and its system dependencies together:
+
+```sh
+uv run playwright install --with-deps chromium
+```
+
+## Configuration
+
+In the project where you use cellenium, run:
+
+```sh
+cellenium init     # writes a .env template, adds .env and credentials.json to .gitignore, installs Chromium and the Claude Code commands
+cellenium claude   # (re)installs the /cellenium:* Claude Code commands and skills into .claude/
+cellenium doctor   # checks settings, credentials.json, Google Sheet access, and that Chromium launches
+```
+
+`cellenium init --with-deps` also installs Chromium's system libraries (Linux/CI). `cellenium doctor --offline` skips opening the sheet; it exits non-zero when a check fails, so it can gate CI.
+
+`cellenium claude --global` installs the commands into `~/.claude` so they are available in every project; locally modified files are kept unless you pass `--force`. Restart Claude Code after installing. `cellenium init --skip-claude` skips this step.
+
+Settings are read from `.env` in the working directory or from environment variables:
+
+```dotenv
+GOOGLE_SHEETS=<spreadsheet-edit-url>
+CREDENTIALS_JSON=credentials.json
+OPENAI_MODEL=<model-name>
+OPENAI_API_KEY=<optional-api-key>
+LOGFIRE_TOKEN=<optional-logfire-token>
+TEST_HEADLESS=true
+```
+
+`GOOGLE_SHEETS` selects the locator spreadsheet. When `LOGFIRE_TOKEN` is omitted, logging remains local and no data is sent to Logfire.
+
+Save the Google service-account key as `credentials.json` and share the locator spreadsheet with its `client_email` as a viewer (`cellenium doctor` prints the address). Never commit `.env` or `credentials.json`.
+
+## Google Sheets Page Object Model
+
+Each worksheet tab represents one screen. The first row must contain these columns:
+
+| Column | Purpose |
+|---|---|
+| `name` | Logical element name used by tests |
+| `locator` | Locator strategy such as `NAME`, `XPATH`, `ID`, or `CSS` |
+| `type` | Locator value; this name is retained for compatibility with the source sheet |
+| `actions` | Optional metadata |
+| `comments` | Optional notes |
+
+Example worksheet:
+
+| name | locator | type | actions | comments |
+|---|---|---|---|---|
+| search | NAME | q | fill | Google search field |
+| button | NAME | btnK | click | Search button |
+
+`PageEngine(screen="Google")` reads locator rows directly from the worksheet tab
+named `Google`. No generated JSON mapping or synchronization step is required.
+
+## Browser automation
+
+```python
+from src.core.engine.page_engine import PageEngine
+
+engine = PageEngine(screen="Google", headless=True)
+
+try:
+    engine.get_web("https://www.google.com")
+    engine.get_element("search").fill("cats")
+    engine.get_element("button").click()
+    screenshot = engine.get_screenshot("google-results")
+    print(screenshot)
+finally:
+    engine.teardown()
+```
+
+`screen="Google"` selects the worksheet tab named `Google`. With multiple tabs, pass the page's tab name when constructing `PageEngine` (for example, `Google`, `Heroku`, or `ST`). Missing worksheets, missing element names, and unsupported locator strategies raise explicit exceptions.
+
+## Tests and linting
+
+Run the test suite:
+
+```sh
+uv run --frozen pytest src/tests tests -v -n auto --dist loadscope
+```
+
+`src/tests/test_google_search.py` exercises the live browser flow. The unit regressions in `tests/` cover screenshot persistence and direct worksheet selection without contacting external services.
+
+Run the blocking CI lint checks:
+
+```sh
+uvx --from flake8==7.4.1 flake8 main.py settings.py src \
+  --count --select=E9,F63,F7,F82 --show-source --statistics
+```
+
+The GitHub Actions workflow in `.github/workflows/python-package.yml` performs locked dependency installation, installs Chromium, runs lint checks, and executes the tests under Xvfb for Python 3.13 and 3.14.
+
+## TestFlow Claude Code skills
+
+TestFlow separates pytest creation into focused stages:
+
+```text
+PRD → test specification → UI locators → pytest writer → executor → evaluator
+```
+
+| Order | Skill | Purpose |
+|---:|---|---|
+| Optional | `web` | Explore a live application in a real browser and produce reproducible bug evidence |
+| 1 | `prd-reader` | Extract explicit, derived, and unknown test requirements from the PRD |
+| 2 | `test-spec` | Design traceable pytest cases, boundaries, fixtures, and execution prerequisites |
+| 3 | `locator-writer` | For UI cases, validate stable Playwright selectors and upsert elements into Google Sheets |
+| 4 | `writer` | Implement deterministic, behavior-focused pytest tests |
+| 5 | `executor` | Run collection, targeted tests, related tests, and classify failures |
+| 6 | `evaluator` | Evaluate traceability, regression sensitivity, coverage quality, and execution evidence |
+
+`artifact` orchestrates the complete pipeline and repeats only the affected downstream stages when evaluation finds a defect.
+
+`web` is a report-only exploratory entry point. Verified findings become regression candidates for `test-spec`; it does not modify application code.
+
+Validate the Claude Code plugin metadata:
+
+```sh
+claude plugin validate .
+```
+
+Run Claude Code from the repository and invoke either the complete pipeline or an individual stage:
+
+```text
+/cellenium:web
+/cellenium:artifact
+/cellenium:prd-reader
+/cellenium:test-spec
+/cellenium:locator-writer
+/cellenium:writer
+/cellenium:executor
+/cellenium:evaluator
+```
+
+The skills are manual-only. The locator writer previews changes before replacing existing Google Sheet selectors and verifies selectors against the live UI.
+
+The separate checklist skills live under `.claude/skills/checklist/`: `before-startup` (system ready to build tests), `cruising` (everything in place, critical errors and potential bugs), `landing` (final production readiness), and the standalone `fordec` emergency decision skill.
+
+## Project layout
+
+```text
+.github/workflows/               GitHub Actions CI
+.claude/skills/cellenium/        Pytest TestFlow skill definitions
+.claude/skills/checklist/        Checklist skills (before-startup, cruising, landing, fordec)
+.claude/commands/cellenium/      TestFlow slash-command entries
+.claude-plugin/plugin.json       Claude Code plugin metadata
+src/core/engine/                 Playwright browser and page engines
+src/core/functions/              Locator resolution and direct Google Sheets access
+src/core/ai/                     CrewAI configuration and vision components
+src/tests/                       Browser test scenarios
+settings.py                      Environment-backed runtime configuration
+pyproject.toml                   Python requirements and dependencies
+uv.lock                          Reproducible dependency lockfile
+```
+
+## Known limitations
+
+- The checked-in vision test uses a placeholder `VisionAssertion` without a `run()` implementation.
+- The sample end-to-end test depends on Google and is not hermetic.
+- Configuration currently requires fields that are reserved but not consumed by every component.
+- The project does not yet define a wheel/sdist build or publishing workflow.
+
+## License
+
+Licensed under the [ISC License](LICENSE). Copyright © 2026 Jenia Petrusenko.