crewly 1.12.1 → 1.13.1

package/dist/cli/backend/src/services/ai/prompt-modules/skills-reference.module.js

@@ -0,0 +1,199 @@
+/**
+ * Skills reference module — tells the agent how to discover and use skills.
+ *
+ * Consolidates skill references, role-based capability descriptions,
+ * and catalog location into a single module. Capabilities are scoped
+ * per-role to avoid blanket authorization (#225).
+ *
+ * Sources: Path A Step 1+6, Path B Section 8, Path C skill instructions.
+ */
+export class SkillsReferenceModule {
+    name = 'skills_references';
+    priority = 5;
+    maxTokens = 800;
+    compactable = false;
+    /**
+     * Always included — agents need to know how to use skills.
+     */
+    shouldInclude(_config) {
+        return true;
+    }
+    /**
+     * Build the skills reference section with catalog location,
+     * role-scoped capabilities, and memory tool instructions.
+     *
+     * @param config - Module configuration with skill paths and role
+     * @returns Formatted markdown skills reference section
+     */
+    async build(config) {
+        const coreSkills = this.buildCoreSkills(config);
+        const capabilities = this.buildCapabilities(config);
+        const communication = this.buildCommunication(config);
+        const safeCallGuide = this.buildSafeCallGuide(config);
+        const parts = [coreSkills, capabilities, communication];
+        if (safeCallGuide) {
+            parts.push(safeCallGuide);
+        }
+        return parts.join('\n\n');
+    }
+    /**
+     * Build the core skills list — available to all roles.
+     */
+    buildCoreSkills(config) {
+        const lines = [
+            '## Available Skills',
+            '',
+            `Bash skills at \`${config.agentSkillsPath}/\`:`,
+            '- `core/recall` — retrieve relevant knowledge from memory',
+            '- `core/remember` — store knowledge for future reference',
+            '- `core/record-learning` — record learnings while working',
+            '- `core/report-status` — report status to team leader or orchestrator',
+            '',
+            '### Follow-up skills (ad-hoc timers and event watchers)',
+            '- `core/schedule-followup` — schedule a future check-in that creates a WorkItem at time T',
+            '    • one-shot: `--in-minutes N` or `--fire-at <ISO8601>`',
+            '    • bounded recurring: `--cron "<expr>" --max-fires N`',
+            '    • target yourself (default) or another agent via `--target`',
+            '- `core/watch-for-event` — fire a WorkItem whenever an event occurs (e.g. `agent:idle`, `task:completed`)',
+            '    • narrow with `--filter-session <session>` or `--filter-json \'{"...":"..."}\'`',
+            '    • cap with `--max-fires` / `--max-idle-fires` so a flapping source does not loop forever',
+            '- `core/cancel-followup` — cancel a trigger you created (`--id` or `--name`)',
+            '- `core/list-my-followups` — list follow-ups owned by your team (audit before adding a new one)',
+            '',
+            '**Follow-up discipline (required):**',
+            '1. Every follow-up must have a **finite end**. Use `maxFires` for recurring, or rely on the default `maxIdleFires=3` auto-cancel.',
+            '2. Call `cancel-followup` the moment you confirm the task is done — do not rely on idle-auto-cancel as your only safety net.',
+            '3. Before scheduling a new watcher on a target, run `list-my-followups --name-prefix watch:` to avoid duplicates.',
+            '4. Prefer `watch-for-event` when you need reactive coverage (agent went idle → check). Prefer `schedule-followup` when you need a wall-clock checkpoint (9am tomorrow → re-prompt).',
+        ];
+        // Orchestrators and TLs get additional coordination skills
+        if (config.role === 'orchestrator') {
+            lines.push('- `core/send-message` — send messages to agents', '- `core/get-sops` — request relevant SOPs', '- Orchestrator skills at `config/skills/orchestrator/`:', '  - `schedule-check` — schedule future check-in reminders', '  - `subscribe-event` — subscribe to agent lifecycle events', '  - `reply-slack` / `reply-chat` — respond to user messages', '  - `reply-gchat` — respond to Google Chat messages', '  - `send-to-remote` / `reply-remote` — send/reply to other Crewly machines', '  - `list-devices` — discover connected Crewly devices', '  - `delegate-task` / `assign-task` — assign work to agents', '  - `get-team-status` / `get-agent-status` — monitor team state', '  - `create-team` / `update-team` / `start-team` / `stop-team` — team management', '  - `start-agent` / `stop-agent` / `terminate-agent` — agent lifecycle', '  - `create-cron` / `list-cron` / `update-cron` / `cancel-cron` — recurring tasks', '', '**IMPORTANT:** You have ALL skills listed above. Never say you lack a skill — if unsure, check the catalog.');
+        }
+        else if (config.canDelegate) {
+            lines.push('- `core/send-message` — communicate with subordinates and orchestrator', '- `core/get-sops` — request relevant SOPs', `- Team leader skills at \`${config.tlSkillsPath}/\`:`, '  - `delegate-task` — assign tasks to subordinates', '  - `verify-output` — check completed work quality', '  - `schedule-check` — schedule follow-up reminders');
+        }
+        else {
+            lines.push('- `core/send-message` — communicate with team leader', '- `core/get-sops` — request relevant SOPs for current situation');
+        }
+        lines.push('', 'Skills catalog: `~/.crewly/skills/AGENT_SKILLS_CATALOG.md`');
+        return lines.join('\n');
+    }
+    /**
+     * Build role-scoped capabilities section (#225).
+     * Workers get narrow read+execute scope; orchestrators get broader coordination scope.
+     */
+    buildCapabilities(config) {
+        const lines = ['## Available Capabilities', ''];
+        if (config.role === 'orchestrator') {
+            lines.push('This session has access to:', '- **Read** project files for status awareness (not for implementation)', '- **Execute** orchestrator skill scripts for team coordination', '- **Execute** agent skill scripts (`core/` memory and status tools)', '- **Browser automation** via Playwright MCP server (when enabled)', '', 'Implementation work (editing code, creating files) should be delegated to agents.');
+        }
+        else if (config.canDelegate) {
+            lines.push('This session has access to:', `- **Read/Write** files within the project directory`, `- **Execute** bash scripts in \`${config.agentSkillsPath}/\` (agent core skills)`, `- **Execute** bash scripts in \`${config.tlSkillsPath}/\` (team leader skills)`, '- **Browser automation** via Playwright MCP server (when enabled)');
+        }
+        else {
+            lines.push('This session has access to:', `- **Read/Write** files within the project directory`, `- **Execute** bash scripts in \`${config.agentSkillsPath}/\` (agent core skills)`, '- **Browser automation** via Playwright MCP server (when enabled)');
+        }
+        // Crewly in Chrome clarification — prevents agents from confusing
+        // the remote-browser skill with Playwright, Chrome DevTools, or computer-use.
+        const remoteBrowserPath = `${config.agentSkillsPath}/remote-browser/execute.sh`;
+        lines.push('', '### Crewly in Chrome (remote-browser skill)', '', '"Crewly in Chrome" = the `remote-browser` skill. This is the ONLY way to control the user\'s real Chrome browser.', `- **Skill path:** \`${remoteBrowserPath}\``, '- **How it works:** Sends commands to the Crewly Chrome Extension installed in the user\'s real Chrome browser.', '  The Extension connects via direct WebSocket or Cloud Relay. The skill calls HTTP endpoints at `/api/browser/*`.', '- **Has the user\'s login sessions:** Because it controls the user\'s actual Chrome, it has access to all logged-in sites.', '- **NOT Playwright** — Playwright runs a headless/sandboxed browser with no user sessions.', '- **NOT Chrome DevTools / CDP** — This is a higher-level tool that works through the Chrome Extension.', '- **NOT computer-use** — computer-use controls the entire desktop; remote-browser only controls Chrome tabs.', '', 'When asked to "use Chrome", "browse the web", or "check a website", use the `remote-browser` skill:', '```bash', `bash ${remoteBrowserPath} '{"action":"navigate","url":"https://example.com"}'`, `bash ${remoteBrowserPath} '{"action":"screenshot"}'`, `bash ${remoteBrowserPath} '{"action":"read-text"}'`, `bash ${remoteBrowserPath} '{"action":"status"}'`, '```');
+        return lines.join('\n');
+    }
+    /**
+     * Build safe skill calling guide for runtimes with shell escaping issues.
+     *
+     * Gemini CLI's run_shell_command mangles JSON arguments containing quotes,
+     * backticks, and parentheses, causing "unexpected EOF" shell errors.
+     * This guide instructs the agent to write JSON to a temp file using heredoc
+     * with a single-quoted delimiter, then pass --file <path>.
+     *
+     * Uses `<< 'CREWLY_EOF'` instead of `printf '%s' '...'` because:
+     * - Single-quoted heredoc delimiter prevents ALL shell interpretation
+     * - Single quotes, double quotes, backticks, $, () all pass through literally
+     * - The previous printf approach broke when JSON contained single quotes
+     *   (e.g., "it's working" or "don't forget")
+     *
+     * Only included for gemini-cli runtime type.
+     *
+     * @param config - Module configuration with runtime type
+     * @returns Safe calling guide markdown, or null if not needed
+     */
+    buildSafeCallGuide(config) {
+        if (config.runtimeType !== 'gemini-cli') {
+            return null;
+        }
+        return `## Safe Skill Calling (MANDATORY)
+
+**CRITICAL:** All skills support **CLI flags** — use them instead of JSON to avoid shell escaping issues.
+Passing JSON as a shell argument causes "unexpected EOF" errors when content contains quotes, backticks, or parentheses.
+
+### CLI Flags Pattern (ALWAYS use this)
+\`\`\`bash
+# report-status
+bash ${config.agentSkillsPath}/core/report-status/execute.sh --session "my-agent" --status done --summary "Fixed the bug — it's working now" --project "${config.projectPath || config.projectRoot}"
+
+# send-message
+bash ${config.agentSkillsPath}/core/send-message/execute.sh --to "target-session" --message "Please implement feature X"
+
+# remember
+bash ${config.agentSkillsPath}/core/remember/execute.sh --agent "my-agent" --content "Key finding" --category pattern --scope project --project "${config.projectPath || config.projectRoot}"
+
+# recall
+bash ${config.agentSkillsPath}/core/recall/execute.sh --agent "my-agent" --context "topic to search" --project "${config.projectPath || config.projectRoot}"
+
+# record-learning
+bash ${config.agentSkillsPath}/core/record-learning/execute.sh --agent "my-agent" --role developer --project "${config.projectPath || config.projectRoot}" --learning "What I learned"
+\`\`\`
+
+### For long text (multi-line or special chars): use stdin or --summary-file/--message-file
+\`\`\`bash
+# Pipe long text via stdin
+echo "Multi-line summary with 'quotes' and special chars" | bash ${config.agentSkillsPath}/core/report-status/execute.sh --session "my-agent" --status done --project "${config.projectPath || config.projectRoot}"
+
+# Or write to file first, then use --summary-file
+cat > /tmp/summary.txt << 'CREWLY_EOF'
+Long summary with 'quotes', \`backticks\`, and (parens)
+CREWLY_EOF
+bash ${config.agentSkillsPath}/core/report-status/execute.sh --session "my-agent" --status done --summary-file /tmp/summary.txt --project "${config.projectPath || config.projectRoot}"
+\`\`\`${config.canDelegate ? `
+
+### Team Leader Skills
+\`\`\`bash
+# delegate-task
+bash ${config.tlSkillsPath}/delegate-task/execute.sh --to "worker-session" --task "implement feature X" --priority high --project "${config.projectPath || config.projectRoot}" --team "${config.teamId || ''}" --tl-member "${config.memberId}"
+
+# For long task descriptions, pipe via stdin:
+echo "Detailed task description here" | bash ${config.tlSkillsPath}/delegate-task/execute.sh --to "worker-session" --priority high --project "${config.projectPath || config.projectRoot}"
+\`\`\`` : ''}
+
+### Rules
+1. **ALWAYS** use CLI flags: \`--session\`, \`--status\`, \`--summary\`, \`--to\`, \`--message\`, etc.
+2. **NEVER** pass JSON directly as a shell argument: \`bash execute.sh '{"key":"value"}'\`
+3. For text with special characters, use **stdin pipe** or \`--summary-file\`/\`--message-file\`/\`--task-file\`
+4. Legacy JSON is still supported via \`--file\` flag if needed, but CLI flags are preferred
+5. Use \`--help\` on any skill to see all available flags`;
+    }
+    /**
+     * Build communication and memory tool instructions.
+     */
+    buildCommunication(config) {
+        return `## Communication
+
+Use bash skills at \`${config.agentSkillsPath}/\` for all team communication. Read \`~/.crewly/skills/AGENT_SKILLS_CATALOG.md\` for a full reference.
+- \`send-message\` to communicate with other agents
+- \`report-progress\` to update on task status
+- \`remember\` to store important learnings (always pass your \`agentId\` and \`projectPath\`)
+- \`recall\` to retrieve relevant knowledge (always pass your \`agentId\` and \`projectPath\`)
+- \`record-learning\` to record learnings (always pass your \`agentId\` and \`projectPath\`)
+- \`get-sops\` to request relevant SOPs for your current situation
+
+**IMPORTANT for memory tools:** When calling \`remember\`, \`recall\`, or \`record-learning\`, you MUST pass:
+- \`agentId\`: Your **Session Name** from the Identity section above
+- \`projectPath\`: Your **Project Path** from the Identity section above
+This ensures your knowledge is stored under your identity and in the correct project.
+
+**IMPORTANT for recall:** Before answering questions about the project, deployment, architecture, or past decisions, ALWAYS call \`recall\` first to check your stored knowledge.`;
+    }
+}
+//# sourceMappingURL=skills-reference.module.js.map

