fix: soft-wrap generated markdown and forward extra flow flags#21
Conversation
Add a uniformly-worded soft-wrap rule to every skill that authors markdown prose artifacts (docs, ed, spec, dev, pm, em, ux), placed at each skill's existing style/format authority and, for dispatchers, in SKILL.md so it loads on every verb. Generated prose must be one continuous line per paragraph; the renderer handles wrapping.
Extend the shared flow-dir arg-parse into a three-bucket parser: flow-control flags (--global/-g, and --set for go) are peeled off as before, and every other flag (e.g. --branch feature/x) is collected in order into PASSTHROUGH_FLAGS instead of being silently dropped. new bakes passthrough flags onto each stored step command; go appends them to each resolved step command at run time. SKILL.md and help.md document the forwarding behavior.
skapoor8
left a comment
skapoor8
left a comment
There was a problem hiding this comment.
Draft review for #21. Two reasonable fixes, but both have consistency gaps.
Issue 1 (soft-wrap): the rule lands at three different authority levels across the seven skills — a Critical-Rules bullet (dev/em/pm), a bespoke ## Global Authoring Rule heading (spec), and references-only with no SKILL.md entry (docs/ed/ux). Separately, qa also writes markdown (debug report, smoke report, and the markdown it posts to GitHub/GitLab/Linear via report) but was left out entirely, so the PR's "all markdown-generating skills" goal isn't actually met. (No inline comment on qa since the file isn't in the diff — flagging here.)
Issue 2 (flow flag pass-through): the PASSTHROUGH_FLAGS parser uses unquoted set -- $ARGS, which corrupts quoted flag values and the multi-word step-command positionals a flow is built from; and new.md strands the flow.md flag-append instruction in Step 3 while the step lines are written in Step 2.
Inline comments below: 2 BLOCKING, 4 CONSIDER, 1 NOTE.
The pass-through parser used `set -- $ARGS`, an unquoted re-split that
word-splits every argument on whitespace. This shredded multi-word step
commands (e.g. `/spec new {{objective}}`) and quoted flag values
(`--set feature="add OAuth"`) into separate tokens, corrupting both
POSITIONALS and PASSTHROUGH_FLAGS.
Iterate the preserved argv (`"$@"`) the dispatcher forwards so each
original argument stays one element. Document the argv contract in
SKILL.md, add a caveat that flag values starting with `-` aren't
supported, and note `--set` is verb-specific (dropped by new, parsed by go).
The instruction to append PASSTHROUGH_FLAGS to each flow.md step line lived in new.md Step 3, but the step lines are written in Step 2 (which still said "keep placeholders verbatim"). An implementer reading top to bottom wrote flow.md without the flags, diverging the stored checklist from the step files. Move the flag-append into Step 2's step-line spec so flags are baked at write time using a single BAKED_FLAGS string shared by flow.md and the step files. Drop `--set` from BAKED_FLAGS (it is a go-time parameter binding, never a stored step flag). In go.md, make the "don't duplicate" dedup deterministic: skip appending a flag whose name already appears as a token in the step command.
The soft-wrap markdown rule had three different placements: dev/em/pm used a Critical-Rules bullet, spec used a bespoke `## Global Authoring Rule` heading, and docs/ed/ux carried it only in a references template with no SKILL.md entry. qa was missed entirely despite writing debug reports, smoke reports, and markdown posted to GitHub/GitLab/Linear. Standardize on the Critical-Rules bullet: convert spec's bespoke heading, add the bullet to docs/ed/ux SKILL.md (pointing to their full template), and add a Critical Rules section with the bullet to qa.
skapoor8
left a comment
skapoor8
left a comment
There was a problem hiding this comment.
Second critical pass on PR #21 (post round-6 fixes).
Verdict: no blocking issues. The argv-based flow parser holds — multi-word step strings and quoted values survive, --set is correctly dropped from baked flags in new, and the go-time dedup is deterministic. The soft-wrap rule is consistent across all 8 skills (docs, ed, spec, dev, pm, em, ux, qa), all under ## Critical Rules.
Non-blocking items (2 inline + 1 here):
NOTE (PR description): the body says the rule was added to "the 7 markdown-generating skills: docs, ed, spec, dev, pm, em, ux" and the validation checklist omits qa, but commit a83a1fb added qa too (8 total, verified present). Worth updating the description to match the final diff.
Address review on PR #21: - go.md Step 2 now merges PASSTHROUGH_FLAGS deterministically: a run-time flag with the same name as one baked into a step at new time replaces the baked value (explicit run-time value wins) instead of being silently dropped by dedup; same-valued flags stay single; a flag never duplicates. - flow-dir.md: cross-reference the two GLOBAL-parse snippets (minimal loop for status/list/save vs. the fuller argv walker for new/go) so a future maintainer editing one keeps --global handling in sync; document that run-time flags override baked ones.
## [1.57.1](v1.57.0...v1.57.1) (2026-07-11) ### Bug Fixes * soft-wrap generated markdown and forward extra flow flags ([#21](#21)) Soft-wrap authoring rule across 8 markdown-generating skills (docs, ed, spec, dev, pm, em, ux, qa); flow arg parsing preserves argv and forwards extra flags like --branch, baked into stored steps by new and appended at go time, with run-time flags overriding baked ones.
|
🎉 This PR is included in version 1.57.1 🎉 The release is available on GitHub release Your semantic-release bot 📦🚀 |
1 participant
Bug
Two separate issues, fixed together.
1. Hard-wrapped generated markdown. Skills that generate markdown (docs, spec, plans, PRDs, etc.) emitted prose hard-wrapped at a fixed column. That produces awkward diffs when a single word is edited and reads poorly in editors that already soft-wrap. There was no authoring rule telling these skills to leave prose on a single logical line and let the editor wrap it.
2.
flowdropped extra flags. Theflowskill's arg parser only recognized a known set of flags. Anything else (for example--branch) was silently discarded instead of being forwarded to the underlying step skills, so callers could not pass step-specific options through a flow.Fix
Issue 1 — soft-wrap authoring rule. Added a "soft-wrap prose, never hard-wrap" rule to the 8 markdown-generating skills: docs, ed, spec, dev, pm, em, ux, qa. Prose stays on one logical line per paragraph; the editor handles visual wrapping. This keeps future diffs word-level rather than reflowing whole paragraphs.
Issue 2 — flow flag pass-through. Extended the
flowarg parsing with a newPASSTHROUGH_FLAGSbucket inflow-dir.md. Unrecognized flags now collect into that bucket and are forwarded to each step. Wired throughnew.md,go.md,SKILL.md, andhelp.md.Validation
flowforwards--branch(and other unknown flags) to steps viaPASSTHROUGH_FLAGS