openclaw-node-harness 2.0.0

package/skills/self-improving-agent/references/openclaw-integration.md

@@ -0,0 +1,248 @@
+# OpenClaw Integration
+
+Complete setup and usage guide for integrating the self-improvement skill with OpenClaw.
+
+## Overview
+
+OpenClaw uses workspace-based prompt injection combined with event-driven hooks. Context is injected from workspace files at session start, and hooks can trigger on lifecycle events.
+
+## Workspace Structure
+
+```
+~/.openclaw/                      
+├── workspace/                   # Working directory
+│   ├── AGENTS.md               # Multi-agent coordination patterns
+│   ├── SOUL.md                 # Behavioral guidelines and personality
+│   ├── TOOLS.md                # Tool capabilities and gotchas
+│   ├── MEMORY.md               # Long-term memory (main session only)
+│   └── memory/                 # Daily memory files
+│       └── YYYY-MM-DD.md
+├── skills/                      # Installed skills
+│   └── <skill-name>/
+│       └── SKILL.md
+└── hooks/                       # Custom hooks
+    └── <hook-name>/
+        ├── HOOK.md
+        └── handler.ts
+```
+
+## Quick Setup
+
+### 1. Install the Skill
+
+```bash
+clawdhub install self-improving-agent
+```
+
+Or copy manually:
+
+```bash
+cp -r self-improving-agent ~/.openclaw/skills/
+```
+
+### 2. Install the Hook (Optional)
+
+Copy the hook to OpenClaw's hooks directory:
+
+```bash
+cp -r hooks/openclaw ~/.openclaw/hooks/self-improvement
+```
+
+Enable the hook:
+
+```bash
+openclaw hooks enable self-improvement
+```
+
+### 3. Create Learning Files
+
+Create the `.learnings/` directory in your workspace:
+
+```bash
+mkdir -p ~/.openclaw/workspace/.learnings
+```
+
+Or in the skill directory:
+
+```bash
+mkdir -p ~/.openclaw/skills/self-improving-agent/.learnings
+```
+
+## Injected Prompt Files
+
+### AGENTS.md
+
+Purpose: Multi-agent workflows and delegation patterns.
+
+```markdown
+# Agent Coordination
+
+## Delegation Rules
+- Use explore agent for open-ended codebase questions
+- Spawn sub-agents for long-running tasks
+- Use sessions_send for cross-session communication
+
+## Session Handoff
+When delegating to another session:
+1. Provide full context in the handoff message
+2. Include relevant file paths
+3. Specify expected output format
+```
+
+### SOUL.md
+
+Purpose: Behavioral guidelines and communication style.
+
+```markdown
+# Behavioral Guidelines
+
+## Communication Style
+- Be direct and concise
+- Avoid unnecessary caveats and disclaimers
+- Use technical language appropriate to context
+
+## Error Handling
+- Admit mistakes promptly
+- Provide corrected information immediately
+- Log significant errors to learnings
+```
+
+### TOOLS.md
+
+Purpose: Tool capabilities, integration gotchas, local configuration.
+
+```markdown
+# Tool Knowledge
+
+## Self-Improvement Skill
+Log learnings to `.learnings/` for continuous improvement.
+
+## Local Tools
+- Document tool-specific gotchas here
+- Note authentication requirements
+- Track integration quirks
+```
+
+## Learning Workflow
+
+### Capturing Learnings
+
+1. **In-session**: Log to `.learnings/` as usual
+2. **Cross-session**: Promote to workspace files
+
+### Promotion Decision Tree
+
+```
+Is the learning project-specific?
+├── Yes → Keep in .learnings/
+└── No → Is it behavioral/style-related?
+    ├── Yes → Promote to SOUL.md
+    └── No → Is it tool-related?
+        ├── Yes → Promote to TOOLS.md
+        └── No → Promote to AGENTS.md (workflow)
+```
+
+### Promotion Format Examples
+
+**From learning:**
+> Git push to GitHub fails without auth configured - triggers desktop prompt
+
+**To TOOLS.md:**
+```markdown
+## Git
+- Don't push without confirming auth is configured
+- Use `gh auth status` to check GitHub CLI auth
+```
+
+## Inter-Agent Communication
+
+OpenClaw provides tools for cross-session communication:
+
+### sessions_list
+
+View active and recent sessions:
+```
+sessions_list(activeMinutes=30, messageLimit=3)
+```
+
+### sessions_history
+
+Read transcript from another session:
+```
+sessions_history(sessionKey="session-id", limit=50)
+```
+
+### sessions_send
+
+Send message to another session:
+```
+sessions_send(sessionKey="session-id", message="Learning: API requires X-Custom-Header")
+```
+
+### sessions_spawn
+
+Spawn a background sub-agent:
+```
+sessions_spawn(task="Research X and report back", label="research")
+```
+
+## Available Hook Events
+
+| Event | When It Fires |
+|-------|---------------|
+| `agent:bootstrap` | Before workspace files inject |
+| `command:new` | When `/new` command issued |
+| `command:reset` | When `/reset` command issued |
+| `command:stop` | When `/stop` command issued |
+| `gateway:startup` | When gateway starts |
+
+## Detection Triggers
+
+### Standard Triggers
+- User corrections ("No, that's wrong...")
+- Command failures (non-zero exit codes)
+- API errors
+- Knowledge gaps
+
+### OpenClaw-Specific Triggers
+
+| Trigger | Action |
+|---------|--------|
+| Tool call error | Log to TOOLS.md with tool name |
+| Session handoff confusion | Log to AGENTS.md with delegation pattern |
+| Model behavior surprise | Log to SOUL.md with expected vs actual |
+| Skill issue | Log to .learnings/ or report upstream |
+
+## Verification
+
+Check hook is registered:
+
+```bash
+openclaw hooks list
+```
+
+Check skill is loaded:
+
+```bash
+openclaw status
+```
+
+## Troubleshooting
+
+### Hook not firing
+
+1. Ensure hooks enabled in config
+2. Restart gateway after config changes
+3. Check gateway logs for errors
+
+### Learnings not persisting
+
+1. Verify `.learnings/` directory exists
+2. Check file permissions
+3. Ensure workspace path is configured correctly
+
+### Skill not loading
+
+1. Check skill is in skills directory
+2. Verify SKILL.md has correct frontmatter
+3. Run `openclaw status` to see loaded skills

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

