clearctx 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 All notable changes to clearctx will be documented in this file.
 
+## [3.2.0] - 2026-02-15
+### Added
+- **Cognition Layer** — Think-Plan-Execute cognitive protocol for workers
+- Communication Channels — 5 new tools: `channel_create`, `channel_post`, `channel_subscribe`, `channel_read`, `channel_list`
+- Project Notebook — 4 new tools: `notebook_write`, `notebook_read`, `notebook_search`, `notebook_list`
+- User Escalation — 2 new tools: `ask_user`, `user_respond`
+- 6-phase cognitive protocol injected into worker system prompts
+- 5 default channels: `#design-decisions`, `#blockers`, `#discoveries`, `#conventions`, `#questions`
+- 7 notebook categories: research, decision, gotcha, pattern, plan, investigation, reference
+- Orchestrator Rule 9: Surface worker questions to the user
+- 3 new modules: `src/channel-hub.js`, `src/notebook-store.js`, `src/user-escalation.js`
+- 15 new enforcement tests (73 total, 100% pass rate)
+- Updated all 3 sources of truth (prompts.js, ORCHESTRATOR-CLAUDE.md, setup.js)
+
+### Changed
+- Total MCP tools: 71 → 82
+- Total tests: 58 → 73
+
+## [3.1.0] - 2026-02-15
+### Added
+- Expertise skills system with 8 bundled domain skills: postgresql, nodejs-backend, react-frontend, testing-qa, api-design, devops, security, typescript
+- 3 new MCP tools: skill_list, skill_get, skill_detect (68 → 71 tools)
+- Auto-detection of relevant skills from task description keywords
+- Role-based skill fallback in team_spawn (e.g., role "backend" → nodejs-backend + api-design)
+- Skill injection via team_spawn `skills` parameter
+- Rule 8: Use expertise skills for domain work (added to orchestrator guide)
+- 9 new tests in Skills System group (49 → 58 tests)
+
+### Fixed
+- ENAMETOOLONG on Windows when injecting skills: system prompts now written to temp files and passed via --append-system-prompt-file instead of CLI args
+- Role-based fallback no longer triggers when skills: [] is explicitly passed (opt-out)
+- getWorkerContext edge case: Worker Context as last section in SKILL.md now extracted correctly
+
 ## [3.0.0] - 2026-02-15
 ### BREAKING CHANGES
 - Renamed package from `claude-multi-session` to `clearctx`

package/README.md

