Merge pull request #73 from win4r/sync/upstream-2026-05-28-cherry-picks

Sync upstream/main 2026-05-28 (197 commits)

Author: AliceLJY

.agents/skills/clawteam-dev/SKILL.md

@@ -1,235 +1,133 @@
 ---
 name: clawteam-dev
 description: >
-  This skill should be used when the user asks to "run e2e test", "test clawteam",
-  "end-to-end test", "test agent team", "verify clawteam works", "dev test", or wants
-  to validate the full ClawTeam lifecycle. Runs a complete end-to-end test: cleanup →
-  create team → create tasks with dependencies → spawn agents → wait for completion →
-  verify results → cleanup.
-version: 0.1.0
+  Use this skill when working inside the ClawTeam repository itself: local development,
+  debugging, reviewing, testing, validating multi-agent flows, or checking whether a
+  code change actually works end-to-end. Use the repository bootstrap scripts to
+  standardize the local `clawteam` command and to wire project-local `.agents` and
+  `.claude` skills back to this repository. This skill is repository-development
+  oriented, not a general end-user usage guide.
+version: 0.2.0
 ---
 
-# ClawTeam End-to-End Test
+# ClawTeam Local Development
 
-This skill runs a full lifecycle test of ClawTeam: cleanup residual state, create a team
-with tasks and dependency chains, spawn real Claude agents in tmux, wait for all tasks to
-complete, verify results, and clean up.
+This skill is for developing and validating ClawTeam inside the ClawTeam repository.
+Use it when the task is about changing ClawTeam itself, testing local behavior, or
+verifying multi-agent workflows against the current checkout.
 
-## Prerequisites
-
-- ClawTeam installed (`pip install -e .` from the ClawTeam repo)
-- `tmux` available
-- `claude` CLI available
-- Current directory is the ClawTeam git repo (for worktree isolation)
-
-## Test Procedure
+## Development Bootstrap
 
-Follow these steps **exactly in order**. Run each bash block and verify the expected output
-before proceeding to the next step.
-
-### Step 1: Cleanup ALL Previous State
-
-Remove **all** residual clawteam teams, worktrees, tmux sessions, and branches from any prior runs.
-This ensures a clean slate regardless of what team names were used before or if a previous test crashed.
+Standardize the local development environment with the bootstrap script:
 
 ```bash
-# 1. Kill ALL clawteam tmux sessions
-for sess in $(tmux list-sessions -F '#{session_name}' 2>/dev/null | grep '^clawteam-'); do
-  tmux kill-session -t "$sess" 2>/dev/null
-done
-echo "tmux sessions cleaned"
-
-# 2. Remove ALL clawteam worktrees
-for wt in $(git worktree list --porcelain | grep 'worktree.*/\.clawteam/' | awk '{print $2}'); do
-  git worktree remove --force "$wt" 2>/dev/null
-done
-echo "worktrees cleaned"
-
-# 3. Delete ALL clawteam branches
-for br in $(git branch --list 'clawteam/*' | tr -d ' +'); do
-  git branch -D "$br" 2>/dev/null
-done
-echo "branches cleaned"
-
-# 4. Remove all team/task/workspace data (preserve config.json)
-rm -rf ~/.clawteam/teams/ ~/.clawteam/tasks/ ~/.clawteam/workspaces/ ~/.clawteam/inboxes/ ~/.clawteam/events/ ~/.clawteam/plans/
-echo "data cleaned"
-
-# 5. Verify clean state
-echo "=== Verification ==="
-git worktree list
-git branch --list 'clawteam/*' | grep . || echo "OK: no clawteam branches"
-tmux list-sessions 2>&1 | grep '^clawteam-' || echo "OK: no clawteam tmux sessions"
-ls ~/.clawteam/ 2>/dev/null
+bash scripts/bootstrap_clawteam_dev.sh
 ```
 
-**Expected**: Only the main worktree remains, no clawteam branches, no clawteam tmux sessions,
-`~/.clawteam/` contains only `config.json`.
+This script lives in `scripts/bootstrap_clawteam_dev.sh` inside this skill folder.
 
