Add issue-planner subagent for autonomous plan refinement

[studykit]

Description

Add issue-planner, an autonomous plan refiner subagent for workflow task / bug / spike issues. The existing implement-issue skill keeps step 1–2 (read issue, refine plan against current code) interactive via plan mode and hands off the rest to issue-implementer. The new agent automates that interactive front-half for cases where the caller wants the body sharpened without a plan-mode loop: it reads the body, cached comments, and every cited related issue 1 hop out; cross-checks the body's planned approach against the current code; refines Approach, Affected Paths, and Acceptance Criteria; writes the refined sections back to the body; and appends a single plan comment that records the refined plan, body-change rationale, and any autonomous decisions taken.

The agent is read-only on source code — no edits, commits, push, or PR. Code modification stays with issue-implementer or the human implementer.

Codex-side subagent context injection is not covered here. Codex's SessionStart can identify a subagent via transcript metadata, but the current _handle_agent_session_start intentionally skips additional-context emission. Extending Codex parity belongs in a follow-up issue.

Approach

Two new markdown files plus a small generalization in workflow_main_context.py:

• plugins/workflow/agents/issue-planner.md — the agent body. Frontmatter: tools: Bash, Read, Write, Grep, Glob (no Edit), no isolation, color: blue. Flow steps cover handle resolution, comment + 1-hop related-issue reading, free code cross-check, internal plan refinement, terminal-state decision, optional review publish, body update + plan comment, and report write. Terminal state tokens: planned, awaits-prereq, published-review, declined, failed. Plan comment carries four sections (## Plan, ## Body changes, ## Decisions made autonomously, ## Open questions) so the audit trail of why the body changed lives next to the body change itself.
• plugins/workflow/hooks/context/subagent/agents/issue-planner.md — SubagentStart injection block. Lists the runbook intents the agent uses (issue-fetch, issue-write, issue-new, issue-comment, issue-link, issue-update). No <commit-prefix> block — this agent never commits.
• plugins/workflow/scripts/workflow_main_context.py — _build_agent_context_block generalized: WORKFLOW_RUNBOOK_DIR and WORKFLOW_ISSUE_PROVIDER substitutions now apply to every agent template; SNIPPET_COMMIT_PREFIX stays gated behind the issue-implementer name. issue-implementer rendering is unchanged.

Affected Paths

• plugins/workflow/agents/issue-planner.md (new)
• plugins/workflow/hooks/context/subagent/agents/issue-planner.md (new)
• plugins/workflow/scripts/workflow_main_context.py (modified — _build_agent_context_block only)

Unit Test Strategy

• Run the workflow pytest suite (uv run --with pytest --with python-frontmatter --with PyYAML pytest plugins/workflow/tests). The existing helper in test_workflow_hook.py already covers the issue-implementer rendering path; the generalization must leave that path byte-identical. No new agent-specific test was added because per the tests AGENTS guidance prose freezing is not a contract — runtime behavior on issue-implementer is the contract.
• Manual end-to-end exercise (dispatching issue-planner against a real workflow task and inspecting the resulting body + comment) is deferred to follow-up usage, not gated by this issue's AC.

Acceptance Criteria

• plugins/workflow/agents/issue-planner.md exists with frontmatter (name, description, tools, color), all flow steps, publish/link/writeback procedures, output contract, and state-token table.
• plugins/workflow/hooks/context/subagent/agents/issue-planner.md exists and lists the six runbook intents the agent uses (issue-fetch, issue-write, issue-new, issue-comment, issue-link, issue-update).
• workflow_main_context.py::_build_agent_context_block applies WORKFLOW_RUNBOOK_DIR + WORKFLOW_ISSUE_PROVIDER substitutions for every per-agent template, with SNIPPET_COMMIT_PREFIX gated to issue-implementer.
• pytest plugins/workflow/tests passes (486 tests).

Out of Scope

• Codex-side subagent context injection (_handle_agent_session_start extension + AGENTS.md invariant update). Tracked separately as a follow-up issue.
• plugin.json version bump and marketplace.json sync — deferred until a release-grouped bump.
• New tests asserting issue-planner rendering — tests AGENTS guidance argues against freezing per-agent prose.