package/dist/cli/backend/src/services/ai/prompt-modules/skills-reference.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills-reference.module.js","sourceRoot":"","sources":["../../../../../../../backend/src/services/ai/prompt-modules/skills-reference.module.ts"],"names":[],"mappings":"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"}

package/dist/cli/backend/src/services/ai/prompt-modules/sop-norm-distinction.module.d.ts

@@ -0,0 +1,79 @@
+import { PromptModule, ModuleConfig } from './prompt-module.interface.js';
+/**
+ * SOP-vs-Norm distinction module — teaches every agent how to differentiate
+ * procedural SOPs (step-by-step deliverable guides) from behavioral Norms
+ * (collaboration covenants applied as constraints), how to name and place
+ * new SOP / Norm docs, how to reconcile conflicting versions, and how to
+ * communicate with task owners (silent-by-default / outcomes-first /
+ * thread-scope-discipline).
+ *
+ * This module sits at v1.5 of the three-tier knowledge-reconciliation
+ * roadmap:
+ *   - v1   (Mia, shipped): Karpathy-lite — `record-learning` entity-centric format.
+ *   - v1.5 (this module):  prompt-layer SOP/Norm classification + naming + reconciliation hint.
+ *   - v2   (Archivist, deferred): full cross-artifact synthesis engine.
+ *
+ * Reconciliation is treated as a horizontal primitive across all knowledge
+ * artifacts. v1.5 is the prompt-layer hint only — it does NOT introduce a
+ * service. It teaches agents to recognise conflict and escalate to TL,
+ * never silently merge.
+ *
+ * Source of truth for SOP/Norm classification:
+ *   YAML frontmatter `type: sop | norm | hybrid` on each doc file.
+ *   Filename prefix (`sop-*` / `norm-*` / `hybrid-*`) is a secondary hint.
+ *
+ * Owner Communication Discipline (3 norms folded as one family):
+ *   - Silent by default
+ *   - Deliver outcomes, not narrate progress
+ *   - Thread scope discipline
+ * The three propagate via this module's system-prompt injection so they
+ * apply to ALL agents, not just orchestrator agent memory.
+ *
+ * Spec source:
+ *   `.crewly/tasks/autonomy_v1/follow-up/sop-norm-prompt-module.md`
+ *   (orc relay 2026-04-26 evening; Steve directive on naming + placement +
+ *   reconciliation rules + Owner Communication Discipline.)
+ *
+ * @module services/ai/prompt-modules/sop-norm-distinction.module
+ */
+export declare class SOPNormDistinctionModule implements PromptModule {
+    name: string;
+    /** Just after `learning_references` (priority 10) so the SOP/Norm lens is established before downstream behavioural sections. */
+    priority: number;
+    /**
+     * Soft cap. Note: the spec acceptance criterion lists "Token estimate < 450"
+     * but that estimate undercounts the verbatim skeleton — once all 6 required
+     * sections (Definitions, Reading rules, Naming + placement, Reconciliation,
+     * Owner Communication Discipline, Why this matters) plus their mandated
+     * sub-items are rendered, the actual content measures ~1009 tokens. The
+     * authoritative budget is therefore raised to 1100 (≈9% headroom). Module is
+     * `compactable = true` so the assembler still trims under budget pressure.
+     * Deviation logged in spec follow-up; spec's "Token estimate < 450" line is
+     * acknowledged as an undercount, not enforced.
+     */
+    maxTokens: number;
+    compactable: boolean;
+    /**
+     * Always include — every agent (orchestrator, TL, executor) needs the
+     * SOP-vs-Norm lens and the Owner Communication Discipline guard rails.
+     *
+     * @param _config - unused; included for interface symmetry.
+     * @returns always `true`.
+     */
+    shouldInclude(_config: ModuleConfig): boolean;
+    /**
+     * Build the SOP-vs-Norm distinction section as a markdown string.
+     * Output structure (6 sections, per spec acceptance criteria):
+     *   1. Definitions (SOP / Team Norm / Hybrid).
+     *   2. Reading rules (4 items).
+     *   3. Naming + placement rules (4 items).
+     *   4. Reconciliation rules (4 items, "extend not replace").
+     *   5. Owner Communication Discipline (3 norms as one family).
+     *   6. Why this matters.
+     *
+     * @param _config - unused; module content is static.
+     * @returns markdown section.
+     */
+    build(_config: ModuleConfig): Promise<string>;
+}
+//# sourceMappingURL=sop-norm-distinction.module.d.ts.map

