openstoat 0.1.0

package/bin/openstoat

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import '../dist/index.js';

package/dist/agent-manual.d.ts

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

package/dist/agent-manual.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-manual.d.ts","sourceRoot":"","sources":["../src/agent-manual.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,YAAY,2uNA0JxB,CAAC"}

package/dist/agent-manual.js

@@ -0,0 +1,159 @@
+/**
+ * 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/dist/commands/daemon.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Daemon commands: start, stop, status, logs, init
+ * Worker daemon polls for ready agent_worker tasks and invokes external agents.
+ */
+import type { Argv } from 'yargs';
+export declare const daemonCommands: {
+    command: string;
+    describe: string;
+    builder: (yargs: Argv) => Argv<{}>;
+    handler: () => void;
+};
+//# sourceMappingURL=daemon.d.ts.map

package/dist/commands/daemon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../../src/commands/daemon.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC;AAOlC,eAAO,MAAM,cAAc;;;qBAGR,IAAI;;CAyEtB,CAAC"}

package/dist/commands/daemon.js

@@ -0,0 +1,82 @@
+/**
+ * Daemon commands: start, stop, status, logs, init
+ * Worker daemon polls for ready agent_worker tasks and invokes external agents.
+ */
+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) => 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 = {};
+            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) => y.option('poll-interval', {
+            type: 'number',
+            default: 5000,
+            describe: 'Poll interval in ms (default 5000)',
+        }),
+        handler: (argv) => {
+            console.log('Daemon starting...');
+            installSkills(process.cwd());
+            const pollInterval = argv['poll-interval'] || 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/dist/commands/install.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Install commands: skill
+ * Installs OpenStoat skills to .agent/skills and .claude/skills.
+ */
+import type { Argv } from 'yargs';
+export declare const installCommands: {
+    command: string;
+    describe: string;
+    builder: (yargs: Argv) => Argv<{}>;
+    handler: () => void;
+};
+//# sourceMappingURL=install.d.ts.map

package/dist/commands/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/commands/install.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC;AAGlC,eAAO,MAAM,eAAe;;;qBAGT,IAAI;;CAiCtB,CAAC"}

package/dist/commands/install.js

@@ -0,0 +1,40 @@
+/**
+ * Install commands: skill
+ * Installs OpenStoat skills to .agent/skills and .claude/skills.
+ */
+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) => yargs
+        .command({
+        command: 'skill',
+        describe: 'Install planner and worker skills. Use --here to install to current directory (no skills/, .agent, or .claude).',
+        builder: (y) => 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) => {
+            const targetRoot = argv.cwd || 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/dist/commands/project.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Project commands: init, ls, show
+ */
+import type { Argv } from 'yargs';
+export declare const projectCommands: {
+    command: string;
+    describe: string;
+    builder: (yargs: Argv) => Argv<{}>;
+    handler: () => void;
+};
+//# sourceMappingURL=project.d.ts.map

package/dist/commands/project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../src/commands/project.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC;AAGlC,eAAO,MAAM,eAAe;;;qBAGT,IAAI;;CA4DtB,CAAC"}

package/dist/commands/project.js

@@ -0,0 +1,62 @@
+/**
+ * Project commands: init, ls, show
+ */
+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) => yargs
+        .command({
+        command: 'init',
+        describe: 'Initialize project with bound template. Required before creating tasks.',
+        builder: (y) => 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) => {
+            const project = createProject(argv.id, argv.name, argv.template);
+            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) => y.positional('project_id', { type: 'string', demandOption: true }),
+        handler: (argv) => {
+            const project = getProject(argv.project_id);
+            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: () => { },
+};

package/dist/commands/task.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Task commands: ls, create, claim, start, done, self-unblock, show
+ */
+import type { Argv } from 'yargs';
+export declare const taskCommands: {
+    command: string;
+    describe: string;
+    builder: (yargs: Argv) => Argv<{}>;
+    handler: () => void;
+};
+//# sourceMappingURL=task.d.ts.map

package/dist/commands/task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/commands/task.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC;AAYlC,eAAO,MAAM,YAAY;;;qBAIN,IAAI;;CAgOtB,CAAC"}

package/dist/commands/task.js

@@ -0,0 +1,212 @@
+/**
+ * Task commands: ls, create, claim, start, done, self-unblock, show
+ */
+import { createTask, getTask, listTasks, claimTask, startTask, completeTask, selfUnblockTask, } from 'openstoat-core';
+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) => yargs
+        .command({
+        command: 'ls',
+        describe: 'List tasks. PLANNER: run before create to avoid duplicates. Use --status ready,in_progress for unfinished.',
+        builder: (y) => 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) => {
+            const statusStr = argv.status;
+            const statuses = statusStr
+                ? statusStr.split(',').map((s) => s.trim())
+                : undefined;
+            const tasks = listTasks(argv.project, {
+                status: statuses,
+                owner: argv.owner,
+            });
+            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) => 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) => {
+            const task = createTask({
+                project: argv.project,
+                title: argv.title,
+                description: argv.description,
+                acceptance_criteria: argv['acceptance-criteria'] || [],
+                depends_on: argv['depends-on'] || [],
+                status: argv.status,
+                owner: argv.owner,
+                task_type: argv['task-type'],
+                created_by: argv['created-by'],
+            });
+            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) => 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) => {
+            const task = claimTask(argv.task_id, argv.as, argv['logs-append']);
+            console.log(`Claimed ${task.id}`);
+        },
+    })
+        .command({
+        command: 'start <task_id>',
+        describe: 'WORKER: start/continue task. Use --logs-append to record progress.',
+        builder: (y) => 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) => {
+            const task = startTask(argv.task_id, argv.as, argv['logs-append']);
+            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) => 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) => {
+            const task = completeTask(argv.task_id, {
+                output: argv.output,
+                handoff_summary: argv['handoff-summary'],
+                logs_append: argv['logs-append'],
+            }, argv.as);
+            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) => 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) => {
+            const deps = argv['depends-on'];
+            const task = selfUnblockTask(argv.task_id, {
+                depends_on: deps,
+                logs_append: argv['logs-append'],
+            }, '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) => y
+            .positional('task_id', { type: 'string', demandOption: true })
+            .option('json', { type: 'boolean', default: false }),
+        handler: (argv) => {
+            const task = getTask(argv.task_id);
+            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) {
+    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/dist/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env bun
+/**
+ * OpenStoat CLI - Agent super-manual for task orchestration
+ * CLI is the operational guide for both agents and humans.
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG"}