onecrawl 4.0.0-alpha.37

package/README.md

@@ -0,0 +1,77 @@
+# onecrawl
+
+Browser automation engine — CLI, MCP server, and AI agent skills.
+
+## Install
+
+```bash
+npm install onecrawl
+```
+
+This will:
+1. Download the OneCrawl binary for your platform
+2. Make `npx onecrawl` available
+
+## Setup Skills
+
+Install AGENTS policies and AI skills into your project:
+
+```bash
+npx onecrawl init
+```
+
+This creates:
+- `AGENTS.md` — Agent policy dispatcher
+- `AGENTS.vscode.MD` — VS Code runtime adapter
+- `AGENTS.copilot-cli.MD` — Copilot CLI runtime adapter
+- `.github/copilot-instructions.md` — GitHub Copilot custom instructions
+- `.github/skills/*/SKILL.md` — 14 operational skills
+
+## Update Skills
+
+Skills update automatically when you update the package:
+
+```bash
+npm update onecrawl
+npx onecrawl update-skills
+```
+
+## Check Status
+
+```bash
+npx onecrawl skills-status
+```
+
+## CLI Usage
+
+All other commands are forwarded to the OneCrawl binary:
+
+```bash
+npx onecrawl run browser navigate --url https://example.com
+npx onecrawl run browser screenshot --json
+npx onecrawl mcp serve
+```
+
+## Programmatic API
+
+```js
+import { initSkills, updateSkills, skillsStatus } from "onecrawl/skills";
+
+await initSkills("/path/to/project");
+await updateSkills("/path/to/project");
+await skillsStatus("/path/to/project");
+```
+
+## Supported Platforms
+
+| Platform | Architecture | Binary |
+|----------|-------------|--------|
+| macOS    | arm64 (M1+) | ✅ |
+| macOS    | x64         | ✅ |
+| Linux    | x64 (glibc) | ✅ |
+| Linux    | arm64       | ✅ |
+| Windows  | x64         | ✅ |
+
+## License
+
+BUSL-1.1

package/assets/.github/copilot-instructions.md

@@ -0,0 +1,44 @@
+# Copilot Custom Instructions — OneCrawl
+
+## Project Overview
+
+OneCrawl is a Rust-based browser automation engine providing CLI, MCP server, NAPI (Node.js), and PyO3 (Python) bindings.
+It uses Chrome DevTools Protocol (CDP) for all browser interactions.
+
+## Build & Test
+
+```bash
+# Check compilation (fast feedback)
+cargo check -p onecrawl-mcp-rs
+
+# Run all tests (exclude e2e)
+cargo test --workspace --exclude onecrawl-e2e -- --test-threads=1
+
+# Build release binary
+cargo build --release -p onecrawl-cli-rs
+```
+
+## Architecture
+
+- **Workspace**: Cargo workspace at `packages/onecrawl-rust/`
+- **Crates**: `onecrawl-cli-rs` (CLI), `onecrawl-mcp-rs` (MCP server), `onecrawl-cdp` (CDP bindings), `onecrawl-browser` (browser core), `onecrawl-napi` (Node.js), `onecrawl-python` (Python)
+- **MCP tools**: 18 tools with 546+ actions — see `crates/onecrawl-mcp-rs/src/actions.rs`
+- **Hexagonal ports**: `onecrawl-browser/src/ports/mod.rs` — BrowserPort, PagePort, ElementPort, NetworkPort, EmulationPort, InputPort
+
+## Conventions
+
+- ESM (`type: module`) for Node.js, requires Node ≥ 20
+- CDP runtime types are at `onecrawl_protocol::cdp::js_protocol::runtime`
+- `rand::rng()` returns `!Send` — scope all RNG in sync blocks before `.await`
+- Security: use `validate_name()` for path safety, `write_sensitive_file()` with chmod 0o600 for credentials
+- Never use `unwrap_or_default()` on serde parse — use `match` with proper error handling
+- Prefer CDP-native operations over JS evaluation
+
+## Agent Protocol
+
+This repo uses AGENTS.md with runtime-specific adapters:
+- **VS Code**: `AGENTS.vscode.MD` (uses `vscode_askQuestions`)
+- **Copilot CLI**: `AGENTS.copilot-cli.MD` (uses `ask_user`)
+- **Skills**: `.github/skills/*/SKILL.md` — 14 operational skills
+
+Do not mix tool names across runtimes.

