| name | doctor |
| description | Health-check a Forward Deploy install - instance reachable and its /api/health green (db, repo, anthropic), local skill config present (forward-deploy.json + FORWARD_DEPLOY_TOKEN), SOP/company-doc paths intact in the repo, and best-effort plugin-freshness against the GitHub source. Reports a worklist; does not auto-fix. Run when the user types /forward-deploy:doctor, or says "is forward deploy healthy", "check the forward deploy install", "why can't the app read the repo", "forward deploy health check", "is the planning app up". |
Doctor - keep the install honest
The health gate. It checks the four legs a working Forward Deploy instance stands on - the app,
its keys, the repo paths, and the local skill config - and reports a worklist; it does not
auto-fix. Run it manually when something feels off, after rotating keys, or on a schedule.
The instance is the company's deployment of the app; forward-deploy.json (repo root,
committed, non-secret) points the skills at it; FORWARD_DEPLOY_TOKEN (env) authenticates them.
How to run
-
Check 1 - local skill config.
forward-deploy.json exists at the repo root and parses; appUrl, repo, sopPath,
companyDocsPath present. Its repo matches the git remote (flag mismatch).FORWARD_DEPLOY_TOKEN is set in the environment / local .env. Never print it.
-
Check 2 - instance health. GET <appUrl>/api/health (no auth) - expect per-dependency
status: db (Postgres reachable, migrations current), repo (GitHub token valid, scopes
sufficient, configured repo/branch readable), anthropic (key valid), email (SMTP config
present - config-level only; do not send a test mail unless asked). Then one authed call
(GET /api/plans?limit=1) to prove FORWARD_DEPLOY_TOKEN is accepted - 401 means the local
token and the instance's have drifted.
-
Check 3 - repo paths. In the repo (at the configured branch): sopPath and
companyDocsPath exist; the company profile doc is present (mockups read it - flag if it is
still the untouched template: branding tokens unset means generic mockups); if CANONIFY.md
exists, note canons available; if not, note plans run on raw code only.
-
Check 4 - plugin freshness (optional, best-effort). Same procedure as Canonify's doctor:
read ~/.claude/plugins/installed_plugins.json for forward-deploy@<marketplace>; resolve the
marketplace's git URL; compare the source's .claude-plugin/plugin.json version against the
installed one. No install record (local dev checkout) or offline -> SKIP and say so. Flag only
on a version difference; never run the update yourself.
-
Open with a self-identifying banner, then report the worklist. A scheduled sweep arrives
with no context, so the FIRST line must name Forward Deploy and the verdict. Group findings by
check, each with evidence and a one-line suggested action.
Don't do
- Don't auto-fix. Report; the human decides (or runs kickoff's reconfigure path).
- Don't print secrets - token/env values never appear in output, only their names and whether
they are set/accepted.
- Don't declare healthy on a partial pass. If a leg was skipped (offline, no token), say
skipped - skipped is not green.
- Don't send outward traffic beyond the checks - no test emails, no posting to plan threads.
Output template
FORWARD DEPLOY DOCTOR - <found <N> item(s) to review | clean, nothing to review>
Instance: <appUrl> Repo: <owner>/<name>@<branch>
### Local config
- [OK|MISSING|MISMATCH] forward-deploy.json ...
- [OK|MISSING] FORWARD_DEPLOY_TOKEN set
### Instance health (/api/health)
- [OK|FAIL] db ... - [OK|FAIL] repo (scopes) ... - [OK|FAIL] anthropic ... - [OK|WARN] email ...
- [OK|401] authed API call
### Repo paths
- [OK|MISSING] <sopPath>/ ... - [OK|MISSING|TEMPLATE] <companyDocsPath>/company-profile.md
- [INFO] CANONIFY.md <present, N canons | absent - plans run on raw code>
### Plugin freshness
- [OK|BEHIND|N/A] forward-deploy@<marketplace> ...
### Summary
<N> checks run, <F> findings, <S> skipped. <Clean | Address the above>.
