@veewo/claw-core 0.1.12

package/dist/src/workflow-guidance.js

@@ -0,0 +1,233 @@
+function truthWriterDelegate(projectConfig) {
+    return {
+        name: "truth-writer",
+        skill: normalizeWriterSkill(projectConfig?.externalTruthSkill, "claw-kit:truth-writer"),
+        model: "gpt-5.4-mini",
+        waitForCompletion: false,
+        preferReuseSameTypeInThread: true,
+        inputContract: "completed subtask report",
+        outputContract: "optional telemetry only",
+        closePolicy: "keep_open_for_reuse",
+    };
+}
+function adrWriterDelegate(projectConfig) {
+    return {
+        name: "adr-writer",
+        skill: normalizeWriterSkill(projectConfig?.externalAdrSkill, "claw-kit:adr-writer"),
+        model: "gpt-5.4-mini",
+        waitForCompletion: false,
+        preferReuseSameTypeInThread: true,
+        inputContract: "completed plan.json only",
+        outputContract: "optional telemetry only",
+        closePolicy: "keep_open_for_reuse",
+    };
+}
+function buildGoalModeObjective(planGoal) {
+    return `\u6309\u7167 claw kit \u6d41\u7a0b\uff0c\u5b8c\u6210 task\uff0c\u66f4\u65b0 plan \u6587\u4ef6\uff0c\u5e76\u6700\u7ec8\u5b8c\u6210\uff1a${planGoal}`;
+}
+function nextUnfinishedTask(plan) {
+    return plan.tasks.find((task) => task.status !== "done");
+}
+function formatNextTask(task) {
+    return `#${task.id} ${task.title}`;
+}
+export function buildPlanWorkflowGuidance(params) {
+    const { taskName, planFile, plan, projectConfig = null, previousStatus, completionHooks, changedTaskIds } = params;
+    const scopedPlan = planFile === "plan.json" ? "" : ` --plan ${planFile}`;
+    const editBase = `claw plan edit --task ${taskName}${scopedPlan}`;
+    const doneBase = `claw plan done --task ${taskName}${scopedPlan}`;
+    const hasTasks = plan.tasks.length > 0;
+    const allTasksDone = hasTasks && plan.tasks.every((task) => task.status === "done");
+    const justEnteredProcess = previousStatus?.startsWith("prepare.") && plan.status.startsWith("process.");
+    const justCompletedTasks = (changedTaskIds?.length ?? 0) > 0;
+    const nextTask = nextUnfinishedTask(plan);
+    switch (plan.status) {
+        case "prepare.requirements":
+            return {
+                stage: "requirements",
+                summary: "Task scope is bound. Confirm the route before execution.",
+                nextStep: "Refine the plan if needed, confirm the route with the user, then move to process.active before doing any implementation or task execution.",
+                notes: [
+                    "Planning should already satisfy the old review quality bar.",
+                    "Do not start implementation while the plan is still in `prepare.requirements`.",
+                    "Move to `process.active` before updating task progress or executing the task.",
+                ],
+                recommendedCommands: [
+                    `${editBase} --patch <updated-plan.json>`,
+                    `${editBase} --plan-status process.active`,
+                    `${editBase} --plan-status process.discussing`,
+                ],
+                goalMode: {
+                    recommendedObjective: buildGoalModeObjective(plan.goal.text),
+                    setWhen: "on_plan_write",
+                    ifNoActiveGoal: true,
+                    doNotOverwriteExisting: true,
+                    supportedSurfaces: ["/goal", "create_goal"],
+                },
+                askUser: {
+                    reason: "Requirements still need explicit confirmation before execution starts.",
+                    useCodexOptions: true,
+                    options: [
+                        {
+                            id: "approve-route",
+                            label: "Approve route",
+                            description: "The current plan is acceptable and can move toward execution.",
+                            recommended: true,
+                        },
+                        {
+                            id: "revise-plan",
+                            label: "Revise plan",
+                            description: "The current plan needs scope, task, or sequencing changes before execution.",
+                        },
+                        {
+                            id: "pause-discussion",
+                            label: "Discuss first",
+                            description: "The route is still ambiguous and needs a user discussion turn before work starts.",
+                        },
+                    ],
+                },
+            };
+        case "prepare.review":
+            return {
+                stage: "review",
+                summary: "This plan is in a legacy review stage.",
+                nextStep: "Fold any remaining review notes into the plan, confirm the route with the user, then move back into process.*.",
+                notes: ["Do not create a separate review pass. Merge review criteria into planning itself."],
+                recommendedCommands: [
+                    `${editBase} --patch <reviewed-plan.json>`,
+                    `${editBase} --plan-status prepare.requirements`,
+                    `${editBase} --plan-status process.discussing`,
+                ],
+                askUser: {
+                    reason: "This legacy review stage should be resolved back into normal planning before execution.",
+                    useCodexOptions: true,
+                    options: [
+                        {
+                            id: "merge-revisions",
+                            label: "Revise plan",
+                            description: "Apply the remaining plan changes directly, then continue with normal planning.",
+                            recommended: true,
+                        },
+                        {
+                            id: "discuss-tradeoff",
+                            label: "Discuss tradeoff",
+                            description: "The review raised a route choice that should be clarified with the user.",
+                        },
+                        {
+                            id: "hold-plan",
+                            label: "Hold execution",
+                            description: "Pause until missing requirements or constraints are clarified.",
+                        },
+                    ],
+                },
+            };
+        case "process.active":
+        case "process.wait":
+        case "process.discussing":
+            if (allTasksDone) {
+                return {
+                    stage: "done",
+                    summary: "All plan tasks are done. Do truth deposition, then close the plan.",
+                    nextStep: "Dispatch `truth-writer`, complete the retrospective, then close the plan with `claw plan done`.",
+                    notes: [
+                        "`all task done` is not ADR completion.",
+                        "ADR happens after completed `plan.json` exists.",
+                        "If the host shows thread progress, sync it to the current plan state now.",
+                    ],
+                    recommendedCommands: [
+                        `${doneBase} --summary \"<retrospective summary>\"`,
+                    ],
+                    delegateSubagents: [truthWriterDelegate(projectConfig)],
+                };
+            }
+            return {
+                stage: plan.status === "process.discussing" ? "discussion" : "execution",
+                summary: justEnteredProcess
+                    ? "Execution is starting."
+                    : "Execution is in progress.",
+                nextStep: justEnteredProcess
+                    ? `Confirm the route with the user if needed, then start with ${nextTask ? formatNextTask(nextTask) : "the next task"} and update task status as work progresses.`
+                    : `Continue execution with ${nextTask ? formatNextTask(nextTask) : "the next task"}, update task status with \`claw plan edit\`, and close with \`claw plan done\` when work is complete.`,
+                ...(nextTask
+                    ? {
+                        nextTask: {
+                            id: nextTask.id,
+                            title: nextTask.title,
+                            status: nextTask.status,
+                            ...(nextTask.detail ? { detail: nextTask.detail } : {}),
+                        },
+                    }
+                    : {}),
+                notes: [
+                    "Use delegated specialists for truth and ADR deposition.",
+                    "In `process.active`, keep moving unless there is a real blocker or explicit user interruption.",
+                    "If the host shows thread progress, sync it after this plan edit.",
+                    ...(justCompletedTasks
+                        ? [
+                            "If the completed subtask produced reusable knowledge, dispatch truth-writer.",
+                            `Continue with next task: ${nextTask ? `id ${nextTask.id} content ${nextTask.title}` : "id <next> content <next task>"}.`,
+                        ]
+                        : []),
+                ],
+                recommendedCommands: [
+                    `${editBase} --task-id <id> --task-status done`,
+                    `${doneBase} --summary \"<retrospective summary>\"`,
+                ],
+                ...(justEnteredProcess
+                    ? {
+                        askUser: {
+                            reason: "Execution is starting and any remaining route choice should be made explicit with the user.",
+                            useCodexOptions: true,
+                            options: [
+                                {
+                                    id: "execute-current-route",
+                                    label: "Execute route",
+                                    description: "Proceed with the current plan as written.",
+                                    recommended: true,
+                                },
+                                {
+                                    id: "revise-before-execution",
+                                    label: "Revise first",
+                                    description: "Adjust the plan before deeper implementation begins.",
+                                },
+                                {
+                                    id: "pause-for-input",
+                                    label: "Pause for input",
+                                    description: "Wait for additional requirements or direction from the user.",
+                                },
+                            ],
+                        },
+                    }
+                    : {}),
+            };
+        case "end.completed":
+            return {
+                stage: "deposition",
+                summary: "The plan is completed. Deposit ADRs now.",
+                nextStep: "Dispatch `adr-writer` with the completed `plan.json`.",
+                notes: [
+                    ...(completionHooks?.truthCandidate.suggestedTruthPaths.length
+                        ? [`Suggested truth targets: ${completionHooks.truthCandidate.suggestedTruthPaths.join(", ")}`]
+                        : []),
+                    "Use completed `plan.json` as the ADR bundle.",
+                ],
+                delegateSubagents: [adrWriterDelegate(projectConfig)],
+            };
+        case "end.closed":
+        case "end.leave":
+            return {
+                stage: "paused",
+                summary: "The plan is no longer active.",
+                nextStep: "Reopen through `prepare.requirements` before resuming, or leave it as historical context.",
+                recommendedCommands: [`${editBase} --plan-status prepare.requirements`],
+            };
+    }
+}
+function normalizeWriterSkill(value, fallback) {
+    if (typeof value !== "string") {
+        return fallback;
+    }
+    const trimmed = value.trim();
+    return trimmed || fallback;
+}
+//# sourceMappingURL=workflow-guidance.js.map

package/dist/src/workflow-guidance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-guidance.js","sourceRoot":"","sources":["../../src/workflow-guidance.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@veewo/claw-core",
+  "version": "0.1.12",
+  "type": "module",
+  "description": "Core .claw harness primitives for project context, plan lifecycle, search, truth ingestion, and retention.",
+  "homepage": "https://github.com/chanyuenpang/claw-kit",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chanyuenpang/claw-kit.git",
+    "directory": "packages/core"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/src",
+    "README.md"
+  ],
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test dist/test/**/*.test.js"
+  }
+}