package/assets/AGENTS.copilot-cli.MD

@@ -0,0 +1,113 @@
+# AGENTS.copilot-cli.MD
+
+## 1. Interaction Protocol (Runtime-Critical Contract)
+
+Interaction must occur **exclusively via `ask_user`** and remain iterative, interactive, and unlimited.
+If `ask_user` is unavailable in the current runtime, use an equivalent structured question tool while preserving the same interaction contract.
+
+Each iteration must ask exactly **one clear question** and provide exactly **5 options**.
+
+Default option composition (for normal development decisions):
+1. **Recommended Development Path** (mark as ⭐ most future-proof)
+2. **Alternative Development Path A**
+3. **Alternative Development Path B**
+4. **Freeform** — "Something else": lets the user type a custom direction (uses `custom` enum value — see below)
+5. **Autonomous Mode**
+
+`Freeform` is a hard invariant across all iterations:
+- option **4** must always be **Freeform** — the "Something else" escape hatch
+- label must remain exactly `Freeform` (no rename, merge, or synonym replacement)
+- **implementation**: set the enum value to `custom` — Copilot CLI ≥ 1.0.2 allows custom responses in enum fields, so the user can type their preferred direction directly in the `ask_user` prompt without a separate freeform tool call
+- when the user types a custom response, treat it as their chosen direction and proceed accordingly
+- applies to default mode, compatibility-triad escalation, rollback/RCA prompts, and task-start mode selection
+- if `Freeform` is missing, the iteration is invalid and must be regenerated before proceeding
+
+Continuity is mandatory:
+- options **1-3** must, by default, carry forward all still-valid options from the previous iteration
+- do not drop an option silently; if one is removed, explicitly state why and what replaced it
+
+For each option, always include:
+- why the option exists
+- where the option leads next (expected outcome / milestone impact)
+- risk level (`low` / `medium` / `high`)
+
+Use this mandatory option card format:
+`<Option title> — Why: <reason> | Leads to: <next step/result> | Risk: <low|medium|high>`
+
+Recommendation tracking is mandatory:
+- mark the current recommendation with ⭐
+- if the recommendation changes from the previous iteration, explain why in one sentence
+
+The compatibility triad below is an **escalation package**, not the default:
+- **Non-Breaking Path**
+- **Breaking Path**
+- **Alternative Structural Path**
+
+Use the compatibility triad only when at least one condition is true:
+- there is a concrete compatibility/contract impact
+- migration effort must be evaluated
+- architectural break/refactor trade-off is the core decision
+- the user explicitly asks for breaking/non-breaking analysis
+
+When the compatibility triad is used:
+- the interaction still remains exactly 5 options: triad options + **Freeform** + **Autonomous Mode**
+- include at minimum: pros/cons, risk level, migration steps
+- explicitly state that quality gates are unchanged (unit/integration/E2E/non-regression must still pass)
+
+At the beginning of each task, mode selection is mandatory: **never assume a default mode globally**.
+Mode selection at task start must use the same 5-option structure above (development-options-first unless escalation is justified).
+
+### Autonomous Mode
+
+`Autonomous Mode` means:
+- work autonomously until all milestones are completed
+- always choose the best, most future-proof option within the selected path
+- if a new unapproved breaking impact appears, pause and ask via `ask_user`
+- **at the end of every autonomous run** — **mandatory, no exceptions**: invoke `ask_user` to re-enter the feedback loop; the run is considered incomplete until this call is made — ask for:
+  1. rating of the completed run
+  2. next action to take
+  3. explicit satisfaction confirmation
+
+### Feedback Loop — Never Interrupt
+
+The feedback loop is **perpetual by design**:
+- the loop **must never self-terminate** for any reason (task completion, milestone reached, silence, assumed satisfaction)
+- the agent must **never presume** the user is satisfied
+- **no reason is sufficient** to break the loop other than the user's explicit stop phrase
+- after every autonomous run, after every decision, after every completion — always re-enter the loop with `ask_user`
+
+The interaction loop stops **only** when the user explicitly says:
+> "I am satisfied"
+
+Until that exact phrase is received, the loop continues — unconditionally and indefinitely.
+
+---
+
+## 2. Operational Procedures (Skill-Owned)
+
+Operational procedures/checklists are owned by skills and are intentionally **not duplicated** here.
+Read the corresponding `SKILL.md` when the trigger condition for that skill is met.
+
+- **[`interaction-loop`](.github/skills/interaction-loop/SKILL.md)** — **Invoke when**: starting a task, hitting a decision point, or completing an autonomous run | **Provides**: 5-option iterative loop template, recommendation tracking, and stop-condition rules (`"I am satisfied"`)
+
+- **[`breaking-change-paths`](.github/skills/breaking-change-paths/SKILL.md)** — **Invoke when**: a task may affect public contracts, APIs, schemas, or behavioral compatibility; or a root-cause fix implies architectural reshaping | **Provides**: structured pros/cons + risk level + migration steps for Breaking vs Non-Breaking path decision
+
+- **[`planning-tracking`](.github/skills/planning-tracking/SKILL.md)** — **Invoke when**: starting any non-trivial task, scope changes during execution, or multiple files/workstreams must be coordinated | **Provides**: mandatory Plan/Milestone/Issue schema with dependency-ordered execution procedure and parallel-safe concurrency rules
+
+- **[`completion-gate`](.github/skills/completion-gate/SKILL.md)** — **Invoke when**: closing an issue, marking a milestone done, or opening/merging a PR | **Provides**: double-consecutive-clean-pass quality gate (lint + build + required tests, zero errors/warnings, no exceptions)
+
+- **[`github-sync`](.github/skills/github-sync/SKILL.md)** — **Invoke when**: creating/updating a plan, changing issue status, or completing milestones | **Provides**: naming rules, required metadata labels (priority/type/status), and step-by-step procedure to keep local plan and GitHub artifacts in sync
+
+- **[`testing-policy`](.github/skills/testing-policy/SKILL.md)** — **Invoke when**: implementing or modifying any feature/fix; preparing issue closure or PR merge | **Provides**: required test layers (unit / integration / E2E / non-regression) and a before/after coverage diff procedure
+
+- **[`e2e-testing`](.github/skills/e2e-testing/SKILL.md)** — **Invoke when**: a user-facing flow changes or a critical integration path is introduced/modified | **Provides**: E2E checklist covering happy path + edge cases, CI-compatible execution, stable selectors, and deterministic setup/teardown
+
+- **[`session-logging`](.github/skills/session-logging/SKILL.md)** — **Invoke when**: starting/ending a session, completing issues/milestones, or syncing GitHub status | **Provides**: session journal file template with required sections (Status, Work Completed, Completion Gate evidence, Decisions, Blockers, GitHub Sync, Branch, Timestamp)
+
+- **[`rollback-rca`](.github/skills/rollback-rca/SKILL.md)** — **Invoke when**: an issue fails the completion gate 3 consecutive times | **Provides**: RCA procedure (architecture/dependency/scope analysis) + 3 recovery options (rescope / rollback / redesign) to present via `ask_user`
+
+- **[`policy-coherence-audit`](.github/skills/policy-coherence-audit/SKILL.md)** — **Invoke when**: updating `AGENTS.MD`, merging new workflow rules, or noticing behavioral ambiguity during execution | **Provides**: cross-policy contradiction checklist covering language, interaction model, completion gates, scope, and skill reference coherence
+
+- **[`systematic-debugging`](.github/skills/systematic-debugging/SKILL.md)** — **Invoke when**: a bug or unexpected behavior is encountered, a test fails without obvious cause, or a previous fix attempt did not resolve the issue | **Provides**: evidence-based debugging procedure (reproduce → hypothesize → instrument → collect `debug-data.log` → analyze → fix → clean up), MCP tool integration for browser/network/runtime debugging
+
+Runtime binding rule: when a skill requires asking the user, use `ask_user` and preserve the 5-option contract with option 4 fixed as `Freeform`.

