@codeharbor/agent-playbook 0.1.0 → 0.1.2

package/skills/self-improving-agent/memory/semantic-patterns.json

@@ -0,0 +1,288 @@
+{
+  "patterns": {
+    "prd_document_separation": {
+      "id": "pat-2025-01-11-001",
+      "name": "Document Separation for Complex PRDs",
+      "source": "user_feedback",
+      "confidence": 0.95,
+      "applications": 0,
+      "created": "2025-01-11",
+      "category": "prd_structure",
+      "pattern": "For non-trivial PRDs, split into 4 files with clear purposes",
+      "problem": "Single large PRD file (~500 lines) with mixed product/technical content is hard to follow",
+      "solution": {
+        "files": [
+          {
+            "name": "{name}-notes.md",
+            "purpose": "Thinking process, options analysis",
+            "audience": "Self + future reviewers"
+          },
+          {
+            "name": "{name}-task-plan.md",
+            "purpose": "Project tracking, phases, progress",
+            "audience": "PM + development lead"
+          },
+          {
+            "name": "{name}-prd.md",
+            "purpose": "Product requirements (what & why)",
+            "audience": "PM + stakeholders + developers"
+          },
+          {
+            "name": "{name}-tech.md",
+            "purpose": "Technical design (how)",
+            "audience": "Developers + architects"
+          }
+        ]
+      },
+      "quality_rules": [
+        "PRD focuses on problem, goals, scope, user flows",
+        "Tech doc focuses on API, data flow, implementation",
+        "Notes document architecture options with A/B/C analysis",
+        "Task plan has checkboxes with timestamps",
+        "PRD references tech doc, doesn't duplicate"
+      ],
+      "target_skills": ["prd-planner", "architecting-solutions"]
+    },
+    "state_monitoring_over_callbacks": {
+      "id": "pat-2025-01-11-002",
+      "name": "Direct State Monitoring vs Callbacks",
+      "source": "implementation_review",
+      "confidence": 0.90,
+      "applications": 0,
+      "created": "2025-01-11",
+      "category": "react_patterns",
+      "pattern": "Prefer direct state monitoring over callback chains for side effects",
+      "problem": "Callback chains passed through multiple layers are hard to trace and debug",
+      "solution": {
+        "anti_pattern": "useBorrowTxUpdate({ onRefresh: () => { /* refresh logic */ } });",
+        "pattern": "const pendingCount = txs.length;\nconst prevPendingCount = usePrevious(pendingCount);\nuseEffect(() => {\n  if (pendingCount < prevPendingCount) {\n    requestBorrowRefresh({ reason: 'completed' });\n  }\n}, [pendingCount, prevPendingCount]);"
+      },
+      "when_to_use": [
+        "State changes need to trigger side effects",
+        "Callback chain would be 3+ layers deep",
+        "Multiple components need to react to same state change"
+      ],
+      "quality_rules": [
+        "Use usePrevious to detect state changes instead of callbacks when feasible",
+        "Keep state monitoring close to where state is consumed",
+        "Use callbacks only for cross-component boundaries"
+      ],
+      "target_skills": ["debugger", "refactoring-specialist"]
+    },
+    "state_machine_over_booleans": {
+      "id": "pat-2025-01-11-003",
+      "name": "State Machine Over Boolean Flags",
+      "source": "implementation_review",
+      "confidence": 0.85,
+      "applications": 0,
+      "created": "2025-01-11",
+      "category": "async_patterns",
+      "pattern": "Use state machines for async operations with multiple phases",
+      "problem": "Simple boolean flags can't represent 'waiting to run' vs 'currently running', causing race conditions",
+      "solution": {
+        "anti_pattern": "const inFlight = false;",
+        "pattern": "enum EStatus {\n  Idle = 'idle',\n  Waiting = 'waiting',  // Scheduled but not running yet\n  Running = 'running',\n}"
+      },
+      "benefits": [
+        "Prevents race conditions (can't schedule new request while running)",
+        "Distinguishes 'waiting to run' from 'currently running'",
+        "Easier to debug and log state transitions"
+      ],
+      "quality_rules": [
+        "Use state machine for async operations with multiple phases",
+        "Prevent state transitions that don't make sense",
+        "Log state transitions for debugging"
+      ],
+      "target_skills": ["debugger", "api-designer"]
+    },
+    "measurable_success_criteria": {
+      "id": "pat-2025-01-11-004",
+      "name": "Measurable Success Criteria",
+      "source": "user_feedback",
+      "confidence": 0.90,
+      "applications": 0,
+      "created": "2025-01-11",
+      "category": "prd_quality",
+      "pattern": "Success criteria must include specific numbers/timings to enable verification",
+      "problem": "Vague success criteria like 'data refreshes' don't enable testing or verification",
+      "solution": {
+        "bad_examples": [
+          "Data refreshes after transaction",
+          "Manual refresh works",
+          "No performance regression"
+        ],
+        "good_examples": [
+          "BorrowHome data refreshes within 3-5 seconds after pending transaction completes",
+          "Manual refresh button triggers full refresh and shows loading state",
+          "API response time under 500ms for 95th percentile"
+        ]
+      },
+      "quality_rules": [
+        "Success criteria include specific numbers/timings",
+        "Each criterion is objectively verifiable",
+        "Performance targets have percentiles (e.g., 95th, 99th)",
+        "User-facing behavior has observable indicators"
+      ],
+      "target_skills": ["prd-planner", "architecting-solutions"]
+    },
+    "non_goals_section": {
+      "id": "pat-2025-01-11-005",
+      "name": "Non-Goals Section",
+      "source": "user_feedback",
+      "confidence": 0.90,
+      "applications": 0,
+      "created": "2025-01-11",
+      "category": "prd_structure",
+      "pattern": "Explicitly state what won't be done to prevent scope creep",
+      "problem": "Without explicit non-goals, scope creeps during implementation",
+      "solution": {
+        "structure": "## Goals\n- [Specific achievable outcomes]\n\n## Non-Goals\n- [Explicit exclusions - things that might seem related but aren't]"
+      },
+      "quality_rules": [
+        "Goals section has 3-5 focused items",
+        "Non-goals section explicitly excludes reasonable-but-out-of-scope items",
+        "Each non-goal has a brief rationale if not obvious"
+      ],
+      "target_skills": ["prd-planner", "architecting-solutions"]
+    },
+    "ui_ux_specification_granularity": {
+      "id": "pat-2025-01-11-006",
+      "name": "UI/UX Specification Granularity",
+      "source": "retrospective",
+      "confidence": 0.95,
+      "applications": 0,
+      "created": "2025-01-11",
+      "category": "ui_patterns",
+      "pattern": "UI/UX PRDs require explicit visual specifications to prevent rework",
+      "problem": "Ambiguous UI specs (position, size, spacing) cause implementation rework",
+      "solution": {
+        "required_elements": {
+          "layout_structure": ["Relative position: same row / next row / below / above", "Parent-child container relationships", "Spacing values (gap, padding, margin)"],
+          "component_specs": ["Icon/Button sizes: iconSize=\"$4\" (24px)", "Text styles: size=\"$bodyMd\", color=\"$textSubdued\"", "Component variants: size=\"small\", variant=\"tertiary\""],
+          "visual_comparison": "Before/After ASCII art showing layout change",
+          "executable_criteria": "Checklist with exact prop values"
+        },
+        "examples": {
+          "bad": "Refresh button next to amount",
+          "good": "Refresh button in same XStack as amount with gap='$3'"
+        }
+      },
+      "quality_rules": [
+        "Relative position explicitly stated (same row/next row/below/above)",
+        "Component sizes with exact values (iconSize prop or px)",
+        "Spacing values defined (gap=\"$3\", mx=\"$2\")",
+        "Before/After visual comparison included",
+        "Success criteria are executable (verify by reading code)",
+        "Mobile vs desktop differences explicitly called out"
+      ],
+      "target_skills": ["prd-planner", "architecting-solutions"]
+    },
+    "reuse_existing_infrastructure": {
+      "id": "pat-2025-01-11-007",
+      "name": "Reuse Existing Infrastructure",
+      "source": "comparison_analysis",
+      "confidence": 0.90,
+      "applications": 0,
+      "created": "2025-01-11",
+      "category": "architecture",
+      "pattern": "Always check if Context/Provider already has the data before adding new fetching",
+      "problem": "Adding duplicate data fetching creates redundant network calls and complexity",
+      "solution": {
+        "anti_pattern": "const { pendingTxs } = useBorrowTxUpdate({ accountId, networkId, provider }); // Creates new polling loop!",
+        "pattern": "const { pendingTxs } = useBorrowContext(); // BorrowDataGate already updates this"
+      },
+      "quality_checklist": [
+        "Check if Context/Provider already has the data",
+        "Verify no duplicate polling/fetching",
+        "Confirm single source of truth",
+        "Only add new fetching when lifecycle is truly independent"
+      ],
+      "benefits": ["Reduces network/background calls", "Better performance (no redundant work)", "Single source of truth", "Simpler code (fewer hooks to manage)"],
+      "target_skills": ["architecting-solutions", "api-designer", "debugger"]
+    },
+    "click_time_vs_open_time_computation": {
+      "id": "pat-2025-01-11-008",
+      "name": "Click-Time vs Open-Time Computation",
+      "source": "implementation_review",
+      "confidence": 0.85,
+      "applications": 0,
+      "created": "2025-01-11",
+      "category": "react_patterns",
+      "pattern": "For mutable state, compute at action time, not at render/init time",
+      "problem": "Open-time computation creates stale snapshots when state changes before user acts",
+      "solution": {
+        "anti_pattern": "const allIds = useMemo(() =>\n  claimableItems.filter(i => !pendingClaimIds.includes(i.id)),\n  [claimableItems, pendingClaimIds]\n); // Stale if pendingClaimIds changes before user clicks",
+        "pattern": "onClaimAll: (ids: string[]) => Promise<void> => {\n  const freshIds = claimableItems\n    .filter(i => !pendingClaimIds.includes(i.id))\n    .map(i => i.id);\n  return submitClaim(freshIds);\n}"
+      },
+      "decision_matrix": {
+        "open_time": ["Immutable data", "Expensive computation"],
+        "click_time": ["Mutable state", "User-dependent filters"]
+      },
+      "benefits": ["State is always fresh when user acts", "No stale data issues", "Simpler reasoning about state"],
+      "target_skills": ["debugger", "api-designer"]
+    },
+    "search_before_creating_components": {
+      "id": "pat-2025-01-11-009",
+      "name": "Search Before Creating Components",
+      "source": "prud_correction",
+      "confidence": 0.90,
+      "applications": 0,
+      "created": "2025-01-11",
+      "category": "development",
+      "pattern": "ALWAYS search existing codebase before proposing new components/types",
+      "problem": "Creating duplicate components creates maintenance burden and UI inconsistency",
+      "solution": {
+        "pre_prd_search": [
+          "grep -r \"Alert\" packages/kit/src/views/ --include=\"*.tsx\"",
+          "grep -r \"IAlert\\|Alert\" packages/shared/types/ --include=\"*.ts\"",
+          "If found, read existing implementation"
+        ],
+        "decision_matrix": {
+          "existing_component_matches_ui": "Reuse",
+          "existing_component_needs_small_tweak": "Extend or wrap",
+          "existing_component_has_wrong_responsibilities": "Create new",
+          "not_sure": "Reuse first"
+        }
+      },
+      "impact": {
+        "duplicate_component": "Over-engineering, UI inconsistency",
+        "reuse": "Faster implementation, shared improvements"
+      },
+      "target_skills": ["prd-planner", "architecting-solutions", "api-designer"]
+    },
+    "spacing_and_divider_debugging": {
+      "id": "pat-2025-01-11-010",
+      "name": "Spacing and Divider Debugging",
+      "source": "bug_analysis",
+      "confidence": 0.85,
+      "applications": 0,
+      "created": "2025-01-11",
+      "category": "debugging",
+      "pattern": "When debugging spacing/divider issues, audit all spacing values systematically",
+      "problem": "Component spacing (mt, mb, py, padding) can create unintended visual separators that appear as extra lines",
+      "solution": {
+        "debugging_steps": [
+          "Search for spacing-related props in components",
+          "Check for StyleSheet.hairlineWidth usage (may render differently per platform)",
+          "Compare components that work vs components that have issues",
+          "Draw component structure to identify spacing conflicts"
+        ],
+        "audit_template": "| Element | Before | After | Unit | Notes |\\n|---------|--------|-------|------|-------|\\n| Trigger padding | `py=\"$3\"` | - | 12px | Accordion.Trigger |\\n| Header top margin | `mt=\"$3\"` | `mt=\"$0\"` | 12px → 0px | Remove this |"
+      },
+      "quality_rules": [
+        "Include ASCII diagram showing component structure",
+        "List exact spacing values with pixel conversions ($3 = 12px, $5 = 20px)",
+        "Compare working vs broken components",
+        "Note platform-specific behaviors (hairlineWidth varies)",
+        "Verify fix on all platforms (iOS, Android, Desktop, Web)"
+      ],
+      "target_skills": ["debugger"]
+    }
+  },
+  "meta": {
+    "version": "1.0.0",
+    "last_updated": "2025-01-12",
+    "total_patterns": 10,
+    "categories": ["prd_structure", "prd_quality", "react_patterns", "async_patterns", "ui_patterns", "architecture", "development", "debugging"]
+  }
+}

