# CLI Agent Surface Work

> Change the public agent-facing CLI surface while preserving registry-backed discovery, JSON envelopes, aliases, docs, and tests.

- Skill: `clawic/cli-agent-surface-work` (Agent Skill)
- Install (CLI): `npx skillmds@latest add clawic/cli-agent-surface-work`
- Raw SKILL.md: https://api.skillmd.com/api/skills/clawic/cli-agent-surface-work/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: clawic (https://skillmd.com/u/clawic)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/clawic/cli-agent-surface-work

---


# cli-agent-surface-work

Work on the public `claw` CLI as an agent-facing contract.

## Procedure

1. Use `claw search`, `claw commands resolve`, and `claw inspect commands|command-intents|why|schemas|storage|codebase --json` when available.
   For governance-heavy CLI/doc work, start with `claw governance doctor --json`
   to collect the current reads, skills, closing checks, external-pending lanes,
   and stale-doc risks.
2. Read the CLI ADR, decision map, naming guide, and the tests for the affected command.
3. Keep stable JSON output in the accepted envelope shape unless the command is explicitly in migration debt.
4. Add registry entries, generated/help docs, aliases, negative legacy tests, and smoke coverage with the behavior.
5. For new CLI words or aliases, classify the phrase as `covered`, `candidate_alias`, `gap`, `future`, `blocked`, or `external_pending`; record explicit demand through `claw commands record` instead of activating semantic routing by guess.
6. If the change adds durable docs, ADRs, guardrails, or harnesses, register
   the discovery route in `docs/discoverability.registry.json` per
   `docs/adr/0017-discoverability-and-meta-code-routing.md`.
7. Treat aliases as thin portals; avoid semantic routers that guess intent.
8. Update docs and examples in the same change when public usage changes.
9. Before closure for canon, route, storage, permission, ADR, skill, or
   Clawix/ClawJS integration changes, run
   `node scripts/discoverability-check.mjs closure --changed-file <path> --json`.
   The closing report must cite the real `claw search ... --json` and
   `claw inspect ... --json` evidence plus the discovered artifact, or mark
   the work `PARTIAL/BLOCKED`.

## Constraints

- `claw` is the public CLI. Do not add new public `clawjs`, `clawix`, or framework-domain CLIs.
- Do not expose secret-bearing, destructive, cost-bearing, or native permission actions without host approval boundaries.
- Do not make source files the primary map when the CLI registry can answer.
- Do not report public CLI surface closure as complete when the affected
  artifact cannot be found by `claw search` and inspected through `claw inspect`.