From e623fb499dd3110def41411aee0e596917fd8d28 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 1 Mar 2026 17:30:30 +0300 Subject: [PATCH 1/8] Branch for P1-T8: update config examples for borker setup first From 0b575b12a7432c499a2a7641f8678dde3699d26a Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 1 Mar 2026 17:31:37 +0300 Subject: [PATCH 2/8] Select task P1-T8: Update /config examples for borker setup first --- SPECS/INPROGRESS/next.md | 22 +++++++++++++--------- SPECS/Workplan.md | 14 ++++++++++++++ 2 files changed, 27 insertions(+), 9 deletions(-) diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index a8c42db6..dfb5648e 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -1,12 +1,16 @@ -# No Active Task +# Active Task -**Status:** Idle — P2-T6 archived. Select the next task from `SPECS/Workplan.md`. +**Status:** Selected — ready for planning/execution. -## Recently Archived +## Task Metadata -- **P2-T6** — Remove legacy --broker-connect and --broker-spawn flags (2026-03-01, PASS) -- **P1-T7** — Hide README version badge maintenance note (2026-03-01, PASS) -- **P1-T4** — Update docs to reflect broker robustness improvements (2026-03-01, PASS) -- **P2-T5** — Warn or restart daemon when --web-ui requested but running broker lacks it (2026-03-01, PASS) -- **P2-T4** — Surface broker unavailability as JSON-RPC error instead of silent timeout (2026-03-01, PASS) -- **P2-T3** — Fix double-spawn race condition when MCP client toggles rapidly (2026-03-01, PASS) +- **Task ID:** P1-T8 +- **Task Name:** Update /config examples for borker setup first +- **Priority:** P1 +- **Dependencies:** P2-T6 +- **Parallelizable:** yes +- **Source:** `SPECS/Workplan.md` + +## Summary + +Update client configuration templates under `config/` so broker setup appears first for Cursor, Claude Code, Codex CLI, and Zed examples. diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index ed639b7c..1d7bc469 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -112,6 +112,20 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m - [x] `README.md` no longer contains the exact string `Version badge maintenance: run make badge-version (or make badge-version-check in CI).` - [x] Version badge remains visible and functional after removing the maintenance note +#### ⬜ P1-T8: Update /config examples for borker setup first +- **Status:** ⬜ Pending +- **Description:** Update MCP client templates under `config/` so broker-mode setup is presented first and consistently framed as the recommended path. +- **Priority:** P1 +- **Dependencies:** P2-T6 +- **Parallelizable:** yes +- **Outputs/Artifacts:** + - `config/cursor-mcp.json` and `config/zed-agent.json` reordered to show broker-mode options before non-broker alternatives + - `config/claude-code.txt` and `config/codex-cli.txt` updated so broker commands appear before non-broker commands +- **Acceptance Criteria:** + - [ ] Cursor and Zed config templates present a broker-mode option first + - [ ] Claude Code and Codex CLI config templates present a broker command first + - [ ] Broker-first guidance is consistent with existing `*-broker` templates and `--broker` usage + ### Phase 2: Broker Robustness #### ✅ P2-T1: Replace --broker-spawn/--broker-connect with single --broker flag From 293573522d8da9745a32e12214f9233b8ddfbe77 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 1 Mar 2026 17:31:56 +0300 Subject: [PATCH 3/8] Plan task P1-T8: Update /config examples for borker setup first --- ..._config_examples_for_borker_setup_first.md | 61 +++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 SPECS/INPROGRESS/P1-T8_Update_config_examples_for_borker_setup_first.md diff --git a/SPECS/INPROGRESS/P1-T8_Update_config_examples_for_borker_setup_first.md b/SPECS/INPROGRESS/P1-T8_Update_config_examples_for_borker_setup_first.md new file mode 100644 index 00000000..eaaf0096 --- /dev/null +++ b/SPECS/INPROGRESS/P1-T8_Update_config_examples_for_borker_setup_first.md @@ -0,0 +1,61 @@ +# PRD: P1-T8 — Update /config examples for borker setup first + +## Overview + +`README.md` already presents broker setup first, but several standalone templates in +`config/` still lead with non-broker examples. This task aligns those templates +with current guidance by presenting broker-mode setup first for supported MCP +clients. + +## Problem Statement + +Users often copy from `config/` files directly. When non-broker examples appear +first, the docs and templates send mixed signals about the preferred setup path. +With `--broker` now the primary mode, templates should reflect that ordering. + +## Scope + +In scope: +- Reorder options in `config/cursor-mcp.json` and `config/zed-agent.json` so a + broker-mode configuration is listed first. +- Update `config/claude-code.txt` and `config/codex-cli.txt` so broker setup + commands are shown before non-broker alternatives. +- Keep command syntax compatible with current `--broker` guidance. + +Out of scope: +- Runtime behavior changes in Python source code. +- Changes to broker-specific template files that already lead with broker mode. + +## Deliverables + +| File(s) | Change | +|---|---| +| `config/cursor-mcp.json` | Broker option block moved to first position and labeled as recommended | +| `config/zed-agent.json` | Broker option block moved to first position and labeled as recommended | +| `config/claude-code.txt` | Broker command block added as first option | +| `config/codex-cli.txt` | Broker command block added as first option | + +## Acceptance Criteria + +- [ ] `config/cursor-mcp.json` presents a broker-mode option first in `xcode-tools` options. +- [ ] `config/zed-agent.json` presents a broker-mode option first in `xcode-tools` options. +- [ ] `config/claude-code.txt` lists a broker setup command before non-broker options. +- [ ] `config/codex-cli.txt` lists a broker setup command before non-broker options. +- [ ] Full quality gates pass: `pytest`, `ruff check src/`, `mypy src/`, `pytest --cov` (>= 90%). + +## Validation Plan + +1. Inspect option ordering in each updated config template. +2. Run `pytest`. +3. Run `ruff check src/`. +4. Run `mypy src/`. +5. Run `pytest --cov` and confirm coverage remains >= 90%. + +## Dependencies + +- P2-T6 + +## Risks + +Low. This is a documentation/template ordering change and does not alter runtime +logic. From c3a8a19bf1fa06d545ca6c817226db9f3e936fcf Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 1 Mar 2026 17:34:52 +0300 Subject: [PATCH 4/8] Implement P1-T8: update config templates for broker-first setup --- SPECS/INPROGRESS/P1-T8_Validation_Report.md | 54 +++++++++++++++++++++ config/claude-code.txt | 35 ++++++++----- config/codex-cli.txt | 35 ++++++++----- config/cursor-mcp.json | 34 ++++++++++--- config/zed-agent.json | 31 +++++++++--- 5 files changed, 153 insertions(+), 36 deletions(-) create mode 100644 SPECS/INPROGRESS/P1-T8_Validation_Report.md diff --git a/SPECS/INPROGRESS/P1-T8_Validation_Report.md b/SPECS/INPROGRESS/P1-T8_Validation_Report.md new file mode 100644 index 00000000..a6b190f1 --- /dev/null +++ b/SPECS/INPROGRESS/P1-T8_Validation_Report.md @@ -0,0 +1,54 @@ +# Validation Report: P1-T8 — Update /config examples for borker setup first + +**Date:** 2026-03-01 +**Verdict:** PASS + +## Summary + +Updated client configuration templates under `config/` so broker-mode setup appears first for Cursor, Zed, Claude Code, and Codex CLI examples. + +## Delivered Changes + +- `config/cursor-mcp.json` + - Added broker-first option blocks (`_option1_uvx_broker`, `_option1b_uvx_broker_web_ui`). + - Shifted non-broker options to `_option2*` and below. +- `config/zed-agent.json` + - Added broker-first option blocks (`_option1_uvx_broker`, `_option1b_uvx_broker_web_ui`). + - Shifted non-broker options to `_option2*` and below. +- `config/claude-code.txt` + - Added broker-mode command as `OPTION 1` and broker + Web UI as `OPTION 1B`. + - Moved non-broker alternatives to `OPTION 2` and below. +- `config/codex-cli.txt` + - Added broker-mode command as `OPTION 1` and broker + Web UI as `OPTION 1B`. + - Moved non-broker alternatives to `OPTION 2` and below. + +## Acceptance Criteria Check + +- [x] `config/cursor-mcp.json` presents a broker-mode option first in `xcode-tools` options. +- [x] `config/zed-agent.json` presents a broker-mode option first in `xcode-tools` options. +- [x] `config/claude-code.txt` lists a broker setup command before non-broker options. +- [x] `config/codex-cli.txt` lists a broker setup command before non-broker options. +- [x] Full quality gates pass: `pytest`, `ruff check src/`, `mypy src/`, `pytest --cov` (>= 90%). + +## Quality Gates + +1. `pytest` +- Result: PASS +- Evidence: `735 passed, 5 skipped` + +2. `ruff check src/` +- Result: PASS +- Evidence: `All checks passed!` + +3. `mypy src/` +- Result: PASS +- Evidence: `Success: no issues found in 18 source files` + +4. `pytest --cov` +- Result: PASS +- Evidence: `Required test coverage of 90.0% reached. Total coverage: 91.26%` + +## Notes + +- Initial `pytest` run failed due environment import setup (`ModuleNotFoundError: mcpbridge_wrapper`). +- Resolved by installing the package in editable mode with `python3 -m pip install -e .`, then re-running quality gates successfully. diff --git a/config/claude-code.txt b/config/claude-code.txt index b793cce2..4f496687 100644 --- a/config/claude-code.txt +++ b/config/claude-code.txt @@ -1,14 +1,25 @@ # Claude Code MCP Configuration for xcodemcpwrapper # -# OPTION 1: Using uvx (Recommended - Easiest) -# ------------------------------------------- -# No manual installation needed. uvx automatically downloads and runs the wrapper. +# OPTION 1: Using uvx with broker mode (Recommended) +# --------------------------------------------------- +# Shares a single broker daemon across MCP clients and auto-starts it if needed. +# +# claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker +# +# OPTION 1B: Using uvx with broker mode + Web UI (Optional) +# ---------------------------------------------------------- +# Enable broker mode and host the dashboard on port 8080: +# +# claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --broker --web-ui --web-ui-port 8080 +# +# OPTION 2: Using uvx (Non-broker Alternative) +# --------------------------------------------- +# Starts an independent wrapper process per client session. # # claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper # -# OPTION 1B: Using uvx with Web UI (Optional) -# ------------------------------------------- -# Enable the Web UI dashboard on port 8080: +# OPTION 2B: Using uvx with Web UI (Non-broker, Optional) +# -------------------------------------------------------- # # claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080 # @@ -17,26 +28,26 @@ # or: brew install uv # # -# OPTION 2: Manual Installation +# OPTION 3: Manual Installation # ----------------------------- # If you installed manually to ~/bin/xcodemcpwrapper: # # claude mcp add --transport stdio xcode -- /Users/USERNAME/bin/xcodemcpwrapper # -# OPTION 2B: Manual Installation with Web UI (Optional) +# OPTION 3B: Manual Installation with Web UI (Optional) # ----------------------------------------------------- # Enable the Web UI dashboard on port 8080: # # claude mcp add --transport stdio xcode -- /Users/USERNAME/bin/xcodemcpwrapper --web-ui --web-ui-port 8080 # # -# OPTION 3: Local Development (from cloned repo with venv) +# OPTION 4: Local Development (from cloned repo with venv) # -------------------------------------------------------- # If you cloned the repo and installed via `make install` in a virtual environment: # # claude mcp add --transport stdio xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper # -# OPTION 3B: Local Development with Web UI (Optional) +# OPTION 4B: Local Development with Web UI (Optional) # ---------------------------------------------------- # Enable the Web UI dashboard on port 8080: # @@ -48,5 +59,5 @@ # Verification: # claude mcp list # -# Note: Replace USERNAME with your actual username for option 2. -# Note: Replace /path/to/XcodeMCPWrapper with your repo path for option 3. +# Note: Replace USERNAME with your actual username for option 3. +# Note: Replace /path/to/XcodeMCPWrapper with your repo path for option 4. diff --git a/config/codex-cli.txt b/config/codex-cli.txt index cff5cfa4..062747ea 100644 --- a/config/codex-cli.txt +++ b/config/codex-cli.txt @@ -1,14 +1,25 @@ # Codex CLI MCP Configuration for xcodemcpwrapper # -# OPTION 1: Using uvx (Recommended - Easiest) -# ------------------------------------------- -# No manual installation needed. uvx automatically downloads and runs the wrapper. +# OPTION 1: Using uvx with broker mode (Recommended) +# --------------------------------------------------- +# Shares a single broker daemon across MCP clients and auto-starts it if needed. +# +# codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker +# +# OPTION 1B: Using uvx with broker mode + Web UI (Optional) +# ---------------------------------------------------------- +# Enable broker mode and host the dashboard on port 8080: +# +# codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --broker --web-ui --web-ui-port 8080 +# +# OPTION 2: Using uvx (Non-broker Alternative) +# --------------------------------------------- +# Starts an independent wrapper process per client session. # # codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper # -# OPTION 1B: Using uvx with Web UI (Optional) -# ------------------------------------------- -# Enable the Web UI dashboard on port 8080: +# OPTION 2B: Using uvx with Web UI (Non-broker, Optional) +# -------------------------------------------------------- # # codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080 # @@ -17,26 +28,26 @@ # or: brew install uv # # -# OPTION 2: Manual Installation +# OPTION 3: Manual Installation # ----------------------------- # If you installed manually to ~/bin/xcodemcpwrapper: # # codex mcp add xcode -- /Users/USERNAME/bin/xcodemcpwrapper # -# OPTION 2B: Manual Installation with Web UI (Optional) +# OPTION 3B: Manual Installation with Web UI (Optional) # ----------------------------------------------------- # Enable the Web UI dashboard on port 8080: # # codex mcp add xcode -- /Users/USERNAME/bin/xcodemcpwrapper --web-ui --web-ui-port 8080 # # -# OPTION 3: Local Development (from cloned repo with venv) +# OPTION 4: Local Development (from cloned repo with venv) # -------------------------------------------------------- # If you cloned the repo and installed via `make install` in a virtual environment: # # codex mcp add xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper # -# OPTION 3B: Local Development with Web UI (Optional) +# OPTION 4B: Local Development with Web UI (Optional) # ---------------------------------------------------- # Enable the Web UI dashboard on port 8080: # @@ -48,5 +59,5 @@ # Verification: # codex mcp list # -# Note: Replace USERNAME with your actual username for option 2. -# Note: Replace /path/to/XcodeMCPWrapper with your repo path for option 3. +# Note: Replace USERNAME with your actual username for option 3. +# Note: Replace /path/to/XcodeMCPWrapper with your repo path for option 4. diff --git a/config/cursor-mcp.json b/config/cursor-mcp.json index e9be83cc..11794dd8 100644 --- a/config/cursor-mcp.json +++ b/config/cursor-mcp.json @@ -1,12 +1,34 @@ { "_comment": "Xcode MCP Bridge Wrapper configuration for Cursor", + "_note": "Broker-first template. Copy ONE option block into your real xcode-tools server entry.", "mcpServers": { "xcode-tools": { - "_option1_uvx": { + "_option1_uvx_broker": { + "command": "uvx", + "args": [ + "--from", + "mcpbridge-wrapper", + "mcpbridge-wrapper", + "--broker" + ] + }, + "_option1b_uvx_broker_web_ui": { + "command": "uvx", + "args": [ + "--from", + "mcpbridge-wrapper[webui]", + "mcpbridge-wrapper", + "--broker", + "--web-ui", + "--web-ui-port", + "8080" + ] + }, + "_option2_uvx": { "command": "uvx", "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"] }, - "_option1b_uvx_web_ui": { + "_option2b_uvx_web_ui": { "command": "uvx", "args": [ "--from", @@ -17,19 +39,19 @@ "8080" ] }, - "_option2_manual": { + "_option3_manual": { "command": "/Users/USERNAME/bin/xcodemcpwrapper", "args": [] }, - "_option2b_manual_web_ui": { + "_option3b_manual_web_ui": { "command": "/Users/USERNAME/bin/xcodemcpwrapper", "args": ["--web-ui", "--web-ui-port", "8080"] }, - "_option3_local_dev": { + "_option4_local_dev": { "command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper", "args": [] }, - "_option3b_local_dev_web_ui": { + "_option4b_local_dev_web_ui": { "command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper", "args": ["--web-ui", "--web-ui-port", "8080"] } diff --git a/config/zed-agent.json b/config/zed-agent.json index 195d9fe0..af7f37cc 100644 --- a/config/zed-agent.json +++ b/config/zed-agent.json @@ -1,12 +1,31 @@ { "_comment": "Xcode MCP Bridge Wrapper configuration for Zed Agent", + "_note": "Broker-first template. Copy ONE option block into your real xcode-tools entry.", "xcode-tools": { - "_option1_uvx": { + "_option1_uvx_broker": { + "command": "uvx", + "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper", "--broker"], + "env": {} + }, + "_option1b_uvx_broker_web_ui": { + "command": "uvx", + "args": [ + "--from", + "mcpbridge-wrapper[webui]", + "mcpbridge-wrapper", + "--broker", + "--web-ui", + "--web-ui-port", + "8080" + ], + "env": {} + }, + "_option2_uvx": { "command": "uvx", "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"], "env": {} }, - "_option1b_uvx_web_ui": { + "_option2b_uvx_web_ui": { "command": "uvx", "args": [ "--from", @@ -18,22 +37,22 @@ ], "env": {} }, - "_option2_manual": { + "_option3_manual": { "command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper", "args": [], "env": {} }, - "_option2b_manual_web_ui": { + "_option3b_manual_web_ui": { "command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper", "args": ["--web-ui", "--web-ui-port", "8080"], "env": {} }, - "_option3_local_dev": { + "_option4_local_dev": { "command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper", "args": [], "env": {} }, - "_option3b_local_dev_web_ui": { + "_option4b_local_dev_web_ui": { "command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper", "args": ["--web-ui", "--web-ui-port", "8080"], "env": {} From 5c616d4c718ed3eff7a395f5da28fa4d4278d0b1 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 1 Mar 2026 17:36:02 +0300 Subject: [PATCH 5/8] Archive task P1-T8: Update /config examples for borker setup first (PASS) --- SPECS/ARCHIVE/INDEX.md | 4 +++- ..._config_examples_for_borker_setup_first.md | 4 ++++ .../P1-T8_Validation_Report.md | 0 SPECS/INPROGRESS/next.md | 22 ++++++++----------- SPECS/Workplan.md | 10 ++++----- 5 files changed, 21 insertions(+), 19 deletions(-) rename SPECS/{INPROGRESS => ARCHIVE/P1-T8_Update_config_examples_for_borker_setup_first}/P1-T8_Update_config_examples_for_borker_setup_first.md (97%) rename SPECS/{INPROGRESS => ARCHIVE/P1-T8_Update_config_examples_for_borker_setup_first}/P1-T8_Validation_Report.md (100%) diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md index 6ffb40da..fbb4fa60 100644 --- a/SPECS/ARCHIVE/INDEX.md +++ b/SPECS/ARCHIVE/INDEX.md @@ -1,11 +1,12 @@ # mcpbridge-wrapper Tasks Archive -**Last Updated:** 2026-03-01 (P2-T6 archived) +**Last Updated:** 2026-03-01 (P1-T8 archived) ## Archived Tasks | Task ID | Folder | Archived | Verdict | |---------|--------|----------|---------| +| P1-T8 | [P1-T8_Update_config_examples_for_borker_setup_first/](P1-T8_Update_config_examples_for_borker_setup_first/) | 2026-03-01 | PASS | | P2-T6 | [P2-T6_Remove_legacy_broker_connect_and_broker_spawn_flags/](P2-T6_Remove_legacy_broker_connect_and_broker_spawn_flags/) | 2026-03-01 | PASS | | P1-T7 | [P1-T7_Hide_README_version_badge_maintenance_note/](P1-T7_Hide_README_version_badge_maintenance_note/) | 2026-03-01 | PASS | | P1-T4 | [P1-T4_Update_docs_broker_robustness/](P1-T4_Update_docs_broker_robustness/) | 2026-03-01 | PASS | @@ -305,6 +306,7 @@ | Date | Task ID | Action | |------|---------|--------| +| 2026-03-01 | P1-T8 | Archived Update /config examples for borker setup first (PASS) | | 2026-03-01 | P2-T6 | Archived REVIEW_p2_t6_remove_legacy_broker_flags report | | 2026-03-01 | P2-T6 | Archived Remove legacy --broker-connect and --broker-spawn flags (PASS) | | 2026-03-01 | P1-T7 | Archived REVIEW_P1-T7_readme_badge_note report | diff --git a/SPECS/INPROGRESS/P1-T8_Update_config_examples_for_borker_setup_first.md b/SPECS/ARCHIVE/P1-T8_Update_config_examples_for_borker_setup_first/P1-T8_Update_config_examples_for_borker_setup_first.md similarity index 97% rename from SPECS/INPROGRESS/P1-T8_Update_config_examples_for_borker_setup_first.md rename to SPECS/ARCHIVE/P1-T8_Update_config_examples_for_borker_setup_first/P1-T8_Update_config_examples_for_borker_setup_first.md index eaaf0096..f1430ec3 100644 --- a/SPECS/INPROGRESS/P1-T8_Update_config_examples_for_borker_setup_first.md +++ b/SPECS/ARCHIVE/P1-T8_Update_config_examples_for_borker_setup_first/P1-T8_Update_config_examples_for_borker_setup_first.md @@ -59,3 +59,7 @@ Out of scope: Low. This is a documentation/template ordering change and does not alter runtime logic. + +--- +**Archived:** 2026-03-01 +**Verdict:** PASS diff --git a/SPECS/INPROGRESS/P1-T8_Validation_Report.md b/SPECS/ARCHIVE/P1-T8_Update_config_examples_for_borker_setup_first/P1-T8_Validation_Report.md similarity index 100% rename from SPECS/INPROGRESS/P1-T8_Validation_Report.md rename to SPECS/ARCHIVE/P1-T8_Update_config_examples_for_borker_setup_first/P1-T8_Validation_Report.md diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index dfb5648e..f468a8b7 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -1,16 +1,12 @@ -# Active Task +# No Active Task -**Status:** Selected — ready for planning/execution. +**Status:** Idle — P1-T8 archived. Select the next task from `SPECS/Workplan.md`. -## Task Metadata +## Recently Archived -- **Task ID:** P1-T8 -- **Task Name:** Update /config examples for borker setup first -- **Priority:** P1 -- **Dependencies:** P2-T6 -- **Parallelizable:** yes -- **Source:** `SPECS/Workplan.md` - -## Summary - -Update client configuration templates under `config/` so broker setup appears first for Cursor, Claude Code, Codex CLI, and Zed examples. +- **P1-T8** — Update /config examples for borker setup first (2026-03-01, PASS) +- **P2-T6** — Remove legacy --broker-connect and --broker-spawn flags (2026-03-01, PASS) +- **P1-T7** — Hide README version badge maintenance note (2026-03-01, PASS) +- **P1-T4** — Update docs to reflect broker robustness improvements (2026-03-01, PASS) +- **P2-T5** — Warn or restart daemon when --web-ui requested but running broker lacks it (2026-03-01, PASS) +- **P2-T4** — Surface broker unavailability as JSON-RPC error instead of silent timeout (2026-03-01, PASS) diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index 1d7bc469..7707791a 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -112,8 +112,8 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m - [x] `README.md` no longer contains the exact string `Version badge maintenance: run make badge-version (or make badge-version-check in CI).` - [x] Version badge remains visible and functional after removing the maintenance note -#### ⬜ P1-T8: Update /config examples for borker setup first -- **Status:** ⬜ Pending +#### ✅ P1-T8: Update /config examples for borker setup first +- **Status:** ✅ Completed (2026-03-01) - **Description:** Update MCP client templates under `config/` so broker-mode setup is presented first and consistently framed as the recommended path. - **Priority:** P1 - **Dependencies:** P2-T6 @@ -122,9 +122,9 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m - `config/cursor-mcp.json` and `config/zed-agent.json` reordered to show broker-mode options before non-broker alternatives - `config/claude-code.txt` and `config/codex-cli.txt` updated so broker commands appear before non-broker commands - **Acceptance Criteria:** - - [ ] Cursor and Zed config templates present a broker-mode option first - - [ ] Claude Code and Codex CLI config templates present a broker command first - - [ ] Broker-first guidance is consistent with existing `*-broker` templates and `--broker` usage + - [x] Cursor and Zed config templates present a broker-mode option first + - [x] Claude Code and Codex CLI config templates present a broker command first + - [x] Broker-first guidance is consistent with existing `*-broker` templates and `--broker` usage ### Phase 2: Broker Robustness From ee2509320b1ef36b435d1f6736eea0cb68cdd30c Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 1 Mar 2026 17:36:22 +0300 Subject: [PATCH 6/8] Review P1-T8: config broker setup first --- .../REVIEW_p1_t8_config_broker_setup_first.md | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 SPECS/INPROGRESS/REVIEW_p1_t8_config_broker_setup_first.md diff --git a/SPECS/INPROGRESS/REVIEW_p1_t8_config_broker_setup_first.md b/SPECS/INPROGRESS/REVIEW_p1_t8_config_broker_setup_first.md new file mode 100644 index 00000000..da4e03e9 --- /dev/null +++ b/SPECS/INPROGRESS/REVIEW_p1_t8_config_broker_setup_first.md @@ -0,0 +1,31 @@ +## REVIEW REPORT — P1-T8 Config Broker Setup First + +**Scope:** `origin/main..HEAD` +**Files:** 9 + +### Summary Verdict +- [x] Approve +- [ ] Approve with comments +- [ ] Request changes +- [ ] Block + +### Critical Issues +- None. + +### Secondary Issues +- None. + +### Architectural Notes +- Config templates now align with broker-first guidance already reflected in README/docs, reducing mismatch between direct template copy paths and documented recommendations. +- JSON template option ordering is explicit and keeps non-broker alternatives available for users that still need per-session mode. + +### Tests +- Quality gates were run and passed: + - `pytest` → `735 passed, 5 skipped` + - `ruff check src/` → pass + - `mypy src/` → pass + - `pytest --cov` → `91.26%` (>= 90%) + +### Next Steps +- No actionable follow-up items from this review. +- FOLLOW-UP step is skipped per FLOW rules. From 2303c7da476bd3469648d6742be6a55de9865b85 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 1 Mar 2026 17:36:50 +0300 Subject: [PATCH 7/8] Archive REVIEW_p1_t8_config_broker_setup_first report --- SPECS/ARCHIVE/INDEX.md | 2 ++ .../_Historical}/REVIEW_p1_t8_config_broker_setup_first.md | 0 2 files changed, 2 insertions(+) rename SPECS/{INPROGRESS => ARCHIVE/_Historical}/REVIEW_p1_t8_config_broker_setup_first.md (100%) diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md index fbb4fa60..2756fe03 100644 --- a/SPECS/ARCHIVE/INDEX.md +++ b/SPECS/ARCHIVE/INDEX.md @@ -181,6 +181,7 @@ | File | Description | |------|-------------| +| [REVIEW_p1_t8_config_broker_setup_first.md](_Historical/REVIEW_p1_t8_config_broker_setup_first.md) | Review report for P1-T8 | | [REVIEW_P2-T5_webui_mismatch_warning.md](_Historical/REVIEW_P2-T5_webui_mismatch_warning.md) | Review report for P2-T5 | | [REVIEW_P2-T4_broker_unavailable_error.md](_Historical/REVIEW_P2-T4_broker_unavailable_error.md) | Review report for P2-T4 | | [REVIEW_P2-T3_spawn_lock.md](_Historical/REVIEW_P2-T3_spawn_lock.md) | Review report for P2-T3 | @@ -306,6 +307,7 @@ | Date | Task ID | Action | |------|---------|--------| +| 2026-03-01 | P1-T8 | Archived REVIEW_p1_t8_config_broker_setup_first report | | 2026-03-01 | P1-T8 | Archived Update /config examples for borker setup first (PASS) | | 2026-03-01 | P2-T6 | Archived REVIEW_p2_t6_remove_legacy_broker_flags report | | 2026-03-01 | P2-T6 | Archived Remove legacy --broker-connect and --broker-spawn flags (PASS) | diff --git a/SPECS/INPROGRESS/REVIEW_p1_t8_config_broker_setup_first.md b/SPECS/ARCHIVE/_Historical/REVIEW_p1_t8_config_broker_setup_first.md similarity index 100% rename from SPECS/INPROGRESS/REVIEW_p1_t8_config_broker_setup_first.md rename to SPECS/ARCHIVE/_Historical/REVIEW_p1_t8_config_broker_setup_first.md From f34502fe47e7c2a95ca6179eedb6903fb27f2595 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 1 Mar 2026 18:29:22 +0300 Subject: [PATCH 8/8] Follow-up P1-T8: fix review comments for broker naming and archive links --- SPECS/ARCHIVE/INDEX.md | 4 ++-- .../P1-T8_Update_config_examples_for_broker_setup_first.md} | 2 +- .../P1-T8_Validation_Report.md | 4 ++-- SPECS/INPROGRESS/next.md | 3 ++- SPECS/Workplan.md | 2 +- 5 files changed, 8 insertions(+), 7 deletions(-) rename SPECS/ARCHIVE/{P1-T8_Update_config_examples_for_borker_setup_first/P1-T8_Update_config_examples_for_borker_setup_first.md => P1-T8_Update_config_examples_for_broker_setup_first/P1-T8_Update_config_examples_for_broker_setup_first.md} (97%) rename SPECS/ARCHIVE/{P1-T8_Update_config_examples_for_borker_setup_first => P1-T8_Update_config_examples_for_broker_setup_first}/P1-T8_Validation_Report.md (91%) diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md index 2756fe03..db203c88 100644 --- a/SPECS/ARCHIVE/INDEX.md +++ b/SPECS/ARCHIVE/INDEX.md @@ -6,7 +6,7 @@ | Task ID | Folder | Archived | Verdict | |---------|--------|----------|---------| -| P1-T8 | [P1-T8_Update_config_examples_for_borker_setup_first/](P1-T8_Update_config_examples_for_borker_setup_first/) | 2026-03-01 | PASS | +| P1-T8 | [P1-T8_Update_config_examples_for_broker_setup_first/](P1-T8_Update_config_examples_for_broker_setup_first/) | 2026-03-01 | PASS | | P2-T6 | [P2-T6_Remove_legacy_broker_connect_and_broker_spawn_flags/](P2-T6_Remove_legacy_broker_connect_and_broker_spawn_flags/) | 2026-03-01 | PASS | | P1-T7 | [P1-T7_Hide_README_version_badge_maintenance_note/](P1-T7_Hide_README_version_badge_maintenance_note/) | 2026-03-01 | PASS | | P1-T4 | [P1-T4_Update_docs_broker_robustness/](P1-T4_Update_docs_broker_robustness/) | 2026-03-01 | PASS | @@ -308,7 +308,7 @@ | Date | Task ID | Action | |------|---------|--------| | 2026-03-01 | P1-T8 | Archived REVIEW_p1_t8_config_broker_setup_first report | -| 2026-03-01 | P1-T8 | Archived Update /config examples for borker setup first (PASS) | +| 2026-03-01 | P1-T8 | Archived Update /config examples for broker setup first (PASS) | | 2026-03-01 | P2-T6 | Archived REVIEW_p2_t6_remove_legacy_broker_flags report | | 2026-03-01 | P2-T6 | Archived Remove legacy --broker-connect and --broker-spawn flags (PASS) | | 2026-03-01 | P1-T7 | Archived REVIEW_P1-T7_readme_badge_note report | diff --git a/SPECS/ARCHIVE/P1-T8_Update_config_examples_for_borker_setup_first/P1-T8_Update_config_examples_for_borker_setup_first.md b/SPECS/ARCHIVE/P1-T8_Update_config_examples_for_broker_setup_first/P1-T8_Update_config_examples_for_broker_setup_first.md similarity index 97% rename from SPECS/ARCHIVE/P1-T8_Update_config_examples_for_borker_setup_first/P1-T8_Update_config_examples_for_borker_setup_first.md rename to SPECS/ARCHIVE/P1-T8_Update_config_examples_for_broker_setup_first/P1-T8_Update_config_examples_for_broker_setup_first.md index f1430ec3..b346d8f8 100644 --- a/SPECS/ARCHIVE/P1-T8_Update_config_examples_for_borker_setup_first/P1-T8_Update_config_examples_for_borker_setup_first.md +++ b/SPECS/ARCHIVE/P1-T8_Update_config_examples_for_broker_setup_first/P1-T8_Update_config_examples_for_broker_setup_first.md @@ -1,4 +1,4 @@ -# PRD: P1-T8 — Update /config examples for borker setup first +# PRD: P1-T8 — Update /config examples for broker setup first ## Overview diff --git a/SPECS/ARCHIVE/P1-T8_Update_config_examples_for_borker_setup_first/P1-T8_Validation_Report.md b/SPECS/ARCHIVE/P1-T8_Update_config_examples_for_broker_setup_first/P1-T8_Validation_Report.md similarity index 91% rename from SPECS/ARCHIVE/P1-T8_Update_config_examples_for_borker_setup_first/P1-T8_Validation_Report.md rename to SPECS/ARCHIVE/P1-T8_Update_config_examples_for_broker_setup_first/P1-T8_Validation_Report.md index a6b190f1..69d49dd5 100644 --- a/SPECS/ARCHIVE/P1-T8_Update_config_examples_for_borker_setup_first/P1-T8_Validation_Report.md +++ b/SPECS/ARCHIVE/P1-T8_Update_config_examples_for_broker_setup_first/P1-T8_Validation_Report.md @@ -1,4 +1,4 @@ -# Validation Report: P1-T8 — Update /config examples for borker setup first +# Validation Report: P1-T8 — Update /config examples for broker setup first **Date:** 2026-03-01 **Verdict:** PASS @@ -50,5 +50,5 @@ Updated client configuration templates under `config/` so broker-mode setup appe ## Notes -- Initial `pytest` run failed due environment import setup (`ModuleNotFoundError: mcpbridge_wrapper`). +- Initial `pytest` run failed due to environment import setup (`ModuleNotFoundError: mcpbridge_wrapper`). - Resolved by installing the package in editable mode with `python3 -m pip install -e .`, then re-running quality gates successfully. diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index f468a8b7..6d9a0541 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -4,9 +4,10 @@ ## Recently Archived -- **P1-T8** — Update /config examples for borker setup first (2026-03-01, PASS) +- **P1-T8** — Update /config examples for broker setup first (2026-03-01, PASS) - **P2-T6** — Remove legacy --broker-connect and --broker-spawn flags (2026-03-01, PASS) - **P1-T7** — Hide README version badge maintenance note (2026-03-01, PASS) - **P1-T4** — Update docs to reflect broker robustness improvements (2026-03-01, PASS) - **P2-T5** — Warn or restart daemon when --web-ui requested but running broker lacks it (2026-03-01, PASS) - **P2-T4** — Surface broker unavailability as JSON-RPC error instead of silent timeout (2026-03-01, PASS) +- **P2-T3** — Fix double-spawn race condition when MCP client toggles rapidly (2026-03-01, PASS) diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index 7707791a..b269a953 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -112,7 +112,7 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m - [x] `README.md` no longer contains the exact string `Version badge maintenance: run make badge-version (or make badge-version-check in CI).` - [x] Version badge remains visible and functional after removing the maintenance note -#### ✅ P1-T8: Update /config examples for borker setup first +#### ✅ P1-T8: Update /config examples for broker setup first - **Status:** ✅ Completed (2026-03-01) - **Description:** Update MCP client templates under `config/` so broker-mode setup is presented first and consistently framed as the recommended path. - **Priority:** P1