package/skills/self-improving-agent/references/appendix.md

@@ -0,0 +1,131 @@
+# Appendix
+
+## Self-Validation
+
+### Validation Report Template
+
+```markdown
+## Validation Report Template
+
+**Date**: [YYYY-MM-DD]
+**Scope**: [skill(s) validated]
+
+### Checks
+- [ ] Examples compile or run
+- [ ] Checklists match current repo conventions
+- [ ] External references still valid
+- [ ] No duplicated or conflicting guidance
+
+### Findings
+- [Finding 1]
+- [Finding 2]
+
+### Actions
+- [Action 1]
+- [Action 2]
+```
+
+## Memory File Structure
+
+```
+~/.claude/memory/
+├── semantic/
+│   └── patterns.json
+├── episodic/
+│   ├── 2025/
+│   │   ├── 2025-01-11-prd-creation.json
+│   │   └── 2025-01-11-debug-session.json
+│   └── episodes.json
+├── working/
+│   ├── current_session.json
+│   ├── last_error.json
+│   └── session_end.json
+└── index.json
+```
+
+## Automatic Workflow Integration
+
+```
+Any Skill Run
+  -> workflow-orchestrator
+    -> self-improving-agent (background)
+    -> create-pr (ask_first)
+    -> session-logger (auto)
+```
+
+## Continuous Learning Metrics
+
+```json
+{
+  "metrics": {
+    "patterns_learned": 47,
+    "patterns_applied": 238,
+    "skills_updated": 12,
+    "avg_confidence": 0.87,
+    "user_satisfaction_trend": "improving",
+    "error_rate_reduction": "-35%",
+    "self_corrections": 8
+  }
+}
+```
+
+## Human-in-the-Loop
+
+### Feedback Collection
+
+```markdown
+## Self-Improvement Summary
+
+I've learned from our session and updated:
+
+### Updated Skills
+- `debugger`: Added callback verification pattern
+- `prd-planner`: Enhanced UI/UX specification requirements
+
+### Patterns Extracted
+1. **state_monitoring_over_callbacks**: Use usePrevious for state-driven side effects
+2. **ui_ux_specification_granularity**: Explicit visual specs prevent rework
+
+### Confidence Levels
+- New patterns: 0.85 (needs validation)
+- Reinforced patterns: 0.95 (well-established)
+
+### Your Feedback
+Rate these improvements (1-10):
+- Were the updates helpful?
+- Should I apply this pattern more broadly?
+- Any corrections needed?
+```
+
+### Feedback Integration
+
+```yaml
+User Feedback:
+  positive (rating >= 7):
+    action: Increase pattern confidence
+    scope: Expand to related skills
+
+  neutral (rating 4-6):
+    action: Keep pattern, gather more data
+    scope: Current skill only
+
+  negative (rating <= 3):
+    action: Decrease confidence, revise pattern
+    scope: Remove from active patterns
+```
+
+## Templates
+
+| Template | Purpose |
+|----------|---------|
+| `templates/pattern-template.md` | Adding new patterns |
+| `templates/correction-template.md` | Fixing incorrect guidance |
+| `templates/validation-template.md` | Validating skill accuracy |
+
+## References
+
+- [SimpleMem: Efficient Lifelong Memory for LLM Agents](https://arxiv.org/html/2601.02553v1)
+- [A Survey on the Memory Mechanism of Large Language Model Agents](https://dl.acm.org/doi/10.1145/3748302)
+- [Lifelong Learning of LLM based Agents](https://arxiv.org/html/2501.07278v1)
+- [Evo-Memory: DeepMind's Benchmark](https://shothota.medium.com/evo-memory-deepminds-new-benchmark)
+- [Let's Build a Self-Improving AI Agent](https://medium.com/@nomannayeem/lets-build-a-self-improving-ai-agent-that-learns-from-your-feedback-722d2ce9c2d9)

package/skills/self-improving-agent/templates/correction-template.md

@@ -0,0 +1,11 @@
+# Correction Template
+
+## Issue Summary
+
+## Previous Guidance
+
+## Corrected Guidance
+
+## Root Cause
+
+## Follow-up Actions

package/skills/self-improving-agent/templates/pattern-template.md

@@ -0,0 +1,15 @@
+# Pattern Template
+
+## Pattern Name
+
+## Context
+- Source skill:
+- Situation:
+
+## Guidance
+
+## Examples
+
+## Confidence
+- Initial confidence:
+- Validation notes:

package/skills/self-improving-agent/templates/validation-template.md

@@ -0,0 +1,14 @@
+# Validation Template
+
+## Date
+
+## Scope
+
+## Checks
+- [ ] Examples compile or run
+- [ ] Guidance matches current repo conventions
+- [ ] External references still valid
+
+## Findings
+
+## Actions

package/skills/session-logger/README.md

@@ -0,0 +1,50 @@
+# Session Logger
+
+Automatically saves conversation history to persistent session log files.
+
+## Overview
+
+Session Logger captures your conversations with Claude Code so you can:
+- Reference previous decisions and context
+- Maintain continuity across sessions
+- Learn from past problem-solving approaches
+- Track project evolution
+
+## Installation
+
+```bash
+# Create symbolic link to global skills directory
+ln -s ~/Documents/code/GitHub/agent-playbook/skills/session-logger/SKILL.md ~/.claude/skills/session-logger.md
+```
+
+## Usage
+
+Simply say:
+
+```
+"保存对话信息"
+```
+
+The skill will automatically:
+1. Review the conversation
+2. Extract key information
+3. Create a session log in `sessions/`
+
+## Trigger Phrases
+
+| 中文 | English |
+|------|---------|
+| 保存对话信息 | save session |
+| 保存本次对话 | save conversation |
+| 记录会话内容 | log session |
+| 保存session | save this session |
+
+## Session File Location
+
+```
+sessions/YYYY-MM-DD-{topic}.md
+```
+
+## Privacy
+
+Session logs are in `.gitignore` - they are NOT committed to git.

package/skills/session-logger/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: session-logger
+description: Saves conversation history to session log files. Use when user says "保存对话", "保存对话信息", "记录会话", "save session", or "save conversation". Automatically creates timestamped session log in sessions/ directory.
+allowed-tools: Read, Write, Edit, Bash
+---
+
+# Session Logger
+
+A skill for automatically saving conversation history to persistent session log files.
+
+## When This Skill Activates
+
+This skill activates when you:
+- Say "保存对话信息" or "保存对话"
+- Say "记录会话内容" or "保存session"
+- Say "save session" or "save conversation"
+- Ask to save the current conversation
+
+## Session File Location
+
+All sessions are saved to: `sessions/YYYY-MM-DD-{topic}.md`
+
+## What Gets Logged
+
+For each session, log:
+
+1. **Metadata**
+   - Date and duration
+   - Context/working directory
+   - Main topic
+
+2. **Summary**
+   - What was accomplished
+   - Key decisions made
+   - Files created/modified
+
+3. **Actions Taken**
+   - Checklist of completed tasks
+   - Pending follow-ups
+
+4. **Technical Notes**
+   - Important code snippets
+   - Commands used
+   - Solutions found
+
+5. **Open Questions**
+   - Issues to revisit
+   - Follow-up tasks
+
+## Session Template
+
+```markdown
+# Session: {Topic}
+
+**Date**: {YYYY-MM-DD}
+**Duration**: {approximate}
+**Context**: {project/directory}
+
+## Summary
+
+{What was accomplished in this session}
+
+## Key Decisions
+
+1. {Decision 1}
+2. {Decision 2}
+
+## Actions Taken
+
+- [x] {Completed action 1}
+- [x] {Completed action 2}
+- [ ] {Pending action 3}
+
+## Technical Notes
+
+{Important technical details}
+
+## Open Questions / Follow-ups
+
+- {Question 1}
+- {Question 2}
+
+## Related Files
+
+- `{file-path}` - {what changed}
+```
+
+## How to Use
+
+### Option 1: Automatic Logging
+
+Simply say:
+```
+"保存对话信息"
+```
+
+The skill will:
+1. Review the conversation history
+2. Extract key information
+3. Create/update the session file
+
+### Option 2: With Topic
+
+Specify the session topic:
+```
+"保存对话，主题是 skill-router 创建"
+```
+
+### Option 3: Manual Prompt
+
+If auto-extraction misses something, provide details:
+```
+"保存对话，重点是：1) 创建了 skill-router，2) 修复了 front matter"
+```
+
+## File Naming
+
+| Input | Filename |
+|-------|----------|
+| "保存对话" | `YYYY-MM-DD-session.md` |
+| "保存对话，主题是 prd" | `YYYY-MM-DD-prd.md` |
+| "保存今天的讨论" | `YYYY-MM-DD-discussion.md` |
+
+## Session Log Structure
+
+```
+sessions/
+├── README.md                      # This file
+├── 2025-01-11-skill-router.md     # Session about skill-router
+├── 2025-01-11-prd-planner.md      # Session about PRD planner
+└── 2025-01-12-refactoring.md      # Session about refactoring
+```
+
+## Privacy Note
+
+Session logs are stored in `sessions/` which is in `.gitignore`.
+- Logs are NOT committed to git
+- Logs contain your actual conversation
+- Safe to include sensitive information
+
+## Quick Reference
+
+| You say | Skill does |
+|---------|------------|
+| "保存对话信息" | Creates session log with today's date |
+| "保存今天的对话" | Creates session log |
+| "保存session" | Creates session log |
+| "记录会话" | Creates session log |
+
+## Best Practices
+
+1. **Save at key milestones**: After completing a feature, fixing a bug, etc.
+2. **Be specific with topics**: Helps when searching later
+3. **Include code snippets**: Save important solutions
+4. **Track decisions**: Why did you choose X over Y?
+5. **List pending items**: What to do next time