package/assets/AGENTS.md

@@ -0,0 +1,66 @@
+# AGENTS.md
+
+## Runtime Dispatcher (No Tool-Name Ambiguity)
+
+This repository provides **two runtime adapter files**:
+
+1. `AGENTS.vscode.MD` — VS Code runtime (`vscode_askQuestions`)
+2. `AGENTS.copilot-cli.MD` — Copilot CLI runtime (`ask_user`)
+
+Do **not** mix tool names across runtimes.
+
+## Selection Rule (Mandatory)
+
+- If runtime is VS Code, use only `AGENTS.vscode.MD`.
+- If runtime is Copilot CLI, use only `AGENTS.copilot-cli.MD`.
+- At task start, mode selection and the 5-option interaction loop remain mandatory in the selected file.
+
+## Ownership Model (Skills-First, Mandatory)
+
+`AGENTS.md` + runtime adapters own only **runtime-critical contract**:
+- question tool binding (`vscode_askQuestions` vs `ask_user`)
+- fixed 5-option interaction shape
+- `Freeform` hard invariant (option 4, exact label — "Something else" via `custom` enum value for inline free-text input)
+- `Autonomous Mode` placement and stop condition (`"I am satisfied"`)
+- escalation trigger for compatibility triad
+
+All operational procedures/checklists are skill-owned and must not be duplicated as full policy prose in runtime adapters.
+
+## Skill Catalog (Global Default)
+
+Operational procedures/checklists are owned by skills. This catalog is the **global source of truth** — runtime adapters inherit it and must not duplicate its content.
+
+Read the corresponding `SKILL.md` when the trigger condition for that skill is met.
+
+- **[`interaction-loop`](.github/skills/interaction-loop/SKILL.md)** — **Invoke when**: starting a task, hitting a decision point, or completing an autonomous run | **Provides**: 5-option iterative loop template, recommendation tracking, and stop-condition rules (`"I am satisfied"`)
+
+- **[`breaking-change-paths`](.github/skills/breaking-change-paths/SKILL.md)** — **Invoke when**: a task may affect public contracts, APIs, schemas, or behavioral compatibility; or a root-cause fix implies architectural reshaping | **Provides**: structured pros/cons + risk level + migration steps for Breaking vs Non-Breaking path decision
+
+- **[`planning-tracking`](.github/skills/planning-tracking/SKILL.md)** — **Invoke when**: starting any non-trivial task, scope changes during execution, or multiple files/workstreams must be coordinated | **Provides**: mandatory Plan/Milestone/Issue schema with dependency-ordered execution procedure and parallel-safe concurrency rules
+
+- **[`completion-gate`](.github/skills/completion-gate/SKILL.md)** — **Invoke when**: closing an issue, marking a milestone done, or opening/merging a PR | **Provides**: double-consecutive-clean-pass quality gate (lint + build + required tests, zero errors/warnings, no exceptions)
+
+- **[`github-sync`](.github/skills/github-sync/SKILL.md)** — **Invoke when**: creating/updating a plan, changing issue status, or completing milestones | **Provides**: naming rules, required metadata labels (priority/type/status), and step-by-step procedure to keep local plan and GitHub artifacts in sync
+
+- **[`testing-policy`](.github/skills/testing-policy/SKILL.md)** — **Invoke when**: implementing or modifying any feature/fix; preparing issue closure or PR merge | **Provides**: required test layers (unit / integration / E2E / non-regression) and a before/after coverage diff procedure
+
+- **[`e2e-testing`](.github/skills/e2e-testing/SKILL.md)** — **Invoke when**: a user-facing flow changes or a critical integration path is introduced/modified | **Provides**: E2E checklist covering happy path + edge cases, CI-compatible execution, stable selectors, and deterministic setup/teardown
+
+- **[`session-logging`](.github/skills/session-logging/SKILL.md)** — **Invoke when**: starting/ending a session, completing issues/milestones, or syncing GitHub status | **Provides**: session journal file template with required sections (Status, Work Completed, Completion Gate evidence, Decisions, Blockers, GitHub Sync, Branch, Timestamp)
+
+- **[`rollback-rca`](.github/skills/rollback-rca/SKILL.md)** — **Invoke when**: an issue fails the completion gate 3 consecutive times | **Provides**: RCA procedure (architecture/dependency/scope analysis) + 3 recovery options (rescope / rollback / redesign) presented via the runtime question tool
+
+- **[`policy-coherence-audit`](.github/skills/policy-coherence-audit/SKILL.md)** — **Invoke when**: updating `AGENTS.MD`, merging new workflow rules, or noticing behavioral ambiguity during execution | **Provides**: cross-policy contradiction checklist covering language, interaction model, completion gates, scope, and skill reference coherence
+
+- **[`systematic-debugging`](.github/skills/systematic-debugging/SKILL.md)** — **Invoke when**: a bug or unexpected behavior is encountered, a test fails without obvious cause, or a previous fix attempt did not resolve the issue | **Provides**: evidence-based debugging procedure (reproduce → hypothesize → instrument → collect `debug-data.log` → analyze → fix → clean up), MCP tool integration for browser/network/runtime debugging
+
+- **[`onecrawl-commands`](.github/skills/onecrawl-commands/SKILL.md)** — **Invoke when**: writing automation scripts, choosing between OneCrawl primitives and eval, or building agent workflows | **Provides**: complete command reference (200+ commands), decision flowchart (primitives-first, eval-as-fallback), anti-patterns, configuration guide
+
+## Maintenance Rule
+
+When updating policy logic:
+
+1. If the change is runtime-critical, apply it to **both** runtime adapters (tool names adjusted per runtime).
+2. If the change is operational/procedural, update the owning skill (`.github/skills/*/SKILL.md`) first, then update the entry in the **Skill Catalog** section above.
+3. Keep semantic parity unless a runtime-specific behavior is intentionally required.
+4. Preserve English-only wording and non-duplicative ownership between AGENTS and skills.

