# Product Command Handler Agent Guide

This file applies to `internal/helpers/`. Read the root `AGENTS.md`,
[`CONTRIBUTING.md`](../../CONTRIBUTING.md), and
[`docs/coding-agent-guide.md`](../../docs/coding-agent-guide.md) first.
For package/file layout, read
[`docs/helpers-structure-guide.md`](../../docs/helpers-structure-guide.md)
before adding or moving product leaves.

## Scope and routing

`internal/helpers` owns product command construction and handler behavior. Find
the owning product file and its closest tests before editing.

| Concern | Owning surface |
|---|---|
| Root/static command wiring or plugin loading | `internal/app` |
| Product command flags and handler behavior | `internal/helpers` |
| Helpers file layout / megafile splits | [`docs/helpers-structure-guide.md`](../../docs/helpers-structure-guide.md) |
| Shared Cobra construction | `internal/cobracmd` |
| Invocation and transport | `internal/executor`, `internal/transport` |
| Structured failures and recovery hints | `internal/errors`, `internal/recovery` |
| Output encoding and projections | `internal/output` |
| Confirmation and dry-run guards | `internal/safety` and command runtime gates |
| Agent identity/Schema/parameters | `internal/cli` and [`docs/schema-contributor-guide.md`](../../docs/schema-contributor-guide.md) |

Do not modify `internal/app` or shared layers merely to register an ordinary
product leaf when the existing helper construction already owns it. Cross the
package boundary only when the task changes that shared contract.

## File layout (hard rules)

- Stay in flat `package helpers`; do not add `helpers/{product}` subpackages by
  default.
- Product root `{product}.go` owns `new{Product}Command()` and wires subgroups.
- Put leaves in `{product}_{resource}.go` by CLI resource (see `sheet_*.go`).
- Do not grow megafiles such as `chat.go` or `aitable.go`; extract or add the
  resource file instead.
- Mechanical splits must be behavior-neutral and keep registration symbols
  stable. Details and size guides:
  [`docs/helpers-structure-guide.md`](../../docs/helpers-structure-guide.md).

## Command contract

- Confirm the current path and flags with `dws <path> --help` and the Cobra
  construction before changing behavior.
- Keep stdout machine-readable business data. Send progress, warnings, and
  diagnostics through the established stderr/logging paths.
- Preserve structured error category, stable exit behavior, cause, trace ID,
  and an actionable recovery hint. Do not replace a typed lower-layer failure
  with an unclassified message.
- Treat paths, JSON payloads, filenames, and remote content as untrusted input;
  use existing validation and sanitization helpers.
- Mutating or destructive commands must keep their preview/confirmation
  behavior aligned with runtime safety and published Schema metadata.
- If flags, identity, parameters, selection, or safety metadata change, follow
  the scoped `internal/cli/AGENTS.md` and regenerate from reviewed inputs.

## Verification matrix

| Change | Required focused evidence |
|---|---|
| Handler bug or behavior | package regression test including the failure path |
| Flags or request mapping | Cobra/help test plus dry-run request assertion when the command supports preview |
| Output or error behavior | structured payload, stderr/stdout, and exit-code assertions |
| Mutating behavior | preview/confirmation test; live execution only with explicit authorization and disposable data |
| Shared helper refactor | affected product tests plus `go test ./internal/helpers/...` |
| Public command surface | Schema/command gates from `internal/cli/AGENTS.md` |

Before handoff, run the narrow package tests, `make format-check`, and the
admission checks selected by `docs/coding-agent-guide.md`. Do not claim a live
round-trip when only dry-run or mocked transport was exercised.