onecrawl 4.0.0-beta.1 → 4.0.0-beta.4

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

@@ -17,43 +17,70 @@ Run a structured, future-proof decision process when a task may affect public co
 | Surface | Breaking Impact | Examples |
 |---------|----------------|----------|
 | **CLI flags/args** | HIGH | Renaming `--headless` → `--head`, removing `--native` |
-| **MCP tool names/schemas** | HIGH | Renaming tool actions, changing JSON schemas |
+| **MCP tool names/schemas** | HIGH | Renaming tool actions, changing JSON input schemas |
 | **NAPI/PyO3 method signatures** | HIGH | Changing function names, param types, return types |
-| **Config keys** | MEDIUM | Renaming `config.toml` keys, changing defaults |
+| **Config keys** (`config.toml`) | MEDIUM | Renaming keys, changing defaults, removing options |
 | **Session file format** | MEDIUM | Changing `/tmp/onecrawl-session-*.json` structure |
-| **Daemon protocol** | MEDIUM | Changing HTTP/WS API between CLI and daemon |
-| **Internal crate APIs** | LOW | Changing `pub` functions in workspace crates |
-| **CDP layer** | LOW | Internal CDP wrapper changes |
+| **Daemon HTTP/WS protocol** | MEDIUM | Changing API between CLI ↔ daemon communication |
+| **Profile file format** | MEDIUM | Changing profile storage schema |
+| **Internal crate `pub` APIs** | LOW | Changing `pub fn` in workspace crates (internal consumers only) |
+| **CDP layer wrappers** | LOW | Internal CDP abstractions (no external consumers) |
+
+## Concrete OneCrawl Examples
+
+### Non-Breaking Change Examples
+```
+✅ Adding new CLI flag: `onecrawl session start --timeout 30`
+✅ Adding new MCP action: `onecrawl run browser get_accessibility_snapshot`
+✅ New config key with default: config.toml gains `stealth.level = "standard"`
+✅ Adding optional field to session JSON: `{"pid": 1234, "created_at": "..."}`
+✅ New NAPI export function (additive)
+```
+
+### Breaking Change Examples
+```
+⛔ Renaming `onecrawl run browser` → `onecrawl browser exec`
+⛔ Removing `--native` flag from session start
+⛔ Changing MCP tool "browser" schema (existing clients break)
+⛔ Changing session JSON key: "session_name" → "name"
+⛔ Changing PyO3 class method signature
+```
 
 ## Decision Framework
 
 ### Non-Breaking Path
 - Add new flags/options alongside existing ones
-- Deprecation warnings before removal (minimum 2 alpha releases)
+- Deprecation warnings before removal (minimum 2 beta releases)
 - Backward-compatible config: new keys get defaults, old keys still work
 - Additive MCP actions (new actions, not renamed ones)
+- Session JSON: add optional fields, never remove/rename existing
 
 ### Breaking Path (requires justification)
-- Must document: what breaks, who is affected, migration steps
-- Must provide: migration guide or automated migration tool
-- Must bump: version increment that signals the break
-- Quality gates unchanged: unit/integration/E2E/non-regression must still pass
+- [ ] Document: what breaks, who is affected, migration steps
+- [ ] Migration: provide guide or automated migration in code
+- [ ] Version: bump that signals the break (beta → beta.N+1 minimum)
+- [ ] CHANGELOG: explicit "BREAKING" section with before/after examples
+- [ ] Quality gates unchanged: completion-gate must still pass
 
 ## Procedure
-1. Identify all contract surfaces affected.
-2. For each, classify as non-breaking or breaking.
-3. Present options via `ask_user` with the compatibility triad:
-   - Non-Breaking Path (additive/compatible)
-   - Breaking Path (with migration plan)
-   - Alternative Structural Path (redesign to avoid the break)
+1. Identify all contract surfaces affected (use table above).
+2. For each surface, classify impact as non-breaking or breaking.
+3. If any HIGH-impact surface is affected, present options to user:
+   - **Non-Breaking Path** (additive/compatible — deprecate first)
+   - **Breaking Path** (with migration plan)
+   - **Alternative Structural Path** (redesign to avoid the break)
 4. Document decision in commit message and CHANGELOG.
+5. If breaking: add `BREAKING:` prefix to commit message.
 
 ## Done Criteria
 - Decision documented with rationale.
 - Migration steps provided for any breaking change.
