@bugzy-ai/bugzy 1.18.4 → 1.19.0

package/templates/init/.bugzy/runtime/hooks/pre-compact.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# PreCompact Hook — Flush insights before context compaction
+# This script runs automatically before Claude Code compacts context.
+# Its stdout is injected into the conversation, instructing Claude to save learnings.
+
+set -euo pipefail
+
+RUNTIME_DIR=".bugzy/runtime"
+LOGS_DIR="$RUNTIME_DIR/logs"
+TODAY=$(date +%Y-%m-%d)
+LOG_FILE="$LOGS_DIR/$TODAY.md"
+
+# Ensure logs directory exists
+mkdir -p "$LOGS_DIR"
+
+cat <<'INSTRUCTIONS'
+=== PRE-COMPACTION: Save Your Learnings ===
+
+Context compaction is about to happen. Before your context is compressed, extract and save any knowledge from this session that matches the categories below.
+
+**Write entries to the daily log file** using the Write tool:
+INSTRUCTIONS
+
+echo "**Daily log path:** \`$LOG_FILE\`"
+
+cat <<'INSTRUCTIONS'
+
+**Format each entry as:**
+```markdown
+### HH:MM — {source-role-or-task}
+<!-- source: {task-or-subagent} -->
+- Insight or pattern learned
+- Another insight
+```
+
+**Extraction Categories (save only what applies):**
+- **Application patterns** — UI flows, navigation, API response patterns
+- **Test reliability** — Flaky selectors, timing issues, retry patterns
+- **Team preferences** — Communication style, workflow expectations
+- **Technical constraints** — Rate limits, auth lifetimes, deployment gotchas
+- **Environment facts** — URLs, test data patterns, feature flags
+
+**Include provenance** on each entry. Only save knowledge that would help in future sessions.
+INSTRUCTIONS
+
+# Inject the full maintenance guide for reference
+if [ -f "$RUNTIME_DIR/knowledge-maintenance-guide.md" ]; then
+  echo ""
+  echo "=== Knowledge Maintenance Guide (Reference) ==="
+  cat "$RUNTIME_DIR/knowledge-maintenance-guide.md"
+fi
+
+exit 0

package/templates/init/.bugzy/runtime/hooks/session-start.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# SessionStart Hook — Load knowledge base and recent daily logs into context
+# This script runs automatically at the start of each Claude Code session.
+# Its stdout is injected into the conversation context.
+
+set -euo pipefail
+
+RUNTIME_DIR=".bugzy/runtime"
+
+# Clean up any stale hook markers from previous sessions
+rm -rf "$RUNTIME_DIR/hooks/.markers" 2>/dev/null || true
+
+PROJECT_CONTEXT="$RUNTIME_DIR/project-context.md"
+KB_FILE="$RUNTIME_DIR/knowledge-base.md"
+LOGS_DIR="$RUNTIME_DIR/logs"
+
+# --- Memory System Overview ---
+cat <<'OVERVIEW'
+=== Memory System ===
+
+This project uses a hooks-based memory system with three layers:
+
+1. **Knowledge Base** (`.bugzy/runtime/knowledge-base.md`) — Curated, long-term knowledge. The source of truth.
+2. **Daily Log** (`.bugzy/runtime/logs/YYYY-MM-DD.md`) — Scratch buffer for the current day's insights.
+3. **Subagent Memory** (`.bugzy/runtime/memory/{role}.md`) — Role-specific knowledge per subagent.
+
+**Lifecycle:** During work, insights accumulate in context. Before context compaction (PreCompact hook), you flush insights to the daily log. At session end (SessionEnd hook), you consolidate the daily log into the knowledge base. Subagents manage their own memory via SubagentStart/SubagentStop hooks.
+
+Below is the current project context, knowledge base, and recent daily logs.
+OVERVIEW
+echo ""
+
+# --- Load Project Context ---
+if [ -f "$PROJECT_CONTEXT" ]; then
+  echo "=== Project Context ==="
+  cat "$PROJECT_CONTEXT"
+  echo ""
+fi
+
+# --- Load Knowledge Base ---
+if [ -f "$KB_FILE" ]; then
+  echo "=== Knowledge Base ==="
+  cat "$KB_FILE"
+  echo ""
+fi
+
+# --- Load Recent Daily Logs ---
+if [ -d "$LOGS_DIR" ]; then
+  TODAY=$(date +%Y-%m-%d)
+  YESTERDAY=$(date -v-1d +%Y-%m-%d 2>/dev/null || date -d "yesterday" +%Y-%m-%d 2>/dev/null || echo "")
+
+  if [ -f "$LOGS_DIR/$TODAY.md" ]; then
+    echo "=== Daily Log: $TODAY ==="
+    cat "$LOGS_DIR/$TODAY.md"
+    echo ""
+  fi
+
+  if [ -n "$YESTERDAY" ] && [ -f "$LOGS_DIR/$YESTERDAY.md" ]; then
+    echo "=== Daily Log: $YESTERDAY ==="
+    cat "$LOGS_DIR/$YESTERDAY.md"
+    echo ""
+  fi
+
+  # --- Prune logs older than 7 days ---
+  find "$LOGS_DIR" -name "*.md" -mtime +7 -delete 2>/dev/null || true
+fi
+
+exit 0

