From a35e5600bebcdaae832df1692eae0344e581ef9e Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 1 Apr 2026 18:01:46 +0000 Subject: [PATCH 1/2] feat: add Cowork platform compatibility and deployment guide Make sigint deployable to Cowork by adding platform declarations, Cowork-specific permissions, and graceful fallbacks for sandboxed environments. Prefer GitHub MCP tools over gh CLI, add file-based fallbacks when Atlatl blackboard is unavailable, and include a Cowork deployment guide. https://claude.ai/code/session_01XnEq1KXGkMEEMtqeEqHc3K --- .claude-plugin/plugin.json | 21 +++++++- README.md | 17 ++++++- agents/dimension-analyst.md | 12 +++-- agents/issue-architect.md | 9 ++-- commands/issues.md | 2 +- docs/how-to/deploy-to-cowork.md | 85 +++++++++++++++++++++++++++++++++ skills/issues/SKILL.md | 4 +- skills/start/SKILL.md | 2 + 8 files changed, 140 insertions(+), 12 deletions(-) create mode 100644 docs/how-to/deploy-to-cowork.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index f460477..ab26fae 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -13,5 +13,24 @@ "trend-analysis", "report-generation", "github-issues" - ] + ], + "platforms": ["claude-code", "cowork"], + "category": "research-and-analysis", + "permissions": { + "web_search": true, + "web_fetch": true, + "file_read": true, + "file_write": true, + "mcp_servers": ["atlatl", "github"] + }, + "optional_dependencies": { + "atlatl": { + "description": "Atlatl MCP server for blackboard coordination and persistent memory. Falls back to file-based state when unavailable.", + "required": false + }, + "github": { + "description": "GitHub MCP server for issue creation. Required only for /sigint:issues command.", + "required": false + } + } } diff --git a/README.md b/README.md index a38b875..fb41af5 100644 --- a/README.md +++ b/README.md @@ -43,6 +43,8 @@ See the [Getting Started Tutorial](docs/tutorials/getting-started.md) for a deta ## Installation +### Claude Code + ```bash # Option 1: Plugin Marketplace (recommended) /plugins add sigint @@ -54,6 +56,14 @@ claude --plugin-dir /path/to/sigint cp -r sigint ~/.claude/plugins/ ``` +### Cowork + +1. Open Claude Desktop app > **Cowork** tab +2. Click **Customize** > **Browse plugins** +3. Search for "sigint" and click **Install** + +For organization-wide deployment and detailed setup, see the [Cowork deployment guide](docs/how-to/deploy-to-cowork.md). + ## Commands | Command | Description | @@ -172,10 +182,13 @@ EOF ## Dependencies -- GitHub CLI (`gh`) for issue creation -- Atlatl MCP server for memory persistence and blackboard coordination +**Required:** - WebSearch/WebFetch tools for research +**Optional:** +- Atlatl MCP server for blackboard coordination and persistent memory (falls back to file-based state) +- GitHub MCP server or GitHub CLI (`gh`) for issue creation + ## References ### Primary Research diff --git a/agents/dimension-analyst.md b/agents/dimension-analyst.md index 5dd374f..efde3a5 100644 --- a/agents/dimension-analyst.md +++ b/agents/dimension-analyst.md @@ -52,7 +52,7 @@ You are a specialized market research analyst focused on a single research dimen ``` blackboard_read(scope="{scope}", key="elicitation") ``` -If no blackboard exists (standalone augment), read from `./reports/*/state.json`. +If no blackboard exists (standalone augment or Cowork without Atlatl), read from `./reports/*/state.json`. ### Step 1: Load Skill Methodology — REQUIRED Read `skills/{skill-directory}/SKILL.md` for your dimension's research methodology. This is **not optional** — you must load your skill before proceeding. @@ -75,8 +75,10 @@ Extract the "## Required Frameworks" table from the loaded skill. Build a method blackboard_write(scope="{scope}", key="methodology_plan_{dimension}", value={methodology plan object}) ``` -📋 After writing, report to user what frameworks will be applied: -"📋 {dimension} analyst: Loading methodology — {N} frameworks planned: {framework names}" +> **Cowork fallback:** If blackboard tools are unavailable, write the methodology plan to `./reports/{topic-slug}/blackboard.json` under key `methodology_plan_{dimension}` instead. + +After writing, report to user what frameworks will be applied: +"{dimension} analyst: Loading methodology — {N} frameworks planned: {framework names}" ### Step 4: Proceed to Research **ONLY AFTER Step 3 succeeds**, proceed to web research. If Step 3 fails, retry once. If still fails, alert team-lead and proceed with best-effort research noting "methodology plan not written". @@ -145,12 +147,16 @@ Format findings as structured JSON: blackboard_write(scope="{scope}", key="findings_{dimension}", value={findings object}) ``` +> **Cowork fallback:** If blackboard tools are unavailable, write findings to `./reports/{topic-slug}/findings_{dimension}.json` and notify the team lead via SendMessage with the file path. + ### Step 6: Check for Cross-Dimension Conflicts Read other dimensions' findings from blackboard: ``` blackboard_read(scope="{scope}", key="findings_{other_dimension}") ``` +> **Cowork fallback:** Read from `./reports/{topic-slug}/findings_{other_dimension}.json` if blackboard is unavailable. + If contradictions found: ``` blackboard_alert(scope="{scope}",channel="conflict_detected", message={ diff --git a/agents/issue-architect.md b/agents/issue-architect.md index a8d0bc8..2b787eb 100644 --- a/agents/issue-architect.md +++ b/agents/issue-architect.md @@ -247,13 +247,14 @@ SendMessage( ## GitHub Integration -**Using gh CLI:** +**Using GitHub MCP tools (preferred — required for Cowork):** +Use ToolSearch to find available GitHub MCP tools (e.g., `mcp__github__issue_write`). This is the preferred method and the only method available in Cowork environments. + +**Using gh CLI (Claude Code fallback):** ```bash gh issue create --title "Title" --body "Body" --label "enhancement" ``` - -**Using GitHub MCP tools:** -Search for available GitHub tools with ToolSearch if needed. +Only use `gh` CLI if GitHub MCP tools are unavailable (e.g., local Claude Code without GitHub MCP configured). ## Quality Checks diff --git a/commands/issues.md b/commands/issues.md index 24877bf..6a1415b 100644 --- a/commands/issues.md +++ b/commands/issues.md @@ -2,7 +2,7 @@ description: Create GitHub issues from research findings as atomic deliverables version: 0.2.0 argument-hint: [--repo ] [--dry-run] [--labels ] -allowed-tools: Read, Write, Bash, Grep, Glob, Agent, TeamCreate, TeamDelete, SendMessage, TaskCreate, TaskUpdate, TaskList, TaskGet, AskUserQuestion, mcp__atlatl__capture_memory, mcp__atlatl__recall_memories, mcp__atlatl__enrich_memory, mcp__atlatl__blackboard_create, mcp__atlatl__blackboard_write, mcp__atlatl__blackboard_read +allowed-tools: Read, Write, Bash, Grep, Glob, Agent, TeamCreate, TeamDelete, SendMessage, TaskCreate, TaskUpdate, TaskList, TaskGet, AskUserQuestion, ToolSearch, mcp__atlatl__capture_memory, mcp__atlatl__recall_memories, mcp__atlatl__enrich_memory, mcp__atlatl__blackboard_create, mcp__atlatl__blackboard_write, mcp__atlatl__blackboard_read, mcp__github__issue_write, mcp__github__issue_read --- Load and execute the `sigint:issues` skill with these arguments: $ARGUMENTS diff --git a/docs/how-to/deploy-to-cowork.md b/docs/how-to/deploy-to-cowork.md new file mode 100644 index 0000000..a263397 --- /dev/null +++ b/docs/how-to/deploy-to-cowork.md @@ -0,0 +1,85 @@ +# Deploy Sigint to Cowork + +Sigint is compatible with both Claude Code and Cowork. This guide covers deploying and using sigint in Cowork environments. + +## Prerequisites + +- Claude Pro, Max, Team, or Enterprise subscription +- Claude Desktop app with Cowork enabled + +## Installation + +### Individual Installation + +1. Open the Claude Desktop app and switch to the **Cowork** tab +2. Click **Customize** in the left sidebar +3. Click **Browse plugins** and search for "sigint" +4. Click **Install** + +### Organization-Wide Deployment (Teams/Enterprise) + +1. Add the sigint plugin to your organization's plugin marketplace repository +2. Configure managed settings to distribute the marketplace to team members +3. Team members install from Cowork sidebar: **Customize > Browse plugins > sigint > Install** + +### Manual Installation + +Clone the repository and point Cowork to the local directory: + +```bash +git clone https://github.com/zircote/sigint.git ~/.claude/plugins/sigint +``` + +## Cowork Environment Differences + +Cowork runs in a sandboxed virtual machine. This affects sigint in the following ways: + +### GitHub Integration + +Cowork uses GitHub MCP tools instead of the `gh` CLI. Sigint's issue-architect agent will automatically prefer MCP tools when available. No configuration needed — ensure your Cowork environment has the GitHub MCP server connected. + +To connect GitHub in Cowork: +1. Go to **Customize > Connectors** +2. Enable the **GitHub** connector +3. Authorize access to your target repositories + +### Atlatl MCP (Optional) + +Sigint uses Atlatl MCP for blackboard coordination and persistent memory. If Atlatl is not available in your Cowork environment: + +- **Blackboard coordination** falls back to file-based state in `./reports/{topic}/blackboard.json` +- **Persistent memory** falls back to `state.json` per research session +- **All core research workflows** continue to function without Atlatl + +To add Atlatl in Cowork (if available): +1. Go to **Customize > Connectors** +2. Enable the **Atlatl** connector + +### File System + +Cowork provides a sandboxed filesystem. Sigint writes all output to `./reports/` within the active project directory. This works normally in Cowork's sandbox. + +## Usage in Cowork + +Usage is identical to Claude Code. All commands work the same way: + +``` +/sigint:start AI-powered customer support tools +/sigint:status +/sigint:report --audience executives +/sigint:issues --repo myorg/myrepo +``` + +## Troubleshooting + +### "Blackboard tools not available" + +Atlatl MCP is not connected. Sigint will automatically fall back to file-based coordination. Research workflows are unaffected. + +### "Cannot create GitHub issues" + +Ensure the GitHub connector is enabled in **Customize > Connectors** and you have authorized access to the target repository. + +### "WebSearch unavailable" + +Cowork requires web access permissions. Check that your organization's managed settings allow web search and web fetch for plugins. diff --git a/skills/issues/SKILL.md b/skills/issues/SKILL.md index 558ba3e..dd31db1 100644 --- a/skills/issues/SKILL.md +++ b/skills/issues/SKILL.md @@ -49,7 +49,9 @@ Priority order: 1. `--repo` argument (if provided) 2. `elicitation.default_repo` (if set in state.json) 3. `./.claude/sigint.local.md` `default_repo` setting -4. `gh repo view --json nameWithOwner -q .nameWithOwner` (auto-detect from git remote) +4. Auto-detect from git remote: use GitHub MCP tools (`mcp__github__get_me` or similar) if available, otherwise fall back to `gh repo view --json nameWithOwner -q .nameWithOwner` + +> **Cowork note:** In Cowork environments, `gh` CLI may not be available. Always prefer GitHub MCP tools for repository detection and issue creation. If `dry_run = true`, repository resolution is informational only — no issues will be created. diff --git a/skills/start/SKILL.md b/skills/start/SKILL.md index 196eb73..e53f53b 100644 --- a/skills/start/SKILL.md +++ b/skills/start/SKILL.md @@ -77,6 +77,8 @@ blackboard_create(scope="{topic-slug}", ttl=86400) ``` Store the scope as `blackboard_scope = "{topic-slug}"`. +> **Cowork fallback:** If `blackboard_create` fails (Atlatl MCP unavailable), use file-based coordination instead. Write shared state to `./reports/{topic-slug}/blackboard.json` and coordinate via TaskCreate/SendMessage only. Set `blackboard_scope = null` and skip all subsequent `blackboard_read`/`blackboard_write` calls — use file reads/writes to `blackboard.json` as the coordination mechanism. + **Step 0.1.4**: **CRITICAL — DO NOT SKIP.** Immediately after blackboard_create returns, use **TaskCreate** to create 3 high-level phase tasks (dimension tasks are created after elicitation when priorities are known): - `"Phase 1: Elicitation"` - `"Phase 3: Merge Findings"` — blockedBy Phase 2 tasks (add blockers after Phase 2 tasks are created) From 414858316e83058e113250add5635539f59c1a21 Mon Sep 17 00:00:00 2001 From: Robert Allen Date: Wed, 1 Apr 2026 14:46:47 -0400 Subject: [PATCH 2/2] fix: address Copilot review feedback on Cowork fallbacks - Create reports directory before blackboard fallback writes - Use per-dimension files instead of shared blackboard.json to avoid race conditions - Fix repo detection to use git remote parsing instead of non-existent MCP tool - Align findings_path in completion message with actual fallback filename - Fix {topic} to {topic-slug} for path consistency in deploy guide Resolves review comments on PR #1 --- agents/dimension-analyst.md | 4 ++-- docs/how-to/deploy-to-cowork.md | 4 ++-- skills/issues/SKILL.md | 4 ++-- skills/start/SKILL.md | 9 ++++++++- 4 files changed, 14 insertions(+), 7 deletions(-) diff --git a/agents/dimension-analyst.md b/agents/dimension-analyst.md index efde3a5..2fd1145 100644 --- a/agents/dimension-analyst.md +++ b/agents/dimension-analyst.md @@ -75,7 +75,7 @@ Extract the "## Required Frameworks" table from the loaded skill. Build a method blackboard_write(scope="{scope}", key="methodology_plan_{dimension}", value={methodology plan object}) ``` -> **Cowork fallback:** If blackboard tools are unavailable, write the methodology plan to `./reports/{topic-slug}/blackboard.json` under key `methodology_plan_{dimension}` instead. +> **Cowork fallback:** If blackboard tools are unavailable, write the methodology plan to a per-dimension file, e.g. `./reports/{topic-slug}/methodology_plan_{dimension}.json`, instead of a shared `blackboard.json`. After writing, report to user what frameworks will be applied: "{dimension} analyst: Loading methodology — {N} frameworks planned: {framework names}" @@ -186,7 +186,7 @@ blackboard_alert(scope="{scope}",channel="conflict_detected", message={ dimension: "{dimension}", topic_slug: "{topic-slug}", findings_key: "findings_{dimension}", - findings_path: "./reports/{topic-slug}/{dimension}-findings.md", + findings_path: "./reports/{topic-slug}/findings_{dimension}.json", finding_count: N, confidence_avg: "high|medium|low" }, diff --git a/docs/how-to/deploy-to-cowork.md b/docs/how-to/deploy-to-cowork.md index a263397..3176232 100644 --- a/docs/how-to/deploy-to-cowork.md +++ b/docs/how-to/deploy-to-cowork.md @@ -47,8 +47,8 @@ To connect GitHub in Cowork: Sigint uses Atlatl MCP for blackboard coordination and persistent memory. If Atlatl is not available in your Cowork environment: -- **Blackboard coordination** falls back to file-based state in `./reports/{topic}/blackboard.json` -- **Persistent memory** falls back to `state.json` per research session +- **Blackboard coordination** falls back to file-based state in `./reports/{topic-slug}/` (per-key files) +- **Persistent memory** falls back to `./reports/{topic-slug}/state.json` per research session - **All core research workflows** continue to function without Atlatl To add Atlatl in Cowork (if available): diff --git a/skills/issues/SKILL.md b/skills/issues/SKILL.md index dd31db1..82d11f0 100644 --- a/skills/issues/SKILL.md +++ b/skills/issues/SKILL.md @@ -49,9 +49,9 @@ Priority order: 1. `--repo` argument (if provided) 2. `elicitation.default_repo` (if set in state.json) 3. `./.claude/sigint.local.md` `default_repo` setting -4. Auto-detect from git remote: use GitHub MCP tools (`mcp__github__get_me` or similar) if available, otherwise fall back to `gh repo view --json nameWithOwner -q .nameWithOwner` +4. Auto-detect from git remote: run `git remote get-url origin` (if inside a git repo), parse the GitHub URL to infer `/`, and if git is unavailable or the remote is not GitHub, fall back to `gh repo view --json nameWithOwner -q .nameWithOwner` -> **Cowork note:** In Cowork environments, `gh` CLI may not be available. Always prefer GitHub MCP tools for repository detection and issue creation. +> **Cowork note:** In Cowork environments, `gh` CLI may not be available. If needed, use ToolSearch to discover an MCP tool that can resolve the current repo/context, or fall back to asking the user for the `/` value. If `dry_run = true`, repository resolution is informational only — no issues will be created. diff --git a/skills/start/SKILL.md b/skills/start/SKILL.md index e53f53b..8475c16 100644 --- a/skills/start/SKILL.md +++ b/skills/start/SKILL.md @@ -72,12 +72,19 @@ TeamCreate with team_name: "sigint-{topic-slug}-research" If TeamCreate fails, retry once. If it fails again, report the error and stop. **Step 0.1.3**: Create research directory and blackboard: + +First, ensure the reports directory exists: +```bash +mkdir -p ./reports/{topic-slug} +``` + +Then create the blackboard: ``` blackboard_create(scope="{topic-slug}", ttl=86400) ``` Store the scope as `blackboard_scope = "{topic-slug}"`. -> **Cowork fallback:** If `blackboard_create` fails (Atlatl MCP unavailable), use file-based coordination instead. Write shared state to `./reports/{topic-slug}/blackboard.json` and coordinate via TaskCreate/SendMessage only. Set `blackboard_scope = null` and skip all subsequent `blackboard_read`/`blackboard_write` calls — use file reads/writes to `blackboard.json` as the coordination mechanism. +> **Cowork fallback:** If `blackboard_create` fails (Atlatl MCP unavailable), use file-based coordination instead. The `./reports/{topic-slug}/` directory was already created above. Write per-key files to `./reports/{topic-slug}/` (e.g., `methodology_plan_{dimension}.json`, `findings_{dimension}.json`) and coordinate via TaskCreate/SendMessage only. Set `blackboard_scope = null` and skip all subsequent `blackboard_read`/`blackboard_write` calls — use per-key file reads/writes as the coordination mechanism. **Step 0.1.4**: **CRITICAL — DO NOT SKIP.** Immediately after blackboard_create returns, use **TaskCreate** to create 3 high-level phase tasks (dimension tasks are created after elicitation when priorities are known): - `"Phase 1: Elicitation"`