-- All quality gates pass.
+- All quality gates pass (completion-gate skill).
+- CHANGELOG updated with breaking change notice if applicable.
 
 ## Anti-patterns
-- Silent breaking changes (no documentation)
+- Silent breaking changes (no documentation, no CHANGELOG entry)
 - Breaking changes without version bump
-- Assuming internal changes are safe (NAPI/PyO3 are public)
+- Assuming internal crate changes are safe (NAPI/PyO3 expose them)
+- Removing deprecated items before 2-release grace period
+- Breaking MCP schemas without client-side migration path

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

@@ -21,37 +21,74 @@ Enforce a mandatory quality gate for every Issue, Milestone, and PR with zero-er
 
 ## OneCrawl Gate Commands
 
-Run these in order. Both must pass **twice consecutively** with zero output:
+Run in order. All must pass **twice consecutively** with zero output:
 
 ```bash
-# 1. Clippy (lint + static analysis) - 0 warnings required
+# 1. Clippy (lint + static analysis) — 0 warnings required
 cargo clippy --workspace --exclude onecrawl-e2e --exclude onecrawl-python -- -W clippy::all
 
 # 2. Build check (fast compilation verification)
-cargo check --workspace
+cargo check -p onecrawl-cli-rs -p onecrawl-mcp-rs
 
-# 3. Test suite (all tests, single-threaded for determinism)
+# 3. Test suite (573 tests, single-threaded for determinism)
 cargo test --workspace --exclude onecrawl-e2e --exclude onecrawl-python -- --test-threads=1
 
-# 4. Health check (binary runs correctly)
+# 4. Release build (binary artifact)
+cargo build --release -p onecrawl-cli-rs
+
+# 5. Health check (binary runs correctly)
 ./target/release/onecrawl health
 ./target/release/onecrawl --version
 ```
 
-Acceptable warnings: `onecrawl-browser` vendor crate (1 warning, do not touch).
+Acceptable warnings: `onecrawl-browser` vendor crate (1 pre-existing clippy warning — do not touch).
+
+## Gate Execution Checklist
+
+- [ ] **Pass 1 — Clippy**: 0 warnings in owned crates
+- [ ] **Pass 1 — Build**: `cargo check` exits 0
+- [ ] **Pass 1 — Tests**: 573 tests passed, 0 failed
+- [ ] **Pass 1 — Binary**: `onecrawl --version` prints `v4.0.0-beta.1`
+- [ ] **Pass 2 — Clippy**: identical to pass 1
+- [ ] **Pass 2 — Tests**: identical to pass 1
+- [ ] **No regressions**: test count ≥ baseline recorded before changes
+- [ ] **Commit**: use `git commit -F /tmp/commit-msg.txt` with Co-authored-by trailer
+
+## CI Verification (release.yml + rust-ci.yml)
+
+After push, verify CI on GitHub:
+
+```bash
+# Check CI status for current branch
+gh run list --repo giulio-leone/onecrawl --branch "$(git branch --show-current)" --limit 5
+
+# Watch a specific run
+gh run watch <run-id> --repo giulio-leone/onecrawl
+
+# Get failed job logs
+gh run view <run-id> --repo giulio-leone/onecrawl --log-failed
+```
+
+**rust-ci.yml** gates: clippy, test (--test-threads=1), build check.
+**release.yml** gates: 5-platform matrix (linux-x64, linux-arm64, macos-x64, macos-arm64, windows-x64).
 
 ## Procedure
-1. Run all gate commands above.
-2. If any error/warning exists in owned crates, fix and restart from step 1.
-3. Repeat until two clean consecutive passes are recorded.
-4. Only then mark status `done`/merge.
+1. Record baseline: `cargo test ... 2>&1 | tail -1` (note test count).
+2. Run all gate commands above.
+3. If any error/warning exists in owned crates, fix and restart from step 1.
+4. Repeat until two clean consecutive passes are recorded.
+5. Verify CI is green after push (`gh run list`).
+6. Only then mark status `done`/merge.
 
 ## Done Criteria
 - Two consecutive clean review passes are documented.
 - No unresolved pre-existing issues in touched scope.
+- CI (rust-ci.yml) is green on the pushed branch.
 
 ## Anti-patterns
 - Single-pass approval
-- Ignoring warnings
+- Ignoring warnings ("it's just one warning")
 - Deferring known issues to "later"
 - Excluding tests with `#[ignore]` to pass the gate
+- Pushing without verifying CI status
+- Using `cargo check --workspace` when `cargo check -p <crate>` suffices (slower)

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