package/dist/cli/backend/src/services/ai/prompt-modules/sop-norm-distinction.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sop-norm-distinction.module.d.ts","sourceRoot":"","sources":["../../../../../../../backend/src/services/ai/prompt-modules/sop-norm-distinction.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,wBAAyB,YAAW,YAAY;IAC5D,IAAI,SAA0B;IAC9B,iIAAiI;IACjI,QAAQ,SAAM;IACd;;;;;;;;;;OAUG;IACH,SAAS,SAAQ;IACjB,WAAW,UAAQ;IAEnB;;;;;;OAMG;IACH,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO;IAI7C;;;;;;;;;;;;OAYG;IACG,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;CAuCnD"}

package/dist/cli/backend/src/services/ai/prompt-modules/sop-norm-distinction.module.js

@@ -0,0 +1,118 @@
+/**
+ * SOP-vs-Norm distinction module — teaches every agent how to differentiate
+ * procedural SOPs (step-by-step deliverable guides) from behavioral Norms
+ * (collaboration covenants applied as constraints), how to name and place
+ * new SOP / Norm docs, how to reconcile conflicting versions, and how to
+ * communicate with task owners (silent-by-default / outcomes-first /
+ * thread-scope-discipline).
+ *
+ * This module sits at v1.5 of the three-tier knowledge-reconciliation
+ * roadmap:
+ *   - v1   (Mia, shipped): Karpathy-lite — `record-learning` entity-centric format.
+ *   - v1.5 (this module):  prompt-layer SOP/Norm classification + naming + reconciliation hint.
+ *   - v2   (Archivist, deferred): full cross-artifact synthesis engine.
+ *
+ * Reconciliation is treated as a horizontal primitive across all knowledge
+ * artifacts. v1.5 is the prompt-layer hint only — it does NOT introduce a
+ * service. It teaches agents to recognise conflict and escalate to TL,
+ * never silently merge.
+ *
+ * Source of truth for SOP/Norm classification:
+ *   YAML frontmatter `type: sop | norm | hybrid` on each doc file.
+ *   Filename prefix (`sop-*` / `norm-*` / `hybrid-*`) is a secondary hint.
+ *
+ * Owner Communication Discipline (3 norms folded as one family):
+ *   - Silent by default
+ *   - Deliver outcomes, not narrate progress
+ *   - Thread scope discipline
+ * The three propagate via this module's system-prompt injection so they
+ * apply to ALL agents, not just orchestrator agent memory.
+ *
+ * Spec source:
+ *   `.crewly/tasks/autonomy_v1/follow-up/sop-norm-prompt-module.md`
+ *   (orc relay 2026-04-26 evening; Steve directive on naming + placement +
+ *   reconciliation rules + Owner Communication Discipline.)
+ *
+ * @module services/ai/prompt-modules/sop-norm-distinction.module
+ */
+export class SOPNormDistinctionModule {
+    name = 'sop_norm_distinction';
+    /** Just after `learning_references` (priority 10) so the SOP/Norm lens is established before downstream behavioural sections. */
+    priority = 11;
+    /**
+     * Soft cap. Note: the spec acceptance criterion lists "Token estimate < 450"
+     * but that estimate undercounts the verbatim skeleton — once all 6 required
+     * sections (Definitions, Reading rules, Naming + placement, Reconciliation,
+     * Owner Communication Discipline, Why this matters) plus their mandated
+     * sub-items are rendered, the actual content measures ~1009 tokens. The
+     * authoritative budget is therefore raised to 1100 (≈9% headroom). Module is
+     * `compactable = true` so the assembler still trims under budget pressure.
+     * Deviation logged in spec follow-up; spec's "Token estimate < 450" line is
+     * acknowledged as an undercount, not enforced.
+     */
+    maxTokens = 1100;
+    compactable = true;
+    /**
+     * Always include — every agent (orchestrator, TL, executor) needs the
+     * SOP-vs-Norm lens and the Owner Communication Discipline guard rails.
+     *
+     * @param _config - unused; included for interface symmetry.
+     * @returns always `true`.
+     */
+    shouldInclude(_config) {
+        return true;
+    }
+    /**
+     * Build the SOP-vs-Norm distinction section as a markdown string.
+     * Output structure (6 sections, per spec acceptance criteria):
+     *   1. Definitions (SOP / Team Norm / Hybrid).
+     *   2. Reading rules (4 items).
+     *   3. Naming + placement rules (4 items).
+     *   4. Reconciliation rules (4 items, "extend not replace").
+     *   5. Owner Communication Discipline (3 norms as one family).
+     *   6. Why this matters.
+     *
+     * @param _config - unused; module content is static.
+     * @returns markdown section.
+     */
+    async build(_config) {
+        return `## SOP vs Team Norm — How to Read, Create, and Reconcile Procedure Docs
+
+### Definitions
+- **SOP** (Standard Operating Procedure): A step-by-step procedure to produce a specific deliverable. Follow it sequentially. Examples: code-commit-sop, content-production-pipeline.
+- **Team Norm**: A behavioral / collaboration covenant with teammates. Apply it as a constraint on *how* you work, not as steps to execute. Examples: branch-guard rule, worktree-isolation pattern.
+- **Hybrid**: A doc containing both. Identify which sections are procedural (follow steps) vs which are normative (apply as constraint).
+
+### Reading rules
+1. **Source of truth = YAML frontmatter \`type:\`** on the doc file (\`sop\` | \`norm\` | \`hybrid\`).
+2. **Filename prefix** is secondary: \`sop-*.md\` → procedural, \`norm-*.md\` → behavioral.
+3. **When you call \`get-sops\` skill**: returned docs declare their type in the response. Do NOT step-through a Norm.
+4. **When in doubt**: ask the team-leader. Misreading a Norm as an SOP causes over-procedure; ignoring a Norm causes collaboration breakdown.
+
+### Naming + placement rules (when you create a new SOP / Norm)
+1. **Filename prefix:** \`sop-<name>.md\` for procedural, \`norm-<name>.md\` for behavioral, \`hybrid-<name>.md\` for mixed.
+2. **YAML frontmatter:** Every doc MUST start with \`---\\ntype: sop|norm|hybrid\\n---\` block. The frontmatter \`type:\` is the contract — filename prefix is a secondary cue.
+3. **Subdirectory:** place under \`sops/sops/\`, \`sops/norms/\`, or \`sops/hybrids/\` respectively.
+4. **Hybrid docs** must have section-level \`<!-- type: sop -->\` / \`<!-- type: norm -->\` HTML comments inside the body so consumers can split.
+
+### Reconciliation rules (when you encounter conflicting SOPs / Norms)
+1. **Flag, don't merge.** If two docs disagree on the same procedure or covenant, do NOT silently merge. Open a conflict marker (write a note + escalate to TL).
+2. **Escalate to team-leader.** TL owns reconciliation decisions. Only TL may declare which version is canonical.
+3. **Multiple-version coexistence priority** (when no TL decision yet): \`mtime\` (newest wins for procedural drift) → \`version:\` frontmatter field (explicit semver wins) → explicit \`owner:\` frontmatter (owner-declared canonical wins).
+4. **Never delete.** Conflicting docs stay on disk. Append \`status: deprecated\` to frontmatter of the losing version once TL decides; keep file for audit. Mirrors Norm v0.2 "extend not replace".
+
+### Owner Communication Discipline
+When you communicate with task owners (TL, PM, Steve, Orchestrator), apply these three norms together — they are one family: **owner attention discipline**.
+
+1. **Silent by default.** Do not surface what should not be surfaced. If a status update doesn't change a decision, don't send it. Heartbeats / "still working" pings are noise; only surface progress when (a) a milestone landed, (b) you are blocked, or (c) the owner asked for an update.
+2. **Deliver outcomes, not narrate progress.** When you do surface, lead with the conclusion + recommendation. Owners parse the first line; everything after is supporting evidence. Never bury the verdict at the bottom of a play-by-play.
+3. **Thread Scope Discipline.** Each Slack thread / message-context has its own topic scope. Replies stay within that scope — no cross-thread sidebars. ("By the way, X thread is also progressing…" is noise to the X-thread owner.) Cross-thread routing is the orchestrator's job; topic owners do not need sidebar updates from peer threads. Exception: owner explicitly asked "also tell me about X".
+
+### Why this matters
+- An SOP says "do X then Y then Z to ship a PR". Follow exactly.
+- A Norm says "always branch-guard before commit". Apply every time, not as a sequential step.
+- Silent merging of conflicting docs erases team-decision history. Always surface conflict, never resolve it implicitly.
+- Owner attention is finite. The three Owner Communication norms compound: silent-by-default reduces volume, outcomes-first reduces parse cost, thread-scope reduces context-switch cost.`;
+    }
+}
+//# sourceMappingURL=sop-norm-distinction.module.js.map

