Skip to content

Clarify runbook input source docs #253

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tobyhede wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Clarify runbook input source docs #253

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 14 additions & 5 deletions docs/FORMAT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,18 +44,26 @@ desc_field ::= "description:" ws text
version_field ::= "version:" ws text
author_field ::= "author:" ws text
tags_field ::= "tags:" newline tag_list
inputs_fm_field ::= "inputs:" newline inputs_map
inputs_fm_field ::= "inputs:" newline input_list
| "inputs:" ws inline_sequence
required_field ::= "required:" newline required_list
| "required:" ws inline_sequence
outputs_fm_field ::= "outputs:" newline output_fm_list
| "outputs:" ws inline_output_sequence

name_string ::= [a-zA-Z0-9_-] ( [a-zA-Z0-9_ -]* [a-zA-Z0-9_-] )?
tag_list ::= ( ws "- " tag newline )+
tag ::= text
inputs_map ::= ( ws variable_name ":" ws value newline )+
value ::= text
input_list ::= ( ws "- " variable_name newline )+
required_list ::= ( ws "- " variable_name newline )+
inline_sequence ::= "[" variable_name ( "," variable_name )* "]"
output_fm_list ::= ( ws "- " quoted_output_entry newline
| ws "- " output_entry newline )+
inline_output_sequence ::= "[" ( output_sequence_entry ( "," output_sequence_entry )* )? "]"
output_sequence_entry ::= output_entry | quoted_output_entry
Comment on lines +59 to +63
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Apr 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Allow optional whitespace in inline frontmatter sequences.

The new inline grammar currently excludes common YAML inline forms with spaced commas (e.g., [PlanPath, environment]). Please add optional whitespace around separators/items so the grammar matches practical authoring and parser behavior.

Suggested grammar tweak 
-inline_sequence ::= "[" variable_name ( "," variable_name )* "]"
+inline_sequence ::= "[" ws? variable_name ( ws? "," ws? variable_name )* ws? "]"

-inline_output_sequence ::= "[" ( output_sequence_entry ( "," output_sequence_entry )* )? "]"
+inline_output_sequence ::= "[" ws? ( output_sequence_entry ( ws? "," ws? output_sequence_entry )* )? ws? "]"
As per coding guidelines: `docs/**/*.md`: “Accuracy against current CLI behavior and public Rundown specification.”
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/FORMAT.md` around lines 59 - 63, The inline grammar currently disallows
spaces around commas and inside brackets; update inline_sequence and
inline_output_sequence to accept optional whitespace around separators and at
the bracket boundaries. Specifically, change inline_sequence (symbol
inline_sequence) to allow optional ws before/after each comma and optional ws
after the opening "[" and before the closing "]", and change
inline_output_sequence (symbol inline_output_sequence) similarly so the pattern
becomes "[" ws? variable_name ( ws? "," ws? variable_name )* ws? "]" and "[" ws?
( output_sequence_entry ( ws? "," ws? output_sequence_entry )* )? ws? "]"
respectively, leaving output_sequence_entry, output_entry, and
quoted_output_entry unchanged.

```

Additional fields beyond those listed are preserved (open schema). All fields are optional.
Public frontmatter keys are case-insensitive (`inputs:`, `INPUTS:`, and `Inputs:` are equivalent); unknown keys are preserved with their original casing. All fields are optional.

## Steps

Expand Down Expand Up @@ -90,12 +98,13 @@ Substeps cannot contain nested substeps. See [SPEC.md §1.1](./SPEC.md) for the
outputs_directive ::= "- OUTPUTS" newline output_list
output_list ::= ( ws "- " output_entry newline )+
output_entry ::= variable_name ( ws output_value )?
quoted_output_entry ::= quoted_string
output_value ::= helper_call | template_variable | quoted_string | variable_name
helper_call ::= "{{" ws? variable_name ( ws argument )+ ws? "}}"
argument ::= quoted_string | variable_path
```

A step or substep may declare at most one OUTPUTS directive. Duplicate directives on the same target are rejected. The `- INPUTS` directive has been removed — use the frontmatter `inputs:` field to declare default variable values.
A step or substep may declare at most one OUTPUTS directive. Duplicate directives on the same target are rejected.

OUTPUTS declares values to inject into the runbook's live variable space
after step completion. An entry may be a **naked declaration** (name only)
Expand Down
14 changes: 7 additions & 7 deletions packages/claude-code-plugin/skills/writing-runbooks/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,12 +142,12 @@ REQUIRED:
---
```

