heyio 0.2.0 → 0.3.0

package/dist/copilot/event-summary.js

@@ -0,0 +1,286 @@
+// Tiered activity log normalizer.
+//
+// Converts raw TaskStreamEvent records (forwarded from the Copilot SDK
+// session) into "activity entries" that present a clean human-readable
+// summary. Each entry preserves the underlying raw payload for drill-down so
+// no information is lost.
+//
+// Used by:
+//   - GET /tasks/:taskId/activity (full collapsed list)
+//   - the SSE per-event payload (single-event summary attached alongside raw)
+//   - the TUI /activity command
+const TOOL_VERBS = {
+    bash: "Ran shell command",
+    shell: "Ran shell command",
+    read_file: "Read file",
+    view: "Read file",
+    create: "Created file",
+    edit: "Edited file",
+    str_replace_editor: "Edited file",
+    grep: "Searched code",
+    glob: "Searched filenames",
+    web_fetch: "Fetched URL",
+    github: "Called GitHub API",
+    delegate_to_teammate: "Delegated to teammate",
+    squad_delegate: "Delegated to squad",
+    squad_status: "Listed squads",
+    squad_agents: "Listed squad agents",
+    squad_set_lead: "Set squad lead",
+    squad_set_qa: "Set squad QA",
+    squad_task_status: "Checked task status",
+    squad_task_reviews: "Read task reviews",
+    squad_log_decision: "Logged squad decision",
+    squad_schedule_create: "Created squad schedule",
+    squad_schedule_list: "Listed squad schedules",
+    squad_schedule_run_now: "Fired squad schedule",
+    wiki_read: "Read wiki page",
+    wiki_write: "Wrote wiki page",
+    wiki_search: "Searched wiki",
+    wiki_list: "Listed wiki pages",
+    skill_list: "Listed skills",
+    skill_install: "Installed skill",
+    skill_remove: "Removed skill",
+    skill_search: "Searched skills registry",
+    config_update: "Updated config",
+    check_update: "Checked for IO update",
+    file_ops: "File operation",
+};
+function trunc(s, n) {
+    if (!s)
+        return "";
+    const flat = s.replace(/\s+/g, " ").trim();
+    return flat.length > n ? flat.slice(0, n - 1) + "…" : flat;
+}
+function pickArgSummary(toolName, args) {
+    if (!args)
+        return "";
+    const a = args;
+    switch (toolName) {
+        case "bash":
+        case "shell": {
+            const cmd = typeof a.command === "string" ? a.command : "";
+            return trunc(cmd, 80);
+        }
+        case "read_file":
+        case "view":
+        case "create":
+        case "edit":
+        case "str_replace_editor": {
+            const p = typeof a.path === "string" ? a.path : (typeof a.file_path === "string" ? a.file_path : "");
+            return p;
+        }
+        case "grep": {
+            const pat = typeof a.pattern === "string" ? `"${trunc(a.pattern, 40)}"` : "";
+            const paths = Array.isArray(a.paths) ? a.paths.join(", ") : (typeof a.paths === "string" ? a.paths : "");
+            return [pat, paths].filter(Boolean).join(" in ");
+        }
+        case "glob": {
+            return typeof a.pattern === "string" ? a.pattern : "";
+        }
+        case "web_fetch": {
+            return typeof a.url === "string" ? a.url : "";
+        }
+        case "delegate_to_teammate": {
+            const teammate = typeof a.teammate === "string" ? a.teammate : "";
+            const task = typeof a.task === "string" ? trunc(a.task, 60) : "";
+            return [teammate, task].filter(Boolean).join(": ");
+        }
+        case "squad_delegate": {
+            const slug = typeof a.slug === "string" ? a.slug : "";
+            const agent = typeof a.agent === "string" ? ` → ${a.agent}` : "";
+            const task = typeof a.task === "string" ? trunc(a.task, 50) : "";
+            return `${slug}${agent}${task ? `: ${task}` : ""}`;
+        }
+        case "wiki_read":
+        case "wiki_write":
+        case "wiki_delete": {
+            return typeof a.path === "string" ? a.path : "";
+        }
+        case "wiki_search":
+        case "skill_search": {
+            return typeof a.query === "string" ? `"${trunc(a.query, 40)}"` : "";
+        }
+        case "github": {
+            const ep = typeof a.endpoint === "string" ? a.endpoint : "";
+            const method = typeof a.method === "string" ? a.method : "";
+            return [method, ep].filter(Boolean).join(" ");
+        }
+        case "file_ops": {
+            const op = typeof a.operation === "string" ? a.operation : "";
+            const p = typeof a.path === "string" ? a.path : "";
+            return [op, p].filter(Boolean).join(" ");
+        }
+        default: {
+            // Best-effort: stringify the first arg value.
+            const k = Object.keys(a)[0];
+            if (!k)
+                return "";
+            const v = a[k];
+            const s = typeof v === "string" ? v : JSON.stringify(v);
+            return `${k}=${trunc(s ?? "", 50)}`;
+        }
+    }
+}
+/** Summarize a single TaskStreamEvent. */
+export function summarizeEvent(ev) {
+    const data = (ev.data ?? {});
+    const base = { ts: ev.ts, rawType: ev.type, raw: ev.data };
+    switch (ev.type) {
+        case "assistant.intent": {
+            const intent = typeof data.intent === "string" ? data.intent : "";
+            return { ...base, kind: "reasoning", icon: "🧠", summary: intent || "(intent)" };
+        }
+        case "assistant.reasoning": {
+            const content = typeof data.content === "string" ? data.content : "";
+            return {
+                ...base,
+                kind: "reasoning",
+                icon: "🧠",
+                summary: trunc(content, 140) || "(reasoning)",
+                detail: content,
+            };
+        }
+        case "assistant.message": {
+            const content = typeof data.content === "string" ? data.content : "";
+            return {
+                ...base,
+                kind: "message",
+                icon: "💬",
+                summary: trunc(content, 200) || "(empty message)",
+                detail: content,
+            };
+        }
+        case "assistant.turn_start":
+            return { ...base, kind: "system", icon: "▶️", summary: "Turn started" };
+        case "assistant.turn_end":
+            return { ...base, kind: "system", icon: "⏹️", summary: "Turn ended" };
+        case "tool.execution_start": {
+            const name = typeof data.toolName === "string" ? data.toolName : "tool";
+            const verb = TOOL_VERBS[name] ?? `Used ${name}`;
+            const args = pickArgSummary(name, data.arguments);
+            return {
+                ...base,
+                kind: "tool",
+                icon: "🔧",
+                summary: args ? `${verb} — ${args}` : verb,
+                toolCallId: typeof data.toolCallId === "string" ? data.toolCallId : undefined,
+                status: "pending",
+            };
+        }
+        case "tool.execution_complete": {
+            const success = data.success === true;
+            const result = (data.result ?? {});
+            const content = typeof result.content === "string" ? result.content : "";
+            return {
+                ...base,
+                kind: "tool",
+                icon: success ? "✅" : "❌",
+                summary: success ? "Tool completed" : "Tool failed",
+                detail: trunc(content, 300),
+                toolCallId: typeof data.toolCallId === "string" ? data.toolCallId : undefined,
+                status: success ? "success" : "error",
+            };
+        }
+        case "tool.execution_progress": {
+            const message = typeof data.message === "string" ? data.message : "";
+            return {
+                ...base,
+                kind: "tool",
+                icon: "⏳",
+                summary: trunc(message, 140) || "Tool progress",
+                toolCallId: typeof data.toolCallId === "string" ? data.toolCallId : undefined,
+                status: "pending",
+            };
+        }
+        case "session.error": {
+            const msg = typeof data.message === "string" ? data.message : (typeof data.error === "string" ? data.error : "");
+            return { ...base, kind: "outcome", icon: "❌", summary: `Error: ${trunc(msg, 160) || "session error"}` };
+        }
+        case "session.warning": {
+            const msg = typeof data.message === "string" ? data.message : "";
+            return { ...base, kind: "outcome", icon: "⚠️", summary: `Warning: ${trunc(msg, 160) || "session warning"}` };
+        }
+        case "task.done": {
+            const r = typeof data.result === "string" ? data.result : "";
+            return { ...base, kind: "outcome", icon: "✅", summary: "Task completed", detail: trunc(r, 300) };
+        }
+        case "task.failed": {
+            const e = typeof data.error === "string" ? data.error : "";
+            return { ...base, kind: "outcome", icon: "❌", summary: `Task failed: ${trunc(e, 160)}` };
+        }
+        case "task.cancelled":
+            return { ...base, kind: "outcome", icon: "🛑", summary: "Task cancelled" };
+        case "task.review":
+            return {
+                ...base,
+                kind: "outcome",
+                icon: data.approved ? "👍" : "👎",
+                summary: `Review by ${data.reviewer ?? "?"}: ${data.approved ? "APPROVED" : "REJECTED"}${data.is_qa ? " (QA)" : ""}`,
+                detail: typeof data.comments === "string" ? data.comments : undefined,
+            };
+        case "task.review_complete":
+            return {
+                ...base,
+                kind: "outcome",
+                icon: data.promoted ? "🚀" : "ℹ️",
+                summary: data.promoted
+                    ? `Promoted PR: ${data.prUrl ?? ""}`
+                    : `Review complete: ${typeof data.reason === "string" ? data.reason : ""}`,
+            };
+        case "task.review_advisory":
+            return {
+                ...base,
+                kind: "outcome",
+                icon: "ℹ️",
+                summary: typeof data.reason === "string" ? data.reason : "Advisory review note",
+            };
+        case "task.review_error": {
+            const e = typeof data.error === "string" ? data.error : "";
+            return { ...base, kind: "outcome", icon: "❌", summary: `Review error: ${trunc(e, 160)}` };
+        }
+        default:
+            return { ...base, kind: "system", icon: "•", summary: ev.type };
+    }
+}
+/**
+ * Collapse a stream of events into the activity log. Tool start + complete
+ * pairs are merged into one entry (success/error and detail attached).
+ * Streaming deltas (assistant.message_delta, assistant.reasoning_delta,
+ * tool.execution_partial_result) are dropped — the "complete" sibling event
+ * is what we summarize.
+ */
+export function summarize(events) {
+    const out = [];
+    const toolIndex = new Map(); // toolCallId → index into out
+    for (const ev of events) {
+        if (ev.type === "assistant.message_delta" ||
+            ev.type === "assistant.reasoning_delta" ||
+            ev.type === "tool.execution_partial_result") {
+            continue;
+        }
+        const entry = summarizeEvent(ev);
+        if (entry.kind === "tool" && entry.toolCallId) {
+            const existing = toolIndex.get(entry.toolCallId);
+            if (existing != null && entry.status && entry.status !== "pending") {
+                // Merge: keep the verb from the start event, add status/detail/icon from completion.
+                const prior = out[existing];
+                out[existing] = {
+                    ...prior,
+                    icon: entry.icon,
+                    status: entry.status,
+                    detail: entry.detail ?? prior.detail,
+                    // Append a brief outcome marker if the start summary is the only descriptor.
+                    summary: prior.summary,
+                    // Keep the completion event raw available for drill-down by stashing on detail when no detail present
+                    raw: { start: prior.raw, complete: entry.raw },
+                    rawType: `${prior.rawType}+${entry.rawType}`,
+                };
+                continue;
+            }
+            toolIndex.set(entry.toolCallId, out.length);
+        }
+        out.push(entry);
+    }
+    return out;
+}
+//# sourceMappingURL=event-summary.js.map

