diff --git a/docs/brainstorms/2026-03-21-setup-dependency-management-requirements.md b/docs/brainstorms/2026-03-21-setup-dependency-management-requirements.md new file mode 100644 index 000000000..c0fbae8cb --- /dev/null +++ b/docs/brainstorms/2026-03-21-setup-dependency-management-requirements.md @@ -0,0 +1,109 @@ +--- +date: 2026-03-22 +topic: setup-dependency-management +--- + +# Setup Skill: Dependency & Environment Management + +## Problem Frame + +The `/setup` skill currently only configures which review agents to enable per project stack. Users of the compound-engineering plugin depend on multiple external CLIs (agent-browser, gh, rtk, rclone), MCP servers (context7), and environment variables (CONTEXT7_API_KEY, GEMINI_API_KEY) -- but there is no unified way to detect what's installed, what's missing, or help users get set up. Users discover missing dependencies only when a skill fails at runtime. + +The plugin supports multiple agent platforms (Claude Code, Codex, Gemini CLI, OpenCode). Setup must work across platforms with tailored behavior for Claude Code and Codex (dominant usage), and reasonable fallbacks for others. + +## Requirements + +### /ce:doctor -- Standalone Diagnostic Skill + +- R1. Create a `/ce:doctor` skill that reads the centralized dependency registry and reports the health of the user's environment +- R2. ce-doctor checks: + - CLI dependency status (installed/missing) via registry check commands + - MCP server availability for deps that have an MCP variant + - Environment variable status (set/unset) for registry-listed env vars + - Plugin version currency (is the installed compound-engineering version the latest?) + - `.gitignore` includes `.context` (scratch space should not be committed) +- R3. ce-doctor is informational only -- it reports status and provides guidance links, never installs anything +- R4. For items that cannot be auto-installed (e.g. Figma MCP, Xcode), ce-doctor reports status as an FYI with a link to setup docs, not as an error + +### Dependency Registry + +- R5. Create a centralized dependency registry file listing all known dependencies. Each entry includes: + - Name and description + - `check_mcp` (optional) -- detect if an MCP server is loaded in the current session + - `check_cli` (optional) -- universal CLI detection command (e.g. `which gh`, `ctx7 --version`). Absent for MCP-only deps + - `install_command` (optional) -- how to install. Absent for detect-only deps + - `project_url` -- fallback link / setup docs + - Which skills/agents use it + - Tier: recommended vs optional + - Related env vars (if any) +- R6. The registry must be easily extensible -- adding a new dependency requires only adding an entry to the registry file, not modifying setup or doctor logic + +### /setup -- Extended with Dependency Phase + +- R7. Extend `/setup` with a new "Dependencies & Environment" phase that runs alongside the existing review-agent configuration phase +- R8. /setup runs ce-doctor first to print a summary status table (installed/missing for each dep and env var). This is informational only -- no install actions yet +- R9. After the summary, present only the missing installable dependencies in two tiers via interactive multi-select: + - **Recommended** (pre-selected): agent-browser, gh, jq + - **Optional** (opt-in): rtk, rclone, Gemini API setup, and any future additions +- R10. For selected missing dependencies, offer install commands one at a time with user approval. Verify installation after each. If install fails, show the project page URL as fallback +- R11. Prompt for related env vars per-dependency immediately after each successful install (e.g. prompt for CONTEXT7_API_KEY right after installing ctx7). Skip env var prompts for deps that have none. After all installs, prompt for any remaining env vars not tied to a specific dependency +- R12. For dependencies with both MCP and CLI variants (e.g. context7), detect MCP availability first, then check CLI as fallback, then offer CLI install if neither is present +- R13. On each run, scan fresh -- no persisted state, since deps can be uninstalled between sessions + +### Multi-Platform + +- R14. Focus platform-specific behavior on Claude Code and Codex (e.g. MCP detection, settings.json configuration). Other platforms get CLI-based detection and install commands only -- no platform-specific MCP or settings configuration + +## Success Criteria + +- A new user running `/setup` can go from zero to fully configured in one session +- Re-running `/setup` or `/ce:doctor` always re-scans and surfaces anything newly missing or newly available +- Adding a new CLI or env var dependency requires only a registry entry, not code changes to setup or doctor +- Context7 detection works regardless of whether the user has the MCP server or the CLI installed +- `/ce:doctor` can be run independently to troubleshoot environment issues + +## Scope Boundaries + +- Does not auto-install without user approval (each install command requires confirmation) +- Does not persist installation state -- always scans fresh since deps can be uninstalled +- Does not handle project-specific dependencies (e.g. `bundle install`, `npm install`) -- only plugin-level tools +- Does not configure MCP servers that require complex auth flows (e.g. Figma) -- just detects and reports their status with guidance +- Does not replace the existing review-agent configuration phase -- extends alongside it +- Does not attempt exhaustive platform-specific tailoring beyond Claude Code and Codex +- ce-doctor does not check git config, shell environment, or Claude Code permissions -- just deps, env vars, plugin version, and .gitignore + +## Key Decisions + +- **ce-doctor as separate skill**: Reusable standalone diagnostic (like `brew doctor`, `flutter doctor`). /setup invokes it but it's also useful for troubleshooting independently +- **Extend /setup rather than replace**: One unified onboarding experience; the new phase is additive to the existing review-agent configuration +- **Centralized registry over frontmatter scanning**: Simpler to maintain, explicit install commands, and includes project page URLs. Skills don't need frontmatter changes +- **Two-tier categorization**: Recommended (pre-selected) vs Optional (opt-in) is clearer than capability-based grouping +- **Always fresh scan**: Dependencies can be uninstalled between sessions, so persisted state would go stale. Re-scanning is cheap +- **Project page URL in registry**: Fallback for when install commands fail or don't work on the user's platform. Also serves as guidance for detect-only deps +- **Detect + offer install (not auto-install)**: Respects user control while reducing friction vs instruction-only +- **MCP-first, CLI-fallback for dual-mode deps**: For context7, check MCP availability first (platform-agnostic), then CLI (`which ctx7`). If neither, offer CLI install since it's universal across agent platforms +- **Claude Code + Codex focus**: These dominate usage. Other platforms get universal CLI checks and installs but no platform-specific MCP configuration +- **Detect-only category**: Some deps (Figma MCP, Xcode) can't be auto-installed. Registry supports entries with no install_command that are reported as FYI/guidance, not errors + +## Dependencies / Assumptions + +- The existing `/setup` skill's review-agent phase remains unchanged; the new phase is additive +- Install commands may vary by platform (macOS vs Linux); registry should support platform-specific install commands or at minimum document the primary install method with project page fallback +- The platform's blocking question tool is available for the selection UI (`AskUserQuestion` in Claude Code, equivalents in other platforms, text fallback otherwise) + +## Outstanding Questions + +### Deferred to Planning + +- [Affects R5][Technical] What format should the registry file use -- YAML, JSON, or markdown table? Consider what's easiest to maintain and parse in a skill context +- [Affects R5][Technical] How should platform-specific install commands be handled in the registry (e.g. `brew` vs `apt` vs `npm`)? +- [Affects R7][Technical] What should the phase ordering be -- dependencies first then review agents, or review agents first then dependencies? +- [Affects R11][Technical] How should env var values be securely prompted and where should they be persisted (e.g. shell profile, .env, Claude settings)? +- [Affects R5][Needs research] Inventory all current dependencies across skills/agents to populate the initial registry -- the explore agent captured a good starting list but it should be validated against current code +- [Affects R12][Needs research] How to reliably detect if an MCP server is loaded in the current session across platforms -- can we attempt a tool call, or is there an introspection API? +- [Affects R12][Technical] Should context7 CLI installation use `npx ctx7 setup` (interactive) or `npm install -g ctx7` (non-interactive)? +- [Affects R2][Technical] How to check plugin version currency -- is there a marketplace API or `claude plugin` CLI command to query the latest version? + +## Next Steps + +-> `/ce:plan` for structured implementation planning diff --git a/docs/plans/2026-03-22-001-feat-setup-dependency-management-beta-plan.md b/docs/plans/2026-03-22-001-feat-setup-dependency-management-beta-plan.md new file mode 100644 index 000000000..695962966 --- /dev/null +++ b/docs/plans/2026-03-22-001-feat-setup-dependency-management-beta-plan.md @@ -0,0 +1,269 @@ +--- +title: "feat: Add dependency management to /setup and create /ce:doctor diagnostic skill" +type: feat +status: completed +date: 2026-03-22 +origin: docs/brainstorms/2026-03-21-setup-dependency-management-requirements.md +--- + +# Add Dependency Management to /setup and Create /ce:doctor + +## Overview + +Extend the `/setup` skill with a dependency and environment phase, create a new `/ce:doctor` diagnostic skill, and introduce a centralized dependency registry that both skills share. Users get a unified onboarding experience that detects missing CLIs, MCP servers, and env vars, then offers guided installation. + +## Problem Frame + +Users discover missing dependencies (agent-browser, gh, context7, API keys) only when a skill fails at runtime. There is no unified way to check environment health or help users install what they need. The plugin supports multiple agent platforms, so the solution must be cross-platform. (see origin: docs/brainstorms/2026-03-21-setup-dependency-management-requirements.md) + +## Requirements Trace + +- R1. `/ce:doctor` skill reads registry and reports environment health +- R2. Doctor checks: CLI deps, MCP availability, env vars, plugin version, .gitignore +- R3. Doctor is informational only — no installs +- R4. Detect-only items reported as FYI with guidance links, not errors +- R5. Centralized dependency registry with structured metadata +- R6. Registry extensibility — add entry, not code changes +- R7. `/setup` extended with dependency phase +- R8. /setup invokes ce-doctor to show diagnostic summary, then continues with install flow +- R9. Missing deps presented in recommended/optional tiers +- R10. Per-dep install with user approval and verification +- R11. Per-dep env var prompting after install +- R12. MCP-first, CLI-fallback for dual-mode deps (context7) +- R13. Always scan fresh +- R14. Claude Code + Codex focus, CLI-only for other platforms + +## Scope Boundaries + +- No auto-install without user approval +- No persisted state — always fresh scan +- No project-specific deps (bundle install, npm install) +- No complex MCP auth flows (Figma) — detect-only +- Existing review-agent phase unchanged +- No platform-specific tailoring beyond Claude Code and Codex + +## Context & Research + +### Relevant Code and Patterns + +- `plugins/compound-engineering/skills/setup/SKILL.md` — current setup skill, 5-step flow: check existing config → detect stack → customize → write local.md → confirm +- `plugins/compound-engineering/skills/rclone/scripts/check_setup.sh` — existing dependency check pattern using `command -v`, version checks, structured output +- `plugins/compound-engineering/skills/ce-review/SKILL.md` (line 67) — pattern for "invoke the `setup` skill" semantic reference +- Cross-platform question tool pattern used in existing setup: `AskUserQuestion` / `request_user_input` / `ask_user` +- `compound-engineering.local.md` — existing config output pattern (YAML frontmatter + markdown body) + +### Institutional Learnings + +- **Script-first architecture** (`docs/solutions/skill-design/script-first-skill-architecture.md`): For v1, the registry is small (~10 CLI deps, ~5 env vars). Agent-iterates approach has modest token overhead and keeps the registry as the single source of truth (R6). A bundled check script can be added later if performance warrants it. +- **Cross-platform skill design** (`docs/solutions/skill-design/compound-refresh-skill-improvements.md`): Must use capability-class tool references, platform-agnostic question tools, relative script paths. No `${CLAUDE_PLUGIN_ROOT}`. +- **Beta skills framework** (`docs/solutions/skill-design/beta-skills-framework.md`): ce-doctor is net new (not replacing anything), so beta framework is not needed. +- **Codex skill entrypoints** (`docs/solutions/codex-skill-prompt-entrypoints.md`): Directory name `ce-doctor/` will map to `ce-doctor` in Codex. Use semantic wording for cross-skill references. +- **Plugin compliance checklist** (`plugins/compound-engineering/AGENTS.md`): Skills need proper YAML frontmatter, markdown links to references/scripts, imperative writing style, cross-platform tool references. + +## Key Technical Decisions + +- **Registry as markdown reference file**: Human-readable, agent-readable, no parser needed. The agent reads it and runs check commands individually. Adding a dep means adding a section — R6 satisfied. (Alternative: YAML + bash parser, rejected for complexity; JSON + jq, rejected because jq is itself a dependency being checked.) +- **Agent-iterates over script-first for v1**: The check set is small (~15 total checks). Token overhead of running individual `command -v` calls is modest (~200 tokens total output). Script can be added later per script-first architecture guidance. This avoids dual-maintenance of registry + script. +- **Registry lives in ce-doctor's references/**: `/setup` invokes ce-doctor for the diagnostic phase, then continues with its own install flow. This follows the established pattern where skills invoke other skills (ce-review invokes setup, ce-brainstorm invokes document-review). One source of truth, one place to update. +- **Dependencies phase runs before review-agent phase**: User knows their environment health before configuring agents. If agent-browser is missing, that context is useful before choosing browser-related review agents. +- **MCP detection via agent introspection**: The agent checks if context7 MCP tools are available in its current session (platform-specific but handled at the agent level, not bash). CLI check is the universal fallback. +- **Env var prompting is advisory only**: The skill prompts for values and advises where to persist them (shell profile, `.env`, or agent settings). It does not write to shell profiles — too invasive and platform-specific. + +## Open Questions + +### Resolved During Planning + +- **Cross-skill invocation**: /setup invokes ce-doctor for diagnostics using the established "load the `ce-doctor` skill" pattern (same as ce-review → setup, ce-brainstorm → document-review). Agent holds both skills in context and transitions back to /setup's install flow. +- **ctx7 install method**: `npm install -g ctx7` (non-interactive). Project URL for the interactive `npx ctx7 setup` +- **Platform-specific install commands**: One primary command per dep + project_url fallback. No OS detection in v1 +- **Env var persistence**: Advisory only — prompt values, advise where to persist, don't write shell profiles + +### Deferred to Implementation + +- **Plugin version currency check**: Needs research on marketplace API or `claude plugin` CLI during implementation +- **MCP introspection mechanism**: Exact method for checking if MCP tools are available varies by platform — implementer should test what works in Claude Code and Codex +- **rtk setup flow**: rtk (token optimization CLI) requires specific setup steps — implementer should check https://github.com/rtk-ai/rtk for current install instructions + +## Implementation Units + +- [x] **Unit 1: Create dependency registry** + +**Goal:** Create the centralized registry file that lists all known dependencies with structured metadata. + +**Requirements:** R5, R6 + +**Dependencies:** None + +**Files:** +- Create: `plugins/compound-engineering/skills/ce-doctor/references/dependency-registry.md` + +**Approach:** +- Each dependency is a markdown section with consistent fields: Description, Tier, Check (CLI command), Check MCP (optional), Install (optional for detect-only), Project URL, Used By (skills/agents), Env Vars (optional) +- Organized into sections: CLI Dependencies (recommended tier), CLI Dependencies (optional tier), MCP/External Services (detect-only), Environment Variables +- Dual-mode deps like context7 have both `Check MCP` and `Check CLI` fields + +**Patterns to follow:** +- Structured markdown similar to how `skills/agent-browser/references/` documents capabilities +- `rclone/scripts/check_setup.sh` for the specific check commands to use (e.g., `command -v`) + +**Test scenarios:** +- Registry contains all dependencies validated in the inventory scan: agent-browser, gh, jq, ctx7/context7, rtk, rclone, plus detect-only entries for Figma MCP and XcodeBuildMCP +- Each entry has all required fields (name, description, tier, check command, project_url, used_by) +- Optional fields (check_mcp, install_command, env_vars) present only where applicable +- Adding a hypothetical new dep requires only adding a new section + +**Verification:** +- Registry file is valid markdown with consistent structure +- All dependencies from the validated inventory are represented +- Each entry has enough information for ce-doctor to run checks and for /setup to offer installs + +--- + +- [x] **Unit 2: Create ce-doctor skill** + +**Goal:** Create the `/ce:doctor` diagnostic skill that reads the registry and reports environment health. + +**Requirements:** R1, R2, R3, R4, R12, R13, R14 + +**Dependencies:** Unit 1 + +**Files:** +- Create: `plugins/compound-engineering/skills/ce-doctor/SKILL.md` + +**Approach:** +- Frontmatter: `name: ce-doctor`, `description: Diagnose environment health...`, `disable-model-invocation: true` +- Reads the registry from `[references/dependency-registry.md](./references/dependency-registry.md)` +- For each CLI dep: run the check command (e.g., `command -v agent-browser`), record installed/missing +- For dual-mode deps (context7): check MCP availability first (attempt to use a context7 tool if available in the session), then fall back to CLI check +- For env vars: check if set via `echo $VAR_NAME` or equivalent +- Plugin version: attempt to determine installed version vs latest (mechanism deferred to implementation) +- .gitignore: check if `.context` is listed +- Output: formatted status table with checkmarks/X marks, guidance links for missing items +- Detect-only items (Figma, Xcode) shown as FYI with project links, not errors +- Cross-platform: use capability-class tool references, platform-agnostic question tool names, relative paths + +**Patterns to follow:** +- `rclone/scripts/check_setup.sh` output format (structured, checkmarks) +- `claude-permissions-optimizer` for cross-platform awareness +- Cross-platform interaction method from existing `/setup` skill (line 9-11) + +**Test scenarios:** +- System with all deps installed: all items show checkmarks +- System with missing deps: missing items show X with install guidance and project URL +- System with MCP loaded but no CLI: context7 shows as available via MCP +- System with CLI but no MCP: context7 shows as available via CLI +- Detect-only items (Figma, Xcode) show informational status, not error +- .gitignore missing `.context`: warning with guidance +- Output is readable and actionable regardless of platform + +**Verification:** +- Skill runs successfully and produces a status report +- Report covers all categories: CLI deps, MCP servers, env vars, plugin version, .gitignore +- No install actions attempted (informational only) +- Follows plugin compliance checklist (AGENTS.md): proper frontmatter, markdown links to references, imperative writing style, cross-platform tool references + +--- + +- [x] **Unit 3: Extend /setup with dependency phase** + +**Goal:** Add a dependency and environment phase to the existing `/setup` skill that invokes ce-doctor for diagnostics, then offers guided installation of missing dependencies. + +**Requirements:** R7, R8, R9, R10, R11, R12, R13 + +**Dependencies:** Unit 2 (ce-doctor must exist) + +**Files:** +- Modify: `plugins/compound-engineering/skills/setup/SKILL.md` + +**Approach:** +- Insert new steps before the existing Step 1 (Check Existing Config). The dependency phase runs first, then the existing review-agent configuration follows unchanged. +- New flow: + 1. Load the `ce-doctor` skill and run the diagnostic to show current environment status + 2. If all deps installed: show brief "Environment healthy" summary, proceed to review-agent config + 3. If deps missing: present missing installable deps in two tiers via multi-select question: + - Recommended (pre-selected): agent-browser, gh, jq + - Optional (opt-in): rtk, rclone, ctx7, etc. + 4. For each selected dep: offer the install command with user approval, run it, verify with check command. If install fails, show project URL as fallback + 5. After each dep install: if the dep has related env vars that are unset, prompt for the value and advise where to persist + 6. After all installs: prompt for any remaining unset env vars not tied to a specific dep + 7. Proceed to existing review-agent configuration (current Steps 1-5) +- For dual-mode deps (context7): if MCP is available, skip CLI install offer. If neither, offer CLI install. +- Existing Steps 1-5 renumber but content stays the same +- Cross-platform question tools used for all new interactions + +**Patterns to follow:** +- Existing `/setup` interaction method (line 9-11): platform-agnostic question tool with examples +- Existing Step 2 auto-detect pattern for the install-and-verify loop +- `ce-brainstorm` invoking `document-review` as the cross-skill invocation pattern + +**Test scenarios:** +- Fresh system with no deps: shows full diagnostic, offers all recommended pre-selected + optional +- User selects all recommended: installs each with approval, prompts env vars after relevant installs +- User deselects a recommended dep: that dep is skipped +- User selects optional deps: those are installed in addition to selected recommended +- Install fails: project URL shown as fallback, flow continues to next dep +- All deps already installed: brief "Environment healthy" message, skips to review-agent config +- Context7 MCP loaded: ctx7 CLI install not offered +- Context7 neither MCP nor CLI: ctx7 CLI install offered +- After dependency phase: existing review-agent flow works unchanged + +**Verification:** +- `/setup` runs the dependency phase before the review-agent phase +- Diagnostic output matches ce-doctor format +- Missing deps presented with correct tier assignments +- Install commands run with user approval and are verified afterward +- Env vars prompted per-dep after install +- Existing review-agent configuration flow unchanged +- Skill follows plugin compliance checklist + +--- + +- [x] **Unit 4: Update README and validate** + +**Goal:** Add ce-doctor to plugin documentation and verify plugin consistency. + +**Requirements:** (housekeeping) + +**Dependencies:** Units 1-3 + +**Files:** +- Modify: `plugins/compound-engineering/README.md` + +**Approach:** +- Add ce-doctor to the appropriate skill category table in README (Utility or Core workflow) +- Update skill count in README and plugin.json description if counts are mentioned +- Run `bun run release:validate` to verify plugin/marketplace consistency +- Do not hand-bump version or add changelog entries (per AGENTS.md) + +**Patterns to follow:** +- Existing skill table entries in README.md +- `plugins/compound-engineering/AGENTS.md` versioning requirements + +**Test scenarios:** +- README skill table includes ce-doctor with accurate description +- Skill count accurate +- `bun run release:validate` passes + +**Verification:** +- `bun run release:validate` exits cleanly +- README accurately reflects the new skill + +## System-Wide Impact + +- **Interaction graph:** `/setup` invokes `/ce:doctor` for its diagnostic phase. ce-doctor reads the registry and reports status. /setup then continues with its install flow. No other skills are affected. +- **Error propagation:** Install failures are non-blocking — the flow continues with a fallback URL. Missing deps are informational, not errors. +- **State lifecycle risks:** No state persisted. Fresh scan each time. No risk of stale state. +- **API surface parity:** The registry format and skill interfaces work across Claude Code, Codex, and other platforms via the existing pass-through conversion. +- **Integration coverage:** The dependency phase must not break the existing review-agent configuration. End-to-end testing of the full `/setup` flow (deps → review agents) validates this. + +## Risks & Dependencies + +- **MCP introspection uncertainty:** Detecting if an MCP server is loaded varies by platform and may not work reliably on all platforms. Mitigation: CLI check is the universal fallback; MCP detection is a bonus on platforms that support it. +- **Install command portability:** `npm install -g` and `brew install` may not work on all systems. Mitigation: project URL fallback for every dep. +- **Plugin version check:** No known API to check the latest marketplace version. Mitigation: implement what's possible, skip gracefully if not. + +## Sources & References + +- **Origin document:** [docs/brainstorms/2026-03-21-setup-dependency-management-requirements.md](docs/brainstorms/2026-03-21-setup-dependency-management-requirements.md) +- Related code: `plugins/compound-engineering/skills/setup/SKILL.md`, `plugins/compound-engineering/skills/rclone/scripts/check_setup.sh` +- Institutional learnings: `docs/solutions/skill-design/script-first-skill-architecture.md`, `docs/solutions/skill-design/compound-refresh-skill-improvements.md` diff --git a/plugins/compound-engineering/README.md b/plugins/compound-engineering/README.md index bce42fc6b..f551326b8 100644 --- a/plugins/compound-engineering/README.md +++ b/plugins/compound-engineering/README.md @@ -152,7 +152,8 @@ Core workflow commands use `ce:` prefix to unambiguously identify them as compou | `proof` | Create, edit, and share documents via Proof collaborative editor | | `claude-permissions-optimizer` | Optimize Claude Code permissions from session history | | `resolve-pr-parallel` | Resolve PR review comments in parallel | -| `setup` | Configure which review agents run for your project | +| `doctor` | Diagnose Compound Engineering plugin environment health -- checks CLI deps, MCP servers, env vars, plugin version | +| `setup` | Configure environment dependencies and review agents for your project | ### Multi-Agent Orchestration diff --git a/plugins/compound-engineering/skills/doctor/SKILL.md b/plugins/compound-engineering/skills/doctor/SKILL.md new file mode 100644 index 000000000..0ff33294e --- /dev/null +++ b/plugins/compound-engineering/skills/doctor/SKILL.md @@ -0,0 +1,69 @@ +--- +name: doctor +description: Diagnose Compound Engineering plugin environment health. Checks CLI dependencies, MCP servers, env vars, plugin version, and .gitignore. Use when troubleshooting missing tools, verifying setup, or before onboarding. +disable-model-invocation: true +--- + +# Compound Engineering Doctor + +Diagnose the health of the current environment for compound-engineering. Report what is installed, what is missing, and provide guidance links. This skill is informational only -- it never installs anything. + +## Step 1: Determine Plugin Version + +Before running the check script, determine the installed compound-engineering plugin version. This is platform-specific -- use whatever mechanism is available: + +- Read the plugin metadata or manifest if accessible +- Check the plugin cache or installation directory +- If the version cannot be determined, skip this step + +If a version is found, pass it to the script via `--version`. Otherwise omit the flag. + +## Step 2: Run the Health Check Script + +Run the bundled check script. Do not perform manual dependency checks -- the script handles all CLI tools, environment variables, .gitignore, and project checks in one pass. + +```bash +bash scripts/check-health --version VERSION +``` + +Or without version if Step 1 could not determine it: + +```bash +bash scripts/check-health +``` + +Script reference: [scripts/check-health](scripts/check-health) + +Display the script's output to the user. + +## Step 3: Check MCP Server Availability + +The script cannot detect MCP servers (that requires agent-level introspection). After running the script, check for these MCP services: + +1. **context7** -- Check whether `resolve-library-id` or `get-library-docs` tools from the context7 MCP server are available in the current session. If available, note "context7 MCP server loaded" alongside the CLI result from the script. + +2. **Figma MCP** -- Check whether any Figma MCP tools are available. Report as informational only. + +3. **XcodeBuildMCP** -- Check whether any XcodeBuildMCP tools are available. Report as informational only. + +Append MCP results after the script output using the same emoji format: + +``` + MCP Servers + 🟢 context7 (MCP server loaded -- ctx7 CLI not required) + ➖ Figma MCP (not detected, optional) + ➖ XcodeBuildMCP (not detected, optional) +``` + +For context7: if MCP is available, note that the ctx7 CLI is not required. If neither MCP nor CLI is available, highlight this as a gap. + +## Step 4: Summary + +After presenting the combined report (script output + MCP results), display: + +``` +Run /setup to install missing dependencies and configure environment variables. +Run /doctor anytime to re-check. +``` + +Registry reference for additional context: [references/dependency-registry.md](./references/dependency-registry.md) diff --git a/plugins/compound-engineering/skills/doctor/references/dependency-registry.md b/plugins/compound-engineering/skills/doctor/references/dependency-registry.md new file mode 100644 index 000000000..54b0776b3 --- /dev/null +++ b/plugins/compound-engineering/skills/doctor/references/dependency-registry.md @@ -0,0 +1,127 @@ +# Dependency Registry + +Centralized registry of external dependencies used by compound-engineering skills and agents. Each entry contains the metadata needed for `/doctor` diagnostics and `/setup` guided installation. + +To add a new dependency, add a new section following the format below. No code changes to doctor or setup are needed. + +--- + +## CLI Dependencies (Recommended) + +These are pre-selected during `/setup`. Most users should install them. + +### agent-browser + +- **Description:** Browser automation CLI for testing, screenshots, and web interaction +- **Tier:** recommended +- **Check:** `command -v agent-browser` +- **Install:** `npm install -g agent-browser && agent-browser install` +- **Project:** https://github.com/nichochar/agent-browser +- **Used by:** test-browser, feature-video, reproduce-bug, ce-review, design-iterator, figma-design-sync +- **Env vars:** AGENT_BROWSER_HEADED (optional, enables headed mode), AGENT_BROWSER_DEFAULT_TIMEOUT (optional, override timeout in ms) + +### gh + +- **Description:** GitHub CLI for issues, PRs, and repo management +- **Tier:** recommended +- **Check:** `command -v gh` +- **Install:** `brew install gh` +- **Project:** https://cli.github.com +- **Used by:** issue-intelligence-analyst, resolve-pr-parallel, test-browser, report-bug-ce, ce-plan, ce-review, ce-work, feature-video +- **Fallback:** GitHub MCP server if available + +### jq + +- **Description:** Command-line JSON processor +- **Tier:** recommended +- **Check:** `command -v jq` +- **Install:** `brew install jq` +- **Project:** https://jqlang.github.io/jq/ +- **Used by:** ce-plan, ce-brainstorm, proof, deploy-docs, orchestrating-swarms, resolve-pr-parallel + +--- + +## CLI Dependencies (Optional) + +These are opt-in during `/setup`. Install if you use the related skills. + +### rtk + +- **Description:** Token-optimized CLI proxy for dev operations (60-90% token savings) +- **Tier:** optional +- **Check:** `command -v rtk` +- **Install options:** + - `brew install rtk` (macOS with Homebrew) + - `curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh` (Linux/macOS) + - `cargo install --git https://github.com/rtk-ai/rtk` (Rust toolchain) +- **Project:** https://github.com/rtk-ai/rtk +- **Used by:** General token optimization across all skills +- **Post-install:** Run `rtk init --global` then restart the agent session +- **Platforms:** Claude Code, Gemini CLI, OpenCode only (requires pre-tool hooks) + +### ffmpeg + +- **Description:** Media processing CLI for video/GIF creation from screenshots +- **Tier:** optional +- **Check:** `command -v ffmpeg` +- **Install:** `brew install ffmpeg` +- **Project:** https://ffmpeg.org +- **Used by:** feature-video + +### ctx7 + +- **Description:** Context7 CLI for fetching up-to-date library documentation +- **Tier:** optional +- **Check:** `command -v ctx7` +- **Check MCP:** Attempt to use the `resolve-library-id` tool from the context7 MCP server. If the tool is available in the current session, context7 MCP is loaded. +- **Install:** `npm install -g ctx7` +- **Project:** https://github.com/nichochar/context7 +- **Used by:** deepen-plan, framework-docs-researcher, best-practices-researcher +- **Env vars:** CONTEXT7_API_KEY (recommended, prevents anonymous rate limiting) +- **Note:** This dependency has both an MCP server variant (bundled with the plugin) and a CLI variant. If the MCP server is loaded, the CLI is not needed. Check MCP availability first. + +--- + +## External Services (Detect-Only) + +These cannot be auto-installed. doctor reports their status as informational guidance. + +### Figma MCP + +- **Description:** MCP server for accessing Figma designs +- **Tier:** detect-only +- **Check MCP:** Attempt to use a Figma MCP tool. If available in the current session, the server is loaded. +- **Project:** https://github.com/nichochar/figma-mcp (or equivalent Figma MCP server) +- **Used by:** figma-design-sync, design-implementation-reviewer +- **Note:** Requires Figma account and MCP server configuration. Cannot be auto-installed. + +### XcodeBuildMCP + +- **Description:** MCP server for iOS simulator build and test +- **Tier:** detect-only +- **Check MCP:** Attempt to use an XcodeBuildMCP tool. If available in the current session, the server is loaded. +- **Project:** https://github.com/nichochar/XcodeBuildMCP (or equivalent) +- **Used by:** test-xcode +- **Note:** Requires Xcode installed on macOS. Cannot be auto-installed. + +--- + +## Environment Variables + +These are checked independently and also prompted per-dependency when relevant. + +### CONTEXT7_API_KEY + +- **Description:** API key for Context7 to avoid anonymous rate limits +- **Check:** Check if the variable is set in the current environment +- **Related dep:** ctx7 / context7 MCP +- **How to get:** Sign up at https://context7.com for an API key +- **Persistence guidance:** Add to shell profile (`~/.zshrc` or `~/.bashrc`) or agent settings + +### GEMINI_API_KEY + +- **Description:** Google Gemini API key for image generation and DSPy.rb +- **Check:** Check if the variable is set in the current environment +- **Related dep:** gemini-imagegen, dspy-ruby +- **How to get:** Create at https://aistudio.google.com/apikey +- **Persistence guidance:** Add to shell profile (`~/.zshrc` or `~/.bashrc`) or agent settings diff --git a/plugins/compound-engineering/skills/doctor/scripts/check-health b/plugins/compound-engineering/skills/doctor/scripts/check-health new file mode 100755 index 000000000..de3bc62c0 --- /dev/null +++ b/plugins/compound-engineering/skills/doctor/scripts/check-health @@ -0,0 +1,161 @@ +#!/usr/bin/env bash +# Compound Engineering environment health check +# Outputs a formatted diagnostic report in one pass + +set -o pipefail + +# --- Args --- +# --version VERSION (optional) plugin version to display (passed by the agent) + +plugin_version="" +while [ $# -gt 0 ]; do + case "$1" in + --version) plugin_version="$2"; shift 2 ;; + *) shift ;; + esac +done + +# --- Helpers --- + +check_cli() { + command -v "$1" >/dev/null 2>&1 && echo "ok" || echo "missing" +} + +check_env() { + printenv "$1" >/dev/null 2>&1 && echo "ok" || echo "missing" +} + +ok() { echo " 🟢 $1"; } +fail() { echo " 🔴 $1"; } +warn() { echo " 🟡 $1"; } +skip() { echo " ➖ $1"; } +detail() { echo " $1"; } +section() { echo ""; echo " $1"; } + +has_brew=$(check_cli brew) + +# --- Collect all results --- + +ab=$(check_cli agent-browser) +gh_s=$(check_cli gh) +jq_s=$(check_cli jq) +rtk_s=$(check_cli rtk) +ffmpeg_s=$(check_cli ffmpeg) +ctx7_s=$(check_cli ctx7) + +env_c7=$(check_env CONTEXT7_API_KEY) +env_gemini=$(check_env GEMINI_API_KEY) + +gi="skip" +if [ -f .gitignore ]; then + grep -q '\.context' .gitignore 2>/dev/null && gi="ok" || gi="missing" +fi + +# --- Counts --- + +cli_ok=0; cli_total=0 +for s in "$ab" "$gh_s" "$jq_s" "$rtk_s" "$ffmpeg_s" "$ctx7_s"; do + cli_total=$((cli_total + 1)) + [ "$s" = "ok" ] && cli_ok=$((cli_ok + 1)) +done + +env_ok=0; env_total=0 +for s in "$env_c7" "$env_gemini"; do + env_total=$((env_total + 1)) + [ "$s" = "ok" ] && env_ok=$((env_ok + 1)) +done + +issues=0 + +# ===================================================== +# Output +# ===================================================== + +echo "" +echo " Compound Engineering Doctor" +echo " ────────────────────────────────────────" + +# --- Plugin version (if provided by the agent) --- + +if [ -n "$plugin_version" ]; then + ok "Latest version installed (v${plugin_version})" +fi + +# --- CLI Tools --- + +section "Tools ${cli_ok}/${cli_total}" + +for pair in "agent-browser:$ab:recommended" "gh:$gh_s:recommended" "jq:$jq_s:recommended" \ + "rtk:$rtk_s:optional" "ffmpeg:$ffmpeg_s:optional" "ctx7:$ctx7_s:optional"; do + name="${pair%%:*}"; rest="${pair#*:}"; status="${rest%%:*}"; tier="${rest##*:}" + if [ "$status" = "ok" ]; then + ok "$name" + elif [ "$tier" = "recommended" ]; then + fail "$name" + issues=$((issues + 1)) + case "$name" in + agent-browser) detail "npm install -g agent-browser && agent-browser install" + detail "https://github.com/nichochar/agent-browser" ;; + gh) if [ "$has_brew" = "ok" ]; then detail "brew install gh" + else detail "https://cli.github.com"; fi ;; + jq) if [ "$has_brew" = "ok" ]; then detail "brew install jq" + else detail "https://jqlang.github.io/jq/"; fi ;; + esac + else + skip "$name (optional)" + case "$name" in + rtk) if [ "$has_brew" = "ok" ]; then detail "brew install rtk" + else detail "https://github.com/rtk-ai/rtk"; fi ;; + ffmpeg) if [ "$has_brew" = "ok" ]; then detail "brew install ffmpeg" + else detail "https://ffmpeg.org"; fi ;; + ctx7) detail "npm install -g ctx7 | https://context7.com" ;; + esac + fi +done + +# --- Environment --- + +section "Environment ${env_ok}/${env_total}" + +if [ "$env_c7" = "ok" ]; then + ok "CONTEXT7_API_KEY" +else + warn "CONTEXT7_API_KEY not set" + detail "Prevents rate limiting -- https://context7.com" + issues=$((issues + 1)) +fi + +if [ "$env_gemini" = "ok" ]; then + ok "GEMINI_API_KEY" +else + skip "GEMINI_API_KEY not set (needed for image generation)" + detail "https://aistudio.google.com/apikey" +fi + +# --- Project --- + +section "Project" + +if [ "$gi" = "ok" ]; then + ok ".gitignore includes .context" +elif [ "$gi" = "missing" ]; then + warn ".context/compound-engineering not in .gitignore" + issues=$((issues + 1)) +else + skip "No .gitignore found" +fi + +# --- Bottom line --- + +echo "" +echo " ────────────────────────────────────────" + +if [ "$issues" -eq 0 ]; then + echo " ✅ All clear ${cli_ok}/${cli_total} tools ${env_ok}/${env_total} env" +else + echo " ⚠️ ${issues} issue(s) found ${cli_ok}/${cli_total} tools ${env_ok}/${env_total} env" + echo "" + echo " Run /setup to resolve." +fi + +echo "" diff --git a/plugins/compound-engineering/skills/setup/SKILL.md b/plugins/compound-engineering/skills/setup/SKILL.md index 189995f05..4a3c203a7 100644 --- a/plugins/compound-engineering/skills/setup/SKILL.md +++ b/plugins/compound-engineering/skills/setup/SKILL.md @@ -1,6 +1,6 @@ --- name: setup -description: Configure which review agents run for your project. Auto-detects stack and writes compound-engineering.local.md. +description: Configure compound-engineering environment and review agents. Checks dependencies, offers guided installation, auto-detects stack, and writes compound-engineering.local.md. disable-model-invocation: true --- @@ -10,9 +10,135 @@ disable-model-invocation: true Ask the user each question below using the platform's blocking question tool (e.g., `AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini). If no structured question tool is available, present each question as a numbered list and wait for a reply before proceeding. For multiSelect questions, accept comma-separated numbers (e.g. `1, 3`). Never skip or auto-configure. -Interactive setup for `compound-engineering.local.md` — configures which agents run during `ce:review` and `ce:work`. +Interactive setup for compound-engineering — checks environment dependencies, then configures which agents run during `ce:review` and `ce:work`. -## Step 1: Check Existing Config +--- + +## Phase 1: Dependencies & Environment + +### Step D1: Run Diagnostics + +Load the `doctor` skill and run it to produce an environment health report. This checks CLI dependencies, MCP servers, environment variables, plugin version, and .gitignore. + +Display the diagnostic report to the user. + +### Step D2: Evaluate Results + +After the diagnostic report, check whether any installable dependencies are missing (items with an **Install** field in the registry that were reported as missing). + +If everything is installed and all recommended env vars are set, display: + +``` +Environment healthy -- all dependencies found. +Proceeding to review agent configuration. +``` + +Skip to Phase 2 (Step 1). + +If any installable dependencies are missing, proceed to Step D3. + +### Step D3: Offer Installation + +Present the missing installable dependencies grouped by tier using a multiSelect question. Pre-select recommended items. Do not include detect-only items (those are informational only from doctor). + +``` +The following tools are missing. Select which to install: +(Recommended items are pre-selected) + +Recommended: + [x] agent-browser - Browser automation for testing and screenshots + [x] gh - GitHub CLI for issues and PRs + [x] jq - JSON processor + +Optional: + [ ] rtk - Token optimization CLI (60-90% savings) + [ ] ffmpeg - Video/GIF creation for feature walkthroughs + [ ] ctx7 - Library documentation CLI +``` + +Only show dependencies that are actually missing. Omit installed ones and detect-only items. + +For context7/ctx7: if the context7 MCP server is available (detected in Step D1), do not offer ctx7 CLI installation -- the MCP server covers its functionality. + +### Step D4: Install Selected Dependencies + +For each selected dependency, in order: + +1. **Show the install command** and ask for approval: + + ``` + Install agent-browser? + Command: npm install -g agent-browser && agent-browser install + + 1. Run this command + 2. Skip - I'll install it manually + ``` + +2. **If approved:** Run the install command using a shell execution tool. After the command completes, verify installation by running the dependency's check command (e.g., `command -v agent-browser`). + +3. **If verification succeeds:** Report success and check for related env vars. + +4. **If verification fails or install errors:** Display the project URL as fallback: + + ``` + Installation did not succeed. Install manually: + https://github.com/nichochar/agent-browser + ``` + + Continue to the next dependency. + +5. **If the dependency has a Post-install step** (from the registry): Display it as guidance after successful install. + +### Step D5: Configure Environment Variables (Per-Dependency) + +Immediately after each successful dependency installation, check whether that dependency has related env vars (from the registry) that are not set. + +If unset env vars exist for the just-installed dependency, prompt: + +``` +CONTEXT7_API_KEY is not set. +This key prevents rate limiting for Context7. + +Enter your API key (or type "skip" to set it later): +``` + +If the user provides a value, advise where to persist it: + +``` +To persist this, add to your shell profile (~/.zshrc or ~/.bashrc): + export CONTEXT7_API_KEY="the-value" + +Or add it to your agent's environment settings. +``` + +If the user skips, continue without error. + +### Step D6: Remaining Environment Variables + +After all dependency installs are complete, check for any env vars from the registry's Environment Variables section that are still unset and were not already prompted in Step D5. + +If any remain unset, prompt for each one with context about what it does and where to get it (from the registry's **How to get** field). + +If all env vars are set, skip this step silently. + +### Step D7: Dependency Phase Summary + +Display a brief summary: + +``` +Dependencies configured. + Installed: agent-browser, gh, jq + Skipped: rtk + Env vars: CONTEXT7_API_KEY (set) + +Proceeding to review agent configuration. +``` + +--- + +## Phase 2: Review Agent Configuration + +### Step 1: Check Existing Config Read `compound-engineering.local.md` in the project root. If it exists, display current settings and ask: @@ -146,5 +272,6 @@ Agents: {count} configured {agent list, one per line} Tip: Edit the "Review Context" section to add project-specific instructions. + Run /doctor anytime to check environment health. Re-run this setup anytime to reconfigure. ```