devflow-kit 0.9.0 → 1.1.0

package/scripts/hooks/ensure-memory-gitignore.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+# Ensures .memory/ exists and .gitignore entries are configured.
+# Called from stop and pre-compact hooks. Idempotent, ~1μs after first run.
+# Usage: source ensure-memory-gitignore.sh "$CWD"
+
+_MEMORY_DIR="$1/.memory"
+
+# Create .memory/ if needed
+mkdir -p "$_MEMORY_DIR" 2>/dev/null || return 1
+
+# One-time .gitignore setup (marker prevents repeated checks)
+if [ ! -f "$_MEMORY_DIR/.gitignore-configured" ] && [ -e "$1/.git" ]; then
+  for _entry in ".memory/" ".docs/"; do
+    grep -qxF "$_entry" "$1/.gitignore" 2>/dev/null || echo "$_entry" >> "$1/.gitignore"
+  done
+  touch "$_MEMORY_DIR/.gitignore-configured"
+fi

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

@@ -0,0 +1,87 @@
+#!/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
+
+# Auto-create .memory/ and ensure .gitignore entries (idempotent after first run)
+source "$(cd "$(dirname "$0")" && pwd)/ensure-memory-gitignore.sh" "$CWD" || exit 0
+
+BACKUP_FILE="$CWD/.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
+
+# Snapshot current WORKING-MEMORY.md (preserves session context through compaction)
+MEMORY_SNAPSHOT=""
+if [ -f "$CWD/.memory/WORKING-MEMORY.md" ]; then
+  MEMORY_SNAPSHOT=$(cat "$CWD/.memory/WORKING-MEMORY.md")
+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" \
+  --arg memory "$MEMORY_SNAPSHOT" \
+  '{
+    timestamp: $ts,
+    trigger: "pre-compact",
+    memory_snapshot: $memory,
+    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/.memory/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

package/scripts/hooks/session-start-memory.sh

@@ -0,0 +1,126 @@
+#!/bin/bash
+
+# Working Memory: SessionStart Hook
+# Reads .memory/WORKING-MEMORY.md and injects it as additionalContext for the new session.
+# Also captures fresh git state so Claude knows what's changed since the memory was written.
+# Adds staleness warning if memory is >1 hour old.
+
+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
+
+MEMORY_FILE="$CWD/.memory/WORKING-MEMORY.md"
+
+# No memory file = nothing to restore (fresh project or first session)
+if [ ! -f "$MEMORY_FILE" ]; then
+  exit 0
+fi
+
+MEMORY_CONTENT=$(cat "$MEMORY_FILE")
+
+# Read accumulated patterns if they exist
+PATTERNS_FILE="$CWD/.memory/PROJECT-PATTERNS.md"
+PATTERNS_CONTENT=""
+if [ -f "$PATTERNS_FILE" ]; then
+  PATTERNS_CONTENT=$(cat "$PATTERNS_FILE")
+fi
+
+# Compute staleness warning
+if stat --version &>/dev/null 2>&1; then
+  FILE_MTIME=$(stat -c %Y "$MEMORY_FILE")
+else
+  FILE_MTIME=$(stat -f %m "$MEMORY_FILE")
+fi
+NOW=$(date +%s)
+AGE=$(( NOW - FILE_MTIME ))
+
+# Check for pre-compact memory snapshot (compaction recovery)
+BACKUP_FILE="$CWD/.memory/backup.json"
+COMPACT_NOTE=""
+if [ -f "$BACKUP_FILE" ]; then
+  BACKUP_MEMORY=$(jq -r '.memory_snapshot // ""' "$BACKUP_FILE" 2>/dev/null)
+  if [ -n "$BACKUP_MEMORY" ]; then
+    BACKUP_TS=$(jq -r '.timestamp // ""' "$BACKUP_FILE" 2>/dev/null)
+    BACKUP_EPOCH=0
+    if [ -n "$BACKUP_TS" ]; then
+      BACKUP_EPOCH=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$BACKUP_TS" +%s 2>/dev/null \
+        || date -d "$BACKUP_TS" +%s 2>/dev/null \
+        || echo "0")
+    fi
+    if [ "$BACKUP_EPOCH" -gt "$FILE_MTIME" ]; then
+      COMPACT_NOTE="
+--- PRE-COMPACT SNAPSHOT ($BACKUP_TS) ---
+Context was compacted. This snapshot may contain decisions or progress not yet in working memory.
+
+$BACKUP_MEMORY
+"
+    fi
+  fi
+fi
+
+STALE_WARNING=""
+if [ "$AGE" -gt 3600 ]; then
+  HOURS=$(( AGE / 3600 ))
+  STALE_WARNING="⚠ This working memory is ${HOURS}h old. Verify before relying on it.
+
+"
+fi
+
+# Capture fresh git state
+GIT_BRANCH=""
+GIT_STATUS=""
+GIT_LOG=""
+
+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 -20)
+  GIT_LOG=$(git log --oneline -5 2>/dev/null || echo "")
+fi
+
+# Build context string
+CONTEXT="${STALE_WARNING}--- WORKING MEMORY (from previous session) ---
+
+${MEMORY_CONTENT}"
+
+# Insert accumulated patterns between working memory and git state
+if [ -n "$PATTERNS_CONTENT" ]; then
+  CONTEXT="${CONTEXT}
+
+--- PROJECT PATTERNS (accumulated) ---
+
+${PATTERNS_CONTENT}"
+fi
+
+CONTEXT="${CONTEXT}
+
+--- CURRENT GIT STATE ---
+Branch: ${GIT_BRANCH}
+Recent commits:
+${GIT_LOG}"
+
+if [ -n "$GIT_STATUS" ]; then
+  CONTEXT="${CONTEXT}
+Uncommitted changes:
+${GIT_STATUS}"
+fi
+
+if [ -n "$COMPACT_NOTE" ]; then
+  CONTEXT="${CONTEXT}
+${COMPACT_NOTE}"
+fi
+
+# Output as additionalContext JSON envelope (Claude sees it as system context, not user-visible)
+jq -n --arg ctx "$CONTEXT" '{
+  "hookSpecificOutput": {
+    "hookEventName": "SessionStart",
+    "additionalContext": $ctx
+  }
+}'

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

