openstoat 0.1.0

package/dist/index.js

@@ -0,0 +1,63 @@
+#!/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/dist/lib/installSkills.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Install OpenStoat skills to .agent/skills and .claude/skills in the target directory.
+ * Used by `openstoat install skill` and when daemon starts.
+ */
+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 declare function installSkills(targetRoot?: string, options?: InstallSkillsOptions): string[];
+//# sourceMappingURL=installSkills.d.ts.map

package/dist/lib/installSkills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"installSkills.d.ts","sourceRoot":"","sources":["../../src/lib/installSkills.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAsCH,MAAM,WAAW,oBAAoB;IACnC,+EAA+E;IAC/E,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,UAAU,SAAgB,EAC1B,OAAO,CAAC,EAAE,oBAAoB,GAC7B,MAAM,EAAE,CAoBV"}

package/dist/lib/installSkills.js

@@ -0,0 +1,60 @@
+/**
+ * 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() {
+    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, dest) {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.cpSync(source, dest, { recursive: true });
+}
+/**
+ * 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) {
+    const sourcePath = getSkillsSourcePath();
+    const installed = [];
+    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/dist/lib/prompt.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Interactive prompt helper using readline.
+ */
+export declare function prompt(question: string, defaultValue?: string): Promise<string>;
+//# sourceMappingURL=prompt.d.ts.map

package/dist/lib/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../src/lib/prompt.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,wBAAgB,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,SAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAU3E"}

package/dist/lib/prompt.js

@@ -0,0 +1,15 @@
+/**
+ * Interactive prompt helper using readline.
+ */
+import { createInterface } from 'readline';
+export function prompt(question, defaultValue = '') {
+    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/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "openstoat",
+  "version": "0.1.0",
+  "bin": {
+    "openstoat": "./bin/openstoat"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "start": "bun run src/index.ts"
+  },
+  "dependencies": {
+    "openstoat-core": "workspace:*",
+    "openstoat-daemon": "workspace:*",
+    "openstoat-skills": "workspace:*",
+    "openstoat-types": "workspace:*",
+    "openstoat-web": "workspace:*",
+    "yargs": "^17.7.2"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^20.0.0",
+    "@types/yargs": "^17.0.35",
+    "typescript": "^5.0.0"
+  }
+}

package/src/agent-manual.ts