@@ -13,12 +13,13 @@ Ensure critical user flows work end-to-end with deterministic, CI-compatible exe
 ## OneCrawl E2E Architecture
 
 E2E tests live in `packages/onecrawl-rust/crates/onecrawl-e2e/` and require a running Chrome instance.
+Session state files: `/tmp/onecrawl-session*.json` (per-PID markers for multi-agent isolation).
 
 ```bash
 # Run E2E tests (requires Chrome)
 cargo test -p onecrawl-e2e -- --test-threads=1
 
-# Manual E2E verification (quick smoke test)
+# Manual E2E smoke test
 onecrawl session start -H                    # Headless Chrome
 onecrawl navigate https://example.com        # Navigate
 onecrawl get title                           # Verify page loaded
@@ -34,20 +35,59 @@ onecrawl session close                       # Cleanup
 5. **Config management**: config set → config show → verify change persists
 6. **Auth persistence**: auth-state save → session close → session start → auth-state load
 7. **Stealth**: session start → stealth detection-audit → verify 0% headless detection
+8. **MCP server**: onecrawl mcp → tool discovery → action execution → clean shutdown
 
-## Checklist
+## Multi-Agent E2E Test Template
+
+Tests verifying process-level isolation between concurrent agents:
+
+```bash
+# Agent A (PID-based session isolation)
+onecrawl session start -H -s "agent-$$-a"
+onecrawl navigate https://example.com
+TITLE_A=$(onecrawl get title)
+
+# Agent B (separate session, same daemon)
+onecrawl session start -H -s "agent-$$-b"
+onecrawl navigate https://httpbin.org
+TITLE_B=$(onecrawl get title)
+
+# Verify isolation — each session sees its own page
+[ "$TITLE_A" != "$TITLE_B" ] && echo "PASS: isolation OK"
+
+# Cleanup both
+onecrawl session close -s "agent-$$-a"
+onecrawl session close -s "agent-$$-b"
+```
+
+## Pre-Test Checklist
+- [ ] Chrome/Chromium installed and accessible
+- [ ] No stale sessions: `ls /tmp/onecrawl-session*.json` (should be empty)
+- [ ] No orphan Chrome processes: `pgrep -f "chrome.*remote-debugging" | head`
+- [ ] Release binary built: `cargo build --release -p onecrawl-cli-rs`
+
+## Test Execution Checklist
 - [ ] Happy path covered for each critical flow
 - [ ] Edge cases: invalid input, missing Chrome, concurrent sessions
-- [ ] Cleanup: sessions closed, temp files removed, profiles deleted
-- [ ] Deterministic: no timing-dependent assertions
+- [ ] Deterministic: no timing-dependent assertions (use wait-for, not sleep)
 - [ ] Stable selectors: use `data-testid` or semantic selectors
 - [ ] CI-compatible: headless mode, no GUI dependencies
 
+## Post-Test Cleanup Checklist
+- [ ] All sessions closed: `onecrawl session close` or `onecrawl session close -s <name>`
+- [ ] Temp files removed: `rm -f /tmp/onecrawl-session*.json`
+- [ ] No orphan Chrome: verify `pgrep -f "chrome.*remote-debugging"` returns empty
+- [ ] Profiles cleaned: `onecrawl profile delete <test-profile>` if created
+- [ ] Daemon stopped (if started for test): `onecrawl daemon stop`
+
 ## Done Criteria
 - All critical flows pass in headless mode.
 - No leaked browser processes after test completion.
+- No residual session files in `/tmp/`.
 
 ## Anti-patterns
 - Hard-coded sleep/timeouts instead of wait-for conditions
-- Tests that depend on network state
+- Tests that depend on network state or external services
 - Shared mutable state between test cases
+- Forgetting to close sessions (leaks Chrome processes)
+- Using `--test-threads=N` where N > 1 (session conflicts)

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

@@ -11,43 +11,113 @@ Keep local plan and GitHub project artifacts perfectly aligned.
 - Creating or updating a plan
 - Changing issue status
 - Completing milestones
+- Preparing a release
 
 ## OneCrawl Repository
 - Owner: `giulio-leone`
 - Repo: `onecrawl`
-- Branch: `main`
-- Tags: `v4.0.0-alpha.XX`
+- Default branch: `main`
+- Current tag: `v4.0.0-beta.1`
+- CI workflows: `release.yml` (5-platform matrix), `rust-ci.yml`
 
 ## Naming Rules
 - Milestones: `MX: <Title>` (e.g., `M14: Deep Audit`)
 - Issues: `<type>: <description>` (e.g., `fix: session name path traversal`)
 - Branches: `<type>/<short-description>` (e.g., `fix/session-path-traversal`)
-- Tags: `v4.0.0-alpha.XX` (SemVer pre-release)
+- Tags: SemVer pre-release (e.g., `v4.0.0-beta.2`)
+- Commits: use `git commit -F /tmp/commit-msg.txt` (not `-m`), always include Co-authored-by trailer
 
 ## Required Labels
 - Priority: `P0-critical`, `P1-high`, `P2-medium`, `P3-low`
 - Type: `bug`, `feature`, `refactor`, `docs`, `chore`
 - Status: `todo`, `in-progress`, `review`, `done`, `blocked`
 
+## gh CLI Commands
+
+```bash
+# Create milestone
+gh api repos/giulio-leone/onecrawl/milestones -f title="M15: Title" -f state="open"
+
+# Create issue with labels and milestone
+gh issue create --repo giulio-leone/onecrawl \
+  --title "fix: description" \
+  --body "Details..." \
+  --label "bug,P1-high,in-progress" \
+  --milestone "M15: Title"
+
+# Update issue status
+gh issue edit <number> --repo giulio-leone/onecrawl --remove-label "in-progress" --add-label "done"
+
+# Close issue
+gh issue close <number> --repo giulio-leone/onecrawl
+
+# List open issues for a milestone
+gh issue list --repo giulio-leone/onecrawl --milestone "M15: Title" --state open
+
+# Check CI status
+gh run list --repo giulio-leone/onecrawl --branch main --limit 5
+```
+
 ## Procedure
 1. Create GitHub milestone matching local plan milestone.
 2. Create issues for each task, linked to milestone.
 3. Apply labels (priority + type + status).
-4. Update issue status as work progresses.
-5. Close milestone when all issues are done.
+4. Update issue status labels as work progresses.
+5. Close issues when completion gate passes.
+6. Close milestone when all issues are done.
+
+## OneCrawl Release Workflow
+
+### Pre-Release Checklist
+- [ ] All milestone issues closed
+- [ ] Completion gate passed (2 consecutive clean runs)
+- [ ] CHANGELOG.md updated with release notes
+- [ ] Version bumped in `packages/onecrawl-rust/Cargo.toml`
+- [ ] `cargo check --workspace` (propagates version to all crates)
+
+### Release Steps
+```bash
+# 1. Version bump
+# Edit packages/onecrawl-rust/Cargo.toml — update version field
+cargo check --workspace
+
+# 2. Update CHANGELOG.md — add release section
+
+# 3. Commit
+echo "chore: release v4.0.0-beta.2
+
+- <summary of changes>
+
+Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" > /tmp/release-msg.txt
+git add -A && git commit -F /tmp/release-msg.txt
+
+# 4. Tag and push
+git tag v4.0.0-beta.2
+git push origin main --tags
+
+# 5. npm publish (from packages/onecrawl/)
+cd packages/onecrawl
+npm version 4.0.0-beta.2 --no-git-tag-version
+npm publish --tag beta --access public
+
+# 6. Verify release.yml CI (5-platform matrix)
+gh run list --repo giulio-leone/onecrawl --workflow release.yml --limit 1
+```
 
-## OneCrawl Release Sync
-After each alpha release:
-1. Tag: `git tag v4.0.0-alpha.XX && git push origin main --tags`
-2. npm: `npm publish --tag alpha --access public`
-3. CHANGELOG: update with release notes
+### Post-Release Verification
+- [ ] `gh run view <id>` — all 5 platforms green
+- [ ] `npm view onecrawl versions --json | tail` — version published
+- [ ] GitHub tag visible: `gh release list --repo giulio-leone/onecrawl`
 
 ## Done Criteria
 - All plan items have matching GitHub artifacts.
 - Labels are applied consistently.
 - Milestones reflect actual progress.
+- Releases are tagged, CI-verified, and npm-published.
 
 ## Anti-patterns
 - Local plan diverges from GitHub state
 - Missing labels on issues
 - Stale milestones with no issues
+- Pushing tags before CI verification
+- Using `git commit -m` instead of `git commit -F`

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

@@ -13,14 +13,14 @@ Enforce a strict iterative decision loop with consistent user checkpoints and ex
 - Completing an autonomous run
 
 ## Default 5-Option Structure
-1. **Recommended Development Path** (mark with star as most future-proof)
+1. **Recommended Development Path** (mark with ⭐ as most future-proof)
 2. **Alternative Development Path A**
 3. **Alternative Development Path B**
 4. **Freeform** — set enum value to `custom` (allows free-text input)
 5. **Autonomous Mode**
 
 ## Escalation (Compatibility Triad)
-Use ONLY when there is a concrete compatibility/contract impact:
+Use ONLY when there is a concrete compatibility/contract impact (see breaking-change-paths skill):
 1. Non-Breaking Path
 2. Breaking Path
 3. Alternative Structural Path
@@ -31,17 +31,62 @@ Use ONLY when there is a concrete compatibility/contract impact:
 Each option must include:
 `<Title> — Why: <reason> | Leads to: <next step> | Risk: <low|medium|high>`
 
+### OneCrawl Example Cards
+```
+⭐ 1. Add new --timeout flag (non-breaking)
+   Why: Users need session timeouts | Leads to: CLI + daemon changes | Risk: low
+
+2. Replace --headless with --head (breaking)
+   Why: Simpler flag name | Leads to: CLI + docs + migration | Risk: high
+
+3. Config-only timeout (no CLI flag)
+   Why: Minimal surface change | Leads to: config.toml + docs | Risk: low
+
+4. Freeform — describe your preferred approach
+
+5. Autonomous Mode — I'll implement the recommended path and report back
+```
+
+## Copilot CLI Implementation
+
+In Copilot CLI runtime, the interaction loop uses natural language responses (not tool calls).
+The agent presents options as a numbered list in the response and the user replies with their choice.
+
+### Autonomous Mode Behavior
+When the user selects Autonomous Mode (option 5):
+1. Agent implements the recommended path (option 1) without further prompts.
+2. Follows all applicable skills (planning-tracking, testing-policy, completion-gate).
+3. On completion, presents a summary with:
+   - What was done
+   - Test results (exact counts)
+   - Files changed
+   - Asks: "Rate this result (1-5), suggest next action, or say 'I am satisfied'."
+4. Loop continues until the exact phrase **"I am satisfied"** is received.
+
+### Decision Tracking
+Record each decision point in the session database:
+```sql
+INSERT INTO session_state (key, value) VALUES
+  ('decision_1', 'Option 1: Add --timeout flag (non-breaking) — user chose at 2024-01-15T10:30Z');
+```
+
 ## Rules
 - One clear question per iteration
 - Exactly 5 options every time
-- Option 4 is ALWAYS Freeform (hard invariant)
+- Option 4 is ALWAYS Freeform (hard invariant — label "Freeform", enum value `custom`)
 - Options 1-3 carry forward from previous iteration unless explicitly replaced
-- Mark recommendation with star; explain changes
+- Mark recommendation with ⭐; explain if recommendation changes between iterations
 - At autonomous completion: ask for rating, next action, satisfaction
-- Loop stops ONLY on exact phrase: "I am satisfied"
+- Loop stops ONLY on exact phrase: **"I am satisfied"**
+
+## Done Criteria
+- User has explicitly ended the loop with "I am satisfied".
+- All decisions are documented in session log.
 
 ## Anti-patterns
 - Multi-question prompts in one iteration
-- Missing or renaming Freeform option
+- Missing or renaming Freeform option (option 4)
 - Stopping without explicit "I am satisfied"
-- Using compatibility triad as default (it's an escalation)
+- Using compatibility triad as default (it's an escalation for breaking changes)
+- Implementing without presenting options first
+- Changing recommendation without explaining why

package/assets/skills/planning-tracking/SKILL.md

@@ -19,42 +19,85 @@ interface Milestone { id: string; description: string; priority: "critical"|"hig
 interface Issue { id: string; task: string; priority: "critical"|"high"|"medium"|"low"; status: "todo"|"in_progress"|"review"|"done"|"blocked"; depends_on: string[]; children: Record<string, Issue>; }
 ```
 