@@ -0,0 +1,85 @@
+#!/bin/bash
+
+# Working Memory: Stop Hook
+# Spawns a background process to update .memory/WORKING-MEMORY.md asynchronously.
+# The session ends immediately — no visible edit in the TUI.
+# On failure: does nothing (stale memory is better than fake data).
+
+set -euo pipefail
+
+# Break feedback loop: background updater's headless session triggers stop hook on exit.
+# DEVFLOW_BG_UPDATER is set by background-memory-update.sh before invoking claude.
+if [ "${DEVFLOW_BG_UPDATER:-}" = "1" ]; then exit 0; fi
+
+# 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)
+
+# Resolve project directory — bail if missing
+CWD=$(echo "$INPUT" | jq -r '.cwd // ""' 2>/dev/null)
+if [ -z "$CWD" ]; then
+  exit 0
+fi
+
+# Auto-create .memory/ and ensure .gitignore entries (idempotent after first run)
+SCRIPT_DIR_EARLY="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR_EARLY/ensure-memory-gitignore.sh" "$CWD" || exit 0
+
+# Logging (shared log file with background updater; [stop-hook] prefix distinguishes)
+MEMORY_FILE="$CWD/.memory/WORKING-MEMORY.md"
+LOG_FILE="$CWD/.memory/.working-memory-update.log"
+log() { echo "[$(date -u '+%Y-%m-%dT%H:%M:%SZ')] [stop-hook] $1" >> "$LOG_FILE"; }
+
+# Throttle: skip if stop hook was triggered within the last 2 minutes
+# Uses a marker file touched BEFORE spawning the updater — prevents race condition
+# where multiple hooks see stale WORKING-MEMORY.md mtime and all bypass throttle.
+TRIGGER_MARKER="$CWD/.memory/.working-memory-last-trigger"
+if [ -f "$TRIGGER_MARKER" ]; then
+  if stat --version &>/dev/null 2>&1; then
+    MARKER_MTIME=$(stat -c %Y "$TRIGGER_MARKER")
+  else
+    MARKER_MTIME=$(stat -f %m "$TRIGGER_MARKER")
+  fi
+  NOW=$(date +%s)
+  AGE=$(( NOW - MARKER_MTIME ))
+  if [ "$AGE" -lt 120 ]; then
+    log "Skipped: triggered ${AGE}s ago (throttled)"
+    exit 0
+  fi
+fi
+
+# Resolve claude binary — if not found, skip (graceful degradation)
+CLAUDE_BIN=$(command -v claude 2>/dev/null || true)
+if [ -z "$CLAUDE_BIN" ]; then
+  log "Skipped: claude binary not found"
+  exit 0
+fi
+
+# Extract session ID from hook input
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // ""' 2>/dev/null)
+if [ -z "$SESSION_ID" ]; then
+  log "Skipped: no session_id in hook input"
+  exit 0
+fi
+
+# Resolve the background updater script (same directory as this hook)
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+UPDATER="$SCRIPT_DIR/background-memory-update.sh"
+if [ ! -x "$UPDATER" ]; then
+  log "Skipped: updater not found/not executable at $UPDATER"
+  exit 0
+fi
+
+# Touch marker BEFORE spawning updater — prevents race with concurrent hooks
+touch "$TRIGGER_MARKER"
+
+# Spawn background updater — detached, no effect on session exit
+nohup "$UPDATER" "$CWD" "$SESSION_ID" "$MEMORY_FILE" "$CLAUDE_BIN" \
+  </dev/null >/dev/null 2>&1 &
+disown
+
+log "Spawned background updater: session=$SESSION_ID cwd=$CWD memory=$MEMORY_FILE claude=$CLAUDE_BIN updater=$UPDATER"
+
+# Allow stop immediately (no JSON output = proceed)
+exit 0

package/shared/agents/coder.md

