harness-everything 0.2.0 → 0.2.1

package/todo-driven-workflow/SKILL.md

@@ -1,54 +1,54 @@
----
-name: todo-driven-workflow
-description: Enforces a deliberate, step-by-step execution loop.
-author: Miya Daniel | Harness Core Team
-version: 1.1.0
-metadata:
-  type: harness-discipline
----
-
-# Todo-Driven Workflow (以 TODO 驅動的自動化工作流)
-
-## 📋 Skill Contract
-
-| Component | Specification |
-| :--- | :--- |
-| **Trigger / Input** | Tier 2/3 Task Identification. Input: High-level task description. |
-| **Expected Output** | Granular execution state. A series of terminal calls to `todo-cli.js`. |
-| **State Mutations** | MUST write to `.claude/harness-state/todo-state.json` via CLI. |
-| **Enforcement Gate** | `node harness-everything/scripts/todo-cli.js`. Exits with Code 1 if multitasking, bypassing initialization, or skipping `verify-gate.js`. |
-
-This skill enforces a disciplined execution loop. It prevents "hallucinated progress" by forcing the Agent to track exact state and prove completion before moving to the next step. 
-
----
-
-## ⚡ Core Trigger (觸發時機)
-This workflow is **the default operating behavior** for any complex, multi-step, or multi-file development tasks (Tier 2 and Tier 3).
-
-## ⚙️ Execution Method
-
-| Environment | Primary Task Tracker | Implementation Method |
-| :--- | :--- | :--- |
-| **All Environments** | `todo-cli.js` | You MUST use `node harness-everything/scripts/todo-cli.js` for all state transitions. Do NOT rely on prompt text. |
-
----
-
-## 🔄 Execution Loop: Think > Try > Summarize > Record
-
-### 1. Analyze and Plan (Think)
-Break the high-level goal into **3 to 7 concrete, verifiable sub-tasks**.
-
-### 2. Initialize the Todo List (Record)
-- **CRITICAL ACTION**: You MUST use the `run_in_terminal` tool to run `node harness-everything/scripts/todo-cli.js init "Task 1" "Task 2"` BEFORE modifying any code.
-- *Rule*: The terminal output will confirm the list is initialized.
-
-### 3. Step-by-Step Execution
-1. **Start**: Use `run_in_terminal` to run `node harness-everything/scripts/todo-cli.js start <id>`. **If you try to start two tasks, the script will crash and block you.**
-2. **Execute**: Perform the necessary actions (read files, grep, run terminal commands, edit files).
-3. **Verify**: The validation gate is hardcoded into the completion step.
-4. **Complete**: Use `run_in_terminal` to run `node harness-everything/scripts/todo-cli.js complete <id>`. If the internal `verify-gate.js` check fails, this command will Exit 1 and block you.
-
-### 4. Handling Blocker Failures (Dynamic Adaptation)
-If a step fails:
-- Use `node harness-everything/scripts/todo-cli.js add "Fix specific error"` to insert a blocker.
-- Do NOT silently ignore or bypass the error.
+---
+name: todo-driven-workflow
+description: Enforces a deliberate, step-by-step execution loop.
+author: Miya Daniel | Harness Core Team
+version: 1.1.0
+metadata:
+  type: harness-discipline
+---
+
+# Todo-Driven Workflow (以 TODO 驅動的自動化工作流)
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Tier 2/3 Task Identification. Input: High-level task description. |
+| **Expected Output** | Granular execution state. A series of terminal calls to `todo-cli.js`. |
+| **State Mutations** | MUST write to `.claude/harness-state/todo-state.json` via CLI. |
+| **Enforcement Gate** | `node harness-everything/scripts/todo-cli.js`. Exits with Code 1 if multitasking, bypassing initialization, or skipping `verify-gate.js`. |
+
+This skill enforces a disciplined execution loop. It prevents "hallucinated progress" by forcing the Agent to track exact state and prove completion before moving to the next step. 
+
+---
+
+## ⚡ Core Trigger (觸發時機)
+This workflow is **the default operating behavior** for any complex, multi-step, or multi-file development tasks (Tier 2 and Tier 3).
+
+## ⚙️ Execution Method
+
+| Environment | Primary Task Tracker | Implementation Method |
+| :--- | :--- | :--- |
+| **All Environments** | `todo-cli.js` | You MUST use `node harness-everything/scripts/todo-cli.js` for all state transitions. Do NOT rely on prompt text. |
+
+---
+
+## 🔄 Execution Loop: Think > Try > Summarize > Record
+
+### 1. Analyze and Plan (Think)
+Break the high-level goal into **3 to 7 concrete, verifiable sub-tasks**.
+
+### 2. Initialize the Todo List (Record)
+- **CRITICAL ACTION**: You MUST use the `run_in_terminal` tool to run `node harness-everything/scripts/todo-cli.js init "Task 1" "Task 2"` BEFORE modifying any code.
+- *Rule*: The terminal output will confirm the list is initialized.
+
+### 3. Step-by-Step Execution
+1. **Start**: Use `run_in_terminal` to run `node harness-everything/scripts/todo-cli.js start <id>`. **If you try to start two tasks, the script will crash and block you.**
+2. **Execute**: Perform the necessary actions (read files, grep, run terminal commands, edit files).
+3. **Verify**: The validation gate is hardcoded into the completion step.
+4. **Complete**: Use `run_in_terminal` to run `node harness-everything/scripts/todo-cli.js complete <id>`. If the internal `verify-gate.js` check fails, this command will Exit 1 and block you.
+
+### 4. Handling Blocker Failures (Dynamic Adaptation)
+If a step fails:
+- Use `node harness-everything/scripts/todo-cli.js add "Fix specific error"` to insert a blocker.
+- Do NOT silently ignore or bypass the error.

