diff --git a/packages/workflow-role-coder/src/coder.ts b/packages/workflow-role-coder/src/coder.ts
index c3c6891..2bd33d1 100644
--- a/packages/workflow-role-coder/src/coder.ts
+++ b/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.`;
 
diff --git a/packages/workflow-role-planner/src/planner.ts b/packages/workflow-role-planner/src/planner.ts
index 33abbc5..49242d0 100644
--- a/packages/workflow-role-planner/src/planner.ts
+++ b/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.",