[PF-24] Advisory messages, plan loading spinner, and spinner module

[chucoding]

Purpose

Improve UX when running plan/implement in the Cursor sandbox: (1) show user-language advisories before running (via skills), (2) show a loading spinner during plan execution until the first stream chunk, and (3) share spinner logic in a common module. Also increase high-effort stream timeout and document timeout vs spinner.

Description

• High effort timeout: Default planner/implementer stream timeout for high effort increased from 300s to 360s in packages/cli-js/src/config/timeout.ts and packages/cli-py/planforge/utils/config.py.

• Advisory messages (skill-based i18n):

  • Removed hardcoded advisory text from CLI (plan.ts, implement.ts, plan.py, implement.py).
  • Updated p and i skills (.cursor/skills/p/SKILL.md, .cursor/skills/i/SKILL.md, and template copies under templates/cursor/skills/, packages/cli-js/templates/cursor/skills/) so the agent outputs a one-line advisory in the user’s language before running the plan/implement script.
  • p: e.g. "This may take a while. Please wait." / i: e.g. "Expand the sandbox and check the output logs."

• Plan loading spinner:

  • Added onFirstChunk?: () => void to PlanOpts (registry). Claude and Codex providers call it once on the first non-empty stream chunk.
  • In plan.ts: when stdout is TTY, start a spinner (createSpinner({ prefix: "Loading... " })), pass onFirstChunk: () => spinner.stop(), and call spinner.stop() in finally.
  • In plan.py: when stdout is TTY, print "Loading..." (flush) before calling the planner.

• Spinner module:

  • Added packages/cli-js/src/utils/spinner.ts: createSpinner(options?) returns { start(), stop(), clear() } with configurable prefix, intervalMs (default 80), stream, and onlyWhenTty.
  • Refactored plan.ts and commands/doctor.ts to use createSpinner instead of inline spinner code.

Area	Files
Config	cli-js/src/config/timeout.ts, cli-py/planforge/utils/config.py
Registry / providers	cli-js/src/providers/registry.ts, claude.ts, codex.ts
Commands	cli-js/src/commands/plan.ts, doctor.ts, cli-py/planforge/commands/plan.py
Utils	cli-js/src/utils/spinner.ts (new)
Skills	.cursor/skills/p/SKILL.md, i/SKILL.md, and template copies

How to test

1. High effort timeout: Set planner effort to high in planforge.json, run planforge plan "<goal>" and confirm the run can proceed past 300s (e.g. up to 360s) when the provider is slow.
2. Advisory: Invoke /p or /i in Cursor; confirm the agent prints a one-line advisory in the same language as your message before the plan/implement command runs.
3. Plan spinner: Run planforge plan "<goal>" in a TTY; confirm "Loading... |/-" appears until the first streamed output, then the line is cleared and plan output continues.
4. Doctor spinner: Run planforge doctor and choose AI mode; confirm the "response:" spinner behaves as before (spinner then PASS/FAIL).
5. Python plan: Run planforge plan "<goal>" via the Python CLI in a TTY; confirm "Loading..." is printed before plan output.

Review Requirement

• Confirm onFirstChunk is only invoked once per run (first non-empty chunk) in both Claude and Codex.
• Confirm spinner is stopped in all exit paths (success, first chunk, error, finally) so it never keeps running after the command ends.
• Confirm skill text is consistent across .cursor/skills/, templates/cursor/skills/, and packages/cli-js/templates/cursor/skills/ for both p and i.

Additional Info

• Related Notion: Cursor Sandbox — design and implementation notes for advisory messages, loading spinner, spinner module, and timeout vs spinner.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.