Document the command signature contribution workflow

[vikvang]

Problem

The README explains where handwritten, autogenerated, and override command signatures live, but it does not provide an end-to-end contribution checklist for adding or updating a signature. Contributors must infer the required formatting, validation, and generated-file expectations from repository tooling and CI.

Desired behavior

Add a concise contribution workflow to the README that explains:

• how to choose between a handwritten signature, an autogenerated signature, and an override;
• which repository-provided formatting and validation commands to run;
• when PowerShell autogeneration must be rerun;
• how generated changes should be separated for review;
• what contributors should verify before opening a pull request.

Acceptance criteria

• The documented commands are taken from the current repository configuration rather than duplicated from external guidance.
• The workflow covers both handwritten JSON signatures and PowerShell-generated signatures/overrides.
• Existing technical details about override behavior remain intact.
• This is documentation-only; no signature data or generator behavior needs to change.

[warp-factories]

Here's what I found while triaging this issue:

• Request: add an end-to-end contribution checklist to README.md — choosing handwritten vs. autogenerated vs. override signatures, which format/validate commands to run, when to rerun PowerShell autogeneration, how to separate generated diffs, and what to verify before opening a PR.
• Confirmed gap: README.md already covers the layout (command-signatures/json/*.json handwritten, json/autogenerated/**, json/overrides/**), cargo run --bin autogenerate_powershell, and override merge semantics — but there is no contributor checklist, and the repo has no CONTRIBUTING.md.
• Commands the checklist should cite (verified in-tree, not external guidance): npm run format / npm run format:check (Prettier; .prettierignore excludes command-signatures/json/autogenerated/), and script/presubmit, which runs format-check, cargo fmt --check, cargo clippy ... -D warnings, and cargo test. .github/workflows/CI.yml mirrors those same three jobs on PRs.
• PowerShell path is real and worth documenting: generator at command-signatures/src/bin/autogenerate_powershell.rs, ~663 generated files under json/autogenerated/powershell/, ~10 overrides under json/overrides/powershell/, alongside ~496 handwritten top-level specs.
• Accuracy note for whoever implements this: README.md currently describes overrides as supporting only template, while command-signatures/src/overrides.rs (and AGENTS.md) also apply generatorName. Worth aligning while keeping the existing override detail intact.
• Scope: documentation-only, essentially confined to README.md; no signature data, generator, or CI behavior needs to change. Reproducible on inspection, and a reasonable first contribution.
• Not a duplicate: Define a documented convention for pairing short and long option names in specs #374 is also documentation-related but covers a short/long option-name pairing convention, which is a different concern.

Routing to @captainsafia to review and apply a gate label (ready-to-spec / ready-to-implement) if this should proceed.

This is my automated analysis and may be incorrect. A maintainer will verify the details.

Responding as Warp for OSS: Open session · View run

[warp-factories]

This issue has been marked ready for a specification. Community contributions are welcome — feel free to pick it up. A maintainer can also mention or assign @warp-factory to start automated work on it.

[vikvang]

@warp-factory pick this up

[warp-agent-staging]

No Factory you can access is connected to warpdotdev/command-signatures. Go to platform.staging.warp.dev to connect this repository to a Factory or ask a Factory admin for access. See Factory GitHub integration docs. Then mention @warp-factory again.

[warp-factories]

Spec approved: #397 (specs/GH396/product.md + specs/GH396/tech.md, spec only — no README or signature changes). ready-to-spec has been cleared now that the spec stage is complete.

What the spec settles:

• The workflow goes into an existing README.md section rather than a new CONTRIBUTING.md, and stays independently usable without the agent-facing .agents/skills/add-command-spec/SKILL.md.
• Covers choosing handwritten vs. PowerShell-generated vs. override, Prettier formatting, script/presubmit, keeping generated output in its own commit, and a pre-PR checklist.
• Confirms against command-signatures/src/overrides.rs that overrides support both template and generatorName — the README's template-only note is stale and the spec calls for correcting it.
• Notes that override edits require regeneration, since the generator applies overrides before writing output.
• Open point for maintainers: the repo doesn't pin the PowerShell version/module set used for generation; the spec keeps that out of scope.

Implementation has not started and is still gated: apply ready-to-implement and assign @warp-factory to this issue to have the factory write the README change. The spec PR itself stays a human merge decision.

Responding as Warp for OSS: Open session · View run