+## SQL-Based Tracking
+
+Use the session database for operational tracking:
+
+```sql
+-- Create plan items
+INSERT INTO todos (id, title, description, status) VALUES
+  ('m1-cdp-refactor', 'Refactor CDP error handling', 'Update onecrawl-cdp error types to use thiserror, propagate to onecrawl-mcp-rs', 'pending'),
+  ('m1-cli-flags', 'Add --timeout flag', 'Add session timeout to onecrawl-cli-rs session start', 'pending'),
+  ('m1-tests', 'Add timeout tests', 'Unit tests for session timeout in cli-rs and cdp', 'pending');
+
+-- Declare dependencies
+INSERT INTO todo_deps (todo_id, depends_on) VALUES
+  ('m1-cli-flags', 'm1-cdp-refactor'),   -- CLI depends on CDP changes
+  ('m1-tests', 'm1-cli-flags');            -- Tests depend on implementation
+
+-- Find ready items (no pending dependencies)
+SELECT t.id, t.title FROM todos t
+WHERE t.status = 'pending'
+AND NOT EXISTS (
+  SELECT 1 FROM todo_deps td
+  JOIN todos dep ON td.depends_on = dep.id
+  WHERE td.todo_id = t.id AND dep.status != 'done'
+);
+
+-- Update status as work progresses
+UPDATE todos SET status = 'in_progress' WHERE id = 'm1-cdp-refactor';
+UPDATE todos SET status = 'done' WHERE id = 'm1-cdp-refactor';
+```
+
 ## OneCrawl Workspace Parallelism Rules
 
 Safe to parallelize:
