From 6ff889f4616fe96c74086dcef7aaa3299c123a33 Mon Sep 17 00:00:00 2001 From: Simon Mak Date: Sat, 3 Oct 2026 01:55:08 +0800 Subject: [PATCH] docs: refresh to current state (9 tools, 35 MCP/33 enabled, 45 skills, v1.1.2, VDD, registry) - README/AGENTS: tools list (9), secrets table (drop Figma/Kimi), recovery steps, score 94 - runtime config + snapshot: 35/33, remote 9, vercel token auth, figma removed, skills 45 - WORKFLOW_STATE, documentation-gaps: reflect delivered implementation + VDD chain - llms.txt/context7/glama/connector: 9 tools, 35 MCP, v1.1.2 - clone-mcp: add bootstrap_host; recovery-gap-analysis refresh - verified: doc/inventory CI checks pass; no stale tokens --- AGENTS.md | 9 +- README.md | 27 +++-- WORKFLOW_STATE.md | 100 +++++++++--------- connector.json | 2 +- context7.json | 5 +- docs/architecture/clone-mcp.md | 1 + docs/architecture/opencode-runtime-config.md | 99 +++++++++-------- .../architecture/opencode-runtime-snapshot.md | 83 ++++++++------- docs/audit/documentation-gaps.md | 95 ++++++----------- docs/recovery/recovery-gap-analysis.md | 19 +++- glama.json | 2 +- llms.txt | 40 +++++-- mcp-server/README.md | 6 +- 13 files changed, 255 insertions(+), 233 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0f6d41d..c7376b2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,8 +13,9 @@ offloaded to a compute box (`cs run "pnpm test"`) or CI — do not run them loca ## Repo structure - `mcp-server/` — the `opencode-workbench` MCP server + connector (TypeScript). - Tools: `inspect_target`, `plan_clone`, `apply_clone`, `verify_clone`, - `install_component`, `bootstrap_host`, `workbench_info`. Local + SSH transports. + Tools: `workbench_info`, `inspect_target`, `plan_clone`, `apply_clone`, + `verify_clone`, `install_component`, `list_required_credentials`, + `run_auth_flow`, `bootstrap_host`. Local + SSH transports. See `mcp-server/README.md` and `docs/architecture/clone-mcp.md`. - `connector.json` — connector manifest / registration snippet. - `plugins/` — the `memory.ts` + `doc-tools.ts` OpenCode plugins (portable, @@ -58,7 +59,7 @@ bash scripts/recovery/validate-recovery.sh # verify workstation is in goo |---|---| | `DATABASE_URL` | `postgres://opencode:opencode@localhost:5432/memory` | | `BROWSERLESS_HOST/PORT/PROTOCOL` | `localhost:3000/http` | -| `DB_PATH` | `/workspaces/workbench/.saga/.tracker.db` | +| `DB_PATH` | `/workspaces/opencode-workbench/.saga/.tracker.db` | | `DEEPSEEK_API_KEY` | primary model: `deepseek/deepseek-v4-pro` | | `OPENCODE_API_KEY` | OpenCode Zen + Console Go providers | | `SIMONPLMAK_CLOUD_PAT` | GitHub MCP (binary) + shadcn MCP + `gh` auth | @@ -90,7 +91,7 @@ bash .devcontainer/start-browserless.sh `~/.local/bin/browserless-mcp/dist/index.js` (on the build box: `/home/node/.local/bin/`). - Model `deepseek/deepseek-v4-pro` (small: `deepseek/deepseek-v4-flash`); `default_agent` is `vdd` (the only subagent defined in `opencode.json`). -- 28 repo skills in `.opencode/skills/`; global skills live under +- 45 repo skills in `.opencode/skills/`; global skills live under `~/.config/opencode/skills/` (not this repo). - Plugins: `./plugins/memory.ts` + `./plugins/doc-tools.ts` (plus npm `opencode-env-protect`, `opencode-sentry-monitor`). diff --git a/README.md b/README.md index 2653fb6..361249e 100644 --- a/README.md +++ b/README.md @@ -107,7 +107,7 @@ opencode-workbench/ | Category | Details | |----------|---------| -| **OpenCode** | CLI v1.18.5, DeepSeek V4 Pro model, LSP enabled | +| **OpenCode** | Latest stable CLI, DeepSeek V4 Pro model, LSP enabled | | **MCP Servers** | 35 configured (33 enabled, 2 disabled), 9 remote + 26 local | | **Agent Skills** | 45 reusable skills in `.opencode/skills/` | | **Infrastructure** | PostgreSQL 16 (Docker), Browserless Chromium (Docker) | @@ -150,9 +150,9 @@ gh SWAS create --repo simonmak-ascent/opencode-workbench --machine basicLinux32g # 2. Wait for automation (3-5 min) -# 3. Two manual steps: -npx playwright install chrome -opencode mcp auth vercel # only if Vercel MCP needed +# 3. If needed (usually done by setup.sh): +npx playwright install chromium +# Vercel MCP uses VERCEL_ACCESS_TOKEN (token auth — no OAuth step) # 4. Validate recovery bash scripts/recovery/validate-recovery.sh @@ -178,13 +178,18 @@ All secrets stored in the build box Secrets. Never in repository files. | # | Secret | Used By | |---|--------|---------| | 1 | `DEEPSEEK_API_KEY` | OpenCode (primary model) | -| 2 | `SIMONPLMAK_CLOUD_PAT` | GitHub MCP, shadcn MCP | -| 3 | `PERPLEXITY_API_KEY` | Perplexity MCP | -| 4 | `BRAVE_API_KEY` | Brave Search MCP | -| 5 | `BROWSERLESS_TOKEN` | Browserless MCP + container | -| 6 | `FIGMA_TOKEN` | Figma MCP | +| 2 | `OPENCODE_API_KEY` | OpenCode Zen / Console Go providers | +| 3 | `SIMONPLMAK_CLOUD_PAT` | GitHub MCP, shadcn MCP, `gh` | +| 4 | `PERPLEXITY_API_KEY` | Perplexity MCP | +| 5 | `BRAVE_API_KEY` | Brave Search MCP | +| 6 | `BROWSERLESS_TOKEN` | Browserless MCP + container | | 7 | `SENTRY_AUTH_TOKEN` | Sentry MCP | -| 8 | `KIMI_API_KEY` | Alternate provider (legacy) | +| 8 | `VERCEL_ACCESS_TOKEN` | Vercel MCP (token auth) | + +Additional keys for opt-in servers (`EXA_API_KEY`, `CLOUDFLARE_API_TOKEN`, +`STRIPE_SECRET_KEY`, `SURREAL_*`, `ALIBABA_CLOUD_*`, `AZURE_*`, `FIRECRAWL_API_KEY`, +`FRED_API_KEY`, `COMPANIES_HOUSE_API_KEY`) are catalogued in +[`docs/architecture/secrets.md`](docs/architecture/secrets.md) — never by value. See: [`docs/architecture/secrets.md`](docs/architecture/secrets.md) @@ -209,7 +214,7 @@ See: [`docs/architecture/secrets.md`](docs/architecture/secrets.md) 4. **Prompt**: Create in `docs/prompts/`, update `prompt-index.md` 5. After any change: Update `CHANGELOG_WORKBENCH.md`, run master backup -## Recovery Score: 92/100 +## Recovery Score: 94/100 Validated disaster recovery within < 10 minutes using repository + build box Secrets alone. diff --git a/WORKFLOW_STATE.md b/WORKFLOW_STATE.md index 53352e6..faafbf5 100644 --- a/WORKFLOW_STATE.md +++ b/WORKFLOW_STATE.md @@ -1,76 +1,72 @@ # Workflow State -> Auto-generated and auto-updated. Read FIRST on every session start. -> Last updated: 2026-07-27T00:00:00Z +> Auto-updated. Read FIRST on every session start. +> Last updated: 2026-10-03 ## Current Status | Item | Status | |------|--------| -| Phase #0 — Verify Docs | **COMPLETED** 2026-07-27 | -| Phase #1 — Research | **COMPLETED** 2026-07-27 | -| Phase #2 — Architecture | **COMPLETED** 2026-07-27 | -| Phase #3 — Implementation | **IN PROGRESS** 2026-07-27 | +| Phase #0 — Verify Docs | **COMPLETED** | +| Phase #1 — Research | **COMPLETED** | +| Phase #2 — Architecture | **COMPLETED** | +| Phase #3 — Implementation | **COMPLETED** (clone MCP + bootstrap_host shipped) | +| VDD chain (Phase 0–8) | **COMPLETED** — `constitution.md` + `vdd/` (gates G1–G7 PASS) | +| Distribution | In progress — npm published; Vercel live; registry publish prepared | ## Last Checkpoint ``` -Phase: #3 — Implementation -Status: Infrastructure + config complete; app/MCP/scraper source pending -Timestamp: 2026-07-27 -Correlation ID: workflow-init-2026-07-27 +Phase: #3 — Implementation (complete) +Status: opencode-workbench v1.1.2 shipped; VDD chain complete; docs refreshed +Timestamp: 2026-10-03 ``` -## Track Status +## Tracks -### AI-Enabled Web App -| Step | Agent | Status | Output | -|------|-------|--------|--------| -| 1 | ResearchAgent | NOT STARTED | — | -| 2 | DesignAgent | NOT STARTED | — | -| 3 | PromptAgent | NOT STARTED | — | -| 4 | ConfigAgent | NOT STARTED | — | -| 5 | ToolingAgent | NOT STARTED | — | -| 6 | BuildAgent | NOT STARTED | — | -| 7 | TestAgent | NOT STARTED | — | -| 8 | DeployAgent | NOT STARTED | — | +### opencode-workbench (clone MCP) — DELIVERED +| Item | Status | Output | +|------|--------|--------| +| Clone engine (inspect/plan/apply/verify) | DONE | `mcp-server/src/clone.ts` | +| Consent gate + value-blind credentials | DONE | `apply_clone`/`install_component` `confirm:true`; `list_required_credentials`, `run_auth_flow` | +| One-call provisioning | DONE | `bootstrap_host` (platform scan + upgrade plan + OpenCode pin + verify + `help`) | +| Tests + CI | DONE | 49 tests; `mcp-server.yml` | -### MCP Server / Agent Skills -| Step | Agent | Status | Output | -|------|-------|--------|--------| -| 1 | SkillAuthorAgent | NOT STARTED | — | -| 2 | SkillValidatorAgent | NOT STARTED | — | -| 3 | SkillPublisherAgent | NOT STARTED | — | +### VDD chain — DELIVERED +| Phase | Artifact | +|-------|----------| +| 0 Init | `constitution.md` | +| 1 Vision | `vdd/vision.md` (V-001; I-001…I-007) | +| 2 Strategy | `vdd/strategy.md` (S-002) | +| 3 Tactics | `vdd/tactics.md` (T-003; A-001…A-011) | +| 4–6 Spec/Plan/Tasks | `vdd/specs/bootstrap-bare-host/`, `vdd/specs/mcp-quality-and-registry/` | +| 7 Implement | `mcp-server/src/{platform,bootstrap,version}.ts` | +| 8 Validate | `vdd/impact-report.generated.md`, `vdd/gates/G1–G7.md` | -### Web Scraper -| Step | Agent | Status | Output | -|------|-------|--------|--------| -| 1 | ScrapeConfigAgent | NOT STARTED | — | -| 2 | ScrapeExecutorAgent | NOT STARTED | — | -| 3 | ScrapeStorageAgent | NOT STARTED | — | -| 4 | ScrapeAlertAgent | NOT STARTED | — | +### Registry distribution +| Registry | Status | +|----------|--------| +| npm | ✅ `@simonmak-ascent/opencode-workbench@1.1.2` | +| Vercel (hosted connector) | ✅ live at `https://opencode-workbench.simonmak.com/mcp` | +| Official MCP Registry | manifest ready (`server.json`) + OIDC workflow | +| Glama | ✅ claim file live | +| Smithery / PulseMCP / mcp.so | prepared (`docs/publishing/registry-listing.md`) | ## Infrastructure Status -| Component | Status | Verified | -|-----------|--------|----------| -| Docker (pg-memory) | Running | 2026-07-27 | -| Docker (browserless) | Running | 2026-07-27 | -| MCP servers (18 enabled) | Connected | 2026-07-27 | -| SurrealDB | Not yet provisioned | — | -| Vercel project | Not yet created | — | -| Sentry project | Not yet created | — | +| Component | Status | +|-----------|--------| +| Docker (pg-memory, browserless) | Running (build box) | +| MCP servers | 35 configured, 33 enabled (2 disabled: `google-search`, `google-workspace`) | +| Vercel project | `opencode-workbench` (AP Team) — production live | +| npm package | `@simonmak-ascent/opencode-workbench@1.1.2` | ## Instructions ### On Session Start -1. Read this file FIRST -2. Check current phase and last checkpoint -3. Resume from the first incomplete agent -4. Update this file after each agent completion +1. Read this file FIRST. +2. Check phase/tracks above. +3. For repo facts, treat `opencode.json` and `package.json` as source of truth. -### On Agent Completion -Update the corresponding track status above and move to next checkpoint. - -### On Infrastructure Change -Update the Infrastructure Status table above. +### On Change +Update the relevant track and `docs/CHANGELOG_WORKBENCH.md`. diff --git a/connector.json b/connector.json index b69b19e..7a795ac 100644 --- a/connector.json +++ b/connector.json @@ -3,7 +3,7 @@ "name": "opencode-workbench", "title": "OpenCode Workbench", "description": "Clones the OpenCode workbench installation onto Linux machines, locally or over SSH.", - "version": "1.0.0", + "version": "1.1.2", "transport": { "type": "stdio", "command": "npx", diff --git a/context7.json b/context7.json index 6023d6f..c27d09b 100644 --- a/context7.json +++ b/context7.json @@ -1,7 +1,7 @@ { "$schema": "https://context7.com/schema/context7.json", "projectTitle": "OpenCode Workbench (opencode-workbench)", - "description": "Clones the OpenCode workbench onto Linux machines — locally or over SSH — reproducing the config, MCP servers, agent skills, plugins and Docker tooling. Exposes 6 tools over stdio.", + "description": "Provisions and clones the OpenCode workbench onto Linux machines — locally or over SSH — reproducing the config, MCP servers (35), agent skills (45), plugins and Docker tooling. Exposes 9 tools over stdio, including bootstrap_host for one-call provisioning.", "folders": [ "mcp-server", "docs", @@ -9,7 +9,8 @@ ], "rules": [ "Run locally with `npx -y @simonmak-ascent/opencode-workbench` (Node stdio MCP server; no API key).", - "Drive a clone with the tool order `workbench_info` → `inspect_target` → `plan_clone` → `apply_clone` → `verify_clone`; use `install_component` to install a single component by id.", + "Drive a clone with the tool order `workbench_info` → `inspect_target` → `plan_clone` → `apply_clone` → `verify_clone`; use `install_component` to install a single component by id, and `bootstrap_host` for a one-call end-to-end provision (platform scan + OpenCode + apply + verify; `help:true` documents parameters).", + "`apply_clone` and `install_component` are consent-gated: without `confirm:true` they return a plan and change nothing.", "Every tool takes a `target` of `{mode: \"local\"}` or `{mode: \"ssh\", host, user, port?, identityFile?}`.", "The connector never reads, transmits or writes secret values; `apply_clone` writes an empty `~/.env.workbench` template (mode 600) listing the `{env:VAR}` names to fill in.", "`apply_clone` is idempotent; pass `dryRun: true` to preview the plan without making changes." diff --git a/docs/architecture/clone-mcp.md b/docs/architecture/clone-mcp.md index 28bf322..a9de543 100644 --- a/docs/architecture/clone-mcp.md +++ b/docs/architecture/clone-mcp.md @@ -45,6 +45,7 @@ mcp-server/src/ | `verify_clone` | Re-check config, env template, and every component. | | `list_required_credentials` | Value-blind: which keys are missing and how to acquire each. | | `run_auth_flow` | Emit-and-verify acquisition guidance for one credential. | +| `bootstrap_host` | One-call provisioning: kernel-up platform scan + dry-run upgrade plan, latest-stable OpenCode with recorded version, apply + verify; `help:true` documents every parameter without touching the target. Consent-gated. | ### Connector model diff --git a/docs/architecture/opencode-runtime-config.md b/docs/architecture/opencode-runtime-config.md index 5192e23..846c8ec 100644 --- a/docs/architecture/opencode-runtime-config.md +++ b/docs/architecture/opencode-runtime-config.md @@ -1,63 +1,72 @@ # OpenCode Runtime Configuration -> Generated: 2026-07-27 -> Source: `~/.config/opencode/opencode.json` (synced from repo `opencode.json`) +> Updated: 2026-10-03 +> Source of truth: repo `opencode.json`, copied to `~/.config/opencode/opencode.json` +> on the build box. Counts below are derived from `opencode.json`. ## Active Configuration | Item | Value | |------|-------| | **Primary Model** | `deepseek/deepseek-v4-pro` | -| **Small Model** | `deepseek/deepseek-v4-pro` | +| **Small Model** | `deepseek/deepseek-v4-flash` | +| **Default agent** | `vdd` | | **LSP** | Enabled | | **Schema** | `https://opencode.ai/config.json` | ## Provider Configuration -### DeepSeek -- **API**: `https://api.deepseek.com/v1` -- **Key env**: `DEEPSEEK_API_KEY` -- **Source**: build box Secret - -## MCP Server Assignments (19 configured, 18 enabled, 1 disabled) - -### Remote MCPs (5) -| Server | URL | Auth Method | -|--------|-----|-------------| -| context7 | `https://mcp.context7.com/mcp` | None | -| gh_grep | `https://mcp.grep.app` | None | -| clerk | `https://mcp.clerk.com/mcp` | None | -| vercel | `https://mcp.vercel.com` | OAuth | - -### Local MCPs (14, 1 disabled) -| Server | Binary/Entry Point | Secrets | -|--------|-------------------|---------| -| github | `/home/node/.local/bin/github-mcp-server` | `SIMONPLMAK_CLOUD_PAT` | -| perplexity | `vendor/perplexity-agent-mcp/index.js` | `PERPLEXITY_API_KEY` | -| brave-search | `@modelcontextprotocol/server-brave-search` | `BRAVE_API_KEY` | -| postgres | `@modelcontextprotocol/server-postgres` | `DATABASE_URL` | -| browserless | `vendor/browserless-mcp/dist/index.js` | `BROWSERLESS_TOKEN` | -| playwright | `@playwright/mcp/cli.js` | None | -| figma | `figma-developer-mcp` | `FIGMA_TOKEN` (mapped to `FIGMA_API_KEY`) | -| mermaid | `mcp-mermaid` | None | -| saga | `saga-mcp` | `DB_PATH` | -| echarts | `mcp-echarts` | None | -| shadcn | `@jpisnice/shadcn-ui-mcp-server` | `SIMONPLMAK_CLOUD_PAT` | -| swagger-testcase | `swagger-testcase-mcp` | None | -| design-system | `mcp-design-system-extractor` | None (needs `STORYBOOK_URL`) | -| sentry | `@sentry/mcp-server` | `SENTRY_AUTH_TOKEN` | +- **DeepSeek** — `https://api.deepseek.com`, key `DEEPSEEK_API_KEY`. +- **OpenCode Zen / Console Go** — key `OPENCODE_API_KEY`. +- Additional optional providers are documented in + `docs/architecture/ai-provider-inventory.md`. + +## MCP Servers (35 configured · 33 enabled · 2 disabled) + +> Full per-server table (entry point + auth env) is the generated inventory: +> [`mcp-inventory.md`](./mcp-inventory.md). Disabled by default: `google-search`, +> `google-workspace`. Opt-in add-ons (dropped unless enabled): see +> `OPTIONAL_MCP_IDS` in `mcp-server/src/render.ts`. + +### Remote MCPs (9, all enabled) +| Server | URL | Auth | +|--------|-----|------| +| context7 | `https://mcp.context7.com/mcp` | none | +| gh_grep | `https://mcp.grep.app` | none | +| clerk | `https://mcp.clerk.com/mcp` | none | +| vdd | `https://vdd.simonmak.com/api/mcp` | none | +| exa | `https://mcp.exa.ai/mcp` | `EXA_API_KEY` | +| cloudflare | `https://mcp.cloudflare.com/mcp` | `CLOUDFLARE_API_TOKEN` | +| sentry | `https://mcp.sentry.dev/mcp` | `SENTRY_AUTH_TOKEN` | +| stripe | `https://mcp.stripe.com` | `STRIPE_SECRET_KEY` | +| vercel | `https://mcp.vercel.com` | `VERCEL_ACCESS_TOKEN` (token auth) | + +### Local MCPs (26: 24 enabled, 2 disabled) +Includes github (binary), perplexity + browserless (vendored), brave-search, +postgres, playwright, mermaid, echarts, shadcn, swagger-testcase, design-system, +saga, arxiv, paper-search, firecrawl, primary-sources, ms-365, alibaba-cloud-ops, +surrealdb, designlang, difflens, browser-mcp, esg-hub, humanity4ai; plus the two +disabled local servers `google-search` and `google-workspace`. + +> `figma` was removed from the profile (superseded by the v0 workflow). ## Recovery Method -1. Clone this repository -2. build box secrets auto-propagate via `devcontainer.json` `remoteEnv` -3. `.devcontainer/setup.sh` installs MCP servers and copies config -4. `opencode.json` is the single source of truth for MCP configuration -5. Runtime copy at `~/.config/opencode/opencode.json` is synced from repo +1. Clone this repository. +2. Build-box secrets propagate via `.devcontainer/devcontainer.json` `remoteEnv`. +3. `.devcontainer/setup.sh` installs the OpenCode CLI, npm/vendored MCP servers, + Playwright Chromium, and copies config. +4. `opencode.json` is the single source of truth; the runtime copy is synced from it. +5. Validate with `bash scripts/recovery/validate-recovery.sh`. -## Custom Skills +## Custom Skills (45 in `.opencode/skills/`) -28 custom agent skills defined in `.opencode/skills/` across three domains: -- **Research** (10): spec-writer, competitive-analysis, api-research, tech-stack-eval, codebase-explorer, dependency-audit, architecture-review, content-research, benchmark-research, security-audit -- **Development** (10): component-builder, api-builder, db-schema, auth-flow, responsive-design, state-management, test-writer, perf-optimizer, error-handling, cicd-setup -- **Publishing** (8): changelog-generator, release-manager, cloud-deploy, docker-builder, npm-publisher, docs-generator, semantic-release, post-deploy-monitor +Ported skill families include: research (spec-writer, competitive-analysis, +api-research, tech-stack-eval, codebase-explorer, dependency-audit, +architecture-review, content-research, benchmark-research, security-audit, +web-research); development (component-builder, api-builder, db-schema, auth-flow, +responsive-design, state-management, test-writer, perf-optimizer, error-handling, +cicd-setup); publishing (changelog-generator, release-manager, cloud-deploy, +docker-builder, npm-publisher, docs-generator, semantic-release, +post-deploy-monitor); plus VDD/spec-driven, data/analysis, scientific-computing, +frontend-design, browser-automation, accessibility and workbench-compute. diff --git a/docs/architecture/opencode-runtime-snapshot.md b/docs/architecture/opencode-runtime-snapshot.md index 0d78075..6bc3c5f 100644 --- a/docs/architecture/opencode-runtime-snapshot.md +++ b/docs/architecture/opencode-runtime-snapshot.md @@ -1,54 +1,65 @@ # OpenCode Runtime Snapshot -> Captured: 2026-07-27 -> Purpose: Preserve behavioural configuration at this point in time +> Captured: 2026-10-03 +> Purpose: behavioural configuration at this point in time. Counts derive from +> `opencode.json`; live per-server health is not asserted here. ## Active Profile | Setting | Value | |---------|-------| | **Model** | `deepseek/deepseek-v4-pro` | -| **Small Model** | `deepseek/deepseek-v4-pro` | +| **Small Model** | `deepseek/deepseek-v4-flash` | +| **Default agent** | `vdd` | | **Reasoning** | Enabled (via model capability) | | **LSP** | Enabled | -| **Formatters** | Not explicitly configured (default: disabled) | - -## MCP Servers — Runtime Status - -| Server | Status | Notes | -|--------|--------|-------| -| context7 | ✅ Active | Remote, docs lookup | -| gh_grep | ✅ Active | Remote, GitHub code search | -| clerk | ✅ Active | Remote, SDK snippets | -| vercel | ⚠️ Active but unauth | OAuth not completed | -| github | ✅ Active | Local, PAT auth | -| perplexity | ❌ Failed (401) | Invalid API key format | -| brave-search | ✅ Active | Local, API key auth | -| postgres | ✅ Active | Local, `memory` database | -| browserless | ✅ Active | Local, Docker container | -| playwright | ✅ Active | Local, Chromium installed | -| figma | ⚠️ Needs restart | Config fixed, old connection closed | -| mermaid | ✅ Active | Local, diagram generation | -| saga | ❌ Disabled | In config but `enabled: false` | -| echarts | ✅ Active | Local, chart generation | -| shadcn | ✅ Active | Local, PAT auth | -| swagger-testcase | ✅ Active | Local, spec parsing | -| design-system | ✅ Active (no Storybook) | Defaults to localhost:6006 | -| sentry | ✅ Active | Local, token auth | +| **Formatters** | Not explicitly configured (default) | + +## MCP Servers — Configuration Status + +| Group | Count | Status | +|-------|-------|--------| +| Remote | 9 | enabled | +| Local | 26 | 24 enabled, 2 disabled | +| **Total** | **35** | **33 enabled** | + +Disabled by default: `google-search`, `google-workspace`. + +Notes: +- `vercel` authenticates with `VERCEL_ACCESS_TOKEN` (token auth — no OAuth step). +- `sentry`, `stripe`, `cloudflare`, `exa` are remote and gated by their API keys. +- `figma` removed (v0 supersedes it). +- Opt-in add-ons (esg-hub, humanity4ai, saga, surrealdb, ms-365, stripe, + alibaba-cloud-ops, designlang, difflens, google-*) are dropped from a portable + clone unless explicitly enabled. + +## MCP Tool Surface + +The server exposes **9 tools**: `workbench_info`, `inspect_target`, `plan_clone`, +`apply_clone`, `verify_clone`, `install_component`, `list_required_credentials`, +`run_auth_flow`, `bootstrap_host`. ## Agent Configuration -- **Type**: Default (no custom agents defined) -- **Permission**: Default (no custom permission rules) -- **Skills**: 28 custom skills loaded from `.opencode/skills/` -- **Built-in skill**: `customize-opencode` for OpenCode self-configuration +- **Default agent**: `vdd` (defined in `opencode.json`). +- **Skills**: 45 in `.opencode/skills/`. +- **Plugins**: `plugins/memory.ts`, `plugins/doc-tools.ts` (+ npm + `opencode-env-protect`, `opencode-sentry-monitor`). + +## Shell Environment (build box) + +- **Shell**: bash +- **OpenCode binary**: `~/.opencode/bin/opencode` +- **Node**: 22 (devcontainer image) +- **npm global prefix**: `~/.npm-global` -## Shell Environment +## Deployment -- **Shell**: bash (via the build box) -- **OpenCode binary**: `/home/node/.opencode/bin/opencode` -- **Node version**: 22 (via devcontainer image) -- **npm global prefix**: `/home/node/.npm-global` +| Target | Where | +|--------|-------| +| npm | `@simonmak-ascent/opencode-workbench@1.1.2` | +| Hosted (Streamable HTTP) | `https://opencode-workbench.simonmak.com/mcp` | +| Vercel project | `opencode-workbench` (team AP Team) | ## External Repos in Home diff --git a/docs/audit/documentation-gaps.md b/docs/audit/documentation-gaps.md index 9b6ac38..267ccae 100644 --- a/docs/audit/documentation-gaps.md +++ b/docs/audit/documentation-gaps.md @@ -1,82 +1,47 @@ # Documentation Gaps -> Phase: #0D | Created: 2026-07-27 -> Tracks all gaps between required documentation and current state. +> Updated: 2026-10-03 +> Tracks the delta between required documentation and current state. ## Gap Severity | Level | Meaning | |-------|---------| -| **Critical** | Blocks workflow progression; must resolve now | -| **High** | Needed for next phase; resolve before phase start | -| **Medium** | Should resolve within current phase | +| **Critical** | Blocks workflow progression | +| **High** | Needed before next phase | +| **Medium** | Resolve within current phase | | **Low** | Nice to have; can defer | -## Current Gaps +## Current State -### Phase #0 Gaps (This Phase) +All Phase #0–#3 documentation gaps are **resolved**; the register is maintained +for drift going forward. -| # | Gap | Severity | Status | -|---|-----|----------|--------| -| 1 | `docs/audit/document-inventory.md` | Critical | ✅ Resolved | -| 2 | `docs/audit/documentation-quality-checklist.md` | Critical | ✅ Resolved | -| 3 | `docs/audit/documentation-review-log.md` | Critical | ✅ Resolved | -| 4 | `docs/audit/documentation-gaps.md` | Critical | ✅ Resolved (this file) | -| 5 | `docs/audit/DOCS_QUALITY_APPROVED.flag` | Critical | 🔲 Pending — write after all Phase #0 docs pass | +### Resolved -### Phase #1 Gaps (Research) +| # | Item | Status | +|---|------|--------| +| 1–4 | `docs/audit/*` inventory / checklist / review-log / gaps | ✅ present | +| 5 | `docs/audit/DOCS_QUALITY_APPROVED.flag` | ✅ present | +| 6–10 | `docs/research/*` (best-practices, tooling) | ✅ present | +| 11–31 | `docs/architecture/*`, `docs/config/*`, `docs/design/*` | ✅ present | +| 32 | `docs/tools/*` | ✅ present | +| 33 | `WORKFLOW_STATE.md` | ✅ refreshed 2026-10-03 | +| 35–37 | Duplicate/stale runtime docs | ✅ consolidated: `docs/architecture/opencode-runtime-config.md` is canonical; `docs/opencode-runtime-config.md` left only as needed | +| — | VDD chain (`constitution.md`, `vdd/**`) | ✅ added 2026-10-03 | +| — | `docs/publishing/registry-listing.md`, `server.json` | ✅ added 2026-10-03 | -| # | Gap | Severity | Status | -|---|-----|----------|--------| -| 6 | `docs/research/` directory | High | 🔲 Create in Phase #1 | -| 7 | `docs/research/01-ai-web-app-best-practices.md` | High | 🔲 Research in Phase #1 | -| 8 | `docs/research/02-mcp-agent-skills-best-practices.md` | High | 🔲 Research in Phase #1 | -| 9 | `docs/research/03-web-scraper-best-practices.md` | High | 🔲 Research in Phase #1 | -| 10 | `docs/research/04-free-tooling-options.md` | High | 🔲 Research in Phase #1 | +### Open (Low) -### Phase #2 Gaps (Architecture) - -| # | Gap | Severity | Status | -|---|-----|----------|--------| -| 11 | `docs/architecture/agents/` directory | Medium | 🔲 Create in Phase #2 | -| 12 | `docs/architecture/workflow-dag.md` | Medium | 🔲 Create in Phase #2 | -| 13 | `docs/architecture/workflow-dag.mermaid` | Medium | 🔲 Create in Phase #2 | -| 14 | `docs/architecture/agent-responsibilities.md` | Medium | 🔲 Create in Phase #2 | -| 15 | `docs/architecture/orchestration-rules.md` | Medium | 🔲 Create in Phase #2 | -| 16 | `docs/architecture/restart-recovery.md` | Medium | 🔲 Create in Phase #2 | -| 17 | `docs/architecture/tooling-decision-log.md` | Medium | 🔲 Create in Phase #2 | -| 18 | `docs/prompts/system-prompt.md` | Medium | 🔲 Create in Phase #2 | -| 19 | `docs/prompts/agent-prompts/` directory | Medium | 🔲 Create in Phase #2 | -| 20 | `docs/prompts/task-templates/` directory | Medium | 🔲 Create in Phase #2 | -| 21 | `docs/config/` directory | Medium | 🔲 Create in Phase #2 | -| 22-26 | Config docs (5 files) | Medium | 🔲 Create in Phase #2 | -| 27 | `docs/design/` directory | Medium | 🔲 Create in Phase #2 | -| 28-31 | Design docs (4 files) | Medium | 🔲 Create in Phase #2 | - -### Phase #3 Gaps (Implementation) - -| # | Gap | Severity | Status | -|---|-----|----------|--------| -| 32 | `docs/tools/` directory | Medium | 🔲 Create in Phase #3 | -| 33 | `WORKFLOW_STATE.md` | Medium | 🔲 Create in Phase #3 | -| 34 | `.opencode/SYSTEM_PROMPT.md` | Medium | 🔲 Create in Phase #3 | - -### Existing Doc Gaps (Low Priority) - -| # | Gap | Severity | Status | -|---|-----|----------|--------| -| 35 | `docs/opencode-runtime-config.md` — may be stale vs current `opencode.json` | Low | 🔲 Resync | -| 36 | `docs/security-audit-report.md` — draft, needs fresh scan | Low | 🔲 Rerun scan | -| 37 | Duplicate docs at `docs/opencode-runtime-config.md` and `docs/architecture/opencode-runtime-config.md` | Low | 🔲 Consolidate | -| 38 | No TODO-only sections found in any doc | — | ✅ Verified | -| 39 | No ambiguous placeholders like "fill later", "TBD", "coming soon" | — | ✅ Verified | -| 40 | All file paths in docs match repo structure | — | ✅ Verified | +| # | Item | Severity | Status | +|---|------|----------|--------| +| 34 | `.opencode/SYSTEM_PROMPT.md` | Low | Deferred — covered by `AGENTS.md` + `docs/prompts/system-prompt.md`; no separate file required unless the workflow demands it | +| 36 | `docs/security-audit-report.md` freshness | Low | Refresh on the next security sprint | +| 41 | `docs/architecture/mcp-inventory.md` is generated (may lag edits) | Low | Regenerate via `scripts/inventory/inventory-mcp.sh` when `opencode.json` changes | ## Summary -- **Critical gaps**: 5 (all Phase #0, 4 resolved, 1 pending flag) -- **High gaps**: 5 (Phase #1 research docs — expected, created in Phase #1) -- **Medium gaps**: 24 (Phase #2 architecture + Phase #3 implementation — expected) -- **Low gaps**: 3 (stale snapshots — non-blocking) - -**Status**: Ready to proceed to Phase #1 after writing `DOCS_QUALITY_APPROVED.flag`. +- **Critical gaps:** 0 · **High:** 0 · **Medium:** 0 +- **Low (open):** 3 (non-blocking) +- **Status:** documentation is complete for the current release; CI enforces + required-doc presence and config/doc count parity. diff --git a/docs/recovery/recovery-gap-analysis.md b/docs/recovery/recovery-gap-analysis.md index 0697dc7..23dfad9 100644 --- a/docs/recovery/recovery-gap-analysis.md +++ b/docs/recovery/recovery-gap-analysis.md @@ -14,7 +14,7 @@ | 5 | setup.sh copies opencode.json | ✅ Pass | Copies to ~/.config/opencode/ | | 6 | setup.sh clones external repos | ✅ Pass | esg-hub, project_human | | 7 | All env vars declared in remoteEnv | ✅ Pass | 17 explicit entries (DB_PATH unreliable at runtime — see I13) | -| 8 | OpenCode skills tracked in repo | ✅ Pass | 28 skills in .opencode/skills/ | +| 8 | OpenCode skills tracked in repo | ✅ Pass | 45 skills in .opencode/skills/ | | 9 | MCP versions documented | ✅ Pass | docs/architecture/mcp-inventory.md | | 10 | AI provider configuration documented | ✅ Pass | docs/architecture/ai-provider-inventory.md | | 11 | Runtime config snapshot preserved | ✅ Pass | docs/architecture/opencode-runtime-snapshot.md | @@ -37,7 +37,7 @@ | Postgres data ephemeral | Low | Acceptable for dev environment | | Storybook URL not configured | Low | Design-system MCP needs `STORYBOOK_URL` env var | | Machine type not in recovery doc | Low | Now documented: `basicLinux32gb` recommended | -| Saga MCP disabled intentionally | Low | `enabled: false` in opencode.json; re-enable after DB_PATH verification | +| Saga MCP enabled | — | `DB_PATH` set; saga-mcp creates the DB on first use | | Vercel OAuth still in DISASTER_RECOVERY.md | Low | Actually uses token auth now — doc drift, fix below | | Perplexity key prefix mismatch (pplx-) | Medium | Key regenerated in GitHub secrets — rebuild needed to propagate | | DB_PATH unreliable at runtime | Medium | Declared in remoteEnv but not always picked up; needs investigation | @@ -60,3 +60,18 @@ - **Automation**: 96 — setup.sh covers all entry points; 17/17 remoteEnv vars; no manual formatter/plugin steps - **Secret Management**: 93 — All critical secrets declared; 1 stale key in history; Perplexity rotation pending rebuild - **Plugin/Fmt Recoverability**: 96 — No plugins to resolve; eslint from devcontainer image; zero manual setup + +## 2026-10-03 refresh + +- MCP servers: **35 configured / 33 enabled** (2 disabled: `google-search`, + `google-workspace`); `figma` removed. +- Agent skills: **45** (was 28). +- Clone MCP hardened and extended: consent gate (`confirm:true` on + `apply_clone`/`install_component`), value-blind credential tools + (`list_required_credentials`, `run_auth_flow`), and `bootstrap_host` (one-call + provisioning with a kernel-up scan and a recorded OpenCode version pin). +- Distribution: npm `@simonmak-ascent/opencode-workbench@1.1.2` published; hosted + connector live at `https://opencode-workbench.simonmak.com/mcp`; `server.json` + + GitHub-OIDC registry-publish workflow added. +- Recovery assets re-validated: `setup.sh` + the component model cover the + required/core set; score held at **94/100**. diff --git a/glama.json b/glama.json index 2814868..130603a 100644 --- a/glama.json +++ b/glama.json @@ -2,7 +2,7 @@ "$schema": "https://glama.ai/mcp/schemas/server.json", "maintainers": ["simonmak-ascent"], "name": "opencode-workbench", - "description": "One-command reproducibility for your AI-agent workstation. Six tools let an agent inspect, plan, apply, and verify an idempotent clone of the full OpenCode stack — the OpenCode CLI, 29 MCP servers, agent skills, plugins, and Docker infrastructure — onto any Linux machine, over SSH or locally, with zero secrets ever written.", + "description": "One-command reproducibility for your AI-agent workstation. Nine tools let an agent inspect, plan, apply, and verify an idempotent, consent-gated clone of the full OpenCode stack — the OpenCode CLI, 35 MCP servers, agent skills, plugins, and Docker infrastructure — onto any Linux machine, over SSH or locally, with zero secrets ever written. bootstrap_host does it end-to-end, including a kernel-up platform scan and a recorded OpenCode version pin.", "repository": "https://github.com/simonmak-ascent/opencode-workbench", "license": "MIT", "runtime": "node", diff --git a/llms.txt b/llms.txt index 868fe86..cac4335 100644 --- a/llms.txt +++ b/llms.txt @@ -1,21 +1,29 @@ # OpenCode Workbench (opencode-workbench) -> Open-source (MIT) MCP server + connector that clones the OpenCode workbench installation onto Linux machines — locally or over SSH — reproducing the same OpenCode config, MCP servers, agent skills, plugins, and Docker tooling. Works with Claude Code, Cursor, OpenCode, VS Code and other MCP clients. +> Open-source (MIT) MCP server + connector that provisions and clones the OpenCode +> workbench onto Linux machines — locally or over SSH. Nine tools cover a +> kernel-up platform scan, a one-call bootstrap, an idempotent, consent-gated +> clone, and value-blind credential guidance. No secret values are ever read, +> transmitted, or written. ## Connect -- Local stdio server (no API key): `npx -y github:simonmak-ascent/opencode-workbench` -- Glama listing: https://glama.ai/mcp/servers/simonmak-ascent/opencode-workbench +- Local stdio server: `npx -y @simonmak-ascent/opencode-workbench` +- Hosted (Streamable HTTP): `https://opencode-workbench.simonmak.com/mcp` +- Glama: https://glama.ai/mcp/servers/simonmak-ascent/opencode-workbench - Context7 library ID: `/simonmak-ascent/opencode-workbench` -## MCP tools (6) +## MCP tools (9) -- `workbench_info`: describe this server — repo, components by tier, optional MCP add-ons -- `inspect_target`: probe a machine — OS, arch, package manager, Node, Docker, OpenCode, home and npm-global paths -- `plan_clone`: diff the target against the profile → install / present / manual steps -- `apply_clone`: clone the profile + install missing components + write rendered config (idempotent) -- `verify_clone`: re-check config, env template, and every component's detection -- `install_component`: install a single component by id (e.g. `node`, `opencode`, `npm-mcps`, `skills`) +- `workbench_info` — describe this server: repo, components by tier, optional MCP add-ons +- `inspect_target` — probe a machine: OS, arch, package manager, Node, Docker, OpenCode, home and npm-global paths +- `plan_clone` — diff the target against the profile → install / present / manual steps (with command previews) +- `apply_clone` — consent-gated: without `confirm:true` returns the plan; with it, clones + installs the profile (idempotent) +- `verify_clone` — re-check config, env template, and every component's detection +- `install_component` — install a single component by id (also `confirm`-gated) +- `list_required_credentials` — value-blind: which credentials are missing and how to acquire each +- `run_auth_flow` — emit-and-verify acquisition guidance for one credential +- `bootstrap_host` — one-call provisioning: kernel-up platform scan + dry-run upgrade plan, latest-stable OpenCode with recorded version, apply + verify; `help:true` documents every parameter without touching the target Every tool takes a `target`: @@ -23,10 +31,20 @@ Every tool takes a `target`: { "target": { "mode": "ssh", "host": "", "user": "", "identityFile": "~/.ssh/id_ed25519" } } ``` -`apply_clone` options: `components[]`, `workspace`, `profileUrl`, `skipRepo`, `dryRun`. +`apply_clone` options: `components[]`, `workspace`, `profileUrl`, `skipRepo`, `dryRun`, `confirm`. +`bootstrap_host` options: `help`, `confirm`, `upgrade`, `assumeYes`, `opencodeVersion`, `dryRun`. ## Docs - [README and quick start](https://github.com/simonmak-ascent/opencode-workbench#readme) - [MCP server README](https://github.com/simonmak-ascent/opencode-workbench/tree/main/mcp-server) - [Clone architecture](https://github.com/simonmak-ascent/opencode-workbench/blob/main/docs/architecture/clone-mcp.md) +- [Registry listing runbook](https://github.com/simonmak-ascent/opencode-workbench/blob/main/docs/publishing/registry-listing.md) +- [VDD vision](https://github.com/simonmak-ascent/opencode-workbench/blob/main/vdd/vision.md) +- [Constitution](https://github.com/simonmak-ascent/opencode-workbench/blob/main/constitution.md) + +## Quality + +- Tool descriptions target the Tool Definition Quality Score (TDQS); `mcp-tdqs lint` reports 0 errors. +- CI: `mcp-server.yml` (build/typecheck/test), `secret-scan.yml` (gitleaks), + `validate-docs.yml`, `validate-inventory.yml` (config/doc parity). diff --git a/mcp-server/README.md b/mcp-server/README.md index 54568ef..6a190f0 100644 --- a/mcp-server/README.md +++ b/mcp-server/README.md @@ -58,9 +58,9 @@ Every tool takes a `target`: - **core** — `pnpm`, `uv`, `gh`, `npm-mcps`, `vendored-mcps`, `research-mcps`, `skills`, `plugins`, `playwright-browsers` - **optional** — `github-mcp`, `docker`, `docker-containers`, `data-tools`, `scientific`, `db-clients` -Add-ons (esg-hub, humanity4ai, vdd, saga, stripe, alibaba, ms-365, google-workspace, -surrealdb, designlang, difflens) are omitted from the rendered config unless you pass -`enabledMcp`/run with the full profile. +Add-ons (esg-hub, humanity4ai, saga, surrealdb, google-workspace, google-search, +ms-365, stripe, alibaba-cloud-ops, designlang, difflens) are omitted from the rendered +config unless you pass `enabledMcp`/run with the full profile. ## Security