@pennyfarthing/core 7.5.0 → 7.6.0

package/pennyfarthing-dist/scripts/workflow/start-workflow.sh

@@ -0,0 +1,256 @@
+#!/bin/bash
+# Start a stepped workflow
+# Usage: .pennyfarthing/scripts/core/run.sh workflow/start-workflow.sh <name> [--mode create|validate|edit]
+#
+# Creates a new workflow session and loads step 1.
+# For tri-modal workflows, --mode selects the step path (default: create)
+
+set -euo pipefail
+
+# PROJECT_ROOT should be set by run.sh, but find it if not
+if [[ -z "${PROJECT_ROOT:-}" ]]; then
+  d="$PWD"
+  while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do
+    d="$(dirname "$d")"
+  done
+  PROJECT_ROOT="$d"
+fi
+
+WORKFLOWS_DIR="$PROJECT_ROOT/pennyfarthing-dist/workflows"
+SESSION_DIR="$PROJECT_ROOT/.session"
+
+if ! command -v yq &> /dev/null; then
+  echo "Error: yq is required but not installed"
+  echo "Install with: brew install yq"
+  exit 1
+fi
+
+# Parse arguments
+WORKFLOW_NAME=""
+MODE=""
+ARGS=("$@")
+
+i=0
+while [[ $i -lt ${#ARGS[@]} ]]; do
+  arg="${ARGS[$i]}"
+  case "$arg" in
+    --mode=*)
+      MODE="${arg#--mode=}"
+      ;;
+    --mode|-m)
+      if [[ $((i+1)) -lt ${#ARGS[@]} ]]; then
+        ((i++))
+        MODE="${ARGS[$i]}"
+      else
+        echo "Error: --mode requires a value (create, validate, or edit)"
+        exit 1
+      fi
+      ;;
+    -*)
+      echo "Error: Unknown option: $arg"
+      echo "Usage: start-workflow.sh <name> [--mode create|validate|edit]"
+      exit 1
+      ;;
+    *)
+      if [[ -z "$WORKFLOW_NAME" ]]; then
+        WORKFLOW_NAME="$arg"
+      else
+        echo "Error: Unexpected argument: $arg"
+        exit 1
+      fi
+      ;;
+  esac
+  ((i++))
+done
+
+if [[ -z "$WORKFLOW_NAME" ]]; then
+  echo "# Start Stepped Workflow"
+  echo ""
+  echo "Usage: /workflow start <name> [--mode create|validate|edit]"
+  echo ""
+  echo "**Available stepped workflows:**"
+  echo ""
+  for f in "$WORKFLOWS_DIR"/*.yaml "$WORKFLOWS_DIR"/*/workflow.yaml; do
+    [[ -f "$f" ]] || continue
+    workflow_type=$(yq eval '.workflow.type // "phased"' "$f")
+    if [[ "$workflow_type" == "stepped" ]]; then
+      name=$(yq eval '.workflow.name' "$f")
+      desc=$(yq eval '.workflow.description' "$f" | head -1 | cut -c1-60)
+      echo "- **$name** - $desc"
+    fi
+  done
+  exit 1
+fi
+
+# Find workflow file (support both flat and directory structure)
+WORKFLOW_FILE=""
+if [[ -f "$WORKFLOWS_DIR/${WORKFLOW_NAME}.yaml" ]]; then
+  WORKFLOW_FILE="$WORKFLOWS_DIR/${WORKFLOW_NAME}.yaml"
+elif [[ -f "$WORKFLOWS_DIR/${WORKFLOW_NAME}/workflow.yaml" ]]; then
+  WORKFLOW_FILE="$WORKFLOWS_DIR/${WORKFLOW_NAME}/workflow.yaml"
+else
+  echo "Error: Workflow '$WORKFLOW_NAME' not found"
+  echo ""
+  echo "Looked in:"
+  echo "  $WORKFLOWS_DIR/${WORKFLOW_NAME}.yaml"
+  echo "  $WORKFLOWS_DIR/${WORKFLOW_NAME}/workflow.yaml"
+  exit 1
+fi
+
+WORKFLOW_DIR=$(dirname "$WORKFLOW_FILE")
+
+# Validate it's a stepped workflow
+WORKFLOW_TYPE=$(yq eval '.workflow.type // "phased"' "$WORKFLOW_FILE")
+if [[ "$WORKFLOW_TYPE" != "stepped" ]]; then
+  echo "Error: '$WORKFLOW_NAME' is a phased workflow, not stepped"
+  echo "Use TDD workflow commands (/sm, /tea, /dev, /reviewer) for phased workflows"
+  exit 1
+fi
+
+# Validate mode if provided
+if [[ -n "$MODE" ]]; then
+  case "$MODE" in
+    create|validate|edit)
+      ;;
+    *)
+      echo "Error: Invalid mode '$MODE'. Must be one of: create, validate, edit"
+      exit 1
+      ;;
+  esac
+fi
+
+# Get workflow info
+WORKFLOW_DESC=$(yq eval '.workflow.description' "$WORKFLOW_FILE")
+WORKFLOW_AGENT=$(yq eval '.workflow.agent // "pm"' "$WORKFLOW_FILE")
+
+# Resolve steps path based on mode
+if [[ -n "$MODE" ]]; then
+  MODE_PATH=$(yq eval ".workflow.modes.$MODE // \"\"" "$WORKFLOW_FILE")
+  if [[ -z "$MODE_PATH" || "$MODE_PATH" == "null" ]]; then
+    AVAILABLE_MODES=$(yq eval '.workflow.modes | keys | .[]' "$WORKFLOW_FILE" 2>/dev/null | grep -v default | tr '\n' ', ' | sed 's/,$//')
+    echo "Error: Mode '$MODE' not available for workflow '$WORKFLOW_NAME'"
+    echo "Available modes: $AVAILABLE_MODES"
+    exit 1
+  fi
+  STEPS_PATH="$MODE_PATH"
+else
+  # Use default mode or steps.path
+  DEFAULT_MODE=$(yq eval '.workflow.modes.default // ""' "$WORKFLOW_FILE")
+  if [[ -n "$DEFAULT_MODE" && "$DEFAULT_MODE" != "null" ]]; then
+    MODE_PATH=$(yq eval ".workflow.modes.$DEFAULT_MODE // \"\"" "$WORKFLOW_FILE")
+    if [[ -n "$MODE_PATH" && "$MODE_PATH" != "null" ]]; then
+      STEPS_PATH="$MODE_PATH"
+      MODE="$DEFAULT_MODE"
+    fi
+  fi
+
+  if [[ -z "${STEPS_PATH:-}" ]]; then
+    STEPS_PATH=$(yq eval '.workflow.steps.path' "$WORKFLOW_FILE")
+    MODE="${MODE:-create}"
+  fi
+fi
+
+# Resolve relative path
+if [[ "$STEPS_PATH" == ./* ]]; then
+  STEPS_PATH="$WORKFLOW_DIR/${STEPS_PATH#./}"
+elif [[ "$STEPS_PATH" != /* ]]; then
+  STEPS_PATH="$PROJECT_ROOT/$STEPS_PATH"
+fi
+
+# Count steps
+STEPS_PATTERN=$(yq eval '.workflow.steps.pattern // "step-*.md"' "$WORKFLOW_FILE")
+STEP_COUNT=$(find "$STEPS_PATH" -maxdepth 1 -name "step-0*.md" -o -name "step-1*.md" 2>/dev/null | wc -l | tr -d ' ')
+
+if [[ "$STEP_COUNT" -eq 0 ]]; then
+  echo "Error: No step files found in $STEPS_PATH"
+  exit 1
+fi
+
+# Create session directory
+mkdir -p "$SESSION_DIR"
+
+# Generate session filename
+SESSION_FILE="$SESSION_DIR/${WORKFLOW_NAME}-workflow-session.md"
+
+# Check for existing session
+if [[ -f "$SESSION_FILE" ]]; then
+  echo "**Warning:** Existing session found"
+  echo ""
+  echo "Session: $SESSION_FILE"
+  echo ""
+  echo "Options:"
+  echo "1. Use \`/workflow resume $WORKFLOW_NAME\` to continue"
+  echo "2. Delete the session file to start fresh"
+  echo ""
+  echo "To start fresh, run:"
+  echo "\`\`\`bash"
+  echo "rm \"$SESSION_FILE\""
+  echo "\`\`\`"
+  exit 0
+fi
+
+# Create initial session file
+NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+cat > "$SESSION_FILE" << EOF
+# Workflow Session: $WORKFLOW_NAME
+
+**Workflow:** $WORKFLOW_NAME
+**Type:** stepped
+**Agent:** $WORKFLOW_AGENT
+**Started:** $NOW
+
+## Workflow State
+- **Workflow Name:** $WORKFLOW_NAME
+- **Type:** stepped
+- **Mode:** $MODE
+- **Started:** $NOW
+- **Last Updated:** $NOW
+- **Current Step:** 1
+- **Steps Completed:** []
+- **Status:** in_progress
+- **Notes:** Session created via /workflow start
+
+## Progress
+- Total Steps: $STEP_COUNT
+- Completion: 0%
+
+---
+
+EOF
+
+# Find step 1 file (handle various naming patterns)
+STEP_FILE=$(find "$STEPS_PATH" -maxdepth 1 \( -name "step-01*.md" -o -name "step-1-*.md" \) 2>/dev/null | sort | head -1)
+
+if [[ -z "$STEP_FILE" ]]; then
+  echo "Error: Could not find step 1 file in $STEPS_PATH"
+  exit 1
+fi
+
+# Output workflow start info
+echo "# Starting Workflow: $WORKFLOW_NAME"
+echo ""
+echo "**Description:** $WORKFLOW_DESC"
+echo "**Mode:** $MODE"
+echo "**Steps:** $STEP_COUNT"
+echo "**Agent:** $WORKFLOW_AGENT"
+echo "**Session:** $SESSION_FILE"
+echo ""
+echo "---"
+echo ""
+echo "## Step 1 of $STEP_COUNT"
+echo ""
+
+# Output step content (strip frontmatter if present)
+if head -1 "$STEP_FILE" | grep -q "^---$"; then
+  awk '/^---$/{if(++c==2){p=1;next}}p' "$STEP_FILE"
+else
+  cat "$STEP_FILE"
+fi
+
+echo ""
+echo "---"
+echo ""
+echo "**Controls:**"
+echo "- \`C\` - Continue to next step"
+echo "- \`/workflow status\` - Check progress"
+echo "- \`/workflow resume\` - Resume after break"

package/pennyfarthing-dist/scripts/workflow/workflow-status.sh

@@ -0,0 +1,167 @@
+#!/bin/bash
+# Show current stepped workflow progress
+# Usage: .pennyfarthing/scripts/core/run.sh workflow/workflow-status.sh [name]
+#
+# If no name provided, shows status of active workflow session
+
+set -euo pipefail
+
+# PROJECT_ROOT should be set by run.sh, but find it if not
+if [[ -z "${PROJECT_ROOT:-}" ]]; then
+  d="$PWD"
+  while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do
+    d="$(dirname "$d")"
+  done
+  PROJECT_ROOT="$d"
+fi
+
+WORKFLOWS_DIR="$PROJECT_ROOT/pennyfarthing-dist/workflows"
+SESSION_DIR="$PROJECT_ROOT/.session"
+
+if ! command -v yq &> /dev/null; then
+  echo "Error: yq is required but not installed"
+  echo "Install with: brew install yq"
+  exit 1
+fi
+
+WORKFLOW_NAME="${1:-}"
+
+# If no name, try to detect from session
+if [[ -z "$WORKFLOW_NAME" ]]; then
+  SESSION_FILE=$(find "$SESSION_DIR" -maxdepth 1 -name "*-workflow-session.md" 2>/dev/null | head -1)
+
+  if [[ -z "$SESSION_FILE" ]]; then
+    echo "# Workflow Status"
+    echo ""
+    echo "No active workflow session found."
+    echo ""
+    echo "Use \`/workflow start <name>\` to begin a new workflow."
+    exit 0
+  fi
+
+  WORKFLOW_NAME=$(grep -E "^\*\*Workflow:\*\*" "$SESSION_FILE" 2>/dev/null | sed 's/\*\*Workflow:\*\* //' | tr -d ' ')
+
+  if [[ -z "$WORKFLOW_NAME" ]]; then
+    WORKFLOW_NAME=$(basename "$SESSION_FILE" | sed 's/-workflow-session.md//')
+  fi
+else
+  SESSION_FILE="$SESSION_DIR/${WORKFLOW_NAME}-workflow-session.md"
+fi
+
+if [[ ! -f "$SESSION_FILE" ]]; then
+  echo "# Workflow Status: $WORKFLOW_NAME"
+  echo ""
+  echo "No session found for workflow '$WORKFLOW_NAME'"
+  echo ""
+  echo "Use \`/workflow start $WORKFLOW_NAME\` to begin."
+  exit 0
+fi
+
+# Find workflow file
+WORKFLOW_FILE=""
+if [[ -f "$WORKFLOWS_DIR/${WORKFLOW_NAME}.yaml" ]]; then
+  WORKFLOW_FILE="$WORKFLOWS_DIR/${WORKFLOW_NAME}.yaml"
+elif [[ -f "$WORKFLOWS_DIR/${WORKFLOW_NAME}/workflow.yaml" ]]; then
+  WORKFLOW_FILE="$WORKFLOWS_DIR/${WORKFLOW_NAME}/workflow.yaml"
+fi
+
+WORKFLOW_DIR=$(dirname "$WORKFLOW_FILE")
+
+# Parse session state
+CURRENT_STEP=$(grep -E "^\- \*\*Current Step:\*\*" "$SESSION_FILE" 2>/dev/null | sed 's/.*\*\* //' || echo "1")
+MODE=$(grep -E "^\- \*\*Mode:\*\*" "$SESSION_FILE" 2>/dev/null | sed 's/.*\*\* //' || echo "create")
+STATUS=$(grep -E "^\- \*\*Status:\*\*" "$SESSION_FILE" 2>/dev/null | sed 's/.*\*\* //' || echo "in_progress")
+STARTED=$(grep -E "^\- \*\*Started:\*\*" "$SESSION_FILE" 2>/dev/null | sed 's/.*\*\* //' || echo "-")
+LAST_UPDATED=$(grep -E "^\- \*\*Last Updated:\*\*" "$SESSION_FILE" 2>/dev/null | sed 's/.*\*\* //' || echo "-")
+STEPS_COMPLETED=$(grep -E "^\- \*\*Steps Completed:\*\*" "$SESSION_FILE" 2>/dev/null | sed 's/.*\*\* //' || echo "[]")
+NOTES=$(grep -E "^\- \*\*Notes:\*\*" "$SESSION_FILE" 2>/dev/null | sed 's/.*\*\* //' || echo "-")
+
+# Get total steps from workflow
+if [[ -n "$WORKFLOW_FILE" && -f "$WORKFLOW_FILE" ]]; then
+  # Resolve steps path based on mode
+  MODE_PATH=$(yq eval ".workflow.modes.$MODE // \"\"" "$WORKFLOW_FILE")
+  if [[ -n "$MODE_PATH" && "$MODE_PATH" != "null" ]]; then
+    STEPS_PATH="$MODE_PATH"
+  else
+    STEPS_PATH=$(yq eval '.workflow.steps.path' "$WORKFLOW_FILE")
+  fi
+
+  # Resolve relative path
+  if [[ "$STEPS_PATH" == ./* ]]; then
+    STEPS_PATH="$WORKFLOW_DIR/${STEPS_PATH#./}"
+  elif [[ "$STEPS_PATH" != /* ]]; then
+    STEPS_PATH="$PROJECT_ROOT/$STEPS_PATH"
+  fi
+
+  STEP_COUNT=$(find "$STEPS_PATH" -maxdepth 1 -name "step-0*.md" -o -name "step-1*.md" 2>/dev/null | wc -l | tr -d ' ')
+  WORKFLOW_DESC=$(yq eval '.workflow.description' "$WORKFLOW_FILE" | head -1)
+else
+  STEP_COUNT="?"
+  WORKFLOW_DESC="-"
+fi
+
+# Calculate completion percentage
+COMPLETED_COUNT=$(echo "$STEPS_COMPLETED" | tr -cd ',' | wc -c | tr -d ' ')
+if [[ "$STEPS_COMPLETED" != "[]" && -n "$STEPS_COMPLETED" ]]; then
+  COMPLETED_COUNT=$((COMPLETED_COUNT + 1))
+fi
+
+if [[ "$STEP_COUNT" != "?" && "$STEP_COUNT" -gt 0 ]]; then
+  COMPLETION_PCT=$((COMPLETED_COUNT * 100 / STEP_COUNT))
+else
+  COMPLETION_PCT=0
+fi
+
+# Build progress bar
+BAR_WIDTH=20
+if [[ "$STEP_COUNT" != "?" && "$STEP_COUNT" -gt 0 ]]; then
+  FILLED=$((COMPLETION_PCT * BAR_WIDTH / 100))
+  EMPTY=$((BAR_WIDTH - FILLED))
+  PROGRESS_BAR=$(printf '%*s' "$FILLED" '' | tr ' ' '#')$(printf '%*s' "$EMPTY" '' | tr ' ' '-')
+else
+  PROGRESS_BAR=$(printf '%*s' "$BAR_WIDTH" '' | tr ' ' '?')
+fi
+
+# Status indicator
+case "$STATUS" in
+  completed)
+    STATUS_ICON="[COMPLETE]"
+    ;;
+  paused)
+    STATUS_ICON="[PAUSED]"
+    ;;
+  *)
+    STATUS_ICON="[IN PROGRESS]"
+    ;;
+esac
+
+# Output status
+echo "# Workflow Status: $WORKFLOW_NAME"
+echo ""
+echo "**Description:** $WORKFLOW_DESC"
+echo ""
+echo "## Progress"
+echo ""
+echo "\`\`\`"
+echo "[$PROGRESS_BAR] $COMPLETION_PCT%"
+echo "\`\`\`"
+echo ""
+echo "| Field | Value |"
+echo "|-------|-------|"
+echo "| Status | $STATUS_ICON |"
+echo "| Mode | $MODE |"
+echo "| Current Step | $CURRENT_STEP of $STEP_COUNT |"
+echo "| Completed | $COMPLETED_COUNT steps |"
+echo "| Steps Done | $STEPS_COMPLETED |"
+echo "| Started | $STARTED |"
+echo "| Last Updated | $LAST_UPDATED |"
+if [[ "$NOTES" != "-" ]]; then
+  echo "| Notes | $NOTES |"
+fi
+echo ""
+echo "**Session:** $SESSION_FILE"
+echo ""
+
+if [[ "$STATUS" != "completed" ]]; then
+  echo "**Next:** Use \`/workflow resume\` to continue from step $CURRENT_STEP"
+fi

package/pennyfarthing-dist/skills/agentic-patterns/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: agentic-patterns
+description: Core reasoning patterns for building effective LLM agents. Use when designing agent behavior, debugging agent failures, improving agent reliability, or understanding ReAct/Plan-and-Execute patterns.
+allowed_tools: [Read, Glob, Grep, Task]
+---
+
+# Agentic Patterns Skill
+
+**Purpose:** Core reasoning patterns for building effective LLM agents.
+
+**Use when:** Designing agent behavior, debugging agent failures, improving agent reliability.
+
+---
+
+## Core Reasoning Patterns
+
+### 1. ReAct (Reasoning and Acting)
+
+The foundational agentic loop. Combines chain-of-thought with tool use.
+
+```
+THOUGHT: What am I trying to accomplish? What do I know?
+ACTION: Execute tool/command based on reasoning
+OBSERVATION: What was the result? Did it match expectations?
+THOUGHT: Based on observation, what next?
+... repeat until goal achieved
+```
+
+**Why it works:** Grounds LLM outputs in real observations. Reduces hallucinations.
+
+**When to use:** Most tasks. This is the default pattern.
+
+**Example:**
+```
+THOUGHT: I need to find where authentication is handled
+ACTION: grep -r "authenticate" --include="*.go"
+OBSERVATION: Found 3 files: auth.go, middleware.go, handlers.go
+THOUGHT: middleware.go likely has the auth middleware, let me read it
+```
+
+### 2. Plan-and-Execute
+
+Decompose complex goals into sub-tasks before acting.
+
+```
+1. PLAN: Break goal into discrete steps
+2. EXECUTE: Work through each step
+3. VERIFY: Check each step succeeded before moving on
+4. ADJUST: Replan if something fails
+```
+
+**Why it works:** Prevents getting lost in complex tasks. Makes progress visible.
+
+**When to use:** Multi-step tasks, unfamiliar codebases, architectural changes.
+
+**Example:**
+```
+PLAN for "Add user authentication":
+1. Check existing auth patterns in codebase
+2. Design auth middleware
+3. Implement token validation
+4. Add protected routes
+5. Write tests
+6. Update documentation
+
+Now executing step 1...
+```
+
+### 3. Self-Reflection
+
+Evaluate own outputs before presenting them.
+
+```
+1. GENERATE: Produce initial output
+2. CRITIQUE: What could be wrong? What did I assume?
+3. REFINE: Improve based on critique
+4. PRESENT: Only after reflection
+```
+
+**Why it works:** Catches errors before they propagate. Improves quality.
+
+**When to use:** Code generation, architectural decisions, any output that matters.
+
+**Example:**
+```
+GENERATED: Function to validate email
+CRITIQUE: Did I handle edge cases? Empty string? Unicode?
+REFINE: Add null check, use proper regex, handle IDN domains
+PRESENT: Here's the validated function...
+```
+
+---
+
+## Confidence and Uncertainty
+
+### Confidence Levels
+
+| Level | Indicators | Action |
+|-------|-----------|--------|
+| HIGH (proceed) | Matches known patterns, clear requirements, similar past success | Act autonomously |
+| MEDIUM (verify) | Some unknowns, first time for this pattern, could break things | Ask before risky actions |
+| LOW (ask) | Architectural change, security-sensitive, deleting files | Always ask user |
+
+### Expressing Uncertainty
+
+When uncertain, SAY SO:
+
+```
+GOOD: "I'm not sure if this is the right approach. Here's my reasoning..."
+GOOD: "I found two possible solutions. Let me explain the tradeoffs..."
+BAD: [silently picks one approach without mentioning alternatives]
+BAD: [confidently states something without verifying]
+```
+
+### Confidence Calibration
+
+Before acting, ask yourself:
+1. Have I seen this pattern before? (in skills, sidecars, or this session)
+2. What could go wrong?
+3. Is this reversible?
+4. Would a senior engineer want to review this?
+
+---
+
+## Error Recovery
+
+### The Retry Pattern
+
+```
+1. ATTEMPT: Try the action
+2. OBSERVE: Did it succeed?
+3. DIAGNOSE: If failed, why?
+4. ADJUST: Modify approach based on diagnosis
+5. RETRY: Max 2 retries with different approaches
+6. ESCALATE: If still failing, ask user
+```
+
+### Graceful Degradation
+
+When stuck:
+1. **Never silently fail.** Always report what happened.
+2. **Provide context.** What were you trying to do? What went wrong?
+3. **Suggest alternatives.** "I couldn't do X, but I could try Y instead..."
+4. **Ask for help.** "I'm blocked on Z. Can you help?"
+
+### Common Failure Modes
+
+| Failure | Recovery |
+|---------|----------|
+| Tool returned error | Read error message, adjust inputs, retry |
+| Unexpected output | Verify assumptions, try different approach |
+| Stuck in loop | Stop, reflect, try fundamentally different approach |
+| Context exhaustion | Summarize progress, ask user for direction |
+
+---
+
+## Multi-Agent Coordination
+
+### Handoff Patterns
+
+When handing off to another agent:
+
+1. **Write before you speak.** Update session file BEFORE saying "ready for X"
+2. **Summarize, don't dump.** Pass key findings, not full context
+3. **State expectations.** What should the next agent do?
+4. **Verify handoff.** Confirm the update was written
+
+### State Synchronization
+
+**Session file is source of truth.** Always:
+- Read session file on activation
+- Write your assessment before handoff
+- Verify what you wrote is actually in the file
+
+### Conflict Resolution
+
+If agents disagree (e.g., Reviewer rejects Dev's code):
+1. Reviewer documents specific issues
+2. Dev addresses each issue
+3. Reviewer re-reviews
+4. Repeat until resolved or escalate to user
+
+---
+
+## Context Management
+
+### Just-in-Time Loading
+
+**Don't:** Load all potentially relevant files upfront
+**Do:** Store paths/identifiers, load only when needed
+
+```
+WRONG: Read all 50 test files to understand testing patterns
+RIGHT: Read testing skill, then load specific test when implementing
+```
+
+### Context Efficiency
+
+- Keep tool results focused (don't read entire files if you need one function)
+- Summarize findings rather than quoting everything
+- Reference file:line instead of copying code
+
+### When Context Gets Full
+
+1. Summarize progress so far
+2. Identify what's still needed
+3. Ask user if you should continue with fresh context
+4. Or hand off to subagent with focused task
+
+---
+
+## Reasoning Mode (Toggleable)
+
+**Default:** Quiet mode - follow patterns internally, show only key decisions
+
+**Verbose mode:** User says "verbose mode" to enable explicit reasoning
+
+When verbose, show:
+```
+THOUGHT: [articulate intent]
+ACTION: [describe tool/command]
+OBSERVATION: [verify result]
+REFLECT: [adjust if needed]
+```
+
+When quiet, only show:
+- Key decisions
+- Results
+- Questions/blockers
+
+---
+
+## Key Sources
+
+- [Anthropic: Building Effective Agents](https://www.anthropic.com/research/building-effective-agents)
+- [Anthropic: Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)
+- [LangChain: ReAct Pattern](https://blog.langchain.com/react-agent/)
+- [LangChain: Reflection Agents](https://blog.langchain.com/reflection-agents/)
+
+---
+
+**Remember:** The goal is not to follow patterns rigidly, but to THINK before acting, VERIFY results, and ASK when uncertain.