package/assets/AGENTS.vscode.MD

@@ -0,0 +1,113 @@
+# AGENTS.vscode.MD
+
+## 1. Interaction Protocol (Runtime-Critical Contract)
+
+Interaction must occur **exclusively via `vscode_askQuestions`** and remain iterative, interactive, and unlimited.
+If `vscode_askQuestions` is unavailable in the current runtime, use an equivalent structured question tool while preserving the same interaction contract.
+
+Each iteration must ask exactly **one clear question** and provide exactly **5 options**.
+
+Default option composition (for normal development decisions):
+1. **Recommended Development Path** (mark as ⭐ most future-proof)
+2. **Alternative Development Path A**
+3. **Alternative Development Path B**
+4. **Freeform** — "Something else": lets the user type a custom direction (uses `custom` enum value — see below)
+5. **Autonomous Mode**
+
+`Freeform` is a hard invariant across all iterations:
+- option **4** must always be **Freeform** — the "Something else" escape hatch
+- label must remain exactly `Freeform` (no rename, merge, or synonym replacement)
+- **implementation**: set the enum value to `custom` — if the runtime supports custom responses in enum fields the user can type their preferred direction directly in the prompt without a separate freeform tool call; otherwise fall back to a follow-up freeform prompt
+- when the user types a custom response, treat it as their chosen direction and proceed accordingly
+- applies to default mode, compatibility-triad escalation, rollback/RCA prompts, and task-start mode selection
+- if `Freeform` is missing, the iteration is invalid and must be regenerated before proceeding
+
+Continuity is mandatory:
+- options **1-3** must, by default, carry forward all still-valid options from the previous iteration
+- do not drop an option silently; if one is removed, explicitly state why and what replaced it
+
+For each option, always include:
+- why the option exists
+- where the option leads next (expected outcome / milestone impact)
+- risk level (`low` / `medium` / `high`)
+
+Use this mandatory option card format:
+`<Option title> — Why: <reason> | Leads to: <next step/result> | Risk: <low|medium|high>`
+
+Recommendation tracking is mandatory:
+- mark the current recommendation with ⭐
+- if the recommendation changes from the previous iteration, explain why in one sentence
+
+The compatibility triad below is an **escalation package**, not the default:
+- **Non-Breaking Path**
+- **Breaking Path**
+- **Alternative Structural Path**
+
+Use the compatibility triad only when at least one condition is true:
+- there is a concrete compatibility/contract impact
+- migration effort must be evaluated
+- architectural break/refactor trade-off is the core decision
+- the user explicitly asks for breaking/non-breaking analysis
+
+When the compatibility triad is used:
+- the interaction still remains exactly 5 options: triad options + **Freeform** + **Autonomous Mode**
+- include at minimum: pros/cons, risk level, migration steps
+- explicitly state that quality gates are unchanged (unit/integration/E2E/non-regression must still pass)
+
+At the beginning of each task, mode selection is mandatory: **never assume a default mode globally**.
+Mode selection at task start must use the same 5-option structure above (development-options-first unless escalation is justified).
+
+### Autonomous Mode
+
+`Autonomous Mode` means:
+- work autonomously until all milestones are completed
+- always choose the best, most future-proof option within the selected path
+- if a new unapproved breaking impact appears, pause and ask via `vscode_askQuestions`
+- **at the end of every autonomous run** — **mandatory, no exceptions**: invoke `vscode_askQuestions` to re-enter the feedback loop; the run is considered incomplete until this call is made — ask for:
+  1. rating of the completed run
+  2. next action to take
+  3. explicit satisfaction confirmation
+
+### Feedback Loop — Never Interrupt
+
+The feedback loop is **perpetual by design**:
+- the loop **must never self-terminate** for any reason (task completion, milestone reached, silence, assumed satisfaction)
+- the agent must **never presume** the user is satisfied
+- **no reason is sufficient** to break the loop other than the user's explicit stop phrase
+- after every autonomous run, after every decision, after every completion — always re-enter the loop with `vscode_askQuestions`
+
+The interaction loop stops **only** when the user explicitly says:
+> "I am satisfied"
+
+Until that exact phrase is received, the loop continues — unconditionally and indefinitely.
+
+---
+
+## 2. Operational Procedures (Skill-Owned)
+
+Operational procedures/checklists are owned by skills and are intentionally **not duplicated** here.
+Read the corresponding `SKILL.md` when the trigger condition for that skill is met.
+
+- **[`interaction-loop`](.github/skills/interaction-loop/SKILL.md)** — **Invoke when**: starting a task, hitting a decision point, or completing an autonomous run | **Provides**: 5-option iterative loop template, recommendation tracking, and stop-condition rules (`"I am satisfied"`)
+
+- **[`breaking-change-paths`](.github/skills/breaking-change-paths/SKILL.md)** — **Invoke when**: a task may affect public contracts, APIs, schemas, or behavioral compatibility; or a root-cause fix implies architectural reshaping | **Provides**: structured pros/cons + risk level + migration steps for Breaking vs Non-Breaking path decision
+
+- **[`planning-tracking`](.github/skills/planning-tracking/SKILL.md)** — **Invoke when**: starting any non-trivial task, scope changes during execution, or multiple files/workstreams must be coordinated | **Provides**: mandatory Plan/Milestone/Issue schema with dependency-ordered execution procedure and parallel-safe concurrency rules
+
+- **[`completion-gate`](.github/skills/completion-gate/SKILL.md)** — **Invoke when**: closing an issue, marking a milestone done, or opening/merging a PR | **Provides**: double-consecutive-clean-pass quality gate (lint + build + required tests, zero errors/warnings, no exceptions)
+
+- **[`github-sync`](.github/skills/github-sync/SKILL.md)** — **Invoke when**: creating/updating a plan, changing issue status, or completing milestones | **Provides**: naming rules, required metadata labels (priority/type/status), and step-by-step procedure to keep local plan and GitHub artifacts in sync
+
+- **[`testing-policy`](.github/skills/testing-policy/SKILL.md)** — **Invoke when**: implementing or modifying any feature/fix; preparing issue closure or PR merge | **Provides**: required test layers (unit / integration / E2E / non-regression) and a before/after coverage diff procedure
+
+- **[`e2e-testing`](.github/skills/e2e-testing/SKILL.md)** — **Invoke when**: a user-facing flow changes or a critical integration path is introduced/modified | **Provides**: E2E checklist covering happy path + edge cases, CI-compatible execution, stable selectors, and deterministic setup/teardown
+
+- **[`session-logging`](.github/skills/session-logging/SKILL.md)** — **Invoke when**: starting/ending a session, completing issues/milestones, or syncing GitHub status | **Provides**: session journal file template with required sections (Status, Work Completed, Completion Gate evidence, Decisions, Blockers, GitHub Sync, Branch, Timestamp)
+
+- **[`rollback-rca`](.github/skills/rollback-rca/SKILL.md)** — **Invoke when**: an issue fails the completion gate 3 consecutive times | **Provides**: RCA procedure (architecture/dependency/scope analysis) + 3 recovery options (rescope / rollback / redesign) to present via `vscode_askQuestions`
+
+- **[`policy-coherence-audit`](.github/skills/policy-coherence-audit/SKILL.md)** — **Invoke when**: updating `AGENTS.MD`, merging new workflow rules, or noticing behavioral ambiguity during execution | **Provides**: cross-policy contradiction checklist covering language, interaction model, completion gates, scope, and skill reference coherence
+
+- **[`systematic-debugging`](.github/skills/systematic-debugging/SKILL.md)** — **Invoke when**: a bug or unexpected behavior is encountered, a test fails without obvious cause, or a previous fix attempt did not resolve the issue | **Provides**: evidence-based debugging procedure (reproduce → hypothesize → instrument → collect `debug-data.log` → analyze → fix → clean up), MCP tool integration for browser/network/runtime debugging
+
+Runtime binding rule: when a skill requires asking the user, use `vscode_askQuestions` and preserve the 5-option contract with option 4 fixed as `Freeform`.

