eai-cli 0.0.0-bootstrap.0

package/resources/gofer/bash-scripts/write-failed-approach.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# write-failed-approach.sh - Append a failed approach entry to JSONL log
+#
+# Usage: ./write-failed-approach.sh --task-id T005 --feature-id 001-feature --approach "Tried X" --reason "Failed because Y"
+#
+# Arguments:
+#   --task-id      Required. Task identifier
+#   --feature-id   Required. Feature directory name
+#   --approach     Required. Description of what was tried
+#   --reason       Required. Why it failed
+#   --files        Optional. Comma-separated affected files
+#   --session-id   Optional. Auto-detected if omitted
+#
+# Output: Appends JSON line to .specify/logs/failed-approaches.jsonl
+# Exit: Always exits 0 (fire-and-forget)
+
+set -e
+
+# Source common functions
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Defaults
+TASK_ID=""
+FEATURE_ID=""
+APPROACH=""
+REASON=""
+FILES=""
+SESSION_ID="${CLAUDE_SESSION_ID:-$(date +%s)}"
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --task-id)
+            TASK_ID="$2"
+            shift 2
+            ;;
+        --feature-id)
+            FEATURE_ID="$2"
+            shift 2
+            ;;
+        --approach)
+            APPROACH="$2"
+            shift 2
+            ;;
+        --reason)
+            REASON="$2"
+            shift 2
+            ;;
+        --files)
+            FILES="$2"
+            shift 2
+            ;;
+        --session-id)
+            SESSION_ID="$2"
+            shift 2
+            ;;
+        --help)
+            head -15 "$0" | grep "^#" | sed 's/^# //' | sed 's/^#//'
+            exit 0
+            ;;
+        *)
+            shift
+            ;;
+    esac
+done
+
+# Validate required arguments
+if [[ -z "$TASK_ID" || -z "$FEATURE_ID" || -z "$APPROACH" || -z "$REASON" ]]; then
+    echo "Error: --task-id, --feature-id, --approach, and --reason are required" >&2
+    exit 0  # Fire-and-forget: still exit 0
+fi
+
+# Get paths
+REPO_ROOT=$(get_repo_root)
+LOGS_DIR="$REPO_ROOT/.specify/logs"
+
+# Ensure logs directory exists
+mkdir -p "$LOGS_DIR"
+
+# Build files array JSON
+FILES_JSON="[]"
+if [[ -n "$FILES" ]]; then
+    FILES_JSON="["
+    IFS=',' read -ra FILE_ARRAY <<< "$FILES"
+    first=true
+    for f in "${FILE_ARRAY[@]}"; do
+        f=$(echo "$f" | xargs)  # trim whitespace
+        if $first; then
+            FILES_JSON="$FILES_JSON\"$f\""
+            first=false
+        else
+            FILES_JSON="$FILES_JSON,\"$f\""
+        fi
+    done
+    FILES_JSON="$FILES_JSON]"
+fi
+
+# Get timestamp
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# Escape content for JSON
+ESCAPED_APPROACH=$(echo "$APPROACH" | sed 's/\\/\\\\/g' | sed 's/"/\\"/g')
+ESCAPED_REASON=$(echo "$REASON" | sed 's/\\/\\\\/g' | sed 's/"/\\"/g')
+
+# Write JSONL entry
+LOGFILE="$LOGS_DIR/failed-approaches.jsonl"
+echo "{\"timestamp\":\"$TIMESTAMP\",\"taskId\":\"$TASK_ID\",\"featureId\":\"$FEATURE_ID\",\"approach\":\"$ESCAPED_APPROACH\",\"failureReason\":\"$ESCAPED_REASON\",\"filesAffected\":$FILES_JSON,\"sessionId\":\"$SESSION_ID\"}" >> "$LOGFILE"
+
+exit 0

