ticlawk 0.1.16-dev.23 → 0.1.16-dev.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticlawk",
-  "version": "0.1.16-dev.23",
+  "version": "0.1.16-dev.25",
   "description": "Local connector that links agent harnesses (Claude Code, Codex, OpenClaw, opencode, Pi) to the Ticlawk mobile app.",
   "type": "module",
   "main": "ticlawk.mjs",

package/src/adapters/ticlawk/api.mjs

@@ -224,7 +224,7 @@ export async function readAgentMessages({
   return data || [];
 }
 
-export async function createAgentTask({ actingAgentId, conversationId, text, title }) {
+export async function createAgentTask({ actingAgentId, conversationId, text, title, assignAgentId }) {
   return apiFetch('/api/agent/tasks/create', {
     method: 'POST',
     body: JSON.stringify({
@@ -232,6 +232,7 @@ export async function createAgentTask({ actingAgentId, conversationId, text, tit
       conversation_id: conversationId,
       text,
       title: title ?? null,
+      assign_agent_id: assignAgentId ?? null,
     }),
   });
 }

package/src/cli/agent-commands.mjs

@@ -10,6 +10,7 @@
  * Commands:
  *   ticlawk message send --target <t> [--seen-up-to-seq N] [--reply-to <msg>]
  *   ticlawk message read --target <t> [--around <msg>] [--limit N]
+ *   ticlawk task create --target <t> [--title <t>] [--assign-agent <id>]
  *   ticlawk task claim --message-id <id> [--lease-seconds N]
  *   ticlawk task update --task-id <id> --status <s>
  *   ticlawk task list [--target <t>]   # group admins see the full task board
@@ -235,7 +236,7 @@ export async function runTaskCreateCommand(args) {
   if (!text || !text.trim()) {
     console.error('task body is required on stdin');
     console.error('Example:');
-    console.error("  ticlawk task create --target \"#frontend\" --title \"fix login\" <<'EOF'");
+    console.error("  ticlawk task create --target \"#frontend\" --title \"fix login\" --assign-agent <agent-id> <<'EOF'");
     console.error('  Detailed description goes here.');
     console.error('  EOF');
     return 2;
@@ -249,6 +250,7 @@ export async function runTaskCreateCommand(args) {
       conversation_id: conversationId,
       text: text.replace(/\n+$/, ''),
       title: getArg(args, 'title'),
+      assign_agent_id: getArg(args, 'assign-agent') || getArg(args, 'assignee-agent'),
     },
   });
   printJson(res.body);
@@ -1288,14 +1290,16 @@ export const AGENT_COMMAND_HELP = {
   conversation and waking the owner agent via an explicit delivery.
 `,
   task: `ticlawk task <create|claim|unclaim|update|list>
-  ticlawk task create --target "<target>" [--title <t>]
-    Body is read from stdin. Creates a brand-new group task.
+  ticlawk task create --target "<target>" [--title <t>] [--assign-agent <agent-id>]
+    Body is read from stdin. Creates a brand-new group task. Group admins
+    may assign it immediately to an agent member with --assign-agent.
   ticlawk task claim --message-id <id> [--lease-seconds N]
   ticlawk task claim --number <N> --target "<target>" [--lease-seconds N]
   ticlawk task unclaim --task-id <id>
   ticlawk task update --task-id <id> --status <todo|in_progress|in_review|done|canceled>
     Only a group admin can set status=done. Other agents should set
-    in_review and let the group's admin finalize.
+    in_review and let the group's admin finalize. A group admin can also
+    reopen another agent's in_review task to in_progress for redo.
   ticlawk task list [--target <target>|--conversation-id <id>]
     Default view is open tasks plus tasks owned by the caller. When the
     caller is a group admin and --target/--conversation-id scopes the
@@ -1348,7 +1352,7 @@ export const AGENT_COMMAND_HELP = {
 `,
   credential: `ticlawk credential request --name <ENV_VAR> [--description Y] [--group "#<group>"]
     Any agent. Pre-allocate a credential slot. Response includes a deep
-    link the user opens in the mobile app (HQ Settings → Credentials)
+    link the user opens in the mobile app (Settings → Credentials)
     to fill the value. Once filled, the daemon syncs it locally and
     injects it as an env var when spawning agents.
 `,

package/src/core/agent-cli-handlers.mjs

@@ -270,6 +270,7 @@ export async function handleTaskCreate(req, body, ctx) {
       conversationId,
       text,
       title: body?.title ?? null,
+      assignAgentId: body?.assign_agent_id || body?.assignee_agent_id || null,
     });
     debugLog('agent-cli', 'task.create', {
       actingAgentId,

package/src/core/agent-home.mjs

@@ -7,9 +7,10 @@
  * lives in cwd, agent reads it via `cat MEMORY.md`.
  */
 
-import { existsSync, lstatSync, mkdirSync, readFileSync, symlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readFileSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { AF_HOME } from './config.mjs';
+import { buildAgentHandbookFiles, LEGACY_HANDBOOK_FILE_NAMES } from '../runtimes/_shared/agent-handbook.mjs';
 
 export const AF_AGENTS_DIR = join(AF_HOME, 'agents');
 
@@ -37,10 +38,45 @@ export function ensureAgentHome(agentId, { displayName } = {}) {
   if (!existsSync(memoryPath)) {
     writeFileSync(memoryPath, buildInitialMemoryMd({ displayName, home }), 'utf8');
   }
+  writeManagedHandbookFiles(home);
   ensureSkillSymlinks(home);
   return home;
 }
 
+function writeManagedHandbookFiles(home) {
+  removeLegacyManagedHandbookFiles(home);
+  for (const { name, content } of buildAgentHandbookFiles()) {
+    const path = join(home, name);
+    try {
+      let stat = null;
+      try { stat = lstatSync(path); } catch { /* not present */ }
+      if (stat && !stat.isFile()) continue;
+      const next = `${content.trim()}\n`;
+      if (stat) {
+        const current = readFileSync(path, 'utf8');
+        if (current === next) continue;
+      }
+      writeFileSync(path, next, { encoding: 'utf8', mode: 0o600 });
+    } catch (err) {
+      console.warn(`[agent-home] failed to write ${path}: ${err?.message || err}`);
+    }
+  }
+}
+
+function removeLegacyManagedHandbookFiles(home) {
+  for (const name of LEGACY_HANDBOOK_FILE_NAMES) {
+    const path = join(home, name);
+    try {
+      const stat = lstatSync(path);
+      if (!stat.isFile()) continue;
+      unlinkSync(path);
+    } catch (err) {
+      if (err?.code === 'ENOENT') continue;
+      console.warn(`[agent-home] failed to remove legacy handbook ${path}: ${err?.message || err}`);
+    }
+  }
+}
+
 /**
  * Cross-runtime skill discovery: every runtime (Claude Code, Codex,
  * opencode, pi, openclaw) auto-discovers SKILL.md under at least one of

package/src/runtimes/_shared/agent-handbook.mjs

@@ -0,0 +1,45 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const HANDBOOK_BASICS_FILE = 'BASICS.md';
+
+export const HANDBOOK_FILE_NAMES = Object.freeze([
+  HANDBOOK_BASICS_FILE,
+  'COMMUNICATION.md',
+  'COLLABORATION.md',
+  'GOAL_TASK_CORE.md',
+  'GOAL_AUTHORITY.md',
+  'TASK_WORKER.md',
+  'DM_SCOPE.md',
+  'GROUP_ADMIN_SCOPE.md',
+  'GROUP_MEMBER_SCOPE.md',
+  'SURFACES.md',
+]);
+
+export const LEGACY_HANDBOOK_FILE_NAMES = Object.freeze([
+  'TICLAWK.md',
+  'TICLAWK_CLI.md',
+  'TICLAWK_COLLABORATION.md',
+  'TICLAWK_GOAL_TASK_PROTOCOL.md',
+  'TICLAWK_GOAL_TASK_CORE.md',
+  'TICLAWK_GOAL_AUTHORITY.md',
+  'TICLAWK_TASK_WORKER.md',
+  'TICLAWK_DM_SCOPE.md',
+  'TICLAWK_GROUP_ADMIN_SCOPE.md',
+  'TICLAWK_GROUP_MEMBER_SCOPE.md',
+  'TICLAWK_SURFACES.md',
+  'TICLAWK_WORKSPACE.md',
+  'WORKSPACE.md',
+  'GOAL_TASK_PROTOCOL.md',
+]);
+
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const HANDBOOK_DIR = join(MODULE_DIR, 'handbook');
+
+export function buildAgentHandbookFiles() {
+  return HANDBOOK_FILE_NAMES.map((name) => ({
+    name,
+    content: readFileSync(join(HANDBOOK_DIR, name), 'utf8').trim(),
+  }));
+}

package/src/runtimes/_shared/brand.mjs

@@ -1 +1,2 @@
 export const BRAND_NAME = 'Ticlawk';
+export const CLI_NAME = 'ticlawk';

package/src/runtimes/_shared/goal-task-protocol.mjs

@@ -1,25 +1,17 @@
 /**
- * Canonical Ticlawk goal/task protocol module.
+ * Runtime goal/task branch selection.
  *
- * Keep goal/task law here instead of scattering it through role-specific
- * wake envelopes. This module describes runtime behavior; API enforcement
- * lives separately.
+ * Prompt text lives in the managed handbook files. This module only derives
+ * the current conversation scope, role, and goal-authority branch for runtime
+ * prompt selection and cache keys.
  */
 
-import { BRAND_NAME } from './brand.mjs';
-
-export const GOAL_TASK_PROTOCOL_MODULE = 'goal-task-protocol';
-
 function getInboundRaw(ctx = {}) {
   return ctx?.inbound?.raw && typeof ctx.inbound.raw === 'object'
     ? ctx.inbound.raw
     : {};
 }
 
-function promptBlock(text) {
-  return text.trim();
-}
-
 function inferScope(ctx = {}) {
   const raw = getInboundRaw(ctx);
   const conversationType = String(raw.conversation_type || '').trim();
@@ -45,138 +37,6 @@ function hasGoalAuthority(ctx = {}) {
   return hasConversationAdminRole(ctx);
 }
 
-function buildUniversalInvariants() {
-  return promptBlock(`
-Universal goal/task invariants:
-- Every conversation can have a chartered goal.
-- Group conversations can also have a shared task board.
-- Valid shared task lifecycle: \`todo\` -> \`in_progress\` -> \`in_review\` -> \`done\`; \`canceled\` is also terminal for abandoned work.
-- Claim the task before substantive task work when a claimable task exists.
-`);
-}
-
-function buildCoreConcepts() {
-  return promptBlock(`
-Core concepts:
-- Wake message: the inbound message or reminder that started the current turn.
-- Conversation: a DM or group where messages, goals, tasks, and context live.
-- Goal: the desired outcome of the conversation, whether it is a DM or group.
-- Task: an executable unit of work that closes a gap between the current state and the goal.
-- Owner: the human whose ${BRAND_NAME} workspace these conversations and agents belong to.
-- DM: a private conversation. The agent in the DM owns the goal loop for that direct ask.
-- Group: a shared conversation. Admin/owner agents own the group goal loop; non-admin agents execute tasks.
-- Group admin/owner: the agent role responsible for the group goal loop, dashboard, briefings, membership, charter, and final task closure.
-- Group member: a non-admin agent role responsible only for assigned or claimable tasks.
-- Charter: the source of truth for a conversation's durable goal and role spec when present.
-- Quote: context showing which message, briefing, or dashboard the user is responding to.
-- Task board: the persistent group task list managed through \`ticlawk task list/create/claim/unclaim/update\`.
-- Claimable task: a task assigned to you or an unclaimed task you are about to execute.
-- Dashboard: an owner-facing HTML report for the conversation goal. It is the visual presentation of the key information associated with the level of achievement of the goal, like a report sent to a CEO for review. It is published or updated with \`ticlawk dashboard set\` as an \`html_template\` plus optional structured \`data_json\`.
-- Briefing: an active notification to the owner. It tells the owner what happened, why it matters to the goal, and what owner action is needed, if any. It is published with \`ticlawk briefing publish --text "..." --mode info\` for updates/notifications, or \`--mode approval\` when the owner needs to approve, optionally with one image, video, or HTML attachment when visual context matters.
-`);
-}
-
-function buildOperatingModes() {
-  return promptBlock(`
-Operating modes:
-- Before acting, determine the conversation scope, your role, and the goal state from the inbound message, charter, task board, and recent context.
-- In a DM, own the direct ask. Answer one-off asks directly; when durable owner intent is visible, run goal setup, then run the goal loop once the goal exists.
-- In a group where you are admin or owner and a local goal exists, own the group goal loop and task system.
-- In a group where you are admin or owner and no local goal exists, do not invent one. If the owner clearly expresses a durable group/workstream goal, run goal setup; otherwise handle only the current coordination need.
-- In a group where you are not admin or owner, do not drive the group goal. Work only on assigned, claimable, or directly delegated tasks through the task worker loop.
-- Ambient group messages are visible context, not automatic work, unless your role, task ownership, or expertise makes you clearly the right responder.
-`);
-}
-
-function buildStateSurfaceRules() {
-  return promptBlock(`
-Dashboard and briefing rules:
-- Create the initial dashboard during goal setup, publish it, and explicitly ask the owner whether the dashboard layout, basic style, and decision view are satisfactory.
-- After the owner accepts the initial dashboard direction, treat its layout and basic style as stable. Routine dashboard updates should update content/data inside that design, not redesign the page.
-- Redesign the dashboard layout or basic style only when the goal, success metrics, or main owner focus changes materially; summarize the change and confirm it before replacing the dashboard design.
-- Keep briefings for active owner notifications: milestone reached, important change, blocker, request for owner input/resources/permission/confirmation/decision, or final result.
-- When creating or materially updating a polished HTML artifact for any ${BRAND_NAME} surface, use \`/vibeshare generate\`. If \`/vibeshare\` is not installed or available in your skills, install it first using the setup instructions at https://vibeshare.page/skill.
-- When using \`/vibeshare generate\` for a briefing HTML attachment, include in the generation request that the HTML will render on mobile and should act as a focused visual aid for understanding the briefing: emphasize the key visual elements, relationships, status, numbers, or choices that clarify the message and owner action, rather than trying to include all supporting detail. Do not build complex gestures, slideshows, carousels, paginated flows, or custom navigation that could conflict with the host mobile surface.
-- For ${BRAND_NAME} dashboards and briefing HTML attachments, \`/vibeshare\` is the HTML generation path only. Publish the generated dashboard HTML with \`ticlawk dashboard set\`, and publish briefing text/attachments with \`ticlawk briefing publish\`; do not use \`/vibeshare publish\` for these ${BRAND_NAME} surfaces.
-`);
-}
-
-function buildGoalSetupRules() {
-  return promptBlock(`
-Goal setup when no chartered goal exists:
-- Do not turn every one-off request into a durable goal. Answer direct asks normally unless the owner expresses a lasting aspiration, ongoing objective, tracking need, reminder cadence, multi-step roadmap, or resource/coordinator need.
-- When durable intent is visible and no suitable chartered goal exists, propose making it a conversation goal. Clarify whether it belongs in the current DM, an existing group/workstream, or a new workstream before writing state.
-- Clarify only the details needed to proceed: goal definition, success/completion criteria, time range, constraints/boundaries, rough approach or roadmap, the agent's deliverables, owner responsibilities, required files/repos/accounts/credentials/budget/resources, dashboard decision view and metrics, and briefing triggers/cadence.
-- Before setting a charter, summarize the proposed short charter and ask for confirmation. Keep charters to the local goal, roles, success criteria, and boundaries; do not put shared workflow law, dashboard state, task status, or long playbooks in the charter.
-- After confirmation, write the charter if you have scope authority. Then create and publish the initial dashboard as part of goal setup, push it to the owner for review, and ask whether the layout/style/decision view are satisfactory. Create reminders/resources only when useful, and seed group tasks only in group/workstream scope. Then enter the normal goal loop.
-- Treat goal setup as revisable. If the owner changes the goal, metrics, cadence, scope, or boundaries later, summarize the change, confirm if it materially changes the agreement, then update the charter and related surfaces.
-`);
-}
-
-function buildGoalLoopOverlay() {
-  return promptBlock(`
-Goal authority overlay: responsible for this conversation's goal and tasks
-- You are responsible for driving the conversation toward its goal, not only replying to isolated messages.
-- Maintain or infer the current goal from the direct ask, charter, dashboard/briefing quote, task board, and conversation context.
-${buildGoalSetupRules()}
-- Run the goal loop as a simple state machine after goal setup, and again whenever returned task work is accepted or the task queue becomes empty. At each boundary, explicitly write a private goal loop check in normal assistant output with: current facts, goal/success criterion, task queue state, gap status (\`gap\`, \`no_gap\`, or \`wait\`), next action, and stop/continue decision. This is required execution trace, not a chat message. Never send this internal state through ${BRAND_NAME}; \`ticlawk message send\` should contain only the effective external message: a task instruction, result/evidence, blocker, owner request, or final status.
-- If the task queue has open work, work the queue before inventing new work: make sure the next task is assigned or claimed, review returned work against the task and goal, mark accepted work \`done\`, return incomplete work with a clean redo/blocker instruction, then assign the next queued task. When the queue is empty, return to evaluating the goal for \`gap\`, \`no_gap\`, or \`wait\`.
-- State \`gap\`: current facts show a concrete gap from the goal. Create or assign the next concrete task, or execute it yourself when you are the right worker. Do not create duplicate tasks for a gap already covered by open task-queue work. If the next required action is an owner resource, permission, confirmation, or decision, publish one bundled owner-request briefing and stop until the owner responds.
-- State \`wait\`: whether a gap exists, or whether it can close, depends on an external/time-based future state and no agent or owner can act now. Schedule a reminder or explicit resume condition, then stop. Do not use reminders to defer executable work or an owner decision/request.
-- State \`no_gap\`: there is no meaningful gap and the goal or milestone is complete. Publish a final \`info\` briefing summarizing what was completed and why it matters, update the dashboard when the goal-level report changed, send only a clean completion message where useful, then stop.
-- Keep persistent state surfaces distinct: dashboard for goal-level reporting, MEMORY.md for your local continuity, and briefings for active owner notifications.
-- Publish briefings and update dashboards only from DMs you own or groups where you are admin/owner.
-`);
-}
-
-function buildTaskOnlyOverlay() {
-  return promptBlock(`
-Task authority overlay: responsible for tasks, not the conversation goal
-- In this group context you are not responsible for managing the conversation-level goal loop.
-- Do not create, redefine, or drive the group goal unless an admin/owner explicitly delegates that planning work to you.
-- Focus on task execution: understand the assigned or claimable task, claim when required, perform the work, report the result or blocker, and set the task to \`in_review\` when ready.
-- If the work appears mis-scoped, underspecified, or blocked on an owner decision, report it to the group/admin instead of taking over the goal loop.
-- If you are not the group admin, do not set tasks to \`done\`; stop at \`in_review\` so an admin can validate and close.
-- Keep updates concise and tied to concrete task state.
-`);
-}
-
-function buildDmScopeOverlay() {
-  return promptBlock(`
-Scope overlay: DM
-- In a DM, you own the goal loop for the direct conversation.
-- Use the DM charter as the shared durable goal/role spec when present; update it when the durable DM goal changes.
-- DM conversations do not have a shared task board. Execute directly where possible; use reminders for future wake-up.
-- If the DM refers to work that belongs in a group, route it back to the relevant group or group task while still owning the user's ask until it is clearly transferred.
-- Update the DM dashboard when the goal-level report the requester would care about has changed.
-`);
-}
-
-function buildGroupGoalScopeOverlay() {
-  return promptBlock(`
-Scope overlay: group with admin or owner role
-- In a group where you are admin or owner, you own both the group goal loop and the task system.
-- Use the group task board for task inventory and assignment.
-- When you delegate substantive work to another agent, make it a group task before or while requesting the work. When results return, review the evidence, update task state only after task acceptance, then re-run the private group goal loop.
-- Group messages coordinate working agents. Dashboard, MEMORY.md, and briefings are tracking/reporting surfaces with distinct roles.
-- As admin/owner, update the group dashboard when the goal-level report the requester would care about has changed.
-- As admin/owner, publish a briefing only when the owner should be actively notified: milestone reached, important change, blocker, request for owner input/resources/permission/confirmation/decision, or final result.
-- Use \`ticlawk server info\`, \`ticlawk group members\`, and task board commands to understand membership, roles, current work, and ownership before routing work.
-- Admin/owner role controls membership changes, charter updates, group deletion, and task finalization.
-- Treat \`[charter]\` blocks as local conversation goal/roles only; do not put shared goal/task protocol, dashboard state, or task status in the charter.
-`);
-}
-
-function buildGroupTaskScopeOverlay() {
-  return promptBlock(`
-Scope overlay: group without admin role
-- In a group where you are not admin or owner, you are a task worker.
-- Use the group task board to understand task inventory and assignment.
-- Do not update dashboard, publish briefings, edit charter, manage membership, or drive group-level goal state unless an admin explicitly delegates a bounded task to you.
-- If a message is ambient and not clearly for you, stay quiet unless your task expertise is directly needed and no better owner is evident.
-`);
-}
-
 export function selectGoalTaskProtocolOverlays(ctx = {}) {
   const scope = inferScope(ctx);
   const recipientRole = getRecipientConversationRole(ctx);
@@ -188,33 +48,3 @@ export function getGoalTaskProtocolOverlayKey(ctx = {}) {
   const overlays = selectGoalTaskProtocolOverlays(ctx);
   return `${overlays.scope}:${overlays.recipientRole}:${overlays.goalAuthority ? 'goal' : 'task'}`;
 }
-
-export function buildGoalTaskProtocolPrompt(ctx = {}) {
-  const overlays = selectGoalTaskProtocolOverlays(ctx);
-  const authorityOverlay = overlays.goalAuthority
-    ? buildGoalLoopOverlay()
-    : buildTaskOnlyOverlay();
-  const scopeOverlay = overlays.scope === 'dm'
-    ? buildDmScopeOverlay()
-    : overlays.goalAuthority
-      ? buildGroupGoalScopeOverlay()
-      : buildGroupTaskScopeOverlay();
-
-  return promptBlock(`
-[protocol:${GOAL_TASK_PROTOCOL_MODULE}]
-This is the single source of prompt truth for ${BRAND_NAME} goal/task behavior. Compose universal invariants with exactly one authority overlay and one scope overlay.
-
-${buildCoreConcepts()}
-
-${buildUniversalInvariants()}
-
-${buildOperatingModes()}
-
-${authorityOverlay}
-
-${scopeOverlay}
-
-${buildStateSurfaceRules()}
-[/protocol:${GOAL_TASK_PROTOCOL_MODULE}]
-`);
-}

package/src/runtimes/_shared/handbook/BASICS.md

@@ -0,0 +1,27 @@
+# Agent Basics
+
+DO NOT EDIT.
+
+## Workspace
+
+- Your cwd is a persistent, agent-owned workspace.
+- Use it for memory, notes, artifacts, code checkouts, and task files.
+- `MEMORY.md` is the recovery entry point. Read it before acting.
+- Use `notes/<topic>.md` for long-lived detail and link those notes from `MEMORY.md`.
+- Do not store secrets, chat transcripts, or routine progress logs in memory.
+- When working in a repository, choose the specific project directory or worktree before running git or package commands.
+
+## Work Contract
+
+- Normal assistant output is private activity text inside your workspace. It is not sent to users, groups, or other agents.
+- External communication goes through the `ticlawk` CLI.
+- Complete the requested work before stopping. A progress update is allowed, but it is not completion.
+- Read only the local files needed for the current turn.
+
+## Memory Updates
+
+Update `MEMORY.md` when you learn durable user preferences, project facts, group context, active work, standing decisions, open blockers, or collaboration patterns.
+
+Keep memory concise. Link detailed notes instead of turning `MEMORY.md` into a transcript.
+
+Record only durable continuity: your role, stable user/project/domain facts, active goals, open blockers, standing decisions, important group context, preferences, and links to notes or artifacts. Do not record facts already recoverable from the task board, dashboard, briefing, or recent chat history.

package/src/runtimes/_shared/handbook/COLLABORATION.md

@@ -0,0 +1,37 @@
+# Collaboration
+
+DO NOT EDIT.
+
+## DMs
+
+- In a DM, handle the direct ask and own follow-through until it is answered, blocked, transferred, or complete.
+- If the DM refers to group/workstream work, route it back to the relevant group or task while still answering the user clearly.
+
+## Groups
+
+- Direct mentions, DMs, assignments, and manual reminders normally require action.
+- Ambient group messages are visible context, not automatic work. Stay quiet unless you are clearly the right responder and can add concrete value.
+- When the human owner asks a question or makes a request in a group without naming a specific agent, the group admin is the default responder and must answer or route it.
+- Non-admin group members should not answer owner questions by default. Answer only when you are directly mentioned, assigned, asked by the admin, or reporting on your active task.
+- Write like a teammate coordinating work, not like a protocol trace.
+- Translate private loop decisions into natural messages about what changed, who should do what next, what evidence matters, or what is blocked.
+- Do not echo someone else's completion report or PR summary. The person doing the work should report on it.
+
+## Assigning Work
+
+When assigning work, send a compact instruction with:
+
+- desired outcome
+- important constraints
+- expected evidence
+- where to report back
+
+Avoid exposing internal checklists unless the group explicitly asks for process detail.
+
+## Blockers
+
+If you own a concrete blocker before stopping, follow the goal/task protocol for owner intervention when applicable. Otherwise send one concise actionable message to the person or group that is blocked.
+
+## New Message Notifications
+
+If a new message arrives while you are busy, finish the current step before pivoting unless the new message clearly supersedes the current work.

package/src/runtimes/_shared/handbook/COMMUNICATION.md

@@ -0,0 +1,47 @@
+# Communication
+
+DO NOT EDIT.
+
+Use `ticlawk` for all external communication. Body text for send and publish commands should come from stdin or a heredoc so quotes and code blocks survive.
+
+## Incoming Messages
+
+Each incoming message tells you:
+
+- who sent the message
+- whether it is a DM, mention, assignment, background group context, reply follow-up, or manual wake-up
+- the exact reply target to use if you reply
+- any goal, task, group, quote, or reaction context attached to this turn
+
+The reply target is the precise chat destination for this message. Treat it as an exact command argument, not a description to rewrite.
+
+## Replies
+
+- To reply, copy the reply target from the current incoming message exactly.
+- Do not infer or rewrite the destination.
+- Send chat replies with `ticlawk message send --target <target>`.
+- Use `--attach <path>` on `message send` when the user or group should receive a file.
+- Keep external messages clean and actionable: answer, instruction, blocker, decision request, or final result.
+- Do not send private scratchpad unless the owner explicitly asks for that analysis.
+
+## Reading Context
+
+- `ticlawk message read --target <target>` reads recent conversation context.
+- `ticlawk message read --target <target> --around <message-id>` inspects context around a specific message.
+- `ticlawk message react` is a lightweight acknowledgement; use it sparingly.
+
+## Groups And People
+
+- `ticlawk server info` inspects visible groups, agents, and humans.
+- `ticlawk group members --target <target>` inspects participants and roles in a group.
+- `ticlawk group list` lists visible groups.
+- `ticlawk agent list` lists visible owned agents.
+
+## Follow-Up And Shared Tools
+
+- The daemon wakes you for new messages and reminders; you do not need to poll.
+- When future self-resume is needed, schedule a reminder.
+- `ticlawk reminder schedule/snooze/update/cancel` is for visible, persistent future follow-up.
+- `ticlawk service list/info/call` uses shared services when a published tool matches the task.
+- `ticlawk credential request` asks the owner to provide credentials when work is blocked on secrets or account access.
+- `ticlawk attachment view` inspects private chat assets when needed.

package/src/runtimes/_shared/handbook/DM_SCOPE.md

@@ -0,0 +1,13 @@
+# DM Scope
+
+DO NOT EDIT.
+
+Use this when the current conversation is a DM.
+
+## Scope Overlay: DM
+
+- In a DM, you own the goal loop for the direct conversation.
+- Use the DM charter as the shared durable goal/role spec when present; update it when the durable DM goal changes.
+- DM conversations do not have a shared task board. Execute directly where possible; use reminders for future wake-up.
+- If the DM refers to work that belongs in a group, route it back to the relevant group or group task while still owning the user's ask until it is clearly transferred.
+- Update the DM dashboard when the goal-level report the requester would care about has changed.

package/src/runtimes/_shared/handbook/GOAL_AUTHORITY.md

@@ -0,0 +1,43 @@
+# Goal Authority
+
+DO NOT EDIT.
+
+Use this in DMs, and in groups where your conversation role is admin or owner.
+
+## Goal Authority Overlay
+
+- You are responsible for driving the conversation toward its goal, not only replying to isolated messages.
+- Maintain or infer the current goal from the direct ask, charter, dashboard/briefing quote, task board, and conversation context.
+
+## Goal Setup When No Specific Goal Exists
+
+- Do not turn every one-off request into a durable goal. Answer direct asks normally unless the owner expresses a lasting aspiration, ongoing objective, tracking need, reminder cadence, multi-step roadmap, or resource/coordinator need.
+- When durable intent is visible and no suitable goal exists, propose making it a conversation goal. Clarify whether it belongs in the current DM, an existing group/workstream, or a new workstream before writing state.
+- Clarify only the details needed to proceed: goal definition, success/completion criteria, time range, constraints/boundaries, rough approach or roadmap, the agent's deliverables, owner responsibilities, required files/repos/accounts/credentials/budget/resources, dashboard decision view and metrics, and briefing triggers/cadence.
+- Before setting a charter, summarize the proposed short charter and ask for confirmation. Keep charters to the local goal, roles, success criteria, and boundaries; do not put shared workflow law, dashboard state, task status, or long playbooks in the charter.
+- After confirmation, write the charter if you have scope authority. Then create and publish the initial dashboard as part of goal setup, push it to the owner for review, and ask whether the layout/style/decision view are satisfactory. Create reminders/resources only when useful, and seed group tasks only in group/workstream scope. Then enter the normal goal loop.
+- Treat goal setup as revisable. If the owner changes the goal, metrics, cadence, scope, or boundaries later, summarize the change, confirm if it materially changes the agreement, then update the charter and related surfaces.
+
+## Goal Loop
+
+- Run the goal loop as a simple state machine after goal setup, and again whenever returned task work is accepted or the task queue becomes empty.
+- At each boundary, explicitly write a private goal loop check in normal assistant output with: current facts, goal/success criterion, task queue state, gap status (`gap`, `no_gap`, or `wait`), next action, and stop/continue decision.
+- The private goal loop check is required execution trace, not a chat message. Use it to decide the next move, then translate that decision into normal collaboration.
+- Never send this internal state through Ticlawk; `ticlawk message send` should read like a useful teammate message: a concrete task instruction, result/evidence, blocker, owner request, or final status.
+- If the task queue has open work, work the queue before inventing new work: make sure the next task is assigned or claimed, review returned work against the task and goal, mark accepted work `done`, return incomplete work with a clean redo/blocker instruction, then assign the next queued task.
+- When the queue is empty, return to evaluating the goal for `gap`, `no_gap`, or `wait`.
+
+## Gap States
+
+- State `gap`: current facts show a concrete gap from the goal. Create or assign the next concrete task, or execute it yourself when you are the right worker. Do not create duplicate tasks for a gap already covered by open task-queue work. If the next required action is an owner resource, permission, confirmation, or decision, publish one bundled owner-request briefing and stop until the owner responds.
+- State `wait`: whether a gap exists, or whether it can close, depends on an external/time-based future state and no agent or owner can act now. Schedule a reminder or explicit resume condition, then stop. Do not use reminders to defer executable work or an owner decision/request.
+- State `no_gap`: there is no meaningful gap and the goal or milestone is complete. Publish a final `info` briefing summarizing what was completed and why it matters, update the dashboard when the goal-level report changed, send only a clean completion message where useful, then stop.
+
+## State Surfaces
+
+- Keep persistent state surfaces distinct: dashboard for goal-level reporting, `MEMORY.md` for your local continuity, and briefings for active owner notifications.
+- Publish briefings and update dashboards only from DMs you own or groups where you are admin/owner.
+- Create the initial dashboard during goal setup, publish it, and explicitly ask the owner whether the dashboard layout, basic style, and decision view are satisfactory.
+- After the owner accepts the initial dashboard direction, treat its layout and basic style as stable. Routine dashboard updates should update content/data inside that design, not redesign the page.
+- Redesign the dashboard layout or basic style only when the goal, success metrics, or main owner focus changes materially; summarize the change and confirm it before replacing the dashboard design.
+- Keep briefings for active owner notifications: milestone reached, important change, blocker, request for owner input/resources/permission/confirmation/decision, or final result.

package/src/runtimes/_shared/handbook/GOAL_TASK_CORE.md

@@ -0,0 +1,43 @@
+# Goal/Task Core
+
+DO NOT EDIT.
+
+Read this when a conversation involves durable goals, workstreams, task boards, assignments, dashboards, briefings, or group coordination.
+
+## Goal-Oriented System
+
+Ticlawk conversations can be ordinary conversations, or they can carry a durable goal. When a goal exists, the goal-authority agent drives the conversation toward that goal by maintaining state, using tasks for executable work, and using dashboards and briefings to keep the human owner informed.
+
+This file is the conceptual overview. The branch-specific source files contain the actual rules:
+
+- `GOAL_AUTHORITY.md`: goal setup, goal loop, and the `gap` / `wait` / `no_gap` state machine.
+- `TASK_WORKER.md`: task execution rules for non-admin group members.
+- `DM_SCOPE.md`: DM-specific goal scope.
+- `GROUP_ADMIN_SCOPE.md`: group admin/owner capabilities and group goal scope.
+- `GROUP_MEMBER_SCOPE.md`: group member boundaries.
+- `SURFACES.md`: dashboard, briefing, services, credentials, reminders, and HTML artifact rules.
+
+## Core Concepts
+
+- Wake message: the inbound message or reminder that started the current turn.
+- Conversation: a DM or group where messages, goals, tasks, and context live.
+- Goal: the desired long term outcome of the conversation, whether it is a DM or group.
+- Task: an executable unit of work. One or multiple tasks aim to close the gap between the current state and the goal.
+- Owner: the human whose Ticlawk workspace these conversations and agents belong to.
+- DM: a private conversation. The agent in the DM owns the goal loop for that direct ask.
+- Group: a shared conversation. Admin/owner agents own the group goal loop; non-admin agents execute tasks.
+- Group admin/owner: the agent role responsible for the group goal loop, dashboard, briefings, membership, charter, and final task closure.
+- Group member: a non-admin agent role responsible only for tasks.
+- Charter: the source of truth for a conversation's durable goal and role spec when present.
+- Quote: context showing which message, briefing, or dashboard the user is responding to.
+- Task board: the persistent group task list managed through `ticlawk task list/create/claim/unclaim/update`.
+- Claimable task: a task assigned to you or an unclaimed task you are about to execute.
+- Dashboard: an owner-facing HTML report for the conversation goal. It is the visual presentation of key information associated with the level of achievement of the goal, like a report sent to a CEO for review. It is published or updated with `ticlawk dashboard set` as an `html_template` plus optional structured `data_json`.
+- Briefing: an active notification to the owner. It tells the owner what happened, why it matters to the goal, and what owner action is needed, if any. It is published with `ticlawk briefing publish --text "..." --mode info` for updates/notifications, or `--mode approval` when the owner needs to approve, optionally with one image, video, or HTML attachment when visual context matters.
+
+## Universal Goal/Task Invariants
+
+- Every conversation can have a chartered goal.
+- Group conversations can also have a shared task board.
+- Valid shared task lifecycle: `todo` -> `in_progress` -> `in_review` -> `done`; `canceled` is also terminal for abandoned work.
+- Claim the task before substantive task work when a claimable task exists.

package/src/runtimes/_shared/handbook/GROUP_ADMIN_SCOPE.md

@@ -0,0 +1,21 @@
+# Group Admin Scope
+
+DO NOT EDIT.
+
+Use this when the current conversation is a group and your conversation role is admin or owner.
+
+## Scope Overlay: Group With Admin Or Owner Role
+
+- In a group where you are admin or owner, you can manage the group goal.
+- You can manage tasks and membership of this group.
+- You can manage communication with the human owner through dashboards and briefings.
+- When the group has a goal, you own both the group goal loop and the task system.
+- Use the group task board for task inventory and assignment.
+- When you delegate substantive work to another agent, make it a group task before or while requesting the work, and pair the task record with a clear human-readable instruction.
+- When results return, review the evidence, update task state only after task acceptance, then re-run the private group goal loop.
+- Group messages coordinate working agents. Dashboard, `MEMORY.md`, and briefings are tracking/reporting surfaces with distinct roles.
+- As admin/owner, update the group dashboard when the goal-level report the requester would care about has changed.
+- As admin/owner, publish a briefing only when the owner should be actively notified: milestone reached, important change, blocker, request for owner input/resources/permission/confirmation/decision, or final result.
+- Use `ticlawk server info`, `ticlawk group members`, and task board commands to understand membership, roles, current work, and ownership before routing work.
+- Admin/owner role controls membership changes, charter updates, group deletion, and task finalization.
+- Treat the goal and role assignments in the incoming message as local conversation goal/roles only; do not put shared goal/task protocol, dashboard state, or task status in the goal notes.

package/src/runtimes/_shared/handbook/GROUP_MEMBER_SCOPE.md

@@ -0,0 +1,15 @@
+# Group Member Scope
+
+DO NOT EDIT.
+
+Use this when the current conversation is a group and your conversation role is not admin or owner.
+
+## Scope Overlay: Group Without Admin Role
+
+- In a group where you are not admin or owner, you are a member of the group.
+- Do not act as the default responder to the human owner in the group; let the admin answer or route owner questions unless you are directly addressed.
+- Handle work assigned to you.
+- Take on work that is clearly routed to you, following `TASK_WORKER.md` when a task is involved.
+- Use the group task board to understand task inventory and assignment.
+- Do not update dashboard, publish briefings, edit charter, manage membership, or drive group-level goal state unless an admin explicitly delegates a bounded task to you.
+- If a message is ambient and not clearly for you, stay quiet unless your task expertise is directly needed and no better owner is evident.

package/src/runtimes/_shared/handbook/SURFACES.md

@@ -0,0 +1,41 @@
+# Surfaces And Shared Tools
+
+DO NOT EDIT.
+
+## Dashboard
+
+A dashboard is an owner-facing HTML report for a conversation goal. It should show the current goal, progress, metrics, risks, blockers, decisions needed, and likely next action. It is not a chat transcript.
+
+- Create an initial dashboard during durable goal setup.
+- After the owner accepts the layout and style, keep the design stable.
+- Routine updates should update content/data, not redesign the surface.
+- Redesign only when the goal, success metrics, or main owner focus changes materially.
+
+## Briefing
+
+A briefing is an active notification to the owner. Use it for milestones, important changes, blockers, requests for owner resources or decisions, and final results.
+
+- Use `--mode info` for updates and notifications.
+- Use `--mode approval` when the owner must approve or decide.
+- Keep the text short and clear about why it matters and what action is needed.
+- Attach one image, video, or HTML artifact only when it clarifies the message.
+
+## HTML Artifacts
+
+When creating or materially updating a polished HTML artifact for a Ticlawk dashboard or briefing attachment, use `/vibeshare generate`. If `/vibeshare` is not installed or available in your skills, install it first using the setup instructions at https://vibeshare.page/skill.
+
+For Ticlawk dashboards and briefing HTML attachments, `/vibeshare` is the HTML generation path only. Publish generated dashboards with `ticlawk dashboard set`, and publish briefing text/attachments with `ticlawk briefing publish`; do not use `/vibeshare publish` for these Ticlawk surfaces.
+
+## Services
+
+Use shared services when they match the task. They exist to centralize scarce or risky shared resources such as browser lanes, account sessions, API keys, release/build queues, and external connectors. If a service call fails, report the failure and avoid retry loops.
+
+## Credentials
+
+Request owner-filled credentials when work is blocked on secrets or account access. Never put secrets in `MEMORY.md`, notes, dashboards, briefings, or ordinary chat text unless the product surface explicitly protects them.
+
+Use `ticlawk credential request --name <ENV_VAR>` to create the credential slot. The command returns a mobile deep link; the owner fills it from Settings → Credentials.
+
+## Reminders
+
+Use reminders only for external/time-based future follow-up or visible, persistent resume conditions. Do not use reminders to defer executable work or an owner decision that should be requested now.

package/src/runtimes/_shared/handbook/TASK_WORKER.md

@@ -0,0 +1,14 @@
+# Task Worker
+
+DO NOT EDIT.
+
+Use this in groups where your conversation role is not admin or owner.
+
+## Task Authority Overlay
+
+- In this group context you are not responsible for managing the conversation-level goal loop.
+- Do not create, redefine, or drive the group goal unless an admin/owner explicitly delegates that planning work to you.
+- Focus on task execution: understand the assigned or claimable task, claim when required, perform the work, report the result or blocker, and set the task to `in_review` when ready.
+- If the work appears mis-scoped, underspecified, or blocked on an owner decision, report it to the group/admin instead of taking over the goal loop.
+- If you are not the group admin, do not set tasks to `done`; stop at `in_review` so an admin can validate and close.
+- Report back like a worker handing off useful evidence: say what changed, where the evidence is, what is blocked if anything, and whether it is ready for admin review. Keep it concise and tied to concrete task state.

package/src/runtimes/_shared/standing-prompt.mjs

@@ -1,130 +1,137 @@
 /**
  * Standing prompt injected into every runtime turn.
  *
- * Encodes the agent's communication contract: how to receive messages,
- * how to reply (always via the `ticlawk` CLI), how to handle ambient
- * vs mention traffic, the canonical goal/task protocol, and the per-agent home-dir +
- * MEMORY.md workspace convention. Trim with care — the etiquette
- * sections are load-bearing for multi-agent coordination without
- * runtime-level orchestration.
+ * Keep this thin. The daemon writes the detailed Ticlawk handbook files
+ * into each agent workspace; this prompt only carries the non-negotiable
+ * routing and execution contract plus the handbook index.
  */
 
-import { BRAND_NAME } from './brand.mjs';
-import { buildGoalTaskProtocolPrompt } from './goal-task-protocol.mjs';
+import { selectGoalTaskProtocolOverlays } from './goal-task-protocol.mjs';
 
 function promptBlock(text) {
   return text.trim();
 }
 
-const BASE_STANDING_PROMPT = `You are an agent in ${BRAND_NAME}, a shared
-message service for humans and agents that may be running on different
-computers. You communicate with people and other agents only through the
-${BRAND_NAME} CLI installed at \`ticlawk\`. Your normal assistant output is
-private activity text; it is not sent to users or groups.
-
-## Non-Negotiables
-
-- Use \`ticlawk\` for all external communication. Do not assume normal
-  assistant output reaches anyone.
-- Follow the \`[protocol:goal-task-protocol]\` module for goal/task
-  authority, claim rules, lifecycle, and group/DM scope.
-- Use the exact target from the current wake message when replying.
-- Complete the work before stopping. Progress updates are allowed, but they
-  are not completion.
-- Use normal assistant output as private work trace. External
-  \`ticlawk message send\` messages should be clean, actionable
-  communication: answer, instruction, blocker, decision request, or final
-  result. Do not send private loop/checklist scratchpad unless the owner
-  explicitly asks for that analysis.
-
-## Per-Turn Routine
-
-1. Read \`MEMORY.md\` in your cwd, then only the files/context needed for
-   the current turn. Follow linked notes only when they are relevant.
-2. If there is no concrete inbound message or reminder to handle, stop.
-3. If the message includes \`[charter]\`, treat it as the local
-   conversation goal and role spec.
-4. If the message includes \`[quote]\`, treat the user's text as a response
-   to that quoted message, briefing, or dashboard.
-5. Work the turn to completion, then report via \`ticlawk message send\`.
-
-## ${BRAND_NAME} CLI Surface
-
-- \`ticlawk message send\`: send chat text; body is stdin/heredoc. Use
-  \`--attach <path>\` for files the user should see.
-- \`ticlawk message read\`: read conversation context.
-- \`ticlawk message react\`: lightweight acknowledgement; use sparingly.
-- \`ticlawk server info\`: inspect visible groups, agents, and humans.
-- \`ticlawk group members\`: inspect participants and roles.
-- \`ticlawk charter get/set\`: inspect or update the current conversation's
-  goal and role spec. DM agents may write their DM charter; group charter
-  writes require admin/owner role.
-- \`ticlawk dashboard set/get\`: publish or read owner-facing HTML
-  dashboards. \`set\` reads JSON from stdin: \`{ html_template, data_json }\`.
-  Allowed from DMs, or from groups where this agent is admin/owner.
-- \`ticlawk briefing publish/get\`: publish or read owner-facing briefings.
-  Use \`publish --text "..."\` with \`--mode info\` for updates/notifications
-  or \`--mode approval\` when the owner needs to approve, plus an optional
-  \`--attach <image|video|html>\`.
-  Allowed from DMs, or from groups where this agent is admin/owner.
-- \`ticlawk task list/create/claim/unclaim/update\`: use only as allowed by
-  the goal/task protocol and backend errors.
-- \`ticlawk reminder schedule/snooze/update/cancel\`: use only for external or
-  time-based future follow-up that should be visible and persistent in ${BRAND_NAME}.
-- \`ticlawk service list/info/call\`: use shared services when a published
-  tool matches the task. If a service call fails, report the failure; do not
-  retry in a loop.
-
-## Group Etiquette
-
-- Direct mentions, DMs, assignments, and manual reminders normally require
-  action.
-- Ambient group messages are visible context, not automatic work. Stay quiet
-  unless you are clearly the right responder and can add concrete value.
-- Broadcast requests to the whole group may be answered when your role,
-  expertise, or task ownership makes you an appropriate responder.
-- Do not echo someone else's completion report or PR summary. The person
-  doing the work should report on it.
-- If you still own a concrete blocker before stopping, follow the
-  goal/task protocol for owner intervention; otherwise send one concise
-  actionable message to the person or group that is blocked.
-
-## Workspace And Memory
-
-- Your cwd is a persistent, agent-owned workspace. Use it for memory, notes,
-  artifacts, code checkouts, and task files.
-- \`MEMORY.md\` is the recovery entry point. Keep it concise and link to
-  detailed notes rather than turning it into a transcript.
-- Update memory when you learn durable user preferences, project/domain
-  facts, group context, active work, or collaboration patterns.
-- Record only durable continuity: your role, stable user/project/domain
-  facts, active goals, open blockers, standing decisions, important group
-  context, preferences, and links to notes/artifacts. Do not store chat
-  transcripts, routine progress logs, secrets, or facts already recoverable
-  from the task board, dashboard, briefing, or recent chat history.
-- When working in a repository, choose the specific project directory or
-  worktree inside the workspace before running git or package commands.
-
-## Formatting
-
-- Write bare @handles, #groups, reply targets, and task #N references
-  naturally; ${BRAND_NAME} renders them as links.
-- When placing URLs next to non-ASCII punctuation, wrap the URL in angle
-  brackets or markdown link syntax so punctuation is not swallowed.
-
-## New Message Notifications
-
-If a new message arrives while you are busy, finish the current step before
-pivoting unless the new message clearly supersedes the current work. The
-daemon wakes agents for new messages and reminders; you do not need to poll.
-When future self-resume is needed, schedule a reminder.`;
+function buildBaseStandingPrompt(ctx = {}) {
+  return `${buildCurrentConversationGuide(ctx)}
 
-export function buildStandingPrompt(_ctx = {}) {
-  return promptBlock(`
-${BASE_STANDING_PROMPT}
+${buildReadInstructions(ctx)}
+
+Read other local files only when the current work clearly needs them.`;
+}
+
+function getInboundRaw(ctx = {}) {
+  return ctx?.inbound?.raw && typeof ctx.inbound.raw === 'object'
+    ? ctx.inbound.raw
+    : {};
+}
+
+function readDeliveryReason(ctx = {}) {
+  const raw = getInboundRaw(ctx);
+  return String(raw.reason || '').trim() || 'unknown';
+}
+
+function readString(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readCharter(ctx = {}) {
+  return readString(getInboundRaw(ctx).conversation_charter);
+}
+
+function readConversationName(ctx = {}) {
+  const raw = getInboundRaw(ctx);
+  return readString(raw.conversation_name || raw.conversation_display_name || raw.conversation_id);
+}
+
+function readQuoteKind(ctx = {}) {
+  const raw = getInboundRaw(ctx);
+  const meta = raw.message_metadata || raw.metadata || null;
+  const quote = meta && typeof meta === 'object' ? meta.quote : null;
+  return readString(quote?.kind).toLowerCase();
+}
+
+function hasTaskContext(ctx = {}) {
+  const raw = getInboundRaw(ctx);
+  return raw.task_number != null || readString(raw.task_status) || readString(raw.task_title);
+}
+
+function hasGoalSurfaceContext(ctx = {}) {
+  const kind = readQuoteKind(ctx);
+  return kind === 'dashboard' || kind === 'briefing';
+}
+
+function buildCurrentConversationGuide(ctx = {}) {
+  const { scope, recipientRole, goalAuthority } = selectGoalTaskProtocolOverlays(ctx);
+  const name = readConversationName(ctx);
+  const lines = [];
+
+  if (scope === 'group') {
+    const groupLabel = name ? `#${name}` : 'this group chat';
+    if (goalAuthority) {
+      const roleLabel = recipientRole === 'owner' ? 'owner' : 'admin';
+      lines.push(`You are in a group chat named ${groupLabel}. You are the ${roleLabel}.`);
+    } else {
+      lines.push(`You are in a group chat named ${groupLabel}. You are a member of the group.`);
+      lines.push('You are not the group admin.');
+    }
+  } else {
+    lines.push('You are in a one-on-one conversation with a human user.');
+    lines.push('The incoming message is from a human user.');
+  }
+  return lines.join('\n');
+}
 
-${buildGoalTaskProtocolPrompt(_ctx)}
-`);
+function buildReadInstructions(ctx = {}) {
+  const files = buildReadFileNames(ctx);
+  const memoryFiles = files.filter((name) => name === 'MEMORY.md');
+  const handbookFiles = files.filter((name) => name !== 'MEMORY.md');
+  const memoryList = memoryFiles.map((name, index) => `${index + 1}. \`${name}\``).join('\n');
+  const handbookList = handbookFiles.map((name, index) => `${index + 1}. \`${name}\``).join('\n');
+  return `Read this file every time before acting because it may be updated:
+${memoryList}
+
+Read these files if you haven't already. Otherwise, skip:
+${handbookList}`;
+}
+
+function buildReadFileNames(ctx = {}) {
+  const { scope, goalAuthority } = selectGoalTaskProtocolOverlays(ctx);
+  const reason = readDeliveryReason(ctx);
+  const taskContext = hasTaskContext(ctx) || reason === 'assignment';
+  const goalSurface = hasGoalSurfaceContext(ctx);
+  const docs = [
+    'MEMORY.md',
+    'BASICS.md',
+    'COMMUNICATION.md',
+    'COLLABORATION.md',
+  ];
+
+  if (scope === 'dm') {
+    docs.push('GOAL_TASK_CORE.md', 'GOAL_AUTHORITY.md', 'DM_SCOPE.md');
+    if (goalSurface) docs.push('SURFACES.md');
+    return unique(docs);
+  }
+
+  if (goalAuthority) {
+    docs.push('GOAL_TASK_CORE.md', 'GOAL_AUTHORITY.md', 'GROUP_ADMIN_SCOPE.md');
+    if (goalSurface) docs.push('SURFACES.md');
+    return unique(docs);
+  }
+
+  if (taskContext) {
+    docs.push('GOAL_TASK_CORE.md', 'TASK_WORKER.md', 'GROUP_MEMBER_SCOPE.md');
+  }
+  if (goalSurface) docs.push('SURFACES.md');
+  return unique(docs);
+}
+
+function unique(values) {
+  return [...new Set(values)];
+}
+
+export function buildStandingPrompt(_ctx = {}) {
+  return promptBlock(buildBaseStandingPrompt(_ctx));
 }
 
 const STANDING_PROMPT = buildStandingPrompt();

package/src/runtimes/_shared/wake-prompt.mjs

@@ -2,9 +2,9 @@
  * Per-turn inbound wake prompt builder.
  *
  * Standing prompts define durable runtime behavior. This module owns the
- * dynamic wrapper around each delivered Ticlawk message: envelope metadata,
- * charter/quote context, group context, and the explicit "reply via
- * ticlawk" instruction that accompanies the concrete inbound turn.
+ * dynamic wrapper around each delivered Ticlawk message: who sent it, why it
+ * reached this agent, the exact reply target, and any attached goal/task/quote
+ * context for this turn.
  */
 
 function promptBlock(text) {
@@ -28,7 +28,7 @@ export function buildEnvelopeTarget(msg) {
   return `#${groupName}`;
 }
 
-export function buildTaskSuffix(msg) {
+export function buildDebugTaskSuffix(msg) {
   if (msg.task_number == null) return '';
   const status = msg.task_status || 'todo';
   const parts = [`task #${msg.task_number} status=${status}`];
@@ -43,7 +43,7 @@ export function buildTaskSuffix(msg) {
   return ` [${parts.join(' ')}]`;
 }
 
-export function buildReactionsSuffix(msg) {
+export function buildDebugReactionsSuffix(msg) {
   const entries = Array.isArray(msg.reactions_summary) ? msg.reactions_summary : [];
   if (entries.length === 0) return '';
   return ` [reactions: ${entries.join('; ')}]`;
@@ -53,58 +53,52 @@ function normalizeDeliveryReasonForPrompt(reason) {
   return reason === 'thread_follow' ? 'reply_follow' : reason;
 }
 
-export function buildEnvelopeHeader(msg) {
+export function buildDebugEnvelopeHeader(msg) {
   const target = buildEnvelopeTarget(msg);
   const msgId = msg.id || msg.message_id || '';
   const seq = msg.seq != null ? msg.seq : '';
   const time = msg.created_at || new Date().toISOString();
   const type = msg.sender_type || 'human';
   const sender = msg.sender_display_name || msg.sender_user_id || msg.sender_agent_id || 'unknown';
-  // `reason` tells the agent how this delivery was routed: 'mention'
-  // / 'assignment' = you were directly addressed → respond by default;
-  // 'ambient' = you are in the room and saw it → respond only if
-  // clearly the right responder; 'dm' / 'reply_follow' / 'manual' =
-  // the legacy direct paths. The agent's behaviour split is in the
-  // standing prompt; we just surface the field.
+  const convType = msg.conversation_type || 'dm';
   const displayReason = normalizeDeliveryReasonForPrompt(msg.reason || '');
   const reason = displayReason ? ` reason=${displayReason}` : '';
-  return `[target=${target} msg=${msgId} seq=${seq} time=${time} type=${type}${reason}] @${sender}:`;
+  const recipientRole = String(msg.recipient_conversation_role || msg.recipient_role || '').trim().toLowerCase();
+  const role = convType === 'group' && recipientRole ? ` role=${recipientRole}` : '';
+  return `[target=${target} msg=${msgId} seq=${seq} time=${time} type=${type}${reason}${role}] @${sender}:`;
 }
 
+export const buildEnvelopeHeader = buildDebugEnvelopeHeader;
+
 export function buildGroupContextBlock(msg) {
   // Only useful in groups — DMs don't need group-purpose context.
   if ((msg.conversation_type || 'dm') !== 'group') return '';
   const lines = [];
   const name = msg.conversation_name || msg.conversation_display_name || '';
-  if (name) lines.push(`name: ${name}`);
+  if (name) lines.push(`Group: #${name}`);
   const description = (msg.conversation_description || '').trim();
-  if (description) lines.push(`purpose: ${description}`);
+  if (description) lines.push(`Purpose: ${description}`);
   if (lines.length === 0) return '';
-  return promptBlock(`
-Group context:
-${lines.map((l) => `  ${l}`).join('\n')}
-Use \`ticlawk group members --target <target>\` if you need to see who else is here.
-`);
+  return lines.join('\n');
 }
 
-// Charter is the group's local markdown spec. It's a stable
-// prefix-cacheable block — same bytes across every turn in the same
-// conversation — so it sits above the per-turn envelope.
 export function buildCharterBlock(msg) {
   const charter = (msg.conversation_charter || '').trim();
   if (!charter) return '';
   return promptBlock(`
-[charter]
+Goal and role assignments for this conversation:
 ${charter}
-[/charter]
 `);
 }
 
-// Quote block: surfaced just above the user's reply so the agent sees
-// what artifact the reply is *about*. Source of truth is
-// `messages.metadata.quote = { kind, ref, snippet }`. We render a
-// short, prefix-cache-friendly block and tell the agent how to fetch
-// the full content if needed.
+export function buildGoalStateBlock(msg) {
+  if ((msg.conversation_charter || '').trim()) return '';
+  const convType = msg.conversation_type || 'dm';
+  return convType === 'group'
+    ? 'This group has no specific goal right now.'
+    : 'This conversation has no specific goal right now.';
+}
+
 export function buildQuoteBlock(msg, target = '') {
   const meta = msg.message_metadata || msg.metadata || null;
   const quote = meta && typeof meta === 'object' ? meta.quote : null;
@@ -120,50 +114,115 @@ export function buildQuoteBlock(msg, target = '') {
       : kind === 'message'
         ? `ticlawk message read --target ${JSON.stringify(target)} --around ${ref}`
         : '';
-  const snippetLine = snippet ? `\n  "${snippet.replace(/"/g, '\\"')}"` : '';
-  const fetchLine = fetchHint ? `\n  fetch: ${fetchHint}` : '';
+  const lines = [
+    `The incoming message is a reply to a ${kind}.`,
+    `Referenced ${kind}: \`${ref}\``,
+  ];
+  if (snippet) lines.push(`Quoted snippet: ${snippet}`);
+  if (fetchHint) lines.push(`Fetch it if needed: \`${fetchHint}\``);
+  return lines.join('\n');
+}
+
+function senderDescription(msg) {
+  const type = msg.sender_type === 'agent' ? 'an agent' : 'a human user';
+  const sender = msg.sender_display_name || msg.sender_user_id || msg.sender_agent_id || '';
+  return sender ? `@${sender}, ${type}` : type;
+}
+
+function conversationLabel(msg, target) {
+  const convType = msg.conversation_type || 'dm';
+  if (convType === 'dm') return 'a one-on-one conversation';
+  return target || 'this group';
+}
+
+function buildMessageSummary(msg, target) {
+  const convType = msg.conversation_type || 'dm';
+  const reason = normalizeDeliveryReasonForPrompt(msg.reason || '');
+  const sender = senderDescription(msg);
+  const where = conversationLabel(msg, target);
+
+  if (convType === 'dm') {
+    return `This is a one-on-one message from ${sender}.`;
+  }
+  if (reason === 'assignment') {
+    return `This message assigns or routes work to you in ${where}.\nSender: ${sender}`;
+  }
+  if (reason === 'ambient') {
+    return `This message was shared as background context in ${where}.\nIt is not assigned work.\nSender: ${sender}`;
+  }
+  if (reason === 'mention') {
+    return `You were mentioned in ${where} by ${sender}.`;
+  }
+  if (reason === 'reply_follow') {
+    return `This is a reply in ${where} from ${sender}.`;
+  }
+  if (reason === 'manual') {
+    return `This is a manual wake-up or reminder for ${where}.\nSource: ${sender}`;
+  }
+  return `This is a message in ${where} from ${sender}.`;
+}
+
+function buildTaskDetailsBlock(msg) {
+  if (msg.task_number == null) return '';
+  const lines = [`Task #${msg.task_number} is currently \`${msg.task_status || 'todo'}\`.`];
+  if (msg.task_title) lines.push(`Task title: ${msg.task_title}`);
+  if (msg.task_assignee_agent_id || msg.task_assignee_user_id) {
+    const t = msg.task_assignee_type || 'agent';
+    const id = msg.task_assignee_agent_id || msg.task_assignee_user_id;
+    lines.push(`Assignee: ${t} \`${id}\``);
+  }
+  return lines.join('\n');
+}
+
+function buildReactionsBlock(msg) {
+  const entries = Array.isArray(msg.reactions_summary) ? msg.reactions_summary : [];
+  if (entries.length === 0) return '';
+  return `Recent reactions: ${entries.join('; ')}`;
+}
+
+function buildContentBlock(rawText) {
+  const text = String(rawText || '').trim();
+  if (!text) return '';
   return promptBlock(`
-[quote
-  kind=${kind} ref=${ref}${snippetLine}${fetchLine}
-[/quote]
+Content:
+${text}
 `);
 }
 
-// Wrap each per-turn message with an explicit reply instruction so the
-// runtime LLM never has to remember the standing prompt to figure out
-// HOW to reply. Codex in particular treats the developerInstructions as
-// background and ignores the chat-send pattern without this per-turn
-// nudge.
-export function buildWakePromptText({ envelopeHeader, target, rawText, groupContext, charterBlock, quoteBlock }) {
-  const body = `${envelopeHeader} ${rawText || ''}`.trim();
-  const contextPrefix = [charterBlock, quoteBlock].filter(Boolean).join('\n\n');
+// Wrap each per-turn message with the concrete dynamic context for this
+// delivery. Durable communication rules live in COMMUNICATION.md; this block
+// only carries the current message and its exact reply target.
+export function buildWakePromptText({ messageSummary, target, rawText, groupContext, charterBlock, goalStateBlock, quoteBlock, taskDetails, reactionsBlock }) {
+  const contextPrefix = [charterBlock, goalStateBlock, quoteBlock].filter(Boolean).join('\n\n');
   const prefix = contextPrefix ? `${contextPrefix}\n\n` : '';
-  const groupSection = groupContext ? `\n\n${groupContext}` : '';
+  const detailBlocks = [
+    messageSummary,
+    `Reply target: \`${target}\``,
+    groupContext,
+    taskDetails ? `Task details:\n${taskDetails}` : '',
+    reactionsBlock,
+    buildContentBlock(rawText),
+  ].filter(Boolean).join('\n\n');
   return promptBlock(`
 ${prefix}New message received:
 
-${body}${groupSection}
-
-Respond as appropriate — reply using \`ticlawk message send --target "${target}"\` (body via stdin / heredoc), or take action as needed. Complete ALL your work before stopping.
-Use the exact target above when replying.
-
-IMPORTANT: If the message requires multi-step work (research, code changes, testing), complete ALL steps before stopping. Sending a progress update does NOT mean your task is done — only stop when you have NO more work to do. The daemon will wake you again automatically when new messages arrive.
+${detailBlocks}
 `);
 }
 
 export function buildInboundWakePrompt(msg) {
   const rawText = msg.text || '';
-  const baseHeader = buildEnvelopeHeader(msg);
-  // Task + reactions suffixes are appended inside the envelope so the
-  // agent can see task status and recent acknowledgements at a glance.
-  const header = baseHeader + buildTaskSuffix(msg) + buildReactionsSuffix(msg);
+  const baseHeader = buildDebugEnvelopeHeader(msg);
+  const header = baseHeader + buildDebugTaskSuffix(msg) + buildDebugReactionsSuffix(msg);
   const target = buildEnvelopeTarget(msg);
   const groupContext = buildGroupContextBlock(msg);
   const charterBlock = buildCharterBlock(msg);
+  const goalStateBlock = buildGoalStateBlock(msg);
   const quoteBlock = buildQuoteBlock(msg, target);
-  const text = header
-    ? buildWakePromptText({ envelopeHeader: header, target, rawText, groupContext, charterBlock, quoteBlock })
-    : rawText;
+  const messageSummary = buildMessageSummary(msg, target);
+  const taskDetails = buildTaskDetailsBlock(msg);
+  const reactionsBlock = buildReactionsBlock(msg);
+  const text = buildWakePromptText({ messageSummary, target, rawText, groupContext, charterBlock, goalStateBlock, quoteBlock, taskDetails, reactionsBlock });
   return {
     header,
     target,