package/templates/init/.bugzy/runtime/knowledge-maintenance-guide.md

@@ -95,3 +95,46 @@ Remove entries when:
 | "On Tuesday user said X, then on Friday user said Y" | "User's position on X is Y" (keep most current) |
 | Keeping every detail ever mentioned | Keeping relevant, current details |
 | "User might like coffee, user mentioned tea once, user drinks water" | "User prefers tea; also drinks coffee occasionally" |
+
+---
+
+## Extraction Schema
+
+When deciding what to save, use these structured categories as guidance. Not every session produces entries in every category — only save what genuinely qualifies.
+
+### Application Patterns
+UI flows, navigation structure, page load behaviors, API response patterns, authentication flows, state transitions.
+
+### Test Reliability
+Flaky selectors, timing-sensitive flows, environment-specific behaviors, retry patterns, stable vs unstable locators.
+
+### Team Preferences
+Communication style, channel routing, workflow expectations, review preferences, notification conventions.
+
+### Technical Constraints
+API rate limits, auth token lifetimes, infrastructure boundaries, deployment gotchas, browser compatibility issues.
+
+### Environment Facts
+URLs, credentials structure (not values), test data patterns, feature flags, environment-specific configurations.
+
+---
+
+## Provenance Format
+
+Every knowledge base entry must include provenance metadata as an HTML comment immediately after the heading:
+
+```markdown
+## Entry Title
+<!-- source: {task-or-subagent} | learned: {YYYY-MM-DD} | verified: {YYYY-MM-DD} -->
+
+Entry content here...
+```
+
+**Fields:**
+- **source**: Which task or subagent produced this knowledge (e.g., `run-tests`, `test-engineer`, `explore-application`)
+- **learned**: Date the knowledge was first discovered
+- **verified**: Date the knowledge was last confirmed as still accurate
+
+**Verification Rule:** If an entry's `verified` date is more than 30 days old and you encounter the same topic, re-verify the information and update the `verified` date. If the fact has changed, update or remove the entry.
+
+**Gradual Migration:** Existing entries without provenance remain valid. Add provenance when you next update an entry — no bulk migration needed.

package/templates/init/.bugzy/runtime/subagent-memory-guide.md

@@ -85,3 +85,38 @@ New information
 - Working knowledge for your specific tasks
 
 **When in doubt**: If multiple sub-agents could use it → Main agent
+
+---
+
+## Provenance Format
+
+Every memory entry must include provenance metadata as an HTML comment immediately after the heading:
+
+```markdown
+## Entry Title
+<!-- source: {your-role} | learned: {YYYY-MM-DD} | verified: {YYYY-MM-DD} -->
+
+Entry content here...
+```
+
+**Fields:**
+- **source**: Your subagent role (e.g., `test-engineer`, `browser-automation`)
+- **learned**: Date the knowledge was first discovered
+- **verified**: Date the knowledge was last confirmed as still accurate
+
+**Verification Rule:** If an entry's `verified` date is more than 30 days old and you encounter the same topic, re-verify the information and update the `verified` date. If the fact has changed, update or remove the entry.
+
+**Gradual Migration:** Existing entries without provenance remain valid. Add provenance when you next update an entry.
+
+---
+
+## Role-Specific Extraction Hints
+
+Each role should focus on extracting knowledge within its domain:
+
+- **test-engineer**: Selector strategies, page object patterns, framework conventions, test data patterns
+- **test-debugger-fixer**: Failure patterns, root cause categories, fix strategies, flaky test indicators
+- **team-communicator**: Channel configurations, message format preferences, thread conventions, escalation paths
+- **browser-automation**: Timing patterns, navigation quirks, viewport requirements, wait strategies
+- **issue-tracker**: Bug categorization, priority heuristics, label conventions, duplicate detection patterns
+- **documentation-researcher**: Source reliability, content structure, search strategies, documentation gaps

package/templates/init/.claude/settings.json

@@ -1,7 +1,28 @@
 {
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .bugzy/runtime/hooks/session-start.sh"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .bugzy/runtime/hooks/pre-compact.sh"
+          }
+        ]
+      }
+    ]
+  },
   "permissions": {
     "allow": [
-      "Bash(jq:*)",
       "mcp__notion__API-post-database-query",
       "mcp__notion__API-retrieve-a-database",
       "Bash(mkdir:*)",

package/templates/init/tests/CLAUDE.md

@@ -3,6 +3,12 @@
 ## Framework
 Playwright with TypeScript
 
+## Environment
+
+Playwright and Chromium browser binaries are **pre-installed** in the execution environment. npm packages from `package.json` are also pre-installed in the project root.
+
+**DO NOT** run `npx playwright install` or `npm install` — all dependencies are already available.
+
 ## Test Execution
 
 Run commands from the project root directory.