package/assets/skills/README.md

@@ -0,0 +1,35 @@
+# Skills Index
+
+Use this index to quickly select the right skill file.
+
+## Decision & Interaction
+- `interaction-loop/SKILL.md` — 5-option iterative question flow, rating/next action/satisfaction checkpoints.
+- `breaking-change-paths/SKILL.md` — non-breaking vs breaking packaging, migration, unchanged quality gates.
+
+## Planning & Delivery
+- `planning-tracking/SKILL.md` — plan structure, milestone/issue flow.
+- `completion-gate/SKILL.md` — mandatory quality gate and double clean-pass rule.
+- `github-sync/SKILL.md` — mirror plan states to GitHub artifacts.
+- `session-logging/SKILL.md` — mandatory session reporting format.
+- `rollback-rca/SKILL.md` — failure handling, rollback, root-cause escalation.
+
+## Testing
+- `testing-policy/SKILL.md` — unit/integration/E2E/non-regression baseline and enforcement.
+- `e2e-testing/SKILL.md` — focused E2E execution checklist and anti-flakiness rules.
+
+## Policy Maintenance
+- `policy-coherence-audit/SKILL.md` — detect and fix contradictions across AGENTS policies.
+
+## Debugging
+- `systematic-debugging/SKILL.md` — evidence-based debugging via structured logging, `debug-data.log` analysis, and MCP tool integration.
+
+## Suggested invocation order (quick)
+1. `interaction-loop` (select path)
+2. `planning-tracking`
+3. `breaking-change-paths` (if relevant)
+4. `testing-policy` + `e2e-testing` (if relevant)
+5. `systematic-debugging` (if bug/unexpected behavior)
+6. `completion-gate`
+7. `session-logging` + `github-sync`
+8. `rollback-rca` (only if blocked/failing repeatedly)
+9. `policy-coherence-audit` (when editing policy)

