@codeharbor/agent-playbook 0.1.0 → 0.1.2

package/skills/test-automator/scripts/generate_test.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+# Template generator for test plan.
+
+from pathlib import Path
+import argparse
+import textwrap
+
+
+def write_output(path: Path, content: str, force: bool) -> bool:
+    if path.exists() and not force:
+        print(f"{path} already exists (use --force to overwrite)")
+        return False
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    return True
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate a test plan.")
+    parser.add_argument("--output", default="tests/test-plan.md", help="Output file path")
+    parser.add_argument("--name", default="example", help="Feature or release name")
+    parser.add_argument("--owner", default="team", help="Owning team")
+    parser.add_argument("--force", action="store_true", help="Overwrite existing file")
+    args = parser.parse_args()
+
+    content = textwrap.dedent(
+        f"""\
+        # Test Plan
+
+        ## Scope
+        {args.name}
+
+        ## Ownership
+        - Owner: {args.owner}
+        - QA contact: TBD
+
+        ## Scenarios
+        - Happy path
+        - Error handling
+        - Edge cases
+
+        ## Test Types
+        - Unit
+        - Integration
+        - End-to-end
+
+        ## Environments
+        - Local
+        - Staging
+        - Production
+
+        ## Exit Criteria
+        - Tests passing
+        - Defects triaged
+        """
+    ).strip() + "\n"
+
+    output = Path(args.output)
+    if not write_output(output, content, args.force):
+        return 1
+    print(f"Wrote {output}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/workflow-orchestrator/README.md

@@ -0,0 +1,20 @@
+# Workflow Orchestrator
+
+> A Claude Code skill that coordinates multi-skill workflows using hook definitions.
+
+## Installation
+
+This skill is part of the [agent-playbook](https://github.com/Charon-Fan/agent-playbook) collection.
+
+## Usage
+
+```
+You: Complete workflow
+You: Finish the process and trigger next steps
+```
+
+## How It Works
+
+- Reads hook definitions from `skills/auto-trigger/SKILL.md`
+- Executes follow-up actions based on `auto`, `background`, or `ask_first` modes
+- Logs progress and context to `session-logger`

package/skills/workflow-orchestrator/SKILL.md

@@ -0,0 +1,342 @@
+---
+name: workflow-orchestrator
+description: Automatically coordinates multi-skill workflows and triggers follow-up actions. Use when completing PRD creation, implementation, or any milestone that should trigger additional skills. This skill reads the auto-trigger configuration and executes the workflow chain.
+allowed-tools: Read, Write, Edit, Bash, Grep, AskUserQuestion
+hooks:
+  after_complete:
+    - trigger: session-logger
+      mode: auto
+      reason: "Save workflow execution context"
+---
+
+# Workflow Orchestrator
+
+A skill that automatically coordinates workflows across multiple skills, triggering follow-up actions at appropriate milestones.
+
+## When This Skill Activates
+
+This skill should be triggered automatically when:
+- A skill completes its main workflow
+- A milestone is reached (PRD complete, implementation done, etc.)
+- User says "complete workflow" or "finish the process"
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Workflow Orchestration                   │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  1. Detect Milestone → 2. Read Hooks → 3. Execute Chain    │
+│                                                             │
+│  prd-planner complete                                       │
+│       ↓                                                     │
+│  workflow-orchestrator                                      │
+│       ↓                                                     │
+│  ┌─────────────────────────────────────┐                   │
+│  │ auto-trigger self-improving-agent   │ (background)       │
+│  │ auto-trigger session-logger         │ (auto)            │
+│  └─────────────────────────────────────┘                   │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Trigger Configuration
+
+Read trigger definitions from `skills/auto-trigger/SKILL.md`:
+
+```yaml
+hooks:
+  after_complete:
+    - trigger: self-improving-agent
+      mode: background
+    - trigger: session-logger
+      mode: auto
+  on_error:
+    - trigger: self-improving-agent
+      mode: background
+```
+
+## Execution Modes
+
+| Mode | Behavior | Use When |
+|------|----------|----------|
+| `auto` | Execute immediately, no confirmation | Logging, status updates |
+| `background` | Execute without blocking | Reflection, analysis |
+| `ask_first` | Ask user before executing | PRs, deployments, major changes |
+
+## Milestone Detection
+
+### PRD Complete
+
+```markdown
+Detected when:
+- docs/{scope}-prd.md exists
+- All phases in {scope}-prd-task-plan.md are checked
+- Status shows "COMPLETE"
+
+Actions:
+1. Trigger self-improving-agent (background)
+2. Trigger session-logger (auto)
+```
+
+### Implementation Complete
+
+```markdown
+Detected when:
+- All PRD requirements implemented
+- Tests pass
+- Code committed
+
+Actions:
+1. Trigger code-reviewer (ask_first)
+2. Trigger create-pr if changes staged
+3. Trigger session-logger (auto)
+```
+
+### Self-Improvement Complete
+
+```markdown
+Detected when:
+- Reflection complete
+- Patterns abstracted
+- Skill files modified
+
+Actions:
+1. Trigger create-pr (ask_first)
+2. Trigger session-logger (auto)
+```
+
+### Universal Learning (Any Skill Complete)
+
+```markdown
+Detected when:
+- ANY skill completes its workflow
+- User provides feedback
+- Error or issue encountered
+
+Actions:
+1. Trigger self-improving-agent (background)
+2. Trigger session-logger (auto)
+
+The self-improving-agent:
+- Extracts experience from completed skill
+- Identifies patterns and insights
+- Updates related skills with learned patterns
+- Consolidates memory for future reference
+```
+
+## Error Handling (on_error)
+
+Detected when:
+- A command returns non-zero exit code
+- Tests fail after following skill guidance
+- User reports the guidance produced incorrect results
+
+Actions:
+1. Trigger self-improving-agent (background) for self-correction
+2. Trigger session-logger (auto) to capture error context
+
+## Hook Implementation in Skills
+
+To enable auto-trigger, add this section to any skill's SKILL.md:
+
+```markdown
+## Auto-Trigger (After Completion)
+
+When this skill completes, automatically trigger:
+
+```yaml
+hooks:
+  after_complete:
+    - trigger: skill-name
+      mode: auto|background|ask_first
+      context: "relevant context"
+  on_error:
+    - trigger: self-improving-agent
+      mode: background
+```
+
+### Current Skill Hooks
+
+- **prd-planner**: After PRD complete → self-improving-agent + session-logger
+- **self-improving-agent**: After improvement → create-pr + session-logger
+- **prd-implementation-precheck**: After implementation → self-improving-agent + session-logger
+- **code-reviewer**: After review → self-improving-agent + session-logger
+- **debugger**: After debugging → self-improving-agent + session-logger
+- **create-pr**: After PR created → session-logger
+- **session-logger**: No trigger (terminates chain)
+
+### Universal Learning Pattern
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                  ANY Skill Completes                        │
+└──────────────┬──────────────────────────────────────────────┘
+               │
+               ↓
+    ┌──────────────────────┐
+    │ workflow-orchestrator │
+    └──────────┬───────────┘
+               │
+    ┌──────────┴─────────┐
+    ↓                   ↓
+self-improving-agent  session-logger
+    ↓                   ↓
+Learn from experience  Save context
+    ↓                   ↓
+Update skills         Log session
+    ↓
+create-pr (if modified)
+```
+```
+
+## Workflow Examples
+
+### Example 1: PRD Creation Workflow
+
+```
+User: "Create a PRD for user authentication"
+        ↓
+prd-planner executes
+        ↓
+Phase 6 complete: PRD delivered
+        ↓
+workflow-orchestrator detects milestone
+        ↓
+┌─────────────────────────────────┐
+│ Background: self-improving-agent │ → Learns from PRD patterns
+│ Auto: session-logger             │ → Saves session
+└─────────────────────────────────┘
+```
+
+### Example 2: Full Feature Workflow
+
+```
+User: "Create a PRD and implement it"
+        ↓
+prd-planner → workflow-orchestrator
+        ↓
+self-improving-agent → workflow-orchestrator
+        ↓
+prd-implementation-precheck
+        ↓
+implementation complete → workflow-orchestrator
+        ↓
+code-reviewer → self-improving-agent → workflow-orchestrator
+        ↓
+create-pr → workflow-orchestrator
+        ↓
+session-logger
+```
+
+Each step triggers `self-improving-agent` to learn from the experience.
+
+## Implementation Steps
+
+### Step 1: Detect Milestone
+
+Check for completion indicators:
+
+```bash
+# PRD complete?
+grep -q "COMPLETE" docs/{scope}-prd-task-plan.md
+
+# All phases checked?
+grep -q "^\- \[x\].*Phase 6" docs/{scope}-prd-task-plan.md
+
+# PRD file exists?
+ls docs/{scope}-prd.md
+```
+
+### Step 2: Read Trigger Config
+
+```bash
+# Read hooks from auto-trigger skill
+cat skills/auto-trigger/SKILL.md
+```
+
+### Step 3: Execute Hooks
+
+For each hook in order (before_start, after_complete, on_error):
+1. Check if condition is met
+2. Execute based on mode
+3. Pass context to triggered skill
+4. Wait/continue based on mode
+
+### Step 4: Update Status
+
+Log what was triggered and the result:
+
+```markdown
+## Workflow Execution
+
+- [x] self-improving-agent (background) - Started
+- [x] session-logger (auto) - Session saved
+- [ ] create-pr (ask_first) - Pending user approval
+```
+
+## Skills with Auto-Trigger
+
+| Skill | Triggers After |
+|-------|----------------|
+| `prd-planner` | self-improving-agent, session-logger |
+| `self-improving-agent` | create-pr, session-logger |
+| `prd-implementation-precheck` | code-reviewer, session-logger |
+| `code-reviewer` | self-improving-agent, session-logger |
+| `create-pr` | session-logger |
+| `refactoring-specialist` | self-improving-agent, session-logger |
+| `debugger` | self-improving-agent, session-logger |
+
+## Adding Auto-Trigger to Existing Skills
+
+To add auto-trigger capability to an existing skill, add to the end of its SKILL.md:
+
+```markdown
+---
+
+## Auto-Trigger
+
+When this skill completes, automatically trigger:
+
+```yaml
+hooks:
+  after_complete:
+    - trigger: session-logger
+      mode: auto
+      context: "Save session context"
+```
+```
+
+For more complex triggers, specify mode and context:
+
+```markdown
+## Auto-Trigger
+
+When this skill completes:
+
+```yaml
+hooks:
+  after_complete:
+    - trigger: next-skill
+      mode: background
+      context: "Description"
+    - trigger: session-logger
+      mode: auto
+      context: "Save session"
+    - trigger: create-pr
+      mode: ask_first
+      context: "Create PR if files modified"
+  on_error:
+    - trigger: self-improving-agent
+      mode: background
+```
+```
+
+## Best Practices
+
+1. **Always log to session** - Every workflow should end with session-logger
+2. **Ask before major actions** - PRs, deployments, destructive changes
+3. **Background for analysis** - Reflection, evaluation, optimization
+4. **Auto for status** - Logging, status updates, bookmarks
+5. **Don't create loops** - Ensure chains terminate

package/src/cli.js

@@ -23,13 +23,13 @@ function main(argv, context) {
     case "init":
       return handleInit(options, context);
     case "status":
-      return handleStatus(options);
+      return handleStatus(options, context);
     case "doctor":
-      return handleDoctor(options);
+      return handleDoctor(options, context);
     case "repair":
       return handleRepair({ ...options, repair: true }, context);
     case "uninstall":
-      return handleUninstall(options);
+      return handleUninstall(options, context);
     case "session-log":
       return handleSessionLog(options);
     case "self-improve":
@@ -48,10 +48,10 @@ function printHelp() {
     `${APP_NAME} ${VERSION}`,
     "",
     "Usage:",
-    `  ${APP_NAME} init [--project] [--copy] [--hooks] [--no-hooks] [--session-dir <path>] [--dry-run] [--repo <path>]`,
+    `  ${APP_NAME} init [--project] [--copy] [--overwrite] [--hooks] [--no-hooks] [--session-dir <path>] [--dry-run] [--repo <path>]`,
     `  ${APP_NAME} status [--project] [--repo <path>]`,
     `  ${APP_NAME} doctor [--project] [--repo <path>]`,
-    `  ${APP_NAME} repair [--project] [--repo <path>]`,
+    `  ${APP_NAME} repair [--project] [--overwrite] [--repo <path>]`,
     `  ${APP_NAME} uninstall [--project] [--repo <path>]`,
     "",
     "Hook commands:",
@@ -116,6 +116,7 @@ function handleInit(options, context) {
   const hooksEnabled = options.hooks !== false;
   const repoRoot = settings.repoRoot;
   const warnings = [];
+  const overwriteState = createOverwriteState(options);
 
   if (!settings.skillsSource) {
     if (options.repair) {
@@ -143,8 +144,8 @@ function handleInit(options, context) {
   let claudeLinks = { created: [], skipped: [] };
   let codexLinks = { created: [], skipped: [] };
   if (settings.skillsSource) {
-    claudeLinks = linkSkills(settings.skillsSource, settings.claudeSkillsDir, options);
-    codexLinks = linkSkills(settings.skillsSource, settings.codexSkillsDir, options);
+    claudeLinks = linkSkills(settings.skillsSource, settings.claudeSkillsDir, options, overwriteState);
+    codexLinks = linkSkills(settings.skillsSource, settings.codexSkillsDir, options, overwriteState);
     manifest.links.claude = claudeLinks.created;
     manifest.links.codex = codexLinks.created;
 
@@ -167,15 +168,15 @@ function handleInit(options, context) {
   return Promise.resolve();
 }
 
-function handleStatus(options) {
-  const settings = resolveSettings(options, {});
+function handleStatus(options, context) {
+  const settings = resolveSettings(options, context || {});
   const status = collectStatus(settings);
   printStatus(status);
   return Promise.resolve();
 }
 
-function handleDoctor(options) {
-  const settings = resolveSettings(options, {});
+function handleDoctor(options, context) {
+  const settings = resolveSettings(options, context || {});
   const status = collectStatus(settings);
   const issues = summarizeIssues(status);
 
@@ -191,8 +192,8 @@ function handleDoctor(options) {
   return Promise.resolve();
 }
 
-function handleUninstall(options) {
-  const settings = resolveSettings(options, {});
+function handleUninstall(options, context) {
+  const settings = resolveSettings(options, context || {});
   const manifestPath = path.join(settings.claudeSkillsDir, ".agent-playbook.json");
   const manifest = readJsonSafe(manifestPath);
 
@@ -251,6 +252,7 @@ async function handleSelfImprove(options) {
     session_id: sessionId,
     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 || "",
@@ -267,7 +269,9 @@ async function handleSelfImprove(options) {
 function resolveSettings(options, context) {
   const cwd = process.cwd();
   const repoRoot = options.repo ? path.resolve(options.repo) : findRepoRoot(cwd);
-  const skillsSource = findSkillsSource(repoRoot || cwd);
+  const cliRoot =
+    context && context.cliPath ? path.resolve(path.dirname(context.cliPath), "..") : null;
+  const skillsSource = resolveSkillsSource([repoRoot || cwd, cliRoot]);
   const projectMode = Boolean(options.project);
 
   const envClaudeDir = process.env.AGENT_PLAYBOOK_CLAUDE_DIR;
@@ -324,9 +328,78 @@ function findSkillsSource(startDir) {
   return null;
 }
 
-function linkSkills(sourceDir, targetDir, options) {
+function resolveSkillsSource(candidates) {
+  for (const candidate of candidates) {
+    if (!candidate) {
+      continue;
+    }
+    const found = findSkillsSource(candidate);
+    if (found) {
+      return found;
+    }
+  }
+  return null;
+}
+
+function createOverwriteState(options) {
+  return {
+    decision: options.overwrite === true ? true : null,
+    prompted: false,
+    nonInteractive: false,
+  };
+}
+
+function promptYesNo(question, defaultYes) {
+  const suffix = defaultYes ? "[Y/n]" : "[y/N]";
+  process.stdout.write(`${question} ${suffix} `);
+  const answer = readLineSync().toLowerCase();
+  if (!answer) {
+    return defaultYes;
+  }
+  return answer === "y" || answer === "yes";
+}
+
+function readLineSync() {
+  const buffer = Buffer.alloc(1024);
+  let input = "";
+  while (true) {
+    const bytes = fs.readSync(0, buffer, 0, buffer.length, null);
+    if (bytes <= 0) {
+      break;
+    }
+    input += buffer.toString("utf8", 0, bytes);
+    if (input.includes("\n")) {
+      break;
+    }
+  }
+  return input.trim();
+}
+
+function shouldOverwriteExisting(options, state, targetPath) {
+  if (options.overwrite) {
+    state.decision = true;
+    return true;
+  }
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    state.nonInteractive = true;
+    return false;
+  }
+  if (state.decision !== null) {
+    return state.decision;
+  }
+  state.prompted = true;
+  state.decision = promptYesNo(
+    `Existing skill found at ${targetPath}. Overwrite all existing skills?`,
+    false
+  );
+  return state.decision;
+}
+
+function linkSkills(sourceDir, targetDir, options, overwriteState) {
   const created = [];
   const skipped = [];
+  const overwritten = [];
+  const state = overwriteState || createOverwriteState(options);
   const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
 
   entries.forEach((entry) => {
@@ -349,8 +422,14 @@ function linkSkills(sourceDir, targetDir, options) {
         skipped.push({ source: skillDir, target: targetPath, reason: "already linked" });
         return;
       }
-      skipped.push({ source: skillDir, target: targetPath, reason: "exists" });
-      return;
+      if (!shouldOverwriteExisting(options, state, targetPath)) {
+        skipped.push({ source: skillDir, target: targetPath, reason: "exists" });
+        return;
+      }
+      overwritten.push({ source: skillDir, target: targetPath });
+      if (!options["dry-run"]) {
+        safeUnlink(targetPath);
+      }
     }
 
     if (options["dry-run"]) {
@@ -374,7 +453,7 @@ function linkSkills(sourceDir, targetDir, options) {
     }
   });
 
-  return { created, skipped };
+  return { created, skipped, overwritten };
 }
 
 function ensureLocalCli(settings, context, options) {
@@ -785,6 +864,7 @@ function buildSessionSummary(insights, sessionId, cwd) {
     `**Date**: ${date}`,
     `**Duration**: unknown`,
     `**Context**: ${repoRoot}`,
+    `**Agent Playbook Version**: ${VERSION}`,
     "",
     "## Summary",
     "Auto-generated session log.",
@@ -892,6 +972,12 @@ function printInitSummary(settings, hooksEnabled, options, claudeLinks, codexLin
   console.log(`- Codex skills: ${settings.codexSkillsDir}`);
   console.log(`- Hooks: ${hooksEnabled ? "enabled" : "disabled"}`);
   console.log(`- Linked skills: ${claudeLinks.created.length + codexLinks.created.length}`);
+  const overwrittenCount =
+    (claudeLinks.overwritten ? claudeLinks.overwritten.length : 0) +
+    (codexLinks.overwritten ? codexLinks.overwritten.length : 0);
+  if (overwrittenCount) {
+    console.log(`- Overwritten skills: ${overwrittenCount}`);
+  }
   if (claudeLinks.skipped.length || codexLinks.skipped.length) {
     console.log("- Some skills were skipped due to existing paths.");
   }
@@ -1049,6 +1135,7 @@ function handleRepair(options, context) {
   const settings = resolveSettings(options, context);
   const status = collectStatus(settings);
   const warnings = [];
+  const overwriteState = createOverwriteState(options);
 
   if (!settings.skillsSource) {
     warnings.push("Skills directory not found; skipping skill linking.");
@@ -1079,8 +1166,8 @@ function handleRepair(options, context) {
   }
 
   if (settings.skillsSource) {
-    linkSkills(settings.skillsSource, settings.claudeSkillsDir, options);
-    linkSkills(settings.skillsSource, settings.codexSkillsDir, options);
+    linkSkills(settings.skillsSource, settings.claudeSkillsDir, options, overwriteState);
+    linkSkills(settings.skillsSource, settings.codexSkillsDir, options, overwriteState);
     if (!options["dry-run"]) {
       const manifestPath = path.join(settings.claudeSkillsDir, ".agent-playbook.json");
       if (!fs.existsSync(manifestPath)) {