[xingzihai]

Fixes #3168

What

Adds a --plan-mode=off flag to gen-skill-docs that drops the ~1.8 KB "Plan Mode Safe Operations" + "Skill Invocation During Plan Mode" preamble block from every generated skill. Default builds (flag absent or --plan-mode=on) keep the block byte-identically.

Live evidence

$ bun run gen:skill-docs --out-dir /tmp/pm-default-build
[103 artifacts generated]
$ grep -rl "Plan Mode" /tmp/pm-default-build/ | wc -l
50

$ bun run gen:skill-docs --plan-mode=off --out-dir /tmp/pm-off-build
[103 artifacts generated]
$ grep -rl "Plan Mode" /tmp/pm-off-build/ | wc -l
1
$ grep -n "Plan Mode" /tmp/pm-off-build/landing-report/SKILL.md
484:## Plan Mode   ← skill-specific section, not the preamble

$ diff -rq /tmp/pm-default-build/ /tmp/pm-off-build/ | grep -c "differ"
58   ← only the plan-mode preamble lines differ

$ bun test test/plan-mode-off-build.test.ts
 9 pass, 0 fail, 14 expect() calls

$ bun test test/terse-build.test.ts test/review-entry-and-design-clarity-au.test.ts
 24 pass, 0 fail, 531 expect() calls

$ bun run typecheck
✓ (no errors)

Liveness proof

Live command output above. The --plan-mode=off flag is parsed in gen-skill-docs.ts, threaded through GenerationOptions → RenderOptions → TemplateContext, and consumed in generate-completion-status.ts where generatePlanModeInfo returns '' when ctx.planMode === false.

[trunk-io]

Merging to main in this repository is managed by Trunk.

• To merge this pull request, check the box to the left or comment /trunk merge below.

After your PR is submitted to the merge queue, this comment will be automatically updated with its status. If the PR fails, failure details will also be posted here

[capy-ai]

Triage (fix wave 5, GSTA-37): this adds a new generator flag for #3168, which is a feature request, so it's outside this bug-fix wave. I left it open for Garry's call.

[capy-ai]

Thanks @xingzihai, this is a clean, well-tested change, and keeping default output byte-identical is exactly right.

Decision: we want this, reworked so it's reachable from an installed gstack. Installed copies never run the generator, so a --plan-mode=off flag alone doesn't help users. Could you wire it to a gstack-config key (for example plan_mode_preamble=off) that setup and /gstack-upgrade pass through when they regenerate skills? Keep default output byte-identical, add a test for the config path, and rebase onto main. Note that #3236 already drops the sections on hosts with planMode:false, so the key only matters for Claude, copilot and opencode. We'll land it with your authorship kept. Tracking in #3168.

[capy-ai]

Thank you @xingzihai. Your flag was clean, well tested and byte-identical by default, and it's now the core of #3308. We went ahead and built the config wiring we asked about on the 17th, so this didn't have to wait on you: gstack-config set plan_mode_preamble off now reaches installed skills through setup, relink, gbrain-refresh and upgrade, including the default Claude install, which normally serves the committed files with no render. Your commit is cherry-picked unchanged with you as author; the only conflict was keeping both guards next to #3236's host-capability check. Closing this in favour of #3308, which closes #3168 when it merges.