pi-crew 0.2.3 → 0.2.5

package/skills/read-only-explorer/SKILL.md

@@ -1,26 +1,250 @@
----
-name: read-only-explorer
-description: Read-only exploration and audit workflow. Use for explorer, analyst, reviewer, and source-audit roles that must inspect code without modifying files.
----
-
-# read-only-explorer
-
-Use this skill for explorer, analyst, reviewer, and source-audit roles.
-
-## Contract
-
-- Do not edit files.
-- Do not write generated artifacts outside the run artifact directory.
-- Prefer `read`, `rg`, `find`, `git status`, and package metadata inspection.
-- Record exact files inspected.
-- Distinguish direct evidence from inference.
-- If implementation is needed, recommend it instead of modifying code.
-
-## Output shape
-
-Return:
-
-1. files inspected;
-2. findings with path references;
-3. risks/unknowns;
-4. recommended next tests or implementation tasks.
+---
+name: read-only-explorer
+description: Read-only exploration and audit workflow. Use for explorer, analyst, reviewer, and source-audit roles that must inspect code without modifying files.
+---
+
+# read-only-explorer
+
+Use this skill for explorer, analyst, reviewer, and source-audit roles. These roles must inspect code without modifying it.
+
+## Core Contract
+
+1. **Do not edit files** — no write, no edit, no delete
+2. **Do not write generated artifacts** outside the run artifact directory
+3. **Prefer read-only commands**: `read`, `rg`, `find`, `ls`, `git status`
+4. **Record exact files inspected** — include path and relevant line numbers
+5. **Distinguish direct evidence from inference** — don't guess
+6. **If implementation is needed, recommend** — don't modify code
+
+## Tool Selection Guide
+
+Choosing the right tool for the task reduces noise and speeds up discovery.
+
+### `rg` (ripgrep) — Code pattern search
+
+**Best for:** Finding function definitions, imports, patterns, usages
+```
+# Find all uses of a function
+rg "functionName" --type ts
+
+# Find with context (2 lines before/after)
+rg "pattern" -B2 -A2
+
+# Case-insensitive
+rg -i "error handling"
+
+# Only match whole word
+rg -w "agent"
+
+# JSON output for machine parsing
+rg "pattern" --json | head -20
+
+# Respect .gitignore (skip node_modules)
+rg "pattern" --type-add 'exclude:*.json' --type ts
+```
+
+### `find` — File and directory search
+
+**Best for:** Finding files by name, type, or path pattern
+```
+# Find all TypeScript files
+find . -name "*.ts" -not -path "*/node_modules/*" | head -20
+
+# Find recently modified files
+find . -name "*.ts" -mtime -7 | head -20
+
+# Find files larger than 100KB
+find . -size +100k -name "*.ts"
+
+# Find by path pattern
+find . -path "*/runtime/*" -name "*.ts" | head -10
+```
+
+### `read` — File content inspection
+
+**Best for:** Reading specific files or file sections
+```
+# Read full file
+read file.ts
+
+# Read with line numbers
+read -n file.ts  # (use read tool with offset/limit)
+
+# Read first N lines
+read --limit 50 file.ts
+
+# Read specific section
+read --offset 100 --limit 30 file.ts
+```
+
+### `ls` — Directory structure
+
+**Best for:** Listing directories, understanding layout
+```
+ls src/runtime/
+ls -la .crew/state/runs/ | head -20
+ls skills/ | head -20
+```
+
+### `git` — Version control inspection
+
+**Best for:** Understanding history, changes, and authorship
+```
+git status --short
+git diff HEAD~3 --stat
+git log --oneline -10
+git show <commit-hash> --stat
+git blame src/file.ts | head -20
+git branch -a
+```
+
+## Scope Containment
+
+Limit searches to relevant areas to avoid noise.
+
+### By directory
+```
+# Only search runtime directory
+rg "pattern" src/runtime/ --type ts
+
+# Exclude test and node_modules
+rg "pattern" --type ts --exclude "test/**" --exclude "node_modules/**"
+```
+
+### By file type
+```
+# Only TypeScript files
+rg "pattern" --type ts
+
+# Only test files
+rg "pattern" --type-add 'test:*.test.ts' --type test
+
+# Exclude generated files
+rg "pattern" --glob "!**/*.generated.ts"
+```
+
+### By depth
+```
+# Only top-level config files
+find . -maxdepth 2 -name "*.json" | head -20
+```
+
+## Findings Format
+
+Every finding should be documented with:
+
+```text
+path/to/file.ts:123
+Evidence: <what you read>
+Severity: critical|high|medium|low
+Finding: <what the problem is>
+Impact: <why it matters>
+Recommendation: <what to do next>
+```
+
+**Example:**
+```
+src/runtime/agent-manager.ts:87
+Evidence: throw new Error("Agent not found") with no error code
+Severity: medium
+Finding: Error thrown without structured error code makes debugging harder
+Impact: Hard to distinguish "not found" from "access denied" or other failures
+Recommendation: Use typed CrewError with error code enum instead
+```
+
+## Risk Assessment Criteria
+
+| Severity | Criteria |
+|---|---|
+| **critical** | Data loss, secret leak, arbitrary command/path escape, broken install |
+| **high** | Broken core workflow, ownership bypass, persistent incorrect state |
+| **medium** | Important regression, flaky test, confusing behavior |
+| **low** | Polish, maintainability, missing docs |
+
+## Next Steps Format
+
+When recommending implementation, structure it as:
+
+```
+1. Files to create:
+   - src/new-feature.ts (new module)
+
+2. Files to modify:
+   - src/existing.ts (add function X, change line Y)
+
+3. Tests to add:
+   - test/unit/new-feature.test.ts
+
+4. Verification:
+   - npx tsc --noEmit
+   - npm test
+```
+
+## Reading Large Codebases Efficiently
+
+### Chunk strategy
+1. Start with entry point (main file, index, README)
+2. Find key function calls → follow the chain
+3. Read function signatures before bodies
+4. Skip test files unless investigating specific test behavior
+
+### Trace data flow
+```
+user input → config resolution → function call → state write → UI update
+```
+
+For each step, identify:
+- What data enters
+- What transforms it
+- What exits
+- Where it could fail
+
+### Distinguish evidence from inference
+
+| Type | Description | Example |
+|---|---|---|
+| **Direct evidence** | Exact content read from file | `"type": "worker.spawned"` found at line 42 |
+| **Inference** | Interpretation based on evidence | "Worker likely crashed because exit code was 1" |
+| **Unknown** | Not confirmed | "This might be a race condition" |
+
+Always label uncertainty clearly. Use "may", "might", "could" for inference; "is", "shows", "contains" for evidence.
+
+## Anti-patterns
+
+- **Editing during exploration**: If you need to add logging or print statements, use a separate test script instead of modifying source files.
+- **Broad searches without context**: `rg "error"` returns thousands of results. Narrow by file, directory, or surrounding context.
+- **Trusting comments over code**: Comments can be outdated. Read the actual code.
+- **Skipping test files**: Tests often reveal the intended behavior and edge cases. Read them.
+- **Not recording files inspected**: Without exact paths, findings can't be verified.
+- **Inference as fact**: If unsure, mark it as inference.
+
+---
+
+## Source patterns
+
+- `src/runtime/task-runner.ts` — task execution pipeline
+- `src/runtime/child-pi.ts` — worker spawning
+- `src/runtime/live-agent-manager.ts` — live agent lifecycle
+- `src/state/event-log.ts` — event logging system
+- `src/extension/team-tool/` — API and tool handling
+- `src/ui/` — widget and TUI rendering
+
+---
+
+## Verification
+
+```bash
+cd pi-crew
+
+# Verify no files were modified
+git status --short
+
+# Count inspected files
+rg "pattern" --type ts | wc -l
+
+# Check for direct evidence in event log
+cat .crew/state/runs/<runId>/events.jsonl | grep "worker.spawned"
+
+# TypeScript
+npx tsc --noEmit
+```