package/dist/copilot/orchestrator.js

@@ -3,8 +3,8 @@ import { approveAll, } from "@github/copilot-sdk";
 import { config } from "../config.js";
 import { SESSIONS_DIR, IO_VERSION } from "../paths.js";
 import { getState, setState, deleteState, logConversation } from "../store/db.js";
-import { clearStaleTasks, getTask } from "../store/tasks.js";
-import { getSquad, listSquads, createSquad, deleteSquad, logDecision, getDecisionsSummary, updateSquadStatus, addSquadAgent, listSquadAgents, removeSquadAgent, } from "../store/squads.js";
+import { clearStaleTasks, getTask, getTaskReviews } from "../store/tasks.js";
+import { getSquad, listSquads, createSquad, deleteSquad, logDecision, getDecisionsSummary, updateSquadStatus, addSquadAgent, listSquadAgents, removeSquadAgent, setSquadLead, getSquadLead, setSquadQA, } from "../store/squads.js";
 import { readPage, writePage, assertPagePath, deletePage, listPages } from "../wiki/fs.js";
 import { resolveModelTiers } from "./model-router.js";
 import { searchWiki, getWikiSummary } from "../wiki/search.js";
@@ -73,8 +73,24 @@ function getToolDeps() {
             model_tier: a.model_tier,
             personality: a.personality,
             status: a.status,
+            is_lead: a.is_lead,
+            is_qa: a.is_qa,
         })),
         removeSquadAgent,
