---
name: v8-v8-workflow
description: "Manages git task isolation and environment setup in V8. Use at the start of any new task or bug fix. Do not use for general C++ editing."
license: "NOASSERTION"
metadata:
  decimalai-skill-id: "a4a099be-1f7f-4de6-908f-725d686a058e"
  decimalai-version-id: "4645091f-3682-4e9f-a52c-4ba01082b098"
  decimalai-version: "3"
  decimalai-body-sha256: "44d051e7c2808cd5897d3494d95c8dff11d02c3475424804ad535ddb6b607ef0"
  decimalai-name: "v8/v8-workflow"
  decimalai-format: "1"
  decimalai-invocation: "model"
  decimalai-category: "productivity"
  decimalai-source: "https://app.decimal.ai/s/v8-v8-workflow@3/SKILL.md"
---
# V8 Workflow Skill

This skill defines the standard process for setting up and managing your
development environment in V8.

## 1. Task Initialization (Isolation Strategy)

Before starting any feature or bug fix, you MUST decide on a strategy:

- **Isolated Strategy (Recommended)**: Create a dedicated git worktree and
  branch (`task-<id>`) to prevent cross-contamination between tasks. Run
  `agents/scripts/create_worktree.sh <id> [base_branch]` and use the worktree
  path printed to stdout (`worktrees/task-<id>`).

- **Reuse Strategy**: Work in the current directory and branch.

  - Use this only if the user explicitly requests to continue previous work or
    prefers a single-branch workflow.

- **Issue Reset**: If starting a *new* task without a worktree, always ask
  before resetting the `git cl` issue.

## 2. Path Management in Worktrees

When using an isolated worktree (e.g., `worktrees/task-fix-10010110`), you MUST
ensure that all file-modifying tools (`replace`, `write_file`, etc.) target the
correct directory:

- **Explicit Prefixing**: Always prefix `file_path` arguments with the worktree
  directory. For example, use `worktrees/task-fix-10010110/src/wasm/...` instead
  of `src/wasm/...`.
- **Tool Context**: Be aware that relative paths starting with `src/` or `test/`
  will default to the main repository's root, violating task isolation.

## 3. Environment Setup

Once the branch is ready, ensure your local environment is configured for V8
development:

- **depot_tools**: Ensure it is in your PATH.
  - `export PATH=$PATH:$HOME/depot_tools`
- **Output Directory**: Use standard V8 output directories (e.g.,
  `out/x64.debug`).

## 4. Available Tools

- **[create_worktree.sh](../../scripts/create_worktree.sh)**: Automates task
  isolation and setup. Automatically detects whether the repository is in a
  standard Git checkout (creating a Git worktree) or a Rift Btrfs workspace
  (forking an isolated Btrfs subvolume). Use this at the start of every new
  task.
- **[cleanup_worktree.sh](../../scripts/cleanup_worktree.sh)**: Safely removes
  task workspaces (Git worktrees or Rift subvolumes) and prunes remnants once a
  CL is landed or abandoned.
- **[setup_worktree_build.py](../../../tools/dev/setup_worktree_build.py)**:
  Sets up shared `gclient` dependency symlinks in a worktree (invoked
  automatically by `create_worktree.sh` and `gm.py`). When a worktree's `DEPS`
  differs from the main repository, it caches a synced dependency tree under
  `<main_repo>/worktrees/.deps_cache/<hash>` and automatically prunes old
  unreferenced entries (keeping at least the 3 most recent).
  - `tools/dev/setup_worktree_build.py prune-cache <main_repo>`: Manually prune
    unreferenced `.deps_cache` entries (keeping all referenced entries and the 3
    most recently used).
  - `tools/dev/setup_worktree_build.py clear-cache <main_repo>`: Remove all
    entries in `<main_repo>/worktrees/.deps_cache`.