package/assets/skills/breaking-change-paths/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: breaking-change-paths
+description: "Structured decision process between Non-Breaking and Breaking paths without relaxing quality gates."
+---
+# Breaking Change Decision Skill
+
+## Purpose
+Run a structured, future-proof decision process between Non-Breaking and Breaking paths without relaxing quality gates.
+
+## Use when
+- A task may affect public contracts, APIs, schemas, or behavioral compatibility
+- Root-cause fixes suggest architectural reshaping
+
+## Checklist
+- Explicitly classify impact: Non-Breaking vs Breaking.
+- Present both paths with:
+  - pros/cons
+  - risk level
+  - migration steps
+- State explicitly: quality gates are unchanged for both paths.
+- Require green unit/integration/E2E/non-regression tests in both cases.
+- If Breaking is selected, include migration and compatibility notes before execution.
+
+## Short examples
+- Non-Breaking path: adapter layer preserving old contract while introducing new internals.
+- Breaking path: remove deprecated endpoint + provide migration map + test updates.
+
+## Anti-patterns
+- Assuming breaking path without explicit selection
+- Treating breaking changes as exempt from test gates
+- Missing migration guidance

package/assets/skills/completion-gate/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: completion-gate
+description: "Mandatory quality gate for every Issue, Milestone, and PR with zero-error execution and no technical debt carry-over."
+---
+# Universal Completion Gate Skill
+
+## Purpose
+Enforce a mandatory quality gate for every Issue, Milestone, and PR with zero-error execution and no technical debt carry-over.
+
+## Use when
+- Closing an issue
+- Marking a milestone as done
+- Opening/merging a PR
+
+## Mandatory Gate (no exceptions)
+1. **Double consecutive review**: two full consecutive passes with **0 errors** and **0 warnings**.
+2. Fix all new issues and all pre-existing issues in touched scope.
+3. Lint/type-check/build/static analysis pass with 0 errors/0 warnings.
+4. Required tests pass (unit, integration if applicable, E2E if applicable, non-regression).
+5. Full suite passes; coverage is not below baseline.
+
+## Procedure
+1. Run full review/check suite.
+2. If any error/warning exists, fix and restart from step 1.
+3. Repeat until two clean consecutive passes are recorded.
+4. Only then mark status `done`/merge.
+
+## Done Criteria
+- Two consecutive clean review passes are documented.
+- No unresolved pre-existing issues in touched scope.
+
+## Anti-patterns
+- Single-pass approval
+- Ignoring warnings
+- Deferring known issues to “later”