-### Step 2: Set Leader Identity
-
-```bash
-export CLAWTEAM_AGENT_ID="e2e-leader-001"
-export CLAWTEAM_AGENT_NAME="leader"
-export CLAWTEAM_AGENT_TYPE="leader"
-```
+This script does all of the following:
 
-These env vars MUST be set for all subsequent commands in this test.
+- Creates a fixed uv environment at `~/.clawteam-venv`
+- Installs the current repository into that environment with dev dependencies
+- Writes `~/.local/bin/clawteam` to point at the fixed environment
+- Adds a `clawteam()` shell function block to `~/.bashrc`
 
-### Step 3: Create Team
+After it finishes:
 
 ```bash
-clawteam team spawn-team e2e-test -d "End-to-end test team" -n leader
+source ~/.bashrc
+clawteam --version
 ```
 
-**Expected**: `OK Team 'e2e-test' created`
-
-### Step 4: Create Tasks with Dependencies
+Use this bootstrap whenever you want the same `clawteam` command across different
+Python environments on the machine.
 
-Create 3 tasks: 2 independent tasks and 1 dependent task that is blocked until both complete.
-
-```bash
-T1=$(clawteam --json task create e2e-test "Implement feature A" -o worker1 -d "Add a hello() function to a new file hello.py" | python3 -c "import sys,json;print(json.load(sys.stdin)['id'])")
-T2=$(clawteam --json task create e2e-test "Implement feature B" -o worker2 -d "Add a goodbye() function to a new file goodbye.py" | python3 -c "import sys,json;print(json.load(sys.stdin)['id'])")
-T3=$(clawteam --json task create e2e-test "Write tests" -o worker3 -d "Write pytest tests for hello.py and goodbye.py" --blocked-by "$T1,$T2" | python3 -c "import sys,json;print(json.load(sys.stdin)['id'])")
-echo "Tasks created: T1=$T1 T2=$T2 T3=$T3"
-```
+## Project Skill Wiring
 
-**Expected**: Three task IDs printed. Then verify:
+To wire another local project so its `./.agents` and `./.claude` directories use
+this repository's local ClawTeam skills directly:
 
 ```bash
-clawteam task list e2e-test
+bash scripts/link_local_clawteam_skills.sh /path/to/project
 ```
 
-**Expected**: worker1 and worker2 tasks are `pending`, worker3 task is `blocked`.
+This script lives in `scripts/link_local_clawteam_skills.sh` inside this skill folder.
 
-### Step 5: Spawn Agents
+This creates these symlinks inside the target project:
 
-Spawn 3 agents. Each gets its own git worktree and tmux window.
+- `./.agents/skills/clawteam`
+- `./.claude/skills/clawteam`
 
-```bash
-clawteam spawn --team e2e-test --agent-name worker1 \
-  --task "Create hello.py with a hello() function that returns 'Hello, World!'. When done, mark your task as completed and send a summary to leader."
+Run the same script again any time you want to refresh or recreate those links.
 
-clawteam spawn --team e2e-test --agent-name worker2 \
-  --task "Create goodbye.py with a goodbye() function that returns 'Goodbye, World!'. When done, mark your task as completed and send a summary to leader."
+## Typical Uses
 
-clawteam spawn --team e2e-test --agent-name worker3 \
-  --task "Write pytest tests in test_all.py for hello.py (hello function) and goodbye.py (goodbye function). When done, mark your task as completed and send a summary to leader."
-```
+- Run targeted local validation after code changes
+- Reproduce a spawn / board / task / inbox / harness bug
+- Smoke-test the real CLI in tmux or subprocess mode
+- Review ClawTeam workflows end-to-end from the current repository checkout
 
-**Expected**: Each prints `OK Agent '<name>' spawned in tmux (clawteam-e2e-test:<name>)` with a workspace path.
+## Fast Validation
 
-### Step 6: Verify Team State
+Prefer the smallest validation that proves the change.
 
 ```bash
-clawteam team status e2e-test
-clawteam board show e2e-test
-git worktree list
-tmux list-windows -t clawteam-e2e-test
+ruff check clawteam/ tests/
+pytest tests/<target_file>.py -q
 ```
 
