feat: add planning skills, reviewer agent, Linear MCP#20
Merged
Conversation
Introduce a plan→build pipeline as Claude Code tooling: - write-plan: turns an issue (Linear/Jira/GitHub) into a two-section HTML plan — human-readable (diagrams + before/after screenshots) and a machine-consumed implementation section — then has a subagent review it for gaps. - implement-plan: executes that implementation section, folding in the reviewer's blocker/major gaps, writing e2e tests, then running vp check + vp test and /simplify. - plan-reviewer agent: Opus, read-only, adversarial gap-finding used by write-plan. - .mcp.json: Linear MCP server so issues are fetched directly. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
📝 WalkthroughWalkthroughThis PR adds a write-plan skill and HTML template to generate issue-based implementation plans, a plan-reviewer agent prompt to adversarially validate those plans, an implement-plan skill to execute tracked tasks with verification, and a ChangesIssue-Driven Plan and Implementation Workflow
Sequence DiagramssequenceDiagram
participant User
participant WritePlan
participant Codebase as Codebase Explorer
participant PlanReviewer
participant User2 as User (Report)
User->>WritePlan: /write-plan <issue-url>
WritePlan->>WritePlan: Resolve issue provider and fetch issue
WritePlan->>Codebase: Identify affected routes/components/stores
WritePlan->>WritePlan: Capture current/proposed screenshots via Playwright
WritePlan->>WritePlan: Generate Mermaid diagrams (current/proposed)
WritePlan->>WritePlan: Fill HTML template with plan and implementation sections
WritePlan->>PlanReviewer: Validate plan file and issue summary
PlanReviewer->>PlanReviewer: Verify file paths and dependencies
PlanReviewer->>PlanReviewer: Check APIs, tokens, config keys
PlanReviewer->>PlanReviewer: Identify gaps and edge cases
PlanReviewer-->>WritePlan: VERDICT: ship | fix-first
WritePlan->>User2: Print plan path and reviewer verdict
sequenceDiagram
participant Agent
participant Plan as Plan Parser
participant TaskExecutor
participant E2E
participant Verify as Verification
participant Report
Agent->>Plan: Resolve plan file (path/issue-id/newest)
Plan->>Plan: Parse implementation tasks from markers
Plan->>Plan: Read reviewer gaps verdict
Plan->>Plan: Fold BLOCKER/MAJOR/MINOR gaps into tasks
Plan->>TaskExecutor: Build tracked task list in dependency order
TaskExecutor->>Agent: Execute tasks on current branch
Agent->>E2E: Create/update e2e specs per module and acceptance criteria
E2E->>E2E: Conditional harness setup if needed
Agent->>Verify: Run vp check, vp test, and e2e
Verify->>Verify: Fix failures introduced by changes
Agent->>Agent: Apply /simplify post-implementation cleanup
Agent->>Verify: Re-run vp check, vp test, and e2e
Agent->>Report: Generate final report with files, gaps, e2e updates, and real outputs
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
devbox | d73aede | Commit Preview URL Branch Preview URL |
Jun 03 2026, 04:58 PM |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
.claude/skills/write-plan/SKILL.md (2)
66-66: ⚡ Quick winAdd instruction to check if dev server is already running before starting.
Line 66 says "Ensure the dev server is up (
vp dev; reuse it if already running)" but doesn't explain how to check. The Notes section (line 136) mentions preferring to reuse, but the procedure should include explicit instructions to check for a running server (e.g., via process list or port check) before spawning a new one.📝 Suggested addition
If the change affects a visible screen AND the app can run: 1. Identify the affected route/page. -2. Ensure the dev server is up (`vp dev`; reuse it if already running). +2. Check if the dev server is already running (e.g., `lsof -i :5173` or check process list). + If not running, start it with `vp dev` and wait for ready signal. If already running, reuse it. 3. Use the **playwright** MCP: `browser_navigate` to the route, then🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.claude/skills/write-plan/SKILL.md at line 66, Update the step that says "Ensure the dev server is up (`vp dev`; reuse it if already running)" to include a concrete check before starting: instruct the user to test the known dev-server port (e.g., with curl or netstat/ss) or look for the running process (e.g., ps/pgrep for the vp dev command) and only run `vp dev` if the port is not responding or the process is absent; reference the exact text "vp dev" and the dev-server port check so readers know what to probe and to prefer reusing an existing instance.
29-53: 💤 Low valueConsider handling the case where all fetch methods fail.
While the fallback chain is comprehensive (MCP → CLI → paste), there's no explicit instruction for what to do if the user doesn't paste the issue text when asked. Consider adding a note to handle this gracefully (e.g., abort with a clear message).
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.claude/skills/write-plan/SKILL.md around lines 29 - 53, Add explicit handling for the case where every fetch method (mcp__linear__get_issue + mcp__linear__list_comments, gh issue view, mcp__atlassian__getJiraIssue and CLI fallbacks) fails and the user declines to paste the issue: detect this terminal failure after the fallback chain and abort with a clear user-facing message instructing next steps (e.g., run /mcp to authenticate MCP servers, re-run gh issue view, or paste title+description); ensure the code path (where you call ToolSearch/select:mcp__linear__get_issue and the subsequent MCP/CLI/paste fallback logic) returns an error/terminates instead of creating a plan file (.claude/plans/<issue-id>-<slug>.html) with missing content.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.claude/skills/implement-plan/SKILL.md:
- Around line 55-73: Update the misleading paragraph under "5. Write / update
e2e tests for the module" that claims "current state of this repo — `e2e/` is
empty, no Playwright dep, no `browser` test config": replace it with text that
acknowledges an existing Playwright harness (detectable via
playwright.config.ts) and an existing e2e spec (e2e/base64.e2e.ts), and change
the guidance so implementers should extend the existing Playwright tests rather
than setting up a new Vitest browser harness; ensure references to creating a
Vitest harness (the "If no e2e harness exists yet" block) are removed or
conditional only if no playwright.config.ts and no e2e/*.e2e.ts files are
present.
---
Nitpick comments:
In @.claude/skills/write-plan/SKILL.md:
- Line 66: Update the step that says "Ensure the dev server is up (`vp dev`;
reuse it if already running)" to include a concrete check before starting:
instruct the user to test the known dev-server port (e.g., with curl or
netstat/ss) or look for the running process (e.g., ps/pgrep for the vp dev
command) and only run `vp dev` if the port is not responding or the process is
absent; reference the exact text "vp dev" and the dev-server port check so
readers know what to probe and to prefer reusing an existing instance.
- Around line 29-53: Add explicit handling for the case where every fetch method
(mcp__linear__get_issue + mcp__linear__list_comments, gh issue view,
mcp__atlassian__getJiraIssue and CLI fallbacks) fails and the user declines to
paste the issue: detect this terminal failure after the fallback chain and abort
with a clear user-facing message instructing next steps (e.g., run /mcp to
authenticate MCP servers, re-run gh issue view, or paste title+description);
ensure the code path (where you call ToolSearch/select:mcp__linear__get_issue
and the subsequent MCP/CLI/paste fallback logic) returns an error/terminates
instead of creating a plan file (.claude/plans/<issue-id>-<slug>.html) with
missing content.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 143fc7d0-df1f-4b62-8f47-6cdb2c1f7409
📒 Files selected for processing (5)
.claude/agents/plan-reviewer.md.claude/skills/implement-plan/SKILL.md.claude/skills/write-plan/SKILL.md.claude/skills/write-plan/template.html.mcp.json
#19 added Playwright, so the skill's "no e2e harness exists" branch was false and would mislead the agent into setting up a duplicate Vitest harness. Make Playwright the established path; keep no-harness as a generic future fallback. (CodeRabbit, PR #20) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a plan→build pipeline as Claude Code project tooling.
write-planskill — turns an issue URL (Linear/Jira/GitHub) into a self-contained two-section HTML plan: a human-readable section (current/proposed Mermaid diagrams + before-after screenshots) and a machine-consumed implementation section, then spawns a reviewer for gaps. Includestemplate.html.implement-planskill — executes the implementation section between theIMPLEMENT-PLANmarkers, folds in the reviewer's blocker/major gaps, writes/updates e2e tests, then runsvp check+vp testand/simplify.plan-revieweragent — Opus, read-only, adversarial gap-finding; verifies file/dep/API claims against the real codebase..mcp.json— Linear MCP server (https://mcp.linear.app/mcp) so issues are fetched directly instead of via brittle WebFetch.Why
Standardizes how issues become reviewed plans and then real changes, with the review step catching gaps before code is written.
Scope
Tooling only —
.claude/agents,.claude/skills/{write-plan,implement-plan},.mcp.json. No app/source changes.Verification
Exercised end-to-end this session: fetched RIV-5 via Linear MCP, generated + reviewed a plan, implemented it on a separate branch. Pre-commit
vp check --fixpassed.🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
Chores