Skip to content

docs(developer-experience): add control-CLI pitfalls to /developer-experience:build-cli #9533

Closed

Description

@kyle-sexton

Refs: #9507

Problem

The five pitfalls in #9507 ("Pitfalls for a control CLI") are not in build-cli/reference/cli-contract.md. Line 55 covers only stdout and stderr in general.

Fix

Add rows to the contract, each with an upstream pointer, an as-of date and a recheck trigger:

  • A child process inherits the caller's handles and hangs a piped caller. Start the app without inheriting handles.
  • A composite command keeps --json stdout to one document and sends sub-step output to stderr.
  • The recorded pid may be a wrapper, so find the real app process before attaching.
  • Reject unknown flags, repeated step ids, malformed ids and unknown apps or environments fast.
  • Name the override mechanism the app actually honors, and never assume environment variables win.

The issue implementer should verify and carry the upstream pointers (the Windows process docs are not on a CI lane fetch host).

Acceptance criteria

  • Five new rows in cli-contract.md, each with a pointer, an as-of date and a trigger.
  • One eval case: a review of a CLI that pipes a child with inherited handles flags it.
  • grep -nE '#[0-9]{3,}' over the changed skill files returns nothing.
  • grep -nE '5031|SETWorks|Blazor' over the changed skill files returns nothing (no consumer-specific default).

Blocked by

None.

Files

  • plugins/developer-experience/skills/build-cli/reference/cli-contract.md
  • plugins/developer-experience/skills/build-cli/evals/evals.json
  • Changelog fragment

Activity

  1. added
    priority: mediumReal value, no hard deadline; normal backlog flow.
    status: readyTriaged, unblocked, and fully specified; eligible to pick up.
    on Oct 24, 2026
  2. added theissue type on Oct 24, 2026
  3. added
    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.
    on Oct 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.priority: mediumReal value, no hard deadline; normal backlog flow.status: readyTriaged, unblocked, and fully specified; eligible to pick up.

    Type

    Fields

    No fields configured for Task.

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions