|
1 | 1 | Generate a Token Model Protocol (TMP) JSON schema for the CLI tool "{{ tool }}". |
2 | 2 |
|
3 | | -A TMP schema defines the subcommand structure, parameters (flags and arguments), primitive token types, descriptions, and dynamic resolvers for a CLI tool. |
| 3 | +Your task is to dynamically discover the full CLI structure of "{{ tool }}" by running its help commands, then produce an exhaustive TMP v2 JSON schema. Do NOT rely on training knowledge alone — actually run the tool to discover its interface. |
4 | 4 |
|
5 | | -Please design a comprehensive and detailed schema file for "{{ tool }}", mapping its most common subcommands, options, and parameters. |
| 5 | +## Step 1: Discover the help system |
6 | 6 |
|
7 | | -## Schema Specification and Format |
8 | | -The output MUST be a valid JSON object matching the following structure: |
| 7 | +Try each method in order and use the first one that succeeds: |
| 8 | + |
| 9 | +1. `{{ tool }} --help` |
| 10 | +2. `{{ tool }} -h` |
| 11 | +3. `man {{ tool }}` |
| 12 | +4. `{{ tool }}` (with no arguments — some tools print usage on bare invocation) |
| 13 | + |
| 14 | +Record which method produced output. If none work, fall back to your training knowledge and set `discovery_method` to `"none"`. |
| 15 | + |
| 16 | +Also discover the tool version by trying `{{ tool }} --version` or `{{ tool }} -V`. |
| 17 | + |
| 18 | +## Step 2: Discover the tool's description |
| 19 | + |
| 20 | +From the help output, extract a concise one-line description of what "{{ tool }}" does (the first sentence or tagline). |
| 21 | + |
| 22 | +## Step 3: Recursively discover ALL subcommands (max 3 levels deep) |
| 23 | + |
| 24 | +Parse the top-level help output for a list of subcommands or command groups. |
| 25 | + |
| 26 | +For each subcommand found: |
| 27 | +- Run `{{ tool }} <subcommand> --help` (or `-h` if `--help` is not supported) |
| 28 | +- Parse the output for nested subcommands |
| 29 | +- For nested subcommands, run `{{ tool }} <subcommand> <nested> --help` |
| 30 | +- Continue up to 3 levels deep (e.g. `{{ tool }} remote add --help`) |
| 31 | + |
| 32 | +If "{{ tool }}" has no subcommands (e.g. simple tools like `cat`, `echo`, `grep`), create a single command entry with `"command": "{{ tool }}"`. |
| 33 | + |
| 34 | +## Step 4: Extract ALL flags, options, and arguments |
| 35 | + |
| 36 | +For every command and subcommand, parse the help output exhaustively. For each parameter: |
| 37 | + |
| 38 | +1. **Name**: derive from the long flag (e.g. `--output` → `"output"`) or positional name |
| 39 | +2. **Flag**: the long form (e.g. `--output`) |
| 40 | +3. **Aliases**: short forms (e.g. `["-o"]`) |
| 41 | +4. **Required vs optional**: mark as `required: true` if the help text indicates it is mandatory or if it is a positional argument without a default |
| 42 | +5. **Token type** — apply these rules: |
| 43 | + - `"Boolean"`: flags that take no value (e.g. `--release`, `--verbose`, `--force`) |
| 44 | + - `"String"`: flags that accept a free-form string value |
| 45 | + - `"Enum"`: flags with a known, finite set of valid values (e.g. `--format json|yaml|toml`) |
| 46 | + - `"File"`: flags that accept a file or directory path (look for hints like `<FILE>`, `<PATH>`, `<DIR>`) |
| 47 | + - `"Number"`: flags that accept a numeric value (e.g. `--jobs <N>`, `--depth <NUM>`) |
| 48 | +6. **Default**: extract the default value if documented (e.g. `[default: 4]`) |
| 49 | +7. **Values**: for `Enum` types, list all valid values as an array (e.g. `["json", "yaml", "toml"]`) |
| 50 | +8. **Description**: the help text for this parameter |
| 51 | + |
| 52 | +Every flag that appears in `--help` output MUST appear in the schema. Be exhaustive. |
| 53 | + |
| 54 | +## Step 5: Map data sources |
| 55 | + |
| 56 | +For parameters that accept dynamic values, attach a `data_source` object. |
| 57 | + |
| 58 | +### Built-in resolvers (use when applicable): |
| 59 | + |
| 60 | +| Resolver | Provides | |
| 61 | +|----------|----------| |
| 62 | +| `cargo:bins` | Binary target names from Cargo workspace | |
| 63 | +| `cargo:examples` | Example target names | |
| 64 | +| `cargo:packages` | Package names in workspace | |
| 65 | +| `cargo:features` | Feature flags | |
| 66 | +| `cargo:profiles` | Build profiles | |
| 67 | +| `cargo:tests` | Test target names | |
| 68 | +| `cargo:benches` | Benchmark target names | |
| 69 | +| `git:branches` | Git branch names | |
| 70 | +| `git:remotes` | Git remote names | |
| 71 | +| `git:status_files` | Files with uncommitted changes | |
| 72 | +| `git:tags` | Git tags | |
| 73 | +| `npm:scripts` | npm script names from package.json | |
| 74 | + |
| 75 | +### Command-based resolvers: |
| 76 | + |
| 77 | +For dynamic values not covered by built-in resolvers, specify a shell command that produces one value per line: |
| 78 | + |
| 79 | +```json |
| 80 | +"data_source": { |
| 81 | + "resolver": null, |
| 82 | + "command": "docker image ls --format '{{"{{"}}.Repository{{"}}"}}:{{"{{"}}.Tag{{"}}"}}'", |
| 83 | + "parse": "lines", |
| 84 | + "fallback": { |
| 85 | + "command": "docker image ls -q" |
| 86 | + } |
| 87 | +} |
| 88 | +``` |
| 89 | + |
| 90 | +Use fallback chains when multiple sources exist. Set `data_source` to `null` for parameters that take literal user input. |
| 91 | + |
| 92 | +## Step 6: Determine metadata |
| 93 | + |
| 94 | +- `requires_binary`: set to `"{{ tool }}"` (the binary that must be on PATH) |
| 95 | +- `requires_file`: set to a project file if relevant (e.g. `"Cargo.toml"` for cargo, `"package.json"` for npm), otherwise `null` |
| 96 | +- `keywords`: 3-6 descriptive keywords for the tool |
| 97 | + |
| 98 | +## Output format |
| 99 | + |
| 100 | +Output a single valid JSON object with this exact structure. Do NOT wrap it in markdown code blocks. Do NOT add conversational commentary. Output ONLY the raw JSON. |
| 101 | + |
| 102 | +``` |
9 | 103 | { |
10 | 104 | "meta": { |
| 105 | + "schema_version": 2, |
11 | 106 | "tool": "{{ tool }}", |
12 | | - "description": "Short description of what the tool does." |
| 107 | + "version": 0, |
| 108 | + "description": "<one-line description of the tool>", |
| 109 | + "generated_by": "ai", |
| 110 | + "generated_with": "waz-agent", |
| 111 | + "verified": false, |
| 112 | + "coverage": "full", |
| 113 | + "discovery_method": "<help|man|none>", |
| 114 | + "requires_file": "<filename or null>", |
| 115 | + "requires_binary": "{{ tool }}", |
| 116 | + "keywords": ["<keyword1>", "<keyword2>", "..."] |
13 | 117 | }, |
14 | 118 | "commands": [ |
15 | 119 | { |
16 | 120 | "command": "{{ tool }} <subcommand>", |
17 | | - "description": "Short description of the subcommand.", |
| 121 | + "description": "<what this subcommand does>", |
18 | 122 | "group": "{{ tool }}", |
19 | | - "verified": true, |
| 123 | + "verified": false, |
20 | 124 | "tokens": [ |
21 | 125 | { |
22 | | - "name": "parameter_name", |
23 | | - "description": "What this flag/argument does.", |
| 126 | + "name": "<param_name>", |
| 127 | + "description": "<what it does>", |
24 | 128 | "required": false, |
25 | | - "token_type": "Enum" | "Boolean" | "String" | "File" | "Number", |
26 | | - "flag": "--flag-name" (optional), |
27 | | - "data_source": { (optional) |
28 | | - "resolver": "git:branches" | "git:status_files" | "cargo:packages" | "npm:scripts" | etc. |
29 | | - } |
| 129 | + "token_type": "String", |
| 130 | + "flag": "--flag-name", |
| 131 | + "aliases": ["-f"], |
| 132 | + "default": null, |
| 133 | + "values": null, |
| 134 | + "data_source": null |
30 | 135 | } |
31 | 136 | ] |
32 | 137 | } |
33 | 138 | ] |
34 | 139 | } |
| 140 | +``` |
| 141 | + |
| 142 | +### Field notes: |
| 143 | +- `command`: full invocation prefix, e.g. `"{{ tool }} build"`, `"{{ tool }} remote add"`, or just `"{{ tool }}"` for tools without subcommands |
| 144 | +- `group`: always `"{{ tool }}"` |
| 145 | +- `verified`: always `false` (this is AI-generated) |
| 146 | +- `token_type`: one of `"String"`, `"Boolean"`, `"Enum"`, `"File"`, `"Number"` |
| 147 | +- `aliases`: array of short flags, e.g. `["-f"]`, or `[]` if none |
| 148 | +- `values`: array of valid values for `Enum` type, or `null` |
| 149 | +- `data_source`: resolver object or `null`. Structure when present: |
| 150 | + ``` |
| 151 | + { |
| 152 | + "resolver": "<built_in_resolver or null>", |
| 153 | + "command": "<shell_command or null>", |
| 154 | + "parse": "lines", |
| 155 | + "fallback": { |
| 156 | + "command": "<fallback_command or null>" |
| 157 | + } |
| 158 | + } |
| 159 | + ``` |
| 160 | + |
| 161 | +## Step 7: Save the schema |
| 162 | + |
| 163 | +After generating the JSON, save it to `~/.waz/schemas/{{ tool }}.json`. Create the `~/.waz/schemas/` directory if it does not exist. |
| 164 | + |
| 165 | +## Important reminders |
35 | 166 |
|
36 | | -## Guidelines |
37 | | -1. The JSON must be valid and ready to be saved to `.waz/schemas/{{ tool }}.json`. |
38 | | -2. Do not wrap the JSON in markdown code blocks or add conversational commentary; output ONLY the raw, clean JSON content. |
39 | | -3. Make sure to define the correct `token_type` for each parameter. Use "Boolean" for flags that take no values (like --force or -f), "Enum" for parameters with specific values, "File" for paths/files, and "String" for generic text. |
| 167 | +- Actually run `{{ tool }} --help` and subcommand help — do not guess from memory |
| 168 | +- Every flag from the help output must appear in the schema — be exhaustive |
| 169 | +- The JSON must be valid and parseable |
| 170 | +- For tools with many subcommands (e.g. `git`, `docker`, `cargo`), this will require many help invocations — that is expected |
| 171 | +- Omit `data_source` (set to `null`) when the parameter takes literal user input with no dynamic completion |
| 172 | +- Group related subcommands logically but keep every subcommand as its own entry in the `commands` array |
0 commit comments