fix(planner,coder): clarify CAS CLI usage in agent prompts

- Planner: mandatory CAS put with complete command template, thread ID guidance
- Coder: CAS get command template with thread ID guidance
- Forbid inventing storage paths — must use uncaged-workflow cas CLI

Fixes #26

entry-solve-issue.ts

@@ -0,0 +1,42 @@
+import { createExtract } from "./packages/workflow/src/index.js";
+import { createHermesAgent } from "./packages/workflow-agent-hermes/src/index.js";
+import {
+  buildSolveIssueDescriptor,
+  createSolveIssueRun,
+} from "./packages/workflow-template-solve-issue/src/index.js";
+
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (value === undefined || value === "") {
+    throw new Error(`missing required env var: ${name}`);
+  }
+  return value;
+}
+
+function optionalEnv(name: string): string | null {
+  const value = process.env[name];
+  if (value === undefined || value === "") {
+    return null;
+  }
+  return value;
+}
+
+const provider = {
+  baseUrl:
+    optionalEnv("WORKFLOW_LLM_BASE_URL") ??
+    "https://dashscope.aliyuncs.com/compatible-mode/v1",
+  apiKey: requireEnv("WORKFLOW_LLM_API_KEY"),
+  model: optionalEnv("WORKFLOW_LLM_MODEL") ?? "qwen-plus",
+};
+
+const agent = createHermesAgent({
+  model: optionalEnv("WORKFLOW_HERMES_MODEL"),
+  timeout: optionalEnv("WORKFLOW_HERMES_TIMEOUT")
+    ? Number(optionalEnv("WORKFLOW_HERMES_TIMEOUT"))
+    : null,
+});
+
+const extract = createExtract(provider);
+
+export const descriptor = buildSolveIssueDescriptor();
+export const run = createSolveIssueRun({ agent }, extract);

packages/workflow-role-coder/src/coder.ts

@@ -10,9 +10,24 @@ export const coderMetaSchema = z.object({
 export type CoderMeta = z.infer<typeof coderMetaSchema>;
 
 const CODER_SYSTEM = `You are a **coder**. Read the thread for the plan and work on the NEXT incomplete phase only.
+
+## Finding the current thread ID
+
+The thread ID is a 26-character Crockford Base32 string (e.g. \`06F03H5V6JTMDST6P3TVH42RWM\`). It appears in the first message of this conversation. If you are unsure, run:
+
+  uncaged-workflow threads
+
+and use the ID of the active thread.
+
+## Reading phase details
+
 Each planner phase is identified by a content-hash and a title. To read a phase's full details (name, description, acceptance criteria), run:
 
-  uncaged-workflow cas get <thread-id> <hash>
+  uncaged-workflow cas get <THREAD_ID> <HASH>
+
+Replace \`<THREAD_ID>\` with the actual thread ID and \`<HASH>\` with the phase hash from the plan.
+
+## Completing a phase
 
 Report which phase you completed using the phase **hash** (not the title). If you legitimately finish every remaining phase in this single turn, set completedPhase to the **last** phase hash in the plan (the workflow treats that as full completion). List the files you changed and summarize what you did.`;
 

packages/workflow-role-planner/src/planner.ts

@@ -14,16 +14,34 @@ export type PlannerMeta = z.infer<typeof plannerMetaSchema>;
 
 const PLANNER_SYSTEM = `You are a **planner** for a software task. Break the work into **sequential phases** the coder will execute one at a time.
 
-For each phase, decide on a name, detailed description, and acceptance criteria. Then store the full detail text in CAS so the coder can retrieve it later:
+## Finding the current thread ID
 
-  uncaged-workflow cas put <thread-id> "# <name>\n\nDescription: <description>\n\nAcceptance: <acceptance>"
+The thread ID is a 26-character Crockford Base32 string (e.g. \`06F03H5V6JTMDST6P3TVH42RWM\`). It appears in the first message of this conversation. If you are unsure, run:
 
-The command prints a content-hash to stdout. Use that hash as the phase identifier.
+  uncaged-workflow threads
 
-Your final structured output must contain compact phases only:
+and use the ID of the active thread.
+
+## Storing phase details — MANDATORY
+
+For each phase you MUST store its full detail text in CAS using this exact CLI command:
+
+  uncaged-workflow cas put <THREAD_ID> '# <name>
+
+Description: <description>
+
+Acceptance: <acceptance>'
+
+Replace \`<THREAD_ID>\` with the actual thread ID you found above. The command prints a content-hash to stdout — use that hash as the phase identifier.
+
+**Do NOT store phase details in any other way** (no temp files, no invented paths). The CLI command is the only supported storage mechanism.
+
+## Output format
+
+After storing all phases via the CLI, output compact JSON only:
   { "phases": [{ "hash": "<hash-from-cas-put>", "title": "<one-line-summary>" }] }
 
-The current thread ID is provided in the thread context. Order phases so earlier steps unblock later ones. Cover root cause, edge cases, and verification across the phases.`;
+Order phases so earlier steps unblock later ones. Cover root cause, edge cases, and verification across the phases.`;
 
 export const plannerRole: RoleDefinition<PlannerMeta> = {
   description: "Breaks the task into sequential phases for the coder.",