@codeharbor/agent-playbook 0.2.2 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codeharbor/agent-playbook",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Local skill manager and installer for agent-playbook across Claude Code, Codex, and Gemini.",
   "license": "MIT",
   "type": "commonjs",

package/skills/api-designer/SKILL.md

@@ -2,6 +2,15 @@
 name: api-designer
 description: REST and GraphQL API architect for designing robust, scalable APIs. Use when designing new APIs or improving existing ones.
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch
+metadata:
+  hooks:
+    after_complete:
+      - trigger: self-improving-agent
+        mode: background
+        reason: "Learn from API design patterns"
+      - trigger: session-logger
+        mode: auto
+        reason: "Log API design activity"
 ---
 
 # API Designer

package/skills/api-documenter/SKILL.md

@@ -2,6 +2,12 @@
 name: api-documenter
 description: API documentation specialist for OpenAPI/Swagger specifications. Use when documenting REST or GraphQL APIs.
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+metadata:
+  hooks:
+    after_complete:
+      - trigger: session-logger
+        mode: auto
+        reason: "Log documentation activity"
 ---
 
 # API Documenter

package/skills/architecting-solutions/SKILL.md

@@ -2,6 +2,15 @@
 name: architecting-solutions
 description: Designs technical solutions and architecture. Use when user says "design solution", "architecture design", "technical design", or "方案设计" WITHOUT mentioning PRD. For PRD-specific work, use prd-planner skill instead.
 allowed-tools: Read, Write, Edit, Bash, AskUserQuestion, WebSearch, Grep, Glob
+metadata:
+  hooks:
+    after_complete:
+      - trigger: self-improving-agent
+        mode: background
+        reason: "Learn from architecture patterns"
+      - trigger: session-logger
+        mode: auto
+        reason: "Log architecture design"
 ---
 
 # Architecting Solutions

package/skills/code-reviewer/SKILL.md

@@ -2,6 +2,15 @@
 name: code-reviewer
 description: Reviews pull requests and code changes for quality, security, and best practices. Use when user asks for code review, PR review, or mentions reviewing changes.
 allowed-tools: Read, Grep, Glob, Bash, WebFetch, WebSearch
+metadata:
+  hooks:
+    after_complete:
+      - trigger: self-improving-agent
+        mode: background
+        reason: "Learn from review patterns"
+      - trigger: session-logger
+        mode: auto
+        reason: "Log review activity"
 ---
 
 # Code Reviewer

package/skills/commit-helper/SKILL.md

@@ -2,6 +2,12 @@
 name: commit-helper
 description: Helps write Git commit messages following the Conventional Commits specification. Use this skill when the user asks to commit changes, write commit messages, format commits, or mentions git commits.
 allowed-tools: Read, Write, Edit, Bash, Grep
+metadata:
+  hooks:
+    after_complete:
+      - trigger: session-logger
+        mode: auto
+        reason: "Log commit activity"
 ---
 
 # Commit Message Helper

package/skills/create-pr/SKILL.md

@@ -2,6 +2,12 @@
 name: create-pr
 description: Creates pull requests with bilingual documentation updates. Use when user asks to create PR, make a pull request, or submit changes for review. Automatically updates both English and Chinese README files.
 allowed-tools: Read, Write, Edit, Bash, Grep, AskUserQuestion
+metadata:
+  hooks:
+    after_complete:
+      - trigger: session-logger
+        mode: auto
+        reason: "Log PR creation"
 ---
 
 # Create PR

package/skills/debugger/SKILL.md

@@ -2,6 +2,15 @@
 name: debugger
 description: Advanced debugging specialist for diagnosing and resolving code issues. Use when user encounters bugs, errors, unexpected behavior, or mentions debugging.
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+metadata:
+  hooks:
+    after_complete:
+      - trigger: self-improving-agent
+        mode: background
+        reason: "Learn from debugging patterns"
+      - trigger: session-logger
+        mode: auto
+        reason: "Log debugging session"
 ---
 
 # Debugger

package/skills/deployment-engineer/SKILL.md