-**Expected**:
-- 4 members (leader + 3 workers)
-- Board shows 2 pending, 1 blocked tasks
-- 3 worktrees under `~/.clawteam/workspaces/e2e-test/`
-- 3 tmux windows
-
-### Step 7: Wait for All Tasks to Complete
-
-Block until all agents finish. Timeout 10 minutes, poll every 5 seconds.
+Use broader runs only when the change crosses modules:
 
 ```bash
-clawteam task wait e2e-test --timeout 600 --poll-interval 5
+pytest tests/test_cli_commands.py -q
+pytest tests/test_spawn_backends.py -q
+pytest tests/test_harness.py tests/test_event_bus.py -q
 ```
 
-**Expected**:
-- Progress updates as tasks complete (e.g., `1/3 tasks completed`)
-- Messages from workers displayed as they arrive
-- Final line: `All 3 tasks completed!`
-- Exit code 0
+## Prerequisites
 
-### Step 8: Verify Results
+- `clawteam` command available
+- `tmux` available
+- A supported CLI agent such as `claude` or `codex` if you are spawning real workers
+- Current directory is the ClawTeam git repo when testing worktree isolation or local source changes
 
-```bash
-# All tasks should be completed
-clawteam task list e2e-test
+## Local Smoke Test
 
-# Board should show 3 completed, 0 pending/blocked
-clawteam board show e2e-test
+Use this when you need a real multi-agent workflow check instead of unit tests.
 
-# Read any remaining inbox messages
-clawteam inbox receive e2e-test
+```bash
+clawteam team spawn-team dev-smoke -d "Local ClawTeam smoke test" -n leader
+clawteam task create dev-smoke "Smoke test worker" -o worker1 -p high
+clawteam spawn --team dev-smoke --agent-name worker1 --task "Report your status to leader and mark the task completed when done."
+clawteam board show dev-smoke
+clawteam task wait dev-smoke --timeout 300 --poll-interval 5
 ```
 
-**Expected**:
-- All 3 tasks show status `completed`
-- Board shows 3 in COMPLETED column
-- Messages from workers summarizing their work
-
-### Step 9: Cleanup
-
-Reuse the same full cleanup from Step 1 to remove everything created during this test.
+If you are validating harness behavior specifically:
 
 ```bash
-# Kill ALL clawteam tmux sessions
-for sess in $(tmux list-sessions -F '#{session_name}' 2>/dev/null | grep '^clawteam-'); do
-  tmux kill-session -t "$sess" 2>/dev/null
-done
-
-# Remove ALL clawteam worktrees
-for wt in $(git worktree list --porcelain | grep 'worktree.*/\.clawteam/' | awk '{print $2}'); do
-  git worktree remove --force "$wt" 2>/dev/null
-done
-
-# Delete ALL clawteam branches
-for br in $(git branch --list 'clawteam/*' | tr -d ' +'); do
-  git branch -D "$br" 2>/dev/null
-done
-
-# Remove all team/task/workspace data (preserve config.json)
-rm -rf ~/.clawteam/teams/ ~/.clawteam/tasks/ ~/.clawteam/workspaces/ ~/.clawteam/inboxes/ ~/.clawteam/events/ ~/.clawteam/plans/
-
-echo "E2E test cleanup complete"
+clawteam harness conduct dev-harness \
+  --goal "Create a small implementation plan and execute it with one worker" \
+  --cli codex \
+  --agents 1
 ```
 
-**Expected**: `E2E test cleanup complete`
+## Cleanup
 
-### Step 10: Final Verification
+Use the real ClawTeam commands instead of ad-hoc directory assumptions whenever possible:
 
 ```bash
