docs(planning): add phase 17 doc to break up the beasts

[bougyman]

No description provided.

[Copilot]

🟡 Changes recommended

The plan contains unresolved critical and moderate issues that must be addressed before approval.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds a Phase 17 plan for splitting monolithic CLI helpers and commands into workflow-focused modules while preserving behavior.

Changes:

• Defines module boundaries, migration steps, testing, and acceptance criteria.
• Adds Phase 17 to AGENTS.md.
• Review findings include one critical, two moderate, and two nit issues concerning command routing, matching logic, test scope, API naming, and development-flow reuse.

File summaries

File	Description
documents/phase-17-plan.adoc	Adds the Phase 17 refactoring plan and acceptance criteria.
AGENTS.md	Adds Phase 17 to the plan index.

Review details

Suppressed comments (3)

documents/phase-17-plan.adoc:33

• issue_helpers_test.exs does not cover bare-ID expansion; that behavior is in the separate expand_issue_id_test.exs (which also owns the profile/favorites setup). Calling it part of this 916-line file makes the baseline and test-split scope inaccurate; please name the separate file explicitly.

public operations. Its 916-line test file covers comment, close/cancel,
workflow-state selection, pull requests, project attachment, update dispatch,
creation, bare-ID expansion, and self-assignment.

documents/phase-17-plan.adoc:140

• This names a function that does not exist in the current helper or in the naming examples below. The existing operation is IssueHelpers.update_issue/2, and its callers/tests use that name; implementing this line literally could introduce a new API instead of preserving the documented contract. Please keep the renamed operation as Actions.update_issue/2.

* `Actions.update/2` returns `:ok | {:error, reason}`, while the other
  mutation functions retain their existing `{:ok, value} | {:error, reason}`

documents/phase-17-plan.adoc:309

• issue_create/2's --develop branch currently calls the private run_develop/2, which is also the implementation behind issue_develop/2 and in turn finish_pull_or_push/2 (app/lib/linear_cli/cli/commands.ex:360-428). Moving private helpers with one command family leaves either a cross-family private call or a duplicated development flow. Specify a named internal entry point in Issues.Development for both callers so the refactor preserves one implementation and the --dev behavior.

Move each `Commands` function with its private helpers into the command-family
module that owns its user-facing command. Preserve injectable options used by
tests (`cwd`, `me`, `runner`, and `halt` where applicable), function arities,
and parser-result input shapes. Private helpers stay with their command family;
they do not become broad shared utilities merely to reduce a few lines of
repetition.

• Files reviewed: 2/2 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.