@@ -0,0 +1,480 @@
+# Self-Improvement Templates & Detailed Examples
+
+Extracted from SKILL.md for reference. See the main SKILL.md for overview and quick reference.
+
+## Logging Format
+
+### Learning Entry
+
+Append to `.learnings/LEARNINGS.md`:
+
+```markdown
+## [LRN-YYYYMMDD-XXX] category
+
+**Logged**: ISO-8601 timestamp
+**Priority**: low | medium | high | critical
+**Status**: pending
+**Area**: frontend | backend | infra | tests | docs | config
+
+### Summary
+One-line description of what was learned
+
+### Details
+Full context: what happened, what was wrong, what's correct
+
+### Suggested Action
+Specific fix or improvement to make
+
+### Metadata
+- Source: conversation | error | user_feedback
+- Related Files: path/to/file.ext
+- Tags: tag1, tag2
+- See Also: LRN-20250110-001 (if related to existing entry)
+
+---
+```
+
+### Error Entry
+
+Append to `.learnings/ERRORS.md`:
+
+```markdown
+## [ERR-YYYYMMDD-XXX] skill_or_command_name
+
+**Logged**: ISO-8601 timestamp
+**Priority**: high
+**Status**: pending
+**Area**: frontend | backend | infra | tests | docs | config
+
+### Summary
+Brief description of what failed
+
+### Error
+```
+Actual error message or output
+```
+
+### Context
+- Command/operation attempted
+- Input or parameters used
+- Environment details if relevant
+
+### Suggested Fix
+If identifiable, what might resolve this
+
+### Metadata
+- Reproducible: yes | no | unknown
+- Related Files: path/to/file.ext
+- See Also: ERR-20250110-001 (if recurring)
+
+---
+```
+
+### Feature Request Entry
+
+Append to `.learnings/FEATURE_REQUESTS.md`:
+
+```markdown
+## [FEAT-YYYYMMDD-XXX] capability_name
+
+**Logged**: ISO-8601 timestamp
+**Priority**: medium
+**Status**: pending
+**Area**: frontend | backend | infra | tests | docs | config
+
+### Requested Capability
+What the user wanted to do
+
+### User Context
+Why they needed it, what problem they're solving
+
+### Complexity Estimate
+simple | medium | complex
+
+### Suggested Implementation
+How this could be built, what it might extend
+
+### Metadata
+- Frequency: first_time | recurring
+- Related Features: existing_feature_name
+
+---
+```
+
+## ID Generation
+
+Format: `TYPE-YYYYMMDD-XXX`
+- TYPE: `LRN` (learning), `ERR` (error), `FEAT` (feature)
+- YYYYMMDD: Current date
+- XXX: Sequential number or random 3 chars (e.g., `001`, `A7B`)
+
+Examples: `LRN-20250115-001`, `ERR-20250115-A3F`, `FEAT-20250115-002`
+
+## Resolving Entries
+
+When an issue is fixed, update the entry:
+
+1. Change `**Status**: pending` to `**Status**: resolved`
+2. Add resolution block after Metadata:
+
+```markdown
+### Resolution
+- **Resolved**: 2025-01-16T09:00:00Z
+- **Commit/PR**: abc123 or #42
+- **Notes**: Brief description of what was done
+```
+
+Other status values:
+- `in_progress` - Actively being worked on
+- `wont_fix` - Decided not to address (add reason in Resolution notes)
+- `promoted` - Elevated to CLAUDE.md, AGENTS.md, or .github/copilot-instructions.md
+
+## Promoting to Project Memory
+
+When a learning is broadly applicable (not a one-off fix), promote it to permanent project memory.
+
+### When to Promote
+
+- Learning applies across multiple files/features
+- Knowledge any contributor (human or AI) should know
+- Prevents recurring mistakes
+- Documents project-specific conventions
+
+### Promotion Targets
+
+| Target | What Belongs There |
+|--------|-------------------|
+| `CLAUDE.md` | Project facts, conventions, gotchas for all Claude interactions |
+| `AGENTS.md` | Agent-specific workflows, tool usage patterns, automation rules |
+| `.github/copilot-instructions.md` | Project context and conventions for GitHub Copilot |
+| `SOUL.md` | Behavioral guidelines, communication style, principles (OpenClaw workspace) |
+| `TOOLS.md` | Tool capabilities, usage patterns, integration gotchas (OpenClaw workspace) |
+
+### How to Promote
+
+1. **Distill** the learning into a concise rule or fact
+2. **Add** to appropriate section in target file (create file if needed)
+3. **Update** original entry:
+   - Change `**Status**: pending` to `**Status**: promoted`
+   - Add `**Promoted**: CLAUDE.md`, `AGENTS.md`, or `.github/copilot-instructions.md`
+
+### Promotion Examples
+
+**Learning** (verbose):
+> Project uses pnpm workspaces. Attempted `npm install` but failed.
+> Lock file is `pnpm-lock.yaml`. Must use `pnpm install`.
+
+**In CLAUDE.md** (concise):
+```markdown
+## Build & Dependencies
+- Package manager: pnpm (not npm) - use `pnpm install`
+```
+
+**Learning** (verbose):
+> When modifying API endpoints, must regenerate TypeScript client.
+> Forgetting this causes type mismatches at runtime.
+
+**In AGENTS.md** (actionable):
+```markdown
+## After API Changes
+1. Regenerate client: `pnpm run generate:api`
+2. Check for type errors: `pnpm tsc --noEmit`
+```
+
+## Recurring Pattern Detection
+
+If logging something similar to an existing entry:
+
+1. **Search first**: `grep -r "keyword" .learnings/`
+2. **Link entries**: Add `**See Also**: ERR-20250110-001` in Metadata
+3. **Bump priority** if issue keeps recurring
+4. **Consider systemic fix**: Recurring issues often indicate:
+   - Missing documentation (promote to CLAUDE.md or .github/copilot-instructions.md)
+   - Missing automation (add to AGENTS.md)
+   - Architectural problem (create tech debt ticket)
+
+## Periodic Review
+
+Review `.learnings/` at natural breakpoints:
+
+### When to Review
+- Before starting a new major task
+- After completing a feature
+- When working in an area with past learnings
+- Weekly during active development
+
+### Quick Status Check
+```bash
+# Count pending items
+grep -h "Status\*\*: pending" .learnings/*.md | wc -l
+
+# List pending high-priority items
+grep -B5 "Priority\*\*: high" .learnings/*.md | grep "^## \["
+
+# Find learnings for a specific area
+grep -l "Area\*\*: backend" .learnings/*.md
+```
+
+### Review Actions
+- Resolve fixed items
+- Promote applicable learnings
+- Link related entries
+- Escalate recurring issues
+
+## Detection Triggers
+
+Automatically log when you notice:
+
+**Corrections** (learning with `correction` category):
+- "No, that's not right..."
+- "Actually, it should be..."
+- "You're wrong about..."
+- "That's outdated..."
+
+**Feature Requests** (feature request):
+- "Can you also..."
+- "I wish you could..."
+- "Is there a way to..."
+- "Why can't you..."
+
+**Knowledge Gaps** (learning with `knowledge_gap` category):
+- User provides information you didn't know
+- Documentation you referenced is outdated
+- API behavior differs from your understanding
+
+**Errors** (error entry):
+- Command returns non-zero exit code
+- Exception or stack trace
+- Unexpected output or behavior
+- Timeout or connection failure
+
+## Priority Guidelines
+
+| Priority | When to Use |
+|----------|-------------|
+| `critical` | Blocks core functionality, data loss risk, security issue |
+| `high` | Significant impact, affects common workflows, recurring issue |
+| `medium` | Moderate impact, workaround exists |
+| `low` | Minor inconvenience, edge case, nice-to-have |
+
+## Area Tags
+
+Use to filter learnings by codebase region:
+
+| Area | Scope |
+|------|-------|
+| `frontend` | UI, components, client-side code |
+| `backend` | API, services, server-side code |
+| `infra` | CI/CD, deployment, Docker, cloud |
+| `tests` | Test files, testing utilities, coverage |
+| `docs` | Documentation, comments, READMEs |
+| `config` | Configuration files, environment, settings |
+
+## Best Practices
+
+1. **Log immediately** - context is freshest right after the issue
+2. **Be specific** - future agents need to understand quickly
+3. **Include reproduction steps** - especially for errors
+4. **Link related files** - makes fixes easier
+5. **Suggest concrete fixes** - not just "investigate"
+6. **Use consistent categories** - enables filtering
+7. **Promote aggressively** - if in doubt, add to CLAUDE.md or .github/copilot-instructions.md
+8. **Review regularly** - stale learnings lose value
+
+## Gitignore Options
+
+**Keep learnings local** (per-developer):
+```gitignore
+.learnings/
+```
+
+**Track learnings in repo** (team-wide):
+Don't add to .gitignore - learnings become shared knowledge.
+
+**Hybrid** (track templates, ignore entries):
+```gitignore
+.learnings/*.md
+!.learnings/.gitkeep
+```
+
+## Hook Integration
+
+Enable automatic reminders through agent hooks. This is **opt-in** - you must explicitly configure hooks.
+
+### Quick Setup (Claude Code / Codex)
+
+Create `.claude/settings.json` in your project:
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [{
+      "matcher": "",
+      "hooks": [{
+        "type": "command",
+        "command": "./skills/self-improvement/scripts/activator.sh"
+      }]
+    }]
+  }
+}
+```
+
+This injects a learning evaluation reminder after each prompt (~50-100 tokens overhead).
+
+### Full Setup (With Error Detection)
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [{
+      "matcher": "",
+      "hooks": [{
+        "type": "command",
+        "command": "./skills/self-improvement/scripts/activator.sh"
+      }]
+    }],
+    "PostToolUse": [{
+      "matcher": "Bash",
+      "hooks": [{
+        "type": "command",
+        "command": "./skills/self-improvement/scripts/error-detector.sh"
+      }]
+    }]
+  }
+}
+```
+
+### Available Hook Scripts
+
+| Script | Hook Type | Purpose |
+|--------|-----------|---------|
+| `scripts/activator.sh` | UserPromptSubmit | Reminds to evaluate learnings after tasks |
+| `scripts/error-detector.sh` | PostToolUse (Bash) | Triggers on command errors |
+
+See `references/hooks-setup.md` for detailed configuration and troubleshooting.
+
+## Automatic Skill Extraction
+
+When a learning is valuable enough to become a reusable skill, extract it using the provided helper.
+
+### Skill Extraction Criteria
+
+A learning qualifies for skill extraction when ANY of these apply:
+
+| Criterion | Description |
+|-----------|-------------|
+| **Recurring** | Has `See Also` links to 2+ similar issues |
+| **Verified** | Status is `resolved` with working fix |
+| **Non-obvious** | Required actual debugging/investigation to discover |
+| **Broadly applicable** | Not project-specific; useful across codebases |
+| **User-flagged** | User says "save this as a skill" or similar |
+
+### Extraction Workflow
+
+1. **Identify candidate**: Learning meets extraction criteria
+2. **Run helper** (or create manually):
+   ```bash
+   ./skills/self-improvement/scripts/extract-skill.sh skill-name --dry-run
+   ./skills/self-improvement/scripts/extract-skill.sh skill-name
+   ```
+3. **Customize SKILL.md**: Fill in template with learning content
+4. **Update learning**: Set status to `promoted_to_skill`, add `Skill-Path`
+5. **Verify**: Read skill in fresh session to ensure it's self-contained
+
+### Manual Extraction
+
+If you prefer manual creation:
+
+1. Create `skills/<skill-name>/SKILL.md`
+2. Use template from `assets/SKILL-TEMPLATE.md`
+3. Follow [Agent Skills spec](https://agentskills.io/specification):
+   - YAML frontmatter with `name` and `description`
+   - Name must match folder name
+   - No README.md inside skill folder
+
+### Extraction Detection Triggers
+
+Watch for these signals that a learning should become a skill:
+
+**In conversation:**
+- "Save this as a skill"
+- "I keep running into this"
+- "This would be useful for other projects"
+- "Remember this pattern"
+
+**In learning entries:**
+- Multiple `See Also` links (recurring issue)
+- High priority + resolved status
+- Category: `best_practice` with broad applicability
+- User feedback praising the solution
+
+### Skill Quality Gates
+
+Before extraction, verify:
+
+- [ ] Solution is tested and working
+- [ ] Description is clear without original context
+- [ ] Code examples are self-contained
+- [ ] No project-specific hardcoded values
+- [ ] Follows skill naming conventions (lowercase, hyphens)
+
+## Multi-Agent Support
+
+This skill works across different AI coding agents with agent-specific activation.
+
+### Claude Code
+
+**Activation**: Hooks (UserPromptSubmit, PostToolUse)
+**Setup**: `.claude/settings.json` with hook configuration
+**Detection**: Automatic via hook scripts
+
+### Codex CLI
+
+**Activation**: Hooks (same pattern as Claude Code)
+**Setup**: `.codex/settings.json` with hook configuration
+**Detection**: Automatic via hook scripts
+
+### GitHub Copilot
+
+**Activation**: Manual (no hook support)
+**Setup**: Add to `.github/copilot-instructions.md`:
+
+```markdown
+## Self-Improvement
+
+After solving non-obvious issues, consider logging to `.learnings/`:
+1. Use format from self-improvement skill
+2. Link related entries with See Also
+3. Promote high-value learnings to skills
+
+Ask in chat: "Should I log this as a learning?"
+```
+
+**Detection**: Manual review at session end
+
+### OpenClaw
+
+**Activation**: Workspace injection + inter-agent messaging
+**Setup**: See "OpenClaw Setup" section in SKILL.md
+**Detection**: Via session tools and workspace files
+
+### Agent-Agnostic Guidance
+
+Regardless of agent, apply self-improvement when you:
+
+1. **Discover something non-obvious** - solution wasn't immediate
+2. **Correct yourself** - initial approach was wrong
+3. **Learn project conventions** - discovered undocumented patterns
+4. **Hit unexpected errors** - especially if diagnosis was difficult
+5. **Find better approaches** - improved on your original solution
+
+### Copilot Chat Integration
+
+For Copilot users, add this to your prompts when relevant:
+
+> After completing this task, evaluate if any learnings should be logged to `.learnings/` using the self-improvement skill format.
+
+Or use quick prompts:
+- "Log this to learnings"
+- "Create a skill from this solution"
+- "Check .learnings/ for related issues"