@@ -0,0 +1,160 @@
+/**
+ * OpenStoat Agent Manual - SKILL-style documentation for AI agents
+ * Use when: orchestrating tasks, planning work, executing tasks, or handing off to humans.
+ */
+
+export const AGENT_MANUAL = `
+# OpenStoat CLI - Agent Operational Manual
+
+## When to Use
+
+Use OpenStoat when:
+- Planning and breaking down work into executable tasks
+- Creating tasks for agents or humans to execute
+- Claiming and executing tasks as an agent worker
+- Handing off work to humans (credentials, review, deploy)
+- Self-unblocking when blocked by human input
+- Querying task status, dependencies, or project context
+
+## Core Concepts
+
+| Concept | Description |
+|---------|-------------|
+| **Project** | Template-bound workspace. Every task belongs to one project. Get project ID via \`project ls\`. |
+| **Task** | Atomic work unit. Status: ready → in_progress → done. Owner: agent_worker | human_worker. |
+| **Handoff** | Required on every completion. Min 200 chars. Transfers context to downstream tasks. |
+| **Self-unblock** | When agent is blocked by human: create human task, then run self-unblock with --depends-on. |
+
+## Role-Based Workflows
+
+### Agent Planner
+
+1. **Before creating tasks** (mandatory): List existing tasks to avoid duplicates.
+   \`openstoat task ls --project <project_id> --status ready,in_progress\`
+
+2. **Create tasks**: Use \`task create\` with all required fields. Set owner=agent_worker for agent tasks, owner=human_worker for human tasks (credentials, review, deploy).
+
+3. **Dependencies**: Use --depends-on when task B waits for task A. Omit when no dependencies.
+
+### Agent Worker
+
+1. **Claim**: \`openstoat task claim <task_id> --as agent_worker --logs-append "..."\`
+2. **Start**: \`openstoat task start <task_id> --as agent_worker --logs-append "..."\`
+3. **Done**: \`openstoat task done <task_id> --output "..." --handoff-summary "..." --logs-append "..."\`
+   - handoff-summary: min 200 chars. Describe what was done and context for downstream.
+
+### Agent Worker (Blocked by Human)
+
+1. Create human task: \`openstoat task create --project X --owner human_worker --task-type credentials ...\`
+2. Self-unblock: \`openstoat task self-unblock <my_task_id> --depends-on <human_task_id> --logs-append "Blocked: ..."\`
+3. Task moves in_progress → ready. Resume after human completes the dependency.
+
+### Human Worker
+
+Same flow as Agent Worker but use --as human_worker when claiming/starting/done.
+
+---
+
+## Command Reference
+
+### project init
+Initialize a project with bound template. Required before creating tasks.
+  --id (required): Project ID. Use this as --project in task commands.
+  --name (required): Display name.
+  --template (required): Template name (e.g. checkout-default-v1).
+
+### project ls
+List all projects. Output: id, name, status.
+
+### project show <project_id>
+Show project details (JSON).
+
+### task ls
+List tasks. **Planner must run before create to avoid duplicates.**
+  --project (required): Project ID.
+  --status: Filter. Comma-separated: ready,in_progress,done.
+  --owner: Filter: agent_worker | human_worker.
+  --json: Output as JSON.
+
+### task create
+Create a task. All fields required except --depends-on, --created-by.
+  --project (required)
+  --title (required)
+  --description (required)
+  --acceptance-criteria (required, pass multiple): e.g. --acceptance-criteria "A" --acceptance-criteria "B"
+  --depends-on (optional, pass multiple): Task IDs this task depends on.
+  --status (required): ready | in_progress | done. New tasks typically ready.
+  --owner (required): agent_worker | human_worker
+  --task-type (required): implementation | testing | review | credentials | deploy | docs | custom
+  --created-by (optional): e.g. agent_planner
+
+### task claim <task_id>
+Worker claims a ready task. Moves ready → in_progress.
+  --as (required): agent_worker | human_worker
+  --logs-append (recommended for agents): Append to task logs.
+
+### task start <task_id>
+Worker starts working. Use after claim or to append progress.
+  --as (required): agent_worker | human_worker
+  --logs-append (optional): Append to task logs.
+
+### task done <task_id>
+Worker completes task. Moves in_progress → done. Handoff mandatory.
+  --output (required): What was delivered.
+  --handoff-summary (required, min 200 chars): Context for downstream tasks.
+  --logs-append (optional)
+  --as (required): agent_worker | human_worker
+
+### task self-unblock <task_id>
+Rollback in_progress → ready when blocked by human. Must add new --depends-on.
+  --depends-on (required, pass multiple): New human task ID(s). At least one.
+  --logs-append (optional)
+  --as: agent_worker only (default)
+
+### task show <task_id>
+Show task details. Use --json for machine-readable output.
+
+### daemon init
+Interactively create \`.openstoat.json\` (project, agent) in current directory.
+
+### daemon start
+Start worker daemon. Polls for ready agent_worker tasks and invokes external agents.
+  --poll-interval (default 5000): Poll interval in ms.
+  Config: read from \`.openstoat.json\` in current directory. Example: \`{ "project": "<project_id>", "agent": "/path/to/agent" }\`
+
+### daemon stop | status | logs
+Stop, check status, or view daemon logs.
+
+---
+
+## Rules (Do Not Violate)
+
+1. **No generic status update**: There is no \`task update --status\`. Use claim, start, done, self-unblock only.
+2. **Planner duplicate check**: Always run \`task ls\` before \`task create\` to avoid duplicates.
+3. **Handoff required**: Every \`task done\` must include --handoff-summary (min 200 chars).
+4. **Self-unblock guard**: in_progress → ready only via self-unblock, and only with new --depends-on.
+5. **Logs for agents**: Agent workers should use --logs-append on claim, start, done for audit trail.
+6. **Project required**: Every task has --project. Get project IDs from \`project ls\`.
+
+---
+
+## Examples
+
+# Planner: list then create
+openstoat task ls --project proj_1 --status ready,in_progress
+openstoat task create --project proj_1 --title "Add Paddle mapping" --description "..." \\
+  --acceptance-criteria "Mapping works" --acceptance-criteria "Tests pass" \\
+  --status ready --owner agent_worker --task-type implementation
+
+# Worker: full lifecycle
+openstoat task claim task_001 --as agent_worker --logs-append "Claimed"
+openstoat task start task_001 --as agent_worker --logs-append "Started"
+openstoat task done task_001 --output "Implemented" \\
+  --handoff-summary "Implemented Paddle mapping in src/payments/provider-map.ts. No migration. Integration tests pass. Downstream can use PaddleProvider class." \\
+  --as agent_worker --logs-append "Done"
+
+# Self-unblock (agent blocked, needs human)
+openstoat task create --project proj_1 --title "Provide API key" --description "..." \\
+  --acceptance-criteria "Key delivered" --status ready --owner human_worker --task-type credentials
+openstoat task self-unblock task_X --depends-on task_H --logs-append "Blocked: need API key"
+`;

