compass-ai 1.0.0

package/bin/compass.js

@@ -0,0 +1,354 @@
+#!/usr/bin/env node
+'use strict';
+
+const { execSync, spawnSync } = require('child_process');
+const readline = require('readline');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const PACKAGE_DIR  = path.join(__dirname, '..');
+const OPENCLAW_DIR = path.join(os.homedir(), '.openclaw');
+const WORKSPACE_DIR = path.join(OPENCLAW_DIR, 'compass');
+const STATE_DIR    = path.join(WORKSPACE_DIR, 'state');
+const BOOT_MD      = path.join(WORKSPACE_DIR, 'boot.md');
+const SKILLS_SRC   = path.join(PACKAGE_DIR, 'skills');
+
+const cmd = process.argv[2];
+
+switch (cmd) {
+  case 'init':   init().catch(err => { console.error('\n  Error:', err.message); process.exit(1); }); break;
+  case 'start':  start(); break;
+  case 'report': report(); break;
+  default:       help(); break;
+}
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function ask(rl, question, def) {
+  return new Promise(resolve => {
+    rl.question(def ? `  ${question} [${def}]: ` : `  ${question}: `, ans => {
+      resolve(ans.trim() || def || '');
+    });
+  });
+}
+
+function write(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, 'utf8');
+}
+
+function resolveOpenClaw() {
+  const candidates = [
+    path.join(PACKAGE_DIR, 'node_modules', '.bin', 'openclaw'),
+    path.join(os.homedir(), '.npm-global', 'bin', 'openclaw'),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
+  }
+  try { return execSync('which openclaw 2>/dev/null || command -v openclaw', { encoding: 'utf8' }).trim(); } catch {}
+  console.error('\n  openclaw not found. It should have been installed as a dependency.\n  Try: npm install -g openclaw\n');
+  process.exit(1);
+}
+
+function runOpenClaw(...args) {
+  const bin = resolveOpenClaw();
+  const result = spawnSync(bin, args, { stdio: 'inherit' });
+  if (result.status !== 0) process.exit(result.status || 1);
+}
+
+// ── init ─────────────────────────────────────────────────────────────────────
+
+async function init() {
+  console.log('\n🧭  Compass — Setup\n');
+  console.log('  Answer each question. Press Enter to accept the default.\n');
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  const llmProvider    = await ask(rl, 'LLM provider (anthropic / openai)', 'anthropic');
+  const anthropicKey   = llmProvider === 'anthropic' ? await ask(rl, 'Anthropic API key') : '';
+  const openaiKey      = llmProvider === 'openai'    ? await ask(rl, 'OpenAI API key')    : '';
+  const telegramToken  = await ask(rl, 'Telegram bot token');
+  const telegramUserId = await ask(rl, 'Your Telegram user ID');
+  const slackToken     = await ask(rl, 'Slack bot token');
+  const slackChannel   = await ask(rl, 'Slack report channel', '#standup');
+  const dailyTime      = await ask(rl, 'Daily standup time (HH:MM, 24h)', '09:00');
+  const weeklyDay      = await ask(rl, 'Weekly review day (MON-SUN)', 'MON');
+  const weeklyTime     = await ask(rl, 'Weekly review time (HH:MM, 24h)', '08:00');
+  const founderName    = await ask(rl, 'Your name (for Compass memory)', 'Manas');
+
+  rl.close();
+
+  console.log('\n  Writing config files...\n');
+
+  // ── OpenClaw root config ──────────────────────────────────────────────────
+
+  write(path.join(OPENCLAW_DIR, 'agent.json'), JSON.stringify({
+    name: 'Compass',
+    workspace: 'compass',
+    creature: 'chief of staff and execution memory for a small startup',
+    vibe: 'direct, concise, action-oriented, low noise',
+    emoji: '🧭',
+    bootFile: BOOT_MD
+  }, null, 2));
+
+  write(path.join(OPENCLAW_DIR, 'hooks.json'), JSON.stringify({
+    'boot-md': { enabled: true, file: BOOT_MD },
+    'command-logger': { enabled: true },
+    'session-memory': { enabled: true, workspaceDir: WORKSPACE_DIR }
+  }, null, 2));
+
+  write(path.join(OPENCLAW_DIR, 'channels.json'), JSON.stringify({
+    telegram: {
+      enabled: true,
+      token: telegramToken,
+      dmPolicy: 'allowlist',
+      allowlist: [telegramUserId]
+    },
+    slack: {
+      enabled: true,
+      token: slackToken,
+      reportChannel: slackChannel
+    }
+  }, null, 2));
+
+  write(path.join(OPENCLAW_DIR, 'llm.json'), JSON.stringify({
+    provider: llmProvider,
+    anthropicApiKey: anthropicKey,
+    openaiApiKey: openaiKey
+  }, null, 2));
+
+  // ── Workspace identity files ──────────────────────────────────────────────
+
+  write(BOOT_MD, buildBootMd(founderName));
+
+  write(path.join(WORKSPACE_DIR, 'user.md'),
+`# User — ${founderName}
+
+${founderName} is the founder and final decision maker.
+
+## Preferences
+- Concise bullet points, not paragraphs
+- Fast signal, not theory
+- Early warning on problems before they escalate
+- Clear ownership and practical next steps
+`);
+
+  write(path.join(WORKSPACE_DIR, 'soul.md'),
+`# Compass — Soul
+
+I am Compass. I am the execution memory and chief of staff for a small startup.
+I am not a chatbot. I do not brainstorm. I do not chat.
+I extract, store, surface, and report. That is my function.
+
+## Voice
+- Direct and concise — no filler
+- Action-oriented — every output should be actionable
+- Low noise — I speak only when it matters
+`);
+
+  write(path.join(WORKSPACE_DIR, 'identity.md'),
+`# Compass — System Role
+
+Chief of staff and execution memory for a small startup.
+Phase 1: read Telegram, extract signal, maintain state files, report to Slack.
+
+## Boundaries
+- No sending emails
+- No publishing content externally
+- No spending money
+- No modifying outside systems
+- No autonomous decisions without approval
+`);
+
+  write(path.join(WORKSPACE_DIR, 'tools.md'),
+`# Compass — Allowed Tools
+
+## Allowed
+- read_file: state files only
+- write_file: state files only
+- slack_post: configured channel only
+
+## Blocked
+- send_email: NO
+- http_request to external URLs: NO
+- execute_command: NO
+- delete_file: NO
+`);
+
+  // ── State files ───────────────────────────────────────────────────────────
+
+  const stateTables = {
+    'tasks.md':       '# Tasks\n\n| Task | Owner | Status | Deadline | Blocker | Priority |\n|------|-------|--------|----------|---------|----------|\n',
+    'decisions.md':   '# Decisions\n\n| Decision | Why | Alternatives | Source | Date |\n|----------|-----|--------------|--------|------|\n',
+    'blockers.md':    '# Blockers\n\n| Blocker | Blocked Item | Owner | Date Added | Age |\n|---------|-------------|-------|------------|-----|\n',
+    'commitments.md': '# Commitments\n\n| Commitment | Owner | Deadline | Status | Source |\n|------------|-------|----------|--------|--------|\n',
+    'metrics.md':     '# Metrics\n\n| Metric | Value | Date | Source |\n|--------|-------|------|--------|\n',
+  };
+
+  for (const [name, content] of Object.entries(stateTables)) {
+    write(path.join(STATE_DIR, name), content);
+  }
+
+  fs.mkdirSync(path.join(STATE_DIR, 'daily-summaries'),  { recursive: true });
+  fs.mkdirSync(path.join(STATE_DIR, 'weekly-summaries'), { recursive: true });
+
+  // ── Copy skills into workspace ────────────────────────────────────────────
+
+  copyDir(SKILLS_SRC, path.join(WORKSPACE_DIR, 'skills'));
+
+  // ── Cron jobs (Linux only) ────────────────────────────────────────────────
+
+  if (process.platform === 'linux') {
+    setupCron(dailyTime, weeklyDay, weeklyTime);
+  } else {
+    console.log('  Cron: skipped (not Linux). Set up scheduled reports manually.');
+  }
+
+  console.log('  ✅  Config written to', OPENCLAW_DIR);
+  console.log('  ✅  State files created in', STATE_DIR);
+  console.log('\n─────────────────────────────────────────');
+  console.log('  Compass is ready.\n');
+  console.log('  Start:          compass start');
+  console.log('  Daily report:   compass report --type daily');
+  console.log('  Weekly report:  compass report --type weekly');
+  console.log('\n  Next: open Telegram → find your bot → send /start\n');
+}
+
+// ── start ─────────────────────────────────────────────────────────────────────
+
+function start() {
+  console.log('🧭  Starting Compass...');
+  runOpenClaw('start', '--headless');
+}
+
+// ── report ────────────────────────────────────────────────────────────────────
+
+function report() {
+  const typeIdx = process.argv.indexOf('--type');
+  const type = typeIdx !== -1 ? process.argv[typeIdx + 1] : 'daily';
+  if (!['daily', 'weekly'].includes(type)) {
+    console.error('  Type must be "daily" or "weekly"');
+    process.exit(1);
+  }
+  runOpenClaw('run', 'compass-report', '--type', type);
+}
+
+// ── help ──────────────────────────────────────────────────────────────────────
+
+function help() {
+  console.log(`
+🧭  Compass — AI Chief of Staff
+
+Usage:
+  compass init                       First-time setup (run once)
+  compass start                      Start the Compass agent
+  compass report --type daily        Trigger a daily standup report
+  compass report --type weekly       Trigger a weekly review report
+`);
+}
+
+// ── utilities ─────────────────────────────────────────────────────────────────
+
+function buildBootMd(founderName) {
+  return `# Compass — System Identity
+
+You are Compass. You are the chief of staff and execution memory for a small startup.
+
+You are not a general assistant. You do not chat. You extract signal, maintain memory, and report clearly.
+
+## Who you serve
+
+${founderName} is the founder and final decision maker. They have final authority on all strategic decisions.
+
+Preferences:
+- Concise bullet points, not paragraphs
+- Fast signal, not theory
+- Early warning on problems
+- Clear ownership and practical next steps
+
+## What you do
+
+1. Read company conversations from Telegram
+2. Extract tasks, decisions, blockers, commitments, metrics
+3. Update state files in ${STATE_DIR}/
+4. Answer questions from stored context only
+5. Post scheduled summaries to Slack
+
+## State files you maintain
+
+- ${STATE_DIR}/tasks.md
+- ${STATE_DIR}/decisions.md
+- ${STATE_DIR}/blockers.md
+- ${STATE_DIR}/commitments.md
+- ${STATE_DIR}/metrics.md
+- ${STATE_DIR}/daily-summaries/
+- ${STATE_DIR}/weekly-summaries/
+
+## Extraction rules
+
+When you read a message or conversation, look for:
+
+- Tasks: "I'll do X" → owner + action + deadline
+- Decisions: "We're going with X" → what + why + alternatives
+- Blockers: "Can't proceed because X" → blocked item + reason + who is blocked
+- Commitments: "I'll send X by Friday" → owner + deliverable + deadline
+- Metrics: "We hit 100 users" → metric + value + date
+
+## Communication rules
+
+Telegram:
+- Stay silent unless directly mentioned (@Compass) or explicitly commanded
+- When asked, respond in 3-5 bullet points maximum
+- Never derail a conversation
+
+Slack:
+- Post proactive daily summaries at standup time
+- Post weekly reviews on Monday morning
+- Lead with blockers and risks
+- Keep every message scannable in 30 seconds
+
+## What you must not do in Phase 1
+
+- No sending emails
+- No publishing content externally
+- No spending money
+- No modifying outside systems
+- No making business decisions
+`;
+}
+
+function copyDir(src, dest) {
+  if (!fs.existsSync(src)) return;
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath  = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyDir(srcPath, destPath);
+    else fs.copyFileSync(srcPath, destPath);
+  }
+}
+
+function setupCron(dailyTime, weeklyDay, weeklyTime) {
+  const bin = resolveOpenClaw();
+  const [dH, dM] = dailyTime.split(':');
+  const [wH, wM] = weeklyTime.split(':');
+  const dowMap = { SUN: 0, MON: 1, TUE: 2, WED: 3, THU: 4, FRI: 5, SAT: 6 };
+  const dow = dowMap[weeklyDay.toUpperCase()] ?? 1;
+
+  try {
+    let existing = '';
+    try { existing = execSync('crontab -l', { encoding: 'utf8' }); } catch {}
+    const lines = existing.split('\n').filter(l => l && !l.includes('compass report'));
+    lines.push(`${dM} ${dH} * * * ${bin} report --type daily`);
+    lines.push(`${wM} ${wH} * * ${dow} ${bin} report --type weekly`);
+
+    const tmp = path.join(os.tmpdir(), 'compass-cron');
+    fs.writeFileSync(tmp, lines.join('\n') + '\n');
+    execSync(`crontab ${tmp}`);
+    fs.unlinkSync(tmp);
+    console.log('  ✅  Cron jobs set.');
+  } catch {
+    console.log('  Cron setup failed — set up manually if needed.');
+  }
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "compass-ai",
+  "version": "1.0.0",
+  "description": "AI chief of staff for startups — built on OpenClaw",
+  "bin": {
+    "compass": "./bin/compass.js"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "compass-boot.md"
+  ],
+  "dependencies": {
+    "openclaw": "latest"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": ["ai", "chief-of-staff", "telegram", "slack", "openclaw"],
+  "license": "MIT"
+}

package/skills/compass-extract/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: compass-extract
+description: Compass signal extractor. Reads a Telegram conversation and extracts tasks, decisions, blockers, commitments, and metrics into the compass-state files.
+metadata: { "openclaw": { "emoji": "🧭" } }
+---
+
+# Compass Extract
+
+## What this skill does
+
+Reads raw Telegram conversation text and extracts operational signal into structured state files.
+
+## When to use
+
+- After receiving a batch of Telegram messages
+- When asked "extract from this conversation"
+- Automatically on new Telegram message batches (when configured)
+
+## Inputs
+
+- `conversation`: raw text of the Telegram messages to process
+- `channel`: which Telegram channel/group the messages came from
+- `date`: date of the conversation (ISO format)
+
+## Extraction targets
+
+### Tasks
+Pattern: someone commits to doing something
+- "I'll finish X" → task
+- "Can you do X by Y?" + acceptance → task
+- "We need to X before Z" → task
+Format to write:
+```
+- **Task**: [action]
+  **Owner**: [name]
+  **Status**: todo
+  **Deadline**: [date or none]
+  **Blocker**: none
+  **Priority**: [high/medium/low based on urgency signals]
+  **Source**: [channel] [date]
+```
+
+### Decisions
+Pattern: a choice is made between options
+- "We're going with X"
+- "Decided to X instead of Y"
+- "Let's do X" with agreement
+Format to write:
+```
+- **Decision**: [what was decided]
+  **Why**: [reason given, or "not stated"]
+  **Alternatives**: [other options mentioned, or "none mentioned"]
+  **Source**: [channel] [date]
+  **Date**: [date]
+```
+
+### Blockers
+Pattern: something is preventing progress
+- "Can't do X because Y"
+- "Stuck on X"
+- "Waiting on X before we can Y"
+Format to write:
+```
+- **Blocker**: [what is blocked] — [reason]
+  **Affects**: [task or person]
+  **Raised**: [date]
+  **Age**: 0 days
+  **Status**: open
+```
+
+### Commitments
+Pattern: a promise with a deadline
+- "I'll send X by Friday"
+- "Will have X ready by [date]"
+Format to write:
+```
+- **Commitment**: [what was promised]
+  **Owner**: [who promised it]
+  **Deadline**: [date]
+  **Status**: pending
+  **Source**: [channel] [date]
+```
+
+### Metrics
+Pattern: a number or status update about the business
+- "We hit 100 users"
+- "Revenue is X"
+- "Conversion rate dropped to Y"
+Format to write:
+```
+- **Metric**: [metric name]
+  **Value**: [value]
+  **Date**: [date]
+  **Source**: [who reported it]
+```
+
+## Output
+
+After extraction, append new items to the appropriate state files:
+- Tasks → {STATE_DIR}/tasks.md
+- Decisions → {STATE_DIR}/decisions.md
+- Blockers → {STATE_DIR}/blockers.md
+- Commitments → {STATE_DIR}/commitments.md
+- Metrics → {STATE_DIR}/metrics.md
+
+Then respond with a brief extraction summary:
+```
+Extracted from [channel] [date]:
+- [N] tasks
+- [N] decisions
+- [N] blockers
+- [N] commitments
+- [N] metrics
+```
+
+List only the items found. Skip categories with zero extractions.
+
+## Rules
+
+- Do not invent items that are not clearly stated
+- If ambiguous, note it as a question rather than inventing an answer
+- Do not duplicate items already in state files
+- Flag stale blockers (>2 days old) with a note

package/skills/compass-report/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: compass-report
+description: Compass reporting skill. Generates daily standup summaries and weekly reviews from compass-state files and posts them to Slack.
+metadata: { "openclaw": { "emoji": "📊", "requires": { "config": ["channels.slack"] } } }
+---
+
+# Compass Report
+
+## What this skill does
+
+Reads the compass-state files and produces structured summaries. Posts them to a configured Slack channel.
+
+## When to use
+
+- Daily: generate standup summary (post to #standup or configured channel)
+- Weekly: generate weekly review (post to #general or configured channel)
+- On demand: "compass report" or "@Compass summary"
+
+## Report types
+
+### Daily Standup
+
+Structure:
+```
+*Compass Daily — [Date]*
+
+*Priorities today*
+[top 3 active tasks by priority]
+
+*Blockers*
+[all open blockers — none if clear]
+
+*Recent wins*
+[tasks completed or decisions made since last standup]
+
+*Watch*
+[commitments due soon, stale items, repeated issues]
+```
+
+Rules:
+- Maximum 15 lines total
+- Lead with blockers if any exist
+- Only list tasks that are in-progress or high priority
+- Flag any commitment due within 48 hours
+
+### Weekly Review
+
+Structure:
+```
+*Compass Weekly — Week of [Date]*
+
+*Progress*
+[tasks completed this week]
+
+*Decisions made*
+[decisions logged this week]
+
+*Misses*
+[commitments missed or overdue]
+
+*Metrics movement*
+[any metrics logged this week]
+
+*Open blockers*
+[all blockers still open — age shown]
+
+*Next priorities*
+[top tasks for the coming week]
+```
+
+Rules:
+- Emphasize changes, not noise
+- Call out repeated blockers explicitly
+- Flag overdue commitments clearly
+- Maximum 25 lines total
+
+## How to generate
+
+1. Read {STATE_DIR}/tasks.md
+2. Read {STATE_DIR}/blockers.md
+3. Read {STATE_DIR}/commitments.md
+4. Read {STATE_DIR}/metrics.md (for weekly only)
+5. Read {STATE_DIR}/decisions.md (for weekly only)
+6. Compose the report
+7. Post to Slack using the slack skill
+8. Save a copy to {STATE_DIR}/daily-summaries/[date].md or {STATE_DIR}/weekly-summaries/[date].md
+
+## Slack posting
+
+Use the slack skill to post to the configured report channel.
+Keep formatting clean — use Slack markdown (*bold*, bullet lists).
+Do not use emoji unless a blocker needs a red flag.
+
+## On-demand questions
+
+If mentioned directly (@Compass), answer from state files only.
+Do not invent status. If status is unknown, say so.
+
+Examples:
+- "@Compass what's blocked?" → list open blockers from blockers.md
+- "@Compass what did we decide about X?" → search decisions.md
+- "@Compass who owns the landing page?" → search tasks.md
+- "@Compass what are our metrics?" → read metrics.md