openstoat 0.1.0

package/src/commands/task.ts

@@ -0,0 +1,254 @@
+/**
+ * Task commands: ls, create, claim, start, done, self-unblock, show
+ */
+
+import type { Argv } from 'yargs';
+import {
+  createTask,
+  getTask,
+  listTasks,
+  claimTask,
+  startTask,
+  completeTask,
+  selfUnblockTask,
+} from 'openstoat-core';
+import type { TaskStatus } from 'openstoat-types';
+
+export const taskCommands = {
+  command: 'task <action>',
+  describe:
+    'Manage tasks. Planner: ls before create, then create. Worker: claim → start → done. Self-unblock when blocked by human.',
+  builder: (yargs: Argv) =>
+    yargs
+      .command({
+        command: 'ls',
+        describe:
+          'List tasks. PLANNER: run before create to avoid duplicates. Use --status ready,in_progress for unfinished.',
+        builder: (y: Argv) =>
+          y
+            .option('project', {
+              type: 'string',
+              demandOption: true,
+              describe: 'Project ID (from project ls)',
+            })
+            .option('status', {
+              type: 'string',
+              describe: 'Filter by status (comma-separated: ready,in_progress,done)',
+            })
+            .option('owner', {
+              type: 'string',
+              describe: 'Filter by owner (agent_worker or human_worker)',
+            })
+            .option('json', {
+              type: 'boolean',
+              default: false,
+              describe: 'Output as JSON',
+            }),
+        handler: (argv: Record<string, unknown>) => {
+          const statusStr = argv.status as string | undefined;
+          const statuses: TaskStatus[] | undefined = statusStr
+            ? (statusStr.split(',').map((s) => s.trim()) as TaskStatus[])
+            : undefined;
+
+          const tasks = listTasks(argv.project as string, {
+            status: statuses,
+            owner: argv.owner as string | undefined,
+          });
+
+          if (argv.json) {
+            console.log(JSON.stringify(tasks, null, 2));
+          } else {
+            if (tasks.length === 0) {
+              console.log('No tasks found.');
+              return;
+            }
+            for (const t of tasks) {
+              console.log(`${t.id}\t${t.status}\t${t.owner}\t${t.title}`);
+            }
+          }
+        },
+      })
+      .command({
+        command: 'create',
+        describe:
+          'Create a task. All required: --project, --title, --description, --acceptance-criteria (×N), --status, --owner, --task-type. Use --depends-on for dependencies.',
+        builder: (y: Argv) =>
+          y
+            .option('project', { type: 'string', demandOption: true })
+            .option('title', { type: 'string', demandOption: true })
+            .option('description', { type: 'string', demandOption: true })
+            .option('acceptance-criteria', {
+              type: 'array',
+              demandOption: true,
+              describe: 'Pass multiple times: --acceptance-criteria "A" --acceptance-criteria "B"',
+            })
+            .option('depends-on', {
+              type: 'array',
+              default: [],
+              describe: 'Task IDs this task depends on; omit when no dependencies',
+            })
+            .option('status', {
+              type: 'string',
+              demandOption: true,
+              choices: ['ready', 'in_progress', 'done'],
+            })
+            .option('owner', {
+              type: 'string',
+              demandOption: true,
+              choices: ['agent_worker', 'human_worker'],
+            })
+            .option('task-type', {
+              type: 'string',
+              demandOption: true,
+              choices: ['implementation', 'testing', 'review', 'credentials', 'deploy', 'docs', 'custom'],
+              describe:
+                'implementation|testing|review|credentials|deploy|docs|custom. credentials/review/deploy often human_worker.',
+            })
+            .option('created-by', { type: 'string', describe: 'Creator role (e.g. agent_planner)' }),
+        handler: (argv: Record<string, unknown>) => {
+          const task = createTask({
+            project: argv.project as string,
+            title: argv.title as string,
+            description: argv.description as string,
+            acceptance_criteria: (argv['acceptance-criteria'] as string[]) || [],
+            depends_on: (argv['depends-on'] as string[]) || [],
+            status: argv.status as TaskStatus,
+            owner: argv.owner as 'agent_worker' | 'human_worker',
+            task_type: argv['task-type'] as any,
+            created_by: argv['created-by'] as string | undefined,
+          });
+          console.log(task.id);
+        },
+      })
+      .command({
+        command: 'claim <task_id>',
+        describe: 'WORKER: claim ready task. Moves ready→in_progress. Use --logs-append for audit.',
+        builder: (y: Argv) =>
+          y
+            .positional('task_id', { type: 'string', demandOption: true })
+            .option('as', {
+              type: 'string',
+              demandOption: true,
+              choices: ['agent_worker', 'human_worker'],
+            })
+            .option('logs-append', { type: 'string', describe: 'Append to task logs (required for agents)' }),
+        handler: (argv: Record<string, unknown>) => {
+          const task = claimTask(
+            argv.task_id as string,
+            argv.as as 'agent_worker' | 'human_worker',
+            argv['logs-append'] as string | undefined
+          );
+          console.log(`Claimed ${task.id}`);
+        },
+      })
+      .command({
+        command: 'start <task_id>',
+        describe: 'WORKER: start/continue task. Use --logs-append to record progress.',
+        builder: (y: Argv) =>
+          y
+            .positional('task_id', { type: 'string', demandOption: true })
+            .option('as', {
+              type: 'string',
+              demandOption: true,
+              choices: ['agent_worker', 'human_worker'],
+            })
+            .option('logs-append', { type: 'string' }),
+        handler: (argv: Record<string, unknown>) => {
+          const task = startTask(
+            argv.task_id as string,
+            argv.as as 'agent_worker' | 'human_worker',
+            argv['logs-append'] as string | undefined
+          );
+          console.log(`Started ${task.id}`);
+        },
+      })
+      .command({
+        command: 'done <task_id>',
+        describe: 'WORKER: complete task. Handoff mandatory (min 200 chars). Transfers context to downstream.',
+        builder: (y: Argv) =>
+          y
+            .positional('task_id', { type: 'string', demandOption: true })
+            .option('output', { type: 'string', demandOption: true, describe: 'What was delivered' })
+            .option('handoff-summary', {
+              type: 'string',
+              demandOption: true,
+              describe: 'Context for downstream tasks. Min 200 chars. No credentials in body.',
+            })
+            .option('logs-append', { type: 'string' })
+            .option('as', {
+              type: 'string',
+              demandOption: true,
+              choices: ['agent_worker', 'human_worker'],
+            }),
+        handler: (argv: Record<string, unknown>) => {
+          const task = completeTask(
+            argv.task_id as string,
+            {
+              output: argv.output as string,
+              handoff_summary: argv['handoff-summary'] as string,
+              logs_append: argv['logs-append'] as string | undefined,
+            },
+            argv.as as 'agent_worker' | 'human_worker'
+          );
+          console.log(`Done ${task.id}`);
+        },
+      })
+      .command({
+        command: 'self-unblock <task_id>',
+        describe:
+          'WORKER: rollback in_progress→ready when blocked. Must add --depends-on (human task). Create human task first.',
+        builder: (y: Argv) =>
+          y
+            .positional('task_id', { type: 'string', demandOption: true })
+            .option('depends-on', {
+              type: 'array',
+              demandOption: true,
+              describe: 'New human task ID(s) - at least one required',
+            })
+            .option('logs-append', { type: 'string' })
+            .option('as', {
+              type: 'string',
+              default: 'agent_worker',
+              choices: ['agent_worker'],
+            }),
+        handler: (argv: Record<string, unknown>) => {
+          const deps = argv['depends-on'] as string[];
+          const task = selfUnblockTask(
+            argv.task_id as string,
+            {
+              depends_on: deps,
+              logs_append: argv['logs-append'] as string | undefined,
+            },
+            'agent_worker'
+          );
+          console.log(`Self-unblocked ${task.id}`);
+        },
+      })
+      .command({
+        command: 'show <task_id>',
+        describe: 'Show task details. Use --json for machine-readable. Read handoff from dependent tasks.',
+        builder: (y: Argv) =>
+          y
+            .positional('task_id', { type: 'string', demandOption: true })
+            .option('json', { type: 'boolean', default: false }),
+        handler: (argv: Record<string, unknown>) => {
+          const task = getTask(argv.task_id as string);
+          if (!task) {
+            console.error(`Task '${argv.task_id}' not found.`);
+            process.exit(1);
+          }
+          console.log(argv.json ? JSON.stringify(task, null, 2) : formatTask(task));
+        },
+      })
+      .demandCommand(1, 'Specify ls, create, claim, start, done, self-unblock, or show'),
+  handler: () => {},
+};
+
+function formatTask(t: { id: string; title: string; status: string; owner: string; logs: string[] }): string {
+  let out = `ID: ${t.id}\nTitle: ${t.title}\nStatus: ${t.status}\nOwner: ${t.owner}\n`;
+  if (t.logs.length > 0) {
+    out += 'Logs:\n';
+    for (const log of t.logs) out += `  - ${log}\n`;
+  }
+  return out;
+}

