clearctx 3.0.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.
@@ -1004,3 +1041,4 @@ clearctx team-replay pre-work --overrides overrides.json
 ## License
 
 MIT
+

package/bin/setup.js

@@ -178,6 +178,57 @@ This shows which workers actually read the conventions. If a worker is missing,
 
 NEVER trust a worker's self-reported completion — verify the artifact exists yourself.
 
+### Rule 8: Use expertise skills for domain work
+
+When spawning workers, assign relevant expertise skills to improve output quality:
+
+1. Call \`skill_detect\` with the task description to auto-match skills
+2. Pass matched skills to \`team_spawn\` via the \`skills\` parameter:
+   \`\`\`
+   team_spawn({
+     name: "db-dev",
+     role: "database",
+     skills: ["postgresql"],
+     prompt: "Create the database schema..."
+   })
+   \`\`\`
+3. Override auto-detection with explicit skills when you know better
+4. Workers with skills produce higher-quality, convention-compliant output
+5. Available skills: postgresql, nodejs-backend, react-frontend, testing-qa, api-design, devops, security, typescript
+
+**Role-based fallback:** If you don't specify skills but provide a role, the system auto-detects relevant skills:
+- database → postgresql
+- backend → nodejs-backend, api-design
+- frontend → react-frontend
+- QA/testing → testing-qa
+- devops → devops
+- 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:
@@ -186,8 +237,9 @@ These happen automatically — no action needed from you or the workers:
 - **Inbox enforcement**: Workers are blocked from using artifact/contract tools until they call \`team_check_inbox\`
 - **File ownership tracking**: \`artifact_publish\` auto-registers file ownership from \`files\`/\`filesCreated\`/\`filesModified\` arrays in artifact data
 - **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 (68 tools)
+## Quick Reference (82 tools)
 
 | You want to... | Use this tool |
 |----------------|---------------|
@@ -202,6 +254,14 @@ These happen automatically — no action needed from you or the workers:
 | Check who read an artifact | \`artifact_readers\` |
 | Check file ownership (Rule 6) | \`check_file_owner\` |
 | Register file ownership | \`register_files\` |
+| Auto-detect skills for a task | \`skill_detect\` |
+| 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.0.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": {
@@ -31,7 +31,7 @@
     "parallel-tasks",
     "workflow-automation"
   ],
-  "author": "",
+  "author": "RevanthThota55 <revanththota55@gmail.com>",
   "license": "MIT",
   "engines": {
     "node": ">=18.0.0"
@@ -39,6 +39,7 @@
   "files": [
     "src/",
     "bin/",
+    "skills/",
     "README.md",
     "CHANGELOG.md",
     "STRATEGY.md",