v35.3 Production Hardening — Implementation Plan¶

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development

Goal: Integrate research findings, fix bugs, add tests, and create international-quality documentation for opencode_initializer.

Architecture: 4 independent blocks executed sequentially. Block A extends scripts with new MCP/LSP/plugins. Block D fixes hardcoded versions and bugs. Block B adds test coverage. Block C rewrites documentation to international standard.

Tech Stack: Bash 5.x, Python 3.14 (inline), npm global, bun bin paths, ShellCheck CI

Global Constraints¶

• All scripts must pass bash -n syntax check
• Every new feature must have real install commands (no stubs)
• Tests: grep-based assert pattern (no real installations)
• Docs: English (international standard), README ≤ 500 lines
• Commit after every completed task (frequent commits)
• No hardcoded secrets anywhere
• Follow existing naming conventions (snake_case functions, 2-space indent)

Block A: Code Integration (6 tasks)¶

Estimate: 1.5 hours

Task A1: Extend MCP_PACKAGES registry¶

Files: - Modify: lib/00-core.sh:169 - Modify: lib/pre-session-check.sh:52

Interfaces: - Consumes: existing MCP_PACKAGES array - Produces: MCP_PACKAGES with +1 entry, pre-session check with +1 entry

• Step 1: Add chrome-devtools-mcp to MCP_PACKAGES in 00-core.sh

Old: "@modelcontextprotocol/server-memory" "memorylayer" "@scitrera/memorylayer-mcp-server" New: add "chrome-devtools-mcp" "chrome-devtools-mcp" "chrome-devtools-mcp" after ollama

• Step 2: Add chrome-devtools-mcp to pre-session-check.sh MCP list (line 52 for loop)

• Step 3: Verify with bash -n lib/00-core.sh lib/pre-session-check.sh

• Step 4: Commit

Task A2: Add new LSP servers to install script¶

Files: - Modify: lib/12-mcp-lsp.sh:70-96 - Modify: lib/18-opencode-json.sh (LSP config generation section) - Modify: modes/health.sh:58-62

• Step 1: Add npm install lines in 12-mcp-lsp.sh for bash-language-server, dockerfile-language-server-nodejs, vscode-langservers-extracted, vscode-json-languageserver

• Step 2: Add LSP config entries in 18-opencode-json.sh generate_lsp_config() for:

• "bash-language-server": {"command": ["bash-language-server", "start"], "extensions": [".sh", ".bash"]}
• "dockerfile-language-server": {"command": ["docker-langserver", "--stdio"], "extensions": ["Dockerfile"]}
• "css-language-server": {"command": ["vscode-css-language-server", "--stdio"], "extensions": [".css", ".scss", ".less"]}
• "html-language-server": {"command": ["vscode-html-language-server", "--stdio"], "extensions": [".html", ".htm"]}

• "json-language-server": {"command": ["vscode-json-language-server", "--stdio"], "extensions": [".json", ".jsonc"]}

• Step 3: Add health checks in modes/health.sh for new LSPs:

• _check "bash-lsp" "which bash-language-server"

• _check "dockerfile-lsp" "which docker-langserver"

• Step 4: Verify with bash -n on all modified files

• Step 5: Commit

Task A3: Add new plugins to install script¶

Files: - Modify: lib/12-mcp-lsp.sh:53-67 - Modify: lib/18-opencode-json.sh (plugins section) - Modify: modes/health.sh:53-56

• Step 1: Add npm install lines in 12-mcp-lsp.sh for:
• @tarquinen/opencode-dcp
• opencode-auto-fallback
• opencode-goal-mode
• opencode-swarm

• opencode-vibeguard

• Step 2: Add plugin names to 18-opencode-json.sh plugin array in generate_opencode_json()

• Step 3: Add health checks in modes/health.sh:

• _check "plugin-dcp" "npm list -g @tarquinen/opencode-dcp &>/dev/null"
• _check "plugin-auto-fallback" "npm list -g opencode-auto-fallback &>/dev/null"

• _check "plugin-swarm" "npm list -g opencode-swarm &>/dev/null"

• Step 4: Verify syntax

• Step 5: Commit

Task A4: Add new CLI tools to system module¶

Files: - Modify: lib/01-system.sh - Modify: modes/health.sh:29-37

• Step 1: Add cargo install lines for bottom, sd, typos-cli in 01-system.sh

• Step 2: Add health checks:

• _check "bottom" "btm --version 2>&1 | head -1"
• _check "sd" "sd --version"

• _check "typos" "typos --version"

• Step 3: Verify syntax

• Step 4: Commit

Task A5: Update opencode.json generation (18-opencode-json.sh)¶

Files: - Modify: lib/18-opencode-json.sh

• Step 1: Add chrome-devtools-mcp detection to generate_mcp_config(): Check if chrome-devtools-mcp is available (which/npm list), add to MCP config with "command": ["npx", "-y", "chrome-devtools-mcp"]

• Step 2: Add new LSP entries to generate_lsp_config() (from Task A2)

• Step 3: Add new plugin entries (from Task A3)

• Step 4: Verify generated JSON is valid with python3 -c "import json; json.load(...)"

• Step 5: Commit

Task A6: Update finalize and verification¶

Files: - Modify: lib/19-finalize.sh:159-173

• Step 1: Add verification checks for new MCP: _verify "chrome-devtools-mcp"