package/src/index.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env bun
+/**
+ * OpenStoat CLI - Agent super-manual for task orchestration
+ * CLI is the operational guide for both agents and humans.
+ */
+
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { projectCommands } from './commands/project.js';
+import { taskCommands } from './commands/task.js';
+import { daemonCommands } from './commands/daemon.js';
+import { installCommands } from './commands/install.js';
+import { AGENT_MANUAL } from './agent-manual.js';
+
+const cli = yargs(hideBin(process.argv))
+  .scriptName('openstoat')
+  .usage(
+    'Usage: $0 <command> [options]\n\n' +
+      'OpenStoat orchestrates tasks between AI agents and humans. Local-first, CLI-first.\n' +
+      'Storage: ~/.openstoat/ (SQLite). No account/API Key required.\n\n' +
+      'WHEN TO USE: Planning work, creating tasks, claiming/executing tasks, handing off to humans,\n' +
+      'self-unblocking when blocked. Run \'openstoat manual\' for full agent operational manual.\n\n' +
+      'Commands:\n' +
+      '  project init       Initialize project (--id, --name, --template required)\n' +
+      '  project ls         List projects (get --project IDs for task commands)\n' +
+      '  project show <id>  Show project details\n' +
+      '  task ls            List tasks (PLANNER: run before create to avoid duplicates)\n' +
+      '  task create        Create task (all required: --project, --title, --description,\n' +
+      '                     --acceptance-criteria, --status, --owner, --task-type)\n' +
+      '  task claim <id>    WORKER: claim ready task (--as agent_worker|human_worker)\n' +
+      '  task start <id>    WORKER: start working (append to logs)\n' +
+      '  task done <id>     WORKER: complete (--output, --handoff-summary min 200 chars)\n' +
+      '  task self-unblock  WORKER: rollback when blocked (--depends-on human_task required)\n' +
+      '  task show <id>     Show task details\n' +
+      '  daemon init       Interactively create .openstoat.json\n' +
+      '  daemon start       Start worker daemon (polls for ready agent_worker tasks)\n' +
+      '  install skill      Install planner and worker skills (--here for current dir)\n' +
+      '  web                Start Web UI server (http://localhost:3080)\n' +
+      '  manual             Print full agent operational manual (SKILL-style)'
+  )
+  .command({
+    command: 'web',
+    describe: 'Start Web UI server. Opens http://localhost:3080 (set PORT env to change).',
+    handler: async () => {
+      await import('openstoat-web');
+    },
+  })
+  .command({
+    command: 'manual',
+    describe: 'Print full agent operational manual. Use when agent needs detailed workflow, rules, and examples.',
+    handler: () => {
+      console.log(AGENT_MANUAL.trim());
+    },
+  })
+  .command(projectCommands)
+  .command(taskCommands)
+  .command(daemonCommands)
+  .command(installCommands)
+  .demandCommand(1, 'Specify a command. Run openstoat --help or openstoat manual for details.')
+  .strict()
+  .help()
+  .alias('h', 'help')
+  .version('0.1.0')
+  .alias('v', 'version')
+  .epilog(
+    'RULES: (1) Planner must run task ls before create. (2) Handoff required on every done (min 200 chars). ' +
+      '(3) No generic status update; use claim/start/done/self-unblock only. (4) Self-unblock requires --depends-on.'
+  );
+
+cli.parse();