package/src/commands/daemon.ts

@@ -0,0 +1,89 @@
+/**
+ * Daemon commands: start, stop, status, logs, init
+ * Worker daemon polls for ready agent_worker tasks and invokes external agents.
+ */
+
+import type { Argv } from 'yargs';
+import { startDaemon } from 'openstoat-daemon';
+import { listProjects } from 'openstoat-core';
+import { loadProjectConfig, saveProjectConfig } from 'openstoat-core';
+import { installSkills } from '../lib/installSkills.js';
+import { prompt } from '../lib/prompt.js';
+
+export const daemonCommands = {
+  command: 'daemon <action>',
+  describe: 'Worker daemon. Polls for ready agent_worker tasks and invokes external agents.',
+  builder: (yargs: Argv) =>
+    yargs
+      .command({
+        command: 'init',
+        describe: 'Interactively create .openstoat.json (project, agent) in current directory.',
+        handler: async () => {
+          const existing = loadProjectConfig();
+          const projects = listProjects();
+
+          console.log('Initialize OpenStoat daemon config (.openstoat.json)\n');
+
+          let project = existing?.project ?? '';
+          if (projects.length > 0) {
+            console.log('Existing projects:');
+            for (const p of projects) {
+              console.log(`  ${p.id}\t${p.name}`);
+            }
+            project = await prompt('Project ID', project);
+          } else {
+            console.log('No projects yet. Run `openstoat project init` first, or enter a project ID to use later.');
+            project = await prompt('Project ID', project);
+          }
+
+          const agent = await prompt('Agent executable path (for daemon to invoke)', existing?.agent ?? '');
+
+          const config: Record<string, string> = {};
+          if (project) config.project = project;
+          if (agent) config.agent = agent;
+
+          saveProjectConfig(config);
+          console.log('\nCreated .openstoat.json');
+          console.log(JSON.stringify(config, null, 2));
+        },
+      })
+      .command({
+        command: 'start',
+        describe: 'Start daemon. Polls for ready agent_worker tasks, invokes configured external agent.',
+        builder: (y: Argv) =>
+          y.option('poll-interval', {
+            type: 'number',
+            default: 5000,
+            describe: 'Poll interval in ms (default 5000)',
+          }),
+        handler: (argv: { 'poll-interval'?: number }) => {
+          console.log('Daemon starting...');
+          installSkills(process.cwd());
+          const pollInterval = (argv['poll-interval'] as number) || 5000;
+          startDaemon(pollInterval);
+        },
+      })
+      .command({
+        command: 'stop',
+        describe: 'Stop daemon',
+        handler: () => {
+          console.log('Daemon stop: run daemon in foreground and use Ctrl+C. PID file not implemented in MVP.');
+        },
+      })
+      .command({
+        command: 'status',
+        describe: 'Check daemon status',
+        handler: () => {
+          console.log('Daemon status: not running (PID file not implemented in MVP.');
+        },
+      })
+      .command({
+        command: 'logs',
+        describe: 'View daemon logs',
+        handler: () => {
+          console.log('Daemon logs: stdout/stderr when running.');
+        },
+      })
+      .demandCommand(1, 'Specify init, start, stop, status, or logs'),
+  handler: () => {},
+};