• Step 2: Add verification for new LSPs: bash-language-server, docker-langserver

• Step 3: Add verification for new CLI tools: btm, sd, typos

• Step 4: Verify syntax

• Step 5: Commit

Block D: Fixes & Version Updates (4 tasks)¶

Estimate: 45 minutes

Task D1: Fix hardcoded versions¶

Files: - Modify: lib/12-mcp-lsp.sh - Modify: lib/05-java.sh

• Step 1: Update marksman version from v2026-02-08 to latest (check GitHub releases)
• Step 2: Update lua-language-server version from v3.17.0 to latest
• Step 3: Update Zig version in 05-java.sh from 0.15.1 to latest stable (check ziglang.org/download)
• Step 4: Update any other hardcoded versions found by grep

• Step 5: Verify syntax

• Step 6: Commit

Task D2: Fix version-check.sh for new tools¶

Files: - Modify: lib/version-check.sh

• Step 1: Add version check for chrome-devtools-mcp (npm latest)
• Step 2: Add version check for opencode-codegraph plugin
• Step 3: Verify by running bash lib/version-check.sh as function test
• Step 4: Commit

Task D3: Fix Sublime apt key and apt issues¶

Files: - Modify: lib/01-system.sh - Create: scripts/fix-apt-keys.sh (already created)

• Step 1: Add Sublime GPG key fix to 01-system.sh (check and auto-fix)
• Step 2: Add apt-key verification step

• Step 3: Verify syntax

• Step 4: Commit

Task D4: Update CI and pre-session check¶

Files: - Modify: .github/workflows/test.yml - Modify: lib/pre-session-check.sh - Modify: lib/19-finalize.sh

• Step 1: Ensure CI test runner catches new modules
• Step 2: Add new MCP checks to pre-session loop (already done in A1)
• Step 3: Update global npm install list in upgrade.sh and dev.sh if needed

• Step 4: Verify CI config syntax

• Step 5: Commit

Block B: Test Expansion (3 tasks)¶

Estimate: 1 hour

Task B1: Add unit test for MCP registry¶

Files: - Create: tests/unit/test_mcp_registry.sh

• Step 1: Create test file that verifies:
• All 14 MCP_PACKAGES entries have 3-element tuples
• Every MCP has a corresponding install command in 12-mcp-lsp.sh

• Health check covers all required MCPs

• Step 2: Run test, verify passes

• Step 3: Commit

Task B2: Add integration test for opencode.json generation¶

Files: - Create: tests/integration/test_opencode_json_gen.sh

• Step 1: Create test that verifies:
• Source 18-opencode-json.sh, call generate function
• Verify output JSON is valid (python3 -m json.tool)
• Verify all expected sections exist (mcp, lsp, plugin, agent, provider)

• Verify no duplicate entries

• Step 2: Run test, verify passes

• Step 3: Commit

Task B3: Expand critical path test¶

Files: - Modify: tests/e2e/test_critical_path.sh

• Step 1: Add checks for:
• New LSP config entries in opencode.json
• New plugin config entries
• Version strings consistency across all files

• No stale references to removed components

• Step 2: Run test, verify passes

• Step 3: Commit

Block C: Documentation (4 tasks)¶

Estimate: 1.5 hours

Task C1: Rewrite README.md to international standard¶

Files: - Modify: README.md

Sections to add/rewrite: 1. Badges (version, license, shellcheck, tests) 2. Quick Start (3 commands) 3. Features (bullet list with emoji) 4. Architecture Diagram (ASCII) 5. Installation (with copy-paste commands) 6. Configuration 7. Documentation Links 8. Community & Support 9. License

• Step 1: Write complete README.md
• Step 2: Verify markdown is valid (no broken links)
• Step 3: Commit

Task C2: Update AGENTS.md¶

Files: - Modify: AGENTS.md

• Step 1: Add v35.3 changelog entries
• Step 2: Update module count (22→24 modules)
• Step 3: Update version table with new components
• Step 4: Add new MCP/LSP/plugin counts
• Step 5: Commit

Task C3: Enhance CONTRIBUTING.md¶

Files: - Modify: CONTRIBUTING.md

Sections to add: 1. Development Setup (clone, test, run) 2. Code Style (bash conventions, function naming) 3. Testing Guide (how to run tests, add new tests) 4. Module Structure (how to add new module) 5. PR Checklist 6. Release Process

• Step 1: Write complete CONTRIBUTING.md
• Step 2: Commit

Task C4: Create docs index and structure¶

Files: - Modify: docs/index.md - Create: docs/SECURITY.md (if missing), update existing

• Step 1: Update docs/index.md with table of contents
• Step 2: Ensure all doc links work
• Step 3: Update docs/tools/ files with new components
• Step 4: Commit

Execution Order¶

A1 → A2 → A3 → A4 → A5 → A6  (code integration)
  ↓
D1 → D2 → D3 → D4              (fixes & versions)
  ↓
B1 → B2 → B3                    (tests)
  ↓
C1 → C2 → C3 → C4              (documentation)

Verification Checklist (after all tasks)¶

• bash -n passes on all lib/.sh modes/.sh setup.sh dev.sh
• bash tests/run_tests.sh passes all 15+ tests
• ShellCheck CI passes
• bash setup.sh --health shows 58+ passed
• python3 -c "import json; json.load(open('...opencode.json'))" succeeds
• README.md has no broken links
• All commits pushed to GitHub + GitVerse