-- Changes in different crates (e.g., `onecrawl-cdp` + `onecrawl-parser`)
+- Changes in independent crates (e.g., `onecrawl-crypto` + `onecrawl-parser`)
 - NAPI + PyO3 bindings (independent build targets)
 - Documentation + code changes
+- Tests in different crates (with `--test-threads=1` per crate)
 
 NOT safe to parallelize:
 - Changes in a crate + its dependents (e.g., `onecrawl-cdp` + `onecrawl-cli-rs`)
 - Multiple changes to the same file
-- Version bumps (must be sequential: Cargo.toml then package.json)
+- Version bumps (must be sequential: Cargo.toml → package.json → tag)
+- Any two changes that touch session state or `/tmp/onecrawl-session*.json`
 
 ## OneCrawl Crate Dependency Graph
 ```
-onecrawl-cli-rs
-  -> onecrawl-mcp-rs -> onecrawl-cdp -> onecrawl-browser
-  -> onecrawl-server -> onecrawl-cdp
-  -> onecrawl-core
-  -> onecrawl-crypto
-  -> onecrawl-parser
-  -> onecrawl-storage
+onecrawl-cli-rs (binary)
+  ├── onecrawl-mcp-rs ──→ onecrawl-cdp ──→ onecrawl-browser (vendor)
+  ├── onecrawl-server ──→ onecrawl-cdp
+  ├── onecrawl-core
+  ├── onecrawl-crypto
+  ├── onecrawl-parser
+  └── onecrawl-storage
+
+Independent leaf crates (safe to change in parallel):
+  onecrawl-core, onecrawl-crypto, onecrawl-parser, onecrawl-storage
+
+High-impact crates (changes cascade):
+  onecrawl-cdp (affects: mcp-rs, server, cli-rs)
+  onecrawl-browser (affects: cdp, mcp-rs, server, cli-rs)
 ```
 
 ## Procedure
