@agentic-coding-framework/orchestrator-core 0.1.0

package/dist/cli.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * cli.ts — CLI entry point for the Agentic Coding Orchestrator
+ *
+ * Commands:
+ *   init <project-root> <project-name>          Initialize .ai/STATE.json
+ *   start-story <project-root> <story-id>       Begin a new User Story (micro-waterfall)
+ *   start-custom <project-root> <instruction>   Begin a custom ad-hoc task
+ *   dispatch <project-root>                     Dispatch next step (prints prompt)
+ *   apply-handoff <project-root>                Parse HANDOFF.md → update STATE
+ *   approve <project-root> [note]               Approve review step
+ *   reject <project-root> <reason> [note]       Reject review step
+ *   status <project-root>                       Print current STATE.json
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * cli.ts — CLI entry point for the Agentic Coding Orchestrator
+ *
+ * Commands:
+ *   init <project-root> <project-name>          Initialize .ai/STATE.json
+ *   start-story <project-root> <story-id>       Begin a new User Story (micro-waterfall)
+ *   start-custom <project-root> <instruction>   Begin a custom ad-hoc task
+ *   dispatch <project-root>                     Dispatch next step (prints prompt)
+ *   apply-handoff <project-root>                Parse HANDOFF.md → update STATE
+ *   approve <project-root> [note]               Approve review step
+ *   reject <project-root> <reason> [note]       Reject review step
+ *   status <project-root>                       Print current STATE.json
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const path_1 = require("path");
+const child_process_1 = require("child_process");
+const state_1 = require("./state");
+const dispatch_1 = require("./dispatch");
+const [, , command, ...args] = process.argv;
+function usage() {
+    console.error(`Usage: orchestrator <command> [args]
+
+Commands:
+  init <project-root> <project-name>              Initialize .ai/STATE.json
+  start-story <project-root> <story-id>           Begin a new User Story (micro-waterfall)
+  start-custom <project-root> <instruction>       Begin a custom ad-hoc task
+  dispatch <project-root>                         Dispatch next step (prints prompt to stdout)
+  apply-handoff <project-root>           Parse HANDOFF.md → update STATE.json
+  post-check <project-root>              Run step's post_check command
+  approve <project-root> [note]          Approve review step
+  reject <project-root> <reason> [note]  Reject review step
+  status <project-root>                  Print current STATE.json
+  query <project-root>                   Project status summary (for OpenClaw)
+  detect <project-root>                  Check if project uses the framework
+  list-projects <workspace-root>         List all projects in workspace
+`);
+    process.exit(1);
+}
+function resolveRoot(raw) {
+    if (!raw) {
+        console.error("Error: <project-root> is required");
+        process.exit(1);
+    }
+    return (0, path_1.resolve)(raw);
+}
+try {
+    switch (command) {
+        case "init": {
+            const projectRoot = resolveRoot(args[0]);
+            const projectName = args[1];
+            if (!projectName) {
+                console.error("Error: <project-name> is required");
+                process.exit(1);
+            }
+            const { created, state } = (0, state_1.initState)(projectRoot, projectName);
+            if (created) {
+                console.log(`Initialized .ai/STATE.json for "${projectName}"`);
+            }
+            else {
+                console.log(`STATE.json already exists (step: ${state.step}, status: ${state.status})`);
+            }
+            break;
+        }
+        case "start-story": {
+            const projectRoot = resolveRoot(args[0]);
+            const storyId = args[1];
+            if (!storyId) {
+                console.error("Error: <story-id> is required");
+                process.exit(1);
+            }
+            const state = (0, dispatch_1.startStory)(projectRoot, storyId);
+            console.log(`Started story ${storyId} (step: ${state.step}, attempt: ${state.attempt})`);
+            break;
+        }
+        case "start-custom": {
+            const projectRoot = resolveRoot(args[0]);
+            const instruction = args[1];
+            if (!instruction) {
+                console.error("Error: <instruction> is required");
+                console.error('Example: orchestrator start-custom ./project "Refactor auth module into separate package"');
+                process.exit(1);
+            }
+            const label = args[2] || undefined; // optional label
+            const state = (0, dispatch_1.startCustom)(projectRoot, instruction, label);
+            console.log(`Started custom task: "${instruction}"`);
+            console.log(`  label: ${state.story}, step: ${state.step}, task_type: ${state.task_type}`);
+            break;
+        }
+        case "dispatch": {
+            const projectRoot = resolveRoot(args[0]);
+            const result = (0, dispatch_1.dispatch)(projectRoot);
+            switch (result.type) {
+                case "dispatched":
+                    // Print prompt to stdout (can be piped to claude -p)
+                    console.log(result.prompt);
+                    // Print metadata to stderr so it doesn't pollute prompt
+                    console.error(`[dispatch] step=${result.step} attempt=${result.attempt}`);
+                    break;
+                case "done":
+                    console.error(`[dispatch] DONE: ${result.summary}`);
+                    break;
+                case "needs_human":
+                    console.error(`[dispatch] NEEDS HUMAN REVIEW`);
+                    console.error(result.message);
+                    break;
+                case "blocked":
+                    console.error(`[dispatch] BLOCKED: ${result.reason}`);
+                    process.exit(1);
+                    break;
+                case "already_running":
+                    console.error(`[dispatch] Already running (${result.elapsed_min} min)`);
+                    break;
+                case "timeout":
+                    console.error(`[dispatch] TIMEOUT at ${result.step} (${result.elapsed_min} min)`);
+                    process.exit(1);
+                    break;
+            }
+            break;
+        }
+        case "apply-handoff": {
+            const projectRoot = resolveRoot(args[0]);
+            const state = (0, dispatch_1.applyHandoff)(projectRoot);
+            console.log(`Applied HANDOFF → step: ${state.step}, status: ${state.status}, reason: ${state.reason ?? "(none)"}`);
+            if (state.tests) {
+                console.log(`  tests: pass=${state.tests.pass} fail=${state.tests.fail} skip=${state.tests.skip}`);
+            }
+            break;
+        }
+        case "post-check": {
+            const projectRoot = resolveRoot(args[0]);
+            const passed = (0, dispatch_1.runPostCheck)(projectRoot, child_process_1.execSync);
+            console.log(passed ? "post_check: PASSED" : "post_check: FAILED");
+            if (!passed)
+                process.exit(1);
+            break;
+        }
+        case "approve": {
+            const projectRoot = resolveRoot(args[0]);
+            const note = args[1] || undefined;
+            (0, dispatch_1.approveReview)(projectRoot, note);
+            console.log(`Review approved${note ? ` (note: "${note}")` : ""}`);
+            break;
+        }
+        case "reject": {
+            const projectRoot = resolveRoot(args[0]);
+            const reason = args[1];
+            if (!reason) {
+                console.error("Error: <reason> is required (constitution_violation, needs_clarification, nfr_missing, scope_warning, test_timeout)");
+                process.exit(1);
+            }
+            const note = args[2] || undefined;
+            (0, dispatch_1.rejectReview)(projectRoot, reason, note);
+            console.log(`Review rejected (reason: ${reason}${note ? `, note: "${note}"` : ""})`);
+            break;
+        }
+        case "status": {
+            const projectRoot = resolveRoot(args[0]);
+            const state = (0, state_1.readState)(projectRoot);
+            console.log(JSON.stringify(state, null, 2));
+            break;
+        }
+        case "query": {
+            const projectRoot = resolveRoot(args[0]);
+            const status = (0, dispatch_1.queryProjectStatus)(projectRoot);
+            console.log(JSON.stringify(status, null, 2));
+            break;
+        }
+        case "detect": {
+            const projectRoot = resolveRoot(args[0]);
+            const result = (0, dispatch_1.detectFramework)(projectRoot);
+            console.log(JSON.stringify(result, null, 2));
+            const levelNames = ["Not adopted", "Partial adoption", "Full adoption"];
+            console.error(`Framework adoption: Level ${result.level} — ${levelNames[result.level]}`);
+            break;
+        }
+        case "list-projects": {
+            const workspaceRoot = resolveRoot(args[0]);
+            const projects = (0, dispatch_1.listProjects)(workspaceRoot);
+            if (projects.length === 0) {
+                console.log("No projects found with .ai/STATE.json");
+            }
+            else {
+                console.log(JSON.stringify(projects, null, 2));
+            }
+            break;
+        }
+        default:
+            if (command) {
+                console.error(`Unknown command: ${command}`);
+            }
+            usage();
+    }
+}
+catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+}