package/skills/safe-bash/SKILL.md

@@ -1,21 +1,307 @@
----
-name: safe-bash
-description: Safe shell-command workflow. Use whenever a task may execute shell commands, especially to prefer read-only commands and avoid destructive actions without confirmation.
----
-
-# safe-bash
-
-Use this skill whenever a task may execute shell commands.
-
-## Rules
-
-- Prefer read-only commands first: `pwd`, `ls`, `find`, `rg`, `git status`, package-manager dry runs.
-- Before mutating commands, explain the target path and expected effect.
-- Never run destructive cleanup (`rm -rf`, `git clean`, force delete, prune, reset hard) without explicit confirmation.
-- Avoid shell-specific assumptions when a cross-platform Node/Pi API exists.
-- On Windows, prefer argv-based process execution and avoid `cmd /c start` or `/bin/bash` unless explicitly required.
-- Capture verification output and summarize exit status.
-
-## Reporting
-
-Mention commands run and whether they were read-only or mutating.
+---
+name: safe-bash
+description: Safe shell-command workflow. Use whenever a task may execute shell commands, especially to prefer read-only commands and avoid destructive actions without confirmation.
+---
+
+# safe-bash
+
+Use this skill whenever a task may execute shell commands. This skill covers cross-platform shell safety, destructive action confirmation, and Windows-specific patterns.
+
+## Classification
+
+Every shell command is either **read-only** or **mutating**. Always report which it is.
+
+### Read-only commands (safe)
+```bash
+pwd              # print working directory
+ls -la           # list files
+find . -name "*.ts" | head -20        # search without writing
+rg "pattern" --type ts | head -20     # ripgrep without write
+git status       # inspect state
+git log --oneline -5  # recent commits
+git diff --staged    # staged changes
+npm view <pkg>   # query registry (no install)
+npx tsc --noEmit  # typecheck (no write)
+node -e "console.log(process.version)"  # inspect version
+```
+
+### Mutating commands (require confirmation)
+```bash
+npm install      # changes node_modules
+git commit       # creates new commit
+git push         # publishes to remote
+rm -rf <path>    # DESTRUCTIVE
+git reset --hard # rewrites history
+npm publish      # publishes to registry
+```
+
+## Cross-Platform Considerations
+
+### Windows vs Unix paths
+
+```typescript
+// ❌ Never hardcode paths with forward slashes on Windows
+const path = "D:/project/src/file.ts";
+
+// ✅ Use path.join() or Node's path module
+import * as path from "path";
+const filePath = path.join(cwd, "src", "file.ts");
+
+// ✅ Or use forward slashes that work on both
+const filePath = "src/file.ts"; // relative paths work on both
+```
+
+### argv vs cmd /c
+
+```typescript
+// ✅ Preferred on Windows: argv-based execution (no shell)
+import { spawn } from "child_process";
+spawn("node", ["--version"], { stdio: "pipe" });
+
+// ✅ If shell needed: use cmd /c explicitly
+spawn("cmd", ["/c", "dir /b"], { stdio: "pipe" });
+
+// ❌ Don't use cmd /c with complex commands as single string
+spawn("cmd", ["/c", "node --version && npm test"], { stdio: "pipe" });
+```
+
+### Package manager detection
+
+```typescript
+// Detect npm vs pnpm vs yarn
+function detectPackageManager(cwd: string): "npm" | "pnpm" | "yarn" | "unknown" {
+  if (fs.existsSync(path.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs.existsSync(path.join(cwd, "yarn.lock"))) return "yarn";
+  return "npm";
+}
+```
+
+## Heredoc and Quoting Gotchas
+
+### Quoting variables in commands
+
+```bash
+# ❌ Unsafe: variable expansion without quoting
+node -e "console.log('$PATH')"  # breaks on spaces
+
+# ✅ Safe: escape single quotes in the string
+node -e "console.log(process.env.PATH)"  # use env, not shell var
+
+# ✅ For file paths with spaces
+ls "D:/my project/src"
+```
+
+### Heredoc in scripts
+
+```bash
+# ❌ Heredoc inside double quotes expands variables
+cat << EOF
+HOME is $HOME
+EOF
+
+# ✅ Use single quotes to prevent expansion
+cat << 'EOF'
+HOME is $HOME
+EOF
+```
+
+## Timeout and Background Execution
+
+### Timeout long-running commands
+
+```bash
+# Linux/macOS: use timeout command
+timeout 30 npm test  # kill after 30 seconds
+
+# Node.js: use AbortSignal
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 30_000);
+spawn("npm", ["test"], { signal: controller.signal });
+
+# Windows: use /wait flag
+start /wait cmd /c "npm test"
+```
+
+### Background vs foreground
+
+```bash
+# Background: run and forget (no output capture)
+npm test &
+
+# Foreground with timeout
+timeout 60 npm test || echo "Timed out or failed"
+```
+
+## Signal Handling
+
+### SIGTERM vs SIGKILL
+
+| Signal | Effect | Use case |
+|---|---|---|
+| SIGTERM (15) | Graceful termination request | Normal shutdown |
+| SIGKILL (9) | Immediate forced termination | Unresponsive process |
+| SIGINT (2) | Interrupt (Ctrl+C) | User cancel |
+
+```bash
+# Graceful: request termination
+kill -15 <pid>   # or: kill <pid>
+
+# Force: immediate termination
+kill -9 <pid>    # or: kill -SIGKILL <pid>
+
+# On Windows (cmd):
+taskkill /pid <pid> /t /f  # /t=tree, /f=force
+```
+
+### Child process inheritance
+
+When spawning subprocesses, child processes inherit the parent's signal handlers. Use `signal: controller.signal` in Node.js to give the child its own abort signal.
+
+## Sudo and Interactive Prompts
+
+### Detecting interactive prompts
+
+```bash
+# Check if stdin is a terminal
+[ -t 0 ] && echo "Interactive" || echo "Non-interactive"
+```
+
+### Avoiding sudo prompts in scripts
+
+```bash
+# ❌ This will hang waiting for password
+npm install -g typescript
+
+# ✅ Use expect or non-interactive mode
+sudo npm install -g typescript 2>/dev/null  # ignores prompt
+NPM_CONFIG_INTERACTIVE=false npm install -g typescript
+```
+
+## Error Trapping
+
+### set -e and set -o pipefail
+
+```bash
+#!/bin/bash
+set -e  # Exit immediately on error
+set -o pipefail  # Pipeline fails if any command fails
+
+# Good for CI/CD scripts
+npm test
+```
+
+### Capture and handle errors
+
+```bash
+# Capture exit code
+npm test || {
+  echo "Tests failed with exit code $?"
+  exit 1
+}
+
+# Check for command existence
+command -v npm >/dev/null 2>&1 || { echo "npm not found"; exit 1; }
+```
+
+## ANSI Color Code Stripping
+
+For log parsing, strip ANSI escape codes:
+
+```typescript
+// Strip ANSI color codes from output
+function stripAnsi(text: string): string {
+  return text.replace(/\x1B\[[0-9;]*[mK]/g, "");
+}
+
+// Usage
+const output = stripAnsi(child.stdout);
+const hasFailure = output.includes("FAIL");
+```
+
+Or via shell:
+```bash
+# Strip ANSI codes using sed
+npm test 2>&1 | sed 's/\x1B\[[0-9;]*[mK]//g'
+```
+
+## Node.js vs Binary Detection
+
+```typescript
+// Detect node executable
+import { execSync } from "child_process";
+function findNode(): string {
+  // Try common paths
+  for (const candidate of [
+    process.execPath,
+    "node",
+    "C:\\Program Files\\nodejs\\node.exe",
+    "/usr/local/bin/node",
+  ]) {
+    try {
+      execSync(`"${candidate}" --version`, { stdio: "ignore" });
+      return candidate;
+    } catch { /* continue */ }
+  }
+  return "node"; // fallback
+}
+```
+
+## Destructive Action Confirmation
+
+Never execute destructive commands without explicit confirmation:
+
+| Command | Risk | Confirmation needed |
+|---|---|---|
+| `rm -rf <path>` | Permanent data loss | "Type the path to confirm" |
+| `git reset --hard` | Undo all changes | "Confirm with: YES" |
+| `git clean -fd` | Remove untracked files | "Confirm with: YES" |
+| `npm publish` | Public package | "Confirm version X.Y.Z" |
+
+**Confirmation pattern:**
+```bash
+# Require user to type the exact path
+read -p "Type the directory path to confirm deletion: " CONFIRM
+if [ "$CONFIRM" = "$TARGET_PATH" ]; then
+  rm -rf "$TARGET_PATH"
+else
+  echo "Aborted: paths do not match"
+fi
+```
+
+## Anti-patterns
+
+- **`rm -rf` without path validation**: Always double-check the path before rm -rf
+- **Blocking on subprocess**: Always use async spawn with timeout
+- **Ignoring exit codes**: Check `$?` or capture `exitCode` from Node.js spawn
+- **Leaking secrets in args**: Use environment variables instead of command-line args
+- **Not handling Windows spaces**: Test on Windows before assuming paths work
+- **Background process zombie**: Always handle process exit or store the pid for cleanup
+
+---
+
+## Source patterns
+
+- `src/utils/resolve-shell.ts` — cross-platform shell detection
+- `src/runtime/child-pi.ts` — spawn, killProcessPid, signal handling
+- `src/worktree/worktree-manager.ts` — git commands via execFileSync
+- `src/config/defaults.ts` — platform detection
+
+---
+
+## Verification
+
+```bash
+cd pi-crew
+
+# Check exit code handling
+node -e "const {spawnSync}=require('child_process'); console.log(spawnSync('false').status)"
+
+# Test ANSI stripping
+node -e "console.log('\x1B[32mgreen\x1B[0m'.replace(/\x1B\[[0-9;]*[mK]/g,''))"
+
+# Verify cross-platform path
+node -e "const p=require('path'); console.log(p.join('D:\\\\','project','src'))"
+
+# TypeScript
+npx tsc --noEmit
+```

