From f94e38029073b0deba485512debf5b4d843fb01a Mon Sep 17 00:00:00 2001 From: lucieleblanc Date: Mon, 30 Mar 2026 17:06:51 -0400 Subject: [PATCH 1/5] command spec skill restructure --- .agents/skills/add-command-spec/SKILL.md | 59 +++++++++++++++++++++--- 1 file changed, 52 insertions(+), 7 deletions(-) diff --git a/.agents/skills/add-command-spec/SKILL.md b/.agents/skills/add-command-spec/SKILL.md index 8b317591..fe521af0 100644 --- a/.agents/skills/add-command-spec/SKILL.md +++ b/.agents/skills/add-command-spec/SKILL.md @@ -5,10 +5,44 @@ description: Guide for adding new command completion specs to warp-command-signa # Adding a New Command Spec -## Steps +This skill covers the full lifecycle of writing a completion spec in warpdotdev/command-signatures: researching the command, implementing the spec, validating it, submitting a PR, and documenting learnings for future completion spec implementations. -1. **Create JSON spec**: `command-signatures/json/.json` following the [Fig completion spec schema](https://fig.io/docs/reference) -2. **Create generator** (if needed): Add `command-signatures/src/generators/.rs`, define a `generator()` function returning `CommandSignatureGenerators`, and register it in `generators/mod.rs` +## Step 1: Research the Command + +Before writing any JSON, build a thorough picture of the command's subcommands, flags, and argument types. Commands often have more surface area than you'd expect — nested subcommands, platform-specific flags, mutually exclusive options. Investing time here prevents rework later. + +Use these strategies roughly in priority order: + +### Start with Fish shell completions + +Fish maintains high-quality, community-reviewed completion definitions at https://github.com/fish-shell/fish-shell/tree/master/share/completions — look for `.fish`. These are thorough and well-structured, so they're the fastest way to get a comprehensive picture of a command's subcommands and flags. Read this file first. + +### Test with Fish shell completions + +You can also use Fish's completion engine to test output interactively: + +1. Install Fish if needed (`brew install fish` on UNIX) +2. Run: `fish -c 'complete -C " "'` to see top-level completions +3. Drill into subcommands: `fish -c 'complete -C " "'` + +For example, to inspect `gcloud compute ssh` completions: `fish -c 'complete -C "gcloud compute ssh w"'` (where `w` is the start of a known target). + +### Install and inspect the command directly + +Use the command's own documentation to fill gaps and verify what Fish reports. Install the command if it isn't already available, then: + +- Check the `man` page (pipe to `cat` to avoid the pager): `man | cat` +- Run ` --help` and ` help` at each subcommand level to discover nested structure +- Run the command itself to observe real output — this matters for generators that parse command output + +### Use Fig specs as a last resort + +The Fig autocomplete repo at https://github.com/withfig/autocomplete/tree/master/src has TypeScript specs for many commands (look for `.ts`). These can help fill gaps, but they vary in quality and may be outdated — always verify against the command's own docs. + +## Step 2: Implement the Spec + +1. **Create the JSON spec**: `command-signatures/json/.json` following the [Fig completion spec schema](https://fig.io/docs/reference) +2. **Create a generator** (if needed): Add `command-signatures/src/generators/.rs`, define a `generator()` function returning `CommandSignatureGenerators`, and register it in `generators/mod.rs` ## Platform Compatibility @@ -68,13 +102,24 @@ Format the JSON spec with `npm run format -- command-signatures/json/.j Run `script/presubmit` to verify formatting, linting, and tests all pass (this runs `cargo fmt --check`, `cargo clippy`, and `cargo test`). -To verify completions end-to-end in a real Warp session, use the **test-local-warp** skill, which covers building and running Warp against a local checkout of this repo. -This requires computer use to be enabled since Warp is a GUI application. +To verify completions end-to-end in a real Warp session, use the **test-local-warp** skill, which covers building and running Warp against a local checkout of this repo. This requires computer use to be enabled since Warp is a GUI application. Use this when adding generators to make sure they produce reasonable candidates. -If you are running unsupervised (autonomy level is `UNSUPERVISED`), this step is required. Produce screenshots for each generator added so that a human can review them. You do not need to zoom in. We only need screenshots for generator functions. Things like sub-commands and options are already well tested. -When running supervised, skip this step. +If you are running unsupervised (autonomy level is `UNSUPERVISED`), screenshot artifacts are required; the generator implementation will not be accepted without them. When running supervised, skip this step. + +## Submitting + +Ttile the branch: `lucie/test-command-spec-`. +Title the PR: **Add completion spec: ``**. + +A consistent title convention makes it easy to scan PR history and understand what was added at a glance. + +## Post-Completion Learnings + +If you encounter something genuinely surprising or novel while writing the spec that would help future completion spec writers — an undocumented edge case, a research strategy that saved significant time, a pattern that the existing guidance doesn't cover — update this skill file with what you learned. Open a separate PR titled **Post-completion learnings: ``** with those changes. + +Skip this if the spec was straightforward and the existing guidance covered everything you needed. The goal is to help future spec implementers, not to generate busywork. ## Reference Examples From f3c4f719c26cbbab689e51f22e41fd4a73e12fa9 Mon Sep 17 00:00:00 2001 From: lucieleblanc Date: Tue, 31 Mar 2026 17:29:52 -0400 Subject: [PATCH 2/5] add submission instructions --- .agents/skills/add-command-spec/SKILL.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/.agents/skills/add-command-spec/SKILL.md b/.agents/skills/add-command-spec/SKILL.md index fe521af0..98f61688 100644 --- a/.agents/skills/add-command-spec/SKILL.md +++ b/.agents/skills/add-command-spec/SKILL.md @@ -110,17 +110,14 @@ If you are running unsupervised (autonomy level is `UNSUPERVISED`), screenshot a ## Submitting -Ttile the branch: `lucie/test-command-spec-`. -Title the PR: **Add completion spec: ``**. +Title the branch: `lucie/test-command-spec-`. +Title the PR: **Add completion spec: ` [short-name])`**. + is the command's full, human-readable name (eg. "ripgrep"). +[short-name] is the command's CLI invocation, if it exists, in parentheses (eg. "(rg)"). +For example, adding support for ripgrep would be done in a branch called `lucie/test-command-spec-rg` and a PR titled "Add completion spec: ripgrep (rg)". A consistent title convention makes it easy to scan PR history and understand what was added at a glance. -## Post-Completion Learnings - -If you encounter something genuinely surprising or novel while writing the spec that would help future completion spec writers — an undocumented edge case, a research strategy that saved significant time, a pattern that the existing guidance doesn't cover — update this skill file with what you learned. Open a separate PR titled **Post-completion learnings: ``** with those changes. - -Skip this if the spec was straightforward and the existing guidance covered everything you needed. The goal is to help future spec implementers, not to generate busywork. - ## Reference Examples - **Simple spec with generator**: `json/kill.json` + `src/generators/kill.rs` — minimal example showing `generatorName` usage for process and signal completions From 2e6df0a75eec4a082050d29ec071f05b5e1b5123 Mon Sep 17 00:00:00 2001 From: lucieleblanc Date: Tue, 31 Mar 2026 17:44:39 -0400 Subject: [PATCH 3/5] add UI verification instructions --- .agents/skills/add-command-spec/SKILL.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/.agents/skills/add-command-spec/SKILL.md b/.agents/skills/add-command-spec/SKILL.md index 98f61688..f0a93a17 100644 --- a/.agents/skills/add-command-spec/SKILL.md +++ b/.agents/skills/add-command-spec/SKILL.md @@ -102,22 +102,21 @@ Format the JSON spec with `npm run format -- command-signatures/json/.j Run `script/presubmit` to verify formatting, linting, and tests all pass (this runs `cargo fmt --check`, `cargo clippy`, and `cargo test`). -To verify completions end-to-end in a real Warp session, use the **test-local-warp** skill, which covers building and running Warp against a local checkout of this repo. This requires computer use to be enabled since Warp is a GUI application. -Use this when adding generators to make sure they produce reasonable candidates. -Produce screenshots for each generator added so that a human can review them. You do not need to zoom in. -We only need screenshots for generator functions. Things like sub-commands and options are already well tested. -If you are running unsupervised (autonomy level is `UNSUPERVISED`), screenshot artifacts are required; the generator implementation will not be accepted without them. When running supervised, skip this step. +Static sub-commands and options are already well-tested. + +Generators require end-to-end verification to make sure they produce reasonable candidates. To verify generator completions end-to-end in a real Warp session, use the `test-local-warp` skill in `command-signatures/.agents/skills/test-local-warp/` which covers building and running Warp against a local checkout of the `command-signatures` repo. This requires computer use to be enabled since Warp is a GUI application. +Use a local warp build to install and set up the command and test the newly-written generators. To trigger the completions menu, press the `tab` key. Remember that we're NOT testing autocomplete (ghost text), but rather testing completions, which are dropdown menus that appear next to the cursor. Take a screenshot to show each generator working; your work will not be accepted without it. You do not need to zoom in. ## Submitting -Title the branch: `lucie/test-command-spec-`. -Title the PR: **Add completion spec: ` [short-name])`**. - is the command's full, human-readable name (eg. "ripgrep"). -[short-name] is the command's CLI invocation, if it exists, in parentheses (eg. "(rg)"). +Title the branch according to the Linear issue, eg: `app-####/command-spec-`. +Title the PR: **Add completion spec: ` [short-name])`**, where `` is the command's full, human-readable name (eg. "ripgrep"). `[short-name]` is the command's CLI invocation, if it exists, in parentheses (eg. "(rg)"). For example, adding support for ripgrep would be done in a branch called `lucie/test-command-spec-rg` and a PR titled "Add completion spec: ripgrep (rg)". A consistent title convention makes it easy to scan PR history and understand what was added at a glance. +Attach screenshots for each generator in the PR body. + ## Reference Examples - **Simple spec with generator**: `json/kill.json` + `src/generators/kill.rs` — minimal example showing `generatorName` usage for process and signal completions From 0a41b57a6188ff610b1672a95c14216b20e53ae4 Mon Sep 17 00:00:00 2001 From: lucieleblanc Date: Tue, 31 Mar 2026 18:04:04 -0400 Subject: [PATCH 4/5] fix heading nesting and add examples --- .agents/skills/add-command-spec/SKILL.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/.agents/skills/add-command-spec/SKILL.md b/.agents/skills/add-command-spec/SKILL.md index f0a93a17..c5674b08 100644 --- a/.agents/skills/add-command-spec/SKILL.md +++ b/.agents/skills/add-command-spec/SKILL.md @@ -5,7 +5,7 @@ description: Guide for adding new command completion specs to warp-command-signa # Adding a New Command Spec -This skill covers the full lifecycle of writing a completion spec in warpdotdev/command-signatures: researching the command, implementing the spec, validating it, submitting a PR, and documenting learnings for future completion spec implementations. +This skill covers the full lifecycle of writing a completion spec in warpdotdev/command-signatures: researching the command, writing the spec, validating it, and submitting it. ## Step 1: Research the Command @@ -44,17 +44,17 @@ The Fig autocomplete repo at https://github.com/withfig/autocomplete/tree/master 1. **Create the JSON spec**: `command-signatures/json/.json` following the [Fig completion spec schema](https://fig.io/docs/reference) 2. **Create a generator** (if needed): Add `command-signatures/src/generators/.rs`, define a `generator()` function returning `CommandSignatureGenerators`, and register it in `generators/mod.rs` -## Platform Compatibility +### Platform Compatibility When implementing generator commands, ensure they work across all applicable platforms where the command exists. For example, a UNIX-only command should work on both macOS and Linux, not just the platform being used for development. -### Common pitfalls +#### Common pitfalls - Commands that work differently across platforms (for example, user lookup via `dscl` on macOS vs `getent` on Linux) - Commands with different output formats across platforms - Hardcoded paths that differ between systems -### Solutions +#### Solutions Identify which platforms the command needs to support. @@ -69,7 +69,7 @@ Prioritize approaches in this order: Implement platform-specific logic in the generator only when behavior fundamentally differs across systems. -## Generator Reusability +### Generator Reusability Generators that are shared by multiple commands should live in `command-signatures/src/generators/common.rs`. Before implementing a new generator: @@ -80,11 +80,11 @@ Generators that are shared by multiple commands should live in `command-signatur See `fn users_generator()` in `common.rs` as an example of a cross-platform generator used by multiple commands. -## Style Guideline +### Style Guideline Match the formatting conventions used in the command's `--help` output. For example, if the help text uses `UPPER_CASE` for positional argument names, use the same casing in the spec's argument `name` field. -### Documenting Argument Formats +#### Documenting Argument Formats If an argument has a specific format (date, time, pattern, etc.), document it in the argument's `description` field. This helps users understand the expected input format. @@ -96,7 +96,7 @@ Example: } ``` -## Validation +## Step 3: Validation Format the JSON spec with `npm run format -- command-signatures/json/.json`. @@ -107,11 +107,11 @@ Static sub-commands and options are already well-tested. Generators require end-to-end verification to make sure they produce reasonable candidates. To verify generator completions end-to-end in a real Warp session, use the `test-local-warp` skill in `command-signatures/.agents/skills/test-local-warp/` which covers building and running Warp against a local checkout of the `command-signatures` repo. This requires computer use to be enabled since Warp is a GUI application. Use a local warp build to install and set up the command and test the newly-written generators. To trigger the completions menu, press the `tab` key. Remember that we're NOT testing autocomplete (ghost text), but rather testing completions, which are dropdown menus that appear next to the cursor. Take a screenshot to show each generator working; your work will not be accepted without it. You do not need to zoom in. -## Submitting +## Step 4: Submitting Title the branch according to the Linear issue, eg: `app-####/command-spec-`. Title the PR: **Add completion spec: ` [short-name])`**, where `` is the command's full, human-readable name (eg. "ripgrep"). `[short-name]` is the command's CLI invocation, if it exists, in parentheses (eg. "(rg)"). -For example, adding support for ripgrep would be done in a branch called `lucie/test-command-spec-rg` and a PR titled "Add completion spec: ripgrep (rg)". +For example, adding support for openshift would be done in a branch called `app-3507/command-spec-openshift` and a PR titled "Add completion spec: openshift (oc)". A consistent title convention makes it easy to scan PR history and understand what was added at a glance. @@ -121,3 +121,6 @@ Attach screenshots for each generator in the PR body. - **Simple spec with generator**: `json/kill.json` + `src/generators/kill.rs` — minimal example showing `generatorName` usage for process and signal completions - **Complex spec with multiple generators**: `json/brew.json` + `src/generators/brew.rs` — shows subcommands, options, and multiple generators (`formulae_generator`, `services`, etc.) +- **Context-aware generators and aliases**: `src/generators/git.rs` — demonstrates `command_from_tokens` (flag-dependent behavior) and `add_alias` (git alias expansion) +- **Multi-command module with shared helpers**: `src/generators/npm.rs` — single module exporting generators for `npm`, `yarn`, and `pnpm`, reusing `get_scripts_generator()` and `dependencies_generator()` +- **Parsing structured output**: `src/generators/cargo.rs` — generators that parse JSON from `cargo metadata` using serde deserialization From 9f8a3f7457a3f7ab14f8c976e61e527412a50e84 Mon Sep 17 00:00:00 2001 From: lucieleblanc Date: Tue, 31 Mar 2026 18:23:43 -0400 Subject: [PATCH 5/5] remove broken Fig link (RIP) --- .agents/skills/add-command-spec/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/add-command-spec/SKILL.md b/.agents/skills/add-command-spec/SKILL.md index c5674b08..d51b574f 100644 --- a/.agents/skills/add-command-spec/SKILL.md +++ b/.agents/skills/add-command-spec/SKILL.md @@ -41,7 +41,7 @@ The Fig autocomplete repo at https://github.com/withfig/autocomplete/tree/master ## Step 2: Implement the Spec -1. **Create the JSON spec**: `command-signatures/json/.json` following the [Fig completion spec schema](https://fig.io/docs/reference) +1. **Create the JSON spec**: `command-signatures/json/.json` following Fig's completion spec schema and the reference examples. 2. **Create a generator** (if needed): Add `command-signatures/src/generators/.rs`, define a `generator()` function returning `CommandSignatureGenerators`, and register it in `generators/mod.rs` ### Platform Compatibility