Move Linear issues to In Review when a PR is ready for review

Issues sat in In Progress or were marked Done when a PR opened, so
reviewers could not see what was waiting. Done stays reserved for
merge and complete outcomes.

Author: TheGreatAxios

CHANGELOG.md

@@ -11,6 +11,13 @@ matching `## [X.Y.Z]` section (plus install instructions). Do not maintain
 parallel copies under `docs/` or `scripts/notes/`. At cut time: rename
 `## [Unreleased]` to `## [X.Y.Z] - YYYY-MM-DD`, then run the release script.
 
+## [Unreleased]
+
+### Changed
+
+- Agents and contributor docs move Linear issues to In Review when a PR is ready
+  for review.
+
 ## [0.3.14] - 2026-09-03
 
 ### Changed

CONTRIBUTING.md

@@ -220,13 +220,21 @@ Fixes #123
 
 Omit magic words. Do not invent issue IDs.
 
+### At PR-open (SHOULD)
+
+When the PR is ready for review (not a draft or WIP), move the linked Linear
+issue to In Review. Never mark Done on PR-open. Done is after merge, when every
+outcome is complete.
+
 ### After merge (SHOULD for agents running the full workflow)
 
 1. Confirm the PR is merged and CI is green on the merge commit.
 2. Comment the PR URL and merge SHA on the Linear issue.
 3. Tick only description checkboxes that `main` actually completed.
 4. Mark the Linear issue Done only when every outcome is truly done — never on
    "PR opened" alone.
+5. If leftover work remains, set the issue to In Progress. Do not leave it In
+   Review after merge.
 
 ## Contributor License Agreement
 

plugins/corbits-skills/skills/implement/SKILL.md

@@ -179,4 +179,4 @@ This skill produces commits. When the work is tracked in Linear and ends in a pu
 1. **Post a real GitHub PR review** with `gh pr review` after the PR exists — not a one-line self-review issue comment.
 2. **Multi-persona when used:** if critic / greybeard / OSS-quality lenses ran with substance, each posts its own labeled review. Primary owns approve/request-changes; secondary lenses comment only.
 3. **No AI slop in review bodies:** lens · verdict, one present-tense line on what the branch does, `path:line` findings. No filler, journey narration, or "LGTM" alone.
-4. **Linear checkboxes and Done are post-merge + green CI only.** Flip boxes only when `main` actually has the outcome. Never partial-Done on open PR.
+4. **Linear: In Review at ready-for-review PR-open; checkboxes and Done post-merge + green CI only.** The Phase 6–7 handoff in `linear-issue-workflow` must move the issue to In Review when the PR is ready for review. Flip boxes and mark Done only when `main` actually has the outcome. Never Done on open PR.

plugins/corbits-skills/skills/linear-issue-workflow/SKILL.md

@@ -255,9 +255,19 @@ EOF
 
 Then post the PR review(s) with `gh pr review` as drafted above. Paste the PR URL **and** every review URL to the user.
 
+### Set Linear to In Review
+
+When the PR is open and **ready for review** (not a draft or WIP), set the issue state to "In Review" with `mcp__linear__save_issue`. Do not mark Done. Done is Phase 7 only (merge + green CI + every outcome complete).
+
+If Linear MCP is unavailable or `save_issue` fails, report that the issue status could not be updated. Do not pretend the move succeeded. Do not mark Done as a fallback.
+
+Draft or WIP PRs stay **In Progress** until they are ready for review. Then move to In Review.
+
+Phase 6 ends when the PR is open and the review is posted. Ready-for-review PRs must be In Review (or the operator has been told the status update failed). Draft or WIP PRs stay In Progress.
+
 ## Phase 7: After Merge — Linear Closeout and Cleanup
 
-Phase 6 ends when the PR is open and the review is posted. Phase 7 runs **after the PR is merged** and **CI is green** on the merge (or on `main` at the merge commit). Do not mark the Linear issue Done on open PR alone. Do not tick outcome checkboxes on hope.
+Phase 7 runs **after the PR is merged** and **CI is green** on the merge (or on `main` at the merge commit). Do not mark the Linear issue Done on open PR alone. Do not tick outcome checkboxes on hope.
 
 ### 1. Confirm merge
 
@@ -287,7 +297,7 @@ Re-read the issue with `mcp__linear__get_issue`. For every checklist item the me
 
 ### 5. Mark Done only when complete
 