- `INPUTS:` is a YAML sequence of variable names the runbook accepts. Declarations only — entries do not carry values. Names must match `/^[a-zA-Z_][a-zA-Z0-9_]*$/` and must not collide with reserved/built-in names.
- `REQUIRED:` is a subset of `INPUTS:`. Every name in `REQUIRED:` must also appear in `INPUTS:` — mismatch is a parse-time error. Missing values trigger a hard `MISSING_REQUIRED_VARS` error at resolution.
- `INPUTS:` is a YAML sequence of variable names the runbook accepts. Declarations only — entries do not carry values. Names must match `/^[a-zA-Z_][a-zA-Z0-9_]*$/` and must not collide with reserved/built-in names. Values may come from `.rundown/config.yaml`, `--input`, `--input-json`, `--input-file`, `RD_INPUT_*` env, or parent-forwarded vars from a parent runbook/step.
- `REQUIRED:` is a subset of `INPUTS:`. Every name in `REQUIRED:` must also appear in `INPUTS:` — mismatch is a parse-time error. Missing values trigger a hard `MISSING_REQUIRED_VARS` error at resolution if not supplied by `.rundown/config.yaml`, `--input`, `--input-json`, `--input-file`, `RD_INPUT_*` env, or parent-forwarded vars from a parent runbook/step.

Defaults are not carried in frontmatter. Provide values via `--input`, `--input-json`, `--input-file`, `RD_INPUT_*` env, parent-forwarded variables (from a parent runbook's `OUTPUTS:`), or project `.rundown/config.yaml`.
Defaults are not carried in frontmatter. Provide values via `.rundown/config.yaml`, `--input`, `--input-json`, `--input-file`, `RD_INPUT_*` env, or parent-forwarded vars from a parent runbook/step.

Variable resolution precedence (highest → lowest): CLI `--input` / `--input-json` / `--input-file`, `RD_INPUT_*` env, parent-forwarded variables, project `.rundown/config.yaml`, built-in defaults.
Variable resolution precedence (highest → lowest): CLI flags (`--input-json` > `--input` > `--input-file`), `RD_INPUT_*` environment variables, parent-forwarded variables, project `.rundown/config.yaml`, built-in defaults.

## Transitions

Expand Down Expand Up @@ -237,8 +237,8 @@ Use `{{ variableName }}` syntax. See [CLAUDE.md — Template Variables](../../..

Key authoring notes:
- Undefined variables preserved as literal `{{ variable }}` text
- Frontmatter `INPUTS:` declares names only — defaults come from `.rundown/config.yaml`, `--input`, `--input-json`, `--input-file`, or `RD_INPUT_*` env
- Data sources for FOR loops: use `--input-json` for inline arrays, or `.rundown/config.yaml` / `--input-file` for arrays and `file:` values
- Frontmatter `INPUTS:` declares names only — values may come from `.rundown/config.yaml`, `--input`, `--input-json`, `--input-file`, `RD_INPUT_*` env, or parent-forwarded vars from a parent runbook/step
- Data sources for FOR loops: use `--input-json` for inline arrays, or `.rundown/config.yaml`, `--input-file`, or parent-forwarded vars from a parent runbook/step for arrays and `file:` values

## Common Mistakes

Expand All @@ -248,7 +248,7 @@ Key authoring notes:
| Command block + substeps in same step | Choose one — cannot mix |
| OUTPUTS after transitions | Content order: OUTPUTS → FOR → transitions → body |
| Reserved word as step ID | `PASS`, `FAIL`, `CONTINUE`, etc. are reserved |
| `INPUTS:` written as a key→default map (`VarName: default`) | `INPUTS:` is a YAML sequence of bare names (`- VarName`). Defaults live in config / `--input-file` / `--input-json` / env, not in frontmatter. |
| `INPUTS:` written as a key→default map (`VarName: default`) | `INPUTS:` is a YAML sequence of bare names (`- VarName`). Values may come from `.rundown/config.yaml`, `--input`, `--input-json`, `--input-file`, `RD_INPUT_*` env, or parent-forwarded vars from a parent runbook/step, not frontmatter defaults. |
| Name in `REQUIRED:` not declared in `INPUTS:` | `REQUIRED:` must be a subset of `INPUTS:`. Add the name to `INPUTS:` too. |
| Skipping `rd check` | Always validate: `rd check <file>` |

Expand Down