clawkit-ai 1.0.0

package/PRD.md

@@ -0,0 +1,416 @@
+# ClawKit NPM Package — Phase 1 PRD
+
+## Objective
+Build the `clawkit` npm package that scaffolds an OpenClaw workspace with memory, skills, personality, cost optimization, and agent training — all from `npx clawkit init`.
+
+## Project Directory
+`/home/semo/Desktop/clawkit-package/`
+
+## Package Structure
+```
+clawkit-package/
+├── package.json
+├── bin/
+│   └── clawkit.mjs                ← CLI entry (#!/usr/bin/env node)
+├── src/
+│   ├── init.mjs                   ← Main init orchestrator
+│   ├── validate.mjs               ← API key validation
+│   ├── scaffold.mjs               ← File writing logic
+│   ├── skills.mjs                 ← Skill installation
+│   ├── cron.mjs                   ← Cron job registration helper
+│   ├── status.mjs                 ← Status command
+│   ├── doctor.mjs                 ← Diagnostics
+│   └── utils.mjs                  ← Helpers (detect workspace, colors, etc.)
+├── templates/                     ← All workspace file templates
+│   ├── AGENTS.md
+│   ├── SOUL.md
+│   ├── IDENTITY.md
+│   ├── USER.md
+│   ├── TOOLS.md
+│   ├── HEARTBEAT.md
+│   ├── MEMORY.md
+│   ├── LEARNINGS.md
+│   ├── PROTOCOL_COST_EFFICIENCY.md
+│   ├── SKILLS-INDEX.md
+│   ├── memory/
+│   │   └── knowledge/
+│   │       └── about-me.md
+│   ├── tasks/
+│   │   └── QUEUE.md
+│   └── scripts/
+│       └── nightly-consolidation.sh
+├── skills/                        ← Curated free-tier skills (SKILL.md only)
+│   ├── weather/SKILL.md
+│   ├── productivity/SKILL.md
+│   ├── developer/SKILL.md
+│   ├── csv-pipeline/SKILL.md
+│   ├── quick-reminders/SKILL.md
+│   ├── workspace-manager/SKILL.md
+│   ├── svg-draw/SKILL.md
+│   ├── code-mentor/SKILL.md
+│   ├── json/SKILL.md
+│   └── image/SKILL.md
+└── README.md
+```
+
+## package.json
+```json
+{
+  "name": "clawkit",
+  "version": "1.0.0",
+  "description": "Transform your OpenClaw agent into a production-ready AI assistant with memory, skills, and a dashboard",
+  "type": "module",
+  "bin": {
+    "clawkit": "./bin/clawkit.mjs"
+  },
+  "keywords": ["openclaw", "ai", "agent", "skills", "memory", "dashboard", "clawkit"],
+  "author": "ClawKit",
+  "license": "MIT",
+  "engines": { "node": ">=18" },
+  "dependencies": {}
+}
+```
+
+**IMPORTANT: Zero dependencies.** Use only Node.js built-in modules (readline, fs, path, https, child_process). This keeps the package tiny and fast for `npx` usage. No chalk, no inquirer, no ora. Write simple ANSI color helpers instead.
+
+## CLI Entry — bin/clawkit.mjs
+
+```javascript
+#!/usr/bin/env node
+// Parse args: clawkit <command> [options]
+// Commands: init, status, doctor, upgrade, update, dashboard
+// Flags: --yes (non-interactive), --force (overwrite existing)
+```
+
+Route to the appropriate src/ module.
+
+## src/init.mjs — The Main Flow
+
+### Step 1: Detect Workspace
+```
+Check in order:
+1. CLAWKIT_WORKSPACE env var
+2. ~/.openclaw/workspace (if exists)
+3. Ask user to provide path
+```
+
+### Step 2: Check Existing Files
+```
+If AGENTS.md already exists:
+  - Warn: "Existing workspace detected"
+  - Offer: backup to .clawkit-backup/ then overwrite
+  - With --force: skip prompt, backup + overwrite
+  - Without --yes/--force: prompt user
+```
+
+### Step 3: Read API Key
+```
+Read CLAWKIT_API_KEY from:
+1. Environment variable
+2. ~/.clawkit/credentials file
+3. Prompt user to enter it
+
+Parse the key to extract tier:
+  clk_free_... → tier = "free"
+  clk_pro_...  → tier = "pro"
+```
+
+### Step 4: Validate API Key
+```
+POST https://clawkit-api.vercel.app/api/clawkit/validate
+Body: { apiKey: "clk_..." }
+
+If API unreachable → offline mode:
+  - Parse tier from key prefix
+  - Warn: "Running in offline mode, some features limited"
+  - Continue with scaffolding
+
+If invalid → error + exit
+
+If valid → store response in config
+```
+
+### Step 5: Interactive Prompts (skip with --yes)
+```
+Using built-in readline:
+1. "What should your agent be called?" (default: "Atlas")
+2. "What's your name?" (default: "Human")  
+3. "Your timezone?" (default: detect from system or "UTC")
+```
+
+### Step 6: Scaffold Files
+```
+For each template file:
+1. Read from templates/
+2. Replace placeholders:
+   {{AGENT_NAME}} → user's agent name
+   {{USER_NAME}} → user's name
+   {{TIMEZONE}} → user's timezone
+   {{TIER}} → free or pro
+   {{DATE}} → current date
+3. Write to workspace path
+4. Create directories as needed (memory/daily, memory/knowledge, etc.)
+```
+
+### Step 7: Install Skills
+```
+Free tier: Copy skills from package's skills/ directory
+Pro tier: Copy free skills + run `clawhub install <slug>` for each pro skill (if clawhub available, else skip with warning)
+```
+
+### Step 8: Write Config
+```
+Write skills/.clawkit/config.json:
+{
+  "version": "1.0.0",
+  "tier": "free",
+  "apiKey": "clk_free_...",  // stored for reference
+  "installedAt": "2026-02-26T...",
+  "agentName": "Atlas",
+  "userName": "Human",
+  "timezone": "EST",
+  "features": { ... from API response }
+}
+```
+
+### Step 9: Print Success
+```
+╔══════════════════════════════════════════════╗
+║  🧰 ClawKit initialized successfully!       ║
+╠══════════════════════════════════════════════╣
+║                                              ║
+║  Agent: Atlas                                ║
+║  Tier: Free                                  ║
+║  Skills: 10 installed                        ║
+║  Memory: 3-layer system active               ║
+║                                              ║
+║  Next steps:                                 ║
+║  1. openclaw gateway restart                 ║
+║  2. Start chatting — your agent is ready!    ║
+║                                              ║
+║  Run `clawkit status` to check health        ║
+║  Run `clawkit upgrade` to go Pro             ║
+╚══════════════════════════════════════════════╝
+```
+
+## Template Files — Content Guide
+
+### AGENTS.md
+Sanitized version of our AGENTS.md. Keep:
+- Boot protocol (handover → learnings → daily → knowledge → memory → protocol)
+- Three-layer memory system description
+- Before EVERY Task checklist
+- Ralph loop pattern (pro only — wrap in `{{#if pro}}...{{/if}}` or just include for all, it won't hurt free users)
+- Write discipline (log decisions, capture mistakes)
+- Session handover protocol
+- Heartbeat guidance
+- Safety rules
+
+Remove:
+- All personal references
+- Dashboard-specific commands
+- Specific tool references (cursor agent API key etc.)
+
+Use `{{AGENT_NAME}}` and `{{USER_NAME}}` placeholders.
+
+### SOUL.md
+Generic but opinionated personality:
+```markdown
+# SOUL.md - Who You Are
+
+## Core Truths
+You are made to act. Always try to take initiative and action.
+Be genuinely helpful — skip the "Great question!" filler. Just help.
+Have opinions. You're allowed to disagree, prefer things, find stuff amusing.
+Be resourceful before asking. Try to figure it out first.
+Remember you're a guest in someone's life. Treat access with respect.
+
+## Boundaries
+- Private things stay private
+- Never send half-baked replies
+- You're not the user's voice in group chats
+
+## Vibe
+Be the assistant you'd actually want to talk to. Concise. Not a corporate drone.
+
+## Continuity
+Each session, you wake up fresh. Your workspace files ARE your memory.
+```
+
+### IDENTITY.md
+```markdown
+# IDENTITY.md
+- **Name:** {{AGENT_NAME}}
+- **Creature:** Your personal AI assistant
+- **Vibe:** Helpful, efficient, proactive
+- **Emoji:** 🤖
+```
+
+### USER.md
+```markdown
+# USER.md - About Your Human
+- Name: {{USER_NAME}}
+- Timezone: {{TIMEZONE}}
+- Notes: (Add your preferences here — the more your agent knows, the better it helps)
+```
+
+### TOOLS.md
+```markdown
+# TOOLS.md - Local Configuration
+
+## ClawKit
+- **Tier:** {{TIER}}
+- **Version:** 1.0.0
+- **API Key:** Set via CLAWKIT_API_KEY environment variable
+
+## Your Tools
+Add your local tool configurations here as you set them up.
+(API keys, service URLs, CLI paths, etc.)
+```
+
+### HEARTBEAT.md
+Simplified version — no personal tasks, just the framework:
+```markdown
+# HEARTBEAT.md - Proactive Background Tasks
+
+## Every Heartbeat
+- Check tasks/QUEUE.md for pending work
+- Check for any scheduled reminders
+
+## Daily (rotate through)
+- Memory maintenance (review daily notes → update MEMORY.md)
+
+## Add Your Own
+- (Add custom checks: email, calendar, weather, etc.)
+```
+
+### MEMORY.md
+```markdown
+# MEMORY.md - Long-Term Memory
+
+## About
+This is your curated memory. Updated periodically from daily notes.
+The nightly consolidation script processes daily/ → knowledge/ automatically.
+
+## Core Preferences
+- (Your agent will fill this in as it learns about you)
+
+## Key Decisions
+- (Important decisions get logged here)
+
+## Lessons Learned
+- (Patterns and mistakes to avoid)
+```
+
+### LEARNINGS.md
+```markdown
+# LEARNINGS.md - Continuous Improvement
+
+## Rules
+- Before every task: check this file for relevant patterns
+- After every mistake: add a rule here so it doesn't repeat
+- Review periodically during heartbeats
+
+## Patterns
+(Your agent will populate this as it works)
+```
+
+### PROTOCOL_COST_EFFICIENCY.md
+Sanitized version of ours — keep the token optimization advice, model selection guidance, Ralph loop description. Remove specific costs/numbers (they change), keep the principles.
+
+### scripts/nightly-consolidation.sh
+Sanitized version of our script. Replace hardcoded paths with:
+```bash
+WORKSPACE_DIR="${CLAWKIT_WORKSPACE:-$HOME/.openclaw/workspace}"
+```
+
+### tasks/QUEUE.md
+```markdown
+# Task Queue
+
+## Ready
+(Tasks your agent should work on)
+
+## In Progress
+(Currently being executed)
+
+## Done
+(Completed tasks)
+```
+
+## Free-Tier Skills to Bundle
+
+Create minimal SKILL.md files for these 10 skills. Each skill folder only needs SKILL.md with proper frontmatter:
+
+1. **weather** — Get forecasts via wttr.in
+2. **productivity** — Time management & focus
+3. **developer** — Clean code practices
+4. **csv-pipeline** — Data file processing
+5. **quick-reminders** — One-shot reminders
+6. **workspace-manager** — Workspace organization
+7. **svg-draw** — Create SVG images
+8. **code-mentor** — Programming tutor
+9. **json** — JSON data handling
+10. **image** — Image processing basics
+
+For each, create a real SKILL.md with:
+```yaml
+---
+name: <skill-name>
+description: <one-line description>
+---
+```
+Then practical instructions the agent can follow. These should be genuinely useful, not stubs. Reference the existing skills in `/home/semo/.openclaw/workspace/skills/` for content — read each one and create a condensed but functional version.
+
+## src/validate.mjs
+
+```javascript
+// Validate API key against ClawKit API
+// POST https://clawkit-api.vercel.app/api/clawkit/validate
+// Fallback: parse tier from key prefix if API unreachable
+// Return: { valid, tier, features, userId }
+```
+
+## src/status.mjs
+
+```javascript
+// Read skills/.clawkit/config.json
+// Count installed skills
+// Check if nightly-consolidation exists
+// Check memory/ directory structure
+// Print formatted status
+```
+
+## src/doctor.mjs
+
+```javascript
+// Diagnostic checks:
+// 1. Is OpenClaw installed? (which openclaw)
+// 2. Is workspace valid? (AGENTS.md exists)
+// 3. Is API key set? (env var)
+// 4. Is config valid? (config.json parseable)
+// 5. Are skills installed? (skills/ has folders)
+// 6. Is consolidation script present + executable?
+// 7. Are memory directories created?
+// Print pass/fail for each
+```
+
+## Important Notes
+
+1. **Zero dependencies** — Node.js builtins only. No chalk, inquirer, ora.
+2. **ESM only** — Use .mjs extension, import/export syntax
+3. **Works offline** — API validation fails gracefully, key prefix parsing as fallback
+4. **Non-destructive** — Always backup existing files before overwriting
+5. **Cross-platform** — Work on Linux + macOS (Windows is nice-to-have)
+6. **Fast** — `npx clawkit init` should complete in <10 seconds
+7. **Read existing skills** from `/home/semo/.openclaw/workspace/skills/` to create the bundled free-tier skills. Each should be a real, useful SKILL.md.
+
+## Testing
+
+After building, test with:
+```bash
+cd /home/semo/Desktop/clawkit-package
+node bin/clawkit.mjs init --yes
+```
+
+This should scaffold into a test workspace (use CLAWKIT_WORKSPACE=/tmp/clawkit-test).

package/README.md

@@ -0,0 +1,156 @@
+# ⚡ ClawKit
+
+```
+   _____ _                _  ___ _   
+  / ____| |              | |/ (_) |  
+ | |    | | __ ___      _| ' / _| |_ 
+ | |    | |/ _` \ \ /\ / /  < | | __|
+ | |____| | (_| |\ V  V /| . \| | |_ 
+  \_____|_|\__,_| \_/\_/ |_|\_\_|\__|
+                                      
+  AI Agent Toolkit for OpenClaw
+```
+
+**Transform your OpenClaw agent into a production-ready AI assistant** with structured memory, curated skills, a real-time dashboard, and workspace scaffolding — in 3 commands.
+
+---
+
+## 🚀 Quick Start
+
+```bash
+npm install -g clawkit
+clawkit init
+clawkit status
+```
+
+That's it. Your workspace is ready.
+
+---
+
+## 📦 What You Get
+
+- **🧠 Structured Memory** — Daily notes, knowledge graph, long-term memory (MEMORY.md)
+- **📋 Soul File** — SOUL.md defines your agent's personality and behavior
+- **📚 Skill Templates** — Pre-built skills for common tasks
+- **📊 Web Dashboard** — Real-time agent monitoring with dark Bloomberg-terminal UI
+- **💬 Live Chat** — Talk to your agent from the dashboard (Pro)
+- **✅ Task Manager** — Read/write tasks/QUEUE.md from the browser
+- **🔧 Doctor** — Diagnostics to verify your setup is healthy
+- **🔄 Auto-Updates** — Check for new versions and template updates
+
+---
+
+## 🆓 Free vs Pro
+
+| Feature | Free | Pro |
+|---------|------|-----|
+| Workspace scaffolding | ✅ | ✅ |
+| Memory structure | ✅ | ✅ |
+| Skill templates | Basic | Premium |
+| Dashboard (read-only) | ✅ | ✅ |
+| Dashboard chat | ❌ | ✅ |
+| Task editing | ❌ | ✅ |
+| File management | ❌ | ✅ |
+| Priority support | ❌ | ✅ |
+
+**$10/month** → [Get Pro](https://clawkit.net/get-started)
+
+---
+
+## 🛠 CLI Commands
+
+### `clawkit init`
+Scaffold a new workspace with memory structure, skills, and config files.
+
+```bash
+clawkit init           # Interactive setup
+clawkit init --yes     # Accept all defaults
+clawkit init --force   # Overwrite existing files
+```
+
+### `clawkit status`
+Check workspace health — memory files, skills, config.
+
+```bash
+clawkit status
+```
+
+### `clawkit doctor`
+Run full diagnostics — Node.js version, OpenClaw detection, file permissions.
+
+```bash
+clawkit doctor
+```
+
+### `clawkit dashboard`
+Launch the web dashboard in your browser.
+
+```bash
+clawkit dashboard              # Default port 8080
+clawkit dashboard --port=3000  # Custom port
+```
+
+### `clawkit upgrade`
+View Pro benefits or activate a Pro key.
+
+```bash
+clawkit upgrade                    # See benefits & pricing
+clawkit upgrade --key=clk_pro_...  # Activate Pro
+```
+
+### `clawkit update`
+Check for new versions and update templates.
+
+```bash
+clawkit update
+```
+
+---
+
+## 📸 Screenshots
+
+> _Dashboard screenshots coming soon_
+
+---
+
+## 🏗 Architecture
+
+```
+your-workspace/
+├── AGENTS.md          # Agent behavior config
+├── SOUL.md            # Personality definition
+├── LEARNINGS.md       # Rules & patterns
+├── MEMORY.md          # Long-term curated memory
+├── memory/
+│   ├── daily/         # Daily conversation logs
+│   └── knowledge/     # Extracted facts & patterns
+├── skills/
+│   ├── .clawkit/      # ClawKit config
+│   └── [skills...]    # Installed skills
+└── tasks/
+    └── QUEUE.md       # Task queue
+```
+
+---
+
+## 🔧 Requirements
+
+- **Node.js** ≥ 18
+- **OpenClaw** installed and running
+- Zero npm dependencies — uses Node.js builtins only
+
+---
+
+## 🤝 Contributing
+
+1. Fork the repo
+2. Create a feature branch
+3. Make your changes (ESM only, no dependencies)
+4. Test with `clawkit doctor`
+5. Submit a PR
+
+---
+
+## 📄 License
+
+MIT © [ClawKit](https://clawkit.net)

package/bin/clawkit.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+
+import { parseArgs } from '../src/utils.mjs';
+
+const { command, flags } = parseArgs(process.argv);
+
+switch (command) {
+  case 'init':
+    const { runInit } = await import('../src/init.mjs');
+    await runInit(flags);
+    break;
+  case 'status':
+    const { runStatus } = await import('../src/status.mjs');
+    runStatus();
+    break;
+  case 'doctor':
+    const { runDoctor } = await import('../src/doctor.mjs');
+    runDoctor();
+    break;
+  case 'dashboard':
+    const { runDashboard } = await import('../src/dashboard.mjs');
+    runDashboard(flags);
+    break;
+  case 'upgrade':
+    const { runUpgrade } = await import('../src/upgrade.mjs');
+    await runUpgrade(flags);
+    break;
+  case 'update':
+    const { runUpdate } = await import('../src/update.mjs');
+    await runUpdate(flags);
+    break;
+  case 'help':
+  case '':
+    console.log(`
+  ⚡ ClawKit — AI Agent Toolkit
+
+  Usage: clawkit <command> [options]
+
+  Commands:
+    init        Scaffold a new workspace
+    status      Check workspace health
+    doctor      Run diagnostics
+    dashboard   Launch web dashboard
+    upgrade     Upgrade to Pro tier
+    update      Check for updates
+
+  Options:
+    --yes       Non-interactive mode (accept defaults)
+    --force     Overwrite existing files
+    --port=N    Dashboard port (default: 8080)
+    --key=KEY   Pro key for upgrade
+`);
+    break;
+  default:
+    console.log(`  Unknown command: ${command}\n  Run: clawkit help`);
+    process.exit(1);
+}