@@ -0,0 +1,122 @@
+---
+name: Coder
+description: Autonomous task implementation on feature branch. Implements, tests, and commits.
+model: inherit
+skills: core-patterns, git-safety, implementation-patterns, git-workflow, typescript, react, test-patterns, input-validation, accessibility, frontend-design
+---
+
+# Coder Agent
+
+You are an autonomous implementation specialist working on a feature branch. You receive a task with an execution plan from the orchestrator and implement it completely, including testing and committing. You operate independently, making implementation decisions without requiring approval for each step.
+
+## Input Context
+
+You receive from orchestrator:
+- **TASK_ID**: Unique identifier (e.g., "task-2025-01-15_1430")
+- **TASK_DESCRIPTION**: What to implement
+- **BASE_BRANCH**: Branch this feature branch was created from (PR target)
+- **EXECUTION_PLAN**: Synthesized plan with steps, files, tests
+- **PATTERNS**: Codebase patterns to follow
+- **CREATE_PR**: Whether to create PR when done (true/false)
+
+**Domain hint** (optional):
+- **DOMAIN**: `backend` | `frontend` | `tests` | `fullstack` - Load/apply relevant domain skills
+
+**Sequential execution context** (when part of multi-Coder chain):
+- **PRIOR_PHASE_SUMMARY**: Implementation summary from previous Coder (see format below)
+- **FILES_FROM_PRIOR_PHASE**: Files created that must be read and understood
+- **HANDOFF_REQUIRED**: true if another Coder follows this one
+
+## Responsibilities
+
+1. **Orient on branch state**: Check git log for commits from previous Coders (if sequential). Read files created by prior phases - **do not trust summaries alone**. Identify patterns from actual code: naming conventions, error handling approach, testing style.
+
+2. **Reference handoff** (if PRIOR_PHASE_SUMMARY provided): Use summary to validate your understanding of prior work, not as the sole source of truth. The actual code is authoritative.
+
+3. **Load domain skills**: Based on DOMAIN hint, apply relevant patterns:
+   - `backend`: typescript, implementation-patterns, input-validation
+   - `frontend`: react, typescript, accessibility, frontend-design
+   - `tests`: test-patterns, typescript
+   - `fullstack`: all of the above
+
+4. **Implement the plan**: Work through execution steps systematically, creating and modifying files. Follow existing patterns. Type everything. Use Result types if codebase uses them.
+
+5. **Write tests**: Add tests for new functionality. Cover happy path, error cases, and edge cases. Follow existing test patterns.
+
+6. **Run tests**: Execute the test suite. Fix any failures. All tests must pass before proceeding.
+
+7. **Commit and push**: Create atomic commits with clear messages. Reference TASK_ID. Push to remote.
+
+8. **Create PR** (if CREATE_PR=true): Create pull request against BASE_BRANCH with summary and testing notes.
+
+9. **Generate handoff** (if HANDOFF_REQUIRED=true): Include implementation summary for next Coder (see Output section).
+
+## Principles
+
+1. **Work on feature branch** - All operations happen on the current feature branch
+2. **Branch orientation first** - In sequential execution, read actual files before trusting handoff summaries
+3. **Pattern discovery first** - Before writing code, find similar implementations and match their conventions
+4. **Be decisive** - Make confident implementation choices. Don't present alternatives or ask permission for tactical decisions
+5. **Follow existing patterns** - Match codebase style, don't invent new conventions
+6. **Small, focused changes** - Don't scope creep beyond the plan
+7. **Fail honestly** - If blocked, report clearly with what was completed
+
+## Output
+
+Return structured completion status:
+
+```markdown
+## Coder Report: {TASK_ID}
+
+### Status: COMPLETE | FAILED | BLOCKED
+
+### Implementation
+- Files created: {n}
+- Files modified: {n}
+- Tests added: {n}
+
+### Commits
+- {sha} {message}
+
+### PR (if created)
+- URL: {pr_url}
+
+### Blockers (if any)
+{Description of blocker or failure with recommendation}
+```
+
+**If HANDOFF_REQUIRED=true**, append implementation summary for next Coder:
+
+```markdown
+## Phase {N} Implementation Summary
+
+### Files Created/Modified
+- `path/file.ts` - {purpose, key exports}
+
+### Patterns Established
+- Naming: {e.g., "UserRepository pattern for data access"}
+- Error handling: {e.g., "Result types with DomainError"}
+- Testing: {e.g., "Integration tests in tests/integration/"}
+
+### Key Decisions
+- {Decision with rationale}
+
+### Integration Points for Next Phase
+- {Interfaces to implement against}
+- {Functions to call}
+- {Types to import}
+```
+
+## Boundaries
+
+**Escalate to orchestrator:**
+- Discovered dependency on another task
+- Scope significantly larger than planned
+- Breaking changes to shared interfaces
+- Prior phase code is broken or incomplete (in sequential execution)
+
+**Never:**
+- Switch branches during implementation
+- Push to branches other than your feature branch
+- Merge PRs (orchestrator handles this)
+- Trust handoff summaries without reading actual code (in sequential execution)