mirror of https://github.com/callstack/agent-device.git synced 2026-09-14 20:06:34 +08:00

Files

T

Michał Pierzchała 1a76344685 docs: restructure AGENTS.md and CONTEXT.md for progressive disclosure (#1402 )

* docs: restructure AGENTS.md and CONTEXT.md for progressive disclosure

Apply the Claude 5 context-engineering guidance to the repo's agent docs:
keep the always-loaded file to gotchas and invariants, and move situational
guidance one hop away behind a routing table.

AGENTS.md 315 -> 229 lines. Cut generic agent-behavior boilerplate, three-way
duplication (Common Mistakes restated Hard Rules; Finding Source Owners
restated the registry section), and facts visible from the repo itself.
Kept verbatim: the expensive-lessons principles, enforcement gates, Hard
Rules, and environment traps.

Split out docs/agents/{cli-flags,pull-requests,device-verification}.md and
folded the Testing Matrix into docs/agents/testing.md, reframed around
pnpm check:affected so the prose stops duplicating the selector.

CONTEXT.md keeps all 50 terms, now grouped under a section index so a task
loads one section instead of the whole glossary.

* fix(check-affected): move the selector-owning sentinel to the Testing Matrix

The Testing Matrix moved from AGENTS.md to docs/agents/testing.md, but the
affected-check selector still treated only AGENTS.md as selector-owning. A
later matrix edit would have been classified as inert docs and skipped the
fail-open, so the selector could keep deriving gates from a spec that had
changed underneath it.

Move the sentinel with the prose, as a named SELECTOR_OWNING_DOCS set so the
next move is one line, and fix the two in-code comments plus the testing.md
paragraph that still pointed at the AGENTS.md matrix.

* docs: restore two rules dropped by the AGENTS.md split

Review caught two repo-specific rules that did not survive the move. Both are
prose without any backticked identifier, so the identifier-diff used to verify
the split could not see them.

- "Test through public interfaces; do not add unrelated production exports
  solely to enable tests" returns next to the behavioral-tests rule in
  docs/agents/testing.md, with the reason it exists.
- The guidance-ownership rule (decide whether new guidance/schema/metadata
  belongs to the command surface, CLI grammar, CLI help, MCP projection, or
  daemon runtime) returns to the always-loaded Docs & skills section, since it
  governs all command-surface work and not just the flag case.

Also point the ADR routing row at docs/adr/README.md, which is already the
"read when you touch…" index, rather than at the bare directory.

2026-07-25 12:13:09 +02:00

2.7 KiB

Raw Permalink Blame History

Adding a CLI Flag

A new flag touches only the layers that need to understand it. Stop at the layer where it stops mattering — threading it further is the common failure, not stopping too early.

src/contracts/cli-flags.ts: add to CliFlags; add the definition to the matching src/commands/cli-grammar/flag-definitions-*.ts owner and the relevant group in flag-groups.ts (for example SNAPSHOT_FLAGS). Then update the command family metadata/schema that exposes the flag; find the owner with rg -n "<command>|supportedFlags|allowedFlags" src/commands src/cli-schema src/cli/parser. For schema-only CLI commands (cdp, auth, connect, proxy, react-devtools, web) the owner is SCHEMA_ONLY_CLI_COMMAND_SCHEMAS in src/cli-schema/command-overrides.ts.
src/commands/cli-grammar/*: read the CLI flag into command input.
src/commands/command-projection.ts and command-family projection helpers: write the input into the daemon request only if the flag affects daemon execution.
src/commands/*-command-contracts.ts: add to the command input schema only if the option should be available through Node.js or MCP as structured input.
src/client/client-types.ts: update the public typed client option only when the Node.js interface exposes it.
src/client/client-normalizers.ts: update daemon flag normalization only when the request still needs a public-to-internal translation.
src/daemon/context.ts and src/core/dispatch-context.ts: add the field only when it flows into platform dispatch.
Handler/platform modules: thread the option only after the command surface, grammar, and projection prove it belongs there.
scripts/integration-progress-model.ts: classify the flag (device-observable vs intentionally-outside). The architecture-progress gate fails CI on unclassified public flags.
If the flag changes interaction semantics, revisit the affected cells in src/contracts/interaction-guarantees.ts (scope with appliesTo when the flag exists only on some commands).

Command-only flags (like find --first) that never reach the platform layer usually stop at steps 1-3, plus step 9.

Where CLI help and schema live

Long help prose: src/cli/parser/cli-help.ts. Flag definitions: src/commands/cli-grammar/.
Command-specific usage/flag metadata lives with the command family metadata that owns the command.
Parser/help rendering stays in src/cli/parser/; command schema metadata is derived from command metadata, family declarations, and the schema-only merge path in src/cli-schema/command-overrides.ts. Keep the two separate.
Locating an owner: rg -n "helpDescription|summary|supportedFlags|allowedFlags" src/commands src/cli/parser src/cli-schema.

2.7 KiB Raw Permalink Blame History

Adding a CLI Flag

Where CLI help and schema live

2.7 KiB

Raw Permalink Blame History