-1. Build plan before implementation.
-2. Assign unique IDs to milestones/issues.
-3. Declare dependencies for every issue.
-4. Execute by dependency order, then priority (critical then high then medium then low).
-5. Run independent same-priority milestones in parallel when safe.
-6. Update statuses continuously.
+1. Build plan before implementation (use SQL todos).
+2. Assign unique IDs to milestones/issues (kebab-case: `m1-feature-name`).
+3. Declare dependencies using `todo_deps` table.
+4. Execute by dependency order, then priority (critical → high → medium → low).
+5. Run independent same-priority items in parallel when safe per rules above.
+6. Update statuses continuously (`pending` → `in_progress` → `done`).
+7. Sync to GitHub when milestones complete (github-sync skill).
 
 ## Done Criteria
-- Plan exists, is up-to-date, and reflects actual execution state.
-- Dependencies are respected and parallel work is safe.
+- Plan exists in SQL todos, is up-to-date, and reflects actual execution state.
+- Dependencies are respected and parallel work follows safety rules.
+- GitHub artifacts are synced (github-sync skill).
 
 ## Anti-patterns
 - Starting implementation without a plan
-- Missing dependency declarations
+- Missing dependency declarations (causes parallel conflicts)
 - Running blocked items in parallel
+- Changing `onecrawl-cdp` and `onecrawl-cli-rs` simultaneously
+- Using free-form notes instead of structured SQL tracking