-git worktree list | grep -v '^\/' | head -1  # should show only main
-git branch --list 'clawteam/*' | grep . || echo "OK: no clawteam branches"
-tmux list-sessions 2>&1 | grep '^clawteam-' || echo "OK: no clawteam tmux sessions"
-ls ~/.clawteam/teams/ 2>&1 | grep -q "No such file" && echo "OK: no team data"
-ls ~/.clawteam/tasks/ 2>&1 | grep -q "No such file" && echo "OK: no task data"
-ls ~/.clawteam/workspaces/ 2>&1 | grep -q "No such file" && echo "OK: no workspace data"
+clawteam team cleanup dev-smoke
+clawteam team cleanup dev-harness
 ```
 
-**Expected**: All lines start with `OK:`.
-
-## Test Variants
-
-### With P2P Transport
-
-Add `--transport p2p` and `export CLAWTEAM_TRANSPORT=p2p` before Step 3 to test ZeroMQ direct messaging with file fallback. The rest of the steps remain the same.
-
-### With subprocess Backend
-
-Replace `clawteam spawn` with `clawteam spawn subprocess claude` to test the subprocess backend instead of tmux. Note: `board attach` and tmux verification steps won't apply.
+If a crashed tmux session or worktree is left behind, clean it up explicitly after inspecting it.
 
-## What This Test Validates
+## Development Rules
 
-| Component | Validated |
-|-----------|-----------|
-| `team spawn-team` | Team creation with leader |
-| `task create --blocked-by` | Task dependency chains |
-| `spawn` (tmux backend) | Agent process launch with worktree isolation |
-| Identity propagation | Env vars passed to sub-agents |
-| Agent coordination | Workers update task status and send messages to leader |
-| Auto-unblock | Blocked task unblocked when dependencies complete |
-| `task wait` | Progress tracking, inbox drain, completion detection |
-| `inbox send/receive` | Point-to-point messaging between agents |
-| `board show` | Kanban board rendering |
-| `workspace` (auto) | Git worktree creation and isolation |
-| Cleanup | Worktree removal, branch deletion, data cleanup |
+- Prefer `clawteam` commands over editing state files directly.
+- Prefer targeted tests over broad end-to-end runs unless the change crosses spawn/runtime/workflow boundaries.
+- Use `board`, `task wait`, and `team status` to observe behavior before assuming a bug is in the spawn layer.
+- When testing agent coordination, keep the team small first: one leader and one or two workers.
+- Only escalate to harness or full swarm tests when the lower-level task/spawn/inbox path already works.

.agents/skills/clawteam-dev/scripts/bootstrap_clawteam_dev.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(cd -- "${SCRIPT_DIR}/.." && pwd)"
+REPO_ROOT="$(cd -- "${SKILL_DIR}/../../.." && pwd)"
+VENV_DIR="${HOME}/.clawteam-venv"
+LAUNCHER="${HOME}/.local/bin/clawteam"
+PYTHON_BIN="${VENV_DIR}/bin/python"
+
+mkdir -p "${HOME}/.local/bin"
+
+if ! command -v uv >/dev/null 2>&1; then
+  echo "Error: uv is not installed or not on PATH." >&2
+  exit 1
+fi
+
+uv venv "${VENV_DIR}"
+(
+  cd "${REPO_ROOT}"
+  uv pip install --python "${PYTHON_BIN}" -e ".[dev]"
+)
+
+cat > "${LAUNCHER}" <<EOF
+#!/usr/bin/env bash
+exec ${PYTHON_BIN} -m clawteam.cli.commands "\$@"
+EOF
+chmod +x "${LAUNCHER}"
+
+python - <<'PY'
+from pathlib import Path
+
+bashrc = Path.home() / ".bashrc"
+launcher = Path.home() / ".clawteam-venv" / "bin" / "python"
+block = f"""# >>> clawteam launcher >>>
+clawteam() {{
+  {launcher} -m clawteam.cli.commands "$@"
+}}
+# <<< clawteam launcher <<<
+"""
+
+text = bashrc.read_text() if bashrc.exists() else ""
+start = "# >>> clawteam launcher >>>"
+end = "# <<< clawteam launcher <<<"
+if start in text and end in text:
+    prefix = text.split(start, 1)[0]
+    suffix = text.split(end, 1)[1]
+    updated = prefix + block + suffix
+else:
+    updated = text.rstrip() + ("\n\n" if text.strip() else "") + block
+bashrc.write_text(updated)
+PY
+
+echo "ClawTeam development environment is ready."
+echo "Launcher: ${LAUNCHER}"
+echo "Venv: ${VENV_DIR}"
+echo "Next: source ~/.bashrc && clawteam --version"