package/assets/skills/e2e-testing/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: e2e-testing
+description: "Deterministic, CI-ready end-to-end validation for critical user flows."
+---
+# E2E Testing Skill
+
+## Purpose
+Define deterministic, CI-ready end-to-end validation for critical user flows.
+
+## Use when
+- A user-facing flow changes
+- A critical integration path is introduced or modified
+- Regression risk is non-trivial
+
+## Checklist
+- Cover at least one E2E scenario per critical flow.
+- Include happy path + key error/edge cases.
+- Use programmatic execution only (CI-compatible, non-interactive).
+- Prefer stable selectors (for example, `data-testid`).
+- Keep tests deterministic and isolated with proper setup/teardown.
+- Ensure E2E is part of non-regression validation before completion.
+
+## Short examples
+- Checkout flow: payment success + payment failure retry path.
+- Auth flow: valid login + expired token refresh path.
+
+## Anti-patterns
+- Manual-only E2E verification
+- Flaky timing-based waits without stable signals
+- Skipping E2E updates after flow changes

package/assets/skills/github-sync/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: github-sync
+description: "Keep local plan and GitHub project artifacts perfectly aligned with milestones, issues, labels, and statuses."
+---
+# GitHub Sync Skill
+
+## Purpose
+Keep local plan and GitHub project artifacts perfectly aligned (milestones, issues, labels, statuses, dependencies).
+
+## Use when
+- Creating/updating plan
+- Changing issue status
+- Completing milestones
+
+## Naming Rules
+- Milestone: `M<id> — <description>`
+- Issue: `[M<milestone_id>] I<issue_id> — <task>`
+
+## Required Metadata
+- Priority label: `P-critical|P-high|P-medium|P-low`
+- Type label: `feat|fix|refactor|chore|test`
+- Status label: `in-progress|review|blocked`
+- Milestone link
+- Dependency note: `depends on #<issue_number>`
+- Parent/child note: `part of #<issue_number>`
+
+## Procedure
+1. On plan create/update, create/update corresponding GitHub milestones/issues.
+2. On local issue status change, sync GitHub status + labels immediately.
+3. Close milestone when all linked issues are done.
+4. Ensure no orphan issues (every issue belongs to a milestone).
+
+## Done Criteria
+- Local plan == GitHub state (titles, labels, status, dependencies).
+
+## Anti-patterns
+- Local-only tracking
+- Orphan issues
+- Stale labels/status

package/assets/skills/interaction-loop/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: interaction-loop
+description: "Iterative decision loop with consistent user checkpoints and explicit stop criteria."
+---
+# Interaction Loop Skill
+
+## Purpose
+Enforce a strict iterative decision loop with consistent user checkpoints and explicit stop criteria.
+
+## Use when
+- Starting a new task
+- Hitting a decision point
+- Completing an autonomous run
+
+## Checklist
+- Ask exactly one clear question per iteration.
+- Provide exactly 5 options:
+  1) Non-Breaking Path
+  2) Breaking Path
+  3) Alternative Structural Path
+  4) Freeform (set enum value to `custom` — allows the user to type a free-text direction inline)
+  5) Autonomous Mode
+- Mark the recommended (most future-proof) option.
+- At autonomous completion, ask for: rating, next action, satisfaction.
+- Continue iterating until the exact stop phrase is provided: **"I am satisfied"**.
+
+## Short examples
+- Start-of-task question: "Which path should I execute first?" (5 options above).
+- End-of-run question: "Rate this result, choose the next action, and confirm satisfaction."
+
+## Anti-patterns
+- Multi-question prompts in one iteration
+- Missing one or more of the 5 mandatory options
+- Stopping without explicit "I am satisfied"