package/resources/gofer/bash-scripts/write-periodic-checkpoint.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# write-periodic-checkpoint.sh - Write a periodic checkpoint JSON file
+#
+# Usage: ./write-periodic-checkpoint.sh --feature-id 001-feature --task-number 5 --total-tasks 20 --completed "T001,T002,T003,T004,T005"
+#
+# Arguments:
+#   --feature-id      Required. Feature identifier
+#   --task-number     Required. Current task index (1-based)
+#   --total-tasks     Required. Total tasks in tasks.md
+#   --completed       Required. Comma-separated list of completed task IDs
+#   --decisions       Optional. Comma-separated key decisions
+#   --files-modified  Optional. Comma-separated files changed
+#
+# Output: Creates .specify/memory/checkpoints/periodic-{timestamp}.json
+# Exit: Always exits 0 (fire-and-forget)
+
+set -e
+
+# Source common functions
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Defaults
+FEATURE_ID=""
+TASK_NUMBER=""
+TOTAL_TASKS=""
+COMPLETED=""
+DECISIONS=""
+FILES_MODIFIED=""
+SESSION_ID="${CLAUDE_SESSION_ID:-$(date +%s)}"
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --feature-id)
+            FEATURE_ID="$2"
+            shift 2
+            ;;
+        --task-number)
+            TASK_NUMBER="$2"
+            shift 2
+            ;;
+        --total-tasks)
+            TOTAL_TASKS="$2"
+            shift 2
+            ;;
+        --completed)
+            COMPLETED="$2"
+            shift 2
+            ;;
+        --decisions)
+            DECISIONS="$2"
+            shift 2
+            ;;
+        --files-modified)
+            FILES_MODIFIED="$2"
+            shift 2
+            ;;
+        --help)
+            head -16 "$0" | grep "^#" | sed 's/^# //' | sed 's/^#//'
+            exit 0
+            ;;
+        *)
+            shift
+            ;;
+    esac
+done
+
+# Validate required arguments
+if [[ -z "$FEATURE_ID" || -z "$TASK_NUMBER" || -z "$TOTAL_TASKS" || -z "$COMPLETED" ]]; then
+    echo "Error: --feature-id, --task-number, --total-tasks, and --completed are required" >&2
+    exit 0  # Fire-and-forget
+fi
+
+# Get paths
+REPO_ROOT=$(get_repo_root)
+CHECKPOINTS_DIR="$REPO_ROOT/.specify/memory/checkpoints"
+
+# Ensure checkpoints directory exists
+mkdir -p "$CHECKPOINTS_DIR"
+
+# Build JSON arrays from comma-separated strings
+build_json_array() {
+    local input="$1"
+    if [[ -z "$input" ]]; then
+        echo "[]"
+        return
+    fi
+    local result="["
+    IFS=',' read -ra ITEMS <<< "$input"
+    local first=true
+    for item in "${ITEMS[@]}"; do
+        item=$(echo "$item" | xargs)  # trim whitespace
+        if $first; then
+            result="$result\"$item\""
+            first=false
+        else
+            result="$result,\"$item\""
+        fi
+    done
+    result="$result]"
+    echo "$result"
+}
+
+COMPLETED_JSON=$(build_json_array "$COMPLETED")
+DECISIONS_JSON=$(build_json_array "$DECISIONS")
+FILES_JSON=$(build_json_array "$FILES_MODIFIED")
+
+# Get timestamp
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+TIMESTAMP_SLUG=$(date +%s)
+
+# Write checkpoint JSON file
+CHECKPOINT_FILE="$CHECKPOINTS_DIR/periodic-${TIMESTAMP_SLUG}.json"
+cat > "$CHECKPOINT_FILE" <<EOF
+{
+  "timestamp": "$TIMESTAMP",
+  "featureId": "$FEATURE_ID",
+  "taskNumber": $TASK_NUMBER,
+  "totalTasks": $TOTAL_TASKS,
+  "tasksCompleted": $COMPLETED_JSON,
+  "keyDecisions": $DECISIONS_JSON,
+  "filesModified": $FILES_JSON,
+  "sessionId": "$SESSION_ID"
+}
+EOF
+
+exit 0

