Add an autonomous issue planner (GitHub Action) to generate test-first plans on issue creation

[acoliver]

Goal

Add a self-hosted, GitHub-Action-driven issue planner that automatically generates implementation plans when issues are filed or edited, replacing CodeRabbit's issue-planner capability for the switch to ocr. It runs the LLxprt CLI agentic (same pattern as pr-review.yml) and posts a single idempotent, tagged plan comment.

Background / motivation

• We are switching PR diff review from CodeRabbit to ocr (open-code-review): ocr finds more PR problems and is more cost-effective.
• Gap: ocr has no planner — it is review / scan / rules / config / llm only. CodeRabbit's issue planner today produces (a) a semantically-matched Related PRs block, (b) a phased Coding Plan, and (c) a per-phase "Prompt for AI agents" block. This issue closes that gap with a self-hosted equivalent.
• The existing .github/workflows/pr-review.yml already runs the LLxprt CLI in agentic --yolo --prompt mode, builds a context.md/instructions.md, captures agent output to a file, and posts a tagged comment. The planner is that same pipeline pointed at issues instead of PRs.

What the planner should do

The planner must be adaptive, not one-size-fits-all.

1. Size the issue (big vs small)

• Estimate magnitude from: number of acceptance criteria, span of packages/files the issue likely touches, whether the body already implies phases, and whether it is a subissue of an epic.
• Classify as small (single package / few criteria / small LoC magnitude) or large (multi-package / multi-phase / epic-scale).
• Classification selects the output format (see o3 isn't working #3). Per repo policy, sizing must use LoC/magnitude only — never time estimates.
• The plan must document the sizing basis so it is auditable, not a black box.

2. Always write test-first plans

Every plan, regardless of size, must be test-first:

• Identify the tests that must exist before implementation, stated up front.
• Favor adjusting/extending existing tests over creating new test files — unless the feature is genuinely new (no existing test file covers the area).
• Name the concrete existing test files to extend (e.g. packages/core/src/.../__tests__/foo.test.ts) and the specific new cases to add.
• Respect the test runner/framework conventions of the touched packages (vitest in this repo).
• When a new test file is warranted, justify why no existing test file can absorb the cases.

3. Format the plan by size

• Small issue — lightweight (mirrors CodeRabbit's compact output): a Summary bullet list, a Test plan (existing files to extend + new cases), short implementation steps, and a single "Prompt for AI agents" block.
• Large issue — a GitHub-adapted version of dev-docs/PLAN.md / dev-docs/PLAN-TEMPLATE.md:
  • Phased structure with phase IDs, prerequisites, and a Phase 0.5 preflight verification (dependency/type/call-path/test-infrastructure checks against the actual repo).
  • stub -> TDD -> impl cycles per feature slice.
  • Integration analysis: which existing code will USE the feature, which existing code is REPLACED, how users ACCESS it, and migration needs (no isolated features — per the "STOP BUILDING ISOLATED FEATURES" rule in PLAN.md).
  • Per-phase verification (deferred-implementation detection: TODO/HACK/STUB/empty returns; behavioral checks).
  • Per-phase "Prompt for AI agents" blocks.
  • Adapted to a single GitHub issue comment (collapsible <details> sections) rather than the dev-docs project-plans/<feature>/ file tree.
• Always include a Related PRs/issues block (CodeRabbit parity): semantically related merged PRs and issues, found by the agent during its run or via a heuristic precompute step.

4. Ground plans in repo conventions

• Encode the repo's lint/complexity policy invariance: no new suppression directives (eslint-disable*, @ts-ignore/@ts-expect-error/@ts-nocheck), no ESLint severity downgrades, no increases to complexity/size thresholds, no new ignores: blocks.
• Reference the real verification scripts the implementer must satisfy: npm run lint:ci, npm run lint:eslint-guard, npm run typecheck, npm run test.
• Honor any explicit constraints stated in the issue body (e.g. no-console handling, specific design decisions).

How it runs

• New workflow: .github/workflows/issue-planner.yml.
• Triggers:
  • on: issues: [opened, edited, reopened, labeled] for automatic planning.
  • on: issue_comment: [created], gated on a /plan (and /plan <feedback>) slash command, to replicate CodeRabbit's @coderabbitai plan replan UX.
• Job modeled on pr-review.yml: checkout -> gh issue view > issue.json -> build issue-context.md (issue body + linked parent/sibling issues + repo conventions + candidate related PRs) -> build planning-instructions.md (encoding rules 1-4 above) -> run llxprt --yolo --prompt "..." writing plan.md -> post the plan.
• Idempotent: comment tag <!-- llxprt-issue-plan -->; replans edit the existing comment rather than stacking new ones.
• Permissions: issues: write, contents: read (less than the PR review job needs; on: issues is repo-scoped, so the pull_request_target/fork-safety concerns do not apply).
• Key budget: reuse scripts/ci-quota-check.js key rotation shared with pr-review.yml. No new external service or secret beyond existing repo vars.

Out of scope / non-goals

• Does not replace ocr on PRs — ocr remains the PR diff reviewer. The planner and ocr are complementary: ocr = review, LLxprt-Action = plan.
• Does not block issue flow; planning is advisory.
• Does not run the dev-docs project-plans/<feature>/ file-tree flow on disk; that stays a separate local workflow. The issue planner adapts that structure into an in-comment form.

Acceptance criteria

• New workflow issue-planner.yml triggers on issue open/edit/reopen/label and on a /plan (and /plan <feedback>) comment.
• Planner sizes each issue (small/large) and documents the basis (criteria count, package span, magnitude — no time estimates).
• All plans are test-first and name the existing test files to extend, or justify a new test file.
• Large issues receive a PLAN.md/PLAN-TEMPLATE.md-adapted phased plan in GitHub comment form (preflight, stub->TDD->impl, integration analysis, per-phase verification); small issues receive the lightweight format.
• Every plan includes a Related PRs/issues block.
• Plans are grounded in repo lint/complexity policy and name the verification scripts to satisfy.
• Plans post as a single idempotent tagged comment; replan edits in place.
• Shares key/quota logic with pr-review.yml; no new external service and no new secrets beyond existing vars.
• The new workflow passes actionlint/shellcheck consistent with the other workflows; the repo's lint:ci, lint:eslint-guard, typecheck, and test all remain green.

Notes / decisions to confirm

• Sizing thresholds for small vs large (propose: criteria count + package span + LoC magnitude).
• Whether PLAN.md-style code markers (@plan:/@requirement:) should be emitted inside the in-comment plan — they are designed for the on-disk file-tree flow and may be adapted or omitted for issue comments.
• Replan UX confirmation: edit-in-place vs. appending a versioned history.
• Whether to gate the initial rollout behind a label (e.g. only plan issues labeled plan) before enabling for all issues.

[coderabbitai]

🔗 Related PRs

#562 - Phase 1 & 2: ToolCall Pipeline Fixes for #518 #556 [merged]
#917 - Fix tool-call history for provider switching [merged]
#961 - fix: resolve tool scheduling, cancellation, and search issues [merged]
#999 - feat: add --continue flag for session resumption [merged]
#1219 - fix(ci): refactor pr-review to agentic workflow with proper baseurl handling [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Clone pr-review.yml's proven agentic LLxprt pipeline into a new issue-planner.yml, retargeting it at issues, dropping fork-safety, and narrowing permissions to issues: write / contents: read.
• Add the repo's first /plan <feedback> slash-command argument parser plus an optional label-based rollout gate, while reusing scripts/ci-quota-check.js unchanged for key rotation.
• Encode the adaptive contract (LoC-only sizing, mandatory test-first with named existing test files, small vs PLAN.md-adapted large formats, always-on Related PRs block, lint/complexity policy invariance + named verification scripts) in a deterministic planning-instructions.md consumed by the agent.
• Publish one idempotent <!-- llxprt-issue-plan -->-tagged comment via peter-evans/find-comment + create-or-update-comment (issue-capable), editing in place on replan, with an infra-failure fallback and full actionlint/shellcheck/ratchet compliance.

Design Choices

Design Choice 1: Idempotent comment posting on plain issues (not PRs)

Options Considered:

1. peter-evans/find-comment + peter-evans/create-or-update-comment — purpose-built, explicitly supports issue comments and tag-marker discovery/update.
2. actions/github-script — write inline JS to list comments, match the <!-- llxprt-issue-plan --> marker, and create/update via the REST API (already used elsewhere in the repo, e.g. assign.yml/ocr-review.yml).
3. Raw gh CLI (gh api list + gh issue comment/PATCH) — manual find-and-edit.

Chosen Option: 1

Rationale: The thollander/actions-comment-pull-request action used by pr-review.yml is PR-scoped and cannot reliably upsert comments on plain issues (confirmed by web search). peter-evans/find-comment + create-or-update-comment gives the cleanest, well-maintained tag-based upsert with native issue support, requires no new secrets/services, and only needs standard SHA-pinning (ratchet) to satisfy CI.

Design Choice 2: Whether to emit `@plan`:/@requirement: code markers inside the in-comment plan

Options Considered:

1. Omit the markers; keep human-readable phase IDs and per-phase headings only.
2. Emit full markers in the comment.

Chosen Option: 1

Rationale: These markers are designed for the on-disk project-plans/ flow and grep-based phase gating. Markers add noise without the on-disk grep tooling; retain phase IDs/REQ references in prose so the plan stays auditable but comment-appropriate.

Design Choice 3: Replan UX (edit-in-place vs. append versioned history)

Options Considered:

1. Edit-in-place using the single <!-- llxprt-issue-plan --> tagged comment.
2. Append a new versioned comment per replan.

Chosen Option: 1

Rationale: The ticket states replans should "edit the existing comment rather than stacking new ones." This matches the ticket's explicit idempotency requirement and CodeRabbit parity; /plan <feedback> regenerates and overwrites the same tagged comment.

Design Choice 4: Initial rollout gating

Options Considered:

1. Plan all issues by default.
2. Gate on a configurable repo variable / label so rollout can start narrow.

Chosen Option: 2

Rationale: The ticket flags label-gating (only plan issues labeled plan) as a decision to confirm. Add a lightweight opt-in gate driven by an existing-style repo variable (e.g. vars.ISSUE_PLANNER_LABEL) that, when set, restricts auto-planning to labeled issues; /plan comments always work. This satisfies the "advisory, non-blocking, safe rollout" intent without new secrets.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Workflow scaffolding, gating, and shared runtime setup

Establish issue-planner.yml with the correct triggers, minimal permissions, concurrency, and the front-of-job setup that mirrors pr-review.yml's infrastructure while dropping fork-safety complexity (issue events are repo-scoped). This phase also introduces the repo's first slash-command argument parser.

Task 1: Create the workflow skeleton with triggers, permissions, and concurrency

Define the entry points and safety scoping for the planner.

• Create .github/workflows/issue-planner.yml with a leading # header comment block explaining purpose, advisory/non-blocking nature, and why fork-safety (pull_request_target) is not needed (issue events are repo-scoped), following the header-comment convention in assign.yml/ocr-review.yml.
• Set on: to issues: [opened, edited, reopened, labeled] and issue_comment: [created].
• Set top-level permissions: { contents: read, issues: write } (narrower than pr-review.yml); add defaults: run: shell: bash and env: FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true' (needed for github-script/JS actions).
• Add a concurrency: group keyed by issue number with cancel-in-progress: true (regenerate-style, matching pr-review.yml/ocr-review.yml).
• Use unquoted YAML scalar style and full-SHA-pinned actions with trailing # ratchet:owner/repo@vX.Y.Z comments so the CI lint_github_actions/ratchet checks pass.

Task 2: Add the run-gate and /plan slash-command parsing step

Decide whether a given event should trigger planning and, for comments, extract optional replan feedback — a new pattern for this repo.

• Add a job-level if: that admits (a) issues events and (b) issue_comment events whose body is exactly /plan or starts with /plan (handling \n/\r\n/\t variants via toJSON(...), as assign.yml/ocr-review.yml do) and whose issue.pull_request is null (exclude PR comments) and whose comment.author_association is OWNER/MEMBER/COLLABORATOR.
• Add an early parsing step (an actions/github-script or bash step) that: determines the trigger mode (auto vs replan), extracts feedback text after /plan into an output/GITHUB_ENV variable for later prompt injection, and resolves the target ISSUE_NUMBER from either github.event.issue.number (both issues and issue_comment events expose this).
• Implement the optional rollout gate (Assumption 4): if vars.ISSUE_PLANNER_LABEL is set, short-circuit auto-mode runs unless the issue carries that label; /plan comments always proceed. Emit a ::notice when skipped.

Task 3: Wire checkout, LLxprt CLI install, and shared quota/key rotation

Reuse pr-review.yml's runtime bootstrap and the shared key-rotation script unchanged.

• Add actions/checkout (default ref is fine — no PR-head fetch needed), then Install LLxprt CLI nightly (npm install -g @vybestack/llxprt-code@nightly).
• Set job-level env for OPENAI_API_KEY/OPENAI_API_KEY_2/OPENAI_BASE_URL/LLXPRT_DEFAULT_PROVIDER/LLXPRT_DEFAULT_MODEL (initial values from secrets[vars.KEY_VAR_NAME] etc.), mirroring pr-review.yml.
• Add the Check API quota and select optimal key step running node scripts/ci-quota-check.js with step-level KEY_VAR_NAME/OPENAI_API_KEY/OPENAI_API_KEY_2 env (from vars/secrets), placed before agent invocation so the selected key propagates via GITHUB_ENV. Do not modify the script.

🤖 Prompt for AI agents

Implement Phase 1: scaffold the new `.github/workflows/issue-planner.yml`
workflow file with triggers, permissions, concurrency, gating logic, and shared
runtime bootstrap.

- Create `.github/workflows/issue-planner.yml` with a leading `#` header comment
block explaining purpose, advisory/non-blocking nature, and why fork-safety
(`pull_request_target`) is not needed (issue events are repo-scoped), following
the header-comment convention in `assign.yml`/`ocr-review.yml`.
- Set `on:` to `issues: [opened, edited, reopened, labeled]` and `issue_comment:
[created]`.
- Set top-level `permissions: { contents: read, issues: write }`; add `defaults:
run: shell: bash` and `env: FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true'`.
- Add a `concurrency:` group keyed by issue number with `cancel-in-progress:
true`.
- Use unquoted YAML scalar style and full-SHA-pinned actions with trailing `#
ratchet:owner/repo@vX.Y.Z` comments to satisfy CI's `lint_github_actions`
checks.
- Add a job-level `if:` admitting `issues` events and `issue_comment` events
whose body is exactly `/plan` or starts with `/plan ` (handle `\n`/`\r\n`/`\t`
via `toJSON(...)` as in `assign.yml`/`ocr-review.yml`), excluding PR comments
(`issue.pull_request` is null), and restricted to `comment.author_association`
OWNER/MEMBER/COLLABORATOR.
- Add an early parsing step (github-script or bash) that determines trigger mode
(`auto` vs `replan`), extracts feedback text after `/plan ` into an
output/`GITHUB_ENV` variable, and resolves `ISSUE_NUMBER` from
`github.event.issue.number`.
- Implement the optional rollout gate: if `vars.ISSUE_PLANNER_LABEL` is set,
skip `auto`-mode runs unless the issue carries that label; `/plan` comments
always proceed; emit `::notice` when skipped.
- Add `actions/checkout` (default ref), then an `Install LLxprt CLI nightly`
step (`npm install -g `@vybestack/llxprt-code`@nightly`).
- Set job-level `env` for
`OPENAI_API_KEY`/`OPENAI_API_KEY_2`/`OPENAI_BASE_URL`/`LLXPRT_DEFAULT_PROVIDER`/`LLXPRT_DEFAULT_MODEL`
from `secrets[vars.KEY_VAR_NAME]` etc., mirroring `pr-review.yml`.
- Add the `Check API quota and select optimal key` step running `node
scripts/ci-quota-check.js` with step-level
`KEY_VAR_NAME`/`OPENAI_API_KEY`/`OPENAI_API_KEY_2` env, placed before agent
invocation so the selected key propagates via `GITHUB_ENV`. Do not modify the
script itself.

Phase 2: Issue context and planning-instruction generation

Gather all issue-related material and encode the four planner behaviors (sizing, test-first, size-based formatting, policy grounding) into a deterministic instructions file the agent will follow.

Task 1: Fetch issue data, comments, and linked parent/sibling issues

Assemble the raw inputs the agent needs, reusing the JSON field sets already proven in pr-review.yml/luther.yml.

• Add a step that runs gh issue view "$ISSUE_NUMBER" --json number,title,url,body,state,labels,assignees into a working file (e.g. planner/issue.json) and gh api repos/$REPO/issues/$ISSUE_NUMBER/comments for comment history.
• Extract linked/parent/sibling references from the issue body using the repo's free-text convention (regex for #([0-9]+), Parent:/Parent Issue:/Parent Epic:/Epic:/Sub-issues:), then fetch each referenced issue via gh issue view <n> --json number,title,url,body,state,labels into planner/issues/<n>.json (mirroring pr-review.yml's linked-issue loop).
• Add a lightweight related-PRs precompute step: use gh search prs/gh api keyed on the issue title/keywords to collect candidate merged PRs and related issues into planner/related-candidates.json as seed data for the mandatory Related PRs/issues block.

Task 2: Build issue-context.md

Render the fetched data into a single structured context document, following pr-review.yml's inline Node Build review context pattern.

• Add a step (inline node --eval or heredoc + node) that reads planner/issue.json, linked issues, comments, and related candidates and writes planner/issue-context.md: issue metadata, full/truncated body, acceptance-criteria checklist items, parent/sibling summaries, candidate related PRs/issues, and (for replans) the extracted /plan feedback text.
• Include a manifest telling the agent which files exist and that it may use read_file/repo exploration to verify test files, package boundaries, and existing tests (needed for accurate sizing and test-first naming).

Task 3: Build planning-instructions.md encoding rules 1–4

Encode the adaptive planning contract so behavior is deterministic and auditable.

• Add a heredoc step writing planner/planning-instructions.md capturing:
  • Sizing heuristic (rule 1): classify small vs large using acceptance-criteria count, package/file span, whether the body implies phases, and epic/subissue status; require an explicit "Sizing basis" section using LoC/magnitude only, never time estimates.
  • Test-first mandate (rule 2): every plan states required tests before implementation; prefer extending existing test files (agent must name concrete *.test.ts paths, vitest convention) and justify any new test file.
  • Format-by-size (rule 3): small → compact Summary/Test plan/steps/single "Prompt for AI agents"; large → GitHub-adapted dev-docs/PLAN.md/PLAN-TEMPLATE.md structure with phase IDs, Phase 0.5 preflight (dependency/type/call-path/test-infra checks), stub→TDD→impl cycles, integration analysis (USE/REPLACE/ACCESS/MIGRATE per "STOP BUILDING ISOLATED FEATURES"), per-phase verification incl. deferred-implementation detection (TODO/HACK/STUB/empty returns), per-phase "Prompt for AI agents", all inside collapsible <details> sections; always a Related PRs/issues block.
  • Policy grounding (rule 4): encode lint/complexity invariance (no new eslint-disable*/@ts-ignore/@ts-expect-error/@ts-nocheck, no severity downgrades, no threshold increases, no new ignores: blocks) and name the verification scripts npm run lint:ci, npm run lint:eslint-guard, npm run typecheck, npm run test; honor explicit issue-body constraints.
  • Output contract: write the final plan to planner/plan.md beginning with the <!-- llxprt-issue-plan --> marker, omitting @plan:/@requirement: code markers per Assumption 2.

🤖 Prompt for AI agents

Implement Phase 2: gather issue context data and encode the planning contract
into instruction files consumed by the agent.

- Add a step running `gh issue view "$ISSUE_NUMBER" --json
number,title,url,body,state,labels,assignees` into `planner/issue.json` and `gh
api repos/$REPO/issues/$ISSUE_NUMBER/comments` for comment history.
- Extract linked/parent/sibling references from the issue body using the
free-text convention (regex for `#([0-9]+)`, `Parent:`/`Parent Issue:`/`Parent
Epic:`/`Epic:`/`Sub-issues:`), then fetch each referenced issue via `gh issue
view <n> --json number,title,url,body,state,labels` into
`planner/issues/<n>.json`, mirroring `pr-review.yml`'s linked-issue loop.
- Add a related-PRs precompute step using `gh search prs`/`gh api` keyed on
issue title/keywords to collect candidate merged PRs and related issues into
`planner/related-candidates.json`.
- Add a step (inline `node --eval` or heredoc + node) that reads
`planner/issue.json`, linked issues, comments, and related candidates and writes
`planner/issue-context.md` containing: issue metadata, full/truncated body,
acceptance-criteria checklist items, parent/sibling summaries, candidate related
PRs/issues, and (for replans) the extracted `/plan` feedback text. Include a
manifest telling the agent which files exist and that it may explore the repo to
verify test files, package boundaries, and existing tests.
- Add a heredoc step writing `planner/planning-instructions.md` encoding:
- Sizing heuristic: classify small vs large using acceptance-criteria count,
package/file span, phase implications, epic/subissue status; require an explicit
"Sizing basis" section using LoC/magnitude only, never time estimates.
- Test-first mandate: state required tests before implementation; prefer
extending existing test files (name concrete `*.test.ts` paths per vitest
convention), justify any new test file.
- Format-by-size: small issues get a compact Summary/Test plan/steps/single
"Prompt for AI agents"; large issues get a GitHub-adapted
`dev-docs/PLAN.md`/`PLAN-TEMPLATE.md` structure with phase IDs, Phase 0.5
preflight checks, stub→TDD→impl cycles, integration analysis
(USE/REPLACE/ACCESS/MIGRATE), per-phase verification including
deferred-implementation detection (TODO/HACK/STUB/empty returns), per-phase
"Prompt for AI agents", all inside collapsible `<details>` sections; always
include a Related PRs/issues block.
- Policy grounding: encode lint/complexity invariance (no new
`eslint-disable*`/`@ts-ignore`/`@ts-expect-error`/`@ts-nocheck`, no severity
downgrades, no threshold increases, no new `ignores:` blocks) and name
verification scripts `npm run lint:ci`, `npm run lint:eslint-guard`, `npm run
typecheck`, `npm run test`; honor explicit issue-body constraints.
- Output contract: write the final plan to `planner/plan.md` beginning with the
`<!-- llxprt-issue-plan -->` marker, omitting `@plan:`/`@requirement:` code
markers.

Phase 3: Agent execution, plan capture, and idempotent issue-comment posting

Run the agent, capture its plan, and publish it as one editable tagged comment with a resilient failure path.

Task 1: Invoke the LLxprt CLI agentically and capture output

Reproduce pr-review.yml's robust invocation/capture pattern pointed at the issue.

• Add a step that constructs an initial prompt instructing the agent to read planner/planning-instructions.md then planner/issue-context.md and write the plan to planner/plan.md, and invokes llxprt --provider ... --model ... --yolo --key "$OPENAI_API_KEY" --baseurl ... --set modelparam.* --set context-limit=... --set shell-replacement=false --prompt "...", teeing to a log.
• Wrap the call in set +e and capture PIPESTATUS[0]; on non-zero exit write an infra-failure body (still starting with <!-- llxprt-issue-plan -->) to the comment file; on success prefer planner/plan.md, falling back to the raw log.

Task 2: Post the idempotent tagged plan comment (edit-in-place on replan)

Publish exactly one tagged comment per issue, updating it on subsequent runs/replans.

• Add a peter-evans/find-comment step (SHA-pinned + ratchet comment) searching the issue for the <!-- llxprt-issue-plan --> marker, followed by peter-evans/create-or-update-comment with issue-number, comment-id (from find), edit-mode: replace, and body-path pointing at the captured comment file — creating if absent, editing in place otherwise (Assumptions 1 & 3).
• Run the posting step with if: always() so infra-failure and success paths both post/update the single comment; add a final ::notice summarizing sizing/verdict for observability.

Task 3: Validate workflow against repo CI linting

Ensure the new file satisfies the same gates as every other workflow.

• Verify issue-planner.yml passes actionlint (valid syntax, quoted ${{ }} expressions, whitelisted -ignore patterns) and that all embedded run: bash blocks are shellcheck-clean, and that all actions are SHA-pinned with ratchet comments — using the local equivalents (scripts/lint-all.sh / npm run lint:all).
• Confirm no changes were made to eslint.config.js, scripts/check-eslint-guard.ts, package.json, or .coderabbit.yaml, so lint:ci, lint:eslint-guard, typecheck, and test remain green.

🤖 Prompt for AI agents

Implement Phase 3: invoke the LLxprt CLI, capture its output, and post/update a
single idempotent tagged comment on the issue, then validate the workflow
against repo CI linting.

- Add a step that constructs an initial prompt instructing the agent to read
`planner/planning-instructions.md` then `planner/issue-context.md` and write the
plan to `planner/plan.md`, then invokes `llxprt --provider ... --model ...
--yolo --key "$OPENAI_API_KEY" --baseurl ... --set modelparam.* --set
context-limit=... --set shell-replacement=false --prompt "..."`, teeing output
to a log file.
- Wrap the invocation in `set +e` and capture `PIPESTATUS[0]`; on non-zero exit,
write an infra-failure body (still starting with `<!-- llxprt-issue-plan -->`)
to the comment file; on success, prefer `planner/plan.md`, falling back to the
raw log if needed.
- Add a `peter-evans/find-comment` step (SHA-pinned with ratchet comment) that
searches the issue for the `<!-- llxprt-issue-plan -->` marker, followed by a
`peter-evans/create-or-update-comment` step using `issue-number`, `comment-id`
from the find step, `edit-mode: replace`, and `body-path` pointing at the
captured comment file — creating the comment if absent, editing in place
otherwise.
- Run the posting step with `if: always()` so both infra-failure and success
paths post/update the single comment; add a final `::notice` summarizing
sizing/verdict for observability.
- Validate the new `issue-planner.yml` passes `actionlint` (valid syntax, quoted
`${{ }}` expressions, whitelisted `-ignore` patterns), that embedded `run:` bash
blocks are shellcheck-clean, and all actions are SHA-pinned with ratchet
comments, using local equivalents (`scripts/lint-all.sh` / `npm run lint:all`).
- Confirm no changes were made to `eslint.config.js`,
`scripts/check-eslint-guard.ts`, `package.json`, or `.coderabbit.yaml`, so
`lint:ci`, `lint:eslint-guard`, `typecheck`, and `test` remain green.

Research

This is a monorepo whose .github/workflows/ directory already contains an agentic LLxprt-CLI PR reviewer (pr-review.yml) that establishes the exact pipeline to replicate: checkout → gather JSON context → build context.md/instructions.md → select an API key via scripts/ci-quota-check.js → invoke llxprt --yolo --prompt capturing output to a file → post an idempotent tagged comment with an infra-failure fallback.

Issue/comment data is fetched with gh issue view --json / gh api .../comments (see luther.yml), and linked/parent/sibling issues follow an informal free-text (Parent:/Epic:/Sub-issues:/#NNN) convention.

Lint/complexity policy invariance is defined in eslint.config.js and durably enforced by scripts/check-eslint-guard.ts; the verification entry points are the lint:ci, lint:eslint-guard, typecheck, and test scripts in package.json.

New workflows must pass CI's lint_github_actions job (actionlint + shellcheck + ratchet SHA-pinning) and follow existing naming/permissions/concurrency conventions.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement Phase 1: scaffold the new `.github/workflows/issue-planner.yml`
workflow file with triggers, permissions, concurrency, gating logic, and shared
runtime bootstrap.

- Create `.github/workflows/issue-planner.yml` with a leading `#` header comment
block explaining purpose, advisory/non-blocking nature, and why fork-safety
(`pull_request_target`) is not needed (issue events are repo-scoped), following
the header-comment convention in `assign.yml`/`ocr-review.yml`.
- Set `on:` to `issues: [opened, edited, reopened, labeled]` and `issue_comment:
[created]`.
- Set top-level `permissions: { contents: read, issues: write }`; add `defaults:
run: shell: bash` and `env: FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true'`.
- Add a `concurrency:` group keyed by issue number with `cancel-in-progress:
true`.
- Use unquoted YAML scalar style and full-SHA-pinned actions with trailing `#
ratchet:owner/repo@vX.Y.Z` comments to satisfy CI's `lint_github_actions`
checks.
- Add a job-level `if:` admitting `issues` events and `issue_comment` events
whose body is exactly `/plan` or starts with `/plan ` (handle `\n`/`\r\n`/`\t`
via `toJSON(...)` as in `assign.yml`/`ocr-review.yml`), excluding PR comments
(`issue.pull_request` is null), and restricted to `comment.author_association`
OWNER/MEMBER/COLLABORATOR.
- Add an early parsing step (github-script or bash) that determines trigger mode
(`auto` vs `replan`), extracts feedback text after `/plan ` into an
output/`GITHUB_ENV` variable, and resolves `ISSUE_NUMBER` from
`github.event.issue.number`.
- Implement the optional rollout gate: if `vars.ISSUE_PLANNER_LABEL` is set,
skip `auto`-mode runs unless the issue carries that label; `/plan` comments
always proceed; emit `::notice` when skipped.
- Add `actions/checkout` (default ref), then an `Install LLxprt CLI nightly`
step (`npm install -g `@vybestack/llxprt-code`@nightly`).
- Set job-level `env` for
`OPENAI_API_KEY`/`OPENAI_API_KEY_2`/`OPENAI_BASE_URL`/`LLXPRT_DEFAULT_PROVIDER`/`LLXPRT_DEFAULT_MODEL`
from `secrets[vars.KEY_VAR_NAME]` etc., mirroring `pr-review.yml`.
- Add the `Check API quota and select optimal key` step running `node
scripts/ci-quota-check.js` with step-level
`KEY_VAR_NAME`/`OPENAI_API_KEY`/`OPENAI_API_KEY_2` env, placed before agent
invocation so the selected key propagates via `GITHUB_ENV`. Do not modify the
script itself.
===============================================================================

Task: 2

Implement Phase 2: gather issue context data and encode the planning contract
into instruction files consumed by the agent.

- Add a step running `gh issue view "$ISSUE_NUMBER" --json
number,title,url,body,state,labels,assignees` into `planner/issue.json` and `gh
api repos/$REPO/issues/$ISSUE_NUMBER/comments` for comment history.
- Extract linked/parent/sibling references from the issue body using the
free-text convention (regex for `#([0-9]+)`, `Parent:`/`Parent Issue:`/`Parent
Epic:`/`Epic:`/`Sub-issues:`), then fetch each referenced issue via `gh issue
view <n> --json number,title,url,body,state,labels` into
`planner/issues/<n>.json`, mirroring `pr-review.yml`'s linked-issue loop.
- Add a related-PRs precompute step using `gh search prs`/`gh api` keyed on
issue title/keywords to collect candidate merged PRs and related issues into
`planner/related-candidates.json`.
- Add a step (inline `node --eval` or heredoc + node) that reads
`planner/issue.json`, linked issues, comments, and related candidates and writes
`planner/issue-context.md` containing: issue metadata, full/truncated body,
acceptance-criteria checklist items, parent/sibling summaries, candidate related
PRs/issues, and (for replans) the extracted `/plan` feedback text. Include a
manifest telling the agent which files exist and that it may explore the repo to
verify test files, package boundaries, and existing tests.
- Add a heredoc step writing `planner/planning-instructions.md` encoding:
- Sizing heuristic: classify small vs large using acceptance-criteria count,
package/file span, phase implications, epic/subissue status; require an explicit
"Sizing basis" section using LoC/magnitude only, never time estimates.
- Test-first mandate: state required tests before implementation; prefer
extending existing test files (name concrete `*.test.ts` paths per vitest
convention), justify any new test file.
- Format-by-size: small issues get a compact Summary/Test plan/steps/single
"Prompt for AI agents"; large issues get a GitHub-adapted
`dev-docs/PLAN.md`/`PLAN-TEMPLATE.md` structure with phase IDs, Phase 0.5
preflight checks, stub→TDD→impl cycles, integration analysis
(USE/REPLACE/ACCESS/MIGRATE), per-phase verification including
deferred-implementation detection (TODO/HACK/STUB/empty returns), per-phase
"Prompt for AI agents", all inside collapsible `<details>` sections; always
include a Related PRs/issues block.
- Policy grounding: encode lint/complexity invariance (no new
`eslint-disable*`/`@ts-ignore`/`@ts-expect-error`/`@ts-nocheck`, no severity
downgrades, no threshold increases, no new `ignores:` blocks) and name
verification scripts `npm run lint:ci`, `npm run lint:eslint-guard`, `npm run
typecheck`, `npm run test`; honor explicit issue-body constraints.
- Output contract: write the final plan to `planner/plan.md` beginning with the
`<!-- llxprt-issue-plan -->` marker, omitting `@plan:`/`@requirement:` code
markers.
===============================================================================

Task: 3

Implement Phase 3: invoke the LLxprt CLI, capture its output, and post/update a
single idempotent tagged comment on the issue, then validate the workflow
against repo CI linting.

- Add a step that constructs an initial prompt instructing the agent to read
`planner/planning-instructions.md` then `planner/issue-context.md` and write the
plan to `planner/plan.md`, then invokes `llxprt --provider ... --model ...
--yolo --key "$OPENAI_API_KEY" --baseurl ... --set modelparam.* --set
context-limit=... --set shell-replacement=false --prompt "..."`, teeing output
to a log file.
- Wrap the invocation in `set +e` and capture `PIPESTATUS[0]`; on non-zero exit,
write an infra-failure body (still starting with `<!-- llxprt-issue-plan -->`)
to the comment file; on success, prefer `planner/plan.md`, falling back to the
raw log if needed.
- Add a `peter-evans/find-comment` step (SHA-pinned with ratchet comment) that
searches the issue for the `<!-- llxprt-issue-plan -->` marker, followed by a
`peter-evans/create-or-update-comment` step using `issue-number`, `comment-id`
from the find step, `edit-mode: replace`, and `body-path` pointing at the
captured comment file — creating the comment if absent, editing in place
otherwise.
- Run the posting step with `if: always()` so both infra-failure and success
paths post/update the single comment; add a final `::notice` summarizing
sizing/verdict for observability.
- Validate the new `issue-planner.yml` passes `actionlint` (valid syntax, quoted
`${{ }}` expressions, whitelisted `-ignore` patterns), that embedded `run:` bash
blocks are shellcheck-clean, and all actions are SHA-pinned with ratchet
comments, using local equivalents (`scripts/lint-all.sh` / `npm run lint:all`).
- Confirm no changes were made to `eslint.config.js`,
`scripts/check-eslint-guard.ts`, `package.json`, or `.coderabbit.yaml`, so
`lint:ci`, `lint:eslint-guard`, `typecheck`, and `test` remain green.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!