MCP ↔ CLI ↔ Web Parity
web (apps/web) is the source of truth for what entities exist. MCP
(apps/mcp, agent tools) and CLI (apps/cli, terminal) are thin adapters
over one shared domain layer, packages/go/ops.
Rule: when web adds an artifact/entity — or a new operation on one — that
agents or the CLI should reach, propagate it to ops → MCP → CLI and record
the decision in apps/mcp/parity_manifest.json. CI-enforced: both
apps/mcp/internal/tools/parity_test.go and apps/cli/cmd/parity_test.go
fail on any tool/command missing a manifest entry.
Checklist
- Ops — add
func Xxx(ctx, *ops.Session, XxxInput) (XxxOutput, error)topackages/go/ops/<domain>.go. Structs needjson+jsonschematags; account-scope every query withs.AccountID. Add ops tests. - MCP — thin
mcp.AddTool(...)adapter inapps/mcp/internal/tools/<domain>.go(wired viaregister.go). Bump the tool count inapps/mcp/CLAUDE.md. - CLI — cobra command in
apps/cli/cmd/<domain>.go: flags → ops input →buildOpsSession()→ same ops func. Seecmd/goal.go. Resolve refs server-side viaops(likeops.GetTaskon UUID-or-display-ID) — never a local.hamstersync-state scan (drifts from MCP, breaks outside a synced repo). - Manifest — add a
pairsentry (MCP tool ↔ CLI command) or a documentedmcp_only/cli_onlyexemption with a reason. - Verify —
cd apps/mcp && go test ./... && cd ../cli && go test ./...
Exemptions (still a manifest entry)
Asymmetry is allowed but never implicit. mcp_only = MCP tool with no CLI
counterpart, or a tracked gap (currently empty — all tools are paired).
cli_only = CLI command with no MCP tool (local concerns init/sync/status,
shortcuts brief status/task assign, authoring method create).
Anti-patterns
- Tool/command with no
parity_manifest.jsonentry → parity test fails. - Query/validation logic in the adapter instead of
ops→ the other frontend can't reuse it and they drift. - CLI resolving entities via local
.hamsterscans instead of anopsserver-side lookup (thetask getbug fixed in this PR). - New web entity exposed to one frontend but not the other — reach parity or record the exemption.