@web42/stask 0.1.5

package/README.md

@@ -0,0 +1,100 @@
+# stask
+
+SQLite-backed task lifecycle CLI with Slack sync — designed for AI agent teams.
+
+stask enforces a spec-first workflow where tasks flow through defined statuses (To-Do, In-Progress, Testing, Ready for Human Review, Done) with guards that prevent illegal transitions. A human approves specs and merges PRs; AI agents (Lead, Workers, QA) handle everything in between. Every mutation syncs bidirectionally with a Slack List.
+
+## Prerequisites
+
+- Node.js 20+
+- [GitHub CLI](https://cli.github.com/) (`gh`)
+- A Slack app with Lists API access (`SLACK_TOKEN`)
+
+## Install
+
+```bash
+npm install -g stask
+```
+
+## Setup
+
+1. Create the global data directory:
+
+```bash
+mkdir -p ~/.stask
+```
+
+2. Copy the example config and customize it:
+
+```bash
+cp config.example.json ~/.stask/config.json
+# Edit ~/.stask/config.json with your paths, Slack IDs, and agent names
+```
+
+3. Create a `.env` file with your Slack credentials:
+
+```bash
+cat > ~/.stask/.env << 'EOF'
+SLACK_TOKEN=xoxb-your-slack-bot-token
+LIST_ID=your-slack-list-id
+EOF
+```
+
+4. Run any command to initialize the database:
+
+```bash
+stask list
+```
+
+## Quick Start
+
+```bash
+# Create a task (uploads spec to Slack)
+stask create --spec specs/my-feature.md --name "Add login page"
+
+# Human approves (or via Slack checkbox)
+stask approve T-001
+
+# Lead creates subtasks and starts work
+stask subtask create --parent T-001 --name "Build form component" --assign worker-1
+stask transition T-001 In-Progress
+
+# Worker marks subtask done (after commit + push)
+stask subtask done T-001.1
+
+# QA submits verdict
+stask qa T-001 --report qa-reports/t001.md --verdict PASS
+
+# Lead creates PR, transitions to review
+stask transition T-001 "Ready for Human Review"
+
+# Human merges PR on GitHub -> task auto-completes
+```
+
+## Agent Integration
+
+The `skills/` folder contains role-specific documentation for AI agents:
+
+- **`skills/stask-general.md`** — Full framework overview, lifecycle, guards, CLI reference
+- **`skills/stask-lead.md`** — Lead agent workflow and decision trees
+- **`skills/stask-worker.md`** — Worker agent workflow and worktree rules
+- **`skills/stask-qa.md`** — QA agent testing workflow and report format
+
+Add the relevant skill file to your agent's context to teach it the stask workflow.
+
+## Config
+
+Config lives at `~/.stask/config.json`. See `config.example.json` for the full schema.
+
+| Field | Description |
+|-------|-------------|
+| `specsDir` | Directory where spec markdown files live |
+| `projectRepoPath` | Git repository for worktrees and PRs |
+| `worktreeBaseDir` | Where task worktrees are created |
+| `human` | Human reviewer (name, Slack ID, GitHub username) |
+| `agents` | Agent definitions (name, role, Slack user ID) |
+| `slack` | Slack List column IDs, status option IDs, type option IDs |
+
+## License
+
+MIT

package/bin/stask.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * stask — Unified task + Slack CLI for the OpenClaw agent team.
+ *
+ * Usage: stask <command> [args...]
+ *
+ * Commands:
+ *   create          Create a new task (uploads spec to Slack)
+ *   approve         Approve a task spec (reassign to Lead)
+ *   transition      Transition task status
+ *   subtask create  Create a subtask under a parent
+ *   subtask done    Mark a subtask as Done
+ *   qa              Submit QA verdict
+ *   heartbeat       Get pending work for an agent
+ *   list            List tasks (filterable)
+ *   show            Show task details
+ *   log             View audit log
+ *   pr-status     Poll PR for comments/merge
+ *   spec-update     Re-upload edited spec
+ *   session         Manage session locks (claim/release/status)
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { loadEnv, CONFIG } from '../lib/env.mjs';
+
+// Auto-load env before anything else
+loadEnv();
+
+// ─── Auto-start sync daemon (lazy guardian) ───────────────────────
+
+function ensureSyncDaemon() {
+  const pidFile = path.resolve(CONFIG.staskHome, 'sync-daemon.pid');
+  try {
+    const pid = parseInt(fs.readFileSync(pidFile, 'utf-8').trim(), 10);
+    process.kill(pid, 0); // Check if alive — throws if dead
+  } catch (_) {
+    // Not running — start it
+    import('../commands/sync-daemon.mjs').then(mod => {
+      mod.startDaemon();
+    }).catch(() => {});
+  }
+}
+
+// Don't auto-start for sync-daemon commands (avoid recursion) or read-only queries
+const _cmd = process.argv[2];
+if (_cmd && _cmd !== 'sync-daemon' && _cmd !== '--help' && _cmd !== '-h') {
+  ensureSyncDaemon();
+}
+
+// ─── Subcommand dispatch ───────────────────────────────────────────
+
+const COMMANDS = {
+  'create':         () => import('../commands/create.mjs'),
+  'approve':        () => import('../commands/approve.mjs'),
+  'transition':     () => import('../commands/transition.mjs'),
+  'subtask':        null, // nested — handled below
+  'qa':             () => import('../commands/qa.mjs'),
+  'heartbeat':      () => import('../commands/heartbeat.mjs'),
+  'list':           () => import('../commands/list.mjs'),
+  'show':           () => import('../commands/show.mjs'),
+  'log':            () => import('../commands/log.mjs'),
+  'pr-status':    () => import('../commands/pr-status.mjs'),
+  'spec-update':    () => import('../commands/spec-update.mjs'),
+  'session':        () => import('../commands/session.mjs'),
+  'delete':         () => import('../commands/delete.mjs'),
+  'assign':         () => import('../commands/assign.mjs'),
+  'sync':           () => import('../commands/sync.mjs'),
+  'sync-daemon':    () => import('../commands/sync-daemon.mjs'),
+};
+
+const SUBTASK_COMMANDS = {
+  'create': () => import('../commands/subtask-create.mjs'),
+  'done':   () => import('../commands/subtask-done.mjs'),
+};
+
+async function main() {
+  const args = process.argv.slice(2);
+  const cmd = args[0];
+
+  if (!cmd || cmd === '--help' || cmd === '-h') {
+    printHelp();
+    process.exit(0);
+  }
+
+  // Handle nested "subtask" commands
+  if (cmd === 'subtask') {
+    const subCmd = args[1];
+    if (!subCmd || !SUBTASK_COMMANDS[subCmd]) {
+      console.error(`Usage: stask subtask <create|done> [args...]`);
+      process.exit(1);
+    }
+    const mod = await SUBTASK_COMMANDS[subCmd]();
+    await mod.run(args.slice(2));
+    return;
+  }
+
+  // Run tests via `stask test [suite]`
+  if (cmd === 'test') {
+    const { execFileSync } = await import('child_process');
+    const { fileURLToPath } = await import('url');
+    const testDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../test');
+    const suite = args[1];
+    const pattern = suite ? `${testDir}/${suite}.test.mjs` : `${testDir}/*.test.mjs`;
+    try {
+      execFileSync(process.execPath, ['--test', pattern], { stdio: 'inherit' });
+    } catch (err) {
+      process.exit(err.status || 1);
+    }
+    return;
+  }
+
+  const loader = COMMANDS[cmd];
+  if (!loader) {
+    console.error(`Unknown command: ${cmd}`);
+    console.error(`Run "stask --help" for usage.`);
+    process.exit(1);
+  }
+
+  const mod = await loader();
+  await mod.run(args.slice(1));
+}
+
+function printHelp() {
+  console.log(`stask — Unified task + Slack CLI
+
+Usage: stask <command> [args...]
+
+Mutation commands (DB + Slack transaction):
+  create --spec <path> --name "..." [--type Feature|Bug|Task]
+  approve <task-id>
+  transition <task-id> <status>
+  subtask create --parent <id> --name "..." --assign <agent>
+  subtask done <subtask-id>
+  qa <task-id> --report <path> --verdict PASS|FAIL
+  assign <task-id> <name>
+  spec-update <task-id> --spec <path>
+
+Read-only commands:
+  list [--status X] [--assignee Y] [--parent Z] [--json]
+  show <task-id> [--log]
+  log [<task-id>] [--limit N]
+  heartbeat <agent-name>
+  pr-status <task-id>
+  session claim|release|status <task-id> [--agent X] [--session-id Y]
+
+Sync commands:
+  sync                          Run one bidirectional sync cycle
+  sync-daemon start|stop|status Manage background sync daemon
+`);
+}
+
+main().catch(err => {
+  console.error(`FATAL: ${err.message}`);
+  process.exit(1);
+});

package/commands/approve.mjs

@@ -0,0 +1,43 @@
+/**
+ * stask approve — Human approves task spec, reassigns to Lead.
+ *
+ * Usage: stask approve <task-id>
+ */
+
+import { CONFIG, getWorkspaceLibs } from '../lib/env.mjs';
+import { withTransaction } from '../lib/tx.mjs';
+import { syncTaskToSlack } from '../lib/slack-row.mjs';
+import { getLeadAgent } from '../lib/roles.mjs';
+
+export async function run(argv) {
+  const taskId = argv[0];
+
+  if (!taskId) {
+    console.error('Usage: stask approve <task-id>');
+    process.exit(1);
+  }
+
+  const leadName = getLeadAgent();
+  if (!leadName) { console.error('ERROR: No agent with role "lead" in config.'); process.exit(1); }
+
+  const result = await withTransaction(
+    (db, libs) => {
+      const task = libs.trackerDb.findTask(taskId);
+      if (!task) throw new Error(`Task ${taskId} not found`);
+      if (task['Status'] !== 'To-Do') throw new Error(`${taskId} is "${task['Status']}". Must be "To-Do" to approve.`);
+      if (task['Assigned To'] !== CONFIG.human.name) throw new Error(`${taskId} is assigned to ${task['Assigned To']}, not ${CONFIG.human.name}.`);
+
+      libs.trackerDb.updateTask(taskId, { assigned_to: leadName });
+      libs.trackerDb.addLogEntry(taskId, `${taskId} "${task['Task Name']}": Spec approved by ${CONFIG.human.name}. Assigned: ${leadName}.`);
+
+      const updated = libs.trackerDb.findTask(taskId);
+      return { taskId, taskRow: updated, taskName: task['Task Name'] };
+    },
+    async ({ taskRow }, db) => {
+      const { slackOps } = await syncTaskToSlack(db, taskRow);
+      return slackOps;
+    }
+  );
+
+  console.log(`${taskId}: "${result.taskName}" | Spec approved | Assigned: ${leadName}`);
+}

package/commands/assign.mjs

@@ -0,0 +1,64 @@
+/**
+ * assign.mjs — Reassign a task to an agent or human.
+ *
+ * Usage: stask assign <task-id> <name>
+ *
+ * Useful for assigning to bot/app users (Richard, Gilfoyle, etc.)
+ * which can't be done through Slack's UI user picker.
+ * Syncs the change to Slack automatically.
+ */
+
+import { CONFIG, getWorkspaceLibs } from '../lib/env.mjs';
+import { getSlackUserId } from '../lib/roles.mjs';
+import { syncTaskToSlack, getSlackRowId } from '../lib/slack-row.mjs';
+
+export async function run(argv) {
+  const taskId = argv[0];
+  const name = argv[1];
+
+  if (!taskId || !name) {
+    console.error('Usage: stask assign <task-id> <name>');
+    console.error('');
+    console.error('Available names:');
+    console.error(`  ${CONFIG.human.name} (human)`);
+    for (const [agent, info] of Object.entries(CONFIG.agents)) {
+      console.error(`  ${agent.charAt(0).toUpperCase() + agent.slice(1)} (${info.role})`);
+    }
+    process.exit(1);
+  }
+
+  const libs = await getWorkspaceLibs();
+  const db = libs.trackerDb.getDb();
+
+  const task = libs.trackerDb.findTask(taskId);
+  if (!task) {
+    console.error(`ERROR: Task ${taskId} not found`);
+    process.exit(1);
+  }
+
+  // Validate the name resolves to a known Slack user
+  const displayName = name.charAt(0).toUpperCase() + name.slice(1);
+  const slackUserId = getSlackUserId(displayName);
+  if (!slackUserId) {
+    console.error(`ERROR: Unknown user "${name}". Available: ${CONFIG.human.name}, ${Object.keys(CONFIG.agents).map(n => n.charAt(0).toUpperCase() + n.slice(1)).join(', ')}`);
+    process.exit(1);
+  }
+
+  const oldAssignee = task['Assigned To'];
+  if (oldAssignee === displayName) {
+    console.log(`${taskId} is already assigned to ${displayName}`);
+    return;
+  }
+
+  // Update DB
+  libs.trackerDb.updateTaskDirect(taskId, { assigned_to: displayName });
+  libs.trackerDb.addLogEntry(taskId, `Reassigned: ${oldAssignee} → ${displayName}`);
+
+  // Push to Slack
+  const updatedTask = libs.trackerDb.findTask(taskId);
+  const parentId = updatedTask['Parent'];
+  const parentRowId = (parentId && parentId !== 'None') ? getSlackRowId(db, parentId) : null;
+  await syncTaskToSlack(db, updatedTask, parentRowId);
+
+  console.log(`${taskId}: ${oldAssignee} → ${displayName} (synced to Slack)`);
+}

package/commands/create.mjs

@@ -0,0 +1,88 @@
+/**
+ * stask create — Create a new task (uploads spec to Slack).
+ *
+ * Usage: stask create --spec <spec-path> --name "Task Name" [--type Feature|Task|Bug]
+ */
+
+import path from 'path';
+import fs from 'fs';
+import { createHash } from 'crypto';
+import { CONFIG, getWorkspaceLibs } from '../lib/env.mjs';
+import { withTransaction } from '../lib/tx.mjs';
+import { syncTaskToSlack } from '../lib/slack-row.mjs';
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--spec' && argv[i + 1]) args.spec = argv[++i];
+    else if (argv[i] === '--name' && argv[i + 1]) args.name = argv[++i];
+    else if (argv[i] === '--type' && argv[i + 1]) args.type = argv[++i];
+  }
+  return args;
+}
+
+export async function run(argv) {
+  const args = parseArgs(argv);
+
+  if (!args.spec || !args.name) {
+    console.error('Usage: stask create --spec <spec-path> --name "Task Name" [--type Feature|Task|Bug]');
+    process.exit(1);
+  }
+
+  const libs = await getWorkspaceLibs();
+  const ws = CONFIG.specsDir;
+  const relPath = args.spec.startsWith('shared/') ? args.spec : path.relative(ws, path.resolve(args.spec));
+  const fullPath = path.resolve(ws, relPath);
+
+  // Validate spec exists
+  libs.validate.validateSpecExists(relPath);
+
+  // Ensure spec is uploaded to Slack
+  const registry = libs.fileUploader.loadRegistry(CONFIG.registryPath);
+  let fileId;
+  const content = fs.readFileSync(fullPath, 'utf-8');
+  const hash = createHash('sha256').update(content).digest('hex').slice(0, 16);
+  const existing = registry.files[relPath];
+
+  if (existing && existing.hash === hash && existing.fileId) {
+    fileId = existing.fileId;
+  } else {
+    const filename = path.basename(relPath);
+    fileId = await libs.slackApi.uploadFile(filename, content);
+    registry.files[relPath] = {
+      fileId, hash, title: filename,
+      uploadedAt: new Date().toISOString(),
+      sizeBytes: Buffer.byteLength(content, 'utf-8'),
+    };
+    libs.fileUploader.saveRegistry(CONFIG.registryPath, registry);
+    console.error(`Uploaded spec to Slack: ${fileId}`);
+  }
+
+  const result = await withTransaction(
+    (db, libs) => {
+      const taskId = libs.trackerDb.getNextTaskId();
+      const specName = relPath.replace(/^shared\//, '');
+      const specValue = libs.validate.formatSpecValue(specName, fileId);
+
+      libs.trackerDb.insertTask({
+        task_id: taskId,
+        task_name: args.name,
+        status: 'To-Do',
+        assigned_to: CONFIG.human.name,
+        spec: specValue,
+        type: args.type || 'Feature',
+      });
+
+      libs.trackerDb.addLogEntry(taskId, `${taskId} "${args.name}" created. Spec: ${specValue}. Status: To-Do → ${CONFIG.human.name}.`);
+
+      const taskRow = libs.trackerDb.findTask(taskId);
+      return { taskId, taskRow, specValue };
+    },
+    async ({ taskRow }, db) => {
+      const { slackOps } = await syncTaskToSlack(db, taskRow);
+      return slackOps;
+    }
+  );
+
+  console.log(`Created ${result.taskId}: "${args.name}" | Status: To-Do | Assigned: ${CONFIG.human.name} | Spec: ${fileId}`);
+}

package/commands/delete.mjs

@@ -0,0 +1,127 @@
+/**
+ * stask delete — Delete a task (and its subtasks) from DB and Slack.
+ *
+ * Usage: stask delete <task-id> [--force]
+ *
+ * Deletes the task, its subtasks, all log entries, session claims,
+ * and Slack rows — atomically. Refuses to delete In-Progress or Testing
+ * tasks unless --force is passed.
+ */
+
+import { CONFIG, getWorkspaceLibs } from '../lib/env.mjs';
+import { getSlackRowId } from '../lib/slack-row.mjs';
+
+export async function run(argv) {
+  const taskId = argv[0];
+  const force = argv.includes('--force');
+
+  if (!taskId) {
+    console.error('Usage: stask delete <task-id> [--force]');
+    process.exit(1);
+  }
+
+  const libs = await getWorkspaceLibs();
+  const db = libs.trackerDb.getDb();
+  const listId = CONFIG.slack.listId;
+
+  const task = libs.trackerDb.findTask(taskId);
+  if (!task) { console.error(`ERROR: Task ${taskId} not found`); process.exit(1); }
+
+  // Safety check — don't delete active work without --force
+  const activeStatuses = ['In-Progress', 'Testing', 'Ready for Human Review'];
+  if (activeStatuses.includes(task['Status']) && !force) {
+    console.error(`ERROR: ${taskId} is "${task['Status']}". Use --force to delete active tasks.`);
+    process.exit(1);
+  }
+
+  // Collect all task IDs to delete (parent + subtasks)
+  const subtasks = libs.trackerDb.getSubtasks(taskId);
+  const allIds = [taskId, ...subtasks.map(s => s['Task ID'])];
+
+  // Phase 1: Delete Slack rows (while we still have row IDs)
+  let slackDeleted = 0;
+  for (const id of allIds) {
+    const rowId = getSlackRowId(db, id);
+    if (rowId) {
+      try {
+        await libs.slackApi.deleteListRow(listId, rowId);
+        slackDeleted++;
+      } catch (err) {
+        console.error(`WARNING: Could not delete Slack row for ${id}: ${err.message}`);
+      }
+    }
+  }
+
+  // Phase 2: Delete from DB (drop triggers temporarily)
+  db.exec('DROP TRIGGER IF EXISTS validate_status_transition');
+  db.exec('DROP TRIGGER IF EXISTS log_no_delete');
+  db.exec('DROP TRIGGER IF EXISTS log_no_update');
+  db.exec('DROP TRIGGER IF EXISTS enforce_in_progress_requirements');
+  db.exec('DROP TRIGGER IF EXISTS enforce_ready_for_review_requirements');
+  db.exec('DROP TRIGGER IF EXISTS update_timestamp');
+
+  try {
+    db.exec('BEGIN');
+    for (const id of allIds) {
+      db.prepare('DELETE FROM slack_row_ids WHERE task_id = ?').run(id);
+      db.prepare('DELETE FROM active_sessions WHERE task_id = ?').run(id);
+      db.prepare('DELETE FROM log WHERE task_id = ?').run(id);
+    }
+    // Delete subtasks first (FK constraint), then parent
+    for (const sub of subtasks) {
+      db.prepare('DELETE FROM tasks WHERE task_id = ?').run(sub['Task ID']);
+    }
+    db.prepare('DELETE FROM tasks WHERE task_id = ?').run(taskId);
+    db.exec('COMMIT');
+  } catch (err) {
+    db.exec('ROLLBACK');
+    throw err;
+  } finally {
+    // Restore all triggers
+    db.exec(`
+      CREATE TRIGGER IF NOT EXISTS validate_status_transition
+      BEFORE UPDATE OF status ON tasks WHEN OLD.status != NEW.status
+      BEGIN SELECT CASE
+        WHEN OLD.status = 'Done' THEN RAISE(ABORT, 'Cannot transition from Done (terminal state)')
+        WHEN OLD.status = 'To-Do' AND NEW.status NOT IN ('In-Progress','Blocked') THEN RAISE(ABORT, 'To-Do can only transition to In-Progress or Blocked')
+        WHEN OLD.status = 'In-Progress' AND NEW.status NOT IN ('Testing','Blocked') THEN RAISE(ABORT, 'In-Progress can only transition to Testing or Blocked')
+        WHEN OLD.status = 'Testing' AND NEW.status NOT IN ('Ready for Human Review','In-Progress','Blocked') THEN RAISE(ABORT, 'Testing can only transition to Ready for Human Review, In-Progress, or Blocked')
+        WHEN OLD.status = 'Ready for Human Review' AND NEW.status NOT IN ('Done','In-Progress','Blocked') THEN RAISE(ABORT, 'Ready for Human Review can only transition to Done, In-Progress, or Blocked')
+        WHEN OLD.status = 'Blocked' AND NEW.status NOT IN ('To-Do','In-Progress','Testing','Ready for Human Review') THEN RAISE(ABORT, 'Blocked can transition to To-Do, In-Progress, Testing, or Ready for Human Review')
+      END; END;
+
+      CREATE TRIGGER IF NOT EXISTS log_no_update BEFORE UPDATE ON log
+      BEGIN SELECT RAISE(ABORT, 'Log entries are immutable'); END;
+
+      CREATE TRIGGER IF NOT EXISTS log_no_delete BEFORE DELETE ON log
+      BEGIN SELECT RAISE(ABORT, 'Log entries cannot be deleted'); END;
+
+      CREATE TRIGGER IF NOT EXISTS enforce_in_progress_requirements
+      BEFORE UPDATE OF status ON tasks
+      WHEN NEW.status = 'In-Progress' AND OLD.status = 'To-Do' AND NEW.parent_id IS NULL
+      BEGIN SELECT CASE
+        WHEN NEW.worktree IS NULL OR NEW.worktree = '' THEN
+          RAISE(ABORT, 'Parent task requires a worktree before moving to In-Progress')
+      END; END;
+
+      CREATE TRIGGER IF NOT EXISTS enforce_ready_for_review_requirements
+      BEFORE UPDATE OF status ON tasks
+      WHEN NEW.status = 'Ready for Human Review' AND NEW.parent_id IS NULL
+      BEGIN SELECT CASE
+        WHEN NEW.qa_fail_count = 0 AND (NEW.qa_report_1 IS NULL OR NEW.qa_report_1 = '') THEN RAISE(ABORT, 'QA Report (attempt 1) required before Ready for Human Review')
+        WHEN NEW.qa_fail_count = 1 AND (NEW.qa_report_2 IS NULL OR NEW.qa_report_2 = '') THEN RAISE(ABORT, 'QA Report (attempt 2) required before Ready for Human Review')
+        WHEN NEW.qa_fail_count = 2 AND (NEW.qa_report_3 IS NULL OR NEW.qa_report_3 = '') THEN RAISE(ABORT, 'QA Report (attempt 3) required before Ready for Human Review')
+        WHEN NEW.worktree IS NULL OR NEW.worktree = '' THEN RAISE(ABORT, 'Worktree required before Ready for Human Review')
+        WHEN NEW.pr IS NULL OR NEW.pr = '' THEN RAISE(ABORT, 'Draft PR required before Ready for Human Review')
+      END; END;
+
+      CREATE TRIGGER IF NOT EXISTS update_timestamp
+      AFTER UPDATE ON tasks
+      BEGIN UPDATE tasks SET updated_at = datetime('now') WHERE task_id = NEW.task_id; END;
+    `);
+  }
+
+  const subCount = subtasks.length;
+  const subMsg = subCount > 0 ? ` + ${subCount} subtask(s)` : '';
+  console.log(`Deleted ${taskId}: "${task['Task Name']}"${subMsg} | DB: ${allIds.length} row(s) | Slack: ${slackDeleted} row(s)`);
+}