package/dist/cli/backend/src/services/ai/prompt-modules/sop-norm-distinction.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sop-norm-distinction.module.js","sourceRoot":"","sources":["../../../../../../../backend/src/services/ai/prompt-modules/sop-norm-distinction.module.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,OAAO,wBAAwB;IACpC,IAAI,GAAG,sBAAsB,CAAC;IAC9B,iIAAiI;IACjI,QAAQ,GAAG,EAAE,CAAC;IACd;;;;;;;;;;OAUG;IACH,SAAS,GAAG,IAAI,CAAC;IACjB,WAAW,GAAG,IAAI,CAAC;IAEnB;;;;;;OAMG;IACH,aAAa,CAAC,OAAqB;QAClC,OAAO,IAAI,CAAC;IACb,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,KAAK,CAAC,OAAqB;QAChC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0LAoCiL,CAAC;IAC1L,CAAC;CACD"}

package/dist/cli/backend/src/services/ai/prompt-modules/soul.module.d.ts

@@ -0,0 +1,102 @@
+import { PromptModule, ModuleConfig } from './prompt-module.interface.js';
+/**
+ * Soul module — provides the agent's personality, tone, and working style.
+ *
+ * Resolution chain (P0-1 Phase 2):
+ *   0. **TL overlay** — when `canDelegate=true`, layer the team-leader
+ *      archetype (`config/souls/team-leader.md`) as the primary soul and
+ *      append the agent's original-role soul as a Capability Specialty.
+ *      A per-member soul still wins over the overlay (explicit > default).
+ *   1. Per-member soul (~/.crewly/teams/{teamId}/members/{memberId}/soul.md)
+ *   2. Role default soul (config/roles/{role}/soul.md)
+ *   3. Reusable archetype (config/souls/{role}.md)
+ *   4. Hardcoded minimal fallback
+ *
+ * Sources: Path A Step 5, Path B Section 9, Soul System Design (Section 6),
+ * P0-1 Team-Leader Soul spec.
+ */
+export declare class SoulModule implements PromptModule {
+    name: string;
+    priority: number;
+    maxTokens: number;
+    compactable: boolean;
+    /**
+     * Always included — every agent benefits from personality definition.
+     */
+    shouldInclude(_config: ModuleConfig): boolean;
+    /**
+     * Build the soul section by resolving the soul file from the resolution chain.
+     * If self-improvement data exists, appends a Self-Awareness section.
+     *
+     * @param config - Module configuration with role and project details
+     * @returns Formatted markdown soul section
+     */
+    build(config: ModuleConfig): Promise<string>;
+    /**
+     * Resolve the soul content by checking each level of the resolution chain.
+     *
+     * @param config - Module configuration
+     * @returns Soul content string
+     */
+    private resolveSoul;
+    /**
+     * Resolve the agent's specialty soul for the TL overlay layer.
+     *
+     * Reuses steps 3 & 4 of the legacy cascade (role default → archetype) but
+     * deliberately skips the per-member soul (already checked in step 1 above)
+     * and the team-leader archetype (which would cause infinite recursion when
+     * `role === 'team-leader'`).
+     *
+     * @param config - Module configuration
+     * @returns Specialty soul content, or null when no role-specific soul exists
+     *          OR when the role IS team-leader (no specialty to layer).
+     */
+    private resolveSpecialtySoul;
+    /**
+     * Format the TL overlay layout: team-leader archetype as the primary soul,
+     * with the original-role specialty appended as Capability Specialty.
+     *
+     * The Capability Specialty section is what the agent draws on when applying
+     * the Self-Implementation Exception Rule from `team-leader.md` (TL leans on
+     * IC instincts when self-implementing under specific conditions).
+     *
+     * @param tlContent - Raw team-leader.md content
+     * @param specialty - Specialty soul content (null when no role specialty exists)
+     * @param role - The agent's original role (used in the specialty header)
+     * @returns Formatted TL overlay markdown
+     */
+    private formatTLOverlay;
+    /**
+     * Get the path to a member's personal soul file.
+     *
+     * @param teamId - Team ID
+     * @param memberId - Member ID
+     * @returns Absolute path to the member soul file
+     */
+    private getMemberSoulPath;
+    /**
+     * Read a file if it exists, returning its content or null.
+     *
+     * @param filePath - Path to the file
+     * @returns File content string or null if not found
+     */
+    private readFileIfExists;
+    /**
+     * Format the soul content with a source annotation.
+     *
+     * @param content - Raw soul file content
+     * @param source - Where the soul was resolved from
+     * @returns Formatted soul section
+     */
+    private formatSoul;
+    /**
+     * Build the Self-Awareness section from self-improvement data.
+     * Reads growth areas, self-model (blind spots), and prediction calibration.
+     * Kept under ~200 tokens.
+     *
+     * @param sessionName - Agent session name
+     * @returns Self-awareness markdown section, or null if no data exists
+     */
+    private buildSelfAwareness;
+}
+//# sourceMappingURL=soul.module.d.ts.map

package/dist/cli/backend/src/services/ai/prompt-modules/soul.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"soul.module.d.ts","sourceRoot":"","sources":["../../../../../../../backend/src/services/ai/prompt-modules/soul.module.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAS1E;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,UAAW,YAAW,YAAY;IAC9C,IAAI,SAAU;IACd,QAAQ,SAAK;IACb,SAAS,SAAO;IAChB,WAAW,UAAS;IAEpB;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO;IAI7C;;;;;;OAMG;IACG,KAAK,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAMlD;;;;;OAKG;YACW,WAAW;IAgDzB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,oBAAoB;IAW5B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,eAAe;IAYvB;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAKzB;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAQxB;;;;;;OAMG;IACH,OAAO,CAAC,UAAU;IAKlB;;;;;;;OAOG;IACH,OAAO,CAAC,kBAAkB;CA+C1B"}