@agentic-coding-framework/orchestrator-core 0.1.1 → 0.2.0

package/dist/auto.d.ts

@@ -0,0 +1,105 @@
+/**
+ * auto.ts — Unified entry point for OpenClaw integration
+ *
+ * Classifies a raw user message into an action (query, dispatch, approve, etc.)
+ * using keyword-based matching (zero LLM tokens), then routes to the appropriate
+ * orchestrator function.
+ *
+ * OpenClaw only needs to call:
+ *   orchestrator auto <project-root> "<user message>"
+ *
+ * and gets back a JSON result with an `action` field telling it what happened.
+ */
+import type { Reason } from "./state";
+import { type ProjectStatus, type FrameworkDetection, type ProjectEntry } from "./dispatch";
+export type AutoResult = {
+    action: "query";
+    data: ProjectStatus;
+    memory?: string;
+    handoff?: string;
+} | {
+    action: "dispatched";
+    step: string;
+    attempt: number;
+    prompt: string;
+    fw_lv: number;
+} | {
+    action: "done";
+    story: string;
+    summary: string;
+} | {
+    action: "needs_human";
+    step: string;
+    message: string;
+} | {
+    action: "blocked";
+    step: string;
+    reason: string;
+} | {
+    action: "already_running";
+    step: string;
+    elapsed_min: number;
+} | {
+    action: "timeout";
+    step: string;
+    elapsed_min: number;
+} | {
+    action: "approved";
+    note?: string;
+} | {
+    action: "rejected";
+    reason: string;
+    note?: string;
+} | {
+    action: "detected";
+    framework: FrameworkDetection;
+} | {
+    action: "listed";
+    projects: ProjectEntry[];
+} | {
+    action: "error";
+    message: string;
+};
+type Intent = {
+    type: "query";
+} | {
+    type: "approve";
+    note?: string;
+} | {
+    type: "reject";
+    reason: Reason;
+    note?: string;
+} | {
+    type: "start_story";
+    storyId: string;
+} | {
+    type: "continue";
+} | {
+    type: "detect";
+} | {
+    type: "list";
+} | {
+    type: "custom";
+    instruction: string;
+};
+/**
+ * Classify a raw user message into an intent.
+ * Pure keyword/regex matching — zero LLM tokens.
+ *
+ * Priority order matters: more specific patterns are checked first.
+ */
+export declare function classify(message: string): Intent;
+/**
+ * Unified orchestrator entry point.
+ *
+ * Takes a project root and a raw user message, classifies the intent,
+ * and routes to the appropriate function. Returns a JSON-serializable result.
+ *
+ * Usage:
+ *   orchestrator auto ./project "目前狀態如何"
+ *   orchestrator auto ./project "繼續"
+ *   orchestrator auto ./project "幫我 refactor auth module"
+ *   orchestrator auto ./project "approve"
+ */
+export declare function auto(projectRoot: string, message: string): AutoResult;
+export {};

package/dist/auto.js