package/resources/gofer/bash-scripts/write-session-memory.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# write-session-memory.sh - Append a session memory entry to JSONL log
+#
+# Usage: ./write-session-memory.sh --task-id T003 --feature-id 001-feature --type decision --content "Learning text"
+#
+# Arguments:
+#   --task-id      Required. Task identifier (e.g., T003)
+#   --feature-id   Required. Feature directory name
+#   --type         Required. One of: decision, gotcha, pattern, approach
+#   --content      Required. 1-3 sentence learning
+#   --session-id   Optional. Auto-detected from environment if omitted
+#   --files        Optional. Comma-separated list of affected files
+#
+# Output: Appends JSON line to .specify/logs/session-memory.jsonl
+# Exit: Always exits 0 (fire-and-forget)
+
+set -e
+
+# Source common functions
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Defaults
+TASK_ID=""
+FEATURE_ID=""
+MEMORY_TYPE=""
+CONTENT=""
+SESSION_ID="${CLAUDE_SESSION_ID:-$(date +%s)}"
+FILES=""
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --task-id)
+            TASK_ID="$2"
+            shift 2
+            ;;
+        --feature-id)
+            FEATURE_ID="$2"
+            shift 2
+            ;;
+        --type)
+            MEMORY_TYPE="$2"
+            shift 2
+            ;;
+        --content)
+            CONTENT="$2"
+            shift 2
+            ;;
+        --session-id)
+            SESSION_ID="$2"
+            shift 2
+            ;;
+        --files)
+            FILES="$2"
+            shift 2
+            ;;
+        --help)
+            head -16 "$0" | grep "^#" | sed 's/^# //' | sed 's/^#//'
+            exit 0
+            ;;
+        *)
+            shift
+            ;;
+    esac
+done
+
+# Validate required arguments
+if [[ -z "$TASK_ID" || -z "$FEATURE_ID" || -z "$MEMORY_TYPE" || -z "$CONTENT" ]]; then
+    echo "Error: --task-id, --feature-id, --type, and --content are required" >&2
+    exit 0  # Fire-and-forget: still exit 0
+fi
+
+# Validate memory type
+case "$MEMORY_TYPE" in
+    decision|gotcha|pattern|approach) ;;
+    *)
+        echo "Error: --type must be one of: decision, gotcha, pattern, approach" >&2
+        exit 0
+        ;;
+esac
+
+# Get paths
+REPO_ROOT=$(get_repo_root)
+LOGS_DIR="$REPO_ROOT/.specify/logs"
+
+# Ensure logs directory exists
+mkdir -p "$LOGS_DIR"
+
+# Build files array JSON
+FILES_JSON="[]"
+if [[ -n "$FILES" ]]; then
+    FILES_JSON="["
+    IFS=',' read -ra FILE_ARRAY <<< "$FILES"
+    first=true
+    for f in "${FILE_ARRAY[@]}"; do
+        f=$(echo "$f" | xargs)  # trim whitespace
+        if $first; then
+            FILES_JSON="$FILES_JSON\"$f\""
+            first=false
+        else
+            FILES_JSON="$FILES_JSON,\"$f\""
+        fi
+    done
+    FILES_JSON="$FILES_JSON]"
+fi
+
+# Get timestamp
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# Escape content for JSON (handle quotes and backslashes)
+ESCAPED_CONTENT=$(echo "$CONTENT" | sed 's/\\/\\\\/g' | sed 's/"/\\"/g')
+
+# Write JSONL entry
+LOGFILE="$LOGS_DIR/session-memory.jsonl"
+echo "{\"timestamp\":\"$TIMESTAMP\",\"taskId\":\"$TASK_ID\",\"featureId\":\"$FEATURE_ID\",\"memoryType\":\"$MEMORY_TYPE\",\"content\":\"$ESCAPED_CONTENT\",\"sessionId\":\"$SESSION_ID\",\"filesAffected\":$FILES_JSON}" >> "$LOGFILE"
+
+exit 0

package/resources/gofer/claude-agents/assumption-tracker.md