package/using-git-worktrees/SKILL.md

@@ -1,161 +1,161 @@
----
-name: using-git-worktrees
-description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
-author: Miya Daniel | Harness Core Team
-version: 0.2.0
----
-
-# Using Git Worktrees
-
-## 📋 Skill Contract
-
-| Component | Specification |
-| :--- | :--- |
-| **Trigger / Input** | Starting feature work that needs isolation from the current workspace, or before executing an implementation plan. |
-| **Expected Output** | An isolated workspace (native worktree tool preferred, `git worktree add` fallback) with dependencies installed and a clean baseline test run confirmed. |
-| **State Mutations** | May create a new worktree directory/branch (`.worktrees/<branch>` by default) and add it to `.gitignore` if not already ignored. |
-| **Enforcement Gate** | **MUST** detect an already-isolated workspace first (`GIT_DIR != GIT_COMMON`, excluding submodules) and skip creating a redundant one. **MUST** verify the worktree directory is gitignored before creating it. **MUST** get human consent before creating a new worktree if no preference was already declared. |
-
-## Overview
-
-Ensure work happens in an isolated workspace. Prefer your platform's native worktree tools. Fall back to manual git worktrees only when no native tool is available.
-
-**Core principle:** Detect existing isolation first. Then use native tools. Then fall back to git. Never fight the harness.
-
-**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
-
-## Step 0: Detect Existing Isolation
-
-**Before creating anything, check if you are already in an isolated workspace.**
-
-```bash
-GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
-GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
-BRANCH=$(git branch --show-current)
-```
-
-**Submodule guard:** `GIT_DIR != GIT_COMMON` is also true inside git submodules. Before concluding "already in a worktree," verify you are not in a submodule:
-
-```bash
-# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
-git rev-parse --show-superproject-working-tree 2>/dev/null
-```
-
-**If `GIT_DIR != GIT_COMMON` (and not a submodule):** You are already in a linked worktree. Skip to Step 2 (Project Setup). Do NOT create another worktree.
-
-Report with branch state:
-- On a branch: "Already in isolated workspace at `<path>` on branch `<name>`."
-- Detached HEAD: "Already in isolated workspace at `<path>` (detached HEAD, externally managed). Branch creation needed at finish time."
-
-**If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout.
-
-Has the user already indicated their worktree preference in your instructions? If not, ask for consent before creating a worktree:
-
-> "Would you like me to set up an isolated worktree? It protects your current branch from changes."
-
-Honor any existing declared preference without asking. If the user declines consent, work in place and skip to Step 2.
-
-## Step 1: Create Isolated Workspace
-
-**You have two mechanisms. Try them in this order.**
-
-### 1a. Native Worktree Tools (preferred)
-
-The user has asked for an isolated workspace (Step 0 consent). Do you already have a way to create a worktree? It might be a tool with a name like `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag. If you do, use it and skip to Step 2.
-
-Native tools handle directory placement, branch creation, and cleanup automatically. Using `git worktree add` when you have a native tool creates phantom state your harness can't see or manage.
-
-Only proceed to Step 1b if you have no native worktree tool available.
-
-### 1b. Git Worktree Fallback
-
-**Only use this if Step 1a does not apply** — you have no native worktree tool available. Create a worktree manually using git.
-
-#### Directory Selection
-
-Follow this priority order. Explicit user preference always beats observed filesystem state.
-
-1. **Check your instructions for a declared worktree directory preference.** If the user has already specified one, use it without asking.
-
-2. **Check for an existing project-local worktree directory:**
-   ```bash
-   ls -d .worktrees 2>/dev/null     # Preferred (hidden)
-   ls -d worktrees 2>/dev/null      # Alternative
-   ```
-   If found, use it. If both exist, `.worktrees` wins.
-
-3. **If there is no other guidance available**, default to `.worktrees/` at the project root.
-
-#### Safety Verification (project-local directories only)
-
-**MUST verify directory is ignored before creating worktree:**
-
-```bash
-git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
-```
-
-**If NOT ignored:** Add to .gitignore, commit the change, then proceed.
-
-**Why critical:** Prevents accidentally committing worktree contents to repository.
-
-#### Create the Worktree
-
-```bash
-# Determine path based on chosen location
-path="$LOCATION/$BRANCH_NAME"
-
-git worktree add "$path" -b "$BRANCH_NAME"
-cd "$path"
-```
-
-**Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), tell the user the sandbox blocked worktree creation and you're working in the current directory instead. Then run setup and baseline tests in place.
-
-## Step 2: Project Setup
-
-Auto-detect and run appropriate setup:
-
-```bash
-# Node.js
-if [ -f package.json ]; then npm install; fi
-
-# Rust
-if [ -f Cargo.toml ]; then cargo build; fi
-
-# Python
-if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-if [ -f pyproject.toml ]; then poetry install; fi
-
-# Go
-if [ -f go.mod ]; then go mod download; fi
-```
-
-## Step 3: Verify Clean Baseline
-
-Run tests to ensure workspace starts clean:
-
-```bash
-# Use project-appropriate command
-npm test / cargo test / pytest / go test ./...
-```
-
-**If tests fail:** Report failures, ask whether to proceed or investigate.
-
-**If tests pass:** Report ready.
-
-### Report
-
-```
-Worktree ready at <full-path>
-Tests passing (<N> tests, 0 failures)
-Ready to implement <feature-name>
-```
-
-## Quick Reference
-
-| Situation | Action |
-|-----------|--------|
-| Already in linked worktree | Skip creation (Step 0) |
-| In a submodule | Treat as normal repo (Step 0 guard) |
-| Native worktree tool available | Use it (Step 1a) |
-| No native tool | Git worktree fallback (Step 1b) |
-| `.worktrees/` exists | Use it (verify ignored) |
+---
+name: using-git-worktrees
+description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
+author: Miya Daniel | Harness Core Team
+version: 0.2.0
+---
+
+# Using Git Worktrees
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Starting feature work that needs isolation from the current workspace, or before executing an implementation plan. |
+| **Expected Output** | An isolated workspace (native worktree tool preferred, `git worktree add` fallback) with dependencies installed and a clean baseline test run confirmed. |
+| **State Mutations** | May create a new worktree directory/branch (`.worktrees/<branch>` by default) and add it to `.gitignore` if not already ignored. |
+| **Enforcement Gate** | **MUST** detect an already-isolated workspace first (`GIT_DIR != GIT_COMMON`, excluding submodules) and skip creating a redundant one. **MUST** verify the worktree directory is gitignored before creating it. **MUST** get human consent before creating a new worktree if no preference was already declared. |
+
+## Overview
+
+Ensure work happens in an isolated workspace. Prefer your platform's native worktree tools. Fall back to manual git worktrees only when no native tool is available.
+
+**Core principle:** Detect existing isolation first. Then use native tools. Then fall back to git. Never fight the harness.
+
+**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
+
+## Step 0: Detect Existing Isolation
+
+**Before creating anything, check if you are already in an isolated workspace.**
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+BRANCH=$(git branch --show-current)
+```
+
+**Submodule guard:** `GIT_DIR != GIT_COMMON` is also true inside git submodules. Before concluding "already in a worktree," verify you are not in a submodule:
+
+```bash
+# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
+git rev-parse --show-superproject-working-tree 2>/dev/null
+```
+
+**If `GIT_DIR != GIT_COMMON` (and not a submodule):** You are already in a linked worktree. Skip to Step 2 (Project Setup). Do NOT create another worktree.
+
+Report with branch state:
+- On a branch: "Already in isolated workspace at `<path>` on branch `<name>`."
+- Detached HEAD: "Already in isolated workspace at `<path>` (detached HEAD, externally managed). Branch creation needed at finish time."
+
+**If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout.
+
+Has the user already indicated their worktree preference in your instructions? If not, ask for consent before creating a worktree:
+
+> "Would you like me to set up an isolated worktree? It protects your current branch from changes."
+
+Honor any existing declared preference without asking. If the user declines consent, work in place and skip to Step 2.
+
+## Step 1: Create Isolated Workspace
+
+**You have two mechanisms. Try them in this order.**
+
+### 1a. Native Worktree Tools (preferred)
+
+The user has asked for an isolated workspace (Step 0 consent). Do you already have a way to create a worktree? It might be a tool with a name like `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag. If you do, use it and skip to Step 2.
+
+Native tools handle directory placement, branch creation, and cleanup automatically. Using `git worktree add` when you have a native tool creates phantom state your harness can't see or manage.
+
+Only proceed to Step 1b if you have no native worktree tool available.
+
+### 1b. Git Worktree Fallback
+
+**Only use this if Step 1a does not apply** — you have no native worktree tool available. Create a worktree manually using git.
+
+#### Directory Selection
+
+Follow this priority order. Explicit user preference always beats observed filesystem state.
+
+1. **Check your instructions for a declared worktree directory preference.** If the user has already specified one, use it without asking.
+
+2. **Check for an existing project-local worktree directory:**
+   ```bash
+   ls -d .worktrees 2>/dev/null     # Preferred (hidden)
+   ls -d worktrees 2>/dev/null      # Alternative
+   ```
+   If found, use it. If both exist, `.worktrees` wins.
+
+3. **If there is no other guidance available**, default to `.worktrees/` at the project root.
+
+#### Safety Verification (project-local directories only)
+
+**MUST verify directory is ignored before creating worktree:**
+
+```bash
+git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
+```
+
+**If NOT ignored:** Add to .gitignore, commit the change, then proceed.
+
+**Why critical:** Prevents accidentally committing worktree contents to repository.
+
+#### Create the Worktree
+
+```bash
+# Determine path based on chosen location
+path="$LOCATION/$BRANCH_NAME"
+
+git worktree add "$path" -b "$BRANCH_NAME"
+cd "$path"
+```
+
+**Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), tell the user the sandbox blocked worktree creation and you're working in the current directory instead. Then run setup and baseline tests in place.
+
+## Step 2: Project Setup
+
+Auto-detect and run appropriate setup:
+
+```bash
+# Node.js
+if [ -f package.json ]; then npm install; fi
+
+# Rust
+if [ -f Cargo.toml ]; then cargo build; fi
+
+# Python
+if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+if [ -f pyproject.toml ]; then poetry install; fi
+
+# Go
+if [ -f go.mod ]; then go mod download; fi
+```
+
+## Step 3: Verify Clean Baseline
+
+Run tests to ensure workspace starts clean:
+
+```bash
+# Use project-appropriate command
+npm test / cargo test / pytest / go test ./...
+```
+
+**If tests fail:** Report failures, ask whether to proceed or investigate.
+
+**If tests pass:** Report ready.
+
+### Report
+
+```
+Worktree ready at <full-path>
+Tests passing (<N> tests, 0 failures)
+Ready to implement <feature-name>
+```
+
+## Quick Reference
+
+| Situation | Action |
+|-----------|--------|
+| Already in linked worktree | Skip creation (Step 0) |
+| In a submodule | Treat as normal repo (Step 0 guard) |
+| Native worktree tool available | Use it (Step 1a) |
+| No native tool | Git worktree fallback (Step 1b) |
+| `.worktrees/` exists | Use it (verify ignored) |