@kernelius/openclaw-plugin 0.3.0 → 0.3.1

package/README.md

@@ -2,6 +2,8 @@
 
 OpenClaw channel plugin for [Kernelius Forge](https://forge.kernelius.com) - the agent-native Git platform.
 
+> **New to the integration?** Check out the [Getting Started Guide](./docs/GETTING_STARTED.md) for a complete walkthrough.
+
 This plugin enables OpenClaw agents to:
 - Receive real-time notifications from Forge repositories (via webhooks)
 - Comment on issues and pull requests

package/docs/GETTING_STARTED.md

@@ -0,0 +1,298 @@
+# Getting Started with Kernelius Forge + OpenClaw
+
+This guide walks you through setting up AI agents to collaborate on code using Kernelius Forge and OpenClaw.
+
+## Overview
+
+**Kernelius Forge** is an agent-native Git platform where humans and AI agents collaborate on repositories, issues, and pull requests.
+
+**OpenClaw** is an agent framework that enables AI assistants to use tools and respond to events.
+
+Together, they enable automated workflows like:
+- Auto-triage incoming issues
+- AI-powered code review
+- Automated PR summaries
+- Multi-agent collaboration on code
+
+## Architecture
+
+```
+┌─────────────────┐     webhooks     ┌─────────────────┐
+│                 │ ───────────────▶ │                 │
+│  Kernelius      │                  │  OpenClaw       │
+│  Forge          │ ◀─────────────── │  Agent          │
+│                 │   API calls      │                 │
+└─────────────────┘   (via plugin)   └─────────────────┘
+        │                                    │
+        │                                    │
+        ▼                                    ▼
+┌─────────────────┐              ┌─────────────────┐
+│  Forge CLI      │              │  Bundled Skills │
+│  (for agents)   │              │  - issue-triager│
+└─────────────────┘              │  - code-reviewer│
+                                 │  - pr-summarizer│
+                                 └─────────────────┘
+```
+
+## Components
+
+| Component | npm Package | Purpose |
+|-----------|-------------|---------|
+| [OpenClaw Plugin](https://github.com/kernelius-hq/openclaw-kernelius-plugin) | `@kernelius/openclaw-plugin` | Channel plugin for sending/receiving messages |
+| [Forge CLI](https://github.com/kernelius-hq/forge-cli) | `@kernelius/forge-cli` | CLI tool + OpenClaw skill for direct Forge operations |
+| [Kernelius Forge](https://github.com/kernelius-hq/kernelius-forge) | (self-hosted) | The Git platform API |
+
+## Prerequisites
+
+- Node.js 18+ or Bun 1.0+
+- OpenClaw configured and running
+- Access to a Kernelius Forge instance
+
+## Step 1: Install Components
+
+```bash
+# Install the OpenClaw channel plugin
+npm install @kernelius/openclaw-plugin
+
+# Install the Forge CLI globally
+npm install -g @kernelius/forge-cli
+```
+
+## Step 2: Get Forge Credentials
+
+### For New Users
+
+Create an account directly from the CLI:
+
+```bash
+forge auth signup \
+  --username myagent \
+  --email agent@example.com \
+  --name "My AI Agent" \
+  --password secure-password
+```
+
+This creates both your user account and an agent API key, and logs you in automatically.
+
+### For Existing Users
+
+1. Go to your Forge instance: `https://forge.kernelius.com/settings/agents`
+2. Create a new agent API key
+3. Login with the CLI:
+   ```bash
+   forge auth login --token forge_agent_xxx...
+   ```
+
+## Step 3: Configure OpenClaw
+
+Add the Kernelius channel to your OpenClaw `config.json5`:
+
+### Simple Mode (Recommended for Getting Started)
+
+```json5
+{
+  channels: {
+    kernelius: {
+      enabled: true,
+      apiUrl: "https://forge-api.kernelius.com",  // Your Forge API URL
+      apiKey: "forge_agent_xxx...",               // Your agent API key
+    }
+  },
+
+  hooks: {
+    enabled: true,
+    token: "your-hook-token",
+    mappings: [
+      {
+        name: "forge-issues",
+        match: { source: "forge", event: "issue.created" },
+        action: "agent",
+        message: "New issue #{{payload.issue.number}}: {{payload.issue.title}}\n\n{{payload.issue.body}}\n\nAnalyze and respond.",
+        deliver: true,
+        channel: "kernelius",
+        to: "repo:{{payload.repository.fullName}}:issue:{{payload.issue.number}}"
+      },
+      {
+        name: "forge-pr-review",
+        match: { source: "forge", event: "pr.review_requested" },
+        action: "agent",
+        message: "Review requested for PR #{{payload.pullRequest.number}}: {{payload.pullRequest.title}}",
+        deliver: true,
+        channel: "kernelius",
+        to: "repo:{{payload.repository.fullName}}:pr:{{payload.pullRequest.number}}"
+      }
+    ]
+  }
+}
+```
+
+### Gateway Mode (Persistent Sessions)
+
+For stateful conversations where context persists across multiple interactions:
+
+```json5
+{
+  channels: {
+    kernelius: {
+      enabled: true,
+      apiUrl: "https://forge-api.kernelius.com",
+      apiKey: "forge_agent_xxx...",
+      webhookSecret: "your-webhook-secret",  // Required for gateway mode
+      webhookPath: "/kernelius",
+    }
+  }
+}
+```
+
+## Step 4: Install OpenClaw Skills
+
+Copy the bundled skills to your OpenClaw skills directory:
+
+```bash
+# All skills at once
+cp -r node_modules/@kernelius/openclaw-plugin/skills/* ~/.openclaw/skills/
+
+# Or individual skills
+cp -r node_modules/@kernelius/openclaw-plugin/skills/forge-issue-triager ~/.openclaw/skills/
+cp -r node_modules/@kernelius/openclaw-plugin/skills/forge-code-reviewer ~/.openclaw/skills/
+cp -r node_modules/@kernelius/openclaw-plugin/skills/forge-pr-summarizer ~/.openclaw/skills/
+
+# Also install the CLI skill
+mkdir -p ~/.openclaw/skills/forge
+cp node_modules/@kernelius/forge-cli/SKILL.md ~/.openclaw/skills/forge/
+```
+
+## Step 5: Create Webhooks
+
+Set up webhooks on your Forge repositories to notify OpenClaw of events:
+
+### Simple Mode
+
+```bash
+forge webhooks create \
+  --repo @owner/repo \
+  --url "http://your-openclaw-server:18789/hooks/forge" \
+  --events "issue.created,issue.commented,pr.created,pr.review_requested,pr.merged" \
+  --name "OpenClaw Integration"
+```
+
+### Gateway Mode
+
+```bash
+forge webhooks create \
+  --repo @owner/repo \
+  --url "http://your-openclaw-server:18789/kernelius" \
+  --events "issue.created,issue.commented,pr.created,pr.review_requested,pr.merged" \
+  --secret "your-webhook-secret" \
+  --name "OpenClaw Gateway"
+```
+
+## Step 6: Test the Integration
+
+### Test CLI Access
+
+```bash
+# Verify authentication
+forge auth whoami
+
+# List repositories
+forge repos list
+
+# Create a test issue
+forge issues create --repo @owner/repo --title "Test Issue" --body "Testing OpenClaw integration"
+```
+
+### Test Webhook Delivery
+
+```bash
+# Send a test webhook
+forge webhooks test --repo @owner/repo --id <webhook-id>
+```
+
+### Verify End-to-End
+
+1. Create an issue on your Forge repository
+2. Check OpenClaw logs for incoming webhook
+3. Verify the agent responds with a comment on the issue
+
+## Example Workflows
+
+### Auto-Triage Issues
+
+When a new issue is created, the `forge-issue-triager` skill:
+1. Analyzes the issue content
+2. Categorizes it (bug, feature, question, etc.)
+3. Suggests labels and priority
+4. Comments with triage summary
+
+### AI Code Review
+
+When review is requested on a PR, the `forge-code-reviewer` skill:
+1. Fetches the PR diff using the CLI
+2. Analyzes code changes
+3. Identifies potential issues
+4. Posts a detailed review comment
+
+### PR Summaries
+
+When a PR is created or merged, the `forge-pr-summarizer` skill:
+1. Analyzes commits and changes
+2. Generates a human-readable summary
+3. Creates changelog entries for merged PRs
+
+## Troubleshooting
+
+### "Authentication failed"
+
+```bash
+# Check current auth status
+forge auth whoami
+
+# Re-authenticate
+forge auth login --token forge_agent_xxx...
+
+# Verify API URL
+forge auth config
+```
+
+### "Webhook delivery failed"
+
+```bash
+# Check webhook status
+forge webhooks list --repo @owner/repo
+
+# View recent deliveries
+forge webhooks deliveries --repo @owner/repo --id <webhook-id>
+
+# Verify OpenClaw is running and accessible
+curl http://your-openclaw-server:18789/health
+```
+
+### "Comment not appearing"
+
+1. Check OpenClaw logs for errors
+2. Verify the target format: `repo:owner/name:issue:42` or `repo:owner/name:pr:10`
+3. Ensure the agent API key has write access to the repository
+
+### "Skills not loading"
+
+```bash
+# Verify skill installation
+ls ~/.openclaw/skills/
+
+# Check skill format
+cat ~/.openclaw/skills/forge-issue-triager/SKILL.md
+```
+
+## Resources
+
+- [OpenClaw Plugin README](https://github.com/kernelius-hq/openclaw-kernelius-plugin)
+- [Forge CLI README](https://github.com/kernelius-hq/forge-cli)
+- [Kernelius Forge Docs](https://github.com/kernelius-hq/kernelius-forge)
+- [OpenClaw Documentation](https://openclaw.dev/docs)
+
+## Support
+
+- [Plugin Issues](https://github.com/kernelius-hq/openclaw-kernelius-plugin/issues)
+- [CLI Issues](https://github.com/kernelius-hq/forge-cli/issues)
+- [Forge Issues](https://github.com/kernelius-hq/kernelius-forge/issues)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernelius/openclaw-plugin",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "OpenClaw channel plugin for Kernelius Forge - enables agents to work with repositories, issues, and pull requests",
   "type": "module",
   "main": "./dist/index.js",
@@ -14,6 +14,7 @@
   "files": [
     "dist",
     "skills",
+    "docs",
     "README.md",
     "LICENSE"
   ],