@@ -0,0 +1,212 @@
+"use strict";
+/**
+ * auto.ts — Unified entry point for OpenClaw integration
+ *
+ * Classifies a raw user message into an action (query, dispatch, approve, etc.)
+ * using keyword-based matching (zero LLM tokens), then routes to the appropriate
+ * orchestrator function.
+ *
+ * OpenClaw only needs to call:
+ *   orchestrator auto <project-root> "<user message>"
+ *
+ * and gets back a JSON result with an `action` field telling it what happened.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classify = classify;
+exports.auto = auto;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const dispatch_1 = require("./dispatch");
+/**
+ * Classify a raw user message into an intent.
+ * Pure keyword/regex matching — zero LLM tokens.
+ *
+ * Priority order matters: more specific patterns are checked first.
+ */
+function classify(message) {
+    const msg = message.trim();
+    const lower = msg.toLowerCase();
+    // ── Approve ──
+    if (/^(approve|核准|lgtm|通過|approved|ok\s*$)/i.test(msg)) {
+        const note = msg.replace(/^(approve|核准|lgtm|通過|approved|ok)\s*/i, "").trim() || undefined;
+        return { type: "approve", note };
+    }
+    // ── Reject ──
+    if (/^(reject|退回|不行|rejected)/i.test(msg)) {
+        const rest = msg.replace(/^(reject|退回|不行|rejected)\s*/i, "").trim();
+        const { reason, note } = extractRejectReason(rest);
+        return { type: "reject", reason, note };
+    }
+    // ── Start Story (must be before query — "start US-007" is not a query) ──
+    const storyMatch = msg.match(/(?:start\s*story|開始\s*story|開新\s*story|start)\s+(US-\d+)/i)
+        || msg.match(/^(US-\d+)/i);
+    if (storyMatch) {
+        return { type: "start_story", storyId: storyMatch[1] };
+    }
+    // ── List projects ──
+    if (/列出|list.*project|所有專案|all\s*projects/i.test(lower)) {
+        return { type: "list" };
+    }
+    // ── Detect framework ──
+    if (/framework|有沒有用|adoption|detect/i.test(lower)) {
+        return { type: "detect" };
+    }
+    // ── Query (information requests — no code changes) ──
+    if (isQuery(lower)) {
+        return { type: "query" };
+    }
+    // ── Continue / Dispatch ──
+    if (/^(繼續|continue|dispatch|next|下一步|run|執行|go|proceed)\s*$/i.test(msg)) {
+        return { type: "continue" };
+    }
+    // ── Fallback: Custom task ──
+    return { type: "custom", instruction: msg };
+}
+/** Check if the message is a read-only query */
+function isQuery(lower) {
+    const queryPatterns = [
+        /狀態/, /status/, /什麼步驟/, /what\s*step/, /which\s*step/,
+        /測試/, /tests?/, /進度/, /progress/,
+        /還有什麼/, /what's\s*next/, /what\s*next/, /what's\s*left/,
+        /history/, /歷史/, /上次/, /last\s*(session|time)/,
+        /怎麼樣/, /how.*project/, /how.*going/,
+        /目前/, /current/, /看一下/, /看看/, /查一下/, /check\s*status/,
+        /哪個步驟/, /卡住/, /blocked/, /why.*block/,
+        /summary/, /摘要/, /report/, /報告/,
+        /打開/, /open\s*project/,
+    ];
+    return queryPatterns.some((p) => p.test(lower));
+}
+/** Extract reject reason from the rest of the message */
+function extractRejectReason(rest) {
+    const reasonMap = {
+        clarification: "needs_clarification",
+        需要說明: "needs_clarification",
+        不清楚: "needs_clarification",
+        constitution: "constitution_violation",
+        架構違反: "constitution_violation",
+        scope: "scope_warning",
+        範圍: "scope_warning",
+        nfr: "nfr_missing",
+        timeout: "test_timeout",
+        超時: "test_timeout",
+    };
+    for (const [keyword, reason] of Object.entries(reasonMap)) {
+        if (rest.toLowerCase().includes(keyword)) {
+            const note = rest.replace(new RegExp(keyword, "i"), "").trim() || undefined;
+            return { reason, note };
+        }
+    }
+    // Default reason
+    return { reason: "needs_clarification", note: rest || undefined };
+}
+// ─── Main Entry Point ───────────────────────────────────────────────────────
+/**
+ * Unified orchestrator entry point.
+ *
+ * Takes a project root and a raw user message, classifies the intent,
+ * and routes to the appropriate function. Returns a JSON-serializable result.
+ *
+ * Usage:
+ *   orchestrator auto ./project "目前狀態如何"
+ *   orchestrator auto ./project "繼續"
+ *   orchestrator auto ./project "幫我 refactor auth module"
+ *   orchestrator auto ./project "approve"
+ */
+function auto(projectRoot, message) {
+    const intent = classify(message);
+    try {
+        switch (intent.type) {
+            case "query":
+                return handleQuery(projectRoot);
+            case "approve":
+                return handleApprove(projectRoot, intent.note);
+            case "reject":
+                return handleReject(projectRoot, intent.reason, intent.note);
+            case "start_story":
+                return handleStartStory(projectRoot, intent.storyId);
+            case "continue":
+                return handleDispatch(projectRoot);
+            case "detect":
+                return { action: "detected", framework: (0, dispatch_1.detectFramework)(projectRoot) };
+            case "list":
+                // Use projectRoot as workspace root for listing
+                return { action: "listed", projects: (0, dispatch_1.listProjects)(projectRoot) };
+            case "custom":
+                return handleCustom(projectRoot, intent.instruction);
+        }
+    }
+    catch (err) {
+        return { action: "error", message: err.message ?? String(err) };
+    }
+}
+// ─── Intent Handlers ────────────────────────────────────────────────────────
+function handleQuery(projectRoot) {
+    const data = (0, dispatch_1.queryProjectStatus)(projectRoot);
+    // Attach memory and handoff content if available
+    let memory;
+    let handoff;
+    const memoryPath = (0, path_1.join)(projectRoot, "PROJECT_MEMORY.md");
+    if ((0, fs_1.existsSync)(memoryPath)) {
+        memory = (0, fs_1.readFileSync)(memoryPath, "utf-8").slice(0, 2000);
+    }
+    const handoffPath = (0, path_1.join)(projectRoot, ".ai", "HANDOFF.md");
+    if ((0, fs_1.existsSync)(handoffPath)) {
+        handoff = (0, fs_1.readFileSync)(handoffPath, "utf-8").slice(0, 2000);
+    }
+    return { action: "query", data, memory, handoff };
+}
+function handleApprove(projectRoot, note) {
+    try {
+        (0, dispatch_1.approveReview)(projectRoot, note);
+        return { action: "approved", note };
+    }
+    catch (err) {
+        return { action: "error", message: err.message };
+    }
+}
+function handleReject(projectRoot, reason, note) {
+    try {
+        (0, dispatch_1.rejectReview)(projectRoot, reason, note);
+        return { action: "rejected", reason, note };
+    }
+    catch (err) {
+        return { action: "error", message: err.message };
+    }
+}
+function handleStartStory(projectRoot, storyId) {
+    (0, dispatch_1.startStory)(projectRoot, storyId);
+    return wrapDispatchResult((0, dispatch_1.dispatch)(projectRoot));
+}
+function handleDispatch(projectRoot) {
+    return wrapDispatchResult((0, dispatch_1.dispatch)(projectRoot));
+}
+function handleCustom(projectRoot, instruction) {
+    // Check if there's an agent-teams keyword
+    const agentTeams = /agent.?teams?|平行|多\s*agent|agents/i.test(instruction);
+    (0, dispatch_1.startCustom)(projectRoot, instruction, { agentTeams });
+    return wrapDispatchResult((0, dispatch_1.dispatch)(projectRoot));
+}
+/** Convert DispatchResult to AutoResult */
+function wrapDispatchResult(result) {
+    switch (result.type) {
+        case "dispatched":
+            return {
+                action: "dispatched",
+                step: result.step,
+                attempt: result.attempt,
+                prompt: result.prompt,
+                fw_lv: result.fw_lv,
+            };
+        case "done":
+            return { action: "done", story: result.story, summary: result.summary };
+        case "needs_human":
+            return { action: "needs_human", step: result.step, message: result.message };
+        case "blocked":
+            return { action: "blocked", step: result.step, reason: result.reason };
+        case "already_running":
+            return { action: "already_running", step: result.step, elapsed_min: result.elapsed_min };
+        case "timeout":
+            return { action: "timeout", step: result.step, elapsed_min: result.elapsed_min };
+    }
+}