+        setSquadLead,
+        getSquadLead: (slug) => {
+            const lead = getSquadLead(slug);
+            return lead
+                ? { character_name: lead.character_name, role_title: lead.role_title }
+                : undefined;
+        },
+        setSquadQA,
+        getTaskReviews: (taskId) => getTaskReviews(taskId).map((r) => ({
+            reviewer_character: r.reviewer_character,
+            approved: r.approved,
+            comments: r.comments,
+            squad_slug: r.squad_slug,
+        })),
         listSkills,
         installSkill,
         removeSkill,
@@ -92,6 +108,30 @@ function toolFingerprint(tools) {
     const names = (tools ?? []).map((t) => t.name).sort().join(",");
     return crypto.createHash("sha256").update(`${IO_VERSION}:${names}`).digest("hex").slice(0, 16);
 }
+function buildSquadRoster() {
+    const squads = listSquads();
+    if (squads.length === 0)
+        return "";
+    return squads
+        .map((s) => {
+        const agents = listSquadAgents(s.slug);
+        const lead = agents.find((a) => a.is_lead === 1);
+        const agentList = agents
+            .map((a) => {
+            const badges = [
+                a.is_lead === 1 ? "⭐ LEAD" : "",
+                a.is_qa === 1 ? "🛡️ QA" : "",
+            ]
+                .filter(Boolean)
+                .join(", ");
+            return `  - ${a.character_name} (${a.role_title})${badges ? ` [${badges}]` : ""}`;
+        })
+            .join("\n");
+        const leadLine = lead ? `\nTeam Lead: ${lead.character_name}` : "";
+        return `**${s.name}** (\`${s.slug}\`) — ${s.status}\n📁 ${s.project_path}${leadLine}\n${agentList || "  _(no agents yet)_"}`;
+    })
+        .join("\n\n");
+}
 function buildFullSessionConfig() {
     const { tools, skillDirectories } = getSessionConfig();
     return {
@@ -102,6 +142,7 @@ function buildFullSessionConfig() {
             content: getOrchestratorSystemMessage({
                 selfEditEnabled: config.selfEditEnabled,
                 memorySummary: getWikiSummary() || undefined,
+                squadRoster: buildSquadRoster() || undefined,
             }),
         },
         tools,

package/dist/copilot/scheduler.js

@@ -0,0 +1,155 @@
+// Squad scheduler — fires recurring "stand-up" meetings on a cron schedule.
+//
+// Design:
+//   - Runs as a single setInterval on the daemon (TICK_MS).
+//   - Each tick: fetch schedules whose next_run_at is in the past.
+//   - For each due schedule: compose a stand-up prompt and delegate it to the
+//     squad lead via the existing delegateToAgent() pipeline. The lead then
+//     orchestrates the agenda by delegating subtasks to teammates internally.
+//   - After firing, advance next_run_at to the next cron occurrence.
+//
+// Schedules survive daemon restarts because next_run_at is persisted. On
+// startup we backfill any next_run_at fields that became stale (or are NULL).
+import { listSchedules, listDueSchedules, recordScheduleRun, updateNextRun } from "../store/schedules.js";
+import { getSquad } from "../store/squads.js";
+import { delegateToAgent } from "./agents.js";
+import { nextRun } from "./cron.js";
+const TICK_MS = 30_000;
+const AGENDA_BLOCKS = {
+    triage: `**Triage**
+- Use the GitHub CLI (\`gh issue list\`) to pull open issues with the \`needs-triage\` label.
+- For each issue: read the body and decide on appropriate labels (priority, area, type, etc).
+- Apply labels with \`gh issue edit <num> --add-label "..."\` and remove \`needs-triage\` once labelled.
+- If the issue lacks information, post a clarifying comment with \`gh issue comment\` instead of labelling, and leave \`needs-triage\` on it.`,
+    prioritize: `**Prioritize**
+- Identify open issues that are ready to be worked on: properly labelled, not blocked, no \`needs-triage\` or \`needs-review\` label, no open PR already addressing them.
+- Rank by priority labels and surface the top candidate.
+- After the stand-up, the team lead should immediately begin work on the highest-priority ready issue by delegating it to the right teammate.`,
+    ideation: `**Ideation**
+- Brainstorm 1–3 concrete improvements or new features for the project.
+- Discuss as a team (use \`delegate_to_teammate\` to gather input from members whose expertise fits the idea).
+- For each idea the team agrees on, create a GitHub issue with \`gh issue create\` tagged with the \`needs-review\` label so the human can approve it before work begins.`,
+};
+function buildStandupPrompt(squad, schedule) {
+    const blocks = schedule.agenda
+        .map((item) => AGENDA_BLOCKS[item] ?? `**${item}** _(no built-in template — improvise)_`)
+        .join("\n\n");
+    const notes = schedule.notes ? `\n\n**Operator notes:** ${schedule.notes}` : "";
+    return `# Scheduled stand-up: ${schedule.name}
+
+You are the team lead for the **${squad.name}** squad (\`${squad.slug}\`). Run a stand-up meeting now.
+
+**Project path:** \`${squad.project_path}\` — \`cd\` here before invoking the GitHub CLI so it picks up the right repo.
+
+**Agenda** (work through these in order; use \`delegate_to_teammate\` to pull in the right specialist for each item):
+
+${blocks}
+
+When you finish the agenda, summarise what was triaged, what was prioritised (and what work you've kicked off), and what new issues were filed during ideation.${notes}`;
+}
+let timer;
+const inFlight = new Set();
+async function fireSchedule(schedule) {
+    if (inFlight.has(schedule.id))
+        return;
+    const squad = getSquad(schedule.squad_slug);
+    if (!squad) {
+        console.error(`[io] scheduler: squad "${schedule.squad_slug}" missing for schedule ${schedule.id}; disabling next_run_at`);
+        updateNextRun(schedule.id, null);
+        return;
+    }
+    inFlight.add(schedule.id);
+    const ranAt = new Date();
+    let nextIso = null;
+    try {
+        nextIso = nextRun(schedule.cron_expr, ranAt).toISOString();
+    }
+    catch (err) {
+        console.error(`[io] scheduler: cron parse error for schedule ${schedule.id}:`, err instanceof Error ? err.message : err);
+    }
+    recordScheduleRun(schedule.id, ranAt, nextIso);
+    const prompt = buildStandupPrompt({ name: squad.name, slug: squad.slug, project_path: squad.project_path }, schedule);
+    console.log(`[io] scheduler: firing schedule "${schedule.name}" for squad "${squad.slug}" (next run: ${nextIso ?? "never"})`);
+    try {
+        await delegateToAgent(squad.slug, prompt, () => {
+            // No-op: result is recorded on the agent task; the standup is fire-and-forget.
+        });
+    }
+    catch (err) {
+        console.error(`[io] scheduler: failed to delegate stand-up for schedule ${schedule.id}:`, err instanceof Error ? err.message : err);
+    }
+    finally {
+        inFlight.delete(schedule.id);
+    }
+}
+async function tick() {
+    let due;
+    try {
+        due = listDueSchedules(new Date());
+    }
+    catch (err) {
+        console.error("[io] scheduler tick failed:", err instanceof Error ? err.message : err);
+        return;
+    }
+    for (const s of due) {
+        // Sequential — avoid stampeding multiple stand-ups simultaneously.
+        await fireSchedule(s);
+    }
+}
+/**
+ * Backfill next_run_at for any schedules where it's NULL or already in the past
+ * but should not have fired (e.g. daemon was offline). We deliberately advance
+ * to the next future occurrence rather than replaying missed runs.
+ */
+export function reconcileSchedules(now = new Date()) {
+    for (const s of listSchedules()) {
+        if (!s.enabled)
+            continue;
+        let needsUpdate = false;
+        if (!s.next_run_at) {
+            needsUpdate = true;
+        }
+        else {
+            const next = new Date(s.next_run_at);
+            if (Number.isNaN(next.getTime()) || next <= now)
+                needsUpdate = true;
+        }
+        if (!needsUpdate)
+            continue;
+        try {
+            const next = nextRun(s.cron_expr, now);
+            updateNextRun(s.id, next.toISOString());
+        }
+        catch (err) {
+            console.error(`[io] scheduler: invalid cron "${s.cron_expr}" on schedule ${s.id}; disabling next_run_at:`, err instanceof Error ? err.message : err);
+            updateNextRun(s.id, null);
+        }
+    }
+}
+export function startScheduler() {
+    if (timer)
+        return;
+    reconcileSchedules();
+    timer = setInterval(() => {
+        void tick();
+    }, TICK_MS);
+    if (typeof timer.unref === "function")
+        timer.unref();
+    console.log(`[io] Scheduler started (tick every ${TICK_MS / 1000}s)`);
+}
+export function stopScheduler() {
+    if (!timer)
+        return;
+    clearInterval(timer);
+    timer = undefined;
+}
+/** Manually fire a schedule. Used by squad_schedule_run_now. */
+export async function runScheduleNow(scheduleId) {
+    const all = listSchedules();
+    const s = all.find((x) => x.id === scheduleId);
+    if (!s)
+        return { ok: false, error: `Schedule ${scheduleId} not found` };
+    await fireSchedule(s);
+    return { ok: true };
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/copilot/system-message.js

@@ -18,8 +18,8 @@ This restriction does NOT apply to:
 - Any files outside the IO installation directory
 `;
     const squadBlock = opts?.squadRoster
-        ? `\n### Active Squads\n${opts.squadRoster}\n`
-        : "";
+        ? `\n## Active Squads\nThe following squads are available. Route relevant coding requests directly to them.\n\n${opts.squadRoster}\n`
+        : `\n## Active Squads\nNo squads created yet. Use \`squad_create\` to set up a project squad.\n`;
     const osName = process.platform === "darwin" ? "macOS"
         : process.platform === "win32" ? "Windows"
             : "Linux";
@@ -47,12 +47,22 @@ When no source tag is present, assume TUI.
 
 ## Your Role
 
-You receive messages and decide how to handle them:
+You receive messages and decide how to handle them based on a strict routing priority:
 
-- **Direct answer**: For simple questions, general knowledge, status checks — answer directly.
-- **Use tools**: For tasks requiring shell access, file operations, web lookups — use your tools.
-- **Create/delegate to squad**: For coding projects that need persistent context — create a squad with specialized agents.
-- **Use a skill**: If you have a skill for the task, use it.
+### 1. Squad routing (highest priority)
+If **active squads are listed below** and the request is clearly related to one of those projects (coding tasks, bugs, features, issues, PRs, architecture), **delegate immediately to that squad's team lead** using \`squad_delegate\` — do NOT plan the work yourself, do NOT break it into subtasks. Just pass the full request to the lead and let the team handle it internally.
+
+- The team lead will plan and delegate internally to teammates.
+- You do not need to understand the full scope of the work — the lead does.
+- Multiple squads? Pick the one whose \`project_path\` / name best matches the request.
+
+### 2. Direct tools (medium priority)
+For tasks that require shell access, file operations, web lookups, or knowledge base updates — and that are NOT squad project work — use your tools directly. Use a skill if one is available for the task.
+
+### 3. Direct answer (lowest priority)
+For general questions, conversation, status checks, or anything outside the scope of a squad's project — answer directly.
+
+> **Rule**: If a squad exists that covers the topic, always delegate. Never plan or implement squad work yourself.
 ${squadBlock}
 ## Squad System
 
@@ -70,14 +80,41 @@ Squads are persistent project teams with **named specialist agents**. Each squad
 - Check overall status with \`squad_status\`.
 
 ### Delegating Work
-After planning tasks with the user, **use \`squad_delegate\` to send each task to the right agent**:
-1. Plan the work with the user (break into concrete tasks).
-2. Call \`squad_delegate\` with the squad slug and task. Optionally specify an \`agent\` (character name) to target a specific specialist. If omitted, the system picks the best available agent.
-3. The agent works autonomously in the background with their specialized system prompt.
-4. Use \`squad_task_status\` to check progress and retrieve results.
-5. Report results back to the user, mentioning the character name.
-
-You can delegate multiple tasks to different agents in parallel.
+**Do not plan squad work yourself.** When a squad-relevant request arrives:
+1. Call \`squad_delegate\` with the squad slug and the full request (as-is from the user). Do NOT specify an agent — let it route to the team lead automatically.
+2. The team lead breaks it down and delegates to teammates internally via \`delegate_to_teammate\`. If no lead is designated, the system falls back to the first idle agent.
+3. Use \`squad_task_status\` to monitor progress and report results back to the user.
+
+Only specify an \`agent\` when the user **explicitly asks** to target a specific squad member by name.
+
+### Team Leads
+Every squad should have a **team lead**. After building the team with \`squad_add_agent\`, designate one agent as the lead using \`squad_set_lead\`. The lead receives delegated tasks (when no specific agent is targeted), breaks them into subtasks, and assigns work to teammates via the lead-only \`delegate_to_teammate\` tool. This keeps coordination inside the squad rather than forcing IO to micro-manage assignments.
+
+### Peer Review & QA Approvals
+When an agent finishes a task, the other squad members automatically review the work and vote APPROVED or REJECTED. Reviews are recorded and emitted as \`task.review\` events.
+
+- **Required**: every squad must have at least one agent designated as QA via \`squad_set_qa\`, AND at least one agent whose role title implies a testing/quality focus (e.g. role contains "test", "qa", or "quality"). Both can be the same agent.
+- \`squad_status\`, \`squad_agents\`, and \`squad_delegate\` will surface a ⚠️ warning when either is missing. Delegation is not blocked, but you should fix the gap before promoting work.
+- **QA agents and the team lead have veto power**: if any QA reviewer or the team lead rejects, the PR stays as a draft. The lead's veto is automatic — no need to also designate them as QA.
+- Non-QA rejections are advisory — they're recorded but don't block promotion.
+- When all QA approvals pass (or no QA agents exist) and the task result contains a GitHub PR URL, the PR is automatically promoted from draft to ready via \`gh pr ready\`.
+- Use \`squad_task_reviews\` to inspect the reviews on any completed task.
+
+### Squad Build Checklist
+After \`squad_create\`, before delegating real work:
+1. Add agents with \`squad_add_agent\` (use roles tailored to the project's stack).
+2. Include at least one **test/quality engineer** role (e.g. "Integration Test Engineer", "QA Specialist", "Quality Reviewer").
+3. Designate a team lead with \`squad_set_lead\`.
+4. Designate at least one QA reviewer with \`squad_set_qa\` (often the same agent as the test engineer).
+
+### Scheduled Stand-ups
+Squads can be put on a recurring cron-style schedule. At the scheduled time IO wakes the team lead, who runs the agenda by delegating to teammates. This runs in the background even when no human is in the TUI/Telegram.
+
+- \`squad_schedule_create\` — create a recurring stand-up. Cron uses standard 5-field syntax: "minute hour day-of-month month day-of-week". Examples: \`0 5 * * *\` (daily 5AM), \`0 9 * * 1-5\` (9AM weekdays), \`30 14 * * 1\` (Mondays 14:30).
+- Built-in agenda items: \`triage\` (process \`needs-triage\` issues), \`prioritize\` (pick highest-priority ready work and start on it), \`ideation\` (brainstorm and open \`needs-review\` issues for the human). Custom items are passed verbatim to the lead.
+- \`squad_schedule_list\`, \`squad_schedule_pause\`, \`squad_schedule_resume\`, \`squad_schedule_delete\`, \`squad_schedule_run_now\` round out the lifecycle.
+
+When a user asks something like "have the IO squad meet every weekday at 5AM to triage and prioritize", call \`squad_schedule_create\` with \`cron: "0 5 * * 1-5"\` and \`agenda: ["triage", "prioritize"]\`.
 
 ### Agent Roles Are Dynamic
 **Do NOT use generic roles** like "developer" or "tester". Analyze the project first and create roles that match its actual technology stack. Examples: