/standards

name: standards
version: 0.5.0
description: >
  Runs Phase 4 review/publish/verify for a cli-web-* CLI: implementation review by
  3 parallel agents, the tiered quality checklist (Tier 1 critical fail-fast, then
  comprehensive), pip install + smoke test, and per-CLI skill generation. Use when a
  CLI's tests pass and it is ready to be validated and published.
when_to_use: >
  Trigger phrases: "validate CLI", "publish CLI", "review CLI", "smoke test",
  "quality check", "start Phase 4", "quality checklist", "generate Claude skill",
  "verify implementation quality", or after the testing skill completes. Not for
  capture, implementation, or test writing.

CLI-Anything-Web Standards (Phase 4: Review + Publish + Verify)

Quality gate for cli-web-* CLIs. This skill owns the complete Phase 4: independent implementation review, structural quality checklist, publishing, and end-user smoke testing. Nothing ships until this phase passes.

Copy this checklist and check off items as you complete them:

Phase 4 Progress:
- [ ] Prerequisites: tests 100% pass, TEST.md Parts 1+2, <APP>.md present
- [ ] Step 1: 3 review agents dispatched, Critical findings = 0
- [ ] Step 2: validate-checklist Tier 1 exits 0, then full run reviewed
- [ ] Step 3: pip install -e . verified (binary on PATH, --help, doctor)
- [ ] Step 4: end-user smoke test — auth, READ, WRITE all pass
- [ ] Step 5: per-CLI skill generated (passes test_skill_quality.py)
- [ ] Step 6: registry entry added, devkit gates green, repo docs updated
- [ ] phase-state marked complete

---

Prerequisites (Hard Gate)

Do NOT start unless:

• [ ] All tests pass (100% pass rate from Phase 3)
• [ ] TEST.md has both Part 1 (plan) and Part 2 (results)
• [ ] All core modules are implemented and functional
• [ ] `<APP>.md` (API map) exists and documents all endpoints

If tests are not passing, invoke the `testing` skill first. If this gate or the phase state is in a failed/inconsistent state, follow `skills/shared/RECOVERY.md` §phase-state Check Failures.

**Optional pre-review coverage scan:** before dispatching the review agents, you MAY run the `gap-analyzer` skill (`${CLAUDE_PLUGIN_ROOT}/skills/gap-analyzer/SKILL.md`, pass `APP_PATH=<app>/agent-harness`) to diff captured endpoints (`<APP>.md` + `traffic-capture/traffic-analysis.json`) against implemented commands. It is *optional* here because the traffic-fidelity-reviewer agent covers endpoint coverage during Step 1; gap-analyzer is the *mandatory first step* of `/refine`, where no reviewer pass exists. Run it here when coverage looks doubtful and you want the structured report before the agents start.

Site Profile Exceptions

Not all checks apply to every CLI. When evaluating, consider the site profile:

• **No-auth sites** (public APIs): Skip auth-related checks (auth.py required,

auth commands, auth smoke test). Mark as N/A.

• **Read-only sites** (no write operations): Skip write operation smoke test.

Verify reads return real data instead.

• **API-key auth sites**: `auth login` takes a key argument, not playwright-cli.

`auth refresh` is not applicable — use `auth logout` instead.

Mark inapplicable checks as "N/A — [reason]" rather than creating dead-code stubs.

---

Step 1: Implementation Review (3 Parallel Agents)

Before checking structure or publishing, verify the code *actually does the right thing*. Tests prove it runs; this step proves it's correct.

Dispatch 3 plugin agents in the **same message** using the Agent tool:

• `traffic-fidelity-reviewer` — API coverage (reads <APP>.md + client.py + commands/)
• `harness-compliance-reviewer` — Code conventions incl. JSON envelope STRUCTURE (reads CONVENTIONS.md + all source)
• `output-ux-reviewer` — User experience (runs --help, checks REPL, validates JSON)

Pass each agent: APP_PATH=`{app}/agent-harness`, APP_NAME=`{app}`, and site profile (auth_type, is_read_only). The agents are defined in the plugin's `agents/` directory.

| Agent | Focus | What it reads | What it catches | |-------|-------|---------------|-----------------| | Traffic Fidelity | API coverage | `<APP>.md` + `client.py` + `commands/` | Missing endpoints, wrong params, broken response parsing, dead client methods, stale API map | | HARNESS Compliance | Code quality + JSON envelope structure | CONVENTIONS.md + checklist + all source | click.ClickException bypass, missing to_dict(), retry_after lost, auth retry missing, stderr UTF-8 | | Output & UX | User experience | `--help` output, `--json` output, REPL | Protocol leaks, stale REPL help, dead command files, broken entry points |

Each agent scores findings on a 0-100 confidence scale. When all 3 return:

1. **Filter out findings with confidence < 75** (noise) 2. Categorize remaining findings:

• **Critical** (90-100): Bugs, missing endpoints, data loss, auth broken
• **Important** (75-89): Wrong fields, incomplete parsing, missing options
• **Minor** (75, edge cases): Help text gaps, cosmetic issues

3. Present the review report 4. **Fix all Critical issues** before proceeding — re-run only the affected agent to verify the fix 5. Fix Important issues (not strictly blocking but strongly recommended)

**Gate: Do not proceed to Step 2 until Critical count = 0.**

---

Step 2: Structural Quality Checklist (tiered)

The checklist is tiered (see `references/quality-checklist.md` "Tiers"): **Tier 1 (critical)** failures block publish; **Tier 2 (comprehensive)** failures are warnings that should still be fixed.

**2a. Tier 1 fail-fast first.** Run only the critical checks and fix every FAIL before doing anything else — there is no point reviewing a CLI whose structure, packaging, or `--json` envelope is broken:

python ${CLAUDE_PLUGIN_ROOT}/scripts/validate-checklist.py \
  <app>/agent-harness --app-name <app> --auth-type <auth-type> --tier1-only

Non-zero exit = Tier 1 failures. Fix and re-run until it exits 0.

**2b. Full run.** Then run the complete checklist (both tiers):

`