Develop an ASC CLI change

Follow AGENTS.md for authority, CLI contracts, implementation invariants, validation, and review gates.

Write the design note

For a small fix, record the reproduced failure, intended behavior, and focused check. For new public behavior or compatibility decisions, also record:

1. Placement in the existing command taxonomy and registry.
2. Current --help behavior and expected invocation shape.
3. Exact OpenAPI endpoint, method, request schema, query parameters, and response shape when API-facing.
4. Flags, output formats, stdout/stderr behavior, and exit codes.
5. Compatibility, lifecycle, migration, and deprecation impact.
6. RED-GREEN tests, black-box checks, live verification, edge cases, and failure modes.
7. Credible alternatives when a material design trade-off exists.

Establish RED

• For a bug, reproduce it first and add the smallest regression test that fails for the expected reason.
• For a feature, start with CLI-level coverage of the changed observable contract; add unit or HTTP tests for distinct behavior that those tests do not cover.
• For a behavior-changing refactor, use existing characterization coverage where sufficient and add coverage for missing behavior before moving code.
• Run the focused test and record the expected failure before implementation.

Read references/test-matrix.md for applicable CLI, output, artifact, and auth cases. Reuse sufficient existing coverage; do not duplicate shared parser or renderer tests for every command.

Validate API support

1. Search docs/openapi/paths.txt, then inspect the exact operation in docs/openapi/latest.json.
2. Apply the endpoint-specific schema checks in AGENTS.md.
3. If the API cannot support the behavior, implement explicit client-side behavior or document the limitation; do not ship a misleading flag.

Implement narrowly

Apply AGENTS.md's implementation invariants. Return usage errors with exit code 2.

Reach GREEN and verify

1. Rerun the focused failing test after each small fix.
2. Run adjacent package and command tests.
3. Build a binary at a worktree-specific path and verify realistic invocations, output streams, and exit codes. Do not share a fixed /tmp/asc path with concurrent tasks.
4. Run a minimal live smoke test when behavior depends on App Store Connect quirks. Prefer read-only calls; live mutations and cleanup require authority under AGENTS.md.
5. Apply AGENTS.md's validation gate, including command-doc generation when help changes. Public CLI behavior, shared code, release surfaces, and meaningful defect or security fixes require the full gate.

Before handoff, compare the exact branch head with current main read-only. Follow the branch-update rules in AGENTS.md; a newer base alone does not justify changing the branch.

Hand off

Use AGENTS.md's handoff contract; include invocation and compatibility details for public-contract changes.