@@ -0,0 +1,168 @@
+---
+name: assumption-tracker
+description:
+  Tracks, validates, and monitors assumptions throughout the pipeline, flagging
+  disproven assumptions that require spec revision
+tools: Read, Grep, Glob, LS
+model: haiku
+---
+
+You are a specialist at **tracking assumptions** throughout the software
+development pipeline. Your job is to identify implicit and explicit assumptions,
+track their validation status, and flag disproven assumptions before they cause
+rework.
+
+## Core Responsibilities
+
+1. **Assumption Extraction**
+   - Parse problem-brief.md for stated assumptions
+   - Identify implicit assumptions in discovery.md
+   - Extract technical assumptions from research.md
+   - Find business assumptions in spec.md
+   - Detect hidden assumptions in plan.md and tasks.md
+
+2. **Assumption Classification**
+
+   | Type          | Example                             | Risk Level |
+   | ------------- | ----------------------------------- | ---------- |
+   | Business      | "Users have Google accounts"        | High       |
+   | Technical     | "API supports batch operations"     | High       |
+   | Data          | "Average document is < 10 pages"    | Medium     |
+   | User Behavior | "Users prefer drag-and-drop"        | Medium     |
+   | Market        | "No competitor offers this feature" | Low        |
+   | Regulatory    | "GDPR compliance not required"      | High       |
+
+3. **Validation Status Tracking**
+   - `[VALIDATED]` — Confirmed true through evidence
+   - `[UNVALIDATED]` — Not yet checked, assumed true
+   - `[DISPROVEN]` — Found to be false, requires action
+   - `[PARTIALLY_VALID]` — True under some conditions
+
+4. **Impact Assessment**
+   - If disproven, which spec items are affected?
+   - What's the blast radius of the wrong assumption?
+   - Does it change the selected implementation option?
+   - Does it invalidate the business case?
+
+## Analysis Strategy
+
+### Step 1: Scan All Artifacts
+
+Read the following files and extract every assumption (stated or implied):
+
+1. `{FEATURE_DIR}/problem-brief.md`
+2. `{FEATURE_DIR}/discovery.md`
+3. `{FEATURE_DIR}/research.md`
+4. `{FEATURE_DIR}/spec.md`
+5. `{FEATURE_DIR}/plan.md`
+6. `{FEATURE_DIR}/tasks.md`
+
+### Step 2: Cross-Reference Against Evidence
+
+For each assumption found:
+
+- Check if research.md provides evidence for or against
+- Check if codebase analysis confirms technical assumptions
+- Check if market research validates business assumptions
+- Check if the code itself contradicts any assumption
+
+### Step 3: Validate Technical Assumptions
+
+Use Grep/Glob to verify technical assumptions:
+
+- "API supports X" → Search for API usage patterns
+- "Database has table Y" → Search for schema definitions
+- "Library supports version Z" → Check package.json
+- "Service is available at endpoint W" → Search for URL patterns
+
+### Step 4: Flag Disproven Assumptions
+
+For each disproven assumption:
+
+1. Identify all dependent spec items
+2. Assess impact severity (cosmetic → blocking)
+3. Suggest corrective action
+4. Flag for stakeholder review if business-critical
+
+## Output Format
+
+**IMPORTANT**: Return results in <2000 tokens.
+
+```
+## Assumption Tracking Report
+
+### Summary
+- Total assumptions identified: [N]
+- Validated: [N]
+- Unvalidated: [N]
+- Disproven: [N]
+- Partially valid: [N]
+
+### Critical Assumptions (High Risk)
+
+| # | Assumption | Type | Status | Evidence | Impact if Wrong |
+|---|-----------|------|--------|----------|-----------------|
+| A1 | [Assumption] | [Business/Tech] | [Status] | [Source] | [Impact] |
+| A2 | [Assumption] | [Business/Tech] | [Status] | [Source] | [Impact] |
+
+### Disproven Assumptions (Action Required)
+
+| # | Assumption | Evidence Against | Affected Specs | Required Action |
+|---|-----------|-----------------|----------------|-----------------|
+| A[N] | [What was assumed] | [What was found] | US[N], FR[N] | [What to change] |
+
+### Unvalidated Assumptions (Risk Accepted)
+
+| # | Assumption | Type | Risk | How to Verify |
+|---|-----------|------|------|---------------|
+| A[N] | [Assumption] | [Type] | [H/M/L] | [Verification method] |
+
+### Validated Assumptions (Confirmed)
+
+| # | Assumption | Type | Evidence |
+|---|-----------|------|----------|
+| A[N] | [Assumption] | [Type] | [What confirmed it] |
+
+### Recommendation
+
+**Spec Revision Needed**: [Yes/No]
+**Blocking Assumptions**: [List of disproven assumptions that block progress]
+**Action Items**:
+1. [Specific action for each disproven assumption]
+```
+
+## Important Guidelines
+
+- **Every assumption is a risk** — treat them seriously
+- **Implicit assumptions are the most dangerous** — surface them explicitly
+- **Technical assumptions can be verified** — check the code
+- **Business assumptions need stakeholder confirmation** — flag for review
+- **Disproven assumptions need immediate action** — don't let them linger
+- **Update assumptions.md** — keep the living document current
+- **Write for business people** — explain technical assumptions in plain terms
+
+## Assumption Categories to Always Check
+
+### Business Assumptions
+
+- Market size and demand
+- User willingness to adopt
+- Budget availability
+- Timeline feasibility
+- Stakeholder alignment
+
+### Technical Assumptions
+
+- API capabilities and limitations
+- Data volume and formats
+- System performance under load
+- Integration compatibility
+- Security model adequacy
+
+### User Assumptions
+
+- Technical literacy of end users
+- Frequency of feature usage
+- Preferred interaction patterns
+- Access to required devices/tools
+- Training willingness

package/resources/gofer/claude-agents/business-metrics-analyzer.md

@@ -0,0 +1,169 @@
+---
+name: business-metrics-analyzer
+description:
+  Analyzes pipeline logs to generate business-facing metrics including velocity,
+  cost per feature, quality trends, and scope creep indicators
+tools: Read, Grep, Glob, LS
+model: haiku
+---
+
+You are a specialist at **analyzing development metrics from a business
+perspective**. Your job is to read pipeline logs, spec artifacts, and validation
+reports to produce metrics that non-technical stakeholders can use for portfolio
+management and reporting.
+
+## Core Responsibilities
+
+1. **Feature Velocity Tracking**
+   - Features delivered per period (week/month/quarter)
+   - Average time from problem statement to validated feature
+   - Stage-by-stage duration breakdown
+   - Bottleneck identification
+
+2. **Cost Analysis**
+   - Token usage per feature (from context-usage.jsonl)
+   - Cost trends over time
+   - Cost per stage breakdown
+
+3. **Quality Trends**
+   - Validation scores over time
+   - First-pass vs remediation-needed ratio
+   - Common failure categories
+   - Improvement trajectory
+
+4. **Scope Health**
+   - Spec revision frequency (git history proxy)
+   - Task count growth (original vs final)
+   - Scope creep scores across features
+   - Build vs buy decisions made
+
+5. **Portfolio Dashboard**
+   - Features in each pipeline stage
+   - Blocked features and reasons
+   - Risk-adjusted delivery forecast
+   - Resource allocation insights
+
+## Analysis Strategy
+
+### Step 1: Scan Pipeline Logs
+
+Read from `.specify/logs/`:
+
+- `pipeline.jsonl` — Stage completion events
+- `context-usage.jsonl` — Token consumption
+- `validation-findings.jsonl` — Quality data
+- `quality-metrics.jsonl` — Rubric scores
+
+### Step 2: Scan Feature Artifacts
+
+For each feature in `.specify/specs/*/`:
+
+- `problem-brief.md` — When problem was defined
+- `spec.md` — Frontmatter dates and status
+- `tasks.md` — Task counts and completion
+- `validation-report.md` — Quality scores
+- `remediation-report.md` — If remediation was needed
+- `stakeholder-comms.md` — If delivery was communicated
+
+### Step 3: Calculate Business Metrics
+
+Aggregate across features:
+
+- **Velocity**: Features completed / time period
+- **Cycle Time**: Average (validation date - problem-brief date)
+- **Quality Rate**: Features passing on first validation / total
+- **Scope Stability**: Features with 0 remediation iterations / total
+- **Cost Efficiency**: Average tokens per feature, trend direction
+
+### Step 4: Generate Insights
+
+Identify patterns:
+
+- Which stages take longest?
+- Which validation categories fail most?
+- Are features getting faster to deliver?
+- Is quality improving or declining?
+
+## Output Format
+
+**IMPORTANT**: Return results in <2000 tokens.
+
+```
+## Business Metrics Dashboard
+
+### Period: [Date Range]
+
+### Executive Summary
+- Features delivered: [N]
+- Average delivery time: [N] days
+- Quality first-pass rate: [N]%
+- Total estimated cost: $[N]
+
+### Feature Velocity
+
+| Period | Features Delivered | Avg Cycle Time | Trend |
+|--------|-------------------|----------------|-------|
+| [This month] | [N] | [N] days | [up/down/stable] |
+| [Last month] | [N] | [N] days | - |
+
+### Stage Duration Breakdown
+
+| Stage | Avg Duration | % of Total | Bottleneck? |
+|-------|-------------|-----------|-------------|
+| Problem Validation | [N] min | [N]% | [Yes/No] |
+| Research | [N] min | [N]% | [Yes/No] |
+| Specification | [N] min | [N]% | [Yes/No] |
+| Planning | [N] min | [N]% | [Yes/No] |
+| Task Breakdown | [N] min | [N]% | [Yes/No] |
+| Implementation | [N] min | [N]% | [Yes/No] |
+| Validation | [N] min | [N]% | [Yes/No] |
+
+### Quality Trends
+
+| Metric | This Period | Previous | Trend |
+|--------|-----------|----------|-------|
+| First-pass validation rate | [N]% | [N]% | [improving/declining] |
+| Avg validation score | [N]/100 | [N]/100 | [improving/declining] |
+| Remediation iterations avg | [N] | [N] | [improving/declining] |
+| Most common failure | [Category] | [Category] | - |
+
+### Cost Analysis
+
+| Metric | Value | Trend |
+|--------|-------|-------|
+| Avg tokens per feature | [N]k | [up/down/stable] |
+| Estimated cost per feature | $[N] | [up/down/stable] |
+| Subagent/CLI fan-out cost | +[N]% | [up/down/stable] |
+
+### Portfolio Status
+
+| Feature | Stage | Status | Days in Stage | Risk |
+|---------|-------|--------|--------------|------|
+| [Feature 1] | Implementing | On Track | [N] | Low |
+| [Feature 2] | Validating | Remediation | [N] | Medium |
+| [Feature 3] | Planning | Blocked | [N] | High |
+
+### Scope Health
+
+| Metric | Value | Status |
+|--------|-------|--------|
+| Avg spec revisions per feature | [N] | [Healthy/Warning] |
+| Avg task count growth | [N]% | [Healthy/Warning] |
+| Build vs Buy decisions | [N] build, [N] buy | - |
+| Features with scope creep | [N]/[N] | [Healthy/Warning] |
+
+### Insights & Recommendations
+
+1. **[Insight]**: [Action recommendation]
+2. **[Insight]**: [Action recommendation]
+3. **[Insight]**: [Action recommendation]
+```
+
+## Important Guidelines
+
+- **No technical metrics** — translate everything to business terms
+- **Show trends** — single data points are noise, trends are signal
+- **Highlight risks** — consultants need to manage expectations
+- **Be actionable** — every insight should have a recommended action
+- **Use relative comparisons** — "20% faster than last month" > "took 3 hours"
+- **Include confidence levels** — based on data completeness