@@ -4,7 +4,7 @@
 [![license](https://img.shields.io/npm/l/clearctx.svg)](https://github.com/)
 [![node](https://img.shields.io/node/v/clearctx.svg)](https://nodejs.org)
 
-> Multi-session orchestration system for Claude Code CLI. Spawn parallel workers that coordinate via artifacts and phase gates. 68 MCP tools. v2.9.0.
+> Multi-session orchestration system for Claude Code CLI. Spawn parallel workers that coordinate via artifacts and phase gates. 82 MCP tools. 8 bundled expertise skills. Cognition Layer. v3.2.0.
 
 ---
 
@@ -39,7 +39,7 @@ After installing, run the setup wizard to register the MCP server with Claude Co
 clearctx setup
 ```
 
-This adds 17 native tools to Claude Code (spawn_session, delegate_task, etc.) so Claude can manage sessions directly — no Bash commands needed.
+This adds 82 native tools to Claude Code (spawn_session, delegate_task, skill_detect, etc.) so Claude can manage sessions directly — no Bash commands needed.
 
 **Non-interactive options:**
 ```bash
@@ -450,7 +450,7 @@ Add to your Claude Code MCP config (`~/.claude/settings.json` or project `.claud
 {
   "mcpServers": {
     "multi-session": {
-      "command": "cms-mcp"
+      "command": "ctx-mcp"
     }
   }
 }
@@ -505,6 +505,28 @@ Once configured, Claude sees these tools:
 |------|-------------|
 | `batch_spawn` | Spawn multiple sessions in parallel |
 
+**Expertise Skills:**
+| Tool | Description |
+|------|-------------|
+| `skill_list` | List all available expertise skills |
+| `skill_get` | Read a skill's full content (conventions, patterns, anti-patterns) |
+| `skill_detect` | Auto-detect relevant skills from a task description |
+
+**Cognition Layer:**
+| Tool | Description |
+|------|-------------|
+| `channel_create` | Create a topic-based communication channel |
+| `channel_post` | Post a message to a team channel |
+| `channel_subscribe` | Subscribe a session to a channel |
+| `channel_read` | Read messages from a channel |
+| `channel_list` | List all channels with subscriber counts |
+| `notebook_write` | Write or append to a shared notebook entry |
+| `notebook_read` | Read a notebook entry with all entries |
+| `notebook_search` | Search notebook by content, title, or tags |
+| `notebook_list` | List notebook entries with filters |
+| `ask_user` | Ask the human user a question (worker escalation) |
+| `user_respond` | Relay the human's answer to a worker |
+
 ### How Claude Uses It
 
 With MCP configured, Claude can autonomously:
@@ -633,6 +655,21 @@ clearctx team-replay pre-graphql --overrides '{"build-auth-api":{"inputs":{"cont
 
 ---
 
+## Cognition Layer (v3.2.0)
+
+Workers now follow a **Think-Plan-Execute cognitive protocol** that teaches them to orient before coding, research ambiguities, share plans before implementing, document discoveries, and self-review before delivering.
+
+### Communication Channels (5 tools)
+Persistent topic-based discussions. 5 default channels: `#design-decisions`, `#blockers`, `#discoveries`, `#conventions`, `#questions`. Workers post plans and discoveries to channels so teammates stay informed without orchestrator relay.
+
+### Project Notebook (4 tools)
+Shared knowledge scratchpad with 7 categories: research, decision, gotcha, pattern, plan, investigation, reference. Multiple workers can append to the same note, enabling collaborative knowledge building.
+
+### User Escalation (2 tools)
+Workers can ask the human user questions when genuinely stuck on ambiguous decisions that can't be resolved by checking artifacts, conventions, channels, notebook, or asking teammates. The orchestrator relays answers.
+
+---
+
 ## Layer 1: Chat (8 MCP Tools)
 
 Sessions can communicate directly without routing through the orchestrator.

package/bin/setup.js

@@ -205,6 +205,30 @@ When spawning workers, assign relevant expertise skills to improve output qualit
 - security → security
 - fullstack → nodejs-backend, react-frontend, typescript
 
+### Rule 9: Surface worker questions to the user
+
+Workers can ask the human user questions via \`ask_user\` when genuinely stuck on ambiguous decisions that can't be resolved by checking artifacts, conventions, channels, notebook, or asking teammates.
+
+- After spawning workers, periodically check for pending questions: use \`user_list_pending\` to see unanswered escalations
+- When you see a pending question, present it to the user clearly with the worker's context
+- After the user answers, relay it with \`user_respond\`
+- Do NOT answer on behalf of the user — relay their actual response
+- If multiple questions are pending, prioritize by priority level (urgent > high > normal > low)
+
+## Cognition Layer (v3.2.0)
+
+Workers now follow a **Think-Plan-Execute cognitive protocol** that teaches them to orient before coding, research ambiguities, share plans in channels before implementing, document discoveries in the notebook, and self-review before delivering. This reduces convention mismatches, duplicate work, and silent failures.
+
+Three new subsystems support this:
+
+| Category | Tools | Purpose |
+|----------|-------|---------|
+| **Channels** | \`channel_create\`, \`channel_post\`, \`channel_read\`, \`channel_subscribe\`, \`channel_list\` | Persistent topic-based discussion. Default channels: \`#design-decisions\`, \`#blockers\`, \`#discoveries\`, \`#conventions\`, \`#questions\` |
+| **Notebook** | \`notebook_write\`, \`notebook_read\`, \`notebook_search\`, \`notebook_list\` | Shared knowledge scratchpad for research, gotchas, patterns, plans, and investigations |
+| **User Escalation** | \`ask_user\`, \`user_respond\` | Worker-to-human escalation for genuinely ambiguous decisions. Workers ask, orchestrator relays answer |
+
+**Orchestrator role:** Monitor channels (\`channel_read\`) and notebook (\`notebook_list\`, \`notebook_read\`) to stay informed. Check \`user_list_pending\` for unanswered worker questions and relay answers with \`user_respond\`. You do NOT need to post to channels yourself — workers handle their own collaboration.
+
 ## Auto-Behaviors (v2.7.0)
 
 These happen automatically — no action needed from you or the workers:
@@ -215,7 +239,7 @@ These happen automatically — no action needed from you or the workers:
 - **Convention completeness check**: \`phase_gate\` warns if \`shared-conventions\` artifact is missing or has incomplete fields
 - **Skills System**: When you provide a \`role\` to \`team_spawn\` without explicit \`skills\`, the system auto-detects relevant expertise skills based on the role (e.g., "database" → postgresql, "backend" → nodejs-backend + api-design). You can override this by passing explicit \`skills\` array.
 
-## Quick Reference (71 tools)
+## Quick Reference (82 tools)
 
 | You want to... | Use this tool |
 |----------------|---------------|
@@ -234,6 +258,10 @@ These happen automatically — no action needed from you or the workers:
 | List available skills | \`skill_list\` |
 | Read a skill's content | \`skill_get\` |
 | Spawn worker with skills | \`team_spawn\` with \`skills\` parameter |
+| Monitor team discussions | \`channel_read\`, \`channel_list\` |
+| Monitor shared knowledge | \`notebook_read\`, \`notebook_list\` |
+| Check pending user questions | \`user_list_pending\` |
+| Relay user's answer to worker | \`user_respond\` |
 | Clean up between runs | \`team_reset\` |
 
 ### When NOT to Delegate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clearctx",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Multi-session orchestrator for Claude Code CLI — spawn, control, pause, resume, and send multiple inputs to Claude Code sessions programmatically",
   "main": "src/index.js",
   "bin": {

package/src/channel-hub.js

@@ -0,0 +1,341 @@
+/**
+ * channel-hub.js
+ * Cognition Layer: Topic-based persistent channels for worker collaboration.
+ *
+ * Provides Slack-like channels where workers can discuss, share findings,
+ * and debate approaches. Each channel is an append-only JSONL message log
+ * with a shared index tracking channel metadata and subscriptions.
+ *
+ * Storage structure:
+ * team/{teamName}/channels/
+ *   channels-index.json   - registry of all channels
+ *   {channelName}.jsonl    - append-only message log per channel
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const { atomicWriteJson, readJsonSafe } = require('./atomic-io');
+const { acquireLock, releaseLock } = require('./file-lock');
+
+/**
+ * Default channels auto-created for new teams.
+ * Exported so mcp-server.js can create them on team_spawn if they don't exist.
+ */
+const DEFAULT_CHANNELS = [
+  'design-decisions',
+  'blockers',
+  'discoveries',
+  'conventions',
+  'questions'
+];
+
+/**
+ * Validate a channel name.
+ * Must be lowercase, alphanumeric + hyphens only, max 50 chars.
+ * @param {string} name - Channel name to validate
+ * @throws {Error} If name is invalid
+ * @private
+ */
+function _validateChannelName(name) {
+  if (!name || typeof name !== 'string') {
+    throw new Error('Channel name is required and must be a string');
+  }
+
+  if (name.length > 50) {
+    throw new Error(`Channel name '${name}' exceeds 50 character limit`);
+  }
+
+  if (!/^[a-z0-9-]+$/.test(name)) {
+    throw new Error(`Channel name '${name}' must be lowercase alphanumeric with hyphens only`);
+  }
+}
+
+/**
+ * ChannelHub manages topic-based persistent channels for worker collaboration.
+ *
+ * Directory structure:
+ * team/{teamName}/channels/
+ *   channels-index.json    - channel registry (locked for writes)
+ *   {channelName}.jsonl    - append-only message log per channel
+ */
+class ChannelHub {
+  /**
+   * Create a new ChannelHub instance
+   * @param {string} teamName - Name of the team (default: 'default')
+   */
+  constructor(teamName = 'default') {
+    const baseDir = path.join(os.homedir(), '.clearctx');
+    this.teamDir = path.join(baseDir, 'team', teamName);
+    this.channelsDir = path.join(this.teamDir, 'channels');
+    this.indexPath = path.join(this.channelsDir, 'channels-index.json');
+    this.locksDir = path.join(this.teamDir, 'locks');
+
+    this._ensureDirectories();
+  }
+
+  /**
+   * Ensure all required directories exist
+   * @private
+   */
+  _ensureDirectories() {
+    [this.channelsDir, this.locksDir].forEach(dir => {
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+    });
+  }
+
+  /**
+   * Get the JSONL file path for a channel
+   * @param {string} channelName - The channel name
+   * @returns {string} Absolute path to the channel's JSONL file
+   * @private
+   */
+  _channelPath(channelName) {
+    return path.join(this.channelsDir, `${channelName}.jsonl`);
+  }
+
+  /**
+   * Create a new channel
+   * @param {string} channelName - Unique channel name (lowercase, alphanumeric + hyphens, max 50 chars)
+   * @param {Object} options - Channel options
+   * @param {string} options.description - Human-readable description
+   * @param {string} options.creator - Session name that created the channel
+   * @returns {Object} { channelName, created: true }
+   */
+  createChannel(channelName, { description, creator }) {
+    // Step 1: Validate channel name
+    _validateChannelName(channelName);
+
+    if (!creator || typeof creator !== 'string') {
+      throw new Error('Channel creator is required');
+    }
+
+    // Step 2: Acquire lock on the channels index
+    acquireLock(this.locksDir, 'channels-index');
+
+    try {
+      // Step 3: Read the current index
+      const index = readJsonSafe(this.indexPath, {});
+
+      // Step 4: Check for duplicates
+      if (index[channelName]) {
+        throw new Error(`Channel '${channelName}' already exists`);
+      }
+
+      // Step 5: Add channel to index
+      index[channelName] = {
+        name: channelName,
+        description: description || '',
+        creator,
+        createdAt: new Date().toISOString(),
+        subscribers: [creator]
+      };
+
+      // Step 6: Save the index atomically
+      atomicWriteJson(this.indexPath, index);
+
+      // Step 7: Create empty JSONL file
+      const jsonlPath = this._channelPath(channelName);
+      if (!fs.existsSync(jsonlPath)) {
+        fs.writeFileSync(jsonlPath, '', 'utf-8');
+      }
+
+      // Step 8: Release the lock
+      releaseLock(this.locksDir, 'channels-index');
+
+      return { channelName, created: true };
+
+    } catch (err) {
+      releaseLock(this.locksDir, 'channels-index');
+      throw err;
+    }
+  }
+
+  /**
+   * Post a message to a channel
+   * @param {string} channelName - Target channel name
+   * @param {Object} options - Message options
+   * @param {string} options.from - Sender session name
+   * @param {string} options.content - Message content
+   * @param {Object} [options.metadata] - Optional metadata
+   * @returns {Object} { messageId, channelName, posted: true }
+   */
+  postMessage(channelName, { from, content, metadata }) {
+    // Step 1: Validate channel exists
+    const index = readJsonSafe(this.indexPath, {});
+    if (!index[channelName]) {
+      throw new Error(`Channel '${channelName}' does not exist`);
+    }
+
+    if (!from || typeof from !== 'string') {
+      throw new Error('Message sender (from) is required');
+    }
+
+    if (!content || typeof content !== 'string') {
+      throw new Error('Message content is required');
+    }
+
+    // Step 2: Build message object
+    const messageId = `msg_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    const message = {
+      id: messageId,
+      channelName,
+      from,
+      content,
+      metadata: metadata || null,
+      timestamp: new Date().toISOString()
+    };
+
+    // Step 3: Acquire lock for safe concurrent append
+    acquireLock(this.locksDir, `channel-${channelName}`);
+
+    try {
+      // Step 4: Append JSONL line
+      const jsonlPath = this._channelPath(channelName);
+      fs.appendFileSync(jsonlPath, JSON.stringify(message) + '\n', 'utf-8');
+
+      // Step 5: Release the lock
+      releaseLock(this.locksDir, `channel-${channelName}`);
+
+      return { messageId, channelName, posted: true };
+
+    } catch (err) {
+      releaseLock(this.locksDir, `channel-${channelName}`);
+      throw err;
+    }
+  }
+
+  /**
+   * Subscribe a session to a channel
+   * @param {string} channelName - Channel to subscribe to
+   * @param {string} sessionName - Session name to subscribe
+   * @returns {Object} { channelName, subscriber: sessionName, subscribed: true }
+   */
+  subscribe(channelName, sessionName) {
+    if (!sessionName || typeof sessionName !== 'string') {
+      throw new Error('Session name is required for subscription');
+    }
+
+    // Acquire lock on the channels index
+    acquireLock(this.locksDir, 'channels-index');
+
+    try {
+      const index = readJsonSafe(this.indexPath, {});
+
+      if (!index[channelName]) {
+        throw new Error(`Channel '${channelName}' does not exist`);
+      }
+
+      // Add subscriber (no duplicates)
+      if (!index[channelName].subscribers.includes(sessionName)) {
+        index[channelName].subscribers.push(sessionName);
+        atomicWriteJson(this.indexPath, index);
+      }
+
+      releaseLock(this.locksDir, 'channels-index');
+
+      return { channelName, subscriber: sessionName, subscribed: true };
+
+    } catch (err) {
+      releaseLock(this.locksDir, 'channels-index');
+      throw err;
+    }
+  }
+
+  /**
+   * Read messages from a channel
+   * @param {string} channelName - Channel to read from
+   * @param {Object} [options={}] - Read options
+   * @param {number} [options.limit=50] - Max messages to return (returns last N)
+   * @param {string} [options.after] - Only return messages after this ISO timestamp
+   * @param {string} [options.subscriber] - If provided, track last-read timestamp in index
+   * @returns {Object} { channelName, messages: [...], total }
+   */
+  readMessages(channelName, { limit = 50, after, subscriber } = {}) {
+    // Step 1: Validate channel exists
+    const index = readJsonSafe(this.indexPath, {});
+    if (!index[channelName]) {
+      throw new Error(`Channel '${channelName}' does not exist`);
+    }
+
+    // Step 2: Read JSONL file and parse each line
+    const jsonlPath = this._channelPath(channelName);
+    let messages = [];
+
+    try {
+      const content = fs.readFileSync(jsonlPath, 'utf-8');
+      const lines = content.split('\n').filter(line => line.trim());
+
+      for (const line of lines) {
+        try {
+          messages.push(JSON.parse(line));
+        } catch (parseErr) {
+          // Skip corrupted lines
+        }
+      }
+    } catch (err) {
+      // File doesn't exist or can't be read — return empty
+      messages = [];
+    }
+
+    const total = messages.length;
+
+    // Step 3: Filter by 'after' timestamp if provided
+    if (after) {
+      messages = messages.filter(msg => msg.timestamp > after);
+    }
+
+    // Step 4: Apply limit (return last N messages)
+    if (limit && messages.length > limit) {
+      messages = messages.slice(-limit);
+    }
+
+    // Step 5: Track last-read timestamp if subscriber provided
+    if (subscriber) {
+      acquireLock(this.locksDir, 'channels-index');
+
+      try {
+        const freshIndex = readJsonSafe(this.indexPath, {});
+
+        if (freshIndex[channelName]) {
+          if (!freshIndex[channelName].lastRead) {
+            freshIndex[channelName].lastRead = {};
+          }
+          freshIndex[channelName].lastRead[subscriber] = new Date().toISOString();
+          atomicWriteJson(this.indexPath, freshIndex);
+        }
+
+        releaseLock(this.locksDir, 'channels-index');
+      } catch (err) {
+        releaseLock(this.locksDir, 'channels-index');
+        // Non-critical — don't fail the read
+      }
+    }
+
+    return { channelName, messages, total };
+  }
+
+  /**
+   * List all channels with subscriber counts
+   * @returns {Object} { channels: [...] }
+   */
+  listChannels() {
+    const index = readJsonSafe(this.indexPath, {});
+
+    const channels = Object.values(index).map(channel => ({
+      name: channel.name,
+      description: channel.description,
+      creator: channel.creator,
+      createdAt: channel.createdAt,
+      subscriberCount: channel.subscribers ? channel.subscribers.length : 0,
+      subscribers: channel.subscribers || []
+    }));
+
+    return { channels };
+  }
+}
+
+module.exports = { ChannelHub, DEFAULT_CHANNELS };