package/src/lib/installSkills.ts

@@ -0,0 +1,76 @@
+/**
+ * Install OpenStoat skills to .agent/skills and .claude/skills in the target directory.
+ * Used by `openstoat install skill` and when daemon starts.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+
+const require = createRequire(import.meta.url);
+
+const SKILL_NAMES = ['openstoat-planner', 'openstoat-worker'];
+const TARGET_DIRS_DEFAULT = ['.agent/skills', '.claude/skills'];
+const TARGET_DIRS_HERE = [''];
+
+/**
+ * Get the path to the openstoat-skills package skills directory.
+ */
+function getSkillsSourcePath(): string {
+  try {
+    // Resolve from openstoat-cli's node_modules (workspace or hoisted)
+    const pkgPath = require.resolve('openstoat-skills/package.json', {
+      paths: [path.dirname(fileURLToPath(import.meta.url))],
+    });
+    return path.join(path.dirname(pkgPath), 'skills');
+  } catch {
+    // Fallback: relative to this file (e.g. in monorepo packages/openstoat-cli)
+    const dir = path.dirname(fileURLToPath(import.meta.url));
+    return path.join(dir, '../../openstoat-skills/skills');
+  }
+}
+
+/**
+ * Copy a skill directory recursively.
+ */
+function copySkill(source: string, dest: string): void {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.cpSync(source, dest, { recursive: true });
+}
+
+export interface InstallSkillsOptions {
+  /** When true, install to current directory (no skills/, .agent, or .claude) */
+  here?: boolean;
+}
+
+/**
+ * Install OpenStoat skills to .agent/skills and .claude/skills, or current dir when here=true.
+ * @param targetRoot - Root directory (default: process.cwd())
+ * @param options - { here: true } to install to current directory (./openstoat-planner, ./openstoat-worker)
+ * @returns Paths where skills were installed
+ */
+export function installSkills(
+  targetRoot = process.cwd(),
+  options?: InstallSkillsOptions
+): string[] {
+  const sourcePath = getSkillsSourcePath();
+  const installed: string[] = [];
+  const targetDirs = options?.here ? TARGET_DIRS_HERE : TARGET_DIRS_DEFAULT;
+
+  for (const skillName of SKILL_NAMES) {
+    const skillSource = path.join(sourcePath, skillName);
+    if (!fs.existsSync(skillSource)) {
+      console.warn(`Skill not found: ${skillName} at ${skillSource}`);
+      continue;
+    }
+
+    for (const targetDir of targetDirs) {
+      const dest = path.join(targetRoot, targetDir, skillName);
+      copySkill(skillSource, dest);
+      installed.push(dest);
+    }
+  }
+
+  return installed;
+}

package/src/lib/prompt.ts

@@ -0,0 +1,17 @@
+/**
+ * Interactive prompt helper using readline.
+ */
+
+import { createInterface } from 'readline';
+
+export function prompt(question: string, defaultValue = ''): Promise<string> {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const suffix = defaultValue ? ` [${defaultValue}]` : '';
+    rl.question(`${question}${suffix}: `, (answer) => {
+      rl.close();
+      const trimmed = answer.trim();
+      resolve(trimmed || defaultValue);
+    });
+  });
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["node"]
+  },
+  "include": ["src/**/*"]
+}