devflow-kit 0.8.1 → 1.0.0

package/plugins/devflow-specify/skills/agent-teams/references/cleanup.md

@@ -0,0 +1,104 @@
+# Session Management and Cleanup
+
+## Team Lifecycle
+
+```
+1. Lead creates team
+2. Lead spawns teammates
+3. Teammates work independently
+4. Debate rounds (teammates message directly)
+5. Lead collects consensus
+6. Lead shuts down teammates
+7. Lead calls cleanup
+8. Lead verifies no orphans
+```
+
+---
+
+## Cleanup Rules
+
+### Lead Responsibilities
+
+1. **Always call cleanup** - Even if team work was interrupted or errored
+2. **Shut down teammates first** - Before calling cleanup
+3. **Verify completion** - Check that no orphaned sessions remain
+
+### Error Handling
+
+If a teammate errors or hangs:
+1. Send shutdown message to the teammate
+2. Wait briefly for graceful shutdown
+3. Proceed with cleanup for remaining team
+4. Report the failed teammate in final output
+
+### Orphan Detection
+
+After cleanup, verify:
+- No tmux sessions from the team remain (split-pane mode)
+- No background processes from teammates
+- Team config at `~/.claude/teams/{team-name}/` is cleaned up
+
+---
+
+## Known Limitations
+
+| Limitation | Mitigation |
+|-----------|------------|
+| No session resumption for teammates | Start fresh; don't rely on teammate state persistence |
+| One team per session | Queue team work sequentially if needed |
+| Task status may lag | Use direct messages for time-sensitive coordination |
+| No nested teams | Teammates cannot spawn sub-teams; keep hierarchy flat |
+| Split-pane requires tmux/iTerm2 | Fall back to in-process mode if unavailable |
+
+---
+
+## Cost Management
+
+### Token Optimization
+
+| Strategy | Savings |
+|----------|---------|
+| Use haiku for validation teammates | ~70% per validation agent |
+| Limit debate to 2 rounds | Prevents runaway token usage |
+| Size teams to task (don't over-spawn) | Fewer agents = fewer tokens |
+| Shut down teammates promptly | No idle token consumption |
+
+### When NOT to Use Teams
+
+- Simple, single-focus tasks (use regular subagent)
+- Tasks requiring sequential dependency (no parallelism benefit)
+- Cost-sensitive operations where subagent is sufficient
+- Tasks where debate adds no value (e.g., formatting, simple fixes)
+
+---
+
+## Sequential Team Transition Protocol
+
+Commands that create multiple teams (e.g., `/implement`, `/specify`) MUST follow this 4-step protocol between teams. Skipping steps causes silent failures due to the one-team-per-session constraint.
+
+```
+Step 1: SHUTDOWN — Send shutdown_request to each teammate by name
+  SendMessage(type: "shutdown_request", recipient: "{name}", content: "Phase complete")
+  Wait for each shutdown_response (approve: true)
+
+Step 2: DELETE — Remove team resources
+  TeamDelete
+
+Step 3: VERIFY — Confirm cleanup succeeded
+  If TeamDelete returned success → proceed
+  If TeamDelete failed → retry once after 5s
+  If retry fails → HALT and report to user:
+    "Team cleanup failed for {team-name}. Cannot create next team."
+
+Step 4: CREATE — Only now create the next team
+  TeamCreate(team_name: "{next-team-name}")
+```
+
+### Failure Modes
+
+| Failure | Action |
+|---------|--------|
+| Teammate ignores shutdown_request | Wait 30s, then proceed to TeamDelete (force cleanup) |
+| TeamDelete fails | Retry once after 5s delay |
+| TeamDelete retry fails | HALT execution, report to user |
+| TeamCreate fails after successful delete | Retry once; if fails, fall back to parallel Task() subagents |

package/plugins/devflow-specify/skills/agent-teams/references/communication.md

@@ -0,0 +1,122 @@
+# Communication Protocols
+
+## Message Types
+
+### Direct Message (one-to-one)
+
+Use when challenging a specific teammate's finding:
+
+```
+To [Security Reviewer]:
+"Your finding about SQL injection at api/users.ts:42 - I disagree.
+The parameterized query at line 45 handles this. Check the query builder
+pattern used throughout this codebase."
+```
+
+### Broadcast (one-to-all)
+
+Use when sharing findings that affect all teammates:
+
+```
+Broadcast:
+"I found that the auth middleware is bypassed for /api/internal/* routes.
+This affects security, architecture, and testing perspectives."
+```
+
+---
+
+## Debate Protocol
+
+### Round Structure
+
+```
+Round 1: Initial findings (each teammate shares top findings)
+Round 2: Challenge round (teammates dispute or validate)
+Round 3: Resolution (update, withdraw, or escalate)
+```
+
+**Cap: 2 challenge exchanges per topic.** If unresolved, escalate to lead.
+
+### Challenge Format
+
+When challenging another teammate:
+
+```
+CHALLENGE to [Teammate]:
+- Finding: [what they claimed]
+- Evidence against: [your counter-evidence with file:line references]
+- Suggested resolution: [what you think is correct]
+```
+
+### Concession Format
+
+When accepting a challenge:
+
+```
+UPDATED based on [Teammate]'s challenge:
+- Original: [what I originally claimed]
+- Revised: [updated finding incorporating their evidence]
+```
+
+### Escalation Format
+
+When debate is unresolved after 2 exchanges:
+
+```
+ESCALATION to Lead:
+- Topic: [what we disagree about]
+- Position A: [first perspective with evidence]
+- Position B: [second perspective with evidence]
+- Recommendation: [which has stronger evidence, or "genuinely split"]
+```
+
+---
+
+## Lead Coordination Messages
+
+### Initiating Debate
+
+```
+Lead broadcast:
+"All teammates: Share your top 3-5 findings. After sharing, challenge
+any finding you disagree with. Provide evidence (file:line references).
+You have 2 exchange rounds to resolve disagreements."
+```
+
+### Ending Debate
+
+```
+Lead broadcast:
+"Debate round complete. Submit final findings with confidence levels:
+- HIGH: Unanimous or unchallenged with evidence
+- MEDIUM: Majority agreed, dissent noted
+- LOW: Split opinion, both perspectives included"
+```
+
+### Requesting Clarification
+
+```
+Lead to [Teammate]:
+"Your finding about X contradicts [Other Teammate]'s finding about Y.
+Can you address their evidence at [file:line]?"
+```
+
+---
+
+## Output Aggregation
+
+### Consensus Report Structure
+
+```markdown
+## Confirmed Findings (HIGH confidence)
+[Findings all teammates agreed on or that survived challenge]
+
+## Majority Findings (MEDIUM confidence)
+[Findings most agreed on, with dissenting view noted]
+
+## Split Findings (LOW confidence)
+[Genuinely contested findings with both perspectives and evidence]
+
+## Withdrawn Findings
+[Findings that were disproved during debate]
+```

package/plugins/devflow-specify/skills/agent-teams/references/team-patterns.md

@@ -0,0 +1,217 @@
+# Team Patterns by Workflow
+
+## Task-Based Coordination
+
+All team workflows should use the shared task list for structured progress tracking:
+
+```
+1. Lead creates team
+2. Lead creates tasks (TaskCreate) for each teammate's work unit
+3. Lead spawns teammates, assigning tasks via TaskUpdate(owner)
+4. Teammates work, mark tasks completed via TaskUpdate(status: completed)
+5. Lead checks TaskList before proceeding to next phase
+6. Lead shuts down teammates, calls TeamDelete
+```
+
+**Example task creation for a review team:**
+
+```
+TaskCreate: "Security review of auth module" → assigned to Security Reviewer
+TaskCreate: "Architecture review of auth module" → assigned to Architecture Reviewer
+TaskCreate: "Performance review of auth module" → assigned to Performance Reviewer
+```
+
+---
+
+## Review Team
+
+### Standard Review (4 perspectives)
+
+```
+Lead spawns:
+├── Security reviewer    → vulnerabilities, injection, auth, crypto
+├── Architecture reviewer → SOLID, coupling, layering, modularity
+├── Performance reviewer  → queries, algorithms, caching, I/O
+└── Quality reviewer      → complexity, tests, consistency, naming
+```
+
+### Extended Review (add conditionally)
+
+```
+Additional teammates based on changed files:
+├── TypeScript reviewer  → type safety, generics (if .ts/.tsx changed)
+├── React reviewer       → hooks, state, rendering (if .tsx/.jsx changed)
+├── Database reviewer    → schema, queries, migrations (if DB files changed)
+└── Dependencies reviewer → CVEs, versions, licenses (if package files changed)
+```
+
+### Review Debate Flow
+
+```
+1. Each reviewer analyzes independently
+2. Lead broadcasts: "Share top 3 findings and challenge others"
+3. Security challenges architecture: "This coupling creates attack surface"
+4. Architecture challenges performance: "Your caching suggestion breaks separation"
+5. Quality validates: "Tests don't cover the security concern raised"
+6. Lead collects consensus after max 2 exchange rounds
+```
+
+---
+
+## Implementation Team
+
+### Exploration Team (4 perspectives)
+
+```
+Lead spawns:
+├── Architecture explorer  → existing patterns, module structure
+├── Integration explorer   → entry points, services, config
+├── Reusable code explorer → utilities, helpers, shared logic
+└── Edge case explorer     → error conditions, boundaries, race conditions
+```
+
+### Planning Team (3 perspectives)
+
+```
+Lead spawns:
+├── Implementation planner → step-by-step coding approach
+├── Testing planner        → test strategy and coverage plan
+└── Risk planner           → potential issues, rollback strategy
+```
+
+### Implementation Debate
+
+```
+1. Explorers share findings
+2. Architecture challenges edge cases: "This boundary isn't handled"
+3. Integration challenges reusable code: "That helper doesn't cover our case"
+4. Lead synthesizes consensus exploration
+
+5. Planners propose approaches
+6. Testing challenges implementation: "This approach is untestable"
+7. Risk challenges both: "Rollback is impossible with this migration"
+8. Lead synthesizes consensus plan
+```
+
+---
+
+## Specification Team
+
+### Requirements Exploration Team (4 perspectives)
+
+```
+Lead spawns:
+├── User Perspective Explorer  → target users, goals, pain points, user journeys
+├── Similar Features Explorer  → comparable features, scope patterns, precedents
+├── Constraints Explorer       → dependencies, business rules, security, performance
+└── Failure Mode Explorer      → error states, edge cases, validation needs
+```
+
+### Requirements Debate Flow
+
+```
+1. Each explorer shares findings from their perspective
+2. Constraints challenges user perspective: "This requirement conflicts with X constraint"
+3. Failure modes challenges similar features: "That pattern failed in Y scenario"
+4. Similar features validates user perspective: "This UX pattern works well in Z"
+5. Lead collects consensus after max 2 exchange rounds
+```
+
+### Scope Planning Team (3 perspectives)
+
+```
+Lead spawns:
+├── User Stories Planner       → actors, actions, outcomes ("As X, I want Y, so that Z")
+├── Scope Boundaries Planner   → v1 MVP, v2 deferred, out of scope, dependencies
+└── Acceptance Criteria Planner → success/failure/edge case criteria (testable)
+```
+
+### Scope Debate Flow
+
+```
+1. Each planner presents their analysis
+2. Scope challenges user stories: "This story is too broad for v1"
+3. Acceptance challenges scope: "These boundaries leave this edge case uncovered"
+4. User stories challenges acceptance: "This criterion is untestable"
+5. Lead collects consensus after max 2 exchange rounds
+```
+
+**Note**: Specification teams complement (not replace) the 3 mandatory clarification gates. User still drives all decisions via Gate 0, Gate 1, and Gate 2.
+
+---
+
+## Resolution Team
+
+### Cross-Validation Resolution Team
+
+```
+Lead spawns resolvers based on batches:
+├── Resolver A → Batch 1 issues (file-a cluster)
+├── Resolver B → Batch 2 issues (file-b cluster)
+└── Resolver C → Batch 3 issues (file-c cluster)
+```
+
+### Resolution Debate Flow
+
+```
+1. Each resolver independently validates + fixes their batch
+2. Lead broadcasts: "Review each other's fixes for cross-batch conflicts"
+3. Resolver A: "My fix in file-a.ts changes the interface that Resolver B depends on"
+4. Resolver B: "Confirmed — my fix in file-b.ts imports from that interface"
+5. Resolvers coordinate the fix or escalate conflict to lead
+6. Lead collects consensus after max 2 exchange rounds
+```
+
+### When Cross-Validation Adds Value
+
+- Fixes touch shared interfaces or types
+- Resolvers modify files that import from each other
+- Batch fixes could introduce conflicting patterns
+- Large resolution sets (>5 issues across multiple files)
+
+### When to Skip Cross-Validation
+
+- All fixes are in completely independent files
+- Only 1-2 batches with no shared dependencies
+- Fixes are trivial (typos, formatting, naming)
+
+---
+
+## Debug Team
+
+### Hypothesis Investigation (3-5 hypotheses)
+
+```
+Lead spawns (one per hypothesis):
+├── Hypothesis A investigator → state management / race condition
+├── Hypothesis B investigator → configuration / environment
+├── Hypothesis C investigator → edge case / input validation
+└── Hypothesis D investigator → dependency / version issue
+```
+
+### Debug Debate Flow
+
+```
+1. Each investigator gathers evidence for their hypothesis
+2. Lead broadcasts: "Present evidence. Disprove each other."
+3. Investigator A: "Found race condition at file:line"
+4. Investigator B: "My config theory is disproved by A's evidence"
+5. Investigator C: "A's race condition doesn't explain the timing"
+6. Converge on surviving hypothesis with strongest evidence
+```
+
+---
+
+## Team Size Guidelines
+
+| Scenario | Min | Max | Rationale |
+|----------|-----|-----|-----------|
+| Quick review | 2 | 3 | Focused, low cost |
+| Full review | 4 | 5 | Core perspectives |
+| Exploration | 3 | 4 | Diminishing returns beyond 4 |
+| Planning | 2 | 3 | Too many cooks |
+| Specification (explore) | 3 | 4 | Requirements need diverse perspectives |
+| Specification (scope) | 2 | 3 | Scope planning benefits from focus |
+| Resolution | 2 | 4 | One per independent batch |
+| Debugging | 3 | 5 | One per viable hypothesis |
+| Parallel coding | 2 | 3 | Merge complexity grows fast |

package/scripts/hooks/background-memory-update.sh

@@ -0,0 +1,167 @@
+#!/bin/bash
+
+# Background Working Memory Updater
+# Called by stop-update-memory.sh as a detached background process.
+# Resumes the parent session headlessly to update .docs/WORKING-MEMORY.md.
+# On failure: logs error, does nothing (no fallback).
+
+set -euo pipefail
+
+CWD="$1"
+SESSION_ID="$2"
+MEMORY_FILE="$3"
+CLAUDE_BIN="$4"
+
+LOG_FILE="$CWD/.docs/.working-memory-update.log"
+LOCK_DIR="$CWD/.docs/.working-memory.lock"
+
+# --- Logging ---
+
+log() {
+  echo "[$(date -u '+%Y-%m-%dT%H:%M:%SZ')] $1" >> "$LOG_FILE"
+}
+
+rotate_log() {
+  if [ -f "$LOG_FILE" ] && [ "$(wc -l < "$LOG_FILE")" -gt 100 ]; then
+    tail -50 "$LOG_FILE" > "$LOG_FILE.tmp" && mv "$LOG_FILE.tmp" "$LOG_FILE"
+  fi
+}
+
+# --- Stale Lock Recovery ---
+
+# Portable mtime in epoch seconds (same pattern as stop-update-memory.sh:35-39)
+get_mtime() {
+  if stat --version &>/dev/null 2>&1; then
+    stat -c %Y "$1"
+  else
+    stat -f %m "$1"
+  fi
+}
+
+STALE_THRESHOLD=300  # 5 min — generous vs 30-60s normal runtime
+
+break_stale_lock() {
+  if [ ! -d "$LOCK_DIR" ]; then return; fi
+  local lock_mtime now age
+  lock_mtime=$(get_mtime "$LOCK_DIR")
+  now=$(date +%s)
+  age=$(( now - lock_mtime ))
+  if [ "$age" -gt "$STALE_THRESHOLD" ]; then
+    log "Breaking stale lock (age: ${age}s, threshold: ${STALE_THRESHOLD}s)"
+    rmdir "$LOCK_DIR" 2>/dev/null || true
+  fi
+}
+
+# --- Locking (mkdir-based, POSIX-atomic) ---
+
+acquire_lock() {
+  local timeout=90
+  local waited=0
+  while ! mkdir "$LOCK_DIR" 2>/dev/null; do
+    if [ "$waited" -ge "$timeout" ]; then
+      return 1
+    fi
+    sleep 1
+    waited=$((waited + 1))
+  done
+  return 0
+}
+
+cleanup() {
+  rmdir "$LOCK_DIR" 2>/dev/null || true
+}
+trap cleanup EXIT
+
+# --- Main ---
+
+# Wait for parent session to flush transcript.
+# 3s provides ~6-10x margin over typical flush times.
+# If --resume shows stale transcripts, bump to 5s.
+sleep 3
+
+log "Starting update for session $SESSION_ID"
+
+# Break stale locks from previous zombie processes
+break_stale_lock
+
+# Acquire lock (other sessions may be updating concurrently)
+if ! acquire_lock; then
+  log "Lock timeout after 90s — skipping update for session $SESSION_ID"
+  # Don't clean up lock we don't own
+  trap - EXIT
+  exit 0
+fi
+
+rotate_log
+
+# Read existing memory for merge context
+EXISTING_MEMORY=""
+if [ -f "$MEMORY_FILE" ]; then
+  EXISTING_MEMORY=$(cat "$MEMORY_FILE")
+fi
+
+# Build instruction
+if [ -n "$EXISTING_MEMORY" ]; then
+  INSTRUCTION="Update the file $MEMORY_FILE with working memory from this session. The file already has content — possibly from a concurrent session that just wrote it moments ago. Merge this session's context with the existing content to produce a single unified working memory snapshot. Both this session and the existing content represent fresh, concurrent work — integrate both fully. Working memory captures what's active now, not a changelog. Deduplicate overlapping information. Keep under 100 lines total. Use the same structure: ## Now, ## Decisions, ## Modified Files, ## Context, ## Session Log.
+
+Existing content:
+$EXISTING_MEMORY"
+else
+  INSTRUCTION="Create the file $MEMORY_FILE with working memory from this session. Keep under 100 lines. Use this structure:
+
+# Working Memory
+
+## Now
+<!-- Current focus, status, blockers (1-3 bullets) -->
+
+## Decisions
+<!-- Key decisions made this session with brief rationale -->
+
+## Modified Files
+<!-- File paths only, most recent first -->
+
+## Context
+<!-- Branch, PR, architectural context, open questions -->
+
+## Session Log
+
+### Today
+<!-- Chronological summary of work done today (2-5 bullets) -->
+
+### This Week
+<!-- Broader multi-day context if relevant -->"
+fi
+
+# Resume session headlessly to perform the update
+TIMEOUT=120  # Normal runtime 30-60s; 2x margin
+
+DEVFLOW_BG_UPDATER=1 env -u CLAUDECODE "$CLAUDE_BIN" -p \
+  --resume "$SESSION_ID" \
+  --model haiku \
+  --dangerously-skip-permissions \
+  --no-session-persistence \
+  --output-format text \
+  "$INSTRUCTION" \
+  > /dev/null 2>> "$LOG_FILE" &
+CLAUDE_PID=$!
+
+# Watchdog: kill claude if it exceeds timeout
+( sleep "$TIMEOUT" && kill "$CLAUDE_PID" 2>/dev/null ) &
+WATCHDOG_PID=$!
+
+if wait "$CLAUDE_PID" 2>/dev/null; then
+  log "Update completed for session $SESSION_ID"
+else
+  EXIT_CODE=$?
+  if [ "$EXIT_CODE" -gt 128 ]; then
+    log "Update timed out (killed after ${TIMEOUT}s) for session $SESSION_ID"
+  else
+    log "Update failed for session $SESSION_ID (exit code $EXIT_CODE)"
+  fi
+fi
+
+# Clean up watchdog
+kill "$WATCHDOG_PID" 2>/dev/null || true
+wait "$WATCHDOG_PID" 2>/dev/null || true
+
+exit 0

package/scripts/hooks/pre-compact-memory.sh

@@ -0,0 +1,81 @@
+#!/bin/bash
+
+# Working Memory: PreCompact Hook
+# Safety net that captures git state to a backup JSON file before context compaction.
+# Also bootstraps a minimal WORKING-MEMORY.md if none exists yet, so SessionStart
+# has something to inject after compaction.
+# PreCompact hooks cannot block compaction — this is informational only.
+
+set -euo pipefail
+
+# jq is required to parse hook input JSON — silently no-op if missing
+if ! command -v jq &>/dev/null; then exit 0; fi
+
+INPUT=$(cat)
+
+CWD=$(echo "$INPUT" | jq -r '.cwd // ""' 2>/dev/null)
+if [ -z "$CWD" ]; then
+  exit 0
+fi
+
+# Only activate in DevFlow-initialized projects
+if [ ! -d "$CWD/.docs" ]; then
+  exit 0
+fi
+
+BACKUP_FILE="$CWD/.docs/working-memory-backup.json"
+
+# Capture git state
+GIT_BRANCH=""
+GIT_STATUS=""
+GIT_LOG=""
+GIT_DIFF_STAT=""
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+if cd "$CWD" 2>/dev/null && git rev-parse --git-dir >/dev/null 2>&1; then
+  GIT_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
+  GIT_STATUS=$(git status --porcelain 2>/dev/null | head -30 || echo "")
+  GIT_LOG=$(git log --oneline -10 2>/dev/null || echo "")
+  GIT_DIFF_STAT=$(git diff --stat HEAD 2>/dev/null || echo "")
+fi
+
+# Write backup JSON
+jq -n \
+  --arg ts "$TIMESTAMP" \
+  --arg branch "$GIT_BRANCH" \
+  --arg status "$GIT_STATUS" \
+  --arg log "$GIT_LOG" \
+  --arg diff "$GIT_DIFF_STAT" \
+  '{
+    timestamp: $ts,
+    trigger: "pre-compact",
+    git: {
+      branch: $branch,
+      status: $status,
+      log: $log,
+      diff_stat: $diff
+    }
+  }' > "$BACKUP_FILE"
+
+# Bootstrap minimal WORKING-MEMORY.md if none exists yet
+# This ensures SessionStart has context to inject after compaction
+MEMORY_FILE="$CWD/.docs/WORKING-MEMORY.md"
+if [ ! -f "$MEMORY_FILE" ] && [ -n "$GIT_BRANCH" ]; then
+  {
+    echo "# Working Memory"
+    echo ""
+    echo "## Now"
+    echo "- Session compacted before working memory was established"
+    echo ""
+    echo "## Context"
+    echo "- Branch: $GIT_BRANCH"
+    echo "$GIT_LOG" | head -3 | while IFS= read -r line; do
+      [ -n "$line" ] && echo "- $line"
+    done
+    echo ""
+    echo "## Modified Files"
+    echo "$GIT_STATUS" | head -10 | while IFS= read -r line; do
+      [ -n "$line" ] && echo "- $(echo "$line" | awk '{print $2}')"
+    done
+  } > "$MEMORY_FILE"
+fi