@@ -2,6 +2,12 @@
 name: deployment-engineer
 description: Deployment automation specialist for CI/CD pipelines and infrastructure. Use when setting up deployment, configuring CI/CD, or managing releases.
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+metadata:
+  hooks:
+    after_complete:
+      - trigger: session-logger
+        mode: auto
+        reason: "Log deployment activity"
 ---
 
 # Deployment Engineer

package/skills/documentation-engineer/SKILL.md

@@ -2,6 +2,12 @@
 name: documentation-engineer
 description: Technical documentation expert for creating clear, comprehensive documentation. Use when user asks to write docs, create README, or document code.
 allowed-tools: Read, Write, Edit, Grep, Glob, WebFetch, WebSearch
+metadata:
+  hooks:
+    after_complete:
+      - trigger: session-logger
+        mode: auto
+        reason: "Log documentation activity"
 ---
 
 # Documentation Engineer

package/skills/performance-engineer/SKILL.md

@@ -2,6 +2,15 @@
 name: performance-engineer
 description: Performance optimization specialist for improving application speed and efficiency. Use when investigating performance issues or optimizing code.
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+metadata:
+  hooks:
+    after_complete:
+      - trigger: self-improving-agent
+        mode: background
+        reason: "Learn from performance patterns"
+      - trigger: session-logger
+        mode: auto
+        reason: "Log performance optimization"
 ---
 
 # Performance Engineer

package/skills/planning-with-files/SKILL.md

@@ -2,6 +2,12 @@
 name: planning-with-files
 description: Uses persistent markdown files for general planning, progress tracking, and knowledge storage (Manus-style workflow). Use for multi-step tasks, research projects, or general organization WITHOUT mentioning PRD. For PRD-specific work, use prd-planner skill instead.
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+metadata:
+  hooks:
+    after_complete:
+      - trigger: session-logger
+        mode: auto
+        reason: "Log planning activity"
 ---
 
 # Planning with Files

package/skills/prd-implementation-precheck/SKILL.md

@@ -1,6 +1,16 @@
 ---
 name: prd-implementation-precheck
 description: Implement PRDs/specs with a mandatory precheck review before coding. Use when a user asks to implement a PRD/feature spec/requirements doc or says "implement PRD/spec". Perform a preflight review, raise questions on scope/consistency/risks, then implement after confirmation.
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion
+metadata:
+  hooks:
+    after_complete:
+      - trigger: self-improving-agent
+        mode: background
+        reason: "Learn from implementation patterns"
+      - trigger: session-logger
+        mode: auto
+        reason: "Log PRD implementation activity"
 ---
 
 # PRD Implementation Precheck

package/skills/qa-expert/SKILL.md

@@ -2,6 +2,12 @@
 name: qa-expert
 description: Quality assurance expert for testing strategies and quality gates. Use when planning test coverage, setting up QA processes, or improving quality standards.
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch
+metadata:
+  hooks:
+    after_complete:
+      - trigger: session-logger
+        mode: auto
+        reason: "Log QA activity"
 ---
 
 # QA Expert

package/skills/refactoring-specialist/SKILL.md

@@ -2,6 +2,15 @@
 name: refactoring-specialist
 description: Code refactoring expert for improving code structure, readability, and maintainability. Use when user asks to refactor, clean up, or improve code quality.
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+metadata:
+  hooks:
+    after_complete:
+      - trigger: self-improving-agent
+        mode: background
+        reason: "Learn from refactoring patterns"
+      - trigger: session-logger
+        mode: auto
+        reason: "Log refactoring activity"
 ---
 
 # Refactoring Specialist

package/skills/security-auditor/SKILL.md

@@ -2,6 +2,15 @@
 name: security-auditor
 description: Security vulnerability expert covering OWASP Top 10 and common security issues. Use when conducting security audits or reviewing code for vulnerabilities.
 allowed-tools: Read, Grep, Glob, Bash, WebSearch
+metadata:
+  hooks:
+    after_complete:
+      - trigger: self-improving-agent
+        mode: background
+        reason: "Learn from security patterns"
+      - trigger: session-logger
+        mode: auto
+        reason: "Log security audit"
 ---
 
 # Security Auditor

package/skills/session-logger/SKILL.md

@@ -154,3 +154,123 @@ Session logs are stored in `sessions/` which is in `.gitignore`.
 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