package/dist/cli.js

@@ -18,11 +18,13 @@ const path_1 = require("path");
 const child_process_1 = require("child_process");
 const state_1 = require("./state");
 const dispatch_1 = require("./dispatch");
+const auto_1 = require("./auto");
 const [, , command, ...args] = process.argv;
 function usage() {
     console.error(`Usage: orchestrator <command> [args]
 
 Commands:
+  auto <project-root> <message...>                 ★ Unified entry — classify message & route automatically
   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
@@ -47,6 +49,53 @@ function resolveRoot(raw) {
 }
 try {
     switch (command) {
+        case "auto": {
+            const projectRoot = resolveRoot(args[0]);
+            const message = args.slice(1).join(" ");
+            if (!message) {
+                console.error("Error: <message> is required");
+                console.error('Example: orchestrator auto ./project "目前狀態如何"');
+                process.exit(1);
+            }
+            const result = (0, auto_1.auto)(projectRoot, message);
+            // JSON to stdout (machine-readable)
+            console.log(JSON.stringify(result, null, 2));
+            // Human-friendly summary to stderr
+            switch (result.action) {
+                case "query":
+                    console.error(`[auto] Query: ${result.data.project} — step=${result.data.step}, status=${result.data.status}`);
+                    break;
+                case "dispatched":
+                    console.error(`[auto] Dispatched: step=${result.step}, attempt=${result.attempt}, fw_lv=${result.fw_lv}`);
+                    break;
+                case "done":
+                    console.error(`[auto] Done: ${result.summary}`);
+                    break;
+                case "needs_human":
+                    console.error(`[auto] Needs human: ${result.message}`);
+                    break;
+                case "blocked":
+                    console.error(`[auto] Blocked: ${result.reason}`);
+                    break;
+                case "approved":
+                    console.error(`[auto] Approved${result.note ? ` (note: ${result.note})` : ""}`);
+                    break;
+                case "rejected":
+                    console.error(`[auto] Rejected: ${result.reason}${result.note ? ` — ${result.note}` : ""}`);
+                    break;
+                case "detected":
+                    console.error(`[auto] Framework level: ${result.framework.level}`);
+                    break;
+                case "listed":
+                    console.error(`[auto] Found ${result.projects.length} project(s)`);
+                    break;
+                case "error":
+                    console.error(`[auto] Error: ${result.message}`);
+                    process.exit(1);
+                    break;
+            }
+            break;
+        }
         case "init": {
             const projectRoot = resolveRoot(args[0]);
             const projectName = args[1];
@@ -61,6 +110,11 @@ try {
             else {
                 console.log(`STATE.json already exists (step: ${state.step}, status: ${state.status})`);
             }
+            // Always ensure CLAUDE.md exists (idempotent, won't overwrite)
+            const claudeCreated = (0, state_1.writeClaudeMd)(projectRoot, projectName);
+            if (claudeCreated) {
+                console.log(`Created CLAUDE.md (CC will auto-detect ACF on session start)`);
+            }
             break;
         }
         case "start-story": {

package/dist/dispatch.js

@@ -212,18 +212,24 @@ function buildPrompt(state, rule) {
         lines.push("===================");
         lines.push("");
     }
-    // Step instruction
+    // === PRIMARY TASK (this is the actual work CC must do) ===
+    lines.push("=== YOUR PRIMARY TASK ===");
     lines.push(rule.step_instruction);
     lines.push("");
-    // Output rules (always appended)
-    lines.push("Output rules:");
+    lines.push("Focus on completing the task above FIRST. Modify source files, create");
+    lines.push("tests, update documents — whatever the task requires. Do NOT stop after");
+    lines.push("just updating .ai/HANDOFF.md — that is only the final bookkeeping step.");
+    lines.push("=========================");
+    lines.push("");
+    // === POST-TASK BOOKKEEPING (only after the real work is done) ===
+    lines.push("After you have completed ALL the work above, do this final bookkeeping:");
     lines.push("- Only modify affected files and paragraphs, don't rewrite unrelated content");
-    lines.push("- After completion, update .ai/HANDOFF.md:");
+    lines.push("- Update .ai/HANDOFF.md as a summary of what you did:");
     lines.push("  - YAML front matter: fill in story, step, attempt, status, reason, files_changed, tests values");
     lines.push("  - Markdown body: record what was done, what's unresolved, what next session should note");
-    lines.push("- If requirements unclear, fill reason field with needs_clarification");
-    lines.push("- If Constitution violation found, fill reason field with constitution_violation");
-    lines.push("- If touching Non-Goals scope, fill reason field with scope_warning");
+    lines.push("- If requirements unclear, set status: failing and reason: needs_clarification");
+    lines.push("- If Constitution violation found, set status: failing and reason: constitution_violation");
+    lines.push("- If touching Non-Goals scope, set status: failing and reason: scope_warning");
     return lines.join("\n");
 }
 /**

package/dist/index.d.ts

@@ -6,6 +6,7 @@
  *   rules.ts   → Step transition rules table (pure data)
  *   dispatch.ts → State machine + prompt builder + handoff parser
  */
-export { type State, type Step, type Status, type Reason, type TaskType, type TestResult, createInitialState, readState, writeState, initState, validate, isTimedOut, isMaxedOut, markRunning, markCompleted, } from "./state";
+export { type State, type Step, type Status, type Reason, type TaskType, type TestResult, createInitialState, readState, writeState, initState, validate, isTimedOut, isMaxedOut, markRunning, markCompleted, generateClaudeMd, writeClaudeMd, } from "./state";
 export { type StepRule, type FailRouting, type TeamRole, type TeamRoles, type DispatchMode, STEP_RULES, BOOTSTRAP_RULE, DEFAULT_TEAM_ROLES, DISPATCH_MODES, getRule, resolvePaths, getDispatchMode, getFailTarget, getStepSequence, } from "./rules";
+export { type AutoResult, auto, classify, } from "./auto";
 export { type DispatchResult, type HandoffResult, dispatch, buildPrompt, parseHandoff, applyHandoff, runPostCheck, approveReview, rejectReview, startStory, startCustom, type ProjectStatus, type FrameworkDetection, type ProjectEntry, detectFramework, queryProjectStatus, listProjects, } from "./dispatch";

package/dist/index.js

@@ -8,7 +8,7 @@
  *   dispatch.ts → State machine + prompt builder + handoff parser
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.listProjects = exports.queryProjectStatus = exports.detectFramework = exports.startCustom = exports.startStory = exports.rejectReview = exports.approveReview = exports.runPostCheck = exports.applyHandoff = exports.parseHandoff = exports.buildPrompt = exports.dispatch = exports.getStepSequence = exports.getFailTarget = exports.getDispatchMode = exports.resolvePaths = exports.getRule = exports.DISPATCH_MODES = exports.DEFAULT_TEAM_ROLES = exports.BOOTSTRAP_RULE = exports.STEP_RULES = exports.markCompleted = exports.markRunning = exports.isMaxedOut = exports.isTimedOut = exports.validate = exports.initState = exports.writeState = exports.readState = exports.createInitialState = void 0;
+exports.listProjects = exports.queryProjectStatus = exports.detectFramework = exports.startCustom = exports.startStory = exports.rejectReview = exports.approveReview = exports.runPostCheck = exports.applyHandoff = exports.parseHandoff = exports.buildPrompt = exports.dispatch = exports.classify = exports.auto = exports.getStepSequence = exports.getFailTarget = exports.getDispatchMode = exports.resolvePaths = exports.getRule = exports.DISPATCH_MODES = exports.DEFAULT_TEAM_ROLES = exports.BOOTSTRAP_RULE = exports.STEP_RULES = exports.writeClaudeMd = exports.generateClaudeMd = exports.markCompleted = exports.markRunning = exports.isMaxedOut = exports.isTimedOut = exports.validate = exports.initState = exports.writeState = exports.readState = exports.createInitialState = void 0;
 // State
 var state_1 = require("./state");
 Object.defineProperty(exports, "createInitialState", { enumerable: true, get: function () { return state_1.createInitialState; } });
@@ -20,6 +20,8 @@ Object.defineProperty(exports, "isTimedOut", { enumerable: true, get: function (
 Object.defineProperty(exports, "isMaxedOut", { enumerable: true, get: function () { return state_1.isMaxedOut; } });
 Object.defineProperty(exports, "markRunning", { enumerable: true, get: function () { return state_1.markRunning; } });
 Object.defineProperty(exports, "markCompleted", { enumerable: true, get: function () { return state_1.markCompleted; } });
+Object.defineProperty(exports, "generateClaudeMd", { enumerable: true, get: function () { return state_1.generateClaudeMd; } });
+Object.defineProperty(exports, "writeClaudeMd", { enumerable: true, get: function () { return state_1.writeClaudeMd; } });
 // Rules
 var rules_1 = require("./rules");
 Object.defineProperty(exports, "STEP_RULES", { enumerable: true, get: function () { return rules_1.STEP_RULES; } });
@@ -31,6 +33,10 @@ Object.defineProperty(exports, "resolvePaths", { enumerable: true, get: function
 Object.defineProperty(exports, "getDispatchMode", { enumerable: true, get: function () { return rules_1.getDispatchMode; } });
 Object.defineProperty(exports, "getFailTarget", { enumerable: true, get: function () { return rules_1.getFailTarget; } });
 Object.defineProperty(exports, "getStepSequence", { enumerable: true, get: function () { return rules_1.getStepSequence; } });
+// Auto (unified entry point)
+var auto_1 = require("./auto");
+Object.defineProperty(exports, "auto", { enumerable: true, get: function () { return auto_1.auto; } });
+Object.defineProperty(exports, "classify", { enumerable: true, get: function () { return auto_1.classify; } });
 // Dispatch
 var dispatch_1 = require("./dispatch");
 Object.defineProperty(exports, "dispatch", { enumerable: true, get: function () { return dispatch_1.dispatch; } });

package/dist/state.d.ts

@@ -71,6 +71,19 @@ export declare function initState(projectRoot: string, project: string): {
     created: boolean;
     state: State;
 };
+/** Path to CLAUDE.md in project root */
+export declare function claudeMdPath(projectRoot: string): string;
+/**
+ * Generate CLAUDE.md content for ACF-enabled projects.
+ * CC reads this file automatically on every session start,
+ * ensuring it follows the ACF workflow even without dispatch.
+ */
+export declare function generateClaudeMd(project: string): string;
+/**
+ * Write CLAUDE.md to project root.
+ * Returns true if created, false if already exists (no overwrite).
+ */
+export declare function writeClaudeMd(projectRoot: string, project: string, force?: boolean): boolean;
 /** Validate a State object. Throws on invalid fields. */
 export declare function validate(state: State): void;
 /** Check if a step has exceeded its timeout */

package/dist/state.js

@@ -11,6 +11,9 @@ exports.statePath = statePath;
 exports.readState = readState;
 exports.writeState = writeState;
 exports.initState = initState;
+exports.claudeMdPath = claudeMdPath;
+exports.generateClaudeMd = generateClaudeMd;
+exports.writeClaudeMd = writeClaudeMd;
 exports.validate = validate;
 exports.isTimedOut = isTimedOut;
 exports.isMaxedOut = isMaxedOut;
@@ -78,6 +81,71 @@ function initState(projectRoot, project) {
     writeState(projectRoot, state);
     return { created: true, state };
 }
+// ─── CLAUDE.md Generation ─────────────────────────────────────────────────
+/** Path to CLAUDE.md in project root */
+function claudeMdPath(projectRoot) {
+    return (0, path_1.join)(projectRoot, "CLAUDE.md");
+}
+/**
+ * Generate CLAUDE.md content for ACF-enabled projects.
+ * CC reads this file automatically on every session start,
+ * ensuring it follows the ACF workflow even without dispatch.
+ */
+function generateClaudeMd(project) {
+    return `# ${project} — Agentic Coding Framework
+
+This project uses the **Agentic Coding Framework (ACF)** with an orchestrator-driven
+micro-waterfall pipeline. You MUST follow the ACF workflow — do NOT work freestyle.
+
+## How to Work in This Project
+
+1. **Check current state first:**
+   Read \`.ai/STATE.json\` to understand which step and status the project is in.
+
+2. **Follow the orchestrator — never skip steps:**
+   The pipeline is: bootstrap → bdd → sdd-delta → contract → review → scaffold → impl → verify → update-memory → done.
+   Each step has specific inputs, outputs, and acceptance criteria.
+
+3. **Use the orchestrator CLI** (preferred):
+   \`\`\`bash
+   orchestrator dispatch .       # Get your current task prompt
+   orchestrator status .         # Check pipeline status
+   \`\`\`
+
+4. **Always update .ai/HANDOFF.md when done:**
+   After completing your work, write a YAML front-matter summary to \`.ai/HANDOFF.md\`
+   with: story, step, attempt, status (pass/failing), reason, files_changed, and tests.
+   The orchestrator hook reads this to advance the pipeline.
+
+## Key Rules
+
+- **Do NOT modify .ai/STATE.json directly** — the orchestrator manages it.
+- **Do NOT skip to a different step** — always complete the current step first.
+- If requirements are unclear, set status: \`failing\` and reason: \`needs_clarification\` in HANDOFF.md.
+- If you find a Constitution violation, set reason: \`constitution_violation\`.
+- Read \`.ai/PROJECT_MEMORY.md\` for cross-session context and architectural decisions.
+
+## Files
+
+| File | Purpose | Who writes |
+|------|---------|-----------|
+| \`.ai/STATE.json\` | Pipeline state machine | Orchestrator only |
+| \`.ai/HANDOFF.md\` | Executor ↔ Orchestrator bridge | You (CC) |
+| \`.ai/PROJECT_MEMORY.md\` | Cross-session knowledge | You (at update-memory step) |
+`;
+}
+/**
+ * Write CLAUDE.md to project root.
+ * Returns true if created, false if already exists (no overwrite).
+ */
+function writeClaudeMd(projectRoot, project, force = false) {
+    const path = claudeMdPath(projectRoot);
+    if ((0, fs_1.existsSync)(path) && !force) {
+        return false;
+    }
+    (0, fs_1.writeFileSync)(path, generateClaudeMd(project), "utf-8");
+    return true;
+}
 // ─── Validation ──────────────────────────────────────────────────────────────
 const VALID_STEPS = new Set([
     "bootstrap",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentic-coding-framework/orchestrator-core",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Zero-token orchestrator for the Agentic Coding Protocol — state machine, rules table, dispatch logic, CC integration",
   "type": "commonjs",
   "main": "dist/index.js",