package/src/commands/install.ts

@@ -0,0 +1,45 @@
+/**
+ * Install commands: skill
+ * Installs OpenStoat skills to .agent/skills and .claude/skills.
+ */
+
+import type { Argv } from 'yargs';
+import { installSkills } from '../lib/installSkills.js';
+
+export const installCommands = {
+  command: 'install <target>',
+  describe: 'Install OpenStoat assets. Use "skill" to install planner and worker skills.',
+  builder: (yargs: Argv) =>
+    yargs
+      .command({
+        command: 'skill',
+        describe:
+          'Install planner and worker skills. Use --here to install to current directory (no skills/, .agent, or .claude).',
+        builder: (y: Argv) =>
+          y
+            .option('cwd', {
+              type: 'string',
+              default: process.cwd(),
+              describe: 'Target directory (default: current working directory)',
+            })
+            .option('here', {
+              type: 'boolean',
+              default: false,
+              describe: 'Install to current directory (./openstoat-planner, ./openstoat-worker)',
+            }),
+        handler: (argv: { cwd?: string; here?: boolean }) => {
+          const targetRoot = (argv.cwd as string) || process.cwd();
+          const installed = installSkills(targetRoot, { here: argv.here });
+          if (installed.length > 0) {
+            console.log('Installed skills to:');
+            for (const p of installed) {
+              console.log(`  ${p}`);
+            }
+          } else {
+            console.log('No skills installed.');
+          }
+        },
+      })
+      .demandCommand(1, 'Specify skill'),
+  handler: () => {},
+};

package/src/commands/project.ts

@@ -0,0 +1,71 @@
+/**
+ * Project commands: init, ls, show
+ */
+
+import type { Argv } from 'yargs';
+import { createProject, getProject, listProjects } from 'openstoat-core';
+
+export const projectCommands = {
+  command: 'project <action>',
+  describe: 'Manage projects. Each project is template-bound. Use project ID as --project in task commands.',
+  builder: (yargs: Argv) =>
+    yargs
+      .command({
+        command: 'init',
+        describe: 'Initialize project with bound template. Required before creating tasks.',
+        builder: (y: Argv) =>
+          y
+            .option('id', {
+              type: 'string',
+              demandOption: true,
+              describe: 'Project ID. Use this as --project in all task commands.',
+            })
+            .option('name', {
+              type: 'string',
+              demandOption: true,
+              describe: 'Display name',
+            })
+            .option('template', {
+              type: 'string',
+              demandOption: true,
+              describe: 'Template name (e.g. checkout-default-v1). Defines default owner per task_type.',
+            }),
+        handler: (argv: { id?: string; name?: string; template?: string; project_id?: string }) => {
+          const project = createProject(
+            argv.id as string,
+            argv.name as string,
+            argv.template as string
+          );
+          console.log(`Project initialized: ${project.id}`);
+        },
+      })
+      .command({
+        command: 'ls',
+        describe: 'List projects. Output: id, name, status. Get --project for task commands.',
+        handler: () => {
+          const projects = listProjects();
+          if (projects.length === 0) {
+            console.log('No projects found.');
+            return;
+          }
+          for (const p of projects) {
+            console.log(`${p.id}\t${p.name}\t${p.status}`);
+          }
+        },
+      })
+      .command({
+        command: 'show <project_id>',
+        describe: 'Show project details (JSON). Includes template_context.',
+        builder: (y: Argv) => y.positional('project_id', { type: 'string', demandOption: true }),
+        handler: (argv: { id?: string; name?: string; template?: string; project_id?: string }) => {
+          const project = getProject(argv.project_id as string);
+          if (!project) {
+            console.error(`Project '${argv.project_id}' not found.`);
+            process.exit(1);
+          }
+          console.log(JSON.stringify(project, null, 2));
+        },
+      })
+      .demandCommand(1, 'Specify init, ls, or show'),
+  handler: () => {},
+};