+
+## Rich Content Extraction (for Self-Improving Agent)
+
+When triggered by other skills via hooks, session-logger extracts structured data for learning:
+
+### Skill Context Capture
+
+When a skill completes, capture:
+
+```markdown
+## Skill Execution Context
+
+**Skill**: {skill-name}
+**Trigger**: {user-invoked | hook-triggered | auto-triggered}
+**Status**: {completed | error | partial}
+**Duration**: {approximate time}
+
+### Input Context
+- User request: {original request}
+- Files involved: {list of files}
+- Codebase patterns detected: {patterns}
+
+### Output Summary
+- Actions taken: {list}
+- Files modified: {list with changes}
+- Decisions made: {key decisions}
+
+### Learning Signals
+- What worked well: {successes}
+- What could improve: {areas for improvement}
+- Patterns discovered: {new patterns}
+- Errors encountered: {errors and resolutions}
+```
+
+### Error Context Capture
+
+When a skill encounters errors:
+
+```markdown
+## Error Context
+
+**Error Type**: {type}
+**Error Message**: {message}
+**Stack Trace**: {if available}
+
+### Resolution Attempted
+- Approach: {what was tried}
+- Result: {success/failure}
+- Root cause: {if identified}
+
+### Prevention Notes
+- How to avoid: {prevention strategy}
+- Related patterns: {similar issues}
+```
+
+### Pattern Extraction
+
+Extract reusable patterns for the self-improving-agent:
+
+```markdown
+## Extracted Patterns
+
+### Code Patterns
+- Pattern name: {name}
+- Context: {when to use}
+- Example: {code snippet}
+
+### Workflow Patterns
+- Trigger: {what initiates}
+- Steps: {sequence}
+- Outcome: {expected result}
+
+### Anti-Patterns
+- Pattern: {what to avoid}
+- Why: {reason}
+- Alternative: {better approach}
+```
+
+### Structured Data Format
+
+For machine-readable extraction, use YAML front matter in session logs:
+
+```yaml
+---
+session_type: skill_execution
+skill_name: code-reviewer
+trigger_source: hook
+status: completed
+files_modified:
+  - path: src/utils.ts
+    changes: refactored error handling
+patterns_learned:
+  - name: error-boundary-pattern
+    category: error-handling
+    confidence: high
+errors_encountered: []
+learning_signals:
+  successes:
+    - "Identified code smell in utils.ts"
+  improvements:
+    - "Could have suggested more specific refactoring"
+---
+```
+
+### Integration with Self-Improving Agent
+
+When triggered by `self-improving-agent`:
+
+1. **Extract episodic memory**: Capture the full context of what happened
+2. **Identify semantic patterns**: Tag reusable knowledge
+3. **Update working memory**: Note immediate follow-ups needed
+4. **Signal completion**: Write trigger file if skill chaining is needed
+
+### Auto-Trigger Behavior
+
+When invoked via hooks with `mode: auto`:
+- Silently create/update session log
+- Extract structured data without user interaction
+- Append to existing session if same day/topic
+- Create new session if context differs significantly

package/skills/skill-router/SKILL.md

@@ -2,6 +2,12 @@
 name: skill-router
 description: Intelligently routes user requests to the most appropriate Claude Code skill. ALWAYS use this skill FIRST when user asks for help, mentions "skill", "which", "how to", or seems unsure about which approach to take. This is the default entry point for all skill-related requests.
 allowed-tools: Read, AskUserQuestion, WebSearch, Grep
+metadata:
+  hooks:
+    after_complete:
+      - trigger: session-logger
+        mode: auto
+        reason: "Log skill routing decisions"
 ---
 
 # Skill Router

package/skills/test-automator/SKILL.md

@@ -2,6 +2,12 @@
 name: test-automator
 description: Test automation framework expert for creating and maintaining automated tests. Use when user asks to write tests, automate testing, or improve test coverage.
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+metadata:
+  hooks:
+    after_complete:
+      - trigger: session-logger
+        mode: auto
+        reason: "Log test creation"
 ---
 
 # Test Automator

package/src/cli.js