package/dist/dispatch.d.ts

@@ -0,0 +1,192 @@
+/**
+ * dispatch.ts — Orchestrator State Machine + Prompt Builder + Handoff Parser
+ *
+ * The only file with logic. Combines state.ts (read/write) and rules.ts (lookup)
+ * to drive the micro-waterfall pipeline. All decisions are deterministic —
+ * zero LLM tokens.
+ *
+ * Main entry point: dispatch(projectRoot)
+ */
+import { type State, type Step, type Status, type Reason } from "./state";
+import { type StepRule } from "./rules";
+export type DispatchResult = {
+    type: "dispatched";
+    step: Step;
+    attempt: number;
+    prompt: string;
+    fw_lv: 0 | 1 | 2;
+} | {
+    type: "blocked";
+    step: Step;
+    reason: string;
+} | {
+    type: "needs_human";
+    step: Step;
+    message: string;
+} | {
+    type: "done";
+    story: string;
+    summary: string;
+} | {
+    type: "already_running";
+    step: Step;
+    elapsed_min: number;
+} | {
+    type: "timeout";
+    step: Step;
+    elapsed_min: number;
+};
+/**
+ * Core dispatch logic — direct translation of Protocol's dispatch(project).
+ *
+ * Reads STATE.json, applies the step rules table, and returns a DispatchResult
+ * telling the caller what to do next. The caller is responsible for actually
+ * invoking the executor (e.g., spawning a Claude Code session).
+ *
+ * This function updates STATE.json as a side effect (marks running, advances
+ * steps, etc.).
+ */
+export declare function dispatch(projectRoot: string): DispatchResult;
+/**
+ * Build the dispatch prompt from the template.
+ * Pure template filling — zero LLM reasoning.
+ */
+export declare function buildPrompt(state: State, rule: StepRule): string;
+/** Parsed result from HANDOFF.md's YAML front matter */
+export interface HandoffResult {
+    story: string | null;
+    step: string | null;
+    attempt: number | null;
+    status: Status | null;
+    reason: Reason | null;
+    files_changed: string[];
+    tests_pass: number | null;
+    tests_fail: number | null;
+    tests_skip: number | null;
+    /** The markdown body (everything after the second ---) */
+    body: string;
+}
+/**
+ * Parse HANDOFF.md — prioritize YAML front matter, fallback to grep.
+ * Direct translation of Protocol's hook pseudocode.
+ */
+export declare function parseHandoff(projectRoot: string): HandoffResult | null;
+/**
+ * After executor exits, read HANDOFF.md and update STATE.json accordingly.
+ * This is the TypeScript equivalent of the Protocol's post-execution hook.
+ *
+ * Call this after the executor process exits, before the next dispatch().
+ */
+export declare function applyHandoff(projectRoot: string): State;
+/**
+ * Run the post_check command for the current step.
+ * Returns true if check passed (or no check defined), false if failed.
+ *
+ * This is a synchronous shell execution — zero LLM tokens.
+ */
+export declare function runPostCheck(projectRoot: string, execSync: (cmd: string, opts: object) => Buffer): boolean;
+/**
+ * Mark the review step as approved by human.
+ * Optionally attach a human note (modification requests, clarifications).
+ */
+export declare function approveReview(projectRoot: string, humanNote?: string): void;
+/**
+ * Reject the review with a reason and optional note.
+ */
+export declare function rejectReview(projectRoot: string, reason: Reason, humanNote?: string): void;
+/**
+ * Begin a new User Story. Resets state to bdd step with attempt 1.
+ * Auto-initializes STATE.json if the project hasn't adopted the framework yet.
+ */
+export declare function startStory(projectRoot: string, storyId: string): State;
+/**
+ * Get a human-friendly project status summary.
+ * OpenClaw calls this when the user asks "how's the project?" or "open project X".
+ *
+ * Returns structured data that OpenClaw LLM can translate to natural language.
+ */
+export interface ProjectStatus {
+    project: string;
+    task_type: string;
+    story: string | null;
+    step: string;
+    status: string;
+    attempt: number;
+    max_attempts: number;
+    reason: string | null;
+    tests: {
+        pass: number;
+        fail: number;
+        skip: number;
+    } | null;
+    lint_pass: boolean | null;
+    files_changed: string[];
+    blocked_by: string[];
+    human_note: string | null;
+    memory_summary: string | null;
+    has_framework: FrameworkDetection;
+}
+export interface FrameworkDetection {
+    has_state: boolean;
+    has_memory: boolean;
+    has_context: boolean;
+    has_constitution: boolean;
+    has_sdd: boolean;
+    has_handoff: boolean;
+    has_history: boolean;
+    /** Adoption level: 0 = none, 1 = partial (some files), 2 = full (all core files) */
+    level: 0 | 1 | 2;
+}
+/**
+ * Detect whether a project uses the Agentic Coding Framework.
+ * OpenClaw calls this when the user asks "is this project using the framework?"
+ */
+export declare function detectFramework(projectRoot: string): FrameworkDetection;
+/**
+ * Get comprehensive project status for OpenClaw to summarize to the user.
+ * Works for ANY project — with or without the Agentic Coding Framework.
+ *
+ * - Framework project (has STATE.json): returns full state + memory summary
+ * - Non-framework project: returns framework detection + whatever files exist
+ */
+export declare function queryProjectStatus(projectRoot: string): ProjectStatus;
+/** Project entry returned by listProjects */
+export interface ProjectEntry {
+    /** Project name (from STATE.json, package.json, or directory name) */
+    name: string;
+    /** Directory name relative to workspace root */
+    dir: string;
+    /** Current step ("none" if not using framework) */
+    step: string;
+    /** Current status ("not_initialized" if not using framework) */
+    status: string;
+    /** Current story ID */
+    story: string | null;
+    /** Whether this project uses the Agentic Coding Framework */
+    has_framework: boolean;
+}
+/**
+ * Scan a workspace directory for all projects — both framework and non-framework.
+ * OpenClaw calls this when the user asks "list my projects" or "switch project".
+ *
+ * A directory is considered a "project" if it contains any of:
+ * - .ai/STATE.json (framework project)
+ * - package.json (Node.js project)
+ * - go.mod (Go project)
+ * - Cargo.toml (Rust project)
+ * - pyproject.toml or setup.py (Python project)
+ * - .git/ (any git repo)
+ */
+export declare function listProjects(workspaceRoot: string): ProjectEntry[];
+/**
+ * Begin a custom (ad-hoc) task. The orchestrator forwards the instruction
+ * to Claude Code with full project context, without going through the
+ * micro-waterfall pipeline.
+ *
+ * Pipeline: custom → update-memory → done
+ * Auto-initializes STATE.json if the project hasn't adopted the framework yet.
+ *
+ * Use cases: refactoring, code review, bug fix, DevOps, documentation,
+ * testing, migration, performance optimization, security, cleanup, etc.
+ */
+export declare function startCustom(projectRoot: string, instruction: string, label?: string): State;