-If **every** outcome checkbox is checked and nothing residual remains, set state to `Done` with `mcp__linear__save_issue`. If anything is still open, leave the issue In Progress (or the team's equivalent) with remaining boxes unchecked — never partial-Done theater.
+If **every** outcome checkbox is checked and nothing residual remains, set state to `Done` with `mcp__linear__save_issue`. If anything is still open, set the issue to In Progress (or the team's equivalent) with remaining boxes unchecked — never partial-Done theater. Do not leave it In Review after merge when work remains.
 
 ### 6. Clean up the worktree
 

plugins/corbits-skills/skills/review/SKILL.md

@@ -393,4 +393,4 @@ No findings.
 
 ### After posting
 
-Paste the review URL(s) back to the user. If `--request-changes`, do not mark the Linear issue Done or tell the user the PR is merge-ready.
+Paste the review URL(s) back to the user. Do not mark the Linear issue Done. `--request-changes` is not merge-ready. While the PR is open and ready for review, the issue stays In Review — including after `--request-changes`. Do not ping-pong it back to In Progress. `linear-issue-workflow` owns the In Review write; this skill does not set Linear state.

src/agent/directors/skywalker/package.test.ts

@@ -205,4 +205,15 @@ describe("skywalkerPackage", () => {
     expect(p).toContain("ship → verify → fix → re-verify");
     expect(p).toContain("Cap re-fix rounds");
   });
+
+  test("systemPrompt Linear three-state: In Review at PR-open, never Done at PR-open", () => {
+    const p = skywalkerPackage.systemPrompt;
+    expect(p).toContain("In Progress");
+    expect(p).toContain("In Review");
+    expect(p).toMatch(/ready for review/);
+    expect(p).toContain("never Done at PR-open");
+    expect(p).not.toContain("mcp__linear__save_issue");
+    expect(p).not.toContain("gh pr create");
+    expect(p).not.toContain("gh pr review");
+  });
 });

src/agent/directors/skywalker/package.ts

@@ -131,7 +131,7 @@ Do not reclassify COMMUNICATION as ORCHESTRATION just to justify parallel spawn
 - Interview when requirements are fuzzy; consult greybeard on architecture/approach.
 - Use counsel for multi-lane eng plans; clarify before a large fan-out.
 - Path tools are the DIY surface; shell file-writes stay denied. Track fleet work with manage_tasks.
-- When claiming Linear work: set the issue to In Progress via Linear MCP as a hard first step before explore/build thrash. Parallel lanes claim their own IDs. If Linear MCP is unavailable, report that status could not be updated.
+- When claiming Linear work: set the issue to In Progress via Linear MCP as a hard first step before explore/build thrash. Parallel lanes claim their own IDs. When a PR is ready for review, move the issue to In Review — never Done at PR-open. If Linear MCP is unavailable, report that status could not be updated.
 - Optional skills when needed on the primary session: style, philosophy, interview (use_skill is primary-mounted).
 
 # Spawn graph

tests/unit/corbits-skills-catalog.test.ts

@@ -267,6 +267,22 @@ test("linear-issue-workflow references use_skill(git-worktrees)", async () => {
   expect(skill).not.toContain("git worktree add");
 });
 
+test("linear-issue-workflow moves ready-for-review PRs to In Review", async () => {
+  const skill = await Bun.file(join(pluginRoot, "skills/linear-issue-workflow/SKILL.md")).text();
+  expect(skill).toContain('set the issue state to "In Review"');
+  expect(skill).toMatch(/ready for review/);
+  expect(skill).toContain("Draft or WIP PRs stay **In Progress**");
+  expect(skill).toContain("Draft or WIP PRs stay In Progress");
+  expect(skill).toContain("Do not mark the Linear issue Done on open PR alone");
+  expect(skill).toContain("Do not leave it In Review after merge when work remains");
+});
+
+test("review skill does not own the Linear In Review write", async () => {
+  const skill = await Bun.file(join(pluginRoot, "skills/review/SKILL.md")).text();
+  expect(skill).toContain("`linear-issue-workflow` owns the In Review write");
+  expect(skill).not.toContain("Reviewers do not change Linear state");
+});
+
 test("slash skills do not set user-invocable: false", async () => {
   for (const name of SLASH_SKILLS) {
     const skill = await Bun.file(join(pluginRoot, "skills", name, "SKILL.md")).text();