@@ -264,9 +264,16 @@ async function handleSelfImprove(options) {
   const memoryRoot = path.join(os.homedir(), ".claude", "memory");
   const episodicDir = path.join(memoryRoot, "episodic", String(now.getFullYear()));
   const workingDir = path.join(memoryRoot, "working");
+  const triggersDir = path.join(memoryRoot, "triggers");
 
   ensureDir(episodicDir, false);
   ensureDir(workingDir, false);
+  ensureDir(triggersDir, false);
+
+  const toolName = input.tool_name || "";
+  const toolInput = input.tool_input || {};
+  const toolOutput = input.tool_output || {};
+  const hookEvent = input.hook_event_name || "PostToolUse";
 
   const entry = {
     id: `ep-${now.toISOString()}`.replace(/[:.]/g, "-"),
@@ -275,11 +282,57 @@ async function handleSelfImprove(options) {
     cwd,
     transcript_path: transcriptPath,
     agent_playbook_version: VERSION,
-    hook_event: input.hook_event_name || "PostToolUse",
-    tool_name: input.tool_name || "",
-    tool_input: input.tool_input || "",
+    hook_event: hookEvent,
+    tool_name: toolName,
+    tool_input: toolInput,
+    tool_output: typeof toolOutput === "string" ? toolOutput.slice(0, 2000) : toolOutput,
   };
 
+  // Detect skill invocations and completions
+  if (toolName === "Skill") {
+    const skillName = toolInput.skill || "";
+    entry.skill_invoked = skillName;
+    entry.skill_args = toolInput.args || "";
+
+    // Track skill start in working memory
+    const skillStatePath = path.join(workingDir, "active_skills.json");
+    const skillState = readJsonSafe(skillStatePath) || { active: [], history: [] };
+
+    if (!skillState.active.includes(skillName)) {
+      skillState.active.push(skillName);
+      skillState.history.push({
+        skill: skillName,
+        started_at: now.toISOString(),
+        session_id: sessionId,
+      });
+      writeJson(skillStatePath, skillState);
+    }
+  }
+
+  // Detect skill completion patterns in tool output
+  const skillCompletion = detectSkillCompletion(toolName, toolInput, toolOutput, cwd);
+  if (skillCompletion) {
+    entry.skill_completed = skillCompletion.skill;
+    entry.completion_type = skillCompletion.type;
+
+    // Update active skills state
+    const skillStatePath = path.join(workingDir, "active_skills.json");
+    const skillState = readJsonSafe(skillStatePath) || { active: [], history: [] };
+    skillState.active = skillState.active.filter((s) => s !== skillCompletion.skill);
+
+    const historyEntry = skillState.history.find(
+      (h) => h.skill === skillCompletion.skill && !h.completed_at
+    );
+    if (historyEntry) {
+      historyEntry.completed_at = now.toISOString();
+      historyEntry.completion_type = skillCompletion.type;
+    }
+    writeJson(skillStatePath, skillState);
+
+    // Create trigger file for skill chaining
+    createSkillTrigger(triggersDir, skillCompletion, sessionId, cwd, now);
+  }
+
   const entryPath = path.join(episodicDir, `${entry.id}.json`);
   fs.writeFileSync(entryPath, JSON.stringify(entry, null, 2));
 
@@ -288,6 +341,145 @@ async function handleSelfImprove(options) {
   console.error(`Self-improvement entry saved to ${entryPath}`);
 }
 
+function detectSkillCompletion(toolName, toolInput, toolOutput, cwd) {
+  const outputStr = typeof toolOutput === "string" ? toolOutput : JSON.stringify(toolOutput);
+
+  // Detect PRD completion
+  if (toolName === "Write" || toolName === "Edit") {
+    const filePath = toolInput.file_path || "";
+    if (filePath.includes("-prd.md") || filePath.includes("prd-task-plan.md")) {
+      if (outputStr.includes("COMPLETE") || outputStr.includes("Phase 6")) {
+        return { skill: "prd-planner", type: "prd_complete", file: filePath };
+      }
+    }
+  }
+
+  // Detect commit completion (commit-helper)
+  if (toolName === "Bash") {
+    const command = toolInput.command || "";
+    if (command.includes("git commit") && !outputStr.includes("error") && !outputStr.includes("fatal")) {
+      return { skill: "commit-helper", type: "commit_complete", command };
+    }
+  }
+
+  // Detect PR creation (create-pr)
+  if (toolName === "Bash") {
+    const command = toolInput.command || "";
+    if (command.includes("gh pr create") && outputStr.includes("github.com")) {
+      const prUrlMatch = outputStr.match(/https:\/\/github\.com\/[^\s]+\/pull\/\d+/);
+      return {
+        skill: "create-pr",
+        type: "pr_created",
+        pr_url: prUrlMatch ? prUrlMatch[0] : null,
+      };
+    }
+  }
+
+  // Detect test completion
+  if (toolName === "Bash") {
+    const command = toolInput.command || "";
+    if (
+      (command.includes("npm test") ||
+        command.includes("bun test") ||
+        command.includes("pytest") ||
+        command.includes("go test")) &&
+      (outputStr.includes("passed") || outputStr.includes("PASS"))
+    ) {
+      return { skill: "test-automator", type: "tests_passed", command };
+    }
+  }
+
+  // Detect session log creation
+  if (toolName === "Write") {
+    const filePath = toolInput.file_path || "";
+    if (filePath.includes("sessions/") && filePath.endsWith(".md")) {
+      return { skill: "session-logger", type: "session_saved", file: filePath };
+    }
+  }
+
+  return null;
+}
+
+function createSkillTrigger(triggersDir, completion, sessionId, cwd, now) {
+  const triggerFile = path.join(
+    triggersDir,
+    `${completion.skill}-${now.toISOString().replace(/[:.]/g, "-")}.json`
+  );
+
+  const trigger = {
+    source_skill: completion.skill,
+    completion_type: completion.type,
+    timestamp: now.toISOString(),
+    session_id: sessionId,
+    cwd,
+    details: completion,
+    pending_triggers: getHooksForSkill(completion.skill, completion.type),
+  };
+
+  writeJson(triggerFile, trigger);
+  console.error(`Skill trigger created: ${completion.skill} -> ${trigger.pending_triggers.map((t) => t.trigger).join(", ") || "none"}`);
+}
+
+function getHooksForSkill(skillName, completionType) {
+  // Define hooks based on skill completion
+  const hookDefinitions = {
+    "prd-planner": {
+      after_complete: [
+        { trigger: "self-improving-agent", mode: "background" },
+        { trigger: "session-logger", mode: "auto" },
+      ],
+    },
+    "prd-implementation-precheck": {
+      after_complete: [
+        { trigger: "code-reviewer", mode: "ask_first" },
+        { trigger: "self-improving-agent", mode: "background" },
+        { trigger: "session-logger", mode: "auto" },
+      ],
+    },
+    "commit-helper": {
+      after_complete: [{ trigger: "session-logger", mode: "auto" }],
+    },
+    "create-pr": {
+      after_complete: [{ trigger: "session-logger", mode: "auto" }],
+    },
+    "code-reviewer": {
+      after_complete: [
+        { trigger: "self-improving-agent", mode: "background" },
+        { trigger: "session-logger", mode: "auto" },
+      ],
+    },
+    "debugger": {
+      after_complete: [
+        { trigger: "self-improving-agent", mode: "background" },
+        { trigger: "session-logger", mode: "auto" },
+      ],
+    },
+    "refactoring-specialist": {
+      after_complete: [
+        { trigger: "self-improving-agent", mode: "background" },
+        { trigger: "session-logger", mode: "auto" },
+      ],
+    },
+    "test-automator": {
+      after_complete: [{ trigger: "session-logger", mode: "auto" }],
+    },
+    "self-improving-agent": {
+      after_complete: [
+        { trigger: "create-pr", mode: "ask_first", condition: "skills_modified" },
+        { trigger: "session-logger", mode: "auto" },
+      ],
+    },
+  };
+
+  const hooks = hookDefinitions[skillName];
+  if (!hooks) {
+    return [];
+  }
+
+  // Return after_complete hooks by default
+  return hooks.after_complete || [];
+}
+
 function handleSkills(options, positionals, context) {
   const settings = resolveSettings(options, context || {});
   const subcommand = positionals[0] || "list";