package/skills/verification-before-done/SKILL.md

@@ -23,7 +23,7 @@ Before any completion claim:
 
 | Claim | Requires | Not sufficient |
 |---|---|---|
-| Tests pass | Fresh test output with zero failures | Prior run, “should pass” |
+| Tests pass | Fresh test output with zero failures | Prior run, "should pass" |
 | Typecheck passes | Typecheck command exit 0 | Lint or targeted tests only |
 | Bug fixed | Original symptom/regression test passes | Code changed |
 | Requirements met | Checklist against request/plan | Generic test success |
@@ -52,6 +52,15 @@ Include:
 - skipped checks and why;
 - risks and rollback notes.
 
+## Required Final Evidence
+
+Before finalizing any work, report:
+
+- **changed files**: list of files modified (or `none` for read-only work)
+- **tests/checks run**: command and pass/fail result for each
+- **artifacts**: run IDs, log paths, or state files inspected
+- **risks and rollback notes**: any known risks, how to undo the changes
+
 ## Red Flags
 
-Stop before saying done if you are using words like “should”, “probably”, “looks”, “seems”, “I think”, or if you are trusting an agent report without checking evidence.
+Stop before saying done if you are using words like "should", "probably", "looks", "seems", "I think", or if you are trusting an agent report without checking evidence.